PHP Manual

# PHP-Handbuch

2026-06-29
Bei der Übersetzung wirkten mit:
Oliver Albers
Florian Anderiasch
Christoph Michael Becker
Arne Blankerts
Cornelia Boenigk
Patrick Eigensatz
Hartmut Holzgraefe
Daniel Jänecke
Carola Köhntopp
Hakan Kücükyilmaz
Raphael Michel
Sebastian Nohn
Sergey Panteleev
Karl Pflästerer
Nikita Popov
Dirk Randhahn
Thorsten Rinne
Joshua Rüsweg
Martin Samesch
Mark Wiesemann
Tim Hollmann

# Copyright

Copyright © 1997 - 2026 by the PHP Documentation Group. Dieses Material darf nur gemäß den Regeln und Bedingungen der Creative Commons Attribution License Version v3.0 oder neuer weiter verbreitet werden. Eine Kopie der Creative Commons Attribution 3.0 license ist in diesem Handbuch enthalten, die aktuellste Version ist unter » http://creativecommons.org/licenses/by/3.0/ verfügbar.

# PHP-Handbuch

# Über dieses Handbuch

PHP ist die Abkürzung für "PHP: Hypertext Preprocessor", eine weitverbreitete Open Source Skriptsprache speziell für Webentwicklungen. PHP läßt sich in HTML einbinden. Die Syntax erinnert an C, Java und Perl und ist einfach zu erlernen. Das Hauptziel der Sprache ist, Webentwicklern die Möglichkeit zu geben, schnell dynamisch generierte Webseiten zu erzeugen. Aber Sie können PHP für weitaus mehr einsetzen.

Dieses Handbuch besteht vorranging aus einer Funktionsreferenz, enthält aber zusätzlich auch eine Sprachreferenz, Erläuterungen zu den wichtigsten Features und weitere ergänzende Informationen.

Dieses Handbuch enthält Informationen zu den beiden letzten Hauptversionen von PHP (Version 7 und 8). Informationen über Erweiterungen, die in diesen Versionen von PHP nicht mehr enthalten sind, und Änderungen an Funktionen in früheren Versionen sind nicht enthalten. Archive älterer Versionen des Handbuchs, die frühere Versionen von PHP dokumentieren, sind im Abschnitt "More documentation" auf der Seite » "Documentation" der PHP-Website verfügbar.

Sie können dieses Handbuch in verschiedenen Formaten unter » https://www.php.net/download-docs.php herunterladen. Informationen dazu, wie dieses Handbuch erstellt wird, finden Sie im Anhang unter dem Kapitel 'Über dieses Handbuch'. Wenn Sie sich für die Geschichte von PHP interessieren, lesen Sie bitte den entsprechenden Anhang.

# Autoren und Mitwirkende

Es gibt eine große Anzahl von Mitwirkenden, die derzeit an unserer Arbeit beteiligt sind oder dem Projekt in der Vergangenheit wertvolle Hilfe geleistet haben. Ebenfalls gibt es eine Vielzahl von Personen, die hier nicht namentlich aufgeführt sind, die durch ihre User Notes auf den Handbuchseiten mithelfen. Die User Notes werden kontinuierlich in unser Handbuch integriert und wir schätzen diese Unterstützung außerordentlich. Alle folgenden Listen sind alphabetisch sortiert.

# Autoren und Editoren

Folgende Personen verdienenen Anerkennung dafür, dass Sie wesentlichen Inhalt zum Handbuch beigetragen haben und/oder weiterhin beitragen werden: Mehdi Achour, Bill Abt, Jouni Ahto, Alexander Aulbach, Stig Bakken, George Peter Banyard, Christoph M. Becker, Daniel Beckham, Friedhelm Betz, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Antony Dovgal, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Nuno Lopes, Hannes Magnusson, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Philip Olson, Richard Quadling, Derick Rethans, Rob Richards, Georg Richter, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Damien Seguy, Masahiro Takagi, Yoshinari Takaoka, Yannick Torres, Jakub Vrana, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar und Andrei Zmievski.

Folgende Personen haben durch Ihre Editionsarbeit wesentlich zum Handbuch beigetragen: Stig Bakken, Peter Cowburn, Gabor Hojtsy, Hartmut Holzgraefe, Philip Olson und Egon Schmid.

# Betreuer der User Notes

Die zurzeit aktivsten Betreuer: Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda und Maciek Sokolewicz.

Auch folgende Personen haben einiges an Mühe und Zeit zur Betreuung der User Notes investiert: Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles und Jeroen van Wolffelaar.

# Einführung

# Was ist PHP und was kann es?

## Was ist PHP?

PHP (rekursives Akronym für PHP: Hypertext Preprocessor) ist eine weit verbreitete und für den allgemeinen Gebrauch bestimmte Open Source-Skriptsprache, welche speziell für die Webprogrammierung geeignet ist und in HTML eingebettet werden kann.

Nett, aber was heißt das genau? Ein Beispiel:

Beispiel #1 Ein einführendes Beispiel

    <!DOCTYPE html>
    <html>
        <head>
            <title>Beispiel</title>
        </head>
        <body>

            <?php
                echo "Hallo, ich bin ein PHP-Skript!";
            ?>

        </body>
    </html>

Anstatt ein Programm mit vielen Anweisungen zur Ausgabe von HTML zu schreiben, schreibt man etwas HTML und bettet einige Anweisungen ein, die irgendetwas tun (wie hier Hallo, ich bin ein PHP-Skript! auszugeben). Der PHP-Code steht zwischen speziellen Anweisungen `<?php` und `?>` zum Starten und Beenden der Verarbeitung, mit denen in den PHP-Modus und zurück gewechselt werden kann.

PHP unterscheidet sich von clientseitigen Sprachen wie Javascript dadurch, dass der Code auf dem Server ausgeführt wird und dort HTML-Ausgaben generiert, die an den Client gesendet werden. Der Client erhält also nur das Ergebnis der Skriptausführung, ohne dass es möglich ist herauszufinden, wie der eigentliche Code aussieht. Ein Webserver kann auch so konfiguriert werden, dass alle HTML-Dateien mit PHP verarbeitet werden, und dann gibt es keine Möglichkeit mehr, zu erkennen, dass PHP verwendet wird.

Das Beste an der Verwendung von PHP ist, dass es für Neueinsteiger extrem einfach ist, aber auch einen riesigen Funktionsumfang für den professionellen Programmierer bietet. Scheuen Sie sich nicht, die lange Liste der PHP-Funktionen zu lesen. Mit PHP kann fast jeder sofort loslegen und in kürzester Zeit einfache Skripte schreiben.

Auch wenn die Entwicklung von PHP auf serverseitige Programmierung fokussiert ist, kann damit weitaus mehr gemacht werden. Lesen Sie weiter und erfahren Sie mehr im Abschnitt Was kann PHP? oder gehen Sie direkt zum Einführungstutorial, um direkt etwas über Webprogrammierung zu lernen.

# Was kann PHP?

Alles. PHP ist hauptsächlich auf serverseitige Skripte fokussiert, weshalb es alles kann, was auch ein anderes CGI-Programm kann, z. B. Formulardaten sammeln, dynamische Inhalte für Webseiten generieren oder Cookies senden und empfangen. Aber PHP kann noch viel mehr.

Es gibt zwei Hauptgebiete, in denen PHP-Skripte genutzt werden.

- Serverseitige Programmierung. Dies ist das meistgenutzte und wichtigste Einsatzgebiet von PHP. Damit das funktioniert, werden drei Dinge benötigt: der PHP-Parser (CGI oder Server-Modul), ein Webserver und ein Webbrowser. Alle diese Programme können auf einem lokalen Rechner ausgeführt werden, um ein wenig mit der PHP-Programmierung zu experimentieren. Weitere Informationen sind im Abschnitt über die Installation zu finden.
- Kommandozeilenprogrammierung. Ein PHP-Skript kann ohne Server oder Browser ausgeführt werden, dazu wird nur der PHP-Parser benötigt. Diese Art der Nutzung ist ideal für Programme, die regelmäßig mittels cron (unter Unix oder macOS) oder dem Task Scheduler (unter Windows) ausgeführt werden. Die Skripte können außerdem für einfache Aufgaben der Textverarbeitung verwendet werden. Weitere Informationen dazu sind im Abschnitt Nutzung von PHP auf der Kommandozeile zu finden.

PHP kann auf allen gängigen Betriebssystemen verwendet werden, inkl. Linux, vielen Unix-Varianten (inkl. HP-UX, Solaris und OpenBSD), Microsoft Windows, macOS, RISC OS und wahrscheinlich anderen. PHP unterstützt auch die meisten der heute gebräuchlichen Webserver. Dies umfasst Apache, IIS und viele andere. Dazu gehört auch jeder Webserver, der das PHP-Binary FastCGI verwenden kann, z. B. lighttpd und nginx. PHP kann entweder als Modul oder als CGI-Prozessor eingesetzt werden.

So haben Entwickler die Freiheit, PHP auf dem Betriebssystem und dem Webserver ihrer Wahl laufen zu lassen. Darüber hinaus kann je nach Vorliebe prozedural oder objektorientiert (OOP) programmiert werden oder eine Mischung aus beidem verwendet werden.

PHP ist nicht auf die Ausgabe von HTML beschränkt. Seine Fähigkeiten umfassen auch die Ausgabe komplexer Dateitypen wie Bilder oder PDF-Dateien, die Verschlüsselung von Daten und der Versand von E-Mails. Es kann auch problemlos jede Art von Text ausgeben, z. B. JSON oder XML. PHP kann diese Dateien automatisch generieren und im Dateisystem speichern, anstatt diese nur auszugeben. Auf diese Weise lässt sich ein serverseitiger Cache der dynamischen Inhalte erstellen.

Vielleicht die größte und bemerkenswerteste Stärke von PHP ist seine Unterstützung für eine große Auswahl von Datenbanken. Eine datenbankgestützte Website zu erstellen ist mithilfe einer der Datenbankerweiterungen (z. B. für MySQL) oder mit einer Abstraktionsschicht wie PDO unglaublich einfach. Oder man verbindet sich über die Erweiterung ODBC mit irgendeiner Datenbank, die den Open Database Connection Standard unterstützt. Andere Datenbanken können cURL oder sockets verwenden (z. B. CouchDB).

PHP unterstützt auch die Kommunikation mit anderen Services, welche Protokolle wie LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (auf Windows) und unzählige andere unterstützen. Es kann auch einfache Netzwerk-Sockets öffnen und unter Verwendung irgendeines anderen Protokolls kommunizieren. PHP unterstützt auch WDDX (Web Distributed Data Exchange) zum Austausch komplexer Daten zwischen Programmiersprachen. Da wir gerade vom Zusammenwirken sprechen: PHP unterstützt auch die Instantiierung von Java-Objekten und deren transparente Verwendung als PHP-Objekte.

PHP verfügt über hilfreiche Funktionen für die Textverarbeitung, von den regulären Ausdrücken (PCRE) bis zum Parsen von XML-Dokumenten. PHP vereinheitlicht alle XML-Erweiterungen auf der soliden Basis der libxml2-Bibliothek und erweitert den Funktionsumfang durch die Unterstützung von SimpleXML, XMLReader und XMLWriter.

Es gibt noch viele andere interessante Erweiterungen, die sowohl alphabetisch als auch nach Kategorien geordnet sind. Darüber hinaus gibt es auch noch PECL-Erweiterungen die ggf. in der PHP-Dokumentation selbst dokumentiert sind, z. B. » XDebug

Diese Seite reicht nicht aus, um alle Möglichkeiten und Vorteile von PHP aufzulisten. Lesen Sie weiter in den Abschnitten über die Installation von PHP und in der Funktionsreferenz sind Erklärungen zu den hier erwähnten Erweiterungen zu finden.

# Ein kleines Tutorial

## Inhaltsverzeichnis

- Ihre erste PHP-erweiterte Seite
- Etwas Nützliches
- Formulare verarbeiten
- Und weiter?

Auf diesen Seiten möchten wir Ihnen die Grundlagen von PHP in einem kleinen Tutorial vorstellen. Dieser Text behandelt nur das Erstellen von dynamischen Webseiten, obwohl PHP natürlich nicht nur dafür geeignet ist. Weitere Informationen finden Sie im Abschnitt Was kann PHP?.

Mit PHP erweiterte Webseiten werden wie normale HTML-Seiten behandelt. Sie können sie genauso wie normale HTML-Seiten erstellen und bearbeiten.

# Ihre erste PHP-erweiterte Seite

Dieses Tutorial setzt voraus, dass PHP bereits installiert ist. Installationsanweisungen finden Sie auf der » Download-Seite.

Erstellen Sie eine Datei mit dem Namen hallo.php mit dem folgenden Inhalt:

Beispiel #1 Unser erstes PHP-Skript: hallo.php

    <?php

    echo "Hello World!";

    ?>

Navigieren Sie im Terminal in das Verzeichnis, das diese Datei enthält, und starten Sie mit folgendem Befehl einen Entwicklungsserver:

    php -S localhost:8000

Verwenden Sie Ihren Browser, um die Datei über die Webserver-URL aufzurufen. Die URL muss mit `/hallo.php` enden. Gemäß dem zuvor ausgeführten Befehl lautet die URL `http://localhost:8000/hallo.php`. Wenn alles korrekt konfiguriert ist, wird die Datei von PHP geparst und Sie sehen die Ausgabe "Hello World!" in Ihrem Browser.

PHP kann in eine normale HTML-Webseite eingebettet werden. Das bedeutet, dass Sie innerhalb Ihres HTML-Dokuments die PHP-Anweisungen schreiben können, wie im folgenden Beispiel gezeigt:

    <!DOCTYPE html>
    <html>
        <head>
            <title>PHP-Test</title>
        </head>
        <body>
            <?php echo '<p>Hallo Welt</p>'; ?>
        </body>
    </html>

Dies führt zur folgenden Ausgabe:

    <!DOCTYPE html>
    <html>
        <head>
            <title>PHP-Test</title>
        </head>
        <body>
            <p>Hallo Welt</p>
        </body>
    </html>

Das Beispiel ist extrem einfach und natürlich brauchen Sie PHP nicht, um eine Seite wie diese zu erstellen. Denn es macht nicht mehr, als mit der echo-Anweisung von PHP `Hallo Welt` auszugeben. Bitte beachten Sie, dass die Datei nicht ausführbar sein muss. Der Server erkennt anhand der Dateiendung ".php", dass sie durch PHP interpretiert werden muss. Stellen Sie sich eine normale HTML-Datei vor, die eine Menge von speziellen Tags enthält, mit denen Sie einige interessante Dinge tun können.

Der Sinn des Beispiels ist es, Ihnen das spezielle PHP Tag-Format zu zeigen. Im Beispiel wurde `<?php` verwendet, um den Beginn eines PHP-Tags zu kennzeichnen. Anschließend folgte die PHP-Anweisung. Mit dem schließenden Tag, `?>`, wurde der PHP-Modus wieder verlassen. Sie können an jeder Stelle und so oft Sie wollen, in den PHP-Modus wechseln und ihn wieder verlassen. Für weitere Details lesen Sie bitte den Abschnitt zu den Grundlagen der Syntax von PHP.

> Hinweis: Anmerkungen zu Zeilenwechseln

> Zeilenwechsel sind in HTML nur von geringer Bedeutung, trotzdem ist es sinnvoll, HTML-Code durch Zeilenwechsel zu formatieren um die Lesbarkeit zu erhöhen. Ein Zeilenwechsel, der direkt auf ein schließendes `?>` folgt, wird von PHP bei der Ausgabe entfernt. Dies ist äußerst nützlich, wenn Sie viele PHP-Blöcke einfügen oder Dateien inkludieren, die keine Ausgabe erzeugen sollen. Auf der anderen Seite kann es aber auch verwirrend sein. Sie können einen Zeilenwechsel erzwingen, indem Sie entweder ein zusätzliches Leerzeichen hinter `?>` einfügen oder explizit mit echo oder print ein Zeilenwechselzeichen am Ende Ihres Codes ausgeben.

> Hinweis: Anmerkung zu Text-Editoren

> Es gibt eine ganze Reihe von Text-Editoren und integrierten Entwicklungsumgebungen (Integrated Development Environments, IDEs), mit denen Sie Ihre PHP-Dateien erstellen, bearbeiten und verwalten können. Eine Liste solcher Programme finden Sie hier: » List of PHP editors. Wenn Sie einen Editor vorschlagen möchten, besuchen Sie bitte die genannte Seite und bitten Sie den Betreiber der Seite, dass er den Editor der Liste hinzufügt. Wir empfehlen Ihnen einen Editor zu verwenden, der Syntax-Highlighting (die farbliche Hervorhebung von Code) bietet.

> Hinweis: Anmerkung zu Textverarbeitungsprogrammen

> Textverarbeitungsprogramme wie StarOffice Writer, Microsoft Word und Abiword sind keine gute Wahl, um PHP-Dateien zu bearbeiten. Wenn Sie eines dieser Programme für dieses Test-Skript nutzen möchten, dann müssen Sie sicherstellen, dass die Datei als "Nur Text"-Datei gespeichert wird, da PHP sonst das Skript nicht lesen und nicht ausführen kann.

Nachdem Sie jetzt erfolgreich ein einfaches, funktionierendes PHP-Skript geschrieben haben, wird es Zeit, das berühmteste PHP-Skript zu schreiben. Rufen Sie die Funktion phpinfo() auf und Sie bekommen viele nützliche Informationen über Ihr System und Ihre Installation wie z. B. die verfügbaren vordefinierten Variablen, die geladenen PHP-Module und die Konfigurations-Einstellungen. Nehmen Sie sich etwas Zeit und schauen Sie sich diese wichtigen Informationen an.

Beispiel #2 Anzeigen von Systeminformationen mit PHP

    <?php

    phpinfo();

    ?>

# Etwas Nützliches

Kommen wir nun zu einem etwas nützlicheren Beispiel. Wir wollen prüfen, welchen Browser der Besucher verwendet. Um das zu tun, prüfen wir den "user agent"-String, den der Browser als Teil seiner HTTP-Anforderung sendet. Diese Information ist in einer Variablen abgelegt. In PHP beginnen Variablen immer mit einem Dollar-Zeichen. Die Variable, die uns jetzt interessiert, ist $_SERVER['HTTP_USER_AGENT'].

> Hinweis:

> $_SERVER ist eine speziell reservierte PHP-Variable, die alle Informationen über den Webserver enthält. Diese Variable wird auch als Superglobal bezeichnet. Mehr Informationen darüber finden Sie im Handbuch auf der Seite über Superglobals.

Um die Variable auszugeben, schreiben Sie einfach:

Beispiel #1 Variable ausgeben (Array-Element)

    <?php

    echo $_SERVER['HTTP_USER_AGENT'];

    ?>

Die Ausgabe dieses Beispiels könnte so aussehen:

    Mozilla/5.0 (Linux) Firefox/112.0

Es gibt viele Typen von Variablen. Im obigen Beispiel haben wir ein Element einer Array-Variable ausgegeben. Arrays können sehr nützlich sein.

$_SERVER ist nur eine von vielen Variablen, die Ihnen automatisch von PHP zur Verfügung gestellt werden. Eine Liste finden Sie auf der Seite Reservierte Variablen im Handbuch. Eine vollständige Liste können Sie auch bekommen, wenn Sie sich die Ausgabe der Funktion phpinfo() ansehen, die im Beispiel des vorigen Abschnitts verwendet wurde.

Sie können mehrere PHP-Anweisungen innerhalb eines PHP-Tags platzieren und so kleine Code-Blöcke schreiben, die mehr als nur eine Ausgabe mit echo enthalten. Wenn wir zum Beispiel prüfen möchten, ob es sich beim Browser des Besuchers um den Firefox handelt, können wir folgenden Code verwenden:

Beispiel #2 Beispiel, das Kontrollstrukturen und Funktionen verwendet

    <?php

    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        echo 'Sie verwenden Firefox.';
    }

    ?>

Die Ausgabe dieses Skripts könnte so aussehen:

    Sie verwenden Firefox.

Hier stellen wir Ihnen eine ganze Reihe von neuen Konzepten vor. Wir haben hier zuerst eine if-Anweisung. Wenn Sie mit der grundlegenden Syntax der Programmiersprache C vertraut sind, sollte Ihnen dies logisch erscheinen. Andernfalls sollten Sie sich ein Buch mit einer PHP-Einführung besorgen und die ersten Kapitel lesen. Sie können natürlich auch in die Sprachreferenz des Handbuchs schauen.

Das zweite hier vorgestellte Konzept ist der Aufruf der Funktion str_contains(). str_contains() ist eine in PHP eingebaute Funktion, die feststellt, ob eine gegebene Zeichenkette eine andere Zeichenkette enthält. In diesem Fall suchen wir nach `'Firefox'` (die so genannte Nadel, engl. needle) in $_SERVER['HTTP_USER_AGENT'] (der so genannte Heuhaufen, engl. haystack). Wenn die Nadel im Heuhaufen gefunden wird, gibt die Funktion `true` zurück. Andernfalls wird `false` zurückgegeben. Wenn `true` zurückgeben wird, wird die if-Anweisung zu `true` ausgewertet und der Code innerhalb der geschweiften Klammern wird ausgeführt. Andernfalls wird der Code innerhalb der Klammern nicht ausgeführt. Probieren Sie weitere ähnliche Beispiele mit if, else und anderen Funktionen wie strtoupper() oder strlen(). Jede dieser Handbuch-Seiten enthält weitere Beispiele. Wenn Sie unsicher sind, wie die Funktionen verwendet werden, lesen Sie die Handbuch-Seite Wie sind Funktionsdefinitionen (Prototypen) zu lesen? und den Abschnitt zu den PHP-Funktionen.

Wir können jetzt einen Schritt weitergehen und sehen, wie Sie innerhalb eines PHP-Blocks den PHP-Modus verlassen und wieder in ihn hinein gelangen können:

Beispiel #3 HTML- und PHP-Modus vermischt

    <?php
    if (str_contains($_SERVER['HTTP_USER_AGENT'], 'Firefox')) {
        ?>
        <h3>str_contains() hat true zurückgegeben</h3>
        <p>Sie verwenden Firefox</p>
        <?php
    } else {
        ?>
        <h3>str_contains() hat false zurückgegeben</h3>
        <p>Sie verwenden nicht Firefox</p>
        <?php
    }
    ?>

Die Ausgabe dieses Skripts könnte so aussehen:

    <h3>str_contains() hat true zurückgegeben</h3>
    <p>Sie verwenden Firefox</p>

Anstatt die PHP-Anweisung echo für die Ausgabe zu verwenden, haben wir den PHP-Modus verlassen und normales HTML verwendet. Der wichtige und entscheidende Punkt hierbei ist, dass der logische Ablauf des Skripts dadurch nicht gestört wird. Nur einer der beiden HTML-Blöcke wird ausgegeben - abhängig davon, was str_contains() zurückgibt bzw. ob die Zeichenkette `Firefox` gefunden wird oder nicht.

# Formulare verarbeiten

Eine der mächtigsten Funktionen von PHP ist die Art, wie HTML-Formulare verarbeitet werden. Sie sollten wissen, dass jedes Element eines Formulars automatisch in Ihren PHP-Skripts verfügbar ist. Bitte lesen Sie die Seite Variablen aus externen Quellen für weitere Informationen und Beispiele über die Verwendung von Formularen mit PHP. Hier ist ein HTML-Beispielformular:

Beispiel #1 Ein einfaches HTML-Formular

    <form action="action.php" method="post">
        <label for="name">Ihr Name:</label>
        <input name="name" id="name" type="text">

        <label for="age">Ihr Alter:</label>
        <input name="alter" id="alter" type="number">

        <button type="submit">Submit</button>
    </form>

An diesem Formular ist nichts Besonderes. Es ist ein normales HTML-Formular ohne irgendwelche speziellen Tags. Wenn der Benutzer das Formular ausfüllt und den Submit-Button anklickt, wird die Seite action.php aufgerufen. Diese Datei könnte so aussehen:

Beispiel #2 Daten des Formulars ausgeben

    Hallo <?php echo htmlspecialchars($_POST['name']); ?>.
    Sie sind <?php echo (int) $_POST['alter']; ?> Jahre alt.

Die Ausgabe des Skripts könnte dann so aussehen:

    Hallo Joe. Sie sind 22 Jahre alt.

Abgesehen von den beiden Teilen htmlspecialchars() und `(int)` sollte einfach zu verstehen sein, was hier geschieht. htmlspecialchars() stellt sicher, dass die Zeichen, die in HTML eine spezielle Bedeutung haben, ordentlich kodiert werden, sodass niemand HTML-Tags oder Javascript-Code in Ihre Seite einschmuggeln kann. Da wir wissen, dass das Feld "alter" eine Zahl enthalten soll, konvertieren wir es in einen Integer-Wert, wodurch automatisch überflüssige Zeichen entfernt werden. Sie können diese Aufgabe auch PHP überlassen, indem Sie die Filter-Erweiterung verwenden. Die Variablen $_POST['name'] und $_POST['alter'] werden für Sie automatisch von PHP gesetzt. Weiter oben haben wir das superglobale Array $_SERVER eingeführt, jetzt verwenden wir hier das - ebenfalls superglobale - Array $_POST, welches alle POST-Daten enthält. Beachten Sie, dass die im Formular verwendete Methode POST ist. Hätten wir GET verwendet, wären die Daten unseres Formulars stattdessen im superglobalen Array $_GET verfügbar. Sie können auch das superglobale Array $_REQUEST verwenden, wenn die Quelle der Daten keine Rolle spielt. Dieses Array enthält die GET-, POST- und COOKIE-Daten.

# Und weiter?

Mit dem neuen Wissen sollten Sie das meiste aus diesem Handbuch verstehen können.

Insbesondere könnten folgende Funktionalitäten interessant sein:

- Dateien lesen und schreiben mit den Dateisystem-Funktionen
- Datei-Uploads verarbeiten
- Entfernte Seiten und Dateien mit Curl abrufen
- Daten in einer Datenbank speichern und auswerten mit PDO (SQLite kann ohne laufenden Datenbankserver verwendet werden)
- Daten über mehrere Requests hinweg beibehalten mit Sessions

Im » Packagist-Repository findet sich für nahezu jeden Anwendungsfall eine Vielzahl von Bibliotheken und » Frameworks, die alle über den Composer-Paketmanager installiert werden können.

Hilfe und Rat aus der Community gibt es auf der » Hilfe-Seite.

Eine Auswahl an Podcasts, Präsentationen und weiteren Videos findet sich auf dem » Community-PeerTube.

Weitere Community-Ressourcen, die hilfreich sein können, sind sogenannte "awesome lists" (kuratierte Linksammlungen) und "developer roadmaps" (Listen verwandter Themen).

Wenn Sie nicht wissen, wo Sie anfangen sollen, hilft es oft, das Projekt oder Problem in kleinere Teile zu zerlegen. So lässt sich leichter erkennen, was Sie bereits können und was Sie noch lernen müssen. Die Liste darf so detailliert werden, wie nötig. Der Bau eines Blogs ließe sich zum Beispiel folgendermaßen aufgliedern:

- Auflisten und Anzeigen von Seiten
  - Datensätze (Seiten) aus einer Datenbank lesen
- Seiten erstellen
  - Formularübermittlung verarbeiten
  - Datensätze (Seiten) in eine Datenbank schreiben
- Admin-Login
  - Datensätze (Benutzer) aus einer Datenbank lesen
  - Mit Passwörtern umgehen
  - Daten (Benutzer-Login) über Requests und Seiten hinweg persistieren (Sessions)

Wenn Sie nichts Bestimmtes entwickeln möchten, können Sie nach Coding-Übungen wie Katas, Challenges oder "Code Golf" suchen. Auch wenn sie nicht speziell auf PHP ausgerichtet sind, lassen sich die meisten umsetzen und werden Ihr Wissen und Denken herausfordern.

- Einführung — Was ist PHP und was kann es?
- Ein kleines Tutorial
  - Ihre erste PHP-erweiterte Seite
  - Etwas Nützliches
  - Formulare verarbeiten
  - Und weiter?

# Installation und Konfiguration

# Generelle Überlegungen

Bevor Sie mit der Installation beginnen, sollten Sie wissen, für was Sie PHP verwenden wollen. Es gibt zwei Hauptbereiche, in denen Sie PHP verwenden können, die im Abschnitt Was kann PHP? beschrieben werden:

- Webseiten und Webapplikationen (serverseitiges Skripting)
- Kommandozeilenskripte

Für die erste und gebräuchlichste Variante brauchen Sie drei Dinge: PHP selbst, einen Webserver und einen Webbrowser. Sie haben wahrscheinlich bereits einen Webbrowser und, abhängig von Ihrem Betriebssystem, möglicherweise ebenso bereits einen Webserver (z. B. Apache auf Linux oder macOS; IIS auf Windows). Sie können ebenfalls Webspace bei einem Unternehmen mieten. Auf diese Weise müssen Sie selbst nichts einrichten und müssen nur PHP-Skripte schreiben, diese auf den gemieteten Server hochladen und die Ergebnisse im Browser betrachten.

Für den Fall, dass Sie den Server und PHP selbst aufsetzen, haben Sie zwei Auswahlmöglichkeiten, um PHP mit dem Server zu verbinden. Für viele Server bietet PHP eine direkte Schnittstelle (auch SAPI genannt). Unter diesen Servern befinden sich Apache, Microsoft Internet Information Server, Netscape und iPlanet Server. Falls PHP kein Modul für Ihren Webserver anbietet, können Sie es noch immer als CGI- oder FastCGI-Prozessor verwenden. Das bedeutet, Sie setzen Ihren Server so auf, dass er die ausführbare Datei für CGI von PHP verwendet, um alle Anfragen nach PHP Dateien auf dem Server zu verarbeiten.

Falls Sie außerdem darin interessiert sind, PHP für Kommandozeilenskripte zu verwenden (z. B. Skripte schreiben, die automatisch offline Bilder erzeugen oder Textdateien abhängig von einigen übergebenen Parametern zu verarbeiten), benötigen Sie die ausführbare Datei für die Kommandozeile. Für mehr Informationen lesen Sie bitte den Abschnitt über PHP auf der Kommandozeile. In diesem Fall benötigen Sie weder einen Server noch einen Browser.

Von jetzt an behandelt dieser Abschnitt nur noch die Installation von PHP für Webserver auf Unix und Windows mittels Serverschnittstellen und CGI. Sie werden außerdem in den folgenden Abschnitten Informationen über die ausführbare Datei für die Kommandozeile finden.

Den PHP-Quellcode und die -Binärpakete für Windows finden Sie unter » https://www.php.net/downloads.php.

# Installation auf Unix-Systemen

## Inhaltsverzeichnis

- Installation von Paketen unter Debian GNU/Linux und verwandten Distributionen
- Installing from packages on GNU/Linux distributions that use DNF
- Installation von Paketen oder Ports unter OpenBSD
- Installing from source on Unix and macOS systems
- CGI und Kommandozeilen Setups
- Apache 2.x auf Unixsystemen
- Nginx 1.4.x auf Unix-Systemen
- Lighttpd 1.4 auf Unix-Systemen
- LiteSpeed-/OpenLiteSpeed-Webserver auf Unix-Systemen
- Solaris-spezifische Tipps für die Installation

Die meisten Unix- (und Linux-) Betriebssysteme und Distributionen bieten über ihr Paketsystem fertige Pakete von PHP und dessen Erweiterungen an. Weitere Informationen zur Installation von PHP unter diesen Systemen sind in den entsprechenden Abschnitten zu finden.

Für einige Distributionen gibt es auch Paketquellen von Drittanbietern, die in der Regel eine größere Auswahl an verfügbaren Versionen und Erweiterungen enthalten.

Darüber hinaus kann PHP als Bestandteil mancher Anwendungsserver von Drittanbietern installiert werden.

Und schließlich kann PHP immer aus dem Quellcode installiert werden, was die größte Flexibilität bei der Auswahl der zu aktivierenden Funktionen, Erweiterungen und Server-APIs bietet. Es gibt Abschnitte mit Informationen über die Kompilierung und Konfiguration von PHP insbesondere für die Verwendung mit verschiedenen Server-APIs.

## Installation von Paketen unter Debian GNU/Linux und verwandten Distributionen

PHP kann nicht nur aus dem Quellcode installiert werden, sondern ist auch über Pakete von » Debian GNU/Linux verfügbar. Dies gilt auch für andere auf Debian basierende Distributionen wie Ubuntu, Kali Linux und Linux Mint.

Warnung

Pakete von Drittanbietern werden als inoffiziell betrachtet und nicht direkt vom PHP-Projekt unterstützt. Auftretende Fehler sollten dem Anbieter dieser inoffiziellen Pakete gemeldet werden, es sei denn, sie können mit den Paketen aus dem » offiziellen Downloadbereich reproduziert werden.

Die Pakete können mit den Befehlen apt oder aptitude installiert werden. Auf dieser Handbuchseite werden beide Befehle synonym verwendet.

### Die Verwendung von APT

Zunächst ist zu beachten, dass möglicherweise andere zugehörige Pakete gewünscht werden, wie `libapache-mod-php` für die Integration mit Apache 2, und `php-pear` für PEAR.

Außerdem sollten vor der Installation eines Pakets sichergestellt werden, dass die Paketliste auf dem aktuellen Stand ist. Üblicherweise kann dies durch das Kommando apt update erledigt werden.

Beispiel #1 Beispiel einer Debian-Installation mit Apache 2

    # apt install php-common libapache2-mod-php php-cli

APT wird automatisch das PHP-Modul für Apache 2 sowie alle seine Abhängigkeiten installieren und danach aktivieren. Damit die Änderungen in Kraft treten, muss Apache neu gestart werden. Zum Beispiel:

Beispiel #2 Stoppen und Starten von Apache nach der Installation von PHP

    # /etc/init.d/apache2 stop
    # /etc/init.d/apache2 start

### Bessere Kontrolle über die Konfiguration

Im letzten Abschnitt wurde PHP nur mit den Basismodulen installiert. In den meisten Fällen werden weitere Module wie MySQL, cURL oder GD gewünscht. Auch diese Module können mit dem Befehl apt installiert werden.

Beispiel #3 Methoden zur Anzeige weiterer PHP-Pakete

    # apt-cache search php
    # apt search php | grep -i mysql
    # aptitude search php

Die Paketliste enthält eine große Anzahl von Paketen, darunter grundlegende PHP-Komponenten wie `php-cgi`, `php-cli` und `php-dev` sowie viele PHP-Erweiterungen. Wenn Erweiterungen installiert werden, werden bei Bedarf automatisch zusätzliche Pakete installiert, um die Abhängigkeiten dieser Pakete zu erfüllen.

Beispiel #4 PHP mit MySQL und cURL installieren

    # apt install php-mysql php-curl

APT fügt die entsprechenden Zeilen automatisch in die verschiedenen zur php.ini gehörenden Dateien wie /etc/php/7.4/php.ini, /etc/php/7.4/conf.d/*.ini etc. ein. Abhängig von der Erweiterung wird es Einträge ähnlich wie `extension=foo.so` hinzufügen. Das Neustarten des Web-Servers (z. B. Apache) ist erforderlich, damit die Änderungen wirksam werden.

### Bekannte Probleme

- Wenn die PHP-Skripte nicht vom Web-Server geparst werden, ist es wahrscheinlich, dass PHP nicht zur Konfigurationsdatei des Web-Servers hinzugefügt wurde. Unter Debian ist dies meist /etc/apache2/apache2.conf (oder ähnlich). Im Debian-Handbuch finden Sie weitere Details hierzu.
- Falls eine Erweiterung anscheinend installiert wurde, aber die Funktionen nicht definiert sind, müssen Sie sicherstellen, dass die entsprechede INI-Datei geladen wurde und/oder dass der Web-Server nach der Installation neu gestartet wurde.

## Installing from packages on GNU/Linux distributions that use DNF

While PHP can be installed from source, it is also available through packages on systems that use DNF, such as Red Hat Enterprise Linux, OpenSUSE, Fedora, CentOS, Rocky Linux, and Oracle Enterprise Linux.

Warnung

Pakete von Drittanbietern werden als inoffiziell betrachtet und nicht direkt vom PHP-Projekt unterstützt. Auftretende Fehler sollten dem Anbieter dieser inoffiziellen Pakete gemeldet werden, es sei denn, sie können mit den Paketen aus dem » offiziellen Downloadbereich reproduziert werden.

The packages can be installed using the dnf command.

### Installing packages

First, note that other related packages may be desired like `php-pear` for » PEAR, or `php-mysqlnd` for the MySQL extension.

Second, before installing a package, it's wise to ensure the package list is up to date. Typically, this is done by running the command dnf update.

Beispiel #1 DNF Install Example

    # dnf install php php-common

DNF will automatically install the configuration for PHP for the web server, but it may need to be restarted in order for the changes to take effect. For example:

Beispiel #2 Restarting Apache once PHP is installed

    # sudo systemctl restart httpd

### Better control of configuration

In the last section, PHP was installed with only core modules. It's very likely that additional modules will be desired, such as MySQL, cURL, GD, etc. These may also be installed via the dnf command.

Beispiel #3 Methods for listing additional PHP packages

    # dnf search php

The list of packages will include a large number of packages that includes basic PHP components, such as `php-cli`, `php-fpm`, and `php-devel`, as well as many PHP extensions. When extensions are installed, additional packages will be automatically installed as necessary to satisfy the dependencies of those packages.

Beispiel #4 Install PHP with MySQL, GD

    # dnf install php-mysqlnd php-gd

DNF will automatically add the appropriate lines to the different php.ini related files like /etc/php/8.3/php.ini, /etc/php/8.3/conf.d/*.ini, etc. and depending on the extension will add entries similar to `extension=foo.so`. However, restarting the web server (like Apache) is required before these changes take effect.

## Installation von Paketen oder Ports unter OpenBSD

Dieser Abschnitt enthält Hinweise und Tipps zur Installation von PHP unter » OpenBSD.

### Verwendung von Paketen

Binärpakete zu verwenden, um PHP auf OpenBSD zu installieren, ist die empfohlene und zugleich einfachste Methode. Die verschiedenen Module sind vom Kernpaket getrennt und können unabhängig voneinander installiert und entfernt werden. Die benötigten Dateien finden Sie auf Ihrer OpenBSD-CD oder auf der FTP-Seite.

Das wichtigste Paket, das Sie installieren müssen, ist php; es enthält die Basissoftware (plus fpm, gettext und iconv) und steht möglicherweise in mehreren Versionen zur Auswahl. Weiter geht es mit den Modulpaketen, wie php-mysqli oder php-imap. Um diese Module in Ihrer php.ini zu aktivieren oder zu deaktivieren, müssen Sie den Befehl phpxs verwenden.

Beispiel #1 Beispiel für die Installation von OpenBSD-Paketen

    # pkg_add php
    # pkg_add php-apache
    # pkg_add php-mysqli
      (Installation der PEAR-Bibliotheken)
    # pkg_add pear

    Befolgen Sie die Anweisungen, die bei jedem Package angegeben werden!

      (um Pakete zu entfernen)
    # pkg_delete php
    # pkg_delete php-apache
    # pkg_delete php-mysqli
    # pkg_delete pear

Weitere Informationen über OpenBSD-Binärpakete finden Sie in der Manpage » packages(7).

### Verwendung von Ports

Sie können PHP auch aus dem Quelltext kompilieren, indem Sie den » Ports-Tree verwenden. Dies ist jedoch nur für Benutzer empfehlenswert, die mit OpenBSD vertraut sind. Der PHP-Port ist in core und extensions aufgeteilt. Die extensions erzeugen Unterpakete für alle unterstützten PHP-Module. Wenn Sie manche dieser Module nicht erstellen wollen, verwenden Sie den FLAVOR no_*. Um zum Beispiel die Erstellung des imap-Moduls zu überspringen, setzen Sie den FLAVOR auf no_imap.

### Häufige Probleme

- Apache und Nginx sind unter OpenBSD nicht mehr die Standard-Server, können aber beide problemlos über Ports und Pakete installiert werden. Der neue Standard-Server wird einfach als "httpd" bezeichnet.
- Die Standardinstallation von httpd läuft in einem » chroot(2)-Jail, das den Zugriff von PHP-Skripten auf Dateien unter /var/www beschränkt. Sie müssen daher das Verzeichnis /var/www/tmp erstellen, in dem PHP-Session-Dateien gespeichert werden, oder ein alternatives Session-Backend verwenden. Außerdem müssen die Datenbank-Sockets innerhalb des Jails platziert werden oder auf der localhost-Schnittstelle lauschen. Wenn Sie Netzwerkfunktionen verwenden, müssen einige Dateien aus /etc wie /etc/resolv.conf und /etc/services nach /var/www/etc kopiert werden. Das PEAR-Paket von OpenBSD installiert sich automatisch in die richtigen chroot-Verzeichnisse.
- Das OpenBSD-Paket für die Erweiterung » gd benötigt Xorg, um installiert zu werden. Wenn es nicht bereits bei der Basisinstallation durch Hinzufügen des xbase.tgz-Dateisets installiert wurde, kann es auch nachträglich hinzugefügt werden (siehe » OpenBSD FAQ#4).

## Installing from source on Unix and macOS systems

Prerequisite software for compiling:

- » GNU make
- A C compiler (as of PHP 8.0.0, C99 compatibility is required; as of PHP 8.4.0, C11 compatibility is required)
- A web server
- Any module specific components (such as GD, PDF libs, etc.)

When building directly from Git sources or after custom modifications, these additional tools may be necessary:

- » autoconf:
  - PHP 7.3 and later: 2.68+
  - PHP 7.2: 2.64+
  - PHP 7.1 and earlier: 2.59+
- » re2c:
  - PHP 8.3 and later: 1.0.3+
  - PHP 8.2 and earlier: 0.13.4+
- » bison:
  - PHP 7.4 and later: 3.0.0+
  - PHP 7.3 and earlier: 2.4+ (including Bison 3.x)

For more detailed steps for compiling PHP from source, see the » README.md file in the source tarball.

The initial PHP setup and configuration process is controlled by the use of the command line options of the configure script. A list of available options along with short explanations can be shown by running ./configure --help. This manual documents the different options separately. The core options can be found in the appendix, while the different extension specific options are described on the reference pages.

After the configuration script was been run, PHP can be built using the make command. The Installation section of the frequently asked questions has further information about how to handle build problems.

> Hinweis: Some Unix systems (such as OpenBSD and SELinux) may disallow mapping pages both writable and executable for security reasons, what is called » PaX MPROTECT or » W^X violation protection. This kind of memory mapping is necessary for PCRE's JIT support, so either PHP has to be built without PCRE's JIT support, or the binary has to be whitelisted by any means provided by the system.

> Hinweis: Cross-compiling for ARM with the Android toolchain is currently not supported.

## CGI und Kommandozeilen Setups

Sandardmäßig wird PHP als CLI und CGI Programm kompiliert, wobei letzteres für die CGI-Verarbeitung verwendet werden kann. Sollte Ihr Webserver die Möglichkeit der Einbindung als Modul besitzen, dann sollten Sie grundsätzlich diese Option aus Leistungsgründen bevorzugen. CGI Versionen bieten jedoch den Vorteil verschiedene PHP-Seiten unter unterschiedlichen Benutzerkennungen auszuführen.

Warnung

Wenn Sie das CGI-Setup verwenden, ist Ihr Server für einige mögliche Angriffe anfällig. Wie Sie sich vor diesen Angriffen schützen können, entnehmen Sie bitte dem Kapitel über CGI-Sicherheit.

### Testen

Wenn Sie PHP als CGI Programm kompiliert haben, dann können Sie Ihren Build mit make test überprüfen. Es ist generell eine gute Idee Ihren Build zu testen. Auf diesem Weg können sie Probleme frühzeitig erkennen statt durch diese später Schwierigkeiten zu bekommen.

### Benutzung von Variablen

Einige vom Server bereitgestellte Variablen sind nicht in der aktuellen » CGI/1.1 Spezifikation spezifiziert. Nur die folgenden Variablen sind dort definiert: AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL und SERVER_SOFTWARE. Alles andere ist als Hersteller spezifische Erweiterung zu verstehen.

## Apache 2.x auf Unixsystemen

Dieser Abschnitt enthält Hinweise und Tipps, die sich auf die Installation von PHP speziell für Apache 2.x auf Unixsystemen beziehen.

Warnung

Wir empfehlen, in einer Produktionsumgebung kein Threaded MPM mit Apache2 zu verwenden. Verwenden Sie stattdessen das Prefork MPM, welches der Standard-MPM für Apace 2.0 und 2.2 ist. Für weitere Informationen und die Gründe lesen Sie bitte den entsprechenden FAQ-Eintrag über die Verwendung von Apache2 mit Threaded MPM.

Die » Apache Dokumentation ist die maßgebliche Informationsquelle für den Apache 2.x Server. Dort können weitere Informationen über Installationsoptionen für Apache gefunden werden.

Die aktuellste Version des Apache HTTP Servers kann von der » Apache Download Site bezogen werden, und eine passende PHP-Version von den oben angegebenen Quellen. Dieser Schnelleinstieg behandelt nur die Grundlagen, um mit Apache 2.x und PHP einzusteigen. Für mehr Informationen lesen Sie bitte die » Apache-Dokumentation. Versionsnummern wurden hier ausgelassen, um sicherzustellen, dass die Anweisungen nicht inkorrekt sind. In den folgenden Beispielen sollte 'NN' durch die spezifische Version des verwendeten Apache ersetzt werden.

Es gibt aktuell zwei Versionen von Apache 2.x: 2.4 und 2.2. Obwohl es verschiedene Gründe gibt, sich für eine zu entscheiden, ist 2.4 die aktuellste Version, und diejenige, die empfohlen wird, wenn sie diese Möglichkeit haben. Allerdings funktionieren die folgenden Anweisungen sowohl für 2.4 als auch 2.2. Es ist zu beachten, dass Apache httpd 2.2 offiziell das Lebensende erreicht hat, so dass keine Weiterentwicklungen oder Fehlerkorrekturen mehr erfolgen werden.

1. Beziehen Sie den Apache HTTP Server vom oben genannten Ort, und entpacken Sie ihn:

       tar -xzf httpd-2.x.NN.tar.gz

2. Beziehen und entpacken Sie die PHP-Quellen gleichermaßen:

       tar -xzf php-NN.tar.gz

3. Kompilieren und installieren Sie Apache. Entnehmen Sie der Apache-Installationsdokumentation weitere Details zur Kompilierung.

       cd httpd-2_x_NN
       ./configure --enable-so
       make
       make install

4. Nun steht Ihnen Apache 2.x.NN unter /usr/local/apache2 zur Verfügung, konfiguriert mit Unterstützung für nachladbare Module und dem Standard MPM Prefork. Um diese Installation zu testen, verwenden Sie die übliche Prozedur, den Apacheserver zu starten, also z. B.:

       /usr/local/apache2/bin/apachectl start

   Stoppen Sie nun den Server, um mit der Konfiguration von PHP fortzufahren:

       /usr/local/apache2/bin/apachectl stop

5. Konfigurieren und kompilieren Sie nun Ihr PHP. Dies ist die Stelle, an der Sie Ihr PHP mit verschiedenen Optionen, wie etwa installierten Erweiterungen, anpassen können. Rufen Sie ./configure --help auf, um eine Liste der verfügbaren Optionen zu erhalten. In unserem Beispiel werden wir eine einfache Konfiguration mit Unterstützung für Apache 2 und MySQL erzeugen.

   Wenn Sie Apache aus den Quelltexten kompiliert haben, wie oben beschrieben wurde, dann stimmt im folgenden Beispiel der Pfad von apxs, aber wenn Sie Apache auf andere Weise installiert haben, müssen Sie den Pfad von apxs entsprechend anpassen. Es ist zu beachten, dass einige Distros möglicherweise apxs zu apxs2 umbenennen.

       cd ../php-NN
       ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-pdo-mysql
       make
       make install

   Wenn Sie sich entscheiden, Ihre Konfigurationsoptionen nach der Installation zu ändern, müssen Sie die Schritte configure, make, und make install erneut ausführen. Um das neue Modul nutzen zu können, muss Apache nur neu gestartet werden. Eine erneute Kompilierung des Apache ist nicht nötig.

   Beachten Sie, dass, wenn nicht anders erwähnt, make install ebenso PEAR und verschiedene PHP-Werkzeuge wie phpize, PHP CLI und anderes installieren wird.

6. Ihre php.ini einrichten

       cp php.ini-development /usr/local/lib/php.ini

   Sie können Ihre `.ini`-Datei ändern, um verschiedene PHP-Optionen zu setzen. Wenn Sie die php.ini-Datei an einer anderen Stelle bevorzugen, verwenden Sie `--with-config-file-path=/some/path` in Schritt 5.

   Wenn Sie sich stattdessen für php.ini-production entscheiden, stellen Sie sicher, dass Sie die darin enthaltene Liste von Änderungen lesen, da diese das Verhalten von PHP beeinflussen.

7. Bearbeiten Sie Ihre httpd.conf, um das PHP Modul zu laden. Der Pfad auf der rechten Seite der Anweisung `LoadModule` muss auf den Ort des PHP-Moduls auf Ihrem System zeigen. Das obige make install könnte dies bereits für Sie hinzugefügt haben, aber Stellen Sie sicher, dass dies der Fall ist.

   Für PHP 8:

       LoadModule php_module modules/libphp.so

   Für PHP 7:

       LoadModule php7_module modules/libphp7.so

8. Weisen Sie Apache an, bestimmte Dateiendungen als PHP Skripte zu behandeln. Zum Beispiel werden wir den Apache Dateien mit der Endung `.php` als PHP ausführen lassen. Anstatt nur die Apache-Direktive `AddType` zu verwenden, wollen wir zusätzlich verhindern, dass potentiell gefährliche hochgeladene und erzeugte Dateien wie exploit.php.jpg als PHP-Dateien ausgeführt werden. Wenn Sie dieses Beispiel verwenden, können Sie jede Dateiendung als PHP interpretieren lassen, wenn Sie sie einfach hinzufügen. Wir demonstrieren dies, indem wir `.php` einfügen.

       <FilesMatch \.php$>
           SetHandler application/x-httpd-php
       </FilesMatch>

   Oder wenn wir erlauben wollen, dass nur Dateien mit den Endungen `.php`, `.php2`, `.php3`, `.php4`, `.php5`, `.php6` und `.phtml` als PHP interpretiert werden können, verwenden wir ein Statement wie dieses:

       <FilesMatch "\.ph(p[2-6]?|tml)$">
           SetHandler application/x-httpd-php
       </FilesMatch>

   Und um zu erlauben, dass `.phps`-Dateien vom PHP Source-Filter verarbeitet und als Quellcode mit Syntax-Highlighting angezeigt werden, verwenden Sie:

       <FilesMatch "\.phps$">
           SetHandler application/x-httpd-php-source
       </FilesMatch>

   `mod_rewrite` kann verwendet werden, um zu erlauben, dass jede beliebige `.php`-Datei als Quellcode mit Syntax-Highlighting angezeigt wird, ohne dass Sie die Datei zu `.phps` umbenennen oder kopieren müssen:

       RewriteEngine On
       RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]

   Der PHP-Source-Filter sollte auf Produktionssystemen nicht aktiviert werden, da er vertrauliche oder anderweitig sensible Informationen, die im Quellcode enthalten sind, preisgeben könnte.

9. Verwenden Sie die übliche Prozedur, um den Apache-Server zu starten, z. B.:

       /usr/local/apache2/bin/apachectl start

   ODER

       service httpd restart

Wenn Sie den obigen Anweisungen folgen, werden Sie einen laufenden Apache2 mit Unterstützung für PHP als `SAPI`-Modul erhalten. Natürlich existieren für Apache und PHP viele weitere Konfigurationseinstellungen. Verwenden Sie ./configure --help im jeweiligen Quellcodeverzeichnis, um weitere Informationen zu erhalten.

Apache2 kann multithreaded kompiliert werden, indem das worker-MPM anstatt des standardmäßigen prefork-MPM für den Build gewählt wird. Dies erfolgt, indem die folgende Option zu dem Argument, das weiter oben in Schritt 3 an ./configure übergeben wird, hinzugefügt wird:

    --with-mpm=worker

Dies sollte nicht durchgeführt werden, ohne sich der Konsequenzen dieser Entscheidung bewusst zu sein, und zumindest eine angemesse Kenntnis der Implikationen zu haben. Die Apache-Dokumentation bezüglich der » MPM-Module erörtert MPMs sehr ausführlich.

> Hinweis:

> Das Apache MultiViews FAQ erörtert die Verwendung von Multiviews mit PHP.

> Hinweis:

> Um eine Multithreaded-Version von Apache zu erzeugen, muss das Zielsystem Threads unterstützen. In diesem Fall sollte auch PHP mit der Zend Thread Safety (ZTS) kompiliert werden. Unter dieser Konfiguration sind nicht alle Erweiterungen verfügbar. Die empfohlene Einstellung ist es, Apache mit dem standardmäßigen prefork-MPM-Modul zu bauen.

## Nginx 1.4.x auf Unix-Systemen

Diese Dokumentation deckt die Installation und Konfiguration von PHP mit PHP-FPM für ein Nginx 1.4.x HTTP Server ab.

Diese Anleitung setzt voraus, dass Sie Nginx aus dem Quelltext erstellt haben und dadurch alle Binaries und Konfigurationsdateien in `/usr/local/nginx` abgelegt sind. Wenn dies nicht der Fall ist und Sie Nginx über eine andere Quelle bezogen haben, dann lesen Sie bitte im » Nginx-Wiki nach, um dieses Handbuch für Ihre Installation anzupassen.

Diese Anleitung wird die Grundlagen der Konfiguration eines Nginx-Servers abdecken, um PHP-Applikationen auszuführen und unter Port 80 bereitzustellen. Wenn Sie Ihre Installation über den Rahmen dieser Dokumentation hinaus optimieren möchten, sollten Sie die Nginx- und PHP-FPM-Dokumentation lesen.

Hinweis: In dieser Dokumentation wurden Versionsnummern durchgehend mit einem 'x' ersetzt. Dies stellt sicher, dass die Dokumentation auch für künftige Versionen richtig bleibt. Bitte ersetzen Sie diese soweit notwendig mit Ihrer entstprechenden Version.

1. Es wird empfohlen, dass Sie die » Installationsseite im Nginx-Wiki besuchen, um Nginx für Ihr System zu erhalten und zu installieren.

2. Den PHP-Quellcode herunterladen und entpacken:

       tar zxf php-x.x.x

3. Konfigurieren und Erstellen von PHP. Dies ist die Stelle, an der Sie Ihre PHP-Installation individuell mit verschiedenen Optionen anpassen. Sowas wie: welche Erweiterung (extension) aktiviert (enabled) wird. Führen Sie ./configure --help für eine Liste der verfügbaren Optionen aus. In unserem Beispiel werden wir eine einfache Konfiguration mit PHP-FPM- und MySQLi-Unterstützung durchführen.

       cd ../php-x.x.x
       ./configure --enable-fpm --with-mysqli
       make
       sudo make install

4. Erhalten und verschieben von Konfigurationsdateien an die richtige Stelle

       cp php.ini-development /usr/local/php/php.ini
       cp /usr/local/etc/php-fpm.conf.default /usr/local/etc/php-fpm.conf
       cp sapi/fpm/php-fpm /usr/local/bin

5. Es ist wichtig, dass wir Nginx daran hindern Anfragen an das PHP-FPM Backend zu leiten, wenn die Datei nicht existiert. Dies erlaubt uns willkürliche Skript Eingaben (script injection) zu verhindern.

   Wir können dies durch eine Einstellung beheben, indem wir innerhalb unserer php.ini Datei die cgi.fix_pathinfo Direktive auf `0` setzen.

   Einlesen der php.ini:

       vim /usr/local/php/php.ini

   Positionieren auf `cgi.fix_pathinfo=` und wie folgt modifizieren:

       cgi.fix_pathinfo=0

6. php-fpm.conf muss angepasst werden, damit php-fpm als User www-data und Gruppe www-data ausgeführt wird, bevor wir es Service starten können:

       vim /usr/local/etc/php-fpm.d/www.conf

   Finden und modifizieren Sie folgendes:

       ; Unix user/group of processes
       ; Note: The user is mandatory. If the group is not set, the default user's group
       ;       will be used.
       user = www-data
       group = www-data

   Der php-fpm Service kann wie folgt gestartet werden:

       /usr/local/bin/php-fpm

   Diese Anleitung wird nicht weiter auf die php-fpm Konfiguration eingehen. Wenn Sie weiteres Interesse an der php-fpm Konfiguration haben, dann ziehen Sie bitte die entsprechende Dokumentation heran.

7. Nginx muss jetzt konfiguriert werden, um PHP Applikationen ablaufen zu lassen:

       vim /usr/local/nginx/conf/nginx.conf

   Modifizieren Sie den Bereich voreingestellte Positionen, um zu gewährleisten, dass .php Dateien verarbeitet werden:

       location / {
           root   html;
           index  index.php index.html index.htm;
       }

   Der nächste Schritt soll sicherstellen, dass .php Dateien an des PHP-FPM Backend geleitet werden. Geben Sie unter dem auskommentierten standard PHP location Block folgendes ein:

       location ~* \.php$ {
           fastcgi_index   index.php;
           fastcgi_pass    127.0.0.1:9000;
           include         fastcgi_params;
           fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
           fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
       }

   Neustart von Nginx.

       sudo /usr/local/nginx/sbin/nginx -s stop
       sudo /usr/local/nginx/sbin/nginx

8. Erstellen einer Test Datei

       rm /usr/local/nginx/html/index.html
       echo "<?php phpinfo(); ?>" >> /usr/local/nginx/html/index.php

   Nun navigieren Sie zu http://localhost. Die Funktion phpinfo() sollte nun angezeigt werden.

Folgen Sie den obigen Schritten und Sie werden ein laufenden Nginx Web-Server mit Unterstützung für PHP als ein `FPM` `SAPI` Modul erhalten. Natürlich sind noch viel mehr Konfigurations-Einstellungen für Nginx und PHP verfügbar. Für weitere Informationen geben Sie ./configure --help im entsprechenden Quellpfad ein.

## Lighttpd 1.4 auf Unix-Systemen

Dieser Abschnitt enthält Notizen und Hinweise zur Installtion von Lighttpd 1.4 für PHP auf Unix-Systemen.

Vor der Installation von Lighttpd wird empfohlen, die Installationsanleitung der » Lighttpd-Dokumentation zu lesen.

FastCGI ist die bevorzugte SAPI, um PHP mit Lighttpd zu verbinden. FastCGI wird in php-cgi automagisch aktiviert.

### Lighttpd einen php-Prozess starten lassen

Um Lighttpd so zu konfigurieren, dass es sich mit PHP verbindet und FastCGI-Prozesse startet, muss die Datei lighttpd.conf editiert werden. Auf einem lokalen System werden vorzugsweise Sockets für die Verbindung zu FastCGI-Prozessen verwendet.

Beispiel #1 Ein Teil der lighttpd.conf

    server.modules += ( "mod_fastcgi" )

    fastcgi.server = ( ".php" =>
      ((
        "socket" => "/tmp/php.socket",
        "bin-path" => "/usr/local/bin/php-cgi",
        "bin-environment" => (
          "PHP_FCGI_CHILDREN" => "16",
          "PHP_FCGI_MAX_REQUESTS" => "10000"
        ),
        "min-procs" => 1,
        "max-procs" => 1,
        "idle-timeout" => 20
      ))
    )

Die Direktive bin-path erlaubt es Lighttpd, FastCGI-Prozesse dynamisch zu erzeugen. PHP erzeugt die Kindprozesse entsprechend der Umgebungsvariable PHP_FCGI_CHILDREN. Die Direktive `bin-environment` definiert die Umgebung für die erzeugten Prozesse. PHP beendet einen Kindprozess, nachdem die in PHP_FCGI_MAX_REQUESTS festgelegte Anzahl von Anfragen erreicht ist. Die Direktiven `min-procs` und `max-procs` sollten bei PHP generell vermieden werden. PHP verwaltet seine eigenen Kindprozesse und OpCode-Caches wie APC nutzen nur die von PHP verwalteten Kindprozesse. Wenn `min-procs` auf einen Wert größer `1` gesetzt ist, wird die Anzahl der PHP-Responder mit PHP_FCGI_CHILDREN multipliziert (2 min-procs * 16 Kindprozesse ergibt 32 Responder).

### Prozesse mit spawn-fcgi erzeugen

Lighttpd stellt das Programm spawn-fcgi zur Verfügung, um das Erzeugen von FastCGI-Prozessen zu vereinfachen.

### php-cgi starten

Es ist möglich, Prozesse ohne spawn-fcgi zu starten, jedoch ist dafür etwas Arbeit nötig. Die Umgebungsvariable PHP_FCGI_CHILDREN definiert, wieviele Kindprozesse PHP erzeugt, um eingehende Anfragen zu bearbeiten. PHP_FCGI_MAX_REQUESTS definiert, wie lange (in Anfragen) jeder Kindprozess existiert. Hier ist ein einfaches Bash-Skript, um das Erzeugen von PHP-Respondern zu vereinfachen.

Beispiel #2 FastCGI-Responder erzeugen

    #!/bin/sh

    # Ort des php-cgi-Programms
    PHP=/usr/local/bin/php-cgi

    # Ort der PID-Datei
    PHP_PID=/tmp/php.pid

    # Bindung an eine Adresse
    #FCGI_BIND_ADDRESS=10.0.1.1:10000
    # Bindung an einen Domain-Socket
    FCGI_BIND_ADDRESS=/tmp/php.sock

    PHP_FCGI_CHILDREN=16
    PHP_FCGI_MAX_REQUESTS=10000

    env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
           PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
           $PHP -b $FCGI_BIND_ADDRESS &

    echo $! > "$PHP_PID"

### Mit entfernten FCGI-Instanzen verbinden

Um Anwendungen besser zu skalieren, können FastCGI-Instanzen auf mehreren entfernten Rechnern gestartet werden.

Beispiel #3 Mit entfernten FCGI-Instanzen verbinden

    fastcgi.server = ( ".php" =>
       (( "host" => "10.0.0.2", "port" => 1030 ),
        ( "host" => "10.0.0.3", "port" => 1030 ))
    )

## LiteSpeed-/OpenLiteSpeed-Webserver auf Unix-Systemen

LiteSpeed PHP ist ein PHP-Build, das für die Verwendung mit LiteSpeed-Produkten über das LiteSpeed-SAPI optimiert wurde. LSPHP läuft als eigener Prozess und verfügt über eine eigenständige Binärdatei, die als einfache Befehlszeilen-Binärdatei zur Ausführung von PHP-Skripten über die Befehlszeile verwendet werden kann.

Die LSAPI ist eine hochoptimierte API, die die Kommunikation zwischen LiteSpeed und Web-Engines von Drittanbietern ermöglicht. Ihr Protokoll ähnelt dem FCGI, ist aber effizienter.

Diese Dokumentation beschreibt die Installation und Konfiguration von PHP mit LSAPI für den LiteSpeed-Webserver und den OpenLiteSpeed-Webserver.

In dieser Anleitung wird davon ausgegangen, dass entweder LSWS oder OLS unter Verwendung der jeweiligen Standardpfade und -flags installiert wurde. Das standardmäßige Installationsverzeichnis für beide Webserver ist /usr/local/lsws und beide können aus dem Unterverzeichnis bin gestartet werden.

Bitte beachten Sie, dass in dieser Dokumentation die Versionsnummern durch ein `x` ersetzt wurden, um sicherzustellen, dass diese Dokumentation auch in Zukunft korrekt bleibt. Bitte ersetzen Sie diese, falls erforderlich, durch die entsprechenden Versionsnummern.

1. Um entweder den LiteSpeed-Webserver oder den OpenLiteSpeed-Webserver herunterzuladen und zu installieren, besuchen Sie die » Installationsseite der LiteSpeed-Dokumentation oder die » Installationsseite der OpenLiteSpeed-Dokumentation.

2. Herunterladen und Entpacken des PHP-Quellcodes:

       mkdir /home/php
       cd /home/php
       wget http://us1.php.net/get/php-x.x.x.tar.gz/von/diesem/mirror
       tar -zxvf php-x.x.x.tar.gz
       cd php-x.x.x

3. Konfigurieren und erstellen Sie PHP. Hier können Sie PHP mit verschiedenen Optionen anpassen, z. B. welche Erweiterungen aktiviert werden sollen. Führen Sie ./configure --help aus, um eine Liste der verfügbaren Optionen zu erhalten. In diesem Beispiel verwenden wir die empfohlenen Standardoptionen für die Konfiguration des LiteSpeed-Webservers:

       ./configure ... '--with-litespeed'
       make
       sudo make install

4. Überprüfen der LSPHP-Installation

   Eine der einfachsten Möglichkeiten zu überprüfen, ob die Installation von PHP erfolgreich war, ist, den folgenden Code auszuführen:

       cd /usr/local/lsws/fcgi-bin/
       ./lsphp5 -v

   Dies sollte Informationen über den neuen PHP-Build zurückgeben:

       PHP 5.6.17 (litespeed) (built: Mar 22 2016 11:34:19)
       Copyright (c) 1997-2014 The PHP Group
       Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies

   Beachten Sie das `litespeed` in Klammern. Dies bedeutet, dass die PHP-Binärdatei mit LSAPI-Unterstützung erstellt wurde.

Nach den oben beschriebenen Schritten sollte der LiteSpeed-/OpenLiteSpeed-Webserver nun als SAPI-Erweiterung mit Unterstützung für PHP laufen. Es gibt noch viele weitere Möglichkeiten der Konfiguration von LSWS/OLS und PHP. Weitere Informationen finden Sie in der LiteSpeed-Dokumentation über » PHP.

Verwendung von LSPHP über die Befehlszeile:

Der LSPHP- (LSAPI + PHP) Befehlszeilenmodus wird verwendet, um PHP-Skripte auf einem entfernten Server zu verarbeiten, auf dem nicht unbedingt ein Webserver läuft. Er wird verwendet, um PHP-Skripte zu verarbeiten, die sich auf einem (separaten) lokalen Webserver befinden. Da die PHP-Verarbeitung auf einen entfernten Server verlagert wird, eignet sich diese Konfiguration für die Skalierbarkeit von Diensten.

LSPHP von der Befehlszeile auf einem entfernten Server starten: LSPHP ist eine ausführbare Datei, die manuell gestartet und mit der Kommandozeilenoption -b socket_address an eine IPv4-, IPv6- oder Unix-Domain-Socket-Adresse gebunden werden kann.

Beispiele:

LSPHP soll sich auf allen IPv4- und IPv6-Adressen an Port 3000 binden:

    /path/to/lsphp -b [::]:3000

LSPHP soll sich auf allen IPv4-Adressen an Port 3000 binden:

    /path/to/lsphp -b *:3000

LSPHP soll sich an die Adresse 192.168.0.2:3000 binden:

    /path/to/lsphp -b 192.168.0.2:3000

LSPHP soll Anfragen auf dem Unix-Domain-Socket `/tmp/lsphp_manual.sock` annehmen:

    /path/to/lsphp -b /tmp/lsphp_manual.sock

Umgebungsvariablen können vor der ausführbaren LSPHP-Datei hinzugefügt werden:

    PHP_LSAPI_MAX_REQUESTS=500 PHP_LSAPI_CHILDREN=35 /path/to/lsphp -b IP_address:port

Derzeit kann LiteSpeed PHP mit dem LiteSpeed-Webserver, dem OpenLiteSpeed-Webserver und mit mod_lsapi von Apache verwendet werden. Anweisungen für die serverseitige Konfiguration finden Sie in den entsprechenden Dokumentationsseiten für den » LiteSpeed-Webserver und » OpenLiteSpeed.

LSPHP kann auf verschiedene Arten installiert werden.

CentOS: Unter CentOS kann LSPHP mittels » RPM aus dem LiteSpeed- oder dem Remi-Repositorium installiert werden.

Debian: Unter Debian kann LSPHP mittels » apt aus dem LiteSpeed-Repositorium installiert werden.

cPanel: Die Installation von LSPHP mit cPanel und LSWS/OLS unter Verwendung von EasyApache 4 wird auf der entsprechenden » Dokumentationsseite beschrieben.

Plesk: Plesk kann mit LSPHP auf CentOS, CloudLinux, Debian und Ubuntu verwendet werden. Weitere Details hierzu finden Sie auf der jeweiligen » Dokumentationsseite

## Solaris-spezifische Tipps für die Installation

Dieser Abschnitt enthält Hinweise und Tipps zur Installation von PHP unter Solaris-Systemen.

### Benötigte Software

Bei Solaris-Installationen sind häufig keine C-Compiler und entsprechende Werkzeuge vorhanden. Lesen Sie diese FAQ, um zu erfahren, warum von einigen dieser Werkzeuge die GNU-Versionen verwendet werden müssen.

Zum Entpacken der PHP-Distribution benötigen Sie

- tar
- gzip oder
- bzip2

Zum Kompilieren von PHP benötigen Sie

- gcc (empfohlen, andere C-Compiler könnten funktionieren)
- make
- GNU sed

Um zusätzliche Erweiterungen zu bauen oder den Code von PHP zu verändern, benötigen Sie möglicherweise auch

- re2c
- bison
- m4
- autoconf
- automake

Darüber hinaus müssen Sie die für Ihre Konfiguration erforderliche zusätzliche Software, wie Oracle oder MySQL, installieren (und möglicherweise kompilieren).

### Verwendung von Paketen

Sie können den Installationsprozess unter Solaris vereinfachen, indem Sie pkgadd verwenden, um die meisten der benötigten Komponenten zu installieren. Das Image Packaging System (IPS) für Solaris 11 Express enthält ebenfalls die meisten der benötigten Komponenten für die Installation mit dem pkg-Befehl.

# Installation unter macOS

## Inhaltsverzeichnis

- Installation unter macOS mit Paketen von Drittanbietern
- Kompilieren von PHP unter macOS
- Verwendung des mitgelieferten PHP vor macOS Monterey

PHP war in den macOS-Versionen 10 und 11 enthalten, ist jedoch seit macOS 12 (Monterey) nicht mehr dabei. Für die Installation auf neueren Versionen müssen entweder Pakete von Drittanbietern verwendet oder der Quellcode kompiliert werden.

## Installation unter macOS mit Paketen von Drittanbietern

Es gibt verschiedene vorkompilierte und gepackte Versionen von PHP für macOS. Sie können zum Aufsetzen von Standardkonfigurationen verwendet werden. Sobald Sie spezielle Funktionen benötigen (z. B. unterschiedliche Datenbanktreiber), müssen Sie sich eventuell Ihr eigenes PHP und/oder auch einen eigenen Webserver kompilieren. Wenn Sie mit dem Kompilieren eigener Software nicht vertraut sind, sollten Sie prüfen, ob nicht bereits jemand ein gepacktes und vorkompiliertes System bereitstellt, das Ihren Anforderungen entspricht.

Eine einfache Möglichkeit, PHP unter macOS zu installieren, bietet der » Homebrew-Paketmanager.

1. Homebrew nach der Anleitung auf der Website installieren.

2. brew install php

Die folgenden alternativen Quellen bieten ebenfalls einfach zu installierende Pakete und vorkompilierte Programme für PHP unter macOS an:

- » MacPorts
- » Fink

## Kompilieren von PHP unter macOS

Um PHP unter macOS zu kompilieren, nutzen Sie die Unix-Installationsanleitung.

## Verwendung des mitgelieferten PHP vor macOS Monterey

PHP ist seit macOS X (10.0.0) und vor macOS Monterey (12.0.0) in macOS enthalten. Um PHP mit dem Standard-Webserver zu verwenden, müssen nur ein paar Zeilen in der Apache-Konfigurationsdatei httpd.conf auskommentiert werden. CGI und/oder CLI sind standardmäßig aktiviert (einfach zugänglich über das Terminal-Programm).

Die folgende Anleitung, um PHP zu aktivieren, ermöglicht ein einfaches und schnelles Aufsetzen einer lokalen Entwicklungsumgebung. Es wird dringend empfohlen, PHP immer auf dem neusten Stand zu halten. Wie für die meisten Anwendungen werden auch für PHP regelmäßig neue Versionen erstellt, um Fehler zu beseitigen und um den Funktionsumfang zu erweitern. Für weitere Informationen sollten Sie die entsprechende macOS-Installations-Dokumentation lesen. Die folgende Anleitung richtet sich an Anfänger, um eine Standardkonfiguration aufzusetzen. Allen Benutzern wird empfohlen, neuere Paket-Versionen zu installieren oder selbst zu kompilieren.

Die normale Installation beinhaltet die Aktivierung des mitgelieferten mod_php für den Apache-Webserver (der Standard-Webserver, der über die Systemeinstellungen von macOS zugänglich ist) und umfasst folgende Schritte:

1. Öffnen Sie die Apache-Konfigurationsdatei. Normalerweise finden Sie diese unter: /private/etc/apache2/httpd.conf Über den `Finder` oder `Spotlight` wird die Datei nur schwer zu finden sein, da sie geschützt ist und den Rechten des `root`-Benutzers unterliegt.

   > Hinweis: Ein Weg, um die Datei zu öffnen, ist, im Terminal einen Unix-basierten Texteditor, z. B. `nano`, zu verwenden. Da die Datei dem Benutzer root gehört, sollten Sie den Befehl `sudo` zum Öffnen (mit Root-Rechten) verwenden, z. B. können Sie Folgendes im `Terminal`-Programm eingeben (danach werden Sie nach dem Passwort gefragt): `sudo nano /private/etc/apache2/httpd.conf` Nennenswerte Befehle für nano: `^w` (suchen), `^o` (speichern), und `^x` (schließen) wobei `^` für die Strg-Taste steht.

   > Hinweis: Versionen von Mac OS X vor 10.5 enthielten ältere Versionen von PHP und Apache. Daher kann sich die Apache-Konfigurationen auf solchen älteren Maschinen im folgenden Verzeichnis befinden: /etc/httpd/httpd.conf.

2. Mit einem Texteditor müssen Sie nur die Zeilen einkommentieren (durch Entfernen von #), die ähnlich wie die folgenden aussehen (die beiden Zeilen sind oft ein Stück voneinander getrennt):

       # LoadModule php5_module libexec/httpd/libphp5.so

       # AddModule mod_php5.c

   Beachten Sie die Dateipfade. Wenn Sie zukünftig PHP selbst kompilieren, sollten die beiden Dateien ersetzt oder wieder auskommentiert werden.

3. Stellen Sie sicher, dass die gewünschten Dateiendungen durch PHP geparst werden (z. B. .php, .html und .inc).

   Durch die folgenden bereits in der Datei httpd.conf enthaltenen Angaben (ab Mac Panther) werden Dateien mit der Endung .php nach dem Aktivieren von PHP automatisch geparst.

       <IfModule mod_php5.c>
           # Wenn PHP aktiviert wurde, werden .php- und .phps-Dateien berücksichtigt.
           AddType application/x-httpd-php .php
           AddType application/x-httpd-php-source .phps

           # Da die meisten Benutzer index.php verwenden möchten, aktivieren
           # wir ebenso automatisch die index.php
           <IfModule mod_dir.c>
               DirectoryIndex index.html index.php
           </IfModule>
       </IfModule>

   > Hinweis:

   > Vor Mac OS X 10.5 (Leopard) war PHP 4 statt PHP 5 enthalten, weswegen die oben genannten Anweisungen angepasst werden müssen (Ersetzen der "5" durch die "4").

4. Stellen Sie sicher, dass durch DirectoryIndex die gewünschten vorgegebenen Index-Dateien geladen werden. Dies kann auch in httpd.conf definiert werden. Normalerweise werden index.php und index.html verwendet. Wie oben bereits gezeigt, ist index.php standardmäßig aktiviert. Passen Sie es wie gewünscht an.
5. Den Pfad zur php.ini setzen oder den Standard verwenden Der Standardpfad unter macOS ist /usr/local/php/php.ini, was durch einen Aufruf von phpinfo() geprüft werden kann. Wenn keine php.ini angegeben wird, verwendet PHP die Standardwerte. Lesen Sie dazu die entsprechende FAQ: Wo sollte sich meine php.ini befinden?.
6. Finden oder Setzen des `DocumentRoot` Dies ist das Wurzelverzeichnis für alle Web-Dateien. Dateien in diesem Verzeichnis werden durch den Webserver ausgeliefert. PHP-Dateien werden geparst, bevor sie an einen Browser ausgeliefert werden. Der standardmäßig gesetzte Pfad ist /Library/WebServer/Documents und kann in der httpd.conf auf einen beliebigen Pfad gesetzt werden. Alternativ ist der standardmäßige Pfad zum DocumentRoot für die einzelnen Benutzer: /Users/ihr_benutzername/Sites
7. Erstellen einer phpinfo()-Datei

   Die Funktion phpinfo() zeigt Informationen über PHP an. Erstellen Sie eine Datei im DocumentRoot mit dem folgenden Inhalt:

       <?php phpinfo(); ?>

8. Starten Sie den Apache neu und laden Sie die eben erzeugte PHP-Datei.

   Um neu zu starten, können Sie entweder `sudo apachectl graceful` im Terminal aufrufen oder die Stop-/Start-Option des "Personal Web Server" in den macOS-Systemeinstellungen verwenden. Standardmäßig sollte folgende URL zum Laden von lokalen Dateien im Webbrowser genügen: http://localhost/info.php Alternativ, um Dateien aus dem DocumentRoot eines lokalen Benutzers zu laden: http://localhost/~ihr_benutzername/info.php

Das CLI (oder CGI in älteren Versionen) heißt entsprechend php und existiert wahrscheinlich als /usr/bin/php. Öffnen Sie das Terminal, lesen Sie das Kapitel PHP auf der Kommandozeile des PHP-Handbuchs und führen Sie `php -v` aus, um die PHP-Version dieses PHP-Binärprogramms zu sehen. Ein Aufruf von phpinfo() enthält diese Information ebenfalls.

# Installation auf Windows-Systemen

## Inhaltsverzeichnis

- Empfohlene Konfiguration auf Windows-Systemen
- Manuelle PHP-Installation auf Windows
- Installation für Apache 2.x auf Windows-Systemen
- Installation with IIS for Windows
- Drittanbieter-Tools zur Installation von PHP
- Erstellen aus dem Quellcode
- PHP auf Windows-Systemen auf der Kommandozeile ausführen

Für den produktiven Einsatz werden die offiziellen Versionen von PHP für Windows empfohlen, aber PHP kann auch aus dem aus dem Quellcode erstellt werden.

PHP kann auch auf Azure App Services installiert werden (auch bekannt als Microsoft Azure, Windows Azure oder (Windows) Azure Web Apps).

Im Abschnitt Installation der häufig gestellten Fragen werden typische Probleme behandelt, die bei der Installation und Konfiguration auftreten können.

## Empfohlene Konfiguration auf Windows-Systemen

### OpCache

Es wird dringend empfohlen, OpCache zu aktivieren. Diese Erweiterung ist im Lieferumfang von PHP für Windows enthalten. Sie kompiliert und optimiert PHP-Skripte und legt sie im Speicher ab, damit sie nicht jedes Mal, wenn die Seite geladen wird, neu kompiliert werden müssen.

Setzen Sie in der php.ini folgende Optionen:

Beispiel #1 Empfohlene Konfiguration für OpCache

    opcache.enable=On
    opcache.enable_cli=On

Und starten Sie den Webserver neu. Für weitere Informationen, siehe OpCache-Konfiguration

### WinCache

Wenn Sie den IIS einsetzen, ist es empfehlenswert, WinCache zu verwenden. Dies gilt insbesondere für gemeinsam genutzte Webhosting-Umgebungen oder für die Verwendung von netzwerkbasiertem Dateispeicher (NAS). Alle PHP-Anwendungen profitieren automatisch von der Dateicache-Funktionalität von WinCache. Dateisystem-Operationen werden im Speicher zwischengespeichert. Darüber hinaus kann WinCache auch Objekte von Benutzern im Speicher zwischenspeichern und sie zwischen php.exe- oder php-cgi.exe-Prozessen austauschen (gemeinsame Nutzung von Objekten zwischen Anfragen). Viele große Webanwendungen verfügen über ein Plugin, eine Erweiterung oder eine Konfigurationsoption, um den Cache für Benutzerobjekte von WinCache zu nutzen. Wenn eine hohe Leistung benötigt wird, sollten Sie den Objekt-Cache in Ihren Anwendungen verwenden. Siehe » https://pecl.php.net/package/WinCache um eine WinCache-DLL (oder WINCACHE_*.tgz) in das Verzeichnis für die PHP-Erweiterungen (extension_dir in der php.ini) herunterzuladen. Setzen Sie in der php.ini folgende Optionen:

Beispiel #2 Empfohlene Konfiguration für WinCache

    extension=php_wincache.dll
    wincache.fcenabled=1
    wincache.ocenabled=1 ; entfernt ab wincache 2.0.0.0

Für weitere Informationen, siehe WinCache-Konfiguration

## Manuelle PHP-Installation auf Windows

### Voraussetzungen für die Installation

PHP ist nur für 32-Bit-x86- und 64-Bit-x64-Systeme verfügbar und läuft derzeit nicht unter Windows RT oder Windows on ARM. Seit Version 8.3.0 benötigt PHP Windows 8 oder Windows Server 2012. Versionen nach 7.2.0 benötigen Windows 2008 R2 oder Windows 7. Versionen vor 7.2.0 unterstützten Windows 2008 und Vista.

PHP benötigt die Visual C-Laufzeitumgebung (C RunTime, CRT). Da diese auch von vielen anderen Anwendungen benötigt wird, ist sie wahrscheinlich bereits installiert. Falls nicht, ist die Microsoft Visual C++ Redistributable for Visual Studio 2022 für die Verwendung mit allen PHP-Versionen geeignet und kann » von Microsoft heruntergeladen werden.

Für PHP-x86-Builds muss die x86-CRT heruntergeladen werden und für PHP-x64-Builds die x64-CRT. Wenn die CRT bereits installiert ist, weist das Installationsprogramm darauf hin, dass sie bereits installiert wurde und nimmt keine Änderungen vor. Das CRT-Installationsprogramm unterstützt die Befehlszeilenoptionen /quiet und /norestart, sodass die Installation per Skript erfolgen kann.

### Where to download PHP binaries

Windows-Builds könnenn von der Website » PHP For Windows heruntergeladen werden. Alle Builds sind optimiert (PGO) und die QA- und GA-Versionen sind gründlich getestet.

### Vorkompilierte PECL-Erweiterungen

Vorgefertigte Windows-Versionen von PECL-Erweiterungen werden als DLL-Dateien auf der PECL-Seite der Erweiterung zur Verfügung gestellt.

Für Erweiterungen, die spezielle Funktionalitäten anderer Systeme wie Unix nutzen oder von Bibliotheken abhängen, die unter Windows nicht verfügbar sind, gibt es keine Binärdateien.

### Build-Typen

Es gibt vier Typen von PHP-Builds:

- Thread-Safe (TS) - für Einzelprozess-Webserver, wie Apache mit mod_php

- Non-Thread-Safe (NTS) - für IIS und andere FastCGI-Webserver (Apache mit mod_fastcgi) und empfohlen für Befehlszeilen-Skripte

- x86 - für 32-Bit-Systeme

- x64 - für 64-Bit-Systeme

## Installation für Apache 2.x auf Windows-Systemen

Dieser Abschnitt enthält Hinweise und Tipps zur Installation von Apache 2.x mit PHP unter Microsoft Windows.

> Hinweis:

> Bitte lesen Sie zuerst die Installationsanweisungen für PHP unter Windows!

Es wird außerdem dringend empfohlen, die » Apache-Dokumentation zu lesen, um ein grundlegendes Verständnis des Apache 2.x Servers zu bekommen. Lesen Sie auch die » Windows-spezifischen Hinweise für Apache 2.x, bevor Sie hier weiterlesen.

Laden Sie die neueste Version von » Apache 2.x und eine passende PHP-Version herunter. Folgen Sie den Installationsanweisungen für PHP unter Windows und kommen Sie zurück, um mit der Integration von PHP und Apache fortzufahren.

Es gibt drei Möglichkeiten, PHP für die Nutzung mit Apache 2.x unter Windows einzurichten. PHP kann als Handler, als CGI oder unter FastCGI ausgeführt werden.

> Hinweis: Beachten Sie bitte, dass Sie bei Pfadangaben in der Apachekonfigurationsdatei unter Windows alle Backslashes, wie z. B. c:\directory\file.ext, in Schrägstriche umwandeln sollten: c:/directory/file.ext. Bei Verzeichnisnamen kann weiterhin ein abschließender Schrägstrich nötig sein.

### Installation als Apache-Handler

> Hinweis: Bei Verwendung der SAPI apache2handler muss die threadsichere (Thread Safe, TS) Version von PHP verwendet werden.

Um das PHP-Modul für Apache 2.x zu laden, müssen die folgenden Zeilen in die Apache-Konfigurationsdatei httpd.conf eingefügt werden:

Beispiel #1 PHP und Apache 2.x als Handler

    # vor PHP 8.0.0 war der Name des Moduls php7_module
    LoadModule php_module "c:/php/php8apache2_4.dll"
    <FilesMatch \.php$>
        SetHandler application/x-httpd-php
    </FilesMatch>
    # Konfigurieren des Pfades zur php.ini
    PHPIniDir "C:/php"

> Hinweis: Statt C:/php/ muss im obigen Beispiel der tatsächliche Pfad zu PHP angegeben werden. Stellen Sie sicher, dass sich die Datei, auf die in der `LoadModule`-Direktive verwiesen wird, am angegebenen Ort befindet. Verwenden Sie für PHP 7 php7apache2_4.dll und für PHP 8 php8apache2_4.dll.

### PHP als CGI ausführen

Es wird dringend empfohlen, die » Apache CGI-Dokumentation zu konsultieren, um ein umfassenderes Verständnis für die Ausführung von CGI unter Apache zu bekommen.

Um PHP als CGI laufen zu lassen, müssen die php-cgi-Dateien in einem Verzeichnis abgelegt werden, das mit der ScriptAlias-Direktive als CGI-Verzeichnis gekennzeichnet ist.

In den PHP-Dateien muss eine `#!`-Zeile eingefügt werden, die auf den Speicherort des PHP-Programms verweist:

Beispiel #2 PHP und Apache 2.x als CGI

    #!C:/php/php.exe
    <?php
      phpinfo();
    ?>

Warnung

Wenn Sie das CGI-Setup verwenden, ist Ihr Server für einige mögliche Angriffe anfällig. Wie Sie sich vor diesen Angriffen schützen können, entnehmen Sie bitte dem Kapitel über CGI-Sicherheit.

### PHP unter FastCGI ausführen

PHP unter FastCGI laufen zu lassen hat eine Reihe von Vorteilen gegenüber der Ausführung als CGI. Die Einrichtung ist ziemlich einfach:

Sie finden `mod_fcgid` auf » https://www.apachelounge.com. Die Win32-Binärdateien können von dieser Website heruntergeladen werden. Installieren Sie das Modul gemäß den Anweisungen, die Sie mit dem Modul erhalten.

Konfigurieren Sie den Webserver wie im Folgenden gezeigt und passen Sie dabei die Pfade entsprechend der Installation auf dem System an:

Beispiel #3 Apache für die Ausführung von PHP als FastCGI konfigurieren

    LoadModule fcgid_module modules/mod_fcgid.so
    # Wo befindet sich die php.ini-Datei?
    FcgidInitialEnv PHPRC        "c:/php"
    <FilesMatch \.php$>
        SetHandler fcgid-script
    </FilesMatch>
    FcgidWrapper "c:/php/php-cgi.exe" .php

Dateien mit der Erweiterung `.php` werden nun vom PHP FastCGI-Wrapper ausgeführt.

## Installation with IIS for Windows

### Installing IIS

Internet Information Services (IIS) is built in to Windows. On Windows Server, the IIS role can be added via the Server Manager. The CGI Role Feature needs to be included. On Windows Desktop, IIS has to be added via the Control Panel's Add/Remove Programs. The Microsoft documentation has » detailed instructions for enabling IIS. For development, » IIS/Express can also be used.

> Hinweis: The Non-Thread Safe (NTS) version of PHP should be installed when using the FastCGI handler with IIS.

### Configuring PHP with IIS

In IIS Manager, Install FastCGI module and add a handler mapping for `.php` to the path to php-cgi.exe (not php.exe)

The APPCMD command line tool can be used to script IIS configuration.

### Example batch script

Beispiel #1 Command line to configure IIS and PHP

    @echo off

    REM download .ZIP file of PHP build from http://windows.php.net/downloads/

    REM path to directory into which PHP .ZIP file was decompressed (no trailing \)
    set phppath=c:\php

    REM Clear current PHP handlers
    %windir%\system32\inetsrv\appcmd clear config /section:system.webServer/fastCGI
    REM The following command will generate an error message if PHP is not installed. This can be ignored.
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /-[name='PHP_via_FastCGI']

    REM Set up the PHP handler
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI /+[fullPath='%phppath%\php-cgi.exe']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /+[name='PHP_via_FastCGI',path='*.php',verb='*',modules='FastCgiModule',scriptProcessor='%phppath%\php-cgi.exe',resourceType='Unspecified']
    %windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers /accessPolicy:Read,Script

    REM Configure FastCGI Variables
    %windir%\system32\inetsrv\appcmd set config -section:system.webServer/fastCgi /[fullPath='%phppath%\php-cgi.exe'].instanceMaxRequests:10000
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
    %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='%phppath%\php-cgi.exe'].environmentVariables.[name='PHPRC',value='%phppath%\php.ini']"

## Drittanbieter-Tools zur Installation von PHP

Warnung

Pakete von Drittanbietern werden als inoffiziell betrachtet und nicht direkt vom PHP-Projekt unterstützt. Auftretende Fehler sollten dem Anbieter dieser inoffiziellen Pakete gemeldet werden, es sei denn, sie können mit den Paketen aus dem » offiziellen Downloadbereich reproduziert werden.

» XAMPP, » WampServer und » Bitnami richten auch PHP-Anwendungen für die Verwendung mit Apache unter Windows ein.

## Erstellen aus dem Quellcode

Siehe die » Schritt für Schritt Anleitung für die Kompilierung mit Visual Studio.

## PHP auf Windows-Systemen auf der Kommandozeile ausführen

Dieser Abschnitt enthält Hinweise und Tipps, wie man PHP unter Windows auf der Befehlszeile zum Laufen bringt.

> Hinweis:

> Lesen Sie zuerst die Anleitung für die manuelle Installation!

PHP kann ohne Änderungen an Windows von der Kommandozeile aus gestartet werden.

    C:\php\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3

Mit ein paar kleinen Maßnahmen lässt sich dies jedoch vereinfachen. Einige dieser Maßnahmen sollten bereits durchgeführt worden sein, werden aber hier wiederholt, um eine vollständige Schritt-für-Schritt-Anleitung zu geben.

> Hinweis:

> Sowohl PATH als auch PATHEXT sind wichtige, bereits existierende Windows-Systemvariablen, und es sollte darauf geachtet werden, keine der beiden Variablen zu überschreiben, sondern sie nur zu ergänzen.

- Ergänzen Sie die Umgebungsvariable PATH um den Ort der ausführbaren PHP-Datei (php.exe, php-win.exe oder php-cli.exe, abhängig von der PHP-Version und den Einstellungen für die Anzeige). Wie Sie das PHP-Verzeichnis zu PATH hinzufügen können, erfahren Sie im entsprechenden FAQ-Eintrag.

- Ergänzen Sie die Umgebungsvariable PATHEXT um die Erweiterung `.PHP`. Dies kann zusammen mit der Änderung der Umgebungsvariablen PATH erledigt werden. Befolgen Sie die in den FAQ beschriebenen Schritte, aber ändern Sie die Umgebungsvariable PATHEXT und nicht die Umgebungsvariable PATH.

  > Hinweis:

  > Die Position, an der das `.PHP` platziert wird, bestimmt, welches Skript oder Programm ausgeführt wird, wenn es übereinstimmende Dateinamen gibt. Wenn Sie `.PHP` zum Beispiel vor `.BAT` platzieren, wird bei einer gleichnamigen Batch-Datei das Skript ausgeführt und nicht die Batch-Datei.

- Verknüpfen Sie die Erweiterung `.PHP` mit einem Dateityp. Dazu führen Sie den folgenden Befehl aus:

      assoc .php=phpfile

- Verknüpfen Sie den Dateityp `phpfile` mit der entsprechenden ausführbaren PHP-Datei. Dazu führen Sie den folgenden Befehl aus:

      ftype phpfile="C:\php\php.exe" -f "%1" -- %~2

Wenn Sie diese Schritte befolgen, können PHP-Skripte von jedem Verzeichnis aus ausgeführt werden, ohne dass Sie die ausführbare PHP-Datei oder die Erweiterung `.PHP` eingeben müssen. Darüber hinaus können Sie Parameter angeben, die an das Skript übergeben werden.

Im folgenden Beispiel sind einige der Änderungen in der Registry aufgeführt, die manuell vorgenommen werden können.

Beispiel #1 Änderungen in der Registry

    Windows Registry Editor Version 5.00

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php]
    @="phpfile"
    "Content Type"="application/php"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile]
    @="PHP Script"
    "EditFlags"=dword:00000000
    "BrowserFlags"=dword:00000008
    "AlwaysShowExt"=""

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon]
    @="C:\\php\\php-win.exe,0"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell]
    @="Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open]
    @="&Open"

    [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command]
    @="\"C:\\php\\php.exe\" -f \"%1\" -- %~2"

Mit diesen Änderungen kann derselbe Befehl wie folgt geschrieben werden:

    "C:\PHP Scripts\script" -arg1 -arg2 -arg3

oder, wenn das Verzeichnis `"C:\PHP Scripts"` in der Umgebungsvariablen PATH steht:

    script -arg1 -arg2 -arg3

> Hinweis:

> Wenn diese Technik verwendet werden soll, um PHP-Skripte als Befehlszeilenfilter zu nutzen, wie im folgenden Beispiel, gibt es ein kleines Problem:

>     dir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3

> oder

>     dir | script -arg1 -arg2 -arg3

> Es kann vorkommen, dass das Skript einfach hängen bleibt und nichts ausgibt. Um dies zu beheben, muss eine weitere Änderung in der Registry vorgenommen werden.

>     Windows Registry Editor Version 5.00

>     [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer]
>     "InheritConsoleHandles"=dword:00000001

> Weitere Informationen zu diesem Problem finden Sie im » Microsoft Knowledgebase Article : 321788. Ab Windows 10 scheint diese Einstellung geändert worden zu sein, sodass die Standardinstallation von Windows 10 geerbte Konsolen-Handles automatisch unterstützt. Dieser » Microsoft-Forenbeitrag liefert die Erklärung.

# Installation auf Cloud Computing Platformen

## Inhaltsverzeichnis

- Azure App Services
- Amazon EC2
- DigitalOcean

PHP installiert in der Wolke. Auf zur PHP Wolke!

## Azure App Services

PHP wird häufig auf Azure App Services (auch bekannt als Microsoft Azure, Windows Azure, Azure Web Apps) verwendet.

Azure App Services verwaltet Pools von Windows-Webservern zum Hosten Ihrer Webanwendung, als Alternative zur Verwaltung Ihres eigenen Webservers auf Ihren eigenen Azure Compute VMs oder anderen Servern.

PHP ist bereits automatisch für Ihre Azure App Services Website aktiviert. Wählen Sie im Azure-Portal Ihre Website aus, und Sie können wählen, welche Version von PHP verwendet werden soll. Möglicherweise möchten Sie eine neuere Version als Standardversion wählen.

Daher werden PHP und Erweiterungen auf Azure App Services genauso wie auf anderen Windows-Servern laufen. Das Verwaltungsinterface für Azure App Services ist jedoch anders:

- Azure-Portal: Erstellen, Bearbeiten von Einstellungen und Löschen von Websites. » Azure Portal

- Kudu-Dashboard: wenn die Website die URL `site_name.azurewebsites.net` hat, befindet sich das Kudu-Dashboard unter `https://site_name.scm.azurewebsites.net/`. Das Dashboard bietet Zugriff auf Debugging-Funktionen, die Dateiverwaltung und Website-Erweiterungen. Die Website-Erweiterungen sind ein Azure-Mechanismus, mit dem einer Website zusätzliche Programme wie PHP-Vorschau-Builds hinzugefügt werden können.

- Sie können IIS Manager, Server Manager und RDP nicht verwenden.

Es gibt auch ein PHP-SDK für die programmatische Nutzung vieler Azure Services aus Ihrem PHP-Code; siehe » Azure SDK for PHP.

Weitere Informationen finden Sie unter » Azure PHP Developer Center

### WinCache

WinCache ist bei den Azure App Services standardmäßig aktiviert und es wird empfohlen, diese Option aktiviert zu lassen. Wenn Sie Ihre eigene Version von PHP installieren, sollten Sie WinCache auch darauf aktivieren.

### Selbsterstellte PHP-Builds

Sie können Ihre eigene PHP-Version auf Ihr D:\Home hochladen (C:\ ist NICHT beschreibbar). Setzen Sie dann im Azure-Portal SCRIPT_PROCESSOR für .php auf den absoluten Pfad zur php-cgi.exe-Datei in Ihrer Version.

## Amazon EC2

PHP kann auf der » EC2 Cloud Plattform installiert werden.

Siehe auch » AWS SDK für PHP.

## DigitalOcean

DigitalOcean bietet die folgenden Plattformen für die Installation von PHP und den Betrieb von Webanwendungen auf seiner Cloud-Hosting-Infrastruktur.

- » Cloudways: Die einfache Bereitstellung der wichtigsten PHP-Anwendungen mit einem Klick: WordPress, Magento, Drupal, Laravel und weitere.

- » Droplet: Virtuelle Maschinen und die » Installation eines Lamp-Stacks auf einem Linux-Server .

- » App Platform: Eine verwaltete Infrastruktur für die schnelle Erstellung, Bereitstellung und Skalierung von Anwendungen. Siehe auch, » wie eine PHP-Anwendung auf der App-Plattform ausgeführt wird .

- » Functions: Eine serverlose Plattform, auf der Entwickler Code ausführen können, ohne einen Server bereitstellen oder verwalten zu müssen; PHP wird nativ unterstützt. Siehe auch, » wie serverlose Funktionen in PHP erstellt werden .

# FastCGI Process Manager (FPM)

## Inhaltsverzeichnis

- Installation
- Konfiguration

FPM (FastCGI Process Manager) ist eine Alternative zu PHP FastCGI mit einigen zusätzlichen Features (besonders) für Websites mit hoher Last.

Zu diesen Features gehören:

- fortschrittliches Prozessmanagement mit sanftem Stop/Start

- Pools, die die Möglichkeit bieten, einzelne Prozesse mit unterschiedlichen Einstellungen für uid/gid/chroot/environment zu starten, auf unterschiedlichen Ports Anfragen entgegenzunehmen, sowie jeweils eigene php.ini verwenden zu können (ersetzt den safe_mode)

- Konfigurierbares Logging auf stdout und stderr

- Notfall-Neustart, für den Fall einer zufälligen Zerstörung des Opcode-Caches

- Unterstützung für beschleunigten Upload

- "slowlog" - loggen von Scripts (nicht nur deren Namen, sondern deren PHP Backtraces, wobei ptrace und andere Dinge zum Einsatz kommen, um die "execute_data" des Prozesses zu debuggen) die ungewöhnlich langsam ausgeführt werden

- fastcgi_finish_request() - Spezialfunktion, um Anfragen zu beenden und alle Daten zu senden, während gleichzeitig etwas zeitintensives, wie Videokonvertierung oder Statistik-Verarbeitung abläuft

- dynamisches, bedarfsunabhängiges und statisches Starten von Kindprozessen

- Einfache und erweiterte Status-Info (vergleichbar mit Apache mod_status) mit Unterstützung verschiedener Formate wie JSON, XML und OpenMetrics

- php.ini-basierte Konfigurationsdatei

## Installation

### Kompilierung des Quellcodes

Um FPM im Ihrem PHP Build zu aktivieren, müssen Sie `--enable-fpm` der Konfigurationszeile hinzufügen.

Es gibt verschiedene andere FPM-spezifsche Einstellungen (alle sind optional):

- `--with-fpm-user` - setzt den FPM Nutzer (Standard - nobody).

- `--with-fpm-group` - setzt die FPM Gruppe (Standard - nobody).

- `--with-fpm-systemd` - aktiviert die systemd-Integration (Standard - no).

- `--with-fpm-acl` - verwende POSIX Access Control Lists (Standard - no).

- `--with-fpm-apparmor` - aktiviert die AppArmor-Integration (Standard - no).

- `--with-fpm-selinux` - aktiviert die SELinux-Integration (Standard - no).

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Die Option `--with-fpm-selinux` wurde hinzugefügt.
8.0.0 | Die Option `--with-fpm-apparmor` wurde hinzugefügt.

## Konfiguration

FPM verwendet die php.ini-Syntax für die Konfigurationsdatei - php-fpm.conf - und Pool-Konfigurationsdateien.

### Liste globaler php-fpm.conf-Direktiven

`pid` string

  Pfad zur PID-Datei. Standardwert: none.

`error_log` string

  Pfad zur Fehlerprotokoll-Datei. Standardwert: `#INSTALL_PREFIX#/log/php-fpm.log`. Ist der Wert "syslog", wird das Protokoll an syslogd gesendet anstatt in eine lokale Datei geschrieben zu werden.

`log_level` string

  Grad der Fehlerprotokollierung. Mögliche Werte: alert, error, warning, notice, debug. Standardwert: notice.

`log_limit` int

  Obergrenze für die protokollierten Zeilen, die es ermöglicht, Nachrichten, die länger als 1024 Zeichen sind, ohne Zeilenumbruch zu protokollieren. Standardwert: 1024. Verfügbar von PHP 7.3.0 an.

`log_buffering` bool

  Experimentelles Protokollieren ohne zusätzliche Pufferung. Standardwert: yes. Verfügbar von PHP 7.3.0 an.

`syslog.facility` string

  Wird verwendet, um anzugeben, welche Art von Programm die Nachricht protokolliert. Standardwert: daemon.

`syslog.ident` string

  Wird jeder Nachricht vorangestellt. Werden mehrere FPM-Instanzen auf demselben Server ausgeführt, können Sie den Standardwert so ändern, dass er den allgemeinen Anforderungen entspricht. Standardwert: php-fpm.

`emergency_restart_threshold` int

  Wenn sich diese Anzahl von Kindprozessen innerhalb des durch `emergency_restart_interval` gesetzten Zeitintervalls mit SIGSEGV oder SIGBUS beendet, dann startet FPM neu. Der Wert 0 bedeutet 'Off'. Standardwert: 0 (Off).

`emergency_restart_interval` mixed

  Zeitintervall, das von `emergency_restart_interval` verwendet wird, um zu bestimmen, wann ein ordnungsgemäßer Neustart ausgelöst werden soll. Das kann nützlich sein, um zufällige Störungen im gemeinsamen Speicher eines Beschleunigers zu umgehen. Verfügbare Einheiten: s(econds), m(inutes), h(ours), oder d(ays). Standardeinheit: seconds. Standardwert: 0 (Off).

`process_control_timeout` mixed

  Zeitlimit für Kindprozesse, die auf eine Reaktion vom Hauptprozess (Master) warten. Verfügbare Einheiten: s(econds), m(inutes), h(ours), oder d(ays). Standardeinheit: seconds. Standardwert: 0.

`process.max` int

  Die Höchstanzahl an Prozessen, die FPM forkt. Dies wurde entwickelt, um die globale Anzahl an Prozessen zu kontrollieren, wenn in vielen Pools dynamisches PM verwendet wird. Mit Vorsicht zu verwenden. Standardwert: 0.

`process.priority` int

  Gibt die auf den Hauptrozess anzuwendende nice(2)-Priorität an (nur falls festgelegt). Der Wert kann zwischen -19 (höchste Priorität) und 20 (niedrigste Priorität) liegen. Standardwert: nicht gesetzt.

`daemonize` bool

  Schickt FPM in den Hintergrund. Bei 'no' bleibt FPM für das Debugging im Vordergrund. Standardwert: yes.

`rlimit_files` int

  Setzt das Ressourcenlimit (rlimit) der offenen Datei-Deskiptoren für den Hauptrozess. Standardwert: Systemeinstellung.

`rlimit_core` int

  Setzt das Ressourcenlimit (rlimit) der Maximalgröße einer Core-Datei für den Hauptprozess. Standardwert: 0.

`events.mechanism` string

  Spezifiziert den Ereignismechanismus, den FPM verwendet. Die folgenden sind möglich: epoll, kqueue (*BSD), port (Solaris), poll, select. Standardwert: leer (automatische Erkennung, bevorzugt epoll und kqueue).

`systemd_interval` int

  Wenn FPM mit systemd-Integration kompiliert wurde, gibt dies das Intervall in Sekunden an, in dem Statusberichtsmeldungen an systemd gesendet werden. 0 deaktiviert dies. Standardwert: 10.

### Liste der Pool-Direktiven

Mit FPM können mehrere Pools von Prozessen mit unterschiedlichen Einstellungen betrieben werden. Die nachfolgenden Einstellungen können pro Pool angepasst werden.

`listen` string

  Die Adresse, unter welcher FastCGI-Anfragen angenommen werden. Gültig sind die Syntaxen: 'ip.add.re.ss:port', 'port' und '/path/to/unix/socket'. Diese Einstellung ist für jeden Pool zwingend notwendig.

`listen.backlog` int

  Stellt die listen(2)-Warteschlange (Backlog) ein. Der Wert `-1` bedeutet das Maximum auf BSD-Systemen. Standardwert: `-1` (FreeBSD oder OpenBSD) oder `511` (Linux und andere Plattformen).

`listen.allowed_clients` string

  Liste mit IPv4- oder IPv6-Adressen von FastCGI-Clients, denen eine Verbindung gestattet ist. Entspricht der Umgebungsvariable FCGI_WEB_SERVER_ADDRS im originalen PHP-FastCGI (5.2.2+). Dies ist nur bei einem empfangenden TCP-Socket sinnvoll. Die Adressen sind durch Komma zu trennen. Wenn der Wert leer gelassen wird, dann werden Verbindungen von beliebigen IP-Adressen akzeptiert. Standardwert: nicht festgelegt (jede IP-Adresse wird akzeptiert).

`listen.owner` string

  Setzt die Berechtigungen für den Unix-Socket, falls dieser verwendet wird. Unter Linux müssen Lese- und Schreibberechtigungen gesetzt werden, um Verbindungen eines Webservers zu erlauben. Viele BSD-Derivate erlauben Verbindungen unabhängig von den Berechtigungen. Standardwert: user und group werden auf den aktuellen Benutzer gesetzt und Mode auf 0660.

`listen.group` string

  Siehe `listen.owner`.

`listen.mode` string

  Siehe `listen.owner`.

`listen.acl_users` string

  Wenn POSIX-Zugriffskontrolllisten unterstützt werden, können Sie diese mit dieser Option einstellen. Wenn eingestellt, dann werden `listen.owner` und `listen.group` ignoriert. Der Wert ist eine durch Kommas getrennte Liste von Benutzernamen.

`listen.acl_groups` string

  Siehe `listen.acl_users`. Der Wert ist eine durch Kommas getrennte Liste von Gruppennamen.

`listen.setfib` int

  Legt die zugehörige Routingtabelle (FIB) fest. Nur FreeBSD. Standardwert: `-1`. Seit PHP 8.2.0.

`user` string

  Der Unix-Benutzer der FPM-Prozesse. Diese Einstellung ist zwingend notwendig.

`group` string

  Die Unix-Benutzergruppe der FPM-Prozesse. Wenn nicht eingestellt, wird als Wert die Gruppe des Standard-Benutzers verwendet.

`pm` string

  Legt fest, wie der Prozess-Manager die Anzahl der Kindprozesse verwaltet. Mögliche Werte: `static`, `ondemand`, `dynamic`. Diese Einstellung ist zwingend notwendig.

  `static` - die Anzahl der Kindprozesse ist fest eingestellt (`pm.max_children`).

  `ondemand` - die Kindprozesse werden gestartet, sobald sie benötigt werden, im Gegensatz zu dynamic, wo zu Beginn bereits `pm.start_servers` Prozesse gestartet werden.

  `dynamic` - die Anzahl der Kindprozesse wird dynamisch eingestellt, wobei die folgenden Einstellungen zugrunde gelegt werden: `pm.max_children`, `pm.start_servers`, `pm.min_spare_servers` und `pm.max_spare_servers`.

`pm.max_children` int

  Die Anzahl an Kindprozessen, die erstellt werden, wenn `pm` auf `static` gesetzt ist, und die maximale Anzahl an Kindprozessen, die erstellt werden, wenn `pm` auf `dynamic` gesetzt ist. Diese Einstellung ist zwingend notwendig.

  Diese Einstellung legt das Limit für die Anzahl gleichzeitiger Verbindungen fest. Gleichzusetzen mit der ApacheMaxClients-Direktive mit mpm_prefork und der Umgebungsvariable PHP_FCGI_CHILDREN im originalen PHP-FastCGI.

`pm.start_servers` int

  Die Anzahl an Kindprozessen, die beim Start erstellt werden. Wird nur verwendet, wenn `pm` auf `dynamic` gesetzt ist. Standardwert: (min_spare_servers + max_spare_servers) / 2.

`pm.min_spare_servers` int

  Die gewünschte Mindestanzahl an Serverprozessen im Leerlauf. Wird nur verwendet, wenn `pm` auf `dynamic` gesetzt ist. Ebenfalls zwingend notwendig.

`pm.max_spare_servers` int

  Die gewünschte Maximalanzahl an Serverprozessen im Leerlauf. Wird nur verwendet, wenn `pm` auf `dynamic` gesetzt ist. Ebenfalls zwingend erforderlich.

`pm.max_spawn_rate` int

  Die Anzahl der gleichzeitig zu erzeugenden Kindprozesse. Wird nur verwendet, wenn `pm` auf `dynamic` gesetzt ist. Standardwert: 32

`pm.process_idle_timeout` mixed

  Die Anzahl der Sekunden, nach der ein Prozess im Leerlauf beendet wird. Wird nur verwendet, wenn `pm` auf `ondemand` gesetzt wurde. Verfügbare Einheiten: s (Sekunden)(Standardwert), m (Minuten), h (Stunden) oder d (Tage). Standardwert: 10s.

`pm.max_requests` int

  Die Anzahl der Anfragen, die ein Kindprozess ausführt, bevor er neu startet. Das kann hilfreich sein, um Speicherlecks in Bibliotheken von Drittanbietern zu umgehen. Für eine unbegrenzte Anzahl Anfragen '0' verwenden. Vergleichbar mit PHP_FCGI_MAX_REQUESTS. Standardwert: 0.

`pm.status_listen` string

  Die Adresse, an der FastCGI-Statusanfragen angenommen werden sollen. Hiermit wird ein neuer unsichtbarer Pool erstellt, der Anfragen eigenständig bearbeiten kann. Dies ist nützlich, wenn der Hauptpool mit lang laufenden Anfragen beschäftigt ist, da es trotzdem möglich ist, die FPM-Statusseite zu erhalten, bevor diese abgeschlossen sind. Die Syntax ist die gleiche wie bei der Direktive listen. Standardwert: none

`pm.status_path` string

  Der URI, um die FPM-Statusseite anzuzeigen. Dieser Wert muss mit einem führenden Schrägstrich (/) beginnen. Wird dieser Wert nicht angegeben, wird kein URI als Statusseite erkannt. Standardwert: none.

`ping.path` string

  Der Ping-URI, um die Monitoring-Seite von FPM aufzurufen. Wenn dieser Wert nicht gesetzt ist, dann wird kein URI als Ping-Seite erkannt. Das kann dafür verwendet werden, um zu testen, ob FPM noch läuft und antwortet. Es ist zu beachten, dass der Wert mit einem Forwardslash (/) beginnen muss.

`ping.response` string

  Diese Direktive kann dazu verwendet werden, um die Antwort auf eine Ping-Anfrage anzupassen. Die Antwort ist vom Typ text/plain mit dem Antwortcode 200. Standardwert: pong.

`process.priority` int

  Legt die nice(2)-Priorität fest, die auf den Worker-Prozess angewendet wird (falls angegeben). Der Wert liegt im Bereich von -19 (höchste Priorität) bis 20 (niedrigste Priorität). Standardwert: nicht gesetzt

`process.dumpable` bool

  Setzt das "process dumpable"-Flag (PR_SET_DUMPABLE prctl), selbst wenn der Benutzer oder die Gruppe des Prozesses sich vom Benutzer des Hauptprozesses unterscheidet. Dies erlaubt es dem Pool-Benutzer, Prozess-Coredumps zu erstellen und den Prozess mit ptrace zu untersuchen. Standardwert: no. Seit PHP 7.0.29, 7.1.17 und 7.2.5.

`prefix` string

  Legt das Prefix für die Pfad-Validierung fest.

`request_terminate_timeout` mixed

  Die Zeitbeschränkung für die Bearbeitung einer einzelnen Anfrage, nach der der Worker-Prozess beendet wird. Diese Einstellung sollte verwendet werden, wenn die ini-Option 'max_execution_time' aus irgendeinem Grund nicht zu einem Skriptabbruch führt. Der Wert '0' steht für 'Off'. Mögliche Einheiten: s(econds)(default), m(inutes), h(ours) oder d(ays). Standardwert: 0.

`request_terminate_timeout_track_finished` bool

  Die Zeitbeschränkung, die durch request_terminate_timeout festgelegt wird, wird nicht aktiviert nach fastcgi_finish_request oder wenn die Anwendung beendet ist und interne Shutdown-Funktionen aufgerufen werden. Mit dieser Direktive kann die Wartezeitbeschränkung auch in solchen Fällen uneingeschränkt angewendet werden. Standardwert: no. Seit PHP 7.3.0.

`request_slowlog_timeout` mixed

  Die Zeitbeschränkung für die Bearbeitung einer einzelnen Anfrage, nach der ein PHP-Backtrace in die 'slowlog'-Datei (Log-Datei für langsame Anfragen geschrieben wird. Der Wert '0' steht für 'Off'. Mögliche Einheiten: s(econds)(default), m(inutes), h(ours) oder d(ays). Standardwert: 0.

`request_slowlog_trace_depth` int

  Die Ausführlichkeit des Slowlog-Log-Stacktrace. Standardwert: 20. Seit PHP 7.2.0.

`slowlog` string

  Die Log-Datei für langsame Anfragen. Standardwert: `#INSTALL_PREFIX#/log/php-fpm.log.slow`.

`rlimit_files` int

  Legt das rlimit für offene Dateideskriptoren der Kindprozesse in diesem Pool fest. Standardwert: Systemeinstellung.

`rlimit_core` int

  Legt das rlimit für die maximale Core-Größe der Kindprozesse in diesem Pool fest. Mögliche Werte: 'unlimited' oder ein Integer größer oder gleich 0. Standardwert: Systemeinstellung.

`chroot` string

  Wechselt beim Start in das angegebene Verzeichnis als Wurzelverzeichnis. Der Wert muss eine absolute Pfadangabe sein. Wenn dieser Wert nicht gesetzt ist, wird chroot nicht verwendet.

`chdir` string

  Wechselt beim Start in das angegebene Verzeichnis. Der Wert muss eine absolute Pfadangabe sein. Standardwert: aktuelles Verzeichnis oder / bei Verwendung von chroot.

`catch_workers_output` bool

  Leitet stdout (Standardausgabe) und stderr (Standard-Fehlerausgabe) in das Haupt-Fehlerprotokoll um. Wenn nicht gesetzt, werden stdout und stderr entsprechend der FastCGI-Spezifikation nach /dev/null umgeleitet. Standardwert: no.

`decorate_workers_output` bool

  Aktiviert die Ausgabedekoration für die Ausgabe von Workern, wenn catch_workers_output aktiviert ist. Standardwert: yes. Verfügbar von PHP 7.3.0 an.

`clear_env` bool

  Löscht die Umgebung in FPM-Worker-Prozessen. Verhindert, dass beliebige Umgebungsvariablen FPM-Worker-Prozesse erreichen, indem die Umgebung in den Worker-Prozessen gelöscht wird, bevor die Umgebungsvariablen, die in dieser Pool-Konfiguration angegeben sind, hinzugefügt werden. Standardwert: Yes.

`security.limit_extensions` string

  Grenzt die Datei-Erweiterungen des Hauptskripts ein, die FPM parsen darf. Dies kann Konfigurationsfehler seitens des Webservers verhindern. Sie sollten FPM nur auf .php-Erweiterungen beschränken, um zu verhindern, dass bösartige Nutzer andere Erweiterungen verwenden, um PHP-Code auszuführen. Standardwert: .php .phar

`apparmor_hat` string

  Wenn AppArmor aktiviert ist, kann die Kopfzeile geändert werden. Standardwert: nicht festgelegt

`access.log` string

  Die Zugriffsprotokolldatei. Standardwert: nicht gesetzt

`access.format` string

  Das Format des Zugriffsprotokolls. Standardwert: `"%R - %u %t \"%m %r\" %s"`:

  Valid options
  Platzhalter | Beschreibung
  --- | ---
  `%%` | Das `%`-Zeichen
  `%C` | Die %CPU, die von der Anfrage verwendet wird. Diese Direktive akzeptiert die folgenden Formate: `%{user}C` nur für die Benutzer-CPU, `%{system}C` nur für die System-CPU, `%{total}C` für Benutzer + System-CPU (Standard)
  `%d` | Die Zeit, die für die Beantwortung der Anfrage benötigt wurde. Diese Direktive akzeptiert die folgenden Formate für die Genauigkeit: `%{Sekunden}d` (Standard), `%{Millisekunden}d`, `%{Mikrosekunden}d`
  `%{Name}e` | Eine Umgebungsvariable (ähnlich wie $_ENV oder $_SERVER). Um den Namen einer Umgebungsvariablen anzugeben, muss der Variablenname in geschweiften Klammern angegeben werden. Zum Beispiel Server-Spezifikationen wie `%{REQUEST_METHOD}e` oder `%{SERVER_PROTOCOL}e`, HTTP-Header wie `%{HTTP_HOST}e` oder `%{HTTP_USER_AGENT}e`
  `%f` | Dateiname des Skripts
  `%l` | `Content-Length` der Anfrage (nur für HTTP-POST-Anfragen)
  `%m` | HTTP-Methode für die Anfrage
  `%M` | Die maximale Größe des von PHP zugewiesenen Speichers. Diese Direktive akzeptiert die folgenden Formate: `%{Bytes}M` (Standard), `%{Kilobytes}M`, `%{Kilo}M`, `%{Megabytes}M`, `%{Mega}M`
  `%n` | Poolname
  `%{Name}o` | Ausgabe-Header. Der Name des Headers muss in geschweiften Klammern angegeben werden. Zum Beispiel: `%{Content-Type}o`, `%{X-Powered-By}o`, `%{Transfer-Encoding}o`
  `%p` | PID des Kindprozesses, der die Anfrage bearbeitet hat
  `%P` | PID des Elternprozesses des Kindprozesses, der die Anfrage bearbeitet hat
  `%q` | Anfragezeichenkette
  `%Q` | Das Zeichen `'?'` oder das Verknüpfungszeichen zwischen `%q` und `%r`, wenn eine Anfragezeichenkette vorhanden ist
  `%r` | Der Anfrage-URI ohne die Abfragezeichenkette, siehe `%q` und `%Q`
  `%R` | Entfernte (Remote-) IP-Adresse
  `%s` | Status (Antwortcode)
  `%t` | Serverzeit, zu der die Anfrage eingegangen ist. Diese Direktive akzeptiert das `strftime(3)`-Format `%d/%b/%Y:%H:%M:%S %z` (Standard). Das `strftime(3)`-Format muss in einem `%{<strftime_format>}t`-Tag gekapselt sein. Für eine Zeitangabe im ISO8601-Format würde z. B. folgendes verwendet: `%{%Y-%m-%dT%H:%M:%S%z}t`
  `%T` | Zeitpunkt, zu dem das Protokoll geschrieben wurde (als die Anfrage beendet wurde). Diese Direktive akzeptiert das `strftime(3)`-Format `%d/%b/%Y:%H:%M:%S %z` (Standard). Das `strftime(3)`-Format muss in einem `%{<strftime_format>}T`-Tag gekapselt sein. Für eine Zeitangabe im ISO8601-Format würde z. B. folgendes verwendet: `%{%Y-%m-%dT%H:%M:%S%z}T`
  `%u` | Benutzer mit Basis-Zugangsauthentifizierung, falls im `Authorization`-Header angegeben

`access.suppress_path` array

  Eine Liste von request_uri-Werten, die aus dem Zugriffsprotokoll herausgefiltert werden sollen. Standardwert: nicht gesetzt. Seit PHP 8.2.0.

Es ist möglich, zusätzliche Umgebungsvariablen zu setzen und PHP-Einstellungen eines bestimmten Pools zu verändern. Dazu sind die nachfolgenden Einstellungen in der Pool-Konfigurationsdatei erforderlich.

Beispiel #1 Übergabe von Umgebungsvariablen und PHP-Einstellungen an einen Pool

    env[HOSTNAME] = $HOSTNAME
         env[PATH] = /usr/local/bin:/usr/bin:/bin
         env[TMP] = /tmp
         env[TMPDIR] = /tmp
         env[TEMP] = /tmp

         php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
         php_flag[display_errors] = off
         php_admin_value[error_log] = /var/log/fpm-php.www.log
         php_admin_flag[log_errors] = on
         php_admin_value[memory_limit] = 32M

PHP-Einstellungen, die mit `php_value` oder `php_flag` übergeben wurden, überschreiben vorherige Werte. Es ist zu beachten, dass disable_functions oder disable_classes nicht dazu führen, dass vorher definierte php.ini-Einstellungen überschrieben werden, vielmehr werden die neuen Werte angehängt.

Einstellungen, die mit `php_admin_value` und `php_admin_flag` gemacht wurden, können nicht mit ini_set() verändert werden.

PHP-Einstellungen können in der Konfiguration des Webservers vorgenommen werden.

Beispiel #2 Festlegen von PHP-Einstellungen in nginx.conf

    set $php_value "pcre.backtrack_limit=424242";
    set $php_value "$php_value \n pcre.recursion_limit=99999";
    fastcgi_param  PHP_VALUE $php_value;

    fastcgi_param  PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";

Achtung

Weil diese Einstellungen an php-fpm als FastCGI-Header übergeben werden, sollte php-fpm nicht an eine öffentlich zugängliche Adresse gebunden sein. Andernfalls könnte jeder die PHP-Konfigurationsoptionen ändern. Siehe auch listen.allowed_clients.

> Hinweis: Pools sind kein Sicherheitsmechanismus, denn sie bieten keine vollständige Trennung; z. B. würden alle Pools eine einzige OPcache-Instanz verwenden.

# Installation der PECL-Erweiterungen

## Inhaltsverzeichnis

- Einführung in die PECL-Installationen
- Herunterladen der PECL-Erweiterungen
- Installation einer PHP-Erweiterung unter Windows
- Kompilieren dynamischer PECL-Erweiterungen mit dem Befehl pecl
- Kompilieren dynamischer PECL-Erweiterungen mit phpize
- php-config
- PECL-Erweiterungen statisch in PHP kompilieren

## Einführung in die PECL-Installationen

> Hinweis: Der "PHP Installer for Extensions" (PIE) ist ein neues Tool, das PECL überflüssig machen wird. Wir empfehlen, für die Installation von Erweiterungen den PIE zu verwenden. Weitere Informationen sind unter » https://github.com/php/pie zu finden.

» PECL ist eine Sammlung von PHP-Erweiterungen, die über das Paketierungssystem » PEAR zur Verfügung gestellt werden. Dieser Abschnitt des Handbuchs soll zeigen, wie man PECL-Erweiterungen bekommt und installiert.

Diese Anweisungen gehen davon aus, dass `/pfad/zu/php/src/` der Pfad zum Quellcode der PHP-Distribution ist und dass `extname` der Name der PECL-Erweiterung ist. Die Angaben müssen entsprechend angepasst werden. Diese Anweisungen setzen außerdem voraus, dass man mit dem » pear-Befehl vertraut ist. Die Informationen des PEAR-Handbuchs zum Befehl pear gelten auch für den Befehl pecl.

Eine dynamische Erweiterung muss kompiliert, installiert und geladen werden, um brauchbar zu sein. Die im Folgenden beschriebenen Methoden bieten verschiedene Anweisungen, wie Erweiterungen erstellt und installiert werden können, laden diese aber nicht automatisch. Erweiterungen können über eine extension-Direktive in der Datei php.ini oder mit der Funktion dl() geladen werden.

Wenn PHP-Module gebaut werden, ist es wichtig, die richtigen Versionen der benötigten Werkzeuge (autoconf, automake, libtool etc.) zu haben. Für Details zu den benötigten Werkzeugen und den benötigten Versionen siehe die » Anweisungen für Git.

## Herunterladen der PECL-Erweiterungen

> Hinweis: Der "PHP Installer for Extensions" (PIE) ist ein neues Tool, das PECL überflüssig machen wird. Wir empfehlen, für die Installation von Erweiterungen den PIE zu verwenden. Weitere Informationen sind unter » https://github.com/php/pie zu finden.

Es gibt mehrere Möglichkeiten, PECL-Erweiterungen herunterzuladen, z. B.:

- Mit dem Befehl pecl install extname wird der Code der Erweiterung automatisch heruntergeladen, sodass in diesem Fall kein gesonderter Download erforderlich ist.
- » https://pecl.php.net/ Die PECL-Website enthält Informationen über die verschiedenen Erweiterungen, die vom PHP Development Team angeboten werden. Die dort bereitgestellten Informationen umfassen Changelog, Versionshinweise, Anforderungen und andere ähnliche Details.
- pecl download extname PECL-Erweiterungen, deren Versionen auf der PECL-Website aufgeführt sind, können mit dem Befehl » pecl heruntergeladen und installiert werden. Es können auch bestimmte Versionen angegeben werden.
- git Viele PECL-Erweiterungen sind auf GitHub zu finden.
- SVN Einige PECL-Erweiterungen sind auch in SVN verfügbar. Eine webbasierte Ansicht ist unter » https://svn.php.net/pecl/ zu finden. Um direkt von SVN herunterzuladen, kann die folgende Befehlsfolge verwendet werden:

      $ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname

- Downloads für Windows Das PHP-Projekt bietet für die meisten PECL-Erweiterungen auf der Paket-Seite kompilierte Windows-DLLs an.

## Installation einer PHP-Erweiterung unter Windows

Unter Windows gibt es zwei Möglichkeiten, eine PHP-Erweiterung zu laden: Entweder sie wird in PHP einkompiliert oder sie wird als DLL geladen. Eine vorkompilierte Erweiterung zu laden ist die einfachste und auch die bevorzugte Methode.

Um eine Erweiterung zu laden, muss sie als .dll-Datei auf dem System vorhanden sein. Alle Erweiterungen werden automatisch und regelmäßig von der PHP-Gruppe kompiliert (bezüglich des Downloads siehe nächster Abschnitt).

Informationen darüber, wie Erweiterungen beim Kompilieren in PHP eingebunden werden, sind in der Dokumentation zum Erstellen aus dem Quellcode zu finden.

Um eine eigenständige Erweiterung (auch DLL-Datei genannt) zu kompilieren, siehe die Dokumentation Erstellen aus dem Quellcode. Wenn die DLL-Datei weder in der PHP-Distribution noch in PECL enthalten ist, muss sie möglicherweise kompiliert werden, bevor die Erweiterung verwendet werden kann.

### Wo finde ich eine Erweiterung?

PHP-Erweiterungen heißen normalerweise php_*.dll (wobei der Stern für den Namen der Erweiterung steht) und befinden sich im Ordner PHP\ext.

PHP wird mit den Erweiterungen ausgeliefert, die für die meisten Entwickler am nützlichsten sind. Sie werden als bundled Erweiterungen bezeichnet.

Wenn allerdings die benötigte Funktionalität von keiner der mitgelieferten Erweiterungen zur Verfügung gestellt wird, kann eine solche Erweiterung vielleicht in » PECL gefunden werden. Die PHP Extension Community Library (PECL) ist eine Sammlung von PHP-Erweiterungen, die eine Liste aller bekannten Erweiterungen sowie einen Hosting-Service für das Herunterladen und Entwickeln von PHP-Erweiterungen bereitstellt.

Wenn eine Erweiterung für bestimmte Zwecke entwickelt wurde, kann diese auf PECL zur Verfügung gestellt werden, damit auch andere davon profitieren können, die die gleichen Anforderungen haben. Ein netter Nebeneffekt ist, dass dies eine gute Möglichkeit ist, Feedback, (hoffentlich) Dank, Fehlerberichte und sogar Korrekturen/Patches zu erhalten. Bevor eine Erweiterung zum Hosting in PECL eingereicht wird, sollte » PECL submit gelesen werden.

### Welche Erweiterung soll ich herunterladen?

Häufig gibt es mehrere Versionen von einer DLL:

- Verschiedene Versionsnummern (zumindest die ersten beiden Nummern sollten übereinstimmen)
- Verschiedene Einstellungen für die Thread-Sicherheit
- Verschiedene Prozessorarchitekturen (x86, x64, ...)
- Verschiedene Einstellungen für das Debugging
- `etc.`

Es ist zu beachten, dass die Einstellungen der Erweiterung mit den Einstellungen des verwendeten PHP-Programms übereinstimmen sollten. Das folgende PHP-Skript zeigt alle PHP-Einstellungen an:

Beispiel #1 Aufruf der Funktion phpinfo()

    <?php
    phpinfo();
    ?>

Alternativ können Sie Folgendes über die Befehlszeile ausführen:

    drive:\path\to\php\executable\php.exe -i

### Laden einer Erweiterung

Die übliche Methode, eine PHP-Erweiterung zu laden, besteht darin, sie in die Konfigurationsdatei php.ini einzutragen. Es ist zu beachten, dass bereits viele Erweiterungen in der php.ini enthalten sind, und dass nur das Semikolon entfernt werden muss, um sie zu aktivieren.

Es ist auch zu beachten, dass seit PHP 7.2.0 anstelle des Dateinamens der Erweiterung auch deren Name verwendet werden kann. Da dies unabhängig vom Betriebssystem gilt und insbesondere für Neueinsteiger einfacher ist, ist dies die empfohlene Methode, um die zu ladenden Erweiterungen anzugeben. Dateinamen werden aus Gründen der Kompatibilität mit früheren Versionen weiterhin unterstützt.

    ;extension=php_extname.dll

    extension=php_extname.dll

    ; Seit PHP 7.2.0 vorzuziehen:
    extension=extname
    zend_extension=another_extension

Manche Webserver können allerdings etwas verwirrend sein, da sie nicht die php.ini aus der PHP-Distribution verwenden. Um herauszufinden, wo sich die tatsächlich verwendete php.ini befindet, kann der Pfad in phpinfo() gesucht werden:

    Configuration File (php.ini) Path  C:\WINDOWS

    Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini

Nachdem Sie eine Erweiterung aktiviert haben, speichern Sie die php.ini, starten den Webserver neu und überprüfen die phpinfo() erneut. Die neue Erweiterung sollte nun ihren eigenen Abschnitt haben.

### Probleme beheben

Wenn die Erweiterung nicht in phpinfo() erscheint, sollten die Logs überprüft werden, um herauszufinden, wo das Problem liegt.

Wenn PHP auf der Befehlszeile (CLI) verwendet wird, ist der Fehler beim Laden der Erweiterung direkt auf dem Bildschirm sehen.

Wenn PHP über einen Webserver verwendet wird, hängen Ort und Format der Logs von der Software ab. Da dies nichts mit PHP selbst zu tun hat, sollte die Dokumentation des Webservers zu Rate gezogen werden, um die Logs zu finden.

Die häufigsten Ursachen für Probleme sind die Speicherorte der DLL selbst und der DLLs, von denen sie abhängt, der Wert der Einstellung "extension_dir" in der php.ini und falsche Einstellungen beim Kompilieren.

Wenn das Problem auf falsche Einstellungen beim Kompilieren zurückzuführen ist, wurde wahrscheinlich nicht die richtige DLL heruntergeladen. Versuchen Sie, die Erweiterung nochmal mit den richtigen Einstellungen herunterzuladen. Auch hier kann phpinfo() eine große Hilfe sein.

## Kompilieren dynamischer PECL-Erweiterungen mit dem Befehl pecl

PECL bietet eine einfache Möglichkeit, dynamische PHP-Erweiterungen zu erstellen. Verwenden Sie dafür den folgenden » PECL-Befehl:

    $ pecl install extname

Mit diesem Befehl wird der Quellcode für extname heruntergeladen, kompiliert und extname.so ins Verzeichnis extension_dir installiert. extname.so kann dann über die php.ini geladen werden

Standardmäßig werden durch den Befehl pecl keine Pakete installiert, die mit dem Status `alpha` oder `beta` gekennzeichnet sind. Wenn keine `stable`-Pakete verfügbar sind, kann mit dem folgenden Befehl ein `beta`-Paket installiert werden:

    $ pecl install extname-beta

Mit dieser Variante kann auch eine bestimmte Version installiert werden:

    $ pecl install extname-0.1

> Hinweis:

> Nachdem die Erweiterung in der php.ini aktiviert wurde, muss der Webserver neu gestartet werden, damit die Änderungen übernommen werden.

## Kompilieren dynamischer PECL-Erweiterungen mit phpize

Manchmal ist es nicht möglich, das Installationsprogramm von pecl zu verwenden. Dies könnte an einer Firewall liegen, oder daran, dass die zu installierende Erweiterung nicht als PECL-kompatibles Paket verfügbar ist, z. B. weil sie noch nicht auf Git veröffentlicht wurde. Wenn eine solche Erweiterung erstellt werden muss, kannen dies mit einfacheren Build-Tools manuell erledigt werden.

Mit dem Befehl phpize wird die Build-Umgebung für eine PHP-Erweiterung vorbereitet. Im folgenden Beispiel befinden sich die Quellen für eine Erweiterung in einem Verzeichnis namens extname:

    $ cd extname
    $ phpize
    $ ./configure
    $ make
    # make install

Wenn alles gutgeht, wird extname.so erstellt und im Verzeichnis für PHP-Erweiterungen abgelegt. Bevor die Erweiterung verwendet werden kann, muss die Zeile `extension=extname.so` in die php.ini eingefügt werden.

Wenn es den Befehl `phpize` auf dem System nicht gibt und vorkompilierte Pakete (z. B. RPMs) verwendet werden, sollten unbedingt auch die entsprechende Entwicklerversion des PHP-Pakets installiert werden, da dieses oft den Befehl `phpize` sowie die entsprechenden Header zum Erstellen von PHP und seinen Erweiterungen enthält.

Mit dem Befehl phpize --help können zusätzliche Informationen zur Verwendung angezeigt werden.

## php-config

php-config ist ein einfaches Shell-Skript, das Informationen über die Konfiguration des installierten PHP-Systems liefert.

Wenn mehrere PHP-Versionen installiert sind, kann beim Kompilieren der Erweiterungen angeben, für welche Version diese erstellt werden soll, indem während der Konfiguration die Option `--with-php-config` verwendet wird und der Pfad des jeweiligen php-config-Skripts angegeben wird.

Die Liste der Kommandozeilenoptionen, die das Skript php-config zur Verfügung stellt, lässt sich jederzeit abfragen, indem php-config mit der Option -h ausgeführt wird:

    Usage: /usr/local/bin/php-config [OPTION]
    Options:
      --prefix            [...]
      --includes          [...]
      --ldflags           [...]
      --libs              [...]
      --extension-dir     [...]
      --include-dir       [...]
      --php-binary        [...]
      --php-sapis         [...]
      --configure-options [...]
      --version           [...]
      --vernum            [...]

Befehlszeilenoptionen
Option | Beschreibung
--- | ---
--prefix | Präfix des Verzeichnisses, in dem PHP installiert ist, z. B. /usr/local
--includes | Liste der `-I`-Optionen mit allen Include-Dateien
--ldflags | `LD`, mit denen PHP kompiliert wurde
--libs | Zusätzliche Bibliotheken, mit denen PHP kompiliert wurde
--extension-dir | Verzeichnis, in dem standardmäßig nach Erweiterungen gesucht wird
--include-dir | Präfix des Verzeichnisses, in das Header-Dateien standardmäßig installiert werden
--php-binary | Vollständiger Pfad zum PHP-CLI- oder -CGI-Binary
--php-sapis | Alle verfügbaren SAPI-Module
--configure-options | Konfigurationsoptionen zur Wiederherstellung der aktuellen PHP-Installationseinstellungen
--version | PHP-Version
--vernum | PHP-Version als Ganzzahl

## PECL-Erweiterungen statisch in PHP kompilieren

In manchen Fällen kann es nötig sein, eine PECL-Erweiterung statisch in das PHP-Binary zu kompilieren. Dazu muss der Quellcode der Erweiterung in das Verzeichnis `/pfad/zu/php/src/` einfügt werden und das PHP-Build-System angewiesen werden, sein configure-Skript neu zu erstellen.

    $ cd /pfad/zu/php/src/ext
    $ pecl download extname
    $ gzip -d < extname.tgz | tar -xvf -
    $ mv extname-x.x.x extname

Dadurch wird das folgende Verzeichnis erstellt:

    /pfad/zu/php/src/ext/extname

An dieser Stelle muss PHP veranlasst werden, das configure-Skript neu zu erstellen, und anschließend kann PHP gebaut werden wie gewohnt:

    $ cd /pfad/zu/php/src/
    $ rm configure
    $ ./buildconf --force
    $ ./configure --help
    $ ./configure --with-extname --enable-someotherext --with-foobar
    $ make
    $ make install

> Hinweis: Um das Skript buildconf auszuführen, werden autoconf `2.68` und automake benötigt. Neuere Versionen von autoconf könnten funktionieren, werden aber nicht unterstützt.

Ob --enable-extname oder --with-extname verwendet wird, hängt von der Erweiterung ab. Bei einer Erweiterung, die keine externen Bibliotheken benötigt, wird in der Regel --enable verwendet. Um sicher zu sein, kann nach buildconf folgender Befehl ausgeführt werden:

    $ ./configure --help | grep extname

# Installation of Composer and third-party packages

## Introduction to Composer

» Composer is a dependency manager for PHP that makes it possible to define third-party code packages used by a project that can then be easily installed and updated. It leverages the built-in class autoloading features of PHP, repositories of PHP packages such as » Packagist, and common project layout and coding conventions.

For example, if a PHP application or website needs to work with UUID values, » Ben Ramsey's `ramsey/uuid` package that implements the widely known and used types of UUIDs that are defined by » RFC 4122 could be used.

Briefly, this is done by creating a `composer.json` in the project, using Composer to install the latest version of the package, and including Composer's autoload script to make it available to the code. The » Composer "Basic Usage" documentation goes into this in more depth.

Beispiel #1 `composer.json` that requires a single package

    {
        "require": {
            "ramsey/uuid": "^4.7"
        }
    }

# Installation of PIE and third-party extensions

## Introduction to PIE

» PIE is an installer for PHP, that makes it possible to install third-party PHP extensions, that can then be easily installed and updated. It leverages the PHP extension repository part of » Packagist to find the source code to build the extension, or a Windows binary to download, if it exists. If it downloads the source code, it also knows how to build and install it.

After » installing the requirements and PIE itself, you can then install the MongoDB extension by running the following on the command line.

Beispiel #1 Installing the MongoDB extension with PIE

    pie install mongodb/mongodb-extension

The » "PIE Usage" documentation goes into this in more depth.

# Laufzeiteinstellungen

## Inhaltsverzeichnis

- Die Konfigurationsdatei
- .user.ini-Dateien
- Wo Konfigurationseinstellungen gesetzt werden können
- Wie man Konfigurationseinstellungen ändert

## Die Konfigurationsdatei

Die Konfigurationsdatei (php.ini) wird beim Start von PHP eingelesen. Für die Servermodul-Versionen von PHP geschieht dies nur einmal beim Start des Webservers. Für die CGI- und CLI-Versionen geschieht dies bei jedem Aufruf.

Nach der php.ini wird an folgenden Orten in der angegebenen Reihenfolge gesucht:

- Spezielle Orte für SAPI-Module (`PHPIniDir`-Direktive im Apache2, `-c` Kommandozeilenparameter in CGI und CLI)
- Die PHPRC-Umgebungsvariable.
- Die Position der `php.ini`-Datei kann für verschiedene Versionen von PHP gesetzt werden. Die Wurzel der Registrierungsschlüssel hängt davon ab, ob es sich um ein 32- oder 64-bit-System handelt, und ebenfalls von der PHP-Version. Für 32-bit-PHP auf einem 32-bit-System oder für 64-bit-PHP auf einem 64-bit-System ist `[(HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` zu verwenden; für 32-bit-PHP auf einem 64-bit-System ist stattdessen `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]`] zu verwenden. Bei einer Installation mit derselben Bitanzahl werden die folgenden Registrierungsschlüssel in der angegebenen Reihenfolge durchsucht: `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y]` und `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x]`, wobei x, y und z die Major-, Minor- und Release-Versionen von PHP darstellen. Für 32-bit PHP-Versionen auf einem 64-bit-System werden die folgenden Registrierungsschlüssel in der angegebenen Reihenfolge durchsucht: `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y.z]`, `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x.y]` und `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6421Node\PHP\x]`, wobei x, y und z die Major-, Minor- und Release-Versionen von PHP darstellen. Falls ein Wert für `IniFilePath` in einem dieser Schlüssel existiert, so wird der zuerst gefundene als Position der `php.ini` verwendet (nur unter Windows).
- `[HKEY_LOCAL_MACHINE\SOFTWARE\PHP]` bzw. `[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\PHP]`, Wert von `IniFilePath` (nur unter Windows).
- Aktuelles Arbeitsverzeichnis (außer CLI).
- Das Webserververzeichnis (für SAPI-Module) oder das PHP-Verzeichnis (andernfalls in Windows).
- Windows-Verzeichnis (C:\windows oder C:\winnt) (unter Windows) oder die `--with-config-file-path`-Kompilierungsoption.

Falls die Datei php-SAPI.ini existiert (wobei SAPI die verwendete SAPI ist, was als Dateinamen z. B. php-cli.ini oder php-apache.ini ergibt), wird diese anstelle der php.ini verwendet. Der Name der SAPI kann durch php_sapi_name() ermittelt werden.

> Hinweis:

> Der Apache-Webserver wechselt beim Start das Arbeitsverzeichnis in das Wurzelverzeichnis, weshalb PHP versucht, die php.ini aus dem Wurzelverzeichnis zu lesen, wenn diese existiert.

Umgebungsvariablen können in Konfigurationswerten in der php.ini referenziert werden, wie unten gezeigt. Seit PHP 8.3.0 kann ein Standardwert angegeben werden, der verwendet wird, wenn die referenzierte Variable nicht definiert ist.

Beispiel #1 php.ini-Umgebungsvariablen

    ; PHP_MEMORY_LIMIT ist der Name einer Umgebungsvariablen
    memory_limit = ${PHP_MEMORY_LIMIT}
    ; Wenn PHP_MAX_EXECUTION_TIME nicht gesetzt ist, wird der Standardwert 30 verwendet
    max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}

Die Optionen der php.ini für Extensions werden auf den Handbuchseiten der jeweiligen Extensions behandelt. Die Beschreibung der php.ini-Direktiven des Sprachkerns ist im Anhang verfügbar. Es werden jedoch möglicherweise nicht alle PHP-Direktiven im Handbuch erläutert. Für eine komplette Liste der in Ihrer PHP-Version verfügbaren Einstellungen lesen Sie bitte die gut kommentierte php.ini. Möglicherweise kann die » aktuellste php.ini aus dem Git-Repository ebenfalls hilfreich sein.

Beispiel #2 php.ini-Beispiel

    ; Jeder Text in einer Zeile nach einem Semikolon, welches nicht
    ; in Anführungszeichen steht, wird ignoriert
    [php] ; Abschnittsmarkierungen (Text in eckigen Klammern) werden ebenfalls ignoriert
    ; Boolesche Werte können auf einen der folgenden Werte eingestellt werden:
    ;      true, on, yes
    ; oder false, off, no, none
    register_globals = off
    track_errors = yes

    ; Sie können Zeichenketten in Anführungszeichen einschließen
    include_path = ".:/usr/local/lib/php"

    ; Backslashes werden wie alle anderen Zeichen behandelt
    include_path = ".;c:\php\lib"

Es ist möglich, sich auf bereits definierte .ini-Variablen innerhalb der .ini-Dateien zu beziehen. Zum Beispiel: `open_basedir = ${open_basedir}":/new/dir"`.

### Scan-Verzeichnisse

Es ist möglich, PHP so zu konfigurieren, dass nach .ini Dateien in einem Verzeichnis gesucht wird, nachdem php.ini gelesen wurde. Dies kann zur Kompilierzeit durch Setzen der Option --with-config-file-scan-dir erfolgen. Das Scan-Verzeichnis kann zur Laufzeit überschrieben werden, indem die Umgebungsvariable PHP_INI_SCAN_DIR gesetzt wird.

Es ist möglich, mehrere Verzeichnisse anzugeben, indem sie mit dem plattformspezifischen Pfadtrenner (`;` unter Windows, NetWare und RISC OS; `:` auf allen anderen Plattformen; der Wert, den PHP verwendet, is als `PATH_SEPARATOR` verfügbar). Wird in PHP_INI_SCAN_DIR ein leeres Verzeichnis angegeben, dann wird PHP beim Kompilieren auch das mit --with-config-file-scan-dir angegebene Verzeichnis durchsuchen.

In jedem Verzeichnis wird PHP alle Dateien mit der Erweiterung `.ini` in alphabetischer Reihenfolge lesen. Eine gemäß der Reihenfolge geordnete Liste der geladenen Dateien ist durch Aufruf von php_ini_scanned_files() verfügbar, oder indem PHP mit der Option --ini ausgeführt wird.

    Wir nehmen an, dass PHP mit --with-config-file-scan-dir=/etc/php.d kompiliert
    wurde, und dass der Pfadtrenner : ist...

    $ php
      PHP wird alle Dateien in /etc/php.d/*.ini als Konfigurationsdateien laden.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d php
      PHP wird alle Dateien in /usr/local/etc/php.d/*.ini als
      Konfigurationsdateien laden.

    $ PHP_INI_SCAN_DIR=:/usr/local/etc/php.d php
      PHP wird alle Dateien in /etc/php.d/*.ini, und dann
      /usr/local/etc/php.d/*.ini als Konfigurationsdateien laden.

    $ PHP_INI_SCAN_DIR=/usr/local/etc/php.d: php
      PHP wird alle Dateien in /usr/local/etc/php.d/*.ini, und dann
      /etc/php.d/*.ini als Konfigurationsdateien laden.

## .user.ini-Dateien

PHP bietet Unterstützung für Konfigurations-INI-Dateien auf Verzeichnisebene an. Diese Dateien werden nur durch die CGI/FastCGI-SAPI verarbeitet. Durch diese Funktionalität wird die PECL-Erweiterung htscanner obsolet. Falls Sie PHP als Apache-Modul ausführen, können Sie für denselben Effekt .htaccess-Dateien benutzen.

Zusätzlich zur Haupt-php.ini-Datei sucht PHP auch nach INI-Dateien in jedem Verzeichnis, beginnend mit dem Verzeichnis in der die angeforderte PHP-Datei liegt, aufwärts bis hin zum aktuellen "document root" (wie in $_SERVER['DOCUMENT_ROOT'] angezeigt). Falls sich die PHP-Datei außerhalb des "document root" befindet, wird nur das Verzeichnis, in dem sich die Datei befindet, durchsucht.

Nur INI-Einstellungen mit den Modi `INI_PERDIR` und `INI_USER` werden als .user.ini-INI-Dateien erkannt.

Zwei neue INI-Direktiven, user_ini.filename und user_ini.cache_ttl steuern die Nutzung der Benutzer-INI-Dateien.

user_ini.filename setzt den Namen der Datei, die von PHP in jedem Verzeichnis gesucht wird; falls dies auf eine leere Zeichenkette gesetzt wird, sucht PHP nach keiner Datei. Der Standardwert ist `.user.ini`.

user_ini.cache_ttl steuert, wie oft die Benutzer-INI-Dateien neu eingelesen werden. Der Standardwert beträgt 300 Sekunden (5 Minuten).

## Wo Konfigurationseinstellungen gesetzt werden können

Diese Modi bestimmen wann und wo eine PHP-Direktive gesetzt oder nicht gesetzt werden kann. Jede Direktive im Handbuch verweist auf einen dieser Modi. Zum Beispiel können einige Einstellungen in einem PHP-Skript mittels ini_set() gesetzt werden, während andere nur über die php.ini oder httpd.conf gesetzt werden können.

Ein Beispiel ist die output_buffering-Einstellung. Wegen `INI_PERDIR` kann sie nicht mittels ini_set() gesetzt werden. Die display_errors-Einstellung hingegegen kann wegen `INI_ALL` überall gesetzt werden, also auch mittels ini_set().

Konstanten für die INI-Modi
`INI_USER` (int)
  Der Eintrag kann in Benutzerskripten gesetzt werden (z. B. mit ini_set()) oder in der Windows-Registry. Der Eintrag kann in der .user.ini gesetzt werden
`INI_PERDIR` (int)
  Der Eintrag kann in der php.ini, der .htaccess, der httpd.conf oder der .user.ini gesetzt werden
`INI_SYSTEM` (int)
  Der Eintrag kann in der php.ini oder der httpd.conf gesetzt werden
`INI_ALL` (int)
  Der Eintrag kann überall gesetzt werden

## Wie man Konfigurationseinstellungen ändert

### PHP läuft als Apachemodul

Wenn man PHP als Apachemodul verwendet, kann man die Konfigurationseinstellungen mittels Direktiven in den Apache-Konfigurationsdateien (z. B. httpd.conf) und .htaccess-Dateien ändern. Dafür benötigt man "AllowOverride Options"- oder "AllowOverride All"-Privilegien.

Es gibt verschiedene Apachedirektiven, die es erlauben, die PHP-Konfiguration aus den Apache-Konfigurationsdateien heraus zu ändern. Für eine Liste von Direktiven, die als `INI_ALL`, `INI_PERDIR`, oder `INI_SYSTEM` definiert sind, werfen Sie einen Blick auf den Anhang Liste von php.ini Einstellungen.

`php_value` `Name` `Wert`

  Setzt den Wert der angegebenen Direktive. Kann nur für Direktiven mit den Typen `INI_ALL` und `INI_PERDIR` verwendet werden. Um einen vorher gesetzten Wert zu löschen, verwenden Sie `none` als Wert.

  > Hinweis: Verwenden Sie `php_value` nicht, um boolesche Werte zu setzen. `php_flag` (siehe unten) sollte stattdessen verwendet werden.

`php_flag` `Name` `on|off`

  Setzt eine boolesche Konfigurationsdirektive. Kann nur für Direktiven mit den Typen `INI_ALL` und `INI_PERDIR` verwendet werden.

`php_admin_value` `Name` `Wert`

  Setzt den Wert der angegebenen Direktive. Dies kann nicht in .htaccess-Dateien verwendet werden. Jeder Direktiventyp, der mit `php_admin_value` gesetzt wird, kann nicht durch .htaccess-Direktiven oder mit ini_set() überschrieben werden. Um einen vorher gesetzten Wert zu löschen, verwenden Sie `none` als Wert.

`php_admin_flag` `Name` `on|off`

  Setzt eine boolesche Konfigurationsdirektive. Dies kann nicht in .htaccess-Dateien verwendet werden. Jeder Direktiventyp, der mit `php_admin_value` gesetzt wird, kann nicht durch .htaccess-Direktiven oder ini_set() überschrieben werden.

Beispiel #1 Apache-Konfigurationsbeispiel

    <IfModule mod_php5.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>
    <IfModule mod_php4.c>
      php_value include_path ".:/usr/local/lib/php"
      php_admin_flag engine on
    </IfModule>

Achtung

PHP-Konstanten existieren nicht außerhalb von PHP. So kann man z. B. in der httpd.conf nicht PHP-Konstanten wie `E_ALL` oder `E_NOTICE` verwenden, um den Wert der error_reporting-Direktive zu ändern, da diese keine Bedeutung haben und als 0 ausgewertet werden. Verwenden Sie stattdessen die zugehörigen Bitmasken-Werte direkt. Diese Konstanten können in der php.ini verwendet werden.

### Die PHP-Konfiguration mit der Windows Registry ändern

Wenn Sie PHP unter Windows einsetzen, können Sie die Konfigurationseinstellungen für jedes einzelne Verzeichnis mit der Windows-Registry anpassen. Die Werte der Konfiguration werden unterhalb des Registrierungsschlüssels `HKLM\SOFTWARE\PHP\Per Directory Values` in den zum Verzeichnisnamen passenden Unterschlüssel gespeichert.Zum Beispiel würden Werte für das Verzeichnis `c:\inetpub\wwwroot` im Registrierungsschlüssel `HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot` gespeichert werden. Die Einstellungen für dieses Verzeichnis wären für alle Skripte aktiv, die in diesem Verzeichnis oder einem seiner Unterverzeichnisse laufen. Die Werte in diesem Schlüssel sollten den Namen eine PHP- Konfigurationsdirektive und einen Zeichenkettenwert haben. Konstenten in den Werten werden nicht ausgewertet. Es können jedoch nur Werte, die in `INI_USER` änderbar sind, auf diese Weise gesetzt werden, nicht als `INI_PERDIR` deklarierte Werte, da diese Konfigurationswerte für jeden Request erneut gelesen werden.

### Andere Zugänge zu PHP

Egal wie Sie PHP betreiben, Sie können bestimmte Werte zur Laufzeit Ihrer Skripte mittels ini_set() setzen. Werfen Sie dazu einen Blick auf die Dokumentation von ini_set().

Wenn Sie an einer kompletten Liste von Konfigurationseinstellungen Ihres Systems inklusive deren aktuellen Werten interessiert sind, können Sie die Funktion phpinfo() ausführen und die daraus resultierende Seite betrachten. Sie können auf die Werte einzelner Konfigurationsdirektiven zur Laufzeit mittels ini_get() oder get_cfg_var() zugreifen.

- Generelle Überlegungen
- Installation auf Unix-Systemen
  - Installation von Paketen unter Debian GNU/Linux und verwandten Distributionen
  - Installing from packages on GNU/Linux distributions that use DNF
  - Installation von Paketen oder Ports unter OpenBSD
  - Installing from source on Unix and macOS systems
  - CGI und Kommandozeilen Setups
  - Apache 2.x auf Unixsystemen
  - Nginx 1.4.x auf Unix-Systemen
  - Lighttpd 1.4 auf Unix-Systemen
  - LiteSpeed-/OpenLiteSpeed-Webserver auf Unix-Systemen
  - Solaris-spezifische Tipps für die Installation
- Installation unter macOS
  - Installation unter macOS mit Paketen von Drittanbietern
  - Kompilieren von PHP unter macOS
  - Verwendung des mitgelieferten PHP vor macOS Monterey
- Installation auf Windows-Systemen
  - Empfohlene Konfiguration auf Windows-Systemen
  - Manuelle PHP-Installation auf Windows
  - Installation für Apache 2.x auf Windows-Systemen
  - Installation with IIS for Windows
  - Drittanbieter-Tools zur Installation von PHP
  - Erstellen aus dem Quellcode
  - PHP auf Windows-Systemen auf der Kommandozeile ausführen
- Installation auf Cloud Computing Platformen
  - Azure App Services
  - Amazon EC2
  - DigitalOcean
- FastCGI Process Manager (FPM)
  - Installation
  - Konfiguration
- Installation der PECL-Erweiterungen
  - Einführung in die PECL-Installationen
  - Herunterladen der PECL-Erweiterungen
  - Installation einer PHP-Erweiterung unter Windows
  - Kompilieren dynamischer PECL-Erweiterungen mit dem Befehl pecl
  - Kompilieren dynamischer PECL-Erweiterungen mit phpize
  - php-config
  - PECL-Erweiterungen statisch in PHP kompilieren
- Introduction to Composer
- Introduction to PIE
- Laufzeiteinstellungen
  - Die Konfigurationsdatei
  - .user.ini-Dateien
  - Wo Konfigurationseinstellungen gesetzt werden können
  - Wie man Konfigurationseinstellungen ändert

# Sprachreferenz

# Grundlagen der Syntax

## Inhaltsverzeichnis

- PHP-Tags
- Den HTML-Bereich verlassen
- Die Trennung von Anweisungen
- Kommentare

## PHP-Tags

Wenn PHP eine Datei verarbeitet, erkennt es die öffnenden und schließenden Tags `<?php` und `?>`, um den Bereich abzugrenzen, in dem PHP-Code ausgeführt wird. Inhalte außerhalb dieser Tags werden vom PHP-Parser ignoriert, so dass PHP nahtlos in verschiedene Dokumenttypen integriert werden kann.

Nach `<?php` muss ein Whitespace-Zeichen (Leerzeichen, Tabulator oder Zeilenumbruch) folgen, um eine korrekte Trennung der Token zu gewährleisten. Wird dieses Zeichen weggelassen, führt dies zu einem Syntaxfehler.

PHP kennt außerdem den kurzen Ausgabe-Tag `<?=`, der eine Kurzform für `<?php echo` ist.

Beispiel #1 Öffnende und schließende PHP-Tags

    1.  <?php echo 'Verwenden Sie diese Tags, wenn Sie PHP-Code in XHTML- oder
                    XML-Dokumenten ausgeben wollen'; ?>

    2.  Sie können den kurzen echo-Tag für die
        <?= 'Ausgabe dieser Zeichenkette' ?> verwenden.
        Es ist äquivalent zur <?php echo 'Ausgabe dieser Zeichenkette' ?>.

    3.  <? echo 'dieser Code ist innerhalb von kurzen Tags, wird aber nur '.
                'funktionieren, wenn short_open_tag aktiviert ist'; ?>

Kurze Tags (Beispiel drei) sind standardmäßig verfügbar, können aber entweder über die Anweisung short_open_tag der php.ini-Konfigurationsdatei deaktiviert werden oder sind standardmäßig deaktiviert, wenn PHP mit der Konfigurationsanweisung --disable-short-tags gebaut wird.

> Hinweis:

> Da kurze Tags deaktiviert werden können, wird für maximale Kompatibilität empfohlen, nur die normalen Tags (`<?php ?>` und `<?= ?>`) zu verwenden.

Wenn eine Datei mit PHP-Code endet, ist es besser, den schließenden PHP-Tag am Ende der Datei wegzulassen. Dies verhindert, dass versehentlich Leerzeichen oder neue Zeilen nach dem schließenden Tag eingefügt werden, was unerwünschte Effekte verursachen kann, da PHP mit der Ausgabe beginnt, obwohl der Programmierer an dieser Stelle des Skripts nicht die Absicht hat, eine Ausgabe zu senden.

Beispiel #2 Datei nur mit PHP-Code

    <?php
    echo "Hallo Welt\n";

    // ... mehr Code

    echo "Letzte Anweisung\n";

    // das Skript endet hier ohne schließenden PHP-Tag

## Den HTML-Bereich verlassen

Alles außerhalb eines Paares von öffnenden und schließenden Tags wird vom PHP-Parser ignoriert, was es ermöglicht, dass PHP-Dateien gemischten Inhalt haben können. Dadurch kann PHP in HTML-Dokumente eingebettet werden, zum Beispiel um Templates zu erstellen.

Beispiel #1 PHP in HTML einbetten

    <p>Das hier wird von PHP ignoriert, und vom Browser angezeigt.</p>
    <?php echo 'Wohingegen das hier geparst wird.'; ?>
    <p>Dies wird ebenfalls von PHP ignoriert, und vom Browser angezeigt.</p>

Dies funktioniert wie erwartet, da der PHP-Interpreter, wenn er auf einen schließenden ?>-Tag trifft, einfach beginnt, alles mit Ausnahme des direkt folgenden Zeilenumbruchs (siehe auch den Abschnitt Abgrenzung von Anweisungen) auszugeben, bis er wieder auf einen öffnenden Tag stößt. Das gilt nicht in der Mitte einer bedingten Anweisung. In diesem Fall ermittelt der Interpreter das Resultat der Bedingung, bevor er entscheidet, was übersprungen wird. Siehe das folgende Beispiel.

Verwendung von Strukturen mit Bedingungen

Beispiel #2 Fortgeschrittene Ausgabe unter Verwendung von Bedingungen

    <?php if ($expression == true): ?>
      Dies wird angezeigt, wenn der Ausdruck wahr ist.
    <?php else: ?>
      Andernfalls wird dies angezeigt.
    <?php endif; ?>

In diesem Beispiel überspringt PHP die Blöcke, in denen die Bedingung nicht erfüllt ist, obwohl diese außerhalb der öffnenden/schließenden PHP-Tags liegen; PHP überspringt sie entsprechend der Bedingung, da der PHP-Interpreter Blöcke innerhalb einer nicht erfüllten Bedingung überspringt.

Für die Ausgabe von großen Textblöcken ist der Ausstieg aus dem Parse-Modus generell effizienter, als den gesamten Text durch echo oder print zu jagen.

> Hinweis:

> Wenn PHP in XML oder XHTML eingebettet wird, müssen die normalen `<?php ?>`-PHP-Tags verwenden werden, um die Standards einzuhalten.

## Die Trennung von Anweisungen

Wie in C oder Perl müssen Anweisungen auch in PHP am Ende mit einem Semikolon abgeschlossen werden. Der abschließende Tag eines PHP-Codeblocks impliziert automatisch ein Semikolon; die letzte Zeile eines PHP-Blocks benötigt kein Semikolon am Ende. Der schließende Tag des Blocks schließt den unmittelbar folgenden Zeilenumbruch, falls vorhanden, ein.

Beispiel #1 Beispiel für den schließenden Tag, der den abschließenden Zeilenumbruch einschließt

    <?php echo "Etwas Text"; ?>
    Kein Zeilenumbruch
    <?= "Aber jetzt ein Zeilenumbruch" ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Etwas TextKein Zeilenumbruch
    Aber jetzt ein Zeilenumbruch

Beispiel #2 Beispiele für das Starten und Beenden des PHP-Parsers

    <?php
        echo "Dies ist ein Test\n";
    ?>

    <?php echo "Dies ist ein Test\n" ?>

    <?php echo "Wir ließen den letzten schließenden Tag weg\n";

> Hinweis:

> Der schließende Tag eines PHP-Blocks am Ende einer Datei ist optional, und in einigen Fällen ist das Weglassen hilfreich, wenn Sie include oder require verwenden, so dass ungewollte Whitespaces nicht am Ende einer Datei auftreten und Sie noch im Stande sind, später weitere Header an die Antwort hinzuzufügen. Es ist ebenfalls praktisch, wenn Sie die Ausgabepufferung verwenden und keine ungewollten Whitespaces am Ende eines durch die eingebundenen Dateien erzeugten Teils sehen wollen.

## Kommentare

PHP unterstützt 'C'-, 'C++'- und Unix-Shell-artige (Perl-artige) Kommentare. Zum Beispiel:

Beispiel #1 Kommentare

    <?php
        echo "Dies ist ein Test\n"; // Dies ist ein einzeiliger Kommentar im C++-Stil
        /* Dies ist ein mehrzeiliger Kommentar
           noch eine weitere Kommentarzeile */
        echo "Dies ist noch ein Test\n";
        echo "... und ein letzter Test\n"; # Dies ist ein einzeiliger Kommentar im Shell-Stil
    ?>

Die "einzeiligen" Kommentar-Arten kommentieren sämtlichen Text bis zum Zeilenende oder bis zum Ende des aktuellen PHP-Blocks aus, je nachdem, was zuerst eintritt. Das bedeutet, das HTML-Code nach `// ... ?>` oder `# ... ?>` ausgegeben WIRD: ?> beendet den PHP-Modus und kehrt in den HTML-Modus zurück, so dass sich `//` oder `#` nicht darauf auswirkt.

Beispiel #2 Einzeilige Kommentare

    <h1>Dies ist ein <?php # echo 'einfaches';?> Beispiel.</h1>
    <p>Obige Überschrift wird lauten: 'Dies ist ein  Beispiel.'.

'C'-artige Kommentare enden am ersten Vorkommen von `*/`. Achten Sie daher darauf, 'C'-artige Kommentare nicht zu verschachteln. Dieser Fehler entsteht leicht, wenn Sie längere Code-Blöcke auskommentieren.

    <?php
    /*
       echo 'Dies ist ein Test'; /* Dieser Kommentar wird ein Problem verursachen. */
    */
    ?>

# Typen

## Inhaltsverzeichnis

- Einführung
- Typsystem
- NULL
- Booleans
- Ganzzahlen (Integer)
- Gleitkommazahlen
- Strings (Zeichenketten)
- Numerische Zeichenketten
- Arrays
- Objekte
- Aufzählungen (Enum)
- Ressourcen
- Callables
- Mixed
- Void
- Never
- Relative Klassentypen
- Singleton-Typen
- Iterable
- Typdeklarationen
- Typumwandlung (Typen-Jonglage)

## Einführung

Jeder einzelne Ausdruck in PHP hat in Abhängigkeit von seinem Wert einen der folgenden internen Typen:

- null
- bool
- int
- float (Gleitkommazahl)
- string
- array
- object
- callable
- resource

PHP ist eine dynamisch typisierte Sprache, was bedeutet, dass es standardmäßig nicht notwendig ist, einer Variablen einen Typ zuzuweisen, weil dieser zur Laufzeit bestimmt wird. Mit Hilfe von Typ-Deklarationen ist es jedoch möglich, einige Aspekte der Sprache statisch zu typisieren. Die verschiedenen Typen, die vom PHP-Typsystem unterstützt werden, können auf der Seite Typsystem gefunden werden.

Durch Typen wird die Art der Operationen, die mit ihnen durchgeführt werden können, eingeschränkt. Wenn jedoch ein Ausdruck oder eine Variable in einer Operation verwendet wird, die ihr Typ nicht unterstützt, wird PHP versuchen, den Wert mittels Typ-Umwandlung (sog. Type Juggling, Typ-Jonglage) in einen Typ zu überführen, der die Operation unterstützt. Dieser Prozess hängt von dem Kontext ab, in dem der Wert verwendet wird. Weitere Informationen hierzu sind im Abschnitt über Typ-Umwandlung zu finden.

Tipp

Die Tabellen mit Vergleichen von PHP-Typen können ebenfalls nützlich sein, da sie verschiedene Beispiele für den Vergleich zwischen Werten verschiedener Typen enthalten.

> Hinweis: Mit einer Typ-Zuweisung kann man erzwingen, dass ein Ausdruck nach einem bestimmten Typ ausgewertet wird. Außerdem kann eine Variable mit Hilfe der Funktion settype() direkt auf einen bestimmten Typ gesetzt werden.

Um den Wert und den Typ eines Ausdrucks zu ermitteln, kann die Funktion var_dump() verwendet werden. Den Typ eines Ausdrucks erhält man mit der Funktion get_debug_type(). Um jedoch zu prüfen, ob ein Ausdruck von einem bestimmten Typ ist, sollten stattdessen die `is_type`-Funktionen verwendet werden.

Beispiel #1 Verschiedene Typen

    <?php
    $a_bool = true;   // Typ bool (Wahrheitswert)
    $a_str  = "foo";  // Typ string (Zeichenkette)
    $a_str2 = 'foo';  // Typ string (Zeichenkette)
    $an_int = 12;     // Typ int (Ganzzahl)

    echo get_debug_type($a_bool), "\n";
    echo get_debug_type($a_str), "\n";

    // Falls es ein Integer ist, erhöhe ihn um vier
    if (is_int($an_int)) {
        $an_int += 4;
    }
    var_dump($an_int);

    // Falls $a_bool ein String ist, gib ihn aus
    if (is_string($a_bool)) {
        echo "String: $a_bool";
    }
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    bool
    string
    int(16)

> Hinweis: Die Funktion get_debug_type() steht erst seit PHP 8.0.0 zur Verfügung. Davor kann stattdessen die Funktion gettype() verwendet werden, die jedoch nicht die kanonischen Typnamen verwendet.

## Typsystem

PHP verwendet ein nominales Typsystem mit einer starken verhaltenbasierten Subtypisierungsbeziehung. Die Subtypisierungsbeziehung wird zur Kompilierzeit überprüft, während die Überprüfung der Typen dynamisch zur Laufzeit erfolgt.

Das PHP-Typsystem unterstützt verschiedene atomare Typen, die zusammengesetzt werden können, um komplexere Typen zu erzeugen. Einige dieser Typen können als Typendeklaration geschrieben werden.

### Atomare Typen

Manche atomare Typen sind eingebaute Typen, die fest in die Sprache integriert sind und nicht durch benutzerdefinierte Typen reproduziert werden können.

Liste der Basistypen:

- Eingebaute Typen
  - Skalare Typen:
    - Typ bool
    - Typ int
    - Typ float
    - Typ string
  - Typ array
  - Typ object
  - Typ resource
  - Typ never
  - Typ void
  - Relative Klassentypen: self, parent und static
  - Singleton-Typen
    - false
    - true
  - Unit types
    - null
- Benutzerdefinierte Typen (im Allgemeinen als Klassentypen bezeichnet)
  - Schnittstellen
  - Klassen
  - Aufzählungen
- Typ callable

#### Skalare Typen

Ein Wert gilt als skalar, wenn er vom Typ int, float, string oder bool ist.

#### Benutzerdefinierte Typen

Mit Schnittstellen, Klassen und Aufzählungen können benutzerdefinierte Typen erstellt werden. Diese werden als benutzerdefinierte Typen oder Klassentypen bezeichnet. So kann beispielsweise eine Klasse namens `Elefant` definiert werden, aus der Objekte vom Typ `Elefant` instanziiert werden. Eine Funktion kann dann einen Parameter vom Typ `Elefant` anfordern.

### Zusammengefasste Typen

Es ist möglich, mehrere atomare Typen zu zusammengefassten Typen zu kombinieren. In PHP können Typen auf folgende Weise kombiniert werden:

- Schnittmenge von Klassentypen (Schnittstellen und Klassennamen).
- Zusammenfassung von Typen (Union-Typen).

#### Schnittmengentypen

Ein Schnittmengentyp akzeptiert Werte, die mehrere Klassentyp-Deklarationen erfüllen, anstatt nur einer. Die einzelnen Typen, die den Schnittmengentyp bilden, werden durch das Symbol `&` verbunden. Daher wird ein Schnittmengentyp, der aus den Typen `T`, `U` und `V` besteht, als `T&U&V` geschrieben.

#### Zusammengefasste Typen (Union-Typen)

Ein Union-Typ akzeptiert die Werte mehrerer verschiedener Typen und nicht nur eines einzigen. Die einzelnen Typen, die den Union-Typ bilden, werden durch das Symbol `|` verbunden. Daher wird ein Union-Typ, der aus den Typen `T`, `U` und `V` besteht, als `T|U|V` geschrieben. Wenn einer der Typen ein Schnittmengentyp ist, muss er in Klammern gesetzt werden, damit er in DNF geschrieben werden kann: `T|(X&Y)`.

### Typ-Aliase

PHP unterstützt die beiden Typ-Aliase mixed und iterable, die dem Union-Typ von `object|resource|array|string|float|int|bool|null` bzw. `Traversable|array` entsprechen.

> Hinweis: PHP unterstützt keine benutzerdefinierten Typ-Aliase.

## NULL

Der Typ null ist der Einheitstyp von PHP, d. h. er hat nur einen Wert: `null`.

Nicht definierte und unset()-Variablen werden zum Wert `null` aufgelöst.

### Syntax

Es gibt nur einen Wert vom Typ null, das ist die von Groß- und Kleinschreibung unabhängige Konstante `null`.

    <?php
    $var = NULL;
    ?>

### Umwandlung in `null`

Warnung

Dieses Feature ist seit PHP 7.2.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieses Features wird dringend abgeraten.

Die Umwandlung einer Variable auf den Typ null durch `(unset) $var` entfernt die Variable nicht oder hebt ihren Wert auf. Es wird lediglich ein `null`-Wert zurückgegeben.

### Siehe auch

- is_null()
- unset()

## Booleans

Der Typ bool kann nur zwei Werte annehmen und wird verwendet, um einen Wahrheitswert auszudrücken; er kann entweder `true` (wahr) oder `false` (falsch) sein.

### Syntax

Ein bool-Wert wird über die Konstanten `true` und `false` spezifiziert, Groß- und Kleinschreibung ist dabei nicht von Bedeutung.

    <?php
    $foo = True; // weist $foo den Wert TRUE zu
    ?>

Normalerweise wird ein bool von einem Operator zurückgegeben und an eine Kontrollstruktur weitergegeben.

    <?php
    $action = "show_version";
    $show_separators = true;

    // == ist ein Operator, der auf Gleichheit prüft
    // und ein boolean-Ergebnis zurückgibt
    if ($action == "show_version") {
        echo "Die Version ist 1.23";
    }

    // die Angabe von '== TRUE' ist nicht nötig...
    if ($show_separators == TRUE) {
        echo "<hr>\n";
    }

    // ... weil folgendes genau dieselbe Bedeutung hat:
    if ($show_separators) {
        echo "<hr>\n";
    }
    ?>

### Umwandlung in Boolean

Um einen Wert explizit in bool zu konvertieren, kann der `(bool)`-Cast verwendet werden. Im Allgemeinen ist dies nicht notwendig, da ein Wert, wenn er in einem logischen Kontext verwendet wird, automatisch als ein Wert vom Typ bool interpretiert wird. Für weitere Informationen siehe die Seite Typumwandlungen.

Bei der Konvertierung zum Typ bool gelten die folgenden Werte als `false`:

- Der Boolean `false` selbst
- Der Integer `0` (null)
- Die Gleitkommazahlen `0.0` und `-0.0` (null)
- Der leere String `""` und der String `"0"`
- Ein Array ohne Elemente
- Der Einheitstyp NULL (inklusive nicht gesetzter Variablen)
- Interne Objekte, die ihr Casting-Verhalten auf bool überladen, zum Beispiel GMP-Objekte, die den Wert `0` repräsentieren.

Jeder andere Wert wird als `true` angenommen (inklusive Ressourcen und `NAN`).

Warnung

`-1` gilt als `true` wie jeder andere Integerwert ungleich 0 (egal ob positiv oder negativ)!

Beispiel #1 Umwandlung in Boolean

    <?php
    var_dump((bool) "");        // bool(false)
    var_dump((bool) "0");       // bool(false)
    var_dump((bool) 1);         // bool(true)
    var_dump((bool) -2);        // bool(true)
    var_dump((bool) "foo");     // bool(true)
    var_dump((bool) 2.3e5);     // bool(true)
    var_dump((bool) array(12)); // bool(true)
    var_dump((bool) array());   // bool(false)
    var_dump((bool) "false");   // bool(true)
    ?>

## Ganzzahlen (Integer)

Ein int ist eine Zahl aus der Menge ℤ = {..., -2, -1, 0, 1, 2, ...}.

### Siehe auch

- Gleitkommazahlen
- Rechnen mit beliebiger Genauigkeit (BCMath)
- Rechnen mit ganzen Zahlen mit beliebiger Genauigkeit (GMP)

### Syntax

Ints können in dezimaler (Basis 10), hexadezimaler (Basis 16), oktaler (Basis 8) oder binärer (Basis 2) Schreibweise angegeben werden. Der Negationsoperator kann verwendet werden, um einen negativen int anzugeben.

Um die oktale Schreibweise zu verwenden, wird der Zahl eine `0` (Null) vorangestellt. Seit PHP 8.1.0 kann der oktalen Schreibweise auch ein `0o` oder `0O` vorangestellt werden. Um die hexadezimale Schreibweise zu verwenden, muss der Zahl `0x` vorangestellt werden, für die binäre Schreibweise `0b`.

Um die Lesbarkeit von Integer-Literalen zu verbessern, dürfen diese seit PHP 7.4.0 Unterstriche (`_`) zwischen den Ziffern enthalten. Diese Unterstriche werden von PHPs Scanner entfernt.

Beispiel #1 Integer-Literale

    <?php
    $a = 1234; // Dezimalzahl
    $a = 0123; // Oktalzahl (entspricht 83 dezimal)
    $a = 0o123; // Oktalzahl (ab PHP 8.1.0)
    $a = 0x1A; // Hexadezimalzahl (entspricht 26 dezimal)
    $a = 0b11111111; // Binärzahl (entspricht 255 dezimal)
    $a = 1_234_567; // Dezimalzahl (ab PHP 7.4.0)
    ?>

Seit PHP 8.1.0 ist die Struktur für int-Literale formal wie folgt definiert (vorher waren die Oktalpräfixe `0o` und `0O` nicht erlaubt, und vor PHP 7.4.0 waren die Unterstriche nicht erlaubt):

    dezimal     : [1-9][0-9]*(_[0-9]+)*
                | 0

    hexadezimal : 0[xX][0-9a-fA-F]+(_[0-9a-fA-F]+)*

    oktal       : 0[oO]?[0-7]+(_[0-7]+)*

    binär       : 0[bB][01]+(_[01]+)*

    ganzzahlig  : dezimal
                | hexadezimal
                | oktal
                | binär

Die Größe eines Werts vom Typ int ist plattformabhängig, wobei der Maximalwert normalerweise bei etwa zwei Milliarden liegt (das sind 32 Bit mit Vorzeichen). Bei 64-Bit-Plattformen liegt der Maximalwert normalerweise bei etwa 9E18. PHP unterstützt keine vorzeichenlosen ints. Die Größe von int kann mit der Konstante `PHP_INT_SIZE` ermittelt werden, der maximale Wert mit der Konstante `PHP_INT_MAX` und der minimale Wert mit der Konstante `PHP_INT_MIN`.

### Integer-Überlauf

Wenn eine Zahl außerhalb der Grenzen des Typs int liegt, interpretiert PHP sie stattdessen als float. Auch eine Operation, die eine Zahl außerhalb der Grenzen des Typs int ergibt, gibt stattdessen einen Float zurück.

Beispiel #2 Integer-Überlauf

    <?php
    $large_number = 50000000000000000000;
    var_dump($large_number);         // float(5.0E+19)

    var_dump(PHP_INT_MAX + 1);       // 32-bit-System: float(2147483648)
                                     // 64-bit-System: float(9.2233720368548E+18)
    ?>

### Integer-Division

In PHP gibt es keinen Operator für die Division von int. Dafür kann die Funktion intdiv() verwendet werden. Das Ergebnis von `1/2` ist der Float-Wert `0.5`. Der Wert kann in einen int umgewandelt werden, um ihn auf Null zu runden. Alternativ dazu kann die Funktion round() verwendet werden, die eine feinere Kontrolle über das Runden ermöglicht.

Beispiel #3 Divisionen

    <?php
    var_dump(25/7);         // float(3.5714285714286)
    var_dump((int) (25/7)); // int(3)
    var_dump(round(25/7));  // float(4)
    ?>

### Umwandlung in Integer

Um einen Wert explizit in int umzuwandeln, kann der `(int)`-Cast verwendet werden. In den meisten Fällen ist das jedoch nicht nötig, weil ein Wert automatisch umgewandelt wird, wenn ein Operator, eine Funktion oder eine Kontrollstruktur ein Argument vom Typ int benötigt. Ein Wert kann auch mit der Funktion intval() in int umgewandelt werden.

Wenn eine Ressource in int umgewandelt wird, dann ist das Ergebnis die eindeutige Nummer der Ressource, die der Ressource von PHP zur Laufzeit zugewiesen wird.

Siehe auch Typumwandlung.

#### Von Booleans

`false` ergibt `0` (Null) und `true` ergibt `1` (Eins).

#### Von Gleitkommazahlen

Bei der Umwandlung von float nach int wird die Zahl abgerundet. Seit PHP 8.1.0 wird davon abgeraten, einen nicht-ganzzahligen Float in Integer umzuwandeln, weil dabei die Genauigkeit abnimmt.

Beispiel #4 Umwandlung von Float

    <?php

    function foo($value): int {
      return $value;
    }

    var_dump(foo(8.1)); // seit PHP 8.1.0: "Deprecated: Implicit conversion from float 8.1 to int loses precision"
    var_dump(foo(8.1)); // bis PHP 8.1.0: 8
    var_dump(foo(8.0)); // in beiden Fällen 8

    var_dump((int) 8.1); // in beiden Fällen 8
    var_dump(intval(8.1)); // in beiden Fällen 8
    ?>

Wenn der Float-Wert außerhalb der Grenzen von int liegt (auf 32-bit-Plattformen normalerweise `+/- 2.15e+9 = 2^31` und auf 64-bit-Plattformen `+/- 9.22e+18 = 2^63`), ist das Ergebnis undefiniert. Das liegt daran, dass der Typ float nicht genau genug ist, um ein exaktes Ergebnis für den Typ int zu liefern. In diesem Fall wird keine Warnung und nicht einmal ein Hinweis ausgegeben!

> Hinweis:

> Wenn `NaN`, `Inf` und `-Inf` in int umgewandelt werden, ergibt dies immer Null.

Warnung

Eine unbekannte Bruchzahl sollte niemals in int umgewandelt werden, weil dies manchmal zu unerwarteten Ergebnissen führen kann.

    <?php
    echo (int) ( (0.1+0.7) * 10 ); // gibt 7 aus!
    ?>

Siehe auch den Warnhinweis zur Genauigkeit von Gleitkommazahlen.

#### Von einer Zeichenkette

Wenn eine Zeichenkette numerisch ist oder numerisch beginnt, wird sie in den entsprechenden Integer-Wert umgewandelt, andernfalls wird sie in Null (`0`) umgewandelt.

#### Von NULL

`null` wird immer in Null (`0`) umgewandelt.

#### Von anderen Typen

Achtung

Für andere Typen ist das Verhalten bei der Umwandlung in int undefiniert. Es ist nicht empfehlenswert, sich auf ein beobachtetes Verhalten zu verlassen, da es sich ohne Vorankündigung ändern kann.

## Gleitkommazahlen

Gleitkommazahlen (auch als "floats", "doubles" oder "reelle Zahlen" bezeichnet) können anhand einer der folgenden Schreibweisen bezeichnet werden:

    <?php
    $a = 1.234;
    $b = 1.2e3;
    $c = 7E-10;
    $d = 1_234.567; // von PHP 7.4.0 an
    ?>

Formell von PHP 7.4.0 an (zuvor waren Unterstriche nicht erlaubt):

    LNUM          [0-9]+(_[0-9]+)*
    DNUM          ({LNUM}?"."{LNUM}) | ({LNUM}"."{LNUM}?)
    EXPONENT_DNUM (({LNUM} | {DNUM}) [eE][+-]? {LNUM})

Die Größe einer Gleitkommazahl ist plattformabhängig, ein Maximalwert von circa 1.8e308 mit einer Präzision von ungefähr 14 Dezimal-Nachkommastellen ist jedoch ein üblicher Wert (64-Bit IEEE-Format).

Warnung

# Genauigkeit von Gleitkommazahlen

Gleitkommazahlen haben eine begrenzte Präzision. Obgleich dies vom System abhängig ist, verwendet PHP üblicherweise das IEEE 754 Double Precision Format, welches einen maximalen relativen Rundungsfehler in einer Größenordnung en 1.11e-16 ergibt. Nicht-Elementare arithmetische Operationen können jedoch größere Fehler hervorrufen und natürlich muss eine Fortpflanzung des Fehlers berücksichtigt werden, wenn mehrere Operationen zusammengesetzt werden.

Außerdem gibt es rationale Zahlen, die zur Basis 10 als Gleitkommazahlen exakt dargestellt werden können, beispielsweise `0.1` oder `0.7`, für die es aber keine exakte Repräsentation als Gleitkommazahlen zur Basis 2 gibt, welche intern aber unabhängig von der Größe der Mantisse verwendet wird. Daher können sie nicht ohne einen geringen Präzisionsverlust in ihre interne binäre Darstellung umgewandelt werden. Dies kann zu verwirrenden Ergebnissen führen: `floor((0.1+0.7)*10)` wird üblicherweise `7` ergeben statt des erwarteten Ergebnisses von `8`, da die interne Repräsentation etwas ist wie `7.9999999999999991118...`.

Man sollte sich daher niemals bis zur letzten Nachkommastelle auf Gleitkommazahlen verlassen und Gleitkommazahlen niemals direkt auf Gleichheit prüfen. Wenn eine höhere Präzision notwendig ist, stehen die Mathematikfunktionen mit beliebiger Präzision und die gmp-Funktionen zur Verfügung.

Für eine "einfache" Erklärung steht der Ratgeber » Floating Point Guide zur Verfügung, welcher auch den Titel hat "Why don’t my numbers add up?"

### Umwandlung in float

#### Von Strings

Wenn der String numerisch ist oder numerisch beginnt, wird er in den entsprechenden Gleitkommawert umgewandelt, andernfalls wird er in Null (`0`) umgewandelt.

#### Von anderen Typen

Werte aller anderen Typen werden umgewandelt, indem die Werte zuerst in den Typ int umgewandelt werden und dieser anschließend zu float. Weitere Informationen findet man unter Umwandlung in Integer.

> Hinweis:

> Da bestimmte Typen ein undefiniertes Verhalten bei der Umwandlung in int haben, ist dies auch bei der Umwandlung in float der Fall.

### Gleitkommazahlen vergleichen

Wie in der obigen Warnung bereits dargestellt, ist es problematisch, Gleitkommazahlen auf Gleichheit zu überprüfen, aufgrund ihrer internen Darstellungsart. Es gibt allerdings Wege, diese Vergleiche von Gleitkommazahlen anzustellen, die diese Beschränkungen umgehen.

Um Gleitkommazahlen auf Gleichheit zu prüfen, wird eine obere Schranke für den Rundungsfehler verwendet. Dieser Wert ist bekannt als Maschinengenauigkeit Epsilon und stellt die kleinste annehmbare Differenz in der Berechnung dar.

$a und $b sind bis auf 5 Nachkommastellen gleich.

Beispiel #1 Vergleichen von Gleitkommazahlen

    <?php
    $a = 1.23456789;
    $b = 1.23456780;
    $epsilon = 0.00001;

    if (abs($a - $b) < $epsilon) {
        echo "true";
    }
    ?>

### NaN

Einige numerische Operationen können einen Wert ergeben, der durch die Konstante `NAN` dargestellt wird. Dieses Ergebnis stellt einen undefinierten oder nicht darstellbaren Wert in den Fließkommaberechnungen dar. Jeder strikte oder nicht strikte Vergleich dieses Werts mit jedem beliebigen anderen Wert, inklusive sich selbst, nur nicht `true`, wird ein Ergebnis von `false` hervorbringen.

Da `NAN` eine beliebige Anzahl von anderen Werten darstellen kann, sollte `NAN` nicht mit anderen Werten, einschließlich sich selbst, verglichen werden. Stattdessen sollte zur Prüfung is_nan() verwendet werden.

## Strings (Zeichenketten)

Ein String stellt eine Kette von Zeichen dar, in der ein Zeichen gleichbedeutend mit einem Byte ist. Das bedeutet, es gibt exakt 256 mögliche Zeichen. Es impliziert zudem, dass PHP keine native Unterstützung von Unicode bietet. Siehe auch Details zum String-Typ.

> Hinweis: Unter 32-bit-Versionen kann ein String bis zu 2GB (maximal 2147483647 Bytes) groß werden.

### Syntax

Ein String-Literal kann auf vier unterschiedliche Arten spezifiziert werden:

- einfache Anführungszeichen
- doppelte Anführungszeichen
- Heredoc-Syntax
- Nowdoc-Syntax

#### Einfache Anführungszeichen

Der einfachste Weg einen String anzugeben, ist ihn mit einfachen Anführungszeichen (das Zeichen `'`) zu umschließen.

Um ein einfaches Anführungszeichen hierin anzugeben, fügen sie einen Backslash (`\`) vor dem Zeichen ein. Um einen Backslash als Zeichen anzugeben, verdoppeln Sie ihn (`\\`). Alle anderen Instanzen von Backslash werden als buchstäblicher Backslash behandelt: Das bedeutet, dass die anderen Escape-Sequenzen, die Sie vielleicht gewohnt sind, wie `\r` oder `\n`, buchstäblich wie angegeben ausgegeben werden und keine besondere Bedeutung haben.

> Hinweis: Im Gegensatz zu den doppelten Anführungszeichen- und Heredoc-Notationen werden Variablen und Escape-Sequenzen für Sonderzeichen nicht aufgelöst (ersetzt), wenn sie in einem mit einfachen Anführungszeichen umschlossenen String erscheinen.

Beispiel #1 Syntax-Varianten

    <?php
    echo 'dies ist ein einfacher String', PHP_EOL;

    echo 'Sie können auch Zeilenumbrüche
    in dieser Art angeben,
    dies ist okay so', PHP_EOL;

    // Gibt aus: Arnold sagte einst: "I'll be back"
    echo 'Arnold sagte einst: "I\'ll be back"', PHP_EOL;

    // Ausgabe: Sie löschten C:\*.*?
    echo 'Sie löschten C:\\*.*?', PHP_EOL;

    // Ausgabe: Sie löschten C:\*.*?
    echo 'Sie löschten C:\*.*?', PHP_EOL;

    // Ausgabe: Dies erzeugt keinen: \n Zeilenumbruch
    echo 'Dies erzeugt keinen: \n Zeilenumbruch', PHP_EOL;

    // Ausgabe: Variablen werden $ebenfalls $nicht ersetzt
    echo 'Variablen werden $ebenfalls $nicht ersetzt', PHP_EOL;
    ?>

#### Doppelte Anführungszeichen

Wenn der String in doppelte Anführungszeichen (`"`) eingeschlossen wird, interpretiert PHP die folgenden Escape-Sequenzen für Sonderzeichen:

Maskierte Zeichen
Sequenz | Bedeutung
--- | ---
`\n` | Zeilenumbruch (LF or 0x0A (10) in ASCII)
`\r` | Wagenrücklauf (CR or 0x0D (13) in ASCII)
`\t` | horizontaler Tabulator (HT or 0x09 (9) in ASCII)
`\v` | vertikaler Tabulator (VT or 0x0B (11) in ASCII)
`\e` | Escape-Zeichen (ESC or 0x1B (27) in ASCII)
`\f` | Seitenvorschub (FF or 0x0C (12) in ASCII)
`\\` | Backslash (Rückstrich)
`\$` | Dollar-Zeichen
`\"` | doppeltes Anführungszeichen
`\[0-7]{1,3}` | Oktal: die Folge von Zeichen, die auf den regulären Ausdruck `[0-7]{1,3}` passt, ist ein Zeichen in oktaler Notation (z. B. `"\101" === "A"`), die stillschweigend überläuft, um in ein Byte zu passen (z. B. "\400" === "\000")
`\x[0-9A-Fa-f]{1,2}` | Hexadezimal: die Folge von Zeichen, die auf den regulären Ausdruck `[0-9A-Fa-f]{1,2}` passt, ist ein Zeichen in hexadezimaler Schreibweise (z. B. `"\x41" === "A"`)
`\u{[0-9A-Fa-f]+}` | Unicode: die Folge von Zeichen, die auf den regulären Ausdruck `[0-9A-Fa-f]+` passt, ist ein Unicode-Codepunkt, der in der Zeichenkette als UTF-8-Darstellung des Codepunkts ausgegeben wird. Die geschweiften Klammern in der Zeichenkette sind erforderlich (z. B. `"\u{41}" === "A"`)

Wie bei Strings in einfachen Anführungszeichen wird beim Maskieren aller anderen Zeichen der Backslash mit ausgegeben.

Das Auflösen von Variablen-Namen ist eine der wichtigsten Besonderheiten von in doppelten Anführungszeichen angegebenen Strings. Siehe hierzu String-Interpolation für weitere Details.

#### Heredoc

Eine dritte Möglichkeit, Strings zu begrenzen, stellt die Heredoc-Syntax dar: `<<<`. Nach diesem Operator wird ein beliebiger Bezeichner angegeben, dann eine neue Zeile. Hiernach folgt der eigentliche String und abschließend erneut der Bezeichner, um die Auszeichnung abzuschließen.

Der schließende Bezeichner darf durch Leerzeichen oder Tabulatoren eingerückt sein, wobei in diesem Fall die Einrückung aus allen Zeilen des Doc-Strings entfernt wird. Vor PHP 7.3.0 muss der schließende Bezeichner in der ersten Spalte der Zeile beginnen.

Außerdem muss der schließende Bezeichner den gleichen Benennungsregeln folgen wie jeder andere Bezeichner in PHP: Er darf nur alphanumerische Zeichen sowie Unterstriche enthalten und muss mit einem nicht-numerischen Zeichen oder einem Unterstrich beginnen.

Beispiel #2 Grundlegendes Heredoc-Beispiel ab PHP 7.3.0

    <?php
    // keine Einrückung
    echo <<<END
          a
         b
        c
    \n
    END;

    // vier Leerzeichen Einrückung
    echo <<<END
          a
         b
        c
        END;

Das oben gezeigte Beispiel erzeugt mit PHP 7.3 folgende Ausgabe:

          a
         b
        c

      a
     b
    c

Wenn der schließende Bezeichner weiter eingerückt ist als alle Zeilen des Textkörpers, wird ein ParseError ausgelöst:

Beispiel #3 Der schließende Bezeichner darf nicht weiter eingerückt sein, als die Zeilen des Textkörpers

    <?php
    echo <<<END
      a
     b
    c
       END;

Das oben gezeigte Beispiel erzeugt mit PHP 7.3 folgende Ausgabe:

    Parse error: Invalid body indentation level (expecting an indentation level of at least 3) in example.php on line 4

Wenn der schließende Bezeichner eingerückt ist, können auch Tabulatoren verwendet werden, allerdings dürfen Tabulatoren und Leerzeichen in Bezug auf die Einrückung des schließenden Bezeichners und die Einrückung des Textkörpers (bis zum schließenden Bezeichner) nicht miteinander vermischt werden. In jedem dieser Fälle wird ein ParseError ausgelöst. Diese Whitespace-Einschränkungen wurden aufgenommen, weil die Vermischung von Tabulatoren und Leerzeichen für die Einrückung die Lesbarkeit beeinträchtigt.

Beispiel #4 Unterschiedliche Einrückung für den Bezeichner, der den Textkörper (Leerzeichen) schließt

    <?php
    // Der gesamte folgende Code funktioniert nicht.

    // Unterschiedliche Einrückung für den Bezeichner (Tabulatoren), der den
    // Textkörper (Leerzeichen) schließt
    {
        echo <<<END
         a
            END;
    }

    // Vermischung von Leerzeichen und Tabulatoren im Textkörper
    {
        echo <<<END
            a
         END;
    }

    // Vermischung von Leerzeichen und Tabulatoren in der Endmarkierung
    {
        echo <<<END
              a
             END;
    }

Das oben gezeigte Beispiel erzeugt mit PHP 7.3 folgende Ausgabe:

    Parse error: Invalid indentation - tabs and spaces cannot be mixed in example.php line 8

Der schließende Bezeichner für den Textkörper muss nicht von einem Semikolon oder Zeilenumbruch gefolgt werden. Zum Beispiel ist der folgende Code ist ab PHP 7.3.0 erlaubt:

Beispiel #5 Fortsetzen eines Ausdrucks nach einem schließenden Bezeichner

    <?php
    $values = [<<<END
    a
      b
        c
    END, 'd e f'];
    var_dump($values);

Das oben gezeigte Beispiel erzeugt mit PHP 7.3 folgende Ausgabe:

    array(2) {
      [0] =>
      string(11) "a
      b
        c"
      [1] =>
      string(5) "d e f"
    }

Warnung

Wenn der schließende Bezeichner am Anfang einer Zeile gefunden wurde, dann kann er unabhängig davon, ob er Teil eines anderen Wortes war, als schließender Bezeichner betrachtet werden und führt zu einem ParseError.

Beispiel #6 Ein schließender Bezeichner im Textkörper der Zeichenkette führt zu einem ParseError

    <?php
    $values = [<<<END
    a
    b
    END ING
    END, 'd e f'];

Das oben gezeigte Beispiel erzeugt mit PHP 7.3 folgende Ausgabe:

    Parse error: syntax error, unexpected identifier "ING", expecting "]" in example.php on line 5

Um dieses Problem zu vermeiden, ist es ratsam, die einfache Regel zu befolgen: keines der im Textkörper vorkommenden Wörter als schließenden Bezeichner wählen.

Warnung

Vor PHP 7.3.0 ist es sehr wichtig, darauf zu achten, dass die Zeile mit dem schließenden Bezeichner keine anderen Zeichen außer einem Semikolon (`;`) enthalten darf. Das heißt insbesondere auch, dass der Bezeichner nicht eingerückt werden darf und dass es vor oder nach dem Semikolon auch keine Leerzeichen oder Tabulatoren geben darf. Zudem muss das erste Zeichen vor dem schließenden Bezeichner ein Zeilenumbruch sein, so wie er vom Betriebssystem definiert wird. In UNIX-Systemen, inlusive macOS, ist dies `\n`. Auf den schließenden Bezeichner muss ebenfalls ein Zeilenumbruch folgen.

Wenn diese Regel gebrochen wird und der schließende Bezeichner nicht valide ist, wird er nicht als Bezeichner angenommen und PHP wird weiter nach einem solchen schließenden Bezeichner suchen. Wird kein gültiger schließender Bezeichner vor dem Dateiende gefunden, gibt PHP einen auf die letzte Zeile der Datei weisenden Parser-Fehler aus.

Beispiel #7 Ungültiges Beispiel vor PHP 7.3.0

    <?php
    class foo {
        public $bar = <<<EOT
    bar
        EOT;
    }
    // Identifier must not be indented
    ?>

Beispiel #8 Gültiges Beispiel, auch vor PHP 7.3.0

    <?php
    class foo {
        public $bar = <<<EOT
    bar
    EOT;
    }
    ?>

Heredocs, die Variablen enthalten, können nicht für die Initialisierung von Klasseneigenschaften verwendet werden.

Heredoc-Text verhält sich genau wie ein String in doppelten Anführungsstrichen, ohne die doppelten Anführungszeichen. Das bedeutet, dass Anführungszeichen in einem Heredoc nicht maskiert werden müssen, aber die oben aufgeführten Maskierungscodes können trotzdem verwendet werden. Variablen werden aufgelöst, aber wenn komplexe Variablen innerhalb eines Heredocs verwendet werden, ist die gleiche Vorsicht geboten wie bei Strings.

Beispiel #9 Beispiel für das Notieren von Heredoc-Strings

    <?php
    $str = <<<EOD
    Ein Beispiel für einen String, der sich
    unter Verwendung der heredoc-Syntax
    über mehrere Zeilen erstreckt.
    EOD;

    /* Ein komplexeres Beispiel mit Variablen. */
    class foo
    {
        var $foo;
        var $bar;

        function __construct()
        {
            $this->foo = 'Foo';
            $this->bar = array('Bar1', 'Bar2', 'Bar3');
        }
    }

    $foo = new foo();
    $name = 'MeinName';

    echo <<<EOT
    Mein Name ist "$name". Ich gebe etwas $foo->foo aus.
    Jetzt gebe ich etwas {$foo->bar[1]} aus.
    Dies sollte ein großes 'A' ausgeben: \x41
    EOT;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Mein Name ist "MeinName". Ich gebe etwas Foo aus.
    Jetzt gebe ich etwas Bar2 aus.
    Dies sollte ein großes 'A' ausgeben: A

Es ist auch möglich, die Heredoc-Syntax zu verwenden, um Daten an Funktionsargumente zu übergeben:

Beispiel #10 Beispiel für Heredoc in Argumenten

    <?php
    var_dump(array(<<<EOD
    foobar!
    EOD
    ));
    ?>

Es ist möglich, statische Variablen und Klasseneigenschaften/Konstanten mit Hilfe der Heredoc-Syntax zu initialisieren:

Beispiel #11 Verwendung von Heredoc zur Initialisierung von statischen Werten

    <?php
    // Statische Variablen
    function foo()
    {
        static $bar = <<<LABEL
    Hier steht nichts drin...
    LABEL;
    }

    // Klasseneigenschaften/Konstanten
    class foo
    {
        const BAR = <<<FOOBAR
    Beispiel für eine Konstante
    FOOBAR;

        public $baz = <<<FOOBAR
    Beispiel für eine Eigenschaft
    FOOBAR;
    }
    ?>

Der öffnende Heredoc-Bezeichner kann optional in doppelte Anführungszeichen gesetzt werden:

Beispiel #12 Verwendung von doppelten Anführungszeichen in Heredoc

    <?php
    echo <<<"FOOBAR"
    Hallo Welt!
    FOOBAR;
    ?>

#### Nowdoc

Nowdocs sind für Strings in einfachen Anführungszeichen das, was Heredocs für Strings in doppelten Anführungszeichen sind. Ein Nowdoc wird ähnlich wie ein Heredoc angegeben, aber innerhalb eines Nowdocs wird keine String-Interpolation durchgeführt. Das Konstrukt ist ideal für die Einbettung von PHP-Code oder anderen großen Textblöcken ohne maskieren zu müssen. Es hat einige Eigenschaften mit dem `<![CDATA[ ]]>`-Konstrukt in SGML gemeinsam, indem es einen Textblock deklariert, der nicht geparst werden soll.

Ein Nowdoc wird mit der gleichen `<<<`-Sequenz identifiziert, die für Heredocs verwendet wird, aber der nachfolgende Bezeichner wird in einfachen Anführungszeichen eingeschlossen, z. B. `<<<'EOT'`. Alle Regeln für Heredoc-Bezeichner gelten auch für Nowdoc-Bezeichner, insbesondere die hinsichtlich des Aussehens des schließenden Bezeichners.

Beispiel #13 Nowdoc-Beispiel für das Notieren von Strings

    <?php
    echo <<<'EOD'
    Ein Beispiel für einen String, der sich über mehrere Zeilen erstreckt
    unter Verwendung der Nowdoc-Syntax. Backslashes werden immer als
    Buchstaben behandelt,
    z. B. \\ und \'.
    EOD;

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ein Beispiel für einen String, der sich über mehrere Zeilen erstreckt
    unter Verwendung der Nowdoc-Syntax. Backslashes werden immer als
    Buchstaben behandelt,
    z. B. \\ und \'.

Beispiel #14 Nowdoc Beispiel für Strings mit Variablen

    <?php
    class foo
    {
        public $foo;
        public $bar;

        function __construct()
        {
            $this->foo = 'Foo';
            $this->bar = array('Bar1', 'Bar2', 'Bar3');
        }
    }

    $foo = new foo();
    $name = 'MeinName';

    echo <<<'EOT'
    Mein Name ist "$name". Ich gebe etwas $foo->foo aus.
    Jetzt gebe ich etwas {$foo->bar[1]} aus.
    Dies sollte ein großes 'A' ausgeben: \x41
    EOT;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Mein Name ist "$name". Ich gebe etwas $foo->foo aus.
    Jetzt gebe ich etwas {$foo->bar[1]} aus.
    Dies sollte ein großes 'A' ausgeben: \x41

Beispiel #15 Beispiel für statische Daten

    <?php
    class foo {
        public $bar = <<<'EOT'
    bar
    EOT;
    }
    ?>

#### String-Interpolation

Wenn ein string in doppelten Anführungszeichen oder mit Heredoc angegeben wird, können die Variablen darin ersetzt werden.

Es gibt zwei Arten von Syntax: eine einfache und eine erweiterte. Die einfache Syntax ist die gebräuchlichste und bequemste. Sie bietet eine Möglichkeit, eine Variable, einen Array-Wert oder eine Objekt-Eigenschaft mit minimalem Aufwand in einen String einzubetten.

Die komplexe Syntax erkennt man an den geschweifte Klammern, die den Ausdruck umgeben.

##### Einfache Syntax

Wenn ein Dollarzeichen (`$`) erkannt wird, werden die darauf folgenden Zeichen, die in einem Variablennamen verwendet werden können, als solche interpretiert und ersetzt.

Beispiel #16 String-Interpolation

    <?php
    $juice = "apple";

    echo "He drank some $juice juice." . PHP_EOL;

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    He drank some apple juice.

Formal ist die Struktur für die grundlegende Syntax der Ersetzung von Variablen wie folgt:

    String-Variable::
         Variablen-Name   (Offset-oder-Eigenschaft)?
       | ${   Ausdruck   }

    Offset-oder-Eigenschaft::
         Offset-im-String
       | Eigenschaft-im-String

    Offset-im-String::
         [   Name    ]
       | [   Variablen-Name   ]
       | [   Ganzzahl-Literal   ]

    Eigenschaft-im-String::
         ->  Name

    Variablen-Name::
         $   Name

    Name::
         [a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*

Warnung

Die Syntax `${ expression }` ist seit PHP 8.2.0 veraltet, da sie als variable Variable interpretiert werden kann:

    <?php
    const foo = 'bar';
    $foo = 'foo';
    $bar = 'bar';
    var_dump("${foo}");
    var_dump("${(foo)}");
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.2 folgende Ausgabe:

    Deprecated: Using ${var} in strings is deprecated, use {$var} instead in file on line 6

    Deprecated: Using ${expr} (variable variables) in strings is deprecated, use {${expr}} instead in file on line 9
    string(3) "foo"
    string(3) "bar"

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "foo"
    string(3) "bar"

Stattdessen sollte die erweiterte Syntax der String-Interpolation verwendet werden.

> Hinweis: Wenn es nicht möglich ist, einen gültigen Namen zu bilden, bleibt das Dollarzeichen unverändert im String erhalten:

>     <?php
>     echo "Für $ wurde keine Interpolation durchgeführt\n";
>     echo "Für $\n wurde keine Interpolation durchgeführt\n";
>     echo "Für $2 wurde keine Interpolation durchgeführt\n";
>     ?>

> Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

>     Für $ wurde keine Interpolation durchgeführt
>     Für $
>      wurde keine Interpolation durchgeführt
>     Für $2 wurde keine Interpolation durchgeführt

Beispiel #17 Interpolieren des Wertes der ersten Dimension eines Arrays oder einer Eigenschaft

    <?php
    $juices = array("apple", "orange", "string_key" => "purple");

    echo "He drank some $juices[0] juice.";
    echo PHP_EOL;
    echo "He drank some $juices[1] juice.";
    echo PHP_EOL;
    echo "He drank some $juices[string_key] juice.";
    echo PHP_EOL;

    class A {
        public $s = "string";
    }

    $o = new A();

    echo "Wert des Objekts: $o->s.";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    He drank some apple juice.
    He drank some orange juice.
    He drank some purple juice.
    Wert des Objekts: string.

> Hinweis: Der Array-Schlüssel muss nicht in Anführungszeichen gesetzt werden, daher ist es nicht möglich, mit der einfachen Syntax auf eine Konstante als Schlüssel zu verweisen. Verwenden Sie stattdessen die erweiterte Syntax.

Seit PHP 7.1.0 werden auch negative numerische Indizes unterstützt.

Beispiel #18 Negative numerische Indizes

    <?php
    $string = 'string';
    echo "Das Zeichen an Index -2 ist $string[-2].", PHP_EOL;
    $string[-3] = 'o';
    echo "Die Änderung des Zeichens an Index -3 auf o ergibt $string.", PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Das Zeichen an Index -2 ist n.
    Die Änderung des Zeichens an Index -3 auf o ergibt strong.

Für alles, das komplexer ist, muss die erweiterte Syntax verwendet werden.

##### Erweiterte (geschweifte) Syntax

Die erweiterte Syntax ermöglicht die Interpolation von Variablen mit beliebigen Zugriffsmethoden.

Jede skalare Variable, jedes Array-Element oder jede Objekteigenschaft (static oder nicht) mit einer String-Darstellung kann über diese Syntax eingebunden werden. Der Ausdruck wird so geschrieben, wie er auch außerhalb des Strings erscheinen würde, und dann von `{` und `}` umschlossen. Da `{` nicht maskiert werden kann, wird diese Syntax nur erkannt werden, wenn das `$` unmittelbar auf das `{` folgt. Verwenden Sie `{\$`, um ein wörtliches `{$` zu erhalten. Einige Beispiele, um es zu verdeutlichen:

Beispiel #19 Syntax mit geschweiften Klammern

    <?php
    const DATA_KEY = 'const-key';
    $great = 'fantastisch';
    $arr = [
        '1',
        '2',
        '3',
        [41, 42, 43],
        'key' => 'Indexierter Wert',
        'const-key' => 'Schlüssel mit Minuszeichen',
        'foo' => ['foo1', 'foo2', 'foo3']
    ];

    // Funktioniert nicht, Ausgabe: Das ist { fantastisch}
    echo "Das ist { $great}";

    // Funktioniert, Ausgabe: Das ist fantastisch
    echo "Das ist {$great}";

    class Square {
        public $width;

        public function __construct(int $width) { $this->width = $width; }
    }

    $square = new Square(5);

    // Funktioniert
    echo "Dieses Quadrat ist {$square->width}00 Zentimeter breit.";

    // Funktioniert, Anführungszeichen funktionieren nur mit der
    // Syntax der geschweiften Klammer
    echo "Das funktioniert: {$arr['key']}";

    // Funktioniert
    echo "Das funktioniert: {$arr[3][2]}";

    echo "Das funktioniert: {$arr[DATA_KEY]}";

    // Verwenden Sie bei mehrdimensionalen Arrays immer geschweifte Klammern
    // um die Arrays, wenn diese innerhalb von Strings stehen
    echo "Das funktioniert: {$arr['foo'][2]}";

    echo "Das funktioniert: {$obj->values[3]->name}";

    echo "Das funktioniert: {$obj->$staticProp}";

    // Funktioniert nicht, Ausgabe: C:\directory\{fantastisch}.txt
    echo "C:\directory\{$great}.txt";

    // Funktioniert, Ausgabe: C:\folder\fantastisch.txt
    echo "C:\\directory\\{$great}.txt";
    ?>

> Hinweis: Da diese Syntax beliebige Ausdrücke erlaubt, ist es möglich, variable Variablen innerhalb der erweiterten Syntax zu verwenden.

#### Zugriff auf Strings und Änderung von Zeichen

Auf ein Zeichen in einem String kann zugegriffen und es kann geändert werden, indem seine Position (von 0 an) hinter dem String mit Hilfe von Array-Klammern angegeben wird, z. B. $str[42]. In diesem Fall ist es hilfreich, sich einen String als ein Array von Zeichen vorzustellen. Die Funktionen substr() und substr_replace() können verwendet werden, wenn mehr als ein Zeichen extrahiert oder ersetzt werden soll.

> Hinweis: Seit PHP 7.1.0 werden auch negative String-Offsets unterstützt. Diese geben den Offset vom Ende des Strings an. Früher verursachten negative Offsets beim Lesen eine `E_NOTICE`-Meldung aus (was einen leeren String ergibt) und beim Schreiben eine `E_WARNING`-Meldung (was den String unangetastet lässt).

> Hinweis: Vor PHP 8.0.0 konnte für den gleichen Zweck auch mit Klammern auf Strings zugegriffen werden, wie in $str{42}. Diese Syntax mit geschweiften Klammern ist seit PHP 7.4.0 veraltet und wird seit PHP 8.0.0 nicht mehr unterstützt.

Warnung

Das Schreiben an einen Offset außerhalb des vorhandenen Bereichs bewirkt, dass der String bis zu dieser Position mit Leerzeichen aufgefüllt wird. Nicht-ganzzahlige Offsets werden in einen ganzzahligen Wert umgewandelt. Bei ungültigen Offset-Typen wird eine `E_WARNING` ausgegeben. Nur das erste Zeichen eines zugewiesenen Strings wird verwendet. Seit PHP 7.1.0 führt die Zuweisung eines leeren Strings zu einem schwerwiegenden Fehler. Vorher wurde ein NULL-Byte zugewiesen.

Warnung

Intern sind PHP-Strings Byte-Arrays. Folglich ist der Zugriff auf einen String oder dessen Änderung mit Array-Klammern nicht Multi-Byte-sicher und sollte nur mit Strings erfolgen, die in einer Ein-Byte-Kodierung wie ISO-8859-1 vorliegen.

> Hinweis: Seit PHP 7.1.0 führt die Anwendung des leeren Indexoperators auf einen leeren String zu einem fatalen Fehler. Zuvor wurde der leere String stillschweigend in ein Array umgewandelt.

Beispiel #20 Einige String-Beispiele

    <?php
    // Ermitteln des ersten Zeichens eines Strings.
    $str = 'Das ist ein Test.';
    $first = $str[0];
    var_dump($first);

    // Ermitteln des dritten Zeichens eines Strings.
    $third = $str[2];
    var_dump($third);

    // Ermitteln das letzten Zeichens eines Strings.
    $str = 'Das ist immer noch ein Test.';
    $last = $str[strlen($str)-1];
    var_dump($last);

    // Ändern des letzten Zeichens eines Strings.
    $str = 'Look at the sea';
    $str[strlen($str)-1] = 'e';
    var_dump($str);
    ?>

String-Offsets müssen entweder Integer oder Integer-ähnliche Strings sein, andernfalls wird eine Warnung ausgelöst.

Beispiel #21 Beispiel für unzulässige String-Offsets

    <?php
    $str = 'abc';

    $keys = [ '1', '1.0', 'x', '1x' ];

    foreach ($keys as $keyToTry) {
        var_dump(isset($str[$keyToTry]));

        try {
            var_dump($str[$keyToTry]);
        } catch (TypeError $e) {
            echo $e->getMessage(), PHP_EOL;
        }

        echo PHP_EOL;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    string(1) "b"

    bool(false)
    Cannot access offset of type string on string

    bool(false)
    Cannot access offset of type string on string

    bool(false)

    Warning: Illegal string offset "1x" in Standard input code on line 10
    string(1) "b"

> Hinweis:

> Der Zugriff auf Variablen anderer Typen (ohne Arrays oder Objekte, die entsprechende Schnittstellen implementieren) mit `[]` oder `{}` gibt stillschweigend `null` zurück.

> Hinweis:

> Auf Zeichen innerhalb von String-Literalen kann mit `[]` oder `{}` zugegriffen werden.

> Hinweis:

> Der Zugriff auf Zeichen innerhalb von String-Literalen mit der `{}`-Syntax ist seit PHP 7.4 veraltet und wurde in PHP 8.0 entfernt.

### Nützliche Funktionen und Operatoren

Strings können mit dem Punkt-Operator '.' verkettet werden. Es ist zu beachten, dass der Additions-Operator '+' in diesem Fall nicht funktioniert. Siehe String-Operatoren für mehr Informationen.

Es gibt eine Reihe nützlicher Funktionen für die String-Manipulation.

Siehe den Abschnitt String-Funktionen für allgemeine Funktionen und die Funktionen für Perl-kompatible reguläre Ausdrücke für erweiterte Funktionen zum Suchen und Ersetzen.

Außerdem gibt es Funktionen für URL-Strings und Funktionen zum Verschlüsseln/Entschlüsseln von Strings (Sodium und Hash).

Siehe zudem auch die Zeichentyp-Funktionen.

### Umwandlung in String

Ein Wert kann mit dem Schlüsselwort `(string)` oder der Funktion strval() in einen String umgewandelt werden. Die Umwandlung in einen String erfolgt automatisch im Kontext eines Ausdrucks, in dem ein String erforderlich ist. Dies geschieht z. B. bei der Verwendung der Funktionen echo oder print oder wenn eine Variable mit einem String verglichen wird. In den Abschnitten über Typen und Typ-Manipulationen werden die folgenden Punkte näher erläutert. Siehe auch die Funktion settype().

Ein bool `true` -Wert wird in den String `"1"` umgewandelt. bool `false` wird in `""` (den leeren String) umgewandelt. Dies ermöglicht es, zwischen bool- und String-Werten hin und her zu konvertieren.

Ein Int oder Float wird in einen String umgewandelt, der die Zahl textuell darstellt (einschließlich des Exponententeil bei Floats). Gleitkommazahlen können mit der Exponentialschreibweise umgewandelt werden (`4.1E+6`).

> Hinweis:

> Seit PHP 8.0.0 ist das Dezimalpunktzeichen immer ein Punkt ("`.`"). Vor PHP 8.0.0 wird das Dezimalpunktzeichen in der Locale des Skripts definiert (Kategorie LC_NUMERIC). Siehe die Funktion setlocale().

Arrays werden immer in String-`"Arrays"` umgewandelt; aus diesem Grund können echo und print nicht von sich aus den Inhalt eines Arrays anzeigen. Um ein einzelnes Element anzuzeigen, verwendet man eine Konstruktion wie `echo $arr['foo']`. Siehe unten für Tipps zur Anzeige des gesamten Inhalts.

Um Objekte in Strings umzuwandeln, muss die magische Methode __toString verwendet werden.

Ressourcen werden immer mit der Struktur `"Resource id #1"` in Strings umgewandelt, wobei `1` die Ressourcennummer ist, die der Ressource von PHP zur Laufzeit zugewiesen wird. Obwohl man sich nicht auf die genaue Struktur dieses Strings verlassen sollte und sie sich ändern kann, wird sie für eine bestimmte Ressource innerhalb der Lebensdauer eines ausgeführten Skripts (d. h. einer Web-Anfrage oder eines CLI-Prozesses) immer eindeutig sein und wird nicht wiederverwendet. Um den Typ einer Ressource zu erhalten, kann die Funktion get_resource_type() verwendet werden.

`null` wird immer in einen leeren String umgewandelt.

Wie oben erwähnt, liefert die direkte Umwandlung eines Arrays, Objekts oder einer Ressource in einen String keine nützlichen Informationen über den Wert, die über seinen Typ hinausgehen. Um den Inhalt dieser Typen zu ermitteln, siehe die Funktionen print_r() und var_dump().

Die meisten PHP-Werte können zur dauerhaften Speicherung auch in Strings umgewandelt werden. Diese Methode wird Serialisierung genannt und wird von der Funktion serialize() durchgeführt.

### Details zum String-Typ

Der Typ string ist in PHP als ein Array von Bytes und einem Integer, der die Länge des Puffers angibt, implementiert. Er hat keine Informationen darüber, wie diese Bytes in Zeichen umgewandelt werden; diese Aufgabe wird dem Programmierer überlassen. Es gibt keine Beschränkungen für die Werte, aus denen der String bestehen kann; insbesondere Insbesondere sind Bytes mit dem Wert `0` ("NUL-Bytes") in der Zeichenkette erlaubt (allerdings können einige Funktionen, die in diesem Handbuch als nicht "binärsicher" eingestuft werden, die Strings an Bibliotheken weitergeben, die Daten nach einem NUL-Byte ignorieren).

Diese Eigenschaft des String-Typs erklärt, warum es in PHP keinen separaten "Byte"-Typ gibt - Strings übernehmen diese Rolle. Funktionen, die keine textuellen Daten zurückgeben - zum Beispiel beliebige Daten, die von einem Netzwerksocket gelesen werden - geben immer noch Strings zurück.

Da PHP keine spezifische Kodierung für Strings vorschreibt, könnte man sich fragen, wie String-Literale kodiert werden. Ist zum Beispiel der String `"á"` äquivalent zu `"\xE1"` (ISO-8859-1), `"\xC3\xA1"` (UTF-8, C-Form), `"\x61\xCC\x81"` (UTF-8, D-Form) oder zu irgendeiner anderen möglichen Darstellung? Die Antwort lautet, dass der String auf die Art und Weise kodiert wird, wie er in der Skriptdatei kodiert ist. Wenn das Skript also in ISO-8859-1 geschrieben ist, wird die Zeichenkette in ISO-8859-1 kodiert und so weiter. Das gilt jedoch nicht, wenn Zend-Multibyte aktiviert ist; in diesem Fall kann das Skript in einer beliebigen Kodierung geschrieben werden (die explizit deklariert ist oder erkannt wird) und dann in eine bestimmte interne Kodierung konvertiert werden, welche dann die Kodierung ist, die für die String-Literale verwendet wird. Es ist zu beachten, dass es einige Beschränkungen für die Kodierung des Skripts gibt (oder für die interne Kodierung gibt, sollte Zend-Multibyte aktiviert sein) - das bedeutet fast immer, dass diese Kodierung eine kompatible Obermenge von ASCII sein sollte, wie z. B. UTF-8 oder ISO-8859-1. Es ist jedoch zu beachten, dass zustandsabhängige Kodierungen, bei denen dieselben Byte-Werte sowohl im Anfangszustand als auch im Nicht-Anfangszustand verwendet werden können, problematisch sein können.

Um nützlich zu sein, müssen Funktionen, die mit Text arbeiten, natürlich Annahmen darüber treffen, wie der String kodiert ist. Leider gibt es in diesem Punkt viele Unterschiede zwischen den PHP-Funktionen:

- Einige Funktionen gehen davon aus, dass der String in einer (beliebigen) Ein-Byte-Kodierung kodiert ist, aber sie müssen diese Bytes nicht als bestimmte Zeichen interpretieren. Dies ist z. B. der Fall bei substr(), strpos(), strlen() oder strcmp(). Eine andere Möglichkeit, sich diese Funktionen vorzustellen, ist, dass sie mit Speicherpuffern arbeiten, d. h. sie arbeiten mit Bytes und Byte-Offsets.
- Anderen Funktionen wird die Kodierung des Strings übergeben, eventuell nehmen sie auch einen Standardwert an, wenn keine solche Information angegeben wird. Dies ist der Fall bei htmlentities() und den meisten der Funktionen in der mbstring-Erweiterung.
- Andere verwenden die aktuelle Locale (siehe setlocale()), arbeiten aber Byte für Byte.
- Letztendlich können sie einfach davon ausgehen, dass der String eine bestimmte Kodierung verwendet, normalerweise UTF-8. Dies ist der Fall bei den meisten Funktionen in der intl-Erweiterung und in der PCRE-Erweiterung (im letzteren Fall nur, wenn der Modifikator `u` verwendet wird).

Letztlich bedeutet dies, dass das Schreiben korrekter Programme mit Unicode davon abhängt, Funktionen, die nicht funktionieren und die Daten höchstwahrscheinlich beschädigen, sorgfältig zu vermeiden und stattdessen die Funktionen zu verwenden, die sich korrekt verhalten. Im Allgemeinen sind das die Funktionen der intl- und mbstring-Erweiterungen. Die Verwendung von Funktionen, die Unicode-Kodierungen verarbeiten können, ist jedoch nur der Anfang. Unabhängig von den Funktionen, die die Sprache zur Verfügung stellt, ist es wichtig, die Unicode-Spezifikation zu kennen. Ein Programm, das zum Beispiel davon ausgeht, dass es nur Groß- und Kleinbuchstaben gibt, geht von einer falschen Annahme aus.

## Numerische Zeichenketten

In PHP gilt eine Zeichenkette (Typ string) als numerisch, wenn er als Ganzzahl (int) oder Gleitkommazahl (float) interpretiert werden kann.

Formal seit PHP 8.0.0:

    WHITESPACES      \s*
    LNUM             [0-9]+
    DNUM             ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
    EXPONENT_DNUM    (({LNUM} | {DNUM}) [eE][+-]? {LNUM})
    INT_NUM_STRING   {WHITESPACES} [+-]? {LNUM} {WHITESPACES}
    FLOAT_NUM_STRING {WHITESPACES} [+-]? ({DNUM} | {EXPONENT_DNUM}) {WHITESPACES}
    NUM_STRING       ({INT_NUM_STRING} | {FLOAT_NUM_STRING})

In PHP gibt es auch das Konzept der vorangestellten numerischen Zeichenkette. Dies ist einfach eine Zeichenkette, die wie eine numerische Zeichenkette beginnt, auf die beliebige Zeichen folgen.

> Hinweis:

> Jede Zeichenkette, die den Buchstaben `E` (Groß- und Kleinschreibung wird nicht berücksichtigt) enthält, wird als Zahl in wissenschaftlicher Notation betrachtet. Dies kann zu unerwarteten Ergebnissen führen.

> Beispiel #1 Vergleich wissenschaftlicher Schreibweisen

>     <?php
>     var_dump("0D1" == "000"); // false, "0D1" ist keine wissenschaftliche Schreibweise
>     var_dump("0E1" == "000"); // true, "0E1" ist 0 * (10 ^ 1) also 0
>     var_dump("2E1" == "020"); // true, "2E1" ist 2 * (10 ^ 1) also 20
>     ?>

### Zeichenketten, die im numerischen Kontext verwendet werden

Wenn ein Wert vom Typ string als Zahl ausgewertet werden muss (z. B. arithmetische Operationen, Deklaration des Typs int usw.), werden die folgenden Schritte durchgeführt, um das Ergebnis zu ermitteln:

1. Wenn der String numerisch ist, wird er in einen Int aufgelöst, sofern er eine ganzzahlige numerische Zeichenkette ist und gemäß der Definition von `PHP_INT_MAX` innerhalb der Grenzen des Typs int liegt, ansonsten wird er in einen Float aufgelöst.
2. Wenn der Kontext vorangestellte numerische Zeichenketten erlaubt und der String eine solche ist, wird in einen Int aufgelöst, sofern der vorangestellte Teil des Strings eine ganzzahlige numerische Zeichenkette ist und gemäß der Definition von `PHP_INT_MAX` innerhalb der Grenzen des Typs int liegt, ansonsten wird in einen Float aufgelöst. Darüber hinaus wird ein Fehler der Stufe `E_WARNING` ausgelöst.
3. Wenn der String nicht numerisch ist, wird eine TypeError-Exception geworfen.

### Verhalten vor PHP 8.0.0

Vor PHP 8.0.0 galt ein String nur dann als numerisch, wenn er ein vorangestelltes Leerzeichen enthielt. Wenn er ein nachgestelltes Leerzeichen enthielt, wurde er als vorangestellt numerisch betrachtet.

Wenn vor PHP 8.0.0 eine Zeichenkette in einem numerischen Kontext verwendet wurde, wurden die gleichen Schritte wie oben beschrieben durchgeführt, mit den folgenden Unterschieden:

- Bei Verwendung einer führenden numerischen Zeichenkette wurde ein `E_NOTICE` anstelle eines `E_WARNING` ausgelöst.
- Wenn die Zeichenkette nicht numerisch war, wurde ein `E_WARNING` ausgelöst und der Wert `0` zurückgegeben.

Vor PHP 7.1.0 wurde weder `E_NOTICE` noch `E_WARNING` ausgelöst.

    <?php
    $foo = 1 + "10.5";                // $foo ist vom Typ float (11.5)
    $foo = 1 + "-1.3e3";              // $foo ist vom Typ float (-1299)
    $foo = 1 + "bob-1.3e3";           // TypeError seit PHP 8.0.0; davor ist $foo vom Typ integer (1)
    $foo = 1 + "bob3";                // TypeError seit PHP 8.0.0; davor ist $foo vom Typ integer (1)
    $foo = 1 + "10 Small Pigs";       // $foo ist vom Typ integer (11) und in PHP 8.0.0 wird ein E_WARNING ausgelöst; davor E_NOTICE
    $foo = 4 + "10.2 Little Piggies"; // $foo ist vom Typ float (14.2) und in PHP 8.0.0 wird ein E_WARNING ausgelöst; davor E_NOTICE
    $foo = "10.0 pigs " + 1;          // $foo ist vom Typ float (11) und in PHP 8.0.0 wird ein E_WARNING ausgelöst; davor E_NOTICE
    $foo = "10.0 pigs " + 1.0;        // $foo ist vom Typ float (11) und in PHP 8.0.0 wird ein E_WARNING ausgelöst; davor E_NOTICE
    ?>

## Arrays

Eine Liste aller Array-Funktionen findet sich im Kapitel Array-Funktionen der Dokumentation.

Ein Array ist in PHP in Wirklichkeit eine geordnete Map (Abbildung). Eine Map ist ein Typ, der Werte zu Schlüsseln zuordnet. Dieser Typ ist für einige verschiedene Nutzungsarten optimiert. Er kann als ein Array verwendet werden, als Liste (Vektor), Hash-Tabelle (eine Implementierung einer Map), Wörterbuch, Sammlung, Stack, Queue (Warteschlange) und wahrscheinlich noch als vieles anderes. Da ein Wert eines Arrays ein weiteres Array sein kann, sind auch Bäume und mehrdimensionale Arrays möglich.

Die Erläuterung dieser Datenstrukturen liegt nicht im Rahmen dieses Handbuchs, aber wenigstens ein Beispiel für jede ist hier angegeben. Um weitere Informationen zu erhalten wird auf die immense Literatur zu diesem weiten Feld verwiesen.

### Syntax

#### Spezifizierung mittels array()

Ein Array kann durch das Sprachkonstrukt array() erzeugt werden. Dies nimmt eine beliebige Anzahl kommaseparierter `Schlüssel => Wert`-Paare als Parameter entgegen.

    array(
        Schlüssel  => Wert,
        Schlüssel2 => Wert2,
        Schlüssel3 => Wert3,
        ...
    )

Das Komma nach dem letzten Array-Element ist optional und kann weggelassen werden. Dies wird üblicherweise in einzeiligen Arrays getan, d. h.. `array(1, 2)` wird der Schreibweise `array(1, 2, )` vorgezogen. Andererseits wird bei mehrzeiligen Arrays das Komma am Ende üblicherweise genutzt, da dies ein einfaches Hinzufügen weiterer Elemente am Ende erlaubt.

> Hinweis:

> Es gibt eine Kurzform der Array-Syntax, die `array()` durch `[]` ersetzt.

Beispiel #1 Ein einfaches Array

    <?php
    $array1 = array(
        "foo" => "bar",
        "bar" => "foo",
    );

    // Verwendung der verkürzten Array-Syntax
    $array2 = [
        "foo" => "bar",
        "bar" => "foo",
    ];

    var_dump($array1, $array2);
    ?>

Der Schlüssel kann entweder ein Integer oder ein String sein. Der Wert kann beliebige Datentypen annehmen.

Zusätzlich werden die folgenden Typkonvertierungen auf den Schlüssel angewendet:

- Strings, die einen gültigen dezimalen Int enthalten, werden zum entsprechenden Int umgewandelt, es sei denn, der Zahl ist ein `+`-Zeichen vorangestellt. Beispielsweise wird der Schlüssel `"8"` tatsächlich unter `8` gespeichert. Andererseits wird `"08"` nicht umgewandelt, da dies kein gültiger Ganzzahlwert ist.
- Floats werden ebenfalls zu Int umgewandelt, was ein Abschneiden des Dezimalbruchs zur Folge hat. Beispielsweise wird der Schlüssel `8.7` als `8` gespeichert.
- Bools werden ebenfalls zu Int umgewandelt, d. h. der Schlüssel `true` wird unter `1` gespeichert und der Schlüssel `false` unter `0`.
- Null wird zu einem leeren String umgewandelt, d. h. der Schlüssel `null` wird tatsächlich unter `""` gespeichert.
- Werte vom Typ Array oder Objekt können nicht als Schlüssel verwendet werden. Ein Versuch, dies zu tun, wird die Warnung `Illegal offset type` zur Folge haben.

Wenn mehrere Elemente in einer Array-Deklaration den gleichen Schlüssel verwenden, dann wird nur der letzte verwendet und alle weiteren werden überschrieben.

Beispiel #2 Beispiel für Typumwandlung und Überschreibung

    <?php
    $array = array(
        1    => "a",
        "1"  => "b",
        1.5  => "c",
        true => "d",
    );
    var_dump($array);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      [1]=>
      string(1) "d"
    }

Da alle Schlüssel im obigen Beispiel zu `1` umgewandelt werden, wird der Wert dieses Elements durch jeden angegebenen Wert überschrieben und nur der letzte zugewiesene Wert `"d"` bleibt übrig.

Arrays können in PHP gleichzeitig Schlüssel der Typen Int und String enthalten, da PHP nicht zwischen indizierten und assoziativen Arrays unterscheidet.

Beispiel #3 Gemischte Int- und String-Schlüssel

    <?php
    $array = array(
        "foo" => "bar",
        "bar" => "foo",
        100   => -100,
        -100  => 100,
    );
    var_dump($array);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      ["foo"]=>
      string(3) "bar"
      ["bar"]=>
      string(3) "foo"
      [100]=>
      int(-100)
      [-100]=>
      int(100)
    }

Die Angabe des Schlüssels ist optional. Ist keiner angegeben, so wird PHP den bisher größten angegebenen Int-Schlüssel erhöhen und das Ergebnis als Schlüssel verwenden.

Beispiel #4 Indizierte Arrays ohne Schlüssel

    <?php
    $array = array("foo", "bar", "hello", "world");
    var_dump($array);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      [0]=>
      string(3) "foo"
      [1]=>
      string(3) "bar"
      [2]=>
      string(5) "hello"
      [3]=>
      string(5) "world"
    }

Es ist auch möglich, den Schlüssel nur bei einigen Elementen anzugeben und bei anderen auszulassen:

Beispiel #5 Schlüssel nicht bei allen Elementen

    <?php
    $array = array(
             "a",
             "b",
        6 => "c",
             "d",
    );
    var_dump($array);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      [0]=>
      string(1) "a"
      [1]=>
      string(1) "b"
      [6]=>
      string(1) "c"
      [7]=>
      string(1) "d"
    }

Hier ist zu erkennen, dass dem letzten Wert `"d"` der Schlüssel `7` zugewiesen wurde. Dies erfolgte, da der größte vorherige ganzzahlige Schlüssel `6` war.

Beispiel #6 Beispiel für komplexe Typumwandlung und Überschreibung

Dieses Beispiel enthält alle Variationen der Typumwandlung von Schlüsseln und des Überschreibens von Elementen.

    <?php
    $array = array(
        1    => 'a',
        '1'  => 'b', // der Wert "a" wird mit "b" überschrieben
        1.5  => 'c', // der Wert "b" wird mit "c" überschrieben
        -1 => 'd',
        '01'  => 'e', // da dies kein Integer-String ist, wird der Schlüssel
                      // für 1 NICHT überschrieben
        '1.5' => 'f', // da dies kein Integer-String ist, wird der Schlüssel
                      // für 1 NICHT überschrieben
        true => 'g', // der Wert "c" wird mit "g" überschrieben
        false => 'h',
        '' => 'i',
        null => 'j', // der Wert "i" wird mit "j" überschrieben
        'k', // dem Wert "k" wird der Schlüssel 2 zugewiesen. Das liegt daran,
             // dass der größte ganzzahlige Schlüssel davor 1 war
        2 => 'l', // der Wert "k" wird mit "l" überschrieben
    );

    var_dump($array);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(7) {
      [1]=>
      string(1) "g"
      [-1]=>
      string(1) "d"
      ["01"]=>
      string(1) "e"
      ["1.5"]=>
      string(1) "f"
      [0]=>
      string(1) "h"
      [""]=>
      string(1) "j"
      [2]=>
      string(1) "l"
    }

Beispiel #7 Beispiel mit negativem Index

Wenn ein negativer ganzzahliger Schlüssel `n` zugewiesen wird, stellt PHP sicher, dass als nächstes der Schlüssel `n+1` zugewiesen wird.

    <?php
    $array = [];

    $array[-5] = 1;
    $array[] = 2;

    var_dump($array);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      [-5]=>
      int(1)
      [-4]=>
      int(2)
    }

Warnung

Vor PHP 8.3.0 würde die Zuweisung eines negativen ganzzahligen Schlüssels `n` dazu führen, dass als nächstes der Schlüssel `0` zugewiesen wird, sodass das obige Beispiel zu diesem Ergebnis führen würde:

    array(2) {
      [-5]=>
      int(1)
      [0]=>
      int(2)
    }

#### Zugriff auf Elemente mit eckigen Klammern

Auf Elemente eines Arrays kann durch Verwendung der Syntax `array[Schlüssel]` zugegriffen werden.

Beispiel #8 Zugriff auf Array-Elemente

    <?php
    $array = array(
        "foo" => "bar",
        42    => 24,
        "multi" => array(
             "dimensional" => array(
                 "array" => "foo"
             )
        )
    );

    var_dump($array["foo"]);
    var_dump($array[42]);
    var_dump($array["multi"]["dimensional"]["array"]);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "bar"
    int(24)
    string(3) "foo"

> Hinweis:

> Vor PHP 8.0.0 konnten sowohl eckige als auch geschweifte Klammern verwendet werden, um auf die Elemente eines Arrays zuzugreifen (z. B. werden im obigen Beispiel `$array[42]` und `array{42}` auf das gleiche Element zugreifen). Die Syntax für geschweifte Klammern ist seit PHP 7.4.0 veraltet und wird seit PHP 8.0.0 nicht mehr unterstützt.

Beispiel #9 Array-Dereferenzierung

    <?php
    function getArray() {
        return array(1, 2, 3);
    }

    $secondElement = getArray()[1];

    var_dump($secondElement);
    ?>

> Hinweis:

> Der Versuch, auf einen nicht definierten Arrayschlüssel zuzugreifen, entspricht dem Zugriff auf jede andere undefinierte Variable: ein Fehler der Stufe `E_WARNING` (der Stufe `E_NOTICE` vor PHP 8.0.0) wird ausgegeben und das Ergebnis ist `null`.

> Hinweis:

> Die Array-Dereferenzierung eines skalaren Werts, der kein String ist, ergibt `null`. Vor PHP 7.4.0 verursachte dies keine Fehlermeldung. Seit PHP 7.4.0 wird ein Fehler der Stufe `E_NOTICE` ausgegeben; seit PHP 8.0.0 ein Fehler der Stufe `E_WARNING`.

#### Anlegen/Ändern mit eckigen Klammern

Ein bestehendes Array kann verändert werden, indem man explizit Werte darin setzt.

Dies wird getan, indem man dem Array Werte zuweist und dabei den Schlüssel in eckigen Klammern angibt. Der Schlüssel kann dabei weggelassen werden, was ein leeres Klammernpaar (`[]`) ergibt.

    $arr[Schlüssel] = Wert;
    $arr[] = Wert;
    // Schlüssel kann ein Int oder String sein
    // Wert kann einen beliebigen Typen haben

Falls $arr noch nicht existiert oder auf `null` oder `false` gesetzt ist, wird es erzeugt; dies ist also eine alternative Methode, um ein Array zu erzeugen. Dieses Vorgehen wird jedoch nicht empfohlen, da, falls $arr bereits einen Wert enthält (z. B. ein String aus einer Requestvariable), dieser Wert bestehen bleibt und `[]` tatsächlich für den String-Zugriffs-Operator stehen kann. Es ist immer besser, eine Variable durch direkte Zuweisung zu initialisieren.

> Hinweis: Seit PHP 7.1.0 löst die Anwendung des leeren Index-Operators auf eine Zeichenkette einen fatalen Fehler aus. Zuvor wurde die Zeichenkette stillschweigend in ein Array umgewandelt.

> Hinweis: Seit PHP 8.1.0 ist das Erstellen eines neuen Arrays aus `false`-Werten veraltet. Es ist weiterhin erlaubt, ein neues Array aus `null`- und undefinierten Werten zu erstellen.

Um einen bestimmten Wert zu ändern, kann man dem Element anhand seines Schlüssels einen Wert zuweisen. Um ein Schlüssel-Wert-Paar zu entfernen, kann man die Funktion unset() darauf anwenden.

Beispiel #10 Verwenden von eckigen Klammern bei Arrays

    <?php
    $arr = array(5 => 1, 12 => 2);

    $arr[] = 56;    // Dies ist dasselbe wie $arr[13] = 56;
                    // an dieser Stelle im Programmablauf

    $arr["x"] = 42; // Dies fügt ein neues Element zum Array
                    // mit dem Schlüssel "x" hinzu

    unset($arr[5]); // Dies entfernt das Element aus dem Array

    var_dump($arr);

    unset($arr);    // Dies löscht das gesamte Array

    var_dump($arr);
    ?>

> Hinweis: Wenn kein Schlüssel angegeben ist, wird als Schlüssel der größte vorhandene Integer-Index + `1` verwendet. Hat das Array noch keine positiven Integer-Indizes, ist der Schlüssel `0`. Seit PHP 8.3.0 darf es auch ein negativer Integer sein.

> Zu beachten ist, dass der Maximalwert der Integer-Schlüssel dafür aktuell nicht im Array existieren muss. Er muss nur zu irgendeinem Zeitpunkt im Array existiert haben, seitdem das Array zuletzt neu indiziert wurde. Das folgende Beispiel erläutert dies:

>     <?php
>     // Create a simple array.
>     $array = array(1, 2, 3, 4, 5);
>     print_r($array);

>     // Nun wird jeder Wert gelöscht, aber das Array selbst bleibt bestehen
>     foreach ($array as $i => $value) {
>         unset($array[$i]);
>     }
>     print_r($array);

>     // Ein Element wird hinzugefügt
>     // (Beachten Sie, dass der neue Schlüssel 5 ist statt 0)
>     $array[] = 6;
>     print_r($array);

>     // Neue Indizierung
>     $array = array_values($array);
>     $array[] = 7;
>     print_r($array);
>     ?>

> Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

>     Array
>     (
>         [0] => 1
>         [1] => 2
>         [2] => 3
>         [3] => 4
>         [4] => 5
>     )
>     Array
>     (
>     )
>     Array
>     (
>         [5] => 6
>     )
>     Array
>     (
>         [0] => 6
>         [1] => 7
>     )

#### Destrukturierung (Zerlegung) von Arrays

Arrays können mit den Sprachkonstrukten `[]` (seit PHP 7.1.0) oder list() destrukuriert werden. Diese Konstrukte können verwendet werden, um ein Array in einzelne Variablen zu zerlegen.

Beispiel #11 Destrukturieren eines Arrays

    <?php
    $source_array = ['foo', 'bar', 'baz'];

    [$foo, $bar, $baz] = $source_array;

    echo $foo, PHP_EOL;    // gibt "foo" aus
    echo $bar, PHP_EOL;    // gibt "bar" aus
    echo $baz, PHP_EOL;    // gibt "baz" aus
    ?>

Die Destrukturierung von Arrays kann in `foreach` verwendet werden, um ein mehrdimensionales Array zu zerlegen, während darüber iteriert wird.

Beispiel #12 Destrukturieren eines Arrays in foreach

    <?php
    $source_array = [
        [1, 'John'],
        [2, 'Jane'],
    ];

    foreach ($source_array as [$id, $name]) {
        echo "{$id}: '{$name}'\n";
    }
    ?>

Array-Elemente werden ignoriert, wenn die Variable nicht angegeben wird. Die Destrukturierung von Arrays beginnt immer beim Index `0`.

Beispiel #13 Ignoren von Elementen

    <?php
    $source_array = ['foo', 'bar', 'baz'];

    // Zuweisen des Elements bei Index 2 an die Variable $baz
    [, , $baz] = $source_array;

    echo $baz;    // gibt "baz" aus
    ?>

Seit PHP 7.1.0 können auch assoziative Arrays destrukturiert werden. Da der Index explizit angegeben werden kann, ermöglicht dies auch in numerisch indizierten Arrays eine einfachere Auswahl des richtigen Elements.

Beispiel #14 Destrukturieren von assoziativen Arrays

    <?php
    $source_array = ['foo' => 1, 'bar' => 2, 'baz' => 3];

    // Zuweisen des Elements bei Index 'baz' an die Variable $three
    ['baz' => $three] = $source_array;

    echo $three, PHP_EOL;  // gibt 3 aus

    $source_array = ['foo', 'bar', 'baz'];

    // Zuweisen des Elements bei Index 2 an die Variable $baz
    [2 => $baz] = $source_array;

    echo $baz, PHP_EOL;    // gibt "baz" aus
    ?>

Array-Destrukturierung kann verwendet werden, um auf einfache Weise zwei Variablen zu vertauschen.

Beispiel #15 Vertauschen von zwei Variablen

    <?php
    $a = 1;
    $b = 2;

    [$b, $a] = [$a, $b];

    echo $a, PHP_EOL;    // gibt 2 aus
    echo $b, PHP_EOL;    // gibt 1 aus
    ?>

> Hinweis:

> Der Spread-Operator (`...`) wird bei Zuweisungen nicht unterstützt.

> Hinweis:

> Wird versucht, auf einen nicht definierten Array-Schlüssel zuzugreifen, so ist dies dasselbe wie der Zugriff auf eine andere undefinierte Variable: Eine Fehlermeldung der Stufe `E_WARNING` (der Stufe `E_NOTICE` vor PHP 8.0.0) wird ausgegeben und das Ergebnis ist `null`.

> Hinweis:

> Bei der Destrukturierung eines skalaren Werts wird allen Variablen `null` zugewiesen.

### Nützliche Funktionen

Es gibt einige nützliche Funktionen für die Arbeit mit Arrays, die im Abschnitt Array-Funktionen nachgeschlagen werden können.

> Hinweis:

> Die Funktion unset() erlaubt es, Schlüssel aus einem Array zu entfernen. Zu beachten ist dabei, dass das Array nicht neu indiziert wird. Falls ein echtes Verhalten von "Entfernen und Verschieben" gewünscht ist, dann kann das Array mittels array_values() neu indiziert werden.

> Beispiel #16 Entfernen von Zwischenelementen

>     <?php
>     $a = array(1 => 'one', 2 => 'two', 3 => 'three');

>     /* dies wird ein Array erzeugen, das wie folgt definiert worden wäre
>        $a = array(1 => 'one', 3 => 'three');
>        und NICHT so
>        $a = array(1 => 'one', 2 =>'three');
>     */
>     unset($a[2]);
>     var_dump($a);

>     $b = array_values($a);
>     // Nun ist $b array(0 => 'one', 1 =>'three')
>     var_dump($b);
>     ?>

Die Kontrollstruktur `foreach` existiert speziell für Arrays. Sie bietet eine einfache Möglichkeit, ein Array zu durchlaufen.

### Dos und Dont's für Arrays (was man tun sollte und was nicht)

#### Wieso ist `$foo[bar]` falsch?

Verwenden Sie immer Anführungszeichen um ein Arrayindex-Zeichenkettenliteral. Beispielsweise ist `$foo['bar']` richtig, `$foo[bar]` hingegen nicht. Aber wieso? Es ist üblich, die folgende Schreibweise in alten Skripten zu finden:

    <?php
    $foo[bar] = 'enemy';
    echo $foo[bar];
    // etc
    ?>

Dies ist falsch, funktioniert aber. Der Grund dafür ist, dass dieser Code eine undefinierte Konstante (`bar`) anstatt eines Strings verwendet (`'bar'` - beachten Sie die Anführungszeichen). Dies funktioniert, da PHP einen nackten String (ein String ohne Anführungszeichen, der keinem bekannten Symbol entspricht) automatisch in einen String umwandelt, welcher den nackten String enthält. Beispielsweise wird PHP, wenn keine Konstante namens `bar` definiert ist, diese automatisch durch den String `'bar'` ersetzen und verwenden.

Warnung

Das Rückfallverhalten, eine nicht definierte Konstante als nackte Zeichenkette zu interpretieren, löst einen Fehler der Stufe `E_NOTICE` aus. Dies ist seit PHP 7.2.0 missbilligt und löst einen Fehler der Stufe `E_WARNING` aus. Mit PHP 8.0.0 wurde es entfernt und löst eine Error-Exception aus.

Dies bedeutet nicht, dass man den Schlüssel immer in Anführungszeichen setzen muss. Setzen Sie keine Schlüssel in Anführungszeichen, welche Konstanten oder Variablen sind, da dies PHP daran hindern wird, diese zu interpretieren.

Beispiel #17 Anführungszeichen bei Schlüsseln

    <?php
    error_reporting(E_ALL);
    ini_set('display_errors', true);
    ini_set('html_errors', false);

    // Ein simples Array:
    $array = array(1, 2);
    $count = count($array);

    for ($i = 0; $i < $count; $i++) {
        echo "\nPrüfe $i: \n";
        echo "Schlecht: " . $array['$i'] . "\n";
        echo "Gut: " . $array[$i] . "\n";
        echo "Schlecht: {$array['$i']}\n";
        echo "Gut: {$array[$i]}\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Prüfe 0:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Schlecht:
    Gut: 1
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Schlecht:
    Gut: 1

    Prüfe 1:
    Notice: Undefined index:  $i in /path/to/script.html on line 9
    Schlecht:
    Gut: 2
    Notice: Undefined index:  $i in /path/to/script.html on line 11
    Schlecht:
    Gut: 2

Weitere Beispiele zur Erläuterung dieses Verhaltens:

Beispiel #18 Weitere Beispiele

    <?php
    // Alle Fehler anzeigen
    error_reporting(E_ALL);

    $arr = array('fruit' => 'apple', 'veggie' => 'carrot');

    // Korrekt
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr['veggie'], PHP_EOL; // carrot

    // Inkorrekt. Dies Funktioniert nicht und PHP löst löst einen Error aus,
    // da eine undefinierte Konstante namens fruit verwendet wird
    //
    // Error: Undefined constant "fruit"
    try {
        echo $arr[fruit];
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    // Dies definiert eine Konstante, um darzustellen, was hier passiert. Der Wert
    // 'veggie' wird einer Konstanten namens fruit zugewiesen
    define('fruit', 'veggie');

    // Beachten Sie nun den Unterschied
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr[fruit], PHP_EOL;    // carrot

    // Hier ist es in Ordnung, da dies innerhalb eines Strings ist. Innerhalb eines
    // Strings wird nicht nach Konstanten gesucht, weshalb kein Fehler auftritt
    echo "Hello $arr[fruit]", PHP_EOL;      // Hello apple

    // Mit einer Ausnahme: Klammern um ein Array sorgen dafür, dass Konstanten
    // interpretiert werden
    echo "Hello {$arr[fruit]}", PHP_EOL;    // Hello carrot
    echo "Hello {$arr['fruit']}", PHP_EOL;  // Hello apple

    // Konkatenation (Verkettung) ist eine weitere Möglichkeit
    echo "Hello " . $arr['fruit'], PHP_EOL; // Hello apple
    ?>

    <?php
    // Dies wird nicht funktionieren und zu einem Parse-Fehler führen:
    // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
    // Dies gilt natürlich ebenso für superglobale Werte innerhalb von Strings
    print "Hello $arr['fruit']";
    print "Hello $_GET['foo']";
    ?>

Wie im Abschnitt zur Syntax gezeigt, muss der Inhalt der eckigen Klammern '`[`' und '`]`') ein Ausdruck sein. Das bedeutet, dass folgendes funktioniert:

    <?php
    echo $arr[somefunc($bar)];
    ?>

Dieses Beispiel zeigt, wie der Rückgabewert einer Funktion als Arrayindex verwendet wird. PHP kann auch Konstanten auflösen:

    <?php
    $error_descriptions[E_ERROR]   = "Ein fataler Fehler ist aufgetreten";
    $error_descriptions[E_WARNING] = "PHP hat eine Warnung ausgegeben";
    $error_descriptions[E_NOTICE]  = "Dies ist nur ein informeller Hinweis";
    ?>

Es ist zu beachten, dass `E_ERROR` ein gültiger Bezeichner ist, genau wie `bar` im ersten Beispiel. Das vorherige Beispiel ist gleichbedeutend mit:

    <?php
    $error_descriptions[1] = "Ein fataler Fehler ist aufgetreten";
    $error_descriptions[2] = "PHP hat eine Warnung ausgegeben";
    $error_descriptions[8] = "Dies ist nur ein informeller Hinweis";
    ?>

da `E_ERROR` gleich `1` ist usw.

##### Wieso ist es also schlecht?

Irgendwann in der Zukunft könnte das PHP-Team eine weitere Konstante oder ein Schlüsselwort hinzufügen oder eine Konstante in anderem Code könnte Einfluss nehmen. Es ist beispielsweise bereits falsch, die Wörter `empty` oder `default` so zu schreiben, da dies reservierte Schlüsselwörter sind.

> Hinweis: Zur Wiederholung: innerhalb eines Strings in doppelten Anführungszeichen ist es korrekt, einen Arrayschlüssel ohne Anführungszeichen zu schreiben, weswegen `"$foo[bar]"` zulässig ist. Die obigen Beispiele erklären dies ebenso, wie der Abschnitt zum Parsen von Variablen in Strings.

### Konvertierung in ein Array

Für jeden der Typen Integer, Float, String, Boolean und Ressource führt eine Konvertierung eines Wertes in ein Array zu einem Array mit einem einzigen Wert mit dem Index Null und dem Wert des Skalaren, der konvertiert wurde. Anders ausgedrückt ist `(array) $scalarValue` exakt identisch mit `array($scalarValue)`.

Wenn ein Objekt in ein Array konvertiert wird, so ist das Ergebnis ein Array, dessen Werte die Eigenschaften des Objekts sind. Die Schlüssel sind die Namen der Eigenschaften des Objektes mit ein paar nennenswerten Ausnahmen: Eigenschaften mit Ganzzahl-Namen sind nicht zugreifbar, privaten Variablen wird der Name der Klasse vorangestellt und protected Variablen wird dem Variablennamen ein '*' vorangestellt. Diese vorangestellten Werte haben `NUL`-Bytes auf beiden Seiten. Nicht-initialisierte typisierte Eigenschaften werden stillschweigend verworfen.

Beispiel #19 Konvertierung in ein Array

    <?php

    class A {
        private $B;
        protected $C;
        public $D;
        function __construct()
        {
            $this->{1} = null;
        }
    }

    var_export((array) new A());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array (
      '' . "\0" . 'A' . "\0" . 'B' => NULL,
      '' . "\0" . '*' . "\0" . 'C' => NULL,
      'D' => NULL,
      1 => NULL,
    )

Diese `NUL`-Bytes können zu einem unerwarteten Verhalten führen:

Beispiel #20 Umwandeln eines Objekts in ein Array

    <?php

    class A {
        private $A; // Dies wird zu '\0A\0A'
    }

    class B extends A {
        private $A; // Dies wird zu '\0B\0A'
        public $AA; // Dies wird zu 'AA'
    }

    var_dump((array) new B());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      ["BA"]=>
      NULL
      ["AA"]=>
      NULL
      ["AA"]=>
      NULL
    }

Im obigen Beispiel scheint es zwei Schlüssel namens 'AA' zu geben, obwohl einer davon eigentlich '\0A\0A' ist.

Die Konvertierung von `null` in ein Array führt zu einem leeren Array.

### Vergleiche

Mit der Funktion array_diff() und mit Array-Operatoren ist es möglich, Arrays zu vergleichen.

### Entpacken von Arrays

Ein Array, dem ein `...` vorangestellt ist, wird bei der Definition des Arrays an Ort und Stelle expandiert (entpackt). Nur Arrays und Objekte, die Traversable implementieren, können entpackt werden. Das Entpacken von Arrays mit `...` ist seit PHP 7.4.0 verfügbar. Dies wird auch als Spread-Operator bezeichnet.

Es ist möglich, ein Array mehrmals zu entpacken und normale Elemente vor oder nach dem Operator `...` hinzuzufügen:

Beispiel #21 Einfaches Entpacken von Arrays

    <?php
    // Verwendung der kurzen Array-Syntax.
    // Funktioniert auch mit der array()-Syntax.
    $arr1 = [1, 2, 3];
    $arr2 = [...$arr1]; // [1, 2, 3]
    $arr3 = [0, ...$arr1]; // [0, 1, 2, 3]
    $arr4 = [...$arr1, ...$arr2, 111]; // [1, 2, 3, 1, 2, 3, 111]
    $arr5 = [...$arr1, ...$arr1]; // [1, 2, 3, 1, 2, 3]

    function getArr() {
      return ['a', 'b'];
    }
    $arr6 = [...getArr(), 'c' => 'd']; // ['a', 'b', 'c' => 'd']

    var_dump($arr1, $arr2, $arr3, $arr4, $arr5, $arr6);
    ?>

Das Entpacken eines Arrays mit dem Operator `...` folgt der Syntax der Funktion array_merge(). Das heißt, nachfolgende Zeichenketten-Schlüssel überschreiben vorherige und Integer-Schlüssel werden neu nummeriert:

Beispiel #22 Entpacken eines Arrays mit doppeltem Schlüssel

    <?php
    // Zeichenketten-Schlüssel
    $arr1 = ["a" => 1];
    $arr2 = ["a" => 2];
    $arr3 = ["a" => 0, ...$arr1, ...$arr2];
    var_dump($arr3); // ["a" => 2]

    // Integer-Schlüssel
    $arr4 = [1, 2, 3];
    $arr5 = [4, 5, 6];
    $arr6 = [...$arr4, ...$arr5];
    var_dump($arr6); // [1, 2, 3, 4, 5, 6]
    // Das ergibt [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6]
    // wobei die ursprünglichen Integer-Schlüssel nicht beibehalten wurden.
    ?>

> Hinweis:

> Schlüssel, die weder Integer noch Zeichenketten sind, lösen einen TypeError aus. Solche Schlüssel können nur von einem Traversable-Objekt erzeugt werden.

> Hinweis:

> Vor PHP 8.1 wird das Entpacken eines Arrays, das einen String-Schlüssel enthält, nicht unterstützt:

>     <?php

>     $arr1 = [1, 2, 3];
>     $arr2 = ['a' => 4];
>     $arr3 = [...$arr1, ...$arr2];
>     // Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5

>     $arr4 = [1, 2, 3];
>     $arr5 = [4, 5];
>     $arr6 = [...$arr4, ...$arr5]; // works. [1, 2, 3, 4, 5]
>     ?>

### Beispiele

Der Array-Typ in PHP ist sehr vielseitig. Hier sind einige Beispiele:

Beispiel #23 Vielseitigkeit von Arrays

    <?php
    // Dies:
    $a = array( 'color' => 'red',
                'taste' => 'sweet',
                'shape' => 'round',
                'name'  => 'apple',
                4        // der Schlüssel wird 0 sein
              );

    $b = array('a', 'b', 'c');

    var_dump($a, $b);

    // . . .ist komplett gleichbedeutend mit:
    $a = array();
    $a['color'] = 'red';
    $a['taste'] = 'sweet';
    $a['shape'] = 'round';
    $a['name']  = 'apple';
    $a[]        = 4;        // der Schlüssel wird 0 sein

    $b = array();
    $b[] = 'a';
    $b[] = 'b';
    $b[] = 'c';

    // Nachdem der obige Code ausgeführt wurde, wird $a das Array
    // array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
    // 'name' => 'apple', 0 => 4) sein und $b wird das Array
    // array(0 => 'a', 1 => 'b', 2 => 'c') oder einfach array('a', 'b', 'c')
    // sein

    var_dump($a, $b);
    ?>

Beispiel #24 Verwendung von array()

    <?php
    // Array als Zuordnung von Eigenschaften
    $map = array( 'version'    => 4,
                  'OS'         => 'Linux',
                  'lang'       => 'englisch',
                  'short_tags' => true
                );
    var_dump($map);

    // Streng numerische Schlüssel
    // Das ist gleichbedeutend mit array(0 => 7, 1 => 8, ...)
    $array = array( 7,
                    8,
                    0,
                    156,
                    -10
                  );
    var_dump($array);

    $switching = array(         10, // Schlüssel = 0
                        5    =>  6,
                        3    =>  7,
                        'a'  =>  4,
                                11, // Schlüssel = 6 (das Maximum der Integer-Schlüssel war 5)
                        '8'  =>  2, // Schlüssel = 8 (Integer!)
                        '02' => 77, // Schlüssel = '02'
                        0    => 12  // Der Wert 10 wird mit 12 überschrieben
                      );
    var_dump($switching);

    // Leeres array
    $empty = array();
    var_dump($empty);
    ?>

Beispiel #25 Sammlung

    <?php
    $farben = array('rot', 'blau', 'grün', 'gelb');

    foreach ($farben as $farbe) {
        echo "Mögen sie $farbe?\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Mögen sie rot?
    Mögen sie blau?
    Mögen sie grün?
    Mögen sie gelb?

Die Veränderung der Werte eines Arrays ist mit der Übergabe als Referenz direkt möglich.

Beispiel #26 Elemente in der Schleife verändern

    <?php
    $colors = array('red', 'blue', 'green', 'yellow');

    foreach ($colors as &$color) {
        $color = mb_strtoupper($color);
    }
    unset($color); /* Sicherstellen, dass nachfolgende
    Zugriffe auf $color nicht das letzte Element ändern */

    print_r($colors);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => ROT
        [1] => BLAU
        [2] => GRÜN
        [3] => GELB
    )

Dieses Beispiel erzeugt ein Array mit erstem Schlüssel 1.

Beispiel #27 1-basierte Indizes

    <?php
    $firstquarter = array(1 => 'Januar', 'Februar', 'März');
    print_r($firstquarter);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [1] => Januar
        [2] => Februar
        [3] => März
    )

Beispiel #28 Füllen eines Arrays

    <?php
    // Dies füllt ein Array mit allen Einträgen eines Verzeichnisses
    $handle = opendir('.');
    while (false !== ($file = readdir($handle))) {
        $files[] = $file;
    }
    closedir($handle);

    var_dump($files);
    ?>

Arrays sind geordnet. Die Reihenfolge kann durch verschiedene Sortierfunktionen verändert werden. Siehe Array-Funktionen für mehr Informationen. Die Funktion count() kann verwendet werden, um die Anzahl der Elemente eines Arrays zu ermitteln.

Beispiel #29 Ein Array sortieren

    <?php
    sort($files);
    print_r($files);
    ?>

Da die Werte eines Arrays beliebig sein können, können diese auch andere Arrays sein. Dies ermöglicht die Erzeugung von rekursiven und mehrdimensionalen Arrays.

Beispiel #30 Rekursive und mehrdimensionale Arrays

    <?php
    $fruits = array ( "fruits"  => array ( "a" => "orange",
                                           "b" => "banana",
                                           "c" => "apple"
                                         ),
                      "numbers" => array ( 1,
                                           2,
                                           3,
                                           4,
                                           5,
                                           6
                                         ),
                      "holes"   => array (      "first",
                                           5 => "second",
                                                "third"
                                         )
                    );
    var_dump($fruits);

    // Einige Beispiele für den Zugriff auf die Werte in den obigen Beispielen
    echo $fruits["holes"][5];    // gibt "second" aus
    echo $fruits["fruits"]["a"]; // gibt "orange" aus
    unset($fruits["holes"][0]);  // entfernt "first"

    // Ein neues mehrdimensionales Array erzeugen
    $juices["apple"]["green"] = "good";
    var_dump($juices);
    ?>

Die Zuweisung eines Arrays beinhaltet immer eine Kopie der Werte. Verwenden Sie den Referenz-Operator, um ein Array per Referenz zu kopieren.

Beispiel #31 Kopieren eines Arrays

    <?php
    $arr1 = array(2, 3);
    $arr2 = $arr1;
    $arr2[] = 4; // $arr2 wurde geändert,
                 // $arr1 ist weiterhin array(2, 3)

    $arr3 = &$arr1;
    $arr3[] = 4; // nun sind $arr1 und $arr3 identisch

    var_dump($arr1, $arr2, $arr3);
    ?>

## Objekte

### Initialisierung von Objekten

Ein neues Objekt (Typ object) kann erstellt werden, indem mit der Anweisung `new` eine Klasse instanziiert wird:

Beispiel #1 Erstellen eines Objekts

    <?php
    class foo
    {
        function do_foo()
        {
            echo "Mache foo.";
        }
    }

    $bar = new foo;
    $bar->do_foo();
    ?>

Eine ausführliche Erörterung ist im Kapitel Klassen und Objekte zu finden.

### Konvertierung in ein Objekt

Wenn ein Objekt in ein Objekt konvertiert wird, wird es nicht verändert. Wenn ein Wert irgendeines anderen Typs in ein Objekt konvertiert wird, dann wird ein neues Exemplar der eingebauten Klasse stdClass erstellt. Wenn der Wert `null` war, wird das neue Exemplar leer sein. Ein Array wird in ein Objekt konvertiert, indem die Schlüssel und Werte des Arrays zu den Namen und Werten der Eigenschaften des Objekts werden. Es ist zu beachten, dass in diesem Fall vor PHP 7.2.0 nicht auf numerische Schlüssel zugegriffen werden konnte, es sei denn, sie wurden iteriert.

Beispiel #2 Konvertierung in ein Objekt

    <?php
    $obj = (object) array('1' => 'foo');
    var_dump(isset($obj->{'1'})); // outputs 'bool(true)'

    // Seit PHP 8.1 veraltet
    var_dump(key($obj)); // outputs 'string(1) "1"'
    ?>

Für alle anderen Werte enthält eine Member-Variable namens `scalar` den Wert.

Beispiel #3 Konvertierung mittels `(object)`

    <?php
    $obj = (object) 'ciao';
    echo $obj->scalar;  // Ausgabe 'ciao'
    ?>

## Aufzählungen (Enum)

(PHP 8 >= 8.1.0)

### Grundlagen der Aufzählungen

Aufzählungen dienen als einschränkende Schicht über Klassen und Klassenkonstanten und bieten eine Möglichkeit, eine geschlossene Menge von möglichen Werten für einen Typ zu definieren.

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function do_stuff(Suit $s)
    {
        // ...
    }

    do_stuff(Suit::Spades);
    ?>

Eine ausführliche Beschreibung ist im Kapitel Aufzählungen zu finden.

### Casting (Umwandlung)

Wenn ein Wert vom Typ enum in ein Objekt umgewandelt wird, wird er nicht verändert. Wenn ein Enum in ein Array umgewandelt wird, wird ein Array mit einem einzelnen Schlüssel `name` erstellt (bei Pure Enums) oder ein Array mit den beiden Schlüsseln `name` und `value` (bei Backed Enums). Alle anderen Cast-Typen führen zu einem Fehler.

## Ressourcen

Eine resource ist eine spezielle Variable, die eine Referenz zu einer externen Ressource darstellt. Ressourcen werden mit Hilfe spezieller Funktionen erzeugt und genutzt. Im Anhang finden Sie eine Liste all dieser Funktionen und der zugehörigen resource-Typen.

Siehe auch get_resource_type().

### Konvertierung von Ressourcen

Da resource-Variablen spezielle Referenzen auf geöffnete Dateien, Datenbankverbindungen, Grafikbereiche usw. enthalten, ist die Konvertierung von resource nicht sinnvoll.

### Ressourcen freigeben

Dank der Referenzzähler, die Teil der Zend Engine sind, werden Ressourcen, die von keiner Variablen mehr referenziert werden, automatisch erkannt und vom Garbage Collector freigegeben. Aus diesem Grund ist es selten nötig, Speicher von Hand freizugeben.

> Hinweis: Persistente Datenbankverbindungen sind eine Ausnahme von dieser Regel, sie werden nicht vom Garbage Collector entfernt. Mehr Informationen finden sie im Abschnitt Persistente Verbindungen.

## Callables

Ein Callable ist eine Referenz auf eine Funktion oder Methode, die einer anderen Funktion als Argument übergeben wird. Sie werden durch die Typdeklaration callable repräsentiert.

    <?php
    function foo(callable $callback) {
        $callback();
    }
    ?>

Einige Funktionen akzeptieren Callback-Funktionen als Parameter, zum Beispiel array_map(), usort() oder preg_replace_callback().

### Erstellung von Callables

Ein Callable ist ein Typ, der etwas repräsentiert, das aufgerufen werden kann. Callables können als Argumente an Funktionen oder Methoden übergeben werden, die einen Callback-Parameter erwarten, oder sie können direkt aufgerufen werden. Der Typ callable kann nicht als Typdeklaration für Klasseneigenschaften verwendet werden. Verwenden Sie stattdessen eine Closure-Typdeklaration.

Callables können auf verschiedene Arten erstellt werden:

- Closure-Objekt
- Ein String, der den Namen einer Funktion oder Methode enthält
- Ein Array, das einen Klassennamen oder ein Object an Index 0 und den Methodennamen an Index 1 enthält
- Ein Objekt, das die magische Methode __invoke() implementiert

Ein Closure-Objekt kann mit der Syntax für anonyme Funktionen, der Syntax für Pfeilfunktionen, der Syntax für Callbacks als Objekte erster Klasse oder mit der Methode Closure::fromCallable() erstellt werden.

> Hinweis: Die Syntax für Callbacks als Objekte erster Klasse ist erst ab PHP 8.1.0 verfügbar.

Beispiel #1 Callback-Beispiel mit einem Closure

    <?php
    // Verwendung der Syntax für anonyme Funktionen
    $double1 = function ($a) {
        return $a * 2;
    };

    // Verwendung der Syntax für Callbacks als Objekte erster Klasse
    function double_function($a) {
        return $a * 2;
    }
    $double2 = double_function(...);

    // Verwendung der Syntax für Pfeilfunktionen
    $double3 = fn($a) => $a * 2;

    // Verwendung von Closure::fromCallable
    $double4 = Closure::fromCallable('double_function');

    // Hier wird das Closure als Callback verwendet, um
    // die Größe jedes Elements unseres Bereichs zu verdoppeln
    $new_numbers = array_map($double1, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double2, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double3, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double4, range(1, 5));
    print implode(' ', $new_numbers);

    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.1 folgende Ausgabe:

    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10

Ein Callable kann auch ein String sein, der den Namen einer Funktion oder einer statischen Methode enthält. Jede eingebaute oder benutzerdefinierte Funktion kann verwendet werden, außer Sprachkonstrukten wie: array(), echo, empty(), eval(), isset(), list(), print oder unset().

Statische Klassenmethoden können verwendet werden, ohne dass ein Object dieser Klasse instantiiert werden muss, indem entweder ein Array mit dem Klassennamen an Index 0 und dem Methodennamen an Index 1 erstellt wird, oder indem die spezielle Syntax mit dem Bereichsauflösungsoperator `::` wie in `'ClassName::methodName'` verwendet wird.

Eine Methode eines instantiierten Objects kann ein Callable sein, wenn sie als Array mit dem Object an Index 0 und dem Methodennamen an Index 1 angegeben wird.

Der Hauptunterschied zwischen einem Closure-Objekt und dem Typ callable besteht darin, dass ein Closure-Objekt unabhängig vom Geltungsbereich ist und immer aufgerufen werden kann, während ein Callable-Typ vom Geltungsbereich abhängig sein kann und möglicherweise nicht direkt aufgerufen werden kann. Closure ist die bevorzugte Art, Callables zu erstellen.

> Hinweis: Während Closure-Objekte an den Geltungsbereich gebunden sind, in dem sie erstellt werden, werden Callables, die Klassenmethoden als Strings oder Arrays referenzieren, in dem Geltungsbereich aufgelöst, in dem sie aufgerufen werden. Um aus einer privaten oder geschützten Methode ein Callable zu erstellen, das dann von außerhalb des Geltungsbereichs der Klasse aufgerufen werden kann, verwenden Sie Closure::fromCallable() oder die Syntax für Callbacks als Objekte erster Klasse.

PHP erlaubt die Erstellung von Callables, die als Callback-Argument verwendet, aber nicht direkt aufgerufen werden können. Dabei handelt es sich um kontextabhängige Callables, die eine Klassenmethode in der Vererbungshierarchie einer Klasse referenzieren, zum Beispiel `'parent::method'` oder `["static", "method"]`.

> Hinweis: Seit PHP 8.2.0 sind kontextabhängige Callables veraltet. Entfernen Sie die Kontextabhängigkeit, indem Sie `'parent::method'` durch `parent::class . '::method'` ersetzen, oder verwenden Sie die Syntax für Callbacks als Objekte erster Klasse.

Beispiel #2 Verschiedene Arten von Callables mit call_user_function() aufrufen

    <?php

    // Eine Beispiel-Callback-Funktion
    function my_callback_function() {
        echo 'hello world!', PHP_EOL;
    }

    // Eine Beispiel-Callback-Methode
    class MyClass {
        static function myCallbackMethod() {
            echo 'Hello World!', PHP_EOL;
        }
    }

    // Typ 1: Einfaches Callback
    call_user_func('my_callback_function');

    // Typ 2: Statischer Methodenaufruf
    call_user_func(['MyClass', 'myCallbackMethod']);

    // Typ 3: Aufruf einer Objektmethode
    $obj = new MyClass();
    call_user_func([$obj, 'myCallbackMethod']);

    // Typ 4: Statischer Methodenaufruf
    call_user_func('MyClass::myCallbackMethod');

    // Typ 5: Statischer Methodenaufruf mit dem Schlüsselwort ::class
    call_user_func([MyClass::class, 'myCallbackMethod']);

    // Typ 6: Relativer statischer Methodenaufruf
    class A {
        public static function who() {
            echo 'A', PHP_EOL;
        }
    }

    class B extends A {
        public static function who() {
            echo 'B', PHP_EOL;
        }
    }

    call_user_func(['B', 'parent::who']); // seit PHP 8.2.0 veraltet

    // Typ 7: Objekte die __invoke implementieren können als Callable verwendet werden
    class C {
        public function __invoke($name) {
            echo 'Hello ', $name;
        }
    }

    $c = new C();
    call_user_func($c, 'PHP!');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    hello world!
    Hello World!
    Hello World!
    Hello World!
    Hello World!

    Deprecated: Callables of the form ["B", "parent::who"] are deprecated in script on line 41
    A
    Hello PHP!

> Hinweis:

> Callbacks, die für Funktionen wie call_user_func() und call_user_func_array() registriert sind, werden nicht mehr ausgeführt, wenn in einem vorherigen Callback eine Exception geworfen und nicht gefangen wurde.

## Mixed

Der Typ mixed kann jeden Wert annehmen. Er ist äquivalent zum Union-Typ `object|resource|array|string|float|int|bool|null`. Verfügbar seit PHP 8.0.0.

Im Sprachgebrauch der Typentheorie ist mixed der Top-Typ. Das bedeutet, dass jeder andere Typ ein Untertyp von ihm ist.

## Void

void ist eine reine Rückgabedeklaration, die anzeigt, dass die Funktion keinen Wert zurückgibt, aber trotzdem beendet werden kann. Daher kann es nicht Teil der Deklaration eines Union-Typs sein. Verfügbar seit PHP 7.1.0.

> Hinweis: Auch wenn eine Funktion den Rückgabetyp void hat, gibt sie einen Wert zurück, und dieser Wert ist immer `null`.

## Never

never ist ein reiner Rückgabetyp, der anzeigt, dass die Funktion nicht beendet wird. Das bedeutet, dass sie entweder exit() aufruft, eine Ausnahme wirft oder eine Endlosschleife ist. Daher kann er nicht Teil einer Union-Typ-Deklaration sein. Verfügbar seit PHP 8.1.0.

Im Sprachgebrauch der Typentheorie ist never der unterste Typ. Das bedeutet, dass er der Untertyp jedes anderen Typs ist und bei der Vererbung jeden anderen Rückgabetyp ersetzen kann.

## Relative Klassentypen

Diese Typdeklarationen können nur innerhalb von Klassen verwendet werden.

### self

Der Wert muss ein `instanceof` derselben Klasse sein wie die, in der die Typdeklaration verwendet wird.

### parent

Der Wert muss ein `instanceof` einer Elternklasse der Klasse sein, in der die Typdeklaration verwendet wird.

### static

static ist ein reiner Rückgabetyp, bei dem der zurückgegebene Wert ein `instanceof` derselben Klasse sein muss wie die, in der die Methode aufgerufen wird. Verfügbar seit PHP 8.0.0.

## Singleton-Typen

Singleton-Typen sind Typen, die nur einen Wert akzeptieren. PHP unterstützt zwei Singleton-Typen: false seit PHP 8.0.0 und true seit PHP 8.2.0.

Warnung

Vor PHP 8.2.0 konnte der Typ false nur als Teil eines Union-Typs verwendet werden.

> Hinweis: Es ist nicht möglich, eigene Singleton-Typen zu definieren. Stattdessen sollte in einem solchen Fall eventuell eine Aufzählung verwendet werden.

## Iterable

Iterable ist ein eingebauter Kompilierzeit-Alias für `array|Traversable`. Dieser Typ wurde in PHP 7.1.0 eingeführt. Bis vor PHP 8.2.0 war iterable ein eingebauter Pseudo-Typ, der als der oben erwähnte Typ-Alias fungierte und als Typdeklaration verwendet werden kann. Ein iterable-Typ kann in `foreach` und in Verbindung mit yield from innerhalb eines Generators verwendet werden.

> Hinweis:

> Funktionen, die iterable als Rückgabetyp deklarieren, können auch Generatoren sein.

> Beispiel #1 Beispiel für einen Generator mit iterable als Rückgabetyp

>     <?php

>     function gen(): iterable {
>         yield 1;
>         yield 2;
>         yield 3;
>     }

>     foreach(gen() as $value) {
>         echo $value, "\n";
>     }
>     ?>

## Typdeklarationen

Typen können für Funktionsargumente, Rückgabewerte, seit PHP 7.4.0 für Klasseneigenschaften und seit PHP 8.3.0 für Klassenkonstanten deklariert werden. Dadurch wird sichergestellt, dass der Wert zum Zeitpunkt des Aufrufs vom angegebenen Typ ist und andernfalls ein TypeError geworfen.

Mit Ausnahme des Typs resource können alle von PHP unterstützten Typen in einer benutzerdefinierten Typdeklaration verwendet werden. Diese Seite enthält eine Changelog über die Verfügbarkeit der verschiedenen Typen und eine Dokumentation über ihre Verwendung in Typdeklarationen.

> Hinweis:

> Wenn eine Klasse eine Methode einer Schnittstelle implementiert oder eine Methode neu implementiert, die bereits von der Elternklasse definiert wurde, muss sie mit der obigen Definition kompatibel sein. Eine Methode ist kompatibel, wenn sie den Regeln der Kovarianz und Kontravarianz folgt.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Unterstützung für die Typisierung von Klassen-, Interface-, Trait- und Enum-Konstanten wurde hinzugefügt.
8.2.0 | Unterstützung für DNF-Typen wurde hinzugefügt.
8.2.0 | Unterstützung für den literalen Typ true wurde hinzugefügt.
8.2.0 | Die Typen null und false können nun eigenständig verwendet werden.
8.1.0 | Unterstützung für Schnittmengentypen wurde hinzugefügt.
8.1.0 | Die Rückgabe per Referenz aus einer void-Funktion ist nun veraltet.
8.1.0 | Unterstützung für den Rückgabetyp never wurde hinzugefügt.
8.0.0 | Unterstützung für mixed wurde hinzugefügt.
8.0.0 | Unterstützung für den reinen Rückgabetyp static wurde hinzugefügt.
8.0.0 | Unterstützung für Union-Typen wurde hinzugefügt.
7.4.0 | Unterstützung für die Typisierung von Klasseneigenschaften wurde hinzugefügt.
7.2.0 | Unterstützung für object wurde hinzugefügt.
7.1.0 | Unterstützung für iterable wurde hinzugefügt.
7.1.0 | Unterstützung für void wurde hinzugefügt.
7.1.0 | Unterstützung für nullable Typen wurde hinzugefügt.

### Hinweise zur Verwendung von atomaren (einfachen) Typen

Atomare Typen verhalten sich einfach, wobei es einige kleinere Einschränkungen gibt, auf die in diesem Abschnitt eingegangen wird.

#### Skalare Typen

Warnung

Namens-Aliase für skalare Typen (bool, int, float, string) werden nicht unterstützt. Stattdessen werden sie wie die Namen von Klassen oder Schnittstellen behandelt. Wird zum Beispiel `boolean` als Typdeklaration verwendet, muss der Wert ein `instanceof` der Klasse oder Schnittstelle `boolean` sein, und nicht vom Typ bool:

    <?php
        function test(boolean $param) {}
        test(true);
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2

    Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
    Stack trace:
    #0 -(3): test(true)
    #1 {main}
      thrown in - on line 2

#### void

> Hinweis:

> Die Rückgabe per Referenz aus einer Funktion, die void zurückgibt, ist seit PHP 8.1.0 veraltet, da eine solche Funktion widersprüchlich ist. Vor PHP 8.1.0 gab sie bereits folgende `E_NOTICE` aus, wenn sie aufgerufen wurde: Only variable references should be returned by reference.

>     <?php
>     function &test(): void {}
>     ?>

#### Callable

Dieser Typ kann nicht als Typdeklaration für die Eigenschaft einer Klasse verwendet werden.

> Hinweis: Es ist nicht möglich, eine Signatur für die Funktion anzugeben.

#### Typdeklarationen für Parameter, die per Referenz übergeben werden

Wenn ein per Referenz übergebener Parameter eine Typdeklaration hat, wird der Typ der Variablen nur beim Eintritt in die Funktion, zu Beginn des Aufrufs, überprüft, nicht aber bei der Rückgabe der Funktion. Das bedeutet, dass eine Funktion den Typ einer Variablenreferenz ändern kann.

Beispiel #1 Typisierte Parameter, die per Referenz übergeben werden

    <?php
    function array_baz(array &$param)
    {
        $param = 1;
    }
    $var = [];
    array_baz($var);
    var_dump($var);
    array_baz($var);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(1)

    Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
    Stack trace:
    #0 -(9): array_baz(1)
    #1 {main}
      thrown in - on line 2

### Hinweise zur Verwendung von zusammengesetzten Typen

Bei der Deklaration von zusammengesetzten Typen gibt es mehrere Einschränkungen und um einfache Fehler zu vermeiden, wird bei der Kompilierung eine Redundanzprüfung durchgeführt.

Achtung

Vor PHP 8.2.0, d. h. vor der Einführung von DNF-Typen, war es nicht möglich, Schnittmengentypen (Intersection-Typen) mit zusammengefassten Typen (Union-Typen) zu kombinieren.

#### Zusammengefasste Typen (Union-Typen)

Warnung

Es ist nicht möglich, die beiden Singleton-Typen false und true in einem Union-Typ zu kombinieren; stattdessen kann bool verwendet werden.

Achtung

Da false und null vor PHP 8.2.0 nicht als eigenständige Typen verwendet werden konnten, war ein Union-Typ, der nur aus diesen Typen bestand, nicht erlaubt. Hierbei handelt es sich um die folgenden Typen: false, `false|null` und `?false`.

##### Syntaktischer Zucker für den Typ nullable

Wenn ein einzelner Basistyp deklariert wird, kann dieser als nullable gekennzeichnet werden, indem dem Typnamen ein Fragezeichen (`?`) vorangestellt wird. Somit bedeuten `?T` und `T|null` dasselbe.

> Hinweis: Diese Syntax wird seit PHP 7.1.0 unterstützt und geht der Unterstützung von allgemeinen Union-Typen voraus.

> Hinweis:

> Es ist auch möglich, nullable Parameter anzugeben, indem `null` zum Standardwert gemacht wird. Dies ist jedoch nicht empfehlenswert, denn wenn der Standardwert in einer Kindklasse geändert wird, wird eine Verletzung der Typkompatibilität ausgelöst, da der Typ null zur Typdeklaration hinzugefügt werden muss. Darüber hinaus ist dieses Verhalten seit PHP 8.4 veraltet.

> Beispiel #2 Die alte Methode, um Parameter nullable zu machen

>     <?php
>     class C {}

>     function f(C $c = null) {
>         var_dump($c);
>     }

>     f(new C);
>     f(null);
>     ?>

> Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

>     object(C)#1 (0) {
>     }
>     NULL

#### Doppelte und redundante Typen

Um einfache Fehler in Deklarationen von zusammengesetzten Typen abzufangen, führen redundante Typen, die ohne Laden einer Klasse erkannt werden können, zu einem Fehler beim Kompilieren. Dies schließt Folgendes ein:

- Jeder Typ, dessen Name aufgelöst wird, darf nur einmal vorkommen. Typen wie `int|string|INT` oder `Countable&Traversable&COUNTABLE` führen zu einem Fehler.
- Die Verwendung des Typs mixed oder never führt zu einem Fehler.
- Bei zusammengesetzen Typen:
  - Wenn der Typ bool verwendet wird, können nicht zusätzlich die Typen false oder true verwendet werden.
  - Wenn der Typ object verwendet wird, können nicht zusätzlich Klassentypen verwendet werden.
  - Wenn der Typ iterable verwendet wird, können nicht zusätzlich array und Traversable verwendet werden.
- Bei Schnittmengentypen:
  - Die Verwendung eines Typs, der kein Klassentyp ist, führt zu einem Fehler.
  - Die Verwendung von self, parent oder static führt zu einem Fehler.
- Bei DNF-Typen:
  - Wenn ein allgemeinerer Typ verwendet wird, ist der restriktivere Typ überflüssig.
  - Die Verwendung zweier identischer Schnittmengentypen.

> Hinweis: Dies garantiert nicht, dass der Typ "minimal" ist, weil dies bedeuten würde, dass alle verwendeten Klassentypen geladen werden müssten.

Wenn zum Beispiel `A` und `B` Aliase von Klassen sind, dann bleibt `A|B` ein gültiger Union-Typ, auch wenn er entweder auf `A` oder `B` reduziert werden könnte. Bei `B extends A {}` ist `A|B` ebenfalls ein gültiger Union-Typ, auch wenn er auf `A` reduziert werden kann.

    <?php
    function foo(): int|INT {} // Unzulässig
    function foo(): bool|false {} // Unzulässig
    function foo(): int&Traversable {} // Unzulässig
    function foo(): self&Traversable {} // Unzulässig

    use A as B;
    function foo(): A|B {} // Unzulässig ("use" ist Teil der Namensauflösung)
    function foo(): A&B {} // Unzulässig ("use" ist Teil der Namensauflösung)

    class_alias('X', 'Y');
    function foo(): X|Y {} // Zulässig (Redundanz ist nur zur Laufzeit bekannt)
    function foo(): X&Y {} // Zulässig (Redundanz ist nur zur Laufzeit bekannt)
    ?>

### Beispiele

Beispiel #3 Grundlegendes Beispiel für die Deklaration eines Klassentyps

    <?php
    class C {}
    class D extends C {}

    // Das erweitert C nicht.
    class E {}

    function f(C $c) {
        echo get_class($c)."\n";
    }

    f(new C);
    f(new D);
    f(new E);
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    C
    D

    Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
    Stack trace:
    #0 -(14): f(Object(E))
    #1 {main}
      thrown in - on line 8

Beispiel #4 Grundlegendes Beispiel für die Deklaration eines Schnittstellentyps

    <?php
    interface I { public function f(); }
    class C implements I { public function f() {} }

    // Das implementiert I nicht.
    class E {}

    function f(I $i) {
        echo get_class($i)."\n";
    }

    f(new C);
    f(new E);
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    C

    Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8
    Stack trace:
    #0 -(13): f(Object(E))
    #1 {main}
      thrown in - on line 8

Beispiel #5 Grundlegendes Beispiel für die Deklaration eines Rückgabetyps

    <?php
    function sum($a, $b): float {
        return $a + $b;
    }

    // Hier wird ein Gleitkommawert zurückgegeben.
    var_dump(sum(1, 2));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(3)

Beispiel #6 Zurückgeben eines Objekts

    <?php
    class C {}

    function getC(): C {
        return new C;
    }

    var_dump(getC());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(C)#1 (0) {
    }

Beispiel #7 Deklaration eines nulllable Parameters

    <?php
    class C {}

    function f(?C $c) {
        var_dump($c);
    }

    f(new C);
    f(null);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(C)#1 (0) {
    }
    NULL

Beispiel #8 Deklaration eines nulllable Rückgabetyps

    <?php
    function get_item(): ?string {
        if (isset($_GET['item'])) {
            return $_GET['item'];
        } else {
            return null;
        }
    }
    ?>

Beispiel #9 Deklaration eines Klasseneigenschafts-Typs

    <?php
    class User {
        public static string $foo = 'foo';

        public int $id;
        public string $username;

        public function __construct(int $id, string $username) {
            $this->id = $id;
            $this->username = $username;
        }
    }
    ?>

### Strikte Typisierung

Standardmäßig wandelt PHP Werte eines falschen Typs automatisch in den erwarteten Typ um, wenn dies möglich ist. Wenn an eine Funktion zum Beispiel ein Wert vom Typ int für einen Parameter übergeben wird, der einen Wert vom Typ string erwartet, dann erhält die Funktion eine Variable vom Typ string.

Der strikte Modus kann auf Dateibasis aktiviert werden. Im strikten Modus wird nur ein Wert akzeptiert, der genau der Typdeklaration entspricht, andernfalls wird ein TypeError geworfen. Die einzige Ausnahme von dieser Regel ist die Übergabe eines int-Wertes, wenn ein float-Wert erwartet wird.

Warnung

Funktionsaufrufe innerhalb interner Funktionen sind von der `strict_types`-Deklaration nicht betroffen.

Um den strikten Modus zu aktivieren, wird die `declare`-Anweisung zusammen mit der `strict_types`-Deklaration verwendet:

> Hinweis:

> Strikte Typisierung gilt für Funktionsaufrufe, die innerhalb einer Datei mit aktivierter strikter Typisierung gemacht werden, nicht für die Funktionen, die innerhalb dieser Datei deklariert sind. Wenn eine Funktion, die in einer Datei mit strikter Typisierung definiert ist, aus einer Datei aufgerufen wird, in der die strikte Typisierung nicht aktiviert ist, wird die Präferenz des Aufrufers (automatische Umwandlung des Typs, coercive typing) berücksichtigt und der Wert wird typkonvertiert.

> Hinweis:

> Die strikte Typisierung ist nur für skalare Typdeklarationen definiert.

Beispiel #10 Strikte Typisierung für die Werte von Argumenten

    <?php
    declare(strict_types=1);

    function sum(int $a, int $b) {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1.5, 2.5));
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    int(3)

    Fatal error: Uncaught TypeError: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4
    Stack trace:
    #0 -(9): sum(1.5, 2.5)
    #1 {main}
      thrown in - on line 4

Beispiel #11 Erzwungene Typisierung für die Werte von Argumenten

    <?php
    function sum(int $a, int $b) {
        return $a + $b;
    }

    var_dump(sum(1, 2));

    // Diese werden in Ganzzahlen umgewandelt: man beachte die folgende Ausgabe!
    var_dump(sum(1.5, 2.5));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(3)
    int(3)

Beispiel #12 Strikte Typisierung für Rückgabewerte

    <?php
    declare(strict_types=1);

    function sum($a, $b): int {
        return $a + $b;
    }

    var_dump(sum(1, 2));
    var_dump(sum(1, 2.5));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(3)

    Fatal error: Uncaught TypeError: sum(): Return value must be of type int, float returned in -:5
    Stack trace:
    #0 -(9): sum(1, 2.5)
    #1 {main}
      thrown in - on line 5

## Typumwandlung (Typen-Jonglage)

PHP verlangt in der Variablendeklaration keine explizite Typdefinition. Der Typ einer Variablen wird in diesem Fall durch den Wert bestimmt, der in ihr gespeichert wird. Das heißt, wenn der Variable $var der Typ string zugewiesen wird, dann ist $var vom Typ string. Wenn $var anschließend ein Wert vom Typ int zugewiesen wird, ist sie vom Typ int.

PHP kann je nach Kontext versuchen, den Typ eines Wertes automatisch in einen anderen umzuwandeln. Folgende Kontexte gibt es:

- Numerisch
- Zeichenkette
- Logisch
- Ganzzahlig und Zeichenkette
- Vergleichend
- Funktion

> Hinweis: Wenn ein Wert als ein anderer Typ interpretiert werden muss, wird der Typ des Wertes selbst nicht geändert.

Um zu erzwingen, dass eine Variable als ein bestimmter Typ ausgewertet wird, siehe den Abschnitt über Explizite Typumwandlung (Type-Casting). Um den Typ einer Variablen zu ändern, siehe die Funktion settype().

### Numerischer Kontext

Dieser Kontext liegt vor, wenn ein arithmetischer Operator verwendet wird.

Wenn in diesem Kontext einer der beiden Operanden vom Typ float ist (oder nicht als Int interpretiert werden kann), werden beide Operanden als Floats interpretiert, und das Ergebnis ist vom Typ float. Andernfalls werden die Operanden als Ints interpretiert, und das Ergebnis ist ebenfalls vom Typ int. Wenn einer der Operanden nicht interpretiert werden kann, wird seit PHP 8.0.0 ein TypeError geworfen.

### Zeichenketten-Kontext

Dieser Kontext liegt vor, wenn echo, print, Zeichenketten-Interpolation, oder der Verkettungsoperator für Zeichenketten verwendet werden.

In diesem Kontext wird der Wert als String interpretiert. Wenn der Wert nicht interpretiert werden kann, wird ein TypeError geworfen. Vor PHP 7.4.0 wurde ein `E_RECOVERABLE_ERROR` ausgelöst.

### Logischer Kontext

Dieser Kontext liegt vor, wenn bedingte Anweisungen, der ternäre Operator oder ein logischer Operator verwendet werden.

In diesem Kontext wird der Wert als Bool interpretiert.

### Kontext für ganzzahlige Werte und Zeichenketten

Dieser Kontext liegt vor, wenn bitweise Operatoren verwendet werden.

Wenn in diesem Kontext alle Operanden vom Typ string sind, ist auch das Ergebnis vom Typ string. Andernfalls werden die Operanden als Ints interpretiert, und das Ergebnis ist ebenfalls vom Typ int. Wenn einer der Operanden nicht interpretiert werden kann, wird seit PHP 8.0.0 ein TypeError geworfen.

### Vergleichender Kontext

Dieser Kontext liegt vor, wenn ein Vergleichsoperator verwendet wird.

Die in diesem Zusammenhang auftretenden Typumwandlungen werden in der Tabelle Vergleich mit verschiedenen Typen erläutert.

### Funktionskontext

Dieser Kontext liegt vor, wenn ein Wert an einen typisierten Parameter oder eine Eigenschaft übergeben oder von einer Funktion zurückgegeben wird, die einen Rückgabetyp deklariert.

In diesem Kontext muss der Wert ein Wert dieses Typs sein. Hiervon gibt es zwei Ausnahmen. Die Erste: Wenn der Wert vom Typ int ist und der deklarierte Typ ist float, dann wird die Ganzzahl in eine Gleitkommazahl umgewandelt. Die Zweite: Wenn der deklarierte Typ ein skalarer Typ ist, der Wert in einen skalaren Typ umgewandelt werden kann und der Modus der zwangsweisen Typisierung aktiv ist (Standard), kann der Wert in einen akzeptierten skalaren Wert umgewandelt werden. Siehe unten für eine Beschreibung dieses Verhaltens.

Warnung

Interne Funktionen wandeln `null` automatisch in skalare Typen um. Dieses Verhalten ist seit PHP 8.1.0 DEPRECATED (veraltet).

#### Automatische Typisierung mit einfachen Typdeklarationen

- Deklaration des Typs bool: Der Wert wird als bool interpretiert.
- Deklaration des Typs int: Der Wert wird als int interpretiert, wenn die Umwandlung wohldefiniert ist, z. B. wenn die Zeichenkette numerisch ist.
- Deklaration des Typs float: Der Wert wird als float interpretiert, wenn die Umwandlung wohldefiniert ist, z. B. wenn die Zeichenkette numerisch ist.
- Deklaration des Typs string: Der Wert wird als string interpretiert.

#### Automatische Typisierung mit Union-Typen

Wenn `strict_types` nicht aktiviert ist, unterliegen skalare Typdeklarationen einer begrenzten impliziten Typumwandlung. Wenn der genaue Typ des Wertes nicht Teil der Union ist, wird der Zieltyp in der folgenden Reihenfolge gewählt:

1. int
2. float
3. string
4. bool

Wenn der Typ in der Union existiert und der Wert gemäß der PHP-Semantik zur Typüberprüfung in diesen Typ umgewandelt werden kann, wird dieser Typ ausgewählt. Andernfalls wird der nächste Typ geprüft.
Achtung

Wenn es sich bei dem Wert um eine Zeichenkette handelt und sowohl int als auch float Teil der Union sind, wird der bevorzugte Typ durch die bestehende Semantik numerischer Zeichenketten bestimmt. Zum Beispiel wird für `"42"` int gewählt, während für `"42.0"` float gewählt wird.

> Hinweis:

> Typen, die nicht in der obigen Präferenzliste aufgeführt sind, kommen als Ziele für implizite Umwandlungen nicht in Frage. Insbesondere gibt es keine impliziten Umwandlungen in die Typen null, false und true.

Beispiel #1 Beispiel für Typen, die in einen Typ umgewandelt werden, der Teil einer Union ist

    <?php
    // int|string
    42    --> 42          // exakter Typ
    "42"  --> "42"        // exakter Typ
    new ObjectWithToString --> "Result of __toString()"
                          // object nicht kompatibel mit int, greift auf string zurück
    42.0  --> 42          // float kompatibel mit int
    42.1  --> 42          // float kompatibel mit int
    1e100 --> "1.0E+100"  // float zu groß für Typ int, greift auf string zurück
    INF   --> "INF"       // float zu groß für Typ int, greift auf string zurück
    true  --> 1           // bool kompatibel mit int
    []    --> TypeError   // array nicht kompatibel mit int oder string

    // int|float|bool
    "45"    --> 45        // Zeichenkette im numerischen Format für int
    "45.0"  --> 45.0      // Zeichenkette im numerischen Format für float

    "45X"   --> true      // keine numerische Zeichenkette, greift auf bool zurück
    ""      --> false     // keine numerische Zeichenkette, greift auf bool zurück
    "X"     --> true      // keine numerische Zeichenkette, greift auf bool zurück
    []      --> TypeError // array nicht kompatibel mit int, float oder bool
    ?>

### Explizite Typumwandlung (Type-Casting)

Typ-Casting wandelt den Wert in einen bestimmten Typ um, indem der Typ in Klammern vor den umzuwandelnden Wert geschrieben wird.

Beispiel #2 Typumwandlung

    <?php
    $foo = 10;          // $foo ist ein Integer
    $bar = (bool) $foo; // $bar ist ein Boolean

    var_dump($bar);
    ?>

Folgende Umwandlungen sind erlaubt:

- `(int)` - Umwandlung in int
- `(bool)` - Umwandlung in bool
- `(float)` - Umwandlung in float
- `(string)` - Umwandlung in string
- `(array)` - Umwandlung in array
- `(object)` - Umwandlung in object
- `(unset)` - Umwandlung in NULL

> Hinweis:

> `(integer)` ist ein Alias des `(int)`-Casts. `(boolean)` ist ein Alias des `(bool)`-Casts. `(binary)` ist ein Alias des `(string)`-Casts. `(double)` und `(real)` sind Aliase des `(float)`-Casts. Da diese Casts nicht den kanonischen Typnamen verwenden, werden sie nicht empfohlen.

Warnung

Der Cast-Alias `(real)` ist seit PHP 7.4.0 veraltet und wurde in PHP 8.0.0 entfernt.

Warnung

Der `(unset)`-Cast ist seit PHP 7.2.0 veraltet und wurde in PHP 8.0.0 entfernt. Es ist zu beachten, dass der `(unset)`-Cast gleichbedeutend ist mit der Zuweisung des Wertes NULL an eine Variable oder einen Aufruf.

Achtung

Der `(binary)`-Cast und das Präfix `b` existieren im Hinblick auf zukünftige Versionen. Derzeit sind `(binary)` und `(string)` identisch, aber weil sich dies in Zukunft ändern könnte, sollte man sich nicht darauf verlassen.

> Hinweis:

> Leerzeichen werden innerhalb der Klammern eines Casts ignoriert, weshalb die beiden folgenden Ausdrücke gleichwertig sind:

>     <?php
>     $foo = (int) $bar;
>     $foo = ( int ) $bar;
>     ?>

Umwandlung literaler Strings und Variablen in binäre Strings:

    <?php
    $binary = (binary) $string;
    $binary = b"binary string";
    ?>

Anstatt eine Variable in einen String umzuwandeln, kann die Variable auch in doppelte Anführungszeichen gesetzt werden.

Beispiel #3 Verschiedene Casting-Mechanismen

    <?php
    $foo = 10;            // $foo ist eine ganze Zahl
    $str = "$foo";        // $str ist eine Zeichenkette
    $fst = (string) $foo; // $fst ist ebenfalls eine Zeichenkette

    // Dies gibt aus "sie sind identisch"
    if ($fst === $str) {
        echo "sie sind identisch", PHP_EOL;
    }
    ?>

In den folgenden Abschnitten wird beschrieben, was genau passiert, wenn zwischen bestimmten Typen umgewandelt wird:

- Umwandlung in boolean
- Umwandlung in integer
- Umwandlung in float
- Umwandlung in string
- Umwandlung in array
- Umwandlung in ein Objekt
- Umwandlung in eine Ressource
- Umwandlung in NULL
- Die Tabellen zu Typenvergleichen

> Hinweis: Da Strings in PHP mit derselben Syntax wie Arrays über Offsets indiziert werden können, gilt das folgende Beispiel für alle PHP-Versionen:

> Beispiel #4 Verwenden des Array-Offsets bei einer Zeichenkette

>     <?php
>     $a    = 'car'; // $a ist eine Zeichenkette
>     $a[0] = 'b';   // $a ist immer noch eine Zeichenkette
>     echo $a;       // bar
>     ?>

> Weitere Informationen sind im Abschnitt Zugriff auf Zeichen in einem String zu finden.

# Variablen

## Inhaltsverzeichnis

- Grundlegendes
- Vordefinierte Variablen
- Geltungsbereich von Variablen
- Variable Variablen
- Variablen aus externen Quellen

## Grundlegendes

Variablen werden in PHP durch ein Dollar-Zeichen ($) gefolgt vom Namen der Variable dargestellt. Bei Variablennamen wird zwischen Groß- und Kleinschreibung unterschieden (case-sensitive).

Ein gültiger Variablenname beginnt mit einem Buchstaben (`A-Z`, `a-z` oder die Bytes von 128 bis 255) oder einem Unterstrich ("_"), gefolgt von einer beliebigen Anzahl von Buchstaben, Zahlen oder Unterstrichen. Als regulärer Ausdruck (Regular Expression) würde das wie folgt ausgedrückt: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

> Hinweis: PHP unterstützt keine Unicode-Variablennamen, aber einige Zeichenkodierungen (z. B. UTF-8) kodieren Zeichen so, dass alle Bytes eines Multi-Byte-Zeichens in den erlaubten Bereich fallen und somit einen gültigen Variablennamen darstellen.

> Hinweis: `$this` ist eine spezielle Variable, die nicht geändert werden kann. Vor PHP 7.1.0 war die indirekte Zuweisung, z. B. durch die Verwendung von variable Variablen, möglich.

Tipp

Siehe auch Userland-Namensregeln.

Beispiel #1 Gültige Variablennamen

    <?php
    $var = "du";
    $Var = "ich";
    echo "$var, $Var";       // gibt "du, ich" aus

    $_4site = 'noch nicht';  // gültig, da Unterstrich am Anfang
    $täbyte = 'irgendwas';   // gültig, da 'ä' dem (Erweiterten) ASCII-Wert 228 entspricht
    ?>

Beispiel #2 Ungültige Variablennamen

    <?php
    $4site = 'noch nicht';     // ungültig, da Anfang eine Zahl

PHP akzeptiert eine Folge von beliebigen Bytes als Variablennamen. Auf Variablennamen, die nicht den oben genannten Benennungsregeln entsprechen, kann nur dynamisch zur Laufzeit zugegriffen werden. Siehe variable Variablen für Informationen, wie man auf sie zugreifen kann.

Beispiel #3 Zugriff auf unklare Variablennamen

    <?php
    ${'ungueltiger-name'} = 'bar';
    $name = 'ungueltiger-name';
    echo ${'ungueltiger-name'}, " ", $$name;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bar bar

Standardmäßig wird Variablen immer ein Wert zugewiesen. Das heißt, wenn einer Variablen ein Ausdruck zugewiesen wird, wird der gesamte Inhalt des Originalausdrucks in die Zielvariable kopiert. Das bedeutet zum Beispiel, dass nach der Zuweisung des Wertes einer Variablen an eine andere die Änderung einer der Variablen keinen Einfluss auf die andere hat. Für weitere Informationen zu dieser Art der Zuordnung lesen Sie bitte das Kapitel unter Expressions / Ausdrücke.

PHP bietet eine andere Möglichkeit der Wertzuweisung bei Variablen: Zuweisung durch Referenzierung. Das bedeutet, dass der Wert der neuen Variablen eine Referenz zur Ursprungs-Variablen darstellt (mit anderen Worten: Der Wert ist ein Alias bzw. Zeiger auf den Inhalt der Ursprungsvariablen). Änderungen der neuen Variablen ändern auch deren Ursprungs-Variable und umgekehrt.

Für die Zuweisung per Referenz müssen Sie der Ursprungsvariablen, die Sie einer anderen Variablen zuweisen wollen, lediglich ein kaufmännisches Und (&) voranstellen. Das folgende Code-Schnipsel wird zweimal '`Ich heiße Bob`' ausgeben:

    <?php
    $foo = 'Bob';             // 'Bob' der Variablen $foo zuweisen.
    $bar = &$foo;             // $foo per $bar referenzieren.
    $bar = "Ich heiße $bar";  // $bar verändern...
    echo $bar;
    echo $foo;                 // $foo wurde ebenfalls verändert.
    ?>

Zu beachten ist, dass nur Variablen referenziert werden können.

    <?php
    $foo = 25;
    $bar = &$foo;      // Gültige Zuweisung.
    $bar = &(24 * 7);  // Ungültig, da ein unbenannter Ausdruck referenziert wird.

    function test()
    {
        return 25;
    }

    $bar = &test();    // Ungültig, da test() keine Variable per Referenz zurückgibt.
    ?>

Es ist in PHP nicht notwendig, Variablen zu deklarieren, aber es wird empfohlen. Der Versuch, auf eine undefinierte Variable zuzugreifen, führt zu einem Fehler der Stufe `E_WARNING` (vor PHP 8.0.0, `E_NOTICE`). Eine undefinierte Variable hat den Standardwert `null`. Um zu prüfen, ob eine Variable bereits initialisiert wurde, kann das Sprachkonstrukt isset() verwendet werden.

Beispiel #4 Vorgabewert einer nicht initialisierten Variable

    <?php
    // Nicht gesetzte UND nicht referenzierte (kein Verwendungskontext) Variable.
    var_dump($unset_var);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Warning: Undefined variable $unset_var in ...
    NULL

PHP erlaubt die Autovivifikation von Arrays (automatische Erstellung neuer Arrays) aus einer undefinierten Variable. Das Anhängen eines Elements an eine undefinierte Variable erzeugt ein neues Array und führt nicht zu einer Warnung.

Beispiel #5 Autovivifikation eines Arrays aus einer undefinierten Variable

    <?php
    $unset_array[] = 'value'; // Erzeugt keine Warnung.
    ?>

Warnung

Sich auf den Standardwert einer nicht initialisierten Variablen zu verlassen, ist problematisch, wenn eine Datei in eine andere eingebunden wird, die denselben Variablennamen verwendet.

Eine Variable kann mit dem Sprachkonstrukt unset() gelöscht werden.

Für Informationen zu variablenbezogenen Funktionen siehe Referenz zu Variablenfunktionen.

## Vordefinierte Variablen

PHP bietet eine Reihe vordefinierter Variablen. Darüber hinaus bietet PHP eine Reihe zusätzlicher vordefinierter Arrays, die Variablen vom Webserver (gegebenenfalls), von der Umgebung und von Benutzereingaben enthalten. Diese Arrays stehen automatisch in jedem Geltungsbereich zur Verfügung. Aus diesem Grund werden sie oft als "Superglobale" bezeichnet. (Es gibt in PHP keinen Mechanismus für benutzerdefinierte Superglobale.) Details hierzu sind unter Liste der Superglobalen zu finden.

> Hinweis: Variable Variablen

> Superglobale können innerhalb von Funktionen und Methoden nicht als variable Variablen verwendet werden.

Falls bestimmte Variablen nicht unter variables_order angegeben sind, dann bleiben auch ihre entsprechenden vordefinierten Arrays leer.

## Geltungsbereich von Variablen

Der Geltungsbereich einer Variablen ergibt sich aus dem Zusammenhang, in dem sie definiert wurde. PHP hat einen Funktionsbereich und einen globalen Bereich. Jede Variable, die außerhalb einer Funktion definiert wird, ist auf den globalen Bereich beschränkt. Wenn eine Datei eingebunden wird, erbt der darin enthaltene Code den Variablenbereich der Zeile, in der die Einbindung erfolgt.

Beispiel #1 Beispiel für den Geltungsbereich globaler Variablen

    <?php
    $a = 1;
    include 'b.inc'; // Die Variable $a wird in b.inc verfügbar sein
    ?>

Jede Variable, die innerhalb einer benannten Funktion oder einer anonymen Funktion erstellt wird, ist auf den Bereich des Funktionskörpers beschränkt. Im Gegensatz dazu binden Pfeilfunktionen Variablen aus dem übergeordneten Bereich, um sie im Körper verfügbar zu machen. Wenn eine Datei innerhalb einer Funktion der aufrufenden Datei eingebunden wird, sind die in der aufgerufenen Datei enthaltenen Variablen so verfügbar, als wären sie innerhalb der aufrufenden Funktion definiert worden.

Beispiel #2 Beispiel für den Geltungsbereich lokaler Variablen

    <?php
    $a = 1; // globaler Geltungsbereich

    function test()
    {
        echo $a; // Die Variable $a ist undefiniert, da sie sich auf eine lokale
                 // Version von $a bezieht
    }
    ?>

Das obige Beispiel erzeugt ein `E_WARNING` wegen einer undefinierten Variable (oder ein E_NOTICE vor PHP 8.0.0). Das liegt daran, dass sich die echo-Anweisung auf eine lokale Variable namens $a bezieht, und dieser kein Wert im lokalen Geltungsbereich zugewiesen wurde. Es ist zu beachten, dass sich dies etwas von C unterscheidet, da in C globale Variablen automatisch für Funktionen zur Verfügung stehen, es sei denn, sie werden durch eine funktionsinterne Definition überschrieben. Dies kann zu Problemen führen, da eine globale Variable versehentlich geändert werden kann. In PHP müssen globale Variablen innerhalb einer Funktionen deklariert werden, wenn sie in dieser Funktion verwendet werden sollen.

### Das Schlüsselwort `global`

Das Schlüsselwort `global` wird verwendet, um eine Variable aus einem globalen Bereich in einen lokalen Bereich zu binden. Das Schlüsselwort kann mit einer Liste von Variablen oder einer einzelnen Variablen verwendet werden. Es wird eine lokale Variable erstellt, die auf die gleichnamige globale Variable verweist. Wenn die globale Variable nicht existiert, wird sie im globalen Bereich erstellt und erhält den Wert `null`.

Beispiel #3 Verwendung von `global`

    <?php
    $a = 1;
    $b = 2;

    function Sum()
    {
        global $a, $b;

        $b = $a + $b;
    }

    Sum();
    echo $b;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3

Durch das Deklarieren der Variablen $a und $b innerhalb der Funktion als global weisen alle Referenzen zu beiden Variablen auf die nun globalen Werte. Es gibt keine Beschränkungen bei der Anzahl an globalen Variablen, die durch eine Funktion verändert werden können.

Eine weitere Möglichkeit, auf Variablen aus dem globalen Bereich zuzugreifen, besteht in der Verwendung des speziellen, von PHP definierten Arrays $GLOBALS. Das obige Beispiel kann damit auch so geschrieben werden:

Beispiel #4 Verwendung von $GLOBALS statt global

    <?php
    $a = 1;
    $b = 2;

    function Sum()
    {
        $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
    }

    Sum();
    echo $b;
    ?>

Das $GLOBALS-Array ist ein assoziatives Array mit dem Namen der globalen Variablen als Schlüssel und dem Inhalt dieser Variablen als Wert des Array-Elements. Beachten Sie, dass $GLOBALS in jedem Geltungsbereich existiert, weil $GLOBALS eine Superglobale ist. Hier ist ein Beispiel, das die Stärke von Superglobalen verdeutlicht:

Beispiel #5 Beispiel zur Demonstration von Superglobalen und Geltungsbereich

    <?php
    function test_superglobal()
    {
        echo $_POST['name'];
    }
    ?>

> Hinweis: Die Verwendung des Schlüsselworts `global` außerhalb einer Funktion ist kein Fehler. Es kann verwendet werden, wenn die Datei innerhalb einer Funktion eingebunden wird.

### Die Verwendung von `static` Variablen

Ein weiterer wichtiger Anwendungszweck von Variablen-Bereichen ist die statische Variable. Eine statische Variable existiert nur in einem lokalen Funktions-Geltungsbereich, der Wert geht beim Verlassen dieses Bereichs aber nicht verloren. Schauen Sie das folgende Beispiel an:

Beispiel #6 Beispiel, das die Notwendigkeit von statischen Variablen demonstriert

    <?php
    function test()
    {
        $a = 0;
        echo $a;
        $a++;
    }
    ?>

Diese Funktion ist sinnlos, da sie bei jedem Aufruf $a auf `0` setzt und `0` ausgibt. Die Anweisung $a++, welche den Wert erhöht, erfüllt keinen Zweck, da der Wert von $a beim Verlassen der Funktion verloren geht. Um eine sinnvolle Zählfunktion zu implementieren, die ihren aktuell gesetzten Wert nicht vergisst, müssen Sie die Variable $a als statisch deklarieren:

Beispiel #7 Beispiel zur Verwendung statischer Variablen

    <?php
    function test()
    {
        static $a = 0;
        echo $a;
        $a++;
    }
    ?>

Nun wird $a nur beim ersten Aufruf der Funktion initialisiert, und jedes mal wenn die Funktion `test()` aufgerufen wird, wird sie den Wert von $a ausgeben und den Variablenwert erhöhen.

Statische Variablen ermöglichen auch einen Weg zum Umgang mit rekursiven Funktionen. Die folgende einfache Funktion zählt rekursiv bis 10. Die statische Variable $count wird verwendet, um die Rekursion zu beenden:

Beispiel #8 Statische Variablen in rekursiven Funktionen

    <?php
    function test()
    {
        static $count = 0;

        $count++;
        echo $count;
        if ($count < 10) {
            test();
        }
        $count--;
    }
    ?>

Vor PHP 8.3.0 konnten statische Variablen nur mit einem konstanten Ausdruck initialisiert werden. Seit PHP 8.3.0 sind auch dynamische Ausdrücke (z. B. Funktionsaufrufe) erlaubt:

Beispiel #9 Statische Variablen deklarieren

    <?php
    function foo(){
        static $int = 0;          // korrekt
        static $int = 1+2;        // korrekt
        static $int = sqrt(121);  // korrekt seit PHP 8.3.0

        $int++;
        echo $int;
    }
    ?>

Statische Variablen innerhalb anonymer Funktionen bleiben nur innerhalb der jeweiligen Funktionsinstanz bestehen. Wenn die anonyme Funktion bei jedem Aufruf neu erstellt wird, wird die statische Variable neu initialisiert.

Beispiel #10 Statische Variablen in anonymen Funktionen

    <?php
    function exampleFunction($input) {
        $result = (static function () use ($input) {
            static $counter = 0;
            $counter++;
            return "Eingabe: $input, Zähler: $counter\n";
        });

        return $result();
    }

    // Bei Aufrufen von exampleFunction wird die anonyme Funktion neu erstellt,
    // so dass die statische Variable ihren Wert nicht beibehält.
    echo exampleFunction('A'); // Ausgabe: Eingabe: A, Zähler: 1
    echo exampleFunction('B'); // Ausgabe: Eingabe: B, Zähler: 1
    ?>

Wenn eine Methode, die statische Variablen verwendet, vererbt (aber nicht überschrieben) wird, teilt die vererbte Methode seit PHP 8.1.0 die statischen Variablen mit der Elternmethode. Das bedeutet, dass sich statische Variablen in Methoden nun genauso verhalten wie statische Eigenschaften.

Seit PHP 8.3.0 können statische Variablen mit beliebigen Ausdrücken initialisiert werden. Das bedeutet, dass z. B. Methodenaufrufe verwendet werden können, um statische Variablen zu initialisieren.

Beispiel #11 Verwendung statischer Variablen in geerbten Methoden

    <?php
    class Foo {
        public static function counter() {
            static $counter = 0;
            $counter++;
            return $counter;
        }
    }
    class Bar extends Foo {}
    var_dump(Foo::counter()); // int(1)
    var_dump(Foo::counter()); // int(2)
    var_dump(Bar::counter()); // int(3), vor PHP 8.1.0 int(1)
    var_dump(Bar::counter()); // int(4), vor PHP 8.1.0 int(2)
    ?>

### Referenzen bei `global` und `static` Variablen

PHP implementiert die Modifikatoren static und global für Variablen als Referenzen. Zum Beispiel erzeugt eine echte globale Variable, die mit der Anweisung `global` in den Funktions-Geltungsbereich importiert wurde, tatsächlich eine Referenz zur globalen Variable. Das kann zu einem unerwarteten Verhalten führen, auf das im folgenden Beispiel eingegangen wird:

    <?php
    function test_global_ref() {
        global $obj;
        $new = new stdClass;
        $obj = &$new;
    }

    function test_global_noref() {
        global $obj;
        $new = new stdClass;
        $obj = $new;
    }

    test_global_ref();
    var_dump($obj);
    test_global_noref();
    var_dump($obj);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL
    object(stdClass)#1 (0) {
    }

Ein ähnliches Verhalten gilt auch für die Anweisung `static`. Referenzen werden nicht statisch gespeichert:

    <?php
    function &get_instance_ref() {
        static $obj;

        echo 'Statisches Objekt: ';
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // Der statischen Variablen eine Referenz zuweisen
            $obj = &$new;
        }
        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }
        return $obj;
    }

    function &get_instance_noref() {
        static $obj;

        echo 'Statisches Objekt: ';
        var_dump($obj);
        if (!isset($obj)) {
            $new = new stdClass;
            // Der statischen Variablen ein Objekt zuweisen
            $obj = $new;
        }
        if (!isset($obj->property)) {
            $obj->property = 1;
        } else {
            $obj->property++;
        }
        return $obj;
    }

    $obj1 = get_instance_ref();
    $still_obj1 = get_instance_ref();
    echo "\n";
    $obj2 = get_instance_noref();
    $still_obj2 = get_instance_noref();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Statisches Objekt: NULL
    Statisches Objekt: NULL

    Statisches Objekt: NULL
    Statisches Objekt: object(stdClass)#3 (1) {
      ["property"]=>
      int(1)
    }

Dieses Beispiel demonstriert, dass die Referenz, die einer statischen Variablen zugewiesen wird, beim zweiten Aufruf der Funktion `&get_instance_ref()` vergessen ist.

## Variable Variablen

Manchmal ist es komfortabel, variable Variablennamen zu verwenden. Das bedeutet, einen Variablennamen zu setzen und dynamisch zu verwenden. Eine normale Variable wird wie folgt festgelegt:

    <?php
    $a = 'Hallo';
    ?>

Eine variable Variable nimmt den Wert einer Variablen und behandelt ihn als Name der Variablen. Im obigen Beispiel kann Hallo als Variablenname verwendet werden, indem man zwei Dollar-Zeichen verwendet, also schreibt:

    <?php
    $$a = 'Welt';
    ?>

Nun existieren in der PHP-Symbol-Struktur zwei definierte und gespeicherte Variablen: $a mit dem Inhalt "Hallo" und $Hallo mit dem Inhalt "Welt". Deshalb wird die Anweisung

    <?php
    echo "$a {$$a}";
    ?>

zur genau gleichen Ausgabe führen wie:

    <?php
    echo "$a $Hallo";
    ?>

also zu: Hallo Welt.

Um variable Variablen mit Arrays zu verwenden, muss ein Problem der Zweideutigkeit gelöst werden. Das heißt, wenn der Parser auf $$a[1] stößt, muss er erkennen können, ob $a[1] als Variable verwendet werden soll, oder ob $$a als Variable verwendet werden soll und dann der `[1]`-Index dieser Variable. Die Syntax zur Auflösung dieser Zweideutigkeit lautet: ${$a[1]} für den ersten Fall und ${$a}[1] für den zweiten Fall.

Auf Klasseneigenschaften kann ebenso unter Verwendung von variablen Eigenschaftsnamen zugegriffen werden. Der variable Eigenschaftsname wird innerhalb des Geltungsbereichs aufgelöst, aus dem der Aufruf erfolgt. Wenn es z. B. einen Ausdruck wie $foo->$bar gibt, dann wird der lokale Geltungsbereich auf $bar untersucht, und dessen Wert wird als Eigenschaftsname von $foo verwendet. Dies gilt analog, wenn $bar ein Arrayzugriff ist.

Geschweifte Klammern können ebenfalls verwendet werden, um den Eigenschaftsnamen deutlich abzugrenzen. Sie sind besonders nützlich beim Zugriff auf Werte in einer Eigenschaft, die ein Array enthält, wenn der Eigenschaftsname aus mehreren Teilen besteht oder wenn der Eigenschaftsname Zeichen enthält, die andernfalls nicht gültig sind, z. B. von json_decode() oder SimpleXML.

Beispiel #1 Beispiel zu variablen Eigenschaften

    <?php
    class Foo {
        public $bar = 'Ich bin bar.';
        public $arr = array('Ich bin A.', 'Ich bin B.', 'Ich bin C.');
        public $r   = 'Ich bin r.';
    }

    $foo = new Foo();
    $bar = 'bar';
    $baz = ['foo', 'bar', 'baz', 'quux'];
    echo $foo->$bar . "\n";
    echo $foo->{$baz[1]} . "\n";

    $start = 'b';
    $end   = 'ar';
    echo $foo->{$start . $end} . "\n";

    $arr = 'arr';
    echo $foo->{$arr[1]} . "\n";
    echo $foo->{$arr}[1] . "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ich bin bar.
    Ich bin bar.
    Ich bin bar.
    Ich bin r.
    Ich bin B.

Warnung

Bitte beachten Sie, dass variable Variablen nicht mit Superglobalen Arrays in Funktionen oder Klassenmethoden verwendet werden können. Die Variable `$this` ist ebenfalls eine spezielle Variable, die nicht dynamisch referenziert werden kann.

## Variablen aus externen Quellen

### HTML-Formulare (GET and POST)

Sobald ein Formular an ein PHP-Skript übergeben wird, werden die Informationen dieses Formulars dem Skript automatisch zur Verfügung gestellt. Es gibt ein paar Möglichkeiten, auf diese Informationen zuzugreifen, zum Beispiel:

Beispiel #1 Ein einfaches HTML-Formular

    <form action="foo.php" method="post">
        Name:  <input type="text" name="username" /><br />
        E-Mail: <input type="text" name="email" /><br />
        <input type="submit" name="submit" value="Und ab!" />
    </form>

Es gibt nur zwei Möglichkeiten, um auf die Daten von HTML-Formularen zuzugreifen. Die zurzeit verfügbaren Methoden werden unten aufgeführt:

Beispiel #2 Zugriff auf die Daten eines einfachen HTML-POST-Formulars

    <?php
    echo $_POST['username'];
    echo $_REQUEST['username'];
    ?>

Die Verwendung eines GET-Formulars ist, davon abgesehen, dass stattdessen die entsprechende vordefinierte GET-Variable verwendet werden kann, ähnlich. Außerdem wird GET auch für den `QUERY_STRING` (die Information nach dem '?' in einer URL) verwendet. So enthält zum Beispiel `http://www.example.com/test.php?id=3` GET-Daten, auf die mit $_GET['id'] zugegriffen werden kann. Siehe auch $_REQUEST.

> Hinweis:

> Punkte und Leerzeichen in Variablennamen werden in Unterstriche umgewandelt. Zum Beispiel wird `<input name="a.b" />` zu `$_REQUEST["a_b"]`.

Im Zusammenhang mit Formular-Variablen versteht PHP auch Arrays (siehe auch die zugehörige FAQ). So können z. B. zusammengehörige Variablen gruppiert werden, oder diese Funktionalität kann verwendet werden, um Werte aus einer Eingabe mit Mehrfachauswahl abzurufen. Schicken wir zum Beispiel ein Formular an sich selbst und lassen nach dem Versand die Daten anzeigen:

Beispiel #3 Komplexere Formular-Variablen

    <?php
    if ($_POST) {
        echo '<pre>';
        echo htmlspecialchars(print_r($_POST, true));
        echo '</pre>';
    }
    ?>
    <form action="" method="post">
        Name:  <input type="text" name="personal[name]" /><br />
        E-Mail: <input type="text" name="personal[email]" /><br />
        Bier: <br />
        <select multiple name="bier[]">
            <option value="oettinger">Öttinger</option>
            <option value="bitburger">Bitburger</option>
            <option value="stuttgarter">Stuttgarter Schwabenbräu</option>
        </select><br />
        <input type="submit" value="Und ab!" />
    </form>

> Hinweis: Beginnt der Name einer externen Variablen mit einer gültigen Array-Syntax, dann werden darauf folgende Zeichen stillschweigend ignoriert. Zum Beispiel wird `<input name="foo[bar]baz">` zu `$_REQUEST['foo']['bar']`.

#### IMAGE-SUBMIT-Variablennamen

Zur Übertragung eines Formulars kann auch ein Bild statt eines Übertragungs-Schalters (Submit-Button) verwendet werden, dessen Tag wie folgt aussieht:

    <input type="image" src="image.gif" name="sub" />

Klickt der Benutzer irgendwo auf das Bild, wird das entsprechende Formular an den Webserver übertragen. Hierbei sind zwei zusätzliche Variablen vorhanden, sub_x und sub_y. Diese enthalten die Koordinaten des Klickpunktes innerhalb des Bildes. Die Erfahreneren werden bemerken, dass die Variablen, die vom Browser gesendet werden, einen Punkt statt eines Unterstrichs enthalten. Dieser Punkt wird von PHP automatisch in einen Unterstrich verwandelt.

### HTTP-Cookies

PHP unterstützt HTTP-Cookies auf völlig transparente Weise, wie in » RFC 6265 definiert. Cookies sind ein Mechanismus zur Speicherung von Daten auf dem Client-Rechner, um damit wiederkehrende Benutzer nachzuverfolgen oder zu identifizieren. Mit der Funktion setcookie() ist es möglich, Cookies zu erzeugen. Cookies sind Teil des HTTP-Headers, deshalb muss die Funktion setcookie() aufgerufen werden, bevor irgendeine Ausgabe an den Browser gesendet wird. Dabei handelt es sich um die gleiche Einschränkung, die auch für die Funktion header() gilt. Cookie-Daten stehen dann in den entsprechenden Cookie-Daten-Arrays, zum Beispiel $_COOKIE, sowie in $_REQUEST zur Verfügung. Weitere Details und Beispiele sind auf der Seite setcookie() des Handbuchs zu finden.

> Hinweis: Aus Sicherheitsgründen werden ab PHP 7.2.34, 7.3.23 bzw. 7.4.11 die Namen der eingehenden Cookies nicht mehr URL-dekodiert.

Wenn einer einzelnen Cookie-Variablen mehrere Werte zugewiesen werden sollen, müssen diese als Array zugewiesen werden. Zum Beispiel:

    <?php
      setcookie("MeinCookie[foo]", 'Ich teste 1', time()+3600);
      setcookie("MeinCookie[bar]", 'Ich teste 2', time()+3600);
    ?>

Dadurch werden zwei einzelne Cookies erzeugt, obwohl MyCookie im Skript nun ein einziges Array ist. Wenn nur ein Cookie mit mehreren Werten gesetzt werden soll, empfiehlt es sich, zuerst serialize() oder explode() auf das Array anzuwenden.

Es ist zu bedenken, dass ein Cookie ein vorhergehendes Cookie gleichen Namens im Browser überschreibt, es sei denn, der Pfad oder die Domain sind anders. Für eine Warenkorb-Anwendung kann somit z. B. ein Zähler mitgeführt und weitergegeben werden:

Beispiel #4 Ein setcookie()-Beispiel

    <?php
    if (isset($_COOKIE['zaehler'])) {
        $count = $_COOKIE['zaehler'] + 1;
    } else {
        $count = 1;
    }
    setcookie('zaehler', $count, time()+3600);
    setcookie("Cart[$count]", $item, time()+3600);
    ?>

### Punkte in eingehenden Variablennamen

Normalerweise verändert PHP die Variablennamen nicht, wenn sie einem Skript übergeben werden. Es sollte aber beachtet werden, dass der Punkt (".") kein gültiger Bestandteil eines Variablennamens ist. Deshalb achten Sie auf folgendes:

    <?php
    $varname.ext;  /* ungültiger Variablenname */
    ?>

Der PHP-Parser sieht eine Variable namens $varname, gefolgt von einem Zeichenketten-Verbindungsoperator, dieser wiederum gefolgt von der offenen Zeichenkette 'ext' (also nicht eingegrenzt durch '"' und auch keinem Schlüsselwort oder reserviertem Bezeichner entsprechend). Das kann natürlich nicht zum gewünschten Ergebnis führen.

Deshalb ist es wichtig zu wissen, dass PHP in den ihm übergebenen Variablen alle Punkte (.) automatisch durch einen Unterstrich (_) ersetzt.

### Bestimmung des Variablen-Typs

Da PHP den Typ der Variablen bestimmt und (im Allgemeinen) selbst eine entsprechende Umformung vornimmt, ist es nicht immer klar, welchen Typ eine Variable gerade hat. PHP beinhaltet einige Funktionen, die dies herausfinden, wie zum Beispiel: gettype(), is_array(), is_float(), is_int(), is_object() und is_string(). Lesen Sie bitte auch das Kapitel über Typen.

Da HTTP ein Text-Protokoll ist, werden die meisten, wenn nicht alle Inhalte von superglobalen Arrays, wie $_POST und $_GET, als Zeichenketten erhalten bleiben. PHP wird nicht versuchen, die Werte in spezifische Typen umzuwandeln. Im Beispiel weiter unten enthält $_GET["var1"] die Zeichenkette "null" und $_GET["var2"] die Zeichenkette "123".

    /index.php?var1=null&var2=123

### Changelog

Version | Beschreibung
--- | ---
7.2.34, 7.3.23, 7.4.11 | Aus Sicherheitsgründen werden die Namen der eingehenden Cookies nicht mehr URL-dekodiert.

# Konstanten

## Inhaltsverzeichnis

- Syntax
- Vordefinierte Konstanten
- Magische Konstanten

Eine Konstante ist ein Bezeichner (Name) für einen einfachen Wert. Wie der Name bereits nahelegt, kann der Wert einer Konstanten zur Laufzeit des Skripts nicht verändert werden (außer bei Magischen Konstanten, die nicht wirklich Konstanten sind). Konstanten unterscheiden standardmäßig zwischen Groß- und Kleinschreibung. Nach gängiger Konvention werden Konstanten immer in Großbuchstaben geschrieben.

> Hinweis:

> Vor PHP 8.0.0 konnten Konstanten, die mit der Funktion define() definiert wurden, ohne Berücksichtigung der Groß- und Kleinschreibung verwendet werden.

Der Name einer Konstanten folgt den gleichen Regeln wie alle anderen Bezeichner in PHP. Ein gültiger Name beginnt mit einem Buchstaben oder einem Unterstrich, gefolgt von beliebig vielen Buchstaben, Ziffern oder Unterstrichen. Als regulärer Ausdruck könnte das so beschrieben werden: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

Es ist möglich, Konstanten mit reservierten oder gar ungültigen Namen mittels define() zu definieren, deren Wert nur mit der Funktion constant() gelesen werden kann. Allerdings wird dies nicht empfohlen.

Tipp

Siehe auch Userland-Namensregeln.

Beispiel #1 Gültige und ungültige Namen für Konstanten

    <?php

    // Gültige Namen für Konstanten
    define("FOO",     "irgendwas");
    define("FOO2",    "etwas anderes");
    define("FOO_BAR", "irgendwas ganz anderes");

    // Ungültige Namen für Konstanten
    define("2FOO",    "irgendwas");

    // Folgendes ist korrekt, sollte aber vermieden werden:
    // PHP könnte eines Tages eine magische Konstante unterstützen,
    // die Ihr Skript nicht mehr wie gewünscht funktionieren lässt
    define("__FOO__", "irgendwas");

    ?>

> Hinweis: Für unsere Zwecke ist hier ein Buchstabe a-z, A-Z und die ASCII-Zeichen von 128 bis 255 (0x80-0xff).

Wie bei superglobals ist der Geltungsbereich einer Konstanten global. Unabhängig vom Geltungsbereich kann in einem Skript überall auf eine Konstante zugegriffen werden. Für mehr Information zum Geltungsbereich lesen Sie bitte den Abschnitt über den Geltungsbereich von Variablen.

> Hinweis: Seit PHP 7.1.0 können Klassenkonstanten eine Sichtbarkeit von protected oder private deklarieren, wodurch sie nur im hierarchischen Bereich der Klasse zur Verfügung stehen, in der sie definiert sind.

## Syntax

Konstanten können mit dem Schlüsselwort `const` oder mit der Funktion define() definiert werden. Während define() es ermöglicht, eine Konstante auf einen beliebigen Wert zu definieren, hat das Schlüsselwort `const` Einschränkungen, die im nächsten Absatz beschrieben werden. Einmal definiert, kann eine Konstante weder verändert noch gelöscht werden.

Wenn das Schlüsselwort `const` verwendet wird, werden nur skalare Ausdrücke (bool, int, float und string) und konstante Arrays, die nur skalare Ausdrücke enthalten, akzeptiert. Es ist möglich, Konstanten vom Typ resource zu definieren, dies sollte allerdings vermieden werden, da es zu unerwarteten Ergebnissen führen kann.

Auf den Wert einer Konstanten wird einfach durch die Angabe ihres Namens zugegriffen. Im Gegensatz zu Variablen wird einer Konstanten kein `$` vorangestellt. Ebenso kann die Funktion constant() verwendet werden, um den Wert einer Konstanten auszulesen, wenn der Name der Konstanten dynamisch ermittelt wird. Mit der Funktion get_defined_constants() erhält man eine Liste aller definierten Konstanten.

> Hinweis: Konstanten und (globale) Variablen befinden sich in unterschiedlichen Namensräumen. Das hat zum Beispiel zur Folge, dass `true` und $TRUE etwas völlig Verschiedenes sind.

Falls eine undefinierte Konstante verwendet wird, wird ein Error ausgelöst. Vor PHP 8.0.0 wurden undefinierte Konstanten als einfaches String-Wort (d. h. CONSTANT vs "CONSTANT") interpretiert. Dieses Rückfallverhalten ist von PHP 7.2.0 an missbilligt, und ein Fehler der Stufe `E_WARNING` wird ausgelöst, wenn es dazu kommt. Vor PHP 7.2.0 wurde stattdessen ein Fehler der Stufe E_NOTICE `E_NOTICE` ausgelöst. Siehe auch den Abschnitt im Handbuch, der erklärt, warum $foo[bar] falsch ist (es sei denn, `bar` ist eine Konstante). Dies gilt nicht für (vollständig) qualifizierte Konstanten, die immer einen Error auslösen, wenn sie undefiniert sind.

> Hinweis: Um zu prüfen, ob eine Konstante gesetzt ist, kann die Funktion defined() verwendet werden.

Dies sind die Unterschiede zwischen Konstanten und Variablen:

- Konstanten haben kein Dollarzeichen (`$`) vorangestellt;
- Konstanten können überall definiert werden und auf Ihren Wert kann ohne Rücksicht auf die Regeln des Geltungsbereichs von Variablen zugegriffen werden;
- Sobald Konstanten definiert sind, können sie nicht neu definiert oder gelöscht werden; und
- Konstanten können nur als skalare Werte oder Arrays ausgewertet werden.

Beispiel #1 Definition von Konstanten

    <?php
    define("KONSTANTE", "Hallo Welt.");
    echo KONSTANTE;     // Ausgabe: "Hallo Welt."
    echo Konstante;     // Gibt einen Fehler aus: Undefined Constant "Konstante"
                        // Vor PHP 8.0.0 wird "Konstante" ausgegeben und eine
                        // Warnung angezeigt.
    ?>

Beispiel #2 Definition von Konstanten unter Verwendung des Schlüsselworts `const`

    <?php
    // Einfacher skalarer Wert
    const KONSTANTE = 'Hallo Welt';

    echo KONSTANTE;

    // Skalarer Ausdruck
    const ANDERE_KONSTANTE = KONSTANTE . '; Ade Welt';
    echo ANDERE_KONSTANTE;

    const ANIMALS = array('Hund', 'Katze', 'Maus');
    echo ANIMALS[1]; // gibt "Katze" aus

    // Array-Konstante
    define('ANIMALS', array(
        'Hund',
        'Katze',
        'Maus'
    ));
    echo ANIMALS[1]; // gibt "Katze" aus
    ?>

> Hinweis:

> Im Gegensatz zu Konstanten, welche mit define() erstellt werden, müssen über `const` definierte Konstanten auf der höchsten Ebene erstellt werden, weil sie bei der Kompilierung definiert werden. Das heißt, dass sie nicht innerhalb von Funktionen, Schleifen, `if`-Anweisungen oder `try`/`catch`-Blöcken definiert werden können.

### Siehe auch

- Klassenkonstanten

## Vordefinierte Konstanten

PHP stellt jedem Skript zur Laufzeit eine Vielzahl von vordefinierten Konstanten zur Verfügung. Viele dieser Konstanten werden jedoch von verschiedenen Erweiterungen definiert, die nur zur Verfügung stehen, wenn diese Erweiterungen selbst zur Verfügung stehen, d. h. entweder über dynamisches Laden zur Laufzeit oder Einkompilieren.

## Magische Konstanten

Es gibt ein paar magische Konstanten, die, abhängig davon, wo sie eingesetzt werden, einen unterschiedlichen Wert haben. Zum Beispiel hängt der Wert der Konstanten `__LINE__` davon ab, in welcher Zeile des Skripts diese Konstante verwendet wird. Alle diese "magischen" Konstanten werden während der Kompilierzeit aufgelöst, im Gegensatz zu regulären Konstanten, die während der Laufzeit aufgelöst werden. Diese besonderen Konstanten sind unabhängig von Groß-/Kleinschreibung und sind folgende:

PHP's magische Konstanten
Name | Beschreibung
--- | ---
`__LINE__` | Die aktuelle Zeilennummer einer Datei.
`__FILE__` | Der vollständige Pfad- und Dateiname einer Datei mit aufgelösten Symlinks. Wird diese Konstante innerhalb einer nachgeladenen Datei verwendet, wird der Name dieser eingebundenen Datei zurückgegeben.
`__DIR__` | Der Name des Verzeichnisses, in dem sich die Datei befindet. Wird die Konstante innerhalb eines Includes verwendet, wird das Verzeichnis der eingebundenen Datei zurückgegeben. Dies entspricht dem Verhalten von `dirname(__FILE__)`. Der Verzeichnisname hat keinen beendenden Schrägstrich, sofern es sich nicht um das Rootverzeichnis handelt.
`__FUNCTION__` | Der Name der Funktion, oder `{closure}` für anonyme Funktionen.
`__CLASS__` | Der Name einer Klasse. Der Klassenname enthält den Namen des Namensraums, in dem sie deklariert wurde (z. B. `Foo\Bar`). Bei Verwendung innerhalb einer Trait-Methode ist `__CLASS__` der Name der Klasse, in der der Trait verwendet wird.
`__TRAIT__` | Der Name eines Traits. Dieser enthält auch den Namensraum, in welchem der Trait definiert wurde (z. B. `Foo\Bar`).
`__METHOD__` | Der Name der Klassenmethode.
`__PROPERTY__` | Nur gültig innerhalb eines Eigenschafts-Hooks; entspricht dem Namen der Eigenschaft.
`__NAMESPACE__` | Der Name des aktuellen Namensraums.
`ClassName::class` | Der vollständig qualifizierte Klassenname.

### Siehe auch

- ::class
- get_class()
- get_object_vars()
- file_exists()
- function_exists()

# Ausdrücke

Ausdrücke (Expressions) sind die wichtigsten Bausteine von PHP. In PHP ist fast alles, was geschrieben wird, ein Ausdruck. Die einfachste, aber auch zutreffendste Definition für einen Ausdruck ist "alles, was einen Wert hat".

Die grundlegendsten Formen von Ausdrücken sind Konstanten und Variablen. Wenn man `$a = 5` schreibt, weist man $a den Ausdruck `5` zu. `5` hat offensichtlich den Wert 5. Anders ausgedrückt: `5` ist ein Ausdruck mit dem Wert 5 (in diesem Fall ist `5` eine Integer-Konstante).

Nach dieser Zuweisung würde man erwarten, dass der Wert von $a nun ebenfalls 5 ist; wenn man also `$b = $a` schreibt, sollte dasselbe dabei herauskommen, als hätte man `$b = 5` geschrieben. Anders ausgedrückt: $a ist ebenfalls ein Ausdruck mit dem Wert 5. Wenn alles richtig funktioniert, wird genau das passieren.

Etwas kompliziertere Beispiele für Ausdrücke sind Funktionen. Betrachten wir zum Beispiel die folgende Funktion:

    <?php
    function foo ()
    {
        return 5;
    }
    ?>

Angenommen, Sie sind mit dem Konzept von Funktionen vertraut (wenn Sie es nicht sind, lesen Sie das Kapitel über Funktionen), dann würden Sie davon ausgehen, dass die Eingabe von `$c = foo()` grundsätzlich dasselbe bedeutet, als würde man `$c = 5` schreiben, und genau das trifft zu. Funktionen sind Ausdrücke mit dem Wert ihres Rückgabewertes. Da `foo()` den Wert 5 zurückgibt, ist der Wert des Ausdruckes '`foo()`' 5. Normalerweise geben Funktionen nicht einfach einen statischen Wert zurück, sondern berechnen etwas.

Natürlich müssen Werte in PHP keine Integer-Zahlen sein, und oft sind sie es auch nicht. PHP unterstützt vier skalare Datentypen: int (Ganzzahlen), float (Fließkommazahlen), string (Zeichenketten) und bool (Wahrheitswerte). (Skalare sind Datentypen, die man, im Gegensatz zu zum Beispiel Arrays, nicht in kleinere Stücke 'brechen' kann.) PHP unterstützt auch zwei zusammengesetzte (nicht-skalare) Datentypen: Arrays und Objekte. Jeder dieser Datentypen kann Variablen zugewiesen und von Funktionen zurückgegeben werden.

PHP fasst den Begriff Ausdruck aber noch viel weiter, wie es auch andere Programmiersprachen tun. PHP ist eine ausdrucksorientierte Sprache, in dem Sinne, dass fast alles einen Ausdruck darstellt. Zurück zu dem Beispiel, mit dem wir uns bereits beschäftigt haben: `$a = 5`. Es ist einfach zu erkennen, dass hier zwei Werte enthalten sind: Der Wert der Integer-Konstanten `5` und der Wert von $a, der ebenfalls auf 5 geändert wird. In Wirklichkeit ist aber noch ein weiterer Wert enthalten, nämlich der Wert der Zuweisung selbst. Die Zuweisung selbst enthält den zugewiesenen Wert, in diesem Fall 5. In der Praxis bedeutet dies, dass `$a = 5`, egal was es tut, immer einen Ausdruck mit dem Wert 5 darstellt. Folglich ist `$b = ($a = 5)` gleichbedeutend mit `$a = 5; $b = 5;` (ein Semikolon markiert das Ende einer Anweisung). Da Wertzuweisungen von rechts nach links geparst werden, kann man auch `$b = $a = 5` schreiben.

Ein anderes gutes Beispiel für die Ausdrucksorientierung von PHP sind Prä- und Post-Inkrement sowie die entsprechenden Dekremente. Benutzer von PHP und vielen anderen Sprachen sind vermutlich mit den Notationen `variable++` und `variable--` vertraut. Dies sind Inkrement- und Dekrement-Operatoren. In PHP gibt es, wie in C, zwei Arten von Inkrementen - Prä-Inkrement und Post-Inkrement. Grundsätzlich erhöhen sowohl Prä- als auch Post-Inkrement den Wert der Variable, und der Effekt auf die Variable ist derselbe. Der Unterschied liegt im Wert des Inkrement-Ausdruckes. Das Prä-Inkrement, das `++$variable` geschrieben wird, enthält als Wert den Wert der erhöhten Variable (PHP erhöht den Wert der Variablen, bevor es ihren Wert ausliest, daher der Name 'PRÄ-Inkrement'). Das Post-Inkrement, das `$variable++` geschrieben wird, enthält dagegen den ursprünglichen Wert von $variable vor der Erhöhung (PHP erhöht den Wert der Variablen, nachdem es ihren Wert ausgelesen hat, daher der Name 'POST-Inkrement').

Ein sehr gebräuchlicher Typ von Ausdrücken sind Vergleichsausdrücke. Diese Ausdrücke geben entweder `false` oder `true` zurück. PHP unterstützt > (größer), >= (größer oder gleich), == (gleich), != (ungleich), < (kleiner), und <= (kleiner oder gleich). Die Sprache unterstützt weiterhin ein Set von absoluten Vergleichsoperatoren: === (inhalts- und typgleich) und !== (nicht inhalts- oder typgleich). Diese Ausdrücke werden meist in bedingten Anweisungen, wie z. B. in `if`-Anweisungen, verwendet.

Im letzten Beispiel für Ausdrücke befassen wir uns mit kombinierten Zuweisungs- und Operator-Ausdrücken. Wir wissen bereits, dass, wenn wir $a um 1 erhöhen wollen, wir einfach `$a++` oder `++$a` schreiben können. Aber was tut man, wenn man den Wert um mehr als eins erhöhen will, z. B. um 3? Man könnte mehrere Male `$a++` schreiben, aber das ist offensichtlich weder ein effizienter noch komfortabler Weg. Viel üblicher ist es, einfach `$a = $a + 3` zu schreiben. `$a + 3` gibt den Wert von $a plus 3 zurück, dieser wird wieder $a zugewiesen, was dazu führt, dass $a nun um 3 erhöht wurde. In PHP - wie in einigen anderen Programmiersprachen, z. B. in C - kann man dies aber noch kürzer schreiben, was mit der Zeit klarer wird und auch einfacher zu verstehen ist. Um 3 zu dem aktuellen Wert von $a hinzuzufügen, schreibt man `$a += 3`. Das bedeutet exakt: "Nimm den Wert von $a, addiere 3 hinzu und weise $a den entstandenen Wert zu". Zusätzlich dazu, dass diese Schreibweise kürzer und klarer ist, wird sie auch schneller ausgeführt. Der Wert von `$a += 3` ist, wie der Wert einer regulären Zuweisung, der zugewiesene Wert. Beachten Sie, dass dieser Wert NICHT 3, sondern dem kombinierten Wert von $a plus 3 entspricht (das ist der Wert, der $a zugewiesen wird). Jeder Operator, der zwei Elemente verbindet, kann in dieser Schreibweise verwendet werden, z. B. `$a -= 5` (vermindert den Wert von $a um 5) oder `$b *= 7` (multipliziert den Wert von $b mit 7), usw.

Es gibt einen weiteren Ausdruck, der Ihnen vielleicht seltsam vorkommt, wenn Sie ihn bisher noch in keiner Programmiersprache kennengelernt haben, den dreifach konditionalen Operator:

    <?php
    $eins ? $zwei : $drei
    ?>

Wenn der Wert des ersten Sub-Ausdruckes (hier: $eins) `true` ist (d. h. nicht 0), dann wird der Wert des zweiten Subausdrucks (hier: $zwei) ausgewertet und ist das Ergebnis des konditionalen Ausdrucks. Andernfalls wird der dritte Subausdruck ausgewertet und dessen Wert zurückgegeben.

Das folgende Beispiel sollte das Verständnis von Prä- und Post-Inkrement und von Ausdrücken im Allgemeinen erleichtern:

    <?php
    function verdoppeln($i)
    {
        return $i*2;
    }
    $b = $a = 5;        /* Weise den Variablen $a und $b den Wert 5 zu */
    $c = $a++;          /* Post-Inkrement, der urspruengliche Wert von $a (5)
                           wird $c zugewiesen. */
    $e = $d = ++$b;     /* Prae-Inkrement, der erhöhte Wert von $b (6) wird $d und
                           $e zugewiesen. */

    /* An diesem Punkt sind $d und $e beide gleich 6 */

    $f = verdoppeln($d++);  /* Weise $f den doppelten Wert von $d vor
                               der Erhöhung um eins zu, 2*6 = 12 */
    $g = verdoppeln(++$e);  /* Weise $g den doppelten Wert von $e nach
                               der Erhoehung um eins zu, 2*7 = 14 to $g */
    $h = $g += 10;      /* Zuerst wird $g um 10 erhöht und hat damit den Wert
                           24. Der Wert dieser Zuweisung (24) wird dann $h
                           zugewiesen, womit $h ebenfalls den Wert von 24 hat. */
    ?>

Einige Ausdrücke können wie Anweisungen verwendet werden. In diesem Falle hat eine Anweisung die Form '`expr ;`', dies meint einen Ausdruck gefolgt von einem Semikolon. In `$b = $a = 5;` ist `$a = 5` ein gültiger Ausdruck, aber für sich allein keine Anweisung. `$b = $a = 5;` ist jedoch eine gültige Anweisung.

Ein letzter Punkt, der noch zu erwähnen ist, ist der Wahrheitswert von Ausdrücken. In vielen Fällen, hauptsächlich in bedingten Anweisungen und Schleifen, ist man nicht am spezifischen Wert eines Ausdrucks interessiert, sondern kümmert sich nur darum, ob er `true` oder `false` bedeutet. Die Konstanten `true` und `false` (case-insensitiv) sind die beiden möglichen Wahrheitswerte. Wenn nötig wird ein Ausdruck automatisch in einen Booleschen Wert konvertiert. Wenn Sie mehr darüber erfahren wollen, lesen Sie den Abschnitt über Typecasting.

PHP stellt eine vollständige und mächtige Implementierung von Ausdrücken bereit, deren vollständige Dokumentation den Rahmen dieses Manuals sprengen würde. Die obigen Beispiele sollten Ihnen einen guten Eindruck davon verschaffen, was Ausdrücke sind und wie man nützliche Ausdrücke konstruieren kann. Im Rest dieses Manuals werden wir expr schreiben, um auszudrücken, dass an dieser Stelle jeder gültige PHP-Ausdruck stehen kann.

# Operatoren

## Inhaltsverzeichnis

- Operator-Rangfolge
- Arithmetisch
- Inkrement und Dekrement
- Zuweisung
- Bit
- Vergleich
- Fehlerkontrolle
- Programmausführung
- Logik
- Zeichenketten
- Array
- Typ
- Functional

Ein Operator ist etwas das Sie mit einem oder mehreren Werten (oder Ausdrücken, um im Programmierjargon zu sprechen) füttern und Sie erhalten als Ergebnis einen anderen Wert (damit wird diese Konstruktion selbst zu einem Ausdruck).

Operatoren können gemäß der Anzahl der Operanden, die sie erwarten, gruppiert werden. Unäre Operatoren arbeiten mit nur einem Operanden, zum Beispiel `!` (der logische Negationsoperator) oder `++` (der Inkrementoperator). Binäre Operatoren arbeiten mit zwei Operanden, wie etwa die bekannten arithmetischen Operatoren `+` (Plus) und `-` (Minus), und die meisten PHP-Operatoren fallen in diese Kategorie. Schließlich gibt es einen einzigen ternären Operator, `? :`, der mit drei Operanden arbeitet; dieser wird meist einfach "der ternäre Operator" genannt (obwohl er wohl richtiger bedingter Operator genannt werden könnte).

Eine vollständige Liste von PHP-Operatoren folgt im Abschnitt Operator-Rangfolge. Dieser Abschnitt erklärt weiterhin die Operator-Rangfolge und die Assoziativität (Ausführungspriorität), die regeln wie Ausdrücke, die mehrere unterschiedliche Operatoren enthalten, ausgewertet werden.

## Operator-Rangfolge

Die Operator-Rangfolge legt fest, wie "eng" ein Operator zwei Ausdrücke miteinander verbindet. Zum Beispiel ist das Ergebnis des Ausdruckes `1 + 5 * 3` `16` und nicht `18`, da der Multiplikations-Operator ("*") in der Rangfolge höher steht als der Additions-Operator ("+"). Wenn nötig, können Sie Klammern setzen, um die Rangfolge der Operatoren zu beeinflussen. Zum Beispiel ergibt: `(1 + 5) * 3` `18`.

Haben Operatoren die gleiche Rangfolge, dann entscheidet ihre Assoziativität wie die Operatoren gruppiert werden. Zum Beispiel ist "-" links-assoziativ, sodass `1 - 2 - 3` als `(1 - 2) - 3` gruppiert und zu `-4` ausgewertet wird. Andererseits ist "=" rechts-assoziativ, sodass `$a = $b = $c` als `$a = ($b = $c)` gruppiert wird.

Operatoren gleicher Rangfolge, die nicht-assoziativ sind, können nicht nebeneinander verwendet werden; beispielsweise ist `1 < 2 > 1` in PHP nicht erlaubt. Der Ausdruck `1 <= 1 == 1` ist allerdings erlaubt, weil der Operator `==` eine niedrigere Rangfolge als der Operator `<` hat.

Assoziativität ist nur für binäre (und ternäre) Operatoren sinnvoll. Unäre Operatoren sind entweder Präfix oder Postfix, sodass dieser Begriff nicht anwendbar ist. Zum Beispiel kann `!!$a` nur als `!(!$a)` gruppiert werden.

Die Verwendung von Klammern, auch wenn sie nicht unbedingt erforderlich sind, kann oft die Lesbarkeit des Codes verbessern, indem explizit gruppiert wird, statt sich auf die implizite Operator-Rangfolge und -Assoziativität zu verlassen.

Die folgende Tabelle zeigt die Rangfolge der Operatoren, oben steht der Operator mit dem höchsten Rang. Operatoren in derselben Zeile haben die gleiche Rangfolge, sodass ihre Assoziativität die Gruppierung entscheidet.

Operator-Rangfolge
Assoziativität | Operatoren | Additional Information
--- | --- | ---
(n. z.) | `clone` `new` | clone und new
rechts | `**` | arithmetisch
(n. z.) | `+` `-` `++` `--` `~` `(int)` `(float)` `(string)` `(array)` `(object)` `(bool)` `@` | arithmetisch (unär `+` und `-`), inkrementell/dekrementell, bitweise, Typumwandlung und Fehlerkontrolle
left | `instanceof` | Typ
(n. z.) | `!` | logisch
links | `*` `/` `%` | arithmetisch
links | `+` `-` `.` | arithmetisch (binär `+` und `-`), Array und Zeichenkette (`.` vor PHP 8.0.0)
links | `<<` `>>` | bitweise
left | `.` | Zeichenkette (seit PHP 8.0.0)
non-associative | `<` `<=` `>` `>=` | Vergleiche
nicht-assoziativ | `==` `!=` `===` `!==` `<>` `<=>` | Vergleiche
links | `&` | bitweise und Referenzen
links | `^` | bitweise
links | `|` | bitweise
links | `&&` | logisch
links | `||` | logisch
rechts | `??` | NULL-Zusammenfügungsoperator
nicht-assoziativ | `? :` | ternärer Operator (vor PHP 8.0.0 links-assoziativ)
rechts | `=` `+=` `-=` `*=` `**=` `/=` `.=` `%=` `&=` `|=` `^=` `<<=` `>>=` `??=` | Zuweisung
(n. z.) | `yield from` | yield from
(n. z.) | `yield` | yield
(n. z.) | `print` | print
links | `and` | logisch
links | `xor` | logisch
links | `or` | logisch

Beispiel #1 Assoziativität

    <?php
    $a = 3 * 3 % 5; // (3 * 3) % 5 = 4
    var_dump($a);

    $a = 1;
    $b = 2;
    $a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
    var_dump($a, $b);
    ?>

Der ternäre Operator erfordert explizit die Verwendung von Klammern, um den Rangfolge zu verdeutlichen.

Beispiel #2 Explizite Rangfolge

    <?php
    $a = true ? 0 : (true ? 1 : 2);
    var_dump($a);

    // Dies ist seit PHP 8 nicht mehr erlaubt
    // $a = true ? 0 : true ? 1 : 2;
    ?>

Operator-Rangfolge und -Assoziativität bestimmen nur wie Ausdrücke gruppiert werden, aber nicht die Auswertungsreihenfolge. PHP legt (im Allgemeinen) nicht fest, in welcher Reihenfolge ein Ausdruck ausgewertet wird. Code, der eine bestimmte Auswertungsreihenfolge erwartet, sollte vermieden werden, denn das Verhalten kann sich von Version zu Version ändern und auch vom umgebenden Code abhängen.

Beispiel #3 Nicht definierte Auswertungsreihenfolge

    <?php
    $a = 1;
    echo $a + $a++; // gibt entweder 2 oder 3 aus

    $i = 1;
    $array[$i] = $i++; // der Index ist entweder 1 oder 2
    ?>

Beispiel #4 Die Rangfolge von `+`, `-` und `.`

    <?php
    $x = 4;
    // diese Zeile könnte eine unerwartete Ausgabe produzieren:
    echo "x minus 1 ist gleich " . $x-1 . ", hoffe ich jedenfalls\n";

    // die gewünschte Rangfolge kann durch die Verwendung von Klammern erzwungen werden:
    echo "x minus 1 ist gleich " . ($x-1) . ", hoffe ich jedenfalls\n";

    // Dies ist nicht erlaubt und führt zu einem TypeError:
    echo (("x minus 1 ist gleich " . $x) - 1) . ", hoffe ich jedenfalls\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    -1, hoffe ich jedenfalls
    -1, hoffe ich jedenfalls
    Fatal error: Uncaught TypeError: Unsupported operand types: string - int

Beispiel #5 Vor PHP 8 hatten `+`, `-` und `.` dieselbe Rangfolge

    <?php
    $x = 4;
    // diese Zeile könnte eine unerwartete Ausgabe produzieren:
    echo "x minus 1 ist gleich " . $x-1 . ", hoffe ich jedenfalls\n";

    // da es wie diese Zeile ausgewertet wird (vor PHP 8.0.0):
    echo (("x minus 1 ist gleich " . $x) - 1) . ", hoffe ich jedenfalls\n";

    // die gewünschte Rangfolge kann durch die Verwendung von Klammern erzwungen werden:
    echo "x minus 1 ist gleich " . ($x-1) . ", hoffe ich jedenfalls\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    -1, hoffe ich jedenfalls
    -1, hoffe ich jedenfalls
    x minus 1 ist gleich 3, hoffe ich jedenfalls

> Hinweis:

> Obwohl `=` einen niedrigeren Rang als die meisten anderen Operatoren hat, erlaubt PHP dennoch Ausdrücke wie den folgenden: `if (!$a = foo())`; in diesem Fall wird der Rückgabewert von `foo()` der Variablen $a zugewiesen.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Die Verkettung von Zeichenketten (`.`) hat jetzt eine niedrigere Rangfolge als die arithmetische Addition/Subtraktion (`+` und `-`) und bitweises Verschieben nach links/rechts (`<<` und `>>`); vorher hatte sie die gleiche Rangfolge wie `+` und `-` und eine höhere Rangfolge als `<<` und `>>`.
8.0.0 | Der ternäre Operator (`? :`) ist jetzt nicht-assoziativ; vorher war er links-assoziativ.
7.4.0 | Der Vorrang der String-Verkettung (`.`) gegenüber der arithmetischen Addition/Subtraktion (`+` oder `-`) oder bitweises Verschieben nach links/rechts (`<<` oder `>>`), d. h. die gemeinsame Verwendung in einem Ausdruck ohne Klammern, ist veraltet.
7.4.0 | Die Links-Assoziativität des ternären Operators (`? :`), d. h. die Verschachtelung mehrerer ternärer Operatoren, die nicht-in Klammern eingeschlossen sind, ist veraltet.

## Arithmetische Operatoren

Erinnern Sie sich noch an die Grundrechenarten aus der Schule? Die arithmetischen Operatoren funktionieren genauso:

Arithmetische Operatoren
Beispiel | Name | Ergebnis
--- | --- | ---
`+$a` | Identity | Umwandlung von $a nach int oder float je nach Bedarf.
`-$a` | Negation | Gegenzahl von $a.
`$a + $b` | Addition | Summe von $a und $b.
`$a - $b` | Subtraktion | Differenz von $a und $b.
`$a * $b` | Multiplikation | Produkt von $a und $b.
`$a / $b` | Division | Quotient von $a und $b.
`$a % $b` | Modulus | Rest von $a geteilt durch $b.
`$a ** $b` | Potenz | $b-te Potenz von $a.

Der Divisions-Operator `/` gibt einen Wert vom Typ float zurück, es sei denn beide Operanden sind vom Typ int (oder numerische Zeichenketten die in int umgewandelt werden) und der Zähler ist ein Vielfaches des Nenners; in diesem Fall wird eine Ganzzahl zurückgegeben. Für Ganzzahldivision siehe intdiv().

Operanden des Modulus-Operators werden vor der Verarbeitung in int umgewandelt. Für den Gleitkommazahlen-Modulus ist fmod() verfügbar.

Das Ergebnis des Modulus-Operators `%` hat dasselbe Vorzeichen wie der Dividend, d. h. das Ergebnis von `$a % $b` hat dasselbe Vorzeichen wie $a. Zum Beispiel:

Beispiel #1 Der Modulus-Operator

    <?php
    var_dump(5 % 3);
    var_dump(5 % -3);
    var_dump(-5 % 3);
    var_dump(-5 % -3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(2)
    int(2)
    int(-2)
    int(-2)

### Siehe auch

- Mathematische Funktionen

## Inkrement- bzw. Dekrement-Operatoren

PHP unterstützt Prä- und Post-Inkrement- und Dekrement-Operatoren. Diese unären (einstelligen) Operatoren ermöglichen es, einen Wert um eins zu erhöhen oder zu verringern.

Inkrement- und Dekrementoperatoren
Beispiel | Name | Auswirkung
--- | --- | ---
++$a | Prä-Inkrementierung | Erhöht $a um eins und gibt dann $a zurück.
$a++ | Post-Inkrementierung | Gibt $a zurück und erhöht $a dann um eins.
--$a | Prä-Dekrementierung | Vermindert $a um eins, und gibt dann $a zurück.
$a-- | Post-Dekrementierung | Gibt $a zurück, und vermindert $a dann um eins.

Beispiel #1 Beispiele für Inkrementierung/Dekrementierung

    <?php
    echo "Post-Inkrementierung", PHP_EOL;
    $a = 5;
    var_dump($a++);
    var_dump($a);

    echo "Prä-Inkrementierung", PHP_EOL;
    $a = 5;
    var_dump(++$a);
    var_dump($a);

    echo "Post-Dekrementierung", PHP_EOL;
    $a = 5;
    var_dump($a--);
    var_dump($a);

    echo "Prä-Dekrementierung", PHP_EOL;
    $a = 5;
    var_dump(--$a);
    var_dump($a);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Post-Inkrementierung:
    int(5)
    int(6)
    Prä-Inkrementierung:
    int(6)
    int(6)
    Post-Dekrementierung:
    int(5)
    int(4)
    Prä-Dekrementierung:
    int(4)
    int(4)

Warnung

Die Inkrement- und Dekrement-Operatoren wirken sich nicht auf Werte vom Typ bool aus. Seit PHP 8.3.0 wird ein `E_WARNING` ausgegeben, weil der Wert dadurch in Zukunft implizit in int umgewandelt wird.

Der Dekrement-Operator wirkt sich nicht auf Werte vom Typ null aus. Seit PHP 8.3.0 wird ein `E_WARNING` ausgegeben, weil der Wert dadurch in Zukunft implizit in int umgewandelt wird.

Der Dekrement-Operator wirkt sich nicht auf nicht-numerische Zeichenketten. aus Seit PHP 8.3.0 wird ein `E_WARNING` ausgegeben, weil in Zukunft ein TypeError geworfen wird.

> Hinweis:

> Interne Objekte, die das Überladen von Addition und/oder Subtraktion unterstützen, können ebenfalls inkrementiert und/oder dekrementiert werden. Ein solches internes Objekt ist GMP.

### Inkrementieren von Zeichenketten im PERL-Stil

Warnung

Diese Funktionalität ist seit PHP 8.3.0 veraltet (soft-deprecated). Stattdessen sollte die Funktion str_increment() verwendet werden.

In PHP ist es möglich, eine nicht-numerische Zeichenkette zu inkrementieren, sofern es sich um eine alphanumerische ASCII-Zeichenkette handelt. Dabei werden die Buchstaben bis zum nächsten Buchstaben hochgezählt, und bei Erreichen des Buchstabens `Z` wird die Inkrementierung auf den Wert auf der linken Seite übertragen. Beispielsweise verwandelt `$a = 'Z'; $a++;` $a in `'AA'`.

Beispiel #2 Beispiel für die Inkrementierung von Zeichenketten im PERL-Stil

    <?php
    echo '== Zeichenketten aus Buchstaben ==' . PHP_EOL;
    $s = 'W';
    for ($n=0; $n<6; $n++) {
        echo ++$s . PHP_EOL;
    }
    // Alphanumerische Zeichenketten verhalten sich anders
    echo '== Alphanumerische Zeichenketten ==' . PHP_EOL;
    $d = 'A8';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }
    $d = 'A08';
    for ($n=0; $n<6; $n++) {
        echo ++$d . PHP_EOL;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    == Zeichenketten aus Buchstaben ==
    X
    Y
    Z
    AA
    AB
    AC
    == Alphanumerische Zeichenketten ==
    A9
    B0
    B1
    B2
    B3
    B4
    A09
    A10
    A11
    A12
    A13
    A14

Warnung

Wenn eine alphanumerische Zeichenkette als numerische Zeichenkette interpretiert werden kann, wird sie in den Typ int oder float umgewandelt. Dies ist vor allem bei Zeichenketten ein Problem, die aussehen wie Gleitkommazahlen in Exponentialschreibweise. Die Funktion str_increment() nimmt diese impliziten Typumwandlungen nicht vor.

Beispiel #3 Umwandlung einer alphanumerischen Zeichenkette in eine Gleitkommazahl

    <?php
    $s = "5d9";
    var_dump(++$s);
    var_dump(++$s);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "5e0"
    float(6)

Das liegt daran, dass der Wert `"5e0"` als float interpretiert und in den Wert `5.0` umgewandelt wird, bevor er inkrementiert wird.

## Zuweisungsoperatoren

Der einfachste Zuweisungsoperator ist "=". Wahrscheinlich kommt man als erstes auf die Idee, ihn mit "ist gleich" zu bezeichnen. Das ist falsch. In Wirklichkeit bedeutet er, dass dem linken Operanden der Wert des Ausdrucks auf der rechten Seite zugewiesen wird (man müsste ihn also mit "wird gesetzt auf den Wert von" übersetzen).

Der Wert eines Zuweisungs-Ausdruckes ist der zugewiesene Wert, d. h. der Wert des Ausdruckes "`$a = 3`" ist 3. Das erlaubt es, einige raffinierte Dinge anzustellen:

Beispiel #1 Verschachtelte Zuweisungen

    <?php
    $a = ($b = 4) + 5; // $a ist nun gleich 9 und $b wurde auf den Wert 4 gesetzt.
    var_dump($a);
    ?>

Zusätzlich zu dem oben vorgestellten Zuweisungsoperator "=" gibt es "kombinierte Operatoren" für alle binären, arithmetischen, Array-Vereinigungs- und Zeichenketten-Operatoren, die es erlauben, den Wert einer Variablen in einem Ausdruck zu benutzen und dieser anschließend das Ergebnis des Ausdrucks als neuen Wert zuzuweisen. Zum Beispiel:

Beispiel #2 Kombinierte Zuweisungen

    <?php
    $a = 3;
    $a += 5; // setzt $a auf den Wert 8, als ob wir geschrieben hätten: $a = $a + 5;
    $b = "Hallo ";
    $b .= "Du!"; // setzt $b auf den Wert "Hallo Du!", äquivalent zu

    var_dump($a, $b);
    ?>

Man beachte, dass die Zuweisung nur den Wert der Ursprungsvariable der neuen Variable zuweist (Zuweisung als Wert, sie "kopiert"), weshalb sich Änderungen an der einen Variable nicht auf die andere auswirken werden. Das kann wichtig sein, wenn man ein großes Array o. ä. in einer Schleife kopieren muss.

Eine Ausnahme vom üblichen Wertzuweisungsverhalten in PHP stellen Objekte (object) dar, die per Referenz zugewiesen werden. Objekte können mit dem clone-Schlüsselwort explizit kopiert werden.

### Referenzzuweisung

Referenzzuweisung wird ebenfalls unterstützt, unter Verwendung der "$var = &$othervar;" Syntax. Referenzzuweisung bedeutet, dass beide Variablen schließlich auf dieselben Daten zeigen, und nichts kopiert wurde.

Beispiel #3 Referenzzuweisung

    <?php
    $a = 3;
    $b = &$a; // $b ist eine Referenz auf $a

    print "$a\n"; // gibt 3 aus
    print "$b\n"; // gibt 3 aus

    $a = 4; // ändere $a

    print "$a\n"; // gibt 4 aus
    print "$b\n"; // gibt ebenfalls 4 aus, da $b eine Referenz auf $a ist, das
                  // geändert wurde
    ?>

Der new-Operator gibt automatisch eine Referenz zurück, sodass das Zuweisen des Ergebnisses von new per Referenz ein Fehler ist.

Beispiel #4 new-Operator per Referenz

    <?php
    class C {}

    $o = &new C;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Parse error: syntax error, unexpected token ";", expecting "("

Weitere Informationen zu Referenzen und ihren Anwendungsmöglichkeiten sind dem Handbuch-Abschnitt Referenzen erklärt zu entnehmen.

### Arithmetische Zuweisungsoperatoren

Beispiel | Entsprechung | Operation
--- | --- | ---
$a += $b | $a = $a + $b | Addition
$a -= $b | $a = $a - $b | Subtraktion
$a *= $b | $a = $a * $b | Multiplikation
$a /= $b | $a = $a / $b | Division
$a %= $b | $a = $a % $b | Modulus
$a **= $b | $a = $a ** $b | Potenzierung

### Bitweise Zuweisungsoperatoren

Beispiel | Entsprechung | Operation
--- | --- | ---
$a &= $b | $a = $a & $b | Und
$a |= $b | $a = $a | $b | Oder
$a ^= $b | $a = $a ^ $b | Xor
$a <<= $b | $a = $a << $b | Linksverschiebung
$a >>= $b | $a = $a >> $b | Rechtsverschiebung

### Andere Zuweisungspperatoren

Beispiel | Entsprechung | Operation
--- | --- | ---
$a .= $b | $a = $a . $b | Stringverknüpfung
$a ??= $b | $a = $a ?? $b | Null-Zusammenführungsoperator

### Siehe auch

- Arithmetische Operatoren
- Bit-Operatoren
- Null-Koaleszenz-Operator

## Bit-Operatoren

Bit-Operatoren erlauben es die Prüfung und Manipulation von bestimmten Bits in einem Integer.

Bit-Operatoren
Beispiel | Name | Ergebnis
--- | --- | ---
`$a & $b` | And (Und) | Bits, die in $a und $b gesetzt sind, werden gesetzt.
`$a | $b` | Or (inklusives Oder) | Bits, die in $a oder $b gesetzt sind, werden gesetzt.
`$a ^ $b` | Xor (exklusives Oder) | Bits, die entweder in $a oder $b, jedoch nicht in beiden gesetzt sind, werden gesetzt.
`~ $a` | Not (Nicht) | Bits, die in $a nicht gesetzt sind, werden gesetzt, und umgekehrt.
`$a << $b` | Nach links verschieben | Verschiebung der Bits von $a um $b Stellen nach links (jede Stelle entspricht einer Mulitplikation mit zwei).
`$a >> $b` | Nach rechts verschieben | Verschiebung der Bits von $a um $b Stellen nach rechts (jede Stelle entspricht einer Division durch zwei).

Bit-Verschiebungen in PHP sind arithmetisch. Bits, die an einem der Enden herausgeschoben werden, werden verworfen. Bei Links-Verschiebungen werden von rechts Nullen hereingeschoben, während das Vorzeichenbit links herausgeschoben wird, was bedeutet, dass das Vorzeichen des Operanden nicht erhalten bleibt. Bei Rechts-Verschiebungen werden Kopien des Vorzeichenbits von links hereingeschoben, sodass das Vorzeichen des Operanden erhalten bleibt.

Klammern sind zu verwenden, um die gewünschte Rangfolge sicherzustellen. Beispielsweise wird bei `$a & $b == true` zunächst der Vergleich ausgewertet, und erst dann das Bit-Und, während bei `($a & $b) == true` zunächst das Bit-Und, und erst dann der Vergleich ausgewertet wird.

Sind beide Operanden der `&`, `|` und `^` Operatoren Zeichenketten, dann wird die Operation auf den ASCII-Werten der Zeichen der Zeichenketten durchgeführt, und das Ergebnis ist wiederum eine Zeichenkette. In allen anderen Fällen werden beide Operanden nach Integer umgewandelt und das Ergebnis ist eine Ganzzahl.

Ist der Operand des `~` Operators eine Zeichenkette, dann wird die Operation auf den ASCII-Werten der Zeichen der Zeichenkette durchgeführt, Und das Ergebnis ist wiederum eine Zeichenkette. Andernfalls werden Operand und Ergebnis als Ganzzahl behandelt.

Beide Operanden und das Ergebnis der `<<` und `>>`-Operatoren werden immer als Ganzzahl behandelt.

Die ini-Einstellung error_reporting von PHP verwendet Bitwerte, was die realitätsnahe Demonstration des Ausschaltens einzelner Bits bietet. Um alle Fehler außer Hinweisen anzuzeigen, muss den Anweisungen der php.ini-Datei entsprechend verwendet werden: `E_ALL & ~E_NOTICE`

         Dies funktioniert, indem mit E_ALL begonnen wird:
         00000000000000000111011111111111
         Dann wird der Wert von E_NOTICE genommen...
         00000000000000000000000000001000
         ... und dieser per ~ invertiert:
         11111111111111111111111111110111
         Schließlich wird AND (&) verwendet, um die Bits zu ermitteln, die in
         beiden Werten gesetzt sind:
         00000000000000000111011111110111

Eine andere Möglichkeit dies zu bewerkstelligen, ist XOR (`^`) zu verwenden, um diejenigen Bits zu finden, die nur in einem der beiden Werte gesetzt sind: `E_ALL ^ E_NOTICE`

error_reporting kann ebenfalls verwendet werden, um zu zeigen, wie Bits gesetzt werden. Auf folgende Weise werden nur Fehler und behebbare Fehler angezeigt: `E_ERROR | E_RECOVERABLE_ERROR`

         Dieser Vorgang kombiniert E_ERROR
         00000000000000000000000000000001
         und
         00000000000000000001000000000000
         unter Verwendung des OR- (|) Operators
         um die Bits zu ermitteln, die in einem oder beiden Werten gesetzt sind:
         00000000000000000001000000000001

Beispiel #1 Bitweise AND, OR und XOR Operationen mit Ganzzahlen

    <?php
    /*
     * Der erste Abschnitt kann ignoriert werden;
     * er dient nur zu Formatierungszwecken, um die Ausgabe deutlicher zu machen.
     */

    $format = '(%1$2d = %1$04b) = (%2$2d = %2$04b)'
          . ' %3$s (%4$2d = %4$04b)' . "\n";

    echo <<<EOH
     ---------     ---------  -- ---------
     Ergebnis      Wert 1     Op Wert 2
     ---------     ---------  -- ---------
    EOH;

    /*
     * Hier kommen die Beispiele.
     */

    $values = array(0, 1, 2, 4, 8);
    $test = 1 + 4;

    echo "\n Bitweises AND \n";
    foreach ($values as $value) {
        $result = $value & $test;
        printf($format, $result, $value, '&', $test);
    }

    echo "\n Bitweises einschließendes OR \n";
    foreach ($values as $value) {
        $result = $value | $test;
        printf($format, $result, $value, '|', $test);
    }

    echo "\n Bitweises ausschließendes OR (XOR) \n";
    foreach ($values as $value) {
        $result = $value ^ $test;
        printf($format, $result, $value, '^', $test);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

     ---------     ---------  -- ---------
     Ergebnis      Wert 1     Op Wert 2
    ---------     ---------  -- ---------
     Bitweises AND
    ( 0 = 0000) = ( 0 = 0000) & ( 5 = 0101)
    ( 1 = 0001) = ( 1 = 0001) & ( 5 = 0101)
    ( 0 = 0000) = ( 2 = 0010) & ( 5 = 0101)
    ( 4 = 0100) = ( 4 = 0100) & ( 5 = 0101)
    ( 0 = 0000) = ( 8 = 1000) & ( 5 = 0101)

     Bitweises einschließendes OR
    ( 5 = 0101) = ( 0 = 0000) | ( 5 = 0101)
    ( 5 = 0101) = ( 1 = 0001) | ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) | ( 5 = 0101)
    ( 5 = 0101) = ( 4 = 0100) | ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) | ( 5 = 0101)

     Bitweises ausschließendes OR (XOR)
    ( 5 = 0101) = ( 0 = 0000) ^ ( 5 = 0101)
    ( 4 = 0100) = ( 1 = 0001) ^ ( 5 = 0101)
    ( 7 = 0111) = ( 2 = 0010) ^ ( 5 = 0101)
    ( 1 = 0001) = ( 4 = 0100) ^ ( 5 = 0101)
    (13 = 1101) = ( 8 = 1000) ^ ( 5 = 0101)

Beispiel #2 Bitweise XOR-Operationen mit Zeichenketten

    <?php
    echo 12 ^ 9, PHP_EOL; // Gibt '5' aus

    echo "12" ^ "9", PHP_EOL; // Gibt das Backspace-Zeichen (ascii 8) aus
                              // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

    echo "hallo" ^ "hello", PHP_EOL; // Gibt die ascii-Werte #0 #4 #0 #0 #0 aus
                                     // 'a' ^ 'e' = #4

    echo 2 ^ "3", PHP_EOL; // Gibt 1 aus
                           // 2 ^ ((int) "3") == 1

    echo "2" ^ 3, PHP_EOL; // Gibt 1 aus
                           // ((int) "2") ^ 3 == 1
    ?>

Beispiel #3 Bit-Verschiebung mit Ganzzahlen

    <?php
    /*
     * Hier kommen die Beispiele.
     */

    echo "\n--- RECHTSVERSCHIEBUNG MIT POSITIVEN GANZZAHLEN ---\n";

    $val = 4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'Kopie des Vorzeichenbits wird links hereingeschoben');

    $val = 4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places);

    $val = 4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'Bits werden rechts herausgeschoben');

    $val = 4;
    $places = 4;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'dasselbe Ergebnis wie oben; man kann nicht über 0 hinaus verschieben');

    echo "\n--- RECHTSVERSCHIEBUNG MIT NEGATIVEN GANZZAHLEN ---\n";

    $val = -4;
    $places = 1;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'Kopie des Vorzeichenbits wird links hereingeschoben');

    $val = -4;
    $places = 2;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'Bits werden rechts herausgeschoben');

    $val = -4;
    $places = 3;
    $res = $val >> $places;
    p($res, $val, '>>', $places, 'dasselbe Ergebnis wie oben; man kann nicht über -1 hinaus verschieben');

    echo "\n--- LINKSSVERSCHIEBUNG MIT POSITIVEN GANZZAHLEN ---\n";

    $val = 4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'Nullen werden rechts hereingeschoben');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 4;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'Vorzeichenbits werden herausgeschoben');

    $val = 4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'Bits werden links herausgeschoben');

    echo "\n--- LINKSVERSCHIEBUNG MIT NEGATIVEN GANZZAHLEN ---\n";

    $val = -4;
    $places = 1;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'Nullen werden rechts hereingeschoben');

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 3;
    $res = $val << $places;
    p($res, $val, '<<', $places);

    $val = -4;
    $places = (PHP_INT_SIZE * 8) - 2;
    $res = $val << $places;
    p($res, $val, '<<', $places, 'Bits werden links herausgeschoben, einschließlich des Vorzeichenbits');

    /*
     * Dieser Abschnitt kann ignoriert werden;
     * es handlet sich nur um Formatierung, um die Ausgabe deutlicher zu machen.
     */

    function p($res, $val, $op, $places, $note = '') {
        $format = '%0' . (PHP_INT_SIZE * 8) . "b\n";

        printf("Ausdruck: %d = %d %s %d\n", $res, $val, $op, $places);

        echo " Dezimal:\n";
        printf("  Wert=%d\n", $val);
        printf("  Erg.=%d\n", $res);

        echo " Binär:\n";
        printf('  Wert=' . $format, $val);
        printf('  Erg.=' . $format, $res);

        if ($note) {
            echo " ANMERKUNG: $note\n";
        }

        echo "\n\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt auf 32-Bit-Systemen folgende Ausgabe:

    --- RECHTSVERSCHIEBUNG MIT POSITIVEN GANZZAHLEN ---
    Ausdruck: 2 = 4 >> 1
     Dezimal:
      Wert=4
      Erg.=2
     Binär:
      Wert=00000000000000000000000000000100
      Erg.=00000000000000000000000000000010
     ANMERKUNG: Kopie des Vorzeichenbits wird links hereingeschoben

    Ausdruck: 1 = 4 >> 2
     Dezimal:
      Wert=4
      Erg.=1
     Binär:
      Wert=00000000000000000000000000000100
      Erg.=00000000000000000000000000000001

    Ausdruck: 0 = 4 >> 3
     Dezimal:
      Wert=4
      Erg.=0
     Binär:
      Wert=00000000000000000000000000000100
      Erg.=00000000000000000000000000000000
     ANMERKUNG: Bits werden rechts herausgeschoben

    Ausdruck: 0 = 4 >> 4
     Dezimal:
      Wert=4
      Erg.=0
     Binär:
      Wert=00000000000000000000000000000100
      Erg.=00000000000000000000000000000000
     ANMERKUNG: dasselbe Ergebnis wie oben; man kann nicht über 0 hinaus verschieben

    --- RECHTSVERSCHIEBUNG MIT NEGATIVEN GANZZAHLEN ---
    Ausdruck: -2 = -4 >> 1
     Dezimal:
      Wert=-4
      Erg.=-2
     Binär:
      Wert=11111111111111111111111111111100
      Erg.=11111111111111111111111111111110
     ANMERKUNG: Kopie des Vorzeichenbits wird links hereingeschoben

    Ausdruck: -1 = -4 >> 2
     Dezimal:
      Wert=-4
      Erg.=-1
     Binär:
      Wert=11111111111111111111111111111100
      Erg.=11111111111111111111111111111111
     ANMERKUNG: Bits werden rechts herausgeschoben

    Ausdruck: -1 = -4 >> 3
     Dezimal:
      Wert=-4
      Erg.=-1
     Binär:
      Wert=11111111111111111111111111111100
      Erg.=11111111111111111111111111111111
     ANMERKUNG: dasselbe Ergebnis wie oben; man kann nicht über -1 hinaus verschieben

    --- LINKSSVERSCHIEBUNG MIT POSITIVEN GANZZAHLEN ---
    Ausdruck: 8 = 4 << 1
     Dezimal:
      Wert=4
      Erg.=8
     Binär:
      Wert=00000000000000000000000000000100
      Erg.=00000000000000000000000000001000
     ANMERKUNG: Nullen werden rechts hereingeschoben

    Ausdruck: 1073741824 = 4 << 28
     Dezimal:
      Wert=4
      Erg.=1073741824
     Binär:
      Wert=00000000000000000000000000000100
      Erg.=01000000000000000000000000000000

    Ausdruck: -2147483648 = 4 << 29
     Dezimal:
      Wert=4
      Erg.=-2147483648
     Binär:
      Wert=00000000000000000000000000000100
      Erg.=10000000000000000000000000000000
     ANMERKUNG: Vorzeichenbits werden herausgeschoben

    Ausdruck: 0 = 4 << 30
     Dezimal:
      Wert=4
      Erg.=0
     Binär:
      Wert=00000000000000000000000000000100
      Erg.=00000000000000000000000000000000
     ANMERKUNG: Bits werden links herausgeschoben

    --- LINKSVERSCHIEBUNG MIT NEGATIVEN GANZZAHLEN ---
    Ausdruck: -8 = -4 << 1
     Dezimal:
      Wert=-4
      Erg.=-8
     Binär:
      Wert=11111111111111111111111111111100
      Erg.=11111111111111111111111111111000
     ANMERKUNG: Nullen werden rechts hereingeschoben

    Ausdruck: -2147483648 = -4 << 29
     Dezimal:
      Wert=-4
      Erg.=-2147483648
     Binär:
      Wert=11111111111111111111111111111100
      Erg.=10000000000000000000000000000000

    Ausdruck: 0 = -4 << 30
     Dezimal:
      Wert=-4
      Erg.=0
     Binär:
      Wert=11111111111111111111111111111100
      Erg.=00000000000000000000000000000000
     ANMERKUNG: Bits werden links herausgeschoben, einschließlich des Vorzeichenbits

Das oben gezeigte Beispiel erzeugt auf 64-Bit-Systemen folgende Ausgabe:

    --- RECHTSVERSCHIEBUNG MIT POSITIVEN GANZZAHLEN ---
    Ausdruck: 2 = 4 >> 1
     Dezimal:
      Wert=4
      Erg.=2
     Binär:
      Wert=0000000000000000000000000000000000000000000000000000000000000100
      Erg.=0000000000000000000000000000000000000000000000000000000000000010
     ANMERKUNG: Kopie des Vorzeichenbits wird links hereingeschoben

    Ausdruck: 1 = 4 >> 2
     Dezimal:
      Wert=4
      Erg.=1
     Binär:
      Wert=0000000000000000000000000000000000000000000000000000000000000100
      Erg.=0000000000000000000000000000000000000000000000000000000000000001

    Ausdruck: 0 = 4 >> 3
     Dezimal:
      Wert=4
      Erg.=0
     Binär:
      Wert=0000000000000000000000000000000000000000000000000000000000000100
      Erg.=0000000000000000000000000000000000000000000000000000000000000000
     ANMERKUNG: Bits werden rechts herausgeschoben

    Ausdruck: 0 = 4 >> 4
     Dezimal:
      Wert=4
      Erg.=0
     Binär:
      Wert=0000000000000000000000000000000000000000000000000000000000000100
      Erg.=0000000000000000000000000000000000000000000000000000000000000000
     ANMERKUNG: dasselbe Ergebnis wie oben; man kann nicht über 0 hinaus verschieben

    --- RECHTSVERSCHIEBUNG MIT NEGATIVEN GANZZAHLEN ---
    Ausdruck: -2 = -4 >> 1
     Dezimal:
      Wert=-4
      Erg.=-2
     Binär:
      Wert=1111111111111111111111111111111111111111111111111111111111111100
      Erg.=1111111111111111111111111111111111111111111111111111111111111110
     ANMERKUNG: Kopie des Vorzeichenbits wird links hereingeschoben

    Ausdruck: -1 = -4 >> 2
     Dezimal:
      Wert=-4
      Erg.=-1
     Binär:
      Wert=1111111111111111111111111111111111111111111111111111111111111100
      Erg.=1111111111111111111111111111111111111111111111111111111111111111
     ANMERKUNG: Bits werden rechts herausgeschoben

    Ausdruck: -1 = -4 >> 3
     Dezimal:
      Wert=-4
      Erg.=-1
     Binär:
      Wert=1111111111111111111111111111111111111111111111111111111111111100
      Erg.=1111111111111111111111111111111111111111111111111111111111111111
     ANMERKUNG: dasselbe Ergebnis wie oben; man kann nicht über -1 hinaus verschieben

    --- LINKSSVERSCHIEBUNG MIT POSITIVEN GANZZAHLEN ---
    Ausdruck: 8 = 4 << 1
     Dezimal:
      Wert=4
      Erg.=8
     Binär:
      Wert=0000000000000000000000000000000000000000000000000000000000000100
      Erg.=0000000000000000000000000000000000000000000000000000000000001000
     ANMERKUNG: Nullen werden rechts hereingeschoben

    Ausdruck: 4611686018427387904 = 4 << 60
     Dezimal:
      Wert=4
      Erg.=4611686018427387904
      Binär:
      Wert=0000000000000000000000000000000000000000000000000000000000000100
      Erg.=0100000000000000000000000000000000000000000000000000000000000000

    Ausdruck: -9223372036854775808 = 4 << 61
     Dezimal:
      Wert=4
      Erg.=-9223372036854775808
     Binär:
      Wert=0000000000000000000000000000000000000000000000000000000000000100
      Erg.=1000000000000000000000000000000000000000000000000000000000000000
     ANMERKUNG: Vorzeichenbits werden herausgeschoben

    Ausdruck: 0 = 4 << 62
     Dezimal:
      Wert=4
      Erg.=0
     Binär:
      Wert=0000000000000000000000000000000000000000000000000000000000000100
      Erg.=0000000000000000000000000000000000000000000000000000000000000000
     ANMERKUNG: Bits werden links herausgeschoben

    --- LINKSVERSCHIEBUNG MIT NEGATIVEN GANZZAHLEN ---
    Ausdruck: -8 = -4 << 1
     Dezimal:
      Wert=-4
      Erg.=-8
     Binär:
      Wert=1111111111111111111111111111111111111111111111111111111111111100
      Erg.=1111111111111111111111111111111111111111111111111111111111111000
     ANMERKUNG: Nullen werden rechts hereingeschoben

    Ausdruck: -9223372036854775808 = -4 << 61
     Dezimal:
      Wert=-4
      Erg.=-9223372036854775808
     Binär:
      Wert=1111111111111111111111111111111111111111111111111111111111111100
      Erg.=1000000000000000000000000000000000000000000000000000000000000000

    Ausdruck: 0 = -4 << 62
     Dezimal:
      Wert=-4
      Erg.=0
     Binär:
      Wert=1111111111111111111111111111111111111111111111111111111111111100
      Erg.=0000000000000000000000000000000000000000000000000000000000000000
     ANMERKUNG: Bits werden links herausgeschoben, einschließlich des Vorzeichenbits

Warnung

Für die bitweise Manipulation von Zahlen größer als `PHP_INT_MAX` sind die Funktion der GMP-Erweiterung zu verwenden.

### Siehe auch

- pack()
- unpack()
- gmp_and()
- gmp_or()
- gmp_xor()
- gmp_testbit()
- gmp_clrbit()

## Vergleichs-Operatoren

Vergleichs-Operatoren erlauben es – wie der Name schon sagt – zwei Werte zu vergleichen. Wenn Sie an Beispielen verschiedener auf Typen bezogener Vergleiche interessiert sind, können Sie sich die PHP Typvergleich-Tabellen anschauen.

Vergleichsoperatoren
Beispiel | Name | Ergebnis
--- | --- | ---
$a == $b | Gleich | Gibt `true` zurück, wenn nach der Typumwandlung $a gleich $b ist.
$a === $b | Identisch | Gibt `true` zurück, wenn $a gleich $b ist und beide denselben Typ haben.
$a != $b | Ungleich | Gibt `true` zurück, wenn nach der Typumwandlung $a nicht gleich $b ist.
$a <> $b | Ungleich | Gibt `true` zurück, wenn nach der Typumwandlung $a nicht gleich $b ist.
$a !== $b | Nicht identisch | Gibt `true` zurück, wenn $a nicht gleich $b ist, oder wenn beide nicht denselben Typ haben.
$a < $b | Kleiner als | Gibt `true` zurück, wenn $a kleiner als $b ist.
$a > $b | Größer als | Gibt `true` zurück, wenn $a größer als $b ist.
$a <= $b | Kleiner oder gleich | Gibt `true` zurück, wenn $a kleiner oder gleich $b ist.
$a >= $b | Größer oder gleich | Gibt `true` zurück, wenn $a größer oder gleich $b ist.
$a <=> $b | Raumschiff | Eine Ganzzahl (int), die kleiner als, gleich oder größer als 0 ist, wenn $a kleiner als, gleich oder größer als $b ist.

Falls beide Operanden numerische Zeichenketten sind oder ein Operand eine Zahl ist und der andere eine numerische Zeichenkette, dann wird der Vergleich numerisch durchgeführt. Diese Regel gilt ebenfalls für die switch-Anweisung. Die Typumwandlung wird nicht durchgeführt, wenn der Vergleichsoperator `===` oder `!==` ist, da hier sowohl der Typ als auch der Wert verglichen werden.

Warnung

Vor PHP 8.0.0 wurde bei einem Vergleich einer Zeichenkette mit einer Zahl oder einer numerischen Zeichenkette die Zeichenkette vor dem Vergleich in eine Zahl umgewandelt und der Vergleich numerisch durchgeführt.

    <?php
    var_dump(0 == "a");
    var_dump("1" == "01");
    var_dump("10" == "1e1");
    var_dump(100 == "1e2");

    switch ("a") {
    case 0:
        echo "0";
        break;
    case "a":
        echo "a";
        break;
    }
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 7 folgende Ausgabe:

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    0

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    a

Beispiel #1 Vergleichsoperatoren

    <?php
    // Ganzzahlen
    echo 1 <=> 1, ' '; // 0
    echo 1 <=> 2, ' '; // -1
    echo 2 <=> 1, ' '; // 1

    // Gleitkommazahlen
    echo 1.5 <=> 1.5, ' '; // 0
    echo 1.5 <=> 2.5, ' '; // -1
    echo 2.5 <=> 1.5, ' '; // 1

    // Zeichenketten
    echo "a" <=> "a", ' '; // 0
    echo "a" <=> "b", ' '; // -1
    echo "b" <=> "a", ' '; // 1

    echo "a" <=> "aa", ' ';  // -1
    echo "zz" <=> "aa", ' '; // 1

    // Arrays
    echo [] <=> [], ' ';               // 0
    echo [1, 2, 3] <=> [1, 2, 3], ' '; // 0
    echo [1, 2, 3] <=> [], ' ';        // 1
    echo [1, 2, 3] <=> [1, 2, 1], ' '; // 1
    echo [1, 2, 3] <=> [1, 2, 4], ' '; // -1

    // Objekte
    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 0

    $a = (object) ["a" => "b"];
    $b = (object) ["a" => "c"];
    echo $a <=> $b, ' '; // -1

    $a = (object) ["a" => "c"];
    $b = (object) ["a" => "b"];
    echo $a <=> $b, ' '; // 1

    // nicht nur die Werte werden verglichen; die Schlüssel müssen übereinstimmen
    $a = (object) ["a" => "b"];
    $b = (object) ["b" => "b"];
    echo $a <=> $b, ' '; // 1

    ?>

Für die verschiedenen Typen wird der Vergleich gemäß der folgenden Tabelle durchgeführt (in der angegebenen Reihenfolge).

Vergleich mit verschiedenen Typen
Typ des 1. Operanden | Typ des 2. Operanden | Ergebnis
--- | --- | ---
null oder string | string | Umwandlung von `null` nach "", dann numerischer oder lexikalischer Vergleich
bool oder null | anything | Umwandlung beider Werte nach bool, dann `false` < `true`
object | object | Eingebaute Klassen können eigene Vergleichsregeln definieren; verschiedene Klassen können nicht verglichen werden; für den Vergleich von Objekten derselben Klasse siehe Objektvergleiche
string, resource, int oder float | string, resource, int oder float | Umwandlung von Zeichenketten und Ressourcen in Zahlen, dann numerischer Vergleich
array | array | Das Array mit weniger Elementen ist kleiner; wird ein Schlüssel vom ersten Operanden nicht im zweiten gefunden, dann sind die Arrays nicht vergleichbar, andernfalls wird Element für Element verglichen (siehe folgendes Beispiel)
object | anything | object ist immer größer
array | anything | array ist immer größer

Beispiel #2 Boolesche und null-Vergleiche

    <?php
    // Boolesche Werte und null werden immer als Boolesche Werte verglichen
    var_dump(1 == TRUE);  // TRUE - dasselbe wie (bool) 1 == TRUE
    var_dump(0 == FALSE); // TRUE - dasselbe wie (bool) 0 == FALSE
    var_dump(100 < TRUE); // FALSE - dasselbe wie (bool) 100 < TRUE
    var_dump(-10 < FALSE);// FALSE - dasselbe wie (bool) -10 < FALSE
    var_dump(min(-100, -10, NULL, 10, 100)); // NULL - (bool) NULL < (bool) -100 ist FALSE < TRUE
    ?>

Beispiel #3 Umschreibung von Standard-Array-Vergleichen

    <?php
    // Arrays werden mit den normalen Vergleichsoperatoren sowie dem Raumschiff-Operator wie folgt verglichen
    function standard_array_compare($op1, $op2)
    {
        if (count($op1) < count($op2)) {
            return -1; // $op1 < $op2
        } elseif (count($op1) > count($op2)) {
            return 1; // $op1 > $op2
        }
        foreach ($op1 as $key => $val) {
            if (!array_key_exists($key, $op2)) {
                return 1;
            } elseif ($val < $op2[$key]) {
                return -1;
            } elseif ($val > $op2[$key]) {
                return 1;
            }
        }
        return 0; // $op1 == $op2
    }
    ?>

Warnung

# Vergleich von Gleitkommazahlen

Aufgrund der Art wie Gleitkommazahlen (float) intern dargestellt werden, sollten zwei Gleitkommazahlen nicht auf Gleichheit getestet werden.

Weitere Informationen sind der Dokumantation von float zu entnehmen.

> Hinweis: Es ist wichtig zu beachten, dass die Typumwandlung von PHP nicht immer offensichtlich ist, wenn Werte unterschiedlichen Typs verglichen werden, insbesondere beim Vergleich von Integern mit Booleans oder Integern mit Strings. Daher ist es im Allgemeinen in den meisten Fällen ratsam, `===` und `!==` für Vergleiche zu verwenden, anstatt `==` und `!=`.

### Nicht vergleichbare Werte

Während der Identitätsvergleich (`===` und `!==`) auf beliebige Werte angewendet werden kann, sollten die anderen Vergleichsoperatoren nur auf vergleichbare Werte angewandt werden. Wenn nicht vergleichbare Werte verglichen werden, ist das Ergebnis undefiniert und sollte nicht als verlässlich eingestuft werden.

### Siehe auch

- strcasecmp()
- strcmp()
- Array-Operatoren
- Typen

### Ternärer Operator

Ein weiterer Vergleichs-Operator ist der "?:" (oder ternäre) Operator.

Beispiel #4 Zuweisen eines Standardwerts

    <?php
    // Beispielanwendung für den ternären Operator
    $action = (empty($_POST['action'])) ? 'standard' : $_POST['action'];

    // Obiges ist mit dieser if/else-Anweisung identisch
    if (empty($_POST['action'])) {
        $action = 'standard';
    } else {
        $action = $_POST['action'];
    }

    ?>

Der Ausdruck `(ausdr1) ? (ausdr2) : (ausdr3)` wird zu ausdr2 ausgewertet, wenn ausdr1 als `true` ausgewertet wird, und zu ausdr3, wenn ausdr1 zu `false` ausgewertet wird.

Beim ternären Operator kann der mittlere Teil weggelassen werden. Der Ausdruck `(ausdr1) ?: (ausdr3)` wird zum Ergebnis von ausdr1 zurück, wenn ausdr1 zu `true` ausgewertet wird, und zu ausdr3 andernfalls. ausdr1 wird in diesem Fall nur einmal ausgewertet.

> Hinweis: Es ist zu beachten, dass der ternäre Operator ein Ausdruck ist und nicht als Variable, sondern als Wert eines Ausdrucks ausgewertet wird. Dies ist unbedingt zu berücksichtigen, wenn eine Variable per Referenz zurückgegeben werden soll. Die Anweisung `return $var == 42 ? $a : $b;` in einer Funktion, die per Referenz zurückgibt, wird daher nicht funktionieren und eine Warnung erzeugen.

> Hinweis:

> Es wird empfohlen, die "Verschachtelung" von ternären Ausdrücken zu vermeiden. Das Verhalten von PHP bei der Verwendung von mehr als einem nicht einkgeklammerten ternären Operator innerhalb eines einzigen Ausdrucks ist im Vergleich zu anderen Sprachen nicht eindeutig. In der Tat wurden ternäre Ausdrücke vor PHP 8.0.0 links-assoziativ (von links nach rechts) ausgewertet, und nicht rechts-assoziativ wie in den meisten anderen Programmiersprachen. Die Links-Assoziativität ist seit PHP 7.4.0 veraltet. Seit PHP 8.0.0 ist der ternäre Operator nicht-assoziativ.

> Beispiel #5 Ungewöhnliches Verhalten des ternären Operators

>     <?php
>     // auf den ersten Blick scheint das folgende 'true' auszugeben
>     echo (true ? 'true' : false ? 't' : 'f');

>     // allerdings wird vor PHP 8.0.0 tatsächlich 't' ausgegeben
>     // das kommt daher, dass ternäre Ausdrücke links-assoziativ ausgewertet werden

>     // das Folgende ist eine augenfälligere Variante desselben Codes wie oben
>     echo ((true ? 'true' : false) ? 't' : 'f');

>     // hier kann man sehen, dass der erste Ausdruck zu 'true' ausgewertet wird,
>     // was wiederum zu (bool) true ausgewertet wird, und daher wird der Wahr-Zweig
>     // des zweiten ternären Ausdrucks zurückgegeben.
>     ?>

> Hinweis:

> Die Verkettung von kurzen ternären Operatoren (`?:`) ist jedoch stabil und verhält sich plausibel. Sie wird zum ersten Argument ausgewertet, das einen nicht-falschen Wert ergibt. Es ist zu beachten, dass undefinierte Werte immer noch eine Warnung auslösen.

> Beispiel #6 Verkettung kurzer ternärer Operatoren

>     <?php
>     echo 0 ?: 1 ?: 2 ?: 3, PHP_EOL; //1
>     echo 0 ?: 0 ?: 2 ?: 3, PHP_EOL; //2
>     echo 0 ?: 0 ?: 0 ?: 3, PHP_EOL; //3
>     ?>

### Null-Koaleszens-Operator

Eine weitere nützliche Kurzform eines Operators ist der Operator "??" (null-Koaleszenz-Operator, etwa: Zuweisungsoperator für die Kombination mit null).

Beispiel #7 Zuweisung eines Standardwerts

    <?php
    // Beispiel für die Verwendung des null-Koaleszenz-Operators
    $action = $_POST['action'] ?? 'standard';

    // Obiges ist mit dieser if/else-Anweisung identisch
    if (isset($_POST['action'])) {
        $action = $_POST['action'];
    } else {
        $action = 'standard';
    }
    ?>

Der Ausdruck `(ausdr1) ?? (ausdr2)` wird zu ausdr2 ausgewertet, wenn ausdr1 `null` ist, und zu ausdr1 andernfalls.

Insbesondere gibt dieser Operator keinen Hinweis und keine Warnung aus, wenn der Wert auf der linken Seite nicht existiert, genau wie isset(). Dies ist besonders für Array-Schlüssel nützlich.

> Hinweis: Es ist zu beachten, dass der null-Koaleszenz-Operator ein Ausdruck ist und nicht als Variable, sondern als Wert eines Ausdrucks ausgewertet wird. Dies ist unbedingt zu berücksichtigen, wenn eine Variable per Referenz zurückgegeben werden soll. Die Anweisung `return $foo ?? $bar;` in einer Funktion, die per Referenz zurückgibt, wird daher nicht funktionieren, und eine Warnung erzeugen.

> Hinweis:

> Der null-Koaleszenz-Operator hat eine niedrige Priorität. Das heißt, wenn er mit anderen Operatoren (z. B. Verkettung von Zeichenketten oder arithmetische Operatoren) kombiniert wird, sind wahrscheinlich Klammern erforderlich.

>     <?php
>     // Löst die Warnung aus, dass $name undefiniert ist.
>     print 'Mr. ' . $name ?? 'Anonymous';

>     // Gibt "Mr. Anonymous" aus
>     print 'Mr. ' . ($name ?? 'Anonymous');
>     ?>

> Hinweis:

> Es ist zu beachten, dass der null-Koaleszenz-Operator einfach verschachtelt werden kann:

> Beispiel #8 Verschachtelung des null-Koaleszenz-Operators

>     <?php

>     $foo = null;
>     $bar = null;
>     $baz = 1;
>     $qux = 2;

>     echo $foo ?? $bar ?? $baz ?? $qux; // gibt 1 aus

>     ?>

## Operator zur Fehlerkontrolle

PHP unterstützt einen Operator für die Fehlerkontrolle: Das `@`-Symbol. Stellt man das `@` in PHP vor einen Ausdruck werden alle Fehlermeldungen, die von diesem Ausdruck erzeugt werden könnten, unterdrückt.

Wurde eine benutzerdefinierte Fehlerbehandlungsfunktion mit set_error_handler() definiert, wird sie auch dann aufgerufen, wenn die Diagnose unterdrückt wurde.

Warnung

Vor PHP 8.0.0 gab die Funktion error_reporting() bei einem Aufruf innerhalb einer benutzerdefinierten Fehlerbehandlung immer `0` zurück, wenn Fehler mit dem Operator `@` unterdückt wurden. Seit PHP 8.0.0 gibt sie den Wert dieses (bitweisen) Ausdrucks zurück: `E_ERROR | E_CORE_ERROR | E_COMPILE_ERROR | E_USER_ERROR | E_RECOVERABLE_ERROR | E_PARSE`.

Alle Fehlermeldungen, die von diesem Ausdruck erzeugt werden, sind im `"message"`-Element des Arrays, das von error_get_last() zurückgegeben wird, enthalten. Da sich das Ergebnis dieser Funktion bei jedem Fehlers ändert, sollte es möglichst früh geprüft werden.

Beispiel #1 Absichtlicher Dateifehler

    <?php
    $my_file = @file ('nicht_vorhandene_Datei') or
        die ("Datei konnte nicht geöffnet werden: Fehler war:'" . error_get_last()['message'] . "'");
    ?>

Beispiel #2 Unterdrückende Ausdrücke

    <?php
    // Das funktioniert bei jedem Ausdruck, nicht nur bei Funktionen:
    $value = @$cache[$key];
    // gibt keine Meldung aus, falls der Index $key nicht vorhanden ist.
    ?>

> Hinweis: Der @-Operator funktioniert nur bei Ausdrücken. Eine einfache Daumenregel: wenn der Wert von etwas bestimmt werden kann, dann kann der `@`-Operator davor geschrieben werden. Zum Beispiel kann er vor Variablen gesetzt werden, vor Funktionsaufrufen, vor Aufrufen bestimmter Sprachkonstrukte (z. B. include), und so weiter. Nicht verwendet werden kann er vor Funktions- oder Klassendefinitionen oder vor Kontrollstrukturen wie `if` und `foreach` und so weiter.

Warnung

Vor PHP 8.0.0 war es möglich, kritische Fehler, die die Skriptausführung beenden, mit dem `@`-Operator zu deaktivieren. Wenn zum Beispiel `@` dem Aufruf einer Funktion vorangestellt wird, die nicht existiert, weil sie nicht verfügbar ist oder falsch eingegeben wurde, würde das Skript ohne Hinweis auf die Ursache abbrechen.

### Siehe auch

- error_reporting()
- Fehlerbehandlungs- und Protokollierfunktionen

## Operator zur Programmausführung

PHP unterstützt einen Operator für die Ausführung externer Programme: Die sog. Backticks (````). Achtung: Die Backticks sind keine einfachen Anführungszeichen! PHP versucht, den Text zwischen den Backticks als Kommandozeilen-Befehl auszuführen. Die Ausgabe des aufgerufenen Programms wird zurückgegeben (d. h. wird nicht einfach ausgegeben, sondern kann einer Variablen zugewiesen werden). Die Verwendung des Backtick-Operators ist mit shell_exec() identisch.

Beispiel #1 Backtick-Operator

    <?php
    $output = `ls -al`;
    echo "<pre>$output</pre>";
    ?>

> Hinweis:

> Der Backtick-Operator steht nicht zur Verfügung, wenn die Funktion shell_exec() deaktiviert wurde.

> Hinweis:

> Anders als bei einigen anderen Sprachen haben Backticks keine besondere Bedeutung, wenn sie in Zeichenketten, die in doppelten Anführungszeichen eingeschlossen sind, verwendet werden.

### Siehe auch

- Funktionen zur Programmausführung
- popen()
- proc_open()
- Nutzung von PHP auf der Kommandozeile

## Logische Operatoren

Logische Operatoren
Beispiel | Name | Ergebnis
--- | --- | ---
$a and $b | Und | `true` wenn sowohl $a als auch $b `true` ist.
$a or $b | Oder | `true` wenn $a oder $b `true` ist.
$a xor $b | Entweder Oder | `true` wenn entweder $a oder $b `true` ist, aber nicht beide.
! $a | Nicht | `true` wenn $a nicht `true` ist.
$a && $b | Und | `true` wenn sowohl $a als auch $b `true` ist.
$a || $b | Oder | `true` wenn $a oder $b `true` ist.

Der Grund dafür, dass es je zwei unterschiedliche Operatoren für die "Und"- und die "Oder"-Verknüpfung gibt, ist der, dass die beiden Operatoren unterschiedliche Rangfolgen haben. (siehe auch Operator-Rangfolge.)

Beispiel #1 Logische Operatoren erklärt

    <?php

    // --------------------
    // foo() wird nie aufgerufen werden, da die Operatoren Kurzschlussauswertung verwenden

    $a = (false && foo());
    $b = (true  || foo());
    $c = (false and foo());
    $d = (true  or  foo());

    // --------------------
    // "||" hat eine höhere Rangfolge als "or"

    // Das Ergebnis des Ausdrucks (false || true) wird $e zugewiesen
    // Funktioniert wie: ($e = (false || true))
    $e = false || true;

    // Die Konstante "false" wird $f zugewiesen bevor die "or" Operation
    // durchgeführt wird
    // Funktioniert wie: (($e = false) or true)
    $f = false or true;

    var_dump($e, $f);

    // --------------------
    // "&&" hat eine höhere Rangfolge als "and"

    // Das Ergebnis des Ausdrucks (true && false) wird $g zugewiesen
    // Funktioniert wie: ($g = (true && false))
    $g = true && false;

    // Die Konstante "true" wird $h zugewiesen bevor die "and" Operation
    // durchgeführt wird
    // Funktioniert wie: (($h = true) and false)
    $h = true and false;

    var_dump($g, $h);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    bool(true)
    bool(false)
    bool(false)
    bool(true)

## Zeichenketten-Operatoren

Es gibt in PHP zwei Operatoren für Zeichenketten (string). Der erste ist der Verknüpfungsoperator ('.'), dessen Rückgabewert eine zusammengesetzte Zeichenkette aus dem rechten und dem linken Argument ist. Der zweite ist der verknüpfende Zuweisungsoperator ('`.=`'), der das Argument auf der rechten Seite an das Argument der linken Seite anhängt. Siehe Zuweisungs-Operatoren für weitere Informationen.

Beispiel #1 Verketten von Zeichenketten

    <?php
    $a = "Hallo ";
    $b = $a . "Welt!"; // $b enthält jetzt den Text "Hallo Welt!"
    var_dump($b);

    $a = "Hallo ";
    $a .= "Welt!";     // $a enthält jetzt den Text "Hallo Welt!"
    var_dump($a);
    ?>

### Siehe auch

- Strings
- String-Funktionen

## Array-Operatoren

Array-Operatoren
Beispiel | Name | Ergebnis
--- | --- | ---
$a + $b | Vereinigung | Vereinigung von $a und $b.
$a == $b | Gleichwertigkeit | `true` wenn $a und $b dieselben Schlüssel-/Wert-Paare enthalten.
$a === $b | Identität | `true` wenn $a und $b dieselben Schlüssel-/Wert-Paare in der gleichen Reihenfolge und vom selben Typ enthalten.
$a != $b | Ungleichheit | `true` wenn $a nicht gleich$b ist.
$a <> $b | Ungleichheit | `true` wenn $a nicht gleich$b ist.
$a !== $b | nicht identisch | `true` wenn $a nicht identisch zu $b ist.

Der Operator `+` hängt das rechsstehende Array an das linksstehende Array an; kommen Schlüssel in beiden Arrays vor, dann werden die Elemente des linksstehenden Arrays verwendet, und die entsprechenden Elemente des rechtstehenden Arrays werden ignoriert.

Beispiel #1 Operator zum Anhängen von Arrays

    <?php
    $a = array("a" => "Apfel", "b" => "Banane");
    $b = array("a" =>"Birne", "b" => "Erdbeere", "c" => "Kirsche");

    $c = $a + $b; // Vereinigung von $a mit $b;
    echo "Vereinigung von \$a mit \$b: \n";
    var_dump($c);

    $c = $b + $a; // Vereinigung von $b mit $a;
    echo "Vereinigung von \$b mit \$a: \n";
    var_dump($c);

    $a += $b; // Vereinigung von $a += $b ist $a + $b
    echo "Vereinigung von \$a += \$b: \n";
    var_dump($a);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Vereinigung von $a mit $b:
    array(3) {
      ["a"]=>
      string(5) "Apfel"
      ["b"]=>
      string(6) "Banane"
      ["c"]=>
      string(7) "Kirsche"
    }
    Vereinigung von $b mit $a:
    array(3) {
      ["a"]=>
      string(4) "Birne"
      ["b"]=>
      string(8) "Erdbeere"
      ["c"]=>
      string(7) "Kirsche"
    }
    Vereinigung von $a += $b:
    array(3) {
      ["a"]=>
      string(5) "Apfel"
      ["b"]=>
      string(6) "Banane"
      ["c"]=>
      string(6) "Kirsche"
    }

Beim Vergleich werden Arrayelemente als gleich angesehen, wenn diese dieselben Schlüssel und Werte beinhalten.

Beispiel #2 Array-Vergleiche

    <?php
    $a = array("Apfel", "Banane");
    $b = array(1 => "Banane", "0" => "Apfel");

    var_dump($a == $b); // bool(true)
    var_dump($a === $b); // bool(false)
    ?>

### Siehe auch

- Arrays
- Array-Funktionen

## Typ-Operatoren

`instanceof` wird dazu verwendet um festzustellen, ob ein gegebenes Objekt ein Objekt ist, das zu einer bestimmten Klasse gehört.

Beispiel #1 Die Verwendung von `instanceof` mit Klassen

    <?php
    class MyClass
    {
    }

    class NotMyClass
    {
    }
    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof NotMyClass);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)

`instanceof` kann auch verwendet werden, um zu bestimmen, ob ein Variable ein Exemplar einer Klasse ist, die von einer Elternklasse erbt:

Beispiel #2 Verwendung von `instanceof` mit ererbten Klassen

    <?php
    class ParentClass
    {
    }

    class MyClass extends ParentClass
    {
    }

    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof ParentClass);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)

Um zu prüfen, ob ein Objekt nicht eine Instanz einer Klasse ist, kann der logische `nicht`-Operator verwendet werden.

Beispiel #3 Verwendung von `instanceof`, um zu prüfen, ob ein Objekt nicht eine Instanz einer Klasse ist

    <?php
    class MyClass
    {
    }

    $a = new MyClass;
    var_dump(!($a instanceof stdClass));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

Schließlich kann `instanceof` auch dazu verwendet werden, um zu bestimmen, ob eine Variable ein instanziiertes Objekt einer Klasse ist, die ein Interface implementiert:

Beispiel #4 Verwendung von `instanceof` mit Interfaces

    <?php
    interface MyInterface
    {
    }

    class MyClass implements MyInterface
    {
    }

    $a = new MyClass;

    var_dump($a instanceof MyClass);
    var_dump($a instanceof MyInterface);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)

Obwohl `instanceof` üblicherweise mit einem Klassennamensbezeichner verwendet wird, kann es auch mit einem anderen Objekt oder einer Zeichenkettenvariablen verwendet werden:

Beispiel #5 Verwendung von `instanceof` mit anderen Variablen

    <?php
    interface MyInterface
    {
    }

    class MyClass implements MyInterface
    {
    }

    $a = new MyClass;
    $b = new MyClass;
    $c = 'MyClass';
    $d = 'NotMyClass';

    var_dump($a instanceof $b); // $b ist ein Exemplar der Klasse MyClass
    var_dump($a instanceof $c); // $c ist die Zeichenkette 'MyClass'
    var_dump($a instanceof $d); // $d ist die Zeichenkette 'NotMyClass'
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)

instanceof löst keinen Fehler aus, wenn die getestete Variable kein Objekt ist; es gibt dann einfach `false` zurück. Konstanten waren allerdings vor PHP 7.3.0 nicht erlaubt.

Beispiel #6 Verwendung von `instanceof` um andere Variablen zu prüfen

    <?php
    $a = 1;
    $b = NULL;
    $c = fopen('/tmp/', 'r');
    var_dump($a instanceof stdClass); // $a ist eine Ganzzahl
    var_dump($b instanceof stdClass); // $b ist NULL
    var_dump($c instanceof stdClass); // $c ist ein Ressource
    var_dump(FALSE instanceof stdClass);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(false)
    bool(false)
    PHP Fatal error:  instanceof expects an object instance, constant given

Von PHP 7.3.0 an sind Konstanten auf der linken Seite des `instanceof`-Operators erlaubt.

Beispiel #7 Verwendung von `instanceof` um Konstanten zu prüfen

    <?php
    var_dump(FALSE instanceof stdClass);
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 7.3 folgende Ausgabe:

    bool(false)

Seit PHP 8.0.0 kann `instanceof` mit beliebigen Ausdrücken verwendet werden. Der Ausdruck muss in Klammern eingeschlossen sein und einen String erzeugen. -

Beispiel #8 Verwendung von `instanceof` mit einem beliebigen Ausdruck

    <?php

    class ClassA extends \stdClass {}
    class ClassB extends \stdClass {}
    class ClassC extends ClassB {}
    class ClassD extends ClassA {}

    function getSomeClass(): string
    {
        return ClassA::class;
    }

    var_dump(new ClassA instanceof ('std' . 'Class'));
    var_dump(new ClassB instanceof ('Class' . 'B'));
    var_dump(new ClassC instanceof ('Class' . 'A'));
    var_dump(new ClassD instanceof (getSomeClass()));
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)
    bool(true)

Der `instanceof`-Operator hat mit der Funktion is_a() eine funktionale Variante.

### Siehe auch

- get_class()
- is_a()

## Functional Operators

PHP 8.5 and later supports one operator that works directly on callables. The `|>` operator, or “pipe,” accepts a single-parameter callable on the right and passes the left-side value to it, evaluating to the callable's result. The callable on the right may be any valid PHP callable: a Closure, a first-class callable, an object that implements __invoke(), etc.

That means the following two lines are logically equivalent.

Beispiel #1 Using `|>`

    <?php
    $result = "Hello World" |> strlen(...);
    echo $result, PHP_EOL;

    $result = strlen("Hello World");
    echo $result, PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    11
    11

For a single call that is not especially useful. It becomes useful when multiple calls are chained together. That is, the following two code fragments are logically equivalent:

Beispiel #2 Chaining |> calls

    <?php
    $result = "PHP Rocks"
        |> htmlentities(...)
        |> str_split(...)
        |> (fn($x) => array_map(strtoupper(...), $x))
        |> (fn($x) => array_filter($x, fn($v) => $v != 'O'))
    ;
    print_r($result);

    $temp = "PHP Rocks";
    $temp = htmlentities($temp);
    $temp = str_split($temp);
    $temp = array_map(strtoupper(...), $temp);
    $temp = array_filter($temp, fn($v) => $v != 'O');
    $result = $temp;
    print_r($result);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )
    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )

The left-hand side of the pipe may be any value or expression. The right-hand side may be any valid PHP callable that takes a single parameter, or any expression that evaluates to such a callable. Functions with more than one required parameter are not allowed and will fail as if the function were called normally with insufficient arguments. Functions that take a variable by reference are not allowed. If the right-hand side does not evaluate to a valid callable it will throw an Error.

> Hinweis:

> Be aware that, to avoid syntax ambiguity, arrow functions MUST be wrapped in parentheses when used with a pipe operator, as in the examples above. Failing to do so will result in a fatal error.

### Siehe auch

- Closure

# Kontrollstrukturen

## Inhaltsverzeichnis

- Einführung
- if
- else
- elseif/else if
- Alternative Syntax für Kontrollstrukturen
- while
- do-while
- for
- foreach
- break
- continue
- switch
- match
- declare
- return
- require
- include
- require_once
- include_once
- goto

## Einführung

Ein PHP-Skript besteht aus einer Abfolge von Anweisungen. Eine Anweisung kann eine Zuweisung, ein Funktionsaufruf oder ein bedingte Anweisung sein oder sogar eine Anweisung die nichts tut (eine leere Anweisung). Anweisungen enden in der Regel mit einem Semikolon. Anweisungen können des Weiteren in Anweisungsgruppen zusammengefasst werden indem sie in geschweifte Klammern eingeschlossen werden. Eine Anweisungsgruppe ist ebenfalls wieder eine Anweisung. Die verschiedenen Anweisungstypen werden in diesem Kapitel beschrieben.

### Siehe auch

Die Folgenden werden ebenfalls als Sprachkonstrukte angesehen, auch wenn sie im Handbuch als Funktionen aufgeführt werden.

- list()
- array()
- echo
- eval()
- print

## if

(PHP 4, PHP 5, PHP 7, PHP 8)

Das `if`-Konstrukt ist eines der wichtigsten Features vieler Programmiersprachen, so auch in PHP, denn es ermöglicht die bedingte Ausführung von Kodefragmenten. PHP bietet eine `if`-Anweisung, die der in C ähnelt:

    if (ausdruck)
      anweisung

ausdruck wird wie im Abschnitt über Ausdrücke beschrieben zu einem booleschen Wahrheitswert ausgewertet. Evaluiert ausdruck zu `true` so wird anweisung von PHP ausgeführt, anderenfalls wird es ignoriert. Weitere Informationen dazu welche Werte als `true` oder `false` ausgewertet werden, dem Abschnitt 'Umwandlung zu boolean' zu entnehmen.

Das folgende Beispiel würde a ist größer als b ausgeben, wenn $a größer als $b ist:

    <?php
    if ($a > $b)
      echo "a ist größer als b";
    ?>

Oft werden Sie mehr als eine Anweisung bedingt ausführen wollen. Dazu ist es natürlich nicht notwendig jede Anweisung mit einer eigenen `if`-Klausel zu versehen. Statt dessen können mehrere Anweisung zu einer Anweisungsgruppe zusammengefasst werden. So würde z.B. der folgende Programmcode a ist größer als b ausgeben, falls $a größer als $b ist, und den Wert von $a an $b zuweisen:

    <?php
    if ($a > $b) {
      echo "a ist größer als b";
      $b = $a;
    }
    ?>

`If`-Anweisungen können beliebig oft ineinander verschachtelt werden, was vollständige Flexibilität für die bedingte Ausführung der verschiedenen Teile des Programs bietet.

## else

(PHP 4, PHP 5, PHP 7, PHP 8)

Oft will man eine Anweisung ausführen, wenn eine bestimmte Bedingung erfüllt ist, und eine andere Anweisung, wenn dies nicht der Fall ist. Dies ist der Einsatzzweck von `else`. `else` erweitert eine `if`-Anweisung um eine weitere Anweisung, die dann ausgeführt werden soll, wenn der Ausdruck in der `if`-Anweisung zu `false` ausgewertet wird. Der folgende Programmcode würde z. B. a ist größer als b ausgeben, wenn $a größer als b ist, ansonsten a ist NICHT größer als b

    <?php
    if ($a > $b) {
      echo "a ist größer als b";
    } else {
      echo "a ist NICHT größer als b";
    }
    ?>

Die `else`-Anweisung wird nur dann ausgeführt, wenn der `if`-Ausdruck und alle etwaigen `elseif` als `false` ausgewertet wurden (siehe auch elseif).

> Hinweis: Baumelndes (dangling) else

> Bei verschachtelten `if`-`else`-Anweisungen wird ein `else` immer mit dem nächsten `if` verbunden.

>     <?php
>     $a = false;
>     $b = true;
>     if ($a)
>         if ($b)
>             echo "b";
>     else
>         echo "c";
>     ?>

> Trotz der Einrückung (die bei PHP keine Rolle spielt), ist das `else` mit dem `if ($b)` verbunden, weshalb das Beispiel keine Ausgabe erzeugt. Obwohl diese Vorgehensweise zulässig ist, sollte sie durch die Verwendung geschweifter Klammern vermieden werden, um mögliche Mehrdeutigkeiten aufzulösen.

## elseif/else if

(PHP 4, PHP 5, PHP 7, PHP 8)

`elseif`, wie der Name schon sagt, ist eine Kombination aus `if` und `else`. Wie `else` erweitert es eine `if`-Kontrollstruktur, um alternative Befehle auszuführen, wenn die ursprüngliche `if`-Bedingung nicht zutrifft. Im Gegensatz zu `else` werden die Alternativ-Befehle aber nur ausgeführt, wenn die `elseif`-Bedingung zutrifft. Der folgende Beispielcode gibt a ist größer als b, a ist gleich groß wie b oder a ist kleiner als b aus:

    <?php
    if ($a > $b) {
        echo "a ist größer als b";
    } elseif ($a == $b) {
        echo "a ist gleich groß wie b";
    } else {
        echo "a ist kleiner als b";
    }
    ?>

Innerhalb einer `if`-Kontrollstruktur können mehrere `elseif`-Strukturen benutzt werden. Der erste `elseif`-Ausdruck (falls vorhanden), der zu `true` ausgewertet wird, wird ausgeführt. In PHP kann ebenfalls als Schlüsselwort `else if` (in zwei Wörtern) benutzt werden, was sich komplett identisch wie `elseif` (in einem Wort) verhält. Die syntaktische Bedeutung ist geringfügig anders (dasselbe Verhalten wie in C), aber das Ergebnis ist, dass beide sich exakt genauso verhalten.

Der `elseif`-Teil wird nur ausgeführt, wenn die vorhergehende `if`-Bedingung und alle vorhergehenden `elseif`-Bedingungen nicht zutrafen (`false`) und die aktuelle `elseif`-Bedingung zutrifft (`true`).

> Hinweis: Achtung: `elseif` und `else if` verhalten sich nur gleich, wenn geschwungene Klammern verwendet werden, wie im obigen Beispiel. Wenn ein Doppelpunkt verwendet wird, um `if`/`elseif`-Bedingungen zu definieren, muss `elseif` in einem einzigen Wort verwendet werden. Wenn `else if` in zwei Wörter aufgeteilt wird, gibt PHP einen Parse-Fehler aus.

    <?php

    /* Falsch: */
    if ($a > $b):
        echo $a." ist größer als ".$b;
    else if ($a == $b): // Funktioniert nicht.
        echo "Die vorige Zeile wird einen Parse Error verursachen.";
    endif;

    <?php
    /* Richtig: */
    if ($a > $b):
        echo $a." ist größer als ".$b;
    elseif ($a == $b): // elseif in einem Wort!
        echo $a." ist gleich groß wie ".$b;
    else:
        echo $a." ist weder größer als noch gleich wie ".$b;
    endif;

    ?>

## Alternative Syntax für Kontrollstrukturen

(PHP 4, PHP 5, PHP 7, PHP 8)

PHP bietet eine alternative Syntax für einige seiner Kontrollstrukturen an, namentlich für `if`, `while`, `for`, `foreach` und `switch`. In jedem Fall ist die Grundform der alternativen Syntax ein Wechsel der öffnenden Klammer gegen einen Doppelpunkt (:) und der schließenden Klammer in `endif;`, `endwhile`, `endfor;`, `endforeach;` respektive `endswitch`.

    <?php if ($a == 5): ?>
    A ist gleich 5
    <?php endif; ?>

Im obigen Beispiel ist der HTML-Block "A ist gleich 5" in ein `if`-Statement verschachtelt, das in alternativer Syntax notiert ist. Der HTML-Block würde nur angezeigt werden, wenn $a gleich 5 ist.

Die alternative Syntax lässt sich ebenfalls auf `else` und `elseif` anwenden. Im Folgenden wird eine `if`-Struktur mit `elseif`- und `else`-Teilen im alternativen Format gezeigt:

    <?php
    if ($a == 5):
        echo "a gleich 5";
        echo "...";
    elseif ($a == 6):
        echo "a gleich 6";
        echo "!!!";
    else:
        echo "a ist weder 5 noch 6";
    endif;
    ?>

> Hinweis:

> Das Vermischen unterschiedlicher Schreibweisen im selben Kontrollblock ist nicht unterstützt.

Warnung

Jegliche Ausgabe (einschließlich Whitespace) zwischen einer `switch` Anweisung und dem ersten `case` ist ein Syntax Fehler. Zum Beispiel ist folgendes ungültig:

    <?php switch ($foo): ?>
        <?php case 1: ?>
        // ...
    <?php endswitch; ?>

Hingegen ist das folgende gültig, da das abschließende Zeilenende nach der `switch` Anweisung als Teil des schließenden `?>` angesehen wird, und daher zwischen `switch` und `case` nichts ausgegeben wird:

    <?php switch ($foo): ?>
    <?php case 1: ?>
        ...
    <?php endswitch; ?>

Siehe auch while, for und if für weitere Beispiele.

## while

(PHP 4, PHP 5, PHP 7, PHP 8)

`while`-Schleifen sind der einfachste Typ von Schleifen in PHP. Sie verhalten sich wie ihre Pendants in C. Die Grundform einer `while`-Schleife ist:

    while (bedingung)
        anweisung

Die Bedeutung einer `while`-Schleife ist simpel. Die Schleife weist PHP an, die untergeordnete(n) Anweisung(en) wiederholt auszuführen, solange die `while`-Bedingung zutrifft. Die Bedingung wird jedes Mal am Anfang der Schleife überprüft, Das bedeutet, dass die Ausführung der untergeordneten Anweisungen nicht stoppt, auch wenn sich der Wahrheitsgehalt der Bedingung zwischendurch ändert (jedes Mal, wenn PHP die Anweisungen ausführt, handelt es sich um eine Runde). Wenn die `while`-Bedingung von Anfang an nicht zutrifft, werden die untergeordneten Anweisung nicht ein einziges Mal ausgeführt.

Wie bei `if`-Abfragen können mehrere Statements innerhalb der selben Schleife mit geschleiften Klammern oder mithilfe der alternativen Syntax gruppiert werden:

    while (bedingung):
        anweisung
        ...
    endwhile;

Die folgenden Beispiele sind identisch und geben die Zahlen von 1 bis 10 aus:

    <?php
    /* Beispiel 1 */

    $i = 1;
    while ($i <= 10) {
        echo $i++;  /* der ausgegebene Wert ist $i bevor
                       er erhöht wird (post-increment) */
    }

    /* Beispiel 2 */

    $i = 1;
    while ($i <= 10):
        echo $i;
        $i++;
    endwhile;
    ?>

## do-while

(PHP 4, PHP 5, PHP 7, PHP 8)

`do-while`-Schleifen sind sehr ähnlich zu `while`-Schleifen, außer dass der Wahrheitsausdruck erst am Ende eines jeden Durchlaufs statt zu dessen Beginn geprüft wird. Der Hauptunterschied zu einer normalen `while`-Schleife ist, dass die `do-while`-Schleife garantiert mindestens einmal durchlaufen wird (Der Wahrheitsausdruck wird ja nur am Ende jeden Durchlaufs geprüft), wohingegen es nicht zwingend ist, dass eine reguläre `while`-Schleife immer ausgeführt wird (hier wird der Wahrheitsausdruck bereits zu Beginn eines jeden Durchlaufs überprüft. Evaluiert er dabei zu `false`, wird die Verarbeitung der Schleife sofort abgebrochen).

Es gibt nur eine Syntax für `do-while`-Schleifen:

    <?php
    $i = 0;
    do {
        echo $i;
    } while ($i > 0);
    ?>

Die obige Schleife wird exakt einmal durchlaufen, da nach dem ersten Durchlauf, wenn der Wahrheitsausdruck geprüft wird, dieser `false` ergibt ($i ist nicht größer als 0), so dass die Schleifenausführung beendet wird.

Fortgeschrittenen C-Programmierern ist möglicherweise eine etwas andere Verwendung von `do-while`-Schleifen bekannt, die es erlaubt, die Ausführung in der Mitte des Codeblocks zu unterbrechen. Dies wird durch ein Kapseln in `do-while`(0) und die Verwendung des `break`-Statements erreicht. Das folgende Codefragment demonstriert dieses Verhalten:

    <?php
    do {
        if ($i < 5) {
            echo "i ist nicht groß genug";
            break;
        }
        $i *= $factor;
        if ($i < $minimum_limit) {
            break;
        }
        echo "i ist ok";

        /* i verarbeiten */

    } while (0);
    ?>

Es ist möglich, statt dieses Hacks den `goto`-Operator zu verwenden.

## for

(PHP 4, PHP 5, PHP 7, PHP 8)

`for`-Schleifen sind die komplexesten Schleifen in PHP. Sie verhalten sich wie ihre Pendants in C. Die Syntax einer `for`-Schleife ist:

    for (expr1; expr2; expr3)
        statement

Der erste Ausdruck (expr1) wird vor Ausführung der Schleife ausgeführt.

Am Anfang jedes Schleifendurchlaufs wird die Anweisung expr2 ausgeführt. Wenn diese wahr ist (`true`), wird die Schleife fortgesetzt und die untergeordneten Anweisungen werden ausgeführt. Andernfalls (`false`) endet die Ausführung der Schleife.

Am Ende jedes Schleifendurchlaufs wird die Anweisung expr3 ausgeführt.

Jede der Anweisungen kann leer sein oder mehrere durch Kommata getrennte Anweisungen enthalten. In letzterem Fall werden bei expr2 zwar alle Anweisungen ausgeführt aber das Ergebnis wird nur von der letzten Anweisung verwendet. Wenn expr2 leer ist, läuft die Schleife unendlich lange (PHP nimmt dies als `true`, ebenso wie C). Dies ist nicht so sinnlos, wie es scheint, denn oft will man die Schleife manuell mit `break` beenden.

Die folgenden Beispiele geben alle die Zahlen 1 bis 10 aus:

    <?php
    /* Beispiel 1 */

    for ($i = 1; $i <= 10; $i++) {
        echo $i;
    }

    /* Beispiel 2 */

    for ($i = 1; ; $i++) {
        if ($i > 10) {
            break;
        }
        echo $i;
    }

    /* Beispiel 3 */

    $i = 1;
    for (; ; ) {
        if ($i > 10) {
            break;
        }
        echo $i;
        $i++;
    }

    /* Beispiel 4 */

    for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);
    ?>

Sicher ist das erste das hübscheste (vielleicht auch das vierte), aber in manchen Fällen sind leere Anweisungen in `for`-Schleifen durchaus praktisch.

PHP unterstützt bei `for`-Schleifen ebenfalls die alternative "Doppelpunkt-Syntax":

    for (expr1; expr2; expr3):
        statement
        ...
    endfor;

Es ist üblich, dass Arrays wie in dem folgenden Beispiel durchlaufen werden.

    <?php
    /*
     * Dies ist ein Array mit Daten, die wir in der
     * Schleife verändern wollen.
     */
    $personen = array(
        array('name' => 'Hans', 'salt' => 856412),
        array('name' => 'Martin', 'salt' => 215863)
    );

    for($i = 0; $i < count($personen); ++$i) {
        $personen[$i]['salt'] = mt_rand(000000, 999999);
    }
    ?>

Der obige Code kann langsam sein, weil die Größe des Arrays bei jedem Schleifendurchlauf abgerufen wird. Da sich die Größe nie ändern, kann die Schleife optimiert werden, indem man die Größe in einer Variablen zwischenspeichert, anstatt sie immer wieder mit count() abzurufen:

    <?php
    $personen = array(
        array('name' => 'Hans', 'salt' => 856412),
        array('name' => 'Martin', 'salt' => 215863)
    );

    for($i = 0, $groesse = count($personen); $i < $groesse; ++$i) {
        $personen[$i]['salt'] = mt_rand(000000, 999999);
    }
    ?>

## foreach

(PHP 4, PHP 5, PHP 7, PHP 8)

Das `foreach`-Konstrukt bietet eine einfache Möglichkeit über arrays und Traversable-Objekte zu iterieren. `foreach` erzeugt einen Fehler, wenn es mit einer Variablen verwendet wird, die einen anderen Datentyp enthält oder mit einer Variablen, die nicht initialisiert wurde.

`foreach` kann optional den `Schlüssel` jedes Elements erhalten:

    foreach (iterable_expression as $value) {
        statement_list
    }

    foreach (iterable_expression as $key => $value) {
        statement_list
    }

Die erste Form durchläuft das in `iterable_expression` angegebene Iterable. Bei jedem Durchlauf wird der Wert des aktuellen Elementes der Variable `$value` zugewiesen.

Die zweite Form schreibt zusätzlich den Schlüssel des aktuellen Elementes in jedem Durchlauf in die Variable `$key`.

Es ist zu beachten, dass `foreach` den internen Array-Zeiger nicht verändert, der von Funktionen wie current() und key() verwendet wird.

Es ist möglich, die Objektiteration anzupassen.

Beispiel #1 Gängige Verwendungen von `foreach`

    <?php

    /* Beispiel: Nur Werte */
    $array = [1, 2, 3, 17];

    foreach ($array as $value) {
        echo "Aktueller Wert von \$array: $value.\n";
    }

    /* Beispiel: Schlüssel und Wert */
    $array = [
        "eins" => 1,
        "zwei" => 2,
        "drei" => 3,
        "siebzehn" => 17
    ];

    foreach ($array as $key => $value) {
        echo "Schlüssel: $key => Wert: $value\n";
    }

    /* Beispiel: Mehrdimensionale Schlüssel-Wert-Arrays */
    $grid = [];
    $grid[0][0] = "a";
    $grid[0][1] = "b";
    $grid[1][0] = "y";
    $grid[1][1] = "z";

    foreach ($grid as $y => $row) {
        foreach ($row as $x => $value) {
            echo "Wert an Position x=$x und y=$y: $value\n";
        }
    }

    /* Beispiel: Dynamische Arrays */
    foreach (range(1, 5) as $value) {
        echo "$value\n";
    }
    ?>

> Hinweis:

> `foreach` unterstützt die Fehlerunterdrückung mittels `@` nicht

### Entpacken verschachtelter Arrays

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Es ist möglich, über Arrays von Arrays zu iterieren und dabei die verschachtelten Arrays in Schleifenvariablen zu entpacken, indem entweder die Array-Destrukturierung mittels `[]` oder das Sprachkonstrukt list() als Wert verwendet wird.

> Hinweis: Es ist zu beachten, dass die Array-Destrukturierung mittels `[]` erst seit PHP 7.1.0 möglich ist.

In den beiden folgenden Beispielen wird `$a` auf das erste Element des verschachtelten Arrays gesetzt und `$b` enthält das zweite Element:

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b]) {
        echo "A: $a; B: $b\n";
    }

    foreach ($array as list($a, $b)) {
        echo "A: $a; B: $b\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    A: 1; B: 2
    A: 3; B: 4

Wenn weniger Variablen angegeben werden, als Elemente im Array vorhanden sind, werden die restlichen Elemente ignoriert. Ebenso können Elemente durch die Verwendung eines Kommas übersprungen werden:

    <?php
    $array = [
        [1, 2, 5],
        [3, 4, 6],
    ];

    foreach ($array as [$a, $b]) {
        // Beachten Sie, dass es hier kein $c gibt.
        echo "$a $b\n";
    }

    foreach ($array as [, , $c]) {
        // $a und $b überspringen
        echo "$c\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1 2
    3 4
    5
    6

Gibt es nicht ausreichend Elemente im Array, um list() zu füllen, wird eine Notice erzeugt.

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b, $c]) {
        echo "A: $a; B: $b; C: $c\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Notice: Undefined offset: 2 in example.php on line 7
    A: 1; B: 2; C:

    Notice: Undefined offset: 2 in example.php on line 7
    A: 3; B: 4; C:

### foreach und Referenzen

Array-Elemente können innerhalb einer Schleife direkt geändert werden, indem `$value` ein `&` vorangestellt wird. In diesem Fall wird der Wert per Referenz zugewiesen.

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr ist nun [2, 4, 6, 8]
    unset($value); // die Referenz mit dem letzten Element aufheben
    ?>

Warnung

Die Referenz auf ein `$value` des letzten Array-Elements bleibt auch nach der `foreach`-Schleife erhalten. Es wird empfohlen, diese mittels unset() zu löschen. Andernfalls tritt folgendes Verhalten auf:

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr ist nun [2, 4, 6, 8]

    // ohne unset($value) ist $value immer noch eine Referenz
    // auf das letzte Element: $arr[3]

    foreach ($arr as $key => $value) {
        // $arr[3] wird mit jedem Wert aus $arr aktualisiert...
        echo "{$key} => {$value} ";
        print_r($arr);
    }
    // ...bis schließlich der vorletzte Wert auf den letzten Wert kopiert wird
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
    1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
    2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
    3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )

Beispiel #2 Werte eines konstanten Arrays per Referenz durchlaufen

    <?php
    foreach ([1, 2, 3, 4] as &$value) {
        $value = $value * 2;
    }
    ?>

### Siehe auch

- array
- Traversable
- iterable
- list()

## break

(PHP 4, PHP 5, PHP 7, PHP 8)

`break` beendet die Ausführung der aktuellen `for`-, `foreach`-, `while`-, `do-while`- oder `switch`-Struktur.

`break` akzeptiert ein optionales numerisches Argument, das angibt, aus wie vielen der es umschließenden verschachtelten Strukturen ausgebrochen werden soll. Der Standardwert ist `1`; nur aus der unmittelbar umschließenden Verschachtelung wird ausgebrochen.

    <?php
    $arr = array('eins', 'zwei', 'drei', 'vier', 'stop', 'fünf');
    foreach ($arr as $val) {
        if ($val == 'stop') {
            break;    /* Sie könnten hier auch 'break 1;' schreiben. */
        }
        echo "$val<br />\n";
    }

    /* Nutzung des optionalen Arguments. */

    $i = 0;
    while (++$i) {
        switch ($i) {
            case 5:
                echo "Bei 5<br />\n";
                break 1;  /* Verlässt nur das switch. */
            case 10:
                echo "Bei 10; brich ab<br />\n";
                break 2;  /* Verlässt das switch und das while. */
            default:
                break;
        }
    }
    ?>

## continue

(PHP 4, PHP 5, PHP 7, PHP 8)

`continue` wird innerhalb von Schleifen verwendet, um den Rest des aktuellen Schleifendurchlaufs abzubrechen und mit der Auswertung der nächsten Bedingung fortzufahren, um dann den nächsten Durchlauf zu beginnen.

> Hinweis: In PHP wird das switch-Statement im Sinne von `continue` als Schleifenstruktur betrachtet. `continue` verhält sich wie `break` (wenn keine Argumente übergeben werden), erzeugt aber eine Warnung, da es sich vermutlich um einen Fehler handelt. Falls sich ein `switch` innerhalb einer Schleife befindet, wird `continue 2` mit der nächsten Iteration der äußeren Schleife fortsetzen.

`continue` akzeptiert ein optionales numerisches Argument, das angibt, wie viele Ebenen umschließender Schleifen bis zu ihrem Ende übersprungen werden sollen. Die Voreinstellung ist `1`, so dass zum Ende der aktuellen Schleife gesprungen wird.

    <?php
    $arr = ['zero', 'one', 'two', 'three', 'four', 'five', 'six'];
    foreach ($arr as $key => $value) {
        if (0 === ($key % 2)) { // ignoriere Elemente mit geradem Schlüssel
            continue;
        }
        echo $value . "\n";
    }
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    one
    three
    five

    <?php
    $i = 0;
    while ($i++ < 5) {
        echo "Äußere\n";
        while (1) {
            echo "Mittlere\n";
            while (1) {
                echo "Innere\n";
                continue 3;
            }
            echo "Das hier wird nie ausgegeben.\n";
        }
        echo "Das hier ebenfalls nicht.\n";
    }
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Outer
    Middle
    Inner
    Outer
    Middle
    Inner
    Outer
    Middle
    Inner
    Outer
    Middle
    Inner
    Outer
    Middle
    Inner

Das Weglassen des Semikolons nach `continue` kann zu unerwarteten Ergebnissen führen. Hier ist ein Beispiel, das zeigt, was Sie nicht tun sollten.

    <?php
    for ($i = 0; $i < 5; ++$i) {
        if ($i == 2)
            continue
        print "$i\n";
    }
    ?>

Man könnte meinen, die Ausgabe wäre:

    0
    1
    3
    4

Changelog für `continue`
Version | Beschreibung
--- | ---
7.3.0 | `continue` innerhalb eines `switch`, das versucht wie eine `break`-Anweisung für das `switch` zu wirken, erzeugt ein `E_WARNING`.

## switch

(PHP 4, PHP 5, PHP 7, PHP 8)

Die `switch`-Anweisung entspricht in etwa einer Folge von `if`-Anweisungen die jeweils den gleichen Ausdruck prüfen. Es kommt oft vor, dass man dieselbe Variable (oder denselben Ausdruck) gegen viele verschiedene mögliche Werte prüfen und abhängig davon unterschiedlichen Code ausführen möchte. Genau hierfür wurde die `switch`-Anweisung eingeführt.

> Hinweis: Beachten Sie, dass im Unterschied zu einigen anderen Sprachen die continue-Anweisung auch auf `switch` anwendbar ist und sich ähnlich wie `break` verhält. Wenn Sie ein `switch` innerhalb einer Schleife verwenden und mit dem nächsten Schleifendurchlauf beginnen wollen so müssen Sie in diesem Fall `continue 2` angeben.

> Hinweis:

> Beachten Sie auch, dass switch/case typschwache Vergleiche durchführt.

Im folgenden Beispiel sind die beiden Codeblöcke gleichwertig. Der eine verwendet eine Reihe von `if`- und `elseif`-Anweisungen und der andere eine `switch`-Anweisung. Die Ausgabe ist in beiden Fällen dieselbe.

Beispiel #1 `switch`-Anweisung

    <?php
    // This switch statement:

    switch ($i) {
        case 0:
            echo "i ist gleich 0";
            break;
        case 1:
            echo "i ist gleich 1";
            break;
        case 2:
            echo "i ist gleich 2";
            break;
    }

    // Is equivalent to:

    if ($i == 0) {
        echo "i ist gleich 0";
    } elseif ($i == 1) {
        echo "i ist gleich 1";
    } elseif ($i == 2) {
        echo "i ist gleich 2";
    }
    ?>

Um Fehler zu vermeiden ist es wichtig zu verstehen wie eine `switch`-Anweisung ausgeführt wird. Eine `switch`-Anweisung wird zeilenweise (genauer: Anweisung für Anweisung) ausgewertet. Zunächst einmal wird überhaupt kein Code ausgeführt. Erst wenn eine `case`-Anweisung gefunden wird, deren Ausdruck zu einem Wert evaluiert, der dem an `switch` übergebenen Ausdruck entspricht, beginnt PHP tatsächlich die folgenden Anweisungen auszuführen. Die Ausführung wird fortgesetzt bis das Ende der `switch`-Anweisung erreicht ist oder bis PHP bei der Ausführung auf eine `break`-Anweisung stößt. Wenn Sie am Ende der Anweisungsliste eines case kein `break` setzen, so wird die Ausführung mit dem nächsten case fortgesetzt, z. B.:

    <?php
    switch ($i) {
        case 0:
            echo "i ist gleich 0";
        case 1:
            echo "i ist gleich 1";
        case 2:
            echo "i ist gleich 2";
    }
    ?>

Wenn in diesem Beispiel $i gleich 0 ist, führt PHP alle echo-Anweisungen aus! Ist $i gleich 1, führt PHP die letzten beiden echo-Anweisungen aus. Sie erreichen das erwartete Verhalten nur, wenn $i gleich 2 ist. Daher ist es wichtig `break`-Anweisungen nicht zu vergessen (auch wenn Sie gelegentlich absichtlich darauf verzichten werden, diese unter bestimmten Bedingungen anzugeben).

In einer `switch`-Anweisung wird die Bedingung nur einmal ausgewertet und das Ergebnis mit jeder `case`-Anweisung verglichen. In einer `elseif`-Anweisung wird die Bedingung erneut ausgewertet. Wenn Ihre Bedingung komplizierter ist als ein einfacher Vergleich, und/oder sich in einer dichten Schleife befindet, kann ein `switch` schneller sein.

Die Anweisungsliste eines case kann ebenso leer sein, was einfach die Kontrolle an die Anweisungsliste des nächsten case übergibt.

    <?php
    switch ($i) {
        case 0:
        case 1:
        case 2:
            echo "i ist kleiner als 3, aber nicht negativ";
            break;
        case 3:
            echo "i ist 3";
    }
    ?>

Ein Sonderfall ist die `default`-Klausel. Diese fängt alles ab, was nicht durch eine der anderen case-Klauseln behandelt wurde. Zum Beispiel:

    <?php
    switch ($i) {
        case 0:
            echo "i ist gleich 0";
            break;
        case 1:
            echo "i ist gleich 1";
            break;
        case 2:
            echo "i ist gleich 2";
            break;
        default:
           echo "i ist nicht gleich 0, 1 oder 2";
    }
    ?>

> Hinweis: Mehrere default case-Anweisungen erzeugen einen `E_COMPILE_ERROR`-Fehler.

> Hinweis: Technisch gesehen kann der `default`-Case an einer beliebigen Stelle stehen. Er wird nur verwendet, wenn kein anderer Fall passt. Nach gängiger Praxis ist es jedoch am besten, ihn als letzten Punkt ans Ende zu setzen.

Wenn kein `case`-Zweig passt und es keinen `default`-Zweig gibt, dann wird kein Code ausgeführt, genauso wie wenn keine `if`-Anweisung `true` wäre.

Ein case-Wert kann als Ausdruck angegeben werden. Dieser Ausdruck wird jedoch für sich allein ausgewertet und dann nur einfach mit dem switch-Wert verglichen. Das bedeutet, dass er nicht für komplexe Auswertungen des switch-Wertes verwendet werden kann. Zum Beispiel:

    <?php
    $target = 1;
    $start = 3;

    switch ($target) {
        case $start - 1:
            print "A";
            break;
        case $start - 2:
            print "B";
            break;
        case $start - 3:
            print "C";
            break;
        case $start - 4:
            print "D";
            break;
    }

    // Gibt "B" aus
    ?>

Für komplexere Vergleiche kann der Wert `true` als Switch-Wert verwendet werden. Statt `switch` können alternativ auch `if`-`else`-Blöcke verwendet werden.

    <?php
    $offset = 1;
    $start = 3;

    switch (true) {
        case $start - $offset === 1:
            print "A";
            break;
        case $start - $offset === 2:
            print "B";
            break;
        case $start - $offset === 3:
            print "C";
            break;
        case $start - $offset === 4:
            print "D";
            break;
    }

    // Gibt "B" aus
    ?>

Die alternative Syntax für Kontrollstrukturen wird von switch-Anweisungen unterstützt. Weitere Information entnehmen Sie dem Abschnitt Alternative Syntax für Kontrollstrukturen.

    <?php
    switch ($i):
        case 0:
            echo "i ist gleich 0";
            break;
        case 1:
            echo "i ist gleich 1";
            break;
        case 2:
            echo "i ist gleich 2";
            break;
        default:
            echo "i ist nicht gleich 0, 1 oder 2";
    endswitch;
    ?>

Es ist möglich, ein Semikolon anstelle eines Doppelpunkts nach einem case zu verwenden, wie:

    <?php
    switch($beer)
    {
        case 'Bitburger';
        case 'Erdinger';
        case 'Jever';
            echo 'Gute Wahl';
            break;
        default;
            echo 'Bitte treffen Sie eine andere Wahl...';
            break;
    }
    ?>

### Siehe auch

- match

## match

(PHP 8)

Der `match`-Ausdruck verzweigt die Auswertung auf der Grundlage einer Identitätsprüfung eines Wertes. Ähnlich wie eine `switch`-Anweisung, hat ein `match`-Ausdruck ein Subjekt, welcher mit mehreren Fällen verglichen wird. Im Gegensatz zu switch ist der Vergleich typsicher (`===`) und nicht typschwache (`==`). Match-Ausdrücke sind ab PHP 8.0.0 verfügbar.

Beispiel #1 Struktur eines `match`-Ausdrucks

    <?php
    $return_value = match (subjekt) {
        einfacher_bedingter_ausdruck => rückgabe_ausdruck,
        bedingter_ausdruck1, bedingter_ausdruck2 => rückgabe_ausdruck,
    };
    ?>

Beispiel #2 Grundlegende Benutzung von `match`

    <?php
    $lebensmittel = 'kuchen';

    $return_value = match ($lebensmittel) {
        'apfel' => 'Das Lebensmittel ist ein Apfel',
        'schokolade' => 'Das Lebensmittel ist Schokolade',
        'kuchen' => 'Das Lebensmittel ist ein Kuchen',
    };

    var_dump($return_value);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(31) "Das Lebensmittel ist ein Kuchen"

Beispiel #3 Beispiel für die Benutzung von `match` mit Vergleichsoperatoren

    <?php
    $age = 18;

    $output = match (true) {
        $age < 2 => "Baby",
        $age < 13 => "Kind",
        $age <= 19 => "Teenager",
        $age >= 40 => "Erwachsener",
        $age > 19 => "Junger Erwachsener",
    };

    var_dump($output);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(8) "Teenager"

> Hinweis: Das Ergebnis eines `match`-Ausdrucks muss nicht verwendet werden.

> Hinweis: Wenn ein `match`-Ausdruck als eigenständiger Ausdruck verwendet wird, muss er mit einem Semikolon `;` abgeschlossen werden.

Der Ausdruck `match` ist ähnlich wie eine `switch`-Anweisung, hat aber einige wesentliche Unterschiede:

- Ein `match`-Fall vergleicht Werte typsicher (`===`) statt typschwach, wie die switch-Anweisung.
- Ein `match`-Ausdruck gibt einen Wert zurück.
- `match`-Fälle fallen nicht auf spätere Fälle durch, so wie es `switch`-Fälle tun können.
- Ein `match`-Ausdruck muss vollständig sein.

Wie `switch`-Anweisungen, werden `match`-Ausdrücke Fall für Fall ausgeführt. Zu Beginn wird kein Code ausgeführt. Die bedingten Ausdrücke werden nur ausgewertet, wenn alle vorherigen bedingten Ausdrücke nicht mit dem betreffenden Ausdruck übereinstimmen. Nur der Rückgabeausdruck, der dem passenden bedingten Ausdruck entspricht, wird ausgewertet. Ein Beispiel dafür:

    <?php
    $result = match ($x) {
        foo() => 'value',
        $this->bar() => 'value', // $this->bar() wird nicht aufgerufen, wenn foo() === $x
        $this->baz => beep(), // beep() wird nur aufgerufen, wenn $x === $this->baz
        // etc.
    };
    ?>

`match`-Bedingungen können mehrere Ausdrücke, die durch Kommata getrennt sind, enthalten. Diese Ausdrücke werden durch ein logisches ODER getrennt und sind ein Kürzel für mehrere `match`-Fälle, welche die gleiche rechte Seite haben.

    <?php
    $result = match ($x) {
        // Dieser Fall:
        $a, $b, $c => 5,
        // ist der gleiche Fall wie:
        $a => 5,
        $b => 5,
        $c => 5,
    };
    ?>

Ein Sonderfall ist die `default`-Klausel. Diese fängt alle Fälle ab, die nicht durch einen der anderen Fälle behandelt wurden. Zum Beispiel:

    <?php
    $expressionResult = match ($condition) {
        1, 2 => foo(),
        3, 4 => bar(),
        default => baz(),
    };
    ?>

> Hinweis: Mehrere default-Anweisungen erzeugen einen `E_COMPILE_ERROR`-Fehler.

Ein `match`-Ausdruck muss vollständig sein. Wenn die Bedingung von keinem Fall behandelt wird, wird eine UnhandledMatchError-Exception geworfen.

Beispiel #4 Beispiel für einen unbehandelten Vergleichsausdruck

    <?php
    $bedingung = 5;

    try {
        match ($bedingung) {
            1, 2 => foo(),
            3, 4 => bar(),
        };
    } catch (\UnhandledMatchError $e) {
        var_dump($e);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(UnhandledMatchError)#1 (7) {
      ["message":protected]=>
      string(33) "Unhandled match value of type int"
      ["string":"Error":private]=>
      string(0) ""
      ["code":protected]=>
      int(0)
      ["file":protected]=>
      string(9) "/in/ICgGK"
      ["line":protected]=>
      int(6)
      ["trace":"Error":private]=>
      array(0) {
      }
      ["previous":"Error":private]=>
      NULL
    }

### Verwendung von Ausdrücken zur Handhabung von Nicht-Vergleichsprüfungen

Es ist möglich, einen `match`-Ausdruck zu verwenden, um nicht-vergleichende Fälle zu behandeln, indem `true` als Bedingung verwendet wird.

Beispiel #5 Prüfung von ganzzahligen Bereichen

    <?php

    $alter = 23;

    $result = match (true) {
        $alter >= 65 => 'Senior',
        $alter >= 25 => 'Erwachsener',
        $alter >= 18 => 'Junger Erwachsener',
        default => 'Kind',
    };

    var_dump($result);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(18) "Junger Erwachsener"

Beispiel #6 Prüfung eines Textes auf enthaltene Zeichenfolgen

    <?php

    $text = 'Bienvenue chez nous';

    $result = match (true) {
        str_contains($text, 'Welcome'), str_contains($text, 'Hello') => 'en',
        str_contains($text, 'Bienvenue'), str_contains($text, 'Bonjour') => 'fr',
        // ...
    };

    var_dump($result);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(2) "fr"

## declare

(PHP 4, PHP 5, PHP 7, PHP 8)

Das `declare`-Konstrukt wird verwendet, um Ausführungsdirektiven für einen Codeblock festzulegen. Die Syntax von `declare` ist ähnlich wie die Syntax anderer Ablauf-Kontrollstrukturen:

    declare (directive)
        statement

Die `directive`-Sektion erlaubt es, das Verhalten des `declare`-Blocks anzugeben. Aktuell werden nur drei Direktiven unterstützt:

- `ticks`
- `encoding`
- `strict_types`

Da Direktiven behandelt werden, wenn die Datei kompiliert wird, dürfen nur Literale als Direktiven-Werte angegeben werden. Variable und Konstante können nicht verwendet werden. Zur Veranschaulichung:

    <?php
    // Dies ist erlaubt:
    declare(ticks=1);

    // Dies ist ungültig:
    const TICK_VALUE = 1;
    declare(ticks=TICK_VALUE);
    ?>

Der `statement`-Teil des `declare`-Blocks wird ausgeführt - wie genau die Ausführung aussieht und welche Seiteneffekte während der Ausführung auftreten können, ist abhängig von der im `directive`-Block gesetzten Direktive.

Das `declare`-Konstrukt kann außerdem im globalen Sichtbarkeitsbereich verwendet werden, es hat dann Auswirkungen auf den gesamten folgenden Code (wird die Datei mit der `declare`-Anweisung inkludiert, hat die Anweisung jedoch keine Auswirkung auf das einbindende File).

    <?php
    // dies sind gleichwertige Schreibweisen:

    // Sie können diese Schreibweise verwenden:
    declare(ticks=1) {
        // hier das vollständige Skript einfügen
    }

    // oder diese:
    declare(ticks=1);
    // hier das vollständige Skript einfügen
    ?>

### Ticks

Ein Tick ist ein Event, das für alle N Low-Level-Statements auftritt, die vom Parser innerhalb des `declare`-Blocks ausgeführt werden. Der Wert für N wird durch die Verwendung von `ticks=N` innerhalb der `directive`-Sektion des `declare`-Blocks angegeben.

Nicht alle Statements führen zu einem Tick-Event. So etwa Konditionen und Argumente.

Das/die bei jedem Tick auftretenden Event(s) werden durch die Verwendung der Funktion register_tick_function() angegeben. Betrachten Sie das folgende Beispiel für mehr Details. Beachten Sie, dass mehr als ein Event bei jedem Tick auftreten kann.

Beispiel #1 Tick Nutzungsbeispiel

    <?php

    declare(ticks=1);

    // Funktion, welche bei jeden Tick-Event aufgerufen wird
    function tick_handler()
    {
        echo "tick_handler() aufgerufen\n";
    }

    register_tick_function('tick_handler'); // löst ein Tick-Ereignis aus

    $a = 1; // löst ein Tick-Ereignis aus

    if ($a > 0) {
        $a += 2; // löst ein Tick-Ereignis aus
        print $a; // löst ein Tick-Ereignis aus
    }

    ?>

Siehe auch register_tick_function() und unregister_tick_function().

### Encoding

Das Encoding eines Skripts kann pro Skript mittels der `encoding`-Direktive festgelegt werden.

Beispiel #2 Das Encoding eines Skripts deklarieren

    <?php
    declare(encoding='ISO-8859-1');
    // hier folgt der Code
    ?>

Achtung

Die einzig zulässige Syntax für ein declare, das mit Namespaces kombiniert wird, ist `declare(encoding='...');`, wobei `...` der Name des Encodings ist. `declare(encoding='...') {}` führt zu einem Parse-Error, wenn es mit Namespaces kombiniert wird.

Siehe auch zend.script_encoding.

## return

(PHP 4, PHP 5, PHP 7, PHP 8)

`return` gibt die Programmsteuerung an das aufrufende Modul zurück. Die Ausführung wird mit dem Ausdruck fortgesetzt, der dem Aufruf des aufrufenden Moduls folgt.

Wenn `return` innerhalb einer Funktion aufgerufen wird, beendet es die Ausführung der Funktion augenblicklich und übergibt den Parameter als Rückgabewert der Funktion. `return` beendet auch die Ausführung von Code innerhalb von eval() oder einer Skript-Datei.

Wenn es im globalen Raum aufgerufen wird, endet die Ausführung des Skripts. Wenn das aktuelle Skript mit include oder require eingebunden wurde, endet nur die Ausführung der eingebundenen Datei, und der Wert, der an `return` übergeben wurde, wird zum Rückgabewert des Aufrufs von include/require. Wenn `return` im Hauptskript aufgerufen wird, endet die Ausführung des gesamten Skripts. Wenn das aktuelle Skript durch die php.ini-Konfigurationsdirektiven auto_prepend_file oder auto_append_file aufgerufen wurde, wird die Ausführung dieses Skripts beendet.

Für mehr Informationen siehe die Dokumentation zu Rückgabewerten.

> Hinweis: Weil `return` keine Funktion ist, sondern ein Sprachkonstrukt, sind die Klammern um den Parameter nicht erforderlich und von deren Verwendung wird abgeraten.

> Hinweis: Wenn kein Parameter übergeben wird, dürfen die Klammern nicht gesetzt werden und `null` wird zurückgegeben. Der Aufruf von `return` mit Klammern aber ohne Parameter verursacht einen Parse-Error.

Seit PHP 7.1.0 lösen return-Anweisungen ohne Parameter bei Funktionen, die einen Rückgabetyp deklarieren, einen Fehler der Stufe `E_COMPILE_ERROR` aus, es sei denn, der Rückgabetyp ist void; in diesem Fall lösen return-Anweisungen mit einem Parameter diesen Fehler aus.

## require

(PHP 4, PHP 5, PHP 7, PHP 8)

`require` entspricht im Wesentlichen include, löst aber im Fehlerfall eine Error-Exception aus (vor PHP 8.0.0 einen Fehler der Stufe `E_COMPILE_ERROR`) während include nur eine Warnung (`E_WARNING`) generiert.

Weitere Informationen hierzu finden Sie in der include-Dokumentation.

## include

(PHP 4, PHP 5, PHP 7, PHP 8)

Der Ausdruck `include` bindet die angegebene Datei ein und wertet sie aus.

Die folgende Dokumentation trifft auch auf require zu.

Dateien werden unter dem angegebenen Pfad gesucht oder, wenn keiner gegeben ist, im include_path. Wenn die Datei auch im include_path nicht gefunden werden kann, sucht `include` noch im Verzeichnis der aufrufenden Datei und im aktuellen Arbeitsverzeichnis. Wenn keine Datei gefunden wurde, erzeugt `include` einen Fehler der Stufe `E_WARNING`; im Gegensatz dazu erzeugt require in diesem Fall einen Fehler der Stufe `E_ERROR`.

Beachten Sie, dass sowohl `include` als auch `require` zusätzliche `E_WARNING`s auslösen, wenn nicht auf die Datei zugegriffen werden kann, bevor sie das endgültige `E_WARNING` bzw. `E_ERROR` auslösen.

Wenn ein Pfad angegeben ist — ob absolut (beginnend mit einem Laufwerksbuchstaben oder `\` auf Windows oder `/` auf Unix/Linux) oder relativ (beginnend mit `.` oder `..`), wird der include_path ignoriert. Wenn der Dateiname beispielsweise mit `../` beginnt, sucht der Parser im übergeordneten Verzeichnis des aktuellen Arbeitsverzeichnisses nach der Datei.

Mehr Informationen über den Umgang PHPs mit dem Einbinden von Dateien im Zusammenhang mit dem Include-Pfad, siehe die Dokumentation zu include_path.

Wenn eine Datei eingebunden wird, wird für den enthaltenen Code der Geltungsbereich für Variablen übernommen, der in der Zeile mit dem include-Befehl gilt. Alle Variablen, die in dieser Zeile in der aufrufenden Datei verfügbar sind, stehen ab diesem Zeitpunkt auch in der aufgerufenen Datei zur Verfügung. Hingegen haben alle Funktionen und Klassen, die in der eingebundenen Datei definiert sind, den globalen Geltungsbereich.

Beispiel #1 Grundlegendes `include`-Beispiel

    vars.php
    <?php

    $farbe = 'grün';
    $frucht = 'Apfel';

    ?>

    test.php
    <?php

    echo "Der $frucht ist $farbe."; // Der  ist  .

    include 'vars.php';

    echo "Der $frucht ist $farbe"; // Der Apfel ist grün

    ?>

Wenn include innerhalb einer Funktion aufgerufen wird, verhält sich der gesamte Code aus der aufgerufenen Datei wie wenn er in der Funktion stünde. Folglich hat er denselben Variablen-Gültigkeitsbereich wie diese Funktion. Eine Ausnahme von dieser Regel sind magische Konstanten, die geparst werden, bevor die Einbindung durchgeführt wird.

Beispiel #2 Include in Funktionen

    <?php

    function foo()
    {
        global $farbe;

        include 'vars.php';

        echo "Der $frucht ist $farbe.";
    }

    /* vars.php ist im Gültigkeitsbereich von foo(),  *
     * sodass $frucht außerhalb von diesem Bereich    *
     * nicht verfügbar ist. $farbe ist auch außerhalb *
     * verfügbar, weil es als global deklariert ist.  */

    foo();                            // Der Apfel ist grün.
    echo "Der $frucht ist $farbe.";   // Der  ist grün.

    ?>

Wenn eine Datei eingebunden wird, wechselt der Parser am Anfang der eingebundenen Datei in den HTML-Modus und am Ende wieder in den PHP-Modus. Aus diesem Grund muss jeder PHP-Code in der eingebundenen Datei mit gültigen PHP-Start- und -Endtags umschlossen sein.

Wenn "include-URL-Wrapper" aktiviert sind (was sie in der Standard-Konfiguration sind), kann die einzubindende Datei mit einer URL (über HTTP oder ein anderes unterstütztes Protokoll - siehe Unterstützte Protokolle und Wrapper für eine Liste unterstützter Protokolle) anstatt eines lokalen Pfades eingebunden werden. Wenn der Zielserver die Zieldatei als PHP-Code interpretiert, können Variablen an die einzubindende Datei mithilfe von HTTP-GET-Query-Strings übergeben werden, obwohl dies nicht dasselbe ist, wie wenn man die Datei einbindet und sie den Variablenbereich übernimmt; das Skript läuft weiterhin auf dem entfernten Server und das Ergebnis wird in das lokale Skript eingebunden.

Beispiel #3 `include` über HTTP

    <?php

    /* Dieses Beispiel setzt voraus, dass www.example.com konfiguriert ist, *
     * .php-Dateien als PHP-Skripte zu interpretieren und .txt-Dateien      *
     * nicht. Des Weiteren meint 'Funktioniert' hier, dass die Variablen    *
     * $foo und $bar innerhalb der eingebundenen Datei verfügbar sind.      */

    // Funktioniert nicht; file.txt wird von www.example.com nicht als PHP interpretiert
    include 'http://www.example.com/file.txt?foo=1&bar=2';

    // Funktioniert nicht; hier wird nach einer Datei mit dem Namen
    // 'file.php?foo=1&bar=2' im lokalen Dateisystem gesucht.
    include 'file.php?foo=1&bar=2';

    // Funktioniert
    include 'http://www.example.com/file.php?foo=1&bar=2';
    ?>

Warnung

# Sicherheits-Warnung

Die entfernte Datei mag vom entfernten Server (je nach Konfiguration) geparst werden oder nicht, aber sie muss weiterhin ein gültiges PHP-Skript ausgeben, weil die Ausgabe auf dem lokalen Server als PHP ausgeführt wird. Wenn die Datei vom entfernten Server dort verarbeitet und lokal nur ausgegeben werden soll, ist readfile() die bessere Wahl. Andernfalls muss sehr gut darauf Acht gegeben werden, sicherzustellen, dass das entfernte Skript gültigen und erwünschten Code ausgibt!

Siehe auch Entfernte Dateien, fopen() und file() für verwandte Informationen.

Umgang mit Rückgabewerten: `include` gibt im Fehlerfall `FALSE` zurück und und generiert eine Warnung. Erfolgreiches Einbinden, außer überschrieben durch die eingebundene Datei, gibt `1` zurück. Es ist möglich, in der eingebundenen Datei return aufzurufen um den Ablauf dieser Datei abzubrechen und zu dem einbindenden Skript zurückzukehren. Der zurückgegebene Wert kann als Rückgabewert des include-Aufrufs abgefragt werden, wie bei einer normalen Funktion. Dies ist beim Einbinden entfernter Dateien nur möglich, wenn die entfernte Datei mit gültigen PHP Start- und Endtags umschlossen ist (wie bei jeder lokalen Datei). Die benötigten Variablen können innerhalb dieser Tags deklariert werden und sie werden an dem Punkt, an dem die Datei eingebunden wird, verfügbar.

Weil `include` eine spezielles Sprachkonstrukt ist, sind die Klammern um das Argument optional. Beim Vergleichen des Rückgabewerts muss allerdings aufgepasst werden (siehe Beispiel).

Beispiel #4 Vergleichen des Rückgabewerts von include

    <?php
    // funktioniert nicht, wird als include(('vars.php') == TRUE) behandelt
    // also als include('1')
    if (include('vars.php') == TRUE) {
        echo 'OK';
    }

    // funktioniert
    if ((include 'vars.php') == TRUE) {
        echo 'OK';
    }
    ?>

Beispiel #5 `include` und return

    return.php
    <?php

    $var = 'PHP';

    return $var;

    ?>

    noreturn.php
    <?php

    $var = 'PHP';

    ?>

    testreturns.php
    <?php

    $foo = include 'return.php';

    echo $foo; // gibt 'PHP' aus

    $bar = include 'noreturn.php';

    echo $bar; // gibt 1 aus

    ?>

`$bar` hat den Wert `1`, weil das Einbinden erfolgreich war. Man beachte den Unterschied zwischen den obigen Beispielen: Die erste Datei nutzt return, was die andere nicht tut. Wenn das Einbinden fehlschlägt, wird `false` zurückgegeben und ein Fehler der Kategorie `E_WARNING` erzeugt.

Wenn in der eingebundenen Datei Funktionen definiert werden, können sie in der einbindenden Datei genutzt werden, unabhängig davon, ob sie vor oder nach return definiert werden. Wenn eine Datei zweimal eingebunden wird, erzeugt PHP einen fatalen Fehler, weil Funktionen bereits definiert wurden. Es wird empfohlen, include_once zu nutzen, anstatt zu überprüfen, ob die Datei bereits eingebunden wurde, und abhängig davon innerhalb der eingebundenen Datei zu handeln.

Ein anderer Weg, die Ausgabe eines eingebundenen Skriptes in eine Variable zu schreiben, ist, `include` mit den Funktionen zur Steuerung des Ausgabepuffers zu verwenden. Beispiel:

Beispiel #6 Nutzung des Ausgabepuffers um eine Datei in einen String aufzunehmen

    <?php
    $string = get_include_contents('somefile.php');

    function get_include_contents($filename) {
        if (is_file($filename)) {
            ob_start();
            include $filename;
            return ob_get_clean();
        }
        return false;
    }

    ?>

Um automatisch Dateien in Skripte einzubinden, siehe auch die Konfigurationsdirektiven auto_prepend_file und auto_append_file in der php.ini.

> Hinweis: Da dies ein Sprachkonstrukt und keine Funktion ist, können Sie dieses nicht mit Variablenfunktionen oder benannten Parametern verwenden.

Siehe auch require, require_once, include_once, get_included_files(), readfile(), virtual(), und include_path.

## require_once

(PHP 4, PHP 5, PHP 7, PHP 8)

Der Ausdruck `require_once` entspricht im Wesentlichen require. PHP prüft hier allerdings, ob die gewünschte Datei bereits eingebunden wurde und wird sie in diesem Fall nicht ein weiteres Mal einbinden.

Nähere Informationen zum Verhalten von `_once` und wie es sich von seinem nicht-`_once`-Gegenstück unterscheidet, finden Sie in der Dokumentation zu include_once.

## include_once

(PHP 4, PHP 5, PHP 7, PHP 8)

Der Ausdruck `include_once` bindet eine angegebene Datei ein und führt sie als PHP-Skript aus. Dieses Verhalten ähnelt dem des Ausdrucks include, mit dem einzigen Unterschied, dass die Datei, wenn sie bereits eingebunden wurde, nicht erneut eingebunden wird und include_once `true` zurückgibt. Wie der Name schon sagt, wird die Datei nur einmal eingebunden.

`include_once` kann beispielsweise benutzt werden, wenn die selbe Datei an mehreren Stellen eingebunden wird, um Problemen durch erneute Definitionen von Funktionen, erneute Zuweisung von Variablen oder ähnliches zu vermeiden.

Für die Funktionsweise der Funktion, siehe die Dokumentation zu include.

## goto

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Bild mit freundlicher Genehmigung von » xkcd

Der `goto`-Operator kann benutzt werden, um innerhalb eines Programs zu einer anderen Anweisung zu springen. Die Zielanweisung wird durch einen Zielnamen festgelegt, bei dem die Groß- und Kleinschreibung beachtet werden muss, gefolgt von einem Doppelpunkt, und der `goto`-Anweisung wird der entsprechende Zielname angefügt. Hierbei handelt es sich jedoch nicht um ein vollständig uneingeschränktes `goto`: Die Zielanweisung muss in der selben Datei und im selben Kontext liegen, d. h. dass weder aus einer Funktion oder Methode herausgesprungen werden kann, noch in sie hineingesprungen. Weiterhin kann nicht in eine Schleifen- oder switch-Anweisung hineingesprungen werden. Es ist jedoch möglich aus diesen herauszuspringen, weshalb `goto` häufig als Ersatz für ein mehrstufiges `break` verwendet wird.

Beispiel #1 `goto`-Beispiel

    <?php

    goto a;
    echo 'Foo';

    a:
    echo 'Bar';

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Bar

Beispiel #2 `goto`-Schleifenbeispiel

    <?php

    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            if ($j == 17) {
                goto end;
            }
        }
    }
    echo "i = $i";
    end:
    echo 'j hit 17';

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    j hit 17

Beispiel #3 Das wird nicht funktionieren

    <?php

    goto loop;
    for ($i = 0, $j = 50; $i < 100; $i++) {
        while ($j--) {
            loop:
        }
    }
    echo "$i = $i";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Fatal error: 'goto' into loop or switch statement is disallowed in
    script on line 2

# Funktionen

## Inhaltsverzeichnis

- Benutzerdefinierte Funktionen
- Funktionsparameter und -argumente
- Rückgabewerte
- Variablenfunktionen
- Interne (eingebaute) Funktionen
- Anonyme Funktionen
- Pfeilfunktionen
- Callback-Funktionen als Objekte erster Klasse

## Benutzerdefinierte Funktionen

Eine Funktion wird definiert mit dem Schlüsselwort `function`, einem Namen, einer Liste von Parametern (die auch leer sein können), die durch Kommata (`,`) getrennt und in Klammern eingeschlossen sind, gefolgt vom Funktionskörper, der in geschweiften Klammern eingeschlossen ist, wie im folgenden Beispiel:

Beispiel #1 Deklarieren einer neuen Funktion namens `foo`

    <?php
    function foo($arg_1, $arg_2, /* ..., */ $arg_n)
    {
        echo "Beispielfunktion.\n";
        return $retval;
    }
    ?>

> Hinweis:

> Seit PHP 8.0.0 kann die Liste der Parameter ein Komma am Ende enthalten:

>     <?php
>     function foo($arg_1, $arg_2,) { }
>     ?>

Innerhalb des Funktionskörpers kann jeder beliebige korrekte PHP-Code vorkommen, sogar andere Funktionen und Klassen-Definitionen.

Für Funktionsnamen gelten in PHP die gleichen Regeln wie für andere Bezeichner. Ein gültiger Funktionsname beginnt mit einem Buchstaben oder Unterstrich gefolgt von einer beliebigen Anzahl von Buchstaben, Ziffern und Unterstrichen. Als regulärer Ausdruck wird dies so ausgedrückt: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`.

Tipp

Siehe auch Userland-Namensregeln.

Es ist nicht erforderlich, dass Funktionen bereits definiert sein müssen, wenn auf sie verwiesen wird, außer wenn eine Funktion nur bedingt definiert wird, wie in den beiden untenstehenden Beispielen gezeigt.

Wenn eine Funktion nur unter bestimmten Bedingungen definiert wird, wie in den beiden folgenden Beispielen, muss die Definition dieser Funktion noch vor deren Aufruf abgearbeitet werden.

Beispiel #2 Bedingte Funktionen

    <?php

    $makefoo = true;

    /* Wir können foo() von hier aus nicht aufrufen, da sie
       noch nicht existiert, aber wir können bar() aufrufen */

    bar();

    if ($makefoo) {
      function foo()
      {
        echo "Ich existiere nicht, bis mich die Programmausführung erreicht hat.\n";
      }
    }

    /* Nun können wir foo() sicher aufrufen,
       da $makefoo als true ausgewertet wurde */

    if ($makefoo) foo();

    function bar()
    {
      echo "Ich existiere sofort nach Programmstart.\n";
    }

    ?>

Beispiel #3 Funktionen innerhalb von Funktionen

    <?php
    function foo()
    {
      function bar()
      {
        echo "Ich existiere nicht, bis foo() aufgerufen wurde.\n";
      }
    }

    /* Wir können bar() noch nicht
       aufrufen, da es nicht existiert */

    foo();

    /* Nun können wir auch bar() aufrufen, da sie durch die
       Abarbeitung von foo() verfügbar gemacht wurde */

    bar();

    ?>

Alle Funktionen und Klassen in PHP existieren im globalen Namensraum - sie können außerhalb von Funktionen aufgerufen werden, selbst wenn sie innerhalb einer Funktion definiert wurden und umgekehrt.

PHP unterstützt weder das Überladen von Funktionen, noch ist es möglich, zuvor deklarierte Funktionen neu zu definieren oder die Definition zu löschen.

> Hinweis: Groß- und Kleinschreibung spielt zwar bei Funktionsnamen keine Rolle für die ASCII-Zeichen `A` bis `Z`, es empfiehlt sich aber trotzdem, bei Funktionsaufrufen die gleiche Schreibweise wie in der Deklaration zu benutzen.

Sowohl eine variable Anzahl Parameter als auch Vorgabewerte für Parameter werden in Funktionen unterstützt. Siehe auch die Funktionsreferenzen für func_num_args(), func_get_arg() und func_get_args() für weitere Informationen.

Es ist in PHP möglich, Funktionen rekursiv aufzurufen.

Beispiel #4 Rekursive Funktionen

    <?php
    function recursion($a)
    {
        if ($a < 20) {
            echo "$a\n";
            recursion($a + 1);
        }
    }
    ?>

> Hinweis: Rekursive Funktions-/Methodenaufrufe mit einer Tiefe von über 100-200 können zu einem Stacküberlauf und damit zum Programmabbruch führen. Insbesondere wird eine unbegrenzte Rekursion als Programmierfehler erachtet.

## Funktionsparameter und -argumente

Die Funktionsparameter werden in der Signatur der Funktion deklariert. Mit einer Liste von Argumenten kann man Informationen an eine Funktion übergeben. Die Argumentenliste ist eine durch Kommas getrennte Liste von Ausdrücken. Die Argumente werden von links nach rechts ausgewertet und das Ergebnis wird den Parametern der Funktion zugewiesen, bevor die eigentliche Funktion aufgerufen wird, d. h. mit der sog. eager-Evaluation (dt. eifrige Auswertung).

PHP unterstützt die Weitergabe von Parametern als Werte (das ist der Standard), als Verweise und als Vorgabewerte. Eine variable Anzahl von Parametern und benannte Parameter werden ebenfalls unterstützt.

> Hinweis:

> Seit PHP 7.3.0 ist es möglich, in der Argumentliste eines Funktionsaufrufs ein nachgestelltes Komma zu verwenden:

>     <?php
>     $v = foo(
>         $arg_1,
>         $arg_2,
>     );
>     ?>

Seit PHP 8.0.0 kann die Liste der Funktionsparameter ein nachgestelltes Komma enthalten, das ignoriert wird. Das ist besonders nützlich in Fällen, in denen die Liste der Parameter lang ist oder lange Variablennamen enthält, sodass es praktisch ist, die Parameter vertikal aufzulisten.

Beispiel #1 Liste von Funktionsparametern mit nachgestelltem Komma

    <?php
    function takes_many_args(
        $first_arg,
        $second_arg,
        $a_very_long_argument_name,
        $arg_with_default = 5,
        $again = 'a default string', // Dieses nachgestellte Komma war vor 8.0.0
                                     // nicht erlaubt.
    )
    {
        // ...
    }
    ?>

### Parameter als Verweise übergeben

Normalerweise werden den Funktionen Werte als Parameter übermittelt. Wenn man also den Wert dieser Parameter innerhalb der Funktion ändert, bleiben sie außerhalb der Funktion unverändert. Wollen Sie aber erreichen, dass die Änderung auch außerhalb der Funktion sichtbar wird, müssen Sie die Parameter als Verweise (Referenzen) übergeben.

Wenn eine Funktion einen Parameter generell als Verweis behandeln soll, setzt man in der Funktionsdefinition ein kaufmännisches Und (&) vor den Parameternamen:

Beispiel #2 Übergeben von Funktionsparametern als Verweis

    <?php
    function fuege_etwas_an(&$string)
    {
        $string .= 'und etwas mehr.';
    }
    $str = 'Dies ist ein String, ';
    fuege_etwas_an($str);
    echo $str; // Ausgabe: 'Dies ist ein String, und etwas mehr.'
    ?>

Es ist ein Fehler, einen konstanten Ausdruck als Argument an einen Parameter zu übergeben, der eigentlich als Referenz übergeben werden müsste.

### Vorgabewerte für Parameter

Eine Funktion kann Standardwerte für Parameter definieren, indem sie eine ähnliche Syntax wie bei der Zuweisung von Variablen verwendet. Der Standardwert wird nur verwendet, wenn für den Parameter kein Argument übergeben wurde. Es ist zu beachten, dass bei der Übergabe von `null` nicht der Standardwert zugewiesen wird.

Beispiel #3 Einsatz von Vorgabeparametern in Funktionen

    <?php
    function machkaffee($typ = "Cappuccino")
    {
        return "Ich mache eine Tasse $typ.\n";
    }
    echo machkaffee();
    echo machkaffee(null);
    echo machkaffee("Espresso");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ich mache eine Tasse Cappuccino.
    Ich mache eine Tasse .
    Ich mache eine Tasse Espresso.

Die Standardwerte der Parameter können skalare Werte, Arrays, der spezielle Typ `null` und seit PHP 8.1.0 auch Objekte sein, die die new ClassName()-Syntax verwenden.

Beispiel #4 Nichtskalare Typen als Vorgabewert

    <?php
    function makecoffee($types = array("Cappuccino"), $coffeeMaker = NULL)
    {
        $device = is_null($coffeeMaker) ? "Hand" : $coffeeMaker;
        return "Ich mache eine Tasse ".join(", ", $types)." mit der $device.\n";
    }
    echo makecoffee();
    echo makecoffee(array("Cappuccino", "Lavazza"), "Teekanne");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ich mache eine Tasse Cappuccino mit der Hand.
    Ich mache eine Tasse Cappuccino, Lavazza mit der Teekanne.

Beispiel #5 Verwendung von Objekten als Standardwerte (seit PHP 8.1.0)

    <?php
    class DefaultCoffeeMaker {
        public function brew() {
            return "Koche Kaffee.\n";
        }
    }
    class FancyCoffeeMaker {
        public function brew() {
            return "Bereite einen schönen Kaffee für Dich zu.\n";
        }
    }
    function makecoffee($coffeeMaker = new DefaultCoffeeMaker)
    {
        return $coffeeMaker->brew();
    }
    echo makecoffee();
    echo makecoffee(new FancyCoffeeMaker);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Koche Kaffee.
    Bereite einen schönen Kaffee für Dich zu.

Der Vorgabewert muss ein konstanter Ausdruck sein, darf also zum Beispiel keine Variable, keine Eigenschaft einer Klasse und kein Funktionsaufruf sein.

Es ist zu beachten, dass optionale Parameter nach den erforderlichen Parametern angegeben werden müssen, da sie sonst bei einem Aufruf nicht weggelassen werden können. Das nachfolgende Beispiel verdeutlicht dies:

Beispiel #6 Ungültige Verwendung von Funktionsparametern mit Vorgabewerten

    <?php
    function mach_joghurt($typ = "rechtsdrehendes", $geschmack)
    {
        return "Mache einen Becher $typ $geschmack-Joghurt.\n";
    }

    echo mach_joghurt("Brombeer"); // "Brombeer" ist $typ, nicht $geschmack
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Fatal error: Uncaught ArgumentCountError: Too few arguments
     to function makeyogurt(), 1 passed in example.php on line 42

Zum Vergleich mit obigem Beispiel::

Beispiel #7 Richtiger Einsatz von Funktionsparametern mit Vorgabewerten

    <?php
    function mach_joghurt($geschmack, $typ = "rechtsdrehendes")
    {
        return "Mache einen Becher $typ $geschmack-Joghurt.\n";
    }

    echo mach_joghurt("Brombeer"); // "Brombeer" ist $geschmack
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Mache einen Becher rechtsdrehendes Brombeer-Joghurt.

Seit PHP 8.0.0 können benannte Argumente verwendet werden, um mehrere optionale Parameter zu überspringen.

Beispiel #8 Korrekte Verwendung von Funktionsparametern mit Vorgabewerten

    <?php
    function makeyogurt($container = "bowl", $flavour = "raspberry", $style = "Greek")
    {
        return "Making a $container of $flavour $style yogurt.\n";
    }

    echo makeyogurt(style: "natural");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Making a bowl of raspberry natural yogurt.

Seit PHP 8.0.0 wird die Angabe von obligatorischen Parametern nach optionalen Parametern missbilligt. Dies kann im Allgemeinen durch das Weglassen des Standardwertes gelöst werden, da er nie verwendet wird. Eine Ausnahme von dieser Regel sind Parameter der Form `Type $param = null`, wobei der Standardwert `null` den Typ implizit nullbar macht. Diese Verwendung ist seit PHP 8.4.0 veraltet und stattdessen sollte ein expliziter nullable Typ verwendet werden.

Beispiel #9 Angabe von optionalen Parametern nach obligatorischen Parametern

    <?php

    function foo($a = [], $b) {}     // Standardwert wird nicht verwendet;
                                     // seit PHP 8.0.0 veraltet
    function foo($a, $b) {}          // Funktionell identisch, aber ohne Veraltet-Hinweis

    function bar(A $a = null, $b) {} // Seit PHP 8.1.0 ist $a implizit erforderlich
                                     // (da es vor dem erforderlichen Parameter steht),
                                     // aber implizit löschbar (seit PHP 8.4.0 veraltet),
                                     // da der Standardparameterwert null ist
    function bar(?A $a, $b) {}       // Empfohlen

    ?>

> Hinweis: Seit PHP 7.1.0 wird ein ArgumentCountError ausgelöst, wenn ein Parameter weggelassen wird, für den kein Standardwert angegeben ist; in früheren Versionen löste es eine Warnung aus.

> Hinweis: Parameter, die ein Argument per Verweis erwarten, dürfen einen Standardwert haben.

### Variable Anzahl von Argumenten

PHP unterstützt eine variable Anzahl an Argumenten in benutzerdefinierten Funktionen durch Verwendung des `...`-Tokens.

Eine Liste von Parametern kann das Token `...` enthalten, um anzugeben, dass die Funktion eine variable Anzahl von Argumenten akzeptiert. Die Argumente werden als Array an die entsprechende Variable übergeben:

Beispiel #10 Verwendung von `...` für den Zugriff auf variable Argumente

    <?php
    function sum(...$numbers) {
        $acc = 0;
        foreach ($numbers as $n) {
            $acc += $n;
        }
        return $acc;
    }

    echo sum(1, 2, 3, 4);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    10

Das Token `...` kann auch dazu verwendet werden, um ein Array oder ein Traversable-Objekt als Liste von Argumenten zu übergeben:

Beispiel #11 Verwendung von `...` zur Übergabe einer Argumentenliste

    <?php
    function add($a, $b) {
        return $a + $b;
    }

    echo add(...[1, 2])."\n";

    $a = [1, 2];
    echo add(...$a);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3
    3

Die Definition von regulären, positionierten Parametern vor dem `...` ist natürlich weiterhin möglich. In einem solchen Fall werden dann nur die zusätzlichen Werte, die zu keinem positionierten Parameter gehören, in das durch `...` erzeugte Array übernommen.

Es ist zudem auch möglich, dem `...`-Token eine Typdeklaration voranzustellen. Ist dies der Fall, dann müssen alle Argumente, die von `...` erfasst werden, vom entsprechenden Typ sein.

Beispiel #12 Variable Argumente mit Typdeklaration

    <?php
    function total_intervals($unit, DateInterval ...$intervals) {
        $time = 0;
        foreach ($intervals as $interval) {
            $time += $interval->$unit;
        }
        return $time;
    }

    $a = new DateInterval('P1D');
    $b = new DateInterval('P2D');
    echo total_intervals('d', $a, $b).' days';

    // Dieser Aufruf wird scheitern, da null keine Instanz von DateInterval ist
    echo total_intervals('d', null);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3 days
    Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2

Durch ein voran gestelltes `&` ist auch die Übergabe von variablen Argumenten als Referenz möglich.

### Benannte Argumente

PHP 8.0.0 führt benannte Argumente als eine Erweiterung der bestehenden Positionsparameter ein. Benannte Argumente ermöglichen die Übergabe von Argumenten an eine Funktion basierend auf dem Parameternamen und nicht auf der Position des Parameters. Das macht die Bedeutung von Argumenten selbsterklärend, macht die Argumente unabhängig von der Reihenfolge und ermöglicht das willkürliche Überspringen von Standardwerten.

Benannte Argumente werden übergeben, indem dem Wert der Parametername gefolgt von einem Doppelpunkt vorangestellt wird. Reservierte Schlüsselwörter dürfen als Parameternamen verwendet werden. Der Parametername muss ein Bezeichner sein; eine dynamische Angabe ist nicht erlaubt.

Beispiel #13 Syntax benannter Argumente

    <?php
    myFunction(paramName: $value);
    array_foobar(array: $value);

    // Wird NICHT unterstützt
    function_name($variableStoringParamName: $value);
    ?>

Beispiel #14 Positionsargumente im Vergleich zu benannten Argumenten

    <?php
    // Verwendung von Positionsargumenten:
    array_fill(0, 100, 50);

    // Verwendung von benannten Argumenten:
    array_fill(start_index: 0, count: 100, value: 50);
    ?>

Die Reihenfolge, in der die benannten Argumente übergeben werden, spielt keine Rolle.

Beispiel #15 Das gleiche Beispiel wie oben mit einer anderen Reihenfolge der Parameter

    <?php
    array_fill(value: 50, count: 100, start_index: 0);
    ?>

Benannte Argumente können mit Positionsargumenten kombiniert werden. In diesem Fall müssen die benannten Argumente nach den Positionsargumenten kommen. Es ist auch möglich, nur einige der optionalen Argumente einer Funktion anzugeben, unabhängig von ihrer Reihenfolge.

Beispiel #16 Kombinieren von benannten Argumenten mit Positionsargumenten

    <?php
    htmlspecialchars($string, double_encode: false);
    // Ist das Gleiche wie
    htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);
    ?>

Die mehrfache Übergabe eines Arguments an denselben benannten Parameter führt zu einer Error-Exception.

Beispiel #17 Die mehrfache Übergabe eines Arguments an denselben benannten Parameter erzeugt einen Fehler

    <?php

    function foo($param) { ... }

    foo(param: 1, param: 2);
    // Error: Named parameter $param overwrites previous argument

    foo(1, param: 2);
    // Error: Named parameter $param overwrites previous argument

    ?>

Seit PHP 8.1.0 ist es möglich, benannte Argumente nach dem Entpacken von Argumenten zu verwenden. Ein bereits entpacktes Argument darf nicht durch einen benanntes Argument überschrieben werden.

Beispiel #18 Verwendung benannter Argumente nach dem Entpacken

    <?php
    function foo($a, $b, $c = 3, $d = 4) {
      return $a + $b + $c + $d;
    }

    var_dump(foo(...[1, 2], d: 40)); // 46
    var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46

    var_dump(foo(...[1, 2], b: 20)); // Fataler Fehler. Der benannte Parameter $b überschreibt das vorherige Argument
    ?>

## Rückgabewerte

Werte können mit der optionalen return-Anweisung zurückgegeben werden. Es können Variablen jeden Typs zurückgegeben werden, auch Arrays oder Objekte. Dies beendet die Funktion sofort und die Kontrolle wird wieder an die aufrufende Zeile zurückgegeben. Für weitere Informationen siehe return.

> Hinweis:

> Wird return weggelassen, dann wird der Wert `null` zurückgegeben.

### Einsatz von return

Beispiel #1 Einsatz von return

    <?php
    function quadrat($zahl)
    {
        return $zahl * $zahl;
    }
    echo quadrat(4);   // gibt '16' aus.

    ?>

Es ist nicht möglich, mehrere Werte von einer Funktion zurückzugeben. Ein ähnliches Resultat kann man aber durch die Rückgabe eines Arrays erreichen.

Beispiel #2 Rückgabe mehrerer Werte als Array

    <?php
    function kleine_zahlen()
    {
       return [0, 1, 2];
    }
    // Bei der Umstrukturierung von Arrays wird jedes Element des Arrays
    // einzeln erfasst.
    [$null, $eins, $zwei] = kleine_zahlen();

    // Vor 7.1.0 ist die einzige gleichwertige Alternative die Verwendung
    // des list()-Konstrukts
    list($null, $eins, $zwei) = kleine_zahlen();

    ?>

Um aus einer Funktion eine Referenz zurückzugeben, muss der Referenz-Operator & sowohl in der Funktionsdeklaration, als auch bei der Zuweisung des zurückgegebenen Wertes verwendet werden:

Beispiel #3 Rückgabe von Referenzen aus Funktionen

    <?php
    function &returniere_referenz()
    {
        return $einereferenz;
    }

    $neuereferenz =& returniere_referenz();
    ?>

Weitere Informationen über Referenzen sind im Kapitel Referenzen in PHP zu finden.

## Variablenfunktionen

PHP unterstützt das Konzept der Variablenfunktionen. Wenn Sie an das Ende einer Variablen Klammern hängen, versucht PHP eine Funktion aufzurufen, deren Name der aktuelle Wert der Variablen ist. Dies kann unter anderem für Callbacks, Funktionstabellen usw. genutzt werden.

Variablenfunktionen funktionieren nicht mit Sprachkonstrukten wie echo, print, unset(), isset(), empty(), include und require. Um diese Konstrukte als Variablenfunktionen benutzen zu können, müssen Sie Ihre eigenen Wrapperfunktionen verwenden.

Beispiel #1 Beispiel für Variablenfunktionen

    <?php
    function foo() {
        echo "In foo()<br />\n";
    }

    function bar($arg = '')
    {
        echo "In bar(); das Argument ist '$arg'.<br />\n";
    }

    // Dies ist eine Wrapperfunktion für echo
    function echoit($string)
    {
        echo $string;
    }

    $func = 'foo';
    $func();        // Dies ruft foo() auf

    $func = 'bar';
    $func('test');  // Dies ruft bar() auf

    $func = 'echoit';
    $func('test');  // Dies ruft echoit() auf
    ?>

Sie können auch die Methode eines Objektes mittels der Variablenfunktionen aufrufen.

Beispiel #2 Beispiel für eine Variablenmethode

    <?php
    class Foo
    {
        function Variable()
        {
            $name = 'Bar';
            $this->$name(); // Dies ruft die Methode Bar() auf
        }

        function Bar()
        {
            echo "Das ist Bar";
        }
    }

    $foo = new Foo();
    $funcname = "Variable";
    $foo->$funcname();  // Dies ruft $foo->Variable() auf

    ?>

Werden statische Methoden aufgerufen, ist der Funktionsaufruf stärker als der statische Eigenschaftsoperator:

Beispiel #3 Beispiel für Variablenmethoden mit statischen Eigenschaften

    <?php
    class Foo
    {
        static $variable = 'statische Eigenschaft';
        static function Variable()
        {
            echo 'Method Variable called';
        }
    }

    echo Foo::$variable; // Dies gibt 'statische Eigenschaft' aus. Es bräuchte
                         // eine $variable im aktuellen Geltungsbereich.
    $variable = "Variable";
    Foo::$variable();  // Dies ruft $foo->Variable() auf, da $variable im
                       // aktuellen Geltungsbereich vorliegt.

    ?>

Beispiel #4 Komplexe Callables

    <?php
    class Foo
    {
        static function bar()
        {
            echo "bar\n";
        }
        function baz()
        {
            echo "baz\n";
        }
    }

    $func = array("Foo", "bar");
    $func(); // gibt "bar" aus
    $func = array(new Foo, "baz");
    $func(); // gibt "baz" aus
    $func = "Foo::bar";
    $func(); // gibt "bar" aus
    ?>

### Siehe auch

- is_callable()
- call_user_func()
- function_exists()
- Variable Variablen

## Interne (eingebaute) Funktionen

PHP enthält standardmäßig viele Funktionen und Konstrukte. Außerdem gibt es viele Funktionen die voraussetzen, dass bestimmte PHP-Erweiterungen einkompiliert wurden, andernfalls erhalten Sie beim Aufruf "undefined function"-Fehlermeldungen. Um z. B. Grafik-Funktionen wie imagecreatetruecolor() nutzen zu können, müssen Sie PHP mit GD-Unterstützung kompilieren, oder um mysqli_connect() nutzen zu können, muss Ihr PHP mit MySQLi-Unterstützung kompiliert sein. Viele Kernfunktionen, z. B. die String- und Variablen-Funktionen sind bereits in jeder PHP-Version enthalten. Ein Aufruf von phpinfo() oder get_loaded_extensions() zeigt Ihnen, welche Erweiterungen in Ihrer PHP-Installation verfügbar sind. Beachten Sie außerdem, dass viele Erweiterungen bereits standardmäßig aktiviert sind und das PHP-Handbuch nach Erweiterungen unterteilt ist. Weitere Informationen zur Einrichtung von PHP finden Sie in den Kapiteln Konfiguration, Installation und den Kapiteln zu den einzelnen Erweiterungen.

Wie Funktionsprototypen zu lesen und zu verstehen sind, wird im Kapitel Wie man eine Funktionsdefinition (Prototyp) liest erklärt. Es ist wichtig zu erkennen, was eine Funktion zurückgibt und ob die übergebenen Parameter verändert werden. So gibt z. B. str_replace() den bearbeiteten String zurück, während usort() die übergebene Variable direkt bearbeitet. Jede Handbuchseite enthält auch spezifische Informationen zu jeder Funktion, wie Informationen über ihre Parameter, die Rückgabewerte sowohl bei Erfolg als auch im Fehlerfall, Änderungen des Verhaltens und die Verfügbarkeit. Die Kenntnis dieser wichtigen (aber oft subtilen) Unterschiede ist von entscheidender Bedeutung für das Schreiben korrekten PHP-Codes.

> Hinweis: Wenn Funktionen andere Parameter erhalten als erwartet, d. h. wenn z. B. ein Array übergeben wird, obwohl ein String erwartet wird, so ist der Rückgabewert undefiniert. In solchen Fällen ist es üblich, dass `null` zurückgegeben wird. Dies ist aber nur eine Konvention, auf die Sie sich nicht unbedingt verlassen können. Seit PHP 8.0.0 sollte in diesem Fall eine TypeError-Exception ausgelöst werden.

> Hinweis:

> Bei eingebauten Funktionen sind skalare Typen im erzwingenden Modus standardmäßig nullbar. Seit PHP 8.1.0 wird in diesem Modus davon abgeraten, an eine interne Funktion für einen Parameter, der nicht als nullbar deklariert ist, `null` zu übergeben. Um sich dem Verhalten benutzerdefinierter Funktionen anzupassen, bei denen skalare Typen explizit als nullbar deklariert werden müssen, wird in diesem Fall ein entsprechender Missbilligungs-Hinweis ausgegeben.

> Zum Beispiel erwartet die Funktion strlen(), dass der Parameter `$string` eine nicht-nullbare Zeichenkette ist. Aus historischen Gründen erlaubt PHP, für diesen Parameter im erzwingenden Modus `null` zu übergeben. Der Parameter wird dabei stillschweigend in den Typ String umgewandelt, was den Wert `""` ergibt. Im Gegensatz dazu wird im strikten Modus ein TypeError ausgegeben.

>     <?php
>     var_dump(strlen(null));
>     // "Deprecated: Passing null to parameter #1 ($string) of type string is deprecated" as of PHP 8.1.0
>     // int(0)

>     var_dump(str_contains("foobar", null));
>     // "Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated" as of PHP 8.1.0
>     // bool(true)
>     ?>

### Siehe auch

- function_exists()
- die Funktionsreferenz
- get_extension_funcs()
- dl()

## Anonyme Funktionen

Anonyme Funktionen, auch bekannt als `Closures`, ermöglichen es, Funktionen ohne Funktionsnamen zu schreiben. Sie sind am nützlichsten als Werte von callable-Parametern, haben aber noch viele andere Verwendungsmöglichkeiten.

Anonyme Funktionen werden unter Verwendung der Klasse Closure implementiert.

Beispiel #1 Beispiel für eine anonyme Funktion

    <?php
    echo preg_replace_callback('~-([a-z])~', function ($match) {
        return strtoupper($match[1]);
    }, 'hallo-welt');
    // gibt halloWelt aus
    ?>

Closures können auch als Werte von Variablen verwendet werden; PHP konvertiert solche Ausdrücke automatisch in Instanzen der internen Klasse Closure. Die Zuweisung einer Closure an eine Variable verwendet die selbe Syntax wie andere Zuweisungen, einschließlich des abschließenden Semikolons:

Beispiel #2 Beispiel für die Zuweisung einer anonymen Funktion

    <?php
    $greet = function($name) {
        printf("Hallo %s\r\n", $name);
    };

    $greet('Welt');
    $greet('PHP');
    ?>

Closures können auch Variablen aus dem Eltern-Gültigkeitsbereich erben. Jede solche Variable muss an das `use`-Sprachkonstrukt übergeben werden. Von PHP 7.1 an dürfen diese Variablen keine superglobals, $this oder Variablen mit dem gleichen Name wie ein Parameter sein. Die Deklaration des Rückgabetyps der Funktion muss nach der `use`-Klausel erfolgen.

Beispiel #3 Erben von Variablen aus dem Eltern-Gültigkeitsbereich

    <?php
    $message = 'hallo';

    // Kein "use"
    $example = function () {
        var_dump($message);
    };
    $example();

    // $message vererben
    $example = function () use ($message) {
        var_dump($message);
    };
    $example();

    // Der Wert einer geerbten Variable ist der Wert zum Zeitpunkt
    // der Funktionsdefinition, nicht des Funktionsaufrufs
    $message = 'welt';
    $example();

    // $message wiederherstellen
    $message = 'hallo';

    // Vererben per Referenz
    $example = function () use (&$message) {
        var_dump($message);
    };
    $example();

    // Der geänderte Wert im Eltern-Gültigkeitsbereich
    // wird in der aufgerufenen Funktion übernommen
    $message = 'welt';
    $example();

    // Closures können auch reguläre Argumente akzeptieren
    $example = function ($arg) use ($message) {
        var_dump($arg . ' ' . $message);
    };
    $example("hallo");

    // Die Deklaration des Rückgabetyps erfolgt nach der use-Klausel
    $example = function () use ($message): string {
        return "hallo $message";
    };
    var_dump($example());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Notice: Undefined variable: message in /example.php on line 10
    NULL
    string(5) "hallo"
    string(5) "hallo"
    string(5) "hallo"
    string(4) "welt"
    string(10) "hallo welt"
    string(10) "hallo welt"

Seit PHP 8.0.0 darf die Liste der geerbten Variablen ein nachgestelltes Komma enthalten, das ignoriert wird.

Das Erben von Variablen aus dem Eltern-Gültigkeitsbereich ist nicht das gleiche wie die Verwendung von globalen Variablen. Globale Variablen existieren im globalen Gültigkeitsbereich, der immer der gleiche ist, unabhängig davon, welche Funktion ausgeführt wird. Der Eltern-Gültigkeitsbereich einer Closure ist die Funktion, in der die Closure deklariert wurde (nicht notwendigerweise die Funktion, aus der sie aufgerufen wurde). Betrachten Sie das folgende Beispiel:

Beispiel #4 Closures und Gültigkeitsbereiche

    <?php
    // Ein einfacher Einkaufswagen, der eine Liste von hinzugefügten Produkten
    // und die Menge jedes Produkts enthält. Er enthält eine Methode, die den
    // Gesamtpreis der Waren im Einkaufswagen unter Verwendung einer Closure
    // als Callback berechnet.
    class Einkaufswagen
    {
        const PREIS_BUTTER  = 1.00;
        const PREIS_MILCH    = 3.00;
        const PREIS_EIER    = 6.95;

        protected $produkte = array();

        public function addiere($produkt, $menge)
        {
            $this->produkte[$produkt] = $menge;
        }

        public function ermittleMenge($produkt)
        {
            return isset($this->produkte[$produkt]) ? $this->produkte[$produkt] :
                   FALSE;
        }

        public function ermittleGesamt($steuer)
        {
            $gesamt = 0.00;

            $callback =
                function ($menge, $produkt) use ($steuer, &$gesamt)
                {
                    $preisProStueck = constant(__CLASS__ . "::PREIS_" .
                        strtoupper($produkt));
                    $gesamt += ($preisProStueck * $menge) * ($steuer + 1.0);
                };

            array_walk($this->produkte, $callback);
            return round($gesamt, 2);
        }
    }

    $mein_einkaufswagen = new Einkaufswagen;

    // Lege ein paar Waren in den Einkaufskorb
    $mein_einkaufswagen->addiere('butter', 1);
    $mein_einkaufswagen->addiere('milch', 3);
    $mein_einkaufswagen->addiere('eier', 6);

    // Gib die Gesamtsumme mit einer Mehrwertsteuer von 5% aus
    print $mein_einkaufswagen->ermittleGesamt(0.05) . "\n";
    // Das Ergebnis ist 54.29
    ?>

Beispiel #5 Automatisches Binden von `$this`

    <?php

    class Test
    {
        public function testing()
        {
            return function() {
                var_dump($this);
            };
        }
    }

    $object = new Test;
    $function = $object->testing();
    $function();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(Test)#1 (0) {
    }

Wird eine anonyme Funktion im Kontext einer Klasse deklariert, so wird diese Klasse automatisch an jene gebunden, was `$this` innerhalb des Geltungsbereichs verfügbar macht. Ist diese automatische Bindung der aktuellen Klasse nicht erwünscht, dann können stattdessen statische anonyme Funktionen verwendet werden.

### Statische anonyme Funktionen

Anonyme Funktionen können statisch deklariert werden. Dies verhindert, dass die aktuelle Klasse automatisch an sie gebunden wird. Objekte können zur Laufzeit ebenfalls nicht an sie gebunden werden.

Beispiel #6 Versuch der Verwendung von `$this` innerhalb einer statischen anonymen Funktion

    <?php

    class Foo
    {
        function __construct()
        {
            $func = static function() {
                var_dump($this);
            };
            $func();
        }
    };
    new Foo();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Notice: Undefined variable: this in %s on line %d
    NULL

Beispiel #7 Versuch, ein Objekt an eine statische anonyme Funktion zu binden

    <?php

    $func = static function() {
        // function body
    };
    $func = $func->bindTo(new stdClass);
    $func();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Warning: Cannot bind an instance to a static closure in %s on line %d

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Closures, die von magischen Methoden erstellt werden, können benannte Parameter akzeptieren.
7.1.0 | Anonyme Funktionen dürfen superglobals, $this und alle Variablen mit dem gleichen Namen wie Parameter nicht als freie Variablen verwenden.

### Anmerkungen

> Hinweis: Es ist möglich, func_num_args(), func_get_arg() und func_get_args() innerhalb einer Closure zu verwenden.

## Pfeilfunktionen

Pfeilfunktionen wurden in PHP 7.4 als prägnantere Syntax für anonyme Funktionen eingeführt.

Sowohl anonyme Funktionen als auch Pfeilfunktionen sind unter Verwendung der Closure-Klasse implementiert.

Pfeilfunktionen haben die grundsätzliche Form `fn (argument_list) => expr`.

Pfeilfunktionen unterstützen dieselbe Funktionalität wie anonyme Funktionen, außer, dass die Verwendung von Variablen des Eltern-Gültigkeitsbereichs immer automatisch erfolgt.

Wenn eine Variable, die im Ausdruck verwendet wird, im Eltern-Gültigkeitsbereich definiert ist, wird sie implizit per Wertübergabe gebunden. Im folgenden Beispiel verhalten sich die Funktionen $fn1 und $fn2 auf die gleiche Weise.

Beispiel #1 Pfeilfunktionen binden Variablen automatisch per Wertübergabe

    <?php

    $y = 1;

    $fn1 = fn($x) => $x + $y;
    // gleichwertig zur Verwendung von $y per Wertübergabe:
    $fn2 = function ($x) use ($y) {
        return $x + $y;
    };

    var_export($fn1(3));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    4

Dies funktioniert auch, wenn Pfeilfunktionen verschachtelt werden:

Beispiel #2 Pfeilfunktionen binden Variablen automatisch per Wertübergabe, selbst wenn sie verschachtelt sind

    <?php

    $z = 1;
    $fn = fn($x) => fn($y) => $x * $y + $z;
    // gibt 51 aus
    var_export($fn(5)(10));
    ?>

Ähnlich wie bei anonymen Funktion erlaubt die Pfeilfunktionssyntax beliebige Funktionssignaturen, einschließlich Parameter- und Rückgabetypen, Defaultwerte, variadische Parameter sowie Referenzübergabe und -rückgabe. Alle folgenden sind gültige Beispiele von Pfeilfunktionen:

Beispiel #3 Beispiele von Pfeilfunktionen

    <?php

    fn(array $x) => $x;
    static fn($x): int => $x;
    fn($x = 42) => $x;
    fn(&$x) => $x;
    fn&($x) => $x;
    fn($x, ...$rest) => $rest;

    ?>

Pfeilfunktionen verwenden die Wertübergabe-Bindung. Dies entspricht in etwa der Verwendung von `use($x)` für jede Variable $x, die in der Pfeilfunktion verwendet wird. Wertübergabe-Bindung bedeutet, dass es nicht möglich ist, Werte aus dem äußeren Geltungsbereich zu ändern. Anonyme Funktionen können statt dessen für Referenzübergabe-Bindungen verwendet werden.

Beispiel #4 Werte aus dem äußeren Geltungsbereich können nicht durch Pfeilfunktionen geändert werden

    <?php

    $x = 1;
    $fn = fn() => $x++; // hat keine Wirkung
    $fn();
    var_export($x);  // gibt 1 aus

    ?>

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Pfeilfunktionen sind verfügbar.

### Anmerkungen

> Hinweis: Es ist möglich func_num_args(), func_get_arg() und func_get_args() innerhalb einer Pfeilfunktion zu verwenden.

## Callback-Funktionen als Objekte erster Klasse

Callback-Funktionen als Objekte erster Klasse wurde mit PHP 8.1.0 eingeführt, um anonyme Funktionen aus Callback-Funktionen zu erstellen. Sie ersetzt die bestehende Callback-Syntax, die Strings und Arrays verwendet. Der Vorteil dieser Syntax ist, dass sie für die statische Analyse zugänglich ist und den Gültigkeitsbereich an der Stelle verwendet, an der die Callback-Funktion aufgerufen wird.

Die `CallableExpr(...)`-Syntax wird verwendet, um ein Closure-Objekt aus einer Callback-Funktion zu erzeugen. `CallableExpr` akzeptiert jeden Ausdruck, der in der PHP-Grammatik direkt aufgerufen werden kann:

Beispiel #1 Einfaches Beispiel für eine Callback-Funktion als Objekt erster Klasse

    <?php

    class Foo {
       public function method() {}
       public static function staticmethod() {}
       public function __invoke() {}
    }

    $obj = new Foo();
    $classStr = 'Foo';
    $methodStr = 'method';
    $staticmethodStr = 'staticmethod';

    $f1 = strlen(...);
    $f2 = $obj(...);  // Callback-Objekt
    $f3 = $obj->method(...);
    $f4 = $obj->$methodStr(...);
    $f5 = Foo::staticmethod(...);
    $f6 = $classStr::$staticmethodStr(...);

    // traditionelle Callback-Funktion mit String, Array
    $f7 = 'strlen'(...);
    $f8 = [$obj, 'method'](...);
    $f9 = [Foo::class, 'staticmethod'](...);
    ?>

> Hinweis:

> Das `...` ist keine Auslassung, sondern Teil der Syntax.

`CallableExpr(...)` hat die gleiche Semantik wie Closure::fromCallable(). Das heißt, im Gegensatz zu Callback-Funktionen, die Strings und Arrays verwenden, wird bei `CallableExpr(...)` der Geltungsbereich an dem Punkt berücksichtigt, an dem er erstellt wird:

Beispiel #2 Vergleich des Anwendungsbereichs von `CallableExpr(...)` und traditionellen Callback-Funktionen

    <?php

    class Foo {
        public function getPrivateMethod() {
            return [$this, 'privateMethod'];
        }

        private function privateMethod() {
            echo __METHOD__, "\n";
        }
    }

    $foo = new Foo;
    $privateMethod = $foo->getPrivateMethod();
    $privateMethod();
    // Fatal error: Call to private method Foo::privateMethod() from global scope
    // Dies liegt daran, dass der Aufruf außerhalb von Foo erfolgt und die Sichtbarkeit ab diesem Punkt geprüft wird.

    class Foo1 {
        public function getPrivateMethod() {
            // Verwendet den Bereich, in dem die Callback-Funktion aufgerufen wird.
            return $this->privateMethod(...); // identisch mit Closure::fromCallable([$this, 'privateMethod']);
        }

        private function privateMethod() {
            echo __METHOD__, "\n";
        }
    }

    $foo1 = new Foo1;
    $privateMethod = $foo1->getPrivateMethod();
    $privateMethod();  // Foo1::privateMethod
    ?>

> Hinweis:

> Die Erzeugung von Objekten mit dieser Syntax (z. B. `new Foo(...)`) wird nicht unterstützt, da die `new Foo()`-Syntax nicht als Aufruf betrachtet wird.

> Hinweis:

> Callback-Funktionen als Objekte erster Klasse können nicht mit dem Nullsafe-Operator kombiniert werden. Beides führt zu einem Fehler bei der Kompilierung:

>     <?php
>     $obj?->method(...);
>     $obj?->prop->method(...);
>     ?>

# Klassen und Objekte

## Inhaltsverzeichnis

- Einführung
- Die Grundlagen
- Eigenschaften
- Property Hooks
- Klassenkonstanten
- Automatisches Laden von Klassen
- Konstruktoren und Destruktoren
- Sichtbarkeit
- Objekt-Vererbung
- Gültigkeitsbereichsoperator (::)
- Schlüsselwort static
- Klassenabstraktion
- Objekt-Interfaces (Schnittstellen)
- Traits
- Anonyme Klassen
- Überladung
- Objektiteration
- Magische Methoden
- Final-Schlüsselwort
- Objekte klonen
- Objekte vergleichen
- Späte statische Bindung
- Objekte und Referenzen
- Serialisierung von Objekten
- Kovarianz und Kontravarianz
- Lazy Objects
- OOP-Changelog

## Einführung

PHP hat ein vollständiges Objektmodell.

Unter den Features finden sich unter anderem Sichtbarkeit, abstrakte und finale Klassen und Methoden sowie magische Methoden, Interfaces und Cloning.

PHP behandelt Objekte auf die gleiche Art wie Referenzen oder Handles, das bedeutet, dass jede Variable eine Objektreferenz statt einer Kopie des gesamten Objekts enthält. Lesen Sie dazu auch den Abschnitt Objekte und Referenzen.

Tipp

Siehe auch Userland-Namensregeln.

## Die Grundlagen

### class

Einfache Klassendefinitionen beginnen mit dem Schlüsselwort `class`, gefolgt von einem Klassennamen, gefolgt von einem Paar geschweifter Klammern, die die Definitionen der Eigenschaften und Methoden der Klasse enthalten.

Der Klassenname kann ein beliebiger gültiger Bezeichner sein, vorausgesetzt es ist kein von PHP reserviertes Wort. Seit PHP 8.4.0 ist die Verwendung eines einzelnen Unterstrichs `_` als Klassenname veraltet. Ein gültiger Klassenname beginnt mit einem Buchstaben oder einem Unterstrich, gefolgt von einer beliebigen Anzahl von Buchstaben, Ziffern oder Unterstrichen; als regulärer Ausdruck formuliert: `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`.

Eine Klasse darf aus ihren eigenen Konstanten, Variablen ("Eigenschaften" genannt) und Funktionen ("Methoden" genannt) bestehen.

Beispiel #1 Definition einer einfachen Klasse

    <?php
    class SimpleClass
    {
        // Deklaration einer Eigenschaft
        public $var = 'ein Standardwert';

        // Deklaration einer Methode
        public function displayVar() {
            echo $this->var;
        }
    }
    ?>

Die Pseudovariable $this ist verfügbar, wenn eine Methode aus einem Objektkontext heraus aufgerufen wird. $this ist eine Referenz auf das aufgerufene Objekt.

Warnung

Wird eine nicht-statische Methode statisch aufgerufen, so wird ein Error ausgelöst. Vor PHP 8.0.0 führte dies zu einem Hinweis über das veraltete Verfahren und $this war nicht definiert.

Beispiel #2 Einige Beispiele für die Pseudovariable $this

    <?php
    class A
    {
        function foo()
        {
            if (isset($this)) {
                echo '$this ist definiert (';
                echo get_class($this);
                echo ").\n";
            } else {
                echo "\$this ist nicht definiert.\n";
            }
        }
    }

    class B
    {
        function bar()
        {
            A::foo();
        }
    }

    $a = new A();
    $a->foo();

    A::foo();

    $b = new B();
    $b->bar();

    B::bar();
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 7 folgende Ausgabe:

    $this ist definiert (A).

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 27
    $this ist nicht definiert.

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
    $this ist nicht definiert.

    Deprecated: Non-static method B::bar() should not be called statically in %s  on line 32

    Deprecated: Non-static method A::foo() should not be called statically in %s  on line 20
    $this ist nicht definiert.

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    $this ist definiert (A).

    Fatal error: Uncaught Error: Non-static method A::foo() cannot be called statically in %s :27
    Stack trace:
    #0 {main}
      thrown in %s  on line 27

#### Schreibgeschützte Klassen

Seit PHP 8.2.0 kann eine Klasse mit dem Modifikator readonly gekennzeichnet werden. Wenn eine Klasse als readonly markiert wird, wird der Modifikator readonly zu jeder deklarierten Eigenschaft hinzugefügt und die Erstellung dynamischer Eigenschaften verhindert. Darüber hinaus ist es nicht möglich, die Unterstützung für solche Eigenschaften mit Hilfe des Attributs AllowDynamicProperties hinzuzufügen. Der Versuch, dies zu tun, führt zu einem Fehler bei der Kompilierung.

    <?php
    #[\AllowDynamicProperties]
    readonly class Foo {
    }

    // Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class Foo
    ?>

Da weder nicht typisierte noch statische Eigenschaften mit dem `readonly`-Modifikator gekennzeichnet werden können, können readonly-Klassen diese auch nicht deklarieren:

    <?php
    readonly class Foo
    {
        public $bar;
    }

    // Fatal error: Readonly property Foo::$bar must have type
    ?>

    <?php
    readonly class Foo
    {
        public static int $bar;
    }

    // Fatal error: Readonly class Foo cannot declare static properties
    ?>

Eine readonly-Klasse kann nur dann erweitert werden, wenn die Kindklasse ebenfalls eine readonly-Klasse ist.

### new

Um eine Instanz einer Klasse zu erzeugen, muss das Schlüsselwort `new` verwendet werden. Ein Objekt wird immer erzeugt, außer das Objekt besitzt einen definierten Konstruktor, der aufgrund eines Fehlers eine Exception auslöst. Klassen sollten vor ihrer Instantiierung definiert werden (in manchen Fällen ist dies eine Notwendigkeit).

Wenn eine Variable, die einen String mit dem Namen einer Klasse enthält, zusammen mit `new` verwendet wird, wird eine neue Instanz dieser Klasse erzeugt. Falls sich die Klasse in einem Namensraum befindet, muss der voll qualifizierte Name hierfür genutzt werden.

> Hinweis:

> Wenn dem Klassenkonstruktor keine Argumente übergeben werden müssen, können die Klammern hinter dem Klassennamen weggelassen werden.

Beispiel #3 Eine Instanz erzeugen

    <?php
    class SimpleClass {
    }

    $instanz = new SimpleClass();
    var_dump($instanz);

    // dies ist auch mit einer Variablen möglich:
    $klassenName = 'SimpleClass';
    $instanz = new $klassenName(); // new SimpleClass()
    ?>

Seit PHP 8.0.0 wird die Verwendung von `new` mit beliebigen Ausdrücken unterstützt. Dies ermöglicht eine komplexere Instanziierung, sofern der Ausdruck einen String erzeugt. Die Ausdrücke müssen in Klammern eingeschlossen werden.

Beispiel #4 Erzeugen einer Instanz mit einem beliebigen Ausdruck

Hier werden mehrere Beispiele für gültige beliebige Ausdrücke gezeigt, die einen Klassennamen erzeugen. Enthalten ist ein Funktionsaufruf, eine String-Verkettung und die Konstante `::class`.

    <?php

    class ClassA extends \stdClass {}
    class ClassB extends \stdClass {}
    class ClassC extends ClassB {}
    class ClassD extends ClassA {}

    function getSomeClass(): string
    {
        return 'ClassA';
    }

    var_dump(new (getSomeClass()));
    var_dump(new ('Class' . 'B'));
    var_dump(new ('Class' . 'C'));
    var_dump(new (ClassD::class));
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    object(ClassA)#1 (0) {
    }
    object(ClassB)#1 (0) {
    }
    object(ClassC)#1 (0) {
    }
    object(ClassD)#1 (0) {
    }

Im Kontext einer Klasse ist es möglich, neue Objekte mit `new self` und `new parent` anzulegen.

Wenn man eine bereits erzeugte Instanz einer Klasse einer neuen Variablen zuweist, wird die neue Variable auf dieselbe Instanz zugreifen wie das Objekt, das zugewiesen wurde. Dieses Verhalten ist dasselbe, wenn man Instanzen an Funktionen übergibt. Eine Kopie eines bereits erzeugten Objekts erhält man, indem man es klont.

Beispiel #5 Objektzuweisung

    <?php
    class SimpleClass {
        public string $var;
    }

    $instanz = new SimpleClass();

    $zugewiesen   =  $instanz;
    $referenz     =& $instanz;

    $instanz->var = '$zugewiesen wird diesen Wert haben';

    $instanz = null; // $instanz und $referenz werden null

    var_dump($instanz);
    var_dump($referenz);
    var_dump($zugewiesen);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL
    NULL
    object(SimpleClass)#1 (1) {
       ["var"]=>
         string(34) "$zugewiesen wird diesen Wert haben"
    }

Es gibt mehrere Möglichkeiten, Instanzen eines Objekts zu erzeugen:

Beispiel #6 Erzeugen neuer Objekte

    <?php

    class Test
    {
        public static function getNew()
        {
            return new static();
        }
    }

    class Child extends Test {}

    $obj1 = new Test(); // Durch den Namen der Klasse
    $obj2 = new $obj1(); // Durch die Variable, die ein Objekt enthält
    var_dump($obj1 !== $obj2);

    $obj3 = Test::getNew(); // Durch die Methode der Klasse
    var_dump($obj3 instanceof Test);

    $obj4 = Child::getNew(); // Durch eine Methode der Kindklasse

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(true)

Es ist möglich, auf ein Mitglied eines neu erzeugten Objekts in einem einzigen Ausdruck zuzugreifen:

Beispiel #7 Zugriff auf ein Mitglied eines neu erzeugten Objekts

    <?php
    echo (new DateTime())->format('Y'), PHP_EOL;
    // Seit PHP 8.4.0 sind umschließende Klammern optional
    echo new DateTime()->format('Y'), PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2025
    2025

> Hinweis: Vor PHP 7.1 werden die Argumente nicht ausgewertet, wenn keine Konstruktor-Funktion definiert ist.

### Eigenschaften und Methoden

Klassen-Eigenschaften und -Methoden leben in separaten "Namensräumen", so dass es eine Eigenschaft und eine Methode desselben Namens geben kann. Der Zugriff auf eine Eigenschaft und eine Methode hat die gleiche Schreibweise und ob auf eine Eigenschaft zugegriffen oder eine Methode aufgerufen wird, hängt einzig und allein vom Kontext ab, d. h. ob die Verwendung ein Variablenzugriff oder ein Funktionsaufruf ist.

Beispiel #8 Variablenzugriff vs. Methodenaufruf

    <?php
    class Foo
    {
        public $bar = 'Eigenschaft';

        public function bar() {
            return 'Methode';
        }
    }

    $obj = new Foo();
    echo $obj->bar, PHP_EOL, $obj->bar(), PHP_EOL;

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Eigenschaft
    Methode

Das bedeutet, dass der Aufruf einer anonymen Funktion, die einer Eigenschaft zugewiesen wurde, nicht direkt möglich ist. Stattdessen muss beispielsweise die Eigenschaft zunächst einer Variablen zugewiesen werden. Es ist möglich, eine solche Eigenschaft direkt aufzurufen, indem man sie in Klammern einschließt.

Beispiel #9 Aufruf einer anonymen Funktion, die in einer Eigenschaft gespeichert ist

    <?php
    class Foo
    {
        public $bar;

        public function __construct() {
            $this->bar = function() {
                return 42;
            };
        }
    }

    $obj = new Foo();

    echo ($obj->bar)(), PHP_EOL;

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    42

### extends

Eine Klasse kann die Konstanten, Methoden und Eigenschaften einer anderen Klasse erben, indem man das Schlüsselwort `extends` in der Deklaration benutzt. Es ist nicht möglich, mehrere Klassen zu erweitern; eine Klasse kann nur eine einzige Basisklasse beerben.

Die geerbten Konstanten, Methoden und Eigenschaften können überschrieben werden, indem sie mit demselben Namen neu deklariert werden, mit dem sie in der Elternklasse definiert wurden. Falls die Elternklasse eine Methode oder eine Konstante als final definiert hat, können diese nicht überschrieben werden. Es ist möglich, auf die überschriebenen Methoden oder statischen Eigenschaften zuzugreifen, wenn diese mittels parent:: referenziert werden.

> Hinweis: Seit PHP 8.1.0 können Konstanten als final deklariert werden.

Beispiel #10 Einfache Vererbung

    <?php
    class SimpleClass
    {
        function displayVar()
        {
            echo "Elternklasse\n";
        }
    }

    class ExtendClass extends SimpleClass
    {
        // Die Elternmethode überschreiben
        function displayVar()
        {
            echo "Erweiternde Klasse\n";
            parent::displayVar();
        }
    }

    $extended = new ExtendClass();
    $extended->displayVar();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Erweiternde Klasse
    Elternklasse

#### Regeln zur Signaturkompatibilität

Wenn eine Methode überschrieben wird, so muss deren Signatur mit derjenigen der Elternmethode kompatibel sein. Andernfalls wird ein fataler Fehler hervorgerufen oder, vor PHP 8.0.0, eine Warnung der Stufe `E_WARNING` ausgegeben. Eine Signatur ist kompatibel, wenn sie die Regeln der Varianz einhält, einen obligatorischen Parameter optional macht, nur neue optionale Parameter hinzufügt und die Sichtbarkeit nicht einschränkt, sondern nur lockert. Dies ist als das Liskovsche Substitutionsprinzip, kurz LSP, bekannt. Der Konstruktor sowie `private` Methoden sind von diesen Regeln zur Signaturkompatibilität ausgenommen, weshalb im Fall einer Untimmigkeit in der Signatur kein fataler Fehler hervorgerufen wird.

Beispiel #11 Kompatible Kindmethoden

    <?php

    class Base
    {
        public function foo(int $a) {
            echo "Gültig\n";
        }
    }

    class Extend1 extends Base
    {
        function foo(int $a = 5)
        {
            parent::foo($a);
        }
    }

    class Extend2 extends Base
    {
        function foo(int $a, $b = 5)
        {
            parent::foo($a);
        }
    }

    $extended1 = new Extend1();
    $extended1->foo();
    $extended2 = new Extend2();
    $extended2->foo(1);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Gültig
    Gültig

Das folgende Beispiel demonstriert, dass eine Kindmethode nicht zur Elternmethode kompatibel ist, wenn sie einen Parameter entfernt oder einen optionalen Parameter notwendig macht.

Beispiel #12 Fataler Fehler, wenn eine Kindmethode einen Parameter entfernt

    <?php

    class Base
    {
        public function foo(int $a = 5) {
            echo "Gültig\n";
        }
    }

    class Extend extends Base
    {
        function foo()
        {
            parent::foo(1);
        }
    }

Das oben gezeigte Beispiel erzeugt mit PHP 8 eine ähnliche Ausgabe wie:

    Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13

Beispiel #13 Fataler Fehler, wenn eine Kindmethode einen optionalen Parameter notwendig macht

    <?php

    class Base
    {
        public function foo(int $a = 5) {
            echo "Gültig\n";
        }
    }

    class Extend extends Base
    {
        function foo(int $a)
        {
            parent::foo($a);
        }
    }

Das oben gezeigte Beispiel erzeugt mit PHP 8 eine ähnliche Ausgabe wie:

    Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13

Warnung

Die Umbenennung eines Parameters einer Methode in einer Kindklasse führt nicht zur Inkompatibilität. Es wird jedoch davon abgeraten, da es zu Fehlern der Stufe Error führt, wenn benannte Parameter verwendet werden.

Beispiel #14 Fehler, wenn benannte Parameter verwendet und diese in der Kindklasse umbenannt werden

    <?php

    class A {
        public function test($foo, $bar) {}
    }

    class B extends A {
        public function test($a, $b) {}
    }

    $obj = new B;

    // Übergabe der Parameter gemäß den Konventionen von A::test()
    $obj->test(foo: "foo", bar: "bar"); // ERROR!

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14
    Stack trace:
    #0 {main}
      thrown in /in/XaaeN on line 14

### ::class

Das Schlüsselwort `class` kann auch für die Namensauflösung einer Klasse verwendet werden. Um den vollständig qualifizierten Namen der Klasse `ClassName` zu erhalten, kann `ClassName::class` verwendet werden. Dies ist vor allem dann praktisch, wenn mit Namensräumen gearbeitet wird.

Beispiel #15 Auflösung von Klassennamen

    <?php
    namespace NS {
        class ClassName {
        }

        echo ClassName::class;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NS\ClassName

> Hinweis:

> Bei der Auflösung des Klassennamens unter Verwendung von `::class` handelt es sich um eine Transformation zur Übersetzungszeit. Das bedeutet, dass zu der Zeit, zu der die Klassennamen-Zeichenkette erzeugt wird, noch kein Autoloading erfolgt ist. Daraus folgt, dass Klassennamen erweitert werden, selbst wenn die Klasse nicht existiert. In diesem Fall wird kein Fehler erzeugt.

> Beispiel #16 Fehlende Auflösung des Klassennamens

>     <?php
>     print Does\Not\Exist::class;
>     ?>

> Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

>     Does\Not\Exist

Von PHP 8.0.0 an kann `::class` auch auf Objekte angewendet werden. Diese Auflösung des Klassennamens erfolgt nicht zur Übersetzungszeit, sondern zur Laufzeit. Sie hat die gleichen Auswirkungen wie der Aufruf von get_class() auf das Objekt.

Beispiel #17 Namensauflösung eines Objekts

    <?php
    namespace NS {
        class ClassName {
        }

        $c = new ClassName();
        print $c::class;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NS\ClassName

### Nullsafe-Methoden und -Eigenschaften

Von PHP 8.0.0 an kann auf Eigenschaften und Methoden stattdessen auch mit dem "Nullsafe"-Operator zugegriffen werden: `?->`. Der Nullsafe-Operator funktioniert genauso als Eigenschafts- oder Methodenzugriff wie oben, mit dem Unterschied, dass `null` zurückgegeben wird, statt dass eine Exception erzeugt wird, wenn das Objekt, das dereferenziert wird, `null` ist. Wenn die Dereferenzierung Teil einer Zeichenkette ist, wird der Rest der Zeichenkette übersprungen.

Der Effekt ist ähnlich, wie wenn man jeden Zugriff zuerst mit is_null() prüft, aber kompakter.

Beispiel #18 Nullsafe Operator

    <?php

    // Von PHP 8.0.0 an entspricht diese Zeile:
    $result = $repository?->getUser(5)?->name;

    // dem folgenden Codeblock:
    if (is_null($repository)) {
        $result = null;
    } else {
        $user = $repository->getUser(5);
        if (is_null($user)) {
            $result = null;
        } else {
            $result = $user->name;
        }
    }
    ?>

> Hinweis:

> Der Nullsafe-Operator wird am besten verwendet, wenn Null ein gültiger und potenziell erwarteter möglicher Rückgabewert für eine Eigenschaft oder eine Methode ist. Um einen Fehler anzuzeigen, ist die Erzeugung einer Exception vorzuziehen.

## Eigenschaften

Variablen in einer Klasse werden Eigenschaften genannt. Andere Begriffe wie Felder werden ebenfalls verwendet, um sich auf dasselbe Konzept zu beziehen, aber innerhalb dieser Referenz wird der Begriff Eigenschaften verwendet. Diese werden definiert, indem mindestens ein Modifikator (wie Sichtbarkeit, Schlüsselwort static oder, seit PHP 8.1.0, readonly) verwendet wird, seit PHP 7.4 optional (außer für `readonly`-Eigenschaften) gefolgt von einer Typdeklaration, gefolgt von einer regulären Variablendeklaration. Die Deklaration darf eine Initialisierung des Variablenwertes beinhalten, der zu setzende Wert muss dabei allerdings ein konstanter Wert sein.

> Hinweis:

> Eine veraltete Art, Klasseneigenschaften zu deklarieren, ist die Verwendung des Schlüsselwors `var` anstelle eines Modifikators.

> Hinweis: Eine Eigenschaft, die ohne Modifikator für Sichtbarkeit deklariert wird, wird als `public` deklariert.

Innerhalb der Methoden einer Klasse kann auf nicht-statische Eigenschaften zugegriffen werden, indem man (den Objektoperator) `->` verwendet: $this->property (wobei `property` der Name der Eigenschaft ist). Zugriff auf statische Eigenschaften erhält man, indem man (den Doppel-Doppelpunkt) `::` verwendet: self::$property. Siehe auch Schlüsselwort static für mehr Informationen zu diesem Thema.

Die Pseudo-Variable $this ist innerhalb jeder Klassenmethode verfügbar, wenn diese Methode im Kontext eines Objektes aufgerufen wird. $this ist der Wert des aufrufenden Objekts.

Beispiel #1 Deklaration von Eigenschaften

    <?php
    class SimpleClass
    {
       public $var1 = 'Hallo ' . 'Welt';
       public $var2 = <<<EOD
    Hallo Welt
    EOD;
       public $var3 = 1+2;
       // Ungültige Deklarationen von Eigenschaften:
       public $var4 = self::myStaticMethod();
       public $var5 = $myVar;

       // Gültige Deklarationen von Eigenschaften:
       public $var6 = myConstant;
       public $var7 = [true, false];

       public $var8 = <<<'EOD'
    Hallo Welt
    EOD;

       // Ohne Modifikator für Sichtbarkeit (Zugriffsrechte):
       static $var9;
       readonly int $var10;
    }
    ?>

> Hinweis:

> Es gibt verschiedene Funktionen für den Umgang mit Klassen und Objekten. Siehe hierzu Klassen- und Objekt-Funktionen.

### Deklaration von Typen

Von PHP 7.4.0 an können Eigenschaftsdefinitionen Typdeklarationen enthalten, mit Ausnahme des Typs callable.

Beispiel #2 Beispiel von typisierten Eigenschaften

    <?php

    class User
    {
        public int $id;
        public ?string $name;

        public function __construct(int $id, ?string $name)
        {
            $this->id = $id;
            $this->name = $name;
        }
    }

    $user = new User(1234, null);

    var_dump($user->id);
    var_dump($user->name);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1234)
    NULL

Typisierte Eigenschaften müssen vor dem Zugriff initialisiert werden, sonst wird ein Error ausgelöst.

Beispiel #3 Auf Eigenschaften zugreifen

    <?php

    class Shape
    {
        public int $numberOfSides;
        public string $name;

        public function setNumberOfSides(int $numberOfSides): void
        {
            $this->numberOfSides = $numberOfSides;
        }

        public function setName(string $name): void
        {
            $this->name = $name;
        }

        public function getNumberOfSides(): int
        {
            return $this->numberOfSides;
        }

        public function getName(): string
        {
            return $this->name;
        }
    }

    $triangle = new Shape();
    $triangle->setName("triangle");
    $triangle->setNumberofSides(3);
    var_dump($triangle->getName());
    var_dump($triangle->getNumberOfSides());

    $circle = new Shape();
    $circle->setName("circle");
    var_dump($circle->getName());
    var_dump($circle->getNumberOfSides());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(8) "triangle"
    int(3)
    string(6) "circle"

    Fatal error: Uncaught Error: Typed property Shape::$numberOfSides must not be accessed before initialization

### Readonly- (nur lesbare) Eigenschaften

Seit PHP 8.1.0 ist es möglich, eine Eigenschaft mit `readonly` zu deklarieren. Dadurch wird verhindert, dass die Eigenschaft nach der Initialisierung geändert wird. Vor PHP 8.4.0 ist eine `readonly`-Eigenschaft implizit auf privat gesetzt und kann nur von derselben Klasse geschrieben werden. Ab PHP 8.4.0 sind `readonly`-Eigenschaften implizit `protected(set)`, können also von Kindklassen aus definiert werden. Dies kann, falls gewünscht, explizit überschrieben werden.

Beispiel #4 Beispiel für Readonly-Eigenschaften

    <?php

    class Test {
       public readonly string $prop;

       public function __construct(string $prop) {
           // Korrekte Initialisierung.
           $this->prop = $prop;
       }
    }

    $test = new Test("foobar");
    // Korrekt ausgelesen.
    var_dump($test->prop); // string(6) "foobar"

    // Unzulässige Neuzuweisung. Es spielt keine Rolle, dass der
    // zugewiesene Wert derselbe ist.
    $test->prop = "foobar";
    // Error: Cannot modify readonly property Test::$prop
    ?>

> Hinweis:

> Der Modifikator readonly kann nur auf typisierte Eigenschaften angewendet werden. Wenn eine Eigenschaft ohne Typbeschränkung readonly sein soll, kann der Typ Mixed verwendet werden.

> Hinweis:

> Statische Readonly-Eigenschaften werden nicht unterstützt.

Eine Readonly-Eigenschaft kann nur einmal initialisiert werden, und zwar nur aus dem Bereich, in dem sie deklariert wurde. Jede andere Zuweisung oder Änderung der Eigenschaft führt zu einer Error-Exception.

Beispiel #5 Unzulässige Initialisierung von Readonly-Eigenschaften

    <?php
    class Test1 {
        public readonly string $prop;
    }

    $test1 = new Test1;
    // Unzulässige Initialisierung außerhalb des privaten Bereichs.
    $test1->prop = "foobar";
    // Error: Cannot initialize readonly property Test1::$prop from global scope
    ?>

> Hinweis:

> Die Angabe eines festen Standardwerts für Readonly-Eigenschaften ist nicht zulässig, da eine Readonly-Eigenschaft mit einem Standardwert im Wesentlichen dasselbe ist wie eine Konstante und daher nicht besonders nützlich.

>     <?php

>     class Test {
>         // Fatal error: Readonly property Test::$prop cannot have default value
>         public readonly int $prop = 42;
>     }
>     ?>

> Hinweis:

> Readonly-Eigenschaften können nach der Initialisierung nicht mit unset() zurückgesetzt werden. Es ist jedoch möglich, eine Readonly-Eigenschaft vor der Initialisierung aus dem Bereich, in dem sie deklariert wurde, zurückzusetzen.

Änderungen sind nicht notwendigerweise einfache Zuweisungen; alle folgenden führen ebenfalls zu einer Error-Exception:

    <?php

    class Test {
        public function __construct(
            public readonly int $i = 0,
            public readonly array $ary = [],
        ) {}
    }

    $test = new Test;
    $test->i += 1;
    $test->i++;
    ++$test->i;
    $test->ary[] = 1;
    $test->ary[0][] = 1;
    unset($test->ary[0]);
    $ref =& $test->i;
    $test->i =& $ref;
    byRef($test->i);
    foreach ($test as &$prop);
    ?>

Readonly-Eigenschaften schließen jedoch nicht die interne Veränderbarkeit aus. Objekte (oder Ressourcen), die in Readonly-Eigenschaften gespeichert sind, können intern immer noch verändert werden:

    <?php

    class Test {
        public function __construct(public readonly object $obj) {}
    }

    $test = new Test(new stdClass);
    // Zulässige interne Änderung.
    $test->obj->foo = 1;
    // Unzulässige Neuzuweisung.
    $test->obj = new stdClass;
    ?>

Seit PHP 8.3.0 können Eigenschaften, die nur gelesen werden können, beim Klonen eines Objekts mit der Methode __clone() neu initialisiert werden.

Beispiel #6 Readonly properties and cloning

    <?php
    class Test1 {
        public readonly ?string $prop;

        public function __clone() {
            $this->prop = null;
        }

        public function setProp(string $prop): void {
            $this->prop = $prop;
        }
    }

    $test1 = new Test1;
    $test1->setProp('foobar');

    $test2 = clone $test1;
    var_dump($test2->prop); // NULL
    ?>

### Dynamische Eigenschaften

Wenn man versucht, einem Objekt eine nicht existierende Eigenschaft zuzuweisen, erstellt PHP automatisch eine entsprechende Eigenschaft. Diese dynamisch erstellte Eigenschaft steht nur dieser Klasseninstanz zur Verfügung.

Warnung

Dynamische Eigenschaften sind seit PHP 8.2.0 veraltet. Es wird empfohlen, die Eigenschaft stattdessen zu deklarieren. Um mit beliebigen Eigenschaftsnamen zu arbeiten, sollte die Klasse die magischen Methoden __get() und __set() implementieren. Als letzte Möglichkeit kann die Klasse mit dem Attribut `#[\AllowDynamicProperties]` markiert werden.

## Property Hooks

Property hooks, also known as "property accessors" in some other languages, are a way to intercept and override the read and write behavior of a property. This functionality serves two purposes:

1. It allows for properties to be used directly, without get- and set- methods, while leaving the option open to add additional behavior in the future. That renders most boilerplate get/set methods unnecessary, even without using hooks.
2. It allows for properties that describe an object without needing to store a value directly.

There are two hooks available on non-static properties: `get` and `set`. They allow overriding the read and write behavior of a property, respectively. Hooks are available for both typed and untyped properties.

A property may be "backed" or "virtual". A backed property is one that actually stores a value. Any property that has no hooks is backed. A virtual property is one that has hooks and those hooks do not interact with the property itself. In this case, the hooks are effectively the same as methods, and the object does not use any space to store a value for that property.

Property hooks are incompatible with `readonly` properties. If there is a need to restrict access to a `get` or `set` operation in addition to altering its behavior, use asymmetric property visibility.

> Hinweis: Version Information
> Property hooks were introduced in PHP 8.4.

### Basic Hook Syntax

The general syntax for declaring a hook is as follows.

Beispiel #1 Property hooks (full version)

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get {
                if ($this->modified) {
                    return $this->foo . ' (modified)';
                }
                return $this->foo;
            }
            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }

    $example = new Example();
    $example->foo = 'changed';
    print $example->foo;
    ?>

The $foo property ends in `{}`, rather than a semicolon. That indicates the presence of hooks. Both a `get` and `set` hook are defined, although it is allowed to define only one or the other. Both hooks have a body, denoted by `{}`, that may contain arbitrary code.

The `set` hook additionally allows specifying the type and name of an incoming value, using the same syntax as a method. The type must be either the same as the type of the property, or contravariant (wider) to it. For instance, a property of type string could have a `set` hook that accepts string|Stringable, but not one that only accepts array.

At least one of the hooks references `$this->foo`, the property itself. That means the property will be "backed". When calling `$example->foo = 'changed'`, the provided string will be first cast to lowercase, then saved to the backing value. When reading from the property, the previously saved value may conditionally be appended with additional text.

There are a number of shorthand syntax variants as well to handle common cases.

If the `get` hook is a single expression, then the `{}` may be omitted and replaced with an arrow expression.

Beispiel #2 Property get expression

This example is equivalent to the previous.

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

If the `set` hook's parameter type is the same as the property type (which is typical), it may be omitted. In that case, the value to set is automatically given the name $value.

Beispiel #3 Property set defaults

This example is equivalent to the previous.

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

If the `set` hook is only setting a modified version of the passed in value, then it may also be simplified to an arrow expression. The value the expression evaluates to will be set on the backing value.

Beispiel #4 Property set expression

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');
            set => strtolower($value);
        }
    }
    ?>

This example is not quite equivalent to the previous, as it does not also modify `$this->modified`. If multiple statements are needed in the set hook body, use the braces version.

A property may implement zero, one, or both hooks as the situation requires. All shorthand versions are mutually-independent. That is, using a short-get with a long-set, or a short-set with an explicit type, or so on is all valid.

On a backed property, omitting a `get` or `set` hook means the default read or write behavior will be used.

> Hinweis: Hooks can be defined when using constructor property promotion. However, when doing so, values provided to the constructor must match the type associated with the property, regardless of what the `set` hook might allow. Consider the following:

>     <?php
>     class Example
>     {
>         public function __construct(
>             public private(set) DateTimeInterface $created {
>                 set (string|DateTimeInterface $value) {
>                     if (is_string($value)) {
>                         $value = new DateTimeImmutable($value);
>                     }
>                     $this->created = $value;
>                 }
>             },
>         ) {
>         }
>     }

> Internally, the engine decomposes this to the following:

>     <?php
>     class Example
>     {
>         public private(set) DateTimeInterface $created {
>             set (string|DateTimeInterface $value) {
>                 if (is_string($value)) {
>                     $value = new DateTimeImmutable($value);
>                 }
>                 $this->created = $value;
>             }
>         }

>         public function __construct(
>             DateTimeInterface $created,
>         ) {
>             $this->created = $created;
>         }
>     }

> Any attempts to set the property outside the constructor will allow either string or DateTimeInterface values, but the constructor will only allow DateTimeInterface. This is because the defined type for the property (DateTimeInterface) is used as the parameter type within the constructor signature, regardless of what the `set` hook allows. If this kind of behavior is needed from the constructor, constructor property promotion cannot be used.

### Virtual properties

Virtual properties are properties that have no backing value. A property is virtual if neither its `get` nor `set` hook references the property itself using exact syntax. That is, a property named `$foo` whose hook contains `$this->foo` will be backed. But the following is not a backed property, and will error:

Beispiel #5 Invalid virtual property

    <?php
    class Example
    {
        public string $foo {
            get {
                $temp = __PROPERTY__;
                return $this->$temp; // Doesn't refer to $this->foo, so it doesn't count.
            }
        }
    }
    ?>

For virtual properties, if a hook is omitted then that operation does not exist and trying to use it will produce an error. Virtual properties take up no memory space in an object. Virtual properties are suited for "derived" properties, such as those that are the combination of two other properties.

Beispiel #6 Virtual property

    <?php
    class Rectangle
    {
        // A virtual property.
        public int $area {
            get => $this->h * $this->w;
        }

        public function __construct(public int $h, public int $w) {}
    }

    $s = new Rectangle(4, 5);
    print $s->area; // prints 20
    $s->area = 30; // Error, as there is no set operation defined.
    ?>

Defining both a `get` and `set` hook on a virtual property is also allowed.

### Scoping

All hooks operate in the scope of the object being modified. That means they have access to all public, private, or protected methods of the object, as well as any public, private, or protected properties, including properties that may have their own property hooks. Accessing another property from within a hook does not bypass the hooks defined on that property.

The most notable implication of this is that non-trivial hooks may sub-call to an arbitrarily complex method if they wish.

Beispiel #7 Calling a method from a hook

    <?php
    class Person {
        public string $phone {
            set => $this->sanitizePhone($value);
        }

        private function sanitizePhone(string $value): string {
            $value = ltrim($value, '+');
            $value = ltrim($value, '1');

            if (!preg_match('/\d\d\d\-\d\d\d\-\d\d\d\d/', $value)) {
                throw new \InvalidArgumentException();
            }
            return $value;
        }
    }
    ?>

### References

Because the presence of hooks intercept the read and write process for properties, they cause issues when acquiring a reference to a property or with indirect modification, such as `$this->arrayProp['key'] = 'value';`. That is because any attempted modification of the value by reference would bypass a set hook, if one is defined.

In the rare case that getting a reference to a property that has hooks defined is necessary, the `get` hook may be prefixed with `&` to cause it to return by reference. Defining both `get` and `&get` on the same property is a syntax error.

Defining both `&get` and `set` hooks on a backed property is not allowed. As noted above, writing to the value returned by reference would bypass the `set` hook. On virtual properties, there is no necessary common value shared between the two hooks, so defining both is allowed.

Writing to an index of an array property also involves an implicit reference. For that reason, writing to a backed array property with hooks defined is allowed if and only if it defines only a `&get` hook. On a virtual property, writing to the array returned from either `get` or `&get` is legal, but whether that has any impact on the object depends on the hook implementation.

Overwriting the entire array property is fine, and behaves the same as any other property. Only working with elements of the array require special care.

### Inheritance

#### Final hooks

Hooks may also be declared final, in which case they may not be overridden.

Beispiel #8 Final hooks

    <?php
    class User
    {
        public string $username {
            final set => strtolower($value);
        }
    }

    class Manager extends User
    {
        public string $username {
            // This is allowed
            get => strtoupper($this->username);

            // But this is NOT allowed, because set is final in the parent.
            set => strtoupper($value);
        }
    }
    ?>

A property may also be declared final. A final property may not be redeclared by a child class in any way, which precludes altering hooks or widening its access.

Declaring hooks final on a property that is declared final is redundant, and will be silently ignored. This is the same behavior as final methods.

A child class may define or redefine individual hooks on a property by redefining the property and just the hooks it wishes to override. A child class may also add hooks to a property that had none. This is essentially the same as if the hooks were methods.

Beispiel #9 Hook inheritance

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Too small');
                }
                $this->x = $value;
            }
        }
    }
    ?>

Each hook overrides parent implementations independently of each other. If a child class adds hooks, any default value set on the property is removed, and must be redeclared. That is consistent with how inheritance works on hook-less properties.

#### Accessing parent hooks

A hook in a child class may access the parent class's property using the `parent::$prop` keyword, followed by the desired hook. For example, `parent::$propName::get()`. It may be read as "access the prop defined on the parent class, and then run its get operation" (or set operation, as appropriate).

If not accessed this way, the parent class's hook is ignored. This behavior is consistent with how all methods work. This also offers a way to access the parent class's storage, if any. If there is no hook on the parent property, its default get/set behavior will be used. Hooks may not access any other hook except their own parent on their own property.

The example above could be rewritten as follows, which would allow for the `Point` class to add its own `set` hook in the future without issues (in the previous example, a hook added to the parent class would be ignored in the child).

Beispiel #10 Parent hook access (set)

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Too small');
                }
                parent::$x::set($value);
            }
        }
    }
    ?>

An example of overriding only a get hook could be:

Beispiel #11 Parent hook access (get)

    <?php
    class Strings
    {
        public string $val;
    }

    class CaseFoldingStrings extends Strings
    {
        public bool $uppercase = true;

        public string $val {
            get => $this->uppercase
                ? strtoupper(parent::$val::get())
                : strtolower(parent::$val::get());
        }
    }
    ?>

### Serialization

PHP has a number of different ways in which an object may be serialized, either for public consumption or for debugging purposes. The behavior of hooks varies depending on the use case. In some cases, the raw backing value of a property will be used, bypassing any hooks. In others, the property will be read or written "through" the hook, just like any other normal read/write action.

- var_dump(): Use raw value
- serialize(): Use raw value
- unserialize(): Use raw value
- __serialize()/__unserialize(): Custom logic, uses get/set hook
- Array casting: Use raw value
- var_export(): Use get hook
- json_encode(): Use get hook
- JsonSerializable: Custom logic, uses get hook
- get_object_vars(): Use get hook
- get_mangled_object_vars(): Use raw value

## Klassenkonstanten

Es ist möglich, Konstanten für jede Klasse zu definieren, die gleich und unveränderlich bleiben. Die standardmäßige Sichtbarkeit einer Klassenkonstante ist `public`.

> Hinweis:

> Klassenkonstanten können von einer Kindklasse neu definiert werden. Ab PHP 8.1.0 können Klassenkonstanten nicht mehr von einer Kindklasse neu definiert werden, wenn sie als final definiert ist.

Ein Interface kann ebenfalls `Konstanten` enthalten. Die Interface-Dokumentation enthält Beispiele dazu.

Es ist möglich, eine Variable als Klassenreferenz zu nutzen. Der Variablenwert darf kein Schlüsselwort (wie `self`, `parent` oder `static`) sein.

Es ist zu beachten, dass Klassenkonstanten nur einmal pro Klasse angelegt werden und nicht für jedes Klassenexemplar.

Seit PHP 8.3.0 können Klassenkonstanten einen skalaren Typ wie `bool`, `int`, `float`, `string` oder sogar `array` haben. Bei Verwendung von `array` kann der Inhalt nur aus anderen skalaren Typen bestehen.

Beispiel #1 Eine Konstante definieren und benutzen

    <?php
    class MyClass
    {
        const CONSTANT = 'Konstanter Wert';

        function showConstant() {
            echo  self::CONSTANT . "\n";
        }
    }

    echo MyClass::CONSTANT . "\n";

    $classname = "MyClass";
    echo $classname::CONSTANT . "\n";

    $class = new MyClass();
    $class->showConstant();

    echo $class::CONSTANT."\n";
    ?>

Die spezielle Konstante `::class` erlaubt die Auflösung voll qualifizierter Klassennamen zur Kompilierzeit, was nützlich für Klassen in Namensräumen ist:

Beispiel #2 Beispiel für ::class in einem Namensraum

    <?php
    namespace foo {
        class bar {
        }

        echo bar::class; // foo\bar
    }
    ?>

Beispiel #3 Beispiel für Ausdrücke mit Klassenkonstanten

    <?php
    const ONE = 1;
    class foo {
        const TWO = ONE * 2;
        const THREE = ONE + self::TWO;
        const SENTENCE = 'Der Wert von THREE ist '.self::THREE;
    }
    ?>

Beispiel #4 Sichtbarkeitsmodifizierer von Klassenkonstanten seit PHP 7.1.0

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }
    echo Foo::BAR, PHP_EOL;
    echo Foo::BAZ, PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 7.1 folgende Ausgabe:

    bar

    Fatal error: Uncaught Error: Cannot access private const Foo::BAZ in …

> Hinweis:

> Von PHP 7.1.0 an sind Sichtbarkeitsmodifizierer für Klassenkonstanten erlaubt.

Beispiel #5 Überprüfen der Sichtbarkeitsvarianz von Klassenkonstanten seit PHP 8.3.0

    <?php

    interface MyInterface
    {
        public const VALUE = 42;
    }

    class MyClass implements MyInterface
    {
        protected const VALUE = 42;
    }
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.3 folgende Ausgabe:

    Fatal error: Access level to MyClass::VALUE must be public (as in interface MyInterface) …

> Hinweis: Seit PHP 8.3.0 wird die Varianz der Sichtbarkeit strenger geprüft. Vor dieser Version konnte sich die Sichtbarkeit einer Klassenkonstante von der Sichtbarkeit der Konstante in der implementierten Schnittstelle unterscheiden.

Beispiel #6 Syntax für das Abrufen von Klassenkonstanten seit PHP 8.3.0

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }

    $name = 'BAR';
    echo Foo::{$name}, PHP_EOL; // bar
    ?>

> Hinweis:

> Seit PHP 8.3.0 können Klassenkonstanten dynamisch über eine Variable abgerufen werden.

Beispiel #7 Zuweisen von Typen zu Klassenkonstanten, seit PHP 8.3.0

    <?php

    class MyClass {
        public const bool MY_BOOL = true;
        public const int MY_INT = 1;
        public const float MY_FLOAT = 1.01;
        public const string MY_STRING = 'one';
        public const array MY_ARRAY = [self::MY_BOOL, self::MY_INT, self::MY_FLOAT, self::MY_STRING];
    }

    var_dump(MyClass::MY_BOOL);
    var_dump(MyClass::MY_INT);
    var_dump(MyClass::MY_FLOAT);
    var_dump(MyClass::MY_STRING);
    var_dump(MyClass::MY_ARRAY);
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.3 folgende Ausgabe:

    bool(true)
    int(1)
    float(1.01)
    string(3) "one"
    array(4) {
      [0]=>
      bool(true)
      [1]=>
      int(1)
      [2]=>
      float(1.01)
      [3]=>
      string(3) "one"
    }

## Automatisches Laden von Klassen

Viele Entwickler, die objektorientierte Anwendungen entwickeln, erzeugen für jede Klassendefinition eine eigene PHP-Quelldatei. Eines der größten Ärgernisse ist die Notwendigkeit, am Anfang eines jeden Skripts eine lange Liste von benötigten Include-Anweisungen (eine für jede Klasse) schreiben zu müssen.

Die Funktion spl_autoload_register() registriert eine beliebige Anzahl von Autoladern, die es ermöglichen, dass Klassen und Schnittstellen automatisch geladen werden, wenn sie derzeit nicht definiert sind. Durch das Registrieren von Autoladern erhält PHP einen letzten Versuch, die Klasse oder Schnittstelle zu laden, bevor es unter Ausgabe einer Fehlermeldung scheitert.

Jedes klassenähnliche Konstrukt kann auf die gleiche Weise automatisch geladen werden. Dazu gehören Klassen, Schnittstellen, Traits und Aufzählungen.

Achtung

Vor PHP 8.0.0 war es möglich, __autoload() zu verwenden, um Klassen und Schnittstellen automatisch zu laden. Dies ist jedoch eine weniger flexible Alternative zu spl_autoload_register(). __autoload() ist seit PHP 7.2.0 veraltet und wurde in PHP 8.0.0 entfernt.

> Hinweis:

> Die Funktion spl_autoload_register() kann mehrfach aufgerufen werden, um mehrere Autoloader zu registrieren. Wenn von einer Autoload-Funktion eine Exception ausgelöst wird, wird dieser Vorgang jedoch unterbrochen und es werden keine weiteren Autoload-Funktionen ausgeführt. Aus diesem Grund wird dringend davon abgeraten, von einer Autoload-Funktion aus eine Exception auszulösen.

Beispiel #1 Autoload-Beispiel

Dieses Beispiel versucht die Klassen `MyClass1` und `MyClass2` aus den entsprechenden Dateien MyClass1.php und MyClass2.php zu laden.

    <?php
    spl_autoload_register(function ($class_name) {
        include $class_name . '.php';
    });

    $obj  = new MyClass1();
    $obj2 = new MyClass2();
    ?>

Beispiel #2 Weiteres Autoload-Beispiel

Dieses Beispiel versucht, das Interface `ITest` zu laden.

    <?php

    spl_autoload_register(function ($name) {
        var_dump($name);
    });

    class Foo implements ITest {
    }

    /*
    string(5) "ITest"

    Fatal error: Interface 'ITest' not found in ...
    */
    ?>

Beispiel #3 Verwenden des Composer-Autoloaders

Der » Composer erzeugt eine `vendor/autoload.php`, die so konfiguriert ist, dass sie die vom Composer verwalteten Pakete automatisch lädt. Durch das Einbinden dieser Datei können diese Pakete ohne zusätzlichen Aufwand verwendet werden.

    <?php
    require __DIR__ . '/vendor/autoload.php';

    $uuid = Ramsey\Uuid\Uuid::uuid7();

    echo "Neue UUID erzeugt -> ", $uuid->toString(), "\n";
    ?>

### Siehe auch

- unserialize()
- unserialize_callback_func
- unserialize_max_depth
- spl_autoload_register()
- spl_autoload()
- __autoload()

## Konstruktoren und Destruktoren

### Konstruktor

function __construct(mixed `...$values` = ""): void

PHP erlaubt es Entwicklern, Konstruktormethoden für Klassen zu deklarieren. Klassen mit Konstruktormethoden rufen diese für jedes neu erzeugte Objekt auf, sodass Konstruktoren für alle Initialisierungen passend sind, die das Objekt brauchen könnte, bevor es benutzt wird.

> Hinweis: Konstruktoren von Elternklassen werden nicht implizit aufgerufen, wenn die Kindklasse einen Konstruktor definiert. Um einen Elternkonstruktor zu benutzen, ist ein Aufruf von parent::__construct() innerhalb des Kindkonstruktors notwendig. Falls das Kind keinen Konstruktor definiert, kann er von der Elternklasse genau wie eine normale Klassenmethode geerbt werden (falls er nicht als privat deklariert wurde).

Beispiel #1 Konstruktoren bei der Vererbung

    <?php
    class BaseClass {
        function __construct() {
            print "Im BaseClass-Konstruktor\n";
        }
    }

    class SubClass extends BaseClass {
        function __construct() {
            parent::__construct();
            print "Im SubClass-Konstruktor\n";
        }
    }

    class OtherSubClass extends BaseClass {
        // erbt den Konstruktor von BaseClass
    }

    // Im BaseClass-Konstruktor
    $obj = new BaseClass();

    // Im BaseClass-Konstruktor
    // Im SubClass-Konstruktor
    $obj = new SubClass();

    // Im BaseClass-Konstruktor
    $obj = new OtherSubClass();
    ?>

Im Gegensatz zu anderen Methoden ist __construct() ist ausgenommen von den üblichen Regeln für die Signaturkompatibilität. wenn sie erweitert wird.

Konstruktoren sind gewöhnliche Methoden, die bei der Instanziierung des entsprechenden Objekts aufgerufen werden. Als solche können sie eine beliebige Anzahl von Argumenten definieren, die erforderlich sein können, einen Typ haben können und einen Standardwert haben können. Konstruktorargumente werden aufgerufen, indem die Argumente in Klammern hinter den Klassennamen gesetzt werden.

Beispiel #2 Die Verwendung von Argumenten eines Konstruktors

    <?php
    class Punkt {
        protected int $x;
        protected int $y;

        public function __construct(int $x, int $y = 0) {
            $this->x = $x;
            $this->y = $y;
        }
    }

    // Beide Parameter übergeben.
    $p1 = new Punkt(4, 5);
    // Nur den erforderlichen Parameter übergeben. $y nimmt den Standardwert von 0 an.
    $p2 = new Punkt(4);
    // Mit benannten Parametern (von PHP 8.0 an):
    $p3 = new Punkt(y: 5, x: 4);
    ?>

Wenn eine Klasse keinen Konstruktor hat oder der Konstruktor keine erforderlichen Argumente hat, können die Klammern weggelassen werden.

#### Konstruktoren alten Stils

Vor PHP 8.0.0 interpretieren Klassen im globalen Namensraum eine Methode, die den gleichen Namen wie die Klasse trägt, als Konstruktor alten Stils. Diese Syntax ist veraltet, und führt zu einem `E_DEPRECATED`-Fehler, ruft die Funktion aber trotzdem als Konstruktor auf. Wenn sowohl __construct() als auch eine Methode gleichen Namens definiert sind, wird __construct() aufgerufen.

In Namensraum-Klassen, oder ab PHP 8.0.0 in jeder Klasse, hat eine Methode mit dem Namen der Klasse keine besondere Bedeutung.

Verwenden Sie in neuem Code immer __construct().

#### Promotion (Beförderung) des Konstruktors

Ab PHP 8.0.0 können Konstruktorparameter auch so befördert werden, dass sie einer Objekteigenschaft entsprechen. Sehr häufig werden Konstruktorparameter einer Eigenschaft im Konstruktor zugewiesen, aber ansonsten nicht bearbeitet. Die Konstruktor-Promotion bietet eine Kurzform für diesen Anwendungsfall. Das obige Beispiel könnte wie folgt umgeschrieben werden:

Beispiel #3 Die Verwendung der Beförderung von Konstruktor-Eigenschaften

    <?php
    class Punkt {
        public function __construct(protected int $x, protected int $y = 0) {
        }
    }

Wenn ein Konstruktorargument einen Modifizierer enthält, interpretiert PHP es sowohl als Objekteigenschaft als auch als Konstruktorargument und weist der Eigenschaft den Wert des Arguments zu. Der Konstruktorkörper kann dann leer sein oder andere Anweisungen enthalten. Alle zusätzlichen Anweisungen werden ausgeführt, nachdem die Argumentwerte den entsprechenden Eigenschaften zugewiesen wurden.

Nicht alle Argumente müssen befördert werden. Beförderte und nicht beförderte Argumente können in beliebiger Reihenfolge zu kombiniert werden. Beförderte Argumente haben keinen Einfluss auf den Code, der den Konstruktor aufruft.

> Hinweis:

> Eigenschaften werden wahrscheinlich meist mit einem Sichtbarkeitsmodifikator (`public`, `protected` oder `private`) befördert, aber jeder andere einzelne Modifikator (z. B. `readonly`) hat denselben Effekt.

> Hinweis:

> Objekteigenschaften dürfen aufgrund der Mehrdeutigkeit, die in die Engine einfließen würde, nicht mit callable typisiert werden. Somit dürfen die angeführten Argumente auch nicht mit callable typisiert werden. Jede andere Typ-Deklaration ist jedoch erlaubt.

> Hinweis:

> Da beförderte Eigenschaften sowohl zu einer Eigenschaft als auch zu einem Funktionsparameter gemacht werden, gelten alle Namensbeschränkungen sowohl für Eigenschaften als auch für Parameter.

> Hinweis:

> Attribute, die auf ein befördertes Konstruktorargument gelegt werden, werden sowohl auf die Eigenschaft als auch auf das Argument übertragen. Die Standardwerte für ein befördertes Konstruktorargument werden nur auf das Argument und nicht auf die Eigenschaft übertragen.

#### New bei der Initialisierung

Ab PHP 8.1.0 können Objekte als Standardwerte für Parameter, als statische Variablen und globale Konstanten sowie in Eigenschaftsparametern verwendet werden. Objekte können nun auch an define() übergeben werden.

> Hinweis:

> Es ist nicht zulässig, einen dynamischen Klassennamen, einen Klassennamen, der keine Zeichenkette ist, oder eine anonyme Klasse zu verwenden. Es ist auch nicht zulässig, Parameter zu entpacken, und nicht unterstützte Ausdrücke als Parameter zu verwenden.

Beispiel #4 Verwendung von new bei Initialisierungen

    <?php

    // Alles zulässig:
    static $x = new Foo;

    const C = new Foo;

    function test($param = new Foo) {}

    #[AnAttribute(new Foo)]
    class Test {
        public function __construct(
            public $prop = new Foo,
        ) {}
    }

    // Alles nicht zulässig (Kompilierfehler):
    function test(
        $a = new (CLASS_NAME_CONSTANT)(), // dynamischer Klassenname
        $b = new class {}, // anonyme Klasse
        $c = new A(...[]), // Entpacken von Parametern
        $d = new B($abc), // nicht unterstützter Ausdruck
    ) {}
    ?>

#### Erzeugung über statische Methoden

PHP unterstützt nur einen einzigen Konstruktor pro Klasse. In einigen Fällen, kann es jedoch wünschenswert sein, dass ein Objekt auf verschiedene Weisen mit unterschiedlichen Eingaben erzeugt werden kann. Der empfohlene Weg, dies zu tun, ist die, Konstruktoren in statische Methoden zu packen.

Beispiel #5 Die Erzeugung über statische Methoden verwenden

    <?php
    $some_json_string = '{ "id": 1004, "name": "Elephpant" }';
    $some_xml_string = "<animal><id>1005</id><name>Elephpant</name></animal>";

    class Produkt {

        private ?int $id;
        private ?string $name;

        private function __construct(?int $id = null, ?string $name = null) {
            $this->id = $id;
            $this->name = $name;
        }

        public static function fromBasicData(int $id, string $name): static {
            $neu = new static($id, $name);
            return $neu;
        }

        public static function fromJson(string $json): static {
            $daten = json_decode($json, true);
            return new static($daten['id'], $daten['name']);
        }

        public static function fromXml(string $xml): static {
            $data = simplexml_load_string($xml);
            $neu = new static();
            $neu->id = (int) $daten->id;
            $neu->name = $daten->name;
            return $neu;
        }
    }

    $p1 = Produkt::fromBasicData(5, 'Widget');
    $p2 = Produkt::fromJson($some_json_string);
    $p3 = Produkt::fromXml($some_xml_string);

    var_dump($p1, $p2, $p3);

Der Konstruktor kann private oder protected gemacht werden, um zu verhindern, dass er von außen aufgerufen wird. Wenn dies der Fall ist, kann nur eine statische Methode die Klasse instanziieren. Da sie in der gleichen Klassendefinition enthalten ist, hat sie Zugriff auf private Methoden, auch wenn sie nicht zur gleichen Objektinstanz gehören. Der private Konstruktor ist optional und kann je nach Anwendungsfall sinnvoll sein oder nicht.

Die drei public static Methoden veranschaulichen dann verschiedene Möglichkeiten das Objekt zu instanziieren.

- `fromBasicData()` nimmt genau die Parameter, die benötigt werden, erzeugt dann das Objekt durch Aufruf des Konstruktors und Rückgabe des Ergebnisses.
- `fromJson()` akzeptiert eine JSON-Zeichenkette und führt selbst eine Vorverarbeitung durch, um sie in das vom Konstruktor gewünschte Format zu konvertieren. Sie gibt dann das neue Objekt zurück.
- `fromXml()` akzeptiert eine XML-Zeichenkette, vorverarbeitet sie und erzeugt dann ein leeres Objekt. Der Konstruktor wird immer noch aufgerufen, aber da alle Parameter optional sind, überspringt sie die Methode. Sie weist dann den Objekteigenschaften direkt Werte zu, bevor sie das Ergebnis zurückgibt.

In allen drei Fällen wird das Schlüsselwort `static` in den Namen der Klasse übersetzt, in der sich der Code befindet. In diesem Fall: `Produkt`.

### Destruktor

function __destruct(): void

PHP verfügt über ein Destruktorkonzept ähnlich dem anderer objektorientierter Programmiersprachen wie C++. Die Destruktormethode wird aufgerufen, sobald es keine weiteren Referenzen auf ein bestimmtes Objekt mehr gibt, oder in beliebiger Reihenfolge am Ende des Skripts.

Beispiel #6 Destruktor-Beispiel

    <?php

    class MyDestructableClass
    {
        function __construct() {
            print "Im Konstruktor\n";
        }

        function __destruct() {
            print "Zerstoere " . __CLASS__ . "\n";
        }
    }

    $obj = new MyDestructableClass();

Wie Konstruktoren auch, werden Elterndestruktoren nicht implizit durch die Engine aufgerufen. Um einen Elterndestruktor zu benutzen muss man explizit die Funktion parent::__destruct() in der Destruktorimplementierung aufrufen. Ebenso wie Konstruktoren kann eine Kindklasse den Destruktor der Eltern erben, falls sie keinen eigenen implementiert.

Der Destruktor wird aufgerufen, wenn das Skript mittels exit() abgebrochen wird. Wenn exit() innerhalb eines Destruktors aufgerufen wird, verhindert das die Ausführung von jeglichen weiteren Shutdown-Routinen.

Wenn ein Destruktor neue Referenzen auf sein Objekt erzeugt, wird er nicht ein zweites Mal aufgerufen, wenn die Anzahl der Referenzen wieder Null erreicht oder während der Abschaltsequenz.

Seit PHP 8.4.0 werden, wenn die Sammlung zyklischer Referenzen während der Ausführung einer Fiber stattfindet, die Destruktoren von Objekten, die für die Sammlung vorgesehen sind, in einer separaten Fiber namens `gc_destructor_fiber` ausgeführt. Wenn diese Fiber unterbrochen wird, wird eine neue erstellt, um alle verbleibenden Destruktoren auszuführen. Die vorherige `gc_destructor_fiber` wird vom Garbage Collector nicht mehr referenziert und kann, wenn sie nicht anderweitig referenziert wird, eingesammelt werden. Objekte, deren Destruktor ausgesetzt ist, werden nicht eingesammelt, bis der Destruktor zurückgibt oder die Fiber selbst eingesammelt wird.

> Hinweis:

> Der Destruktor wird während der Skript-Abschaltung aufgerufen, weshalb die Header immer bereits gesendet sind. Das aktuelle Verzeichnis während der Beendigungsphase des Skripts kann bei einigen SAPIs (z. B. Apache) ein anderes sein.

> Hinweis:

> Der Versuch, eine Exception aus einem Destruktor (der am Ende des Skripts aufgerufen wird) heraus zu auszulösen, führt zu einem fatalen Fehler.

## Sichtbarkeit

Die Sichtbarkeit einer Eigenschaft, Methode oder (von PHP 7.1.0 an) einer Konstante kann definiert werden, indem man der Deklaration eines der Schlüsselwörter `public`, `protected` oder `private` voranstellt. Auf public deklarierte Elemente kann von überall her zugegriffen werden. Protected beschränkt den Zugang auf Elternklassen und abgeleitete Klassen (sowie die Klasse, die das Element definiert). Private grenzt die Sichtbarkeit einzig auf die Klasse ein, die das Element definiert.

### Sichtbarkeit von Membern

Klasseneigenschaften können als public, private oder protected definiert werden. Eigenschaften, die ohne explizites Schlüsselwort für die Sichtbarkeit deklariert sind, werden als public definiert.

Beispiel #1 Deklarieren von Eigenschaften

    <?php
    /**
     * Definiere MyClass
     */
    class MyClass
    {
        public $public = 'Public';
        protected $protected = 'Protected';
        private $private = 'Private';

        function printHello()
        {
            echo $this->public;
            echo $this->protected;
            echo $this->private;
        }
    }

    $obj = new MyClass();
    echo $obj->public; // Funktioniert
    echo $obj->protected; // Fataler Fehler
    echo $obj->private; // Fataler Fehler
    $obj->printHello(); // Zeigt Public, Protected und Private

    /**
     * Definiere MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Wir können die public- und protected-Eigenschaften neu deklarieren,
        // aber nicht die private
        public $public = 'Public2';
        protected $protected = 'Protected2';

        function printHello()
        {
            echo $this->public;
            echo $this->protected;
            echo $this->private;
        }
    }

    $obj2 = new MyClass2();
    echo $obj2->public; // Funktioniert
    echo $obj2->protected; // Fataler Fehler
    echo $obj2->private; // Undefiniert
    $obj2->printHello(); // Zeigt Public2, Protected2, Undefined

    ?>

#### Asymmetrische Sichtbarkeit von Eigenschaften

Seit PHP 8.4 kann die Sichtbarkeit von Eigenschaften auch asymmetrisch festgelegt werden, mit unterschiedlichem Geltungsbereich für Lesen (`get`) und Schreiben (`set`). Insbesondere kann die Sichtbarkeit von `set` separat spezifiziert werden, vorausgesetzt, sie erlaubt nicht mehr als die standardmäßige Sichtbarkeit.

Beispiel #2 Asymmetrische Sichtbarkeit von Eigenschaften

    <?php
    class Book
    {
        public function __construct(
            public private(set) string $title,
            public protected(set) string $author,
            protected private(set) int $pubYear,
        ) {}
    }

    class SpecialBook extends Book
    {
        public function update(string $author, int $year): void
        {
            $this->author = $author; // OK
            $this->pubYear = $year; // Fataler Fehler
        }
    }

    $b = new Book('How to PHP', 'Peter H. Peterson', 2024);

    echo $b->title; // Funktioniert
    echo $b->author; // Funktioniert
    echo $b->pubYear; // Fataler Fehler

    $b->title = 'How not to PHP'; // Fataler Fehler
    $b->author = 'Pedro H. Peterson'; // Fataler Fehler
    $b->pubYear = 2023; // Fataler Fehler
    ?>

Bei der asymmetrischen Sichtbarkeit gibt es ein paar Einschränkungen:

- Nur typisierte Eigenschaften können eine separate Sichtbarkeit von `set` haben.
- Die Sichtbarkeit von `set` muss dieselbe sein wie `get` oder restriktiver. Das heißt, `public protected(set)` und `protected protected(set)` sind erlaubt, aber `protected public(set)` führt zu einem Syntaxfehler.
- Wenn eine Eigenschaft `public` ist, dann kann die Hauptsichtbarkeit weggelassen werden. Das heißt, `public private(set)` und `private(set)` haben das gleiche Ergebnis.
- Eine Eigenschaft mit der Sichtbarkeit `private(set)` ist automatisch `final` und darf in einer Kindklasse nicht neu deklariert werden.
- Der Zugriff auf eine Eigenschaftsreferenz folgt der Sichtbarkeit von `set`, nicht `get`. Das liegt daran, dass eine Referenz verwendet werden kann, um den Eigenschaftswert zu ändern.
- In ähnlicher Weise beinhaltet der Versuch, in eine Array-Eigenschaft zu schreiben, intern sowohl eine `get`- als auch eine `set`-Operation und folgt daher der Sichtbarkeit von `set`, da diese immer die restriktivere ist.

> Hinweis: Leerzeichen sind in der Sichtbarkeitsdeklaration von set nicht erlaubt. `private(set)` ist korrekt. `private( set )` ist nicht korrekt und führt zu einem Parser-Fehler.

Wenn eine Klasse eine andere erweitert, kann die Kindklasse jede Eigenschaft, die nicht `final` ist, neu definieren. Dabei kann sie entweder die Hauptsichtbarkeit oder die Sichtbarkeit von `set` erweitern, vorausgesetzt, die neue Sichtbarkeit ist gleich oder größer als die der Elternklasse. Es ist jedoch zu beachten, dass eine `private` Eigenschaft, die überschrieben wird, nicht die Eigenschaft der Elternklasse ändert, sondern eine neue Eigenschaft mit einem anderen internen Namen erzeugt.

Beispiel #3 Vererbung asymmetrischer Eigenschaften

    <?php
    class Book
    {
        protected string $title;
        public protected(set) string $author;
        protected private(set) int $pubYear;
    }

    class SpecialBook extends Book
    {
        public protected(set) string $title; // OK, da die Rechte zum Lesen breiter sind und die zum Schreiben gleich.
        public string $author; // OK, da die Rechte zum Lesen gleich sind und die zum Schreiben breiter.
        public protected(set) int $pubYear; // Fatal Fehler. private(set)-Eigenschaften sind final.
    }
    ?>

### Sichtbarkeit von Methoden

Klassenmethoden müssen mit public, private oder protected definiert werden. Methoden ohne jede explizite Deklaration sind als public definiert.

Beispiel #4 Deklarieren von Methoden

    <?php
    /**
     * Definiere MyClass
     */
    class MyClass
    {
        // Deklariert einen public Konstruktor
        public function __construct() { }

        // Deklariere eine public Funktion
        public function MyPublic() { }

        // Deklariere eine protected Funktion
        protected function MyProtected() { }

        // Deklariere eine private Funktion
        private function MyPrivate() { }

        // Dies ist public
        function Foo()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate();
        }
    }

    $myclass = new MyClass;
    $myclass->MyPublic(); // Funktioniert
    $myclass->MyProtected(); // Fataler Fehler
    $myclass->MyPrivate(); // Fataler Fehler
    $myclass->Foo(); // Public, Protected und Private funktionieren

    /**
     * Definiere MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Dies ist public
        function Foo2()
        {
            $this->MyPublic();
            $this->MyProtected();
            $this->MyPrivate(); // Fataler Fehler
        }
    }

    $myclass2 = new MyClass2;
    $myclass2->MyPublic(); // Funktioniert
    $myclass2->Foo2(); // Public und Protected funktionieren, Private nicht

    class Bar
    {
        public function test() {
            $this->testPrivate();
            $this->testPublic();
        }

        public function testPublic() {
            echo "Bar::testPublic\n";
        }

        private function testPrivate() {
            echo "Bar::testPrivate\n";
        }
    }

    class Foo extends Bar
    {
        public function testPublic() {
            echo "Foo::testPublic\n";
        }

        private function testPrivate() {
            echo "Foo::testPrivate\n";
        }
    }

    $myFoo = new Foo();
    $myFoo->test(); // Bar::testPrivate
                    // Foo::testPublic
    ?>

### Sichtbarkeit von Konstanten

Von PHP 7.1.0 an können Klassenkonstanten als public, private, oder protected definiert werden. Konstanten, die ohne eine explizite Sichtbarkeitsangabe deklariert wurden, sind public.

Beispiel #5 Deklarieren von Konstanten von PHP 7.1.0 an

    <?php
    /**
     * Definiere MyClass
     */
    class MyClass
    {
        // Deklariere eine öffentliche Konstante
        public const MY_PUBLIC = 'öffentlich';

        // Deklariere eine geschützte Konstante
        protected const MY_PROTECTED = 'geschützt';

        // Deklariere eine private Konstante
        private const MY_PRIVATE = 'privat';

        public function foo()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE;
        }
    }

    $myclass = new MyClass();
    MyClass::MY_PUBLIC; // funktioniert
    MyClass::MY_PROTECTED; // fataler Fehler
    MyClass::MY_PRIVATE; // fataler Fehler
    $myclass->foo(); // öffentlich, geschützt und private funktioniert

    /**
     * Definiere MyClass2
     */
    class MyClass2 extends MyClass
    {
        // Dies ist öffentlich
        function foo2()
        {
            echo self::MY_PUBLIC;
            echo self::MY_PROTECTED;
            echo self::MY_PRIVATE; // fataler Fehler
        }
    }

    $myclass2 = new MyClass2;
    echo MyClass2::MY_PUBLIC; // funktioniert
    $myclass2->foo2(); // öffentlich und geschützt funktioniert, aber nicht privat
    ?>

### Sichtbarkeit von anderen Objekten

Objekte des gleichen Types haben untereinander Zugriff auf die als private und protected markierten Member, obwohl es sich nicht um die gleichen Instanzen handelt. Dies liegt daran, dass die Details über die Implementierung innerhalb solcher Objekte bekannt sind.

Beispiel #6 Zugriff auf als private markierte Member des gleichen Objekttyps

    <?php
    class Test
    {
        private $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        private function bar()
        {
            echo 'Zugriff auf die private Methode';
        }

        public function baz(Test $other)
        {
            // Ändern der privaten Eigenschaft ist möglich:
            $other->foo = 'Hallo';
            var_dump($other->foo);

            // Aufruf der privaten Methode ist ebenfalls möglich:
            $other->bar();
        }
    }

    $test = new Test('test');

    $test->baz(new Test('other'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(5) "Hallo"
    Zugriff auf die private Methode
    +

## Objekt-Vererbung

Vererbung ist ein gängiges Prinzip der Programmierung und PHP verwendet dieses Prinzip in seinem Objektmodell. Dieses Prinzip beeinflusst die Art und Weise, in der mehrere Klassen und Objekte in Beziehung zueinander stehen.

Wenn zum Beispiel eine Klasse erweitert wird, so erbt die Unterklasse alle Methoden der Sichtbarkeiten public und protected sowie alle Eigenschaften und Konstanten von der Elternklasse. Wenn eine Klasse diese Methoden nicht überschreibt, wird die ursprüngliche Funktionalität beibehalten.

Dies ist nützlich, um Funktionalität zu definieren und zu abstrahieren und erlaubt es, zusätzliche Funktionalität in ähnlichen Objekten zu implementieren, ohne sämtliche gemeinsame Funktionalitäten neu implementieren zu müssen.

Private Methoden einer Elternklasse sind für eine Kindklasse nicht zugänglich. Folglich können Kindklassen eine private Methode ohne Berücksichtigung der normalen Vererbungsregeln selbst reimplementieren. Vor PHP 8.0.0 wurden jedoch die Einschränkungen `final` und `static` auf private Methoden angewandt. Ab PHP 8.0.0 ist die einzige Einschränkung für private Methoden, die erzwungen wird, die die `private final` bei Konstruktoren, da dies ein üblicher Weg ist, den Konstruktor zu "deaktivieren", wenn stattdessen statische Fabrikmethoden (factory methods) verwendet werden.

Die Sichtbarkeit von Methoden, Eigenschaften und Konstanten kann gelockert werden, so kann z. B. eine `protected` Methode als `public` markiert werden, aber sie können nicht eingeschränkt werden, indem z. B. eine `public` Eigenschaft als `private` markiert wird. Eine Ausnahme sind Konstruktoren, deren Sichtbarkeit eingeschränkt werden kann, z. B. kann ein `public` Konstruktor in einer Kindklasse als `private` markiert werden.

> Hinweis:

> Wenn Autoloading nicht verwendet wird, so müssen die Klassen definiert werden, bevor sie verwendet werden. Wenn eine Klasse eine andere erweitert, so muss die Elternklasse vor der Kindklasse deklariert werden. Diese Regel gilt für Klassen, die von anderen Klassen und Interfaces erben.

> Hinweis:

> Es ist nicht erlaubt, eine schreib- und lesbare Eigenschaft mit einer schreibgeschützten Eigenschaft zu überschreiben oder umgekehrt.

>     <?php

>     class A {
>         public int $prop;
>     }
>     class B extends A {
>         // Unzulässig: lesen-schreiben -> nur-lesen
>         public readonly int $prop;
>     }
>     ?>

Beispiel #1 Beispiel für Vererbung

    <?php

    class Foo
    {
        public function printItem($string)
        {
            echo 'Foo: ' . $string . PHP_EOL;
        }

        public function printPHP()
        {
            echo 'PHP ist großartig.' . PHP_EOL;
        }
    }

    class Bar extends Foo
    {
        public function printItem($string)
        {
            echo 'Bar: ' . $string . PHP_EOL;
        }
    }

    $foo = new Foo();
    $bar = new Bar();
    $foo->printItem('baz'); // Ausgabe: 'Foo: baz'
    $foo->printPHP();       // Ausgabe: 'PHP ist großartig.'
    $bar->printItem('baz'); // Ausgabe: 'Bar: baz'
    $bar->printPHP();       // Ausgabe: 'PHP ist großartig.'

    ?>

### Kompatibilität des Rückgabetyps bei internen Klassen

Vor PHP 8.1 haben die meisten internen Klassen oder Methoden ihren Rückgabetyp nicht deklariert und wenn sie erweitert wurden, war jeder Rückgabetyp erlaubt.

Seit PHP 8.1.0 sind die meisten internen Methoden dazu übergegangen, den Typ des Rückgabewertes "vorläufig" zu deklarieren. In diesem Fall muss der Typ des Rückgabewerts einer Methode mit dem des erweiterten Elternteils kompatibel sein, andernfalls wird ein Missbilligungs-Hinweis ausgegeben. Es ist zu beachten, dass eine fehlende explizite Deklaration des Rückgabetyps ebenfalls als Signaturfehler betrachtet wird, und daher zu einer entsprechenden Meldung führt.

Wenn der Rückgabetyp für eine überschreibende Methode aufgrund von Kompatibilitätsproblemen zwischen PHP-Versionen nicht deklariert werden kann, kann das Attribut ReturnTypeWillChange hinzugefügt werden, um den Missbilligungs-Hinweis zu unterdrücken.

Beispiel #2 Die überschreibende Methode deklariert keinen Rückgabetyp

    <?php
    class MyDateTime extends DateTime
    {
        public function modify(string $modifier) { return false; }
    }

    // "Deprecated: Return type of MyDateTime::modify(string $modifier) should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" as of PHP 8.1.0
    ?>

Beispiel #3 Die überschreibende Methode deklariert einen falschen Rückgabetyp

    <?php
    class MyDateTime extends DateTime
    {
        public function modify(string $modifier): ?DateTime { return null; }
    }

    // "Deprecated: Return type of MyDateTime::modify(string $modifier): ?DateTime should either be compatible with DateTime::modify(string $modifier): DateTime|false, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice" as of PHP 8.1.0
    ?>

Beispiel #4 Die überschreibende Methode deklariert einen falschen Rückgabetyp ohne Missbilligungs-Hinweis

    <?php
    class MyDateTime extends DateTime
    {
        /**
         * @return DateTime|false
         */
        #[\ReturnTypeWillChange]
        public function modify(string $modifier) { return false; }
    }

    // Es wird kein Missbilligungs-Hinweis ausgelöst
    ?>

## Gültigkeitsbereichsoperator (::)

Der Gültigkeitsbereichsoperator (auch Paamayim Nekudotayim genannt) oder einfacher ausgedrückt, der Doppel-Doppelpunkt, ist ein Kürzel, das den Zugriff auf eine Konstante, eine statische Eigenschaft oder eine statische Methode einer Klasse oder einer ihrer Eltern erlaubt. Außerdem können statische Eigenschaften oder Methoden durch späte statische Bindung überschrieben werden.

Wenn Sie diese Elemente außerhalb der Klassendefinition ansprechen, benutzen Sie den Namen der Klasse.

Es ist möglich, eine Variable als Klassenreferenz zu nutzen. Der Variablenwert darf kein Schlüsselwort (wie `self`, `parent` oder `static`) sein.

Paamayim Nekudotayim scheint auf den ersten Blick eine eigenartige Wahl für die Benennung eines Doppel-Doppelpunktes zu sein. Jedoch entschied sich das Zend Team ihn so zu nennen, während sie die Zend Engine 0.5 schrieben (welche PHP 3 antreibt). Tatsächlich bedeutet das Doppel-Doppelpunkt - in Hebräisch.

Beispiel #1 :: außerhalb der Klassendefinition

    <?php
    class MyClass {
        const CONST_VALUE = 'Ein konstanter Wert';
    }

    $classname = 'MyClass';
    echo $classname::CONST_VALUE;

    echo MyClass::CONST_VALUE;
    ?>

Die drei speziellen Schlüsselwörter self, parent und static werden benutzt, um auf Member und Methoden von innerhalb der Klassendefinition zuzugreifen.

Beispiel #2 :: innerhalb der Klassendefinition

    <?php
    class MyClass {
        const CONST_VALUE = 'Ein konstanter Wert';
    }

    class OtherClass extends MyClass
    {
        public static $my_static = 'statische Variable';

        public static function doubleColon() {
            echo parent::CONST_VALUE . "\n";
            echo self::$my_static . "\n";
        }
    }

    $classname = 'OtherClass';
    $classname::doubleColon();

    OtherClass::doubleColon();
    ?>

Wenn eine abgeleitete Klasse die Definition der Methode eines Vaters überschreibt, wird PHP die Methode des Vaters nicht aufrufen. Es obliegt der abgeleiteten Klasse, ob die Methode der Vaterklasse aufgerufen wird oder nicht. Dies gilt ebenfalls für Konstruktoren und Destruktoren, Überladung und magische Methodendefinitionen.

Beispiel #3 Eine Vatermethode aufrufen

    <?php
    class MyClass
    {
        protected function myFunc() {
            echo "MyClass::myFunc()\n";
        }
    }

    class OtherClass extends MyClass
    {
        // Die Definition des Vaters überschreiben
        public function myFunc()
        {
            // Aber dennoch die Funktion des Vaters aufrufen
            parent::myFunc();
            echo "OtherClass::myFunc()\n";
        }
    }

    $class = new OtherClass();
    $class->myFunc();
    ?>

Siehe auch ein Beispiel zur Bedeutung von `$this`, wenn nicht-statische Methoden statisch aufgerufen werden.

## Schlüsselwort static

Tipp

Diese Seite beschreibt die Verwendung des Schlüsselworts `static`, mit dem statische Methoden und Eigenschaften definiert werden. `static` kann ebenfalls benutzt werden, um statische Variablen zu definieren, statische anonyme Funktionen zu definieren und für späte statische Bindung. Bitte entnehmen Sie diesen Seiten Informationen zu diesen Bedeutungen von `static`.

Klasseneigenschaften oder -methoden als statisch zu deklarieren, macht diese zugänglich, ohne dass man die Klasse instantiieren muss. Auch innerhalb eines instantiierten Klassenobjekts kann statisch auf sie zugegriffen werden.

### Statische Methoden

Weil statische Methoden ohne die Instanz eines erzeugten Objektes aufrufbar sind, ist die Pseudovariable $this nicht innerhalb von Methoden verfügbar, die als statisch deklariert wurden.

Warnung

Der Aufruf von nicht-statischen Methoden löst einen Error aus.

Vor PHP 8.0.0 wird der statische Aufruf von nicht-statischen Methoden missbilligt und erzeugt eine Warnung der Stufe `E_DEPRECATED`.

Beispiel #1 Beispiel für statische Methoden

    <?php
    class Foo {
        public static function aStaticMethod() {
            // ...
        }
    }

    Foo::aStaticMethod();
    $classname = 'Foo';
    $classname::aStaticMethod();
    ?>

### Statische Eigenschaften

Auf statische Eigenschaften wird mit dem Operator zur Auflösung des Gültigkeitsbereichs (::) zugegriffen. Es kann nicht über den Objektoperator (`->`) darauf zugegriffen werden.

Die Klasse kann über eine Variable referenziert werden. Der Variablenwert darf dabei kein Schlüsselwort (wie `self`, `parent` oder `static`) sein.

Beispiel #2 Beispiel für statische Eigenschaften

    <?php
    class Foo
    {
        public static $my_static = 'foo';

        public function staticValue() {
            return self::$my_static;
        }
    }

    class Bar extends Foo
    {
        public function fooStatic() {
            return parent::$my_static;
        }
    }

    print Foo::$my_static . "\n";

    $foo = new Foo();
    print $foo->staticValue() . "\n";
    print $foo->my_static . "\n";      // Undefinierte "Eigenschaft" my_static

    print $foo::$my_static . "\n";
    $classname = 'Foo';
    print $classname::$my_static . "\n";

    print Bar::$my_static . "\n";
    $bar = new Bar();
    print $bar->fooStatic() . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8 eine ähnliche Ausgabe wie:

    foo
    foo

    Notice: Accessing static property Foo::$my_static as non static in /in/V0Rvv on line 23

    Warning: Undefined property: Foo::$my_static in /in/V0Rvv on line 23

    foo
    foo
    foo
    foo

## Klassenabstraktion

PHP unterstützt abstrakte Klassen und Methoden. Abstrakt definierte Klassen können nicht instantiiert werden. Jede Klasse, die wenigstens eine abstrakte Methode oder Eigenschaft enthält, muss ebenso abstrakt sein. Als abstrakt definierte Methoden deklarieren nur die Signatur der Methode und ob sie öffenlich oder geschützt ist - sie können nicht die Implementierung definieren. Als abstrakt definierte Eigenschaften können eine Anforderung für das Verhalten von `get` oder `set` deklarieren und eine Implementierung für eine, aber nicht für beide Operationen bereitstellen.

Wenn von einer abstrakten Klasse abgeleitet wird, müssen alle in der Deklaration der Elternklasse als abstrakt bezeichneten Methoden durch das Kind definiert werden und den üblichen Regeln zur Vererbung und Signatur-Kompatibilität folgen.

Seit PHP 8.4 kann eine abstrakte Klasse eine abstrakte Eigenschaft deklarieren, die entweder öffenlich oder geschützt ist. Eine abstrakte Eigenschaft, die geschützt ist, kann durch eine Eigenschaft erfüllt werden, die entweder vom geschützten oder vom öffenlichen Geltungsbereich aus lesbar/schreibbar ist

Eine abstrakte Eigenschaft kann entweder durch eine Standardeigenschaft oder durch eine Eigenschaft mit definierten Hooks erfüllt werden, die der erforderlichen Operation entspricht.

Beispiel #1 Beispiel für eine abstrakte Methode

    <?php

    abstract class AbstractClass
    {
        // Die abgeleitete Klasse zwingen, diese Methoden zu definieren
        abstract protected function getValue();
        abstract protected function prefixValue($prefix);

        // Gemeinsame Methode
        public function printOut()
        {
            print $this->getValue() . "\n";
        }
    }

    class ConcreteClass1 extends AbstractClass
    {
        protected function getValue()
        {
            return "ConcreteClass1";
        }

        public function prefixValue($prefix)
        {
            return "{$prefix}ConcreteClass1";
        }
    }

    class ConcreteClass2 extends AbstractClass
    {
        public function getValue()
        {
            return "ConcreteClass2";
        }

        public function prefixValue($prefix)
        {
            return "{$prefix}ConcreteClass2";
        }
    }

    $class1 = new ConcreteClass1();
    $class1->printOut();
    echo $class1->prefixValue('FOO_'), "\n";

    $class2 = new ConcreteClass2();
    $class2->printOut();
    echo $class2->prefixValue('FOO_'), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ConcreteClass1
    FOO_ConcreteClass1
    ConcreteClass2
    FOO_ConcreteClass2

Beispiel #2 Beispiel für eine abstrakte Methode

    <?php

    abstract class AbstractClass
    {
        // Eine abstrakte Methode muss nur die verpflichtenden Parameter definieren
        abstract protected function prefixName($name);
    }

    class ConcreteClass extends AbstractClass
    {
        // Eine Kindklasse kann optionale Parameter definieren, die sich nicht in der
        // Signatur der Elternklasse wiederfinden
        public function prefixName($name, $separator = ".")
        {
            if ($name == "Pacman") {
                $prefix = "Mr";
            } elseif ($name == "Pacwoman") {
                $prefix = "Mrs";
            } else {
                $prefix = "";
            }

            return "{$prefix}{$separator} {$name}";
        }
    }

    $class = new ConcreteClass();
    echo $class->prefixName("Pacman"), "\n";
    echo $class->prefixName("Pacwoman"), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Mr. Pacman
    Mrs. Pacwoman

Beispiel #3 Beispiel für eine abstrakte Eigenschaft

    <?php

    abstract class A
    {
        // Erweiternde Klassen müssen eine öffentlich lesbare Eigenschaft haben
        abstract public string $readable {
            get;
        }

        // Erweiternde Klassen müssen eine geschützt oder öffentlich schreibbare
        // Eigenschaft haben
        abstract protected string $writeable {
            set;
        }

        // Erweiternde Klassen müssen eine geschützte oder öffentliche symmetrische
        // Eigenschaft haben
        abstract protected string $both {
            get;
            set;
        }
    }

    class C extends A
    {
        // Dies erfüllt die Anforderung und macht sie außerdem einstellbar, was
        // gültig ist
        public string $readable;

        // Dies würde die Anforderung NICHT erfüllen, da sie nicht öffentlich
        // lesbar ist
        protected string $readable;

        // Dies erfüllt die Anforderung genau, ist also ausreichend.
        // Es darf nur geschrieben werden, und zwar nur aus dem geschützten Bereich
        protected string $writeable {
            set => $value;
        }

        // Dies erweitert die Sichtbarkeit von geschützt auf öffentlich, was in
        // Ordnung ist
        public string $both;
    }

    ?>

Eine abstrakte Eigenschaft einer abstrakten Klasse kann Implementierungen für jeden Hook bereitstellen, muss aber entweder `get` oder `set` deklariert, aber nicht definiert haben (wie im obigen Beispiel).

Beispiel #4 Beispiel für eine abstrakte Eigenschaft mit Hooks

    <?php

    abstract class A
    {
        // Dies bietet eine vorgegebene (aber überschreibbare) set-Implementierung
        // und erfordert, dass Kindklassen eine get-Implementierung bereitstellen
        abstract public string $foo {
            get;

            set {
                $this->foo = $value;
            }
        }
    }

    ?>

## Objekt-Interfaces (Schnittstellen)

Objekt-Interfaces ermöglichen die Erzeugung von Code, der spezifiziert, welche Methoden und Eigenschaften eine Klasse implementieren muss, ohne definieren zu müssen, wie diese Methoden und Eigenschaften implementiert werden. Interfaces teilen sich einen Namensraum mit Klassen, Traits und Aufzählungen (Enums), daher dürfen sie nicht denselben Namen verwenden.

Interfaces werden auf dieselbe Weise wie eine Klasse definiert, aber mit dem Schlüsselwort `interface` anstatt des Schlüsselworts `class`, und ohne, dass eine der Methoden ihren Inhalt definiert.

Alle in einem Interface deklarierten Methoden müssen public sein; dies liegt in der Natur eines Interfaces.

In der Praxis erfüllen die Interfaces zwei sich ergänzende Zwecke:

- Um Entwicklern zu ermöglichen, Objekte verschiedener Klassen zu erstellen, die austauschbar verwendet werden können, weil sie das gleiche Interface oder die gleichen Interfaces implementieren. Ein häufiges Beispiel sind mehrere Dienste für den Datenbankzugriff, mehrere Zahlungs-Gateways oder unterschiedliche Caching-Strategien. Verschiedene Implementierungen können ausgetauscht werden, ohne dass Änderungen am Code vorgenommen werden müssen, der sie verwendet.
- Um einer Funktion oder Methode zu ermöglichen, einen Parameter zu akzeptieren und zu bearbeiten, der der mit einem Interface konform ist, ohne sich darum zu kümmern, was das Objekt sonst noch tun kann oder wie es implementiert ist. Diese Interfaces werden oft benannt als `Iterable`, `Cacheable`, `Renderable`, oder so weiter, um die Bedeutung des des Verhaltens zu beschreiben.

Interfaces können magische Methoden definieren, um implementierende Klassen zu zwingen, diese Methoden zu implementieren.

> Hinweis:

> Obwohl diese unterstützt werden, wird von der Aufnahme von Konstruktoren in Interfaces dringend abgeraten. Dadurch wird die Flexibilität der Objekte, die das Interface implementieren, drastisch eingeschränkt. Außerdem werden Konstruktoren nicht durch Vererbungsregeln erzwungen, was zu Inkonsistenzen und unerwartetem Verhalten führen kann.

### `implements`

Um ein Interface zu implementieren, wird der Operator `implements` benutzt. Alle Methoden des Interfaces müssen innerhalb der Klasse implementiert werden, andernfalls führt dies zu einem schwerwiegenden Fehler. Klassen dürfen, falls dies gewünscht wird, mehr als ein Interface implementieren, indem man die Interfaces mit einem Komma voneinander trennt.

Warnung

Eine Klasse, die ein Interface implementiert, kann für ihre Parameter einen anderen Namen verwenden als das Interface. Seit PHP 8.0 unterstützt die Sprache benannte Argumente, was bedeutet, dass sich der Aufrufende auf den Parameternamen im Interface verlassen kann. Aus diesem Grund wird dringend empfohlen, dass Entwickler die gleichen Parameternamen verwenden wie das zu implementierende Interface.

> Hinweis:

> Eine Schnittstelle kann ebenso wie eine Klasse mit Hilfe des Operators extends erweitert werden.

> Hinweis:

> Die Klasse, die die Schnittstelle implementiert, muss alle Methoden der Schnittstelle mit einer kompatiblen Signatur deklarieren. Eine Klasse kann mehrere Schnittstellen implementieren, die eine Methode mit demselben Namen deklarieren. In diesem Fall muss die Implementierung die Regeln für die Signaturkompatibilität für alle Schnittstellen befolgen. Auf diese Weise können Kovarianz und Kontravarianz angewendet werden.

### Konstanten

Eine Schnittstelle kann Konstanten definieren. Schnittstellen-Konstanten funktionieren genauso wie Klassenkonstanten. Vor PHP 8.1.0 können sie nicht von einer Klasse/Schnittstelle überschrieben werden, die sie erbt.

### Eigenschaften

Seit PHP 8.4.0 können Schnittstellen auch Eigenschaften deklarieren. In diesem Fall muss die Deklaration angeben, ob die Eigenschaft lesbar, schreibbar oder beides sein soll. Die Deklaration der Schnittstelle gilt nur für den öffentlichen Lese- und Schreibzugriff.

Eine Klasse kann eine Schnittstelleneigenschaft auf mehrere Arten erfüllen. Sie kann eine öffentliche Eigenschaft definieren. Sie kann eine öffentliche virtuelle Eigenschaft definieren, die nur den entsprechenden Hook implementiert. Oder eine lesbare Eigenschaft kann durch eine `readonly`-Eigenschaft erfüllt werden. Eine Schnittstelleneigenschaft, die gesetzt werden kann, kann jedoch nicht `readonly` sein.

Beispiel #1 Beispiel für Schnittstelleneigenschaften

    <?php
    interface I
    {
        // Eine implementierende Klasse MUSS eine öffentlich lesbare Eigenschaft
        // haben, wobei es keine Rolle spielt, ob sie öffentlich gesetzt werden kann.
        public string $readable { get; }

        // Eine implementierende Klasse MUSS eine öffentlich schreibbare Eigenschaft
        // haben, wobei es keine Rolle spielt, ob sie öffentlich lesbar ist oder nicht.
        public string $writeable { set; }

        // Eine implementierende Klasse MUSS eine Eigenschaft haben, die sowohl
        // öffentlich lesbar als auch öffentlich schreibbar ist.
        public string $both { get; set; }
    }

    // Diese Klasse implementiert alle drei Eigenschaften als konventionelle, nicht
    // eingehängte Eigenschaften. Dies ist absolut gültig.
    class C1 implements I
    {
        public string $readable;

        public string $writeable;

        public string $both;
    }

    // Diese Klasse implementiert alle drei Eigenschaften, indem sie nur die
    // angeforderten Hooks verwendet. Dies ist auch absolut gültig.
    class C2 implements I
    {
        private string $written = '';
        private string $all = '';

        // Verwendet nur einen get-Hook, um eine virtuelle Eigenschaft zu erstellen.
        // Damit wird die Anforderung "public get" erfüllt.
        // Sie ist nicht schreibbar, aber das ist für die Schnittstelle nicht
        // erforderlich.
        public string $readable { get => strtoupper($this->writeable); }

        // Die Schnittstelle verlangt nur, dass die Eigenschaft gesetzt werden
        // kann, aber auch get-Operationen sind absolut zulässig.
        // Dieses Beispiel erzeugt eine virtuelle Eigenschaft, was in Ordnung ist.
        public string $writeable {
            get => $this->written;
            set {
                $this->written = $value;
            }
        }

        // Diese Eigenschaft verlangt, dass sowohl Lesen als auch Schreiben
        // möglich ist, sodass entweder beides implementiert werden muss
        // oder das Standardverhalten beibehalten werden kann.
        public string $both {
            get => $this->all;
            set {
                $this->all = strtoupper($value);
            }
        }
    }
    ?>

### Beispiele

Beispiel #2 Interface-Beispiel

    <?php
    // Deklariere das Interface 'Template'
    interface Template
    {
        public function setVariable($name, $var);
        public function getHtml($template);
    }

    // Implementiere das Interface
    // Dies funktioniert
    class WorkingTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }

        public function getHtml($template)
        {
            foreach($this->vars as $name => $value) {
                $template = str_replace('{' . $name . '}', $value, $template);
            }

            return $template;
        }
    }

    // Dies wird nicht funktionieren
    // Fatal error: Class BadTemplate contains 1 abstract methods
    // and must therefore be declared abstract (Template::getHtml)
    class BadTemplate implements Template
    {
        private $vars = [];

        public function setVariable($name, $var)
        {
            $this->vars[$name] = $var;
        }
    }
    ?>

Beispiel #3 Erweiterbare Interfaces

    <?php
    interface A
    {
        public function foo();
    }

    interface B extends A
    {
        public function baz(Baz $baz);
    }

    // Dies Funktioniert
    class C implements B
    {
        public function foo()
        {
        }

        public function baz(Baz $baz)
        {
        }
    }

    // Dies funktioniert nicht und führt zu einem schwerwiegenden Fehler
    class D implements B
    {
        public function foo()
        {
        }

        public function baz(Foo $foo)
        {
        }
    }
    ?>

Beispiel #4 Varianzkompatibilität mit mehreren Schnittstellen

    <?php
    class Foo {}
    class Bar extends Foo {}

    interface A {
        public function myfunc(Foo $arg): Foo;
    }

    interface B {
        public function myfunc(Bar $arg): Bar;
    }

    class MyClass implements A, B
    {
        public function myfunc(Foo $arg): Bar
        {
            return new Bar();
        }
    }
    ?>

Beispiel #5 Interface-Mehrfachvererbung

    <?php
    interface A
    {
        public function foo();
    }

    interface B
    {
        public function bar();
    }

    interface C extends A, B
    {
        public function baz();
    }

    class D implements C
    {
        public function foo()
        {
        }

        public function bar()
        {
        }

        public function baz()
        {
        }
    }
    ?>

Beispiel #6 Interfaces mit Konstanten

    <?php
    interface A
    {
        const B = 'Interface-Konstante';
    }

    // Ausgabe: Interface-Konstante
    echo A::B;

    class B implements A
    {
        const B = 'Klassen-Konstante';
    }

    // Ausgabe: Klassen-Konstante
    // Vor PHP 8.1.0 funktioniert dies allerdings nicht, da es nicht erlaubt
    // war, Konstanten zu überschreiben.
    echo B::B;
    ?>

Beispiel #7 Interfaces mit abstrakten Klassen

    <?php
    interface A
    {
        public function foo(string $s): string;

        public function bar(int $i): int;
    }

    // Eine abstrakte Klasse muss ein Interface nicht komplett implementieren.
    // Klassen, die die abstrakte Klasse erweitern, müssen den Rest implementieren.
    abstract class B implements A
    {
        public function foo(string $s): string
        {
            return $s . PHP_EOL;
        }
    }

    class C extends B
    {
        public function bar(int $i): int
        {
            return $i * 2;
        }
    }
    ?>

Beispiel #8 Gleichzeitiges Erweitern und Implementieren

    <?php

    class One
    {
        /* ... */
    }

    interface Usable
    {
        /* ... */
    }

    interface Updatable
    {
        /* ... */
    }

    // Die Reihenfolge der Schlüsselwörter ist hier wichtig. 'extends' muss an
    // erster Stelle stehen.
    class Two extends One implements Usable, Updatable
    {
        /* ... */
    }
    ?>

Ein Interface bietet in Verbindung mit Typ-Deklarationen eine gute Möglichkeit, um sicherzustellen, dass ein bestimmtes Objekt bestimmte Methoden enthält. Siehe instanceof-Operator und Typdeklarationen.

## Traits

In PHP gibt es eine Methode der Wiederverwendung von Code, die Traits genannt wird.

Traits sind ein Mechanismus zur Wiederverwendung von Code, der in Programmiersprachen mit einfacher Vererbung wie PHP verwendet wird. Ein Trait kann verwendet werden, um den Beschränkungen der einfachen Vererbung auszuweichen, indem er erlaubt, dass Mengen von Methoden frei in mehreren unabhängigen Klassen, die in verschiedenen Klassenhierarchien stecken, wiederzuverwenden. Die Semantik der Kombination von Traits und Klassen ist so definiert, dass die Komplexität reduziert wird und die üblichen Probleme vermeidet, die mit Mehrfachvererbung und Mixins in Verbindung gebracht werden.

Ein Trait hat Ähnlichkeit mit einer Klasse, ist aber nur dafür vorgesehen, Funktionalität in einer feingranularen und konsistenten Art und Weise zu bündeln. Es ist nicht möglich einen Trait alleinstehend zu instantiieren. Es handelt sich um einen Zusatz zur traditionellen Vererbung und erlaubt horizontale Komposition von Verhaltensweisen, d. h. die Verwendung von Klassenmethoden ohne Vererbung vorauszusetzen.

Beispiel #1 Trait-Beispiel

    <?php

    trait TraitA {
        public function sayHello() {
            echo 'Hello';
        }
    }

    trait TraitB {
        public function sayWorld() {
            echo 'World';
        }
    }

    class MyHelloWorld
    {
        use TraitA, TraitB; // Eine Klasse kann mehrere Traits verwenden

        public function sayHelloWorld() {
            $this->sayHello();
            echo ' ';
            $this->sayWorld();
            echo "!\n";
        }
    }

    $myHelloWorld = new MyHelloWorld();
    $myHelloWorld->sayHelloWorld();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hello World!

### Rangfolge

Methoden der aktuellen Klasse überschreiben Methoden, welche von Traits definiert wurden. Jene wiederum überschreiben von Elternklassen geerbte Methoden.

Beispiel #2 Rangfolge-Beispiel

Die Methode `sayHello` der Basisklasse wird durch die gleichnamige Methode aus dem Trait überschrieben.

    <?php
    class Base {
        public function sayHello() {
            echo 'Hallo ';
        }
    }

    trait SayWorld {
        public function sayHello() {
            parent::sayHello();
            echo 'Welt!';
        }
    }

    class MyHelloWorld extends Base {
        use SayWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hallo Welt!

Beispiel #3 Weiteres Beispiel für Rangfolge

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hallo Welt!';
        }
    }

    class TheWorldIsNotEnough {
        use HelloWorld;
        public function sayHello() {
            echo 'Hallo Universum!';
        }
    }

    $o = new TheWorldIsNotEnough();
    $o->sayHello();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hallo Universum!

### Mehrere Traits

Mehrere Traits können durch eine kommaseparierte Auflistung im `use`-Statement zu einer Klasse hinzugefügt werden.

Beispiel #4 Verwendung mehrerer Traits

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hallo ';
        }
    }

    trait World {
        public function sayWorld() {
            echo ' Welt';
        }
    }

    class MyHelloWorld {
        use Hello, World;
        public function sayExclamationMark() {
            echo '!';
        }
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    $o->sayExclamationMark();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hallo Welt!

### Konfliktauflösung

Falls zwei Traits eine Methode mit gleichem Namen einfügen, so wird ein Fatal Error erzeugt, wenn der Konflikt nicht explizit aufgelöst wird.

Um einen Namenskonflikt zwischen Traits in der gleichen Klasse aufzulösen muss der `insteadof`-Operator verwendet werden, um genau eine der Methoden des Konflikts auszuwählen.

Da dies es nur erlaubt Methoden auszuschließen kann der `as`-Operator verwendet werden, um einen Alias zu einer der Methoden hinzuzufügen. Es ist zu beachten, dass der `as` Operator die Methode nicht umbenennt, und auch keine andere Methode beeinflusst.

Beispiel #5 Konfliktauflösung

In diesem Beispiel verwendet die Klasse Talker die Traits A und B. Nachdem A und B sich widersprechende Methoden besitzen definiert die Klasse, dass sie die Variante von smallTalk aus dem Trait B und die Variante von bigTalk des Traits A verwenden möchte.

Die Klasse Aliased_Talker verwendet den `as`-Operator, damit sie außerdem die Implementierung der bigTalk-Methode von B unter dem Alias `talk` verwenden kann.

    <?php
    trait A {
        public function smallTalk() {
            echo 'a';
        }
        public function bigTalk() {
            echo 'A';
        }
    }

    trait B {
        public function smallTalk() {
            echo 'b';
        }
        public function bigTalk() {
            echo 'B';
        }
    }

    class Talker {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
        }
    }

    class Aliased_Talker {
        use A, B {
            B::smallTalk insteadof A;
            A::bigTalk insteadof B;
            B::bigTalk as talk;
        }
    }
    ?>

### Veränderung der Sichtbarkeit von Methoden

Mit der `as`-Syntax ist es ebenso möglich, die Sichtbarkeit einer Methode in der darstellenden Klasse zu verändern.

Beispiel #6 Veränderung der Sichtbarkeit von Methoden

    <?php
    trait HelloWorld {
        public function sayHello() {
            echo 'Hallo Welt!';
        }
    }

    // Ändern der Sichtbarkeit von sayHello
    class MyClass1 {
        use HelloWorld { sayHello as protected; }
    }

    // Alias der Methode mit geänderter Sichtbarkeit
    // Die Sichtbarkeit von sayHello bleibt unverändert
    class MyClass2 {
        use HelloWorld { sayHello as private myPrivateHello; }
    }
    ?>

### Trait-Zusammensetzung aus Traits

Ebenso wie Klassen können auch Traits andere Traits verwenden. Indem man einen oder mehrere Traits in einer Traitdefinition verwendet kann man Traits entweder teilweise oder vollständig aus Methoden, welche in anderen Traits definiert sind, zusammensetzen.

Beispiel #7 Trait-Zusammensetzung aus Traits

    <?php
    trait Hello {
        public function sayHello() {
            echo 'Hallo ';
        }
    }

    trait World {
        public function sayWorld() {
            echo 'Welt!';
        }
    }

    trait HelloWorld {
        use Hello, World;
    }

    class MyHelloWorld {
        use HelloWorld;
    }

    $o = new MyHelloWorld();
    $o->sayHello();
    $o->sayWorld();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hallo Welt!

### Abstrakte Traitmember

Traits unterstützen auch die Verwendung von abstrakten Methoden, um darstellenden Klassen Anforderungen vorzugeben. Es werden öffentliche, geschützte und private Methoden unterstützt. Vor PHP 8.0.0 wurden nur öffentliche und geschützte abstrakte Methoden unterstützt.

Achtung

Seit PHP 8.0.0 muss die Signatur einer konkreten Methode den Regeln zur Signaturkompatibilität entsprechen; zuvor durfte ihre Signatur davon abweichen.

Beispiel #8 Ausdrücken von Anforderungen durch abstrakte Methoden

    <?php
    trait Hello {
        public function sayHelloWorld() {
           echo 'Hallo'.$this->getWorld();
        }
        abstract public function getWorld();
    }

    class MyHelloWorld {
        private $world;
        use Hello;
        public function getWorld() {
            return $this->world;
        }
        public function setWorld($val) {
            $this->world = $val;
        }
    }
    ?>

### Statische Traitmember

Traits unterstützen sowohl statische Variablen, statische Methoden und statische Eignschaften.

> Hinweis:

> Seit PHP 8.1.0 sind der Aufruf einer statischen Methode oder der Zugriff auf eine statische Eigenschaft direkt in einem Trait veraltet. Auf statische Methoden und Eigenschaften sollte nur in einer Klasse zugegriffen werden, die den Trait verwendet.

Beispiel #9 Statische Variablen

    <?php

    trait Counter
    {
        public function inc()
        {
            static $c = 0;
            $c = $c + 1;
            echo "$c\n";
        }
    }

    class C1
    {
        use Counter;
    }

    class C2
    {
        use Counter;
    }

    $o = new C1();
    $o->inc();
    $p = new C2();
    $p->inc();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1
    1

Beispiel #10 Statische Methoden

    <?php

    trait StaticExample
    {
        public static function doSomething()
        {
            return 'Tue etwas';
        }
    }

    class Example
    {
        use StaticExample;
    }

    echo Example::doSomething();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Doing something

Beispiel #11 Statische Eigenschaften

Achtung

Vor PHP 8.3.0 wurden statische Eigenschaften, die in einem Trait definiert waren, von allen Klassen in derselben Vererbungshierarchie, die diesen Trait verwendeten, gemeinsam genutzt. Seit PHP 8.3.0 wird eine statische Eigenschaft, die von einer Kindklasse über einen Trait verwendet wird, als von der in der Elternklasse definierte Eigenschaft unterschieden betrachtet.

    <?php

    trait T
    {
        public static $counter = 1;
    }

    class A
    {
        use T;

        public static function incrementCounter()
        {
            static::$counter++;
        }
    }

    class B extends A
    {
        use T;
    }

    A::incrementCounter();

    echo A::$counter, "\n";
    echo B::$counter, "\n";

    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.3 folgende Ausgabe:

    2
    1

### Eigenschaften

Traits können ebenfalls Eigenschaften definieren.

Beispiel #12 Eigenschaften definieren

    <?php

    trait PropertiesTrait
    {
        public $x = 1;
    }

    class PropertiesExample
    {
        use PropertiesTrait;
    }

    $example = new PropertiesExample();
    $example->x;

    ?>

Definiert ein Trait eine Eigenschaft, dann kann eine Klasse keine Eigenschaft mit dem selben Namen definieren, es sei denn, sie ist kompatibel (selbe Sichtbarkeit und Typ, readonly-Modifikator und Initialwert); andernfalls wird ein fataler Fehler auftreten.

Beispiel #13 Konfliktauflösung

    <?php
    trait PropertiesTrait {
        public $same = true;
        public $different1 = false;
        public bool $different2;
        public bool $different3;
    }

    class PropertiesExample {
        use PropertiesTrait;
        public $same = true;
        public $different1 = true; // Fatal error
        public string $different2; // Fatal error
        readonly protected bool $different3; // Fatal error
    }
    ?>

### Konstanten

Seit PHP 8.2.0 können Traits auch Konstanten definieren.

Beispiel #14 Definieren von Konstanten

    <?php
    trait ConstantsTrait {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample {
        use ConstantsTrait;
    }

    $example = new ConstantsExample;
    echo $example::FLAG_MUTABLE;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1

Wenn ein Trait eine Konstante definiert, kann eine Klasse keine Konstante mit demselben Namen definieren, es sei denn, sie ist kompatibel (dieselbe Sichtbarkeit, derselbe Initialwert und dieselbe Finalität), andernfalls wird ein fataler Fehler ausgegeben.

Beispiel #15 Konfliktauflösung

    <?php
    trait ConstantsTrait {
        public const FLAG_MUTABLE = 1;
        final public const FLAG_IMMUTABLE = 5;
    }

    class ConstantsExample {
        use ConstantsTrait;
        public const FLAG_IMMUTABLE = 5; // Fatal error
    }
    ?>

### Finale Methoden

Seit PHP 8.3.0 kann der Modifikator final mit dem Operator `as` auf Methoden angewendet werden, die aus Traits importiert wurden. Dies kann verwendet werden, um zu verhindern, dass Kindklassen die Methode überschreiben. Die Klasse, die den Trait verwendet, kann die Methode jedoch weiterhin überschreiben.

Beispiel #16 Definieren einer Methode aus einem Trait als `final`

    <?php

    trait CommonTrait
    {
        public function method()
        {
            echo 'Hello';
        }
    }

    class FinalExampleA
    {
        use CommonTrait {
            CommonTrait::method as final; // Das "final" verhindert, dass Kindklassen
                                          // die Methode überschreiben.
        }
    }

    class FinalExampleB extends FinalExampleA
    {
        public function method() {}
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Fatal error: Cannot override final method FinalExampleA::method() in ...

## Anonyme Klassen

Anonyme Klassen sind nützlich, wenn einfache Objekte zum einmaligen Gebrauch erzeugt werden müssen.

    <?php

    // Verwendung einer expliziten Klasse
    class Logger
    {
        public function log($msg)
        {
            echo $msg;
        }
    }

    $util->setLogger(new Logger());

    // Verwendung einer anonymen Klasse
    $util->setLogger(new class {
        public function log($msg)
        {
            echo $msg;
        }
    });

Anonyme Klassen können Argumente über ihren Konstruktor empfangen, andere Klassen erweitern, Interfaces implementieren und Traits genau wie eine normale Klasse verwenden:

    <?php

    class SomeClass {}
    interface SomeInterface {}
    trait SomeTrait {}

    var_dump(new class(10) extends SomeClass implements SomeInterface {
        private $num;

        public function __construct($num)
        {
            $this->num = $num;
        }

        use SomeTrait;
    });

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(class@anonymous)#1 (1) {
      ["Command line code0x104c5b612":"class@anonymous":private]=>
      int(10)
    }

Das Verschachteln einer anonymen Klasse innerhalb einer anderen Klasse gibt ihr keinen Zugriff auf private oder geschützte Methoden oder Eigenschaften der äußeren Klasse. Um die geschützten Methoden oder Eigenschaften der äußeren Klasse zu verwenden, kann die anonyme Klasse die äußere Klasse erweitern. Um private Eigenschaften der äußeren Klasse in der anonymen Klasse zu verwenden, müssen sie dem Konstruktor übergeben werden:

    <?php

    class Outer
    {
        private $prop = 1;
        protected $prop2 = 2;

        protected function func1()
        {
            return 3;
        }

        public function func2()
        {
            return new class($this->prop) extends Outer {
                private $prop3;

                public function __construct($prop)
                {
                    $this->prop3 = $prop;
                }

                public function func3()
                {
                    return $this->prop2 + $this->prop3 + $this->func1();
                }
            };
        }
    }

    echo (new Outer)->func2()->func3();

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    6

Alle Objekte, die durch dieselbe anonyme Klassendeklaration erzeugt werden, sind Instanzen von genau dieser Klasse.

    <?php
    function anonymous_class()
    {
        return new class {};
    }

    if (get_class(anonymous_class()) === get_class(anonymous_class())) {
        echo 'dieselbe Klasse';
    } else {
        echo 'eine andere Klasse';
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    dieselbe Klasse

> Hinweis:

> Es ist zu beachten, dass anonymen Klassen von der Engine ein Name zugewiesen wird, wie im folgenden Beispiel gezeigt. Dieser Name muss als Implementierungsdetail eingestuft werden, auf dass sich nicht verlassen werden sollte.

>     <?php
>     echo get_class(new class {});

> Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

>     class@anonymous/in/oNi1A0x7f8636ad2021

### Anonyme Klassen, die nur lesbar sind

Seit PHP 8.3.0 kann der Modifikator `readonly` auf anonyme Klassen angewendet werden.

Beispiel #1 Definieren einer anonymen Klasse, die nur gelesen werden kann

    <?php

    // Verwenden einer anonymen Klasse
    var_dump(new readonly class('[DEBUG]') {
        public function __construct(private string $prefix)
        {
        }

        public function log($msg)
        {
            echo $this->prefix . ' ' . $msg;
        }
    });

## Überladung

Überladung bietet in PHP Möglichkeiten, um dynamisch Eigenschaften und Methoden zu erzeugen. Diese dynamisch erzeugten Entitäten werden unter Zuhilfenahme von magischen Methoden verarbeitet, die man in einer Klasse zu verschiedenen Aktivitäten definieren kann.

Die Überladungsmethoden werden aufgerufen, wenn mit Eigenschaften oder Methoden interagiert wird, die entweder nicht deklariert wurden oder im aktuellen Geltungsbereich nicht sichtbar sind. Im Rest dieses Abschnitts werden die Begriffe unzugreifbare Eigenschaft und unzugreifbare Methode verwendet, um auf die Kombination von Deklaration und Sichtbarkeit zu verweisen.

Alle Überladungsmethoden müssen als `public` definiert sein.

> Hinweis:

> Keiner der Parameter dieser magischen Methoden kann als Referenz übergeben werden.

> Hinweis:

> Die Interpretation von Überladung weicht von den meisten objektorientierten Programmiersprachen ab. Traditionell bezeichnet Überladung die Möglichkeit mehrere Methoden mit gleichem Namen aber unterschiedlichen Anzahlen und Typen von Parametern zu definieren.

### Überladung von Eigenschaften

public function __set(string `$name`, mixed `$value`): void
public function __get(string `$name`): mixed
public function __isset(string `$name`): bool
public function __unset(string `$name`): void

__set wird aufgerufen, wenn Daten in unzugreifbare (protected oder private) Eigenschaften geschrieben werden sollen.

__get wird verwendet, um Daten aus unzugreifbaren (protected oder private) Eigenschaften zu lesen.

__isset wird aufgerufen, indem isset() oder empty() auf unzugreifbare (protected oder private) Eigenschaften angewendet wird.

__unset wird aufgerufen, wenn unset() für unzugreifbaren (protected oder private) Eigenschaften aufgerufen wird.

Der Parameter $name beinhaltet den Namen der Eigenschaft, mit der interagiert wird. Der Parameter $value der Funktion __set spezifiziert den Wert den die Eigenschaft $name annehmen soll.

Überladung von Eigenschaften funktioniert nur im Kontext von Objekten. Diese magischen Methoden werden nicht aus einem statischen Kontext aufgerufen. Diese Methoden sollten daher nicht als static deklariert werden. Eine Warnung wird ausgegeben, wenn eine dieser magischen Überladungsmethoden als `static` deklariert ist.

> Hinweis:

> Der Rückgabewert von __set wird, aufgrund der Behandlung des Zuweisungsoperators in PHP, ignoriert. Aus ähnlichen Gründen wird __get nicht aufgerufen, wenn man Zuweisungen in etwa wie folgt verkettet: ``

>      $a = $obj->b = 8;

> Hinweis:

> PHP ruft niemals eine überladene Methode von derselben überladenen Methode aus auf. Das bedeutet zum Beispiel, dass `return $this->foo` innerhalb von __get() `null` zurückgibt und ein `E_WARNING` auslöst, wenn die Eigenschaft `foo` nicht definiert ist, anstatt __get() ein zweites Mal aufzurufen. Es ist jedoch möglich, dass eine überladene Methode implizit eine andere überladene Methode aufruft (z. B. löst __set() den Aufruf von __get() aus).

Beispiel #1 Überladung von Eigenschaften mit den Methoden __get, __set, __isset und __unset

    <?php
    class EigenschaftTest
    {
        /**  Speicherplatz für überladene Daten.  */
        private $data = array();

        /**  Überladung wird nicht bei deklarierten Eigenschaften benutzt.  */
        public $declared = 1;

        /**  Überladung wird nur von außerhalb der Klasse angewendet.  */
        private $hidden = 2;

        public function __set($name, $value)
        {
            echo "Setze '$name' auf '$value'\n";
            $this->data[$name] = $value;
        }

        public function __get($name)
        {
            echo "Lese '$name'\n";
            if (array_key_exists($name, $this->data)) {
                return $this->data[$name];
            }

            $trace = debug_backtrace();
            trigger_error(
                'Undefinierte Eigenschaft für __get(): ' . $name .
                ' in ' . $trace[0]['file'] .
                ' Zeile ' . $trace[0]['line'],
                E_USER_NOTICE);
            return null;
        }

        public function __isset($name)
        {
            echo "Ist '$name' gesetzt?\n";
            return isset($this->data[$name]);
        }

        public function __unset($name)
        {
            echo "Lösche '$name'\n";
            unset($this->data[$name]);
        }

        /**  Keine magische Methode, nur beispielhaft hier.  */
        public function getHidden()
        {
            return $this->hidden;
        }
    }

    $obj = new EigenschaftTest;

    $obj->a = 1;
    echo $obj->a . "\n\n";

    var_dump(isset($obj->a));
    unset($obj->a);
    var_dump(isset($obj->a));
    echo "\n";

    echo $obj->declared . "\n\n";

    echo "Wir experimentieren nun mit der private-Eigenschaft 'hidden':\n";
    echo "Private ist innerhalb der Klasse sichtbar, also wird __get() nicht benutzt...\n";
    echo $obj->getHidden() . "\n";
    echo "Private nicht sichtbar von außerhalb der Klasse, also wird __get() benutzt...\n";
    echo $obj->hidden . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Setze 'a' auf '1'
    Lese 'a'
    1

    Ist 'a' gesetzt?
    bool(true)
    Lösche 'a'
    Ist 'a' gesetzt?
    bool(false)

    1

    Wir experimentieren nun mit der private-Eigenschaft 'hidden':
    Private ist innerhalb der Klasse sichtbar, also wird __get() nicht benutzt...
    2
    Private nicht sichtbar von außerhalb der Klasse, also wird __get() benutzt...
    Lese 'hidden'

    Notice:  Undefinierte Eigenschaft für __get(): hidden in <file> Zeile 70 in <file> on line 29

### Überladung von Methoden

public function __call(string `$name`, array `$arguments`): mixed
public static function __callStatic(string `$name`, array `$arguments`): mixed

__call wird aufgerufen, wenn eine unzugreifbare Methode in einem Objekt aufgerufen wird.

__callStatic wird aufgerufen, wenn eine unzugreifbare Methode in einem statischen Kontext aufgerufen wird.

Der Parameter $name ist der Name der aufgerufenen Methode. Der Parameter $arguments beinhaltet ein Array mit den Parametern, die der Methode $name übergeben wurden.

Beispiel #2 Überladung von Methoden mit den methoden __call und __callStatic

    <?php
    class MethodenTest {
        public function __call($name, $arguments)
        {
            // Achtung: Der Wert von $name beachtet die Groß-/Kleinschreibung
            echo "Rufe die Objektmethode '$name' "
                 . implode(', ', $arguments). "\n";
        }

        public static function __callStatic($name, $arguments)
        {
            // Achtung: Der Wert von $name beachtet die Groß-/Kleinschreibung
            echo "Rufe die statische Methode '$name' "
                 . implode(', ', $arguments). "\n";
        }
    }

    $obj = new MethodenTest;
    $obj->runTest('eines Objektes auf');

    MethodenTest::runTest('aus statischem Kontext auf');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Rufe die Objektmethode 'runTest' eines Objektes auf
    Rufe die statische Methode 'runTest' aus statischem Kontext auf

## Objektiteration

PHP bietet eine Möglichkeit Objekte so zu definieren, dass es möglich ist eine Liste von Elementen zu durchlaufen, z.B. mit einem `foreach`-Statement. Standardmäßig werden alle sichtbaren Eigenschaften für die Iteration benutzt.

Beispiel #1 Einfache Objektiteration

    <?php
    class MyClass
    {
        public $var1 = 'Wert 1';
        public $var2 = 'Wert 2';
        public $var3 = 'Wert 3';

        protected $protected = 'protected var';
        private   $private   = 'private var';

        function iterateVisible() {
           echo "MyClass::iterateVisible:\n";
           foreach ($this as $key => $value) {
               print "$key => $value\n";
           }
        }
    }

    $class = new MyClass();

    foreach($class as $key => $value) {
        print "$key => $value\n";
    }
    echo "\n";

    $class->iterateVisible();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    var1 => Wert 1
    var2 => Wert 2
    var3 => Wert 3

    MyClass::iterateVisible:
    var1 => Wert 1
    var2 => Wert 2
    var3 => Wert 3
    protected => protected var
    private => private var

Wie die Ausgabe zeigt, durchläuft das `foreach` alle sichtbaren Eigenschaften, auf die zugegriffen werden kann.

### Siehe auch

- Generatoren
- Iterator
- IteratorAggregate
- Iteratoren

## Magische Methoden

Magische Methoden sind Methoden, die PHPs Standardverhalten überschreiben, wenn bestimmte Aktionen mit einem Objekt durchgeführt werden.

Achtung

Alle Methodennamen, die mit `__` beginnen, sind durch PHP reserviert. Es wird daher nicht empfohlen solche Methodennamen zu verwenden, außer wenn das Verhalten von PHP überschrieben werden soll.

Die folgenden Methodennamen werden als magisch betrachtet: __construct(), __destruct(), __call(), __callStatic(), __get(), __set(), __isset(), __unset(), __serialize(), __unserialize(), __sleep(), __wakeup(), __toString(), __invoke(), __set_state(), __clone() und __debugInfo().

Warnung

Mit Ausnahme von __construct(), __destruct() und __clone() müssen alle magischen Methoden als `public` deklariert werden, andernfalls wird eine `E_WARNING` ausgegeben. Vor PHP 8.0.0 wurde für die magischen Methoden __sleep(), __wakeup(), __serialize(), __unserialize() und __set_state() keine Diagnose ausgegeben.

Warnung

Falls Typdeklarationen in der Definition der magischen Methoden angegeben werden, müssen diese identisch zu den Signaturen sein, die in diesem Dokument beschrieben werden, andernfalls wird ein fataler Fehler hervorgerufen. Vor PHP 8.0.0 wurde keine Diagnose ausgegeben. Allerdings dürfen __construct() und __destruct() keinen Rückgabetyp deklarieren, sonst wird ein fataler Fehler ausgegeben.

### __serialize() und __unserialize()

public function __serialize(): array
public function __unserialize(array `$data`): void

serialize() prüft, ob die Klasse eine Funktion mit dem magischen Namen __serialize() besitzt. Wenn dem so ist, wird die Funktion vor jeder Serialisierung ausgeführt. Sie muss ein assoziatives Array von Schlüssel/Wert-Paaren erzeugen und zurückgeben, die die serialisierte Form des Objekts darstellen. Wird kein Array zurückgegeben, wird ein TypeError geworfen.

> Hinweis:

> Sind sowohl __serialize() als auch __sleep() im selben Objekt definiert, wird nur __serialize() aufgerufen. __sleep() wird ignoriert. Implementiert das Objekt das Serializable-Interface, wird die `serialize()`-Methode des Interfaces ignoriert und stattdessen __serialize() verwendet.

Der Zweck von __serialize() ist, eine für die Serialisierung geeignete beliebige Darstellung eines Objekts zu definieren. Die Elemente des Arrays können den Eigenschaften des Objekts entsprechen, aber das ist nicht erforderlich.

Umgekehrt überprüft unserialize(), ob eine Funktion mit dem magischen Namen __unserialize() vorhanden ist. Falls vorhanden, wird dieser Funktion das wiederhergestellte Array übergeben, das von __serialize() zurückgegeben wurde. Sie kann dann gegebenenfalls die Eigenschaften des Objekts aus diesem Array wiederherstellen.

> Hinweis:

> Sind sowohl __unserialize() als auch __wakeup() im selben Objekt definiert, wird nur __unserialize() aufgerufen. __wakeup() wird ignoriert.

> Hinweis:

> Dieses Feature ist seit PHP 7.4.0 verfügbar.

Beispiel #1 Serialize und unserialize

    <?php
    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __serialize(): array
        {
            return [
              'dsn' => $this->dsn,
              'user' => $this->username,
              'pass' => $this->password,
            ];
        }

        public function __unserialize(array $data): void
        {
            $this->dsn = $data['dsn'];
            $this->username = $data['user'];
            $this->password = $data['pass'];

            $this->connect();
        }
    }?>

### __sleep() und __wakeup()

Warnung

Dieser Serialisierungsmechanismus gilt seit PHP 8.5.0 als veraltet (soft-deprecated). Er wird aus Gründen der Abwärtskompatibilität beibehalten. Neuer und bestehender Code sollte jedoch stattdessen auf die magischen Methoden __serialize() und __unserialize() umgestellt werden.

public function __sleep(): array
public function __wakeup(): void

serialize() prüft, ob die Klasse eine Funktion mit dem magischen Namen __sleep() besitzt. Wenn dem so ist, wird die Funktion vor jeder Serialisierung ausgeführt. Sie kann das Objekt aufräumen und es wird von ihr erwartet, dass sie ein Array mit den Namen aller Variablen zurückgibt, die serialisiert werden sollen. Wenn die Methode nichts zurückgibt, wird `null` serialisiert und eine `E_NOTICE` ausgegeben.

> Hinweis:

> __sleep() kann keine Namen von privaten Eigenschaften in Elternklassen zurückgeben. Dies würde zu einem Fehler der Stufe `E_NOTICE` führen. Stattdessen sollte __serialize() verwendet werden.

> Hinweis:

> Seit PHP 8.0.0 erzeugt die Rückgabe eines Wertes von __sleep(), der kein Array ist, eine Warnung; vorher führte dies zu einem Hinweis.

Der Zweck von __sleep() ist, nicht gespeicherte Daten zu sichern oder ähnliche Aufräumarbeiten zu erledigen. Die Funktion ist ebenfalls nützlich, wenn ein sehr großes Objekt nicht komplett gespeichert werden muss.

Umgekehrt überprüft unserialize(), ob eine Funktion mit dem magischen Namen __wakeup() vorhanden ist. Falls vorhanden, kann diese Funktion alle Ressourcen, die das Objekt möglicherweise hat, wiederherstellen.

Der Zweck von __wakeup() ist es, alle Datenbankverbindungen, die bei der Serialisierung verlorengegangen sind, wiederherzustellen und andere Aufgaben der erneuten Initialisierung durchzuführen.

Beispiel #2 Sleep- und Wakeup-Beispiel

    <?php
    class Connection
    {
        protected $link;
        private $dsn, $username, $password;

        public function __construct($dsn, $username, $password)
        {
            $this->dsn = $dsn;
            $this->username = $username;
            $this->password = $password;
            $this->connect();
        }

        private function connect()
        {
            $this->link = new PDO($this->dsn, $this->username, $this->password);
        }

        public function __sleep()
        {
            return array('dsn', 'username', 'password');
        }

        public function __wakeup()
        {
            $this->connect();
        }
    }?>

### __toString()

public function __toString(): string

Mit der Methode __toString() kann eine Klasse entscheiden, wie sie reagieren soll, wenn sie wie eine Zeichenkette behandelt wird. Die beeinflusst beispielsweise, was `echo $obj;` ausgeben wird.

Warnung

Seit PHP 8.0.0 unterliegt der Rückgabewert dieser Methode der üblichen PHP-Semantik für Typen. Das heißt, er bei deaktivierter strikter Typisierung nach Möglichkeit in einen String umgewandelt.

Wenn die Strikte Typisierung aktiviert ist, wird ein Stringable-Objekt von einer string-Typdeklaration nicht akzeptiert. Wenn ein solches Verhalten erwünscht ist, muss die Typdeklaration Stringable und string mittels Union-Typ akzeptieren.

Seit PHP 8.0.0 implementiert jede Klasse, die eine __toString()-Methode enthält, implizit auch das Interface Stringable und erfüllt daher auch Typprüfungen auf dieses Interface. Es wird dennoch empfohlen, dieses Interface explizit zu implementieren.

In PHP 7.4 muss der Rückgabewert ein Wert vom Typ string sein, andernfalls wird ein Error geworfen.

Vor PHP 7.4.0 muss der Rückgabewert ein Wert vom Typ string sein, ansonsten wird ein Fehler der Stufe `E_RECOVERABLE_ERROR` hervorgerufen.

Warnung

Es war vor PHP 7.4.0 nicht möglich eine Exception aus einer __toString()-Methode zu werfen. Dies resultierte in einem fatalen Fehler.

Beispiel #3 Einfaches Beispiel

    <?php
    // Deklariere eine einfache Klasse
    class TestClass
    {
        public $foo;

        public function __construct($foo)
        {
            $this->foo = $foo;
        }

        public function __toString()
        {
            return $this->foo;
        }
    }

    $class = new TestClass('Hallo');
    echo $class;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hallo

### __invoke()

function __invoke( `...$values`): mixed

Die Methode __invoke() wird aufgerufen, wenn ein Skript versucht, ein Objekt als Funktion aufzurufen.

Beispiel #4 Nutzung von __invoke()

    <?php
    class CallableClass
    {
        public function __invoke($x)
        {
            var_dump($x);
        }
    }
    $obj = new CallableClass;
    $obj(5);
    var_dump(is_callable($obj));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(5)
    bool(true)

Beispiel #5 Nutzung von __invoke()

    <?php
    class Sort
    {
        private $key;

        public function __construct(string $key)
        {
            $this->key = $key;
        }

        public function __invoke(array $a, array $b): int
        {
            return $a[$this->key] <=> $b[$this->key];
        }
    }

    $customers = [
        ['id' => 1, 'first_name' => 'John', 'last_name' => 'Do'],
        ['id' => 3, 'first_name' => 'Alice', 'last_name' => 'Gustav'],
        ['id' => 2, 'first_name' => 'Bob', 'last_name' => 'Filipe']
    ];

    // Kunden nach Vornamen sortieren
    usort($customers, new Sort('first_name'));
    print_r($customers);

    // Kunden nach Nachnamen sortieren
    usort($customers, new Sort('last_name'));
    print_r($customers);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

    )
    Array
    (
        [0] => Array
            (
                [id] => 1
                [first_name] => John
                [last_name] => Do
            )

        [1] => Array
            (
                [id] => 2
                [first_name] => Bob
                [last_name] => Filipe
            )

        [2] => Array
            (
                [id] => 3
                [first_name] => Alice
                [last_name] => Gustav
            )

    )

### __set_state()

static function __set_state(array `$properties`): object

Diese statische Methode wird für Klassen aufgerufen, die mittels var_export() exportiert werden.

Der einzige Parameter dieser Methode ist ein Array, welches aus exportierten Eigenschaften der Form `['Eigenschaft' => Wert, ...]` besteht.

Beispiel #6 Verwendung von __set_state()

    <?php

    class A
    {
        public $var1;
        public $var2;

        public static function __set_state($an_array)
        {
            $obj = new A;
            $obj->var1 = $an_array['var1'];
            $obj->var2 = $an_array['var2'];
            return $obj;
        }
    }

    $a = new A;
    $a->var1 = 5;
    $a->var2 = 'foo';

    $b = var_export($a, true);
    var_dump($b);
    eval('$c = ' . $b . ';');
    var_dump($c);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(60) "A::__set_state(array(
       'var1' => 5,
       'var2' => 'foo',
    ))"
    object(A)#2 (2) {
      ["var1"]=>
      int(5)
      ["var2"]=>
      string(3) "foo"
    }

> Hinweis: Wenn ein Objekt exportiert wird, überprüft var_export() nicht, ob __set_state() von der Objektklasse implementiert wird, sodass der erneute Import von Objekten zu einer Error-Exception führt, falls __set_state() nicht implementiert ist. Die betrifft insbesondere einige interne Klassen. Es liegt im Aufgabenbereich des Programmiers, sicherzustellen, dass nur Objekte wieder re-importiert werden, welche auch __set_state() implementieren.

### __debugInfo()

function __debugInfo(): array

Diese Methode wird von var_dump() aufgerufen, wenn ein Objekt ausgegeben wird, um die Eigenschaften auszulesen die gezeigt werden sollen. Wenn diese Methode in einem Objekt nicht definiert ist, so werden alle Eigenschaften angezeigt, die public, protected oder private sind.

Beispiel #7 Verwendung von __debugInfo()

    <?php
    class C {
        private $prop;

        public function __construct($val) {
            $this->prop = $val;
        }

        public function __debugInfo() {
            return [
                'propSquared' => $this->prop ** 2,
            ];
        }
    }

    var_dump(new C(42));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(C)#1 (1) {
      ["propSquared"]=>
      int(1764)
    }

## Final-Schlüsselwort

Das Schlüsselwort final hält Kindklassen davon ab, Methoden, Eigenschaften oder Konstanten zu überschreiben, indem man der Definition `final` voranstellt. Wenn die Klasse selbst als final definiert wird, kann sie nicht erweitert werden.

Beispiel #1 Beispiel für finale Methoden

    <?php
    class BaseClass {
       public function test() {
           echo "BaseClass::test() aufgerufen\n";
       }

       final public function moreTesting() {
           echo "BaseClass::moreTesting() aufgerufen\n";
       }
    }

    class ChildClass extends BaseClass {
       public function moreTesting() {
           echo "ChildClass::moreTesting() aufgerufen\n";
       }
    }
    // Erzeugt einen fatalen Fehler: Cannot override final method BaseClass::moreTesting()
    ?>

Beispiel #2 Beispiel für finale Klassen

    <?php
    final class BaseClass {
       public function test() {
           echo "BaseClass::test() aufgerufen\n";
       }

       // Da die Klasse bereits final ist, ist das Schlüsselwort final redundant
       final public function moreTesting() {
           echo "BaseClass::moreTesting() aufgerufen\n";
       }
    }

    class ChildClass extends BaseClass {
    }
    // Erzeugt einen fatalen Fehler: Class ChildClass may not inherit from final class (BaseClass)
    ?>

Beispiel #3 Beispiel für finale Eigenschaften (seit PHP 8.4.0)

    <?php
    class BaseClass {
       final protected string $test;
    }

    class ChildClass extends BaseClass {
        public string $test;
    }
    // Erzeugt einen fatalen Fehler: Cannot override final property BaseClass::$test
    ?>

Beispiel #4 Beispiel für finale Konstanten (seit PHP 8.1.0)

    <?php
    class Foo
    {
        final public const X = "foo";
    }

    class Bar extends Foo
    {
        public const X = "bar";
    }

    // Fatal error: Bar::X cannot override final constant Foo::X
    ?>

> Hinweis: Seit PHP 8.0.0 dürfen private Methoden nicht mehr als final deklariert werden. Ausgenommen davon ist der Konstruktor.

> Hinweis: Eine als `private(set)` deklarierte Eigenschaft ist implizit `final`.

## Objekte klonen

Eine Kopie eines Objektes mit vollständig replizierten Eigenschaften zu erzeugen, ist nicht immer das gewünschte Verhalten. Ein gutes Beispiel für die Notwendigkeit von Kopierkonstruktoren ist ein Objekt, welches ein GTK Fenster repräsentiert und dieses Objekt enthält die Ressource des GTK-Fensters. Wenn Sie ein Duplikat dieses Objektes erzeugen, könnten Sie ein neues Fenster mit gleichen Eigenschaften erzeugen wollen und das neue Objekt soll die Ressource des neuen Fensters speichern. Ein weiteres Beispiel ist ein Objekt, welches eine Referenz auf ein anderes Objekt, das es benutzt, hält und wenn das Vaterobjekt repliziert wird, will man eine neue Instanz dieses anderen Objektes erzeugen, damit das Replikat eine eigene Kopie besitzt.

Eine Objektkopie wird durch die Nutzung des clone Schlüsselwortes (welches wenn möglich die __clone()-Methode des Objektes aufruft) erzeugt.

    $kopie_des_objektes = clone $objekt;

Wenn ein Objekt geklont wird, wird PHP eine seichte Kopie der Eigenschaften des Objektes durchführen. Alle Eigenschaften, die Referenzen auf andere Variablen sind, werden Referenzen bleiben.

function __clone(): void

Sobald der Klonvorgang abgeschlossen und eine __clone()- Methode definiert ist, so wird die __clone()-Methode des neu erzeugten Objekts aufgerufen, damit alle notwendigen Eigenschaften verändert werden können.

Beispiel #1 Ein Objekt klonen

    <?php
    class SubObject
    {
        static $instanzen = 0;
        public $instanz;

        public function __construct() {
            $this->instanz = ++self::$instanzen;
        }

        public function __clone() {
            $this->instanz = ++self::$instanzen;
        }
    }

    class MyCloneable
    {
        public $objekt1;
        public $objekt2;

        function __clone()
        {
            // Erzwinge eine Kopie von this->object,
            // andernfalls wird es auf das selbe Objekt zeigen
            $this->objekt1 = clone $this->objekt1;
        }
    }

    $obj = new MyCloneable();

    $obj->objekt1 = new SubObject();
    $obj->objekt2 = new SubObject();

    $obj2 = clone $obj;

    print "Original Objekt:\n";
    print_r($obj);

    print "geklontes Objekt:\n";
    print_r($obj2);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Original Objekt:
    MyCloneable Object
    (
        [object1] => SubObject Object
            (
                [instanz] => 1
            )

        [object2] => SubObject Object
            (
                [instanz] => 2
            )

    )
    geklontes Object:
    MyCloneable Object
    (
        [objekt1] => SubObject Object
            (
                [instanz] => 3
            )

        [objekt2] => SubObject Object
            (
                [instanz] => 2
            )

    )

Es ist möglich, auf die Klassenelemente eines soeben geklonten Objekts in einem einzigen Ausdruck zuzugreifen:

Beispiel #2 Zugriff auf ein Element eines soeben geklonten Objekts

    <?php
    $dateTime = new DateTime();
    echo (clone $dateTime)->format('Y');
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2016

## Objekte vergleichen

Wenn man den Vergleichsoperator (`==`) benutzt, werden Objektvariablen auf einfache Weise verglichen, d.h.: Zwei Objektinstanzen sind gleich, wenn sie die gleichen Attribute mit dem selben Wert (verglichen mit `==`) haben und Instanzen der selben Klasse sind.

Wenn man den Identitätsoperator benutzt (`===`), sind zwei Objekte identisch, genau dann, wenn sie die selbe Instanz der selben Klasse referenzieren.

Ein Beispiel wird diese Regeln verdeutlichen.

Beispiel #1 Beispiel für Objektvergleiche

    <?php
    function bool2str($bool)
    {
        if ($bool === false) {
            return 'FALSE';
        } else {
            return 'TRUE';
        }
    }

    function compareObjects(&$o1, &$o2)
    {
        echo 'o1 == o2 : ' . bool2str($o1 == $o2) . "\n";
        echo 'o1 != o2 : ' . bool2str($o1 != $o2) . "\n";
        echo 'o1 === o2 : ' . bool2str($o1 === $o2) . "\n";
        echo 'o1 !== o2 : ' . bool2str($o1 !== $o2) . "\n";
    }

    class Flag
    {
        public $flag;

        function __construct($flag = true) {
            $this->flag = $flag;
        }
    }

    class OtherFlag
    {
        public $flag;

        function __construct($flag = true) {
            $this->flag = $flag;
        }
    }

    $o = new Flag();
    $p = new Flag();
    $q = $o;
    $r = new OtherFlag();

    echo "Zwei Instanzen der selben Klasse\n";
    compareObjects($o, $p);

    echo "\nZwei Referenzen auf die selbe Instanz\n";
    compareObjects($o, $q);

    echo "\nInstanzen zweier verschiedener Klassen\n";
    compareObjects($o, $r);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Zwei Instanzen der selben Klasse
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

    Zwei Referenzen auf die selbe Instanz
    o1 == o2 : TRUE
    o1 != o2 : FALSE
    o1 === o2 : TRUE
    o1 !== o2 : FALSE

    Instanzen zweier verschiedener Klassen
    o1 == o2 : FALSE
    o1 != o2 : TRUE
    o1 === o2 : FALSE
    o1 !== o2 : TRUE

> Hinweis:

> Erweiterungen können eigene Regeln für ihre Objektvergleiche (`==`) definieren.

## Späte statische Bindung

PHP unterstützt späte statische Bindung ("Late static binding"). Hiermit kann die aufgerufene Klasse im Kontext statischer Vererbung referenziert werden.

Genauer gesagt funktioniert späte statische Bindung durch das Speichern der Klasse, die im letzten "nicht weiterleitenden Aufruf" angegeben wurde. Im Fall von statischen Methodenaufrufen ist dies die explizit angegebene Klasse (üblicherweise diejenige auf der linken Seite des Operators `::`); im Fall von nicht statischen Methodenaufrufen ist es die Klasse des Objekts. Ein "weiterleitender Aufruf" ist ein statischer, der durch `self::`, `parent::`, `static::` oder, in der Klassenhierarchie nach oben gehend, durch forward_static_call() eingeleitet wurde. Die Funktion get_called_class() kann benutzt werden, um eine Zeichenkette mit dem Namen der aufgerufenen Klasse abzufragen, und `static::` führt ihren Geltungsbereich ein.

Diese Funktionalität wurde in Hinblick auf die interne Perspektive als "späte statische Bindung" benannt. "Späte Bindung" bezieht sich auf die Tatsache, dass `static::` nicht über die Klasse, in der die aufgerufene Methode definiert ist, aufgelöst wird, stattdessen wird diese mit Hilfe von Laufzeitinformationen bestimmt. Die Benennung als "statische Bindung" beruht darauf, dass dieser Mechanismus unter anderem für statische Methodenaufrufe genutzt werden kann.

### Beschränkungen von `self::`

Statische Referenzen auf die aktuelle Klasse wie `self::` oder `__CLASS__` werden mit Hilfe der Klasse, zu der die Methode gehört, also in welcher sie definiert ist, aufgelöst.

Beispiel #1 Nutzung von `self::`

    <?php

    class A
    {
        public static function who()
        {
            echo __CLASS__;
        }

        public static function test()
        {
            self::who();
        }
    }

    class B extends A
    {
        public static function who()
        {
            echo __CLASS__;
        }
    }

    B::test();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    A

### Nutzung später statischer Bindung

Späte statische Bindung versucht diese Beschränkung zu umgehen, indem ein neues Schlüsselwort eingeführt wird, das die Klasse referenziert, die tatsächlich zur Laufzeit genutzt wurde. Im Grunde genommen also ein Schlüsselwort, das es im vorherigen Beispiel ermöglicht die Klasse `B` aus der aufgerufenen Methode `test()` zu referenzieren. Es wurde entschieden, kein neues Schlüsselwort einzuführen, sondern statt dessen `static` zu verwenden, das bereits als reserviertes Schlüsselwort existierte.

Beispiel #2 Einfache Nutzung von `static::`

    <?php

    class A
    {
        public static function who()
        {
            echo __CLASS__;
        }

        public static function test()
        {
            static::who(); // Hier kommt die späte statische Bindung
        }
    }

    class B extends A
    {
        public static function who()
        {
            echo __CLASS__;
        }
    }

    B::test();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    B

> Hinweis:

> In nicht statischen Kontexten ist die aufgerufene Klasse die Klasse des Objekt-Exemplars. Da `$this->` versucht private Methoden im gleichen Geltungsbereich aufzurufen, kann die Verwendung von `static::` andere Ergebnisse liefern. Ein weiterer Unterschied ist, dass `static::` sich nur auf statische Eigenschaften beziehen kann.

Beispiel #3 Nutzung von `static::` außerhalb eines statischen Kontexts

    <?php

    class A
    {
        private function foo()
        {
            echo "Erfolg!\n";
        }

        public function test()
        {
            $this->foo();
            static::foo();
        }
    }

    class B extends A
    {
        /* foo() wird nach B kopiert, weshalb ihr Geltungsbereich immer noch A ist
        * und der Aufruf erfolgreich sein wird */
    }

    class C extends A
    {
        private function foo()
        {
            /* ursprüngliche Methode wird ersetzt; der Geltungsbereich der neuen ist C */
        }
    }

    $b = new B();
    $b->test();

    $c = new C();
    try {
        $c->test();
    } catch (Error $e) {
        echo $e->getMessage();
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Erfolg!
    Erfolg!
    Erfolg!
    Call to private method C::foo() from scope A

> Hinweis:

> Die Auflösung später statischer Bindungen endet mit einem vollständig aufgelösten statischen Aufruf ohne Alternative. Statische Aufrufe, die Schlüsselworte wie `parent::` oder `self::` nutzen, geben dagegen die Aufrufinformationen weiter.

> Beispiel #4 Weitergegebene und nicht weitergegebene Aufrufe

>     <?php

>     class A
>     {
>         public static function foo()
>         {
>             static::who();
>         }

>         public static function who()
>         {
>             echo __CLASS__ . "\n";
>         }
>     }

>     class B extends A
>     {
>         public static function test()
>         {
>             A::foo();
>             parent::foo();
>             self::foo();
>         }

>         public static function who()
>         {
>             echo __CLASS__ . "\n";
>         }
>     }

>     class C extends B
>     {
>         public static function who()
>         {
>             echo __CLASS__ . "\n";
>         }
>     }

>     C::test();

>     ?>

> Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

>     A
>     C
>     C

## Objekte und Referenzen

Eine der häufigsten Aussagen zu objektorientierter Programmierung in PHP ist, dass "Objekte standardmäßig als Referenz übergeben werden". Dies ist nicht komplett wahr. Dieser Abschnitt berichtigt diese verbreitete Annahme anhand von Beispielen.

Eine PHP-Referenz ist ein Alias, der es ermöglicht, dass zwei unterschiedliche Variablen sich auf denselben Wert beziehen. In PHP enthält eine Objektvariable nicht mehr das Objekt als Wert, sondern nur einen Objektbezeichner, der bei Objektzugriffen die Identifizierung des eigentlichen Objektes ermöglicht. Wenn ein Objekt als Argument oder Rückgabewert übergeben oder einer anderen Variable zugewiesen wird, so sind die verschiedenen Variablen keine Aliase, sie enthalten vielmehr Kopien des Bezeichners, die auf dasselbe Objekt verweisen.

Beispiel #1 Referenzen und Objekte

    <?php
    class A {
        public $foo = 1;
    }

    $a = new A;
    $b = $a;     // $a und $b sind Kopien des gleichen Bezeichners
                 // ($a) = ($b) = <id>
    $b->foo = 2;
    echo $a->foo."\n";

    $c = new A;
    $d = &$c;    // $c und $d sind Referenzen
                 // ($c,$d) = <id>

    $d->foo = 2;
    echo $c->foo."\n";

    $e = new A;

    function foo($obj) {
        // ($obj) = ($e) = <id>
        $obj->foo = 2;
    }

    foo($e);
    echo $e->foo."\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2
    2
    2

## Serialisierung von Objekten - Objekte in Sessions

serialize() erzeugt einen String, welcher die Byte-Stream-Repräsentation eines jeden Wertes besitzt, der in PHP gespeichert werden kann. unserialize() kann diesen String verwenden, um die ursprünglichen Variablenwerte wiederherzustellen. Verwendet man serialize(), um ein Objekt zu speichern, so werden alle Variablen dieses Objektes gespeichert. Die Methoden des Objektes werden nicht gespeichert, nur der Name der Klasse.

Damit man imstande ist, ein Objekt mit unserialize() wiederherzustellen, muss die Klasse des Objektes definiert sein. Das heißt, wenn man ein Objekt der Klasse A serialisiert, erhält man einen String, der sich auf die Klasse A bezieht und die Werte aller darin enthaltenen Variablen beinhaltet. Wenn man in einer anderen Datei diesen String wieder zu einem Objekt der Klasse A deserialisieren will, so muss die Klasse A in dieser Datei vorher bekannt sein. Dies kann man erreichen, indem man die Definition der Klasse A in eine mittels include ladbare Datei auslagert und diese Datei einbindet oder die Funktion spl_autoload_register() verwendet.

    <?php
    // A.php:

      class A {
          public $one = 1;

          public function show_one() {
              echo $this->one;
          }
      }

    // page1.php:

      include "A.php";

      $a = new A;
      $s = serialize($a);
      // $s irgendwo ablegen, wo page2.php dies finden kann.
      file_put_contents('store', $s);

    // page2.php:

      // Dies ist nötig, damit unserialize korrekt funktioniert.
      include "A.php";

      $s = file_get_contents('store');
      $a = unserialize($s);

      // Nun kann man die Funktion show_one() des Objektes $a
      // verwenden.
      $a->show_one();
    ?>

Es ist dringend empfohlen, dass wenn eine Anwendung Objekte zur späteren Verwendung in der Anwendung serialisiert, die Klassendefinitionen in der gesamten Anwendung eingebunden werden. Wird dies nicht beachtet, so wird das Objekt ohne eine Klassendefinition deserialisiert, was dazu führen wird, dass PHP dem Objekt eine Klasse __PHP_Incomplete_Class_Name zuweisen wird, welche keine Methoden besitzt. Dies wird das Objekt nutzlos machen.

Wenn also im obigen Beispiel $a Teil einer Session würde, indem ein neuer Schlüssel zum superglobalen Array $_SESSION hinzugefügt wird, dann sollte die Datei `A.php` in jeder Seite eingebunden werden, nicht nur in page1.php und page2.php.

Beachten Sie neben den obigen Hinweisen dass man sich in die Serialisierungs- und Deserialisierungs-Ereignisse einklinken kann, indem man die Methoden __sleep() und __wakeup() eines Objektes verwendet. Die Verwendung von __sleep() erlaubt es nur eine Teilmenge der Eigenschaften eines Objektes zu serialisieren.

## Kovarianz und Kontravarianz

Mit PHP 7.2.0 wurde teilweise Kontravarianz eingeführt, indem Typeneinschränkungen bei Parametern von Kindmethoden entfernt wurden. Mit PHP 7.4.0 wurde dann vollständige Unterstützung für Kovarianz und Kontravarianz eingeführt.

Kovarianz erlaubt es den Methoden eines Kindes, einen spezifischeren Typen als die Elternmethode für den Rückgabewert zurückzugeben. Die Kontravarianz erlaubt einen weniger spezifischen Parametertyp in einer Kindmethode als in der Elternmethode.

Eine Typdeklaration wird in den folgenden Fällen als spezifischer angesehen:

- Ein Typ wird aus einem Vereinigungstypen entfernt
- Ein Typ wird zu einem Schnittmengentypen hinzugefügt.
- Ein Klassentyp wird zu dem Typen eines seiner Kinder geändert
- iterable wird zu array oder Traversable geändert

Falls das Gegenteil zutrifft, wird ein Klassentyp als weniger spezifisch angesehen.

### Kovarianz

Um Kovarianz zu illustrieren, wird eine einfache abstrakte Elternklasse Tier erzeugt. Tier wird von seinen Kindern Katze und Hund beerbt.

    <?php

    abstract class Tier
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        abstract public function gibLaut();
    }

    class Hund extends Tier
    {
        public function gibLaut()
        {
            echo $this->name . " bellt";
        }
    }

    class Katze extends Tier
    {
        public function gibLaut()
        {
            echo $this->name . " miaut";
        }
    }

Beachtenswert ist, dass keine der Methoden hier einen Wert zurückgibt. Es werden nun ein paar Factories hinzugefügt, die ein neues Objekt der Klassen Tier, Katze oder Hund erzeugen.

    <?php

    interface TierHeim
    {
        public function adoptiere(string $name): Tier;
    }

    class KatzenHeim implements TierHeim
    {
        public function adoptiere(string $name): Katze // statt den Klassentyp Tier zurückzugeben, kann hier Typ Katze verwendet werden
        {
            return new Katze($name);
        }
    }

    class HundeHeim implements TierHeim
    {
        public function adoptiere(string $name): Hund // statt den Klassentyp Tier zurückzugeben, kann hier Typ Hund verwendet werden
        {
            return new Hund($name);
        }
    }

    $kaetzchen = (new KatzenHeim)->adoptiere("Ricky");
    $kaetzchen->gibLaut();
    echo "\n";

    $huendchen = (new HundeHeim)->adoptiere("Mavrick");
    $huendchen->gibLaut();

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ricky miaut
    Mavrick bellt

### Kontravarianz

Um das vorherige Beispiel mit den Klassen Tier, Katze und Hund fortzusetzen, werden nun die Klassen Nahrung sowie Tierfutter definiert, sowie auch eine Methode iss(Tierfutter $futter) zur abstrakten Klasse Tier hinzugefügt.

    <?php

    class Nahrung {}

    class Tierfutter extends Nahrung {}

    abstract class Tier
    {
        protected string $name;

        public function __construct(string $name)
        {
            $this->name = $name;
        }

        public function iss(Tierfutter $futter)
        {
            echo $this->name . " isst " . get_class($futter);
        }
    }

Um das Verhalten der Kontravarianz zu sehen, wird nun die Methode iss in der Klasse Hund überschrieben, um jedes Objekt der Klasse Nahrung zuzulassen. Die Klasse Katze bleibt unverändert.

    <?php

    class Hund extends Tier
    {
        public function iss(Nahrung $futter) {
            echo $this->name . " isst " . get_class($futter);
        }
    }

Das folgende Beispiel zeigt das Verhalten der Kontravarianz.

    <?php

    $kaetzchen = (new KatzenHeim)->adoptiere("Ricky");
    $katzenFutter = new Tierfutter();
    $kaetzchen->iss($katzenFutter);
    echo "\n";

    $huendchen = (new HundeHeim)->adoptiere("Mavrick");
    $banane = new Nahrung();
    $huendchen->iss($banane);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ricky isst Tierfutter
    Mavrick isst Nahrung

Was geschieht nun aber, wenn man der iss()-Methode von $kaetzchen versucht die $banane zu übergeben?

    $kitty->iss($banane);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Fatal error: Uncaught TypeError: Argument 1 passed to Tier::iss() must be an instance of Tierfutter, instance of Nahrung given

### Varianz der Eigenschaften

Standardmäßig sind Eigenschaften weder kovariant noch kontravariant, d. h. sie sind invariant. Das bedeutet, dass sich ihr Typ in einer Kindklasse überhaupt nicht ändern darf. Der Grund dafür ist, dass "get"-Operationen kovariant und "set"-Operationen kontravariant sein müssen. Die einzige Möglichkeit für eine Eigenschaft, beide Anforderungen zu erfüllen, besteht darin, invariant zu sein.

Seit PHP 8.4.0 ist es mit der Einführung von abstrakten Eigenschaften (auf einer Schnittstelle oder einer abstrakten Klasse) und virtuellen Eigenschaften möglich, eine Eigenschaft zu deklarieren, die nur eine get- oder set-Operation hat. Folglich können abstrakte Eigenschaften oder virtuelle Eigenschaften, die nur eine "get"-Operation benötigen, kovariant sein. Ebenso kann eine abstrakte Eigenschaft oder eine virtuelle Eigenschaft, die nur eine "set"-Operation benötigt, kontravariant sein.

Sobald eine Eigenschaft jedoch sowohl eine get- als auch eine set-Operation hat, ist sie für weitere Erweiterungen nicht mehr kovariant oder kontravariant. Mit anderen Worten: Sie ist nun invariant.

Beispiel #1 Varianz des Eigenschaftstyps

    <?php
    class Animal {}
    class Dog extends Animal {}
    class Poodle extends Dog {}

    interface PetOwner
    {
        // Es wird nur eine get-Operation benötigt, so dass diese kovariant
        // sein kann.
        public Animal $pet { get; }
    }

    class DogOwner implements PetOwner
    {
        // Dies kann ein restriktiverer Typ sein, da die "get"-Seite immer ein
        // Animal zurückgibt. Da es sich jedoch um eine native Eigenschaft handelt,
        // können Kinder dieser Klasse den Typ nicht mehr ändern.
        public Dog $pet;
    }

    class PoodleOwner extends DogOwner
    {
        // Dies ist NICHT ZULÄSSIG, da für DogOwner::$pet sowohl get- als auch
        // set-Operationen definiert sind und benötigt werden.
        public Poodle $pet;
    }
    ?>

## Lazy Objects

A lazy object is an object whose initialization is deferred until its state is observed or modified. Some use-case examples include dependency injection components that provide lazy services fully initialized only if needed, ORMs providing lazy entities that hydrate themselves from the database only when accessed, or a JSON parser that delays parsing until elements are accessed.

Two lazy object strategies are supported: Ghost Objects and Virtual Proxies, hereafter referred to as "lazy ghosts" and "lazy proxies". In both strategies, the lazy object is attached to an initializer or factory that is called automatically when its state is observed or modified for the first time. From an abstraction point of view, lazy ghost objects are indistinguishable from non-lazy ones: they can be used without knowing they are lazy, allowing them to be passed to and used by code that is unaware of laziness. Lazy proxies are similarly transparent, but care must be taken when their identity is used, as the proxy and its real instance have different identities.

> Hinweis: Version Information
> Lazy objects were introduced in PHP 8.4.

### Creating Lazy Objects

It is possible to create a lazy instance of any user defined class or the stdClass class (other internal classes are not supported), or to reset an instance of these classes to make it lazy. The entry points for creating a lazy object are the ReflectionClass::newLazyGhost() and ReflectionClass::newLazyProxy() methods.

Both methods accept a function that is called when the object requires initialization. The function's expected behavior varies depending on the strategy in use, as described in the reference documentation for each method.

Beispiel #1 Creating a Lazy Ghost

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyGhost(function (Example $object) {
        // Initialize object in-place
        $object->__construct(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Triggers initialization
    var_dump($lazyObject->prop);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    lazy ghost object(Example)#3 (0) {
    ["prop"]=>
    uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

Beispiel #2 Creating a Lazy Proxy

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyProxy(function (Example $object) {
        // Create and return the real instance
        return new Example(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // Triggers initialization
    var_dump($lazyObject->prop);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    lazy proxy object(Example)#3 (0) {
      ["prop"]=>
      uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

Any access to properties of a lazy object triggers its initialization (including via ReflectionProperty). However, certain properties might be known in advance and should not trigger initialization when accessed:

Beispiel #3 Initializing Properties Eagerly

    <?php
    class BlogPost
    {
        public function __construct(
            public int $id,
            public string $title,
            public string $content,
        ) { }
    }

    $reflector = new ReflectionClass(BlogPost::class);

    $post = $reflector->newLazyGhost(function ($post) {
        $data = fetch_from_store($post->id);
        $post->__construct($data['id'], $data['title'], $data['content']);
    });

    // Without this line, the following call to ReflectionProperty::setValue() would
    // trigger initialization.
    $reflector->getProperty('id')->skipLazyInitialization($post);
    $reflector->getProperty('id')->setValue($post, 123);

    // Alternatively, one can use this directly:
    $reflector->getProperty('id')->setRawValueWithoutLazyInitialization($post, 123);

    // The id property can be accessed without triggering initialization
    var_dump($post->id);
    ?>

The ReflectionProperty::skipLazyInitialization() and ReflectionProperty::setRawValueWithoutLazyInitialization() methods offer ways to bypass lazy-initialization when accessing a property.

### About Lazy Object Strategies

Lazy ghosts are objects that initialize in-place and, once initialized, are indistinguishable from an object that was never lazy. This strategy is suitable when we control both the instantiation and initialization of the object, making it unsuitable if either of these is managed by another party.

Lazy proxies, once initialized, act as proxies to a real instance: any operation on an initialized lazy proxy is forwarded to the real instance. The creation of the real instance can be delegated to another party, making this strategy useful in cases where lazy ghosts are unsuitable. Although lazy proxies are nearly as transparent as lazy ghosts, caution is needed when their identity is used, as the proxy and its real instance have distinct identities.

### Lifecycle of Lazy Objects

Objects can be made lazy at instantiation time using ReflectionClass::newLazyGhost() or ReflectionClass::newLazyProxy(), or after instantiation by using ReflectionClass::resetAsLazyGhost() or ReflectionClass::resetAsLazyProxy(). Following this, a lazy object can become initialized through one of the following operations:

- Interacting with the object in a way that triggers automatic initialization. See Initialization triggers.
- Marking all its properties as non-lazy using ReflectionProperty::skipLazyInitialization() or ReflectionProperty::setRawValueWithoutLazyInitialization().
- Calling explicitly ReflectionClass::initializeLazyObject() or ReflectionClass::markLazyObjectAsInitialized().

As lazy objects become initialized when all their properties are marked non-lazy, the above methods will not mark an object as lazy if no properties could be marked as lazy.

### Initialization Triggers

Lazy objects are designed to be fully transparent to their consumers, so normal operations that observe or modify the object's state will automatically trigger initialization before the operation is performed. This includes, but is not limited to, the following operations:

- Reading or writing a property.
- Testing if a property is set or unsetting it.
- Accessing or modifying a property via ReflectionProperty::getValue(), ReflectionProperty::getRawValue(), ReflectionProperty::setValue(), or ReflectionProperty::setRawValue().
- Listing properties with ReflectionObject::getProperties(), ReflectionObject::getProperty(), get_object_vars().
- Iterating over properties of an object that does not implement Iterator or IteratorAggregate using foreach.
- Serializing the object with serialize(), json_encode(), etc.
- Cloning the object.

Method calls that do not access the object state will not trigger initialization. Similarly, interactions with the object that invoke magic methods or hook functions will not trigger initialization if these methods or functions do not access the object's state.

#### Non-Triggering Operations

The following specific methods or low-level operations allow access or modification of lazy objects without triggering initialization:

- Marking properties as non-lazy with ReflectionProperty::skipLazyInitialization() or ReflectionProperty::setRawValueWithoutLazyInitialization().
- Retrieving the internal representation of properties using get_mangled_object_vars() or by casting the object to an array.
- Using serialize() when `ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE` is set, unless __serialize() or __sleep() trigger initialization.
- Calling ReflectionObject::__toString().
- Using var_dump() or debug_zval_dump(), unless __debugInfo() triggers initialization.

### Initialization Sequence

This section outlines the sequence of operations performed when initialization is triggered, based on the strategy in use.

#### Ghost Objects

- The object is marked as non-lazy.
- Properties not initialized with ReflectionProperty::skipLazyInitialization() or ReflectionProperty::setRawValueWithoutLazyInitialization() are set to their default values, if any. At this stage, the object resembles one created with ReflectionClass::newInstanceWithoutConstructor(), except for already initialized properties.
- The initializer function is then called with the object as its first parameter. The function is expected, but not required, to initialize the object state, and must return `null` or no value. The object is no longer lazy at this point, so the function can access its properties directly.

After initialization, the object is indistinguishable from an object that was never lazy.

#### Proxy Objects

- The object is marked as non-lazy.
- Unlike ghost objects, the properties of the object are not modified at this stage.
- The factory function is called with the object as its first parameter and must return a non-lazy instance of a compatible class (see ReflectionClass::newLazyProxy()).
- The returned instance is referred to as the real instance and is attached to the proxy.
- The proxy's property values are discarded as though unset() was called.

After initialization, accessing any property on the proxy will yield the same result as accessing the corresponding property on the real instance; all property accesses on the proxy are forwarded to the real instance, including declared, dynamic, non-existing, or properties marked with ReflectionProperty::skipLazyInitialization() or ReflectionProperty::setRawValueWithoutLazyInitialization().

The proxy object itself is not replaced or substituted for the real instance.

While the factory receives the proxy as its first parameter, it is not expected to modify it (modifications are allowed but will be lost during the final initialization step). However, the proxy can be used for decisions based on the values of initialized properties, the class, the object itself, or its identity. For instance, the initializer might use an initialized property's value when creating the real instance.

#### Common Behavior

The scope and $this context of the initializer or factory function remains unchanged, and usual visibility constraints apply.

After successful initialization, the initializer or factory function is no longer referenced by the object and may be released if it has no other references.

If the initializer throws an exception, the object state is reverted to its pre-initialization state and the object is marked as lazy again. In other words, all effects on the object itself are reverted. Other side effects, such as effects on other objects, are not reverted. This prevents exposing a partially initialized instance in case of failure.

### Cloning

Cloning a lazy object triggers its initialization before the clone is created, resulting in an initialized object.

For proxy objects, both the proxy and its real instance are cloned, and the clone of the proxy is returned. The `__clone` method is called on the real instance, not on the proxy. The cloned proxy and real instance are linked as they are during initialization, so accesses to the proxy clone are forwarded to the real instance clone.

This behavior ensures that the clone and the original object maintain separate states. Changes to the original object or its initializer's state after cloning do not affect the clone. Cloning both the proxy and its real instance, rather than returning a clone of the real instance alone, ensures that the clone operation consistently returns an object of the same class.

### Destructors

For lazy ghosts, the destructor is only called if the object has been initialized. For proxies, the destructor is only called on the real instance, if one exists.

The ReflectionClass::resetAsLazyGhost() and ReflectionClass::resetAsLazyProxy() methods may invoke the destructor of the object being reset.

## OOP-Changelog

Hier werden Änderungen am OOP-Modell von PHP protokolliert. Beschreibungen und andere Hinweise zu diesen Features werden innerhalb der OOP-Modell-Dokumentation dargelegt.

Version | Beschreibung
--- | ---
8.4.0 | Hinzugefügt: Unterstützung für Eigenschafts-Hooks.
8.4.0 | Hinzugefügt: Unterstützung für Verzögerte Initialisierung (Lazy Objects).
8.1.0 | Hinzugefügt: Unterstützung für den Modifikator final für Klassenkonstanten. Außerdem werden Schnittstellenkonstanten standardmäßig überschreibbar.
8.0.0 | Hinzugefügt: Unterstützung für den nullsafe-Operator ?-> für den Zugriff auf Eigenschaften und Methoden von Objekten, die null sein können.
7.4.0 | Geändert: es ist nun möglich eine Exception in __toString() zu werfen.
7.4.0 | Hinzugefügt: Unterstützung für eingeschränkte Rückgabetypkovarianz und Parametertypkontravarianz. Vollständige Varianzunterstützung ist nur bei Verwendung von Autoloading verfügbar. Innerhalb einer einzelnen Datei sind nur nicht-zyklische Typreferenzen möglich.
7.4.0 | Hinzugefügt: es ist nun möglich Klasseneigenschaften zu typisieren.
7.3.0 | Inkompatibel: das Argument-Entpacken von Traversablen mit nicht-Integer Schlüsseln wird nicht länger unterstützt. Dieses Verhalten war nicht beabsichtigt und wurde daher entfernt.
7.3.0 | Inkompatibel: in früheren Version war es möglich statische Eigenschaften durch Referenzzuweisung zu separieren. Dies wurde entfernt.
7.3.0 | Geändert: der instanceof-Operator erlaubt nun Literale als erster Operand, in welchem Fall das Ergebnis immer `false` ist.
7.2.0 | Missbilligt: die Funktion __autoload() wurde zugunsten von spl_autoload_register() missbilligt.
7.2.0 | Geändert: der folgende Name kann nicht verwendet werden, um Klassen, Interfaces oder Traits zu benennen: `object`.
7.2.0 | Geändert: der gruppierenden Use-Syntax für Namensräume kann nun ein abschließendes Komma angefügt werden.
7.2.0 | Geändert: Parametertyp-Erweiterung. Parametertypen in übersteuerten Methoden und Interfaceimplementierungen können nun weggelassen werden.
7.2.0 | Geändert: abstrakte Methoden können nun übersteuert werden, wenn eine abstrakte Klasse eine andere abstrakte Klasse erweitert.
7.1.0 | Geändert: folgende Namen können nicht verwendet werden, um Klassen, Interfaces oder Traits zu benennen: `void` und `iterable`.
7.1.0 | Hinzugefügt: es ist nun möglich die Sichtbarkeit von Klassenkonstanten anzugeben.
7.0.0 | Missbilligt: statische Aufrufe von Methoden, die nicht als statisch deklariert wurden.
7.0.0 | Missbilligt: Konstruktoren im Stil von PHP 4, d. h. Methoden, die denselben Namen wie die Klasse, in der sie definiert wurden, haben.
7.0.0 | Hinzugefügt: gruppierte use Deklaration: Klassen, Funktionen und Konstanten, die aus demselben Namensraum importiert werden, können nun in einer einzigen use-Anweisung gruppiert werden.
7.0.0 | Hinzugefügt: Unterstützung für anonyme Klassen per `new class` wurde hinzugefügt.
7.0.0 | Inkompatibel: die Iteration über ein nicht-Traversable Objekt hat nun dasselbe Verhalten wie die Iteration über Array-Referenzen.
7.0.0 | Definieren (kompatibler) Eigenschaften in zwei verwendeten Traits erzeugt keinen Fehler mehr.
5.6.0 | Hinzugefügt: die __debugInfo() Methode.
5.5.0 | Hinzugefügt: die magische ::class Konstante.
5.5.0 | finally zur Behandlung von Exceptions hinzugefügt.
5.4.0 | Traits hinzugefügt.
5.4.0 | Geändert: Wenn eine abstrakte Klasse eine Signatur für den Konstruktor definiert, so wird diese nun erzwungen.
5.3.3 | Geändert: Methoden, die den Namen des letzten Elementes eines Klassennamens in einem Namespace tragen, werden nicht länger als Konstruktor behandelt. Diese Änderung beeinflusst Klassen außerhalb von Namespaces nicht.
5.3.0 | Geändert: Klassen, die Interfaces implementieren, welche Methoden mit Vorgabewerten in ihrem Prototypen enthalten müssen nicht mehr dem Vorgabewert des Interfaces entsprechen.
5.3.0 | Geändert: Es ist nun möglich eine Klasse mittels einer Variablen zu referenzieren (z. B. `echo $classname::constant;`). Der Wert der Variable darf kein Schlüsselwort sein (z. B. `self`, `parent` oder `static`).
5.3.0 | Geändert: Ein Fehler der Stufe `E_WARNING` wird ausgelöst, wenn die magischen Methoden für Überladung als static deklariert werden. Dies erzwingt auch die Anforderung nach öffentlicher Sichtbarkeit.
5.3.0 | Geändert: Vor PHP 5.3.0 konnten Exceptions, die in einer __autoload()-Funktion geworfen wurden, nicht mit einem catch-Block gefangen werden und resultierten in einem "fatal error". Nun können Exceptions, die in einer __autoload-Funktion geworfen wurden, im catch-Block unter einer Bedingung gefangen werden. Wenn eine selbst definierte Exception geworfen wird, so muss diese Exception verfügbar sein. Die __autoload-Funktion kann jedoch rekursiv aufgerufen werden, um die Exceptionklasse automatisch zu laden.
5.3.0 | Hinzugefügt: Die Methode __callStatic.
5.3.0 | Hinzugefügt: Unterstützung für die heredoc- und nowdoc-Syntax für const und Definition von Eigenschaften in einer Klasse. Beachten Sie: die heredoc-Werte müssen den gleichen Regeln wie Strings in doppelten Anführungszeichen folgen (d. h. keine Variablen beinhalten).
5.3.0 | Hinzugefügt: Späte statische Bindung.
5.3.0 | Hinzugefügt: Die Methode __invoke.
5.2.0 | Geändert: Die Methode __toString wurde nur in direkter Verbindung mit echo oder print aufgerufen. Nun wird sie in jedem String-Kontext aufgerufen (z. B. in printf() mit dem `%s`-Modifizierer), aber nicht in anderen Kontexten (z. B. mit dem `%d`-Modifizierer). Von PHP 5.2.0 an löst die Konvertierung von Objekten ohne __toString-Methode zu String einen Fehler der Stufe `E_RECOVERABLE_ERROR` aus.
5.1.3 | Geändert: In vorhergehenden Versionen von PHP 5 wurde die Verwendung von `var` als veraltet betrachtet und löste einen Fehler der Stufe `E_STRICT` aus. Dies ist nicht länger veraltet und daher wird kein Fehler mehr ausgelöst.
5.1.0 | Geändert: Die statische Methode __set_state wird nun für Klassen aufgerufen, wenn sie durch var_export() exportiert werden.
5.1.0 | Hinzugefügt: Die Methoden __isset und __unset.

# Namespaces

## Inhaltsverzeichnis

- Übersicht
- Namespaces
- Unter-Namespaces
- Mehrere Namespaces in derselben Datei definieren
- Grundlagen
- Namespaces und dynamische Sprachfeatures
- Schlüsselwort namespace und __NAMESPACE__
- Aliase und Importieren
- Globaler Namensraum
- Rückgriff auf den globalen Namespace
- Regeln für Namensauflösung
- FAQ

## Übersicht über Namespaces

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Was sind Namespaces? Im weitesten Sinne bieten Namespaces eine Möglichkeit, verschiedene Gegenstände zu kapseln. Dies kann man als abstraktes Konzept an vielen Dingen beobachten. In einem Betriebssystem dienen zum Beispiel Verzeichnisse dazu, um zusammengehörige Dateien zu gruppieren, und dienen als Namespace für die beinhalteten Dateien. In einem konkreten Beispiel kann die Datei `foo.txt` sowohl im Verzeichnis `/home/greg` als auch in `/home/other` existieren, aber es können keine zwei Varianten der Datei `foo.txt` im gleichen Verzeichnis existieren. Um auf die Datei `foo.txt` von außerhalb des Verzeichnisses `/home/greg` zuzugreifen, muss man zusätzlich dem Verzeichnisnamen den Dateinamen und ein Trennzeichen voranstellen, um `/home/greg/foo.txt` zu erhalten. Das gleiche Prinzip streckt sich auf Namespaces in der Programmierwelt aus.

In der Welt von PHP wurden Namespaces entworfen, um zwei Probleme zu lösen, auf die die Autoren von Bibliotheken und Anwendungen stoßen, wenn sie wiederverwendbare Codeelemente wie Klassen und Funktionen entwickeln:

1. Namenskollisionen zwischen eigenem Code und internen PHP-Klassen/Funktionen/Konstanten oder Klassen/Funktionen/Konstanten von Drittanbietern.
2. Die Möglichkeit, einen Alias (oder einen Kurznamen) für Sehr_Lange_Namen einzuführen, die geschaffen wurde, um das erste Problem zu umgehen. Damit kann man die Lesbarkeit des Quellcodes erhöhen.

PHP-Namespaces bieten eine Möglichkeit, zusammengehörige Klassen, Interfaces, Funktionen und Konstanten zusammenzufassen. Dies ist ein Beispiel für die Namespace-Syntax in PHP:

Beispiel #1 Beispiel für Namespace-Syntax

    <?php
    namespace my\name; // siehe Abschnitt "Namespaces definieren"

    class MyClass {}
    function myfunction() {}
    const MYCONST = 1;

    $a = new MyClass;
    $c = new \my\name\MyClass; // siehe Abschnitt "Globaler Namensraum"

    $a = strlen('hi'); // siehe Abschnitt "Namespaces verwenden: Rückgriff auf
                       // globale Funktion/Konstante"

    $d = namespace\MYCONST; // siehe Abschnitt "Namespace-Schlüsselwort und __NAMESPACE__-
                            // Konstante"
    $d = __NAMESPACE__ . '\MYCONST';
    echo constant($d); // siehe Abschnitt "Namespaces und dynamische Sprachfeatures"
    ?>

> Hinweis: Bei Namespace-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden.

> Hinweis:

> Der Namespace `PHP`, sowie zusammengesetzte Namen, die mit dieser Bezeichnung beginnen (wie z. B. `PHP\Classes`), sind zur internen Verwendung in der Sprache reserviert und sollten im eigenen Programmcode nicht verwendet werden.

## Namespaces definieren

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Obwohl jeder gültige PHP-Quellcode in Namespaces eingeschlossen werden kann, werden nur die folgenden Arten von Code von Namespaces beeinflusst: Klassen (inklusive abstrakter Klassen, Traits und Enums), Interfaces, Funktionen und Konstanten.

Namespaces werden mit dem Schlüsselwort `namespace` definiert. Eine Datei, die einen Namespace beinhaltet, muss den Namespace am Anfang der Datei vor jeglichem anderen Code deklarieren - mit Ausnahme des declare-Schlüsselwortes.

Beispiel #1 Einen einzelnen Namespace deklarieren

    <?php
    namespace MyProject;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

    ?>

> Hinweis: Vollständig qualifizierte Namen (d. h. Namen, die mit einem Rückwärtsschrägstrich beginnen) sind in Namensraumdeklarationen nicht erlaubt, weil solche Konstrukte als relative Namensraumausdrücke interpretiert werden.

Der einzige Quellcode, der vor einer Namespacedeklaration stehen darf, ist der `declare`-Ausdruck, der die Kodierung der Quellcodedatei definiert. Gleichzeitig darf kein Nicht-PHP-Code vor einer Namespacedeklaration stehen - auch keine zusätzlichen Leerzeichen, Zeilenumbrüche oder Tabulatoren.

Beispiel #2 Einen einzelnen Namespace deklarieren

    <html>
    <?php
    namespace MyProject; // fatal error - Namespace muss der erste Ausdruck im Skript sein
    ?>

Zusätzlich darf - im Gegensatz zu anderen PHP-Konstrukten - der selbe Namespace in mehreren Dateien definiert werden, womit man den Inhalt eines Namespaces im Dateisystem aufteilen kann.

## Unter-Namespaces deklarieren

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Ähnlich wie Verzeichnisse und Dateien hat ein PHP-Namespace auch die Möglichkeit, eine Hierarchie von Namespacenamen zu beinhalten. Ein Namespace kann also mit Unterebenen definiert werden:

Beispiel #1 Einen einzelnen Namespace mit einer Hierarchie deklarieren

    <?php
    namespace MyProject\Sub\Level;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

    ?>

Das obige Beispiel erzeugt eine Konstante `MyProject\Sub\Level\CONNECT_OK`, die Klasse `MyProject\Sub\Level\Connection` und die Funktion `MyProject\Sub\Level\connect`.

## Mehrere Namespaces in derselben Datei definieren

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Es können auch mehrere Namespaces in derselben Datei definiert werden. Es gibt hierfür zwei mögliche Schreibweisen:

Beispiel #1 Mehrere Namespaces definieren, einfache Kombinationssyntax

    <?php
    namespace MyProject;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }

    namespace AnotherProject;

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    ?>

Diese Syntax ist nicht die empfohlene Syntax, um mehrere Namespaces in einer einzigen Datei zusammenzuführen. Stattdessen wird die geklammerte Syntax empfohlen.

Beispiel #2 Mehrere Namespaces definieren, geklammerte Syntax

    <?php
    namespace MyProject {

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    }

    namespace AnotherProject {

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    }
    ?>

Es wird stark von der Programmierpraxis, mehrere Namespaces in einer Datei zu definieren, abgeraten. Der wichtigste Einsatzzweck dieser Möglichkeit ist es, mehrere PHP-Skripte in derselben Datei zusammenzuführen.

Um Code ohne Namensräume mit solchem mit Namensräumen zusammenzuführen, wird nur die geklammerte Syntax unterstützt. Globaler Code sollte in einem Namespace-Statement ohne Namespace eingeschlossen werden:

Beispiel #3 Mehrere Namespaces und Code ohne Namespace deklarieren

    <?php
    namespace MyProject {

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    }

    namespace { // global code
    session_start();
    $a = MyProject\connect();
    echo MyProject\Connection::start();
    }
    ?>

Es darf kein PHP-Code außerhalb der Namespace-Klammern existieren, abgesehen von einem beginnenden declare-Ausdruck.

Beispiel #4 Mehrere Namespaces und Code ohne Namespace deklarieren

    <?php
    declare(encoding='UTF-8');
    namespace MyProject {

    const CONNECT_OK = 1;
    class Connection { /* ... */ }
    function connect() { /* ... */  }
    }

    namespace { // globaler Code
    session_start();
    $a = MyProject\connect();
    echo MyProject\Connection::start();
    }
    ?>

## Namespaces verwenden: Grundlagen

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Bevor die Verwendung von Namespaces besprochen wird, ist es wichtig zu verstehen, woher PHP weiß, welches Element mit Namespace vom Code angefordert wird. Eine einfache Analogie kann zwischen PHP-Namensräumen und einem Dateisystem gesehen werden. Es gibt drei Möglichkeiten, mit denen man auf eine Datei in einem Dateisystem zugreifen kann:

1. Relative Dateinamen wie `foo.txt`. Dies wird zu `aktuellesVerzeichnis/foo.txt` aufgelöst, wenn `aktuellesVerzeichnis` das gerade geöffnete Verzeichnis ist. Wenn also das aktuelle Verzeichnis `/home/foo` ist, so wird dies als `/home/foo/foo.txt` aufgelöst.
2. Relative Pfade wie `unterVerzeichnis/foo.txt`. Dies wird zu `aktuellesVerzeichnis/unterVerzeichnis/foo.txt` aufgelöst.
3. Absolute Pfadangaben wie `/main/foo.txt`. Dies wird zu `/main/foo.txt` aufgelöst.

Das gleiche Prinzip kann auf Elemente mit Namespaces in PHP angewandt werden. Zum Beispiel kann eine Klasse auf drei Arten angesprochen werden:

1. Unqualifizierte Namen oder ein Klassenname ohne Präfix, wie etwa `$a = new foo();` oder `foo::staticmethod();`. Falls der aktuelle Namespace `aktuellerNamespace` ist, so wird dies zu `aktuellerNamespace\foo` aufgelöst. Ist der Code globaler Code ohne Namespaces, so wird dies zu `foo` aufgelöst. Es gibt eine Ausnahme hierzu: Unqualifizierte Namen für Funktionen und Konstanten werden zu globalen Funktionen und Konstanten aufgelöst, wenn die Funktion oder Konstante im Namespace nicht definiert ist. Siehe auch Namespaces verwenden: Rückgriff auf globale Funktion/Konstante für weitere Details.
2. Qualifizierte Namen oder ein Klassenname mit Präfix, wie etwa `$a = new unterNamespace\foo();` oder `unterNamespace\foo::staticmethod();`. Wenn der aktuelle Namespace `aktuellerNamespace` ist, so wird dies als `aktuellerNamespace\unterNamespace\foo` verstanden. Wenn der Code global und ohne Namespaces ist, so wird dies zu `unterNamespace\foo` aufgelöst.
3. Vollständig qualifizierte Namen oder Namen mit globalem Präfixoperator wie `$a = new \aktuellerNamespace\foo();` oder `\aktuellerNamespace\foo::staticmethod();`. Dies wird immer wörtlich wie der im Code angegebene Name verstanden, also `aktuellerNamespace\foo`.

Hier ein Beispiel für die drei Schreibweisen in tatsächlichem Code:

file1.php

    <?php
    namespace Foo\Bar\subnamespace;

    const FOO = 1;
    function foo() {}
    class foo
    {
        static function staticmethod() {}
    }
    ?>

file2.php

    <?php
    namespace Foo\Bar;
    include 'file1.php';

    const FOO = 2;
    function foo() {}
    class foo
    {
        static function staticmethod() {}
    }

    /* Unqualifizierter Name */
    foo(); // wird als Funktion Foo\Bar\foo aufgelöst
    foo::staticmethod(); // wird als Klasse Foo\Bar\foo und Methode staticmethod aufgelöst
    echo FOO; // gibt die Konstante Foo\Bar\FOO aus

    /* Qualifizierter Name */
    subnamespace\foo(); // wird als Funktion Foo\Bar\subnamespace\foo aufgelöst
    subnamespace\foo::staticmethod(); // wird als Klasse Foo\Bar\subnamespace\foo und
                                      // Methode staticmethod aufgelöst
    echo subnamespace\FOO; // gibt die Konstante Foo\Bar\subnamespace\FOO aus

    /* Vollständig qualifizierter Name */
    \Foo\Bar\foo(); // wird als Funktion Foo\Bar\foo aufgelöst
    \Foo\Bar\foo::staticmethod(); // wird als Klasse Foo\Bar\foo und Methode staticmethod aufgelöst
    echo \Foo\Bar\FOO; // gibt die Konstante Foo\Bar\FOO aus
    ?>

Beachten Sie, dass für den Zugriff auf jede globale Klasse, Funktion oder Konstante9 auch ein vollständig qualifizierter Name verwendet werden kann, wie z. B. \strlen(), \Exception oder \`INI_ALL`.

Beispiel #1 Zugriff auf globale Klassen, Funktionen und Konstanten aus einem Namespace

    <?php
    namespace Foo;

    function strlen() {}
    const INI_ALL = 3;
    class Exception {}

    $a = \strlen('hi'); // ruft die globale Funktion strlen auf
    $b = \INI_ALL; // greift auf die globale Konstante INI_ALL zu
    $c = new \Exception('error'); // erzeugt eine Neue Instanz der globalen
                                  // Klasse Exception
    ?>

## Namespaces und dynamische Sprachfeatures

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Die Implementierung von Namespaces in PHP ist stark von seinen Eigenschaften als Programmiersprache mit dynamischen Features beeinflusst. Man kann also den folgenden Code in Code mit Namespaces umformen:

Beispiel #1 Dynamischer Zugriff auf Elemente

example1.php:

    <?php
    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function funcname()
    {
        echo __FUNCTION__,"\n";
    }
    const constname = "global";

    $a = 'classname';
    $obj = new $a; // gibt classname::__construct aus
    $b = 'funcname';
    $b(); // gibt funcname aus
    echo constant('constname'), "\n"; // gibt global aus
    ?>

Um diesen Code umzuformen, muss man den vollständig qualifizierten Namen (Klassenname mit namespace-Präfix) verwenden. Beachten Sie, dass, weil es keinen Unterschied zwischen einem qualifizierten und vollständig qualifizierten Namen innerhalb eines dynamischen Klassen-, Funktions- oder Konstantennamen gibt, der führende Backslash nicht notwendigerweise angegeben werden muss.

Beispiel #2 Dynamischer Zugriff auf Elemente mit Namespace

    <?php
    namespace namespacename;
    class classname
    {
        function __construct()
        {
            echo __METHOD__,"\n";
        }
    }
    function funcname()
    {
        echo __FUNCTION__,"\n";
    }
    const constname = "namespaced";

    /* Wenn man doppelte Anführungszeichen verwendet,
    muss "\\namespacename\\classname" verwendet werden */
    $a = '\namespacename\classname';
    $obj = new $a; // gibt namespacename\classname::__construct aus
    $a = 'namespacename\classname';
    $obj = new $a; // gibt ebenfalls namespacename\classname::__construct aus
    $b = 'namespacename\funcname';
    $b(); // gibt namespacename\funcname aus
    $b = '\namespacename\funcname';
    $b(); // gibt ebenfalls namespacename\funcname aus
    echo constant('\namespacename\constname'), "\n"; // gibt namespaced aus
    echo constant('namespacename\constname'), "\n"; // gibt ebenfalls namespaced aus
    ?>

Bitte lesen Sie auch den Hinweis zum Escaping von Namespacenamen in Strings.

## Das Schlüsselwort namespace und die magische Konstante __NAMESPACE__

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP unterstützt zwei Arten des abstrakten Zugriffs auf Elemente innerhalb eines Namespaces, die magische Konstante `__NAMESPACE__` und das Schlüsselwort `namespace`.

Der Wert von `__NAMESPACE__` ist ein String, der den Namen des aktuellen Namespace beinhaltet. In globalem Code ohne Namespaces beinhaltet dies einen leeren String.

Beispiel #1 __NAMESPACE__-Beispiel, Code mit Namespace

    <?php
    namespace MyProject;

    echo '"', __NAMESPACE__, '"'; // gibt "MyProject" aus
    ?>

Beispiel #2 __NAMESPACE__-Beispiel, globaler Code

    <?php

    echo '"', __NAMESPACE__, '"'; // gibt "" aus
    ?>

Die Konstante `__NAMESPACE__` ist nützlich, um dynamische Namen zu konstruieren, zum Beispiel:

Beispiel #3 __NAMESPACE__ zur dynamischen Namenszusammensetzung verwenden

    <?php
    namespace MyProject;

    function get($classname)
    {
        $a = __NAMESPACE__ . '\\' . $classname;
        return new $a;
    }
    ?>

Das Schlüsselwort `namespace` kann verwendet werden, um explizit ein Element des aktuellen Namespaces oder eines untergeordneten Namespaces anzufordern. Es ist das äquivalent der Namespaces zum `self`-Operator für Klassen.

Beispiel #4 Der namespace-Operator, innerhalb eines Namespace

    <?php
    namespace MyProject;

    use blah\blah as mine; // siehe "Namespaces verwenden: Aliase/Importieren"

    blah\mine(); // ruft die Funktion MyProject\blah\mine() auf
    namespace\blah\mine(); // ruft die Funktion MyProject\blah\mine() auf

    namespace\func(); // ruft die Function MyProject\func() auf
    namespace\sub\func(); // ruft die Function MyProject\sub\func() auf
    namespace\cname::method(); // ruft die statische Methode "method" der Klasse MyProject\cname auf
    $a = new namespace\sub\cname(); // erzeugt ein Objekt der Klasse MyProject\sub\cname
    $b = namespace\CONSTANT; // weist den Wert der Konstante MyProject\CONSTANT $b zu
    ?>

Beispiel #5 Der namespace-Operator, in globalem Code

    <?php

    namespace\func(); // ruft die Function func() auf
    namespace\sub\func(); // ruft die Function sub\func() auf
    namespace\cname::method(); // ruft die statische Methode "method" der Klasse cname auf
    $a = new namespace\sub\cname(); // erzeugt ein Objekt der Klasse sub\cname
    $b = namespace\CONSTANT; // weist den Wert der Konstante CONSTANT $b zu
    ?>

## Namespaces verwenden: Aliase/Importieren

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Die Möglichkeit, auf vollständig qualifizierte Namen mit einem Alias (Importieren) zuzugreifen, ist ein wichtiges Feature von Namespaces. Dies ist ähnlich wie die Möglichkeit von Unix-basierten Dateisystemen einen symbolischen Link auf eine Datei oder ein Verzeichnis anzulegen.

PHP unterstützt das Vergeben von Aliasen (Importe) für Konstanten, Funktionen, Klassen, Interfaces, Traits, Aufzählungen (Enums) und Namespaces.

Ein Alias wird mittels des `use`-Operators angelegt. Hier ein Beispiel, welches alle fünf Arten von Importen zeigt:

Beispiel #1 Aliase/Importieren mit dem use-Operator

    <?php
    namespace foo;
    use My\Full\Classname as Another;

    // dies ist das gleiche wie use My\Full\NSname as NSname
    use My\Full\NSname;

    // importiert eine globale Klasse
    use ArrayObject;

    // Eine Funktion importieren
    use function My\Full\functionName;

    // Alias für eine Funktion
    use function My\Full\functionName as func;

    // Eine Konstante importieren
    use const My\Full\CONSTANT;

    $obj = new namespace\Another; // erzeugt ein Objekt der Klasse foo\Another
    $obj = new Another; // erzeugt ein Objekt der Klasse My\Full\Classname
    NSname\subns\func(); // ruft die Funktion My\Full\NSname\subns\func auf
    $a = new ArrayObject(array(1)); // erzeugt ein Objekt der Klasse ArrayObject
    // ohne das "use ArrayObject" wäre ein Objekt der Klasse foo\ArrayObject erzeugt worden
    func(); // ruft die Funktion My\Full\functionName auf
    echo CONSTANT; // Gibt den Wert von My\Full\CONSTANT aus
    ?>

Beachten Sie, dass für Namen von Namespaces (vollständig qualifizierte Namespacenamen mit einem Namensraumseparator, wie `Foo\Bar`, im Gegensatz zu globalen Namen ohne Separator, wie `FooBar`) der führende Backslash nicht notwendig und nicht empfohlen ist, weil importierte Namen vollständig qualifiziert sein müssen und nicht relativ zum aktuellen Namespace verarbeitet werden.

PHP unterstützt zusätzlich auch eine komfortable Kurzsyntax, mit der mehrere use-Ausdrücke in der gleichen Zeile erscheinen können.

Beispiel #2 Aliase/Importieren mit dem use-Operator, mehrere use-Ausdrücke kombiniert

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // erzeugt ein Objekt der Klasse My\Full\Classname
    NSname\subns\func(); // ruft die Funktion My\Full\NSname\subns\func auf
    ?>

Importieren wird zur Kompilierungszeit ausgeführt und hat daher keinen Einfluss auf dynamische Klassen-, Funktions- oder Konstantennamen.

Beispiel #3 Importieren und dynamische Namen

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // erzeugt ein Objekt der Klasse My\Full\Classname
    $a = 'Another';
    $obj = new $a;      // erzeugt ein Objekt der Klasse Another
    ?>

Zusätzlich beeinflusst das Importieren nur unqualifizierte und qualifizierte Namen. Vollständig qualifizierte Namen sind absolut und werden von Importen nicht beeinflusst.

Beispiel #4 Importieren und vollständig qualifizierte Namen

    <?php
    use My\Full\Classname as Another, My\Full\NSname;

    $obj = new Another; // erzeugt ein Objekt der Klasse My\Full\Classname
    $obj = new \Another; // erzeugt ein Objekt der Klasse Another
    $obj = new Another\thing; // erzeugt ein Objekt der Klasse My\Full\Classname\thing
    $obj = new \Another\thing; // erzeugt ein Objekt der Klasse Another\thing
    ?>

### Gültigkeitsbereiche für Importe

Das Schlüsselwort `use` muss im äußersten Gültigkeitsbereich (dem globalen Gültigkeitsbereich) oder innerhalb einer Namespace-Deklaration angegeben werden. Das ist darin begründet, dass Importe zur Kompilierungszeit und nicht zur Laufzeit durchgeführt werden und daher nicht in einem anderen Gültigkeitsbereich liegen dürfen. Das folgende Beispiel zeigt eine ungültige Verwendung des `use`-Schlüsselwortes:

Beispiel #5 Ungültige Importregel

    <?php
    namespace Languages;

    function toGreenlandic()
    {
        use Languages\Danish;

        // ...
    }
    ?>

> Hinweis:

> Importregeln sind auf Dateibasis gültig, das heißt eine eingebundene Datei wird NICHT die Importregeln der einbindenden Datei erben.

### Gruppierte `use` Deklarationen

Klassen, Funktionen und Konstanten, die aus dem gleichen Namespace importiert werden, in einer einzigen `use` Anweisung gruppiert werden.

    <?php

    use some\namespace\ClassA;
    use some\namespace\ClassB;
    use some\namespace\ClassC as C;

    use function some\namespace\fn_a;
    use function some\namespace\fn_b;
    use function some\namespace\fn_c;

    use const some\namespace\ConstA;
    use const some\namespace\ConstB;
    use const some\namespace\ConstC;

    // gleichbedeutend zu folgender gruppierter Use-Deklaration
    use some\namespace\{ClassA, ClassB, ClassC as C};
    use function some\namespace\{fn_a, fn_b, fn_c};
    use const some\namespace\{ConstA, ConstB, ConstC};

## Globaler Namensraum

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Ohne die Definition eines Namespace werden alle Klassen- und Funktionsdefinitionen im globalen Namensraum platziert, so wie dies auch in PHP geschah bevor Namespaces unterstützt wurden. Wenn man dem Namen ein `\` voranstellt, so spezifiziert man, dass der Name dem globalen Namensraum angehört, auch wenn man sich im Kontext eines Namensraumes befindet.

Beispiel #1 Verwenden der Spezifikation des globalen Namensraumes

    <?php
    namespace A\B\C;

    /* Diese Funktion ist A\B\C\fopen */
    function fopen() {
         /* ... */
         $f = \fopen(...); // globale Funktion fopen aufrufen
         return $f;
    }
    ?>

## Namespaces verwenden: Rückgriff auf den globalen Namespace für Funktionen und Konstanten

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Wenn PHP innerhalb eines Namespace auf einen unqualifizierten Namen für einen Klassen-, Funktions- oder Konstantennamen trifft, so werden diese mit unterschiedlichen Prioritäten aufgelöst. Klassennamen werden immer auf den aktuellen Namespace aufgelöst. Um also auf interne Klassen oder Benutzerklassen ohne Namespace zuzugreifen, muss man diese mit ihrem vollständig qualifizierten Namen ansprechen:

Beispiel #1 Zugriff auf globale Klasse innerhalb eines Namespace

    <?php
    namespace A\B\C;
    class Exception extends \Exception {}

    $a = new Exception('hi'); // $a ist ein Objekt der Klasse A\B\C\Exception
    $b = new \Exception('hi'); // $b ist ein Objekt der Klasse Exception

    $c = new ArrayObject; // fatal error, die Klasse A\B\C\ArrayObject konnte
                          // nicht gefunden werden
    ?>

Für Funktionen und Konstanten wird PHP auf globale Funktionen oder Konstanten zurückgreifen, wenn eine Funktion oder Konstante im Namespace nicht existiert.

Beispiel #2 Rückgriff auf globale Funktionen/Konstanten innerhalb eines Namespace

    <?php
    namespace A\B\C;

    const E_ERROR = 45;
    function strlen($str)
    {
        return \strlen($str) - 1;
    }

    echo E_ERROR, "\n"; // gibt "45" aus
    echo INI_ALL, "\n"; // gibt "7" aus - Rückgriff auf globale INI_ALL

    echo strlen('hi'), "\n"; // gibt "1" aus
    if (is_array('hi')) { // gibt "ist kein Array" aus
        echo "ist Array\n";
    } else {
        echo "ist kein Array\n";
    }
    ?>

## Regeln für Namensauflösung

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Hier einige wichtige Definitionen für die Zwecke der Namensauflösungsregeln:

Namespace-Namen-Definitionen
Unqualifizierter Name

  Dies ist ein Bezeichner ohne einen Namespaceseparator, z. B. `Foo`

Qualifizierter Name

  Dies ist ein Bezeichner mit einem Namespaceseparator, z. B. `Foo\Bar`

Vollständig qualifizierter Name

  Dies ist ein Bezeichner mit einem Namespaceseparator, der mit einem Namespaceseparator beginnt, z. B. `\Foo\Bar`. Der Namespace `namespace\Foo` ist ebenfalls ein vollständig qualifizierter Name.

Relativer Name

  Dies ist ein Bezeichner, der mit `namespace` beginnt, wie etwa `namespace\Foo\Bar`.

Namen werden gemäß den folgenden Regeln aufgelöst:

1. Vollständig qualifizierte Namens werden immer zu dem Namen ohne führenden Namensraumtrenner aufgelöst. `\A\B` wird z. B. zu `A\B` aufgelöst.
2. Relative Namen werden immer zu dem Namen aufgelöst, in dem `namespace` durch den aktuellen Namensraum ersetzt wurde. Taucht der Namen im globalen Geltungsbereich auf, wird das `namespace\`-Präfix entfernt. Beispielsweise wird `namespace\A` innerhalb des Namensraums `X\Y` zu `X\Y\A` aufgelöst. Derselbe Name im globalen Geltungsbereich wird zu `A` aufgelöst.
3. Für qualifizierte Namen wird das erste Segment des Namens gemäß der aktuellen Klassen-/Namensraum-Importtabelle übersetzt. Wird beispielsweise der Namensraum `A\B\C` als `C` importiert, wird der Name `C\D\E` zu `A\B\C\D\E` übersetzt.
4. Wenn für qualifizierte Namen keine Importregel zutrifft, wird der aktuelle Namensraum dem Namen vorangestellt. Beispielsweise wird der Name `C\D\E` innerhalb des Namensraums `A\B` zu `A\B\C\D\E` aufgelöst.
5. Für unqualifizierte Namen wird der Name gemäß der aktuellen Importtabelle für die betreffende Symboltabelle übersetzt. Das bedeutet, dass klassenartige Namen gemäß der Klassen-/Namensraum-Importtabelle, Funktionsnamen gemäß der Funktions-Importtabelle und Konstantennamen gemäß der Konstanten-Importtabelle übersetzt werden. Beispielsweise wird nach `use A\B\C;` eine Verwendung wie etwa `new C()` zum Namen `A\B\C()` aufgelöst. Analog wird nach `use function A\B\foo;` eine Verwendung wie etwa `foo()` zum Namen `A\B\foo` aufgelöst.
6. Wenn für unqualifizierte Namen keine Importregel zutrifft, und sich der Name auf ein klassenartiges Symbol bezieht, wird der aktuelle Namensraum vorangestellt. Beispielsweise wird `new C()` innerhalb des Namensraums `A\B` zum Namen `A\B\C` aufgelöst.
7. Wenn für unqualifizierte Namen keine Importregel zutrifft, und sich der Name auf eine Funktion oder Konstante bezieht, und der Code sich außerhalb des globalen Geltungsbereichs befindet, wird der Name zur Laufzeit aufgelöst. Angenommen der Code befindet sich im Namensraum `A\B`, wird im folgenden erläutert, wie der Aufruf einer Funktion `foo()` aufgelöst wird:
   1. Zuerst wird nach der Funktion im aktuellen Namespace gesucht: `A\B\foo()`.
   2. Es wird versucht, die Funktion `foo()` im globalen Namensraum zu finden und aufzurufen.

Beispiel #1 Illustration der Namensauflösung

    <?php
    namespace A;
    use B\D, C\E as F;

    // Funktionsaufrufe

    foo();      // versucht zuerst die Funktion "foo" im Namespace "A" aufzurufen
                // danach wird die globale Funktion "foo" aufgerufen

    \foo();     // ruft die Funktion "foo" im globalen Namensraum auf

    my\foo();   // ruft die Funktion "foo" im Namespace "A\my" auf

    F();        // versucht zuerst die Funktion "F" im Namespace "A" aufzurufen,
                // danach wird die globale Funktion "F" aufgerufen

    // Klassenreferenzen

    new B();    // erzeugt ein Objekt der Klasse "B" im Namespace "A"
                // wenn diese Klasse nicht bekannt ist, so wird versucht per
                //  Autoload die Klasse "A\B" zu laden

    new D();    // gemäß den Importregeln wird ein Objekt der Klasse "D"
                //  aus dem Namenspace "B" erzeugt
                // wenn diese Klasse nicht bekannt ist, so wird versucht per
                //  Autoload die Klasse "B\D" zu laden

    new F();    // gemäß den Importregeln wird ein Objekt der Klasse "E"
                //  aus dem Namespace "C" erzeugt
                // wenn diese Klasse nicht bekannt ist, so wird versucht per
                //  Autoload die Klasse "C\E" zu laden

    new \B();   // erzeugt ein Objekt der Klasse "B" aus dem globalen Namensraum
                // wenn diese Klasse nicht bekannt ist, so wird versucht per
                //  Autoload die Klasse "B" zu laden

    new \D();   // erzeugt ein Objekt der Klasse "D" aus dem globalen Namensraum
                // wenn diese Klasse nicht bekannt ist, so wird versucht per
                //  Autoload die Klasse "D" zu laden

    new \F();   // erzeugt ein Objekt der Klasse "F" aus dem globalen Namensraum
                // wenn diese Klasse nicht bekannt ist, so wird versucht per
                //  Autoload die Klasse "F" zu laden

    // statische Methoden und Funktionen mit Namespace aus anderen Namespaces

    B\foo();    // ruft die Funktion "foo" aus dem Namensraum "A\B" auf

    B::foo();   // ruft die Methode "foo" der Klasse "B" im Namensraum "A" auf
                // wenn die Klasse "A\B" nicht bekannt ist, so wird versucht
                //  die Klasse "A\B" mittels Autoload zu laden

    D::foo();   // ruft gemäß den Importregeln die Methode "foo" der Klasse "D"
                //  im Namensraum "B" auf
                // wenn die Klasse "B\D" nicht bekannt ist, so wird versucht
                //  die Klasse "B\D" mittels Autoload zu laden

    \B\foo();   // ruft die Funktion "foo" im Namespace "B" auf

    \B::foo();  // ruft die Methode "foo" der Klasse "B" im
               //   globalen Namensraum auf
                // wenn die Klasse "B" nicht bekannt ist, so wird versucht
                //  die Klasse "B" mittels Autoload zu laden

    // statische Methoden und Funktionen mit Namespace aus den gleichen Namespaces

    A\B::foo();   // ruft die Methode "foo" der Klasse "B" aus dem Namespace "A\A" auf
                  // wenn die Klasse "A\A\B" nicht bekannt ist, so wird
                  //  versucht die Klasse "A\A\B" mittels Autoload zu laden

    \A\B::foo();  // ruft die Methode "foo" der Klasse "B" aus dem Namespace "A" auf
                  // wenn die Klasse "A\B" nicht bekannt ist, so wird
                  //  versucht die Klasse "A\B" mittels Autoload zu laden
    ?>

## FAQ: Dinge, die Sie über Namespaces wissen sollten

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Diese häufig gestellten Fragen (FAQ) wurden in zwei Abschnitte aufgeteilt: allgemeine Fragen und einige Implementierungsdetails, deren vollständiges Verständnis hilfreich sein kann.

Zuerst die allgemeinen Fragen.

1. Wenn ich keine Namespaces verwende, sollte mich das alles hier überhaupt interessieren?
2. Wie verwende ich interne oder globale Klassen in einem Namespace?
3. Wie verwende ich Klassen, Funktionen oder Konstanten mit Namespaces in ihrem eigenen Namespace?
4. Wie wird ein Name wie `\mein\name` oder `\name` aufgelöst?
5. Wie wird ein Name wie `mein\name` aufgelöst?
6. Wie wird ein unqualifizierter Name wie `name` aufgelöst?
7. Wie wird ein unqualifizierter Funktions- oder Konstantenname wie `name` aufgelöst?

Es gibt einige Implementierungsdetails von Namespaces, deren Verständnis hilfreich ist.

1. Importierte Namen dürfen keine Konflikte mit Klassennamen in der gleichen Datei erzeugen.
2. Verschachtelte Namespaces sind nicht erlaubt.
3. Dynamische Namespacenamen sollten den Backslash escapen.
4. Zugriff auf undefinierte Konstanten mit Backslashes beendet das Skript mit einem fatal error.
5. Die speziellen Konstanten `null`, `true` und `false` können nicht überschrieben werden.

### Wenn ich keine Namespaces verwende, sollte mich das alles hier überhaupt interessieren?

Nein. Namespaces haben keinerlei Einfluss auf bereits bestehenden Code oder irgendwelchen Code der noch geschrieben wird, der keine Namespaces verwendet. Sie können folgenden Code schreiben, wenn Sie dies wünschen:

Beispiel #1 Zugriff auf globale Klassen außerhalb eines Namespace

    <?php
    $a = new \stdClass;
    ?>

Dies ist äquivalent zu:

Beispiel #2 Zugriff auf globale Klassen außerhalb eines Namespace

    <?php
    $a = new stdClass;
    ?>

### Wie verwende ich interne oder globale Klassen in einem Namespace?

Beispiel #3 Zugriff auf interne Klassen in Namespaces

    <?php
    namespace foo;
    $a = new \stdClass;

    function test(\ArrayObject $parameter_type_example = null) {}

    $a = \DirectoryIterator::CURRENT_AS_FILEINFO;

    // erben von einer internen oder globalen Klasse
    class MyException extends \Exception {}
    ?>

### Wie verwende ich Klassen, Funktionen oder Konstanten mit Namespaces in ihrem eigenen Namespace?

Beispiel #4 Zugriff auf interne Klassen, Funktionen oder Konstanten in Namespaces

    <?php
    namespace foo;

    class MyClass {}

    // verwendet eine Klasse des aktuellen Namensraumes als Parametertyp
    function test(MyClass $parameter_type_example = null) {}
    // eine andere Möglichkeit, eine Klasse des aktuellen Namensraums
    // als Parametertyp zu verwenden
    function test(\foo\MyClass $parameter_type_example = null) {}

    // ableiten von einer Klasse aus dem aktuellen Namespace
    class Extended extends MyClass {}

    // Zugriff auf eine globale Funktion
    $a = \globalfunc();

    // Zugriff auf eine globale Konstante
    $b = \INI_ALL;
    ?>

### Wie wird ein Name wie `\mein\name` oder `\name` aufgelöst?

Namen, die mit einem `\` beginnen, werden immer zu exakt dem aufgelöst wie sie aussehen. `\mein\name` ist also tatsächlich `\mein\name` und `\Exception` ist `Exception`.

Beispiel #5 Vollständig qualifizierte Namen

    <?php
    namespace foo;
    $a = new \my\name(); // erzeugt ein Objekt der Klasse "my\name"
    echo \strlen('hi'); // ruft die Funktion "strlen" auf
    $a = \INI_ALL; // $a wird auf den Wert der Konstante "INI_ALL" gesetzt
    ?>

### Wie wird ein Name wie `mein\name` aufgelöst?

Namen, die einen Backslash beinhalten, aber nicht mit einem Backslash beginnen, wie z. B. `mein\name`, können auf zwei verschiedene Arten aufgelöst werden.

Falls es einen Import-Ausdruck gibt, der einen Alias für einen anderen Namen definiert, so dass dieser `mein` heißen soll, dann wird dieser Alias für das `mein` in `mein\name` angewandt.

Andernfalls wird der aktuelle Namespace vor `mein\name` vorangestellt.

Beispiel #6 Qualifizierte Namen

    <?php
    namespace foo;
    use blah\blah as foo;

    $a = new my\name(); // erzeugt ein Objekt der Klasse "foo\my\name"
    foo\bar::name(); // ruft die statische Methode "name"
                     // der Klasse "blah\blah\bar" auf
    my\bar(); // ruft die Funktion "foo\my\bar" auf
    $a = my\BAR; // setzt $a auf den Wert der Konstante "foo\my\BAR"
    ?>

### Wie wird ein unqualifizierter Name wie `name` aufgelöst?

Klassennamen, die keinen Backslash beinhalten, wie z. B. `name`, können auf zwei Arten aufgelöst werden.

Falls es einen Import-Ausdruck gibt, der einen Alias für einen anderen Namen definiert, so dass dieser `name` heißen soll, dann wird dieser Alias angewandt.

Andernfalls wird der aktuelle Namespace `name` vorangestellt.

Beispiel #7 Unqualifizierter Klassennamen

    <?php
    namespace foo;
    use blah\blah as foo;

    $a = new name(); // erzeugt ein Objekt der Klasse "foo\name"
    foo::name(); // ruft die statische Methode "name" der Klasse "blah\blah" auf
    ?>

### Wie wird ein unqualifizierter Funktions- oder Konstantenname wie `name` aufgelöst?

Funktions- oder Konstantennamen, die keinen Backslash beinhalten, wie z. B. `name`, können auf zwei verschiedene Arten aufgelöst werden.

Zuerst wird der aktuelle Namespace dem `name` vorangestellt.

Wenn die Konstante oder Funktion `name` im aktuellen Namensraum nicht existiert, so wird die globale Konstante oder Funktion `name` verwendet, wenn sie existiert.

Beispiel #8 Unqualifizierte Funktions- oder Konstantennamen

    <?php
    namespace foo;
    use blah\blah as foo;

    const FOO = 1;

    function my() {}
    function foo() {}
    function sort(&$a)
    {
        \sort($a);
        $a = array_flip($a);
        return $a;
    }

    my(); // ruft "foo\my" auf
    $a = strlen('hi'); // ruft die globale Funktion "strlen" auf, weil
                       // foo\strlen nicht existiert
    $arr = array(1,3,2);
    $b = sort($arr); // ruft die Funktion "foo\sort" auf
    $c = foo(); // ruft die Funktion "foo\foo" auf - der Alias wird ignoriert

    $a = FOO; // setzt $a auf den Wert der Konstante "foo\FOO" -
              // der Alias wird ignoriert
    $b = INI_ALL; // setzt $b auf den Wert der globalen Konstante "INI_ALL"
    ?>

### Importierte Namen dürfen keine Konflikte mit Klassennamen in der gleichen Datei erzeugen.

Die folgende Kombination von Skripten ist gültig:

file1.php

    <?php
    namespace mein\zeug;
    class MyClass {}
    ?>

anderes.php

    <?php
    namespace anderes;
    class Ding {}
    ?>

file2.php

    <?php
    namespace mein\zeug;
    include 'file1.php';
    include 'anderes.php';

    use anderes\Ding as MyClass;
    $a = new MyClass; // erzeugt ein Objekt der Klasse "Ding"
                      // aus dem Namespace "anderes"
    ?>

Es gibt hier, trotzdem es eine Klasse `MyClass` im Namespace `mein\zeug` gibt, keinen Namenskonflikt, weil die Definition der Klasse `MyClass` sich in einer anderen Datei befindet. Das nächste Beispiel erzeugt hingegen einen fatal error wegen eines Namenskonflikts, weil `MyClass` in derselben Datei definiert wird, die auch den use-Ausdruck beinhaltet.

    <?php
    namespace mein\zeug;
    use anderes\Ding as MyClass;
    class MyClass {} // fatal error: Konflikt zwischen MyClass und import-Ausdruck
    $a = new MyClass;
    ?>

### Verschachtelte Namespaces sind nicht erlaubt.

PHP erlaubt das Verschachteln von Namespaces nicht.

    <?php
    namespace mein\zeug {
        namespace verschachtelt {
            class foo {}
        }
    }
    ?>

Es ist jedoch leicht möglich, verschachtelte Namespaces zu simulieren:

    <?php
    namespace mein\zeug\verschachtelt {
        class foo {}
    }
    ?>

### Dynamische Namespacenamen sollten den Backslash escapen.

Es ist wichtig zu bemerken, dass ein Backslash in Strings als Escape-Zeichen verwendet wird und daher immer verdoppelt werden sollte, wenn er in einem String verwendet wird. Andernfalls besteht das Risiko ungewollter Auswirkungen:

Beispiel #9 Gefahren von Namespacenamen in Strings mit doppelten Anführungszeichen

    <?php
    $a = "gefaehrlicher\name"; // \n ist in doppelten Anführungszeichen
                               // ein Zeilenumbruch!
    $obj = new $a;

    $a = 'ueberhaupt\nicht\gefaehrlich'; // hier gibt es keine Probleme
    $obj = new $a;
    ?>

Innerhalb eines Strings, der von einfachen Anführungszeichen umschlossen ist, ist es deutlich ungefährlicher, die Backslash-Escape-Sequenz zu verwenden. Es wird dennoch empfohlen, Backslashes in allen Strings zu escapen.

### Zugriff auf undefinierte Konstanten mit Backslashes beendet das Skript mit einem fatal error.

Jeder Zugriff auf eine Konstante mit unqualifiziertem Namen, wie `FOO`, wird eine Notice erzeugen, welche erklärt, dass PHP angenommen hat, dass `FOO` der Wert der Konstante sei. Jede Konstante, qualifiziert oder vollständig qualifiziert, deren Name einen Backslash enthält, wird einen fatal error hervorrufen, wenn sie nicht gefunden wurde.

Beispiel #10 Undefinierte Konstanten

    <?php
    namespace bar;
    $a = FOO; // notice - undefined constant "FOO" assumed "FOO";
    $a = \FOO; // fatal error, undefined namespace constant FOO
    $a = Bar\FOO; // fatal error, undefined namespace constant bar\Bar\FOO
    $a = \Bar\FOO; // fatal error, undefined namespace constant Bar\FOO
    ?>

### Die speziellen Konstanten `null`, `true` und `false` können nicht überschrieben werden.

Jeder Versuch, eine Konstante in einem Namespace zu definieren, die eine der speziellen, eingebauten Konstanten ist, wird einen fatal error hervorrufen.

Beispiel #11 Spezielle Konstanten

    <?php
    namespace bar;
    const NULL = 0; // fatal error;
    const true = 'stupid'; // ebenfalls fatal error;
    // etc.
    ?>

# Aufzählungen (Enum)

## Inhaltsverzeichnis

- Übersicht über Aufzählungen
- Grundlagen der Aufzählungen
- Wertgebundene Aufzählungen (Backed Enums)
- Aufzählungen und Methoden
- Aufzählungen und statische Methoden
- Aufzählungen und Konstanten
- Traits
- Enum-Werte in konstanten Ausdrücken
- Unterschiede zu Objekten
- Liste mit Werten
- Serialisierung
- Warum Enums nicht erweiterbar sind
- Beispiele

## Übersicht über Aufzählungen

(PHP 8 >= 8.1.0)

Aufzählungen, oder kurz "Enums", ermöglichen es einem Entwickler, benutzerdefinierte Typen mit einer begrenzten Anzahl möglicher Werte zu definieren. Dies kann besonders bei der Definition eines Domänenmodells hilfreich sein, da es ermöglicht, "ungültige Zustände nicht darzustellen".

Enums gibt es in vielen Programmiersprachen mit einer Vielzahl unterschiedlicher Eigenschaften. In PHP sind Enums eine besondere Art von Objekten. Die Enum selbst ist eine Klasse und jeder in ihr definierte Fall (Case) ist eine Instanz dieser Klasse. Das bedeutet, dass Enum-Fälle gültige Objekte sind und überall dort verwendet werden können, wo ein Objekt verwendet werden kann, einschließlich Typprüfungen.

Das bekannteste Beispiel für Aufzählungen ist der eingebaute Typ Boolean. Dies ist ein Aufzählungstyp mit den zulässigen Werten `true` und `false`. Enums ermöglichen es Entwicklern, ihre eigenen, beliebig robusten Aufzählungen zu definieren.

## Grundlagen der Aufzählungen

Enums sind ähnlich wie Klassen und teilen sich die gleichen Namensräume wie Klassen, Schnittstellen und Traits. Sie können auch auf die gleiche Weise automatisch geladen werden. Eine Enum definiert einen neuen Typ, der eine feste, begrenzte Anzahl von möglichen zulässigen Werten hat.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

Diese Deklaration erzeugt einen neuen Aufzählungstyp namens `Suit`, der genau vier zulässige Werte hat: `Suit::Hearts`, `Suit::Diamonds`, `Suit::Clubs`, und `Suit::Spades`. Variablen kann einer dieser zulässigen Werte zugewiesen werden. Eine Funktion kann gegen einen Aufzählungstyp typgeprüft werden; in diesem Fall dürfen nur Werte dieses Typs übergeben werden.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function pick_a_card(Suit $suit)
    {
        var_dump($suit);
    }

    $val = Suit::Diamonds;

    // OK
    pick_a_card($val);

    // OK
    pick_a_card(Suit::Clubs);

    // TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
    pick_a_card('Spades');

Eine Aufzählung kann null oder mehr `case`-Definitionen haben, wobei es kein Maximum gibt. Eine Aufzählung mit null Fällen ist zwar syntaktisch gültig, aber ziemlich nutzlos.

Für Aufzählungsfälle gelten die gleichen Syntaxregeln wie für jedes Label in PHP, siehe Konstanten.

Standardmäßig werden Fälle intern nicht mit einem skalaren Wert verknüpft. Das bedeutet, dass `Suit::Hearts` nicht gleich `"0"` ist. Stattdessen wird jeder Fall mit einem Singleton-Objekt mit diesem Namen verknüpft. Der folgende Code veranschaulicht dies:

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    $a = Suit::Spades;
    $b = Suit::Spades;

    if ($a === $b) {
        print "Suits match using ===\n";
    }

    if ($a instanceof Suit) {
        print "Suits match using instanceof\n";
    }

    if ($a !== 'Spades') {
        print "Suit does not match the string\n";
    }

Es bedeutet auch, dass Enum-Werte niemals `<` oder `>` sind, da diese Vergleiche bei Objekten keinen Sinn ergeben. Wenn Enum-Werte auf diese Weise verglichen werden, wird immer `false` zurückgegeben.

Eine solche Art von Fall, der keine zugehörigen Daten enthält, wird als "Pure Case" (reiner Fall) bezeichnet. Eine Enum, die nur reine Fälle enthält, wird als "Pure Enum" bezeichnet.

Alle Pure Cases werden als Instanzen ihres Enum-Typs implementiert. Der Enum-Typ wird intern als Klasse dargestellt.

Alle Fälle haben die schreibgeschützte Eigenschaft `name`, die den Namen des Falls selbst angibt, wobei zwischen Groß- und Kleinschreibung unterschieden wird.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    print Suit::Spades->name;
    // Gibt "Spades" aus

Wenn der Name eines Enum-Falls dynamisch ermittelt wird, ist es auch möglich, die Funktionen defined() und constant() zu verwenden, um zu prüfen, ob es den Enum-Fall gibt, bzw. diesen auszulesen. Davon wird jedoch abgeraten, da die Verwendung von Wertgebundene Aufzählungen (Backed Enums) die meisten Anwendungsfälle abdecken sollte.

## Wertgebundene Aufzählungen (Backed Enums)

Standardmäßig haben Enum-Fälle keine skalare Entsprechung. Es handelt sich einfach um Singleton-Objekte. In vielen Fällen ist es jedoch auch notwendig, einen Enum-Fall von einer Datenbank oder einem ähnlichen Datenspeicher zu lesen und in diese zu schreiben, sodass es sinnvoll ist, ein intern definiertes skalares (und damit einfach serialisierbares) Äquivalent zu haben.

Um für eine Aufzählung eine skalare Entsprechung zu definieren, wird folgende Syntax verwendet:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

Ein Fall, der eine skalare Entsprechung hat, wird als "Backed Case" bezeichnet, da er durch einen einfacheren Wert "unterstützt" wird. Eine Enum, die ausschließlich Backed Cases enthält, wird als "Backed Enum" bezeichnet. Eine Backed Enum kann nur Backed Cases enthalten. Eine Pure Enum kann nur Pure Cases enthalten.

Eine Backed Enum kann entweder durch den Typ `int` oder den Typ `string` unterstützt werden, wobei eine gegebene Aufzählung jeweils nur einen einzigen Typ unterstützt (d. h. der Vereinigungstyp `int|string` wird nicht unterstützt). Wenn eine Aufzählung als "skalar äquivalent" gekennzeichnet ist, müssen alle Fälle eine eindeutige, explizit definierte skalare Entsprechung haben. Es gibt keine automatisch generierten skalare Entsprechungen (z. B. fortlaufende Ganzzahlen). Backed Cases müssen eindeutig sein; zwei Backed Enum Cases dürfen nicht dieselbe skalare Entsprechung haben. Eine Konstante kann jedoch auf einen Fall verweisen und somit einen Alias erzeugen. Siehe Aufzählungskonstanten.

Die entsprechenden Werte können konstante skalare Ausdrücke sein. Vor PHP 8.2.0 mussten die Entsprechungen Literale sein oder literale Ausdrücke sein. Das bedeutet, dass Konstanten und Ausdrücke mit Konstanten nicht unterstützt wurden. Das heißt, `1 + 1` war erlaubt, aber `1 + SOME_CONST` war nicht erlaubt.

Backed Cases haben eine zusätzliche schreibgeschützte Eigenschaft, `value`, die der in der Definition angegebene Wert ist.

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    print Suit::Clubs->value;
    // Gibt "C" aus

Um sicherzustellen, dass die Eigenschaft `value` schreibgeschützt ist, kann eine Variable nicht als Referenz zugewiesen werden. Das bedeutet, dass Folgendes einen Fehler auslöst:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $suit = Suit::Clubs;
    $ref = &$suit->value;
    // Fatal Error: Cannot indirectly modify readonly property Suit::$value

Backed Enums implementieren die interne Schnittstelle BackedEnum, die zwei zusätzliche Methoden zur Verfügung stellt:

- `from(int|string): self` akzeptiert einen skalaren Wert und gibt den entsprechenden Enum-Fall zurück. Wird ein solcher nicht gefunden, löst das einen ValueError aus. Dies ist vor allem in Fällen nützlich, in denen der eingegebene Wert vertrauenswürdig ist und ein fehlender Enum-Wert als Fehler angesehen werden sollte, der die Anwendung abbricht.
- `tryFrom(int|string): ?self` akzeptiert einen skalaren Wert und gibt den entsprechenden Enum-Fall zurück. Wenn keiner gefunden wird, wird `null` zurückgegeben. Dies ist vor allem in Fällen nützlich, in denen der eingegebene Wert nicht vertrauenswürdig ist und der Aufrufer seine eigene Fehlerbehandlung oder Logik für Standardwerte implementieren möchte.

Die Methoden `from()` und `tryFrom()` folgen den Standardregeln für schwache bzw. starke Typisierung. Bei schwacher Typisierung ist die Übergabe einer Ganzzahl oder einer Zeichenkette zulässig und das System wandelt den Wert entsprechend um. Auch Gleitkommazahlen können übergeben werden und werden dann entsprechend umgewandelt. Im Modus der strengen Typisierung führt die Übergabe einer Ganzzahl an `from()` bei einer Enum mit Zeichenketten (oder umgekehrt) zu einem TypeError. Für Gleitkommazahlen gelten in allen Fällen die gleichen Typisierungsregeln. Bei allen anderen Typen wird in beiden Modi ein TypeError ausgelöst.

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    function get_stuff_from_database($id) {
        return [
            'suit' => 'S',
        ];
    }

    $record = get_stuff_from_database(42);
    print $record['suit'] . "\n";

    $suit = Suit::tryFrom('A') ?? Suit::Spades;
    // Ungültige Daten ergeben null, also wird stattdessen Suit::Spades verwendet.
    print $suit->value . "\n";

    $suit =  Suit::from('X');
    // Ungültige Daten führen zu einem ValueError: "X" is not a valid backing scalar value for enum Suit
    print $suit->value . "\n";

Die manuelle Definition der Methoden `cases()` oder `tryFrom()` führt bei einer Enum zu einem fatalen Fehler.

## Aufzählungen und Methoden

Enums (sowohl Pure Enums als auch Backed Enums) können Methoden enthalten und Schnittstellen implementieren. Wenn eine Enum eine Schnittstelle implementiert, dann akzeptiert eine Typüberprüfung für diese Schnittstelle auch alle Fälle dieser Enum.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit implements Colorful
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;

        // Erfüllt die Schnittstellenvereinbarung
        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }

        // Nicht Teil der Schnittstelle; das ist OK
        public function shape(): string
        {
            return "Rectangle";
        }
    }

    function paint(Colorful $c)
    {
       print $c->color() . "\n";
    }

    paint(Suit::Clubs);  // funktioniert

    print Suit::Diamonds->shape(); // gibt "Rectangle" aus

In diesem Beispiel haben alle vier Instanzen von `Suit` zwei Methoden: `color()` und `shape()`. In Bezug auf den aufrufenden Code und die Überprüfung des Typs verhalten sie sich genau wie jede andere Objektinstanz.

Bei einer Backed Enum erfolgt die Deklaration der Schnittstelle nach der Deklaration des zugehörigen Typs.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    enum Suit: string implements Colorful
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';

        // Erfüllt die Schnittstellenvereinbarung
        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }
    }

Innerhalb einer Methode wird die Variable `$this` definiert, die sich auf die Case-Instanz bezieht.

Die Methoden können beliebig komplex sein, geben aber in der Praxis normalerweise einen statischen Wert zurück oder ein match (Übereinstimmung) auf `$this`, um für verschiedene Fälle verschiedene Ergebnisse zu liefern.

In diesem Fall wäre es für die Datenmodellierung besser, auch einen Enum-Typ `SuitColor` mit den Werten Red und Black zu definieren und stattdessen diesen zurückzugeben, aber das würde dieses Beispiel verkomplizieren.

Die obige Hierarchie ähnelt logisch der folgenden Klassenstruktur (obwohl dies nicht der tatsächlich ausgeführte Code ist):

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    final class Suit implements UnitEnum, Colorful
    {
        public const Hearts = new self('Hearts');
        public const Diamonds = new self('Diamonds');
        public const Clubs = new self('Clubs');
        public const Spades = new self('Spades');

        private function __construct(public readonly string $name) {}

        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }

        public function shape(): string
        {
            return "Rectangle";
        }

        public static function cases(): array
        {
            // Unzulässige Methode, weil bei einer Enum keine benutzerdefinierte case()-Methode erlaubt ist.
            // Siehe auch Abschnitt "Werteliste".
        }
    }

Methoden können public, private oder protected sein, wobei private und protected praktisch gleichwertig sind, da Vererbung nicht erlaubt ist.

## Aufzählungen und statische Methoden

Enums können auch statische Methoden haben. In der Enum selbst werden statische Methoden hauptsächlich für alternative Konstruktoren verwendet, z. B.:

    <?php

    enum Size
    {
        case Small;
        case Medium;
        case Large;

        public static function fromLength(int $cm): self
        {
            return match (true) {
                $cm < 50 => self::Small,
                $cm < 100 => self::Medium,
                default => self::Large,
            };
        }
    }

    var_dump(Size::fromLength(50));

Statische Methoden können public, private oder protected sein, wobei private und protected praktisch gleichwertig sind, da Vererbung nicht erlaubt ist.

## Aufzählungen und Konstanten

Enums können Konstanten enthalten, die public, private oder protected sein können, wobei private und protected praktisch gleichwertig sind, da Vererbung nicht erlaubt ist.

Eine Enum-Konstante kann sich auf einen Enum-Fall beziehen:

    <?php

    enum Size
    {
        case Small;
        case Medium;
        case Large;

        public const Huge = self::Large;
    }

    var_dump(Size::Huge);

## Traits

Enums können Traits verwenden, die sich dann genauso verhalten wie in Klassen. Hierbei ist zu beachten, dass die in einer Enum verwendeten Traits keine Eigenschaften enthalten dürfen, sondern nur Methoden, statische Methoden und Konstanten. Ein Trait mit Eigenschaften führt zu einem fatalen Fehler.

    <?php

    interface Colorful
    {
        public function color(): string;
    }

    trait Rectangle
    {
        public function shape(): string
        {
            return "Rectangle";
        }
    }

    enum Suit implements Colorful
    {
        use Rectangle;

        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;

        public function color(): string
        {
            return match ($this) {
                Suit::Hearts, Suit::Diamonds => 'Red',
                Suit::Clubs, Suit::Spades => 'Black',
            };
        }
    }

    $suit = Suit::Spades;
    var_dump($suit->color());
    var_dump($suit->shape());

## Enum-Werte in konstanten Ausdrücken

Da die Fälle in der Enum selbst als Konstanten dargestellt werden, können sie in den meisten konstanten Ausdrücken als statische Werte verwendet werden: als Standardwerte für Eigenschaften, statische Variablen und Parameter und als globale Werte und Klassenkonstanten. Sie dürfen nicht in den Werten anderer Enum-Fälle verwendet werden, aber normale Konstanten können sich auf einen Enum-Fall beziehen.

Dagegen sind implizite Aufrufe magischer Methoden wie ArrayAccess in Enums in statischen oder konstanten Definitionen nicht erlaubt, da nicht absolut garantiert werden kann, dass der resultierende Wert deterministisch ist oder dass der Methodenaufruf frei von Seiteneffekten ist. Funktionsaufrufe, Methodenaufrufe und der Zugriff auf Eigenschaften sind in konstanten Ausdrücken weiterhin nicht erlaubt.

    <?php

    // Dies ist eine völlig zulässige Definition einer Enum.
    enum Direction implements ArrayAccess
    {
        case Up;
        case Down;

        public function offsetExists($offset): bool
        {
            return false;
        }

        public function offsetGet($offset): mixed
        {
            return null;
        }

        public function offsetSet($offset, $value): void
        {
            throw new Exception();
        }

        public function offsetUnset($offset): void
        {
            throw new Exception();
        }
    }

    class Foo
    {
        // Dies ist erlaubt.
        const DOWN = Direction::Down;

        // Dies ist unzulässig, da es nicht deterministisch sein kann.
        const UP = Direction::Up['short'];
        // Fatal error: Cannot use [] on enums in constant expression
    }

    // Dies ist völlig zulässig, da es kein konstanter Ausdruck ist.
    $x = Direction::Up['short'];
    var_dump("\$x is " . var_export($x, true));

    $foo = new Foo();

## Unterschiede zu Objekten

Obwohl Enums auf Klassen und Objekten aufgebaut sind, unterstützen sie nicht alle objektbezogenen Funktionen. Insbesondere dürfen Enum-Fälle keinen Zustand haben.

- Konstruktoren und Destruktoren sind nicht erlaubt.
- Vererbung wird nicht unterstützt; Enums dürfen weder erweitern noch erweitert werden.
- Statische oder Objekteigenschaften sind nicht erlaubt.
- Enum-Fälle dürfen nicht geklont werden, weil die Fälle Singleton-Instanzen sein müssen.
- Magische Methoden sind mit Ausnahme der unten aufgeführten nicht erlaubt.
- Enums müssen immer deklariert werden, bevor sie verwendet werden.

Folgende Objektfunktionalität ist verfügbar und verhält sich wie bei jedem anderen Objekt auch:

- Public, private und protected Methoden.
- Public, private und protected statische Methoden.
- Public, private, und protected Konstanten.
- Enums können eine beliebige Anzahl von Schnittstellen implementieren.
- Zu Enums und Fällen können Attribute hinzugefügt werden. Der Zielfilter `TARGET_CLASS` enthält auch die Enums selbst. Der Zielfilter `TARGET_CLASS_CONST` schließt die Enum-Fälle ein.
- Die magischen Methoden __call, __callStatic, und __invoke
- Die Konstanten `__CLASS__` und `__FUNCTION__` verhalten sich wie üblich.

Bei einem Enum-Typ entspricht die magische Konstante `::class` dem Namen des Typs einschließlich des Namensraums, genau wie bei einem Objekt. Bei einer Case-Instanz wird die magische Konstante `::class` ebenfalls nach dem Enum-Typ ausgewertet, da es sich um eine Instanz dieses Typs handelt.

Außerdem dürfen Enum-Fälle nicht direkt mit `new` oder mit ReflectionClass::newInstanceWithoutConstructor() instanziiert werden. Beides führt zu einem Fehler.

    <?php

    $clovers = new Suit();
    // Error: Cannot instantiate enum Suit

    $horseshoes = (new ReflectionClass(Suit::class))->newInstanceWithoutConstructor()
    // Error: Cannot instantiate enum Suit

## Liste mit Werten

Sowohl Pure Enums als auch Backed Enums implementieren eine interne Schnittstelle namens UnitEnum. `UnitEnum` enthält die statische Methode `cases()`. `cases()` gibt ein gepacktes Array mit allen definierten Fällen in der Reihenfolge zurück, in der sie deklariert wurden.

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());

    enum SuitBacked: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    var_dump(SuitBacked::cases());

Die manuelle Definition der Methode `cases()` führt bei einer Enum zu einem fatalen Fehler.

## Serialisierung

Aufzählungen werden anders serialisiert als Objekte. Insbesondere haben sie einen neuen Serialisierungscode `"E"`, der den Namen des Enum-Falls angibt. Die Deserialisierungsroutine ist dann in der Lage, diesen Code zu verwenden, um eine Variable auf den vorhandenen Singleton-Wert zu setzen. Dadurch ist Folgendes gewährleistet:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    Suit::Hearts === unserialize(serialize(Suit::Hearts));

    print serialize(Suit::Hearts);
    // E:11:"Suit:Hearts";

Wenn bei der Deserialisierung kein Enum und kein Fall gefunden wird, der mit einem serialisierten Wert übereinstimmt, wird eine Warnung ausgegeben und `false` zurückgegeben.

Wenn eine Pure Enum in JSON serialisiert wird, wird ein Fehler ausgelöst. Wenn eine Backed Enum in JSON serialisiert wird, wird sie nur durch ihren skalaren Wert im entsprechenden Typ dargestellt. Das Verhalten von beiden kann durch die Implementierung von JsonSerializable überschrieben werden.

Um Verwechslungen zu vermeiden, unterscheidet sich die Ausgabe bei print_r() leicht von der bei Objekten.

    <?php

    enum Foo
    {
        case Bar;
    }

    enum Baz: int
    {
        case Beep = 5;
    }

    print_r(Foo::Bar);
    print_r(Baz::Beep);

    /* Ergibt

    Foo Enum (
        [name] => Bar
    )
    Baz Enum:int {
        [name] => Beep
        [value] => 5
    }
    */

## Warum Enums nicht erweiterbar sind

Klassen haben Vereinbarungen bezüglich ihrer Methoden:

    <?php

    class A {}
    class B extends A {}

    function foo(A $a) {}

    function bar(B $b)
    {
        foo($b);
    }

Dieser Code ist typsicher, da B der Vereinbarung von A folgt, und die Magie der Ko-/Kontra-Varianz sicherstellt, dass bis auf Exceptions alle an die Methoden gestellten Erwartungen erfüllt werden.

Enums haben Vereinbarungen über ihre Fälle, nicht über ihre Methoden:

    <?php

    enum ErrorCode
    {
        case SOMETHING_BROKE;
    }

    function quux(ErrorCode $errorCode)
    {
        // Mit diesem Code werden offenbar alle Fälle abgedeckt
        match ($errorCode) {
            ErrorCode::SOMETHING_BROKE => true,
        };
    }

Die Anweisung match in der Funktion `quux` kann statisch analysiert werden, um alle Fälle in ErrorCode abzudecken.

Aber angenommen, es wäre erlaubt, Enums zu erweitern:

    <?php

    // Ein gedankliches Code-Experiment, bei dem Enums nicht final sind.
    // Es ist zu beachten, dass dies in PHP nicht funktioniert.
    enum MoreErrorCode extends ErrorCode
    {
        case PEBKAC;
    }

    function fot(MoreErrorCode $errorCode)
    {
        quux($errorCode);
    }

    fot(MoreErrorCode::PEBKAC);

Nach den normalen Vererbungsregeln besteht eine Klasse, die eine andere Klasse erweitert, die Typprüfung.

Das Problem besteht darin, dass die Anweisung match in `quux()` nicht mehr alle Fälle abdeckt. Da sie `MoreErrorCode::PEBKAC` nicht kennt, löst der Abgleich eine Exception aus.

Aus diesem Grund sind Enums final und können nicht erweitert werden.

## Beispiele

Beispiel #1 Grundlegende eingeschränkte Werte

    <?php

    enum SortOrder
    {
        case Asc;
        case Desc;
    }

    function query($fields, $filter, SortOrder $order = SortOrder::Asc)
    {
         /* ... */
    }

Die Funktion `query()` kann nun mit der Gewissheit fortfahren, dass `$order` garantiert entweder `SortOrder::Asc` oder `SortOrder::Desc` ist. Jeder andere Wert hätte zu einem TypeError geführt, sodass keine weitere Fehlerkontrolle oder Prüfung erforderlich ist.

Beispiel #2 Erweiterte exklusive Werte

    <?php

    enum UserStatus: string
    {
        case Pending = 'P';
        case Active = 'A';
        case Suspended = 'S';
        case CanceledByUser = 'C';

        public function label(): string
        {
            return match ($this) {
                self::Pending => 'Pending',
                self::Active => 'Active',
                self::Suspended => 'Suspended',
                self::CanceledByUser => 'Canceled by user',
            };
        }
    }

    $status = UserStatus::Suspended;
    var_dump($status->label());

In diesem Beispiel kann der Status eines Benutzers einer der folgenden sein: `UserStatus::Pending`, `UserStatus::Active`, `UserStatus::Suspended` oder `UserStatus::CancledByUser`. Eine Funktion kann als Parameter `UserStatus` angeben und akzeptiert dann nur diese vier Werte, Punkt.

Alle vier Werte haben eine `label()`-Methode, die eine von Menschen lesbare Zeichenkette zurückgibt. Diese Zeichenkette ist unabhängig von der skalaren Zeichenkette "machine name", die z. B. in der Spalte einer Datenbank oder in einem HTML-Auswahlfeld verwendet werden kann.

    <?php

    enum UserStatus: string
    {
        case Pending = 'P';
        case Active = 'A';
        case Suspended = 'S';
        case CanceledByUser = 'C';

        public function label(): string
        {
            return match ($this) {
                self::Pending => 'Pending',
                self::Active => 'Active',
                self::Suspended => 'Suspended',
                self::CanceledByUser => 'Canceled by user',
            };
        }
    }

    foreach (UserStatus::cases() as $case) {
        printf(
            "<option value=\"%s\">%s</option>\n",
            htmlentities($case->value),
            htmlentities($case->label())
        );
    }

# Fehler

## Inhaltsverzeichnis

- Basics
- Fehler in PHP 7

## Einführung

Schade, aber wahr: egal wie vorsichtig wir unseren Code schreiben, Fehler sind ein Teil des Lebens. PHP zeigt Fehler, Warnungen und Hinweise für viele gängige Programmier- und Laufzeitprobleme an, und zu wissen, wie man diese erkennt und behandelt, macht das Debuggen viel einfacher.

## Basics

PHP meldet Fehler als Reaktion auf eine Reihe von internen Fehlerzuständen. Diese können verwendet werden, um eine Reihe von verschiedenen Zuständen zu signalisieren, und können nach Bedarf angezeigt und/oder protokolliert werden.

Jeder Fehler, den PHP erzeugt, beinhaltet einen Typ. Eine Liste dieser Fehlertypen ist verfügbar, zusammen mit einer kurzen Beschreibung ihres Verhaltens und wie sie hervorgerufen werden können.

### Fehlerbehandlung mit PHP

Wenn keine Funktion zur FehlerBehandlung bestimmt wurde, behandelt PHP alle auftretenden Fehler gemäß seiner Konfiguration. Welche Fehler berichtet und welche ignoriert werden wird dabei durch die Anweisung `error_reporting` in der php.ini oder zur Laufzeit durch den Aufruf von error_reporting() kontrolliert. Es wird dringend empfohlen, dass die Konfigurationsanweisung gesetzt werden, da einige Fehler auftreten können, bevor die Ausführung des Skripts beginnt.

In einer Entwicklungsumgebung sollte `error_reporting` immer auf den Wert `E_ALL` eingestellt werden, damit man auf alle von PHP festgestellten Probleme aufmerksam gemacht wird und diese korrigieren kann. In einer Produktivumgebung würde man dies auf einen weniger geschwätzigen Wert wie etwa `E_ALL & ~E_NOTICE & ~E_DEPRECATED` einstellen, wobei aber in vielen Fällen `E_ALL` ebenfalls angemessen ist, da es eine Frühwarnung für potentielle Probleme anbieten kann.

Wie PHP mit diesen Fehlern weiter fortfährt, hängt von zwei weiteren Anweisungen in php.ini ab. `display_errors` kontrolliert, ob ein Fehler als Teil der Ausgabe des Skriptes angezeigt wird. Dies sollte in einer Produktivumgebung immer abgestellt werden, da es sensible Informationen wie beispielsweise Datenbankzugangsdaten beinhalten kann, aber in Entwicklungsumgebungen ist es oft hilfreich dies einzuschalten, da es eine sofortige Berichterstattung über Probleme sicherstellt.

Zusätzlich zum Anzeigen von Fehlern kann PHP die Fehler protokollieren, wenn die Anweisung `log_errors` aktiviert ist. Damit werden alle Fehler in die Datei oder Syslog protokolliert, welche durch die Anweisung `error_log` eingestellt ist. Dies kann in Produktivumgebungen sehr hilfreich sein, da damit auftretende Fehler protokolliert und daraus hilfreiche Berichte erzeugt werden können.

### Benutzerdefinierte Fehlerbehandlung

Wenn die standardmäßige Fehlerbehandlung von PHP nicht ausreichend ist, kann man außerdem viele Arten von Fehlern mit einer eigenen Funktion zur Fehlerbehandlung verarbeiten, in dem man diese mittels set_error_handler() einrichtet. Während manche Arten von Fehlern damit nicht verarbeitet werden können, kann ein Skript diejenigen die behandelt werden können damit so behandeln wie es am sinnvollsten erscheint: Beispielsweise kann dies benutzt werden, um dem Benutzer eine angepasste Fehlerseite anzuzeigen und anschließend über den Fehler direkter als nur durch ein Protokoll zu berichten, zum Beispiel durch das Senden einer E-Mail.

## Fehler in PHP 7

PHP 7 verändert, wie die meisten Fehler durch PHP berichtet werden. Anstatt Fehler durch den traditionellen Berichterstattungsmechanismus, der durch Php 5 verwendet wurde, zu berichten, werden die meisten Fehler nun durch das Werfen einer Error-Ausnahme berichtet.

Wie auch normale Ausnahmen, werden diese Error-Ausnahmen so lange nach oben weiter gereicht bis sie einen ersten passenden `catch`-Block erreichen. Wenn es keinen passenden Block gibt, wird der standardmäßige Exception-Handler, der durch set_exception_handler() eingerichtet werden kann, aufgerufen und wenn es keinen standardmäßigen Exception-Handler gibt wird die Ausnahme in einen fatalen Fehler umgewandelt und diese wie ein traditioneller Fehler behandelt.

Da die Error-Hierarchie nicht von Exception abgeleitet ist, wird Code der `catch (Exception $e) { ... }`-Blöcke zur Behandlung von ungefangenen Ausnahmen in PHP 5 verwendet feststellen, dass Error nicht durch diese Blöcke gefangen werden. Dazu wird entweder ein `catch (Error $e) { ... }`-Block oder ein durch set_exception_handler() gesetzter Handler benötigt.

### Error-Hierarchie

- Throwable
  - Error
    - ArithmeticError
      - DivisionByZeroError
    - AssertionError
    - CompileError
      - ParseError
    - TypeError
      - ArgumentCountError
    - ValueError
    - UnhandledMatchError
    - FiberError
    - RequestParseBodyException
  - Exception
    - ...

# Exceptions (Ausnahmen)

## Inhaltsverzeichnis

- Exceptions erweitern

> Hinweis: Siehe auch die Klasse Exception

PHP hat ein Exceptionmodell ähnlich dem anderer Programmiersprachen. Eine Exception kann in PHP geworfen (`throw`) und abgefangen (`catch`) werden. Um das Abfangen potentieller Exceptions zu ermöglichen, sollte der jeweilige Code von einem `try`-Block umschlossen werden. Jeder `try`-Block muss mindestens einen zugehörigen `catch`- oder `finally`-Block besitzen.

Wenn eine Exception geworfen wird und der aktuelle Funktionsbereich keinen `catch`-Block hat, steigt die Exception im Aufrufstapel bis zur aufrufenden Funktion auf, bis sie einen passenden `catch`-Block findet. Alle `finally`-Blöcke, auf die sie unterwegs trifft, werden ausgeführt. Wenn der Aufrufstapel bis in den globalen Bereich abgewickelt ist, ohne auf einen passenden `catch`-Block zu stoßen, bricht das Programm mit einem fatalen Fehler ab, es sei denn, es wurde ein globaler Exception-Handler gesetzt.

Das geworfene Objekt muss eine Instanz von (`instanceof`) Throwable sein. Der Versuch ein Objekt werfen, das das nicht ist, wird einen fatalen PHP-Fehler zur Folge haben.

Seit PHP 8.0.0 ist das Schlüsselwort `throw` ein Ausdruck und kann in jedem Ausdruckskontext verwendet werden. In früheren Versionen war es eine Anweisung und musste in einer eigenen Zeile stehen.

## `catch`

Ein `catch`-Block definiert, wie auf eine geworfene Exception reagiert werden soll. Ein `catch`-Block definiert eine oder mehrere Arten von Exceptions oder Fehlern, die er behandeln kann, und optional eine Variable, der die Exception zugewiesen werden soll (vor PHP 8.0.0 war die Variable erforderlich). Der erste `catch`-Block, auf den eine geworfene Exception oder ein Fehler trifft, der mit dem Typ des geworfenen Objekts übereinstimmt, behandelt das Objekt.

Mehrere `catch`-Blöcke können verwendet werden, um verschiedene Klassen von Exceptions abzufangen. Wenn innerhalb des `try`-Blocks keine Exception geworfen wird, wird die normale Programmausführung nach dem letzten in Folge definierten `catch`-Block fortgesetzt. Exceptions können innerhalb eines `catch`-Blocks geworfen (oder erneut geworfen) werden. Falls nicht, wird die Ausführung nach dem `catch`-Block, der geworfen wurde, fortgesetzt.

Wenn eine Exception geworfen wird, führt PHP den Programmcode hinter der werfenden Anweisung nicht aus, sondern versucht, den ersten passenden `catch`-Block zu finden. Falls eine Exception nicht abgefangen wird, wird ein fataler Fehler mit einer "`Uncaught Exception ...`"-Nachricht ausgegeben, sofern keine Behandlung mittels set_exception_handler() definiert wurde.

Seit PHP 7.1.0 kann ein `catch`-Block mehrere Exceptions getrennt durch Pipe-Zeichen (`|`) angeben. Dies ist nützlich, wenn unterschiedliche Exceptions von unterschiedlichen Klassenhierarchien gleich behandelt werden sollen.

Seit PHP 8.0.0 ist der Variablenname für eine abgefangene Exception optional. Wird er nicht angegeben, wird der `catch`-Block trotzdem ausgeführt, hat aber keinen Zugriff auf das geworfene Objekt.

## `finally`

Ein `finally`-Block kann auch nach den `catch`-Blöcken oder stattdessen definiert werden. Egal, ob eine Exception geworfen wurde, wird der Code innerhalb des `finally`-Blocks immer nach den `try`- und `catch`-Blöcken ausgeführt, bevor die normale Ausführung fortgesetzt wird.

Eine bemerkenswerte Wechselwirkung besteht zwischen dem `finally`-Block und einer `return`-Anweisung. Wird eine `return`-Anweisung innerhalb der `try`- oder `catch`-Blöcke angetroffen, wird der `finally`-Block dennoch ausgeführt. Außerdem wird die `return`-Anweisung ausgewertet, wenn sie angetroffen wird, aber das Ergebnis wird erst nach dem `finally`-Block zurückgegeben. Des Weiteren wird, wenn der `finally`-Block ebenfalls eine `return`-Anweisung enthält, der Wert aus dem `finally`-Block zurückgegeben.

Eine weitere bemerkenswerte Wechselwirkung tritt auf, wenn sowohl im `try`- als auch im `finally`-Block eine Exception geworfen wird. In diesem Fall wird die vom `finally`-Block geworfene Exception weitergegeben, während die vom `try`-Block geworfene Exception als deren vorherige Exception verwendet wird.

## Der globale Exception-Handler

Wenn eine Exception in den globalen Bereich aufsteigen darf, kann sie durch einen globalen Exception-Handler abgefangen werden, falls gesetzt. Die Funktion set_exception_handler() kann eine Funktion festlegen, die anstelle eines `catch`-Blocks aufgerufen wird, wenn kein anderer Block aufgerufen wird. Der Effekt ist im Wesentlichen derselbe, als ob das gesamte Programm in einen `try`-`catch`-Block mit dieser Funktion als `catch` verpackt wäre.

## Anmerkungen

> Hinweis:

> Interne PHP-Funktionen verwenden in den meisten Fällen Error-Reporting, nur moderne objektorientierte Erweiterungen nutzen Exceptions. Fehler können allerdings einfach mittels ErrorException in eine Exception umgewandelt werden. Diese Technik funktioniert jedoch nur bei nicht-fatalen Fehlern.

> Beispiel #1 Fehlermeldungen in Exceptions umwandeln

>     <?php
>     function exceptions_error_handler($severity, $message, $filename, $lineno) {
>         throw new ErrorException($message, 0, $severity, $filename, $lineno);
>     }

>     set_error_handler('exceptions_error_handler');

Tipp

Die Standard PHP Library (SPL) bietet eine große Anzahl eingebauter Exceptions.

## Beispiele

Beispiel #2 Eine Exception werfen

    <?php
    function inverse($x) {
        if (!$x) {
           throw new Exception('Division durch Null.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Exception abgefangen: ',  $e->getMessage(), "\n";
    }

    // Ausführung fortsetzen
    echo "Hallo Welt\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0.2
    Exception abgefangen: Division durch Null
    Hallo Welt

Beispiel #3 Exceptionbehandlung mit einem `finally`-Block

    <?php
    function inverse($x) {
        if (!$x) {
            throw new Exception('Division durch Null.');
        }
        return 1/$x;
    }

    try {
        echo inverse(5) . "\n";
    } catch (Exception $e) {
        echo 'Exception abgefangen: ',  $e->getMessage(), "\n";
    } finally {
        echo "Erstes finally.\n";
    }

    try {
        echo inverse(0) . "\n";
    } catch (Exception $e) {
        echo 'Exception abgefangen: ',  $e->getMessage(), "\n";
    } finally {
        echo "Zweites finally.\n";
    }

    // Ausführung fortsetzen
    echo "Hallo Welt\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0.2
    Erstes finally.
    Exception abgefangen: Division durch Null.
    Zweites finally.
    Hallo Welt

Beispiel #4 Wechselwirkung zwischen dem `finally`-Block und `return`

    <?php

    function test() {
        try {
            throw new Exception('foo');
        } catch (Exception $e) {
            return 'catch';
        } finally {
            return 'finally';
        }
    }

    echo test();

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    finally

Beispiel #5 Verschachtelte Exceptions

    <?php

    class MyException extends Exception { }

    class Test {
        public function testing() {
            try {
                try {
                    throw new MyException('foo!');
                } catch (MyException $e) {
                    // Exception erneut werfen
                    throw $e;
                }
            } catch (Exception $e) {
                var_dump($e->getMessage());
            }
        }
    }

    $foo = new Test;
    $foo->testing();

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(4) "foo!"

Beispiel #6 Behandlung mehrerer Exceptions in einem Catch-Block

    <?php

    class MyException extends Exception { }

    class MyOtherException extends Exception { }

    class Test {
        public function testing() {
            try {
                throw new MyException();
            } catch (MyException | MyOtherException $e) {
                var_dump(get_class($e));
            }
        }
    }

    $foo = new Test;
    $foo->testing();

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(11) "MyException"

Beispiel #7 Catch-Block ohne Angabe einer Variablen

Erst ab PHP 8.0.0 erlaubt.

    <?php

    class SpecificException extends Exception {}

    function test() {
        throw new SpecificException('Oopsie');
    }

    try {
        test();
    } catch (SpecificException) {
        print "Eine SpecificException wurde geworfen, aber die Details interessieren uns nicht.";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Eine SpecificException wurde geworfen, aber die Details interessieren uns nicht.

Beispiel #8 Als Ausdruck werfen

Erst ab PHP 8.0.0 erlaubt.

    <?php

    function test() {
        do_something_risky() or throw new Exception('Es hat nicht funktioniert');
    }

    function do_something_risky() {
        return false; // Fehler simulieren
    }

    try {
        test();
    } catch (Exception $e) {
        print $e->getMessage();
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Es hat nicht funktioniert

Beispiel #9 Exception in try und in finally

    <?php

    try {
        try {
            throw new Exception(message: 'Dritte', previous: new Exception('Vierte'));
        } finally {
            throw new Exception(message: 'Erste', previous: new Exception('Zweite'));
        }
    } catch (Exception $e) {
        var_dump(
            $e->getMessage(),
            $e->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getPrevious()->getMessage(),
        );
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(5) "Erste"
    string(6) "Zweite"
    string(5) "Dritte"
    string(6) "Vierte"

## Exceptions erweitern

Eine benutzerdefinierte Exceptionklasse kann durch Ableitung von der eingebauten Exceptionklasse erstellt werden. Die unten angegebenen Methoden und Eigenschaften zeigen, was innerhalb der Kindklasse von der eingebauten Exceptionklasse verfügbar ist.

Beispiel #1 Die eingebaute Exceptionklasse

    <?php
    class Exception implements Throwable
    {
        protected $message = 'Unknown exception';   // Exceptionmitteilung
        private   $string;                          // __toString-Cache
        protected $code = 0;                        // Benutzerdefinierte Fehlernummer
        protected $file;                            // Quelldateiname der Exception
        protected $line;                            // Quelldateizeile der Exception
        private   $trace;                           // Rückverfolgung
        private   $previous;                        // Vorherige Exception, falls verschachtelte Exception

        public function __construct($message = '', $code = 0, ?Throwable $previous = null);

        final private function __clone();           // Verhindert klonen von Exceptions

        final public  function getMessage();        // Mitteilung der Exception
        final public  function getCode();           // Fehlercode der Exception
        final public  function getFile();           // Quelldateiname
        final public  function getLine();           // Quelldateizeile
        final public  function getTrace();          // Array zum Rückverfolgen
        final public  function getPrevious();       // Vorherige Exception
        final public  function getTraceAsString();  // Formatierter String der Rückverfolgung

        // Überschreibbar
        public function __toString();               // Formatierter String für die Ausgabe
    }

Wenn eine Klasse die eingebaute Exceptionklasse erweitert und den Konstruktor neu definiert, ist es dringend empfohlen, dass der Konstruktor der Klasse parent::__construct() aufruft, um sicherzustellen, dass alle verfügbaren Daten korrekt zugewiesen wurden. Die __toString()-Methode kann überschrieben werden, um eine benutzerdefinierte Ausgabe anzubieten, wenn das Objekt durch eine Zeichenkette repräsentiert werden soll.

> Hinweis:

> Exceptions können nicht geklont werden. Der Versuch, eine Exception zu klonen, wird einen fatalen `E_ERROR`-Fehler zur Folge haben.

Beispiel #2 Die Exceptionklasse erweitern

    <?php
    /**
     * Eine eigene Exceptionklasse definieren
     */
    class MyException extends Exception
    {
        // Die Exception neu definieren, damit die Mitteilung nicht optional ist
        public function __construct($message, $code = 0, ?Throwable $previous = null) {
            // etwas Code

            // sicherstellen, dass alles korrekt zugewiesen wird
            parent::__construct($message, $code, $previous);
        }

        // benutzerdefinierte Stringdarstellung des Objektes
        public function __toString() {
            return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
        }

        public function customFunction() {
            echo "Eine eigene Funktion für diesen Exceptiontyp\n";
        }
    }

    /**
     * Erzeuge eine Klasse, um die Exception zu testen
     */
    class TestException
    {
        public $var;

        const THROW_NONE    = 0;
        const THROW_CUSTOM  = 1;
        const THROW_DEFAULT = 2;

        function __construct($avalue = self::THROW_NONE) {

            switch ($avalue) {
                case self::THROW_CUSTOM:
                    // eigene Exception werfen
                    throw new MyException('1 ist ein ungültiger Parameter', 5);
                    break;

                case self::THROW_DEFAULT:
                    // Vorgabe werfen
                    throw new Exception('2 ist kein zugelassener Parameter', 6);
                    break;

                default:
                    // Keine Exception; das Objekt wird erzeugt
                    $this->var = $avalue;
                    break;
            }
        }
    }

    echo "# Beispiel 1\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (MyException $e) {      // Wird gefangen
        echo "Meine Exception gefangen\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // Übersprungen
        echo "Standardexception gefangen\n", $e;
    }

    // Ausführung fortsetzen
    var_dump($o); // Null

    echo "\n\n# Beispiel 2\n";
    try {
        $o = new TestException(TestException::THROW_DEFAULT);
    } catch (MyException $e) {      // Dieser Typ passt nicht
        echo "Meine Exception gefangen\n", $e;
        $e->customFunction();
    } catch (Exception $e) {        // Wird gefangen
        echo "Standardexception gefangen\n", $e;
    }

    // Ausführung fortsetzen
    var_dump($o); // Null

    echo "\n\n# Beispiel 3\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (Exception $e) {        // Wird gefangen
        echo "Standardexception gefangen\n", $e;
    }

    // Ausführung fortsetzen
    var_dump($o); // Null

    echo "\n\n# Beispiel 4\n";
    try {
        $o = new TestException();
    } catch (Exception $e) {        // Übersprungen, keine Exception geworfen
        echo "Standardexception gefangen\n", $e;
    }

    // Ausführung fortsetzen
    var_dump($o); // TestException

# Fibers

### Übersicht über Fibers

(PHP 8 >= 8.1.0)

Fibers stellen unterbrechbare Funktionen dar, die den gesamten Aufrufstapel (Call-Stack) umfassen. Sie können an jeder Stelle des Aufrufstapels unterbrochen werden, wobei die Ausführung innerhalb der Fiber solange unterbrochen wird, bis die Fiber zu einem späteren Zeitpunkt fortgesetzt wird.

Fibers halten den gesamten Ausführungsstapel an, sodass der direkte Aufrufer der Funktion nicht ändern muss, wie er die Funktion aufruft.

Mit Fiber::suspend() kann die Ausführung an jeder Stelle im Aufrufstapel unterbrochen werden (d. h. der Aufruf von Fiber::suspend() kann in einer tief verschachtelten Funktion liegen oder auch gar nicht existieren).

Im Gegensatz zu einem Generator, der keinen Stapel hat, hat jede Fiber ihren eigenen Aufrufstapel, sodass sie innerhalb tief verschachtelter Funktionsaufrufe unterbrochen werden kann. Im Gegensatz zu einer Funktion, die `yield` verwendet und eine Generator-Instanz zurückgeben muss, muss eine Funktion, die einen Unterbrechungspunkt deklariert (d. h. Fiber::suspend() aufruft), ihren Rückgabetyp nicht ändern.

Fibers können beim Aufruf einer beliebigen Funktion unterbrochen werden. Dies gilt auch für Funktionen, die innerhalb der PHP-VM aufgerufen werden, z. B. Funktionen, die an array_map() übergeben werden oder Methoden eines Iterator-Objekts, die von `foreach` aufgerufen werden.

Sobald die Ausführung einer Fiber unterbrochen wurde, kann sie wieder aufgenommen werden, indem ein beliebiger Wert an Fiber::resume() übergeben wird oder indem Fiber::throw() verwendet wird, um eine Exception an die Fiber zu senden. Bei der Wiederaufnahme wird von Fiber::suspend() ein Wert zurückgegeben (oder es wird eine Exception ausgelöst).

> Hinweis: Vor PHP 8.4.0 war es nicht erlaubt, Fibers während der Ausführung eines Objekt-Destruktors zu schalten.

Beispiel #1 Grundlegende Verwendung

    <?php
    $fiber = new Fiber(function (): void {
       $value = Fiber::suspend('fiber');
       echo "Der Wert für die Wiederaufnahme der Fiber: ", $value, PHP_EOL;
    });

    $value = $fiber->start();

    echo "Der Wert vom Unterbrechen der Fiber: ", $value, PHP_EOL;

    $fiber->resume('test');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Der Wert vom Unterbrechen der Fiber: fiber
    Der Wert für die Wiederaufnahme der Fiber: test

# Generatoren

## Inhaltsverzeichnis

- Generatoren-Übersicht
- Generator-Syntax
- Vergleich von Generatoren mit Iterator-Objekten

## Generatoren-Übersicht

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generatoren bieten eine einfache Möglichkeit, um einfache Iteratoren zu erstellen, ohne den Overhead oder die Komplexität der Erstellung einer Klasse zu haben, die das Iterator-Interface implementiert.

Mit einem Generator können auf bequeme Weise Daten für `foreach` -Schleifen bereitgestellt werden, ohne ein Array im Speicher zu erzeugen, was dazu führen kann, dass das Programm ein Speicherlimit überschreitet oder beträchtliche Prozessorzeit benötigt. Alternativ kann eine Generatorfunktion verwendet werden, die einer normalen Funktion entspricht, bei der aber keine einmalige Rückgabe erfolgt, sondern der Generator so oft wie nötig einen Wert abgibt (Stichwort: `yield`), um die Werte zu liefern, über die iteriert werden soll. Wie bei Iteratoren ist ein wahlfreier Datenzugriff nicht möglich.

Ein einfaches Beispiel dazu ist, die range()-Funktion durch einen Generator neu zu implementieren. Die Standard-range()-Funktion generiert und liefert Arrays, welche jeden Wert enthalten, was große Arrays zur Folge haben kann: zum Beispiel hat der Aufruf range(0, 1000000) zur Folge, dass weit über 100 MB an Speicher benötigt werden.

Als Alternative können wir einen `xrange()`-Generator implementieren, welcher immer nur genug Speicher benötigt, um ein Iterator-Objekt zu erzeugen und intern den aktuellen Zustand des Generators zu verfolgen, was sich als weniger als 1 Kilobyte herausstellt.

Beispiel #1 Implementierung von range() als Generator

    <?php
    function xrange($start, $limit, $step = 1) {
        if ($start <= $limit) {
            if ($step <= 0) {
                throw new LogicException('Schrittweite muss positiv sein');
            }

            for ($i = $start; $i <= $limit; $i += $step) {
                yield $i;
            }
        } else {
            if ($step >= 0) {
                throw new LogicException('Schrittweite muss negativ sein');
            }

            for ($i = $start; $i >= $limit; $i += $step) {
                yield $i;
            }
        }
    }

    /*
     * Hinweis: sowohl range() als auch xrange()
     * erzeugen die gleiche Ausgabe.
     */

    echo 'Einstellige ungerade Zahlen von range():  ';
    foreach (range(1, 9, 2) as $zahl) {
        echo "$zahl ";
    }
    echo "\n";

    echo 'Einstellige ungerade Zahlen von xrange(): ';
    foreach (xrange(1, 9, 2) as $zahl) {
        echo "$zahl ";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Einstellige ungerade Zahlen von range():  1 3 5 7 9
    Einstellige ungerade Zahlen von xrange(): 1 3 5 7 9

### Generator-Objekte

Beim Aufruf einer Generatorfunktion wird ein neues Objekt der internen Generator-Klasse zurückgegeben. Dieses Objekt implementiert das Iterator-Interface in gleicher Weise wie es ein forward-only Iterator-Objekt machen würde und stellt Methoden zur Verfügung, die aufgerufen werden können, um den Zustand des Generators zu manipulieren, einschließlich des Sendens von Werten an, und der Rückgabe von Werten von ihm.

## Generator-Syntax

Eine Generatorfunktion sieht genau so aus wie eine normale Funktion mit der Ausnahme, dass ein Generator statt eines Wertes so viele Werte wie nötig zurückgibt (Stichwort: `yield`). Jede Funktion, die `yield` enthält, ist eine Generatorfunktion.

Wenn eine Generatorfunktion aufgerufen wird, wird ein Objekt zurückgegeben, über das iteriert werden kann. Wenn Sie über dieses Objekt iterieren (zum Beispiel, per `foreach`-Schleife), wird PHP die Iteratorfunktionen des Objekts jedes Mal aufrufen, wenn ein Wert benötigt wird. Dann wird der Status des Generators gesichert, so dass fortgefahren werden kann, wenn der nächste Wert benötigt wird.

Sobald keine weiteren Werte zurückgegeben werden können, kann der Generator einfach zurückgeben, und der rufende Code wird fortgesetzt, als gäbe es keine weiteren Werte in einem Array.

> Hinweis:

> Ein Generator kann Werte zurückgeben, die unter Verwendung von Generator::getReturn() ermittelt werden können.

### yield-Schlüsselwort

Das Herz einer Generatorfunktion ist das yield-Schlüsselwort. In seiner einfachsten Form sieht das yield-Schlüsselwort wie eine return-Anweisung aus, ausser dass die Ausführung mit der Rückgabe nicht beendet wird, sondern yield stattdessen bei der Schleife über den Generator einen Wert für den Code bereitstellt und die Ausführung der Generatorfunktion anhält.

Beispiel #1 Ein einfaches Beispiel zum liefern (yielding) von Werten

    <?php
    function generiere_eins_bis_drei() {
        for ($i = 1; $i <= 3; $i++) {
            // Hinweis: $i bleibt zwischen den yields erhalten.
            yield $i;
        }
    }

    $generator = generiere_eins_bis_drei();
    foreach ($generator as $wert) {
        echo "$wert\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1
    2
    3

> Hinweis:

> Intern werden sequentielle Integer-Schlüssel mit den abgelieferten Werten verknüpft, so wie mit einem nicht-assoziativen Array.

#### Produzieren von Werten mit Schlüsseln

PHP unterstützt ebenfalls assoziative Arrays, und Generatoren unterscheiden sich nicht davon. Als Ergänzung zum Produzieren einfacher Werte, wie oben gezeigt, können Sie zur gleichen Zeit auch einen Schlüssel liefern.

Die Syntax für das Produzieren eines Schlüssel/Wert-Paares ist sehr ähnlich wie die Definition von assoziativen Arrays, wie unten gezeigt.

Beispiel #2 Produzieren eines Schlüssel/Wert-Paares

    <?php
    /*
     * Die Eingabe sind Semikolon getrennte Felder, wobei das erste Feld
     * eine ID ist, die als Schlüssel genutzt wird.
     */

    $eingabe = <<<'EOF'
    1;PHP;mag Dollarzeichen
    2;Python;mag Leerzeichen
    3;Ruby;mag Blöcke
    EOF;

    function eingabe_parser($eingabe) {
        foreach (explode("\n", $eingabe) as $zeile) {
            $felder = explode(';', $zeile);
            $id = array_shift($felder);

            yield $id => $felder;
        }
    }

    foreach (eingabe_parser($eingabe) as $id => $felder) {
        echo "$id:\n";
        echo "    $felder[0]\n";
        echo "    $felder[1]\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1:
        PHP
        mag Dollarzeichen
    2:
        Python
        mag Leerzeichen
    3:
        Ruby
        mag Blöcke

#### Produzieren von null-Werten

Yield kann ohne Argument aufgerufen werden, um einen `null`-Wert mit einem automatischen Schlüssel zurückzugeben.

Beispiel #3 Produzieren von `null`s

    <?php
    function generiere_drei_nulls() {
        foreach (range(1, 3) as $i) {
            yield;
        }
    }

    var_dump(iterator_to_array(generiere_drei_nulls()));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      NULL
      [1]=>
      NULL
      [2]=>
      NULL
    }

#### Produzieren als Referenz

Generatorfunktionen sind genauso in der Lage Werte als Referenz zurückzugeben, wie als Wert. Dies kann in gleicher Weise erfolgen, wie beim Zurückgeben von Referenzen aus Funktionen: dies geschieht, indem dem Funktionsnamen ein Kaufmanns-Und vorangestellt wird.

Beispiel #4 Produzieren von Werten als Referenz

    <?php
    function &generiere_referenz() {
        $wert = 3;

        while ($wert > 0) {
            yield $wert;
        }
    }

    /*
     * Hinweis: wir können $nummer innerhalb der Schleife ändern,
     * und weil der Generator Referenzen zurückgibt, wird $wert
     * innerhalb von generiere_referenz() verändert.
     */
    foreach (generiere_referenz() as &$nummer) {
        echo (--$nummer).'... ';
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2... 1... 0...

#### Generatordelegation per yield from

Die Generatordelegation ermöglicht, mittels yield from-Ausdruck Werte von einem anderen Generator, Traversable-Objekt oder Array liefern zu lassen. Der äußere Generator liefert dann alle Werte vom inneren Generator, Objekt oder Array, bis dies nicht mehr gültig ist und die Ausführung im äußeren Generator fortfährt.

Falls ein Generator mit yield from verwendet wird, gibt der yield from-Ausdruck auch alle Werte zurück, die vom inneren Generator zurückgegeben werden.

Achtung

# Speichern in ein Array (z. B. mit iterator_to_array())

yield from setzt nicht die Schlüssel zurück. Es erhält die Schlüssel, die vom Traversable-Objekt oder Array zurückgegeben wurden. Daher können einige Werte den selben Schlüssel mit einem anderen yield oder yield from gemein haben, der, bei der Einfügung in ein Array, vorherige Werte mit diesem Schlüssel überschreibt.

Ein üblicher Fall, für den dies relevant ist, ist iterator_to_array(), das standardmäßig ein indexiertes Array zurück gibt, was zu möglicherweise unerwarteten Ergebnissen führen kann. iterator_to_array() hat einen zweiten Parameter `preserve_keys`, der auf `false` gesetzt werden kann, um alle Werte zu sammeln, während die Schlüssel, die vom Generator geliefert werden, ignoriert werden.

Beispiel #5 yield from mit iterator_to_array()

    <?php
    function inner() {
        yield 1; // Schlüssel 0
        yield 2; // Schlüssel 1
        yield 3; // Schlüssel 2
    }
    function gen() {
        yield 0; // Schlüssel 0
        yield from inner(); // Schlüssel 0-2
        yield 4; // Schlüssel 1
    }
    // Übergib false als zweiten Parameter, um das Array [0, 1, 2, 3, 4] zu erhalten
    var_dump(iterator_to_array(gen()));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      int(1)
      [1]=>
      int(4)
      [2]=>
      int(3)
    }

Beispiel #6 Grundlegende Verwendung von yield from

    <?php
    function zaehle_bis_zehn() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from sieben_acht();
        yield 9;
        yield 10;
    }

    function sieben_acht() {
        yield 7;
        yield from acht();
    }

    function acht() {
        yield 8;
    }

    foreach (zaehle_bis_zehn() as $zahl) {
        echo "$zahl ";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1 2 3 4 5 6 7 8 9 10

Beispiel #7 yield from und Rückgabewerte

    <?php
    function zaehle_bis_zehn() {
        yield 1;
        yield 2;
        yield from [3, 4];
        yield from new ArrayIterator([5, 6]);
        yield from sieben_acht();
        return yield from neun_zehn();
    }

    function sieben_acht() {
        yield 7;
        yield from acht();
    }

    function acht() {
        yield 8;
    }

    function neun_zehn() {
        yield 9;
        return 10;
    }

    $gen = zaehle_bis_zehn();
    foreach ($gen as $zahl) {
        echo "$zahl ";
    }
    echo $gen->getReturn();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1 2 3 4 5 6 7 8 9 10

## Vergleich von Generatoren mit Iterator-Objekten

Der Hauptvorteil von Generatoren ist deren Einfachheit. Viel weniger Boilerplate-Code muss geschrieben werden als im Vergleich zur Implementierung einer Iterator-Klasse und der Code ist generell einfacher zu lesen. Zum Beispiel sind die folgende Funktion und Klasse äquivalent:

    <?php
    function leseZeilenVonDatei($dateiName) {
        if (!$dateiHandle = fopen($dateiName, 'r')) {
            return;
        }

        while (false !== $zeile = fgets($dateiHandle)) {
            yield $zeile;
        }

        fclose($dateiHandle);
    }

    // im Gegensatz zu...

    class LineIterator implements Iterator {
    class LineIterator implements Iterator {
        protected $fileHandle;

        protected $line;
        protected $i;

        public function __construct($fileName) {
            if (!$this->fileHandle = fopen($fileName, 'r')) {
                throw new RuntimeException('Couldn\'t open file "' . $fileName . '"');
            }
        }

        public function rewind() {
            fseek($this->fileHandle, 0);
            $this->line = fgets($this->fileHandle);
            $this->i = 0;
        }

        public function valid() {
            return false !== $this->line;
        }

        public function current() {
            return $this->line;
        }

        public function key() {
            return $this->i;
        }

        public function next() {
            if (false !== $this->line) {
                $this->line = fgets($this->fileHandle);
                $this->i++;
            }
        }

        public function __destruct() {
            fclose($this->fileHandle);
        }
    }
    ?>

Diese Flexibilität kommt allerdings nicht ohne Preis: Generatoren sind forward-only-Iteratoren, und können nicht zurückgesetzt werden, wenn sie einmal gestartet wurden. Das heißt außerdem, dass der selbe Generator nicht mehrfach iteriert werden kann: der Generator muss durch einen erneuten Aufruf der Generator-Funktion neu erstellt werden.

### Siehe auch

- Objektiteration

# Attribute

## Inhaltsverzeichnis

- Übersicht über die Attribute
- Syntax von Attributen
- Lesen von Attributen mit der Reflection-API
- Deklaration von Attributklassen

## Übersicht über die Attribute

(PHP 8)

PHP-Attribute bieten strukturierte, maschinenlesbare Metadaten für Klassen, Methoden, Funktionen, Parameter, Eigenschaften und Konstanten. Sie können zur Laufzeit über die Reflection-API inspiziert werden und ermöglichen dynamisches Verhalten ohne Änderung des Codes. Attribute bieten eine deklarative Möglichkeit, den Code mit Metadaten zu kommentieren.

Attribute ermöglichen es, die Implementierung eines Merkmals von seiner Verwendung zu trennen. Während Schnittstellen die Struktur definieren, indem sie Methoden vorschreiben, liefern Attribute Metadaten über mehrere Elemente, einschließlich Methoden, Funktionen, Eigenschaften und Konstanten. Im Gegensatz zu Schnittstellen, die die Implementierung von Methoden vorschreiben, kommentieren Attribute den Code, ohne dessen Struktur zu verändern.

Attribute können optionale Schnittstellenmethoden ergänzen oder ersetzen, indem sie Metadaten anstelle einer vorgeschriebenen Struktur bereitstellen. Ein Beispiel könnte eine `ActionHandler`-Schnittstelle sein, die eine Operation in einer Anwendung repräsentiert. Einige Implementierungen könnten einen Konfigurationsschritt erfordern, während andere dies nicht tun. Anstatt alle Klassen, die `ActionHandler` implementieren, zu zwingen, eine `setUp()`-Methode zu definieren, kann ein Attribut die Setup-Anforderungen spezifizieren. Dieser Ansatz erhöht die Flexibilität, da Attribute bei Bedarf mehrfach verwendet werden können.

Beispiel #1 Implementierung optionaler Methoden einer Schnittstelle mit Hilfe von Attributen

    <?php
    interface ActionHandler
    {
        public function execute();
    }

    #[Attribute]
    class SetUp {}

    class CopyFile implements ActionHandler
    {
        public string $fileName;
        public string $targetDirectory;

        #[SetUp]
        public function fileExists()
        {
            if (!file_exists($this->fileName)) {
                throw new RuntimeException("Die Datei existiert nicht");
            }
        }

        #[SetUp]
        public function targetDirectoryExists()
        {
            if (!file_exists($this->targetDirectory)) {
                mkdir($this->targetDirectory);
            } elseif (!is_dir($this->targetDirectory)) {
                throw new RuntimeException("Das Zielverzeichnis $this->targetDirectory ist kein Verzeichnis");
            }
        }

        public function execute()
        {
            copy($this->fileName, $this->targetDirectory . '/' . basename($this->fileName));
        }
    }

    function executeAction(ActionHandler $actionHandler)
    {
        $reflection = new ReflectionObject($actionHandler);

        foreach ($reflection->getMethods() as $method) {
            $attributes = $method->getAttributes(SetUp::class);

            if (count($attributes) > 0) {
                $methodName = $method->getName();

                $actionHandler->$methodName();
            }
        }

        $actionHandler->execute();
    }

    $copyAction = new CopyFile();
    $copyAction->fileName = "/tmp/foo.jpg";
    $copyAction->targetDirectory = "/home/user";

    executeAction($copyAction);

## Syntax von Attributen

Die Syntax eines Attributs besteht aus mehreren Schlüsselkomponenten. Die Deklaration eines Attributs beginnt mit `#[` und endet mit `]`. Sie kann ein oder mehrere Attribute enthalten, die durch Kommata getrennt sind. Der Name des Attributs kann unqualifiziert, qualifiziert oder voll qualifiziert sein, wie in Grundlagen zu Namensräumen beschrieben. Argumente für das Attribut sind optional und werden in Klammern `()` eingeschlossen. Argumente können nur Literalwerte oder konstante Ausdrücke sein. Es wird sowohl die Syntax für Positionsargumente als auch für benannte Argumente unterstützt.

Wenn ein Attribut über die Reflection-API angefordert wird, wird sein Name wie ein Klassenname behandelt und seine Argumente werden an seinen Konstruktor übergeben. Es wird daher empfohlen, für jedes Attribut eine Klasse einzuführen.

Beispiel #1 Syntax von Attributen

    <?php
    // a.php
    namespace MyExample;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
        const VALUE = 'value';

        private $value;

        public function __construct($value = null)
        {
            $this->value = $value;
        }
    }

    // b.php

    namespace Another;

    use MyExample\MyAttribute;

    #[MyAttribute]
    #[\MyExample\MyAttribute]
    #[MyAttribute(1234)]
    #[MyAttribute(value: 1234)]
    #[MyAttribute(MyAttribute::VALUE)]
    #[MyAttribute(array("key" => "value"))]
    #[MyAttribute(100 + 200)]
    class Thing
    {
    }

    #[MyAttribute(1234), MyAttribute(5678)]
    class AnotherThing
    {
    }

## Lesen von Attributen mit der Reflection-API

Mit der von der Reflection-API bereitgestellten Methode getAttributes() kann auf die Attribute von Klassen, Methoden, Funktionen, Parametern, Eigenschaften und Klassenkonstanten zugegriffen werden. Diese Methode gibt ein Array von ReflectionAttribute-Instanzen zurück. Diese Instanzen können nach dem Attributnamen und den Argumenten abgefragt werden und können verwendet werden, um eine Instanz des dargestellten Attributs zu instanziieren.

Die Trennung der Repräsentation des reflektierten Attributs von seiner tatsächlichen Instanz ermöglicht eine bessere Kontrolle über die Behandlung von Fehlern wie fehlende Attributklassen, falsch eingegebene Argumente oder fehlende Werte. Objekte der Attributklasse werden erst nach dem Aufruf der Funktion ReflectionAttribute::newInstance() instanziiert, um sicherzustellen, dass die Validierung der Argumente zu diesem Zeitpunkt erfolgt.

Beispiel #1 Lesen von Attributen mit der Reflection-API

    <?php

    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing
    {
    }

    function dumpAttributeData($reflection) {
        $attributes = $reflection->getAttributes();

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpAttributeData(new ReflectionClass(Thing::class));
    /*
    string(11) "MyAttribute"
    array(1) {
      ["value"]=>
      int(1234)
    }
    object(MyAttribute)#3 (1) {
      ["value"]=>
      int(1234)
    }
    */

Anstatt alle Attribute der Reflection-Instanz zu durchlaufen, kann auch der Name einer bestimmten Attributklasse als Argument übergeben werden, um nur die Attribute dieser Attributklasse abzurufen.

Beispiel #2 Lesen bestimmter Attribute mit der Reflection-API

    <?php

    function dumpMyAttributeData($reflection) {
        $attributes = $reflection->getAttributes(MyAttribute::class);

        foreach ($attributes as $attribute) {
           var_dump($attribute->getName());
           var_dump($attribute->getArguments());
           var_dump($attribute->newInstance());
        }
    }

    dumpMyAttributeData(new ReflectionClass(Thing::class));

## Deklaration von Attributklassen

Es ist empfehlenswert, für jedes Attribut eine eigene Klasse zu definieren. Im einfachsten Fall genügt eine leere Klasse, in der das Attribut `#[Attribute]` deklariert wird. Das Attribut kann mit einer `use`-Anweisung aus dem globalen Namensraum importiert werden.

Beispiel #1 Einfache Attributklasse

    <?php

    namespace Example;

    use Attribute;

    #[Attribute]
    class MyAttribute
    {
    }

Um die Arten der Deklarationen einzuschränken, auf die ein Attribut angewendet werden kann, kann eine Bitmaske als erstes Argument an die `#[Attribute]`-Deklaration übergeben werden.

Beispiel #2 Verwendung der Zielspezifikation, um die Verwendung von Attributen zu beschränken

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION)]
    class MyAttribute
    {
    }

Wenn MyAttribute für einen anderen Typ deklariert wird, wird nun beim Aufruf von ReflectionAttribute::newInstance() eine Exception ausgelöst.

Die folgenden Ziele können angegeben werden:

- `Attribute::TARGET_CLASS`
- `Attribute::TARGET_FUNCTION`
- `Attribute::TARGET_METHOD`
- `Attribute::TARGET_PROPERTY`
- `Attribute::TARGET_CLASS_CONSTANT`
- `Attribute::TARGET_PARAMETER`
- `Attribute::TARGET_ALL`

Standardmäßig kann ein Attribut nur einmal pro Deklaration verwendet werden. Damit ein Attribut wiederholbar ist, muss es in der Bitmaske der `#[Attribut]`-Deklaration mit dem Flag `Attribute::IS_REPEATABLE` angegeben werden.

Beispiel #3 Verwendung von IS_REPEATABLE um ein Attribut mehrfach in einer Deklaration zu erlauben

    <?php

    namespace Example;

    use Attribute;

    #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
    class MyAttribute
    {
    }

# Referenzen

## Inhaltsverzeichnis

- Was Referenzen sind
- Was Referenzen leisten
- Was Referenzen nicht sind
- Parameterübergabe per Referenz
- Referenzen zurückgeben
- Referenzen aufheben
- Referenzen entdecken

## Was Referenzen sind

Referenzen sind in PHP ein Mechanismus, um verschiedene Namen für den gleichen Inhalt von Variablen zu ermöglichen. Sie sind nicht mit Zeigern in C zu vergleichen; zum Beispiel ist damit keine Zeigerarithmetik möglich, sie sind keine tatsächlichen Speicheradressen usw. Siehe Was Referenzen nicht sind für weitere Informationen. Stattdessen sind sie Aliasdefinitionen für die Symboltabelle. PHP unterscheidet zwischen Variablenname und Variableninhalt, wobei der gleiche Variableninhalt unterschiedliche Namen besitzen kann. Der bestmögliche Vergleich ist der mit Dateinamen und Dateien im Dateisystem von Unix – Variablennamen sind Verzeichniseinträge, während der Variableninhalt die eigentliche Datei darstellt. Referenzen können nun als Hardlinks im Dateisystem verstanden werden.

## Was Referenzen leisten

Es können grundsätzlich drei Operationen mit Referenzen durchgeführt werden: Referenzzuweisung, Referenzübergabe und Referenzrückgabe. Dieser Abschnitt enthält eine Einführung zu diesen Operationen mit Links zu weiteren Informationen.

### Referenzzuweisung

PHP Referenzen erlauben es, zwei Variablennamen, sich auf den gleichen Variableninhalt beziehen zu lassen. Zum Beispiel:

    <?php

    $a =& $b;

    ?>

Das bedeutet, dass $a und $b auf denselben Inhalt zeigen.

> Hinweis:

> $a und $b sind hier gleichwertig, und $a ist kein Zeiger auf $b oder umgekehrt, sondern $a und $b zeigen auf dieselben Stelle.

> Hinweis:

> Wenn man eine undefinierte Variable per Referenz zuweist, übergibt oder zurückgibt, wird sie erstellt.

> Beispiel #1 Referenzen mit undefinierten Variablen benutzen

>     <?php

>     function foo(&$var) {}

>     foo($a); // $a wird "erstellt" und dem Wert null zugewiesen

>     $b = array();
>     foo($b['b']);
>     var_dump(array_key_exists('b', $b)); // bool(true)

>     $c = new stdClass();
>     foo($c->d);
>     var_dump(property_exists($c, 'd')); // bool(true)

>     ?>

Diese Syntax kann auch mit Funktionen, die Referenzen zurückgeben, benutzt werden:

    <?php

    $foo =& find_var($bar);

    ?>

Die Verwendung der gleichen Syntax bei einer Funktion, die nicht per Referenz zurückgibt, führt zu einem Fehler, ebenso wie die Verwendung mit dem Ergebnis des new-Operators. Obwohl Objekte als Zeiger übergeben werden, sind diese nicht dasselbe wie Referenzen, wie im Abschnitt über Objekte und Referenzen erläutert wird.

Warnung

Wird eine Referenz auf eine Variable zugewiesen, die in einer Funktion als `global` deklariert wurde, dann ist die Referenz nur innerhalb der Funktion sichtbar. Das kann vermieden werden, indem das $GLOBALS-Array verwendet wird.

Beispiel #2 Referenzieren globaler Variablen innerhalb von Funktionen

    <?php

    $var1 = "Beispiel-Variable";
    $var2 = "";

    function global_references($use_globals)
    {
        global $var1, $var2;

        if (!$use_globals) {
            $var2 =& $var1; // nur innerhalb der Funktion sichtbar
        } else {
            $GLOBALS["var2"] =& $var1; // ebenso im globalen Kontext sichtbar
        }
    }

    global_references(false);
    echo "Der Wert von var2 ist '$var2'\n"; // Der Wert von var2 ist ''

    global_references(true);
    echo "Der Wert von var2 ist '$var2'\n"; // Der Wert von var2 ist 'Beispiel-Variable'

    ?>

`global $var;` kann als Abkürzung für `$var =& $GLOBALS['var'];` angesehen werden. Daher ändert die Zuweisung einer anderen Referenz zu `$var` nur die Referenz der lokalen Variable.

> Hinweis:

> Wenn man einer Variable einen Wert per Referenz in einer `foreach`-Anweisung zuweist, werden auch die Referenzen geändert.

> Beispiel #3 Referenzen und die foreach-Anweisung

>     <?php

>     $ref = 0;
>     $row =& $ref;

>     foreach (array(1, 2, 3) as $row) {
>         // Mach was
>     }

>     echo $ref; // 3 - letztes Element des durchlaufenen Arrays

>     ?>

Obgleich keine Referenzzuweisung im engeren Sinne, können Ausdrücke, die mit dem Sprachkonstrukt `array()` erstellt werden, sich ebenso verhalten, wenn dem hinzuzufügenden Array-Element `&` vorangestellt wird. Beispiel:

    <?php

    $a = 1;
    $b = array(2, 3);

    $arr = array(&$a, &$b[0], &$b[1]);
    $arr[0]++;
    $arr[1]++;
    $arr[2]++;
    /* $a == 2, $b == array(3, 4); */

    ?>

Es ist allerdings zu beachten, dass Referenzen in Arrays potentiell gefährlich sind. Eine normale Zuweisung (also nicht per Referenz) mit einer Referenz auf der rechten Seite wandelt die linke Seite nicht in eine Referenz um, aber Referenzen innerhalb von Arrays bleiben bei solchen normalen Zuweisungen erhalten. Dies gilt ebenso für Funktionsaufrufe, bei denen das Array als Wertübergabe entgegengenommen wird. Beispiel:

    <?php

    /* Zuweisung skalarer Variablen */
    $a = 1;
    $b =& $a;
    $c = $b;
    $c = 7; // $c ist keine Referenz; keine Änderung an $a oder $b

    /* Zuweisung von Array-Variablen */
    $arr = array(1);
    $a =& $arr[0]; // $a und $arr[0] sind in derselben Referenzmenge
    $arr2 = $arr; // Keine Referenzzuweisung!
    $arr2[0]++;
    /* $a == 2, $arr == array(2) */
    /* Der Inhalt von $arr hat sich geändert, obwohl es keine Referenz ist! */

    ?>

Anders ausgedrückt ist das Referenzverhalten von Arrays auf einer Element-für-Element-Basis definiert; das Referenzverhalten einzelner Elemente ist getrennt vom Referenzzustand des Array-Behälters.

### Referenzübergabe

Eine weitere Einsatzmöglichkeit von Referenzen ist die Übergabe von Variablen an eine Funktion per Referenz. Hierbei beziehen sich sowohl der lokale Variablenname als auch der Variablenname der aufrufenden Instanz auf denselben Variableninhalt:

    <?php

    function foo(&$var)
    {
        $var++;
    }

    $a=5;
    foo($a);

    ?>

Nach der Ausführung hat $a den Wert 6, da sich in der Funktion foo der Variablenname $var auf denselben Variableninhalt bezieht wie $a. Weitere Information hierzu sind dem Abschnitt Referenzübergabe zu entnehmen.

### Referenzrückgabe

Als Drittes bieten Referenzen die Möglichkeit, Werte aus Funktionen heraus per Referenz zurückzugeben.

## Was Referenzen nicht sind

Wie bereits gesagt: Referenzen sind keine Zeiger. Das bedeutet, der folgende Code tut nicht, was man erwarten könnte:

    <?php

    function foo(&$var)
    {
        $var =& $GLOBALS["baz"];
    }

    foo($bar);

    ?>

Folgendes passiert: $var in foo wird zunächst an $bar aus der aufrufenden Instanz gebunden, wird dann aber neu gebunden an $GLOBALS["baz"]. Es gibt keine Möglichkeit, $bar unter Verwendung des Referenzmechanismus im aufrufenden Geltungsbereich an etwas anderes zu binden, da $bar in der Funktion foo nicht zur Verfügung steht (es wird durch $var repräsentiert, aber $var hat in der aufrufenden Symboltabelle) nur Variableninhalte und keine Name-an-Wert-Bindung). Man kann die. Rückgabe von Referenzen verwenden, um die von der Funktion ausgewählten Variablen zu referenzieren.

## Parameterübergabe per Referenz

Man kann Variablen an Funktionen per Referenz übergeben, so dass die Funktion die Variable modifizieren kann. Dazu benutzt man folgende Syntax:

    <?php

    function foo(&$var)
    {
        $var++;
    }

    $a=5;

    foo($a);
    // $a ist 6

    ?>

> Hinweis: Zu beachten ist, dass beim Funktionsaufruf kein Referenz-Zeichen steht, sondern nur in der Funktionsdefinition. Diese allein ist ausreichend, um das Argument per Referenz zu übergeben.

Folgende Dinge können per Referenz übergeben werden:

- Variablen, zum Beispiel `foo($a)`

- Referenzen, zurückgegeben von einer Funktion, zum Beispiel:

      <?php

      function foo(&$var)
      {
          $var++;
      }

      function &bar()
      {
          $a = 5;
          return $a;
      }

      foo(bar());

      ?>

  Es gibt detailliertere Erläuterungen zur Rückgabe per Referenz.

Alle anderen Ausdrücke sollten nicht per Referenz übergeben werden, da das Ergebnis undefiniert ist. Folgende Beispiele sind etwa ungültig:

    <?php

    function foo(&$var)
    {
        $var++;
    }

    function bar() // Beachte das fehlende &
    {
        $a = 5;
        return $a;
    }

    foo(bar()); // Erzeugt einen Hinweis

    foo($a = 5); // Ausdruck, nicht Variable
    foo(5); // Erzeugt einen fatalen Fehler

    class Foobar {}

    foo(new Foobar()) // Erzeugt einen Hinweis von PHP 7.0.7 an
                      // Hinweis: Nur Variablen sollten als Referenz übergeben werden

    ?>

## Referenzen zurückgeben

Das Zurückgeben von Ergebnissen per Referenz aus Funktionen heraus kann manchmal recht nützlich sein, um herauszufinden, an welche Variable eine Referenz gebunden werden soll. Man sollte diese Funktionalität nicht aus Performancegründen benutzen, der Kern ist intelligent genug, um dies selbst zu optimieren. Man sollte Referenzen nur dann zurückgeben, wenn man sinnvolle technische Gründe hat. Hierbei ist folgende Syntax zu verwenden:

    <?php

    class Foo
    {
        public $value = 42;

        public function &getValue()
        {
            return $this->value;
        }
    }

    $obj = new Foo();
    $myValue = &$obj->getValue(); // $myValue ist eine Referenz auf $obj->value, was den Wert 42 hat
    $obj->value = 2;
    echo $myValue;                // Zeigt den neuen Wert von $obj->value, also 2.

    ?>

In diesem Beispiel weisen wir der Eigenschaft des von der Funktion getValue zurückgegebenen Objekts einen Wert zu, und nicht seiner Kopie, wie es der Fall wäre, wenn wir nicht die Referenzsyntax verwendet hätten.

> Hinweis: Im Gegensatz zur Parameterübergabe ist hier an beiden Stellen die Angabe des `&` notwendig. Dies zeigt an, dass Sie eine Referenz und keine Kopie zurückgeben. Ebenfalls wird angezeigt, dass für $myValue im Gegensatz zur normalen Zuweisung eine Referenzbindung durchgeführt werden soll.

> Hinweis: Wenn man versucht, eine Referenz aus einer Funktion mit der Syntax `return ($this->value);` zurückzugeben, wird das nicht funktionieren, weil man versucht, das Ergebnis eines Ausdrucks zurückzugeben und nicht eine Variable per Referenz. Man kann nur Variablen per Referenz aus einer Funktion zurückgeben - sonst nichts.

Um die zurückgegebene Referenz zu verwenden, muss Referenzzuweisung benutzt werden:

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    $collection = &collector();
    // Jetzt ist $collection eine referenzierte Variable, die auf das statische
    // Array innerhalb der Funktion verweist

    $collection[] = 'foo';

    print_r(collector());
    // Array
    // (
    //    [0] => foo
    // )

    ?>

> Hinweis: Wenn die Zuweisung ohne das `&`-Symbol erfolgt, z. B. `$collection = collector();`, erhält die Variable $collection eine Kopie des Wertes und nicht die von der Funktion zurückgegebene Referenz.

Um die zurückgegebene Referenz an eine andere Funktion zu übergeben, die eine Referenz erwartet, kann diese Syntax verwendet werden:

    <?php

    function &collector()
    {
        static $collection = array();
        return $collection;
    }

    array_push(collector(), 'foo');

    ?>

> Hinweis: Es ist zu beachten, dass `array_push(&collector(), 'foo');` nicht funktioniert; es erzeugt einen fatalen Fehler.

## Referenzen aufheben

Wird eine Referenz aufgehoben, so wird nur die Bindung zwischen einem Variablennamen und dem Variableninhalt entfernt. Der Inhalt der Variablen wird hierbei nicht gelöscht. Betrachten wir folgendes Beispiel:

    <?php

    $a = 1;
    $b =& $a;
    unset($a);

    ?>

Dies wird $b nicht aufheben, sondern nur $a.

Wiederum sieht man die Analogie zwischen Unix und den Referenzen: Das Aufheben einer Referenz entspricht einem Aufruf von unlink unter Unix.

## Referenzen entdecken

Viele Sprachelemente von PHP sind intern mit der Benutzung von Referenzen implementiert, daher gilt alles bisher gesagte auch für diese Konstrukte. Manche Konstrukte, wie das Übergeben und Rückgeben per Referenz, wurden oben erwähnt. Andere Konstrukte, die Referenzen verwenden, sind:

### Globale Referenzen

Wird eine Variable als global $var deklariert, wird eine Referenz auf die globale Variable $var erzeugt. Das ist also dasselbe wie:

    <?php

    $var =& $GLOBALS["var"];

    ?>

Dies hat zur Folge, dass das Anwenden von unset() auf $var keinen Einfluss auf die globale Variable hat.

# Vordefinierte Variablen

PHP stellt vordefinierte Variablen zur Verfügung, die externe Variablen, eingebaute Umgebungsvariablen und andere Informationen über die Ausführungsumgebung darstellen, z. B. die Anzahl und Werte der Argumente, die einem Skript in der CLI-Umgebung übergeben wurden.

# Superglobals

Superglobals — Interne Variablen, die immer in allen Gültigkeitsbereichen verfügbar sind

### Beschreibung

Etliche vordefinierte Variablen in PHP sind sogenannte "Superglobals", was bedeutet, dass sie in allen Gültigkeitsbereichen (sogenannte Scopes) eines Skripts verfügbar sind. Daher ist es nicht nötig, global $variable; zu verwenden, um innerhalb einer Funktion oder Methode auf sie zuzugreifen.

Diese Superglobals sind:

- $GLOBALS
- $_SERVER
- $_GET
- $_POST
- $_FILES
- $_COOKIE
- $_SESSION
- $_REQUEST
- $_ENV

### Anmerkungen

> Hinweis: Verfügbarkeit der Variablen

> Standardmäßig sind alle Superglobals verfügbar, allerdings haben einige Einstellung in PHP Einfluss auf ihre Verfügbarkeit. Für weitere Informationen lesen Sie bitte die Dokumentation zu variables_order.

> Hinweis: Variable Variablen

> Superglobals können nicht als variable Variablen innerhalb von Funktionen oder Klassenmethoden verwendet werden.

### Siehe auch

- Gültigkeit von Variablen
- Die Direktive variables_order
- Die Filter-Erweiterung

# $GLOBALS

(PHP 4, PHP 5, PHP 7, PHP 8)

$GLOBALS — Referenziert alle Variablen, die im globalen Gültigkeitsbereich vorhanden sind

### Beschreibung

Ein assoziatives Array, das Referenzen auf alle Variablen enthält, die derzeit im globalen Gültigkeitsbereich (Scope) des Skripts bekannt sind. Die Namen der jeweiligen Variablen sind die Schlüsselwerte, um auf den Inhalt der jeweils referenzierten Variablen zuzugreifen.

### Beispiele

Beispiel #1 $GLOBALS-Beispiel

    <?php

    function test()
    {
        $foo = "local variable";

        echo '$foo in global scope: ' . $GLOBALS["foo"] . "\n";
        echo '$foo in current scope: ' . $foo . "\n";
    }

    $foo = "Example content";
    test();

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    $foo in global scope: Example content
    $foo in current scope: local variable

Warnung

Seit PHP 8.1.0 wird der Schreibzugriff auf das gesamte $GLOBALS-Array nicht mehr unterstützt:

Beispiel #2 Das Schreiben des gesamten $GLOBALS führt zu einem Fehler

    <?php

    // Erzeugt einen Kompilierungsfehler:
    $GLOBALS = [];
    $GLOBALS += [];
    $GLOBALS =& $x;
    $x =& $GLOBALS;
    unset($GLOBALS);
    array_pop($GLOBALS);
    // ...und jede andere Schreib-/Lese-Schreiboperation auf $GLOBALS

    ?>

### Anmerkungen

> Hinweis:

> Dies ist eine 'Superglobale' oder automatisch globale Variable. Dies bedeutet, dass sie innerhalb des Skripts in jedem Geltungsbereich sichtbar ist. Es ist nicht nötig, sie mit global $variable bekannt zu machen, um aus Funktionen oder Methoden darauf zuzugreifen.

> Hinweis: Verfügbarkeit der Variablen

> Im Gegensatz zu allen anderen Superglobals ist $GLOBALS notwendigerweise immer in PHP verfügbar.

> Hinweis:

> Seit PHP 8.1.0 ist $GLOBALS eine schreibgeschützte Kopie der globalen Symboltabelle. Das heißt, globale Variablen können nicht über diese Kopie verändert werden. Zuvor war das Array $GLOBALS vom üblichen Verhalten der Wertübergabe (by-value) von PHP-Arrays ausgenommen und globale Variablen konnten über seine Kopie geändert werden.

>     <?php

>     // Vor PHP 8.1.0
>     $a = 1;

>     $globals = $GLOBALS; // Eine by-value-Kopie
>     $globals['a'] = 2;
>     var_dump($a); // int(2)

>     // Seit PHP 8.1.0
>     // $a wird dadurch nicht mehr verändert. Das vorherige Verhalten verletzte die Semantik von by-value.
>     $globals = $GLOBALS;
>     $globals['a'] = 1;

>     // Um das vorherige Verhalten wiederherzustellen, durchlaufen Sie die Kopie und übertragen jede Eigenschaft zurück auf $GLOBALS.
>     foreach ($globals as $key => $value) {
>         $GLOBALS[$key] = $value;
>     }

>     ?>

# $_SERVER

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SERVER — Informationen über Server und Ausführungsumgebung

### Beschreibung

$_SERVER ist ein Array, das Informationen wie Header, Pfade und die verschiedenen Wege, das Skript anzusprechen beinhaltet. Die Einträge in diesem Array werden vom Webserver erstellt, weshalb es keine Garantie dafür gibt, dass jeder Webserver alle diese Einträge unterstützt - Server können einige weglassen oder andere Einträge unterstützen, die hier nicht aufgeführt sind. Die meisten dieser Variablen werden jedoch in der » CGI/1.1-Spezifikation ausgewiesen und sind wahrscheinlich definiert.

> Hinweis: Wenn PHP auf der Kommandozeile läuft, sind die meisten dieser Einträge nicht verfügbar oder haben keine Bedeutung.

Zusätzlich zu den unten aufgelisteten Elementen erstellt PHP weitere Elemente mit Werten aus Anfrage-Headern. Diese Einträge erhalten die Bezeichnung `HTTP_`, gefolgt vom Namen des Headers in Großbuchstaben und mit Unterstrichen anstelle von Bindestrichen. Zum Beispiel wäre der `Accept-Language`-Header als `$_SERVER['HTTP_ACCEPT_LANGUAGE']` verfügbar.

### Indizes

'PHP_SELF'
  Der Dateiname des aktuell ausgeführten Skripts, relativ zum Document-Root. Beispielsweise enthält $_SERVER['PHP_SELF'] in einem Skript, das über die Adresse http://example.com/foo/bar.php aufgerufen wird, den Wert /foo/bar.php. Die Konstante __FILE__ enthält den vollständigen Pfad und Dateinamen der aktuellen (z. B. via include eingebundenen) Datei. Falls PHP als Kommandozeilenprogramm läuft, enthält diese Variable den Namen des Skripts.
'argv'
  Das Array der an das Skript übergebenen Argumente. Wenn das Skript auf der Kommandozeile ausgeführt wird, ermöglicht dies den Zugriff auf die Kommandozeilenparameter im C-Stil. Wird das Skript via GET aufgerufen, enthält die Variable den Querystring.
'argc'
  Enthält die Anzahl der per Kommandozeile an das Skript übergebenen Parameter (sofern das Skript auf der Kommandozeile ausgeführt wird).
'GATEWAY_INTERFACE'
  Enthält die Version der vom Server verwendete CGI-Spezifikation, z. B. `'CGI/1.1'`.
'SERVER_ADDR'
  Die IP-Adresse des Servers, auf dem das aktuelle Skript ausgeführt wird.
'SERVER_NAME'
  Der Hostname des Servers, auf dem das aktuelle Skript ausgeführt wird. Wenn das Skript auf einem virtuellen Host läuft, wird dieser Wert vom virtuellen Host bestimmt.

  > Hinweis: Unter Apache 2 müssen `UseCanonicalName = On` und `ServerName` gesetzt werden. Ansonsten reflektiert dieser Wert den Hostnamen, der vom Client gesendet wurde und vorgetäuscht werden kann. Es ist nicht sicher, sich in einem sicherheitsabhängigen Umfeld auf diesen Wert zu verlassen.

'SERVER_SOFTWARE'
  Die Identifikation der verwendeten Server-Software, die bei einer Antwort auf den eingegangenen Request verwendet wird.
'SERVER_PROTOCOL'
  Der Name und die Versionsnummer des verwendeten Übertragungsprotokolls, mittels dessen die aktuelle Seite aufgerufen wurde, z. B. `'HTTP/1.0'`.
'REQUEST_METHOD'
  Die Requestmethode, die verwendet wurde, um die Seite aufzurufen; z. B. `'GET'`, `'HEAD'`, `'POST'`, `'PUT'`.

  > Hinweis:

  > Ist die Requestmethode `HEAD`, wird ein PHP-Skript beendet, nachdem die Header gesendet wurden (sofern Ausgaben ohne die Verwendung des Ausgabepuffers (output buffering) erzeugt werden).

'REQUEST_TIME'
  Der Timestamp des Zeitpunkts, an dem PHP mit der Verarbeitung der Anfrage begonnen hat.
'REQUEST_TIME_FLOAT'
  Der Timestamp des Zeitpunkts, an dem PHP mit der Verarbeitung der Anfrage begonnen hat, mit Mikrosekunden-Genauigkeit.
'QUERY_STRING'
  Sofern vorhanden, der Querystring, mittels dessen auf die Seite zugegriffen wurde.
'DOCUMENT_ROOT'
  Das Document-Root-Verzeichnis, unter dem das aktuelle Skript ausgeführt wird, so wie es in der Konfiguration des Servers festgelegt wurde.
'HTTPS'
  Wird auf einen nicht-leeren Wert gesetzt, wenn das Skript via HTTPS aufgerufen wurde.
'REMOTE_ADDR'
  Die IP-Adresse, von der aus der Benutzer die aktuelle Seite ansieht.
'REMOTE_HOST'
  Der Name des Hosts, von dem aus der Benutzer die aktuelle Seite ansieht. Der Auflösung der IP-Adresse (Reverse DNS Lookup) basiert auf der REMOTE_ADDR des Benutzers.

  > Hinweis: Der Webserver muss so konfiguriert sein, dass er diese Variable erzeugt. Zum Beispiel muss bei Apache in der httpd.conf die Direktive `HostnameLookups On` gesetzt werden, damit sie existiert. Siehe auch gethostbyaddr().

'REMOTE_PORT'
  Der vom Rechner des Benutzers verwendete Port, um mit dem Webserver zu kommunizieren.
'REMOTE_USER'
  Der beglaubigte Benutzer.
'REDIRECT_REMOTE_USER'
  Der beglaubigte Benutzer, falls der Request intern weitergeleitet wurde.
'SCRIPT_FILENAME'

  Der absolute Pfad des aktuell ausgeführten Skripts.

  > Hinweis:

  > Wenn ein Skript als CLI mit einem relativen Pfad wie file.php oder ../file.php ausgeführt wird, enthält $_SERVER['SCRIPT_FILENAME'] den vom Benutzer angegebenen relativen Pfad.

'SERVER_ADMIN'
  Der Wert, der für die SERVER_ADMIN-Direktive (für Apache) im Konfigurationsfile des Webservers eingestellt wurde. Wenn das Skript auf einem Virtuellen Host läuft, wird der für diesen Virtuellen Host definierte Wert verwendet.
'SERVER_PORT'
  Der Port, der auf dem Server vom Webserver für die Kommunikation genutzt wird. In einer Standardumgebung ist dies `'80'`; wenn Sie beispielsweise SSL verwenden, wird dieser Wert auf den Port geändert, über den Sie Ihre verschlüsselte HTTP-Kommunikation abwickeln.

  > Hinweis: Unter Apache 2 müssen `UseCanonicalName = On` sowie `UseCanonicalPhysicalPort = On` gesetzt werden, um den physikalischen (wirklichen) Port zu erhalten; andernfalls kann dieser Wert gefälscht werden und gibt dann den Wert des physikalischen Ports zurück oder auch nicht. Es ist nicht sicher, sich in einem sicherheitsabhängigen Umfeld auf diesen Wert zu verlassen.

'SERVER_SIGNATURE'
  Ein String, der die Version der verwendeten Serversoftware und den Namen des Virtuellen Hosts enthält, der, sofern die Option auf dem Server aktiviert ist, an die servergenerierten Seiten angefügt wird.
'PATH_TRANSLATED'
  Auf dem Dateisystem (nicht dem Document-Root!) basierender Pfad zum aktuellen Skript, nachdem der Server ein Virtual-to-Real-Mapping durchgeführt hat.

  > Hinweis: Apache 2-Benutzer können die Direktive `AcceptPathInfo = On` in der httpd.conf verwenden, um einen Wert für PATH_INFO zu definieren.

'SCRIPT_NAME'
  Enthält den Pfad zum aktuellen Skript. Dies ist nützlich für Seiten, die auf sich selbst verweisen sollen. Die Konstante __FILE__ enthält den vollständigen Pfad und Dateinamen der aktuellen (z. B. via include eingebundenen) Datei.
'REQUEST_URI'
  Der URI, der angegeben wurde, um auf die aktuelle Seite zuzugreifen, beispielsweise '`/index.html`'.
'PHP_AUTH_DIGEST'
  Wenn die Digest HTTP Authentication verwendet wird, wird diese Variable mit dem Inhalt des vom Client gesendeten 'Authorization'-Headers gefüllt, welchen Sie für eine adäquate Validierung nutzen sollten.
'PHP_AUTH_USER'
  Wenn die HTTP Authentication verwendet wird, wird diese Variable mit dem vom Benutzer angegebenen Usernamen gefüllt.
'PHP_AUTH_PW'
  Wenn die HTTP Authentication verwendet wird, wird diese Variable mit dem vom Benutzer angegebenen Passwort gefüllt.
'AUTH_TYPE'
  Wenn die HTTP Authentication verwendet wird, wird diese Variable mit dem verwendeten HTTP-Authentifizierungsmechanismus gefüllt.
'PATH_INFO'
  Enthält, sofern vorhanden, den Teil des Pfadnamens hinter dem Namen des PHP-Skripts, aber vor dem Query-String. Wenn zum Beispiel das aktuelle Skript mittels dem URI http://www.example.com/php/path_info.php/some/stuff?foo=bar aufgerufen wird, würde $_SERVER['PATH_INFO'] `/some/stuff` enthalten.
'ORIG_PATH_INFO'
  Originalversion von 'PATH_INFO' vor der Verarbeitung durch PHP.

### Beispiele

Beispiel #1 $_SERVER-Beispiel

    <?php
    echo $_SERVER['SERVER_NAME'];
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    www.example.com

### Anmerkungen

> Hinweis:

> Dies ist eine 'Superglobale' oder automatisch globale Variable. Dies bedeutet, dass sie innerhalb des Skripts in jedem Geltungsbereich sichtbar ist. Es ist nicht nötig, sie mit global $variable bekannt zu machen, um aus Funktionen oder Methoden darauf zuzugreifen.

### Siehe auch

- Die Filter-Erweiterung

# $_GET

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_GET — Query-String-Variablen

### Beschreibung

Ein assoziatives Array von Variablen, die dem aktuellen Skript mittels der URL-Parameter (auch als Query-String bezeichnet) übergeben werden. Es ist zu beachten, dass dieses Array immer dann gefüllt wird, wenn ein Query-String vorhanden ist, unabhängig von der HTTP-Anfragemethode.

### Beispiele

Beispiel #1 $_GET-Beispiel

    <?php
    echo 'Hallo ' . htmlspecialchars($_GET["name"]) . '!';
    ?>

Angenommen, der Benutzer gab `http://example.com/?name=Hannes` ein.

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Hallo Hannes!

### Anmerkungen

> Hinweis:

> Dies ist eine 'Superglobale' oder automatisch globale Variable. Dies bedeutet, dass sie innerhalb des Skripts in jedem Geltungsbereich sichtbar ist. Es ist nicht nötig, sie mit global $variable bekannt zu machen, um aus Funktionen oder Methoden darauf zuzugreifen.

> Hinweis:

> Die $_GET-Variablen werden automatisch mit urldecode() behandelt.

### Siehe auch

- Behandlung externer Variablen
- Die Filter-Erweiterung

# $_POST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_POST — Formulardaten aus HTTP-POST-Anfragen

### Beschreibung

Ein assoziatives Array von Variablen, die dem aktuellen Skript mittels der HTTP POST-Methode übergeben werden, wenn `application/x-www-form-urlencoded` oder `multipart/form-data` als HTTP Content-Type für die Anfrage verwendet wurde.

### Beispiele

Beispiel #1 $_POST-Beispiel

    <?php
    echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
    ?>

Angenommen, der Benutzer hat eine POST-Anfrage mit `name=Hannes` im Body gesendet.

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Hello Hannes!

### Anmerkungen

> Hinweis:

> Dies ist eine 'Superglobale' oder automatisch globale Variable. Dies bedeutet, dass sie innerhalb des Skripts in jedem Geltungsbereich sichtbar ist. Es ist nicht nötig, sie mit global $variable bekannt zu machen, um aus Funktionen oder Methoden darauf zuzugreifen.

> Hinweis: Um POST-Daten zu lesen, die mit anderen Inhaltstypen (z. B. `application/json` oder `application/xml`) gesendet wurden, muss php://input verwendet werden. Im Gegensatz zu $_POST, das nur mit `application/x-www-form-urlencoded` und `multipart/form-data` funktioniert, bietet php://input direkten Zugriff auf die Rohdaten aus dem Body der Anfrage.

### Siehe auch

- Behandlung externer Variablen
- Die Filter-Erweiterung

# $_FILES

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_FILES — HTTP Dateiupload-Variablen

### Beschreibung

Ein assoziatives Array von Elementen, die vom aktuellen Skript via HTTP POST-Methode hochgeladen werden. Die Struktur dieses Arrays wird im Abschnitt Dateiuploads mit POST beschrieben.

### Anmerkungen

> Hinweis:

> Dies ist eine 'Superglobale' oder automatisch globale Variable. Dies bedeutet, dass sie innerhalb des Skripts in jedem Geltungsbereich sichtbar ist. Es ist nicht nötig, sie mit global $variable bekannt zu machen, um aus Funktionen oder Methoden darauf zuzugreifen.

### Siehe auch

- move_uploaded_file() - Verschiebt eine hochgeladene Datei an einen neuen Ort
- Behandlung von Dateiuploads

# $_REQUEST

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_REQUEST — HTTP Request-Variablen

### Beschreibung

Ein assoziatives Array, das standardmäßig den Inhalt von $_GET, $_POST und $_COOKIE enthält.

### Anmerkungen

> Hinweis:

> Dies ist eine 'Superglobale' oder automatisch globale Variable. Dies bedeutet, dass sie innerhalb des Skripts in jedem Geltungsbereich sichtbar ist. Es ist nicht nötig, sie mit global $variable bekannt zu machen, um aus Funktionen oder Methoden darauf zuzugreifen.

> Hinweis:

> Wenn das Skript auf der Kommandozeile ausgeführt wird, enthält die Variable nicht den Inhalt von argv und argc; diese finden sich im Array $_SERVER.

> Hinweis:

> Die Variablen in $_REQUEST werden dem Skript mittels der GET-, POST- und COOKIE-Inputmechanismen zur Verfügung gestellt. Daher kann der Inhalt durch einen entfernten Benutzer modifiziert worden sein und ist daher als nicht vertrauenswürdig zu betrachten. Das Vorhandensein und die Reihenfolge des Variableninhalts in diesem Array wird entsprechend der PHP-Konfigurationsdirektiven request_order und variables_order bestimmt.

### Siehe auch

- Behandlung externer Variablen
- Die Filter-Erweiterung

# $_SESSION

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SESSION — Sessionvariablen

### Beschreibung

Ein assoziatives Array, das die Sessionvariablen enthält und dem aktuellen Skript zur Verfügung stellt. Lesen Sie den Abschnitt Sessionfunktionen der Dokumentation, um weitere Informationen zur Verwendung zu erhalten.

### Anmerkungen

> Hinweis:

> Dies ist eine 'Superglobale' oder automatisch globale Variable. Dies bedeutet, dass sie innerhalb des Skripts in jedem Geltungsbereich sichtbar ist. Es ist nicht nötig, sie mit global $variable bekannt zu machen, um aus Funktionen oder Methoden darauf zuzugreifen.

### Siehe auch

- session_start() - Erzeugt eine neue Session oder setzt eine vorhandene fort

# $_ENV

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_ENV — Umgebungsvariablen

### Beschreibung

Ein assoziatives Array von Variablen, die dem aktuellen Skript mittels der Environment-Methode übergeben werden.

Die Variablen werden aus der Laufzeitumgebung, unter der der PHP-Parser läuft, in PHPs globalen Namespace importiert. Die meisten Werte werden von der Shell, unter der PHP läuft, unterstützt, da es aber die unterschiedlichsten Systeme mit unterschiedlichsten Shells gibt, ist es unmöglich, eine definitive Liste aller verfügbaren Werte zu erstellen. Bitte konsultieren Sie die Dokumentation Ihrer Shell, um eine Liste aller definierten Umgebungsvariablen zu erhalten.

Andere Umgebungsvariablen enthalten die CGI-Variablen, die unabhängig davon eingefügt werden, ob PHP als Servermodul oder CGI-Prozess läuft.

### Beispiele

Beispiel #1 $_ENV-Beispiel

    <?php
    echo 'My username is ' .$_ENV["USER"] . '!';
    ?>

Angenommen "bjori" führt das Skript aus

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    My username is bjori!

### Anmerkungen

> Hinweis:

> Dies ist eine 'Superglobale' oder automatisch globale Variable. Dies bedeutet, dass sie innerhalb des Skripts in jedem Geltungsbereich sichtbar ist. Es ist nicht nötig, sie mit global $variable bekannt zu machen, um aus Funktionen oder Methoden darauf zuzugreifen.

### Siehe auch

- getenv() - Liefert den Wert einer einzelnen oder aller Umgebungsvariablen
- Die Filter-Erweiterung

# $_COOKIE

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_COOKIE — HTTP Cookies

### Beschreibung

Ein assoziatives Array von Variablen, die dem aktuellen Skript mittels HTTP-Cookies übergeben werden.

### Beispiele

Beispiel #1 $_COOKIE-Beispiel

    <?php
    echo 'Hello ' . htmlspecialchars($_COOKIE["name"]) . '!';
    ?>

Angenommen der Cookie "name" wurde bereits früher gesetzt:

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Hello Hannes!

### Anmerkungen

> Hinweis:

> Dies ist eine 'Superglobale' oder automatisch globale Variable. Dies bedeutet, dass sie innerhalb des Skripts in jedem Geltungsbereich sichtbar ist. Es ist nicht nötig, sie mit global $variable bekannt zu machen, um aus Funktionen oder Methoden darauf zuzugreifen.

### Siehe auch

- setcookie() - Sendet ein Cookie
- Behandlung externer Variablen
- Die Filter-Erweiterung

# $php_errormsg

(PHP 4, PHP 5, PHP 7)

$php_errormsg — Die vorangegangene Fehlermeldung

Warnung

Dieses Feature ist seit PHP 7.2.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieses Features wird dringend abgeraten.

Stattdessen sollte error_get_last() verwendet werden.

### Beschreibung

$php_errormsg ist eine Variable, die den Text der letzten von PHP generierten Fehlermeldung enthält. Die Variable ist nur innerhalb des Gültigkeitsbereichs (Scopes) verfügbar, in dem der Fehler auftrat, und auch nur, wenn die Konfigurationsoption track_errors eingeschaltet wurde (standardmäßig aus).

Warnung

Wird ein benutzerdefinierter Errorhandler (set_error_handler()) verwendet, wird $php_errormsg nur dann gesetzt, wenn der Errorhandler `false` zurückgibt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Die Direktive track_errors, die bewirkte, dass $php_errormsg verfügbar war, wurde entfernt.
7.2.0 | Die Direktive track_errors, die bewirkt, dass $php_errormsg verfügbar ist, ist nun veraltet.

### Beispiele

Beispiel #1 $php_errormsg-Beispiel

    <?php
    @strpos();
    echo $php_errormsg;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Wrong parameter count for strpos()

### Siehe auch

- error_get_last() - Liefert den zuletzt aufgetretenen Fehler

# $http_response_header

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

$http_response_header — HTTP Response-Header

Warnung

Dieses Feature ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

Stattdessen sollte http_get_last_response_headers() verwendet werden.

### Beschreibung

Das $http_response_header-Array ist vergleichbar mit der Funktion get_headers(). Bei der Verwendung eines HTTP-Wrappers enthält $http_response_header die HTTP Response-Header. $http_response_header wird im lokalen Geltungsbereich von Variablen erstellt.

### Beispiele

Beispiel #1 $http_response_header-Beispiel

    <?php
    function get_contents() {
      file_get_contents("http://example.com");
      var_dump($http_response_header); // die Variable wird im lokalen Geltungsbereich belegt
    }
    get_contents();
    var_dump($http_response_header); // ein Aufruf von get_contents() belegt die Variable nicht außerhalb des Funktionsbereichs
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(9) {
      [0]=>
      string(15) "HTTP/1.1 200 OK"
      [1]=>
      string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
      [2]=>
      string(29) "Server: Apache/2.2.3 (CentOS)"
      [3]=>
      string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
      [4]=>
      string(27) "ETag: "280100-1b6-80bfd280""
      [5]=>
      string(20) "Accept-Ranges: bytes"
      [6]=>
      string(19) "Content-Length: 438"
      [7]=>
      string(17) "Connection: close"
      [8]=>
      string(38) "Content-Type: text/html; charset=UTF-8"
    }

    Warning: Undefined variable $http_response_header
    NULL

### Siehe auch

- http_get_last_response_headers() - Retrieve last HTTP response headers
- http_clear_last_response_headers() - Clears the stored HTTP response headers

# $argc

(PHP 4, PHP 5, PHP 7, PHP 8)

$argc — Die Anzahl der an das Skript übergebenen Argumente

### Beschreibung

Enthält die Anzahl der an das aktuelle Skript übergebenen Argumente, wenn das Skript auf der Kommandozeile läuft.

> Hinweis: Der Dateiname des Skripts ist immer das erste an das Skript übergebene Argument, damit ist der kleinstmögliche Wert von $argc `1`.

> Hinweis: Diese Variable ist nicht verfügbar, wenn register_argc_argv ausgeschaltet ist.

### Beispiele

Beispiel #1 $argc-Beispiel

    <?php
    var_dump($argc);
    ?>

Wenn das Beispiel so aufgerufen wird: php script.php arg1 arg2 arg3

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(4)

### Anmerkungen

> Hinweis:

> Dies ist ebenfalls als $_SERVER['argc'] verfügbar.

### Siehe auch

- getopt() - Gets options from the command line argument list
- $argv

# $argv

(PHP 4, PHP 5, PHP 7, PHP 8)

$argv — Array der an das Skript übergebenen Argumente

### Beschreibung

Enthält ein Array aller an das Skript übergebenen Argumente, wenn dies auf der Kommandozeile ausgeführt wird.

> Hinweis: Das erste Argument $argv[0] ist immer der Name der zum Aufrufen des Skripts genutzt wurde.

> Hinweis: Diese Variable ist nicht verfügbar, wenn register_argc_argv ausgeschaltet ist.

Warnung

Um zu überprüfen, ob ein Skript von der Befehlszeile ausgeführt wird, sollte php_sapi_name() verwendet werden, anstatt zu prüfen, ob die Variablen $argv oder $_SERVER['argv'] gesetzt sind.

### Beispiele

Beispiel #1 $argv-Beispiel

    <?php
    var_dump($argv);
    ?>

Wenn das Beispiel so aufgerufen wird: php script.php arg1 arg2 arg3

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(4) {
      [0]=>
      string(10) "script.php"
      [1]=>
      string(4) "arg1"
      [2]=>
      string(4) "arg2"
      [3]=>
      string(4) "arg3"
    }

### Anmerkungen

> Hinweis:

> Dies ist ebenfalls als $_SERVER['argv'] verfügbar.

### Siehe auch

- getopt() - Gets options from the command line argument list
- $argc

## Inhaltsverzeichnis

- Superglobals — Interne Variablen, die immer in allen Gültigkeitsbereichen verfügbar sind
- $GLOBALS — Referenziert alle Variablen, die im globalen Gültigkeitsbereich vorhanden sind
- $_SERVER — Informationen über Server und Ausführungsumgebung
- $_GET — Query-String-Variablen
- $_POST — Formulardaten aus HTTP-POST-Anfragen
- $_FILES — HTTP Dateiupload-Variablen
- $_REQUEST — HTTP Request-Variablen
- $_SESSION — Sessionvariablen
- $_ENV — Umgebungsvariablen
- $_COOKIE — HTTP Cookies
- $php_errormsg — Die vorangegangene Fehlermeldung
- $http_response_header — HTTP Response-Header
- $argc — Die Anzahl der an das Skript übergebenen Argumente
- $argv — Array der an das Skript übergebenen Argumente

# Vordefinierte Exceptions

## Inhaltsverzeichnis

- Exception
- ErrorException
- ClosedGeneratorException
- Error
- ArgumentCountError
- ArithmeticError
- AssertionError
- DivisionByZeroError
- CompileError
- ParseError
- TypeError
- ValueError
- UnhandledMatchError
- FiberError
- RequestParseBodyException

Siehe auch das Kapitel SPL-Exceptions.

# Exception

(PHP 5, PHP 7, PHP 8)

## Einführung

Exception ist die Basisklasse für alle Benutzer-Exceptions.

## Klassenbeschreibung

class Exception implements Throwable {
/* Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Eigenschaften

message

  Die Exceptionmeldung

code

  Die Fehlernummer der Exception

file

  Der Name der Datei, in der die Exception erzeugt wurde

line

  Die Zeile, in der die Exception ausgelöst wurde

previous

  Die zuvor ausgelöste Exception

string

  Die String-Darstellung des Stacktraces

trace

  Der Stacktrace als Array

# Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__construct — Erstellt die Exception

### Beschreibung

public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Erstellt die Exception.

### Parameter-Liste

`message`

  Die auszugebende Beschreibung der Exception.

`code`

  Die Fehlernummer der Exception.

`previous`

  Die vorangegangene Exception, die für Exception-Verkettung verwendet werden soll.

> Hinweis: Der Aufruf des Konstruktors der Klasse Exception aus einer Unterklasse ignoriert die Standardargumente, wenn die Eigenschaften $code und $message bereits gesetzt wurden.

### Anmerkungen

> Hinweis:

> Die `message` is NICHT binary-safe.

# Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessage — Gibt die Exceptionbeschreibung zurück

### Beschreibung

final public function Exception::getMessage(): string

Gibt die Exceptionbeschreibung zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Exceptionbeschreibung als String zurück.

### Beispiele

Beispiel #1 Exception::getMessage()-Beispiel

    <?php
    try {
        throw new Exception("Some error message");
    } catch(Exception $e) {
        echo $e->getMessage();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Some error message

### Siehe auch

- Throwable::getMessage() - Liefert die Nachricht

# Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPrevious — Gibt die vorhergehende Throwable zurück

### Beschreibung

final public function Exception::getPrevious(): ?Throwable

Gibt die vorhergende Throwable zurück (welche als dritter Parameter von Exception::__construct() übergeben wurde).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die vorhergehende Throwable zurück falls vorhanden, anderenfalls `null`.

### Beispiele

Beispiel #1 Exception::getPrevious() Beispiel

Ausgabeschleife über einen Exception-Verlauf

    <?php
    class MyCustomException extends Exception {}

    function doStuff() {
        try {
            throw new InvalidArgumentException("Sie machen es nicht richtig!", 112);
        } catch(Exception $e) {
            throw new MyCustomException("Irgendetwas geschah", 911, $e);
        }
    }

    try {
        doStuff();
    } catch(Exception $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    /home/bjori/ex.php:8 Irgendetwas geschah (911) [MyCustomException]
    /home/bjori/ex.php:6 Sie machen es nicht richtig! (112) [InvalidArgumentException]

### Siehe auch

- Throwable::getPrevious() - Liefert das vorherige Throwable

# Exception::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCode — Gibt die Fehlernummer der Exception zurück

### Beschreibung

final public function Exception::getCode(): int

Gibt die Fehlernummer der Exception zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Exception selbst gibt den Fehlercode als int zurück. Von Exception erbende Unterklassen können jedoch auch einen anderen Typ zurückgeben. So gibt PDOException beispielsweise ein string zurück.

### Beispiele

Beispiel #1 Exception::getCode()-Beispiel

    <?php
    try {
        throw new Exception("Some error message", 30);
    } catch(Exception $e) {
        echo "The exception code is: " . $e->getCode();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    The exception code is: 30

### Siehe auch

- Throwable::getCode() - Liefert den Exception-Code

# Exception::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFile — Gibt den Namen der Datei zurück, in der die Exception erzeugt wurde

### Beschreibung

final public function Exception::getFile(): string

Gibt den Namen der Datei zurück, in der die Exception ausgelöst wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Namen der Datei zurück, in der die Exception ausgelöst wurde.

### Beispiele

Beispiel #1 Exception::getFile()-Beispiel

    <?php
    try {
        throw new Exception;
    } catch(Exception $e) {
        echo $e->getFile();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    /home/bjori/tmp/ex.php

### Siehe auch

- Throwable::getFile() - Liefert die Datei, in der das Objekt erzeugt wurde

# Exception::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLine — Gibt die Zeile zurück, in der die Exception erzeugt wurde

### Beschreibung

final public function Exception::getLine(): int

Gibt die Zeile zurück, in der die Exception ausgelöst wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Zeile zurück, in der die Exception ausgelöst wurde.

### Beispiele

Beispiel #1 Exception::getLine()-Beispiel

    <?php
    try {
        throw new Exception("Some error message");
    } catch(Exception $e) {
        echo "The exception was created on line: " . $e->getLine();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    The exception was created on line: 3

### Siehe auch

- Throwable::getLine() - Liefert die Zeile, in der das Objekt instantiiert wurde

# Exception::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTrace — Gibt den Stacktrace zurück

### Beschreibung

final public function Exception::getTrace(): array

Gibt den Stacktrace der Exception zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Stacktrace der Exception als Array zurück.

### Beispiele

Beispiel #1 Exception::getTrace()-Beispiel

    <?php
    function test() {
     throw new Exception;
    }

    try {
     test();
    } catch(Exception $e) {
     var_dump($e->getTrace());
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### Siehe auch

- Throwable::getTrace() - Liefert den Stacktrace

# Exception::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsString — Gibt den Stacktrace als String zurück

### Beschreibung

final public function Exception::getTraceAsString(): string

Gibt den Stacktrace als String zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Stacktrace als String zurück.

### Beispiele

Beispiel #1 Exception::getTraceAsString()-Beispiel

    <?php
    function test() {
        throw new Exception;
    }

    try {
        test();
    } catch(Exception $e) {
        echo $e->getTraceAsString();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### Siehe auch

- Throwable::getTraceAsString() - Liefert den Stacktrace als String

# Exception::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toString — Stringrepräsentation der Exception

### Beschreibung

public function Exception::__toString(): string

Gibt die Stringrepräsentation der Exception zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Stringrepräsentation der Exception zurück.

### Beispiele

Beispiel #1 Exception::__toString()-Beispiel

    <?php
    try {
        throw new Exception("Some error message");
    } catch(Exception $e) {
        echo $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    exception 'Exception' with message 'Some error message' in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Siehe auch

- Throwable::__toString() - Gibt eine Repräsentation des geworfenen Objekts als String zurück

# Exception::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__clone — Klont die Exception

### Beschreibung

private function Exception::__clone(): void

Exceptions können nicht geklont werden, und der Versuch, dies zu tun, führt zu einem Error.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

Exceptions sind nicht klonbar.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Exception::__clone() ist nicht mehr final.

## Inhaltsverzeichnis

- Exception::__construct — Erstellt die Exception
- Exception::getMessage — Gibt die Exceptionbeschreibung zurück
- Exception::getPrevious — Gibt die vorhergehende Throwable zurück
- Exception::getCode — Gibt die Fehlernummer der Exception zurück
- Exception::getFile — Gibt den Namen der Datei zurück, in der die Exception erzeugt wurde
- Exception::getLine — Gibt die Zeile zurück, in der die Exception erzeugt wurde
- Exception::getTrace — Gibt den Stacktrace zurück
- Exception::getTraceAsString — Gibt den Stacktrace als String zurück
- Exception::__toString — Stringrepräsentation der Exception
- Exception::__clone — Klont die Exception

# ErrorException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Einführung

Eine Fehler-Exception.

## Klassenbeschreibung

class ErrorException extends Exception {
/* Eigenschaften */
protected int $severity = E_ERROR;
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
public function __construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)
final public function getSeverity(): int
/* Geerbte Methoden */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Eigenschaften

severity

  Der Schweregrad der Exception

## Beispiele

Beispiel #1 Verwenden von set_error_handler() um eine Fehlermeldung in eine ErrorException zu verwandeln

    <?php

    set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline) {
        if (!(error_reporting() & $errno)) {
            // Dieser Fehlercode ist nicht in error_reporting enthalten.
            return;
        }

        if ($errno === E_DEPRECATED || $errno === E_USER_DEPRECATED) {
            // Keine Exception für Veralterungswarnungen werfen, da neue oder
            // unerwartete Veralterungen die Anwendung zerstören würden.
            return;
        }

        throw new \ErrorException($errstr, 0, $errno, $errfile, $errline);
    });

    // Das Deserialisieren fehlerhafter Daten löst eine Warnung aus, die vom
    // Error-Handler in eine ErrorException umgewandelt wird.
    unserialize('broken data');

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Fatal error: Uncaught ErrorException: unserialize(): Error at offset 0 of 11 bytes in test.php:16
    Stack trace:
    #0 [internal function]: {closure}(2, 'unserialize(): ...', 'test.php', 16)
    #1 test.php(16): unserialize('broken data')
    #2 {main}
      thrown in test.php on line 16

# ErrorException::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::__construct — Erstellt die Exception

### Beschreibung

public function ErrorException::__construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)

Erstellt die Exception.

### Parameter-Liste

`message`

  Die auszugebende Exceptionbeschreibung.

`code`

  Die Fehlernummer der Exception.

`severity`

  Die Schwere des aufgetretenen Fehlers.

  > Hinweis:

  > Obgleich die Schwere ein beliebiger int-Wert sein kann, ist es vorgesehen, dass die Fehler- Konstanten verwendet werden.

`filename`

  Der Name der Datei, in der die Exception aufgetreten ist.

`line`

  Die Zeilennummer, in der die Exception aufgetreten ist.

`previous`

  Die vorherige Exception (für Exception Chaining).

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `filename` and `line` sind jetzt nullbar. Bisher waren die Standardeinstellungen `__FILE__` bzw. `__LINE__`.

# ErrorException::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverity — Liefert die Schwere der Exception

### Beschreibung

final public function ErrorException::getSeverity(): int

Gibt die Schwere der Exception zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Schwere der Exception zurück.

### Beispiele

Beispiel #1 ErrorException::getSeverity()-Beispiel

    <?php
    try {
        throw new ErrorException("Exception message", 0, E_USER_ERROR);
    } catch(ErrorException $e) {
        echo "This exception severity is: " . $e->getSeverity();
        var_dump($e->getSeverity() === E_USER_ERROR);
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    This exception severity is: 256
    bool(true)

## Inhaltsverzeichnis

- ErrorException::__construct — Erstellt die Exception
- ErrorException::getSeverity — Liefert die Schwere der Exception

# Die Klasse ClosedGeneratorException

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

Wenn versucht wird, einen Wert von einem geschlossenen Generator abzurufen, wird eine ClosedGeneratorException geworfen.

## Klassenbeschreibung

class ClosedGeneratorException extends Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Error

(PHP 7, PHP 8)

## Einführung

Error ist die Basisklasse für alle internen PHP-Fehler.

## Klassenbeschreibung

class Error implements Throwable {
/* Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
public function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## Eigenschaften

message

  Die Fehlermeldung

code

  Der Fehlercode

file

  Der Name der Datei, in der der Fehler aufgetreten ist

line

  Die Zeile, in der der Fehler aufgetreten ist

previous

  Die zuvor ausgelöste Exception

string

  Der Stacktrace, dargestellt als Zeichenkette

trace

  Der Stacktrace als Array

# Error::__construct

(PHP 7, PHP 8)

Error::__construct — Erzeugt ein Error-Objekt

### Beschreibung

public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

Erzeugt ein Error.

### Parameter-Liste

`message`

  Die Fehlermeldung.

`code`

  Der Fehlercode.

`previous`

  Das vorherige Throwable, für die Verkettung von Ausnahmen.

### Anmerkungen

> Hinweis:

> Der Wert von `message` ist NICHT sicher im Umgang mit binären Werten.

# Error::getMessage

(PHP 7, PHP 8)

Error::getMessage — Gibt die Fehlermeldung zurück

### Beschreibung

final public function Error::getMessage(): string

Gibt die Fehlermeldung zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Fehlermeldung als Zeichenkette zurück.

### Beispiele

Beispiel #1 Error::getMessage()-Beispiel

    <?php
    try {
        throw new Error("Eine Fehlermeldung");
    } catch(Error $e) {
        echo $e->getMessage();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Eine Fehlermeldung

### Siehe auch

- Throwable::getMessage() - Liefert die Nachricht

# Error::getPrevious

(PHP 7, PHP 8)

Error::getPrevious — Gibt das vorherige Throwable zurück

### Beschreibung

final public function Error::getPrevious(): ?Throwable

Gibt das vorherige Throwable zurück (das dritte Argument von Error::__construct()).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das vorherige Throwable zurück, wenn eines vorhanden ist, andernfalls `null`.

### Beispiele

Beispiel #1 Error::getPrevious()-Beispiel

Schleife über und Ausgabe von Fehlern

    <?php
    class MyCustomError extends Error {}

    function doStuff() {
        try {
            throw new InvalidArgumentError("Du machst das falsch!", 112);
        } catch(Error $e) {
            throw new MyCustomError("Etwas ist passiert", 911, $e);
        }
    }

    try {
        doStuff();
    } catch(Error $e) {
        do {
            printf("%s:%d %s (%d) [%s]\n", $e->getFile(), $e->getLine(), $e->getMessage(), $e->getCode(), get_class($e));
        } while($e = $e->getPrevious());
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    /home/bjori/ex.php:8 Etwas ist passiert (911) [MyCustomError]
    /home/bjori/ex.php:6 Du machst das falsch! (112) [InvalidArgumentError]

### Siehe auch

- Throwable::getPrevious() - Liefert das vorherige Throwable

# Error::getCode

(PHP 7, PHP 8)

Error::getCode — Gibt den Fehlercode zurück

### Beschreibung

final public function Error::getCode(): int

Gibt den Fehlercode zurück

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Fehlercode als int zurück

### Beispiele

Beispiel #1 Error::getCode()-Beispiel

    <?php
    try {
        throw new Error("Eine Fehlermeldung", 30);
    } catch(Error $e) {
        echo "Der Fehlercode ist: " . $e->getCode();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Der Fehlercode ist: 30

### Siehe auch

- Throwable::getCode() - Liefert den Exception-Code

# Error::getFile

(PHP 7, PHP 8)

Error::getFile — Gibt die Datei zurück in der der Fehler

### Beschreibung

final public function Error::getFile(): string

Gibt den Namen der Datei zurück, in der der Fehler auftrat.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Namen der Datei zurück, in der der Fehler auftrat.

### Beispiele

Beispiel #1 Error::getFile()-Beispiel

    <?php
    try {
        throw new Error;
    } catch(Error $e) {
        echo $e->getFile();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    /home/bjori/tmp/ex.php

### Siehe auch

- Throwable::getFile() - Liefert die Datei, in der das Objekt erzeugt wurde

# Error::getLine

(PHP 7, PHP 8)

Error::getLine — Gibt die Zeile zurück in der der Fehler auftrat

### Beschreibung

final public function Error::getLine(): int

Gibt die Zeilennummer zurück, in der der Fehler auftrat.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Zeilennummer zurück, in der der Fehler auftrat.

### Beispiele

Beispiel #1 Error::getLine()-Beispiel

    <?php
    try {
        throw new Error("Some error message");
    } catch(Error $e) {
        echo "Der Fehler wurde erzeigt in Zeile: " . $e->getLine();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Der Fehler wurde erzeigt in Zeile: 3

### Siehe auch

- Throwable::getLine() - Liefert die Zeile, in der das Objekt instantiiert wurde

# Error::getTrace

(PHP 7, PHP 8)

Error::getTrace — Gibt den Stacktrace zurück

### Beschreibung

final public function Error::getTrace(): array

Gibt den Stacktrace zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Stacktrace als Array zurück.

### Beispiele

Beispiel #1 Error::getTrace()-Beispiel

    <?php
    function test() {
     throw new Error;
    }

    try {
     test();
    } catch(Error $e) {
     var_dump($e->getTrace());
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(4) {
        ["file"]=>
        string(22) "/home/bjori/tmp/ex.php"
        ["line"]=>
        int(7)
        ["function"]=>
        string(4) "test"
        ["args"]=>
        array(0) {
        }
      }
    }

### Siehe auch

- Throwable::getTrace() - Liefert den Stacktrace

# Error::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsString — Gibt den Stacktrace als String zurück

### Beschreibung

final public function Error::getTraceAsString(): string

Gibt den Stacktrace als String zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Stacktrace als String zurück.

### Beispiele

Beispiel #1 Error::getTraceAsString()-Beispiel

    <?php
    function test() {
        throw new Error;
    }

    try {
        test();
    } catch(Error $e) {
        echo $e->getTraceAsString();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    #0 /home/bjori/tmp/ex.php(7): test()
    #1 {main}

### Siehe auch

- Throwable::getTraceAsString() - Liefert den Stacktrace als String

# Error::__toString

(PHP 7, PHP 8)

Error::__toString — Gibt eine Repräsentation des Fehlers als String zurück

### Beschreibung

public function Error::__toString(): string

Gibt eine Repräsentation des Fehlers als string zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt eine Repräsentation des Fehlers als string zurück.

### Beispiele

Beispiel #1 Error::__toString()-Beispiel

    <?php
    try {
        throw new Error("Eine Fehlermeldung");
    } catch(Error $e) {
        echo $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Error: Eine Fehlermeldung in /home/bjori/tmp/ex.php:3
    Stack trace:
    #0 {main}

### Siehe auch

- Throwable::__toString() - Gibt eine Repräsentation des geworfenen Objekts als String zurück

# Error::__clone

(PHP 7, PHP 8)

Error::__clone — Klont einen Fehler

### Beschreibung

private function Error::__clone(): void

Error kann nicht geklont werden, sodass diese Methode einen fatalen Fehler hervorruft.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

Error können nicht geklont werden.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Error::__clone() ist nicht mehr final.

## Inhaltsverzeichnis

- Error::__construct — Erzeugt ein Error-Objekt
- Error::getMessage — Gibt die Fehlermeldung zurück
- Error::getPrevious — Gibt das vorherige Throwable zurück
- Error::getCode — Gibt den Fehlercode zurück
- Error::getFile — Gibt die Datei zurück in der der Fehler
- Error::getLine — Gibt die Zeile zurück in der der Fehler auftrat
- Error::getTrace — Gibt den Stacktrace zurück
- Error::getTraceAsString — Gibt den Stacktrace als String zurück
- Error::__toString — Gibt eine Repräsentation des Fehlers als String zurück
- Error::__clone — Klont einen Fehler

# ArgumentCountError

(PHP 7 >= PHP 7.1.0, PHP 8)

## Einführung

ArgumentCountError wird geworfen, wenn zu wenige Argumente an eine benutzerdefinierte Funktion oder Methode übergeben werden.

Dieser Fehler wird auch ausgelöst, wenn zu viele Argumente an eine interne Funktion übergeben werden, die keinen Parameter mit variabler Länge hat.

## Klassenbeschreibung

class ArgumentCountError extends TypeError {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# ArithmeticError

(PHP 7, PHP 8)

## Einführung

ArithmeticError wird geworfen, wenn bei einer mathematischen Operation ein Fehler auftritt. Das ist z. B. der Fall, wenn versucht wird, eine Bitverschiebung um einen negativen Betrag durchzuführen, oder wenn ein Aufruf von intdiv() zu einem Wert außerhalb des möglichen Bereichs von int führen würde.

## Klassenbeschreibung

class ArithmeticError extends Error {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# AssertionError

(PHP 7, PHP 8)

## Einführung

AssertionError wird geworfen, wenn eine über assert() gemachte Zusicherung fehlschlägt.

## Klassenbeschreibung

class AssertionError extends Error {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# DivisionByZeroError

(PHP 7, PHP 8)

## Einführung

DivisionByZeroError wird geworfen, wenn versucht wird, eine Zahl durch Null zu dividieren.

## Klassenbeschreibung

class DivisionByZeroError extends ArithmeticError {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# CompileError

(PHP 7 > 7.3.0, PHP 8)

## Einführung

CompileError wird bei einigen Kompilierungsfehlern geworfen, die früher einen fatalen Fehler verursachten.

## Klassenbeschreibung

class CompileError extends Error {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# ParseError

(PHP 7, PHP 8)

## Einführung

ParseError wird geworfen, wenn bei der Analyse des PHP-Codes ein Fehler auftritt, z. B. wenn eval() aufgerufen wird.

> Hinweis: Seit PHP 7.3.0 erweitert ParseError CompileError; vorher war es eine Erweiterung von Error.

## Klassenbeschreibung

class ParseError extends CompileError {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# TypeError

(PHP 7, PHP 8)

## Einführung

Ein TypeError kann geworfen werden, wenn:

- der Wert, der für eine Klasseneigenschaft festgelegt wird, nicht dem deklarierten Typ der Eigenschaft entspricht.
- der Typ eines Arguments, das an eine Funktion übergeben wird, nicht mit dem deklarierten Typ des entsprechenden Parameters übereinstimmt.
- ein von einer Funktion zurückgegebener Wert nicht dem deklarierten Rückgabetyp der Funktion entspricht.

## Klassenbeschreibung

class TypeError extends Error {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Changelog

Version | Beschreibung
--- | ---
7.1.0 | Im Strict-Modus führt die Übergabe einer falschen Anzahl von Argumenten an eine interne PHP-Funktion nicht mehr zu einem generischen TypeError. Stattdessen wird ein spezifischerer ArgumentCountError ausgelöst, der den TypeError erweitert.

# ValueError

(PHP 8)

## Einführung

Ein ValueError wird geworfen, wenn der Typ eines Arguments korrekt ist, aber der Wert nicht stimmt. Zum Beispiel, wenn eine negative Ganzzahl übergeben wird, obwohl die Funktion eine positive erwartet, oder wenn eine leere Zeichenkette oder ein leeres Array übergeben wird, obwohl die Funktion erwartet, dass es nicht leer ist.

## Klassenbeschreibung

class ValueError extends Error {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# UnhandledMatchError

(PHP 8)

## Einführung

Ein UnhandledMatchError wird geworfen, wenn der an einen match-Ausdruck übergebene Suchbegriff von keinem Zweig des match-Ausdrucks verarbeitet werden konnte.

## Klassenbeschreibung

class UnhandledMatchError extends Error {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FiberError

(PHP 8 >= 8.1.0)

## Einführung

FiberError wird geworfen, wenn eine ungültige Operation auf einer Fiber durchgeführt wird.

## Klassenbeschreibung

final class FiberError FiberError {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
public function __construct()
/* Geerbte Methoden */
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FiberError::__construct

(PHP 8 >= 8.1.0)

FiberError::__construct — Konstruktor, um die direkte Instanziierung zu unterbinden

### Beschreibung

public function FiberError::__construct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Fehler/Exceptions

Wirft beim Aufruf eine Error-Exception.

## Inhaltsverzeichnis

- FiberError::__construct — Konstruktor, um die direkte Instanziierung zu unterbinden

# RequestParseBodyException

(PHP 8 >= 8.4.0)

## Einführung

A RequestParseBodyException is thrown in request_parse_body() when the request body is invalid, according to the `Content-Type` header.

## Klassenbeschreibung

class RequestParseBodyException extends Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Vordefinierte Interfaces und Klassen

## Inhaltsverzeichnis

- Traversable
- Iterator
- IteratorAggregate
- InternalIterator
- Throwable
- Countable
- ArrayAccess
- Serializable
- Closure
- stdClass
- Generator
- Fiber
- WeakReference
- WeakMap
- Stringable
- UnitEnum
- BackedEnum
- SensitiveParameterValue
- __PHP_Incomplete_Class

Siehe auch SPL-Interfaces und reservierte Klassen.

# Das Traversable-Interface

(PHP 5, PHP 7, PHP 8)

## Einführung

Interface, um herauszufinden, ob eine Klasse mittels `foreach` durchlaufen werden kann.

Das abstrakte Interface kann nicht direkt implementiert werden. Stattdessen muss es entweder mittels IteratorAggregate oder Iterator implementiert werden.

## Interface-Übersicht

interface Traversable {
}

Dieses Interface besitzt keine Methoden, sein einziger Sinn ist es, als Basisinterface für alle traversierbaren Klassen zu dienen.

## Changelog

Version | Beschreibung
--- | ---
7.4.0 | Das Traversable-Interface kann nun von abstrakten Klassen implementiert werden. Erweiternde Klassen müssen Iterator oder IteratorAggregate implementieren.

## Anmerkungen

> Hinweis:

> Interne (eingebaute) Klassen, die dieses Interface implementieren, können in `foreach`-Konstrukten verwendet werden und benötigen keine explizite Implementierung von IteratorAggregate oder Iterator.

> Hinweis:

> Vor PHP 7.4.0 kann dieses interne Interface der Engine nicht in PHP-Skripten implementiert werden. Stattdessen müssen IteratorAggregate oder Iterator verwendet werden.

# Das Iterator-Interface

(PHP 5, PHP 7, PHP 8)

## Einführung

Interface für externe Iteratoren oder Objekte, die selbstiterierend sind.

## Interface-Übersicht

interface Iterator extends Traversable {
/* Methoden */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

## Vordefinierte Iteratoren

PHP bietet bereits eine Anzahl von Iteratoren für viele alltägliche Aufgaben an. SPL-Iteratoren enthält eine entsprechende Liste.

## Beispiele

Beispiel #1 Grundlegende Nutzung

Dieses Beispiel demonstriert, in welcher Reihenfolge Methoden aufgerufen werden, wenn `foreach` auf einem Iterator angewendet wird.

    <?php
    class meinIterator implements Iterator {
        private $position = 0;
        private $array = array(
            "erstesElement",
            "zweitesElement",
            "letztesElement",
        );

        public function __construct() {
            $this->position = 0;
        }

        public function rewind(): void {
            var_dump(__METHOD__);
            $this->position = 0;
        }

        #[\ReturnTypeWillChange]
        public function current() {
            var_dump(__METHOD__);
            return $this->array[$this->position];
        }

        #[\ReturnTypeWillChange]
        public function key() {
            var_dump(__METHOD__);
            return $this->position;
        }

        public function next(): void {
            var_dump(__METHOD__);
            ++$this->position;
        }

        public function valid(): bool {
            var_dump(__METHOD__);
            return isset($this->array[$this->position]);
        }
    }

    $it = new meinIterator;

    foreach($it as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(18) "meinIterator::rewind"
    string(17) "meinIterator::valid"
    string(19) "meinIterator::current"
    string(15) "meinIterator::key"
    int(0)
    string(12) "erstesElement"

    string(16) "meinIterator::next"
    string(17) "meinIterator::valid"
    string(19) "meinIterator::current"
    string(15) "meinIterator::key"
    int(1)
    string(13) "zweitesElement"

    string(16) "meinIterator::next"
    string(17) "meinIterator::valid"
    string(19) "meinIterator::current"
    string(15) "meinIterator::key"
    int(2)
    string(11) "letztesElement"

    string(16) "meinIterator::next"
    string(17) "meinIterator::valid"

## Siehe auch

Objekt-Iteration

# Iterator::current

(PHP 5, PHP 7, PHP 8)

Iterator::current — Liefert das aktuelle Element

### Beschreibung

public function Iterator::current(): mixed

Gibt das aktuelle Element zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Kann Werte jeden Typs zurückgeben.

# Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::key — Liefert den Schlüssel des aktuellen Elements

### Beschreibung

public function Iterator::key(): mixed

Gibt den Schlüssel des aktuellen Elements zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg einen Skalar zurück. Im Fehlerfall wird `null` zurückgegeben.

### Fehler/Exceptions

Gibt im Fehlerfall eine Meldung vom Typ `E_NOTICE` aus.

# Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::next — Rückt den Zeiger auf das nächste Element vor

### Beschreibung

public function Iterator::next(): void

Verschiebt die aktuelle Position auf das nächste Element.

> Hinweis:

> Diese Methode wird nach jedem Durchlauf der `foreach`-Schleife aufgerufen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Zurückgegebene Werte werden ignoriert.

# Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewind — Setzt den Iterator auf das erste Element zurück

### Beschreibung

public function Iterator::rewind(): void

Setzt den Zeiger auf das erste Element des Iterators zurück.

> Hinweis:

> Dies ist die erste Methode, die aufgerufen wird, wenn eine `foreach`-Schleife gestartet wird. Sie wird nicht nach `foreach`-Durchläufen ausgeführt.

> Da `foreach` vor Beginn der Iteration immer rewind() aufruft, wird ein manuell vorgerückter Iteratorstand (z. B. über SplFileObject::seek()) zurückgesetzt. Um ohne Zurücksetzen des Iterators zu iterieren, kann er in einen NoRewindIterator verpackt werden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Zurückgegebene Werte werden ignoriert.

# Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::valid — Prüft, ob die aktuelle Position zulässig ist

### Beschreibung

public function Iterator::valid(): bool

Diese Methode wird nach Iterator::rewind() und Iterator::next() aufgerufen, um zu prüfen, ob die aktuelle Position zulässig ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Der Rückgabewert wird in den Typ bool umgewandelt und dann ausgewertet. Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

## Inhaltsverzeichnis

- Iterator::current — Liefert das aktuelle Element
- Iterator::key — Liefert den Schlüssel des aktuellen Elements
- Iterator::next — Rückt den Zeiger auf das nächste Element vor
- Iterator::rewind — Setzt den Iterator auf das erste Element zurück
- Iterator::valid — Prüft, ob die aktuelle Position zulässig ist

# Das IteratorAggregate-Interface

(PHP 5, PHP 7, PHP 8)

## Einführung

Ein Interface, um einen externen Iterator zu erzeugen.

## Interface-Übersicht

interface IteratorAggregate extends Traversable {
/* Methoden */
public function getIterator(): Traversable
}

## Beispiele

Beispiel #1 Grundlegende Verwendung

    <?php

    class meineDaten implements IteratorAggregate
    {
        public $property1 = "Öffentliche Eigenschaft eins";
        public $property2 = "Öffentliche Eigenschaft zwei";
        public $property3 = "Öffentliche Eigenschaft drei";
        public $property4 = "";

        public function __construct()
        {
            $this->property4 = "letzte Eigenschaft";
        }

        public function getIterator(): Traversable
        {
            return new ArrayIterator($this);
        }
    }

    $obj = new meineDaten();

    foreach ($obj as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(9) "property1"
    string(19) "Öffentliche Eigenschaft eins"

    string(9) "property2"
    string(19) "Öffentliche Eigenschaft zwei"

    string(9) "property3"
    string(21) "Öffentliche Eigenschaft drei"

    string(9) "property4"
    string(13) "letzte Eigenschaft"

# IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIterator — Ruft einen externen Iterator oder ein Traversable ab

### Beschreibung

public function IteratorAggregate::getIterator(): Traversable

Gibt einen externen Iterator oder ein externes Traversable zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Eine Instanz eines Objektes, das Iterator oder Traversable implementiert.

### Fehler/Exceptions

Wirft im Fehlerfall eine Exception.

## Inhaltsverzeichnis

- IteratorAggregate::getIterator — Ruft einen externen Iterator oder ein Traversable ab

# Die Klasse InternalIterator

(PHP 8)

## Einführung

Eine Klasse, die bei internen Klassen die Implementierung von IteratorAggregate vereinfacht.

## Klassenbeschreibung

final class InternalIterator implements Iterator {
/* Methoden */
private function __construct()
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# InternalIterator::__construct

(PHP 8)

InternalIterator::__construct — Privater Konstruktor, um eine direkte Instanziierung zu verhindern

### Beschreibung

private function InternalIterator::__construct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# InternalIterator::current

(PHP 8)

InternalIterator::current — Liefert das aktuelle Element

### Beschreibung

public function InternalIterator::current(): mixed

Gibt das aktuelle Element zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das aktuelle Element zurück.

# InternalIterator::key

(PHP 8)

InternalIterator::key — Liefert den Schlüssel des aktuellen Elements

### Beschreibung

public function InternalIterator::key(): mixed

Gibt den Schlüssel des aktuellen Elements zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Schlüssel des aktuellen Elements zurück.

# InternalIterator::next

(PHP 8)

InternalIterator::next — Rückt zum nächsten Element vor

### Beschreibung

public function InternalIterator::next(): void

Verschiebt die aktuelle Position zum nächsten Element.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# InternalIterator::rewind

(PHP 8)

InternalIterator::rewind — Setzt den Iterator auf das erste Element zurück

### Beschreibung

public function InternalIterator::rewind(): void

Springt auf das erste Element des Iterators zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# InternalIterator::valid

(PHP 8)

InternalIterator::valid — Prüft, ob die aktuelle Position gültig ist

### Beschreibung

public function InternalIterator::valid(): bool

Prüft, ob die aktuelle Position gültig ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das Ergebnis der Prüfung zurück, ob die aktuelle Position gültig ist.

## Inhaltsverzeichnis

- InternalIterator::__construct — Privater Konstruktor, um eine direkte Instanziierung zu verhindern
- InternalIterator::current — Liefert das aktuelle Element
- InternalIterator::key — Liefert den Schlüssel des aktuellen Elements
- InternalIterator::next — Rückt zum nächsten Element vor
- InternalIterator::rewind — Setzt den Iterator auf das erste Element zurück
- InternalIterator::valid — Prüft, ob die aktuelle Position gültig ist

# Throwable

(PHP 7, PHP 8)

## Einführung

Throwable ist das zugrundeliegende Interface aller Objekte, die mittels des `throw`-Statements geworfen werden können, inklusive Error und Exception.

> Hinweis:

> PHP-Klassen können das Interface Throwable nicht direkt implementieren und müssen stattdessen von Exception abgeleitet werden.

## Interface-Übersicht

interface Throwable extends Stringable {
/* Methoden */
public function getMessage(): string
public function getCode(): int
public function getFile(): string
public function getLine(): int
public function getTrace(): array
public function getTraceAsString(): string
public function getPrevious(): ?Throwable
public function __toString(): string
/* Geerbte Methoden */
public function Stringable::__toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
8.0.0 | Throwable implementiert nun Stringable.

# Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessage — Liefert die Nachricht

### Beschreibung

public function Throwable::getMessage(): string

Gibt die Nachricht zurück, die dem geworfenen Objekt zugewiesen ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Nachricht zurück, die dem geworfenen Objekt zugewiesen ist.

### Siehe auch

- Exception::getMessage() - Gibt die Exceptionbeschreibung zurück

# Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCode — Liefert den Exception-Code

### Beschreibung

public function Throwable::getCode(): int

Gibt den Fehlercode zurück, der dem geworfenen Objekt zugewiesen ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Fehlercode von Exception-Objekten als int zurück, aber bei abgeleiteten Klassen von Exception möglicherweise als andere Typen (z. B. als String bei PDOException).

### Siehe auch

- Exception::getCode() - Gibt die Fehlernummer der Exception zurück

# Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFile — Liefert die Datei, in der das Objekt erzeugt wurde

### Beschreibung

public function Throwable::getFile(): string

Gibt den Namen der Datei zurück, in der das geworfene Objekt erzeugt wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Dateinamen der Datei zurück, in der das geworfene Objekt erzeugt wurde.

### Siehe auch

- Exception::getFile() - Gibt den Namen der Datei zurück, in der die Exception erzeugt wurde

# Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLine — Liefert die Zeile, in der das Objekt instantiiert wurde

### Beschreibung

public function Throwable::getLine(): int

Gibt die Zeilennummer zurück, in der das geworfene Objekt instantiiert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Zeilennummer zurück, in der das geworfene Objekt instantiiert wurde.

### Siehe auch

- Exception::getLine() - Gibt die Zeile zurück, in der die Exception erzeugt wurde

# Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTrace — Liefert den Stacktrace

### Beschreibung

public function Throwable::getTrace(): array

Gibt den Stacktrace als Array zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Stacktrace als Array im gleichen Format wie debug_backtrace() zurück.

### Siehe auch

- Exception::getTrace() - Gibt den Stacktrace zurück

# Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsString — Liefert den Stacktrace als String

### Beschreibung

public function Throwable::getTraceAsString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Stacktrace als String zurück.

### Siehe auch

- Exception::getTraceAsString() - Gibt den Stacktrace als String zurück

# Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPrevious — Liefert das vorherige Throwable

### Beschreibung

public function Throwable::getPrevious(): ?Throwable

Gibt ein mögliches vorheriges Throwable zurück (z. B. eines, welches als drittes Argument an Exception::__construct() übergeben wurde).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das vorherige Throwable zurück, wenn eines vorhanden ist, andernfalls `null`.

### Siehe auch

- Exception::getPrevious() - Gibt die vorhergehende Throwable zurück

# Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toString — Gibt eine Repräsentation des geworfenen Objekts als String zurück

### Beschreibung

public function Throwable::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt eine Repräsentation des geworfenen Objekts als string zurück.

### Siehe auch

- Exception::__toString() - Stringrepräsentation der Exception

## Inhaltsverzeichnis

- Throwable::getMessage — Liefert die Nachricht
- Throwable::getCode — Liefert den Exception-Code
- Throwable::getFile — Liefert die Datei, in der das Objekt erzeugt wurde
- Throwable::getLine — Liefert die Zeile, in der das Objekt instantiiert wurde
- Throwable::getTrace — Liefert den Stacktrace
- Throwable::getTraceAsString — Liefert den Stacktrace als String
- Throwable::getPrevious — Liefert das vorherige Throwable
- Throwable::__toString — Gibt eine Repräsentation des geworfenen Objekts als String zurück

# The Countable interface

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Einführung

Classes implementing Countable can be used with the count() function.

## Interface-Übersicht

interface Countable {
/* Methoden */
public function count(): int
}

# Countable::count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Countable::count — Zählt die Elemente eines Objekts

### Beschreibung

public function Countable::count(): int

Diese Methode wird ausgeführt, wenn `value` für count() ein Objekt ist, das Countable implementiert.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Die benutzerdefinierte Anzahl als int.

### Beispiele

Beispiel #1 Countable::count()-Beispiel

    <?php

    class Counter implements Countable
    {
        private $count = 0;

        public function count(): int
        {
            return ++$this->count;
        }
    }

    $counter = new Counter;

    for ($i = 0; $i < 10; ++$i) {
        echo "Ich wurde " . count($counter) . " mal ge-count()ed\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Ich wurde 1 mal ge-count()ed
    Ich wurde 2 mal ge-count()ed
    Ich wurde 3 mal ge-count()ed
    Ich wurde 4 mal ge-count()ed
    Ich wurde 5 mal ge-count()ed
    Ich wurde 6 mal ge-count()ed
    Ich wurde 7 mal ge-count()ed
    Ich wurde 8 mal ge-count()ed
    Ich wurde 9 mal ge-count()ed
    Ich wurde 10 mal ge-count()ed

## Inhaltsverzeichnis

- Countable::count — Zählt die Elemente eines Objekts

# Das ArrayAccess-Interface

(PHP 5, PHP 7, PHP 8)

## Einführung

Interface, um Objekte als Arrays ansprechen zu können

## Interface-Übersicht

interface ArrayAccess {
/* Methoden */
public function offsetExists(mixed `$offset`): bool
public function offsetGet(mixed `$offset`): mixed
public function offsetSet(mixed `$offset`, mixed `$value`): void
public function offsetUnset(mixed `$offset`): void
}

## Beispiele

Beispiel #1 Grundlegende Verwendung

    <?php
    class Obj implements ArrayAccess {
        public $container = [
            "eins" => 1,
            "zwei" => 2,
            "drei" => 3,
        ];

        public function offsetSet($offset, $value): void {
            if (is_null($offset)) {
                $this->container[] = $value;
            } else {
                $this->container[$offset] = $value;
            }
        }

        public function offsetExists($offset): bool {
            return isset($this->container[$offset]);
        }

        public function offsetUnset($offset): void {
            unset($this->container[$offset]);
        }

        public function offsetGet($offset): mixed {
            return isset($this->container[$offset]) ? $this->container[$offset] : null;
        }
    }

    $obj = new Obj;

    var_dump(isset($obj["zwei"]));
    var_dump($obj["zwei"]);
    unset($obj["zwei"]);
    var_dump(isset($obj["zwei"]));
    $obj["zwei"] = "Ein Wert";
    var_dump($obj["zwei"]);
    $obj[] = 'Anhängen 1';
    $obj[] = 'Anhängen 2';
    $obj[] = 'Anhängen 3';
    print_r($obj);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    bool(true)
    int(2)
    bool(false)
    string(7) "Ein Wert"
    Obj Object
    (
        [container] => Array
            (
                [eins] => 1
                [drei] => 3
                [zwei] => Ein Wert
                [0] => Anhängen 1
                [1] => Anhängen 2
                [2] => Anhängen 3
            )

    )

# ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExists — Prüft, ob ein Offset-Punkt existiert

### Beschreibung

public function ArrayAccess::offsetExists(mixed `$offset`): bool

Prüft, ob ein Offset-Punkt existiert oder nicht.

Diese Methode wird aufgerufen, wenn die Funktionen isset() oder empty() auf Objekte angewendet werden, die ArrayAccess implementieren.

> Hinweis:

> Wenn empty() verwendet wird, wird die Funktion ArrayAccess::offsetGet() nur dann aufgerufen und untersucht, ob noch kein Wert zugewiesen wurde, wenn ArrayAccess::offsetExists() `true` zurückgibt.

### Parameter-Liste

`offset`

  Der zu untersuchende Offset-Punkt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

> Hinweis:

> Wenn der Rückgabewert kein Boolean ist, wird er in bool umgewandelt.

### Beispiele

Beispiel #1 ArrayAccess::offsetExists()-Beispiel

    <?php
    class obj implements ArrayAccess {
        public function offsetSet($offset, $wert): void {
            var_dump(__METHOD__);
        }
        public function offsetExists($var): bool {
            var_dump(__METHOD__);
            if ($var == "foobar") {
                return true;
            }
            return false;
        }
        public function offsetUnset($var): void {
            var_dump(__METHOD__);
        }
        #[\ReturnTypeWillChange]
        public function offsetGet($var) {
            var_dump(__METHOD__);
            return "Wert";
        }
    }

    $obj = new obj;

    echo "Ausführung obj::offsetExists()\n";
    var_dump(isset($obj["foobar"]));

    echo "\nAusführung obj::offsetExists() und obj::offsetGet()\n";
    var_dump(empty($obj["foobar"]));

    echo "\nAusführung obj::offsetExists(), "
        ."obj:offsetGet() wird *nicht* ausgeführt, "
        ."wenn nichts zurückgegeben werden kann\n";
    var_dump(empty($obj["foobaz"]));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Ausführung obj::offsetExists()
    string(17) "obj::offsetExists"
    bool(true)

    Ausführung obj::offsetExists() und obj::offsetGet()
    string(17) "obj::offsetExists"
    string(14) "obj::offsetGet"
    bool(false)

    Ausführung obj::offsetExists(), obj:offsetGet() wird *nicht* ausgeführt, wenn nichts zurückgegeben werden kann
    string(17) "obj::offsetExists"
    bool(true)

# ArrayAccess::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGet — Gibt den Wert eines Offset-Punkts zurück

### Beschreibung

public function ArrayAccess::offsetGet(mixed `$offset`): mixed

Gibt den Wert des angegebenen Offset-Punkts zurück.

Diese Methode wird ausgeführt, wenn geprüft wird, ob ein Offset-Punkt empty() ist.

### Parameter-Liste

`offset`

  Der zu untersuchende Offset-Punkt.

### Rückgabewerte

Kann Werte aller Typen zurückgeben.

### Anmerkungen

> Hinweis:

> Es ist möglich, dass Implementierungen dieser Methode als Referenz zurückgeben. Somit ist es möglich Array Offsets von Objekten welche mit ArrayAccess überladen wurden indirekt zu modifizieren.

> Bei einer direkten Änderung wird der Wert eines Array Offsets komplett ersetzt (beispielsweise `$obj[6] = 7`). Bei einer indirekten Änderung wird nur ein Teil des Array Offsets geändert (`$obj[6][7] = 7`) oder das Array Offset einer Variablen per Referenz zugewiesen (`$var =& $obj[6]`). Auch Inkrementierung mit `++` und Dekrementierung mit `--` sind derartig implementiert, dass sie indirekte Änderung erfordern.

> Direkte Änderungen führen zu einem Aufruf von ArrayAccess::offsetSet(), wohingegen indirekte Änderungen in einem Aufruf von ArrayAccess::offsetGet() resultieren. In diesem Fall muss die Implementierung von ArrayAccess::offsetGet() in der Lage sein per Referenz zurückzugeben, ansonsten wird ein `E_NOTICE` Fehler generiert.

### Siehe auch

- ArrayAccess::offsetExists() - Prüft, ob ein Offset-Punkt existiert

# ArrayAccess::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSet — Zuweisen eines Wertes an angegebenen Offset

### Beschreibung

public function ArrayAccess::offsetSet(mixed `$offset`, mixed `$value`): void

Weist dem angegebenen Offset-Punkt einen Wert zu.

### Parameter-Liste

`offset`

  Der Offset-Punkt, dem ein Wert zugewiesen werden soll.

`value`

  Der zuzuweisende Wert.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Anmerkungen

> Hinweis:

> Der `offset`-Parameter wird auf `null` gesetzt, wenn sonst kein anderer Wert verfügbar ist, siehe auch das folgende Beispiel:

>     <?php
>     $arrayaccess[] = "Erster Wert";
>     $arrayaccess[] = "Zweiter Wert";
>     print_r($arrayaccess);
>     ?>

> Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

>     Array
>     (
>         [0] => Erster Wert
>         [1] => Zweiter Wert
>     )

> Hinweis:

> Diese Funktion wird nicht aufgerufen, wenn einer Variable ein Array Offset per Referenz zugewiesen wird oder eine andere indirekte Änderungen eines Array Offsets stattfindet (wenn beispielsweise nur ein Sub-Offset oder eine Sub-Eigenschaft geändert wird). Stattdessen wird ArrayAccess::offsetGet() aufgerufen. Die Operation wird nur erfolgreich sein, wenn jene Methode per Referenz zurückgibt.

# ArrayAccess::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnset — Löschen eines Offsets

### Beschreibung

public function ArrayAccess::offsetUnset(mixed `$offset`): void

Löscht einen Offset-Punkt.

> Hinweis:

> Diese Methode wird nicht aufgerufen, wenn ein Typecast auf (unset) durchgeführt wird.

### Parameter-Liste

`offset`

  Der zu löschende Offset-Punkt.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

## Inhaltsverzeichnis

- ArrayAccess::offsetExists — Prüft, ob ein Offset-Punkt existiert
- ArrayAccess::offsetGet — Gibt den Wert eines Offset-Punkts zurück
- ArrayAccess::offsetSet — Zuweisen eines Wertes an angegebenen Offset
- ArrayAccess::offsetUnset — Löschen eines Offsets

# Das Serializable-Interface

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Einführung

Interface für benutzerdefiniertes Serialisieren.

Die Klassen, die dieses Interface implementieren, unterstützen __sleep und __wakeup nicht mehr. Die Methode serialize wird immer aufgerufen, wenn eine Instanz serialisiert werden muss. Dabei wird weder __destruct() aufgerufen noch irgend ein anderer Nebeneffekt erzeugt, es sei denn, ein solcher wird in der Methode serialize explizit erzeugt. Wenn die Daten deserialisiert werden, ist die Klasse bekannt und die passende unserialize()-Methode wird anstelle des Konstruktors __construct() aufgerufen. Falls notwendig, kann der Standardkonstruktor innerhalb von unserialize() aufgerufen werden.

Warnung

Seit PHP 8.1.0 erzeugt eine Klasse, die Serializable implementiert, ohne gleichzeitig auch __serialize() und __unserialize() zu implementieren, eine Deprecated- (veraltet) Warnung.

## Interface-Übersicht

interface Serializable {
/* Methoden */
public function serialize(): ?string
public function unserialize(string `$data`): void
}

## Beispiele

Beispiel #1 Grundlegende Verwendung

    <?php
    class obj implements Serializable {
        private $data;
        public function __construct() {
            $this->data = "Meine private-Daten";
        }
        public function serialize() {
            return serialize($this->data);
        }
        public function unserialize($data) {
            $this->data = unserialize($data);
        }
        public function getData() {
            return $this->data;
        }
    }

    $obj = new obj;
    $ser = serialize($obj);

    var_dump($ser);

    $newobj = unserialize($ser);

    var_dump($newobj->getData());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(42) "C:3:"obj":27:{s:19:"Meine private-Daten";}"
    string(19) "Meine private-Daten"

# Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serialize — Die String-Darstellung eines Objekts

### Beschreibung

public function Serializable::serialize(): ?string

Die Funktion sollte die String-Darstellung des Objekts zurückgeben.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die String-Darstellung des Objekts oder `null` zurück.

### Fehler/Exceptions

Wirft eine Exception, wenn andere Typen als String oder `null` zurückgegeben werden.

### Siehe auch

- __sleep()
- __serialize()

# Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserialize — Erstellt das Objekt

### Beschreibung

public function Serializable::unserialize(string `$data`): void

Wird beim Deserialisieren des Objekts aufgerufen.

> Hinweis:

> Diese Methode agiert wie der Konstruktor des Objekts. Die __construct-Methode wird nicht nach dieser Methode aufgerufen.

### Parameter-Liste

`data`

  Die String-Darstellung des Objekts.

### Rückgabewerte

Der Rückgabewert dieser Methode wird ignoriert.

### Siehe auch

- __wakeup()
- __unserialize()

## Inhaltsverzeichnis

- Serializable::serialize — Die String-Darstellung eines Objekts
- Serializable::unserialize — Erstellt das Objekt

# Die Klasse Closure

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Einführung

Klasse zur Darstellung von anonymen Funktionen.

Eine anonyme Funktion erzeugt ein Objekt dieses Typs. Diese Klasse enthält Methoden, mit denen eine anonyme Funktion nach ihrer Erstellung weiterhin kontrolliert werden kann.

Neben den hier aufgeführten Methoden hat diese Klasse auch eine `__invoke`-Methode. Dies dient der Konsistenz mit anderen Klassen, die die magische Methode __invoke() implementieren, da diese nicht für den Aufruf von Funktionen verwendet wird.

## Klassenbeschreibung

final class Closure {
/* Methoden */
private function __construct()
public static function bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function call(object `$newThis`, mixed `...$args`): mixed
public static function fromCallable(callable `$callback`): Closure
public static function getCurrent(): Closure
}

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Ausgabe von Closure::__debugInfo() enthält nun den Namen, die Zeile und die Datei der Closure.

# Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__construct — Konstruktor, der keine Instanziierung zulässt

### Beschreibung

private function Closure::__construct()

Diese Methode existiert nur, um die Instanziierung der Klasse Closure zu verbieten. Objekte dieser Klasse werden erstellt, wie auf der Seite Anonyme Funktionen beschrieben.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- Anonyme Funktionen

# Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bind — Dupliziert eine Closure mit einem bestimmten gebundenen Objekt und Geltungsbereich einer Klasse

### Beschreibung

public static function Closure::bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

Diese Methode ist die statische Version von Closure::bindTo(). Siehe die Dokumentation zu dieser Methode für weitere Informationen.

### Parameter-Liste

`closure`

  Die anonymen Funktionen, die gebunden werden sollen.

`newThis`

  Das Objekt, an das die angegebene anonyme Funktion gebunden werden soll, oder `null` wenn die Closure nicht gebunden werden soll.

`newScope`

  Der Geltungsbereich der Klasse, dem die Closure zugeordnet werden soll, oder 'static', um den aktuellen Bereich beizubehalten. Wenn ein Objekt angegeben wird, wird stattdessen der Typ des Objekts verwendet. Dieser bestimmt die Sichtbarkeit der protected und private Methoden des gebundenen Objekts. Es ist nicht erlaubt, eine interne Klasse (oder ein Objekt einer solchen) als Parameter zu übergeben.

### Rückgabewerte

Gibt ein neues Closure-Objekt zurück oder `null`, wenn ein Fehler auftritt.

### Beispiele

Beispiel #1 Closure::bind()-Beispiel

    <?php
    class A {
        private static $sfoo = 1;
        private $ifoo = 2;
    }
    $cl1 = static function() {
        return A::$sfoo;
    };
    $cl2 = function() {
        return $this->ifoo;
    };

    $bcl1 = Closure::bind($cl1, null, 'A');
    $bcl2 = Closure::bind($cl2, new A(), 'A');
    echo $bcl1(), "\n";
    echo $bcl2(), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1
    2

### Siehe auch

- Anonyme Funktionen
- Closure::bindTo() - Dupliziert eine Closure mit einem neuen gebundenen Objekt und Geltungsbereich einer Klasse

# Closure::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindTo — Dupliziert eine Closure mit einem neuen gebundenen Objekt und Geltungsbereich einer Klasse

### Beschreibung

public function Closure::bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure

Erzeugt eine neue anonyme Funktion mit demselben Funktionskörper und denselben gebundenen Variablen wie diese und gibt sie zurück, aber möglicherweise mit einem anderen gebundenen Objekt und einem neuen Geltungsbereich der Klasse.

Das "gebundene Objekt" bestimmt den Wert, den `$this` im Funktionskörper haben wird, und der "Klassenbereich" ist eine Klasse, die bestimmt, auf welche private und protected Mitglieder die anonyme Funktion zugreifen kann. Das heißt, die für die Funktion sichtbaren Mitglieder sind dieselben, als ob die anonyme Funktion eine Methode der im Parameter `newScope` übergebenen Klasse wäre.

Eine statische Closure kann zwar kein Objekt binden (der Wert des Parameters `newThis` muss `null` sein), aber diese Methode kann trotzdem verwendet werden, um den Geltungsbereich ihrer Klasse zu ändern.

Diese Methode stellt sicher, dass eine nicht-statische Closure mit einer gebundenen Instanz einen Geltungsbereich hat und umgekehrt. Zu diesem Zweck wird eine nicht-statische Closure, der zwar ein Geltungsbereich, dafür aber nur eine eine `null`-Instanz gegeben wird, statisch gemacht, und eine nicht-statische Closure ohne Geltungsbereich, die eine Nicht-`null`-Instanz erhält, kommt in den Geltungsbereich einer nicht spezifizierte Klasse.

> Hinweis:

> Wenn nur anonyme Funktionen dupliziert werden sollen, kann stattdessen cloning verwendet werden.

### Parameter-Liste

`newThis`

  Das Objekt, an das die angegebene anonyme Funktion gebunden werden soll, oder `null` wenn die Closure nicht gebunden werden soll.

`newScope`

  Der Bereich der Klasse, dem die Closure zugeordnet werden soll, oder 'static', um den aktuellen Bereich beizubehalten. Wenn ein Objekt angegeben wird, wird stattdessen der Typ des Objekts verwendet. Dieser bestimmt die Sichtbarkeit der protected und private Methoden des gebundenen Objekts. Es ist nicht erlaubt, eine interne Klasse (oder ein Objekt einer solchen) als Parameter zu übergeben.

### Rückgabewerte

Gibt ein neu erstelltes Closure-Objekt zurück oder `null`, wenn ein Fehler auftritt.

### Beispiele

Beispiel #1 Closure::bindTo()-Beispiel

    <?php

    class A
    {
        private $val;

        public function __construct($val)
        {
            $this->val = $val;
        }

        public function getClosure()
        {
            // Gibt eine Closure zurück, die an dieses Objekt und diesen
            // Bereich gebunden ist
            return function() {
                return $this->val;
            };
        }
    }

    $ob1 = new A(1);
    $ob2 = new A(2);

    $cl = $ob1->getClosure();
    echo $cl(), "\n";

    $cl = $cl->bindTo($ob2);
    echo $cl(), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1
    2

### Siehe auch

- Anonyme Funktionen
- Closure::bind() - Dupliziert eine Closure mit einem bestimmten gebundenen Objekt und Geltungsbereich einer Klasse

# Closure::call

(PHP 7, PHP 8)

Closure::call — Bindet eine Closure und ruft sie auf

### Beschreibung

public function Closure::call(object `$newThis`, mixed `...$args`): mixed

Bindet eine Closure vorübergehend an `newThis` und ruft sie mit den angegebenen Parametern auf.

### Parameter-Liste

`newThis`

  Das Objekt, an das die Closure für die Dauer des Aufrufs gebunden wird.

`args`

  Optional können beliebig viele Parameter angegeben werden, die an die Closure übergeben werden sollen.

### Rückgabewerte

Gibt den Rückgabewert der Closure zurück.

### Beispiele

Beispiel #1 Closure::call()-Beispiel

    <?php
    class Value {
        protected $value;

        public function __construct($value) {
            $this->value = $value;
        }

        public function getValue() {
            return $this->value;
        }
    }

    $three = new Value(3);
    $four = new Value(4);

    $closure = function ($delta) { var_dump($this->getValue() + $delta); };
    $closure->call($three, 4);
    $closure->call($four, 4);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(7)
    int(8)

# Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallable — Wandelt ein Callable in eine Closure um

### Beschreibung

public static function Closure::fromCallable(callable `$callback`): Closure

Erzeugt aus dem angegebenen `Callback` eine neue anonyme Funktion im aktuellen Geltungsbereich und gibt diese zurück. Diese Methode prüft, ob der `Callback` im aktuellen Bereich aufrufbar ist und wirft einen TypeError, wenn dies nicht der Fall ist.

> Hinweis:

> Seit PHP 8.1.0 hat Callback-Funktionen als Objekte erster Klasse die gleiche Semantik wie diese Methode.

### Parameter-Liste

`callback`

  Das Callable, das umgewandelt werden soll.

### Rückgabewerte

Gibt die neu erstellte Closure zurück oder wirft einen TypeError, wenn der `callback` nicht im aktuellen Geltungsbereich aufrufbar ist.

### Siehe auch

- Anonyme Funktionen
- Callback-Funktionen als Objekte erster Klasse

# Closure::getCurrent

(PHP 8 >= 8.5.0)

Closure::getCurrent — Returns the currently executing closure

### Beschreibung

public static function Closure::getCurrent(): Closure

Returns the currently executing closure. This method is primarily useful for implementing recursive closures without needing to capture a reference to the closure variable using the `use` keyword.

This method must be called from within a closure; calling it outside of a closure context will result in `Error: Current function is not a closure.`

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the currently executing Closure instance.

### Fehler/Exceptions

Throws an Error if called outside of a closure context.

### Beispiele

Beispiel #1 Closure::getCurrent() example

Using Closure::getCurrent() to implement a recursive Fibonacci function:

    <?php
    $fibonacci = function (int $n) {
        if ($n === 0 || $n === 1) {
            return $n;
        }

        $fn = Closure::getCurrent();
        return $fn($n - 1) + $fn($n - 2);
    };

    echo $fibonacci(10); // Outputs: 55
    ?>

Beispiel #2 Comparison with traditional approach

Prior to PHP 8.5, implementing recursive closures required capturing a reference to the closure variable using the `use` keyword:

    <?php
    // Traditional approach (still works in PHP 8.5)
    $fibonacci = function (int $n) use (&$fibonacci) {
        if ($n === 0) return 0;
        if ($n === 1) return 1;
        return $fibonacci($n - 1) + $fibonacci($n - 2);
    };

    echo $fibonacci(10); // Outputs: 55
    ?>

The Closure::getCurrent() approach eliminates the need to declare the variable with a reference in the `use` clause, making the code cleaner and less error-prone.

## Inhaltsverzeichnis

- Closure::__construct — Konstruktor, der keine Instanziierung zulässt
- Closure::bind — Dupliziert eine Closure mit einem bestimmten gebundenen Objekt und Geltungsbereich einer Klasse
- Closure::bindTo — Dupliziert eine Closure mit einem neuen gebundenen Objekt und Geltungsbereich einer Klasse
- Closure::call — Bindet eine Closure und ruft sie auf
- Closure::fromCallable — Wandelt ein Callable in eine Closure um
- Closure::getCurrent — Returns the currently executing closure

# Die Klasse stdClass

(PHP 4, PHP 5, PHP 7, PHP 8)

## Einführung

Eine generische leere Klasse mit dynamischen Eigenschaften.

Objekte dieser Klasse können mit dem Operator new instanziiert oder durch Konvertierung in ein Objekt erzeugt werden. Auch mehrere PHP-Funktionen erzeugen Instanzen dieser Klasse, z. B. json_decode(), mysqli_fetch_object() oder PDOStatement::fetchObject().

Obwohl diese Klasse die magischen Methoden __get()/__set() nicht implementiert, lässt sie dynamische Eigenschaften zu und benötigt das Attribut `#[\AllowDynamicProperties]` nicht.

Da PHP kein Konzept einer universellen Basisklasse hat, handelt es sich hierbei nicht um eine Basisklasse. Es ist jedoch möglich, eine benutzerdefinierte Klasse zu erstellen, die von stdClass erweitert wird und dadurch die Funktionalität der dynamischen Eigenschaften erbt.

## Klassenbeschreibung

#[\AllowDynamicProperties]
class stdClass {
}

Diese Klasse hat weder Methoden noch Standardeigenschaften.

## Beispiele

Beispiel #1 Erzeugt durch eine Typumwandlung in ein Objekt

    <?php
    $obj = (object) array('foo' => 'bar');
    var_dump($obj);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Beispiel #2 Erzeugt mittels json_decode()

    <?php
    $json = '{"foo":"bar"}';
    var_dump(json_decode($json));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(stdClass)#1 (1) {
      ["foo"]=>
      string(3) "bar"
    }

Beispiel #3 Deklarieren dynamischer Eigenschaften

    <?php
    $obj = new stdClass();
    $obj->foo = 42;
    $obj->{1} = 42;
    var_dump($obj);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(stdClass)#1 (2) {
      ["foo"]=>
      int(42)
      ["1"]=>
      int(42)
    }

# Die Klasse Generator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

Generator-Objekte werden von Generatoren zurückgegeben.

Achtung

Generator-Objekte können nicht durch new instanziiert werden.

## Klassenbeschreibung

final class Generator implements Iterator {
/* Methoden */
public function current(): mixed
public function getReturn(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function send(mixed `$value`): mixed
public function throw(Throwable `$exception`): mixed
public function valid(): bool
public function __wakeup(): void
}

## Siehe auch

Siehe Objekt-Iteration.

# Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::current — Ermittelt den aktuellen Wert eines Generators

### Beschreibung

public function Generator::current(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den ermittelten Wert zurück.

# Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturn — Ermittelt den Rückgabewert eines Generators

### Beschreibung

public function Generator::getReturn(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Rückgabewert eines Generators zurück, nachdem dessen Ausführung beendet ist.

### Beispiele

Beispiel #1 Generator::getReturn()-Beispiel

    <?php

    $gen = (function() {
        yield 1;
        yield 2;

        return 3;
    })();

    foreach ($gen as $val) {
        echo $val, PHP_EOL;
    }

    echo $gen->getReturn(), PHP_EOL;

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1
    2
    3

# Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::key — Ruft einen gelieferten Schlüssel ab

### Beschreibung

public function Generator::key(): mixed

Ermittelt den Schlüssel des gelieferten Wertes.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den gelieferten Schlüssel zurück.

### Beispiele

Beispiel #1 Generator::key()-Beispiel

    <?php

    function Gen()
    {
        yield 'key' => 'value';
    }

    $gen = Gen();

    echo "{$gen->key()} => {$gen->current()}";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    key => value

# Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::next — Setzt die Ausführung eines Generators fort

### Beschreibung

public function Generator::next(): void

Der Aufruf von Generator::next() hat denselben Effekt wie der Aufruf von Generator::send() mit `null` als Argument.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — Führt den Generator bis einschließlich des ersten yield aus

### Beschreibung

public function Generator::rewind(): void

Führt den Generator bis einschließlich zum ersten `yield` aus. Wenn sich der Generator bereits am ersten `yield` befindet, wird keine Aktion ausgeführt. Sobald der Generator jemals über einen `yield`-Ausdruck hinaus fortgesetzt wurde, löst diese Methode eine Exception aus.

> Hinweis:

> Dies ist die erste Methode, die aufgerufen wird, wenn eine `foreach`-Schleife gestartet wird. Sie wird nicht nach `foreach`-Schleifen ausgeführt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 Generator::rewind()-Beispiel

    <?php

    function generator(): Generator
    {
        echo "Ich bin ein Generator!\n";

        for ($i = 1; $i <= 3; $i++) {
            yield $i;
        }
    }

    // Initialisieren des Generators
    $generator = generator();

    // Zurücksetzen des Generators an den Anfang des ersten yield-Ausdrucks,
    // falls er sich noch nicht dort befindet
    $generator->rewind(); // Ich bin ein Generator!

    // Hier passiert nichts, der Generator ist bereits zurückgesetzt.
    $generator->rewind(); // No output (NULL)

    // Dies setzt den Generator auf den ersten yield-Ausdruck zurück, falls
    // er sich noch nicht dort befindet, und iteriert über den Generator
    foreach ($generator as $value) {
        // Nach der Ausgabe des ersten Wertes bleibt der Generator beim ersten
        // yield-Ausdruck stehen, bis er die Ausführung wieder aufnimmt und zum
        // nächsten übergeht
        echo $value, PHP_EOL; // 1

        break;
    }

    // Fortsetzen und erneut zurücksetzen. Es tritt kein Fehler auf, da der
    // Generator nicht über das erste yield hinausgelangt ist
    $generator->rewind();

    echo $generator->current(), PHP_EOL; // 1

    // Es tritt kein Fehler auf, der Generator ist immer noch beim ersten yield
    $generator->rewind();

    // Damit wird der Generator zum zweiten yield-Ausdruck vorgerückt
    $generator->next();

    try {
        // Dies führt zu einer Exception,
        // da der Generator bereits zum zweiten yield vorgerückt ist
        $generator->rewind(); // Fatal error: Uncaught Exception: Cannot rewind a generator that was already run
    } catch (Exception $e) {
        echo $e->getMessage();
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ich bin ein Generator!
    1
    1
    Cannot rewind a generator that was already run

# Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::send — Sendet einen Wert an einen Generator

### Beschreibung

public function Generator::send(mixed `$value`): mixed

Sendet den angegebenen Wert als Ergebnis des aktuellen `yield`-Ausdrucks an den Generator und setzt die Ausführung des Generators fort.

Wenn sich der Generator beim Aufruf dieser Methode noch nicht bei einem `yield`-Ausdruck befindet, kann er zunächst zum ersten `yield`-Ausdruck vorrücken, bevor er den Wert sendet. Daher ist es bei einem PHP-Generator nicht nötig, ihn mit einem Generator::next()-Aufruf "vorzubereiten" (wie es bei Python der Fall ist).

### Parameter-Liste

`value`

  Der Wert, der an den Generator gesendet werden soll. Dieser Wert ist dann der Rückgabewert des `yield`-Ausdrucks, bei dem der Generator gerade steht.

### Rückgabewerte

Gibt den gelieferten Wert zurück.

### Beispiele

Beispiel #1 Werte mittels Generator::send() einfügen

    <?php
    function printer() {
        echo "I'm printer!".PHP_EOL;
        while (true) {
            $string = yield;
            echo $string.PHP_EOL;
        }
    }

    $printer = printer();
    $printer->send('Hello world!');
    $printer->send('Bye world!');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    I'm printer!
    Hello world!
    Bye world!

# Generator::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throw — Wirft eine Exception in einen Generator

### Beschreibung

public function Generator::throw(Throwable `$exception`): mixed

Wirft eine Exception in einem Generator und setzt die Ausführung des Generators fort. Der Generator verhält sich dann so, als wäre der aktuelle `yield`-Ausdruck durch eine `throw $exception`-Anweisung ersetzt worden.

Wenn der Generator beim Aufruf dieser Methode bereits geschlossen ist, wird die Exception stattdessen im Kontext des aufrufenden Codes geworfen.

### Parameter-Liste

`exception`

  Die Exception, die in den Generator geworfen wird.

### Rückgabewerte

Gibt den gelieferten Wert zurück.

### Beispiele

Beispiel #1 Eine Exception in einen Generator werfen

    <?php
    function gen() {
        echo "Foo\n";
        try {
            yield;
        } catch (Exception $e) {
            echo "Exception: {$e->getMessage()}\n";
        }
        echo "Bar\n";
    }

    $gen = gen();
    $gen->rewind();
    $gen->throw(new Exception('Test'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Foo
    Exception: Test
    Bar

# Generator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::valid — Prüft, ob der Iterator geschlossen wurde

### Beschreibung

public function Generator::valid(): bool

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Wenn der Iterator geschlossen wurde, wird `false` zurückgegeben, andernfalls `true`.

# Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeup — Serialisierungs-Callback

### Beschreibung

public function Generator::__wakeup(): void

Wirft eine Exception, weil Generatoren nicht serialisiert werden können.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

## Inhaltsverzeichnis

- Generator::current — Ermittelt den aktuellen Wert eines Generators
- Generator::getReturn — Ermittelt den Rückgabewert eines Generators
- Generator::key — Ruft einen gelieferten Schlüssel ab
- Generator::next — Setzt die Ausführung eines Generators fort
- Generator::rewind — Führt den Generator bis einschließlich des ersten yield aus
- Generator::send — Sendet einen Wert an einen Generator
- Generator::throw — Wirft eine Exception in einen Generator
- Generator::valid — Prüft, ob der Iterator geschlossen wurde
- Generator::__wakeup — Serialisierungs-Callback

# Die Klasse Fiber

(PHP 8 >= 8.1.0)

## Einführung

Fibers stellen unterbrechbare Funktionen dar, die den gesamten Stapel (Stack) abdecken. Fibers können an einer beliebigen Stelle im Aufrufstapel (Call-Stack) unterbrochen werden, wodurch die Ausführung innerhalb der Fiber unterbrochen wird, bis die Fiber zu einem späteren Zeitpunkt wieder fortgesetzt wird.

## Klassenbeschreibung

final class Fiber {
/* Methoden */
public function __construct(callable `$callback`)
public function start(mixed `...$args`): mixed
public function resume(mixed `$value` = `null`): mixed
public function throw(Throwable `$exception`): mixed
public function getReturn(): mixed
public function isStarted(): bool
public function isSuspended(): bool
public function isRunning(): bool
public function isTerminated(): bool
public static function suspend(mixed `$value` = `null`): mixed
public static function getCurrent(): ?Fiber
}

## Siehe auch

Übersicht über Fibers

# Fiber::__construct

(PHP 8 >= 8.1.0)

Fiber::__construct — Erstellt eine neue Instanz von Fiber

### Beschreibung

public function Fiber::__construct(callable `$callback`)

### Parameter-Liste

`callback`

  Das callable, der beim Starten der Fiber aufgerufen wird. Die Argumente, die an Fiber::start() übergeben werden, werden als Argumente an das angegebene Callable übergeben.

# Fiber::start

(PHP 8 >= 8.1.0)

Fiber::start — Startet die Ausführung einer Fiber

### Beschreibung

public function Fiber::start(mixed `...$args`): mixed

Eine variable Liste von Argumenten, die dem beim Aufbau der Fiber verwendeten Callable übergeben werden.

Wenn die Fiber zum Zeitpunkt des Aufrufs dieser Methode bereits gestartet wurde, wird ein FiberError geworfen.

### Parameter-Liste

`args`

  Die Argumente, die beim Aufruf des im Konstruktor der Fiber angegebenen Callables zu verwenden sind.

### Rückgabewerte

Gibt den Wert zurück, der dem ersten Aufruf von Fiber::suspend() übergeben wird, oder `null`, wenn die Fiber einen Rückgabewert liefert. Wenn die Fiber eine Exception wirft, bevor sie unterbrochen wird, wird diese beim Aufruf dieser Methode geworfen.

# Fiber::resume

(PHP 8 >= 8.1.0)

Fiber::resume — Setzt die Ausführung einer Fiber mit einem Wert fort

### Beschreibung

public function Fiber::resume(mixed `$value` = `null`): mixed

Setzt die Fiber mit dem angegebenen Wert als Ergebnis des aktuellen Fiber::suspend()-Aufrufs fort.

Wenn die Fiber zum Zeitpunkt des Aufrufs dieser Methode nicht unterbrochen ist, wird ein FiberError geworfen.

### Parameter-Liste

`value`

  Der Wert, mit dem die Fiber fortgesetzt wird. Dieser Wert ist der Rückgabewert des aktuellen Fiber::suspend()-Aufrufs.

### Rückgabewerte

Gibt den Wert zurück, der dem nächsten Aufruf von Fiber::suspend() übergeben wird, oder `null`, wenn die Fiber einen Rückgabewert liefert. Wenn die Fiber eine Exception wirft, bevor sie unterbrochen wird, wird diese beim Aufruf dieser Methode geworfen.

# Fiber::throw

(PHP 8 >= 8.1.0)

Fiber::throw — Setzt die Ausführung einer Fiber mit einer Exception fort

### Beschreibung

public function Fiber::throw(Throwable `$exception`): mixed

Setzt eine Fiber fort, indem es die Exception des aktuellen Fiber::suspend()-Aufrufs wirft.

Wenn die Fiber zum Zeitpunkt des Aufrufs dieser Methode nicht unterbrochen ist, wird ein FiberError geworfen.

### Parameter-Liste

`exception`

  Die Exception vom aktuellen Fiber::suspend()-Aufruf, die in die Fiber geworfen wird.

### Rückgabewerte

Gibt den Wert zurück, der dem nächsten Aufruf von Fiber::suspend() übergeben wird, oder `null`, wenn die Fiber einen Rückgabewert liefert. Wenn die Fiber eine Exception wirft, bevor sie unterbrochen wird, wird diese beim Aufruf dieser Methode geworfen.

### Beispiele

    <?php

    $fiber = new Fiber(function () {
       try {
           // Unterbricht die Ausführung der Fiber und deklariert dabei einen Unterbrechungspunkt
           Fiber::suspend();
       } catch (Throwable $e) {
           echo $e->getMessage();
       }
    });

    $fiber->start();

    // Setzt die Ausführung der Fiber fort und übergibt
    // die Exception, die am aktuellen Unterbrechungspunkt geworfen werden soll
    $fiber->throw(new Exception('Message of an exception thrown at the current interrupt point'));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Message of an exception thrown at the current interrupt point

# Fiber::getReturn

(PHP 8 >= 8.1.0)

Fiber::getReturn — Ermittelt den von einer Fiber zurückgegebenen Wert

### Beschreibung

public function Fiber::getReturn(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Wert zurück, der von der Callable an Fiber::__construct() übergeben wurde. Wenn die Fiber keinen Wert zurückgegeben hat, entweder weil sie nicht gestartet wurde, nicht beendet wurde oder eine Exception geworfen hat, wird ein FiberError geworfen.

# Fiber::isStarted

(PHP 8 >= 8.1.0)

Fiber::isStarted — Prüft, ob eine Fiber gestartet wurde

### Beschreibung

public function Fiber::isStarted(): bool

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt nur dann `true` zurück, wenn eine Fiber gestartet wurde; andernfalls wird `false` zurückgegeben.

# Fiber::isSuspended

(PHP 8 >= 8.1.0)

Fiber::isSuspended — Prüft, ob eine Fiber unterbrochen wurde

### Beschreibung

public function Fiber::isSuspended(): bool

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn eine Fiber gerade unterbrochen ist; andernfalls wird `false` zurückgegeben.

# Fiber::isRunning

(PHP 8 >= 8.1.0)

Fiber::isRunning — Prüft, ob gerade eine Fiber aktiv ist

### Beschreibung

public function Fiber::isRunning(): bool

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt nur dann `true` zurück, wenn eine Fiber aktiv ist. Eine Fiber wird als aktiv betrachtet, nachdem Fiber::start() oder Fiber::resume() aufgerufen wurde oder Fiber::throw(), das noch nicht abgeschlossen ist. Gibt `false` zurück, wenn keine Fiber aktiv ist.

# Fiber::isTerminated

(PHP 8 >= 8.1.0)

Fiber::isTerminated — Prüft, ob eine Fiber beendet wurde

### Beschreibung

public function Fiber::isTerminated(): bool

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt nur dann `true` zurück, wenn eine Fiber beendet wurde, d. h. wenn entweder ein Wert zurückgegeben oder eine Exception geworfen wurde; andernfalls wird `false` zurückgegeben.

# Fiber::suspend

(PHP 8 >= 8.1.0)

Fiber::suspend — Unterbricht die Ausführung der aktuellen Fiber

### Beschreibung

public static function Fiber::suspend(mixed `$value` = `null`): mixed

Unterbricht die Ausführung der aktuellen Fiber. Der Wert, der dieser Methode übergeben wird, wurde vom Aufruf von Fiber::start(), Fiber::resume() oder Fiber::throw() zurückgegeben, der die Ausführung der aktuellen Fiber aktiviert hat.

Wenn die Fiber fortgesetzt wurde, gibt diese Methode den Wert zurück, der Fiber::resume() übergeben wurde. Wenn die Fiber mit Fiber::throw() fortgesetzt wurde, wird die an jene Methode übergebene Exception beim Aufruf dieser Methode geworfen.

Wenn diese Methode von außerhalb einer Fiber aufgerufen wird, wird ein FiberError geworfen.

### Parameter-Liste

`value`

  Der Wert, der vom Aufruf von Fiber::start(), Fiber::resume() oder Fiber::throw() zurückgegeben wurde, der die Ausführung der aktuellen Fiber aktiviert hat.

### Rückgabewerte

Gibt den Wert zurück, der an Fiber::resume() übergeben wurde.

# Fiber::getCurrent

(PHP 8 >= 8.1.0)

Fiber::getCurrent — Ermittelt die aktuell laufende Instanz von Fiber

### Beschreibung

public static function Fiber::getCurrent(): ?Fiber

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die aktuell laufende Instanz von Fiber zurück oder `null`, wenn diese Methode außerhalb einer Fiber aufgerufen wird.

## Inhaltsverzeichnis

- Fiber::__construct — Erstellt eine neue Instanz von Fiber
- Fiber::start — Startet die Ausführung einer Fiber
- Fiber::resume — Setzt die Ausführung einer Fiber mit einem Wert fort
- Fiber::throw — Setzt die Ausführung einer Fiber mit einer Exception fort
- Fiber::getReturn — Ermittelt den von einer Fiber zurückgegebenen Wert
- Fiber::isStarted — Prüft, ob eine Fiber gestartet wurde
- Fiber::isSuspended — Prüft, ob eine Fiber unterbrochen wurde
- Fiber::isRunning — Prüft, ob gerade eine Fiber aktiv ist
- Fiber::isTerminated — Prüft, ob eine Fiber beendet wurde
- Fiber::suspend — Unterbricht die Ausführung der aktuellen Fiber
- Fiber::getCurrent — Ermittelt die aktuell laufende Instanz von Fiber

# Die Klasse WeakReference

(PHP 7 >= 7.4.0, PHP 8)

## Einführung

Schwache Referenzen erlauben es dem Programmierer, eine Referenz auf ein Objekt zu behalten, die nicht verhindert, dass das Objekt zerstört wird. Sie sind nützlich für die Implementierung von Cache-ähnlichen Strukturen. Wenn das ursprüngliche Objekt zerstört wurde, wird beim Aufruf der Methode WeakReference::get() `null` zurückgegeben. Wenn der Referenzzähler für das ursprüngliche Objekt auf Null fällt, wird es zerstört; das Erstellen von schwachen Referenzen erhöht den `refcount` des referenzierten Objekts nicht.

WeakReferences können nicht serialisiert werden.

## Klassenbeschreibung

final class WeakReference {
/* Methoden */
public function __construct()
public static function create(object `$object`): WeakReference
public function get(): ?object
}

## WeakReference-Beispiele

Beispiel #1 Grundlegende Verwendung von WeakReference

    <?php

    $obj = new stdClass();
    $weakref = WeakReference::create($obj);

    var_dump($weakref->get());

    unset($obj);

    var_dump($weakref->get());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#1 (0) {
    }
    NULL

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Ausgabe von WeakReference::__debugInfo() enthält nun das referenzierte Objekt oder `NULL`, wenn die Referenz nicht mehr gültig ist.

# WeakReference::__construct

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::__construct — Konstruktor, der Instanziierung verhindert

### Beschreibung

public function WeakReference::__construct()

Diese Methode dient nur dazu, die Instanziierung der Klasse WeakReference zu verbieten. Schwache Referenzen müssen mit der Werksmethode WeakReference::create() instanziiert werden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- WeakReference::create() - Erzeugt eine neue schwache Referenz

# WeakReference::create

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::create — Erzeugt eine neue schwache Referenz

### Beschreibung

public static function WeakReference::create(object `$object`): WeakReference

Erzeugt eine neue WeakReference.

### Parameter-Liste

`object`

  Das Objekt, das schwach referenziert werden soll

### Rückgabewerte

Gibt eine neue WeakReference zurück oder die vorhandene Instanz, wenn es für dasselbe Objekt bereits eine WeakReference gibt.

# WeakReference::get

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::get — Ruft ein schwach referenziertes Objekt ab

### Beschreibung

public function WeakReference::get(): ?object

Ruft ein schwach referenziertes Objekt ab. Wenn das Objekt bereits gelöscht wurde, wird `null` zurückgegeben.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das referenzierte Objekt zurück, oder `null`, wenn das Objekt gelöscht wurde.

## Inhaltsverzeichnis

- WeakReference::__construct — Konstruktor, der Instanziierung verhindert
- WeakReference::create — Erzeugt eine neue schwache Referenz
- WeakReference::get — Ruft ein schwach referenziertes Objekt ab

# Die Klasse WeakMap

(PHP 8)

## Einführung

Eine WeakMap ist eine Zuordnungstabelle (Map oder Dictionary), die Objekte als Schlüssel akzeptiert. Jedoch - anders als bei einem ansonsten ähnlichen SplObjectStorage - zählt ein Objekt, welches in einer WeakMap enthalten ist, nicht auf dessen Referenzzähler ein. Das bedeutet, dass wenn zu einem beliebigen Zeitpunkt die letzte verbleibende Referenz auf ein Objekt diejenige in einer WeakMap ist, wird das Objekt durch die Garbage Collection bereinigt und aus der WeakMap entfernt. Der primäre Anwendungsfall ist das Erzeugen eines Caches von Daten, die sich aus einem Objekt ableiten und keine längere Lebensdauer als das zugrunde liegende Objekt benötigen.

WeakMap implementiert ArrayAccess, Traversable (über IteratorAggregate), und Countable, kann also in den meisten Fällen genau wie ein assoziatives Array verwendet werden.

## Klassenbeschreibung

final class WeakMap implements ArrayAccess, Countable, IteratorAggregate {
/* Methoden */
public function count(): int
public function getIterator(): Iterator
public function offsetExists(object `$object`): bool
public function offsetGet(object `$object`): mixed
public function offsetSet(object `$object`, mixed `$value`): void
public function offsetUnset(object `$object`): void
}

## Beispiele

Beispiel #1 Weakmap-Anwendungsbeispiel

    <?php
    $wm = new WeakMap();

    $o = new stdClass;

    class A {
        public function __destruct() {
            echo "Zerstört!\n";
        }
    }

    $wm[$o] = new A;

    var_dump(count($wm));
    echo "Entferne...\n";
    unset($o);
    echo "Fertig\n";
    var_dump(count($wm));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)
    Entferne...
    Zerstört!
    Fertig
    int(0)

# WeakMap::count

(PHP 8)

WeakMap::count — Zählt die aktiven Einträge in der Map

### Beschreibung

public function WeakMap::count(): int

Zählt die aktiven Einträge in der Map.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der aktiven Einträge in der Map zurück.

# WeakMap::getIterator

(PHP 8)

WeakMap::getIterator — Liefert einen externen Iterator

### Beschreibung

public function WeakMap::getIterator(): Iterator

Gibt einen externen Iterator zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Eine Instanz eines Objektes, welches Iterator oder Traversable implementiert

### Fehler/Exceptions

Wirft im Fehlerfall eine Exception.

# WeakMap::offsetExists

(PHP 8)

WeakMap::offsetExists — Prüft, ob ein bestimmtes Objekt in der Map enthalten ist

### Beschreibung

public function WeakMap::offsetExists(object `$object`): bool

Prüft, ob eine Referenz auf das übergebene Objekt in der Map enthalten ist.

### Parameter-Liste

`object`

  Das zu prüfende Objekt.

### Rückgabewerte

Gibt `true` zurück, wenn das Objekt in der Map enthalten ist, andernfalls `false`.

# WeakMap::offsetGet

(PHP 8)

WeakMap::offsetGet — Gibt den Wert zurück, der einem bestimmten Objekt zugeordnet ist

### Beschreibung

public function WeakMap::offsetGet(object `$object`): mixed

Gibt den Wert zurück, der einem bestimmten Objekt zugeordnet ist.

### Parameter-Liste

`object`

  Ein beliebiges Objekt, das als Schlüssel in der Map enthalten ist.

### Rückgabewerte

Gibt den dem als Parameter übergebenen Objekt zugewiesenen Wert zurück.

### Fehler/Exceptions

Wirft bei einem Fehler einen Error.

# WeakMap::offsetSet

(PHP 8)

WeakMap::offsetSet — Aktualisiert die Map mit einem neuen Schlüssel-Wert-Paar

### Beschreibung

public function WeakMap::offsetSet(object `$object`, mixed `$value`): void

Aktualisiert die Map mit einem neuen Schlüssel-Wert-Paar. Falls der Schlüssel bereit in der Map enthalten war, wird der bereits enthaltene Wert durch einen neuen Wert ersetzt.

### Parameter-Liste

`object`

  Das Objekt, welches als Schlüssel für das Schlüssel-Wert-Paar fungiert.

`value`

  Beliebige Daten, die als Wert für das Schlüssel-Wert-Paar fungieren.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# WeakMap::offsetUnset

(PHP 8)

WeakMap::offsetUnset — Entfernt einen Eintrag aus der Map

### Beschreibung

public function WeakMap::offsetUnset(object `$object`): void

Entfernt einen Eintrag aus der Map.

### Parameter-Liste

`object`

  Das Schlüsselobjekt, welches aus der Map entfernt werden soll.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

## Inhaltsverzeichnis

- WeakMap::count — Zählt die aktiven Einträge in der Map
- WeakMap::getIterator — Liefert einen externen Iterator
- WeakMap::offsetExists — Prüft, ob ein bestimmtes Objekt in der Map enthalten ist
- WeakMap::offsetGet — Gibt den Wert zurück, der einem bestimmten Objekt zugeordnet ist
- WeakMap::offsetSet — Aktualisiert die Map mit einem neuen Schlüssel-Wert-Paar
- WeakMap::offsetUnset — Entfernt einen Eintrag aus der Map

# Das Stringable-Interface

(PHP 8)

## Einführung

Das Interface Stringable kennzeichnet, dass eine Klasse eine __toString()-Methode enthält. Anders als die meisten anderen Interfaces, ist das Interface Stringable implizit bei allen Klassen präsent, welche die magische Methode __toString() enthalten. Das Interface kann und sollte jedoch explizit deklariert werden.

Der primäre Anwendungsfall ist es, Funktionen eine Typenüberprüfung gegen den Vereinigungstypen `string|Stringable` zu ermöglichen. Damit können diese entweder eine Zeichenkette oder ein Objekt akzeptieren, welches in eine Zeichenkette umgewandelt werden kann.

## Interface-Übersicht

interface Stringable {
/* Methoden */
public function __toString(): string
}

## Stringable-Beispiele

Beispiel #1 Grundlegende Verwendung von Stringable

Dieses Beispiel verwendet die Promotion (Beförderung) von Konstruktoreigenschaften.

    <?php
    class IPv4Address implements Stringable {
        public function __construct(
            private string $oct1,
            private string $oct2,
            private string $oct3,
            private string $oct4,
        ) {}

        public function __toString(): string {
            return "$this->oct1.$this->oct2.$this->oct3.$this->oct4";
        }
    }

    function showStuff(string|Stringable $value) {
        // Bei einem Stringable wird damit implizit __toString() aufgerufen.
        print $value;
    }

    $ip = new IPv4Address('123', '234', '42', '9');

    showStuff($ip);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    123.234.42.9

# Stringable::__toString

(PHP 8)

Stringable::__toString — Liefert die String-Darstellung eines Objekts

### Beschreibung

public function Stringable::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die String-Darstellung des Objekts zurück.

### Siehe auch

- __toString()

## Inhaltsverzeichnis

- Stringable::__toString — Liefert die String-Darstellung eines Objekts

# Die UnitEnum-Schnittstelle

(PHP 8 >= 8.1.0)

## Einführung

Die UnitEnum-Schnittstelle wird von der PHP-Engine automatisch auf alle Aufzählungen (Enumerations) angewendet. Sie darf nicht von benutzerdefinierten Klassen implementiert werden. Aufzählungen dürfen ihre Methoden nicht überschreiben, weil die Engine Standard-Implementierungen zur Verfügung stellt. Sie ist nur für Typprüfungen vorgesehen.

## Interface-Übersicht

interface UnitEnum {
/* Methoden */
public static function cases(): array
}

# UnitEnum::cases

(PHP 8 >= 8.1.0)

UnitEnum::cases — Liefert eine Liste der Fälle einer Enum

### Beschreibung

public static function UnitEnum::cases(): array

Diese Methode gibt ein gepacktes Array aller Fälle einer Aufzählung (Enumeration) in der Reihenfolge ihrer Deklaration zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array mit allen definierten Fällen dieser Aufzählung in der Reihenfolge ihrer Deklaration zurück.

### Beispiele

Beispiel #1 Grundlegende Verwendung

Das folgende Beispiel zeigt, wie Enum-Fälle zurückgegeben werden.

    <?php
    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
        [0]=>
        enum(Suit::Hearts)
        [1]=>
        enum(Suit::Diamonds)
        [2]=>
        enum(Suit::Clubs)
        [3]=>
        enum(Suit::Spades)
    }

## Inhaltsverzeichnis

- UnitEnum::cases — Liefert eine Liste der Fälle einer Enum

# Die BackedEnum-Schnittstelle

(PHP 8 >= 8.1.0)

## Einführung

Die BackedEnum-Schnittstelle wird von der PHP-Engine automatisch auf Backed Enums angewendet. Sie darf nicht von benutzerdefinierten Klassen implementiert werden. Aufzählungen (Enumerations) dürfen ihre Methoden nicht überschreiben, da die Standardimplementierung von der Engine bereitgestellt wird. Diese Schnittstelle existiert ausschließlich für Typüberprüfungen.

## Interface-Übersicht

interface BackedEnum extends UnitEnum {
/* Methoden */
public static function from(int|string `$value`): static
public static function tryFrom(int|string `$value`): ?static
/* Geerbte Methoden */
public static function UnitEnum::cases(): array
}

# BackedEnum::from

(PHP 8 >= 8.1.0)

BackedEnum::from — Ordnet einen Skalar einer Enum-Instanz zu

### Beschreibung

public static function BackedEnum::from(int|string `$value`): static

Die Methode from() übersetzt einen Wert vom Typ string oder int in den entsprechenden Enum-Fall, falls vorhanden. Wenn kein passender Fall definiert ist, wird ein ValueError geworfen.

### Parameter-Liste

`value`

  Der skalare Wert, der einem Enum-Fall zugeordnet werden soll.

### Rückgabewerte

Gibt eine Instanz eines Falles dieser Aufzählung zurück.

### Beispiele

Beispiel #1 Grundlegende Verwendung

Das folgende Beispiel zeigt, wie Enum-Fälle zurückgegeben werden.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::from('H');

    var_dump($h);

    $b = Suit::from('B');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    enum(Suit::Hearts)

    Fatal error: Uncaught ValueError: "B" is not a valid backing value for enum "Suit" in /file.php:15

### Siehe auch

- UnitEnum::cases() - Liefert eine Liste der Fälle einer Enum
- BackedEnum::tryFrom() - Ordnet einen Skalar einer Enum-Instanz oder null zu

# BackedEnum::tryFrom

(PHP 8 >= 8.1.0)

BackedEnum::tryFrom — Ordnet einen Skalar einer Enum-Instanz oder `null` zu

### Beschreibung

public static function BackedEnum::tryFrom(int|string `$value`): ?static

Die Methode tryFrom() übersetzt einen Wert vom Typ string oder int in den entsprechenden Enum-Fall, falls vorhanden. Wenn kein passender Fall definiert ist, wird `null` zurückgegeben.

### Parameter-Liste

`value`

  Der skalare Wert, der einem Enum-Fall zugeordnet werden soll.

### Rückgabewerte

Gibt eine Instanz eines Falles dieser Aufzählung zurück oder null, falls diese nicht gefunden wird.

### Beispiele

Beispiel #1 Grundlegende Verwendung

Das folgende Beispiel zeigt, wie Enum-Fälle zurückgegeben werden.

    <?php
    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $h = Suit::tryFrom('H');

    var_dump($h);

    $b = Suit::tryFrom('B') ?? Suit::Spades;

    var_dump($b);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    enum(Suit::Hearts)
    enum(Suit::Spades)

### Siehe auch

- UnitEnum::cases() - Liefert eine Liste der Fälle einer Enum
- BackedEnum::from() - Ordnet einen Skalar einer Enum-Instanz zu

## Inhaltsverzeichnis

- BackedEnum::from — Ordnet einen Skalar einer Enum-Instanz zu
- BackedEnum::tryFrom — Ordnet einen Skalar einer Enum-Instanz oder null zu

# Die Klasse SensitiveParameterValue

(PHP 8 >= 8.2.0)

## Einführung

Die Klasse SensitiveParameterValue ermöglicht es, sensible Werte zu umhüllen, um sie vor versehentlicher Offenlegung zu schützen.

Werte von Parametern mit dem Attribut SensitiveParameter werden in Stacktraces automatisch in einem SensitiveParameterValue-Objekt verpackt.

## Klassenbeschreibung

final class SensitiveParameterValue {
/* Eigenschaften */
private readonly mixed $value;
/* Methoden */
public function __construct(mixed `$value`)
public function __debugInfo(): array
public function getValue(): mixed
}

## Eigenschaften

value

  Der sensible Wert, der vor versehentlicher Offenlegung geschützt werden soll.

# SensitiveParameterValue::__construct

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__construct — Erstellt ein neues SensitiveParameterValue-Objekt

### Beschreibung

public function SensitiveParameterValue::__construct(mixed `$value`)

Erstellt eine neue Instanz von SensitiveParameterValue, die einen vertraulichen Wert enthält.

### Parameter-Liste

`value`

  Ein beliebiger Wert, der im SensitiveParameterValue-Objekt gespeichert werden soll.

# SensitiveParameterValue::__debugInfo

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__debugInfo — Schützt einen sensiblen Wert vor versehentlicher Offenlegung

### Beschreibung

public function SensitiveParameterValue::__debugInfo(): array

Gibt ein leeres Array zurück, um den sensiblen Wert bei Verwendung von var_dump() vor versehentlicher Offenlegung zu schützen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Ein leeres Array

### Beispiele

Beispiel #1 Übergabe eines SensitiveParameterValue-Objekts an var_dump()

    <?php
    $s = new \SensitiveParameterValue('geheim');

    var_dump($s);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(SensitiveParameterValue)#1 (0) {
    }

# SensitiveParameterValue::getValue

(PHP 8 >= 8.2.0)

SensitiveParameterValue::getValue — Liefert einen sensiblen Wert

### Beschreibung

public function SensitiveParameterValue::getValue(): mixed

Ruft den sensiblen Wert ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den sensiblen Wert zurück.

### Beispiele

Beispiel #1 SensitiveParameterValue::getValue()-Beispiel

    <?php
    $s = new \SensitiveParameterValue('geheim');

    echo "Der geschützte Wert ist: ", $s->getValue(), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Der geschützte Wert ist: geheim

## Inhaltsverzeichnis

- SensitiveParameterValue::__construct — Erstellt ein neues SensitiveParameterValue-Objekt
- SensitiveParameterValue::__debugInfo — Schützt einen sensiblen Wert vor versehentlicher Offenlegung
- SensitiveParameterValue::getValue — Liefert einen sensiblen Wert

# Die Klasse __PHP_Incomplete_Class

(PHP 4 >=4.0.1, PHP 5, PHP 7, PHP 8)

## Einführung

Wird von der Funktion unserialize() erzeugt, wenn versucht wird, eine undefinierte Klasse zu deserialisieren oder eine Klasse, die nicht in `allowed_classes` des `options`-Arrays von unserialize() aufgeführt ist.

Vor PHP 7.2.0 gab die Funktion is_object() `false` zurück, wenn sie auf ein Objekt der Klasse __PHP_Incomplete_Class angewendet wurde. Seit PHP 7.2.0 gibt sie `true` zurück.

## Klassenbeschreibung

#[\AllowDynamicProperties]
final class __PHP_Incomplete_Class {
}

Diese Klasse hat keine Standardeigenschaften oder -methoden. Wenn sie mittels unserialize() erzeugt wird, hat sie zusätzlich zu allen deserialisierten Eigenschaften und Werten die Eigenschaft `__PHP_Incomplete_Class_Name`, die den Namen der deserialisierten Klasse enthält.

## Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Klasse ist nun `final`.

## Beispiele

Beispiel #1 Erzeugt durch unserialize()

    <?php

    class MyClass
    {
        public string $property = "myValue";
    }

    $myObject = new MyClass;

    $foo = serialize($myObject);

    // Desialisiert alle Objekte zu __PHP_Incomplete_Class-Objekten
    $disallowed = unserialize($foo, ["allowed_classes" => false]);

    var_dump($disallowed);

    // Deserialisiert alle Objekte außer denen von MyClass2 und MyClass3
    // zu __PHP_Incomplete_Class-Objekten
    $disallowed2 = unserialize($foo, ["allowed_classes" => ["MyClass2", "MyClass3"]]);

    var_dump($disallowed2);

    // Deserialisiert die undefinierte Klasse zu einem __PHP_Incomplete_Class-Objekt
    $undefinedClass = unserialize('O:16:"MyUndefinedClass":0:{}');

    var_dump($undefinedClass);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(__PHP_Incomplete_Class)#2 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#3 (2) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(7) "MyClass"
      ["property"]=>
      string(7) "myValue"
    }
    object(__PHP_Incomplete_Class)#4 (1) {
      ["__PHP_Incomplete_Class_Name"]=>
      string(16) "MyUndefinedClass"
    }

# Vordefinierte Attribute

## Inhaltsverzeichnis

- Attribute
- AllowDynamicProperties
- DelayedTargetValidation
- Deprecated
- NoDiscard
- Override
- ReturnTypeWillChange
- SensitiveParameter

PHP stellt einige vordefinierte Attribute zur Verfügung.

# Das Attribut Attribute

(PHP 8)

## Einführung

Attribute bieten die Möglichkeit, strukturierte, maschinenlesbare Metadaten-Informationen über Deklarationen in den Code einfügen: Attribute können für Klassen, Methoden, Funktionen, Parameter, Eigenschaften und Klassenkonstanten verwendet werden. Die durch Attribute definierten Metadaten können dann zur Laufzeit mit Hilfe der Reflection-APIs inspiziert werden. Attribute können daher als eine direkt in den Code eingebettete Konfigurationssprache betrachtet werden.

## Klassenbeschreibung

#[\Attribute]
final class Attribute {
/* Konstanten */
const int TARGET_CLASS;
const int TARGET_FUNCTION;
const int TARGET_METHOD;
const int TARGET_PROPERTY;
const int TARGET_CLASS_CONSTANT;
const int TARGET_PARAMETER;
const int TARGET_ALL;
const int IS_REPEATABLE;
/* Eigenschaften */
public int $flags;
/* Methoden */
public function __construct(int `$flags` = Attribute::TARGET_ALL)
}

## Vordefinierte Konstanten

Attribute::TARGET_CLASS

Attribute::TARGET_FUNCTION

Attribute::TARGET_METHOD

Attribute::TARGET_PROPERTY

Attribute::TARGET_CLASS_CONSTANT

Attribute::TARGET_PARAMETER

Attribute::TARGET_ALL

Attribute::IS_REPEATABLE

## Eigenschaften

flags

## Siehe auch

Übersicht über die Attribute

# Attribute::__construct

(PHP 8)

Attribute::__construct — Erstellt eine neue Instanz von Attribute

### Beschreibung

public function Attribute::__construct(int `$flags` = `Attribute::TARGET_ALL`)

Erstellt eine neue Instanz von Attribute.

### Parameter-Liste

`flags`

## Inhaltsverzeichnis

- Attribute::__construct — Erstellt eine neue Instanz von Attribute

# Das Attribut AllowDynamicProperties

(PHP 8 >= 8.2.0)

## Einführung

Dieses Attribut wird verwendet, um Klassen zu kennzeichnen, die dynamische Eigenschaften erlauben.

## Klassenbeschreibung

#[\Attribute]
final class AllowDynamicProperties {
/* Methoden */
public function __construct()
}

## Beispiele

Dynamische Eigenschaften sind seit PHP 8.2.0 veraltet. Wenn sie in einer Klasse verwendet werden, ohne diese mit diesem Attribut zu kennzeichnen, wird ein entsprechender Hinweis ausgegeben.

    <?php
    class DefaultBehaviour { }

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties { }

    $o1 = new DefaultBehaviour();
    $o2 = new ClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;
    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.2 folgende Ausgabe:

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 10

## Siehe auch

Übersicht über die Attribute

# AllowDynamicProperties::__construct

(PHP 8 >= 8.2.0)

AllowDynamicProperties::__construct — Erstellt eine neue Instanz des Attributs AllowDynamicProperties

### Beschreibung

public function AllowDynamicProperties::__construct()

Erstellt eine neue Instanz von AllowDynamicProperties.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

## Inhaltsverzeichnis

- AllowDynamicProperties::__construct — Erstellt eine neue Instanz des Attributs AllowDynamicProperties

# The DelayedTargetValidation attribute

(PHP 8 >= 8.5.0)

## Einführung

This attribute delays target validation errors for internal attributes from compile time to when the attribute is instantiated via the Reflection API.

When applied to a declaration, any invalid usage of internal attributes on the same target will not trigger a compile time error. Instead, the validation is deferred and performed when the attribute is instantiated via ReflectionAttribute::newInstance().

This is primarily intended for forward compatibility, allowing code to use attributes that may gain additional valid targets in future PHP versions without breaking on older versions.

## Klassenbeschreibung

#[\Attribute]
final class DelayedTargetValidation {
}

## Beispiele

Beispiel #1 Delaying validation of an invalid target

    <?php

    class Base {
        protected function foo(): void {}
    }

    class Child extends Base {

        #[\DelayedTargetValidation]
        #[\Override]
        public const NAME = 'child';

        #[\Override]
        protected function foo(): void {}
    }

On PHP versions where Override is not allowed on class constants, this does not produce a compile time error.

Beispiel #2 Validation occurs during reflection

    <?php

    $reflection = new ReflectionClassConstant(Child::class, 'NAME');

    foreach ($reflection->getAttributes() as $attribute) {
        $attribute->newInstance(); // May throw if invalid
    }

When any attribute applied to the same target (other than DelayedTargetValidation itself) is instantiated via reflection using ReflectionAttribute::newInstance(), target validation is performed and an exception may be thrown if the attribute is used on an unsupported target.

## Anmerkungen

This attribute only affects target validation of internal attributes.

It does not suppress functional validation performed by those attributes. For example, Override will still emit an error if a method does not actually override a parent method.

## Siehe auch

- Attributes overview
- Override

# Das Attribut Deprecated

(PHP 8 >= 8.4.0)

## Einführung

Dieses Attribut wird verwendet, um eine Funktionalität als veraltet zu kennzeichnen. Die Verwendung einer veralteten Funktionalität führt zur Ausgabe eines Fehlers der Stufe `E_USER_DEPRECATED`.

## Klassenbeschreibung

#[\Attribute]
final class Deprecated {
/* Eigenschaften */
public readonly ?string $message;
public readonly ?string $since;
/* Methoden */
public function __construct(?string `$message` = null, ?string `$since` = null)
}

## Eigenschaften

message

  Eine optionale Meldung, die den Grund für die Abschaffung der Funktionalität und mögliche Funktionen für den Ersatz erläutert. Wird in die ausgegebene Meldung über die veraltete Funktionalität aufgenommen.

since

  Eine optionale Zeichenkette, die angibt, seit wann die Funktionalität veraltet ist. Der Inhalt wird nicht von PHP überprüft und kann eine Versionsnummer, ein Datum oder einen anderen Wert enthalten, der als angemessen erachtet wird. Wird in die ausgegebene Meldung über die veraltete Funktionalität aufgenommen.

  PHP-eigene Funktionalitäten verwenden Hauptversion.Nebenversion als Wert für since, zum Beispiel `'8.4'`.

## Beispiele

    <?php

    #[\Deprecated(message: "use safe_replacement() instead", since: "1.5")]
    function unsafe_function()
    {
    echo "Dies ist unsicher", PHP_EOL;
    }

    unsafe_function();

    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.4 eine ähnliche Ausgabe wie:

    Deprecated: Function unsafe_function() is deprecated since 1.5, use safe_replacement() instead in example.php on line 9
    Dies ist unsicher

## Siehe auch

- Attributes overview
- ReflectionFunctionAbstract::isDeprecated()
- ReflectionClassConstant::isDeprecated()
- `E_USER_DEPRECATED`

# Deprecated::__construct

(PHP 8 >= 8.4.0)

Deprecated::__construct — Erstellt eine neue Instanz des Attributs Deprecated

### Beschreibung

public function Deprecated::__construct(?string `$message` = `null`, ?string `$since` = `null`)

Erstellt eine neue Instanz von Deprecated.

### Parameter-Liste

`message`

  Der Wert der Eigenschaft message.

`since`

  Der Wert der Eigenschaft since property.

## Inhaltsverzeichnis

- Deprecated::__construct — Erstellt eine neue Instanz des Attributs Deprecated

# Das Attribut NoDiscard

(PHP 8 >= 8.5.0)

## Einführung

Dieses Attribut kann verwendet werden, um zu kennzeichnen, dass der Rückgabewert einer Funktion oder Methode nicht verworfen werden sollte. Wenn der Rückgabewert in keiner Weise verwendet wird, wird eine Warnung ausgegeben.

Dies ist nützlich bei Funktionen, bei denen die fehlende Prüfung des Rückgabewerts wahrscheinlich ein Fehler ist.

Um den Rückgabewert einer solchen Funktion absichtlich zu verwerfen, kann ein (void)-Cast verwendet werden, um die Warnung zu unterdrücken.

> Hinweis: Da Attribute auf Abwärtskompatibilität ausgelegt sind, kann `#[\NoDiscard]` auch dann zu Funktionen und Methoden hinzugefügt werden, wenn PHP 8.4 oder älter unterstützt werden muss; es hat dann lediglich keine Wirkung. Unter PHP 8.5 und neuer wird eine Warnung ausgegeben, wenn das Ergebnis unbenutzt bleibt. Um die Warnung ohne Verwendung von `(void)` zu unterdrücken, das vor PHP 8.5 nicht unterstützt wird, kann beispielsweise eine Variable wie `$_` verwendet werden.

## Klassenbeschreibung

#[\Attribute]
final class NoDiscard {
/* Eigenschaften */
public readonly ?string $message;
/* Methoden */
public function __construct(?string `$message` = null)
}

## Eigenschaften

message
  Eine optionale Meldung, die erklärt, warum der Rückgabewert nicht verworfen werden sollte.

## Beispiele

Beispiel #1 Grundlegende Verwendung

    <?php

    /**
     * Verarbeitet alle angegebenen Elemente und gibt ein Array mit den
     * Ergebnissen der Operation für jedes Element zurück. `null` bedeutet
     * Erfolg und eine Exception bedeutet einen Fehler. Die Schlüssel des
     * Ergebnisarrays entsprechen den Schlüsseln des $items-Arrays.
     *
     * @param array<string> $items
     * @return array<null|Exception>
     */
    #[\NoDiscard("da die Verarbeitung einzelner Elemente fehlschlagen kann")]
    function bulk_process(array $items): array {
     $results = [];

     foreach ($items as $key => $item) {
      if (\random_int(0, 9999) < 9999) {
       // Simuliere das etwas Sinnvolles mit $item passiert,
       // was in 99,99 % der Fälle erfolgreich ist.
       echo "Verarbeite {$item}", PHP_EOL;
       $error = null;
      } else {
       $error = new \Exception("Verarbeitung von {$item} fehlgeschlagen.");
      }

      $results[$key] = $error;
     }

     return $results;
    }

    bulk_process($items);

    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.5 eine ähnliche Ausgabe wie:

    Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), da die Verarbeitung einzelner Elemente fehlschlagen kann

Beispiel #2 Rückgabewert absichtlich verwerfen

    <?php

    #[\NoDiscard]
    function some_command(): int {
        return 1;
    }

    // Warnung mit (void) unterdrücken - PHP 8.5+
    (void) some_command();

    // Für Kompatibilität mit PHP-Versionen vor 8.5 eine temporäre Variable verwenden
    $_ = some_command();

    ?>

## Siehe auch

- Übersicht über die Attribute

# NoDiscard::__construct

(PHP 8 >= 8.5.0)

NoDiscard::__construct — Erstellt eine neue Instanz des Attributs NoDiscard

### Beschreibung

public function NoDiscard::__construct(?string `$message` = `null`)

Erstellt eine neue Instanz von NoDiscard.

### Parameter-Liste

`message`
  Der Wert der Eigenschaft message.

## Inhaltsverzeichnis

- NoDiscard::__construct — Erstellt eine neue Instanz des Attributs NoDiscard

# Das Attribut Override

(PHP 8 >= 8.3.0)

## Einführung

Dieses Attribut wird verwendet, um anzuzeigen, dass eine Methode oder Eigenschaft eine Methode oder Eigenschaft einer Elternklasse überschreiben soll oder dass sie eine in einer Schnittstelle definierte Methode oder Eigenschaft implementiert.

Wenn es weder in einer Elternklasse noch in einer implementierten Schnittstelle eine Methode oder Eigenschaft mit demselben Namen gibt, wird ein Kompilierungsfehler ausgegeben.

Das Attribut kann nicht auf die Methode __construct() angewendet werden, da diese von der Signaturprüfung ausgenommen ist.

## Klassenbeschreibung

#[\Attribute]
final class Override {
/* Methoden */
public function __construct()
}

## Changelog

Version | Beschreibung
--- | ---
8.5.0 | Override kann auf Eigenschaften angewendet werden.

## Beispiele

Beispiel #1 Verwendung mit Methoden

    <?php

    class Base {
        protected function foo(): void {}
    }

    final class Extended extends Base {
        #[\Override]
        protected function boo(): void {}
    }

    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.3 eine ähnliche Ausgabe wie:

    Fatal error: Extended::boo() has #[\Override] attribute, but no matching parent method exists

Beispiel #2 Verwendung mit Eigenschaften

    <?php

    class Base {
        protected string $foo;
    }

    final class Extended extends Base {
        #[\Override]
        protected string $boo;
    }

    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.5 eine ähnliche Ausgabe wie:

    Fatal error: Extended::$boo has #[\Override] attribute, but no matching parent property exists

## Siehe auch

- Übersicht über die Attribute

# Override::__construct

(PHP 8 >= 8.3.0)

Override::__construct — Erstellt eine neue Instanz des Attributs Override

### Beschreibung

public function Override::__construct()

Erstellt eine neue Instanz von Override.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

## Inhaltsverzeichnis

- Override::__construct — Erstellt eine neue Instanz des Attributs Override

# Das Attribut ReturnTypeWillChange

(PHP 8 >= 8.1.0)

## Einführung

Bei den meisten nicht-finalen internen Methoden müssen überschreibende Methoden nun einen kompatiblen Rückgabetyp deklarieren, andernfalls wird bei der Validierung der Vererbung ein entsprechender Hinweis auf eine veraltete Verwendung (DEPRECATED) ausgegeben. Für den Fall, dass der Rückgabetyp aufgrund von Kompatibilitätsproblemen mit anderen PHP-Versionen für eine überschreibende Methode nicht deklariert werden kann, kann das Attribut `#[\ReturnTypeWillChange]` hinzugefügt werden, um den Warnhinweis über die veraltete Technik zu unterdrücken.

## Klassenbeschreibung

#[\Attribute]
final class ReturnTypeWillChange {
/* Methoden */
public function __construct()
}

## Siehe auch

Übersicht über die Attribute

# ReturnTypeWillChange::__construct

(PHP 8 >= 8.1.0)

ReturnTypeWillChange::__construct — Erstellt eine neue Instanz des Attributs ReturnTypeWillChange

### Beschreibung

public function ReturnTypeWillChange::__construct()

Erstellt eine neue Instanz von ReturnTypeWillChange.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

## Inhaltsverzeichnis

- ReturnTypeWillChange::__construct — Erstellt eine neue Instanz des Attributs ReturnTypeWillChange

# Das Attribut SensitiveParameter

(PHP 8 >= 8.2.0)

## Einführung

Dieses Attribut wird verwendet, um einen Parameter als sensibel zu kennzeichnen und dessen Wert unkenntlich gemacht werden sollte, wenn er in einem Stacktrace vorkommt.

## Klassenbeschreibung

#[\Attribute]
final class SensitiveParameter {
/* Methoden */
public function __construct()
}

## Beispiele

    <?php

    function defaultBehavior(
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    function sensitiveParametersWithAttribute(
        #[\SensitiveParameter]
        string $secret,
        string $normal
    ) {
        throw new Exception('Error!');
    }

    try {
        defaultBehavior('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

    try {
        sensitiveParametersWithAttribute('password', 'normal');
    } catch (Exception $e) {
        echo $e, PHP_EOL, PHP_EOL;
    }

    ?>

Das oben gezeigte Beispiel erzeugt mit PHP 8.2 eine ähnliche Ausgabe wie:

    Exception: Error! in example.php:7
    Stack trace:
    #0 example.php(19): defaultBehavior('password', 'normal')
    #1 {main}

    Exception: Error! in example.php:15
    Stack trace:
    #0 example.php(25): sensitiveParametersWithAttribute(Object(SensitiveParameterValue), 'normal')
    #1 {main}

## Siehe auch

- Übersicht über die Attribute
- SensitiveParameterValue

# SensitiveParameter::__construct

(PHP 8 >= 8.2.0)

SensitiveParameter::__construct — Erstellt eine neue Instanz des Attributs SensitiveParameter

### Beschreibung

public function SensitiveParameter::__construct()

Erstellt eine neue Instanz von SensitiveParameter.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

## Inhaltsverzeichnis

- SensitiveParameter::__construct — Erstellt eine neue Instanz des Attributs SensitiveParameter

# Kontextoptionen und -parameter

PHP bietet eine Menge von Kontextoptionen und -parametern, die in Zusammenhang mit allen Dateisystem- und Streamwrappern genutzt werden können. Ein Kontext wird mit stream_context_create() erzeugt. Optionen werden mit stream_context_set_option() gesetzt und Parameter mit stream_context_set_params().

# Socket-Kontextoptionen

Socket-Kontextoptionen — Liste der Socket-Kontextoptionen

### Beschreibung

Socket-Kontextoptionen sind für alle Wrapper verfügbar, die über Sockets arbeiten, wie `tcp`, `http` und `ftp`.

### Optionen

`bindto`

  Wird verwendet, um die IP-Adresse (entweder IPv4 oder IPv6) und/oder die Portnummer anzugeben, die PHP für den Zugriff auf das Netzwerk verwenden soll. Die Syntax ist für IPv4-Adressen `ip:port` und für IPv6-Adressen `[ip]:port`. Wenn die IP oder der Port auf `0` gesetzt wird, kann das System die IP und/oder den Port selbst auswählen.

  > Hinweis:

  > Da FTP im Normalbetrieb zwei Socket-Verbindungen herstellt, kann die Portnummer bei dieser Option nicht angegeben werden.

`backlog`

  Wird verwendet, um ausgehende Verbindungen in der Verbindungs-Warteschlange des Sockets zu begrenzen.

  > Hinweis:

  > Dies gilt nur für stream_socket_server().

`ipv6_v6only`

  Überschreibt den Standard des Betriebssystems bezüglich der Abbildung von IPv4 auf IPv6.

  > Hinweis:

  > Dies ist insbesondere dann wichtig, wenn bei einer Bindung an `[::]` versucht wird, IPv4-Adressen separat abzuhören.

  > Dies gilt nur für stream_socket_server().

`so_reuseport`

  Erlaubt mehrere Bindungen an ein und dasselbe ip:port-Paar, sogar von verschiedenen Prozessen aus.

  > Hinweis:

  > Dies gilt nur für stream_socket_server().

`so_broadcast`

  Ermöglicht das Senden und Empfangen von Daten an/von Broadcast-Adressen.

  > Hinweis:

  > Dies gilt nur für stream_socket_server().

`tcp_nodelay`

  Wenn diese Option auf `true` gesetzt wird, wird entsprechend auch `SOL_TCP,NO_DELAY=1` gesetzt, wodurch der Nagle-Algorithmus für TCP deaktiviert wird.

### Changelog

Version | Beschreibung
--- | ---
7.1.0 | `tcp_nodelay` wurde hinzugefügt.
7.0.1 | `ipv6_v6only` wurde hinzugefügt.

### Beispiele

Beispiel #1 Grundlegendes Beispiel für die Verwendung von `bindto`

    <?php
    // Verbindung zum Internet über die IP-Adresse '192.168.0.100' aufbauen
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:0',
        ),
    );

    // Verbindung zum Internet über die IP-Adresse '192.168.0.100'
    // und den Port '7000' aufbauen
    $opts = array(
        'socket' => array(
            'bindto' => '192.168.0.100:7000',
        ),
    );

    // Verbindung zum Internet über die IPv6-Adresse '2001:db8::1'
    // und den Port '7000' aufbauen
    $opts = array(
        'socket' => array(
            'bindto' => '[2001:db8::1]:7000',
        ),
    );

    // Verbindung zum Internet über Port '7000' aufbauen
    $opts = array(
        'socket' => array(
            'bindto' => '0:7000',
        ),
    );

    // den Kontext erstellen...
    $context = stream_context_create($opts);

    // ...und ihn zum Abrufen der Daten verwenden
    echo file_get_contents('http://www.example.com', false, $context);

    ?>

# HTTP-Kontextoptionen

HTTP-Kontextoptionen — Liste der HTTP-Kontextoptionen

### Beschreibung

Kontextoptionen für die Transportprotokolle `http://` und `https://`.

### Optionen

`method` string

  `GET`, `POST` oder eine andere vom entfernten Server unterstützte HTTP-Methode.

  Der Standardwert ist `GET`.

`header` array oder string

  Zusätzliche Kopfzeilen, die während der Anfrage gesendet werden. Die Werte in dieser Option überschreiben andere Werte (wie `User-Agent:`, `Host:`, und `Authentication:`), selbst wenn sie `Location:`-Weiterleitungen folgen. Es ist daher nicht empfehlenswert, eine `Host:`-Kopfzeile zu setzen, wenn `follow_location` aktiviert ist.

  Der Wert der Zeichenkette sollte aus `Schlüssel: Wert`-Paaren bestehen, die durch `\r\n` begrenzt sind, z. B. `"Content-Type: application/json\r\nConnection: close"`. Der Wert des Arrays sollte eine Liste von `Schlüssel: Wert`-Paaren sein, z. B. `["Content-Type: application/json", "Connection: close"]`.

`user_agent` string

  Der Wert, der mit der Kopfzeile `User-Agent:` gesendet wird. Dieser Wert wird nur verwendet, wenn der User-Agent nicht in der obigen Kontextoption `header` angegeben wurde.

  Standardmäßig wird der Wert von user_agent aus der php.ini verwendet.

`content` string

  Zusätzliche Daten, die nach den Kopfzeilen gesendet werden; wird in der Regel bei POST- oder PUT-Anfragen verwendet.

`proxy` string

  Der URI, der die Adresse des Proxy-Servers angibt (z. B. `tcp://proxy.example.com:5100`).

`request_fulluri` bool

  Wenn auf `true` gesetzt, wird beim Aufbau der Anfrage der gesamte URI verwendet (z. B. `GET http://www.example.com/path/to/file.html HTTP/1.0`). Dies ist zwar kein Standard-Anfrageformat, wird aber von einigen Proxy-Servern verlangt.

  Der Standardwert ist `false`.

`follow_location` int

  Folgt den Weiterleitungen der Kopfzeile `Location`; zum Deaktivieren auf 0 setzen.

  Der Standardwert ist `1`.

`max_redirects` int

  Die maximale Anzahl der zu verfolgenden Weiterleitungen. Der Wert `1` oder weniger bedeutet, dass keine Weiterleitungen verfolgt werden.

  Der Standardwert ist `20`.

`protocol_version` float

  Die Version des HTTP-Protokolls.

  Seit PHP 8.0.0 ist der Standardwert `1.1`; vorher war es `1.0`.

`timeout` float

  Das Zeitlimit für Lesevorgänge in Sekunden, angegeben durch einen Wert vom Typ float (z. B. `10.5`).

  Standardmäßig wird der Wert von default_socket_timeout aus der php.ini verwendet.

`ignore_errors` bool

  Ruft den Inhalt auch dann ab, wenn ein Fehlerstatus vorliegt.

  Der Standardwert ist `false`.

### Beispiele

Beispiel #1 Abrufen einer Seite mit Übermittlung von POST-Daten

    <?php

    $postdata = http_build_query(
        [
            'var1' => 'some content',
            'var2' => 'doh',
        ]
    );

    $opts = [
        'http' => [
            'method'  => 'POST',
            'header'  => 'Content-type: application/x-www-form-urlencoded',
            'content' => $postdata,
        ]
    ];

    $context = stream_context_create($opts);

    $result = file_get_contents('http://example.com/submit.php', false, $context);

    ?>

Beispiel #2 Weiterleitungen ignorieren, aber Kopfzeilen und Inhalt abrufen

    <?php

    $url = "http://www.example.org/header.php";

    $opts = [
        'http' => [
            'method'        => 'GET',
            'max_redirects' => '0',
            'ignore_errors' => '1',
        ]
    ];

    $context = stream_context_create($opts);
    $stream = fopen($url, 'r', false, $context);

    // die Header-Informationen sowie die Metadaten über den Stream
    var_dump(stream_get_meta_data($stream));

    // die eigentlichen Daten von $url
    var_dump(stream_get_contents($stream));
    fclose($stream);
    ?>

### Anmerkungen

> Hinweis: Kontextoptionen für den zugrundeliegenden Socket-Stream
> Vom zugrundeliegenden Transport können zusätzliche Kontextoptionen unterstützt werden. Für `http://`-Streams, siehe Kontextoptionen für das Transportprotokoll `tcp://`. Für `https://`-Streams, siehe Kontextoptionen für das Transportprotokoll `ssl://`.

> Hinweis: HTTP-Statuszeile
> Wenn dieser Stream-Wrapper einer Weiterleitung (Redirect) folgt, ist der Inhalt von Index `0` in den von stream_get_meta_data() zurückgegebenen `wrapper_data` nicht unbedingt die HTTP-Statuszeile für diesen Inhalt.

>     array (
>       'wrapper_data' =>
>       array (
>         0 => 'HTTP/1.0 301 Moved Permanently',
>         1 => 'Cache-Control: no-cache',
>         2 => 'Connection: close',
>         3 => 'Location: http://example.com/foo.jpg',
>         4 => 'HTTP/1.1 200 OK',
>         ...

> Die erste Anfrage lieferte eine `301` (permanente Weiterleitung), sodass der Stream-Wrapper automatisch der Weiterleitung folgte, bei der er eine `200`-Antwort erhielt (index = `4`).

### Siehe auch

- http://
- Socket-Kontextoptionen
- SSL-Kontext-Optionen

# FTP-Kontextoptionen

FTP-Kontextoptionen — Liste der FTP-Kontextoptionen

### Beschreibung

Kontextoptionen für `ftp://` und `ftps://`.

### Optionen

`overwrite` bool

  Gestattet das Überschreiben bereits existierender Dateien auf einem Server. Hat nur Auswirkungen auf den Schreibmodus (Upload).

  Die Standardeinstellung ist `false`.

`resume_pos` int

  Dateioffset von dem aus die Übertragung begonnen werden soll. Hat nur Auswirkungen auf den Lesemodus (Download).

  Standardwert ist `0` (Dateianfang).

`proxy` string

  Leitet FTP-Anfragen über einen Proxyserver um. Hat nur Auswirkungen auf Lesezugriffe. Beispiel: `tcp://squid.example.com:8000`.

### Anmerkungen

> Hinweis: Kontextoptionen des zugrundeliegenden Socket Streams
> Der zugrundeliegende Transportmechanismus kann weitere Optionen zur Verfügung stellen. Für `ftp://` Streams siehe hierzu die Optionen des `tcp://`-Mechanismus, für `ftps://` Streams stehen entsprechend die Optionen des `ssl://`-Mechanismus zur Verfügung.

### Siehe auch

- ftp://
- Socket-Kontextoptionen
- SSL-Kontext-Optionen

# SSL-Kontext-Optionen

SSL-Kontext-Optionen — Liste der SSL-Kontext-Optionen

### Beschreibung

Kontextoptionen für die `ssl://` und `tls://` Übermittlung.

### Optionen

`peer_name` string

  Zu verwendender Peer-Name. Wird dieser Wert nicht gesetzt, so wird der Name anhand des Hostnamen erraten, sobald der Stream geöffnet wird.

`verify_peer` bool

  Die Überprüfung des verwendeten SSL-Zertifikats ist erforderlich.

  Standardmäßig `true`.

`verify_peer_name` bool

  Erfordere die Verifikation des Peernamens.

  Standardmäßig `true`.

`allow_self_signed` bool

  Selbst signifizierte Zerifikate erlauben. Setzt `verify_peer` voraus.

  Standardmäßig `false`

`cafile` string

  Speicherort der Zertifizierungsstellendatei auf dem lokalen Dateisystem, welche im Zusammenhang mit der `verify_peer` Option verwendet werden soll, um die Identität der Gegenstelle zu authentifizieren.

`capath` string

  Falls `cafile` nicht angegeben wurde, oder dort das Zertifikat nicht gefunden wurde, so wird das durch `capath` angegebene Verzeichnis nach einem passenden Zertifikat durchsucht. `capath` muss ein korrekt gehashtes Zertifikatsverzeichnis sein.

`local_cert` string

  Pfad zur lokalen Zertifikatsdatei im Dateisystem. Dies muss eine im PEM-Format gespeicherte Datei sein, welche das Zertifikat und den privaten Schlüssel enthält. Optional kann dies die Kette an Herausgeberzertifikaten enthalten. Der private Schlüssel kann ebenfalls in einer eigenen Datei enthalten sein, die durch `local_pk` angegeben wird.

`local_pk` string

  Pfad zu einer lokalen Datei, die den privaten Schlüssel enthält, falls es unterschiedliche Dateien für Zertifikate (`local_cert`) und private Schlüssel gibt.

`passphrase` string

  Passphrase mit der die `local_cert`-Datei gespeichert wurde.

`verify_depth` int

  Abbruch, wenn die Zertifikatskette zu tief ist.

  Standardmäßig keine Prüfung.

`ciphers` string

  Setzt die Liste der verfügbaren Verschlüsselungsverfahrenn. Das Format dieser Zeichenkette wird in » ciphers(1) beschrieben.

  Standardmäßig auf `DEFAULT` gesetzt.

`capture_peer_cert` bool

  Falls dies auf `true` gesetzt ist, so wird die Kontextoption `peer_certificate` angelegt, welche das Zertifikat der Gegenstelle enthält.

`capture_peer_cert_chain` bool

  Falls dies auf `true` gesetzt ist, so wird die Kontextoption `peer_certificate_chain` angelegt, welche die Zertifikatskette enthält.

`SNI_enabled` bool

  Falls dies auf `true` gesetzt wird, so wird Server Name Indication eingeschaltet. Die Verwendung von SNI erlaubt die Benutzung von mehreren Zertifikaten unter der gleichen IP-Adresse.

`disable_compression` bool

  Wenn dies gesetzt wird, so wird TLS-Komprimierung ausgeschaltet. Dies kann den CRIME-Angriffsvektor entschärfen.

`peer_fingerprint` string | array

  Beendet die Verbindung, wenn der Fingerabdruck des entfernten Zertifikats nicht dem angegebenen Hashwert entspricht.

  Wird ein String verwendet, so wird der zu verwendende Hashalgorithmus anhand der Länge der Zeichenkette ermittelt, entweder "md5" (32) oder "sha1" (40).

  Wird ein Array verwendet, so geben die Schlüsselnamen den Namen des Hashalgorithmus an, und jeder zugehörige Wert entspricht dem erwarteten Fingerabdruck.

`security_level` int

  Legt die Sicherheitsstufe fest. Falls nicht angegeben, wird die Standard-Sicherheitsstufe der Bibliothek verwendet. Die Sicherheitsstufen sind in » SSL_CTX_get_security_level(3) beschrieben.

  Verfügbar von PHP 7.2.0 und OpenSSL 1.1.0 an.

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | `security_level` hinzugefügt. Erfordert OpenSSL >= 1.1.0.

### Anmerkungen

> Hinweis: Weil `ssl://` die den Wrappern `https://` und `ftps://` zugrunde liegende Übertragungsschicht ist, gelten alle Optionen, die für `ssl://` angewendet werden, ebenfalls für `https://` und `ftps://`.

> Hinweis: Damit SNI (Server Name Indication) verfügbar ist muss PHP mit OpenSSL 0.9.8j oder neuer kompiliert sein. Die Konstante `OPENSSL_TLSEXT_SERVER_NAME` kann zur Prüfung, ob SNI verfügbar ist, herangezogen werden.

### Siehe auch

- Socket-Kontextoptionen

# Phar Kontextoptionen

Phar Kontextoptionen — Liste der Phar Kontextoptionen

### Beschreibung

Kontextoptionen des `phar://` Wrappers.

### Optionen

`compress` int

  Eine der Phar Kompressionskonstanten.

`metadata` mixed

  Phar Metadaten, siehe auch Phar::setMetadata().

### Siehe auch

- phar://
- Phar Stream Wrapper

# Kontextparameter

Kontextparameter — Liste der Kontextparameter

### Beschreibung

Diese `Parameter` eines `Kontextes` können mit Hilfe der Funktion stream_context_set_params() gesetzt werden.

### Optionen

`notification` callable

  Ein callable, der bei dem Auftreten eines Ereignisses auf einem Stream aufgerufen wird.

  Für weitere Informationen siehe auch stream_notification_callback.

# Zip-Kontextoptionen

Zip-Kontextoptionen — Liste der Zip-Kontextoptionen

### Beschreibung

Die Zip-Kontextoptionen sind für `zip`-Wrapper verfügbar.

### Optionen

`password`

  Wird verwendet, um das Passwort für ein verschlüsseltes Archiv anzugeben.

### Changelog

Version | Beschreibung
--- | ---
7.2.0, PECL zip 1.14.0 | `password` wurde hinzugefügt.

### Beispiele

Beispiel #1 Grundlegendes Beispiel für die Verwendung von `password`

    <?php
    // Verschlüsseltes Archiv lesen
    $opts = array(
        'zip' => array(
            'password' => 'secret',
        ),
    );
    // den Kontext erstellen...
    $context = stream_context_create($opts);

    // ...und ihn zum Abrufen der Daten verwenden
    echo file_get_contents('zip://test.zip#test.txt', false, $context);

    ?>

# Zlib-Kontextoptionen

Zlib-Kontextoptionen — Liste der Zlib-Kontextoptionen

### Beschreibung

Die Zlib-Kontextoptionen sind für `zlib`-Wrapper verfügbar.

### Optionen

`level`

  Wird zur Angabe des Komprimierungsgrades verwendet (`0` - `9`).

### Changelog

Version | Beschreibung
--- | ---
7.3.0 | `level` wurde hinzugefügt.

## Inhaltsverzeichnis

- Socket-Kontextoptionen — Liste der Socket-Kontextoptionen
- HTTP-Kontextoptionen — Liste der HTTP-Kontextoptionen
- FTP-Kontextoptionen — Liste der FTP-Kontextoptionen
- SSL-Kontext-Optionen — Liste der SSL-Kontext-Optionen
- Phar Kontextoptionen — Liste der Phar Kontextoptionen
- Kontextparameter — Liste der Kontextparameter
- Zip-Kontextoptionen — Liste der Zip-Kontextoptionen
- Zlib-Kontextoptionen — Liste der Zlib-Kontextoptionen

# Unterstützte Protokolle und Wrapper

PHP bietet viele integrierte Wrapper für verschiedene Protokolle im URL-Stil auf die so mit Dateisystem-Funktionen wie fopen(), copy(), file_exists() und filesize() zugegriffen werden. Zusätzlich zu diesen eingebauten Wrappern ist es auch möglich eigene mit Hilfe der stream_wrapper_register() Funktion hinzuzufügen.

> Hinweis: Die zur Beschreibung eines Wrappers genutzte URL-Syntax unterstützt nur URLs der Form `schema://...` mit zwei Schrägstrichen. Die `schema:/` und `schema:` Varianten werden nicht unterstützt.

# file://

file:// — Zugriff auf das lokale Dateisystem

### Beschreibung

`file://` ist der Standard-Wrapper von PHP und stellt das lokale Dateisystem dar. Wenn ein relativer Pfad angegeben wird (ein Pfad, der nicht mit `/`, `\`, `\\` oder einem Windows-Laufwerksbuchstaben beginnt), wird der angegebene Pfad auf das aktuelle Arbeitsverzeichnis angewendet. Häufig ist dies das Verzeichnis, in dem sich das Skript befindet, sofern es nicht geändert wurde. Bei Verwendung der CLI-SAPI (Befehlszeilenschnittstelle) ist dies standardmäßig das Verzeichnis, von dem aus das Skript aufgerufen wurde.

Bei einigen Funktionen wie fopen() und file_get_contents() können optional auch die relativen Pfade von `include_path` durchsucht werden.

### Verwendung

- /path/to/file.ext
- relative/path/to/file.ext
- fileInCwd.ext
- C:/path/to/winfile.ext
- C:\path\to\winfile.ext
- \\smbserver\share\path\to\winfile.ext
- file:///path/to/file.ext

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Nein
Erlaubt Lesen | Ja
Erlaubt Schreiben | Ja
Erlaubt Anfügen | Ja
Erlaubt gleichzeitiges Lesen und Schreiben | Ja
Unterstützt stat() | Ja
Unterstützt unlink() | Ja
Unterstützt rename() | Ja
Unterstützt mkdir() | Ja
Unterstützt rmdir() | Ja

# http://

# https://

http:// -- https:// — Zugriff auf HTTP(s)-URLs

### Beschreibung

Ermöglicht den rein lesenden Zugriff auf Dateien/Ressourcen über HTTP. Standardmäßig wird HTTP 1.0 GET verwendet. Um namensbasierte virtuelle Hosts verwalten zu können, wird zusammen mit der Anfrage ein `Host:`-Header gesendet. Wenn in der Datei php.ini oder im Stream-Kontext die Direktive user_agent konfiguriert wurde, wird diese ebenfalls in die Anfrage aufgenommen.

Der Stream ermöglicht den Zugriff auf den Inhalt (body) der Ressource; die Header werden in der Variablen $http_response_header gespeichert.

Wenn es wichtig ist, die URL der Ressource zu kennen, von der das Dokument stammt (nachdem alle Weiterleitungen verarbeitet wurden), muss die Reihe der vom Stream zurückgegebenen Antwort-Header verarbeitet werden.

Ist die Direktive from gesetzt ist und wird nicht durch die Kontextoptionen und -parameter überschrieben, wird sie für den `From:`-Header verwendet.

### Verwendung

- http://example.com
- http://example.com/file.php?var1=val1&var2=val2
- http://user:password@example.com
- https://example.com
- https://example.com/file.php?var1=val1&var2=val2
- https://user:password@example.com

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Ja
Erlaubt Lesen | Ja
Erlaubt Schreiben | Nein
Erlaubt Anfügen | Nein
Erlaubt gleichzeitiges Lesen und Schreiben | N/A
Unterstützt stat() | Nein
Unterstützt unlink() | Nein
Unterstützt rename() | Nein
Unterstützt mkdir() | Nein
Unterstützt rmdir() | Nein

### Beispiele

Beispiel #1 Ermitteln der letzten URL nach Weiterleitungen

    <?php
    $url = 'http://www.example.com/redirecting_page.php';

    $fp = fopen($url, 'r');

    $meta_data = stream_get_meta_data($fp);
    foreach ($meta_data['wrapper_data'] as $response) {

        /* Wurden wir weitergeleitet? */
        if (strtolower(substr($response, 0, 10)) == 'location: ') {

            /* $url mit dem Ziel der Weiterleitung aktualisieren */
            $url = substr($response, 10);
        }

    }

    ?>

### Anmerkungen

> Hinweis: HTTPS wird nur unterstützt, wenn die Erweiterung openssl aktiviert ist.

HTTP-Verbindungen sind schreibgeschützt; in eine HTTP-Ressource können weder Daten geschrieben noch Dateien kopiert werden.

POST- und PUT-Anfragen können zum Beispiel mit Hilfe von HTTP-Kontexten gesendet werden.

### Siehe auch

- HTTP-Kontextoptionen
- $http_response_header
- stream_get_meta_data() - Retrieves header/meta data from streams/file pointers

# ftp://

# ftps://

ftp:// -- ftps:// — Zugriff auf FTP(s)-URLs

### Beschreibung

Ermöglicht es, über FTP lesend auf bestehende Dateien zuzugreifen und neue Dateien zu erstellen. Wenn der Server den passiven FTP-Modus nicht unterstützt, schlägt die Verbindung fehl.

Dateien können entweder zum Lesen oder zum Schreiben geöffnet werden, aber nicht beides gleichzeitig. Wenn eine Datei auf dem FTP-Server bereits vorhanden ist und versucht wird, sie ohne die Kontextoption `overwrite` zum Schreiben zu öffnen, schlägt die Verbindung fehl. Wenn bereits vorhandene Dateien über ftp überschrieben werden sollen, muss die Option `overwrite` im Kontext angegeben und die Datei zum Schreiben geöffnet werden. Alternativ kann auch die Erweiterung FTP verwendet werden.

Wenn die Direktive from in der php.ini gesetzt ist, dann wird dieser Wert als anonymes FTP-Passwort gesendet.

### Verwendung

- ftp://example.com/pub/file.txt
- ftp://user:password@example.com/pub/file.txt
- ftps://example.com/pub/file.txt
- ftps://user:password@example.com/pub/file.txt

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Ja
Erlaubt Lesen | Ja
Erlaubt Schreiben | Ja (neue Dateien; vorhandene Dateien mit dem Parameter `overwrite`)
Erlaubt Anfügen | Ja
Erlaubt gleichzeitiges Lesen und Schreiben | Nein
Unterstützt stat() | Nur filesize(), filemtime(), filetype(), file_exists(), is_file() und is_dir().
Unterstützt unlink() | Ja
Unterstützt rename() | Ja
Unterstützt mkdir() | Ja
Unterstützt rmdir() | Ja

### Anmerkungen

> Hinweis:

> FTPS wird nur unterstützt, wenn die Erweiterung openssl aktiviert ist.

> Wenn SSL vom Server nicht unterstützt wird, wird die Verbindung auf normales unverschlüsseltes FTP zurückgesetzt.

> Hinweis: Anfügen
> Dateien können über den `ftp://`-URL-Wrapper angefügt werden.

### Siehe auch

- FTP-Kontextoptionen

# php://

php:// — Zugriff auf verschiedene I/O-Streams

### Beschreibung

PHP stellt eine Reihe verschiedener I/O-Streams zur Verfügung. Diese ermöglichen den Zugriff auf PHP-eigene Ein- und Ausgabestreams, Dateideskriptoren für Standardeingabe, -ausgabe und -fehler, temporäre Dateistreams im Speicher und auf der Festplatte sowie Filter, die andere Dateiressourcen während des Lesen und Schreibens manipulieren können.

#### php://stdin, php://stdout und php://stderr

php://stdin, php://stdout und php://stderr ermöglichen den direkten Zugriff auf den entsprechenden Ein- oder Ausgabestream des PHP-Prozesses. Der Stream verweist auf eine Kopie eines Dateideskriptors, d. h. wenn php://stdin geöffnet und später wieder geschlossen wird, wird nur die Kopie des Deskriptors geschlossen - der eigentliche Stream, auf den `STDIN` verweist, bleibt davon unberührt. Es wird empfohlen, einfach die Konstanten `STDIN`, `STDOUT` und `STDERR` zu verwenden, anstatt die Streams manuell mit diesen Wrappern zu öffnen.

php://stdin ist schreibgeschützt, während php://stdout und php://stderr nur geschrieben werden können.

#### php://input

php://input ist ein schreibgeschützter Stream, mit dem Rohdaten aus dem Body der Anfrage gelesen werden können. Wenn die Option enable_post_data_reading aktiviert ist, stehtphp://input in POST-Anfragen mit `enctype="multipart/form-data"` nicht zur Verfügung.

#### php://output

php://output ist ein nur schreibbarer Stream, mit dem auf die gleiche Weise in den Ausgabepuffer geschrieben werden kann wie mit print und echo.

#### php://fd

Mit php://fd kann direkt auf den angegebenen Dateideskriptor zugegriffen werden; z. B. verweist php://fd/3 auf den Dateideskriptor 3.

#### php://memory und php://temp

php://memory und php://temp sind les- und schreibbare Streams, mit denen temporäre Daten in einem dateiähnlichen Wrapper gespeichert werden können. Ein Unterschied zwischen den beiden besteht darin, dass php://memory die Daten immer im Speicher ablegt, während php://temp eine temporäre Datei verwendet, sobald die Menge der gespeicherten Daten eine vordefinierte Grenze (der Standardwert ist 2 MB) erreicht. Der Speicherort dieser temporären Datei wird auf die gleiche Weise ermittelt, wie bei der Funktion sys_get_temp_dir().

Das Speicherlimit von php://temp kann durch Anhängen von `/maxmemory:NN` festgelegt werden, wobei `NNN` die maximale Datenmenge in Bytes ist, die im Speicher gehalten werden soll, bevor eine temporäre Datei verwendet wird.

Achtung

Manche PHP-Erweiterungen benötigen einen Standard-IO-Stream und versuchen, einen gegebenen Stream in einen Standard-IO-Stream umzuwandeln. Diese Umwandlung kann bei Speicher-Streams fehlschlagen, da hierfür die C-Funktion fopencookie() verfügbar sein muss. Unter Windows steht diese C-Funktion nicht zur Verfügung.

#### php://filter

php://filter ist eine Art Meta-Wrapper, mit dem Filter auf einen Stream angewendet werden können, wenn dieser geöffnet wird. Dies ist nützlich bei All-in-One-Dateifunktionen wie readfile(), file() und file_get_contents(), wo es sonst keine Möglichkeit gibt, einen Filter auf den Stream anzuwenden, bevor der Inhalt gelesen wird.

Der Wrapper php://filter akzeptiert die folgenden Parameter als Teil seines Pfades. Es können mehrere Filterketten in einem Pfad angegeben werden. Einzelheiten zur Verwendung dieser Parameter werden in den Beispielen erläutert.

Parameter für php://filter
Name | Beschreibung
--- | ---
`resource=<zu filternder Stream>` | Dieser Parameter ist erforderlich; er gibt den Stream an, der gefiltert werden soll.
`read=<Liste der Filter, die auf den Lese-Stream angewendet werden sollen>` | Dieser Parameter ist optional; ein oder mehrere Filternamen, getrennt durch ein Pipe-Zeichen (`|`).
`write=<Liste der Filter, die auf den Schreib-Stream angewendet werden sollen>` | Dieser Parameter ist optional; ein oder mehrere Filternamen, getrennt durch ein Pipe-Zeichen (`|`).
`<Liste der Filter, die auf beide Streams angewendet werden sollen>` | Alle Filterlisten, denen kein `read=` oder `write=` vorangestellt ist, werden je nach Bedarf sowohl auf den Lese- als auch auf den Schreib-Stream angewendet.

### Optionen

Zusammenfassung des Wrappers (für `php://filter` siehe die Zusammenfassung des Wrappers, der gefiltert wird)
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Nein
Eingeschränkt durch allow_url_include | Nur `php://input`, `php://stdin`, `php://memory` und `php://temp`.
Erlaubt Lesen | Nur `php://stdin`, `php://input`, `php://fd`, `php://memory` und `php://temp`.
Erlaubt Schreiben | Nur `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` und `php://temp`.
Erlaubt Anfügen | Nur `php://stdout`, `php://stderr`, `php://output`, `php://fd`, `php://memory` und `php://temp` (Entspricht dem Schreiben).
Erlaubt gleichzeitiges Lesen und Schreiben | Nur `php://fd`, `php://memory` und `php://temp`.
Unterstützt stat() | Nein, aber `php://memory` und `php://temp` unterstützen fstat().
Unterstützt unlink() | Nein
Unterstützt rename() | Nein
Unterstützt mkdir() | Nein
Unterstützt rmdir() | Nein
Unterstützt stream_select() | Nur `php://stdin`, `php://stdout`, `php://stderr`, `php://fd` und `php://temp`.

### Beispiele

Beispiel #1 php://temp/maxmemory

Mit diesem optionalen Parameter kann festgelegt werden, wie viel Speicherplatz php://temp verwenden darf, bevor eine temporäre Datei verwendet wird.

    <?php
    // Das Limit auf 5 MB setzen.
    $fiveMBs = 5 * 1024 * 1024;
    $fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

    fputs($fp, "hello\n");

    // Lesen, was geschrieben wurde.
    rewind($fp);
    echo stream_get_contents($fp);
    ?>

Beispiel #2 php://filter/resource=<zu filternder Stream>

Dieser Parameter muss sich am Ende der php://filter-Spezifikation befinden und auf den Stream verweisen, der gefiltert werden soll.

    <?php
    /* Da keine Filter angegeben werden, entspricht dies einem einfachen
      readfile("http://www.example.com"); */

    readfile("php://filter/resource=http://www.example.com");
    ?>

Beispiel #3 php://filter/read=<Liste der Filter, die auf den Lese-Stream angewendet werden sollen>

Dieser Parameter akzeptiert einen oder mehrere Filternamen, die durch das Pipe-Zeichen `|` getrennt sind.

    <?php
    /* Dies gibt den Inhalt von www.example.com
      komplett in Großbuchstaben aus */
    readfile("php://filter/read=string.toupper/resource=http://www.example.com");

    /* Dies bewirkt dasselbe wie oben,
      aber zusätzlich wird ROT13-kodiert */
    readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
    ?>

Beispiel #4 php://filter/write=<Liste der Filter, die auf den Schreib-Stream angewendet werden sollen>

Dieser Parameter akzeptiert einen oder mehrere Filternamen, die durch das Pipe-Zeichen `|` getrennt sind.

    <?php
    /* Dies wendet einen rot13-Filter auf die Zeichenkette
      "Hello World" an und schreibt sie dann in die Datei
      example.txt im aktuellen Verzeichnis */
    file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
    ?>

Beispiel #5 php://memory und php://temp sind nicht wiederverwendbar

php://memory und php://temp können nicht wiederverwendet werden, d. h. nachdem die Streams geschlossen wurden, kann nicht mehr auf sie zugegriffen werden.

    <?php
    file_put_contents('php://memory', 'PHP');
    echo file_get_contents('php://memory'); // gibt nichts aus

Beispiel #6 JSON-Daten mittels php://input aus dem Body einer Anfrage lesen

Dieses Beispiel zeigt, wie mittels php://input JSON-Rohdaten aus POST-, PUT- und PATCH-Anfragen gelesen werden können.

    <?php
    $input = file_get_contents("php://input");
    $json_array = json_decode(
      json: $input,
      associative: true,
      flags: JSON_THROW_ON_ERROR
    );

    echo "Empfangene JSON-Daten: ";
    print_r($json_array);
    ?>

# zlib://

# bzip2://

# zip://

zlib:// -- bzip2:// -- zip:// — Komprimierungsstreams

### Beschreibung

compress.zlib:// und compress.bzip2://

zlib: funktioniert wie gzopen(), mit dem Unterschied, dass der Stream mit fread() und den anderen Dateisystemfunktionen verwendet werden kann. Diese Schreibweise ist aufgrund von Mehrdeutigkeiten mit Dateinamen, die einen Doppelpunkt (":") enthalten, veraltet; stattdessen sollte compress.zlib:// verwendet werden.

compress.zlib:// und compress.bzip2:// entsprechen den Funktionen gzopen() bzw. bzopen() und funktionieren auch auf Systemen, die fopencookie nicht unterstützen.

Die ZIP-Erweiterung registriert den Wrapper zip:. Seit PHP 7.2.0 und libzip 1.2.0+ werden Passwörter für verschlüsselte Archive unterstützt, sodass Passwörter über die Stream-Kontexte bereitgestellt werden können. Das Passwort kann mit der Stream-Kontextoption `'password'` gesetzt werden.

### Verwendung

- compress.zlib://file.gz
- compress.bzip2://file.bz2
- zip://archive.zip#dir/file.txt

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Nein
Erlaubt Lesen | Ja
Erlaubt Schreiben | Ja (außer `zip://`)
Erlaubt Anfügen | Ja (außer `zip://`)
Erlaubt gleichzeitiges Lesen und Schreiben | Nein
Unterstützt stat() | Nein, zum Abrufen von Informationen über komprimierte Dateien kann der Standard-Wrapper `file://` verwendet werden.
Unterstützt unlink() | Nein, zum Löschen komprimierter Dateien kann der Standard-Wrapper `file://` verwendet werden.
Unterstützt rename() | Nein
Unterstützt mkdir() | Nein
Unterstützt rmdir() | Nein

### Siehe auch

- Zlib-Kontextoptionen

# data://

data:// — Daten (RFC 2397)

### Beschreibung

Der Stream-Wrapper data: (» RFC 2397).

### Verwendung

- data://text/plain;base64,

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Ja
Eingeschränkt durch allow_url_include | Ja
Erlaubt Lesen | Ja
Erlaubt Schreiben | Nein
Erlaubt Anfügen | Nein
Erlaubt gleichzeitiges Lesen und Schreiben | Nein
Unterstützt stat() | Nein
Unterstützt unlink() | Nein
Unterstützt rename() | Nein
Unterstützt mkdir() | Nein
Unterstützt rmdir() | Nein

### Beispiele

Beispiel #1 Ausgabe des Inhalts von data://

    <?php
    // gibt "Ich liebe PHP" aus
    echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
    ?>

Beispiel #2 Abrufen des Medientyps

    <?php
    $fp   = fopen('data://text/plain;base64,', 'r');
    $meta = stream_get_meta_data($fp);

    // gibt "text/plain" aus
    echo $meta['mediatype'];
    ?>

# glob://

glob:// — Suche nach Pfadnamen, die einem Muster entsprechen

### Beschreibung

Der Stream-Wrapper glob:.

### Verwendung

- glob://

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Nein
Eingeschränkt durch allow_url_include | Nein
Erlaubt Lesen | Nein
Erlaubt Schreiben | Nein
Erlaubt Anfügen | Nein
Erlaubt gleichzeitiges Lesen und Schreiben | Nein
Unterstützt stat() | Nein
Unterstützt unlink() | Nein
Unterstützt rename() | Nein
Unterstützt mkdir() | Nein
Unterstützt rmdir() | Nein

### Beispiele

Beispiel #1 Grundlegende Verwendung

    <?php
    // Durchläuft alle *.php-Dateien im Verzeichnis ext/spl/examples/
    // und gibt den Dateinamen und die Größe der Dateien aus
    $it = new DirectoryIterator("glob://ext/spl/examples/*.php");
    foreach($it as $f) {
        printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
    }
    ?>

    tree.php: 1.0K
    findregex.php: 0.6K
    findfile.php: 0.7K
    dba_dump.php: 0.9K
    nocvsdir.php: 1.1K
    phar_from_dir.php: 1.0K
    ini_groups.php: 0.9K
    directorytree.php: 0.9K
    dba_array.php: 1.1K
    class_tree.php: 1.8K

# phar://

phar:// — PHP-Archiv

### Beschreibung

Der Stream-Wrapper phar://. Eine ausführliche Beschreibung ist unter Phar-Stream-Wrapper zu finden.

### Verwendung

- phar://

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Nein
Eingeschränkt durch allow_url_include | Nein
Erlaubt Lesen | Ja
Erlaubt Schreiben | Ja
Erlaubt Anfügen | Nein
Erlaubt gleichzeitiges Lesen und Schreiben | Ja
Unterstützt stat() | Ja
Unterstützt unlink() | Ja
Unterstützt rename() | Ja
Unterstützt mkdir() | Ja
Unterstützt rmdir() | Ja

### Siehe auch

- Phar Kontextoptionen

# ssh2://

ssh2:// — Secure Shell 2

### Beschreibung

ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// (PECL)

> Hinweis: Dieser Wrapper ist standardmäßig nicht aktiviert
> Um den Wrapper ssh2.*:// verwenden zu können, muss die » SSH2-Erweiterung von » PECL installiert werden

Neben den herkömmlichen URI-Anmeldedaten akzeptieren die ssh2-Wrapper auch eine im Host-Teil der URL übergebene Verbindungsressource, mit der offene Verbindungen wiederverwendet werden können.

### Verwendung

- ssh2.shell://user:pass@example.com:22/xterm
- ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd
- ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14
- ssh2.sftp://user:pass@example.com:22/path/to/filename

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | ssh2.shell | ssh2.exec | ssh2.tunnel | ssh2.sftp | ssh2.scp
--- | --- | --- | --- | --- | ---
Eingeschränkt durch allow_url_fopen | Ja | Ja | Ja | Ja | Ja
Erlaubt Lesen | Ja | Ja | Ja | Ja | Ja
Erlaubt Schreiben | Ja | Ja | Ja | Ja | Nein
Erlaubt Anfügen | Nein | Nein | Nein | Ja (falls vom Server unterstützt) | Nein
Erlaubt gleichzeitiges Lesen und Schreiben | Ja | Ja | Ja | Ja | Nein
Unterstützt stat() | Nein | Nein | Nein | Ja | Nein
Unterstützt unlink() | Nein | Nein | Nein | Ja | Nein
Unterstützt rename() | Nein | Nein | Nein | Ja | Nein
Unterstützt mkdir() | Nein | Nein | Nein | Ja | Nein
Unterstützt rmdir() | Nein | Nein | Nein | Ja | Nein

Kontextoptionen
Name | Verwendung | Voreinstellung
--- | --- | ---
`session` | Vorab verbundene ssh2-Ressource, die wiederverwendet werden soll |
`sftp` | Vorab zugewiesene sftp-Ressource, die wiederverwendet werden soll |
`methods` | Schlüsselaustausch, Host-Schlüssel, Verschlüsselung, Komprimierung und MAC-Methoden, die verwendet werden sollen |
`callbacks` |  |
`username` | Der Benutzername für die Verbindung |
`password` | Das Passwort für die Authentifizierung |
`pubkey_file` | Der Name der Datei, die den öffentlichen Schlüssel für die Authentifizierung enthält |
`privkey_file` | Der Name der Datei, die den privaten Schlüssel für die Authentifizierung enthält |
`env` | Ein assoziatives Array der zu setzenden Umgebungsvariablen |
`term` | Der Typ der Terminalemulation, der bei der Zuweisung eines pty angefordert wird |
`term_width` | Die Breite des Terminals, die bei der Zuweisung eines pty angefordert wird |
`term_height` | Die Höhe des Terminals, die bei der Zuweisung eines pty angefordert wird |
`term_units` | Die Einheiten, die für term_width und term_height verwendet werden sollen | `SSH2_TERM_UNIT_CHARS`

### Beispiele

Beispiel #1 Öffnen eines Streams aus einer aktiven Verbindung

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
    ?>

Beispiel #2 Diese $session-Variable muss immer verfügbar sein!

Um die ssh2.*://$session-Wrapper verwenden zu können, muss die Ressourcenvariable $session erhalten bleiben. Der folgende Code hat nicht die gewünschte Wirkung:

    <?php
    $session = ssh2_connect('example.com', 22);
    ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                                '/home/username/.ssh/id_rsa', 'secret');
    $connection_string = "ssh2.sftp://$session/";
    unset($session);
    $stream = fopen($connection_string . "path/to/file", 'r');
    ?>

unset() schließt die Session, weil $connection_string keinen Verweis auf die Variable $session enthält, sondern nur eine von ihr abgeleitete Zeichenkette. Dies ist auch der Fall, wenn unset() implizit aufgerufen wird, weil der Gültigkeitsbereich verlassen wird (z. B. bei einer Funktion).

# rar://

rar:// — RAR

### Beschreibung

Der Wrapper akzeptiert den URL-kodierten Pfad zum RAR-Archiv (relativ oder absolut), ein optionales Sternchen (`*`), ein optionales Nummernzeichen (`#`) und optional den URL-kodierten Namen des Eintrags, wie er im Archiv gespeichert ist. Bei Angabe eines Eintragsnamens muss das Nummernzeichen angegeben werden; ein führender Schrägstrich im Eintragsnamen ist optional.

Mit diesem Wrapper können sowohl Dateien als auch Verzeichnisse geöffnet werden. Beim Öffnen eines Verzeichnisses erzwingt das Sternchen, dass der Name des Verzeichniseintrags unkodiert zurückgegeben wird. Wenn es nicht angegeben ist, wird er URL-kodiert zurückgegeben. Damit soll sichergestellt werden, dass der Wrapper korrekt mit eingebauten Funktionen wie dem RecursiveDirectoryIterator verwendet werden kann, wenn der Dateiname nach URL-kodierten Daten aussieht.

Wenn der Teil mit dem Nummernsymbol und dem Eintragsnamen nicht angegeben wird, wird das Stammverzeichnis des Archivs angezeigt. Der Unterschied zu normalen Verzeichnissen besteht darin, dass der resultierende Stream keine Informationen wie z. B. die Änderungszeit enthält, weil das Stammverzeichnis nicht in als separater Eintrag im Archivs gespeichert ist. Wenn der Wrapper mit RecursiveDirectoryIterator verwendet werden soll, muss die URL das Nummernsymbol enthalten, damit die URLs der Unterverzeichnisse korrekt erstellt werden können.

> Hinweis: Dieser Wrapper ist standardmäßig nicht aktiviert
> Um den Wrapper rar:// verwenden zu können, muss die » rar-Erweiterung von » PECL installiert werden

rar:// Available since PECL rar 3.0.0

### Verwendung

- rar://<URL-kodierter Name des Archivs>[*][#[<URL-kodierter Name des Eintrags>]]

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Nein
Eingeschränkt durch allow_url_include | Nein
Erlaubt Lesen | Ja
Erlaubt Schreiben | Nein
Erlaubt Anfügen | Nein
Erlaubt gleichzeitiges Lesen und Schreiben | Nein
Unterstützt stat() | Ja
Unterstützt unlink() | Nein
Unterstützt rename() | Nein
Unterstützt mkdir() | Nein
Unterstützt rmdir() | Nein

Kontextoptionen
Name | Verwendung | Voreinstellung
--- | --- | ---
`open_password` | Das Passwort, mit dem die Header des Archivs verschlüsselt werden, falls vorhanden. WinRAR verschlüsselt alle Dateien mit dem für die Header verwendeten Passwort, falls dieses vorhanden ist; bei Archiven mit verschlüsselten Headern wird `file_password` also ignoriert. |
`file_password` | Das zur Verschlüsselung einer Datei verwendete Passwort, falls vorhanden. Wenn die Header ebenfalls verschlüsselt sind, wird diese Option zugunsten von `open_password` ignoriert. Es gibt diese beiden Optionen, damit auch Archive mit verschiedenen Header- und Dateipasswörtern unterstützt werden können, falls es solche Archive geben sollte. Wenn die Header des Archivs nicht verschlüsselt sind, wird `open_password` ignoriert und stattdessen muss diese Option verwendet werden. |
`volume_callback` | Ein Callback, mit dem der Pfad von fehlenden Archiv-Volumes ermittelt werden kann. Siehe RarArchive::open() für weitere Informationen. |

### Beispiele

Beispiel #1 Durchlaufen eines RAR-Archivs

    <?php

    class MyRecDirIt extends RecursiveDirectoryIterator {
        function current() {
            return rawurldecode($this->getSubPathName()) .
                (is_dir(parent::current())?" [DIR]":"");
        }
    }

    $f = "rar://" . rawurlencode(dirname(__FILE__)) .
        DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';

    $it = new RecursiveTreeIterator(new MyRecDirIt($f));

    foreach ($it as $s) {
        echo $s, "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    |-allow_everyone_ni [DIR]
    |-file1.txt
    |-file2_אּ.txt
    |-with_streams.txt
    \-אּ [DIR]
      |-אּ\%2Fempty%2E [DIR]
      | \-אּ\%2Fempty%2E\file7.txt
      |-אּ\empty [DIR]
      |-אּ\file3.txt
      |-אּ\file4_אּ.txt
      \-אּ\אּ_2 [DIR]
        |-אּ\אּ_2\file5.txt
        \-אּ\אּ_2\file6_אּ.txt

Beispiel #2 Öffnen einer verschlüsselten Datei (Header-Verschlüsselung)

    <?php
    $stream = fopen("rar://" .
        rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
        'encrypted_headers.rar' . '#encfile1.txt', "r", false,
        stream_context_create(
            array(
                'rar' =>
                    array(
                        'open_password' => 'samplepassword'
                    )
                )
            )
        );
    var_dump(stream_get_contents($stream));
    /* Erstellungsdatum und Datum des letzten Zugriffs sind in WinRAR optional,
     * weshalb diese Angaben bei den meisten Dateien fehlen */
    var_dump(fstat($stream));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(26) "Encrypted file 1 contents."
    Array
    (
        [0] => 0
        [1] => 0
        [2] => 33206
        [3] => 1
        [4] => 0
        [5] => 0
        [6] => 0
        [7] => 26
        [8] => 0
        [9] => 1259550052
        [10] => 0
        [11] => -1
        [12] => -1
        [dev] => 0
        [ino] => 0
        [mode] => 33206
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 26
        [atime] => 0
        [mtime] => 1259550052
        [ctime] => 0
        [blksize] => -1
        [blocks] => -1
    )

# ogg://

ogg:// — Audio-Streams

### Beschreibung

Dateien, die über den Wrapper ogg:// zum Lesen geöffnet werden, werden als komprimierte Audiodaten behandelt, die mit dem `OGG/Vorbis`-Codec kodiert wurden. Entsprechend werden Dateien, die über den Wrapper ogg:// im Schreib- oder Anfügemodus geöffnet werden, als komprimierte Audiodaten geschrieben. Wenn die Funktion stream_get_meta_data() auf eine `OGG/Vorbis`-Datei angewendet wird, die im Lesemodus geöffnet wurde, gibt sie verschiedene Details über den Stream zurück, einschließlich des Hersteller- (`vendor`) Tags, aller enthaltenen Kommentare (`comments`), der Anzahl der Kanäle (`channels`), der Abtastrate (`rate`) und der Kodierungsrate, beschrieben durch `bitrate_lower`, `bitrate_upper`, `bitrate_nominal` und `bitrate_window`.

ogg:// (PECL)

> Hinweis: Dieser Wrapper ist standardmäßig nicht aktiviert
> Um den Wrapper ogg:// verwenden zu können, muss die » OGG/Vorbis-Erweiterung von » PECL installiert werden

### Verwendung

- ogg://soundfile.ogg
- ogg:///path/to/soundfile.ogg
- ogg://http://www.example.com/path/to/soundstream.ogg

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Nein
Erlaubt Lesen | Ja
Erlaubt Schreiben | Ja
Erlaubt Anfügen | Ja
Erlaubt gleichzeitiges Lesen und Schreiben | Nein
Unterstützt stat() | Nein
Unterstützt unlink() | Nein
Unterstützt rename() | Nein
Unterstützt mkdir() | Nein
Unterstützt rmdir() | Nein

Kontextoptionen
Name | Verwendung | Voreinstellung | Modus
--- | --- | --- | ---
`pcm_mode` | Die PCM-Kodierung, die beim Lesen angewendet werden soll, eine von: `OGGVORBIS_PCM_U8`, `OGGVORBIS_PCM_S8`, `OGGVORBIS_PCM_U16_BE`, `OGGVORBIS_PCM_S16_BE`, `OGGVORBIS_PCM_U16_LE` und `OGGVORBIS_PCM_S16_LE`. (8 oder 16 Bit, vorzeichenbehaftet oder vorzeichenlos, big- oder little-`endian`) | OGGVORBIS_PCM_S16_LE | Lesen
`rate` | Die Abtastrate der Eingangsdaten, in Hz | 44100 | Schreiben/Anfügen
`bitrate` | Bei Angabe als Ganzzahl die feste Bitrate, mit der kodiert werden soll (16000 bis 131072). Bei Angabe als Gleitkommazahl die zu verwendende Qualität der variablen Bitrate (-1.0 bis 1.0). | 128000 | Schreiben/Anfügen
`channels` | Die Anzahl der zu kodierenden Audiokanäle, normalerweise 1 (Mono) oder 2 (Stereo). Bis zu 16 Kanäle sind möglich. | 2 | Schreiben/Anfügen
`comments` | Ein Array von Zeichenketten, die in den Track-Header kodiert werden sollen. |  | Schreiben/Anfügen

# expect://

expect:// — Streams für die Interaktion mit Prozessen

### Beschreibung

Streams, die über den Wrapper expect:// geöffnet werden, bieten über PTY Zugriff auf stdin, stdout und stderr eines Prozesses.

> Hinweis: Dieser Wrapper ist standardmäßig nicht aktiviert
> Um den Wrapper expect:// verwenden zu können, muss die » Expect-Erweiterung von » PECL installiert werden

expect:// (PECL)

### Verwendung

- expect://befehl

### Optionen

Zusammenfassung des Wrappers
Eigenschaft | wird unterstützt
--- | ---
Eingeschränkt durch allow_url_fopen | Nein
Erlaubt Lesen | Ja
Erlaubt Schreiben | Ja
Erlaubt Anfügen | Ja
Erlaubt gleichzeitiges Lesen und Schreiben | Nein
Unterstützt stat() | Nein
Unterstützt unlink() | Nein
Unterstützt rename() | Nein
Unterstützt mkdir() | Nein
Unterstützt rmdir() | Nein

## Inhaltsverzeichnis

- file:// — Zugriff auf das lokale Dateisystem
- http:// — Zugriff auf HTTP(s)-URLs
- ftp:// — Zugriff auf FTP(s)-URLs
- php:// — Zugriff auf verschiedene I/O-Streams
- zlib:// — Komprimierungsstreams
- data:// — Daten (RFC 2397)
- glob:// — Suche nach Pfadnamen, die einem Muster entsprechen
- phar:// — PHP-Archiv
- ssh2:// — Secure Shell 2
- rar:// — RAR
- ogg:// — Audio-Streams
- expect:// — Streams für die Interaktion mit Prozessen

- Grundlagen der Syntax
  - PHP-Tags
  - Den HTML-Bereich verlassen
  - Die Trennung von Anweisungen
  - Kommentare
- Typen
  - Einführung
  - Typsystem
  - NULL
  - Booleans
  - Ganzzahlen (Integer)
  - Gleitkommazahlen
  - Strings (Zeichenketten)
  - Numerische Zeichenketten
  - Arrays
  - Objekte
  - Aufzählungen (Enum)
  - Ressourcen
  - Callables
  - Mixed
  - Void
  - Never
  - Relative Klassentypen
  - Singleton-Typen
  - Iterable
  - Typdeklarationen
  - Typumwandlung (Typen-Jonglage)
- Variablen
  - Grundlegendes
  - Vordefinierte Variablen
  - Geltungsbereich von Variablen
  - Variable Variablen
  - Variablen aus externen Quellen
- Konstanten
  - Syntax
  - Vordefinierte Konstanten
  - Magische Konstanten
- Ausdrücke
- Operatoren
  - Operator-Rangfolge
  - Arithmetisch — Arithmetische Operatoren
  - Inkrement und Dekrement — Inkrement- bzw. Dekrement-Operatoren
  - Zuweisung — Zuweisungsoperatoren
  - Bit — Bit-Operatoren
  - Vergleich — Vergleichs-Operatoren
  - Fehlerkontrolle — Operator zur Fehlerkontrolle
  - Programmausführung — Operator zur Programmausführung
  - Logik — Logische Operatoren
  - Zeichenketten — Zeichenketten-Operatoren
  - Array — Array-Operatoren
  - Typ — Typ-Operatoren
  - Functional — Functional Operators
- Kontrollstrukturen
  - Einführung
  - if
  - else
  - elseif/else if
  - Alternative Syntax für Kontrollstrukturen
  - while
  - do-while
  - for
  - foreach
  - break
  - continue
  - switch
  - match
  - declare
  - return
  - require
  - include
  - require_once
  - include_once
  - goto
- Funktionen
  - Benutzerdefinierte Funktionen
  - Funktionsparameter und -argumente
  - Rückgabewerte
  - Variablenfunktionen
  - Interne (eingebaute) Funktionen
  - Anonyme Funktionen
  - Pfeilfunktionen
  - Callback-Funktionen als Objekte erster Klasse
- Klassen und Objekte
  - Einführung
  - Die Grundlagen
  - Eigenschaften
  - Property Hooks
  - Klassenkonstanten
  - Automatisches Laden von Klassen
  - Konstruktoren und Destruktoren
  - Sichtbarkeit
  - Objekt-Vererbung
  - Gültigkeitsbereichsoperator (::)
  - Schlüsselwort static
  - Klassenabstraktion
  - Objekt-Interfaces (Schnittstellen)
  - Traits
  - Anonyme Klassen
  - Überladung
  - Objektiteration
  - Magische Methoden
  - Final-Schlüsselwort
  - Objekte klonen
  - Objekte vergleichen
  - Späte statische Bindung
  - Objekte und Referenzen
  - Serialisierung von Objekten — Serialisierung von Objekten - Objekte in Sessions
  - Kovarianz und Kontravarianz
  - Lazy Objects
  - OOP-Changelog
- Namespaces
  - Übersicht — Übersicht über Namespaces
  - Namespaces — Namespaces definieren
  - Unter-Namespaces — Unter-Namespaces deklarieren
  - Mehrere Namespaces in derselben Datei definieren
  - Grundlagen — Namespaces verwenden: Grundlagen
  - Namespaces und dynamische Sprachfeatures
  - Schlüsselwort namespace und __NAMESPACE__ — Das Schlüsselwort namespace und die magische Konstante __NAMESPACE__
  - Aliase und Importieren — Namespaces verwenden: Aliase/Importieren
  - Globaler Namensraum
  - Rückgriff auf den globalen Namespace — Namespaces verwenden: Rückgriff auf den globalen Namespace für Funktionen und Konstanten
  - Regeln für Namensauflösung
  - FAQ — FAQ: Dinge, die Sie über Namespaces wissen sollten
- Aufzählungen (Enum)
  - Übersicht über Aufzählungen
  - Grundlagen der Aufzählungen
  - Wertgebundene Aufzählungen (Backed Enums)
  - Aufzählungen und Methoden
  - Aufzählungen und statische Methoden
  - Aufzählungen und Konstanten
  - Traits
  - Enum-Werte in konstanten Ausdrücken
  - Unterschiede zu Objekten
  - Liste mit Werten
  - Serialisierung
  - Warum Enums nicht erweiterbar sind
  - Beispiele
- Fehler
  - Basics
  - Fehler in PHP 7
- Exceptions (Ausnahmen)
  - Exceptions erweitern
- Fibers
- Generatoren
  - Generatoren-Übersicht
  - Generator-Syntax
  - Vergleich von Generatoren mit Iterator-Objekten
- Attribute
  - Übersicht über die Attribute
  - Syntax von Attributen
  - Lesen von Attributen mit der Reflection-API
  - Deklaration von Attributklassen
- Referenzen
  - Was Referenzen sind
  - Was Referenzen leisten
  - Was Referenzen nicht sind
  - Parameterübergabe per Referenz
  - Referenzen zurückgeben
  - Referenzen aufheben
  - Referenzen entdecken
- Vordefinierte Variablen
  - Superglobals — Interne Variablen, die immer in allen Gültigkeitsbereichen verfügbar sind
  - $GLOBALS — Referenziert alle Variablen, die im globalen Gültigkeitsbereich vorhanden sind
  - $_SERVER — Informationen über Server und Ausführungsumgebung
  - $_GET — Query-String-Variablen
  - $_POST — Formulardaten aus HTTP-POST-Anfragen
  - $_FILES — HTTP Dateiupload-Variablen
  - $_REQUEST — HTTP Request-Variablen
  - $_SESSION — Sessionvariablen
  - $_ENV — Umgebungsvariablen
  - $_COOKIE — HTTP Cookies
  - $php_errormsg — Die vorangegangene Fehlermeldung
  - $http_response_header — HTTP Response-Header
  - $argc — Die Anzahl der an das Skript übergebenen Argumente
  - $argv — Array der an das Skript übergebenen Argumente
- Vordefinierte Exceptions
  - Exception
  - ErrorException
  - ClosedGeneratorException — Die Klasse ClosedGeneratorException
  - Error
  - ArgumentCountError
  - ArithmeticError
  - AssertionError
  - DivisionByZeroError
  - CompileError
  - ParseError
  - TypeError
  - ValueError
  - UnhandledMatchError
  - FiberError
  - RequestParseBodyException
- Vordefinierte Interfaces und Klassen
  - Traversable — Das Traversable-Interface
  - Iterator — Das Iterator-Interface
  - IteratorAggregate — Das IteratorAggregate-Interface
  - InternalIterator — Die Klasse InternalIterator
  - Throwable
  - Countable — The Countable interface
  - ArrayAccess — Das ArrayAccess-Interface
  - Serializable — Das Serializable-Interface
  - Closure — Die Klasse Closure
  - stdClass — Die Klasse stdClass
  - Generator — Die Klasse Generator
  - Fiber — Die Klasse Fiber
  - WeakReference — Die Klasse WeakReference
  - WeakMap — Die Klasse WeakMap
  - Stringable — Das Stringable-Interface
  - UnitEnum — Die UnitEnum-Schnittstelle
  - BackedEnum — Die BackedEnum-Schnittstelle
  - SensitiveParameterValue — Die Klasse SensitiveParameterValue
  - __PHP_Incomplete_Class — Die Klasse __PHP_Incomplete_Class
- Vordefinierte Attribute
  - Attribute — Das Attribut Attribute
  - AllowDynamicProperties — Das Attribut AllowDynamicProperties
  - DelayedTargetValidation — The DelayedTargetValidation attribute
  - Deprecated — Das Attribut Deprecated
  - NoDiscard — Das Attribut NoDiscard
  - Override — Das Attribut Override
  - ReturnTypeWillChange — Das Attribut ReturnTypeWillChange
  - SensitiveParameter — Das Attribut SensitiveParameter
- Kontextoptionen und -parameter
  - Socket-Kontextoptionen — Liste der Socket-Kontextoptionen
  - HTTP-Kontextoptionen — Liste der HTTP-Kontextoptionen
  - FTP-Kontextoptionen — Liste der FTP-Kontextoptionen
  - SSL-Kontext-Optionen — Liste der SSL-Kontext-Optionen
  - Phar Kontextoptionen — Liste der Phar Kontextoptionen
  - Kontextparameter — Liste der Kontextparameter
  - Zip-Kontextoptionen — Liste der Zip-Kontextoptionen
  - Zlib-Kontextoptionen — Liste der Zlib-Kontextoptionen
- Unterstützte Protokolle und Wrapper
  - file:// — Zugriff auf das lokale Dateisystem
  - http:// — Zugriff auf HTTP(s)-URLs
  - ftp:// — Zugriff auf FTP(s)-URLs
  - php:// — Zugriff auf verschiedene I/O-Streams
  - zlib:// — Komprimierungsstreams
  - data:// — Daten (RFC 2397)
  - glob:// — Suche nach Pfadnamen, die einem Muster entsprechen
  - phar:// — PHP-Archiv
  - ssh2:// — Secure Shell 2
  - rar:// — RAR
  - ogg:// — Audio-Streams
  - expect:// — Streams für die Interaktion mit Prozessen

# Sicherheit

# Einführung

PHP ist eine mächtige Sprache, und der Interpreter, der in einen Webserver als Modul oder als separate CGI-Version eingebunden werden kann, kann auf Dateien zugreifen, Befehle ausführen und Netzwerkverbindungen zu einem Server herstellen. Diese Eigenschaften können einen Webserver unsicher machen, wenn man es bei den Voreinstellungen belässt. PHP wurde besonders dafür entwickelt, um eine sicherere Sprache als Perl oder C für die Erstellung von CGI-Programmen bereitzustellen. Mit der richtigen Wahl der Einstellungen beim Kompilieren und zur Laufzeit bietet PHP genau die Kombination aus Freiheit und Sicherheit, die gerade benötigt wird.

Da es sehr viele verschiedene Möglichkeiten gibt, PHP zu nutzen, gibt es viele Konfigurationseinstellungen, die das Verhalten von PHP beeinflussen. Eine große Auswahl an Einstellungen garantiert, dass man PHP für viele Zwecke einsetzen kann. Allerdings bedeutet das auch, dass es Kombinationen gibt, die eine Installation mit nur ungenügender Sicherheit zur Folge haben.

Die Flexibilität der Konfiguration konkurriert mit der Flexibilität in der Programmierung. Mit PHP können komplette Server-Applikationen mit allen Möglichkeiten eines Shell Benutzers erstellt werden, oder auch nur einfache Server-Side-Includes mit einem minimalen Risiko in einer streng kontrollierten Umgebung. Wie die Umgebung erstellt wird, und wie sicher diese ist, ist zu einem großen Teil die Sache des PHP-Entwicklers.

Dieses Kapitel beginnt mit einigen generellen Ratschlägen zur Sicherheit, erklärt die verschiedenen Kombinationen der Konfigurationseinstellungen und unter welchen Gegebenheiten sie sicher genutzt werden können, und beschreibt verschiedene Überlegungen zur Programmierung für verschiedene Sicherheitsstufen.

# Allgemeine Überlegungen

Ein komplett sicheres System ist praktisch ein Ding der Unmöglichkeit, weshalb ein unter Sicherheitsprofis oft genutzter Ansatz ist, einen Mittelweg zwischen Risiko und Verwendbarkeit zu finden. Wenn jede von einem Benutzer übermittelte Variable zwei Formen von biometrischer Prüfung (wie z.B. ein Scan der Netzhaut und ein Fingerabdruck) verlangen würde, wäre eine extrem hohe Ebene der Verantwortlichkeit erreicht. Ein sehr komplexes Formular auszufüllen würde auch eine halbe Stunde in Anspruch nehmen, die Benutzer dazu ermuntern könnte, Wege zur Umgehung der Sicherheitsmaßnahmen zu suchen.

Die beste Sicherheit ist oft unaufdringlich genug, um den Anforderungen zu entsprechen, ohne den Benutzer an seiner Arbeit zu hindern oder den Code-Autor mit übertriebener Komplexität zu überlasten. Tatsächlich sind einige Sicherheitsangriffe nur die Folge von allzu strengen Sicherheitsmaßnahmen, was mit der Zeit nur zu deren Unterminierung führt.

Eine Phrase, die es wert ist, sich an sie zu erinnern: Ein System ist nur so gut wie das schwächste Glied in der Kette. Wenn alle Transaktionen mittels Zeit, Ort, Transaktionstyp, etc. streng mitprotokolliert werden, der Benutzer aber nur mittels eines einzigen Cookies verifiziert wird, lässt die Zuverlässigkeit für die Bindung des Benutzers an das Transaktions-Log bedrohlich nach.

Denken Sie während der Tests daran, dass Sie selbst für die einfachsten Seiten nicht alle Möglichkeiten testen können. Der von Ihnen vielleicht erwartete Input wird zu dem eines verstimmten Mitarbeiters oder eines Crackers, der Monate Zeit hat, oder einer Katze, die über die Tastatur läuft, in keinerlei Zusammenhang stehen. Deshalb betrachten Sie Ihren Code am Besten aus der logischen Perspektive, um zu erkennen, wo unerwartete Daten eingebracht werden können und fragen sich dann, wie diese modifiziert, reduziert, oder weiter ausgeführt werden.

Das Internet ist voll von Leuten, die versuchen, sich durch Entschlüsseln/Zerstören Ihres Codes, den Zusammenbruch Ihres Systems, Einsetzen von unangebrachten Inhalten, und anderen, Ihren Tag interessant gestaltenden Maßnahmen, einen Namen zu machen. Es ist egal, ob Sie eine kleine oder große Site haben, Sie sind einfach ein Ziel, wenn Sie online sind oder wenn Sie einen Server haben, zu dem man eine Verbindung aufbauen kann. Viele Cracker-Programme erkennen nicht die Größe, sondern durchsieben einfach gewaltige IP-Blöcke im Netz, um Opfer zu finden. Versuchen Sie, keines zu werden.

# Installiert als CGI-Version

## Inhaltsverzeichnis

- Mögliche Angriffe
- Fall 1: Nur öffentliche Dateien vorhanden
- Fall 2: --enable-force-cgi-redirect benutzen
- Fall 3: doc_root oder user_dir festlegen
- Fall 4: PHP-Parser außerhalb des Webverzeichnisbaums

## Mögliche Angriffe

PHP als CGI-Version zu nutzen, ist eine Möglichkeit für Installationen, bei denen aus irgendwelchen Gründen kein Modul in die Serversoftware eingebunden werden soll (wie beim Apache) oder für Systeme, bei denen verschiedene CGI-Wrapper genutzt werden sollen, um sichere chroot- und setuid-Umgebungen für Skripte zu schaffen. Bei dieser Konfiguration wird das ausführbare php-Binary üblicherweise im cgi-bin-Verzeichnis des Webservers installiert. CERT-Advisory » CA-96.11 spricht sich gegen die Platzierung von Interpretern im cgi-bin-Verzeichnis aus. Obwohl das php-Binary als eigenständiger Interpreter verwendet werden kann, wurde PHP so entwickelt, um den durch diese Konfiguration möglich werdenden Angriffe vorzubeugen:

- Zugriff auf Systemdateien: http://my.host/cgi-bin/php?/etc/passwd Die auf ein Fragezeichen (`?`) folgende Abfrageinformation in einer URL wird durch das CGI-Interface als Kommandozeilenargument an den Interpreter weitergereicht. In der Kommandozeile wird üblicherweise die im ersten Argument angegebene Datei von Interpretern geöffnet und ausgeführt. Beim Aufruf als CGI-Binary verweigert php die Interpretation der Kommandozeilenargumente.
- Zugriff auf beliebige Web-Dokumente auf dem Server: http://my.host/cgi-bin/php/secret/doc.html Der Teil der URL-Pfadinformation nach dem Namen der PHP Binärdatei, /secret/doc.html, wird im Allgemeinen benutzt, um den Namen der Datei zu übergeben, die durch das CGI-Programm geöffnet und interpretiert werden soll. Normalerweise werden einige Einträge in der Konfigurationsdatei des Webservers benutzt (Apache: `Action`), um Aufrufe von Dokumenten wie http://my.host/secret/script.php an den PHP-Interpreter umzuleiten. Bei dieser Konfiguration überprüft der Webserver zuerst die Zugriffsrechte im Verzeichnis /secret und erstellt anschließend den umgeleiteten Aufruf http://my.host/cgi-bin/php/secret/script.php. Unglücklicherweise wird, wenn der Aufruf bereits in dieser Form geschieht, vom Webserver keine Zugriffsüberprüfung der Datei /secret/script.php, sondern lediglich der Datei /cgi-bin/php vorgenommen. So ist jeder Benutzer, der auf /cgi-bin/php zugreifen darf, in der Lage, sich zu jedem geschützten Dokument auf dem Webserver Zugriff zu verschaffen. Bei PHP können beim Kompilieren die Konfigurationsdirektiven cgi.force_redirect, doc_root und user_dir benutzt werden, um diesen Angriff zu verhindern, falls der Verzeichnisbaum des Servers Verzeichnisse mit Zugriffsbeschränkungen beinhaltet. Ausführliche Informationen über die verschiedenen Kombinationen sind weiter unten beschrieben.

## Fall 1: Nur öffentliche Dateien vorhanden

Wenn der Server keine Inhalte hat, die durch ein Passwort oder IP-basierte Zugriffskontrolle geschützt sind, werden diese Konfigurationsoptionen nicht benötigt. Wenn der Webserver keine Redirects erlaubt oder keine Möglichkeit hat, dem PHP-Binary mitzuteilen, dass es sich um eine sicher umgeleitete Anfrage handelt, kann die Konfigurationsdirekive cgi.force_redirect aktiviert werden. Nichtsdestotrotz müssen Sie sicherstellen, dass Ihre PHP-Skripte nicht auf die eine oder andere Art des Aufrufs angewiesen sind, weder direkt durch http://my.host/cgi-bin/php/dir/script.php noch durch einen Redirect http://my.host/dir/script.php.

Beim Apache kann der Redirect durch Verwendung der Direktiven `AddHandler` und `Action` konfiguriert werden (siehe unten).

## Fall 2: `--enable-force-cgi-redirect` benutzen

Die Konfigurationsdirektive cgi.force_redirect verhindert grundsätzlich den Aufruf von php mit einer URL wie http://my.host/cgi-bin/php/secretdir/script.php. Stattdessen parst PHP in diesem Modus nur dann, wenn der Aufruf durch einen korrekten Redirect des Webservers erfolgte.

Normalerweise wird der Redirect in der Apache-Konfiguration mit den folgenden Einträgen festgelegt:

    Action php-script /cgi-bin/php
    AddHandler php-script .php

Diese Option wurde nur mit dem Apache Webserver getestet und ist abhängig davon, wie Apache die nicht standardmäßige CGI-Umgebungsvariable REDIRECT_STATUS bei Redirect-Anfragen setzt. Sollte Ihr Webserver keine Möglichkeit unterstützen, zu übermitteln, ob es sich um einen direkten Aufruf oder einen Redirect handelt, können Sie diese Option nicht verwenden und müssen einen der anderen hier beschriebenen Wege gehen, die CGI-Version zu nutzen.

## Fall 3: doc_root oder user_dir festlegen

Aktiven Inhalt, wie beispielsweise Skripts und ausführbare Dateien, in den Dokumentverzeichnissen des Webservers abzulegen, wird manchmal als unsichere Methode angesehen. Wenn, beispielsweise aufgrund von Konfigurationsfehlern, die Skripte nicht ausgeführt, sondern als reguläre HTML-Dokumente angezeigt werden, kann dies ein Durchsickern von geistigem Eigentum und sicherheitsrelevanter Informationen wie Passwörtern zur Folge haben. Deshalb ziehen es viele Systemadministratoren vor, eine zweite Verzeichnisstruktur für Skripte einzurichten, auf die nur durch das PHP-CGI zugegriffen werden kann. Diese werden dann stets interpretiert und nicht angezeigt.

Auch wenn die Methode zum sichergestellten Verhindern einer Umleitung von Anfragen (wie im vorangegangenen Abschnitt beschrieben) nicht verfügbar ist, ist es notwendig, ein doc_root für Skripte zusätzlich zum Web-Dokumentenverzeichnis einzurichten.

Sie können das PHP-Skriptverzeichnis durch die Direktive doc_root in der Konfigurationsdatei festlegen, oder Sie setzen die Umgebungsvariable PHP_DOCUMENT_ROOT. Wenn sie gesetzt ist, wird die CGI-Version von PHP den Namen der zu öffnenden Datei stets aus `doc_root` und der Pfadinformation der Anfrage zusammensetzen, sodass man sicher sein kann, dass außerhalb dieses Verzeichnisses keine Skripte ausgeführt werden (außer `user_dir`, siehe unten).

Eine weitere hier nützliche Option ist user_dir. Wenn `user_dir` nicht gesetzt ist, hat nur `doc_root` Einfluss auf die zu öffnende Datei. Der Aufruf einer URL wie http://my.host/~user/doc.php hat nicht zum Ergebnis, dass eine Datei im Heimatverzeichnis des Benutzers geöffnet wird, sondern eine Datei namens ~user/doc.php unterhalb von `doc_root`. (Ja, ein Verzeichnisname, der mit einer Tilde anfängt [`~`].)

Ist `user_dir` beispielsweise auf public_php gesetzt, wird eine Anfrage wie http://my.host/~user/doc.php eine Datei namens doc.php im Verzeichnis public_php im Heimatverzeichnis des Benutzers öffnen. Wenn das Heimatverzeichnis des Benutzers /home/user ist, so ist die ausgeführte Datei /home/user/public_php/doc.php.

Die `user_dir`-Expansion erfolgt ohne Berücksichtigung der `doc_root`-Einstellung. So können Zugriffe auf die Dokumenten- und Benutzerverzeichnisse separat gesteuert werden.

## Fall 4: PHP-Parser außerhalb des Webverzeichnisbaums

Eine sehr sichere Sache ist es, das PHP-Parser-Binary irgendwo außerhalb des Webverzeichnisbaums zu platzieren, beispielsweise in /usr/local/bin. Der einzige Nachteil dieses Verfahrens ist, dass eine Zeile ähnlich der folgenden Zeile:

    #!/usr/local/bin/php

als erste Zeile in jeder Datei, die PHP-Tags enthält, stehen muss. Außerdem muss die Datei ausführbar sein. Ansonsten ist sie genauso zu behandeln wie ein beliebiges CGI-Script in Perl oder sh oder anderen gebräuchlichen Skriptsprachen, die den `#!`-shell-escape-Mechanismus nutzen, um sich selbst aufzurufen.

Damit PHP bei dieser Konfiguration die PATH_INFO- und PATH_TRANSLATED-Informationen korrekt auswertet, muss die Konfigurationsdirektive cgi.discard_path aktiviert werden.

# Verwendung als Apache-Modul

Wenn PHP als Apache-Modul eingesetzt wird, übernimmt es die Benutzerrechte des Apache (üblicherweise die des Users "nobody"). Das hat verschiedene Auswirkungen auf Sicherheit und Authentifizierung. Wenn Sie beispielsweise via PHP auf eine Datenbank zugreifen, müssen Sie dem Benutzer "nobody" Zugriffsrechte auf die Datenbank erteilen, es sei denn, diese Datenbank hat eine integrierte Zugriffskontrolle. Das heißt, dass ein böswilliges Skript auch ohne Benutzerkennung und Passwort auf die Datenbank zugreifen und sie verändern könnte. Es ist durchaus möglich, dass ein Web-Spider über die Webseite eines Datenbankadministrators stolpert und alle Ihre Datenbanken löscht. Sie können sich dagegen mit Apache-Authentifizierung schützen, oder ein eigenes Zugangsmodell unter Verwendung von LDAP, .htaccess Dateien etc. entwerfen, und diesen Code als Teil Ihrer PHP-Skripte einbinden.

Ist erst einmal eine Sicherheitsstruktur bis zu dem Punkt eingerichtet, an dem der PHP-User (in diesem Falle der Apache-User) nur noch ein geringes Risiko darstellt, hat man meist die Situation, dass PHP gehindert wird, beliebige Dateien in das Benutzerverzeichnis zu schreiben. Oder vielleicht ist PHP dann nicht mehr in der Lage, auf Datenbanken lesend oder verändernd zuzugreifen. In gleicher Weise wird auch verhindert, "gute" oder "bösartige" Dateien zu schreiben, oder "gute" bzw. "bösartige" Datenbanktransaktionen durchzuführen.

Ein an diesem Punkt oft geöffnetes Sicherheitsloch ist die Zuweisung von Root-Rechten an den Apache-Prozess oder die Ausweitung der Rechte des Apache auf anderem Wege.

Die Ausweitung der Benutzerrechte für Apache auf root ist extrem gefährlich und kann das gesamte System kompromittieren, daher sollten Prozesse, die wie sudo oder chroot mit Rootrechten arbeiten, niemandem zugänglich sein, der kein Sicherheitsprofi ist.

Es gibt deutlich einfachere Lösungen. Mit open_basedir können Sie kontrollieren, welche Verzeichnisse PHP benutzen darf oder nicht. Sie können auch einen Bereich nur für Apache einrichten, um alle webbasierten Aktivitäten auf dem System oder nicht dem Benutzer gehörende Dateien zu verhindern.

# Session Sicherheit

Es ist wichtig, die HTTP-Session-Verwaltung sicher zu halten. Sessionbezogene Sicherheit wird im Abschnitt Session Sicherheit der Referenz zum Session-Modul beschrieben.

# Sicherheit des Dateisystems

## Inhaltsverzeichnis

- Probleme im Zusammenhang mit Nullbytes

PHP ist hinsichtlich der Berechtigungen auf Datei- und Verzeichnisebene von den in den meisten Serversystemen implementierten Sicherheitseinstellungen abhängig. Dies verleiht Ihnen Kontrolle darüber, welche Dateien im Dateisystem gelesen werden dürfen. Es sollte sichergestellt werden, dass alle öffentlich zugänglichen Dateien von allen Benutzern, die Zugang zu diesem Dateisystem haben, gelesen werden können, ohne die Sicherheit zu gefährden.

Da PHP entwickelt wurde, um Zugriffe auf das Dateisystem auf Benutzebene zu erlauben, ist es natürlich auch möglich, ein PHP-Skript zu schreiben, dass Ihnen erlaubt, Systemdateien wie /etc/passwd zu lesen, Ethernetverbindungen zu modifizieren, enorme Druckaufträge zu senden etc. Dies hat offensichtliche Implikationen, indem Sie sicherstellen müssen, dass alle von Ihnen zu lesenden bzw. zu schreibenden Dateien auch die richtigen sind.

Stellen Sie sich folgendes Skript vor, in dem ein Benutzer zum Ausdruck bringt, dass er eine Datei in seinem Heimatverzeichnis löschen möchte. Es wird davon ausgegangen, dass ein PHP-Webinterface regelmäßig für das Dateimanagement verwendet wird und dass der Apache-Benutzer berechtigt ist, in seinem Heimatverzeichnis Dateien zu löschen.

Beispiel #1 Schlechte Variablenprüfung führt zu....

    <?php

    // Löschen einer Datei aus dem Heimatverzeichnis des Users
    $username = $_POST['user_submitted_name'];
    $userfile = $_POST['user_submitted_filename'];
    $homedir  = "/home/$username";

    unlink("$homedir/$userfile");

    echo "Die Datei wurde gelöscht!";

    ?>

Da Benutzer- und Dateiname über ein Benutzerformular bereitgestellt werden, kann jeder jemand anderes Benutzer- und Dateinamen übertragen und so Dateien löschen, ohne über die entsprechnde Erlaubnis zu verfügen. In diesem Fall empfiehlt es sich, eine andere Form der Authentifizierung zu verwenden. Stellen Sie sich vor was passieren würde, wenn die übertragenen Variablen `"../etc/"` und `"passwd"` beinhalten würden. Der Code würde dann folgendermaßen aussehen:

Beispiel #2 ... Ein Angriff auf das Dateisystem

    <?php

    // Löscht eine Datei irgendwo auf der Festplatte, wo der Benutzer
    // die nötigen Rechte besitzt. Wenn PHP root-Zugriff hat:
    $username = $_POST['user_submitted_name']; // "../etc"
    $userfile = $_POST['user_submitted_filename']; // "passwd"
    $homedir  = "/home/$username"; // "/home/../etc"

    unlink("$homedir/$userfile"); // "/home/../etc/passwd"

    echo "Die Datei wurde gelöscht!";?>

    ?>

Es gibt zwei wichtige Kriterien die Sie beachten sollten, um diese Dinge zu vermeiden:

- Erteilen Sie dem PHP Web-user (Binärdatei) nur eingeschränkte Rechte.
- Prüfen Sie alle übertragenen Variablen.

Hier ist ein verbessertes Skript:

Beispiel #3 Etwas sicherere Prüfung des Dateinamens

    <?php

    // Löscht eine Datei von der Festplatte, auf die
    // der PHP-Benutzer Zugriff hat.
    $username = $_SERVER['REMOTE_USER']; // using an authentication mechanism
    $userfile = basename($_POST['user_submitted_filename']);
    $homedir  = "/home/$username";

    $filepath = "$homedir/$userfile";

    if (file_exists($filepath) && unlink($filepath)) {
        $logstring = "$filepath gelöscht\n";
    } else {
        $logstring = "$filepath konnte nicht gelöscht\n";
    }

    $fp = fopen("/home/logging/filedelete.log", "a");
    fwrite($fp, $logstring);
    fclose($fp);

    echo htmlentities($logstring, ENT_QUOTES);

    ?>

Auch dies nicht ohne Schwachstellen. Wenn Ihr Authentifizierungssystem Benutzern erlauben sollte, deren eigene Logins zu kreieren, und ein Benutzer wählt den Login `"../etc/"`, ist das System erneut angreifbar. Aus diesem Grund sollten Sie eventuell eine speziellere Überprüfung durchführen

Beispiel #4 Sicherere Dateinamensprüfung

    <?php

    $username     = $_SERVER['REMOTE_USER']; // Nutzung eines Authentifikationsmechanismus
    $userfile     = $_POST['user_submitted_filename'];
    $homedir      = "/home/$username";

    $filepath     = "$homedir/$userfile";

    if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
        die("Ungültiger Benutzer- oder Dateiname");
    }

    // etc.

    ?>

Abhängig vom Betriebssystem gibt es eine große Anzahl Dateien, auf die Sie achten sollten, inklusive Einträge für Geräte (/dev/ oder com1), Konfigurationsdateien (die Dateien in /etc/ und die `.ini`-Dateien), allgemein bekannte Verzeichnisse (/home/, My Documents) etc. Aus diesem Grund ist es für gewöhnlich einfacher, eine Richtlinie zu erstellen, in der alles verboten ist, was Sie nicht ausdrücklich erlauben.

## Probleme im Zusammenhang mit Nullbytes

Da PHP die Funktionen der C-Standardbibliothek für Dateisystemoperationen nutzt kann es Nullbytes in unerwarteter Weise verarbeiten. Da Nullbytes in C das Stringende festlegen werden Strings die solche enthalten nicht vollständig verarbeitet sondern nur bis zum ersten Auftreten eines Nullbytes. Das folgende Beispiel zeigt einen anfälligen Code, der dieses Problem verdeutlicht:

Beispiel #1 Skript mit Nullbyte-Verwundbarkeit

    <?php

    $file = $_GET['file']; // "../../etc/passwd\0"

    if (file_exists('/home/wwwrun/' . $file . '.php')) {
        // file_exists gibt true zurück, da /home/wwwrun/../../etc/passwd existiert
        include '/home/wwwrun/' . $file . '.php';

        // Die Datei /etc/passwd wird eingebunden
    }

    ?>

Daher sollte jede nicht vertrauenswürdige Zeichenkette, die in Dateisystemoperationen verwendet wird, ordentlich geprüft werden. Hier sehen Sie eine eine bessere Version des vorhergehenden Beispiels:

Beispiel #2 Korrekte Validierung der Eingabe

    <?php

    $file = $_GET['file'];

    // Liste zulässiger Werte (Whitelisting)
    switch ($file) {
        case 'main':
        case 'foo':
        case 'bar':
            include '/home/wwwrun/include/' . $file . '.php';
            break;
        default:
            include '/home/wwwrun/include/main.php';
    }

    ?>

# Datenbank-Sicherheit

## Inhaltsverzeichnis

- Datenbanken entwerfen
- Mit der Datenbank verbinden
- Verschlüsseltes Speichermodell
- SQL-Injection

Heutzutage sind Datenbanken die Hauptkomponenten jeder webbasierten Anwendung, aufgrund welcher Websites verschiedene dynamische Inhalte anbieten können. Nachdem sensible oder geheime Informationen in solch einer Datenbank gespeichert werden können, sollten Sie deren Schutz ernsthaft bedenken.

Um Informationen zu bekommen oder zu speichern, müssen Sie eine Verbindung zur Datenbank herstellen, eine legitime Abfrage senden, das Ergebnis holen, und die Verbindung schließen. Heutzutage ist die allgemein verwendete Abfragesprache für solche Interaktionen die Structured Query Language (SQL). Sehen Sie, wie sich ein Angreifer an einer SQL-Abfrage zu schaffen machen kann.

Sie werden merken, dass PHP Ihre Datenbank nicht selbst schützen kann. Die folgenden Abschnitte sind eine Einführung in die Grundlagen, wie man innerhalb von PHP-Skripten auf Datenbanken zugreift und diese manipuliert.

Behalten Sie diese einfache Regel im Hinterkopf: tief gestaffelte Verteidigung. Je mehr Platz Sie den Maßnahmen zum Schutz Ihrer Datenbank geben, desto geringer ist die Wahrscheinlichkeit, dass ein Angreifer Erfolg hat und gespeicherte Geheiminformationen aufdeckt oder missbraucht. Ein gutes Design des Datenbankschemas und die Anwendung wird mit Ihren größten Befürchtungen fertig.

## Datenbanken entwerfen

Der erste Schritt ist immer das Erstellen der Datenbank, außer Sie wollen eine bereits existierende von Dritten verwenden. Ist eine Datenbank erstellt, ist sie einem Eigentümer zugewiesen, welcher das Kommando zum Erstellen ausgeführt hat. Gewöhnlich kann nur der Eigentümer (oder ein Superuser) alles mit den Objekten in dieser Datenbank machen, und um anderen Benutzern die Verwendung zu erlauben, müssen Rechte vergeben werden.

Anwendungen sollten sich mit der Datenbank nie als deren Eigentümer oder als ein Superuser verbinden, da diese Benutzer jede beliebige Abfrage ausführen können, um z. B. das Schema zu modifizieren (z. B. Tabellen löschen) oder den gesamten Inhalt löschen.

Sie können verschiedene Datenbanknutzer für jeden Aspekt Ihrer Anwendung mit sehr limitierten Rechten auf Datenbankobjekte anlegen. Nur die wirklich benötigten Rechte sollten gewährt werden, und vermeiden Sie, dass der gleiche Benutzer in verschiedenen Anwendungsfällen mit der Datenbank interagieren kann. Das heißt, dass Eindringlinge, welche unter Verwendung einer dieser Referenzen Zugriff auf Ihre Datenbank erlangt haben, nur so viele Änderungen durchführen können, wie es Ihre Anwendung kann.

## Mit der Datenbank verbinden

Sie sollten die Verbindungen über SSL herstellen, um die Client/Server-Kommunikation für eine erhöhte Sicherheit zu verschlüsseln, oder aber auch SSH verwenden, um die Netzwerkverbindung zwischen den Clients und dem Datenbankserver zu verschlüsseln. Wird eines davon verwendet, dann wird es für einen Angreifer schwierig, Ihre Datenübertragung zu überwachen und Informationen über Ihre Datenbank zu erlangen.

## Verschlüsseltes Speichermodell

SSL/SSH schützt zwar Daten, die vom Client zum Server übertragen werden, aber SSL/SSH schützt keine dauernd in einer Datenbank gespeicherten Daten. SSL ist ein "auf-der-Leitung"-Protokoll.

Hat ein Angreifer direkten Zugriff auf Ihre Datenbank (unter Umgehung des Webservers), können gespeicherte sensible Daten aufgedeckt oder zweckentfremdet werden, außer wenn die Informationen durch die Datenbank selbst geschützt sind. Die Daten zu verschlüsseln ist eine gute Methode, diese Gefahr zu mildern, doch bieten nur wenige Datenbanken diese Art der Datenverschlüsselung an.

Der einfachste Weg, dieses Problem zu umgehen ist, erst einmal Ihr eigenes Verschlüsselungspaket zu erstellen, und dieses dann in Ihren PHP-Skripten zu nutzen. PHP kann Ihnen in diesem Fall mit seinen verschiedenen Erweiterungen helfen, wie z. B. OpenSSL und Sodium, welche eine große Auswahl an Verschlüsselungsalgorithmen abdecken. Das Skript verschlüsselt die Daten vor dem Speichern und entschlüsselt diese wieder beim Erhalt. Siehe die Verweise für weitere Beispiele, wie Verschlüsselung funktioniert.

### Hashing

Im Fall von wirklich versteckten Daten, wenn deren unverschlüsselte Darstellung nicht nötig ist (d. h. die nicht angezeigt werden sollen), ist Hashing ebenfalls überlegenswert. Das bekannte Beispiel für Hashing ist das Speichern des kryptographischen Hashes eines Passwortes in einer Datenbank, anstatt des Passworts selbst.

Die Passwort-Funktionen bieten eine bequeme Möglichkeit, sensible Daten zu hashen und mit diesen Hashes zu arbeiten.

password_hash() wird verwendet, um eine gegebene Zeichenkette unter Verwendung des stärksten zurzeit verfügbaren Algorithmus zu hashen, und password_verify() prüft, ob ein gegebenes Passwort mit dem Hash, der in der Datenbank gespeichert ist, übereinstimmt.

Beispiel #1 Hashen eines Passwortfeldes

    <?php

    // Speichern des Passwort-Hashes
    $query  = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
                pg_escape_string($username),
                password_hash($password, PASSWORD_DEFAULT));
    $result = pg_query($connection, $query);

    // Abfragen, ob der User das richtige Passwort übermittelt hat
    $query = sprintf("SELECT pwd FROM users WHERE name='%s';",
                pg_escape_string($username));
    $row = pg_fetch_assoc(pg_query($connection, $query));

    if ($row && password_verify($password, $row['pwd'])) {
        echo 'Willkommen, ' . htmlspecialchars($username) . '!';
    } else {
        echo 'Authentifizierung für ' . htmlspecialchars($username) . 'fehlgeschlagen.';
    }

    ?>

## SQL-Injection

SQL-Injection ist eine Technik, bei der ein Angreifer Schwachstellen im Anwendungscode ausnutzt, mit dem dynamische SQL-Abfragen erstellt werden. Ein Angreifer kann sich Zugang zu besonders geschützten Bereichen der Anwendung verschaffen, sämtliche Informationen aus der Datenbank abrufen, vorhandene Daten manipulieren oder sogar gefährliche Befehle auf der Systemebene des Datenbank-Hosts ausführen. Die Schwachstelle entsteht, wenn Entwickler in ihren SQL-Anweisungen beliebige Eingaben miteinander verknüpfen oder einfügen.

Beispiel #1 Die Ergebnisliste in mehrere Seiten aufsplitten ... und Superuser anlegen (PostgreSQL)

Im folgenden Beispiel wird die Benutzereingabe direkt in die SQL-Abfrage eingefügt, wodurch der Angreifer ein Superuser-Konto für die Datenbank erlangen kann.

    <?php

    $offset = $_GET['offset']; // Vorsicht, keine Validierung der Eingabe!
    $query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
    $result = pg_query($conn, $query);

    ?>

Normale Benutzer klicken auf die 'nächste'- bzw. 'vorige'-Links, wo der $offset in der URL enthalten ist. Das Skript erwartet, dass der ankommende $offset eine Zahl enthält. Was aber, wenn jemand versucht einzubrechen, indem er das Folgende an die URL anhängt:

    0;
    insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
        select 'crack', usesysid, 't','t','crack'
        from pg_shadow where usename='postgres';
    --

In diesem Fall würde das Skript dem Angreifer einen Superuser-Zugang zur Verfügung stellen. Beachten Sie, dass `0;` einen gültigen Offset zur ursprünglichen Abfrage liefert, und sie beendet.

> Hinweis:

> Es ist eine übliche Technik, den SQL-Parser mit dem SQL-Kommentarzeichen `--` zu zwingen, den Rest der vom Entwickler geschriebenen Abfrage zu ignorieren.

Eine gangbare Methode, an Passwörter zu gelangen, ist, Ihre Seiten mit den Suchergebnissen zu umgehen. Der Angreifer braucht nur zu probieren, ob irgendeine übertragene Variable, die in dem SQL-Statement verwendet wird, nicht richtig gehandhabt wird. Diese Filter können gewöhnlich in einem vorausgehenden Formular gesetzt werden, indem `WHERE-, ORDER BY-, LIMIT-` und `OFFSET`-Klauseln in `SELECT`-Statements angepasst werden. Wenn Ihre Datenbank das `UNION`-Konstrukt unterstützt, kann der Angreifer versuchen, eine komplette Abfrage an das Original anzuhängen, um Passwörter aus einer beliebigen Tabelle aufzulisten. Es wird dringend empfohlen, nur sichere Hashes von Passwörtern zu speichern und nicht die Passwörter selbst.

Beispiel #2 Artikel auflisten ... und ein paar Passwörter (beliebiger Datenbankserver)

    <?php

    $query  = "SELECT id, name, inserted, size FROM products
               WHERE size = '$size'";
    $result = odbc_exec($conn, $query);

    ?>

Der statische Teil der Abfrage kann mit einem anderen `SELECT`-Statement kombiniert werden, welches alle Passwörter preisgibt

    '
    union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
    --

Auch `UPDATE`- und `INSERT`-Anweisungen sind für derartige Angriffe anfällig.

Beispiel #3 Vom Zurücksetzen eines Passworts ... zum Erlangen von mehr Rechten (beliebiger Datenbankserver)

    <?php
    $query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
    ?>

Wenn ein böswilliger Benutzer den Wert `' or uid like'%admin%` an $uid übermittelt, um das Administrator-Passwort zu ändern, oder einfach $pwd auf `hehehe', trusted=100, admin='yes` setzt, um mehr Rechte zu erhalten, dann wird die Abfrage verdreht:

    <?php

    // $uid: ' or uid like '%admin%
    $query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%';";

    // $pwd: hehehe', trusted=100, admin='yes
    $query = "UPDATE usertable SET pwd='hehehe', trusted=100, admin='yes' WHERE
    ...;";

    ?>

Obwohl es offensichtlich ist, dass ein Angreifer zumindest ein wenig Kenntnis der genutzten Datenbankarchitektur besitzen muss, um einen erfolgreichen Angriff durchzuführen, ist es oft sehr einfach, diese Informationen zu erhalten. Der Code kann z. B. Teil einer Open-Source-Software sein und öffentlich zugänglich sein. Diese Informationen können auch durch Closed-Source-Code preisgegeben werden - selbst wenn dieser kodiert, verschleiert oder kompiliert ist - und sogar durch Ihren eigenen Code durch die Anzeige von Fehlermeldungen. Andere Methoden beinhalten die Nutzung typischer Tabellen- und Spaltennamen. Ein Login-Formular etwa, dass eine Tabelle 'users' mit den Spaltennamen 'id', 'username' und 'password' nutzt.

Beispiel #4 Angriff auf das Betriebssystem des Datenbank-Hosts (MSSQL-Server)

Ein erschreckendes Beispiel, wie der Zugriff auf Befehle auf Betriebssystemebene bei manchen Datenbankservern erfolgen kann:

    <?php

    $query  = "SELECT * FROM products WHERE id LIKE '%$prod%'";
    $result = mssql_query($query);

    ?>

Wenn ein Angreifer den Wert `a%' exec master..xp_cmdshell 'net user test testpass /ADD' --` auf $prod überträgt, wird $query zu:

    <?php

    $query  = "SELECT * FROM products
               WHERE id LIKE '%a%'
               exec master..xp_cmdshell 'net user test testpass /ADD' --%'";
    $result = mssql_query($query);

    ?>

Der MSSQL-Server führt die SQL-Statements im Batch aus, inklusive eines Kommandos um einen neuen Benutzer zur Datenbank der lokalen Konten hinzuzufügen. Würde diese Anwendung als `sa` und der MSSQLSERVER-Service mit genügend Rechten laufen, hätte der Angreifer nun ein Konto, mit welchem er Zugriff auf diese Maschine hätte.

> Hinweis:

> Manche der obigen Beispiele sind an einen spezifischen Datenbankserver gebunden, aber das bedeutet nicht, dass ein ähnlicher Angriff auf andere Produkte unmöglich wäre. Ihr Datenbankserver könnte auf andere Weise genauso verwundbar sein.

Bild mit freundlicher Genehmigung von » xkcd

### Techniken zur Vermeidung

Um das Risiko einer SQL-Injection zu verringern, wird empfohlen, alle Daten über vorbereitete Anweisungen zu binden. Die Verwendung von parametrisierten Abfragen ist zwar nicht ausreichend, um SQL-Injections vollständig zu verhindern, aber es ist der einfachste und sicherste Weg, um Daten für SQL-Anweisungen bereitzustellen. Alle dynamischen Datenliterale in `WHERE`-, `SET`- und `VALUES`-Klauseln müssen durch Platzhalter ersetzt werden. Die eigentlichen Daten werden bei der Ausführung gebunden und getrennt vom SQL-Befehl gesendet.

Die Parameterbindung kann nur für Daten verwendet werden. Andere dynamische Teile der SQL-Abfrage müssen gegen eine bekannte Liste zulässiger Werte gefiltert werden.

Beispiel #5 Ein sicherer Weg, eine Abfrage zu erstellen

    <?php

    // Der dynamische SQL-Teil wird anhand der erwarteten Werte validiert
    $sortingOrder = $_GET['sortingOrder'] === 'DESC' ? 'DESC' : 'ASC';
    $productId = $_GET['productId'];
    // Das SQL wird mit einem Platzhalter vorbereitet
    $stmt = $pdo->prepare("SELECT * FROM products WHERE id LIKE ? ORDER BY price {$sortingOrder}");
    // Der Wert wird mit LIKE-Wildcards versehen
    $stmt->execute(["%{$productId}%"]);

    ?>

Vorbereitete Anweisungen werden von PDO, MySQLi und anderen Bibliotheken angeboten.

Angriffe durch SQL-Injection basieren hauptsächlich darauf, Code auszunutzen, der nicht unter dem Aspekt der Sicherheit geschrieben wurde. Vertrauen Sie niemals einer Eingabe, insbesondere nicht von der Clientseite, selbst wenn sie von einer Auswahlbox, einem versteckten Eingabefeld oder einem Cookie kommt. Das erste Beispiel zeigt, dass eine so einfache Abfrage zu einer Katastrophe führen kann.

Eine umfassende Verteidigungsstrategie umfasst mehrere bewährte Programmierpraktiken:

- Stellen Sie nie als Superuser oder Eigentümer einer Datenbank eine Verbindung zur Datenbank her. Verwenden Sie immer speziell angelegte Benutzer mit sehr limitierten Rechten.
- Prüfen Sie, ob die gegebene Eingabe dem erwarteten Datentyp entspricht. PHP bietet eine große Auswahl an Funktionen zum Validieren der Eingaben, von den einfachsten unter Variablenfunktionen und Character-Type-Funktionen (z. B. is_numeric(), bzw. ctype_digit()), bis hin zu den Perl-kompatiblen regulären Ausdrücken.
- Wenn die Anwendung eine numerische Eingabe erwartet, sollten Sie die Daten mittels ctype_digit() überprüfen, den Typ stillschweigend mittels settype() ändern oder deren numerische Darstellung mittels sprintf() verwenden.
- Unterstützt die Datenbank-Ebene das Binden von Variablen nicht, so maskieren Sie jede nichtnumerische Benutzereingabe, welche zur Datenbank weitergereicht werden soll, mit der jeweiligen datenbankspezifischen Maskierungsfunktion für Zeichenketten (z. B. mysql_real_escape_string(), sqlite_escape_string() usw.). Generische Funktionen wie addslashes() sind nur in einer sehr spezifischen Umgebung nützlich (z. B. MySQL mit einem SingleByte-Zeichensatz bei deaktiviertem NO_BACKSLASH_ESCAPES), sodass es besser ist, diese zu vermeiden.
- Geben Sie um keinen Preis irgendwelche datenbankspezifischen Informationen aus, speziell über das Schema. Siehe auch Fehlerbehandlung und Fehlerbehandlungsfunktionen.

Abgesehen davon profitieren Sie von einer Protokollierung der Abfragen entweder in Ihrem Skript oder durch die Datenbank selbst, falls sie Protokollierung unterstützt. Klar, die Protokollierung kann keinen schädlichen Versuch verhindern, aber sie kann helfen herauszufinden, welche Anwendung umgangen wurde. Das Protokoll ist nicht von sich aus nützlich, aber durch die in ihm enthaltenen Informationen, und je mehr Details es enthält, desto besser ist es im Allgemeinen.

# Fehlerbehandlung

PHP Security hat zwei Seiten der Fehlerbehandlung. Eine ist für die Erhöhung der Sicherheit vorteilhaft, die andere ist schädlich.

Eine Standard-Angriffstaktik beinhaltet die Erstellung eines Profils des anzugreifenden Systems, indem die aufgrund der Einspeisung von unzulässigen Daten zurückgegebenen Fehlermeldungen anhand deren Art und des Kontextes ausgewertet werden. Dies erlaubt es einem Angreifer, nach Informationen über den Server zu suchen, um seine potentielle Verwundbarkeit herauszufinden. Wenn z.B. ein Angreifer Informationen über eine auf einem eingesendeten Formular basierte Seite zusammengetragen hat, kann er versuchen, Variablen zu überschreiben bzw. zu modifizieren:

Beispiel #1 Variablen mit einer eigenen HTML-Seite angreifen

    <form method="post" action="attacktarget?username=badfoo&password=badfoo">
    <input type="hidden" name="username" value="badfoo">
    <input type="hidden" name="password" value="badfoo">
    </form>

Die normalerweise zurückgegebenen PHP-Fehler können für den Entwickler hilfreich sein, wenn dieser ein Skript debuggen möchte, da sie z.B. Hinweise auf eine nicht vorhandene Funktion oder Datei, die PHP-Datei und die Zeilennummer des auftretenden Fehlers ausgeben. Dies alles sind Informationen, die ausgenutzt werden können. Es ist für einen PHP-Entwickler nicht unüblich, show_source(), highlight_string() oder highlight_file() zur Fehlersuche zu verwenden, jedoch kann dies in einem produktiven System auch versteckte Variablen, ungeprüfte Syntax und andere gefährliche Informationen aufdecken. Besonders gefährlich ist es, Code aus bekannten Quellen mit integrierten Debugging-Handlern auszuführen, oder weit verbreitete Debuggingtechniken zu verwenden. Wenn ein Angreifer die von Ihnen benutzte generelle Technik herausfindet, kann er versuchen, Ihre Seite mittels Bruteforce zu knacken, indem er verschiedene allgemein gebräuchliche Debugstrings sendet:

Beispiel #2 Ausnutzen von gebräuchlichen Debugging-Variablen

    <form method="post" action="attacktarget?errors=Y&amp;showerrors=1&amp;debug=1">
    <input type="hidden" name="errors" value="Y" />
    <input type="hidden" name="showerrors" value="1" />
    <input type="hidden" name="debug" value="1" />
    </form>

Ungeachtet der Fehlerbehandlungsmethode führt die Möglichkeit, ein System nach Fehlermeldungen zu sondieren, dazu, dass einem Angreifer mehr Informationen geboten werden.

Zum Beispiel weist schon alleine der Stil einer Standardfehlermeldung darauf hin, dass auf einem System PHP läuft. Wenn der Angreifer auf eine `.html` Seite kommt und untersuchen möchte, welches System im Hintergrund läuft (um nach bekannten Systemschwächen Ausschau zu halten), könnte dieser mittels der Einspeisung von falschen Daten herausfinden, dass ein System mit PHP aufgebaut ist.

Ein Fehler einer Funktion gibt Aufschluss darüber, ob ein System eine bestimmte Datenbankapplikation benutzt, oder gibt Hinweise darauf, wie eine Webseite programmiert bzw. entworfen wurde. Dies erlaubt eine tiefere Überprüfung von offenen Datenbankports oder die Suche nach spezifischen Bugs bzw. Schwächen einer Webseite. Mit der Einspeisung von falschen Daten kann ein Angreifer z.B. die Reihenfolge der Authentifizierung in einem Skript bestimmen (anhand der Zeilennummern in den Fehlermeldungen). Ebenso lassen sich auch durch "Herumstochern" Missbrauchsmöglichkeiten an verschiedenen Stellen im Skript herausfinden.

Eine Fehlermeldung des Dateisystems oder eines generellen PHP-Errors kann darüber Auskunft geben, welche Rechte der Webserver hat, ebenso darüber, wie die Dateien auf dem Webserver strukturiert und organisiert sind. Vom Entwickler geschriebene Fehlermeldungen können das Problem verschlimmern, bis hin zum Preisgeben von zuvor "versteckten" Informationen.

Es gibt drei bedeutende Lösungen zu diesem Thema. Die erste ist, alle Funktionen zu überprüfen und zu versuchen, einen Großteil der Fehlermeldungen zu ersetzen. Die zweite ist, die Ausgabe von Fehlermeldungen bei produktivem Code generell zu deaktivieren. Die dritte ist, sich unter Verwendung der PHP-Funktionen zur Fehlerbehandlung einen eigenen Errorhandler zu schreiben. Abhängig von Ihrer Sicherheitspolitik könnte jede der drei Lösungen für Sie geeignet sein.

Ein Weg, diesen Punkt zügig abzuarbeiten, ist, das PHP-eigene error_reporting() zu benutzen, um Ihren Code sicherer zu gestalten und möglicherweise gefährliche Nutzungen von Variablen zu entdecken. Wenn Sie Ihren Code noch vor dem Einsatz mit `E_ALL` testen, können Sie schnell Bereiche entdecken, in denen Ihre Variablen eventuell für Verseuchung oder andere Modifikationen offen sind. Ist Ihr Code einsatzbereit, können Sie entweder das Errorreporting komplett ausschalten, indem Sie error_reporting() auf 0 setzen, oder Sie schalten die Fehleranzeige mittels der php.ini-Option `display_errors` aus, um Ihren Code vor dem Ausspähen zu schützen. Wenn Sie letztere Möglichkeit wählen, sollten Sie mittels der Ini-Direktive `error_log` einen Pfad definieren, in dem sich das Logfile befindet, und `log_errors` anschalten.

Beispiel #3 Gefährliche Variablen mit E_ALL finden

    <?php
    if ($username) {  // Vor Verwendung nicht initialisiert oder geprüft
        $good_login = 1;
    }
    if ($good_login == 1) { // Wenn der obige Test fehlschlägt, ist vor der
                            // Verwendung nicht initialisiert oder geprüft
        readfile ("/highly/sensitive/data/index.html");
    }
    ?>

# Vom Nutzer übermittelte Daten

In vielen PHP Programmen liegt die größte Schwäche nicht an der Sprache selbst, sondern bloß an Code, der nicht mit dem nötigen Augenmerk auf die Sicherheit geschrieben wurde. Deshalb sollten Sie sich immer Zeit nehmen, die Implikationen eines gegebenen Codestücks zu bedenken, um einen möglichen Schaden durch eine eventuell unerwartete übergebene Variable festzustellen.

Beispiel #1 Gefährliche Verwendung von Variablen

    <?php
    // lösche eine Datei aus dem Benutzer-Verzeichnis...
    // oder vielleicht dem eines anderen Benutzers?
    unlink ($evil_var);

    // Schreibe die Log-Information von deren Zugriff...
    // oder vielleicht einen /etc/passwd Eintrag?
    fputs ($fp, $evil_var);

    // Führe etwas triviales aus... oder rm -rf *?
    system ($evil_var);
    exec ($evil_var);

    ?>

Sie sollten Ihren Code immer sorgfältig kontrollieren, um eine sorgfältige Prüfung irgendwelcher von einem Web-Browser übertragenen Variablen sicherzustellen, und sich selbst folgende Fragen stellen:

- Wird sich dieses Skript nur auf die vorgesehenen Dateien auswirken?
- Kann auf ungewöhnliche oder unerwünschte Daten reagiert werden?
- Kann dieses Skript auf nicht vorgesehene Art genutzt werden?
- Kann dies in Verbindung mit anderen Skripten in einer negativen Art benutzt werden?
- Werden alle Transaktionen ausreichend geloggt?

Wenn Sie sich diese Fragen anstatt danach schon während des Schreibens des Skriptes stellen, ersparen Sie sich das unangenehme Umschreiben, wenn eine Erhöhung der Sicherheit erforderlich wird. Mit dieser Art zu denken werden Sie die Sicherheit des Systems zwar nicht garantieren, aber sie können helfen, sie zu erhöhen.

Verbessern Sie die Sicherheit, indem Sie Komfort-Einstellungen deaktivieren, die die Herkunft, die Gültigkeit oder die Integrität von Eingabedaten verschleiern. Die implizite Erstellung von Variablen und ungeprüfte Eingaben können zu Sicherheitslücken wie Injection-Attacken und Datenmanipulation führen.

Funktionalitäten wie `register_globals` und `magic_quotes` (beide in PHP 5.4.0 entfernt) trugen früher zu diesen Risiken bei, indem sie automatisch Variablen aus Benutzereingaben erzeugten und Daten inkonsistent maskierten. Obwohl sie nicht mehr in PHP enthalten sind, bleiben ähnliche Risiken bestehen, wenn die Verarbeitung von Eingaben nicht richtig gehandhabt wird.

Aktivieren Sie error_reporting(E_ALL), um nicht initialisierte Variablen zu erkennen und Eingaben zu validieren. Verwenden Sie strikte Typen (declare(strict_types=1), eingeführt in PHP 7), um Typsicherheit zu erzwingen, unbeabsichtigte Typumwandlungen zu verhindern und die allgemeine Sicherheit zu verbessern.

# PHP verstecken

Generell ist Sicherheit durch Unklarheit eine der schwächsten Formen von Sicherheit. Aber in manchen Fällen ist ein klein wenig mehr an zusätzlicher Sicherheit wünschenswert.

Ein paar einfache Techniken helfen, PHP zu verstecken, um nach Schwächen in Ihrem System suchende Angreifer unter Umständen langsamer zu machen. Wenn Sie in Ihrer php.ini expose_php auf `off` setzen, reduzieren Sie damit die zur Verfügung stehenden Informationen.

Eine andere Taktik ist, den Webserver wie z.B. Apache entweder mittels einer .htaccess-Direktive oder in der Apache-Konfigurationsdatei selbst so einzustellen, dass dieser verschiedene Dateitypen durch PHP parst. So können Sie irreführende Dateierweiterungen verwenden:

Beispiel #1 PHP als andere Sprache ausgeben

    # Lasse PHP-Code wie andere Arten von Code aussehen
    AddType application/x-httpd-php .asp .py .pl

Oder komplett unklar machen:

Beispiel #2 Verwenden von unbekannten Typen für PHP-Dateierweiterungen

    # Lasse PHP Code wie unbekannte Typen aussehen
    AddType application/x-httpd-php .bop .foo .133t

Oder verstecken Sie ihn als HTML-Code, was einen leichten Performanceverlust bedeutet, da so alle HTML-Dateien durch die PHP-Engine geparst werden:

Beispiel #3 Verwenden von HTML-Typen für PHP-Dateierweiterungen

    # Lasse PHP-Code wie HTML aussehen
    AddType application/x-httpd-php .htm .html

Um dies effektiv arbeiten zu lassen, müssen Sie Ihre PHP-Dateien nach den obigen Dateierweiterungen umbenennen. Obwohl dies eine Form der Sicherheit durch Verhüllung ist, ist es eine geringfügige präventive Maßnahme mit nur wenigen Nachteilen.

# Aktuell bleiben

PHP wird, wie jedes andere große System auch, ständig geprüft und weiterentwickelt. Neue Versionen enthalten in der Regel sowohl kleinere als auch größere Änderungen, um die Sicherheit zu erhöhen und sowohl Fehler als auch Konfigurationspannen und andere Probleme auszugleichen, die die Gesamtsicherheit und -stabilität Ihres Systems beeinflussen können.

Wie auch bei anderen Scriptsprachen und Programmen auf Systemebene, ist der beste Ansatz ein regelmäßiges Updaten, und sich laufend über die letzten Versionen und deren Änderungen zu informieren.

- Einführung
- Allgemeine Überlegungen
- Installiert als CGI-Version
  - Mögliche Angriffe
  - Fall 1: Nur öffentliche Dateien vorhanden
  - Fall 2: --enable-force-cgi-redirect benutzen
  - Fall 3: doc_root oder user_dir festlegen
  - Fall 4: PHP-Parser außerhalb des Webverzeichnisbaums
- Verwendung als Apache-Modul
- Session Sicherheit
- Sicherheit des Dateisystems
  - Probleme im Zusammenhang mit Nullbytes
- Datenbank-Sicherheit
  - Datenbanken entwerfen
  - Mit der Datenbank verbinden
  - Verschlüsseltes Speichermodell
  - SQL-Injection
- Fehlerbehandlung
- Vom Nutzer übermittelte Daten
- PHP verstecken
- Aktuell bleiben

# Features

# HTTP-Authentifizierung mit PHP

Man kann die Funktion header() verwenden, um die Nachricht `"Authentifizierung erforderlich"` an den Client-Browser zu senden, damit dieser ein Fenster zur Eingabe von Benutzername/Passwort öffnet. Hat der Benutzer diese eingegeben, wird die URL des PHP-Skripts mit den vordefinierten Variablen PHP_AUTH_USER, PHP_AUTH_PW und AUTH_TYPE, die den Benutzernamen, das Passwort und den Typ der Authentifizierung enthalten, erneut aufgerufen. Diese vordefinierten Variablen befinden sich im Array $_SERVER. Es wird nur die Authentifizierungsmethode "Basic" unterstützt. Näheres hierzu bei der Funktion header().

Ein Auszug aus einem Skript, das die Clientauthentifizierung auf einer Seite erzwingt, würde so aussehen:

Beispiel #1 Beispiel: Basic-HTTP-Authentifizierung

    <?php
    if (!isset($_SERVER['PHP_AUTH_USER'])) {
        header('WWW-Authenticate: Basic realm="My Realm"');
        header('HTTP/1.0 401 Unauthorized');
        echo 'Text, der gesendet wird, falls der Benutzer auf Abbrechen drückt';
        exit;
    } else {
        echo "<p>Hallo {$_SERVER['PHP_AUTH_USER']}.</p>";
        echo "<p>Sie gaben {$_SERVER['PHP_AUTH_PW']} als Passwort ein.</p>";
    }
    ?>

> Hinweis: Hinweis zur Kompatibilität

> Achten Sie für die maximale Kompatibilität mit allen Clients bei den Header-Zeilen auf die richtige Schreibweise! Das Schlüsselwort "Basic" sollte genau so geschrieben werden, der Realm-String muss in doppelte (nicht einfache) Anführungszeichen gesetzt werden und in der HTTP/1.0 401-Zeile darf nur genau ein Leerzeichen vor dem 401-Code stehen. Die Authentifizierungsparameter müssen durch Kommata getrennt werden.

Anstatt PHP_AUTH_USER und PHP_AUTH_PW wie im Beispiel oben einfach nur auszugeben, werden Sie den Benutzernamen und das Passwort auf Gültigkeit überprüfen wollen. Dies kann durch das Abfragen einer Datenbank oder die Suche des Benutzers in einer Textdatei geschehen.

Vorsicht bei einigen Internet Explorer-Versionen - sie scheinen sehr wählerisch zu sein, was die Reihenfolge der Header angeht. Abhilfe schafft hier das Senden des WWW-Authenticate-Headers vor dem `HTTP/1.0 401`-Header.

> Hinweis: Konfigurationshinweis

> PHP prüft das Vorhandensein einer `AuthType` Apache-Direktive, um zu entscheiden, ob eine externe Authentifizierung aktiv ist.

Zu beachten ist, dass Obenstehendes keinesfalls jemanden, der auf demselben Server die Kontrolle über eine nicht authentifizierte URL hat, davon abhalten kann, Passwörter von authentifizierten URLs auszulesen.

Sowohl Netscape als auch der Internet Explorer löschen den lokalen Authentifizierungscache des Browserfensters, wenn der Server eine 401-Meldung zurückgibt. Dies kann verwendet werden, um einen Benutzer "auszuloggen" und eine erneute Eingabe des Benutzernamens/Passworts zu erzwingen. Manchmal wird dieses Verhalten für das automatische Ausloggen nach Ablauf einer bestimmten Zeitspanne oder für einen Logout-Button genutzt.

Beispiel #2 HTTP-Authentifizierung, mit erneuter Anforderung von Name/Passwort

    <?php
    function authentifizieren() {
        header('WWW-Authenticate: Basic realm="Test Authentication System"');
        header('HTTP/1.0 401 Unauthorized');
        echo "Bitte geben Sie eine gültige Login-ID und das Passwort für den
            Zugang ein\n";
        exit;
    }

    if (!isset($_SERVER['PHP_AUTH_USER']) ||
        ($_POST['Gesehen'] == 1 && $_POST['AlteAuth'] == $_SERVER['PHP_AUTH_USER'])) {
        authentifizieren();
    } else {
        echo "<p>Willkommen: " . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "<br />";
        echo "Alt: " . htmlspecialchars($_REQUEST['AlteAuth']);
        echo "<form action='' method='post'>\n";
        echo "<input type='hidden' name='Gesehen' value='1' />\n";
        echo "<input type='hidden' name='AlteAuth' value=\"" . htmlspecialchars($_SERVER['PHP_AUTH_USER']) . "\" />\n";
        echo "<input type='submit' value='Erneut Anmelden' />\n";
        echo "</form></p>\n";
    }
    ?>

Dieses Verhalten wird vom Authentifizierungsstandard `HTTP Basic` nicht gefordert, daher sollte man sich nie darauf verlassen. Tests mit `Lynx` haben gezeigt, dass `Lynx` die Authentifizierungsinformationen bei Erhalt einer 401-Meldung nicht löscht. Solange der benötigte Berechtigungsnachweis nicht geändert wird, kann der Benutzer auf die vorhergehende Seite zurück und danach vorwärts und die angeforderte Adresse wieder öffnen. Der Benutzer kann die Authentifizierungsinformationen aber durch Drücken von `'_'` löschen.

Damit die HTTP-Authentifizierung funktioniert, wenn der IIS mit der CGI-Version von PHP verwendet wird, müssen Sie die "`Directory Security`" Ihrer IIS-Konfiguration ändern. Klicken Sie auf "`Edit`" und aktivieren Sie nur "`Anonymous Access`". Alle anderen Felder sollten deaktiviert bleiben.

> Hinweis: IIS-Anmerkung:
> Damit die HTTP-Authentifizierung mit dem IIS funktioniert, muss die PHP-Konfigurationsanweisung cgi.rfc2616_headers auf `0` (die Voreinstellung) gesetzt sein.

# Cookies

PHP unterstützt HTTP-Cookies. Hierbei handelt es sich um einen Mechanismus, um Informationen beim Client zu speichern und somit wiederkehrende Besucher zu identifizieren oder ihren Weg innerhalb des Angebotes nachzuvollziehen. Cookies können durch die Funktionen setcookie() und setrawcookie() gesetzt werden. Sie sind Bestandteil des HTTP-Headers, was bedeutet, dass die Funktion setcookie() aufgerufen werden muss, bevor irgendeine Ausgabe an den Browser erfolgt. Dies ist die gleiche Einschränkung, der auch die Funktion header() unterliegt. Sie können die Funktionen zur Ausgabesteuerung verwenden, um die Ausgaben des Skriptes zu verzögern, bis entschieden ist, ob Cookies gesetzt bzw. Header gesendet werden sollen oder nicht.

Vom Client gesendete Cookies werden automatisch im auto-globalen Array $_COOKIE abgelegt, wenn die variables_order-Konfigurationsvariable den Kennbuchstaben "C" enthält. Sollen einem Cookie mehrere Werte zugewiesen werden, so muss dem Cookienamen lediglich `[]` angefügt werden.

Weitere Informationen sowie Anmerkungen zu Browser-Bugs finden Sie in den Abschnitten setcookie() und setrawcookie().

# Sessions

Sessionunterstützung in PHP besteht aus einer Möglichkeit, bestimmte Daten für nachfolgende Zugriffe aufzubewahren. Dies erlaubt es Ihnen, stärker angepasste Anwendungen zu entwickeln und den Reiz Ihrer Webseite zu erhöhen. Alle Informationen finden sich im Abschnitt mit der Session Referenz.

# Steuerung von Dateiuploads

## Inhaltsverzeichnis

- Dateiuploads mit POST
- Fehlermeldungen erklärt
- Häufige Probleme
- Upload mehrerer Dateien
- PUT-Unterstützung
- Siehe auch

## Dateiuploads mit POST

Dieses Feature erlaubt es Benutzern sowohl Text- als auch Binärdaten hochzuladen. Mit PHP's Authentifizierungs- und Dateifunktionen besteht volle Kontrolle darüber, wer Dateien hochladen darf und was mit den Dateien geschehen soll, wenn das Hochladen beendet ist.

PHP kann Dateiuploads von jedem RFC-1867-konformen Browser empfangen.

> Hinweis: Diesbezügliche Konfigurationshinweise

> Siehe auch die Anweisungen file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size und max_input_time in der php.ini

PHP unterstützt auch das Hochladen von Dateien nach der PUT-Methode, die beispielsweise vom Netscape Composer und den W3C-Amaya-Clients verwendet wird. Siehe dazu PUT-Unterstützung für nähere Informationen.

Beispiel #1 Formular zum Hochladen von Dateien

Um Dateieuploads zu ermöglichen muss ein Formular erstellt werden, welches ungefähr wie folgt aussieht:

    <!-- Der Kodierungstyp enctype MUSS wie dargestellt angegeben werden -->
    <form enctype="multipart/form-data" action="__URL__" method="POST">
        <!-- MAX_FILE_SIZE muss vor dem Datei-Eingabefeld stehen -->
        <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
        <!-- Der Name des Eingabefelds bestimmt den Namen im $_FILES-Array -->
        Diese Datei hochladen: <input name="userfile" type="file" />
        <input type="submit" value="Send File" />
    </form>

`__URL__` im obigen Beispiel sollte durch die URL eines PHP-Skripts ersetzt werden.

Das "hidden"-Feld `MAX_FILE_SIZE` muss dem "file"-Eingabefeld vorangestellt werden; der angegebene Wert bestimmt die maximale akzeptierte Dateigröße in Bytes. Dieses Formular-Element sollte immer benutzt werden, da es dem Benutzer erspart auf einen großen Dateiupload zu warten, nur um festzustellen, dass die Datei zu groß war und der Upload fehlgeschlagen ist. Es sollte jedoch beachtet werden, dass diese Browserseitige Einstellung sehr einfach zu umgehen ist und man sich daher niemals darauf verlassen sollte, dass sie übergroße Dateiuploads verhindert. Die Server-seitige Option für die Maximalgröße kann hingegen nicht umgangen werden.

> Hinweis:

> Das Uploadformular muss unbedingt das Attribut `enctype="multipart/form-data"` angeben, andernfalls wird der Upload nicht funktionieren.

Die globale Variable $_FILES enthält alle Informationen über hochgeladene Dateien. Im Folgenden sind ihre Inhalte für das obige Beispielformular aufgelistet. Beachten Sie, dass dies auf der Annahme basiert, dass der Name des Dateiuploads wie in dem obigen Beispielskript userfile ist. Es kann aber auch jeder andere Name verwendet werden.

$_FILES['userfile']['name']

  Der ursprüngliche Dateiname auf dem Computer des Benutzers.

$_FILES['userfile']['type']

  Der MIME-Type der Datei, falls der Browser diese Information zur Verfügung gestellt hat. Ein Beispiel wäre `"image/gif"`. Dieser MIME-Type wird jedoch nicht von PHP geprüft und kann somit falsch sein.

$_FILES['userfile']['size']

  Die Größe der hochgeladenen Datei in Bytes.

$_FILES['userfile']['tmp_name']

  Der temporäre Dateiname, unter dem die hochgeladene Datei auf dem Server gespeichert wurde.

$_FILES['userfile']['error']

  Der Fehlercode des Uploads.

$_FILES['userfile']['full_path']

  Der vollständige Pfad, wie er vom Browser übermittelt wurde. Dieser Wert enthält nicht immer eine echte Verzeichnisstruktur und ist daher nicht vertrauenswürdig. Verfügbar ab PHP 8.1.0.

Standardmäßig werden Dateien im standardmäßigen temporären Verzeichnis des Servers gespeichert, außer es wurde mittels upload_tmp_dir in der php.ini ein anderer Ort konfiguriert. Das Standardverzeichnis des Servers kann durch das Setzen der Umgebungsvariablen TMPDIR in der Umgebung, in der PHP ausgeführt wird, geändert werden. Das Setzen mittels der Funktion putenv() innerhalb eines Skriptes ist nicht möglich. Mittels dieser Umgebungsvariable kann auch sichergestellt werden, dass auch andere Operationen an hochgeladenen Dateien arbeiten können.

Beispiel #2 Dateiuploads prüfen

Weitere Informationen finden Sie auch in den Beschreibungen für is_uploaded_file() und move_uploaded_file(). Das folgende Beispiel verarbeitet einen von einem HTML-Formular kommenden Dateiupload.

    <?php
    $uploaddir = '/var/www/uploads/';
    $uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

    echo '<pre>';
    if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
        echo "Datei ist valide und wurde erfolgreich hochgeladen.\n";
    } else {
        echo "Möglicherweise eine Dateiupload-Attacke!\n";
    }

    echo 'Weitere Debugging Informationen:';
    print_r($_FILES);

    print "</pre>";

    ?>

Das die hochgeladene Datei empfangende Skript sollte die notwendige Logik zur Entscheidung enthalten, was mit der hochgeladenen Datei geschehen soll. Sie können zum Beispiel $_FILES['userfile']['size'] verwenden, um zu kleine bzw. zu große Dateien wegzuwerfen. Sie können $_FILES['userfile']['type'] nutzen, um Dateien eines unerwünschten Typs wegzuwerfen, sollten dabei jedoch beachten, dass dieser Wert vollständig vom Benutzer kontrolliert wird und somit falsch sein kann. Sie können Ihre Logik auch mittels $_FILES['userfile']['error'] anhand der Fehlercodes planen. Egal welche Logik Sie verwenden, Sie sollten die Datei im temporären Verzeichnis entweder löschen, oder an einen anderen Ort verschieben.

Wenn im Formular keine Datei ausgewählt wurde so wird $_FILES['userfile']['size'] von PHP auf 0 gesetzt und $_FILES['userfile']['tmp_name'] ist leer.

Wurde die Datei in dem temporären Verzeichnis nicht verschoben oder umbenannt, wird sie am Ende des Requests gelöscht.

Beispiel #3 Hochladen eines Arrays von Dateien

PHP unterstützt HTML Arrays auch für Dateien.

    <form action="" method="post" enctype="multipart/form-data">
    <p>Pictures:
    <input type="file" name="pictures[]" />
    <input type="file" name="pictures[]" />
    <input type="file" name="pictures[]" />
    <input type="submit" value="Send" />
    </p>
    </form>

    <?php
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() kann Directory Traversal Angriffe verhindern; weitere
            // Gültigkeitsprüfung/Bereinigung des Dateinamens kann angebracht sein
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "data/$name");
        }
    }
    ?>

Eine Fortschrittsanzeige für Dateiuploads kann mittels Session Upload Progress implementiert werden.

## Fehlermeldungen erklärt

PHP gibt zusammen mit dem Datei-Array entsprechende Fehlermeldungen zurück. Die Fehlermeldung befindet sich im Segment `error` des Datei-Arrays, welches während des Hochladens der Datei erstellt wird. Mit anderen Worten: der Fehler kann in $_FILES['userfile']['error'] gefunden werden.

Der Wert dieses Fehlercodes ist eine der `UPLOAD_ERR_*`-Konstanten.

## Häufige Probleme

Der mit `MAX_FILE_SIZE` eingestellte Wert kann nicht größer sein als der des ini-Parameters upload_max_filesize. Der Standardwert ist 2 Megabyte.

Ist das Speicherlimit aktiviert, könnte eine Erhöhung von memory_limit nötig sein. Stellen Sie sicher, dass der Wert von memory_limit groß genug ist.

Wenn max_execution_time zu kurz konfiguriert ist, könnte das Skript den Wert überschritten haben. Stellen Sie sicher, dass der Wert von `max_execution_time` groß genug ist.

> Hinweis: max_execution_time beschränkt nur die Ausführungszeit des Skripts selbst. Jegliche Zeit die auf Dinge entfällt die außerhalb des Skripts stattfinden, wie z. B. Systemaufrufe mit system(), die Funktion sleep(), Datenbankabfragen und die für das Hochladen von Dateien benötigte Zeit werden bei der Bestimmung der Ausführungszeit nicht mit einbezogen.

Warnung

max_input_time legt die maximale Zeit in Sekunden fest während der es einem Skript gestattet ist Eingaben zu empfangen. Diese beinhaltet auch die für das Hochladen von Dateien benötigte Zeit. Werden viele oder große Dateien übertragen oder ist die Verbindung zum Benutzer langsam, so kann die Standardeinstellung von `60` Sekunden überschritten werden.

Ist post_max_size zu klein eingestellt, können große Dateien nicht hochgeladen werden. Stellen Sie sicher, dass der Wert von `post_max_size` groß genug ist.

Die Option max_file_uploads kontrolliert die maximale Anzahl der Dateien, die während einer Anfrage hochgeladen werden können. Wenn mehr Dateien hochgeladen werden als das Limit, werden diese nicht in das $_FILES-Array aufgenommen. Wenn max_file_uploads beispielsweise auf `10` gesetzt ist, so wird $_FILES nie mehr als 10 Einträge enthalten.

Nicht zu prüfen, an welcher Datei Sie arbeiten, kann bedeuten, dass Benutzer auf sensible Informationen in anderen Verzeichnissen Zugriff erhalten.

Aufgrund der vielen möglichen Arten der Darstellung von Verzeichnissen können wir nicht garantieren, dass Dateien mit exotischen Namen (wie z. B. mit enthaltenen Leerzeichen) auch wirklich richtig verarbeitet werden.

Es ist nicht möglich, für normale Formularfelder und Dateifelder die gleiche Formularvariable (wie z. B. `foo[]`) zu verwenden.

## Upload mehrerer Dateien

Mehrere Dateien können hochgeladen werden, indem Sie verschiedene Namen `name` für `input` verwenden.

Es ist ebenfalls möglich, mehrere Dateien simultan hochzuladen, und die Informationen automatisch in Arrays zu erhalten. Um dies zu tun, verwenden Sie in dem HTML-Formular die gleiche Array-Sende-Syntax wie bei Auswahllisten mit Mehrfachauswahl und Checkboxen:

Beispiel #1 Hochladen mehrerer Dateien

    <form action="file-upload.php" method="POST" enctype="multipart/form-data">
      Send these files:<br>
      <input name="userfile[]" type="file"><br>
      <input name="userfile[]" type="file"><br>
      <input type="submit" value="Send files">
    </form>

Wenn das obige Formular übermittelt ist, werden die Arrays $_FILES['userfile'], $_FILES['userfile']['name'] und $_FILES['userfile']['size'] initialisiert.

Nehmen wir zum Beispiel an, dass die Dateinamen /home/test/review.html und /home/test/xwp.out übermittelt wurden. In diesem Fall würde $_FILES['userfile']['name'][0] review.html enthalten und $_FILES['userfile']['name'][1] hätte den Wert xwp.out. Genauso würde $_FILES['userfile']['size'][0] die Dateigröße von review.html enthalten, usw.

$_FILES['userfile']['name'][0], $_FILES['userfile']['tmp_name'][0], $_FILES['userfile']['size'][0] und $_FILES['userfile']['type'][0] sind ebenfalls gesetzt.

Warnung

Die Option max_file_uploads setzt ein Limit auf die Anzahl der Dateien, welche in einer Anfrage hochgeladen werden können. Sie müssen sicherstellen, dass ihr Formular nicht erlaubt, mehr Dateien hochzuladen als dieses Limit.

Beispiel #2 Hochladen eines kompletten Verzeichnisses

In den HTML-Feldern zum Hochladen von Dateien ist es mit dem Attribut `webkitdirectory` möglich, ein ganzes Verzeichnis hochzuladen. Diese Funktion wird von den meisten modernen Browsern unterstützt.

Mit der Angabe `full_path` ist es möglich, die relativen Pfade zu speichern, oder das gleiche Verzeichnis auf dem Server zu rekonstruieren.

    <form action="file-upload.php" method="post" enctype="multipart/form-data">
      Dieses Verzeichnis hochladen:<br />
      <input name="userfile[]" type="file" webkitdirectory multiple />
      <input type="submit" value="Dateien abschicken" />
    </form>

Warnung

Das Attribut `webkitdirectory` ist nicht standardisiert und gehört nicht zu den Standards. Es sollte nicht auf Websites verwendet werden, die mit dem Internet verbunden sind: Es wird nicht bei jedem Benutzer funktionieren. Außerdem kann es große Inkompatibilitäten zwischen Implementierungen geben, und das Verhalten kann sich in Zukunft ändern.

PHP analysiert nur die relativen Pfadinformationen, die vom Browser/User-Agenten übermittelt werden, und übergibt diese Informationen an das Array $_FILES. Es gibt keine Garantie, dass die Werte im Array `full_path` eine echte Verzeichnisstruktur enthalten, weshalb die PHP-Anwendung diesen Informationen nicht vertrauen darf.

## PUT-Unterstützung

PHP unterstützt die HTTP-PUT-Methode, welche von einigen Clients verwendet wird, um Dateien auf dem Server zu speichern. PUT-Anfragen sind weitaus unkomplizierter als ein POST-Dateiupload und sehen etwa so aus:

    PUT /path/filename.html HTTP/1.1

Das würde normalerweise bedeuten, dass der Client den nachfolgenden Inhalt als /path/filename.html auf dem Server speichern will. Natürlich ist es keine gute Idee, dass PHP oder Apache jeden Benutzer beliebige Dateien überschreiben lässt. Um eine solche Anfrage bearbeiten zu können, muss der Webserver erst angewiesen werden, ein bestimmtes PHP-Skript für die Abarbeitung aufzurufen. In Apache wird dies durch die Direktive Script festgelegt. Sie kann fast überall in der Apache-Konfigurationsdatei platziert werden, gebräuchlich ist die Platzierung innerhalb eines `<Directory>`- oder `Virtualhost`-Abschnitts. Eine Zeile wie die folgende erledigt dies:

    Script PUT /put.php

Diese Zeile legt fest, dass Apache alle PUT-Anfragen für URIs, die dem Kontext entsprechen, in dem diese Zeile steht, an das put.php Skript weiterleitet. Dies setzt natürlich voraus, dass PHP aktiv und für die .php-Dateierweiterung registriert ist.

In der put.php könnte anschließend ein Code wie der folgende verwendet werden. Dieser würde den Inhalt der hochgeladenen Datei in die Datei myputfile.ext auf dem Server kopieren.

Beispiel #1 Speichern von HTTP-PUT-Dateien

    <?php
    /* PUT Daten kommen in den stdin Stream */
    $putdata = fopen("php://input","r");

    /* Eine Datei zum Schreiben öffnen */
    $fp = fopen("myputfile.ext","w");

    /* Jeweils 1kB Daten lesen und
       in die Datei schreiben */
    while ($data = fread($putdata,1024))
      fwrite($fp,$data);

    /* Die Streams schließen */
    fclose($fp);
    fclose($putdata);
    ?>

## Siehe auch

- Dateisystem-Sicherheit

# Zugriff auf entfernte Dateien

Wenn `allow_url_fopen` in der php.ini aktiviert ist, können HTTP- und FTP-URLs bei den meisten Funktionen verwendet werden, die einen Dateinamen als Parameter benötigen. Darüber hinaus können URLs in include-, include_once-, require- und require_once-Anweisungen verwendet werden (allow_url_include muss dafür aktiviert sein). Weitere Informationen zu den Protokollen, die von PHP unterstützt werden, finden Sie im Abschnitt Unterstützte Protokolle und Wrapper.

Beispielsweise kann damit eine Datei auf einem anderen Webserver geöffnet und nach benötigten Daten analysiert werden. Diese Daten können zur Abfrage einer Datenbank verwendet werden oder passend zum Rest der eigenen Website ausgegeben werden.

Beispiel #1 Den Titel einer entfernten Seite auslesen

    <?php
    $datei = fopen ("http://www.example.com/", "r");
    if (!$datei) {
        echo "<p>Datei konnte nicht geöffnet werden.\n";
        exit;
    }
    while (!feof ($datei)) {
        $zeile = fgets ($datei, 1024);
        /* Funktioniert nur, wenn Titel und title-Tags in einer Zeile stehen */
        if (preg_match ("@\<title\>(.*)\</title\>@i", $zeile, $treffer)) {
            $title = $treffer[1];
            break;
        }
    }
    fclose($datei);
    ?>

Auch eine Datei auf einem FTP-Server kann geschrieben werden, vorausgesetzt man ist als Benutzer mit entsprechenden Zugriffsrechten angemeldet. Auf diesem Weg können nur neue Dateien angelegt werden. Falls Sie versuchen eine schon existierende Datei zu überschreiben, wird der fopen()-Aufruf fehlschlagen.

Um sich statt als 'anonymous' als anderer Benutzer anzumelden, muss ein Benutzername (und möglicherweise ein Passwort) innerhalb der URL angegeben werden, z. B. '`ftp://benutzer:passwort@ftp.example.com/pfad/zur/datei`'. Dieselbe Syntax kann verwendet werden, um auf Dateien via HTTP zuzugreifen, wenn diese eine Basic-Authentifizierung benötigen.

Beispiel #2 Daten auf einen entfernten Server speichern

    <?php
    $datei = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
    if (!$datei) {
        echo "<p>Datei konnte nicht zum schreiben geöffnet werden.\n";
        exit;
    }
    /* Schreibe die Daten hier hin. */
    fputs ($datei, $_SERVER['HTTP_USER_AGENT'] . "\n");
    fclose ($datei);
    ?>

> Hinweis:

> Obiges Beispiel könnte dazu verleiten, dieses Verfahren zu verwenden, um in eine entfernte Log-Datei zu schreiben. Das würde aber leider nicht funktionieren, weil der fopen()-Aufruf fehlschlagen würde, wenn die entfernte Datei bereits existiert. Für eine dezentralisierte Protokollierung sollten Sie sich die Funktion syslog() anschauen.

# Verbindungssteuerung

PHP erhält intern einen Verbindungsstatus. Dieser kann vier Zustände annehmen:

- 0 - NORMAL
- 1 - ABORTED
- 2 - TIMEOUT
- 3 - ABORTED und TIMEOUT

Wenn ein PHP-Skript aktiv ist, ist der Status üblicherweise NORMAL. Sollte der Client-Rechner die Verbindung beenden, wird der Status auf ABORTED gesetzt. Ein clientseitiges Beenden der Verbindung wird für gewöhnlich veranlasst, wenn Benutzer den STOP-Button des Browsers drücken. Wenn das eingestellte Zeitlimit (siehe set_time_limit()) überschritten wird, wird der Status TIMEOUT gesetzt.

Sie können entscheiden, ob der Verbindungsabbruch seitens des Clients den Abbruch des Skriptes zur Folge haben soll. Manchmal ist es sinnvoll, Skripte sauber zu beenden, auch wenn kein Browser mehr zur Verfügung steht, der die Ausgabe empfängt. Die Abarbeitung eines Skriptes wird standardmäßig abgebrochen, wenn der Client die Verbindung beendet. Dieses Verhalten kann sowohl durch die Option ignore_user_abort in der Konfigurationsdatei php.ini, durch die entsprechende Option `php_value ignore_user_abort` in der Apache-Konfigurationsdatei httpd.conf als auch durch ignore_user_abort() beeinflußt werden. Wenn PHP nicht angewiesen wird, einen Verbindungsabbruch durch den Benutzer zu ignorieren und die Verbindung dann durch den Benutzer beendet wird, wird die Abarbeitung des Scriptes abgebrochen. Die einzige Ausnahme ist, wenn durch die Funktion register_shutdown_function() eine Shutdown-Funktion angegeben wird, die bei clientseitigem Abbruch ausgeführt wird. Wenn dann der Benutzer den STOP-Button seines Browsers drückt, wird PHP bei der nächsten Ausgabe des Skriptes feststellen, dass die Verbindung abgebrochen wurde und die Shutdown-Funktion aufrufen. Diese Shutdown-Funktion wird auch aufgerufen, wenn das Skript auf normalem Wege beendet wird, daher sollte man, wenn man für den Fall eines Benutzerabbruchs etwas anderes vorgesehen hat, die Funktion connection_aborted() verwenden. Sie gibt `true` zurück, wenn die Verbindung abgebrochen wurde.

Ein Skript kann ebenfalls durch den eingebauten Script-Timer beendet werden. Der Standard-Timeout beträgt 30 Sekunden. Er kann durch die Option max_execution_time in der php.ini, durch den entsprechenden Eintrag `php_value max_execution_time` in der Apache-Konfigurationsdatei httpd.conf oder durch die Funktion set_time_limit() beeinflußt werden. Bei Zeitüberschreitung wird das Skript beendet und, genau wie im obigen Fall des Verbindungsabbruchs, eine registrierte Shutdown-Funktion ausgeführt. Um zu überprüfen, ob es sich um einen Abbruch aufgrund von Zeitüberschreitung handelt, kann die Funktion connection_status() benutzt werden. Sie gibt `2` zurück, wenn es sich um eine Zeitüberschreitung handelt.

Zu bemerken ist, dass der ABORTED- und der TIMEOUT-Status gleichzeitig auftreten können. Dies ist möglich, wenn PHP angewiesen wird, Benutzerabbrüche zu ignorieren. PHP wird feststellen, dass der Benutzer die Verbindung abgebrochen hat, das Skript allerdings läuft weiter. Sollte es dann das Zeitlimit erreichen, wird es abgebrochen und eine Shutdown-Funktion, wenn definiert, wird aufgerufen. Zu diesem Zeitpunkt kann man feststellen, dass connection_timeout() und connection_aborted() `true` zurückgeben. Diese beiden Statusmöglichkeiten können auch durch einen Aufruf der Funktion connection_status() abgefragt werden. Sie liefert ein Bitfeld des aktiven Status. Wenn beispielsweise TIMEOUT und ABORTED aktiv sind, wird 3 zurückgegeben.

# Persistente Datenbankverbindungen

### Was sind persistente Verbindungen?

Persistente Verbindungen sind Verbindungen, die nach Beendigung der Skriptausführung nicht geschlossen werden. Wird eine persistente Verbindung angefordert, prüft PHP, ob bereits eine identische persistente Verbindung (die von einem früheren Aufruf offen geblieben ist) existiert; ist dies der Fall, wird sie wiederverwendet, andernfalls wird eine neue Verbindung aufgebaut. Eine "identische" Verbindung ist eine Verbindung, die zum gleichen Host mit demselben Benutzernamen und Passwort (sofern zutreffend) hergestellt wurde.

Es gibt keine Möglichkeit, eine bestimmte Verbindung anzufordern oder zu garantieren, ob die zurückgegebene Verbindung eine bestehende oder eine ganz neue ist (etwa wenn alle bestehenden Verbindungen in Verwendung sind oder die Anfrage von einem anderen Worker bearbeitet wird, der über einen eigenen Verbindungs-Pool verfügt).

Die persistenten Verbindungen von PHP können daher beispielsweise nicht verwendet werden, um:

- eine bestimmte Datenbanksitzung einem bestimmten Web-Benutzer zuzuweisen
- eine umfangreiche Transaktion über mehrere Anfragen hinweg aufzubauen
- eine Abfrage in einer Anfrage zu starten und die Ergebnisse in einer anderen abzurufen

Persistente Verbindungen bieten keinerlei Funktionalität, die nicht auch mit nicht-persistenten Verbindungen möglich wäre.

### Web-Anfragen

Es gibt zwei Möglichkeiten, wie ein Webserver PHP zur Generierung von Webseiten einsetzen kann:

Die erste Methode ist, PHP als CGI-"Wrapper" zu benutzen. Wenn diese Methode eingesetzt wird, wird für jede Anfrage nach einer PHP-Seite vom Webserver eine Instanz des PHP-Interpreters gestartet und anschließend wieder beendet. Durch die Beendigung des Interpreters nach jeder Anfrage werden alle Ressourcen, auf die zugegriffen wurde (wie beispielsweise eine Verbindung zu einem SQL-Datenbankserver), wieder geschlossen. In diesem Fall erreicht man nichts, wenn man persistente Verbindungen benutzt - Persistenz ist in diesem Fall nicht gegeben.

Die zweite und populärste Methode ist der Einsatz von PHP-FPM oder von PHP als Modul in einem Multiprozess-Webserver (derzeit nur Apache). Solche Umgebungen haben typischerweise einen Prozess (den Elternprozess), der eine Reihe weiterer Prozesse (seine Kinder) koordiniert, welche die eigentliche Arbeit des Bereitstellens der Webseiten übernehmen. Wenn eine Anfrage von einem Client eingeht, wird sie an eines der Kinder weitergereicht, das gerade keinen anderen Client bedient. Das bedeutet, dass eine zweite Anfrage desselben Clients an den Server unter Umständen von einem anderen Kindprozess als die erste Anfrage bearbeitet wird. Wurde eine persistente Verbindung einmal geöffnet, kann jede danach vom selben Kindprozess bediente Seite die bereits aufgebaute Verbindung zum SQL-Server weiterverwenden.

> Hinweis:

> Die verwendete Methode lässt sich anhand des Werts von "Server API" in der Ausgabe von phpinfo() oder anhand des Werts der Konstante `PHP_SAPI`, ausgeführt über eine Web-Anfrage, prüfen.

> Lautet die Server API "Apache 2 Handler" oder "FPM/FastCGI", werden persistente Verbindungen über Anfragen hinweg wiederverwendet, die vom selben Worker bedient werden. Bei jedem anderen Wert bleiben persistente Verbindungen nach jeder Anfrage nicht erhalten.

### Kommandozeilen-Prozesse

Da PHP auf der Kommandozeile für jedes Skript einen neuen Prozess verwendet, werden persistente Verbindungen nicht zwischen Kommandozeilen-Skripten geteilt. Es bringt daher keinen Nutzen, sie in kurzlebigen Skripten wie Cronjobs oder einmaligen Kommandozeilenbefehlen einzusetzen. Sie können jedoch zum Beispiel in einem langlaufenden Anwendungsserver nützlich sein, der viele Anfragen oder Aufgaben bedient, von denen jede ihre eigene Datenbankverbindung benötigen kann.

### Wozu sie verwenden?

Persistente Verbindungen sind nützlich, wenn der Aufwand zum Aufbau einer Verbindung zu einem SQL-Server hoch ist. Ob dieser Aufwand signifikant ist, hängt von vielen Faktoren ab, etwa von der Art der Datenbank, davon, ob sie auf demselben Rechner wie der Webserver läuft, und davon, wie stark dieser Rechner ausgelastet ist. Ist der Verbindungsaufwand hoch, können persistente Verbindungen erheblich helfen: Jeder Kindprozess verbindet sich nur einmal während seiner gesamten Lebensdauer, statt jedes Mal, wenn er eine Seite verarbeitet, die eine Verbindung zum SQL-Server benötigt. Das bedeutet, dass jeder Kindprozess, der eine persistente Verbindung öffnet, seine eigene Verbindung zum Server unterhält. Bei beispielsweise 20 verschiedenen Kindprozessen, die jeweils ein Skript ausführen, das eine persistente Verbindung zum SQL-Server aufbaut, ergeben sich 20 separate Verbindungen zu diesem Server, eine pro Kind.

### Mögliche Nachteile: Verbindungslimits

Es ist jedoch zu beachten, dass dies Nachteile haben kann, wenn eine Datenbank mit Verbindungslimits verwendet wird, die durch persistente Verbindungen der Kindprozesse überschritten werden. Hat die Datenbank ein Limit von 16 gleichzeitigen Verbindungen und versuchen während einer stark ausgelasteten Server-Sitzung 17 Kindprozesse, eine Verbindung herzustellen, wird einer von ihnen fehlschlagen. Bestehen in den Skripten Fehler, die das Schließen der Verbindungen verhindern (wie etwa Endlosschleifen), können die verfügbaren 16 Verbindungen schnell aufgebraucht sein.

Persistente Verbindungen erhöhen in der Regel die Anzahl der zu einem gegebenen Zeitpunkt geöffneten Verbindungen, da untätige Worker weiterhin die Verbindungen halten, die sie für vorherige Anfragen geöffnet haben. Werden viele Worker hochgefahren, um eine Lastspitze zu bewältigen, bleiben die von ihnen geöffneten Verbindungen bestehen, bis der Worker beendet wird oder der Datenbankserver die Verbindung schließt.

Es ist sicherzustellen, dass die vom Datenbankserver erlaubte maximale Anzahl an Verbindungen größer ist als die maximale Anzahl der Worker für Web-Anfragen (zuzüglich aller weiteren Verwendungen wie Cronjobs oder administrativer Verbindungen).

Es empfiehlt sich, in der Dokumentation der Datenbank nachzuschlagen, wie der Datenbankserver aufgegebene oder im Leerlauf befindliche Verbindungen per Timeout behandelt. Lange Timeouts können die Anzahl der zu einem Zeitpunkt geöffneten persistenten Verbindungen erheblich erhöhen.

### Mögliche Nachteile: Verwaltung des Verbindungszustands

Manche Datenbank-Erweiterungen führen eine automatische Bereinigung durch, wenn die Verbindung wiederverwendet wird; andere überlassen diese Aufgabe dem Anwendungsentwickler. Je nach gewählter Datenbank-Erweiterung und Anwendungsdesign kann eine manuelle Bereinigung vor Beendigung des Skripts erforderlich sein. Änderungen, die Verbindungen in einem unerwarteten Zustand zurücklassen können, sind unter anderem:

- Ausgewählte/voreingestellte Datenbank
- Tabellensperren
- Nicht abgeschlossene Transaktionen
- Temporäre Tabellen
- Verbindungsspezifische Einstellungen oder Funktionen wie Profiling

Tabellensperren und Transaktionen, die nicht aufgeräumt oder abgeschlossen werden, können dazu führen, dass andere Abfragen unbegrenzt blockiert werden und/oder dass eine spätere Wiederverwendung der Verbindung unerwartete Änderungen verursacht.

Ist die falsche Datenbank ausgewählt, kann eine spätere Wiederverwendung der Verbindung Abfragen nicht wie erwartet ausführen (oder führt sie auf der falschen Datenbank aus, wenn sich die Schemata ausreichend ähneln).

Werden temporäre Tabellen nicht aufgeräumt, können nachfolgende Anfragen dieselbe Tabelle nicht erneut anlegen.

Die Bereinigung kann mithilfe von Klassen-Destruktoren oder register_shutdown_function() umgesetzt werden. Dedizierte Connection-Pooling-Proxies, die dies als Teil ihrer Funktionalität enthalten, können ebenfalls in Betracht gezogen werden.

### Schlussbemerkungen

Aufgrund des oben beschriebenen Verhaltens und der potenziellen Nachteile sollten persistente Verbindungen nicht ohne sorgfältige Abwägung eingesetzt werden. Sie sollten nicht ohne zusätzliche Anpassungen der Anwendung sowie ohne sorgfältige Konfiguration von Datenbankserver und Webserver und/oder PHP-FPM verwendet werden.

Es sollten alternative Lösungen in Betracht gezogen werden, etwa die Untersuchung und Behebung der Ursachen für den Verbindungsaufbau-Overhead (beispielsweise das Deaktivieren von Reverse-DNS-Lookups auf dem Datenbankserver) oder dedizierte Connection-Pooling-Proxies.

Für Web-APIs mit hohem Anfragevolumen sollten alternative Runtimes oder langlaufende Anwendungsserver in Betracht gezogen werden.

### Siehe auch

- ibase_pconnect()
- oci_pconnect()
- odbc_pconnect()
- pfsockopen()
- pg_connect()
- MySQLi und persistente Verbindungen
- PDO-Verbindungsverwaltung

# Nutzung von PHP auf der Kommandozeile

## Inhaltsverzeichnis

- Unterschiede zu anderen SAPIs
- Optionen
- Verwendung
- I/O Streams
- Interaktive Shell
- Eingebauter Webserver
- INI-Einstellungen

## Introduction

Das Hauptaugenmerk der CLI SAPI liegt auf der Entwicklung von Kommandozeilenanwendungen. Es gibt einige Unterschiede zwischen der CLI SAPI und anderen SAPIs, welche in diesem Kapitel beschrieben werden. Es ist erwähnenswert, dass CLI und CGI verschiedene SAPIs sind, auch wenn sie viele Verhaltensweisen teilen.

Die CLI SAPI ist standardmäßig durch die Option --enable-cli aktiviert, kann jedoch durch Angabe der Option --disable-cli im ./configure-Skript deaktiviert werden.

Der Name, der Pfad und das Vorhandensein der CLI/CGI-Binaries hängt davon ab, wie PHP auf dem System installiert wurde. Standarmäßig werden nach dem Aufruf von make sowohl CGI als auch CLI kompiliert und als sapi/cgi/php-cgi beziehungsweise sapi/cli/php in Ihrem PHP-Quellcodeverzeichnis gespeichert. Sie werden bemerken, dass beide php heißen. Was während make install passiert, hängt davon ab, wie PHP konfiguriert wurde. Wenn bei der Konfiguration eine Modul-SAPI wie z. B. apxs gewählt wurde oder die Option --disable-cgi genutzt wurde, wird die CLI während make install nach {PREFIX}/bin/php kopiert. Andernfalls wird das CGI-Binary dorthin kopiert. Also wird, wenn beispielsweise --with-apxs in Ihrem configure-Kommando angegeben ist, die CLI während make install nach {PREFIX}/bin/php kopiert. Wenn Sie die Installation des CGI-Binaries überschreiben wollen, verwenden Sie make install-cli nach make install. Alternativ können Sie --disable-cgi in Ihrem configure-Kommando angeben.

> Hinweis:

> Weil sowohl --enable-cli als auch --enable-cgi standardmäßig eingeschaltet sind, muss --enable-cli in Ihrem configure-Kommando nicht zwingend bedeuten, dass die CLI während make install nach {PREFIX}/bin/php kopiert wird.

Auf Windows wird das CLI-Binary im Hauptordner als php.exe ausgeliefert. Die CGI-Version wird als php-cgi.exe bereitgestellt. Zusätzlich wird php-win.exe ausgeliefert, wenn PHP mit --enable-cli-win32 konfiguriert wurde. Dieses Binary verhält sich genauso wie die CLI-Version, bis auf die Tatsache, dass sie nichts ausgibt und somit keine Konsole zur Verfügung stellt.

> Hinweis: Welche SAPI habe ich?

> Auf der Kommandozeile wird Ihnen die Eingabe von php -v verraten, ob Sie php als CGI oder CLI einsetzen. Sehen Sie sich auch die Funktion php_sapi_name() und die Konstante `PHP_SAPI` an.

> Hinweis:

> Eine UNIX-`man`page ist durch Eingabe von man php auf der Kommandozeile verfügbar.

## Unterschiede zu anderen SAPIs

Wesentliche Unterschiede der CLI-SAPI zu anderen SAPIs:

- Anders als bei der CGI-SAPI werden keine Header ausgegeben.

  Obwohl die CGI-SAPI eine Option bietet, HTTP-Header zu unterdrücken, gibt es keine gleichwertige Option, sie in der CLI SAPI anzuzeigen.

  CLI wird standardmäßig im stillen Modus gestartet, dennoch gibt es die Optionen -q und --no-header aus Kompatibilitätsgründen noch, sodass auch ältere CGI-Skripte noch verwendet werden können.

  Es wechselt das Arbeitsverzeichnis nicht in das des Skriptes. (Die Optionen -C und --no-chdir wurden aus Kompatibilitätsgründen beibehalten.)

  Fehlermeldungen im Klartext (keine HTML-Formatierung).

- Es gibt bestimmte php.ini-Direktiven, die von der CLI SAPI außer Kraft gesetzt werden, weil sie in einer Kommandozeilenumgebung keinen Sinn ergeben.

  Überschriebene php.ini-Direktiven
  Direktive | CLI SAPI-Standardwert | Kommentar
  --- | --- | ---
  html_errors | `false` | Die Standardeinstellung ist `false`, weil es sehr schwierig sein kann, Fehlermeldunge auf der Kommandozeile zu lesen, wenn sie mit bedeutungslosen HTML-Tags vollgestopft ist.
  implicit_flush | `true` | Auf der Kommandozeile ist es normalerweise erwünscht, dass alle Ausgaben, die von print, echo und Konsorten kommen, sofort angezeigt werden und nicht in einem Puffer zwischengespeichert werden. Es ist jedoch immer noch möglich, output buffering zu verwenden, um die Standardausgabe aufzuschieben oder zu manipulieren.
  max_execution_time | 0 (unendlich) | Da die Anwendungsbereiche von PHP auf der Kommandozeile wesentlich vielfältiger sind als in webbasierten Anwendungen und oft lange Laufzeiten besitzen, wird die maximale Ausführungszeit auf unendlich gesetzt.
  register_argc_argv | `true` | Weil diese Einstellung auf `true` gesetzt ist, haben Skripte, die über die CLI-SAPI ausgeführt werden, immer Zugriff auf argc (die Anzahl der Argumente, die der Anwendung übergeben wurden) und argv (das Array mit den übergebenen Argumenten). Die PHP-Variablen $argc und $argv werden automatisch mit den entsprechenden Werten gefüllt, wenn die CLI-SAPI verwendet wird. Diese Werte können auch im Array $_SERVER gefunden werden, beispielsweise: $_SERVER['argv']. Warnung Wenn register_argc_argv aktiviert ist, ist das Vorhandensein von $argv oder $_SERVER['argv'] kein zuverlässiger Hinweis darauf, dass ein Skript von der Kommandozeile aus ausgeführt wird, da diese Variablen auch in anderen Kontexten gesetzt werden können. Stattdessen sollte der von php_sapi_name() zurückgegebene Wert überprüft werden.
      <?php

      if (php_sapi_name() === 'cli') {
          echo "Dies wird von der Befehlszeile aus ausgeführt!\n";
      }
  output_buffering | `false` | Auch wenn diese php.ini-Option fest auf `false` gesetzt ist, sind die Funktionen der Ausgabepufferung verfügbar.
  max_input_time | `false` | Die PHP-CLI unterstützt GET, POST und Dateiuploads nicht.

  > Hinweis:

  > Diese Direktiven können nicht mit einem anderen Wert aus der Konfigurationsdatei php.ini oder einer eigenen (falls angegeben) initialisiert werden. Diese Einschränkung ergibt sich dadurch, dass diese Standardwerte angewandt werden, nachdem alle Konfigurationsdateien gelesen wurden. Dennoch können die Werte zur Laufzeit verändert werden (was aber nicht für alle dieser Direktiven einen Sinn ergibt, beispielsweise register_argc_argv).

  > Hinweis:

  > Es wird empfohlen ignore_user_abort für Kommandozeilenanwendungen zu setzen. Siehe ignore_user_abort() für weitere Informationen.

- Um die Arbeit auf der Kommandozeilenumgebung zu erleichtern, wurden einige Konstanten für Ein- und Ausgabestreams definiert.

- Die CLI SAPI wechselt das aktuelle Arbeitsverzeichnis nicht ins Verzeichnis des ausgeführten Skripts.

  Beispiel #1 Beispiel, welches den Unterschied zur CGI-SAPI verdeutlicht:

      <?php
      // Unsere einfache Anwendung namens test.php
      echo getcwd(), "\n";
      ?>

  Bei der CGI-Version ist die Ausgabe folgende:

      $ pwd
      /tmp

      $ php -q anderes_verzeichnis/test.php
      /tmp/anderes_verzeichnis

  Dies zeigt deutlich, dass PHP vom aktuellen Verzeichnis in das des ausgeführten Skriptes wechselt.

  Nutzung der CLI SAPI führt zu folgender Ausgabe:

      $ pwd
      /tmp

      $ php -f anderes_verzeichnis/test.php
      /tmp

  Dies ermöglicht eine größere Flexibilität beim Erstellen von Kommandozeilenanwendungen in PHP.

  > Hinweis:

  > Die CGI-SAPI unterstützt das Verhalten der CLI SAPI durch Angabe der Option -C beim Starten von der Kommandozeile.

## Kommandozeilenoptionen

Die Liste der Kommandozeilenoptionen, die das PHP-Binary bereitstellt, kann jederzeit abgerufen werden, indem PHP mit der Option -h gestartet wird:

    Usage: php [options] [-f] <file> [--] [args...]
       php [options] -r <code> [--] [args...]
       php [options] [-B <begin_code>] -R <code> [-E <end_code>] [--] [args...]
       php [options] [-B <begin_code>] -F <file> [-E <end_code>] [--] [args...]
       php [options] -- [args...]
       php [options] -a

      -a               Run interactively
      -c <path>|<file> Look for php.ini file in this directory
      -n               No php.ini file will be used
      -d foo[=bar]     Define INI entry foo with value 'bar'
      -e               Generate extended information for debugger/profiler
      -f <file>        Parse and execute <file>.
      -h               This help
      -i               PHP information
      -l               Syntax check only (lint)
      -m               Show compiled in modules
      -r <code>        Run PHP <code> without using script tags <?..?>
      -B <begin_code>  Run PHP <begin_code> before processing input lines
      -R <code>        Run PHP <code> for every input line
      -F <file>        Parse and execute <file> for every input line
      -E <end_code>    Run PHP <end_code> after processing all input lines
      -H               Hide any passed arguments from external tools.
      -S <addr>:<port> Run with built-in web server.
      -t <docroot>     Specify document root <docroot> for built-in web server.
      -s               Output HTML syntax highlighted source.
      -v               Version number
      -w               Output source with stripped comments and whitespace.
      -z <file>        Load Zend extension <file>.

      args...          Arguments passed to script. Use -- args when first argument
                       starts with - or script is read from stdin

      --ini            Show configuration file names

      --rf <name>      Show information about function <name>.
      --rc <name>      Show information about class <name>.
      --re <name>      Show information about extension <name>.
      --rz <name>      Show information about Zend extension <name>.
      --ri <name>      Show configuration for extension <name>.

Kommandozeilenoptionen
Option | Langform | Beschreibung
--- | --- | ---
-a | --interactive | Startet PHP im interaktiven Modus. Für weitere Informationen siehe die Dokumentation für den Interaktiven Modus.
-b | --bindpath | Der Bind-Pfad für den externen FASTCGI-Servermodus (nur CGI).
-C | --no-chdir | Nicht in das Verzeichnis des Skripts wechseln (nur CGI).
-q | --no-header | Der Quiet-Modus. Unterdrücke die Ausgabe von HTTP-Headern (nur CGI).
-T | --timing | Misst die Ausführungszeit des Skripts. Dies wird count mal durchgeführt (nur CGI).
-c | --php-ini | Mit dieser Option kann man entweder ein Verzichnis angeben, in welchem nach der php.ini gesucht werden soll, oder man kann eine eigene `INI`-Datei angeben (diese muss nicht php.ini heissen). Zum Beispiel:
    $ php -c /custom/directory/ my_script.php

    $ php -c /custom/directory/custom-file.ini my_script.php
Wenn diese Option nicht angegeben wird, wird die php.ini-Datei an den vorgegebenen Orten gesucht.
-n | --no-php-ini | php.ini komplett ignorieren.
-d | --define | Diese Option erlaubt es Ihnen, einen eigenen Wert für eine beliebige in php.ini erlaubte Direktive zu setzen. Die Syntax ist:
    -d configuration_directive[=value]
Beispiel #1 Beispiel für die Verwendung von `-d` zum Setzen einer INI-Direktive
    # Auslassen des Wertes setzt die Direktive auf "1"
    $ php -d max_execution_time
          -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(1) "1"

    # Übergeben eines leeren Wertes setzt die Direktive auf ""
    php -d max_execution_time=
        -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(0) ""

    # Die Direktive wird auf das gesetzt, was nach '=' kommt
    $  php -d max_execution_time=20
           -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(2) "20"
    $  php
           -d max_execution_time=doesntmakesense
           -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
    string(15) "doesntmakesense"
-e | --profile-info | Erweiterte Informationen für Debugger/Profiler erstellen.
-f | --file | Parst die angegebene Datei und führt sie aus. Das -f ist optional und kann weggelassen werden. Es genügt, nur den Dateinamen anzugeben.
-h und -? | --help und --usage | Gibt eine Liste von Kommandozeilenoptionen mit kurzen Beschreibungen ihrer Funktion aus.
-i | --info | Diese Kommandozeilenoption ruft phpinfo() auf und gibt das Ergebnis aus. Wenn PHP nicht korrekt funktioniert, ist es empfehlenswert, php -i zu verwenden und nachzusehen, ob etwa Fehlermeldungen vor oder statt der Informationstabellen ausgegeben werden. Beachten Sie, dass die Ausgabe bei Verwendung des CGI-Modus in HTML erfolgt und deswegen ziemlich umfangreich ist.
-l | --syntax-check | Überprüft die Syntax, führt aber den angegebenen PHP-Code nicht aus. Wenn kein Dateiname angegeben ist, wird die Eingabe von der Standardeingabe verarbeitet, andernfalls wird jede angegebene Datei überprüft. Bei Erfolg wird der Text `No syntax errors detected in <filename>` auf der Standardausgabe ausgegeben. Bei einem Fehler wird zusätzlich zum internen Parser-Fehler der Text `Errors parsing <filename>` auf der Standardausgabe ausgegeben. Wenn in den angegebenen Dateien (oder der Standardeingabe) irgendwelche Fehler gefunden werden, wird der Shell-Rückgabecode auf `-1` gesetzt, andernfalls wird er auf `0` gesetzt. Diese Option findet keine fatalen Fehler (z. B. undefinierte Funktionen), die die Ausführung des Codes erfordern. Hinweis: Vor PHP 8.3.0 war es nur möglich, den Namen einer Datei anzugeben, die überprüft werden sollte. Hinweis: Diese Option funktioniert nicht zusammen mit der Option -r.
-m | --modules | Beispiel #2 Ausgabe der geladenen PHP- und Zend-Module
    $ php -m
    [PHP Modules]
    xml
    tokenizer
    standard
    session
    posix
    pcre
    overload
    mysql
    mbstring
    ctype

    [Zend Modules]
> -r | --run | Diese Option erlaubt die Ausführung von PHP Code direkt von der Kommandozeile. Die PHP-Tags `<?php` und `?>` werden nicht benötigt und verursachen einen Parsefehler, wenn sie dennoch vorhanden sind. Hinweis: Bei der Verwendung dieser Option in PHP ist besondere Vorsicht geboten, dass es nicht zu Kollisionen mit dem Ersetzen von Kommandozeilenvariablen durch die Shell kommt. Beispiel #3 Syntaxfehler beim Verwenden von doppelten Anführungszeichen
>     $ php -r "$foo = get_defined_constants();"
>     PHP Parse error:  syntax error, unexpected '=' in Command line code on line 1

>     Parse error: syntax error, unexpected '=' in Command line code on line 1
> Das Problem hier ist, dass auch sh/bash Variablen ersetzt, wenn doppelte Anführungszeichen (`"`) verwendet werden. Weil die Variable $foo wahrscheinlich nicht definiert ist, wird die Variable zu nichts aufgelöst. Der entstehende Code, welcher PHP übergeben wird, sieht so aus:
>     $ php -r " = get_defined_constants();"
> Der richtige Weg wäre, einfache Anführungszeichen (`'`) zu verwenden. Variablen in einfachen Anführungszeichen werden von sh/bash nicht ersetzt. Beispiel #4 Verwendung einfacher Anführungszeichen, um ein Ersetzen der Variablen durch die Shell zu verhindern
>     $ php -r '$foo = get_defined_constants(); var_dump($foo);'
>     array(370) {
>       ["E_ERROR"]=>
>       int(1)
>       ["E_WARNING"]=>
>       int(2)
>       ["E_PARSE"]=>
>       int(4)
>       ["E_NOTICE"]=>
>       int(8)
>       ["E_CORE_ERROR"]=>
>       [...]
Wenn eine andere Kommandozeilenumgebung als sh/bash verwendet wird, könnten weitere Probleme auftreten. Gegebenenfalls kann unter » https://github.com/php/php-src/issues ein Bugreport erstellt werden. Man kann dennoch leicht in Schwierigkeiten geraten, wenn man versucht PHP- oder Shell-Variablen zu verwenden, oder Backslashes zum Maskieren verwendet. Sie wurden gewarnt! Hinweis: `-r` ist in der CLI SAPI verfügbar, nicht jedoch in der CGI-SAPI. Hinweis: Diese Option ist für sehr einfachen Code gedacht, weshalb einige Direktiven wie etwa auto_prepend_file und auto_append_file in diesem Modus ignoriert werden.
-B | --process-begin | PHP-Code, der ausgeführt werden soll, bevor stdin ausgewertet wird.
-R | --process-code | PHP-Code, der für jede Eingabezeile ausgeführt werden soll. Es gibt zwei spezielle Variablen in diesem Modus: $argn und $argi. $argn enthält die Zeile, die PHP gerade verarbeitet und $argi enthält die Zeilennummer.
-F | --process-file | PHP-Datei, die für jede Eingabezeile ausgeführt werden soll.
-E | --process-end | PHP-Code, der nach der Verarbeitung der Eingabe ausgeführt werden soll. Beispiel #5 Nutzung der Optionen -B, -R und -E, um die Anzahl der Zeilen in einem Projekt zu zählen.
    $ find my_proj | php -B '$l=0;' -R '$l += count(@file($argn));' -E 'echo "Zeilen insgesamt: $l\n";'
    Zeilen insgesamt: 37328
-S | --server | Startet den eingebauten Webserver.
-t | --docroot | Gibt den Document-Root (Wurzelverzeichnis der Dokumente) für den eingebauten Webserver an.
-s | --syntax-highlight und --syntax-highlighting | Den Quelltext mit farblich hervorgehobener Syntax anzeigen. Diese Option verwendet den internen Mechanismus zum Parsen von Dateien, um eine HTML-Version mit Syntax-Highlighting auf die Standardausgabe zu schreiben. Beachten Sie, dass sie nur einen Block mit den HTML-Tags `<code> [...] </code>` erzeugt, jedoch keine HTML-Header. Hinweis: Diese Option funktioniert nicht zusammen mit -r.
-v | --version | Beispiel #6 Nutzung von -v, um den SAPI-Namen, sowie die PHP- und Zend-Version zu ermitteln
    $ php -v
    PHP 5.3.1 (cli) (built: Dec 11 2009 19:55:07)
    Copyright (c) 1997-2009 The PHP Group
    Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies
-w | --strip | Den Quelltext ohne Kommentare und Leerzeichen anzeigen. Hinweis: Diese Option funktioniert nicht zusammen mit -r.
-z | --zend-extension | Eine Zend-Erweiterung laden. Wenn nur ein Dateiname angegeben wird, versucht PHP, die Erweiterung aus dem momentanen Standard-Bibliotheken-Pfad auf Ihrem System zu laden (auf Linux-Systemen normalerweise in /etc/ld.so.conf angegeben). Wenn ein Dateiname mit absoluter Pfadinformation übergeben wird, wird der Bibliotheken-Pfad des Systems nicht verwendet. Ein relativer Dateiname mit Pfadinformationen wird PHP veranlassen, zu versuchen, die Erweiterung in einem Pfad relativ zum aktuellen Verzeichnis zu laden.
| --ini | Zeigt die Namen der Konfigurationsdateien und die durchsuchten Verzeichnisse. Beispiel #7 `--ini`-Beispiel
    $ php --ini
    Configuration File (php.ini) Path: /usr/dev/php/5.2/lib
    Loaded Configuration File:         /usr/dev/php/5.2/lib/php.ini
    Scan for additional .ini files in: (none)
    Additional .ini files parsed:      (none)
--rf | --rfunction | Zeigt Informationen über die angegebene Funktion oder Klassenmethode (z. B. Anzahl und Namen der Parameter). Diese Option ist nur verfügbar, wenn PHP mit Reflection-Unterstützung kompiliert wurde. Beispiel #8 Einfache `--rf`-Nutzung
    $ php --rf var_dump
    Function [ <internal> public function var_dump ] {

      - Parameters [2] {
        Parameter #0 [ <required> $var ]
        Parameter #1 [ <optional> $... ]
      }
    }
--rc | --rclass | Zeigt Inforationen über die angegebene Klasse (Liste der Konstanten, Eigenschaften und Methoden). Diese Option ist nur verfügbar, wenn PHP mit Reflection-Unterstützung kompiliert wurde. Beispiel #9 `--rc`-Beispiel
    $ php --rc Directory
    Class [ <internal:standard> class Directory ] {

      - Constants [0] {
      }

      - Static properties [0] {
      }

      - Static methods [0] {
      }

      - Properties [0] {
      }

      - Methods [3] {
        Method [ <internal> public method close ] {
        }

        Method [ <internal> public method rewind ] {
        }

        Method [ <internal> public method read ] {
        }
      }
    }
--re | --rextension | Zeigt Informationen über die angegebene Erweiterung (Liste der php.ini-Optionen, definierte Funktionen, Konstanten und Klassen). Diese Option ist nur verfügbar, wenn PHP mit Reflection-Unterstützung kompiliert wurde. Beispiel #10 `--re`-Beispiel
    $ php --re json
    Extension [ <persistent> extension #19 json version 1.2.1 ] {

      - Functions {
        Function [ <internal> function json_encode ] {
        }
        Function [ <internal> function json_decode ] {
        }
      }
    }
--rz | --rzendextension | Zeigt Konfiguration der angegebenen Zend-Erweiterung an (entspricht der von phpinfo() zurückgegebenen Information).
--ri | --rextinfo | Zeigt die Konfiguration der angegebenen Erweiterung an (entspricht der von phpinfo() zurückgegebenen Information). Die Konfiguration des Sprachkerns kann über den speziellen Erweiterungsnamen "main" ermittelt werden. Beispiel #11 `--ri`-Beispiel
    $ php --ri date

    date

    date/time support => enabled
    "Olson" Timezone Database Version => 2009.20
    Timezone Database => internal
    Default timezone => Europe/Oslo

    Directive => Local Value => Master Value
    date.timezone => Europe/Oslo => Europe/Oslo
    date.default_latitude => 59.930972 => 59.930972
    date.default_longitude => 10.776699 => 10.776699
    date.sunset_zenith => 90.583333 => 90.583333
    date.sunrise_zenith => 90.583333 => 90.583333

> Hinweis:

> Die Optionen `-rBRFEH`, `--ini` und `--r[fcezi]` sind nur für CLI verfügbar.

## Ausführen von PHP-Dateien

Es gibt drei verschiedene Wege, PHP-Code in der CLI SAPI auszuführen:

1. PHP mitteilen, eine bestimmte Datei auszuführen.

       $ php my_script.php

       $ php -f my_script.php

   Beide Methoden (ob die Option -f verwendet wird oder nicht) führen die Datei my_script.php aus. Zu beachten ist, dass es keine Einschränkungen dafür gibt, welche Dateien ausgeführt werden können; beispielsweise muss das PHP-Skript nicht auf `.php` enden.

2. Den auszuführenden PHP-Code direkt auf der Kommandozeile angeben.

       $ php -r 'print_r(get_defined_constants());'

   Es muss besonders Acht gegeben werden auf die Ersetzung von Kommandozeilenvariablen und Benutzung von Anführungszeichen.

   > Hinweis:

   > Achten Sie darauf, dass sie keine PHP-Tags übergeben. Die Option -r benötigt diese nicht und löst einen Parser-Fehler aus, falls sie dennoch verwendet werden.

3. Eingabe des PHP-Codes über die Standardeingabe (`stdin`).

   Dies eröffnet die Möglichkeit, PHP-Code dynamisch zu generieren und anschließend an das PHP-Binary zu übergeben, wie in diesem (ausgedachten) Beispiel dargestellt:

       $ some_application | some_filter | php | sort -u > final_output.txt

Die drei Möglichkeiten zur Codeausführung können nicht kombiniert werden.

Wie jede Kommandozeilenanwendung nimmt das PHP-Binary etliche Argumente entgegen, aber auch das PHP-Skript kann Argumente entgegennehmen. Die Anzahl der Argumente, die an ein Skript übergeben werden können, ist nicht von PHP beschränkt (und obwohl die Kommandozeilenumgebung ein Limit für die Anzahl der Zeichen hat, die übergeben werden können, wird dieses im Allgemeinen nicht erreicht werden). Die Argumente, die dem Skript übergeben werden, sind in dem globalen Array $argv gespeichert. Der erste Index (Null) enthält immer den Skriptnamen. Wenn der Code mittels der Option -r ausgeführt wurde, ist der Wert von $argv[0] `"Standard input code"`; vor PHP 7.2.0 war es ein Bindestrich (`-`). Selbiges gilt für Code, welcher über `STDIN` ausgeführt wird.

Die zweite registrierte globale Variable ist $argc, welche die Anzahl der Elemente im Array $argv enthält, (nicht die Anzahl Argumente, die dem Skript übergeben wurden).

Solange die Argumente, welche dem Skript übergeben werden, nicht mit dem Zeichen `-` beginnen, gibt es nichts besonderes zu beachten. Ein Argument zu übergeben, welches mit `-` beginnt, wird jedoch Probleme bereiten, da PHP denkt, dass es das Argument selbst verarbeiten muss, noch bevor das Skript ausgeführt wird. Nutzen Sie das Argument-Trennzeichen `--`, um dies zu vermeiden. Nachdem dieses Trennzeichen von PHP geparst wurde, wird jedes folgende Argument unangetastet an das Skript weitergereicht.

    # Dies führt nicht den angegebenen Code aus, sondern zeigt die Optionen von PHP an
    $ php -r 'var_dump($argv);' -h
    Usage: php [options] [-f] <file> [args...]
    [...]

    # Dies übergibt das Argument '-h' an Ihr Skript und zeigt die Optionen von PHP nicht an
    $ php -r 'var_dump($argv);' -- -h
    array(2) {
      [0]=>
      string(1) "-"
      [1]=>
      string(2) "-h"
    }

Es gibt auf Unix-Systemen jedoch einen weiteren Weg, um PHP für Kommandozeilenskripte zu verwenden. Sie können ein Skript erstellen, in dem die erste Zeile mit `#!/usr/bin/php` beginnt (oder wie auch immer der Pfad zu Ihrer PHP-CLI-Binärdatei ist). Nachfolgend können Sie normalen PHP-Code innerhalb der PHP-Start- und -End-Tags verwenden. Sobald Sie die Datei ausführbar gemacht haben (beispielsweise mittels chmod +x test), kann Ihr Skript wie ein normales Kommandozeilen- oder Perl-Skript gestartet werden.

Beispiel #1 PHP als Shellskript ausführen

    #!/usr/bin/php
    <?php
    var_dump($argv);
    ?>

Angenommen, die Datei heißt test und befindet sich im aktuellen Verzeichnis, dann können wir nun folgendes tun:

    $ chmod +x test
    $ ./test -h -- foo
    array(4) {
      [0]=>
      string(6) "./test"
      [1]=>
      string(2) "-h"
      [2]=>
      string(2) "--"
      [3]=>
      string(3) "foo"
    }

Wie zu sehen ist, muss in diesem Fall keine besondere Rücksicht auf die Übergabe von Parametern genommen werden, die mit `-` beginnen.

Die ausführbare PHP-Datei kann verwendet werden, um PHP-Skripte vollkommen unabhängig von einem Webserver auszuführen. Auf Unix-Systemen sollte die spezielle erste Zeile `#!` ("Shebang") zu PHP-Skripten hinzugefügt werden, damit das System automatisch herausfinden kann, welches Programm zur Ausführung der Datei genutzt werden soll. Auf Windows-Systemen ist es möglich, php.exe mit der Doppelklick-Option der Erweiterung `.php` zu verknüpfen. Es kann auch eine Batchdatei erstellt werden, um das Skript von PHP ausführen zu lassen. Die erste Zeile, die dem Skript hinzugefügt wird, damit es unter UNIX läuft, stört unter Windows nicht, so dass auf diese Weise problemlos plattformübergreifende Programme geschrieben werden können. Im Folgenden wird anhand eines einfachen Beispiels gezeigt, wie ein PHP-Kommandozeilenprogramm geschrieben wird.

Beispiel #2 Ein Skript, das von der Kommandozeile aus ausgeführt werden soll (script.php)

    #!/usr/bin/php
    <?php

    if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
    ?>

    Das ist ein Kommandozeilenprogramm in PHP mit einer Option.

      Verwendung:
      <?php echo $argv[0]; ?> <option>

      <option> kann ein Wort sein, das Sie gerne
      ausgeben möchten. Mit den Optionen --help,
      -help, -h oder -? bekommen Sie diese Hilfe.

    <?php
    } else {
        echo $argv[1];
    }
    ?>

In dem oben beschriebenen Skript haben wir die erste Zeile dazu verwendet, anzugeben, dass die Datei von PHP ausgeführt werden soll. Wir arbeiten hier mit einer CLI-Version, deswegen werden keine HTTP-Header ausgegeben.

In dem obigen Programm wird zuerst überprüft, ob das notwendige Argument angeben ist (zusätzlich zum Skriptnamen, welcher auch gezählt wird). Wenn nicht, oder wenn das Argument --help, -help, -h oder -? war, wird eine Hilfe-Nachricht ausgegeben, welche $argv[0] nutzt, um den auf der Kommandozeile eingegebenen Skript-Namen auszugeben. Andernfalls wird das Argument genauso ausgegeben, wie es übergeben wurde.

Um das obige Skript unter UNIX auszuführen, muss es zuerst ausführbar gemacht werden, und danach einfach als script.php GebeDasHierAus oder script.php -h aufgerufen werden. Unter Windows kann zu diesem Zweck eine Batchdatei erstellt werden:

Beispiel #3 Batchdatei zur Ausführung eines Kommandozeilen-Skripts in PHP (script.bat)

    @echo OFF
    "C:\php\php.exe" script.php %*

Angenommen, das obige Programm wurde script.php genannt und die CLI php.exe hat den Pfad C:\php\php.exe, so wird diese Batchdatei es mit allen übergebenen Argumenten aufrufen: script.bat GebeDasHierAus oder script.bat -h.

Siehe auch die Readline-Erweiterung für weitere Funktionen, um PHP-Kommandozeilenanwendungen zu verbessern.

Unter Windows kann PHP so konfiguiert werden, dass es auch ausgeführt wird, wenn weder C:\php\php.exe angegeben wird, noch die Dateierweiterung `.php` genutzt wird. Siehe dazu die Dokumentation zur PHP-Kommandozeile unter Microsoft Windows.

> Hinweis:

> Unter Windows wird empfohlen, PHP unter einem echten User-Account auszuführen. Wird es unter einem Netzwerk-Account ausgeführt, werden bestimmte Operationen fehlschlagen, weil "keine Zuordnung zwischen Kontennamen und Sicherheits-IDs erfolgte".

## Ein- und Ausgabestreams

Die CLI SAPI definiert einige Konstanten für Ein- und Ausgabestreams, um das Erstellen von Kommandozeilenanwendungen zu erleichtern.

CLI-spezifische Konstanten
Konstante | Beschreibung
--- | ---
`STDIN` | Ein schon geöffneter Stream auf `stdin`. Dies erspart das Öffnen mit
    <?php
    $stdin = fopen('php://stdin', 'r');
    ?>
Wenn sie einzelne Zeilen von `stdin` lesen wollen, können Sie folgendes Code-Fragment verwenden:
    <?php
    $line = trim(fgets(STDIN)); // liest eine Zeile von STDIN
    fscanf(STDIN, "%d\n", $number); // liest eine Zahl von STDIN
    ?>
`STDOUT` | Ein schon geöffneter Stream auf `stdout`. Das erspart das Öffnen mit
    <?php
    $stdout = fopen('php://stdout', 'w');
    ?>
`STDERR` | Ein schon geöffneter Stream auf `stderr`. Das erspart das Öffnen mit
    <?php
    $stderr = fopen('php://stderr', 'w');
    ?>

Angesichts des oben Genannten, brauchen Sie beispielsweise nicht selbst einen Stream für `stderr` öffnen, sondern können einfach die Konstante anstelle der Ressource verwenden:

    php -r 'fwrite(STDERR, "stderr\n");'

Sie brauchen diese Streams nicht explizit zu schließen, weil sie automatisch von PHP geschlossen werden, wenn Ihr Skript endet.

> Hinweis:

> Diese Konstanten sind nicht verfügbar, wenn ein PHP Skript von `stdin` eingelesen wird.

## Interaktive Shell

Wenn PHP mit der Option --with-readline kompiliert wurde, bietet die CLI SAPI mit der Option -a eine interaktive Shell an. Von PHP 7.1.0 an steht die interaktive Shell auch unter Windows zu Verfügung, wenn die readline-Erweiterung aktiviert ist.

Mittels der interaktiven Shell können Sie PHP-Code eingeben und direkt ausführen lassen.

Beispiel #1 Ausführung von Code in der interaktiven Shell

    $ php -a
    Interactive shell

    php > echo 5+8;
    13
    php > function addTwo($n)
    php > {
    php { return $n + 2;
    php { }
    php > var_dump(addtwo(2));
    int(4)
    php >

Die interaktive Shell bietet auch Tabulator-Autovervollständigung für Funktionen, Konstanten, Klassen, Variablen, statische Methoden und Klassenkonstanten.

Beispiel #2 Tabulator-Autovervollständigung

Wenn es mehrere mögliche Vervollständigungen gibt, wird durch zweimaliges Drücken der Tabulator-Taste eine Liste dieser Vervollständigungen angezeigt:

    php > strp[TAB][TAB]
    strpbrk   strpos    strptime
    php > strp

Wenn es nur eine mögliche Vervollständigung gibt, führt ein einmaliges Drücken der Tabulator-Taste zur Vervollständigung der Zeile:

    php > strpt[TAB]ime(

Autovervollständigung funktioniert auch für Namen, welche bereits während dieser interaktiven Session definiert wurden:

    php > $fooThisIsAReallyLongVariableName = 42;
    php > $foo[TAB]ThisIsAReallyLongVariableName

Die interaktive Shell speichert den Verlauf von zuletzt eingegeben Zeilen, auf die mittels der Pfeiltasten zugegriffen werden kann. Der Verlauf wird in der Datei ~/.php_history gespeichert. Seit PHP 8.4.0 kann der Pfad zur History-Datei mit der Umgebungsvariablen PHP_HISTFILE festgelegt werden.

Die CLI SAPI bietet die php.ini-Optionen `cli.pager` und `cli.prompt`. Die Option `cli.pager` erlaubt einem externen Programm (wie etwa less) als Pager für die Ausgabe zu agieren, anstatt dass diese direkt ausgegeben wird. Die Option `cli.prompt` erlaubt das Ändern der `php >`-Eingabeaufforderung.

Es ist auch möglich, die php.ini-Optionen in der interaktiven Shell zu setzen, indem man eine Kurzschreibweise verwendet.

Beispiel #3 Setzen von php.ini-Optionen in der interaktiven Shell

Die Option `cli.prompt`:

    php > #cli.prompt=hello world :>
    hello world :>

Mittels Backticks kann PHP-Code in der Eingabeaufforderung ausgeführt werden:

    php > #cli.prompt=`echo date('H:i:s');` php >
    15:49:35 php > echo 'hi';
    hi
    15:49:43 php > sleep(2);
    15:49:45 php >

Setzen des Pagers auf less:

    php > #cli.pager=less
    php > phpinfo();
    (output displayed in less)
    php >

Die Option `cli.prompt` unterstützt einige Escape-Sequenzen.

`cli.prompt`-Escape-Sequenzen
Sequenzen | Beschreibung
--- | ---
`\e` | Wird verwendet, um Farben zur Eingabeaufforderung hinzuzufügen. Ein Beispiel: `\e[032m\v \e[031m\b \e[34m\> \e[0m`
`\v` | Die PHP-Version.
`\b` | Gibt an, in welchem Block sich PHP befindet. Zum Beispiel gibt `/*` an, dass man sich gerade in einem mehrzeiligen Kommentar befindet. Der äußerste Block ist `php`.
`\>` | Gibt das Eingabeaufforderungszeichen an. Standardmäßig ist dies `>`, ändert sich jedoch, wenn sich die Shell innerhalb eines nicht beendeten Blocks oder Strings befindet. Mögliche Zeichen sind: `' " { ( >`

> Hinweis:

> Dateien, die mit auto_prepend_file und auto_append_file eingebunden wurden, werden in diesem Modus mit einigen Einschränkungen geparst - z. B. müssen Funktionen vor dem Aufruf definiert werden.

## Interaktiver Modus

Wenn die readline-Erweiterung nicht verfügbar ist, wurde vor PHP 8.1.0 durch den Aufruf von CLI SAPI mit der Option -a in den interaktiven Modus gewechselt. In diesem Modus muss ein komplettes PHP-Skript über STDIN übergeben werden, das nach dem Beenden mit ``CTRL` +`D`` (POSIX) oder ``CTRL` +`Z`` gefolgt von `ENTER` (Windows) ausgewertet wird. Dies ist im Grunde dasselbe wie der Aufruf von CLI SAPI ohne die Option -a.

Seit PHP 8.1.0 schlägt der Aufruf von CLI SAPI mit der Option -a fehl, wenn die readline-Erweiterung nicht verfügbar ist.

## Eingebauter Webserver

Warnung

Dieser Webserver wurde entwickelt, um bei der Anwendungsentwicklung zu helfen. Er kann ebenso für Testzwecke und für Anwendungsdemonstrationen nützlich sein, die in kontrollierten Umgebungen ausgeführt werden. Er ist nicht als voll funktioneller Webserver gedacht. Er sollte nicht in einem öffentlichen Netzwerk verwendet werden.

Die CLI SAPI bietet einen eingebauten Webserver.

Der Webserver läuft nur mit einem single-threaded Prozess, sodass PHP-Anwendungen nicht weiter ausgeführt werden, wenn eine Anfrage blockiert wird.

URI-Anfragen werden vom aktuellen Arbeitsverzeichnis ausgehend ausgeliefert, sofern nicht die -t Option genutzt wurde um ein explizites Document-Root anzugeben. Wenn eine URI-Anfrage keine Datei angibt, wird entweder index.php oder index.html aus dem aufgerufenen Verzeichnis zurückgegeben. Wenn beide Dateien nicht existieren, wird die Suche von index.php und index.html im übergeordneten Verzeichnis fortgesetzt usw., bis eine gefunden wurde, oder das Document-Root erreicht wurde. Wurde eine index.php oder index.html gefunden, wird sie zurückgegeben und $_SERVER['PATH_INFO'] wird auf den abschließenden Teil des URI gesetzt. Andernfalls wird ein 404-Antwortcode zurückgeben.

Wenn auf der Kommandozeile beim Starten des Webservers eine PHP-Datei angegeben wird, wird diese als "Router"-Skript verwendet. Dieses Skript wird dann zu Beginn jeder HTTP-Anfrage gestartet. Wenn dieses Skript `false` zurückgibt, dann wird die angefragte Ressource direkt zurückgegeben. Andernfalls wird die Ausgabe des Skripts zurückgegeben.

Standard-MIME-Typen werden für Dateien mit den folgenden Erweiterungen zurückgegeben: `.3gp`, `.apk`, `.avi`, `.bmp`, `.css`, `.csv`, `.doc`, `.docx`, `.flac`, `.gif`, `.gz`, `.gzip`, `.htm`, `.html`, `.ics`, `.jpe`, `.jpeg`, `.jpg`, `.js`, `.kml`, `.kmz`, `.m4a`, `.mov`, `.mp3`, `.mp4`, `.mpeg`, `.mpg`, `.odp`, `.ods`, `.odt`, `.oga`, `.ogg`, `.ogv`, `.pdf`, `.png`, `.pps`, `.pptx`, `.qt`, `.svg`, `.swf`, `.tar`, `.text`, `.tif`, `.txt`, `.wav`, `.webm`, `.wmv`, `.xls`, `.xlsx`, `.xml`, `.xsl`, `.xsd`, `.zip` .

Seit PHP 7.4.0 kann der eingebaute Webserver so konfiguriert werden, dass mehrere Worker geforkt werden können, um Code zu testen, der mehrere gleichzeitige Anfragen erfordert. Dazu muss die Umgebungsvariable PHP_CLI_SERVER_WORKERS auf die Zahl der gewünschten Worker gesetzt werden, bevor der Server gestartet wird.

> Hinweis: Dieses Feature wird unter Windows nicht unterstützt.

Warnung

Dieses experimentelle Feature ist nicht für den Produktionseinsatz vorgesehen. Der eingebaute Webserver ist grundsätzlich nicht für den Produktionseinsatz vorgesehen.

Beispiel #1 Starten des Webservers

    $ cd ~/public_html
    $ php -S localhost:8000

Die Kommandozeile wird ausgeben:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit

Nach URI-Anfragen für http://localhost:8000/ und http://localhost:8000/myscript.html wird die Kommandozeile in etwa so aussehen:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:43:28 2011
    Listening on localhost:8000
    Document root is /home/me/public_html
    Press Ctrl-C to quit.
    [Thu Jul 21 10:48:48 2011] ::1:39144 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39146 GET / - Request read
    [Thu Jul 21 10:48:50 2011] ::1:39147 GET /favicon.ico - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39148 GET /myscript.html - Request read
    [Thu Jul 21 10:48:52 2011] ::1:39149 GET /favicon.ico - Request read

Es ist zu beachten, dass bis zu PHP 7.4.0 symbolisch verknüpfte statische Ressourcen unter Windows nicht erreichbar waren, es sei denn, das Router-Skript würde diese verarbeiten.

Beispiel #2 Starten mit einer expliziten Document-Root

    $ cd ~/public_html
    $ php -S localhost:8000 -t foo/

Die Kommandozeile wird ausgeben:

    PHP 5.4.0 Development Server started at Thu Jul 21 10:50:26 2011
    Listening on localhost:8000
    Document root is /home/me/public_html/foo
    Press Ctrl-C to quit

Beispiel #3 Nutzung eines Router-Skripts

In diesem Beispiel werden bei Anfragen nach Bildern diese direkt angezeigt; bei Anfragen nach HTML-Dateien wird stattdessen "Willkommen in PHP!" angezeigt.

    <?php
    // router.php
    if (preg_match('/\.(?:png|jpg|jpeg|gif)$/', $_SERVER["REQUEST_URI"])) {
        return false; // Liefere die angefragte Ressource direkt aus
    } else {
        echo "<p>Willkommen in PHP!</p>";
    }
    ?>

    $ php -S localhost:8000 router.php

Beispiel #4 Prüfung auf die Verwendung des CLI-Webservers

Um ein Framework-Router-Skript sowohl während der Entwicklung mit dem CLI-Webserver als auch später mit einem Produktions-Webserver zu verwenden:

    <?php
    // router.php
    if (php_sapi_name() == 'cli-server') {
        /* statische Assets weiterleiten und false zurückgeben */
    }
    /* weiter mit den normalen index.php-Operationen */
    ?>

    $ php -S localhost:8000 router.php

Beispiel #5 Behandlung nicht unterstützter Dateitypen

Wenn Sie statische Ressourcen ausliefern müssen, deren MIME-Typ vom CLI-Webserver nicht unterstützt wird, verwenden Sie:

    <?php
    // router.php
    $path = pathinfo($_SERVER["SCRIPT_FILENAME"]);
    if ($path["extension"] == "el") {
        header("Content-Type: text/x-script.elisp");
        readfile($_SERVER["SCRIPT_FILENAME"]);
    }
    else {
        return FALSE;
    }
    ?>

    $ php -S localhost:8000 router.php

Beispiel #6 Zugriff auf den CLI-Webserver von anderen Computern aus

Sie können den Webserver wie folgt auf Port 8000 für jeden zugänglich machen:

    $ php -S 0.0.0.0:8000

Warnung

Der eingebaute Webserver sollte nicht in einem öffentlichen Netzwerk verwendet werden.

## INI-Einstellungen

CLI-SAPI-Konfigurations-Direktiven
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
cli_server.color | "0" | `INI_ALL` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`cli_server.color` bool

  Gibt an, ob der eingebaute Webserver ANSI-Color-Codes für Ausgaben auf die Kommandozeile nutzen soll.

# Garbage Collection (Speicherbereinigung)

## Inhaltsverzeichnis

- Grundlagen des Zählens von Referenzen
- Sammeln zyklischer Referenzen
- Leistungsrelevante Überlegungen

Dieser Abschnitt erklärt die Vorzüge der neuen Garbage Collection (auch bekannt als GC), die ein Bestandteil von PHP 5.3 ist.

## Grundlagen des Zählens von Referenzen

Eine PHP-Variable wird in einem Container namens "zval" gespeichert. Ein zval-Container enthält neben dem Typ und dem Wert der Variablen noch zwei weitere Informationen. Die erste heißt "is_ref" und ist ein boolescher Wert, der angibt, ob die Variable Teil einer "Referenzmenge" ist oder nicht. Mit diesem Bit kann die PHP-Engine zwischen normalen Variablen und Referenzen unterscheiden. Da PHP mit dem &-Operator erzeugte benutzerdefinierte Referenzen zulässt, hat ein zval-Container auch einen internen Mechanismus zum Zählen von Referenzen, um die Speichernutzung zu optimieren. Diese zweite zusätzliche Information wird "refcount" genannt und enthält die Anzahl der Variablennamen (auch Symbole genannt), die auf diesen einen zval-Container verweisen. Alle Symbole sind in einer Symboltabelle gespeichert, von denen es eine pro Bereich gibt. Es gibt einen Bereich für das Hauptskript (d. h. das vom Browser angeforderte), sowie einen für jede Funktion oder Methode.

Ein zval-Container wird erstellt, wenn eine neue Variable mit einem konstanten Wert erstellt wird, z. B.:

Beispiel #1 Erstellen eines neuen zval-Containers

    <?php
    $a = "new string";
    ?>

In diesem Fall wird der neue Symbolname `a` im aktuellen Bereich erstellt und ein neuer Variablencontainer mit dem Typ string und dem Wert `new string` angelegt. Das Bit "is_ref" ist standardmäßig auf `false` gesetzt, weil noch keine benutzerdefinierte Referenz erstellt wurde. Der "refcount" ist auf `1` gesetzt, da es nur ein Symbol gibt, das diesen Variablencontainer verwendet. Es ist zu beachten, dass Referenzen (d. h. "is_ref" ist `true`) mit "refcount" `1` so behandelt werden, als ob sie keine Referenzen wären (d. h. als ob "is_ref" `false` wäre). Wenn » Xdebug installiert ist, kann xdebug_debug_zval() aufgerufen werden, um diese Informationen anzuzeigen.

Beispiel #2 Anzeigen von zval-Informationen

    <?php
    $a = "new string";
    xdebug_debug_zval('a');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    a: (refcount=1, is_ref=0)='new string'

Wenn diese Variable einem anderen Variablennamen zugewiesen wird, erhöht sich der Referenzzähler.

Beispiel #3 Erhöhen des Referenzzählers eines Zval

    <?php
    $a = "new string";
    $b = $a;
    xdebug_debug_zval( 'a' );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    a: (refcount=2, is_ref=0)='new string'

Der Referenzzähler ist hier `2`, weil derselbe Variablencontainer sowohl mit a als auch mit b verknüpft ist. PHP ist schlau genug, den eigentlichen Variablencontainer nicht zu kopieren, wenn es nicht notwendig ist. Variablencontainer werden zerstört, wenn der "refcount" Null erreicht. Der "refcount" wird um eins verringert, wenn ein Symbol, das mit dem Variablencontainer verbunden ist, den Gültigkeitsbereich verlässt (z. B. am Ende einer Funktion) oder wenn ein Symbol nicht mehr zugewiesen ist (z. B. durch den Aufruf von unset()). Das folgende Beispiel zeigt dies:

Beispiel #4 Verringern des zval-Referenzzählers

    <?php
    $a = "new string";
    $c = $b = $a;
    xdebug_debug_zval( 'a' );
    $b = 42;
    xdebug_debug_zval( 'a' );
    unset( $c );
    xdebug_debug_zval( 'a' );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    a: (refcount=3, is_ref=0)='new string'
    a: (refcount=2, is_ref=0)='new string'
    a: (refcount=1, is_ref=0)='new string'

Wenn nun `unset($a);` aufgerufen wird, wird der Variablencontainer einschließlich Typ und Wert aus dem Speicher entfernt.

### Zusammengesetzte Typen

Etwas komplexer wird es bei zusammengesetzten Typen wie Arrays und Objekten. Im Gegensatz zu scalaren Werten speichern Arrays und Objekte ihre Eigenschaften in einer eigenen Symboltabelle. Das bedeutet, dass das folgende Beispiel drei zval-Container erzeugt:

Beispiel #5 Erstellen eines Array-Zvals

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    xdebug_debug_zval( 'a' );
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=1, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42
    )

Oder grafisch

Die drei zval-Container sind: a, meaning und number. Ähnliche Regeln gelten für das Erhöhen und Verringern von "refcounts". Im Folgenden fügen wir dem Array ein weiteres Element hinzu und setzen seinen Wert auf den Inhalt eines bereits vorhandenen Elements:

Beispiel #6 Hinzufügen eines bereits vorhandenen Elements zu einem Array

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    xdebug_debug_zval( 'a' );
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    a: (refcount=1, is_ref=0)=array (
       'meaning' => (refcount=2, is_ref=0)='life',
       'number' => (refcount=1, is_ref=0)=42,
       'life' => (refcount=2, is_ref=0)='life'
    )

Oder grafisch

Aus der obigen Xdebug-Ausgabe geht hervor, dass sowohl das alte als auch das neue Array-Element nun auf einen zval-Container zeigen, dessen "refcount" `2` ist. Obwohl die Xdebug-Ausgabe zwei zval-Container mit dem Wert `'life'` anzeigt, handelt es sich um denselben. Die Funktion xdebug_debug_zval() zeigt dies nicht an, aber man könnte es sehen, wenn man sich auch den Speicherzeiger anzeigen lässt.

Wenn ein Element aus dem Array entfernt wird, ist das so, als würde ein Symbol aus einem Bereich entfernt. Dadurch wird der "refcount" eines Containers, auf den ein Array-Element zeigt, verringert. Auch hier gilt: Wenn der "refcount" Null erreicht, wird der Variablencontainer aus dem Speicher entfernt. Ein weiteres Beispiel soll dies verdeutlichen:

Beispiel #7 Entfernen eines Elements aus einem Array

    <?php
    $a = array( 'meaning' => 'life', 'number' => 42 );
    $a['life'] = $a['meaning'];
    unset( $a['meaning'], $a['number'] );
    xdebug_debug_zval( 'a' );
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    a: (refcount=1, is_ref=0)=array (
       'life' => (refcount=1, is_ref=0)='life'
    )

Interessant wird es nun, wenn das Array selbst als Element des Arrays hinzugefügt wird. Das geschieht im nächsten Beispiel, in dem außerdem ein Referenzoperator eingebaut wird, da PHP sonst eine Kopie erstellen würde:

Beispiel #8 Hinzufügen des Arrays als Element von sich selbst

    <?php
    $a = array( 'one' );
    $a[] =& $a;
    xdebug_debug_zval( 'a' );
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    a: (refcount=2, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=2, is_ref=1)=...
    )

Oder grafisch

Wie man sieht, zeigen nun sowohl die Array-Variable (a) als auch das zweite Element (1) auf einen Variablencontainer, der einen "refcount" von `2` hat. Das "..." in der obigen Darstellung zeigt, dass es sich um eine Rekursion handelt, was natürlich in diesem Fall bedeutet, dass das "..." zurück auf das ursprüngliche Array zeigt.

Genau wie zuvor wird beim Aufheben einer Variablen das Symbol entfernt, und die Anzahl der Referenzen des Variablencontainers, auf den sie zeigt, wird um eins verringert. Wenn also die Variable $a nach der Ausführung des obigen Codes aufgehoben wird, wird die Anzahl der Referenzen des Variablencontainers, auf den $a und das Element "1" zeigen, um eins verringert, von "2" auf "1". Dies kann wie folgt dargestellt werden:

Beispiel #9 Aufheben von $a

    (refcount=1, is_ref=1)=array (
       0 => (refcount=1, is_ref=0)='one',
       1 => (refcount=1, is_ref=1)=...
    )

Oder grafisch

### Probleme bei der Bereinigung

Obwohl es in keinem Bereich mehr ein Symbol gibt, das auf diese Struktur zeigt, kann sie nicht bereinigt werden, weil das Array-Element "1" immer noch auf dasselbe Array zeigt. Da es kein externes Symbol gibt, das darauf verweist, gibt es für den Benutzer keine Möglichkeit, diese Struktur zu bereinigen, was zu einem Speicherleck führt. Glücklicherweise bereinigt PHP diese Datenstruktur am Ende der Anfrage, aber bis dahin nimmt sie wertvollen Speicherplatz in Anspruch. Diese Situation tritt häufig auf, wenn Parsing-Algorithmen oder andere Dinge implementiert werden, bei denen ein untergeordnetes Element auf ein "übergeordnetes" Element zurückverweist. Die gleiche Situation kann natürlich auch bei Objekten eintreten, wobei dies sogar wahrscheinlicher ist, da Objekte immer implizit "per Referenz" verwendet werden.

Das ist vielleicht kein Problem, wenn es nur ein- oder zweimal vorkommt, aber wenn es Tausende oder sogar Millionen solcher Speicherverluste gibt, fängt es natürlich an, zum Problem zu werden. Besonders problematisch ist dies bei lang laufenden Skripten, z. B. Daemons, bei denen die Anfrage im Grunde nie endet, oder bei großen Mengen von Unit-Tests. Letzteres führte zu Problemen bei der Ausführung der Unit-Tests für die Template-Komponente der eZ Components-Bibliothek. In einigen Fällen wurden über 2 GB Speicher benötigt, die der Testserver nicht zur Verfügung hatte.

## Sammeln zyklischer Referenzen

In der Vergangenheit konnten referenzzählende Speichermechanismen, wie der von PHP verwendete, zyklische Referenzspeicherlecks nicht beheben. Seit Version 5.3.0 implementiert PHP jedoch den synchronen Algorithmus aus der Abhandlung » Concurrent Cycle Collection in Reference Counted Systems, die dieses Problem behandelt.

Eine vollständige Erklärung der Funktionsweise des Algorithmus würde den Rahmen dieses Abschnitts etwas sprengen, aber die Grundlagen werden hier erläutert. Zunächst müssen ein paar Grundregeln festgelegt werden. Wenn ein Referenzzähler erhöht wird, ist er noch in Gebrauch und daher kein Garbage. Wenn der Referenzzähler verringert wird und Null erreicht, kann das Zval freigegeben werden. Das bedeutet, dass problematische Zyklen nur dann erzeugt werden können, wenn ein refcount-Argument auf einen Wert ungleich Null verringert wird. Damit kann festgestellt werden, welche Teile in einem problematischen Zyklus Garbage sind, indem geprüft wird, ob es möglich ist, ihren Referenzzähler um eins zu verringern, und dann geprüft wird, welche der Zvals einen Referenzzähler von Null haben.

Um zu vermeiden, dass die Überprüfung von problematischen Zyklen bei jeder möglichen Verringerung eines Referenzzählers aufgerufen werden muss, legt der Algorithmus stattdessen alle möglichen Wurzeln (Zvals) in den "Wurzelpuffer" (und markiert sie "lila"). Er sorgt auch dafür, dass jede mögliche Wurzel nur einmal im Puffer landet. Erst wenn der Wurzelpuffer voll ist, beginnt der Sammelmechanismus für alle verschiedenen Zvals darin. Siehe Schritt A in der Abbildung oben.

In Schritt B führt der Algorithmus bei allen möglichen Wurzeln eine Tiefensuche durch, um die Referenzzähler jedes gefundenen Zvals um eins zu verringern. Dabei wird darauf geachtet, dass der Referenzzähler desselben Zvals nicht zweimal verringert wird (indem sie als "grau" markiert werden). In Schritt C führt der Algorithmus erneut eine Tiefensuche bei jedem Wurzelknoten aus, um den Referenzzähler jedes Zvals erneut zu überprüfen. Stellt er fest, dass der Referenzzähler Null ist, wird das Zval als "weiß" markiert (in der Abbildung blau). Ist er größer als Null, wird die Verringerung des Refcount um eins mit einer Tiefensuche von diesem Punkt an rückgängig gemacht, und die Zvals werden wieder "schwarz" markiert. Im letzten Schritt (D) geht der Algorithmus über den Wurzelpuffer und entfernt die Zval-Wurzeln von dort, wobei er gleichzeitig überprüft, welche Zvals im vorherigen Schritt als "weiß" markiert wurden. Jedes Zval, das als "weiß" markiert wurde, wird freigegeben.

Nachdem nun ein grundlegendes Verständnis für die Funktionsweise des Algorithmus vorhanden ist, wird nun erläutert, wie dieser in PHP integriert ist. Standardmäßig ist der Garbage Collector von PHP aktiviert, aber es gibt eine php.ini-Einstellung, mit der dies geändert werden kann: zend.enable_gc.

Wenn der Garbage Collector aktiviert ist, wird der oben beschriebene Algorithmus zum Finden von Zyklen immer dann ausgeführt, wenn der Wurzelpuffer voll ist. Der Wurzelpuffer hat eine feste Größe von 10.000 möglichen Wurzeln (obwohl man dies ändern kann, indem man im PHP-Quellcode in `Zend/zend_gc.c` die Konstante `GC_THRESHOLD_DEFAULT` ändert und PHP neu kompiliert). Wenn der Garbage Collector deaktiviert ist, wird der Algorithmus zum Finden von Zyklen nie ausgeführt. Allerdings werden mögliche Wurzeln immer im Wurzelpuffer aufgezeichnet, unabhängig davon, ob der Mechanismus der Garbage Collection mit dieser Konfigurationseinstellung aktiviert wurde.

Wenn der Wurzelpuffer bei deaktiviertem Mechanismus der Garbage Collection vollständig mit möglichen Wurzeln gefüllt ist, werden weitere mögliche Wurzeln einfach nicht aufgezeichnet. Die möglichen Wurzeln, die nicht aufgezeichnet werden, werden vom Algorithmus nie analysiert. Wären sie Teil eines zirkulären Referenzzyklus, würden sie nie bereinigt werden und ein Speicherleck verursachen.

Dass mögliche Wurzeln aufgezeichnet werden, auch wenn der Mechanismus deaktiviert wurde, liegt daran, dass es schneller ist, mögliche Wurzeln aufzuzeichnen, als jedes Mal, wenn eine mögliche Wurzel gefunden wurde, zu prüfen, ob der Mechanismus aktiviert ist. Der Mechanismus der Garbage Collection und Analyse selbst kann jedoch sehr viel Zeit in Anspruch nehmen.

Neben der Änderung der Konfigurationseinstellung zend.enable_gc ist es auch möglich, den Mechanismus der Garbage Collection zu aktivieren oder zu deaktivieren, indem man gc_enable() bzw. gc_disable() aufruft. Diese Funktionen haben den gleichen Effekt wie die Konfigurationseinstellung, mit der der Mechanismus aktiviert oder deaktiviert wird. Es ist auch möglich, das Sammeln von Zyklen zu erzwingen, selbst wenn der Wurzelpuffer noch nicht voll ist. Dazu kann die Funktion gc_collect_cycles() verwendet werden. Diese Funktion ermittelt, wieviele Zyklen durch den Algorithmus gesammelt wurden.

Der Grund für die Möglichkeit, den Mechanismus zu aktivieren und zu deaktivieren und die Sammlung von Zyklen selbst einzuleiten, besteht darin, dass einige Teile einer Anwendung sehr zeitkritisch sein könnten. In diesen Fällen ist es vielleicht nicht erwünscht, dass der Mechanismus der Garbage Collection ausgelöst wird. Wenn die Garbage Collection für bestimmte Teile einer Anwendung ausgeschaltet wird, besteht natürlich die Gefahr, dass Speicherlecks entstehen, weil einige mögliche Wurzeln nicht in den begrenzten Wurzelpuffer passen. Daher ist es wahrscheinlich ratsam, gc_collect_cycles() kurz vor dem Aufruf von gc_disable() aufzurufen, um den Speicher freizugeben, der durch eventuell bereits im Wurzelpuffer aufgezeichnete Wurzeln verloren gegangen sein könnte. Dadurch bleibt ein leerer Puffer übrig, sodass mehr Platz für die Speicherung möglicher Wurzeln vorhanden ist, während der Mechanismus zum Sammeln von Zyklen deaktiviert ist.

## Leistungsrelevante Überlegungen

Wie bereits im vorangegangenen Abschnitt erwähnt, wirkt sich das einfache Sammeln der möglichen Wurzeln nur geringfügig auf die Leistung aus. Dies gilt jedoch nur im Vergleich zwischen PHP 5.2 und PHP 5.3. Obwohl die Aufzeichnung möglicher Wurzeln langsamer ist als wenn sie wie in PHP 5.2 überhaupt nicht aufgezeichnet werden, haben andere Änderungen an der PHP-Laufzeit in PHP 5.3 verhindert, dass dieser spezielle Leistungsverlust überhaupt sichtbar wird.

Es gibt zwei Hauptbereiche, in denen die Leistung betroffen ist. Der erste Bereich ist die verringerte Speichernutzung und der zweite Bereich ist die Laufzeitverzögerung, wenn der Mechanismus der Garbage Collection seine Speicherbereinigungen durchführt. Um diese beiden Punkte geht es im Folgenden.

### Verringerte Speichernutzung

In erster Linie soll durch die Implementierung des Mechanismus der Garbage Collection der Speicherverbrauch reduziert werden, indem zirkulär referenzierte Variablen gelöscht werden, sobald die Voraussetzungen dafür erfüllt sind. In der PHP-Implementierung geschieht dies, sobald der Wurzelpuffer voll ist oder wenn die Funktion gc_collect_cycles() aufgerufen wird. Im folgenden Diagramm wird der Speicherverbrauch eines Skripts sowohl in PHP 5.2 als auch in PHP 5.3 dargestellt, wobei der Basisspeicher, den PHP selbst beim Starten verwendet, nicht berücksichtigt wird.

Beispiel #1 Beispiel für die Speichernutzung

    <?php
    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    $baseMemory = memory_get_usage();

    for ( $i = 0; $i <= 100000; $i++ )
    {
        $a = new Foo;
        $a->self = $a;
        if ( $i % 500 === 0 )
        {
            echo sprintf( '%8d: ', $i ), memory_get_usage() - $baseMemory, "\n";
        }
    }
    ?>

In diesem sehr theoretischen Beispiel wird ein Objekt erstellt, in dem eine Eigenschaft so gesetzt wird, dass sie auf das Objekt selbst zurückverweist. Wenn die Variable $a im Skript in der nächsten Iteration der Schleife neu zugewiesen wird, kommt es normalerweise zu einem Speicherleck. In diesem Fall sind zwei zval-Container betroffen (das Objekt zval und die Eigenschaft zval), aber es wird nur eine mögliche Wurzel gefunden: die Variable, die nicht gesetzt wurde. Wenn der Wurzelpuffer nach 10.000 Iterationen (mit insgesamt 10.000 möglichen Wurzeln) voll ist, setzt der Mechanismus der Garbage Collection ein und gibt den mit diesen möglichen Wurzeln verbundenen Speicher frei. Dies ist sehr deutlich in der gezackten Grafik der Speichernutzung für PHP 5.3 zu sehen. Nach jeweils 10.000 Iterationen schaltet sich der Mechanismus ein und gibt den Speicher frei, der mit den zirkulär referenzierten Variablen verbunden ist. Der Mechanismus selbst muss in diesem Beispiel nicht viel Arbeit leisten, da die Struktur, die das Leck aufweist, extrem einfach ist. Aus dem Diagramm ist ersichtlich, dass der maximale Speicherverbrauch in PHP 5.3 etwa 9 MB beträgt, während der Speicherverbrauch in PHP 5.2 stetig ansteigt.

### Verzögerungen in der Laufzeit

Der zweite Bereich, in dem der Mechanismus der Garbage Collection die Leistung beeinflusst, ist die Zeit, die benötigt wird, wenn die Garbage Collection einsetzt, um den "ausgelaufenen" Speicher freizugeben. Um zu sehen, wieviel das ist, wird das vorherige Skript leicht abgeändert, um eine größere Anzahl von Iterationen zu ermöglichen und die Zahlen für die zwischenzeitliche Speichernutzung zu entfernen. Das zweite Skript ist hier:

Beispiel #2 Einfluss der GC auf die Leistung

    <?php
    class Foo
    {
        public $var = '3.14159265359';
        public $self;
    }

    for ( $i = 0; $i <= 1000000; $i++ )
    {
        $a = new Foo;
        $a->self = $a;
    }

    echo memory_get_peak_usage(), "\n";
    ?>

Dieses Skript wird zweimal ausgeführt, einmal ist die Einstellung zend.enable_gc aktiviert und einmal ist sie deaktiviert:

Beispiel #3 Ausführen des obigen Skripts

    time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php
    # und
    time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php

Auf dem verwendeten Rechner scheint der erste Befehl konstant etwa 10,7 Sekunden zu dauern, während der zweite Befehl etwa 11,4 Sekunden benötigt. Das ist eine Verlangsamung um etwa 7%. Der vom Skript maximal benötigte Speicherplatz wird jedoch um 98% von 931 MB auf 10 MB reduziert. Dieser Benchmark ist nicht sehr wissenschaftlich oder gar repräsentativ für reale Anwendungen, aber er zeigt die Vorteile, die dieser Mechanismus der Garbage Collection bei der Speichernutzung bietet. Das Gute daran ist, dass die Verlangsamung bei diesem speziellen Skript immer dieselben 7% beträgt, während die Fähigkeit, Speicher zu sparen, immer mehr Speicher einspart, je mehr zirkuläre Referenzen während der Ausführung des Skripts gefunden werden.

### PHPs interne GC-Statistik

Es ist möglich, PHP etwas mehr Informationen darüber zu entlocken, wie der Mechanismus der Garbage Collection abläuft. Dazu muss PHP jedoch neu kompiliert werden, um den Code für den Benchmark und die Datenerfassung zu aktivieren. Bevor `./configure` mit den gewünschten Optionen ausgeführt wird, muss die Umgebungsvariable `CFLAGS` auf `-DGC_BENCH=1` gesetzt werden. Die folgende Befehlsfolge sollte dafür genügen:

Beispiel #4 PHP neu kompilieren, um das GC-Benchmarking zu aktivieren

    export CFLAGS=-DGC_BENCH=1
    ./config.nice
    make clean
    make

Wenn der obige Beispielcode mit der neu erstellten PHP-Binärdatei erneut ausgeführt wird, wird Folgendes angezeigt, nachdem PHP die Ausführung beendet hat:

Beispiel #5 GC-Statistik

    GC Statistics
    -------------
    Runs:               110
    Collected:          2072204
    Root buffer length: 0
    Root buffer peak:   10000

          Possible            Remove from  Marked
            Root    Buffered     buffer     grey
          --------  --------  -----------  ------
    ZVAL   7175487   1491291    1241690   3611871
    ZOBJ  28506264   1527980     677581   1025731

Die aufschlussreichste Statistik wird im ersten Block angezeigt. Hier ist zu sehen, dass der Mechanismus der Garbage Collection 110 mal ausgeführt wurde und bei diesen 110 Durchläufen insgesamt mehr als 2 Millionen Speicherzuweisungen freigegeben wurden. Nachdem der Mechanismus der Garbage Collection mindestens einmal gelaufen ist, beträgt der "Root buffer peak" immer 10000.

### Zusammenfassung

Im Allgemeinen führt der Garbage Collector in PHP nur dann zu einer Verlangsamung, wenn der Algorithmus für die Zyklussammlung tatsächlich ausgeführt wird, während es bei normalen (kleineren) Skripten zu keinerlei Leistungseinbußen kommen sollte.

In den Fällen, in denen der Mechanismus für die Zyklussammlung bei normalen Skripten ausgeführt wird, ermöglicht die damit verbundene Reduzierung des Speicherbedarfs die gleichzeitige Ausführung von mehr Skripten auf dem Server, da insgesamt weniger Speicher benötigt wird.

Die Vorteile sind am deutlichsten bei länger laufenden Skripten, z. B. bei langen Testsuiten oder Daemon-Skripten. Auch für » PHP-GTK-Anwendungen, die in der Regel länger laufen als Skripte für das Web, sollte der neue Mechanismus einen großen Unterschied in Bezug auf Speicherlecks machen, die sich mit der Zeit einschleichen.

# DTrace Dynamic Tracing (Anwendungsanalyse in Echtzeit)

## Inhaltsverzeichnis

- Einführung in PHP und DTrace
- PHP mit DTrace verwenden
- Verwendung von SystemTap mit statischen PHP-DTrace-Sonden

## Einführung in PHP und DTrace

DTrace ist ein Tracing-Framework, das immer verfügbar ist, einen geringen zusätzlichen Rechenaufwand verursacht und auf vielen Plattformen wie Solaris, macOS, Oracle Linux und BSD zur Verfügung steht. DTrace kann das Verhalten des Betriebssystems und die Ausführung von Benutzerprogrammen verfolgen. Es kann Parameterwerte anzeigen und zur Abschätzung von Leistungsstatistiken verwendet werden. Prüfsonden (Probes) werden durch vom Benutzer erstellte Skripte, die in der DTrace-Skriptsprache D geschrieben sind, überwacht. Dies ermöglicht eine effiziente Analyse der Datenpunkte.

PHP-Sonden, die nicht aktiv vom DTrace-D-Skript eines Benutzers überwacht werden, enthalten keinen Instrumentierungscode, sodass es während der normalen Ausführung der Anwendungen keine Leistungseinbußen gibt. Sonden, die überwacht werden, verursachen im Allgemeinen einen so geringen zusätzlichen Rechenaufwand, dass die Überwachung mit DTrace auf Produktivsystemen möglich ist.

PHP verfügt über USDT-Sonden, die zur Laufzeit ausgelöst werden (USDT: User-level Statically Defined Tracing; statisch definiertes Tracing auf Benutzerebene). Wenn ein D-Skript zum Beispiel PHP's `function-entry`-Sonde überwacht, löst diese Sonde bei jedem Funktionsaufruf den entsprechenden D-Skript-Aktionscode aus. Dieser Aktionscode könnte zum Beispiel die Parameter der Sonde, also z. B. den Speicherort der Quelldatei dieser PHP-Funktion, ausgeben. Oder die Aktion könnte Daten sammeln, z. B. wie oft jede Funktion aufgerufen wird.

Hier werden nur die PHP-USDT-Sonden beschrieben. Um zu erfahren, wie DTrace verwendet werden kann, um beliebige Funktionen und das Verhalten des Betriebssystems zu überwachen, sind die allgemeine und die betriebssystemspezifische DTrace-Literatur zu empfehlen. Es ist zu beachten, dass nicht alle DTrace-Funktionen in allen DTrace-Implementierungen verfügbar sind.

Die statischen DTrace-Sonden in PHP können auf einigen Linux-Distributionen alternativ auch mit SystemTap verwendet werden.

## PHP mit DTrace verwenden

PHP kann auf Plattformen, die DTrace Dynamic Tracing unterstützen, mit statischen DTrace-Sonden konfiguriert werden.

### PHP für statische DTrace-Sonden konfigurieren

Um die DTrace-Unterstützung des Betriebssystems zu aktivieren, siehe die externe plattformspezifische Dokumentation. Unter Oracle Linux muss zum Beispiel ein UEK3-Kernel gebootet und anschließend Folgendes ausgeführt werden:

    # modprobe fasttrap
    # chmod 666 /dev/dtrace/helper

Anstatt `chmod` zu verwenden, kann stattdessen eine ACL-Paketregel verwendet werden, um den Gerätezugriff auf einen bestimmten Benutzer zu beschränken.

PHP mit dem Konfigurationsparameter `--enable-dtrace` kompilieren:

    # ./configure --enable-dtrace ...
    # make
    # make install

Dadurch werden die statischen Sonden im Kern von PHP verfügbar. Alle PHP-Erweiterungen, die ihre eigenen Sonden bereitstellen, müssen separat als dynamische Erweiterungen gebaut werden.

Um Sonden zu aktivieren, muss die Umgebungsvariable USE_ZEND_DTRACE=1 für die PHP-Zielprozesse gesetzt werden.

### Statische DTrace-Sonden im Kern von PHP

Die folgenden statischen Sonden stehen in PHP zur Verfügung
Name der Probe | Beschreibung der Probe | Parameter der Probe
--- | --- | ---
`request-startup` | Wird ausgelöst, wenn eine Anfrage beginnt. | char *file, char *request_uri, char *request_method
`request-shutdown` | Wird ausgelöst, wenn eine Anfrage endet. | char *file, char *request_uri, char *request_method
`compile-file-entry` | Wird ausgelöst, wenn die Kompilierung eines Skripts beginnt. | char *compile_file, char *compile_file_translated
`compile-file-return` | Wird ausgelöst, wenn die Kompilierung eines Skripts endet. | char *compile_file, char *compile_file_translated
`execute-entry` | Wird ausgelöst, wenn ein OpCode-Array ausgeführt wird, z. B. bei Funktionsaufrufen, Includes und wenn ein Generator fortfährt. | char *request_file, int lineno
`execute-return` | Wird nach der Ausführung eines OpCode-Arrays ausgelöst. | char *request_file, int lineno
`function-entry` | Wird ausgelöst, wenn die PHP-Engine in eine PHP-Funktion oder -Methode gelangt. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`function-return` | Wird ausgelöst, wenn die PHP-Engine aus einer PHP-Funktion oder -Methode zurückkehrt. | char *function_name, char *request_file, int lineno, char *classname, char *scope
`exception-thrown` | Wird ausgelöst, wenn eine Exception ausgelöst wird. | char *classname
`exception-caught` | Wird ausgelöst, wenn eine Exception abgefangen wird. | char *classname
`error` | Wird ausgelöst, wenn ein Fehler auftritt, unabhängig von der error_reporting-Stufe. | char *errormsg, char *request_file, int lineno

PHP-Erweiterungen verfügen möglicherweise über zusätzliche statische Sonden.

### Liste statischer DTrace-Sonden in PHP

Um die verfügbaren Sonden aufzulisten, ist es nötig, einen PHP-Prozess zu starten und dann Folgendes auszuführen:

    # dtrace -l

Die Ausgabe wird ungefähr so aussehen:

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
        4   php15271               php               dtrace_compile_file compile-file-entry
        5   php15271               php               dtrace_compile_file compile-file-return
        6   php15271               php                        zend_error error
        7   php15271               php  ZEND_CATCH_SPEC_CONST_CV_HANDLER exception-caught
        8   php15271               php     zend_throw_exception_internal exception-thrown
        9   php15271               php                 dtrace_execute_ex execute-entry
       10   php15271               php           dtrace_execute_internal execute-entry
       11   php15271               php                 dtrace_execute_ex execute-return
       12   php15271               php           dtrace_execute_internal execute-return
       13   php15271               php                 dtrace_execute_ex function-entry
       14   php15271               php                 dtrace_execute_ex function-return
       15   php15271               php              php_request_shutdown request-shutdown
       16   php15271               php               php_request_startup request-startup

Die Werte der Spalte PROVIDER setzen sich aus `php` und der Prozess-ID des aktuell laufenden PHP-Prozesses zusammen.

Wenn der Apache-Webserver läuft, könnte der Modulname zum Beispiel libphp5.so sein, und es gäbe pro laufendem Apache-Prozess einen Auflistungs-Block.

Die Spalte FUNCTION verweist auf den Funktionsnamen der PHP-internen C-Implementierung, in der sich der jeweilige Provider befindet.

Wenn kein PHP-Prozess läuft, werden auch keine PHP-Sonden angezeigt.

### DTrace-Beispiel für PHP

Dieses Beispiel zeigt die grundlegenden Möglichkeiten der DTrace-Skriptsprache D.

Beispiel #1 all_probes.d für die Verfolgung aller statischen PHP-Sonden mit DTrace

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::compile-file-entry
    {
        printf("PHP compile-file-entry\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::compile-file-return
    {
        printf("PHP compile-file-return\n");
        printf("  compile_file              %s\n", copyinstr(arg0));
        printf("  compile_file_translated   %s\n", copyinstr(arg1));
    }

    php*:::error
    {
        printf("PHP error\n");
        printf("  errormsg                  %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
    }

    php*:::exception-caught
    {
        printf("PHP exception-caught\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::exception-thrown
    {
        printf("PHP exception-thrown\n");
        printf("  classname                 %s\n", copyinstr(arg0));
    }

    php*:::execute-entry
    {
        printf("PHP execute-entry\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::execute-return
    {
        printf("PHP execute-return\n");
        printf("  request_file              %s\n", copyinstr(arg0));
        printf("  lineno                    %d\n", (int)arg1);
    }

    php*:::function-entry
    {
        printf("PHP function-entry\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::function-return
    {
        printf("PHP function-return\n");
        printf("  function_name             %s\n", copyinstr(arg0));
        printf("  request_file              %s\n", copyinstr(arg1));
        printf("  lineno                    %d\n", (int)arg2);
        printf("  classname                 %s\n", copyinstr(arg3));
        printf("  scope                     %s\n", copyinstr(arg4));
    }

    php*:::request-shutdown
    {
        printf("PHP request-shutdown\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

    php*:::request-startup
    {
        printf("PHP request-startup\n");
        printf("  file                      %s\n", copyinstr(arg0));
        printf("  request_uri               %s\n", copyinstr(arg1));
        printf("  request_method            %s\n", copyinstr(arg2));
    }

Dieses Skript verwendet dtrace mit der Option `-Z`, damit es auch dann ausgeführt werden kann, wenn gerade kein PHP-Prozess läuft. Ohne diese Option würde das Skript sofort beendet, weil es erkennt, dass keine der zu überwachenden Sonden vorhanden ist.

Das Skript verfolgt während der gesamten Zeit, in der ein PHP-Skript läuft, alle statischen Sondenpunkte des PHP-Kerns.

    # ./all_probes.d

Sobald nun ein PHP-Skript oder eine Anwendung ausgeführt wird, beginnt das überwachende D-Skript, alle Parameter der ausgelösten Sonden auszugeben.

Um die Überwachung abzuschließen, kann das D-Skript mittels ``CTRL`+`C`` beendet werden.

Auf Rechnern mit mehreren CPUs ist die Reihenfolge der Tests möglicherweise nicht sequentiell. Dies hängt davon ab, welche CPU die Sonden verarbeitet hat und wie die Threads zwischen den CPUs wechseln. Die Anzeige der Zeitstempel der Sonden hilft, Verwechslungen zu vermeiden, zum Beispiel:

    php*:::function-entry
    {
          printf("%lld: PHP function-entry ", walltimestamp);
          [ . . .]
    }

### Siehe auch

- OCI8 und DTrace Dynamic Tracing

## Verwendung von SystemTap mit statischen PHP-DTrace-Sonden

Auf einigen Linux-Distributionen kann das Tracing-Tool SystemTap verwendet werden, um die statischen DTrace-Sonden von PHP zu überwachen. Diese Möglichkeit steht mit PHP 5.4.20 und PHP 5.5 zur Verfügung.

### Installation von PHP mit SystemTap

Installieren des SystemTap-SDT-Entwicklungspakets:

    # yum install systemtap-sdt-devel

Installieren von PHP mit aktivierten DTrace-Sonden:

    # ./configure --enable-dtrace ...
    # make

### Auflistung statischer Sonden mittels SystemTap

Die statischen Sonden in PHP können mittels stap aufgelistet werden:

    # stap -l 'process.provider("php").mark("*")' -c 'sapi/cli/php -i'

This outputs:

    process("sapi/cli/php").provider("php").mark("compile__file__entry")
    process("sapi/cli/php").provider("php").mark("compile__file__return")
    process("sapi/cli/php").provider("php").mark("error")
    process("sapi/cli/php").provider("php").mark("exception__caught")
    process("sapi/cli/php").provider("php").mark("exception__thrown")
    process("sapi/cli/php").provider("php").mark("execute__entry")
    process("sapi/cli/php").provider("php").mark("execute__return")
    process("sapi/cli/php").provider("php").mark("function__entry")
    process("sapi/cli/php").provider("php").mark("function__return")
    process("sapi/cli/php").provider("php").mark("request__shutdown")
    process("sapi/cli/php").provider("php").mark("request__startup")

### Beispiel für die Verwendung von SystemTap mit PHP

Beispiel #1 all_probes.stp - Verfolgung aller statischen PHP-Sonden mit SystemTap

    probe process("sapi/cli/php").provider("php").mark("compile__file__entry") {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("compile__file__return") {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", user_string($arg1));
        printf("  compile_file_translated %s\n", user_string($arg2));
    }
    probe process("sapi/cli/php").provider("php").mark("error") {
        printf("Probe error\n");
        printf("  errormsg %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
    }
    probe process("sapi/cli/php").provider("php").mark("exception__caught") {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("exception__thrown") {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", user_string($arg1));
    }
    probe process("sapi/cli/php").provider("php").mark("execute__entry") {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("execute__return") {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", user_string($arg1));
        printf("  lineno %d\n", $arg2);
    }
    probe process("sapi/cli/php").provider("php").mark("function__entry") {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("function__return") {
        printf("Probe function__return: %s\n", user_string($arg1));
        printf(" function_name %s\n", user_string($arg1));
        printf("  request_file %s\n", user_string($arg2));
        printf("  lineno %d\n", $arg3);
        printf("  classname %s\n", user_string($arg4));
        printf("  scope %s\n", user_string($arg5));
    }
    probe process("sapi/cli/php").provider("php").mark("request__shutdown") {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }
    probe process("sapi/cli/php").provider("php").mark("request__startup") {
        printf("Probe request__startup\n");
        printf("  file %s\n", user_string($arg1));
        printf("  request_uri %s\n", user_string($arg2));
        printf("  request_method %s\n", user_string($arg3));
    }

Das obige Skript verfolgt während der gesamten Dauer eines laufenden PHP-Skripts alle statischen Sondenpunkte des PHP-Kerns:

    # stap -c 'sapi/cli/php test.php' all_probes.stp

- HTTP-Authentifizierung mit PHP
- Cookies
- Sessions
- Steuerung von Dateiuploads
  - Dateiuploads mit POST
  - Fehlermeldungen erklärt
  - Häufige Probleme
  - Upload mehrerer Dateien
  - PUT-Unterstützung
  - Siehe auch
- Zugriff auf entfernte Dateien
- Verbindungssteuerung
- Persistente Datenbankverbindungen
- Nutzung der Kommandzeile — Nutzung von PHP auf der Kommandozeile
  - Unterschiede zu anderen SAPIs
  - Optionen — Kommandozeilenoptionen
  - Verwendung — Ausführen von PHP-Dateien
  - I/O Streams — Ein- und Ausgabestreams
  - Interaktive Shell
  - Eingebauter Webserver
  - INI-Einstellungen
- Garbage Collection (Speicherbereinigung)
  - Grundlagen des Zählens von Referenzen
  - Sammeln zyklischer Referenzen
  - Leistungsrelevante Überlegungen
- DTrace Dynamic Tracing (Anwendungsanalyse in Echtzeit)
  - Einführung in PHP und DTrace
  - PHP mit DTrace verwenden
  - Verwendung von SystemTap mit statischen PHP-DTrace-Sonden

# Funktionsreferenz

Tipp

Siehe auch Extension-Liste/-Kategorisierung.

# Das Verhalten von PHP beeinflussen

# APC User Cache

# Einführung

APCu is an in-memory key-value store for PHP. Keys are of type String and values can be any PHP variables. APCu only supports userland caching of variables.

The APCu cache is per-process on Windows, so when using a process-based (rather than thread-based) SAPI, it will not be shared between different processes.

APCu is APC stripped of opcode caching.

The first APCu codebase was versioned 4.0.0, it was forked from the head of the APC master branch at the time. PHP 7 support is available as of APCu 5.0.0. PHP 8 support is available as of APCu 5.1.19.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Laufzeit-Konfiguration

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/apcu.

Tipp

PHP 7 has a separate module (» apcu-bc) for backwards compatibility with APC.

In backward compatibility mode, APCu registers the applicable APC functions with backward compatible prototypes.

Where an APC function accepted `cache_type`, it is simply ignored by the backward compatible version, and omitted from the prototype for the APCu version.

Warnung

As of PHP 8.0.0, apcu-bc is no longer supported.

> Hinweis: On Windows, APCu needs a temp path to exist, and be writable by the web server. It checks the TMP, TEMP and USERPROFILE environment variables in that order and finally tries the WINDOWS directory if none of those are set.

> Hinweis: For more in-depth, highly technical implementation details, see the » developer-supplied TECHNOTES file .

APCu sources can be found » here.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Although the default APCu settings are fine for many installations, serious users should consider tuning the following parameters.

There is one decision to be made configuring APCu. How much memory is going to be allocated to APCu. The ini directive that controls this is `apc.shm_size` Read the sections on this carefully below.

Once the server is running, the `apc.php` script that is bundled with the extension should be copied somewhere into the docroot and viewed with a browser as it provides a detailed analysis of the internal workings of APCu. If GD is enabled in PHP, it will even display some interesting graphs.

If APCu is working, the `Cache full count` number (on the left) will display the number of times the cache has reached maximum capacity and has had to evict entries to free up memory. During eviction, if `apc.ttl` was specified, APCu will first attempt to remove expired entries, i.e. entries whose TTL has either expired, or entries that have no TTL set and haven't been accessed in the last `apc.ttl` seconds. If `apc.ttl` was not set, or removing expired entries did not free up enough space, APCu will clear the entire cache.

The number of evictions should be minimal in a well-configured cache. If the cache is constantly being filled, and thusly forcefully freed, the resulting churning will have disparaging effects on script performance. The easiest way to minimize this number is to allocate more memory for APCu.

When APCu is compiled with mmap support (Memory Mapping), it will use only one memory segment, unlike when APCu is built with SHM (SysV Shared Memory) support that uses multiple memory segments. MMAP does not have a maximum limit like SHM does in `/proc/sys/kernel/shmmax`. In general MMAP support is recommended because it will reclaim the memory faster when the webserver is restarted and all in all reduces memory allocation impact at startup.

APCu configuration options
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
apc.enabled | 1 | `INI_SYSTEM` |
apc.shm_segments | 1 | `INI_SYSTEM` |
apc.shm_size | "32M" | `INI_SYSTEM` |
apc.entries_hint | 512 * apc.shm_size | `INI_SYSTEM` | Prior to APCu 5.1.25, the default was 4096
apc.ttl | 0 | `INI_SYSTEM` |
apc.gc_ttl | 3600 | `INI_SYSTEM` |
apc.mmap_file_mask | NULL | `INI_SYSTEM` |
apc.slam_defense | 0 | `INI_SYSTEM` |
apc.enable_cli | 0 | `INI_SYSTEM` |
apc.use_request_time | 0 | `INI_ALL` | Prior to APCu 5.1.19, the default was `1`.
apc.serializer | "php" | `INI_SYSTEM` | Prior to APCu 5.1.15, the default was `"default"`.
apc.coredump_unmap | 0 | `INI_SYSTEM` |
apc.preload_path | NULL | `INI_SYSTEM` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`apc.enabled` bool
  `apc.enabled` can be set to 0 to disable APC. This is primarily useful when APC is statically compiled into PHP, since there is no other way to disable it (when compiled as a DSO, the `extension` line in `php.ini` can just be commented-out).
`apc.shm_segments` int
  The number of shared memory segments to allocate for the compiler cache. If APC is running out of shared memory but `apc.shm_size` is set as high as the system allows, raising this value might prevent APC from exhausting its memory.
`apc.shm_size` string
  The size of each shared memory segment given by a shorthand notation as described in this FAQ. By default, some systems (including most BSD variants) have very low limits on the size of a shared memory segment.
`apc.entries_hint` int
  A "hint" about the number of distinct variables that might be stored. Set to zero or omit if not sure.
`apc.ttl` int
  Consider cache entries without an explicit TTL to be expired if they have not been accessed in this many seconds. Effectively, this allows such entries to be removed opportunistically during a cache insert, or prior to a full expunge. Note that because removal is opportunistic, entries can still be readable even if they are older than `apc.ttl` seconds. This setting has no effect on cache entries that have an explicit TTL specified.
`apc.gc_ttl` int
  The number of seconds that a cache entry may remain on the garbage-collection list after being removed or invalidated. Entries are eligible for removal if their reference count is zero, or they exceed this time limit. If set to `0`, time-based cleanup is disabled, and entries are only removed when their reference count drops to zero.
`apc.mmap_file_mask` string
  If compiled with MMAP support by using `--enable-mmap` this is the mktemp-style file_mask to pass to the mmap module for determining whether your mmap'ed memory region is going to be file-backed or shared memory backed. For straight file-backed mmap, set it to something like `/tmp/apc.XXXXXX` (exactly 6 `X`s). To use POSIX-style shm_open/mmap put a `.shm` somewhere in your mask. e.g. `/apc.shm.XXXXXX` You can also set it to `/dev/zero` to use your kernel's `/dev/zero` interface to anonymous mmap'ed memory. Leaving it undefined will force an anonymous mmap.
`apc.slam_defense` bool
  On very busy servers whenever you start the server or modify files you can create a race of many processes all trying to cache the same file at the same time. Setting `apc.slam_defense` to `1` can help prevent multiple processes from caching the same file simultaneously by introducing a probability mechanism. If the same key is attempted to be cached within a short period by different processes, it skips the caching for the current process to mitigate potential cache slams.
`apc.enable_cli` int
  Mostly for testing and debugging. Setting this enables APC for the CLI version of PHP. Under normal circumstances, it is not ideal to create, populate and destroy the APC cache on every CLI request, but for various test scenarios it is useful to be able to enable APC for the CLI version of PHP easily.
`apc.serializer` string
  Used to configure APC to use a third party serializer.
`apc.coredump_unmap` bool
  Enables APC handling of signals, such as SIGSEGV, that write core files when signaled. When these signals are received, APC will attempt to unmap the shared memory segment in order to exclude it from the core file. This setting may improve system stability when fatal signals are received and a large APC shared memory segment is configured.
  Warnung

  This feature is potentially dangerous. Unmapping the shared memory segment in a fatal signal handler may cause undefined behaviour if a fatal error occurs.

  > Hinweis: Although some kernels may provide a facility to ignore various types of shared memory when generating a core dump file, these implementations may also ignore important shared memory segments such as the Apache scoreboard.

`apc.preload_path` string
  Optionally, set a path to the directory that APC will load cache data at startup.
`apc.use_request_time` bool
  Use the SAPI request start time for TTL.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`APC_ITER_ALL` (int)
`APC_ITER_ATIME` (int)
`APC_ITER_CTIME` (int)
`APC_ITER_DEVICE` (int)
`APC_ITER_DTIME` (int)
`APC_ITER_FILENAME` (int)
`APC_ITER_INODE` (int)
`APC_ITER_KEY` (int)
`APC_ITER_MD5` (int)
`APC_ITER_MEM_SIZE` (int)
`APC_ITER_MTIME` (int)
`APC_ITER_NONE` (int)
`APC_ITER_NUM_HITS` (int)
`APC_ITER_REFCOUNT` (int)
`APC_ITER_TTL` (int)
`APC_ITER_TYPE` (int)
`APC_ITER_VALUE` (int)
`APC_LIST_ACTIVE` (int)
`APC_LIST_DELETED` (int)

# APCu Funktionen

# apcu_add

(PECL apcu >= 4.0.0)

apcu_add — Cache a new variable in the data store

### Beschreibung

function apcu_add(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Caches a variable in the data store, only if it's not already stored.

> Hinweis: Unlike many other mechanisms in PHP, variables stored using apcu_add() will persist between requests (until the value is removed from the cache).

### Parameter-Liste

`key`
  Store the variable using this name. `key`s are cache-unique, so attempting to use apcu_add() to store data with a key that already exists will not overwrite the existing data, and will instead return `false`. (This is the only difference between apcu_add() and apcu_store().)
`var`
  The variable to store
`ttl`
  Time To Live; store `var` in the cache for `ttl` seconds. After the `ttl` has passed, the stored variable will be expunged from the cache (on the next request). If no `ttl` is supplied (or if the `ttl` is `0`), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).
`values`
  Names in key, variables in value.

### Rückgabewerte

Returns TRUE if something has effectively been added into the cache, FALSE otherwise. Second syntax returns array with error keys.

### Beispiele

Beispiel #1 A apcu_add() example

    <?php
    $bar = 'BAR';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    $bar = 'NEVER GETS SET';
    apcu_add('foo', $bar);
    var_dump(apcu_fetch('foo'));
    echo "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "BAR"
    string(3) "BAR"

### Siehe auch

- apcu_store() - Cache a variable in the data store
- apcu_fetch() - Fetch a stored variable from the cache
- apcu_delete() - Removes a stored variable from the cache

# apcu_cache_info

(PECL apcu >= 4.0.0)

apcu_cache_info — Ruft zwischengespeicherte Informationen aus dem Datenspeicher von APCu ab

### Beschreibung

function apcu_cache_info(bool `$limited` = `false`): array|false

Ruft zwischengespeicherte Informationen und Metadaten aus dem Datenspeicher von APCu ab.

### Parameter-Liste

`limited`
  Wenn `limited` den Wert `true` hat, wird die Liste der einzelnen Cache-Einträge aus dem Rückgabewert ausgeschlossen. Dies ist nützlich, um Aufrufe zur Erfassung von Statistiken zu optimieren..

### Rückgabewerte

Array der zwischengespeicherten Daten (und Metadaten). Bei einem Fehler wird `false` zurückgegeben.

> Hinweis: apcu_cache_info() löst eine Warnung aus, wenn die APCu-Cache-Daten nicht abgerufen werden können. Dies tritt üblicherweise auf, wenn APCu nicht aktiviert ist.

### Changelog

Version | Beschreibung
--- | ---
PECL apcu 3.0.11 | Der Parameter `limited` wurde eingeführt.
PECL apcu 3.0.16 | Die Option "`filehits`" für den Parameter `cache_type` wurde eingeführt.

### Beispiele

Beispiel #1 Ein Beispiel für apcu_cache_info()

    <?php
    print_r(apcu_cache_info());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [num_slots] => 2000
        [ttl] => 0
        [num_hits] => 9
        [num_misses] => 3
        [start_time] => 1123958803
        [cache_list] => Array
            (
                [0] => Array
                    (
                        [filename] => /path/to/apcu_test.php
                        [device] => 29954
                        [inode] => 1130511
                        [type] => file
                        [num_hits] => 1
                        [mtime] => 1123960686
                        [creation_time] => 1123960696
                        [deletion_time] => 0
                        [access_time] => 1123962864
                        [ref_count] => 1
                        [mem_size] => 677
                    )
                [1] => Array (...iterates for each cached file)
    )

### Siehe auch

- APCu-Konfigurationsdirektiven
- APCUIterator::getTotalSize() - Get total cache size
- APCUIterator::getTotalHits() - Get total cache hits
- APCUIterator::getTotalCount() - Get total count

# apcu_cas

(PECL apcu >= 4.0.0)

apcu_cas — Updates an old value with a new value

### Beschreibung

function apcu_cas(string `$key`, int `$old`, int `$new`): bool

apcu_cas() updates an already existing integer value if the `old` parameter matches the currently stored value with the value of the `new` parameter.

### Parameter-Liste

`key`
  The key of the value being updated.
`old`
  The old value (the value currently stored).
`new`
  The new value to update to.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 apcu_cas() example

    <?php
    apcu_store('foobar', 2);
    echo '$foobar = 2', PHP_EOL;
    echo '$foobar == 1 ? 2 : 1 = ', (apcu_cas('foobar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
    echo '$foobar == 2 ? 1 : 2 = ', (apcu_cas('foobar', 2, 1) ? 'ok' : 'fail'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;

    echo '$f__bar == 1 ? 2 : 1 = ', (apcu_cas('f__bar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;

    apcu_store('perfection', 'xyz');
    echo '$perfection == 2 ? 1 : 2 = ', (apcu_cas('perfection', 2, 1) ? 'ok' : 'epic fail'), PHP_EOL;

    echo '$foobar = ', apcu_fetch('foobar'), PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    $foobar = 2
    $foobar == 1 ? 2 : 1 = fail
    $foobar == 2 ? 1 : 2 = ok
    $foobar = 1
    $f__bar == 1 ? 2 : 1 = fail
    $perfection == 2 ? 1 : 2 = epic fail
    $foobar = 1

### Siehe auch

- apcu_dec() - Decrease a stored number
- apcu_store() - Cache a variable in the data store

# apcu_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cache — Clears the APCu cache

### Beschreibung

function apcu_clear_cache(): bool

Clears the cache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` always

### Siehe auch

- apcu_cache_info() - Ruft zwischengespeicherte Informationen aus dem Datenspeicher von APCu ab

# apcu_dec

(PECL apcu >= 4.0.0)

apcu_dec — Decrease a stored number

### Beschreibung

function apcu_dec(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Decreases a stored integer value.

### Parameter-Liste

`key`
  The key of the value being decreased.
`step`
  The step, or value to decrease.
`success`
  Optionally pass the success or fail boolean value to this referenced variable.
`ttl`
  TTL to use if the operation inserts a new value (rather than decrementing an existing one).

### Rückgabewerte

Returns the current value of `key`'s value on success, Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 apcu_dec() example

    <?php
    echo "Let's do something with success", PHP_EOL;

    apcu_store('anumber', 42);

    echo apcu_fetch('anumber'), PHP_EOL;

    echo apcu_dec('anumber'), PHP_EOL;
    echo apcu_dec('anumber', 10), PHP_EOL;
    echo apcu_dec('anumber', 10, $success), PHP_EOL;

    var_dump($success);

    echo "Now, let's fail", PHP_EOL, PHP_EOL;

    apcu_store('astring', 'foo');

    $ret = apcu_dec('astring', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Let's do something with success
    42
    41
    31
    21
    bool(true)
    Now, let's fail

    bool(false)
    bool(false)

### Siehe auch

- apcu_inc() - Increase a stored number

# apcu_delete

(PECL apcu >= 4.0.0)

apcu_delete — Removes a stored variable from the cache

### Beschreibung

function apcu_delete(mixed `$key`): mixed

Removes a stored variable from the cache.

### Parameter-Liste

`key`
  A `key` used to store the value as a string for a single key, or as an array of strings for several keys, or as an APCUIterator object.

### Rückgabewerte

If `key` is an Array, an indexed Array of the keys is returned. Otherwise `true` is returned on success, or `false` on failure.

### Beispiele

Beispiel #1 A apcu_delete() example

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    apcu_delete('foo');
    // this is obviously useless in this form

    // Alternatively delete multiple keys.
    apcu_delete(['foo', 'bar', 'baz']);

    // Or use an Iterator with a regular expression.
    apcu_delete(new APCUIterator('#^myprefix_#'));
    ?>

### Siehe auch

- apcu_store() - Cache a variable in the data store
- apcu_fetch() - Fetch a stored variable from the cache
- apcu_clear_cache() - Clears the APCu cache
- APCUIterator

# apcu_enabled

(PECL apcu >= 4.0.3)

apcu_enabled — Prüft, ob APCu in der aktuellen Umgebung verfügbar ist

### Beschreibung

function apcu_enabled(): bool

Gibt zurück, ob APCu in der aktuellen Umgebung verfügbar ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn APCu in der aktuellen Umgebung verfügbar ist, andernfalls `false`.

# apcu_entry

(PECL apcu >= 5.1.0)

apcu_entry — Atomically fetch or generate a cache entry

### Beschreibung

function apcu_entry(string `$key`, callable `$callback`, int `$ttl` = 0): mixed

Atomically attempts to find `key` in the cache, if it cannot be found `callback` is called, passing `key` as the only argument. The return value of the call is then cached with the optionally specified `ttl`, and returned.

> Hinweis: When control enters apcu_entry() the lock for the cache is acquired exclusively, it is released when control leaves apcu_entry(): In effect, this turns the body of `callback` into a critical section, disallowing two processes from executing the same code paths concurrently. In addition, it prohibits the concurrent execution of any other APCu functions, since they will acquire the same lock.

Warnung

The only APCu function that can be called safely by `callback` is apcu_entry().

### Parameter-Liste

`key`
  Identity of cache entry
`callback`
  A callable that accepts `key` as the only argument and returns the value to cache.
`ttl`
  Time To Live; store the `callback`'s return value in the cache for `ttl` seconds. After the `ttl` has passed, the stored entry will be expunged from the cache (on the next request). If no `ttl` is supplied (or if the `ttl` is `0`), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).

### Rückgabewerte

Returns the cached value

### Beispiele

Beispiel #1 An apcu_entry() example

    <?php
    $config = apcu_entry("config", function($key) {
     return [
       "fruit" => apcu_entry("config.fruit", function($key){
         return [
           "apples",
           "pears"
         ];
       }),
       "people" => apcu_entry("config.people", function($key){
         return [
          "bob",
          "joe",
          "niki"
         ];
       })
     ];
    });

    var_dump($config);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      ["fruit"]=>
      array(2) {
        [0]=>
        string(6) "apples"
        [1]=>
        string(5) "pears"
      }
      ["people"]=>
      array(3) {
        [0]=>
        string(3) "bob"
        [1]=>
        string(3) "joe"
        [2]=>
        string(4) "niki"
      }
    }

### Siehe auch

- apcu_store() - Cache a variable in the data store
- apcu_fetch() - Fetch a stored variable from the cache
- apcu_delete() - Removes a stored variable from the cache

# apcu_exists

(PECL apcu >= 4.0.0)

apcu_exists — Checks if entry exists

### Beschreibung

function apcu_exists(string|array `$keys`): bool|array

Checks if one or more APCu entries exist.

### Parameter-Liste

`keys`
  A string, or an array of strings, that contain keys.

### Rückgabewerte

Returns `true` if the key exists, otherwise `false` Or if an array was passed to `keys`, then an array is returned that contains all existing keys, or an empty array if none exist.

### Beispiele

Beispiel #1 apcu_exists() example

    <?php
    $fruit  = 'apple';
    $veggie = 'carrot';

    apcu_store('foo', $fruit);
    apcu_store('bar', $veggie);

    if (apcu_exists('foo')) {
        echo "Foo exists: ";
        echo apcu_fetch('foo');
    } else {
        echo "Foo does not exist";
    }

    echo PHP_EOL;
    if (apcu_exists('baz')) {
        echo "Baz exists.";
    } else {
        echo "Baz does not exist";
    }

    echo PHP_EOL;

    $ret = apcu_exists(array('foo', 'donotexist', 'bar'));
    var_dump($ret);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Foo exists: apple
    Baz does not exist
    array(2) {
      ["foo"]=>
      bool(true)
      ["bar"]=>
      bool(true)
    }

### Siehe auch

- apcu_cache_info() - Ruft zwischengespeicherte Informationen aus dem Datenspeicher von APCu ab
- apcu_fetch() - Fetch a stored variable from the cache

# apcu_fetch

(PECL apcu >= 4.0.0)

apcu_fetch — Fetch a stored variable from the cache

### Beschreibung

function apcu_fetch(mixed `$key`, bool `&$success` = ?): mixed

Fetches an entry from the cache.

### Parameter-Liste

`key`
  The `key` used to store the value (with apcu_store()). If an array is passed then each element is fetched and returned.
`success`
  Set to `true` in success and `false` in failure.

### Rückgabewerte

The stored variable or array of variables on success; `false` on failure

### Changelog

Version | Beschreibung
--- | ---
PECL apcu 3.0.17 | The `success` parameter was added.

### Beispiele

Beispiel #1 A apcu_fetch() example

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "BAR"

### Siehe auch

- apcu_store() - Cache a variable in the data store
- apcu_delete() - Removes a stored variable from the cache
- APCUIterator

# apcu_inc

(PECL apcu >= 4.0.0)

apcu_inc — Increase a stored number

### Beschreibung

function apcu_inc(
string `$key`,
int `$step` = 1,
bool `&$success` = ?,
int `$ttl` = 0
): int|false

Increases a stored number.

### Parameter-Liste

`key`
  The key of the value being increased.
`step`
  The step, or value to increase.
`success`
  Optionally pass the success or fail boolean value to this referenced variable.
`ttl`
  TTL to use if the operation inserts a new value (rather than incrementing an existing one).

### Rückgabewerte

Returns the current value of `key`'s value on success, Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 apcu_inc() example

    <?php
    echo "Let's do something with success", PHP_EOL;

    apcu_store('anumber', 42);

    echo apcu_fetch('anumber'), PHP_EOL;

    echo apcu_inc('anumber'), PHP_EOL;
    echo apcu_inc('anumber', 10), PHP_EOL;
    echo apcu_inc('anumber', 10, $success), PHP_EOL;

    var_dump($success);

    echo "Now, let's fail", PHP_EOL, PHP_EOL;

    apcu_store('astring', 'foo');

    $ret = apcu_inc('astring', 1, $fail);

    var_dump($ret);
    var_dump($fail);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Let's do something with success
    42
    43
    53
    63
    bool(true)
    Now, let's fail

    bool(false)
    bool(false)

### Siehe auch

- apcu_dec() - Decrease a stored number

# apcu_key_info

(PECL apcu >= 4.0.2)

apcu_key_info — Liefert detaillierte Informationen über den Cache-Schlüssel

### Beschreibung

function apcu_key_info(string `$key`): ?array

Liefert detaillierte Informationen über den Cache-Schlüssel

### Parameter-Liste

`key`
  Der Schlüssel, für den Informationen abgerufen werden sollen.

### Rückgabewerte

Ein Array mit den detaillierten Informationen über den Cache-Schlüssel oder `null`, wenn der Schlüssel nicht existiert.

### Beispiele

Beispiel #1 Ein Beispiel für apcu_key_info()

    <?php
    apcu_add('a','b');
    var_dump(apcu_key_info('a'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(7) {
      ["hits"]=>
      int(0)
      ["access_time"]=>
      int(1606701783)
      ["mtime"]=>
      int(1606701783)
      ["creation_time"]=>
      int(1606701783)
      ["deletion_time"]=>
      int(0)
      ["ttl"]=>
      int(0)
      ["refs"]=>
      int(0)
    }

### Siehe auch

- apcu_store() - Cache a variable in the data store
- apcu_fetch() - Fetch a stored variable from the cache
- apcu_delete() - Removes a stored variable from the cache

# apcu_sma_info

(PECL apcu >= 4.0.0)

apcu_sma_info — Retrieves APCu Shared Memory Allocation information

### Beschreibung

function apcu_sma_info(bool `$limited` = `false`): array|false

Retrieves APCu Shared Memory Allocation information.

### Parameter-Liste

`limited`
  When set to `false` (default) apcu_sma_info() will return a detailed information about each segment.

### Rückgabewerte

Array of Shared Memory Allocation data; `false` on failure.

### Beispiele

Beispiel #1 A apcu_sma_info() example

    <?php
    print_r(apcu_sma_info());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [num_seg] => 1
        [seg_size] => 31457280
        [avail_mem] => 31448408
        [block_lists] => Array
            (
                [0] => Array
                    (
                        [0] => Array
                            (
                                [size] => 31448408
                                [offset] => 8864
                            )

                    )

            )

    )

### Siehe auch

- APCu configuration directives

# apcu_store

(PECL apcu >= 4.0.0)

apcu_store — Cache a variable in the data store

### Beschreibung

function apcu_store(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function apcu_store(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): array

Cache a variable in the data store.

> Hinweis: Unlike many other mechanisms in PHP, variables stored using apcu_store() will persist between requests (until the value is removed from the cache).

### Parameter-Liste

`key`
  Store the variable using this name. `key`s are cache-unique, so storing a second value with the same `key` will overwrite the original value.
`var`
  The variable to store
`ttl`
  Time To Live; store `var` in the cache for `ttl` seconds. After the `ttl` has passed, the stored variable will be expunged from the cache (on the next request). If no `ttl` is supplied (or if the `ttl` is `0`), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).
`values`
  Names in key, variables in value.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. Second syntax returns array with error keys.

### Beispiele

Beispiel #1 A apcu_store() example

    <?php
    $bar = 'BAR';
    apcu_store('foo', $bar);
    var_dump(apcu_fetch('foo'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "BAR"

### Siehe auch

- apcu_add() - Cache a new variable in the data store
- apcu_fetch() - Fetch a stored variable from the cache
- apcu_delete() - Removes a stored variable from the cache

## Inhaltsverzeichnis

- apcu_add — Cache a new variable in the data store
- apcu_cache_info — Ruft zwischengespeicherte Informationen aus dem Datenspeicher von APCu ab
- apcu_cas — Updates an old value with a new value
- apcu_clear_cache — Clears the APCu cache
- apcu_dec — Decrease a stored number
- apcu_delete — Removes a stored variable from the cache
- apcu_enabled — Prüft, ob APCu in der aktuellen Umgebung verfügbar ist
- apcu_entry — Atomically fetch or generate a cache entry
- apcu_exists — Checks if entry exists
- apcu_fetch — Fetch a stored variable from the cache
- apcu_inc — Increase a stored number
- apcu_key_info — Liefert detaillierte Informationen über den Cache-Schlüssel
- apcu_sma_info — Retrieves APCu Shared Memory Allocation information
- apcu_store — Cache a variable in the data store

# The APCUIterator class

(PECL apcu >= 5.0.0)

## Einführung

The APCUIterator class makes it easier to iterate over large APCu caches. This is helpful as it allows iterating over large caches in steps, while grabbing a defined number of entries per lock instance, so it frees the cache locks for other activities rather than hold up the entire cache to grab 100 (the default) entries. Also, using regular expression matching is more efficient as it's been moved to the C level.

## Klassenbeschreibung

class APCUIterator implements Iterator {
/* Methoden */
public function __construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)
public function current(): mixed
public function getTotalCount(): int
public function getTotalHits(): int
public function getTotalSize(): int
public function key(): string
public function next(): bool
public function rewind(): void
public function valid(): bool
}

# APCUIterator::__construct

(PECL apcu >= 5.0.0)

APCUIterator::__construct — Constructs an APCUIterator iterator object

### Beschreibung

public function APCUIterator::__construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)

Constructs an APCUIterator object.

### Parameter-Liste

`search`
  Either a PCRE regular expression that matches against APCu key names, given as a String. Or an Array of Strings with APCu key names. Or, optionally `null` to skip the search.
`format`
  The desired format, as configured with one or more of the APC_ITER_* constants.
`chunk_size`
  The chunk size. Must be a value greater than 0. The default value is 100.
`list`
  The type to list. Either pass in `APC_LIST_ACTIVE` or `APC_LIST_DELETED`.

### Beispiele

Beispiel #1 A APCUIterator::__construct() example

    <?php
    foreach (new APCUIterator('/^counter\./') as $counter) {
        echo "$counter[key]: $counter[value]\n";
        apc_dec($counter['key'], $counter['value']);
    }
    ?>

### Siehe auch

- apcu_exists() - Checks if entry exists
- apcu_cache_info() - Ruft zwischengespeicherte Informationen aus dem Datenspeicher von APCu ab

# APCUIterator::current

(PECL apcu >= 5.0.0)

APCUIterator::current — Get current item

### Beschreibung

public function APCUIterator::current(): mixed

Gets the current item from the APCUIterator stack.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the current item on success, or `false` if no more items exist, or on failure.

### Siehe auch

- APCUIterator::next() - Move pointer to next item
- Iterator::current() - Liefert das aktuelle Element

# APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCount — Get total count

### Beschreibung

public function APCUIterator::getTotalCount(): int

Get the total count.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The total count.

### Siehe auch

- APCUIterator::getTotalHits() - Get total cache hits
- APCUIterator::getTotalSize() - Get total cache size
- apcu_cache_info() - Ruft zwischengespeicherte Informationen aus dem Datenspeicher von APCu ab

# APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHits — Get total cache hits

### Beschreibung

public function APCUIterator::getTotalHits(): int

Gets the total number of cache hits.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The number of hits on success, or `false` on failure.

### Siehe auch

- APCUIterator::getTotalCount() - Get total count
- APCUIterator::getTotalSize() - Get total cache size
- apcu_cache_info() - Ruft zwischengespeicherte Informationen aus dem Datenspeicher von APCu ab

# APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSize — Get total cache size

### Beschreibung

public function APCUIterator::getTotalSize(): int

Gets the total cache size.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The total cache size.

### Siehe auch

- APCUIterator::getTotalCount() - Get total count
- APCUIterator::getTotalHits() - Get total cache hits
- apc_cache_info()

# APCUIterator::key

(PECL apcu >= 5.0.0)

APCUIterator::key — Get iterator key

### Beschreibung

public function APCUIterator::key(): string

Gets the current iterator key.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the key on success, or `false` upon failure.

### Siehe auch

- APCUIterator::current() - Get current item
- Iterator::key() - Liefert den Schlüssel des aktuellen Elements

# APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::next — Move pointer to next item

### Beschreibung

public function APCUIterator::next(): bool

Moves the iterator pointer to the next element.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- APCUIterator::current() - Get current item
- APCUIterator::rewind() - Rewinds iterator
- Iterator::next() - Rückt den Zeiger auf das nächste Element vor

# APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewind — Rewinds iterator

### Beschreibung

public function APCUIterator::rewind(): void

Rewinds back the iterator to the first element.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- APCUIterator::next() - Move pointer to next item
- Iterator::next() - Rückt den Zeiger auf das nächste Element vor

# APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::valid — Checks if current position is valid

### Beschreibung

public function APCUIterator::valid(): bool

Checks if the current iterator position is valid.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the current iterator position is valid, otherwise `false`.

### Siehe auch

- APCUIterator::current() - Get current item
- Iterator::valid() - Prüft, ob die aktuelle Position zulässig ist

## Inhaltsverzeichnis

- APCUIterator::__construct — Constructs an APCUIterator iterator object
- APCUIterator::current — Get current item
- APCUIterator::getTotalCount — Get total count
- APCUIterator::getTotalHits — Get total cache hits
- APCUIterator::getTotalSize — Get total cache size
- APCUIterator::key — Get iterator key
- APCUIterator::next — Move pointer to next item
- APCUIterator::rewind — Rewinds iterator
- APCUIterator::valid — Checks if current position is valid

- Installation/Konfiguration
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- APCu Funktionen
  - apcu_add — Cache a new variable in the data store
  - apcu_cache_info — Ruft zwischengespeicherte Informationen aus dem Datenspeicher von APCu ab
  - apcu_cas — Updates an old value with a new value
  - apcu_clear_cache — Clears the APCu cache
  - apcu_dec — Decrease a stored number
  - apcu_delete — Removes a stored variable from the cache
  - apcu_enabled — Prüft, ob APCu in der aktuellen Umgebung verfügbar ist
  - apcu_entry — Atomically fetch or generate a cache entry
  - apcu_exists — Checks if entry exists
  - apcu_fetch — Fetch a stored variable from the cache
  - apcu_inc — Increase a stored number
  - apcu_key_info — Liefert detaillierte Informationen über den Cache-Schlüssel
  - apcu_sma_info — Retrieves APCu Shared Memory Allocation information
  - apcu_store — Cache a variable in the data store
- APCUIterator — The APCUIterator class
  - APCUIterator::__construct — Constructs an APCUIterator iterator object
  - APCUIterator::current — Get current item
  - APCUIterator::getTotalCount — Get total count
  - APCUIterator::getTotalHits — Get total cache hits
  - APCUIterator::getTotalSize — Get total cache size
  - APCUIterator::key — Get iterator key
  - APCUIterator::next — Move pointer to next item
  - APCUIterator::rewind — Rewinds iterator
  - APCUIterator::valid — Checks if current position is valid

# Componere

# Einführung

Componere (latin, English: compose) targets production environments and provides an API for composition of classes, monkey patching, and casting.

##### Composition:

Componere\Definition is used to define (or redefine) a class at runtime; The class can then be registered, and in the case of redefinition it replaces the original class for as long as the Componere\Definition exists.

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

##### Patching:

Componere\Patch is used to change the class of a specific instance of an object at runtime; Upon application the patch will remain applied for as long as the Componere\Patch exists, and can be reverted explicitly.

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

##### Casting:

Componere\ casting functions can cast among user defined compatible types; Where compatible means Type is sub or super to the type of `object`.

function Componere\cast(string `$type`, object `$object`): object
function Componere\cast_by_ref(string `$type`, object `$object`): object

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

Reflection is required

## Installation

Componere source and releases are available on » github

# The Componere\Abstract\Definition class

(Componere 2 >= 2.1.0)

## Einführung

This final abstract represents a class entry, and should not be used by the programmer.

## Klassenbeschreibung

final abstract class Componere\Abstract\Definition {
/* Methoden */
public function addInterface(string `$interface`): Definition
public function addMethod(string `$name`, Componere\Method `$method`): Definition
public function addTrait(string `$trait`): Definition
public function getReflector(): ReflectionClass
}

# Componere\Abstract\Definition::addInterface

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addInterface — Add Interface

### Beschreibung

public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition

Shall implement the given interface on the current definition

### Parameter-Liste

`interface`
  The case insensitive name of an interface

### Rückgabewerte

The current Definition

### Exceptions

Warnung

Shall throw RuntimeException if Definition was registered

# Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethod — Add Method

### Beschreibung

public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition

Shall create or override a method on the current definition.

### Parameter-Liste

`name`
  The case insensitive name for method
`method`
  Componere\Method not previously added to another Definition

### Rückgabewerte

The current Definition

### Exceptions

Warnung

Shall throw RuntimeException if Definition was registered

Warnung

Shall throw RuntimeException if Method was added to another Definition

# Componere\Abstract\Definition::addTrait

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addTrait — Add Trait

### Beschreibung

public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition

Shall use the given trait for the current definition

### Parameter-Liste

`trait`
  The case insensitive name of a trait

### Rückgabewerte

The current Definition

### Exceptions

Warnung

Shall throw RuntimeException if Definition was registered

# Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflector — Reflection

### Beschreibung

public function Componere\Abstract\Definition::getReflector(): ReflectionClass

Shall create or return a ReflectionClass

### Rückgabewerte

A ReflectionClass for the current definition (cached)

## Inhaltsverzeichnis

- Componere\Abstract\Definition::addInterface — Add Interface
- Componere\Abstract\Definition::addMethod — Add Method
- Componere\Abstract\Definition::addTrait — Add Trait
- Componere\Abstract\Definition::getReflector — Reflection

# The Componere\Definition class

(Componere 2 >= 2.1.0)

## Einführung

The Definition class allows the programmer to build and register a type at runtime.

Should a Definition replace an existing class, the existing class will be restored when the Definition is destroyed.

## Klassenbeschreibung

final class Componere\Definition extends Componere\Abstract\Definition {
/* Constructors */
public function __construct(string `$name`)
public function __construct(string `$name`, string `$parent`)
public function __construct(string `$name`, array `$interfaces`)
public function __construct(string `$name`, string `$parent`, array `$interfaces`)
/* Methoden */
public function addConstant(string `$name`, Componere\Value `$value`): Definition
public function addProperty(string `$name`, Componere\Value `$value`): Definition
public function register(): void
public function isRegistered(): bool
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Geerbte Methoden */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Definition::__construct

(Componere 2 >= 2.1.0)

Componere\Definition::__construct — Definition Construction

### Beschreibung

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function Componere\Definition::__construct(string `$name`, string `$parent`, array `$interfaces`)

### Parameter-Liste

`name`
  A case insensitive class name
`parent`
  A case insensitive class name
`interfaces`
  An array of case insensitive class names

### Exceptions

Warnung

Shall throw InvalidArgumentException if an attempt is made to replace an internal class

Warnung

Shall throw InvalidArgumentException if an attempt is made to replace an interface

Warnung

Shall throw InvalidArgumentException if an attempt is made to replace a trait

Warnung

Shall throw RuntimeException if a class in `interfaces` cannot be found

Warnung

Shall throw RuntimeException if a class in `interfaces` is not an interface

# Componere\Definition::addConstant

(Componere 2 >= 2.1.0)

Componere\Definition::addConstant — Add Constant

### Beschreibung

public function Componere\Definition::addConstant(string `$name`, Componere\Value `$value`): Definition

Shall declare a class constant on the current Definition

### Parameter-Liste

`name`
  The case sensitive name for the constant
`value`
  The Value for the constant, must not be undefined or static

### Rückgabewerte

The current Definition

### Exceptions

Warnung

Shall throw RuntimeException if Definition was registered

Warnung

Shall throw RuntimeException if `name` is already declared as a constant

Warnung

Shall throw RuntimeException if `value` is static

Warnung

Shall throw RuntimeException if `value` is undefined

# Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addProperty — Add Property

### Beschreibung

public function Componere\Definition::addProperty(string `$name`, Componere\Value `$value`): Definition

Shall declare a class property on the current Definition

### Parameter-Liste

`name`
  The case sensitive name for the property
`value`
  The default Value for the property

### Rückgabewerte

The current Definition

### Exceptions

Warnung

Shall throw RuntimeException if Definition was registered

Warnung

Shall throw RuntimeException if `name` is already declared as a property

# Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::register — Registration

### Beschreibung

public function Componere\Definition::register(): void

Shall register the current Definition

### Exceptions

Warnung

Shall throw RuntimeException if Definition was registered

# Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegistered — State Detection

### Beschreibung

public function Componere\Definition::isRegistered(): bool

Shall detect the registration state of this Definition

### Rückgabewerte

Shall return true if this Definition is registered

# Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosure — Get Closure

### Beschreibung

public function Componere\Definition::getClosure(string `$name`): Closure

Shall return a Closure for the method specified by name

### Parameter-Liste

`name`
  The case insensitive name of the method

### Rückgabewerte

A Closure bound to the correct scope

### Exceptions

Warnung

Shall throw RuntimeException if Definition was registered

Warnung

Shall throw RuntimeException if `name` could not be found

# Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosures — Get Closures

### Beschreibung

public function Componere\Definition::getClosures(): array

Shall return an array of Closures

### Rückgabewerte

Shall return all methods as an array of Closure objects bound to the correct scope

### Exceptions

Warnung

Shall throw RuntimeException if Definition was registered

## Inhaltsverzeichnis

- Componere\Definition::__construct — Definition Construction
- Componere\Definition::addConstant — Add Constant
- Componere\Definition::addProperty — Add Property
- Componere\Definition::register — Registration
- Componere\Definition::isRegistered — State Detection
- Componere\Definition::getClosure — Get Closure
- Componere\Definition::getClosures — Get Closures

# The Componere\Patch class

(Componere 2 >= 2.1.0)

## Einführung

The Patch class allows the programmer to change the type of an instance at runtime without registering a new Definition

When a Patch is destroyed it is reverted, so that instances that were patched during the lifetime of the Patch are restored to their formal type.

## Klassenbeschreibung

final class Componere\Patch extends Componere\Abstract\Definition {
/* Constructors */
public function __construct(object `$instance`)
public function __construct(object `$instance`, array `$interfaces`)
/* Methoden */
public function apply(): void
public function revert(): void
public function isApplied(): bool
public function derive(object `$instance`): Patch
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* Geerbte Methoden */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Patch::__construct

(Componere 2 >= 2.1.0)

Componere\Patch::__construct — Patch Construction

### Beschreibung

public function Componere\Patch::__construct(object `$instance`)
public function Componere\Patch::__construct(object `$instance`, array `$interfaces`)

### Parameter-Liste

`instance`
  The target for this Patch
`interfaces`
  A case insensitive array of class names

### Exceptions

Warnung

Shall throw RuntimeException if a class in `interfaces` cannot be found

Warnung

Shall throw RuntimeException if a class in `interfaces` is not an interface

# Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::apply — Application

### Beschreibung

public function Componere\Patch::apply(): void

Shall apply the current patch

# Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revert — Reversal

### Beschreibung

public function Componere\Patch::revert(): void

Shall revert the current patch

# Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isApplied — State Detection

### Beschreibung

public function Componere\Patch::isApplied(): bool

# Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::derive — Patch Derivation

### Beschreibung

public function Componere\Patch::derive(object `$instance`): Patch

Shall derive a Patch for the given `instance`

### Parameter-Liste

`instance`
  The target for the derived Patch

### Rückgabewerte

Patch for `instance` derived from the current Patch

### Exceptions

Warnung

Shall throw InvalidArgumentException if `instance` is not compatible

# Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosure — Get Closure

### Beschreibung

public function Componere\Patch::getClosure(string `$name`): Closure

Shall return a Closure for the method specified by name

### Parameter-Liste

`name`
  The case insensitive name of the method

### Rückgabewerte

A Closure bound to the correct scope and object

### Exceptions

Warnung

Shall throw RuntimeException if `name` could not be found

# Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosures — Get Closures

### Beschreibung

public function Componere\Patch::getClosures(): array

Shall return an array of Closures

### Rückgabewerte

Shall return all methods as an array of Closure objects bound to the correct scope and object

## Inhaltsverzeichnis

- Componere\Patch::__construct — Patch Construction
- Componere\Patch::apply — Application
- Componere\Patch::revert — Reversal
- Componere\Patch::isApplied — State Detection
- Componere\Patch::derive — Patch Derivation
- Componere\Patch::getClosure — Get Closure
- Componere\Patch::getClosures — Get Closures

# The Componere\Method class

(Componere 2 >= 2.1.0)

## Einführung

A Method represents a function with modifiable accessibility flags

## Klassenbeschreibung

final class Componere\Method {
/* Constructor */
public function __construct(Closure `$closure`)
/* Methoden */
public function setPrivate(): Method
public function setProtected(): Method
public function setStatic(): Method
public function getReflector(): ReflectionMethod
}

# Componere\Method::__construct

(Componere 2 >= 2.1.0)

Componere\Method::__construct — Method Construction

### Beschreibung

public function Componere\Method::__construct(Closure `$closure`)

### Parameter-Liste

`closure`

# Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivate — Accessibility Modification

### Beschreibung

public function Componere\Method::setPrivate(): Method

### Rückgabewerte

The current Method

### Exceptions

Warnung

Shall throw RuntimeException if access level was previously set

# Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtected — Accessibility Modification

### Beschreibung

public function Componere\Method::setProtected(): Method

### Rückgabewerte

The current Method

### Exceptions

Warnung

Shall throw RuntimeException if access level was previously set

# Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStatic — Accessibility Modification

### Beschreibung

public function Componere\Method::setStatic(): Method

### Rückgabewerte

The current Method

# Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflector — Reflection

### Beschreibung

public function Componere\Method::getReflector(): ReflectionMethod

Shall create or return a ReflectionMethod

### Rückgabewerte

A ReflectionMethod for the current method (cached)

## Inhaltsverzeichnis

- Componere\Method::__construct — Method Construction
- Componere\Method::setPrivate — Accessibility Modification
- Componere\Method::setProtected — Accessibility Modification
- Componere\Method::setStatic — Accessibility Modification
- Componere\Method::getReflector — Reflection

# The Componere\Value class

(Componere 2 >= 2.1.0)

## Einführung

A Value represents a PHP variable of all types, including undefined

## Klassenbeschreibung

final class Componere\Value {
/* Constructor */
public function __construct(mixed `$default` = ?)
/* Methoden */
public function setPrivate(): Value
public function setProtected(): Value
public function setStatic(): Value
public function isPrivate(): bool
public function isProtected(): bool
public function isStatic(): bool
public function hasDefault(): bool
}

# Componere\Value::__construct

(Componere 2 >= 2.1.0)

Componere\Value::__construct — Value Construction

### Beschreibung

public function Componere\Value::__construct(mixed `$default` = ?)

### Parameter-Liste

`default`

### Exceptions

Warnung

Shall throw InvalidArgumentException if `default` does not have a suitable value

# Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivate — Accessibility Modification

### Beschreibung

public function Componere\Value::setPrivate(): Value

### Rückgabewerte

The current Value

### Exceptions

Warnung

Shall throw RuntimeException if access level was previously set

# Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtected — Accessibility Modification

### Beschreibung

public function Componere\Value::setProtected(): Value

### Rückgabewerte

The current Value

### Exceptions

Warnung

Shall throw RuntimeException if access level was previously set

# Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStatic — Accessibility Modification

### Beschreibung

public function Componere\Value::setStatic(): Value

### Rückgabewerte

The current Value

# Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivate — Accessibility Detection

### Beschreibung

public function Componere\Value::isPrivate(): bool

# Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtected — Accessibility Detection

### Beschreibung

public function Componere\Value::isProtected(): bool

# Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStatic — Accessibility Detection

### Beschreibung

public function Componere\Value::isStatic(): bool

# Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefault — Value Interaction

### Beschreibung

public function Componere\Value::hasDefault(): bool

## Inhaltsverzeichnis

- Componere\Value::__construct — Value Construction
- Componere\Value::setPrivate — Accessibility Modification
- Componere\Value::setProtected — Accessibility Modification
- Componere\Value::setStatic — Accessibility Modification
- Componere\Value::isPrivate — Accessibility Detection
- Componere\Value::isProtected — Accessibility Detection
- Componere\Value::isStatic — Accessibility Detection
- Componere\Value::hasDefault — Value Interaction

# Componere Funktionen

# Componere\cast

(Componere 2 >= 2.1.2)

Componere\cast — Casting

### Beschreibung

function Componere\cast(string `$type`, object `$object`): object

### Parameter-Liste

`type`
  A user defined type
`object`
  An object with a user defined type compatible with Type

### Rückgabewerte

An object of type Type, cast from `object`

### Fehler/Exceptions

Warnung

Shall throw InvalidArgumentException if the type of `object` is or is derived from an internal class

Warnung

Shall throw InvalidArgumentException if Type is an interface

Warnung

Shall throw InvalidArgumentException if Type is a trait

Warnung

Shall throw InvalidArgumentException if Type is an abstract

Warnung

Shall throw InvalidArgumentException if Type is not compatible with the type of `object`

### Siehe auch

- Componere\cast_by_ref

# Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_ref — Casting

### Beschreibung

function Componere\cast_by_ref(string `$type`, object `$object`): object

### Parameter-Liste

type
  A user defined type
`object`
  An object with a user defined type compatible with Type

### Rückgabewerte

An object of type Type, cast from `object`, where members are references to `object` members

### Fehler/Exceptions

Warnung

Shall throw InvalidArgumentException if the type of `object` is or is derived from an internal class

Warnung

Shall throw InvalidArgumentException if Type is an interface

Warnung

Shall throw InvalidArgumentException if Type is a trait

Warnung

Shall throw InvalidArgumentException if Type is an abstract

Warnung

Shall throw InvalidArgumentException if Type is not compatible with the type of `object`

### Siehe auch

- Componere\cast

## Inhaltsverzeichnis

- Componere\cast — Casting
- Componere\cast_by_ref — Casting

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Componere\Abstract\Definition — The Componere\Abstract\Definition class
  - Componere\Abstract\Definition::addInterface — Add Interface
  - Componere\Abstract\Definition::addMethod — Add Method
  - Componere\Abstract\Definition::addTrait — Add Trait
  - Componere\Abstract\Definition::getReflector — Reflection
- Componere\Definition — The Componere\Definition class
  - Componere\Definition::__construct — Definition Construction
  - Componere\Definition::addConstant — Add Constant
  - Componere\Definition::addProperty — Add Property
  - Componere\Definition::register — Registration
  - Componere\Definition::isRegistered — State Detection
  - Componere\Definition::getClosure — Get Closure
  - Componere\Definition::getClosures — Get Closures
- Componere\Patch — The Componere\Patch class
  - Componere\Patch::__construct — Patch Construction
  - Componere\Patch::apply — Application
  - Componere\Patch::revert — Reversal
  - Componere\Patch::isApplied — State Detection
  - Componere\Patch::derive — Patch Derivation
  - Componere\Patch::getClosure — Get Closure
  - Componere\Patch::getClosures — Get Closures
- Componere\Method — The Componere\Method class
  - Componere\Method::__construct — Method Construction
  - Componere\Method::setPrivate — Accessibility Modification
  - Componere\Method::setProtected — Accessibility Modification
  - Componere\Method::setStatic — Accessibility Modification
  - Componere\Method::getReflector — Reflection
- Componere\Value — The Componere\Value class
  - Componere\Value::__construct — Value Construction
  - Componere\Value::setPrivate — Accessibility Modification
  - Componere\Value::setProtected — Accessibility Modification
  - Componere\Value::setStatic — Accessibility Modification
  - Componere\Value::isPrivate — Accessibility Detection
  - Componere\Value::isProtected — Accessibility Detection
  - Componere\Value::isStatic — Accessibility Detection
  - Componere\Value::hasDefault — Value Interaction
- Componere Funktionen
  - Componere\cast — Casting
  - Componere\cast_by_ref — Casting

# Fehlerbehandlung und Protokollierung

# Einführung

Diese Funktionen beschäftigen sich mit Fehlerbehandlung und -protokollierung. Sie ermöglichen es Ihnen, sowohl Ihre eigenen Fehlerbehandlungsregeln aufzustellen als auch die Art, wie Fehler protokolliert werden, zu ändern. Dies gestattet es Ihnen, die Fehlerbehandlung nach Ihren Bedürfnissen zu ändern und zu erweitern.

Die Protokollierungsfunktionen ermöglichen es Ihnen, Fehlermeldungen direkt an andere Maschinen, als Email, in Systemprotokolle usw. zu senden. Sie können so selektiv die wichtigsten Teile Ihrer Applikationen und Websites beobachten und protokollieren.

Die Fehlermeldungsfunktionen gestatten es Ihnen, die Art und das Ausmaß der erzeugten Fehlermeldungen von einfachen Hinweisen bis zu speziell angepassten Funktionsaufrufen beim Auftreten eines Fehlers nach Ihren Bedürfnissen anzupassen.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Laufzeit-Konfiguration

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Konfigurationsoptionen für Fehler und Protokollierung
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
error_reporting | NULL | `INI_ALL` |
fatal_error_backtraces | "1" | `INI_ALL` | Verfügbar seit PHP 8.5.0
display_errors | "1" | `INI_ALL` |
display_startup_errors | "1" | `INI_ALL` | Vor PHP 8.0.0 war der Standardwert `"0"`.
log_errors | "0" | `INI_ALL` |
log_errors_max_len | "1024" | `INI_ALL` | Seit PHP 8.0.0 wirkungslos; entfernt in PHP 8.1.0.
ignore_repeated_errors | "0" | `INI_ALL` |
ignore_repeated_source | "0" | `INI_ALL` |
report_memleaks | "1" | `INI_ALL` | Veraltet seit PHP 8.5.0
track_errors | "0" | `INI_ALL` | Veraltet seit PHP 7.2.0; entfernt in PHP 8.0.0.
html_errors | "1" | `INI_ALL` |
xmlrpc_errors | "0" | `INI_SYSTEM` |
xmlrpc_error_number | "0" | `INI_ALL` |
docref_root | "" | `INI_ALL` |
docref_ext | "" | `INI_ALL` |
error_prepend_string | NULL | `INI_ALL` |
error_append_string | NULL | `INI_ALL` |
error_log | NULL | `INI_ALL` |
error_log_mode | 0o644 | `INI_ALL` | Verfügbar seit PHP 8.2.0
syslog.facility | "LOG_USER" | `INI_SYSTEM` | Verfügbar seit PHP 7.3.0.
syslog.filter | "no-ctrl" | `INI_ALL` | Verfügbar seit PHP 7.3.0.
syslog.ident | "php" | `INI_SYSTEM` | Verfügbar seit PHP 7.3.0.

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`error_reporting` int

  Legt die Stufe der Fehlermeldung fest. Der Parameter ist entweder eine Ganzzahl, die ein Bitfeld darstellt, oder eine benannte Konstante. Die Stufen und Konstanten von error_reporting werden in Vordefinierte Konstanten und in der php.ini beschrieben. Mit der Funktion error_reporting() können die Werte zur Laufzeit festgelegt werden. Siehe auch die Direktive display_errors.

  Der Standardwert ist `E_ALL`.

  Vor PHP 8.0.0 war der Standardwert ``E_ALL` & ~`E_NOTICE` & ~`E_STRICT` & ~`E_DEPRECATED``. Das bedeutet, dass Fehler der Stufen `E_NOTICE`, `E_STRICT` und `E_DEPRECATED` nicht angezeigt wurden.

  > Hinweis: PHP-Konstanten außerhalb von PHP

  > Es ist nicht sinnvoll, PHP-Konstanten außerhalb von PHP, z. B. in der httpd.conf, zu verwenden, weshalb in solchen Fällen die int-Werte benötigt werden. Und weil im Laufe der Zeit weitere Fehlerstufen hinzugefügt werden, wird sich der Maximalwert (für `E_ALL`) wahrscheinlich ändern. Um also jetzt und auch in Zukunft alle Bitfelder abzudecken, sollte statt `E_ALL` ein größerer numerischer Wert wie `2147483647` (einschließlich aller Fehler, nicht nur `E_ALL`) verwendet werden.

`fatal_error_backtraces` bool
  Legt fest, ob schwerwiegende Fehler einen Backtrace enthalten sollen. Schwerwiegende Fehler sind `E_ERROR`, `E_CORE_ERROR`, `E_COMPILE_ERROR`, `E_USER_ERROR`, `E_RECOVERABLE_ERROR` und `E_PARSE`.
`display_errors` string

  Legt fest, ob Fehlermeldungen als Teil der Ausgabe auf dem Bildschirm ausgegeben oder vor dem Benutzer verborgen werden sollen.

  - `Off` - es werden keine Fehler angezeigt.
  - `On` oder `stdout` - Fehler werden an `stdout` gesendet. Dies ist die Standardeinstellung.
  - `stderr` - Fehler werden an `stderr` gesendet. Dies gilt nur für die SAPIs `CLI`, `phpdbg` und `CGI`.
  Die mitgelieferte `php.ini-development` setzt diese Option auf `On`; `php.ini-production` setzt sie auf `Off`.

  > Hinweis: Diese Funktionalität ist für die Entwicklung gedacht und sollte niemals auf Produktionssystemen (z. B. Systemen, die mit dem Internet verbunden sind) verwendet werden.

  > Hinweis:

  > Obwohl display_errors zur Laufzeit gesetzt werden kann (mit ini_set()), hat dies keine Auswirkung, wenn das Skript fatale Fehler hat. Dies liegt daran, dass die gewünschte Aktion zur Laufzeit nicht ausgeführt wird.

`display_startup_errors` bool

  Auch wenn display_errors aktiviert ist, werden Fehler, die während des Startvorgangs von PHP auftreten, nicht angezeigt. Es wird dringend empfohlen, display_startup_errors nur für die Fehlersuche zu aktivieren.

`log_errors` bool

  Legt fest, ob vom Skript verursachte Fehlermeldungen im Fehlerprotokoll des Servers oder in error_log protokolliert werden sollen und ist daher serverspezifisch.

  > Hinweis:

  > Es wird dringend empfohlen, auf Produktiv-Websites Fehler zu protokollieren, anstatt sie anzuzeigen.

`log_errors_max_len` int

  Legt die maximale Länge von log_errors in Bytes fest. Informationen über die Quelle werden in error_log hinzugefügt. Der Standardwert ist 1024 und der Wert 0 bedeutet, dass die maximale Länge überhaupt nicht angewendet wird. Diese Länge gilt für protokollierte Fehler, angezeigte Fehler und auch für $php_errormsg, aber nicht für explizit aufgerufene Funktionen wie error_log().

  Wird ein Wert vom Typ int verwendet, wird dieser Wert in Bytes gemessen. Es kann auch die Kurzschreibweise verwendet werden, wie in dieser FAQ beschrieben.
`ignore_repeated_errors` bool

  Wiederholte Meldungen nicht protokollieren. Wiederholte Fehler müssen in derselben Datei in derselben Zeile auftreten, es sei denn, ignore_repeated_source ist auf true gesetzt.

`ignore_repeated_source` bool

  Die Quelle der Meldung ignorieren, wenn wiederholte Meldungen ignoriert werden. Wenn diese Einstellung auf On gesetzt ist, werden Fehler mit wiederholten Meldungen aus verschiedenen Dateien oder anderen Zeilen des Quellcodes nicht protokolliert.

`report_memleaks` bool
  Wenn dieser Parameter auf On gesetzt ist (die Standardeinstellung), wird ein Bericht über Speicherlecks angezeigt, die vom Zend-Speichermanager entdeckt wurden. Auf Posix-Plattformen wird dieser Bericht an stderr gesendet. Unter Windows wird er mittels OutputDebugString() an den Debugger gesendet und kann mit Tools wie » DbgView angesehen werden. Dieser Parameter ist nur in einem Debug-Build wirksam und nur, wenn `E_WARNING` in der Liste von error_reporting enthalten ist.
  Warnung

  Dieses Feature ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

`track_errors` bool

  Wenn diese Option aktiviert ist, wird die letzte Fehlermeldung immer in der Variablen $php_errormsg abgelegt.

`html_errors` bool

  Wenn diese Option aktiviert ist, enthalten die Fehlermeldungen HTML-Tags. Die HTML-Fehlermeldungen sind anklickbar und verweisen auf die jeweilige Seite, auf der der Fehler oder die Funktion, die den Fehler verursacht hat, beschrieben wird. Diese Verweise werden durch docref_root und docref_ext beeinflusst.

  Ist diese Option deaktiviert, werden Fehlermeldungen nur als reiner Text angezeigt.

`xmlrpc_errors` bool

  Wenn diese Option aktiviert ist, wird die normale Fehlerberichterstattung deaktiviert und Fehler werden als XML-RPC-Fehlermeldungen formatiert.

`xmlrpc_error_number` int

  Wird als Wert für das XML-RPC-Element faultCode verwendet.

`docref_root` string

  Das neue Format für Fehlermeldungen enthält einen Verweis auf eine Seite, die den Fehler oder die Funktion, die den Fehler verursacht hat, beschreibt. Im Falle von Handbuchseiten kann das Handbuch in der gewünschten Sprache heruntergeladen und diese ini-Direktive auf die URL der lokalen Kopie gesetzt werden. Wenn die lokale Kopie des Handbuchs beispielsweise über `"/manual/"` erreichbar ist, kann einfach `docref_root=/manual/` verwendet werden. Darüber hinaus muss die Direktive docref_ext den Dateierweiterungen der Kopie entsprechend gesetzt werden: `docref_ext=.html`. Es ist auch möglich, externe Verweise zu verwenden, z. B. `docref_root=http://manual/en/` oder `docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon&url=http%3A%2F%2Fwww.php.net%2F"`.

  In den meisten Fällen sollte der Wert von docref_root mit einem Schrägstrich `"/"` enden. Wie das zweite Beispiel oben zeigt, ist dies jedoch nicht zwingend notwendig.

  > Hinweis:

  > Dieses Feature ist als Hilfe bei der Entwicklung gedacht, da es das Nachschlagen einer Funktionsbeschreibung erleichtert. Es sollte jedoch niemals auf Produktionssystemen verwendet werden (z. B. auf Systemen, die mit dem Internet verbunden sind).

`docref_ext` string

  Siehe docref_root.

  > Hinweis:

  > Der Wert von docref_ext muss mit einem Punkt `"."` beginnen.

`error_prepend_string` string

  Eine Zeichenkette, die vor einer Fehlermeldung ausgegeben wird; wird nur verwendet, wenn die Fehlermeldung auf dem Bildschirm angezeigt wird. Der Hauptzweck besteht darin, der Fehlermeldung zusätzliches HTML-Markup voranstellen zu können.

`error_append_string` string

  Eine Zeichenkette, die nach einer Fehlermeldung ausgegeben wird; wird nur verwendet, wenn die Fehlermeldung auf dem Bildschirm angezeigt wird. Der Hauptzweck besteht darin, zusätzliches HTML-Markup an die Fehlermeldung anhängen zu können.

`error_log` string

  Der Name der Datei, in der Skriptfehler protokolliert werden sollen. Die Datei muss für den Benutzer des Webservers beschreibbar sein. Wenn der spezielle Wert `syslog` verwendet wird, werden die Fehler stattdessen an den Systemlogger gesendet. Unter Unix ist dies syslog(3) und unter Windows das Ereignisprotokoll. Siehe auch syslog(). Wenn diese Direktive nicht gesetzt ist, werden Fehler an den SAPI-Fehlerlogger gesendet. Beim Apache ist das z. B. ein Fehlerprotokoll und beim CLI ist es `stderr`. Siehe auch error_log().

`error_log_mode` int

  Der Dateimodus (Berechtigungen) für die in error_log beschriebene Datei.

`syslog.facility` string

  Gibt an, welche Art von Programm die Meldung protokolliert; nur wirksam, wenn error_log auf "syslog" gesetzt ist.

`syslog.filter` string

  Gibt den Filtertyp an, mit dem die protokollierten Nachrichten gefiltert werden sollen. Erlaubte Zeichen werden unverändert weitergegeben; alle anderen werden in ihrer hexadezimalen Darstellung mit dem Präfix `\x` geschrieben.

  - `all` – die protokollierte Zeichenkette wird an Zeilenumbrüchen geteilt und alle Zeichen werden unverändert übgegeben
  - `ascii` – die protokollierte Zeichenkette wird an Zeilenumbrüchen geteilt und alle nicht druckbaren 7-Bit-ASCII-Zeichen werden maskiert
  - `no-ctrl` – die protokollierte Zeichenkette wird an Zeilenumbrüchen aufgeteilt und alle nicht druckbaren Zeichen werden maskiert
  - `raw` – alle Zeichen werden unverändert und ohne Zeilenumbruch an den Systemlogger übergeben (entspricht dem Verhalten vor PHP 7.3)
  Diese Einstellung ist nur relevant, wenn error_log auf "syslog" gesetzt ist und wenn syslog() aufgerufen wird.

  > Hinweis:

  > Der Filtertyp `raw` ist seit PHP 7.3.8 und PHP 7.4.0 verfügbar.

  Diese Direktive wird unter Windows nicht unterstützt.
`syslog.ident` string

  Gibt die Zeichenkette für die Identifizierung an, die jeder Meldung vorangestellt wird; nur relevant, wenn error_log auf "syslog" gesetzt ist.

# Vordefinierte Konstanten

Die aufgelisteten Konstanten stehen immer zur Verfügung, da sie zum Grundbestand von PHP gehören.

Die folgenden Konstanten (entweder die entsprechenden numerischen Werte oder ihre symbolischen Namen) werden als Bitmasken verwendet, um anzugeben, welche Fehler gemeldet werden sollen. Es ist möglich, diese Werte mit den Bit-Operatoren zu kombinieren oder bestimmte Fehlertypen auszublenden.

Tipp

In der php.ini können die Namen der Konstanten anstelle der reinen numerischen Werte, denen sie entsprechen, verwendet werden. Innerhalb der php.ini werden jedoch nur die Operatoren `|`, `~`, `^`, `!` und `&` verstanden.

Warnung

Es ist nicht möglich, die symbolischen Namen außerhalb von PHP zu verwenden. Zum Beispiel muss in der httpd.conf stattdessen der berechnete Wert der Bitmaske verwendet werden.

`E_ERROR` (int)
  Fatale Laufzeit-Fehler. Dies zeigt Fehler an, die nicht behoben werden können, z. B. Probleme bei der Speicherzuweisung. Die Ausführung des Skripts wird abgebrochen. Wert der Konstante: `1`
`E_WARNING` (int)
  Warnungen (nicht-fatale Fehler) zur Laufzeit des Skripts. Die Ausführung des Skripts wird nicht abgebrochen. Wert der Konstante: `2`
`E_PARSE` (int)
  Parser-Fehler während der Übersetzung. Parser-Fehler können nur vom Parser erzeugt werden. Wert der Konstante: `4`
`E_NOTICE` (int)
  Benachrichtigungen während der Laufzeit. Sie zeigen an, dass im Skript irgendetwas gefunden wurde, was einen Fehler verursachen könnte. Es ist aber genauso möglich, dass Benachrichtigungen im ordnungsgemäßen Ablauf eines Skripts ausgegeben werden. Wert der Konstante: `8`
`E_CORE_ERROR` (int)
  Fatale Fehler, die beim Starten von PHP auftreten. Dies ist ähnlich wie `E_ERROR`, nur dass diese Fehlermeldungen vom PHP-Kern erzeugt werden. Wert der Konstante: `16`
`E_CORE_WARNING` (int)
  Warnungen (nicht-fatale Fehler), die beim Starten von PHP auftreten. Dies ist ähnlich wie `E_WARNING`, nur dass diese Warnungen vom PHP-Kern erzeugt werden. Wert der Konstante: `32`
`E_COMPILE_ERROR` (int)
  Fatale Fehler zur Übersetzungszeit. Dies ist ähnlich wie `E_ERROR`, nur dass diese Fehlermeldungen von der Zend-Scripting-Engine erzeugt werden. Wert der Konstante: `64`
`E_COMPILE_WARNING` (int)
  Warnungen (nicht-fatale Fehler) zur Übersetzungszeit. Dies ist ähnlich wie `E_WARNING`, nur dass diese Warnungen von der Zend Scripting Engine erzeugt werden. Wert der Konstante: `128`
`E_DEPRECATED` (int)
  Benachrichtigungen über veralteten Code zur Laufzeit. Wenn diese Option aktiviert ist, werden Warnungen über Code ausgegeben, der in zukünftigen Versionen nicht mehr funktionieren wird. Wert der Konstante: `8192`
`E_USER_ERROR` (int)
  Benutzerdefinierte Fehlermeldungen. Dies ist ähnlich wie `E_ERROR`, nur dass diese Fehlermeldungen im PHP-Code mit trigger_error() erzeugt werden. Wert der Konstante: `256`
  Warnung

  Die Verwendung dieser Konstante mit trigger_error() ist seit PHP 8.4.0 veraltet. Es wird empfohlen, entweder eine Exception zu werfen oder stattdessen exit() aufzurufen.

`E_USER_WARNING` (int)
  Benutzerdefinierte Warnungen. Dies ist ähnlich wie `E_WARNING`, nur dass diese Warnungen im PHP-Code mit trigger_error() erzeugt werden. Wert der Konstante: `512`
`E_USER_NOTICE` (int)
  Benutzerdefinierte Benachrichtigungen. Dies ist ähnlich wie `E_NOTICE`, nur dass diese Benachrichtigungen im PHP-Code mit trigger_error() erzeugt werden. Wert der Konstante: `1024`
`E_USER_DEPRECATED` (int)
  Benutzerdefinierte Warnmeldung über veralteten Code. Dies entspricht `E_DEPRECATED`, nur dass diese Benachrichtigungen im PHP-Code mit trigger_error() erzeugt werden. Wert der Konstante: `16384`
`E_STRICT` (int)
  Vorschläge, die PHP zur Laufzeit über den ausgeführten Code ausgibt, um die Aufwärtskompatibilität zu gewährleisten. Wert der Konstante: `2048`
  Warnung

  Diese Stufe der Fehlermeldungen wird nicht mehr verwendet und ist seit PHP 8.4.0 veraltet.

`E_RECOVERABLE_ERROR` (int)
  "Exceptions" der Legacy-Engine, die einem abfangbaren fatalen Fehler entsprechen. Ähnlich wie Error, aber sie müssen von einem benutzerdefinierten Fehlerhandler abgefangen werden (siehe set_error_handler()). Wenn ein solcher Fehler nicht abgefangen wird, verhält er sich wie `E_ERROR`. Wert der Konstante: `4096`

  > Hinweis: Diese Stufe von Fehlermeldungen wird praktisch nicht verwendet. Der einzige Fall, in dem sie auftreten kann, ist, wenn die Interpretation eines Objekts als bool fehlschlägt. Dies kann nur bei internen Objekten vorkommen. Das häufigste Beispiel vor PHP 8.4.0 ist die Verwendung einer GMP-Instanz in einer Bedingung.

`E_ALL` (int)
  Eine Bitmaske, die alle Fehler, Warnungen und Hinweise enthält. Wert der Konstante: `30719`
  Warnung

  Vor PHP 8.4 war der Wert der Konstante `32767`

# Beispiele

Unten können wir ein Beispiel dafür sehen, wie die Fehlercode-Funktionen in PHP benutzt werden. Wir definieren eine Fehlerfunktion, die die Information unter Verwendung des XML-Formates in einer Datei speichert und diese per E-Mail dem Entwickler sendet, wenn ein schwerer Fehler in der Programmlogik auftritt.

Beispiel #1 Fehlerbehandlung in einem Script

    <?php
    // Wir werden unsere Fehler selbst behandeln
    error_reporting(0);

    // Benutzerdefinierte Fehlerfunktion
    function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars)
    {
        // Zeitstempel für den Fehlereintrag
        $dt = date("Y-m-d H:i:s (T)");

        // Definiert ein assoziatives Array für den Fehler
        // Tatsächlich sollten wir nur
        // E_WARNING, E_NOTICE, E_USER_ERROR,
        // E_USER_WARNING und E_USER_NOTICE beachten.
        $errortype = array (
                    E_ERROR              => 'Fehler',
                    E_WARNING            => 'Warnung',
                    E_PARSE              => 'Parser-Fehler',
                    E_NOTICE             => 'Hinweis',
                    E_CORE_ERROR         => 'Kern-Fehler',
                    E_CORE_WARNING       => 'Kern-Warnung',
                    E_COMPILE_ERROR      => 'Kompilierungsfehler',
                    E_COMPILE_WARNING    => 'Kompilierungswarnung',
                    E_USER_ERROR         => 'Benutzerfehler',
                    E_USER_WARNING       => 'Benutzerwarnung',
                    E_USER_NOTICE        => 'Benutzerhinweis',
                    E_STRICT             => 'Laufzeitwarnung',
                    E_RECOVERABLE_ERROR  => 'Abfangbarer fataler Fehler'
                    );
        // Satz von Fehlern für welche ein Eintrag gespeichert wird.
        $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);

        $err = "<errorentry>\n";
        $err .= "\t<datetime>" . $dt . "</datetime>\n";
        $err .= "\t<errornum>" . $errno . "</errornum>\n";
        $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
        $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
        $err .= "\t<scriptname>" . $filename . "</scriptname>\n";
        $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";

        if (in_array($errno, $user_errors)) {
            $err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variablen") . "</vartrace>\n";
        }
        $err .= "</errorentry>\n\n";

        // Zum Test:
        // echo $err;

        // Speicher den Fehler im Log und schicke mir eine E-Mail falls es ein kritischer Benutzerfehler ist.
        error_log($err, 3, "/usr/local/php4/error.log");
        if ($errno == E_USER_ERROR) {
            mail("phpdev@example.com", "Critical User Error", $err);
        }
    }

    function distance($vect1, $vect2)
    {
        if (!is_array($vect1) || !is_array($vect2)) {
            trigger_error("Falsche Parameter, Arrays erwartet", E_USER_ERROR);
            return NULL;
        }

        if (count($vect1) != count($vect2)) {
            trigger_error("Die Vektoren müssen die selbe Dimension besitzen.", E_USER_ERROR);
            return NULL;
        }

        for ($i=0; $i<count($vect1); $i++) {
            $c1 = $vect1[$i]; $c2 = $vect2[$i];
            $d = 0.0;
            if (!is_numeric($c1)) {
                trigger_error("Koordinate $i im Vektor 1 ist keine Nummer, verwende stattdessen Null.",
                                E_USER_WARNING);
                $c1 = 0.0;
            }
            if (!is_numeric($c2)) {
                trigger_error("Koordinate $i im Vektor 2 ist keine Nummer, verwende stattdessen Null",
                                E_USER_WARNING);
                $c2 = 0.0;
            }
            $d += $c2*$c2 - $c1*$c1;
        }
        return sqrt($d);
    }

    $old_error_handler = set_error_handler("userErrorHandler");

    //Undefinierte Konstante, generiert eine Warnung
    $t = I_AM_NOT_DEFINED;

    // Definiere einige "Vektoren"
    $a = array(2, 3, "foo");
    $b = array(5.5, 4.3, -1.6);
    $c = array(1, -3);

    // Benutzerfehler erzeugen
    $t1 = distance($c, $b) . "\n";

    // Einen weiteren Benutzerfehler erzeugen
    $t2 = distance($b, "i am not an array") . "\n";

    // Eine Warnung erzeugen
    $t3 = distance($a, $b) . "\n";

    ?>

# Fehlerbehandlungsfunktionen

# Siehe auch

Siehe auch syslog().

# debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtrace — Erzeugt eine Ablaufverfolgung

### Beschreibung

function debug_backtrace(int `$options` = `DEBUG_BACKTRACE_PROVIDE_OBJECT`, int `$limit` = 0): array

debug_backtrace() erzeugt eine PHP-Ablaufverfolgung.

### Parameter-Liste

`options`

  Dieser Parameter ist eine Bitmaske für die folgenden Optionen:

  debug_backtrace()-Optionen
  DEBUG_BACKTRACE_PROVIDE_OBJECT | Legt fest, ob der "object"-Index befüllt werden soll.
  DEBUG_BACKTRACE_IGNORE_ARGS | Legt fest, ob der "args"-Index, welcher alle Funktions- oder Methodenargumente enthält, ausgelassen werden soll, um Arbeitsspeicher zu sparen.

  > Hinweis:

  > Es gibt vier mögliche Kombinationen:

  > debug_backtrace()-Optionen
  > `debug_backtrace()` | Füllt beide Indizes
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT)`
  > `debug_backtrace(1)`
  > `debug_backtrace(0)` | Lässt den Index `"object"` weg und belegt den Index `"args"`.
  > `debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)` | Lässt die Indizes `"object"` und `"args"` weg.
  > `debug_backtrace(2)`
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT|DEBUG_BACKTRACE_IGNORE_ARGS)` | Belegt den Index `"object"` und lässt den Index `"args"` weg.
  > `debug_backtrace(3)`

`limit`

  Dieser Parameter kann benutzt werden, um die Anzahl an zurückgegebenen Stackframes zu limitieren. Standardmäßig (`limit`=`0`) werden alle Stackframes zurückgegeben.

### Rückgabewerte

Gibt ein assoziatives Array zurück. Als zurückgegebene Arrayelemente von debug_backtrace() sind möglich:

Mögliche Rückgabewerte von debug_backtrace()
Name | Typ | Beschreibung
--- | --- | ---
function | string | Der Name der aktuell ausgeführten Funktion. Siehe auch __FUNCTION__.
line | int | Die aktuelle Zeilennummer. Siehe auch __LINE__.
file | string | Der aktuelle Dateiname. Siehe auch __FILE__.
class | string | Der aktuelle Name der Klasse. Siehe auch __CLASS__.
object | object | Das aktuelle Objekt.
type | string | Der aktuelle Typ des Aufrufs. Falls der Aufruf in einer Methode erfolgte, wird "->" zurückgegeben. Falls der Aufruf aus einer statischen Funktion erfolgte, wird "::" zurückgegeben, und falls der Aufruf aus einer Funktion erfolgte, wird nichts zurückgegeben.
args | array | Falls der Aufruf aus einer Funktion erfolgte, werden hier die Funktionsargumente aufgelistet. Falls der Aufruf aus einer eingebundenen Datei erfolgte, werden die Namen der Include-Dateien angegeben.

### Beispiele

Beispiel #1 debug_backtrace()-Beispiel

    <?php
    // Dateiname: /tmp/a.php

    function a_test($str)
    {
        echo "\nHi: $str";
        var_dump(debug_backtrace());
    }

    a_test('friend');
    ?>

    <?php
    // Dateiname: /tmp/b.php
    include_once '/tmp/a.php';
    ?>

Ähnliche Ergebnisse wie die folgenden beim Aufruf von /tmp/b.php:

    Hi: friend
    array(2) {
    [0]=>
    array(4) {
        ["file"] => string(10) "/tmp/a.php"
        ["line"] => int(10)
        ["function"] => string(6) "a_test"
        ["args"]=>
        array(1) {
          [0] => &string(6) "friend"
        }
    }
    [1]=>
    array(4) {
        ["file"] => string(10) "/tmp/b.php"
        ["line"] => int(2)
        ["args"] =>
        array(1) {
          [0] => string(10) "/tmp/a.php"
        }
        ["function"] => string(12) "include_once"
      }
    }

### Siehe auch

- trigger_error() - Erzeugt eine benutzerdefinierte Fehlermeldung/Warnung/Benachrichtigung
- debug_print_backtrace() - Gibt die Daten für eine Ablaufverfolgung aus

# debug_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtrace — Gibt die Daten für eine Ablaufverfolgung aus

### Beschreibung

function debug_print_backtrace(int `$options` = 0, int `$limit` = 0): void

debug_print_backtrace() gibt eine PHP-Ablaufverfolgung aus. Diese enthält Ausgaben zu allen Funktionsaufrufen, mit include oder require eingebundenen Dateien und mit eval() ausgeführtem Code.

### Parameter-Liste

`options`

  Über diesen Parameter kann eine Bitmaske mit folgenden möglichen Optionen übergeben werden:

  debug_print_backtrace()-Optionen
  DEBUG_BACKTRACE_IGNORE_ARGS | Gibt an, ob der "args"-Index aller Funktions- und Methoden-Argumente weggelassen werden soll (z. B. um Speicher zu sparen).

`limit`

  Hiermit kann die Anzahl der auszugebenden Aufrufebenen begrenzt werden. Der Vorgabewert (`limit`=`0`) führt zur Ausgabe aller Aufrufe.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 debug_print_backtrace()-Beispiel

    <?php
    // include.php-Datei

    function a() {
        b();
    }

    function b() {
        c();
    }

    function c(){
        debug_print_backtrace();
    }

    a();

    ?>

    <?php
    // test.php-Datei
    // Dies ist die Datei, die Sie ausführen sollten

    include 'include.php';
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    #0  c() called at [/tmp/include.php:10]
    #1  b() called at [/tmp/include.php:6]
    #2  a() called at [/tmp/include.php:17]
    #3  include(/tmp/include.php) called at [/tmp/test.php:3]

### Siehe auch

- debug_backtrace() - Erzeugt eine Ablaufverfolgung

# error_clear_last

(PHP 7, PHP 8)

error_clear_last — Löscht den zuletzt aufgetretenen Fehler

### Beschreibung

function error_clear_last(): void

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Löscht den letzten Fehler, sodass er nicht mehr mit error_get_last() abgerufen werden kann.

### Beispiele

Beispiel #1 error_clear_last()-Beispiel

    <?php
    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());

    @$a = $b;

    var_dump(error_get_last());
    error_clear_last();
    var_dump(error_get_last());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    NULL
    NULL
    array(4) {
      ["type"]=>
      int(8)
      ["message"]=>
      string(21) "Undefined variable: b"
      ["file"]=>
      string(9) "%s"
      ["line"]=>
      int(6)
    }
    NULL

### Siehe auch

- Error constants

# error_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_last — Liefert den zuletzt aufgetretenen Fehler

### Beschreibung

function error_get_last(): ?array

Liefert Informationen über den zuletzt aufgetretenen Fehler

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein assoziatives Array zurück das den zuletzt aufgetretenen Fehler mit den Elementen "type" (für die Art des Fehlers), "message" (für die Fehlermeldung) sowie "file" und "line" (für den Ort an dem der Fehler aufgetreten ist) beschreibt. Wenn bisher noch kein Fehler aufgetreten ist, wird `null` zurückgegeben.

### Beispiele

Beispiel #1 error_get_last()-Beispiel

    <?php
    echo $a;
    print_r(error_get_last());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [type] => 8
        [message] => Undefined variable: a
        [file] => C:\WWW\index.php
        [line] => 2
    )

### Siehe auch

- Fehlerkonstanten
- Die Variable $php_errormsg
- error_clear_last() - Löscht den zuletzt aufgetretenen Fehler
- Die Direktive `display_errors`
- Die Direktive `html_errors`
- Die Direktive `xmlrpc_errors`

# error_log

(PHP 4, PHP 5, PHP 7, PHP 8)

error_log — Sendet eine Fehlermeldung an die definierten Fehlerbehandlungsroutinen

### Beschreibung

function error_log(
string `$message`,
int `$message_type` = 0,
?string `$destination` = `null`,
?string `$additional_headers` = `null`
): bool

Sendet eine Fehlermeldung an das Fehlerprotokoll (Errorlog) des Webservers, oder an eine Datei.

### Parameter-Liste

`message`

  Die Fehlermeldung, die protokolliert werden soll.

`message_type`

  Sagt, wohin der Fehler gehen soll. Folgende Meldungstypen sind möglich:

  error_log()-Protokolltypen
  0 | `message` wird an das Log-Subsystem von PHP gesendet, das abhängig von der Einstellung in der Konfigurationsdirektive error_log das Errorlogging des Betriebssystems verwendet oder in eine Datei schreibt. Dies ist die Standardeinstellung.
  1 | `message` wird via E-Mail an die Adresse gesendet, die im Parameter `destination` angegeben wurde. Dies ist der einzige Meldungstyp, bei dem der vierte Parameter `additional_headers` verwendet wird.
  2 | Diese Option ist nicht mehr verfügbar.
  3 | `message` wird an die Datei `destination` angefügt. Ein Zeilenumbruch wird nicht automatisch an das Ende des `message`-Strings angehängt.
  4 | `message` wird direkt zum SAPI-Logging-Handler gesendet.

`destination`

  Das Ziel. Die jeweilige Bedeutung hängt wie oben beschrieben vom Parameter `message_type` ab.

`additional_headers`

  Die zusätzlichen Kopfzeilen. Dieser Parameter wird verwendet, wenn der Parameter `message_type` auf `1` gesetzt ist. Dieser Meldungstyp verwendet dieselbe interne Funktion wie mail().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. Wenn `message_type` null ist, gibt diese Funktion immer `true` zurück, unabhängig davon, ob der Fehler protokolliert werden konnte oder nicht.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `destination` und `additional_headers` sind jetzt nullbar.

### Beispiele

Beispiel #1 error_log()-Beispiele

    <?php
    // Sende eine Nachricht an das Serverlog, falls
    // keine Verbindung zur Datenbank herstellbar ist.
    if (!Ora_Logon($benutzername, $passwort)) {
        error_log("Die Oracle-Datenbank ist nicht erreichbar!", 0);
    }

    // Benachrichtige den Administrator per E-Mail, falls kein FOO mehr verfügbar ist.
    if (!($foo = allocate_new_foo())) {
        error_log("Wir haben ein Problem: FOO ist alle!", 1,
                   "operator@example.com");
    }

    // Eine weitere Möglichkeit, error_log() aufzurufen:
    error_log("Du hast Mist gebaut!", 3, "/var/tmp/meine-fehler.log");
    ?>

### Anmerkungen

Warnung

error_log() ist nicht binär-sicher. `message` wird durch ein Null-Zeichen abgeschnitten.

Tipp

`message` sollte keine Null-Zeichen enthalten. Es ist zu beachten, dass `message` an eine Datei, das Syslog, per Mail usw. gesendet werden kann. Geeignete Konvertierungs/Maskierungs-Funktionen, base64_encode(), rawurlencode() oder addslashes(), sind anzuwenden bevor error_log() aufgerufen wird.

# error_reporting

(PHP 4, PHP 5, PHP 7, PHP 8)

error_reporting — Gibt an, welche PHP-Fehlermeldungen gemeldet werden

### Beschreibung

function error_reporting(?int `$error_level` = `null`): int

Mit error_reporting() wird die Direktive error_reporting zur Laufzeit des Programms gesetzt. In PHP gibt es viele Stufen für die Anzeige von Fehlermeldungen, die mit dieser Funktion für die Dauer (Laufzeit) des Skripts eingestellt werden kann. Wenn das optionale Argument `error_level` nicht übergeben wird, gibt error_reporting() die aktuelle Stufe der Fehlermeldungen zurück.

### Parameter-Liste

`error_level`

  Die neue Stufe von error_reporting. Es können sowohl eine numerische Bitmaske als auch benannte Konstanten übergeben werden. Der Einsatz benannter Konstanten wird empfohlen, um die Kompatibilität mit zukünftigen Versionen sicherzustellen. Wann immer Konstanten für Fehlerstufen hinzugefügt werden, erweitert sich der genutzte Integerbereich, sodass ältere Integerkonstanten nicht unbedingt weiter das erwartete Verhalten zeigen.

  Die verfügbaren Konstanten und die Bedeutungen der jeweiligen Fehlerstufe sind im Abschnitt Vordefinierte Konstanten beschrieben.

### Rückgabewerte

Gibt das Level von error_reporting zurück, bevor es auf `error_level` geändert wird.

> Hinweis: Der Fehlerkontroll-Operator `@` ändert den Wert von `error_level` während der Fehlerbehandlung.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `error_level` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 error_reporting()-Beispiel

    <?php

    // Fehlermeldungen komplett abschalten
    error_reporting(0);

    // Nur einfache Fehler melden
    error_reporting(E_ERROR | E_WARNING | E_PARSE);

    // E_NOTICE ist sinnvoll, um uninitialisierte oder
    // falsch geschriebene Variablen zu entdecken
    error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);

    // Melde alle Fehler außer E_NOTICE
    error_reporting(E_ALL & ~E_NOTICE);

    // Melde alle PHP-Fehler
    error_reporting(E_ALL);

    // Melde alle PHP-Fehler
    error_reporting(-1);

    // Dies entspricht error_reporting(E_ALL);
    ini_set('error_reporting', E_ALL);

    ?>

### Anmerkungen

Tipp

Durch Übergeben des Wertes `-1` werden alle möglichen Fehler angezeigt, auch wenn neue Level in zukünftigen PHP-Versionen hinzugefügt werden. Das Verhalten ist äquivalent zur Übergabe der Konstante `E_ALL`.

### Siehe auch

- Die Direktive display_errors
- Die Direktive html_errors
- Die Direktive xmlrpc_errors
- Der Operator für die Fehlerkontrolle
- ini_set() - Sets the value of a configuration option

# get_error_handler

(PHP 8 >= 8.5.0)

get_error_handler — Gets the user-defined error handler function

### Beschreibung

function get_error_handler(): ?callable

Returns the current error handler function, if any.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the currently defined error handler (if any). If the built-in error handler is used `null` is returned.

The returned handler is the exact callable value that was passed to set_error_handler() to define it.

### Beispiele

Beispiel #1 get_error_handler() example

    <?php

    $handler = function (int $errno, string $errstr, ?string $errfile, ?int $errline) {
         echo "Error: " . $errstr . "\n";
    };

    var_dump(get_error_handler()); // NULL

    set_error_handler($handler);

    var_dump(get_error_handler() === $handler); // bool(true)

    ?>

### Anmerkungen

Tipp

Prior to PHP 8.5.0, this functionality can be provided by the following polyfill:

    <?php
    if (!function_exists('get_error_handler')) {
        function noop_error_handler() {
        }
        function get_error_handler(): ?callable {
            $handler = set_error_handler('noop_error_handler');
            restore_error_handler();
            return $handler;
        }
    }
    ?>

### Siehe auch

- error_reporting() - Gibt an, welche PHP-Fehlermeldungen gemeldet werden
- set_error_handler() - Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung
- restore_error_handler() - Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her
- trigger_error() - Erzeugt eine benutzerdefinierte Fehlermeldung/Warnung/Benachrichtigung
- error level constants

# get_exception_handler

(PHP 8 >= 8.5.0)

get_exception_handler — Gets the user-defined exception handler function

### Beschreibung

function get_exception_handler(): ?callable

Returns the current exception handler function, if any.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the currently defined exception handler. If no handler is defined, `null` is returned.

The returned handler is the exact callable value that was passed to set_exception_handler() to define it.

### Beispiele

Beispiel #1 get_exception_handler() example

    <?php

    $handler = function (Throwable $ex) {
         echo "Exception: " . $ex::class . ": " . $ex->getMessage() . "\n";
    };

    var_dump(get_exception_handler()); // NULL

    set_exception_handler($handler);

    var_dump(get_exception_handler() === $handler); // bool(true)

    ?>

### Anmerkungen

Tipp

Prior to PHP 8.5.0, this functionality can be provided by the following polyfill:

    <?php
    if (!function_exists('get_exception_handler')) {
        function noop_exception_handler() {
        }
        function get_exception_handler(): ?callable {
            $handler = set_exception_handler('noop_exception_handler');
            restore_exception_handler();
            return $handler;
        }
    }
    ?>

### Siehe auch

- set_exception_handler() - Installiert einen benutzerdefinierten Exceptionhandler
- restore_exception_handler() - Stellt den vorherigen Exceptionhandler wieder her
- restore_error_handler() - Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her
- error_reporting() - Gibt an, welche PHP-Fehlermeldungen gemeldet werden
- Exceptions

# restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handler — Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her

### Beschreibung

function restore_error_handler(): true

Diese Funktion wird benutzt, um eine mit set_error_handler() gesetzte Fehlerbehandlungsfunktion wieder zurückzusetzen und zur zuvor benutzten Fehlerbehandlung zurückzukehren (dies kann entweder eine eingebaute oder eine benutzerdefinierte Funktion sein).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `true` zurück.

### Beispiele

Beispiel #1 restore_error_handler()-Beispiel

Prüft, ob unserialize() einen Fehler verursacht und stellt dann die ursprüngliche Fehlerbehandlung wieder her.

    <?php
    function unserialize_handler($errno, $errstr)
    {
        echo "Ungültiger serialisierter Wert.\n";
    }

    $serialized = 'foo';
    set_error_handler('unserialize_handler');
    $original = unserialize($serialized);
    restore_error_handler();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ungültiger serialisierter Wert.

### Siehe auch

- error_reporting() - Gibt an, welche PHP-Fehlermeldungen gemeldet werden
- set_error_handler() - Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung
- get_error_handler() - Gets the user-defined error handler function
- restore_exception_handler() - Stellt den vorherigen Exceptionhandler wieder her
- trigger_error() - Erzeugt eine benutzerdefinierte Fehlermeldung/Warnung/Benachrichtigung

# restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handler — Stellt den vorherigen Exceptionhandler wieder her

### Beschreibung

function restore_exception_handler(): true

Diese Funktion kann genutzt werden, um die Installation eines Exceptionhandlers mit set_exception_handler() rückgängig zu machen und den vorherigen Handler wieder in Kraft zu setzen (entweder den eingebauten oder eine andere benutzerdefinierte Funktion).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `true` zurück.

### Beispiele

Beispiel #1 restore_exception_handler()-Beispiel

    <?php
    function exception_handler_1(Exception $e)
    {
        echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
    }

    function exception_handler_2(Exception $e)
    {
        echo '[' . __FUNCTION__ . '] ' . $e->getMessage();
    }

    set_exception_handler('exception_handler_1');
    set_exception_handler('exception_handler_2');

    restore_exception_handler();

    throw new Exception('Dies löst den ersten Exceptionhandler aus ...');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    [exception_handler_1] Dies löst den ersten Exceptionhandler aus ...

### Siehe auch

- set_exception_handler() - Installiert einen benutzerdefinierten Exceptionhandler
- get_exception_handler() - Gets the user-defined exception handler function
- set_error_handler() - Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung
- restore_error_handler() - Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her
- error_reporting() - Gibt an, welche PHP-Fehlermeldungen gemeldet werden

# set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung

### Beschreibung

function set_error_handler(?callable `$callback`, int `$error_levels` = `E_ALL`): ?callable

Setzt eine benutzerdefinierte Funktion (`callback`), um Fehler in einem Skript zu behandeln.

Mit dieser Funktion können während der Laufzeit benutzerdefinierte Fehlerbehandlungen erstellt werden, beispielsweise in Anwendungen, die bei einem kritischen Fehler die Löschung von Daten bzw. Dateien erfordert, oder wenn es nötig ist, unter bestimmten Bedingungen (mit der Funktion trigger_error()) eine Fehlermeldung zu generieren.

Es ist unbedingt zu beachten, dass auf diese Weise die standardmäßige PHP-Fehlerbehandlung für die durch `error_levels` angegebenen Fehlertypen vollkommen umgangen wird, außer wenn die Callback-Funktion `false` zurückgibt. Die Einstellungen der Funktion error_reporting() haben keine Auswirkung und die Fehlerbehandlungsroutine wird ohne Rücksicht darauf aufgerufen, es ist jedoch immer noch möglich, den aktuellen Wert von error_reporting zu lesen und entsprechend zu handeln.

Es ist auch zu beachten, dass die Fehlerbehandlung dafür zuständig ist, bei Bedarf exit() aufzurufen, um die Ausführung des Skripts zu beenden. Nach der Funktion für die Fehlerbehandlung wird die Ausführung des Skripts bei der Anweisung fortgesetzt, die auf die Fehler verursachende Anweisung folgt.

Die folgenden Fehlertypen können nicht von einer benutzerdefinierten Funktion behandelt werden: `E_ERROR`, `E_PARSE`, `E_CORE_ERROR`, `E_CORE_WARNING`, `E_COMPILE_ERROR` und `E_COMPILE_WARNING` unabhängig davon, wo sie ausgelöst wurden, und die meisten `E_STRICT`, die in der Datei ausgelöst werden, in der set_error_handler() aufgerufen wird.

Falls Fehler auftreten, bevor das Skript ausgeführt wird (z. B. beim Hochladen von Dateien), kann eine benutzerdefinierte Fehlerbehandlung nicht aufgerufen werden, weil sie zu diesem Zeitpunkt noch nicht registriert ist.

### Parameter-Liste

`callback`

  Falls `null` übergeben wird, wird der Handler auf seinen Standardwert zurückgesetzt. Andernfalls ist der Handler ein Callback mit der folgenden Signatur:

  function handler(
  int `$errno`,
  string `$errstr`,
  string `$errfile` = ?,
  int `$errline` = ?,
  array `$errcontext` = ?
  ): bool
  `errno`
    Dem erstem Parameter, `errno`, wird der Schweregrad des ausgelösten Fehlers als Integer übergeben.
  `errstr`
    Dem zweiten Parameter, `errstr`, wird die Fehlermeldung als String übergeben.
  `errfile`
    Wenn der Callback einen dritten Parameter akzeptiert, nämlich `errfile`, wird der Dateiname, in dem der Fehler aufgetreten ist, als String übergeben.
  `errline`
    Wenn der Callback einen vierten Parameter akzeptiert, nämlich `errline`, wird die Zeilennummer, in der der Fehler aufgetreten ist, als Integer übergeben.
  `errcontext`
    Wenn der Callback einen fünften Parameter akzeptiert, nämlich `errcontext`, wird ihm ein Array übergeben, das auf die aktive Symboltabelle zu dem Punkt zeigt, an dem der Fehler auftrat. Mit anderen Worten: `errcontext` enthält ein Array mit allen Variablen, die im fehlerauslösenden Bereich existierten. Benutzerdefinierte Fehlerbehandlungen dürfen den Fehlerkontext nicht verändern.
    Warnung

    Dieser Parameter ist von PHP 7.2.0 an MISSBILLIGT und wurde in PHP 8.0.0 ENTFERNT. Wenn die Funktion diesen Parameter ohne Vorgabe definiert, wird beim Aufruf der Funktion der Fehler "too few arguments" (zu wenig Parameter) ausgelöst.

  Falls diese Funktion `false` zurückgibt, wird mit der normalen Fehlerbehandlung fortgesetzt.

`error_levels`

  Kann wie die php.ini-Konfigurationseinstellung error_reporting, die bestimmt, welche Fehler angezeigt werden, zum Maskieren des Aufrufs der `callback`-Funktion verwendet werden. Wird diese Maske nicht gesetzt, wird der `callback` unabhängig von der Einstellung error_reporting bei jedem Fehler aufgerufen.

### Rückgabewerte

Gibt die zuvor definierte Fehlerbehandlungsroutine (falls eine definiert wurde) als callable zurück. Wenn der eingebaute Errorhandler verwendet wurde, wird `null` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `errcontext` wurde entfernt und wird nicht mehr an Benutzer-Callbacks übergeben.
7.2.0 | `errcontext` wurde missbilligt. Die Verwendung dieses Parameters erzeugt nun einen `E_DEPRECATED`-Hinweis.

### Beispiele

Beispiel #1 Fehlerbehandlung mit set_error_handler() und trigger_error()

Das untenstehende Beispiel zeigt die Behandlung von internen Ausnahmen, indem Fehler ausgelöst und durch eine benutzerdefinierte Funktion behandelt werden:

    <?php
    // Fehlerbehandlungsfunktion
    function myErrorHandler($fehlercode, $fehlertext, $fehlerdatei, $fehlerzeile)
    {
        if (!(error_reporting() & $fehlercode)) {
            // Dieser Fehlercode ist nicht in error_reporting enthalten
            return false;
        }

        // $fehlertext muss möglicherweise maskiert werden:
        $fehlertext = htmlspecialchars($fehlertext);

        switch ($fehlercode) {
        case E_USER_ERROR:
            echo "<b>Mein FEHLER</b> [$fehlercode] $fehlertext<br />\n";
            echo "  Fataler Fehler in Zeile $fehlerzeile in der Datei $fehlerdatei";
            echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
            echo "Abbruch...<br />\n";
            break;

        case E_USER_WARNING:
            echo "<b>Meine WARNUNG</b> [$fehlercode] $fehlertext<br />\n";
            break;

        case E_USER_NOTICE:
            echo "<b>Mein HINWEIS</b> [$fehlercode] $fehlertext<br />\n";
            break;

        default:
            echo "Unbekannter Fehlertyp: [$fehlercode] $fehlertext<br />\n";
            break;
        }

        /* Damit die PHP-interne Fehlerbehandlung nicht ausgeführt wird */
        return true;
    }

    // Funktion zum Test der Fehlerbehandlung
    function logarithmisch_skalieren($vektor, $skalierung)
    {
        if (!is_numeric($skalierung) || $skalierung <= 0) {
            trigger_error("log(x) ist für x <= 0 nicht definiert, Sie verwendeten: skalierung = $skalierung", E_USER_ERROR);
        }

        if (!is_array($vektor)) {
            trigger_error("Fehlerhafter Eingabevektor, es wird ein Wertearray erwartet", E_USER_WARNING);
            return null;
        }

        $temp = array();
        foreach($vektor as $pos => $wert) {
            if (!is_numeric($wert)) {
                trigger_error("Der Wert an Position $pos ist keine Zahl, verwende 0 (Null)", E_USER_NOTICE);
                $wert = 0;
            }
            $temp[$pos] = log($skalierung) * $wert;
        }

        return $temp;
    }

    // auf die benutzerdefinierte Fehlerbehandlung umstellen
    $alter_error_handler = set_error_handler("myErrorHandler");

    // ein paar Fehler auslösen, zuerst wird ein gemischtes Array mit einem
    // nichtnumerischen Eintrag definiert
    echo "Vektor a\n";
    $a = array(2, 3, "foo", 5.5, 43.3, 21.11);
    print_r($a);

    // ein zweites Array erzeugen
    echo "----\nVektor b - ein Hinweis (b = log(PI) * a)\n";
    /* Der Wert an Position $pos ist keine Zahl, verwende 0 (Null) */
    $b = logarithmisch_skalieren($a, M_PI);
    print_r($b);

    // das gibt Ärger: statt eines Arrays wird eine Zeichenkette übergeben
    echo "----\nVektor c - eine Warnung\n";
    /* Fehlerhafter Eingabevektor, es wird ein Wertearray erwartet */
    $c = logarithmisch_skalieren("kein Array", 2.3);
    var_dump($c); // NULL

    // dies ist ein kritischer Fehler: log ist für Null oder negative Werte
    // nicht definiert
    echo "----\nVektor d - fataler Fehler\n";
    /* log(x) ist für x <= 0 nicht definiert, Sie verwendeten: skalierung = $skalierung */
    $d = logarithmisch_skalieren($a, -2.5);
    var_dump($d); // wird nie erreicht
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Vektor a
    Array
    (
        [0] => 2
        [1] => 3
        [2] => foo
        [3] => 5.5
        [4] => 43.3
        [5] => 21.11
    )
    ----
    Vektor b - ein Hinweis (b = log(PI) * a)
    <b>Mein HINWEIS</b> [1024] Der Wert an Position 2 ist keine Zahl, verwende 0 (Null)<br />
    Array
    (
        [0] => 2.2894597716988
        [1] => 3.4341896575482
        [2] => 0
        [3] => 6.2960143721717
        [4] => 49.566804057279
        [5] => 24.165247890281
    )
    ----
    Vektor c - eine Warnung
    <b>Meine WARNUNG</b> [512] Fehlerhafter Eingabevektor, es wird ein Wertearray erwartet<br />
    NULL
    ----
    Vektor d - fataler Fehler
    <b>Mein FEHLER</b> [256] log(x) ist für x <= 0 nicht definiert, Sie verwendeten: skalierung = -2.5<br />
      Fataler Fehler in Zeile 35 in der Datei trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
    Abbruch...<br />

### Siehe auch

- ErrorException
- error_reporting() - Gibt an, welche PHP-Fehlermeldungen gemeldet werden
- restore_error_handler() - Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her
- get_error_handler() - Gets the user-defined error handler function
- trigger_error() - Erzeugt eine benutzerdefinierte Fehlermeldung/Warnung/Benachrichtigung
- Errorlevel-Konstanten

# set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handler — Installiert einen benutzerdefinierten Exceptionhandler

### Beschreibung

function set_exception_handler(?callable `$callback`): ?callable

Setzt den Standard-Exceptionhandler für Exceptions, die nicht von einem try/catch-Block aufgefangen wurden. Nach dem Aufruf von `callback` wird die Ausführung angehalten.

### Parameter-Liste

`callback`

  Die Funktion, die aufgerufen werden soll, wenn eine nicht aufgefangene Exception auftritt. Diese Handler-Funktion muss einen Parameter akzeptieren, und zwar das Throwable-Objekt, das ausgelöst wurde. Sowohl Error als auch Exception implementieren das Throwable-Interface. Dies ist die Handler-Signatur:

  function handler(Throwable `$ex`): void

  Stattdessen kann `null` übergeben werden, um den Handler auf seinen Standardwert zurückzusetzen.

### Rückgabewerte

Gibt den zuvor definierten Exception-Handler zurück oder `null` bei Fehlern oder wenn kein vorheriger Exception-Handler definiert war.

### Beispiele

Beispiel #1 set_exception_handler()-Beispiel

    <?php
    function exception_handler(Throwable $exception) {
      echo "Nicht aufgefangene Exception: " , $exception->getMessage(), "\n";
    }

    set_exception_handler('exception_handler');

    throw new Exception('Nicht aufgefangene Exception');
    echo "Nicht ausgeführt.\n";
    ?>

### Siehe auch

- get_exception_handler() - Gets the user-defined exception handler function
- restore_exception_handler() - Stellt den vorherigen Exceptionhandler wieder her
- restore_error_handler() - Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her
- error_reporting() - Gibt an, welche PHP-Fehlermeldungen gemeldet werden
- Exceptions

# trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — Erzeugt eine benutzerdefinierte Fehlermeldung/Warnung/Benachrichtigung

### Beschreibung

function trigger_error(string `$message`, int `$error_level` = `E_USER_NOTICE`): true

Wird verwendet, um eine benutzerdefinierte Fehlerbedingung auszulösen und kann in Verbindung mit der eingebauten Fehlerbehandlung verwendet werden oder mit einer benutzerdefinierten Funktion, die mittels set_error_handler() als neue Fehlerbehandlung festgelegt wurde.

Diese Funktion ist nützlich, wenn Sie zur Laufzeit eine bestimmte Rückmeldung bei einer Ausnahme brauchen.

### Parameter-Liste

`message`

  Die gewünschte Fehlermeldung für diesen Fehler. Die Länge ist auf 1024 Bytes begrenzt, darüber hinausgehende Zeichen werden abgeschnitten.

`error_level`

  Der gewünschte Fehlertyp für diesen Fehler. Es können nur Konstanten der `E_USER_*`-Familie gewählt werden, der Vorgabewert ist `E_USER_NOTICE`.

  Warnung

  Die Übergabe von `E_USER_ERROR` als `error_level` ist nun veraltet. Stattdessen sollte eine Exception geworfen oder exit() aufgerufen werden.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Wenn `error_level` nicht einer der Werte `E_USER_ERROR`, `E_USER_WARNING`, `E_USER_NOTICE`, `E_USER_DEPRECATED` ist, wirft diese Funktion einen ValueError.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Übergabe von `E_USER_ERROR` als `error_level` ist nun veraltet. Stattdessen sollte eine Exception geworfen oder exit() aufgerufen werden.
8.4.0 | Die Funktion hat nun den Rückgabetyp true statt bool.
8.0.0 | Die Funktion wirft nun einen ValueError, wenn ein ungültiges `error_level` angegeben wird; zuvor gab sie `false` zurück.

### Beispiele

Beispiel #1 trigger_error()-Beispiel

Siehe auch set_error_handler() für ein ausführlicheres Beispiel.

    <?php
    $password = $_POST['password'] ?? '';
    if ($password === '') {
      trigger_error("Die Verwendung eines leeren Passworts ist unsicher", E_USER_WARNING);
    }
    $hash = password_hash($password, PASSWORD_DEFAULT);
    ?>

### Anmerkungen

Warnung

Die HTML-Entities in der `error_msg` werden nicht automatisch maskiert. Wenn die Fehlermeldung in einem Browser ausgegeben werden soll, so sollten Sie diese mit htmlentities() vorverarbeiten.

### Siehe auch

- error_reporting() - Gibt an, welche PHP-Fehlermeldungen gemeldet werden
- set_error_handler() - Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung
- restore_error_handler() - Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her
- Die Error Level Konstanten
- Das Attribut Deprecated

# user_error

(PHP 4, PHP 5, PHP 7, PHP 8)

user_error — Alias von trigger_error()

### Beschreibung

Diese Funktion ist ein Alias für: trigger_error().

## Inhaltsverzeichnis

- debug_backtrace — Erzeugt eine Ablaufverfolgung
- debug_print_backtrace — Gibt die Daten für eine Ablaufverfolgung aus
- error_clear_last — Löscht den zuletzt aufgetretenen Fehler
- error_get_last — Liefert den zuletzt aufgetretenen Fehler
- error_log — Sendet eine Fehlermeldung an die definierten Fehlerbehandlungsroutinen
- error_reporting — Gibt an, welche PHP-Fehlermeldungen gemeldet werden
- get_error_handler — Gets the user-defined error handler function
- get_exception_handler — Gets the user-defined exception handler function
- restore_error_handler — Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her
- restore_exception_handler — Stellt den vorherigen Exceptionhandler wieder her
- set_error_handler — Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung
- set_exception_handler — Installiert einen benutzerdefinierten Exceptionhandler
- trigger_error — Erzeugt eine benutzerdefinierte Fehlermeldung/Warnung/Benachrichtigung
- user_error — Alias von trigger_error

- Installation/Konfiguration
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Beispiele
- Fehlerbehandlungsfunktionen
  - debug_backtrace — Erzeugt eine Ablaufverfolgung
  - debug_print_backtrace — Gibt die Daten für eine Ablaufverfolgung aus
  - error_clear_last — Löscht den zuletzt aufgetretenen Fehler
  - error_get_last — Liefert den zuletzt aufgetretenen Fehler
  - error_log — Sendet eine Fehlermeldung an die definierten Fehlerbehandlungsroutinen
  - error_reporting — Gibt an, welche PHP-Fehlermeldungen gemeldet werden
  - get_error_handler — Gets the user-defined error handler function
  - get_exception_handler — Gets the user-defined exception handler function
  - restore_error_handler — Stellt die zuvor benutzte Fehlerbehandlungsfunktion wieder her
  - restore_exception_handler — Stellt den vorherigen Exceptionhandler wieder her
  - set_error_handler — Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung
  - set_exception_handler — Installiert einen benutzerdefinierten Exceptionhandler
  - trigger_error — Erzeugt eine benutzerdefinierte Fehlermeldung/Warnung/Benachrichtigung
  - user_error — Alias von trigger_error

# Foreign Function Interface

# Einführung

This extension allows the loading of shared libraries (.DLL or .so), calling of C functions and accessing of C data structures in pure PHP, without having to have deep knowledge of the Zend extension API, and without having to learn a third “intermediate” language. The public API is implemented as a single class FFI with several static methods (some of them may be called dynamically), and overloaded object methods, which perform the actual interaction with C data.

Achtung

FFI is dangerous, since it allows to interface with the system on a very low level. The FFI extension should only be used by developers having a working knowledge of C and the used C APIs. To minimize the risk, the FFI API usage may be restricted with the ffi.enable php.ini directive.

> Hinweis: The FFI extension does not render the classic PHP extension API obsolete; it is merely provided for ad-hoc interfacing with C functions and data structures.

Tipp

Currently, accessing FFI data structures is significantly (about 2 times) slower than accessing native PHP arrays and objects. Therefore, it makes no sense to use the FFI extension for speed; however, it may make sense to use it to reduce memory consumption.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

This extension requires the » libffi library to be installed.

## Installation

To enable the FFI extension, PHP has to be configured with --with-ffi.

Windows users have to include php_ffi.dll into php.ini to enable the FFI extension.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

FFI Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
ffi.enable | "preload" | `INI_SYSTEM` |
ffi.preload | "" | `INI_SYSTEM` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`ffi.enable` string
  Allows enabling (`"true"`) or disabling (`"false"`) FFI API usage, or restricting it only to the CLI SAPI and preloaded files (`"preload"`). The FFI API restrictions only affect the FFI class, but not overloaded functions of FFI\CData objects. This means that it is possible to create some FFI\CData objects in preloaded files, and then to use these directly in PHP scripts.
`ffi.preload` string
  Allows preloading of FFI bindings during startup, which is not possible with FFI::load() if opcache.preload_user is set. This directive accepts a `DIRECTORY_SEPARATOR` delimited list of filenames. The preloaded bindings can be accessed by calling FFI::scope().

# Beispiele

## Inhaltsverzeichnis

- Basic FFI usage
- PHP Callbacks
- A Complete PHP/FFI/preloading Example

## Basic FFI usage

Before diving into the details of the FFI API, lets take a look at a few examples demonstrating the simplicity of the FFI API usage for regular tasks.

> Hinweis: Some of these examples require libc.so.6 and as such will not work on systems where it is not available.

Beispiel #1 Calling a function from shared library

    <?php
    // create FFI object, loading libc and exporting function printf()
    $ffi = FFI::cdef(
        "int printf(const char *format, ...);", // this is a regular C declaration
        "libc.so.6");
    // call C's printf()
    $ffi->printf("Hello %s!\n", "world");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hello world!

> Hinweis: Note that some C functions need specific calling conventions, e.g. `__fastcall`, `__stdcall` or `,__vectorcall`.

Beispiel #2 Calling a function, returning a structure through an argument

    <?php
    // create gettimeofday() binding
    $ffi = FFI::cdef("
        typedef unsigned int time_t;
        typedef unsigned int suseconds_t;

        struct timeval {
            time_t      tv_sec;
            suseconds_t tv_usec;
        };

        struct timezone {
            int tz_minuteswest;
            int tz_dsttime;
        };

        int gettimeofday(struct timeval *tv, struct timezone *tz);
    ", "libc.so.6");
    // create C data structures
    $tv = $ffi->new("struct timeval");
    $tz = $ffi->new("struct timezone");
    // call C's gettimeofday()
    var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz)));
    // access field of C data structure
    var_dump($tv->tv_sec);
    // print the whole C data structure
    var_dump($tz);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(0)
    int(1555946835)
    object(FFI\CData:struct timezone)#3 (2) {
      ["tz_minuteswest"]=>
      int(0)
      ["tz_dsttime"]=>
      int(0)
    }

Beispiel #3 Accessing existing C variables

    <?php
    // create FFI object, loading libc and exporting errno variable
    $ffi = FFI::cdef(
        "int errno;", // this is a regular C declaration
        "libc.so.6");
    // print C's errno
    var_dump($ffi->errno);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)

Beispiel #4 Creating and Modifying C variables

    <?php
    // create a new C int variable
    $x = FFI::new("int");
    var_dump($x->cdata);

    // simple assignment
    $x->cdata = 5;
    var_dump($x->cdata);

    // compound assignment
    $x->cdata += 2;
    var_dump($x->cdata);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    int(5)
    int(7)

Beispiel #5 Working with C arrays

    <?php
    // create C data structure
    $a = FFI::new("long[1024]");
    // work with it like with a regular PHP array
    for ($i = 0; $i < count($a); $i++) {
        $a[$i] = $i;
    }
    var_dump($a[25]);
    $sum = 0;
    foreach ($a as $n) {
        $sum += $n;
    }
    var_dump($sum);
    var_dump(count($a));
    var_dump(FFI::sizeof($a));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(25)
    int(523776)
    int(1024)
    int(8192)

Beispiel #6 Working with C enums

    <?php
    $a = FFI::cdef('typedef enum _zend_ffi_symbol_kind {
        ZEND_FFI_SYM_TYPE,
        ZEND_FFI_SYM_CONST = 2,
        ZEND_FFI_SYM_VAR,
        ZEND_FFI_SYM_FUNC
    } zend_ffi_symbol_kind;
    ');
    var_dump($a->ZEND_FFI_SYM_TYPE);
    var_dump($a->ZEND_FFI_SYM_CONST);
    var_dump($a->ZEND_FFI_SYM_VAR);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    int(2)
    int(3)

## PHP Callbacks

It is possible to assign a PHP closure to a native variable of function pointer type or to pass it as a function argument:

Beispiel #1 Assigning a PHP Closure to a C function pointer

    <?php
    $zend = FFI::cdef("
        typedef int (*zend_write_func_t)(const char *str, size_t str_length);
        extern zend_write_func_t zend_write;
    ");

    echo "Hello World 1!\n";

    $orig_zend_write = clone $zend->zend_write;
    $zend->zend_write = function($str, $len) {
        global $orig_zend_write;
        $orig_zend_write("{\n\t", 3);
        $ret = $orig_zend_write($str, $len);
        $orig_zend_write("}\n", 2);
        return $ret;
    };
    echo "Hello World 2!\n";
    $zend->zend_write = $orig_zend_write;
    echo "Hello World 3!\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hello World 1!
    {
            Hello World 2!
    }
    Hello World 3!

Although this works, this functionality is not supported on all libffi platforms, is not efficient and leaks resources by the end of request.
Tipp

It is therefore recommended to minimize the usage of PHP callbacks.

## A Complete PHP/FFI/preloading Example

php.ini

    ffi.enable=preload
    opcache.preload=preload.php

preload.php

    <?php
    FFI::load(__DIR__ . "/dummy.h");
    opcache_compile_file(__DIR__ . "/dummy.php");
    ?>

dummy.h

    #define FFI_SCOPE "DUMMY"
    #define FFI_LIB "libc.so.6"

    int printf(const char *format, ...);

dummy.php

    <?php
    final class Dummy {
        private static $ffi = null;
        function __construct() {
            if (is_null(self::$ffi)) {
                self::$ffi = FFI::scope("DUMMY");
            }
        }
        function printf($format, ...$args) {
           return (int) self::$ffi->printf($format, ...$args);
        }
    }
    ?>

test.php

    <?php
    $d = new Dummy();
    $d->printf("Hello %s!\n", "world");
    ?>

# Main interface to C code and data

(PHP 7 >= 7.4.0, PHP 8)

## Einführung

Objects of this class are created by the factory methods FFI::cdef(), FFI::load() or FFI::scope(). Defined C variables are made available as properties of the FFI instance, and defined C functions are made available as methods of the FFI instance. Declared C types can be used to create new C data structures using FFI::new() and FFI::type().

FFI definition parsing and shared library loading may take significant time. It is not useful to do it on each HTTP request in a Web environment. However, it is possible to preload FFI definitions and libraries at PHP startup, and to instantiate FFI objects when necessary. Header files may be extended with special `FFI_SCOPE` defines (e.g. `#define FFI_SCOPE "foo"`; the default scope is "C") and then loaded by FFI::load() during preloading. This leads to the creation of a persistent binding, that will be available to all the following requests through FFI::scope(). Refer to the complete PHP/FFI/preloading example for details.

It is possible to preload more than one C header file into the same scope.

## Klassenbeschreibung

final class FFI {
/* Konstanten */
public const int __BIGGEST_ALIGNMENT__;
/* Methoden */
public static function addr(FFI\CData `&$ptr`): FFI\CData
public static function alignof(FFI\CData|FFI\CType `&$ptr`): int
public static function arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType
public function cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData
public static function cdef(string `$code` = "", ?string `$lib` = `null`): FFI
public static function free(FFI\CData `&$ptr`): void
public static function isNull(FFI\CData `&$ptr`): bool
public static function load(string `$filename`): ?FFI
public static function memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int
public static function memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void
public static function memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void
public function new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData
public static function scope(string `$name`): FFI
public static function sizeof(FFI\CData|FFI\CType `&$ptr`): int
public static function string(FFI\CData `&$ptr`, ?int `$size` = `null`): string
public function type(string `$type`): ?FFI\CType
public static function typeof(FFI\CData `&$ptr`): FFI\CType
}

## Vordefinierte Konstanten

`FFI::__BIGGEST_ALIGNMENT__`

# FFI::addr

(PHP 7 >= 7.4.0, PHP 8)

FFI::addr — Creates an unmanaged pointer to C data

### Beschreibung

public static function FFI::addr(FFI\CData `&$ptr`): FFI\CData

Creates an unmanaged pointer to the C data represented by the given FFI\CData. The source `ptr` must survive the resulting pointer. This function is mainly useful to pass arguments to C functions by pointer.

### Parameter-Liste

`ptr`
  The handle of the pointer to a C data structure.

### Rückgabewerte

Returns the freshly created FFI\CData object.

# FFI::alignof

(PHP 7 >= 7.4.0, PHP 8)

FFI::alignof — Gets the alignment

### Beschreibung

public static function FFI::alignof(FFI\CData|FFI\CType `&$ptr`): int

Gets the alignment of the given FFI\CData or FFI\CType object.

### Parameter-Liste

`ptr`
  The handle of the C data or type.

### Rückgabewerte

Returns the alignment of the given FFI\CData or FFI\CType object.

# FFI::arrayType

(PHP 7 >= 7.4.0, PHP 8)

FFI::arrayType — Dynamically constructs a new C array type

### Beschreibung

public static function FFI::arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType

Dynamically constructs a new C array type with elements of type defined by `type`, and dimensions specified by `dimensions`. In the following example `$t1` and `$t2` are equivalent array types:

    <?php
    $t1 = FFI::type("int[2][3]");
    $t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
    ?>

### Parameter-Liste

`type`
  A valid C declaration as string, or an instance of FFI\CType which has already been created.
`dimensions`
  The dimensions of the type as array.

### Rückgabewerte

Returns the freshly created FFI\CType object.

# FFI::cast

(PHP 7 >= 7.4.0, PHP 8)

FFI::cast — Performs a C type cast

### Beschreibung

public function FFI::cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData

FFI::cast() creates a new FFI\CData object, that references the same C data structure, but is associated with a different type. The resulting object does not own the C data, and the source `ptr` must survive the result. The C type may be specified as a string with any valid C type declaration or as FFI\CType object, created before. Any type declared for the instance is allowed.

### Parameter-Liste

`type`
  A valid C declaration as string, or an instance of FFI\CType which has already been created.
`ptr`
  The handle of the pointer to a C data structure.

### Rückgabewerte

Returns the freshly created FFI\CData object.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Calling FFI::cast() statically is now deprecated.

# FFI::cdef

(PHP 7 >= 7.4.0, PHP 8)

FFI::cdef — Creates a new FFI object

### Beschreibung

public static function FFI::cdef(string `$code` = "", ?string `$lib` = `null`): FFI

Creates a new FFI object.

### Parameter-Liste

`code`
  A string containing a sequence of declarations in regular C language (types, structures, functions, variables, etc). Actually, this string may be copy-pasted from C header files.

  > Hinweis: C preprocessor directives are not supported, i.e. `#include`, `#define` and CPP macros do not work.

`lib`
  The name of a shared library file, to be loaded and linked with the definitions.

  > Hinweis: If `lib` is omitted or `null`, platforms supporting `RTLD_DEFAULT` attempt to lookup symbols declared in `code` in the normal global scope. Other systems will fail to resolve these symbols.

### Rückgabewerte

Returns the freshly created FFI object.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | C functions returning `void` return a PHP null instead of FFI\CType::TYPE_VOID.
8.0.0 | `lib` is nullable now.

# FFI::free

(PHP 7 >= 7.4.0, PHP 8)

FFI::free — Releases an unmanaged data structure

### Beschreibung

public static function FFI::free(FFI\CData `&$ptr`): void

Manually releases a previously created unmanaged data structure.

### Parameter-Liste

`ptr`
  The handle of the unmanaged pointer to a C data structure.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# FFI::isNull

(PHP 7 >= 7.4.0, PHP 8)

FFI::isNull — Checks whether a FFI\CData is a null pointer

### Beschreibung

public static function FFI::isNull(FFI\CData `&$ptr`): bool

Checks whether a FFI\CData is a null pointer.

### Parameter-Liste

`ptr`
  The handle of the pointer to a C data structure.

### Rückgabewerte

Returns whether a FFI\CData is a null pointer.

# FFI::load

(PHP 7 >= 7.4.0, PHP 8)

FFI::load — Loads C declarations from a C header file

### Beschreibung

public static function FFI::load(string `$filename`): ?FFI

Loads C declarations from a C header file. It is possible to specify shared libraries that should be loaded, using special `FFI_LIB` defines in the loaded C header file.

### Parameter-Liste

`filename`
  The name of a C header file. C preprocessor directives are not supported, i.e. `#include`, `#define` and CPP macros do not work, except for special cases listed below. The header file should contain a `#define` statement for the `FFI_SCOPE` variable, e.g.: `#define FFI_SCOPE "MYLIB"`. Refer to the class introduction for details. The header file may contain a `#define` statement for the `FFI_LIB` variable to specify the library it exposes. If it is a system library only the file name is required, e.g.: `#define FFI_LIB "libc.so.6"`. If it is a custom library, a relative path is required, e.g.: `#define FFI_LIB "./mylib.so"`.

### Rückgabewerte

Returns the freshly created FFI object, or `null` on failure.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | FFI::load() is now allowed in preload scripts when the current system user is the same as the one defined in the `opcache.preload_user` configuration directive.

### Siehe auch

- FFI::scope() - Instantiates an FFI object with C declarations parsed during preloading

# FFI::memcmp

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcmp — Compares memory areas

### Beschreibung

public static function FFI::memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int

Compares `size` bytes from the memory areas `ptr1` and `ptr2`. Both `ptr1` and `ptr2` can be any native data structures (FFI\CData) or PHP strings.

### Parameter-Liste

`ptr1`
  The start of one memory area.
`ptr2`
  The start of another memory area.
`size`
  The number of bytes to compare.

### Rückgabewerte

Returns a value less than `0` if the contents of the memory area starting at `ptr1` are considered less than the contents of the memory area starting at `ptr2`, a value greater than `0` if the contents of the first memory area are considered greater than the second, and `0` if they are equal.

# FFI::memcpy

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcpy — Copies one memory area to another

### Beschreibung

public static function FFI::memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void

Copies `size` bytes from the memory area `from` to the memory area `to`.

### Parameter-Liste

`to`
  The start of the memory area to copy to.
`from`
  The start of the memory area to copy from.
`size`
  The number of bytes to copy.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# FFI::memset

(PHP 7 >= 7.4.0, PHP 8)

FFI::memset — Fills a memory area

### Beschreibung

public static function FFI::memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void

Fills `size` bytes of the memory area pointed to by `ptr` with the given byte `value`.

### Parameter-Liste

`ptr`
  The start of the memory area to fill.
`value`
  The byte to fill with.
`size`
  The number of bytes to fill.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# FFI::new

(PHP 7 >= 7.4.0, PHP 8)

FFI::new — Creates a C data structure

### Beschreibung

public function FFI::new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData

Creates a native data structure of the given C type. Any type declared for the instance is allowed.

### Parameter-Liste

`type`
  `type` is a valid C declaration as string, or an instance of FFI\CType which has already been created.
`owned`
  Whether to create owned (i.e. managed) or unmanaged data. Managed data lives together with the returned FFI\CData object, and is released when the last reference to that object is released by regular PHP reference counting or GC. Unmanaged data should be released by calling FFI::free(), when no longer needed.
`persistent`
  Whether to allocate the C data structure permanently on the system heap (using malloc()), or on the PHP request heap (using emalloc()).

### Rückgabewerte

Returns the freshly created FFI\CData object, or `null` on failure.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Calling FFI::new() statically is now deprecated.

# FFI::scope

(PHP 7 >= 7.4.0, PHP 8)

FFI::scope — Instantiates an FFI object with C declarations parsed during preloading

### Beschreibung

public static function FFI::scope(string `$name`): FFI

Instantiates an FFI object with C declarations parsed during preloading.

The FFI::scope() method is safe to call multiple times for the same scope. Multiple references to the same scope may be loaded at the same time.

### Parameter-Liste

`name`
  The scope name defined by a special `FFI_SCOPE` define.

### Rückgabewerte

Returns the freshly created FFI object.

### Siehe auch

- FFI::load() - Loads C declarations from a C header file

# FFI::sizeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::sizeof — Gets the size of C data or types

### Beschreibung

public static function FFI::sizeof(FFI\CData|FFI\CType `&$ptr`): int

Returns the size of the given FFI\CData or FFI\CType object.

### Parameter-Liste

`ptr`
  The handle of the C data or type.

### Rückgabewerte

The size of the memory area pointed at by `ptr`.

# FFI::string

(PHP 7 >= 7.4.0, PHP 8)

FFI::string — Creates a PHP string from a memory area

### Beschreibung

public static function FFI::string(FFI\CData `&$ptr`, ?int `$size` = `null`): string

Creates a PHP string from `size` bytes of the memory area pointed to by `ptr`.

### Parameter-Liste

`ptr`
  The start of the memory area from which to create a string.
`size`
  The number of bytes to copy to the string. If `size` is omitted or `null`, `ptr` must be a zero terminated array of C `char`.

### Rückgabewerte

The freshly created PHP string.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `size` is nullable now; previously, its default was `0`.

# FFI::type

(PHP 7 >= 7.4.0, PHP 8)

FFI::type — Creates an FFI\CType object from a C declaration

### Beschreibung

public function FFI::type(string `$type`): ?FFI\CType

This function creates and returns a FFI\CType object for the given string containing a C type declaration. Any type declared for the instance is allowed.

### Parameter-Liste

`type`
  A valid C declaration as string.

### Rückgabewerte

Returns the freshly created FFI\CType object, or `null` on failure.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Calling FFI::type() statically is now deprecated.

# FFI::typeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::typeof — Gets the FFI\CType of FFI\CData

### Beschreibung

public static function FFI::typeof(FFI\CData `&$ptr`): FFI\CType

Gets the FFI\CType object representing the type of the given FFI\CData object.

### Parameter-Liste

`ptr`
  The handle of the pointer to a C data structure.

### Rückgabewerte

Returns the FFI\CType object representing the type of the given FFI\CData object.

## Inhaltsverzeichnis

- FFI::addr — Creates an unmanaged pointer to C data
- FFI::alignof — Gets the alignment
- FFI::arrayType — Dynamically constructs a new C array type
- FFI::cast — Performs a C type cast
- FFI::cdef — Creates a new FFI object
- FFI::free — Releases an unmanaged data structure
- FFI::isNull — Checks whether a FFI\CData is a null pointer
- FFI::load — Loads C declarations from a C header file
- FFI::memcmp — Compares memory areas
- FFI::memcpy — Copies one memory area to another
- FFI::memset — Fills a memory area
- FFI::new — Creates a C data structure
- FFI::scope — Instantiates an FFI object with C declarations parsed during preloading
- FFI::sizeof — Gets the size of C data or types
- FFI::string — Creates a PHP string from a memory area
- FFI::type — Creates an FFI\CType object from a C declaration
- FFI::typeof — Gets the FFI\CType of FFI\CData

# C Data Handles

(PHP 7 >= 7.4.0, PHP 8)

## Einführung

FFI\CData objects can be used in a number of ways as a regular PHP data:

- C data of scalar types can be read and assigned via the $cdata property, e.g. `$x = FFI::new('int'); $x->cdata = 42;`
- C struct and union fields can be accessed as regular PHP object property, e.g. `$cdata->field`
- C array elements can be accessed as regular PHP array elements, e.g. `$cdata[$offset]`
- C arrays can be iterated using `foreach` statements.
- C arrays can be used as arguments of count().
- C pointers can be dereferenced as arrays, e.g. `$cdata[0]`
- C pointers can be compared using regular comparison operators (`<`, `<=`, `==`, `!=`, `>=`, `>`).
- C pointers can be incremented and decremented using regular `+`/`-`/ `++`/`--` operations, e.g. `$cdata += 5`
- C pointers can be subtracted from another using regular `-` operations.
- C pointers to functions can be called as a regular PHP closure, e.g. `$cdata()`
- Any C data can be duplicated using the clone operator, e.g. `$cdata2 = clone $cdata;`
- Any C data can be visualized using var_dump(), print_r(), etc.
- FFI\CData can now be assigned to structs and fields as of PHP 8.3.0.

> Hinweis: Notable limitations are that FFI\CData instances do not support isset(), empty() and unset(), and that wrapped C structs and unions do not implement Traversable.

## Klassenbeschreibung

namespace FFI;
final class CData {
}

## Changelog

Version | Beschreibung
--- | ---
8.3.0 | FFI\CData can now be assigned to structs and fields.

# C Type Handles

(PHP 7 >= 7.4.0, PHP 8)

## Einführung

## Klassenbeschreibung

namespace FFI;
final class CType {
/* Konstanten */
public const int TYPE_VOID;
public const int TYPE_FLOAT;
public const int TYPE_DOUBLE;
public const int TYPE_LONGDOUBLE;
public const int TYPE_UINT8;
public const int TYPE_SINT8;
public const int TYPE_UINT16;
public const int TYPE_SINT16;
public const int TYPE_UINT32;
public const int TYPE_SINT32;
public const int TYPE_UINT64;
public const int TYPE_SINT64;
public const int TYPE_ENUM;
public const int TYPE_BOOL;
public const int TYPE_CHAR;
public const int TYPE_POINTER;
public const int TYPE_FUNC;
public const int TYPE_ARRAY;
public const int TYPE_STRUCT;
public const int ATTR_CONST;
public const int ATTR_INCOMPLETE_TAG;
public const int ATTR_VARIADIC;
public const int ATTR_INCOMPLETE_ARRAY;
public const int ATTR_VLA;
public const int ATTR_UNION;
public const int ATTR_PACKED;
public const int ATTR_MS_STRUCT;
public const int ATTR_GCC_STRUCT;
public const int ABI_DEFAULT;
public const int ABI_CDECL;
public const int ABI_FASTCALL;
public const int ABI_THISCALL;
public const int ABI_STDCALL;
public const int ABI_PASCAL;
public const int ABI_REGISTER;
public const int ABI_MS;
public const int ABI_SYSV;
public const int ABI_VECTORCALL;
/* Methoden */
public function getAlignment(): int
public function getArrayElementType(): FFI\CType
public function getArrayLength(): int
public function getAttributes(): int
public function getEnumKind(): int
public function getFuncABI(): int
public function getFuncParameterCount(): int
public function getFuncParameterType(int `$index`): FFI\CType
public function getFuncReturnType(): FFI\CType
public function getKind(): int
public function getName(): string
public function getPointerType(): FFI\CType
public function getSize(): int
public function getStructFieldNames(): array
public function getStructFieldOffset(string `$name`): int
public function getStructFieldType(string `$name`): FFI\CType
}

## Vordefinierte Konstanten

`FFI\CType::TYPE_VOID`
`FFI\CType::TYPE_FLOAT`
`FFI\CType::TYPE_DOUBLE`
`FFI\CType::TYPE_LONGDOUBLE`
`FFI\CType::TYPE_UINT8`
`FFI\CType::TYPE_SINT8`
`FFI\CType::TYPE_UINT16`
`FFI\CType::TYPE_SINT16`
`FFI\CType::TYPE_UINT32`
`FFI\CType::TYPE_SINT32`
`FFI\CType::TYPE_UINT64`
`FFI\CType::TYPE_SINT64`
`FFI\CType::TYPE_ENUM`
`FFI\CType::TYPE_BOOL`
`FFI\CType::TYPE_CHAR`
`FFI\CType::TYPE_POINTER`
`FFI\CType::TYPE_FUNC`
`FFI\CType::TYPE_ARRAY`
`FFI\CType::TYPE_STRUCT`
`FFI\CType::ATTR_CONST`
`FFI\CType::ATTR_INCOMPLETE_TAG`
`FFI\CType::ATTR_VARIADIC`
`FFI\CType::ATTR_INCOMPLETE_ARRAY`
`FFI\CType::ATTR_VLA`
`FFI\CType::ATTR_UNION`
`FFI\CType::ATTR_PACKED`
`FFI\CType::ATTR_MS_STRUCT`
`FFI\CType::ATTR_GCC_STRUCT`
`FFI\CType::ABI_DEFAULT`
`FFI\CType::ABI_CDECL`
`FFI\CType::ABI_FASTCALL`
`FFI\CType::ABI_THISCALL`
`FFI\CType::ABI_STDCALL`
`FFI\CType::ABI_PASCAL`
`FFI\CType::ABI_REGISTER`
`FFI\CType::ABI_MS`
`FFI\CType::ABI_SYSV`
`FFI\CType::ABI_VECTORCALL`

# FFI\CType::getAlignment

(PHP 8 >= 8.1.0)

FFI\CType::getAlignment — Description

### Beschreibung

public function FFI\CType::getAlignment(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getArrayElementType

(PHP 8 >= 8.1.0)

FFI\CType::getArrayElementType — Description

### Beschreibung

public function FFI\CType::getArrayElementType(): FFI\CType

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getArrayLength

(PHP 8 >= 8.1.0)

FFI\CType::getArrayLength — Description

### Beschreibung

public function FFI\CType::getArrayLength(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getAttributes

(PHP 8 >= 8.1.0)

FFI\CType::getAttributes — Description

### Beschreibung

public function FFI\CType::getAttributes(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getEnumKind

(PHP 8 >= 8.1.0)

FFI\CType::getEnumKind — Description

### Beschreibung

public function FFI\CType::getEnumKind(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getFuncABI

(PHP 8 >= 8.1.0)

FFI\CType::getFuncABI — Description

### Beschreibung

public function FFI\CType::getFuncABI(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getFuncParameterCount

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterCount — Retrieve the count of parameters of a function type

### Beschreibung

public function FFI\CType::getFuncParameterCount(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of parameters for the underlying function type. If the underlying type is not a function, an FFI\Exception is thrown.

# FFI\CType::getFuncParameterType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterType — Retrieve the type of a function parameter

### Beschreibung

public function FFI\CType::getFuncParameterType(int `$index`): FFI\CType

Returns the type of a parameter for the underlying function type.

### Parameter-Liste

`index`
  Index of the function parameter, zero-based.

### Rückgabewerte

Returns the type of a parameter for the underlying function type. If the underlying type is not a function, or the given index is outside of the range of parameters of the function, an FFI\Exception is thrown.

# FFI\CType::getFuncReturnType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncReturnType — Description

### Beschreibung

public function FFI\CType::getFuncReturnType(): FFI\CType

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getKind

(PHP 8 >= 8.1.0)

FFI\CType::getKind — Description

### Beschreibung

public function FFI\CType::getKind(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getName

(PHP 7 >= 7.4.0, PHP 8)

FFI\CType::getName — Description

### Beschreibung

public function FFI\CType::getName(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getPointerType

(PHP 8 >= 8.1.0)

FFI\CType::getPointerType — Description

### Beschreibung

public function FFI\CType::getPointerType(): FFI\CType

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getSize

(PHP 8 >= 8.1.0)

FFI\CType::getSize — Description

### Beschreibung

public function FFI\CType::getSize(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getStructFieldNames

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldNames — Description

### Beschreibung

public function FFI\CType::getStructFieldNames(): array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# FFI\CType::getStructFieldOffset

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldOffset — Description

### Beschreibung

public function FFI\CType::getStructFieldOffset(string `$name`): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`name`

### Rückgabewerte

# FFI\CType::getStructFieldType

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldType — Description

### Beschreibung

public function FFI\CType::getStructFieldType(string `$name`): FFI\CType

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`name`

### Rückgabewerte

## Inhaltsverzeichnis

- FFI\CType::getAlignment — Description
- FFI\CType::getArrayElementType — Description
- FFI\CType::getArrayLength — Description
- FFI\CType::getAttributes — Description
- FFI\CType::getEnumKind — Description
- FFI\CType::getFuncABI — Description
- FFI\CType::getFuncParameterCount — Retrieve the count of parameters of a function type
- FFI\CType::getFuncParameterType — Retrieve the type of a function parameter
- FFI\CType::getFuncReturnType — Description
- FFI\CType::getKind — Description
- FFI\CType::getName — Description
- FFI\CType::getPointerType — Description
- FFI\CType::getSize — Description
- FFI\CType::getStructFieldNames — Description
- FFI\CType::getStructFieldOffset — Description
- FFI\CType::getStructFieldType — Description

# FFI Exceptions

(PHP 7 >= 7.4.0, PHP 8)

## Einführung

## Klassenbeschreibung

namespace FFI;
class Exception extends Error {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FFI Parser Exceptions

(PHP 7 >= 7.4.0, PHP 8)

## Einführung

## Klassenbeschreibung

namespace FFI;
final class ParserException extends FFI\Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Beispiele
  - Basic FFI usage
  - PHP Callbacks
  - A Complete PHP/FFI/preloading Example
- FFI — Main interface to C code and data
  - FFI::addr — Creates an unmanaged pointer to C data
  - FFI::alignof — Gets the alignment
  - FFI::arrayType — Dynamically constructs a new C array type
  - FFI::cast — Performs a C type cast
  - FFI::cdef — Creates a new FFI object
  - FFI::free — Releases an unmanaged data structure
  - FFI::isNull — Checks whether a FFI\CData is a null pointer
  - FFI::load — Loads C declarations from a C header file
  - FFI::memcmp — Compares memory areas
  - FFI::memcpy — Copies one memory area to another
  - FFI::memset — Fills a memory area
  - FFI::new — Creates a C data structure
  - FFI::scope — Instantiates an FFI object with C declarations parsed during preloading
  - FFI::sizeof — Gets the size of C data or types
  - FFI::string — Creates a PHP string from a memory area
  - FFI::type — Creates an FFI\CType object from a C declaration
  - FFI::typeof — Gets the FFI\CType of FFI\CData
- FFI\CData — C Data Handles
- FFI\CType — C Type Handles
  - FFI\CType::getAlignment — Description
  - FFI\CType::getArrayElementType — Description
  - FFI\CType::getArrayLength — Description
  - FFI\CType::getAttributes — Description
  - FFI\CType::getEnumKind — Description
  - FFI\CType::getFuncABI — Description
  - FFI\CType::getFuncParameterCount — Retrieve the count of parameters of a function type
  - FFI\CType::getFuncParameterType — Retrieve the type of a function parameter
  - FFI\CType::getFuncReturnType — Description
  - FFI\CType::getKind — Description
  - FFI\CType::getName — Description
  - FFI\CType::getPointerType — Description
  - FFI\CType::getSize — Description
  - FFI\CType::getStructFieldNames — Description
  - FFI\CType::getStructFieldOffset — Description
  - FFI\CType::getStructFieldType — Description
- FFI\Exception — FFI Exceptions
- FFI\ParserException — FFI Parser Exceptions

# OPcache

# Einführung

OPcache erhöht die PHP-Performance durch das Speichern des vorkompilierten Bytecodes im Arbeitsspeicher. Dadurch wird das Laden und Parsen der Scripte bei jedem Request vermieden.

Diese Erweiterung ist ab PHP 5.5.0 enthalten und auch als » PECL Paket für PHP Version 5.2, 5.3 und 5.4 verfügbar.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Laufzeit-Konfiguration

## Installation

OPcache can only be compiled as a shared extension. If you have disabled the building of default extensions with --disable-all, you must compile PHP with the --enable-opcache option for OPcache to be available.

Once compiled, you can use the zend_extension configuration directive to load the OPcache extension into PHP. This can be done with `zend_extension=/full/path/to/opcache.so` on non-Windows platforms, and `zend_extension=C:\path\to\php_opcache.dll` on Windows.

> Hinweis: If you want to use OPcache with » Xdebug, you must load OPcache before Xdebug.

### Recommended php.ini settings

The following settings are generally recommended as providing good performance:

    opcache.memory_consumption=128
    opcache.interned_strings_buffer=8
    opcache.max_accelerated_files=4000
    opcache.revalidate_freq=60
    opcache.fast_shutdown=1 ; prior to PHP 7.2.0
    opcache.enable_cli=1

You may also want to consider disabling opcache.save_comments and enabling opcache.enable_file_override, however note that you will have to test your code before using these in production as they are known to break some frameworks and applications, particularly in cases where documentation comment annotations are used.

On Windows, opcache.file_cache_fallback should be enabled, and opcache.file_cache should be set to an already existing and writable directory.

A full list of configuration directives supported by OPcache is also available.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

OPcache configuration options
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
opcache.enable | 1 | `INI_ALL` |
opcache.enable_cli | 0 | `INI_SYSTEM` | Between PHP 7.1.2 and 7.1.6 inclusive, the default was `1`
opcache.memory_consumption | 128 | `INI_SYSTEM` |
opcache.interned_strings_buffer | 8 | `INI_SYSTEM` |
opcache.max_accelerated_files | 10000 | `INI_SYSTEM` |
opcache.max_wasted_percentage | 5 | `INI_SYSTEM` |
opcache.use_cwd | 1 | `INI_SYSTEM` |
opcache.validate_timestamps | 1 | `INI_ALL` |
opcache.revalidate_freq | 2 | `INI_ALL` |
opcache.revalidate_path | 0 | `INI_ALL` |
opcache.save_comments | 1 | `INI_SYSTEM` |
opcache.fast_shutdown | 0 | `INI_SYSTEM` | Removed in PHP 7.2.0
opcache.enable_file_override | 0 | `INI_SYSTEM` |
opcache.optimization_level | 0x7FFEBFFF | `INI_SYSTEM` | Changed from `0x7FFFBFFF` in PHP 7.3.0
opcache.inherited_hack | 1 | `INI_SYSTEM` | Removed in PHP 7.3.0
opcache.dups_fix | 0 | `INI_ALL` |
opcache.blacklist_filename | "" | `INI_SYSTEM` |
opcache.max_file_size | 0 | `INI_SYSTEM` |
opcache.consistency_checks | 0 | `INI_ALL` | Disabled as of 8.1.18 and 8.2.5. Removed as of PHP 8.3.0.
opcache.force_restart_timeout | 180 | `INI_SYSTEM` |
opcache.error_log | "" | `INI_SYSTEM` |
opcache.log_verbosity_level | 1 | `INI_SYSTEM` |
opcache.record_warnings | 0 | `INI_SYSTEM` | Available as of PHP 8.0.0
opcache.preferred_memory_model | "" | `INI_SYSTEM` |
opcache.protect_memory | 0 | `INI_SYSTEM` |
opcache.mmap_base | `null` | `INI_SYSTEM` | Windows only.
opcache.restrict_api | "" | `INI_SYSTEM` |
opcache.file_update_protection | 2 | `INI_ALL` |
opcache.huge_code_pages | 0 | `INI_SYSTEM` |
opcache.lockfile_path | "/tmp" | `INI_SYSTEM` |
opcache.opt_debug_level | 0 | `INI_SYSTEM` | Available as of PHP 7.1.0
opcache.file_cache | `null` | `INI_SYSTEM` |
opcache.file_cache_only | 0 | `INI_SYSTEM` |
opcache.file_cache_consistency_checks | 1 | `INI_SYSTEM` |
opcache.file_cache_fallback | 1 | `INI_SYSTEM` | Windows only.
opcache.validate_permission | 0 | `INI_SYSTEM` | Available as of PHP 7.0.14
opcache.validate_root | 0 | `INI_SYSTEM` | Available as of PHP 7.0.14
opcache.preload | "" | `INI_SYSTEM` | Available as of PHP 7.4.0
opcache.preload_user | "" | `INI_SYSTEM` | Available as of PHP 7.4.0
opcache.cache_id | "" | `INI_SYSTEM` | Windows only. Available as of PHP 7.4.0
opcache.jit | "disable" | `INI_ALL` | Available as of PHP 8.0.0. Prior to PHP 8.4.0, the default value was "tracing".
opcache.jit_buffer_size | 64M | `INI_SYSTEM` | Available as of PHP 8.0.0. Prior to PHP 8.4.0, the default value was 0.
opcache.jit_debug | 0 | `INI_ALL` | Available as of PHP 8.0.0
opcache.jit_bisect_limit | 0 | `INI_ALL` | Available as of PHP 8.0.0
opcache.jit_prof_threshold | 0.005 | `INI_ALL` | Available as of PHP 8.0.0
opcache.jit_max_root_traces | 1024 | `INI_SYSTEM` | Available as of PHP 8.0.0
opcache.jit_max_side_traces | 128 | `INI_SYSTEM` | Available as of PHP 8.0.0
opcache.jit_max_exit_counters | 8192 | `INI_SYSTEM` | Available as of PHP 8.0.0
opcache.jit_hot_loop | 61 | `INI_SYSTEM` | Available as of PHP 8.0.0. Before PHP 8.5.0, the default value was 64
opcache.jit_hot_func | 127 | `INI_SYSTEM` | Available as of PHP 8.0.0
opcache.jit_hot_return | 8 | `INI_SYSTEM` | Available as of PHP 8.0.0
opcache.jit_hot_side_exit | 8 | `INI_SYSTEM` | Available as of PHP 8.0.0
opcache.jit_blacklist_root_trace | 16 | `INI_ALL` | Available as of PHP 8.0.0
opcache.jit_blacklist_side_trace | 8 | `INI_ALL` | Available as of PHP 8.0.0
opcache.jit_max_loop_unrolls | 8 | `INI_ALL` | Available as of PHP 8.0.0
opcache.jit_max_recursive_calls | 2 | `INI_ALL` | Available as of PHP 8.0.0
opcache.jit_max_recursive_returns | 2 | `INI_ALL` | Available as of PHP 8.0.0
opcache.jit_max_polymorphic_calls | 2 | `INI_ALL` | Available as of PHP 8.0.0

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`opcache.enable` bool
  Enables the opcode cache. When disabled, code is not optimised or cached. The setting `opcache.enable` can not be enabled at runtime through ini_set(), it can only be disabled. Trying to enable it in a script will generate a warning.
`opcache.enable_cli` bool
  Enables the opcode cache for the CLI version of PHP.
`opcache.memory_consumption` int
  The size of the shared memory storage used by OPcache, in megabytes. The minimum permissible value is `"8"`, which is enforced if a smaller value is set.
`opcache.interned_strings_buffer` int
  The amount of memory used to store interned strings, in megabytes. The maximum value is 32767 on 64bit architectures, and 4095 on 32bit architectures.

  > Hinweis: Prior to PHP 8.4.0, the maximum value was 4095 megabytes on all architectures.

`opcache.max_accelerated_files` int
  The maximum number of keys (and therefore scripts) in the OPcache hash table. The actual value used will be the first number in the set of prime numbers `{ 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987, 262237, 524521, 1048793 }` that is greater than or equal to the configured value. The minimum value is 200. The maximum value is 1000000. Values outside of this range are clamped to the permissible range.
`opcache.max_wasted_percentage` int
  The maximum percentage of wasted memory that is allowed before a restart is scheduled, if there is insufficient free memory. The maximum permissible value is `"50"`, which is enforced if a larger value is set.
`opcache.use_cwd` bool
  If enabled, OPcache appends the current working directory to the script key, thereby eliminating possible collisions between files with the same base name. Disabling this directive improves performance, but may break existing applications.
`opcache.validate_timestamps` bool

  If enabled, OPcache will check for updated scripts every opcache.revalidate_freq seconds. When this directive is disabled, you must reset OPcache manually via opcache_reset(), opcache_invalidate() or by restarting the Web server for changes to the filesystem to take effect.

  > Hinweis: OPcache may still validate the timestamp of a file at compile-time if opcache.file_update_protection or opcache.max_file_size options are set to non-zero values.

`opcache.revalidate_freq` int
  How often to check script timestamps for updates, in seconds. `0` will result in OPcache checking for updates on every request. This configuration directive is ignored if opcache.validate_timestamps is disabled.
`opcache.revalidate_path` bool
  If disabled, existing cached files using the same include_path will be reused. Thus, if a file with the same name is elsewhere in the include_path, it won't be found.
`opcache.save_comments` bool
  If disabled, all documentation comments will be discarded from the opcode cache to reduce the size of the optimised code. Disabling this configuration directive may break applications and frameworks that rely on comment parsing for annotations, including Doctrine, Zend Framework 2 and PHPUnit.
`opcache.fast_shutdown` bool
  If enabled, a fast shutdown sequence is used that doesn't free each allocated block, but relies on the Zend Engine memory manager to deallocate the entire set of request variables en masse. This directive has been removed in PHP 7.2.0. A variant of the fast shutdown sequence has been integrated into PHP and will be automatically used if possible.
`opcache.enable_file_override` bool
  When enabled, the opcode cache will be checked for whether a file has already been cached when file_exists(), is_file() and is_readable() are called. This may increase performance in applications that check the existence and readability of PHP scripts, but risks returning stale data if opcache.validate_timestamps is disabled.
`opcache.optimization_level` int
  A bitmask that controls which optimisation passes are executed. The default value is `0x7FFEBFFF`, which enables all safe optimizations. Disabling optimizations or enabling unsafe optimizations is mostly useful for debugging/developing the optimizer. Each bit in the bitmask enables a specific optimization pass:

  Optimization Pass Bitmask
  Bit | Pass Name | Beschreibung | Default
  --- | --- | --- | ---
  0 | PASS_1 | Simple peephole optimizations | On
  1 | PASS_2 | Unused (got merged into PASS_1) | On
  2 | PASS_3 | Simple jump optimization | On
  3 | PASS_4 | Call optimization | On
  4 | PASS_5 | Control Flow Graph based optimization | On
  5 | PASS_6 | Data Flow Analysis based optimization | On
  6 | PASS_7 | Whether call graph should be used for SSA-based optimizations | On
  7 | PASS_8 | Sparse conditional constant propagation | On
  8 | PASS_9 | Temporary variable optimization | On
  9 | PASS_10 | Removal of NOP opcodes | On
  10 | PASS_11 | Literal compaction | On
  11 | PASS_12 | Pre-compute call stack size | On
  12 | PASS_13 | Unused variable removal | On
  13 | PASS_14 | Dead code elimination | On
  14 | PASS_15 | Collect and substitute constant declarations (unsafe) | Off
  15 | PASS_16 | Trivial function inlining (part of call optimization) | On
  16 | (Flag) | Ignore possibility of operator overloading (unsafe) | Off

  > Hinweis: Safe vs Unsafe Optimizations
  > Safe optimizations (enabled by default) preserve the exact behavior of PHP code while improving performance. They include dead code elimination, constant folding, and jump optimization. Unsafe optimizations (disabled by default) may alter behavior in edge cases:

  > - Bit 14: Collecting constants. Constants are substituted at compile-time, ignoring runtime declaration order:

  >       <?php
  >       echo getA();         // Outputs: "hello" instead of throwing an Error
  >       const A = "hello";
  >       function getA() { return A; }

  > - Bit 16: Ignoring operator overloading. Unsafe when using classes with `do_operation` (e.g. GMP, BCMath) in arithmetic operations. With type declarations, the optimizer can apply the same optimizations safely.

`opcache.inherited_hack` bool
  This configuration directive is ignored.
`opcache.dups_fix` bool
  This hack should only be enabled to work around "Cannot redeclare class" errors.
`opcache.blacklist_filename` string
  The location of the OPcache blacklist file. A blacklist file is a text file containing the names of files that should not be accelerated, one per line. Wildcards are allowed, and prefixes can also be provided. Lines starting with a semi-colon are ignored as comments. A simple blacklist file might look as follows:

      ; Matches a specific file.
      /var/www/broken.php
      ; A prefix that matches all files starting with x.
      /var/www/x
      ; A wildcard match.
      /var/www/*-broken.php

`opcache.max_file_size` int
  The maximum file size that will be cached, in bytes. If this is `0`, all files will be cached.
`opcache.consistency_checks` int
  If non-zero, OPcache will verify the cache checksum every N requests, where N is the value of this configuration directive. This should only be enabled when debugging, as it will impair performance.

  > Hinweis: Disabled as of 8.1.18 and 8.2.5. Removed as of PHP 8.3.0.

`opcache.force_restart_timeout` int
  The length of time to wait for a scheduled restart to begin if the cache isn't active, in seconds. If the timeout is hit, then OPcache assumes that something is wrong and will kill the processes holding locks on the cache to permit a restart. If opcache.log_verbosity_level is set to 2 or above, a warning will be recorded in the error log when this occurs. This directive is not supported on Windows.
`opcache.error_log` string
  The error log for OPcache errors. An empty string is treated the same as `stderr`, and will result in logs being sent to standard error (which will be the Web server error log in most cases).
`opcache.log_verbosity_level` int
  The log verbosity level. By default, only fatal errors (level 0) and errors (level 1) are logged. Other levels available are warnings (level 2), information messages (level 3) and debug messages (level 4).
`opcache.record_warnings` bool
  If enabled, OPcache will record compile-time warnings and replay them on the next include, even if it is served from cache.
`opcache.preferred_memory_model` string
  The preferred memory model for OPcache to use. If left empty, OPcache will choose the most appropriate model, which is the correct behaviour in virtually all cases. Possible values include `mmap`, `shm`, `posix` and `win32`.
`opcache.protect_memory` bool
  Protects shared memory from unexpected writes while executing scripts. This is useful for internal debugging only.
`opcache.mmap_base` string
  The base used for shared memory segments on Windows. All PHP processes have to map shared memory into the same address space. Using this directive allows "Unable to reattach to base address" errors to be fixed.
`opcache.restrict_api` string
  Allows calling OPcache API functions only from PHP scripts which path is started from specified string. The default `""` means no restriction.
`opcache.file_update_protection` string
  Prevents caching files that are less than this number of seconds old. It protects from caching of incompletely updated files. In case all file updates are atomic, performance can be increased by setting this to `0`. This will allow files to be cached immediately.
`opcache.huge_code_pages` bool
  Enables or disables copying of PHP code (text segment) into HUGE PAGES. This should improve performance, but requires appropriate OS configuration. Available on Linux as of PHP 7.0.0, and on FreeBSD as of PHP 7.4.0.
`opcache.lockfile_path` string
  Absolute path used to store shared lockfiles (for *nix only)
`opcache.opt_debug_level` string
  Produces opcode dumps for debugging different stages of optimizations. 0x10000 will output opcodes as the compiler produced them before any optimization occurs while 0x20000 will output optimized codes.
`opcache.file_cache` string
  Enables and sets the second level cache directory. It should improve performance when SHM memory is full, at server restart or SHM reset. The default `""` disables file based caching.
`opcache.file_cache_only` bool
  Enables or disables opcode caching in shared memory.

  > Hinweis: Prior to PHP 8.1.0, disabling this directive with an already populated file cache required to manually clear the file cache.

`opcache.file_cache_consistency_checks` bool
  Enables or disables checksum validation when script loaded from file cache.
`opcache.file_cache_fallback` bool
  Implies `opcache.file_cache_only=1` for a certain process that failed to reattach to shared memory (Windows only). Explicitly enabling the file cache is required.
  Achtung

  Disabling this configuration option may prevent processes to start, and is therefore discouraged.

`opcache.validate_permission` bool
  Validates the cached file permissions against the current user.
`opcache.validate_root` bool
  Prevents name collisions in chroot'ed environments. This should be enabled in all chroot'ed environments to prevent access to files outside the chroot.
`opcache.preload` string
  Specifies a PHP script that is going to be compiled and executed at server start-up, and which may preload other files, either by includeing them or by using the opcache_compile_file() function. All the entities (e.g. functions and classes) defined in these files will be available to requests out of the box, until the server is shut down.

  > Hinweis: Preloading is not supported on Windows.

`opcache.preload_user` string
  Lets the preloading to be run as the specified system user. This is useful for servers that startup as root before switching to an unprivileged system user. Preloading as root is not allowed by default for security reasons, unless this directive is explicitly set to `root`. As of PHP 8.3.0, this directive does not need to be set in order to allow preloading while running as root when using the CLI SAPI or phpdbg SAPI.
`opcache.cache_id` string

  On Windows, all processes running the same PHP SAPI under the same user account having the same cache ID share a single OPcache instance. The value of the cache ID can be freely chosen.

  Tipp

  For IIS, different application pools can have their own OPcache instance by using the environment variable APP_POOL_ID as `opcache.cache_id`.

`opcache.jit` string|int
  For typical usage, this option accepts one of four string values:
  - `disable`: Completely disabled, cannot be enabled at runtime.
  - `off`: Disabled, but can be enabled at runtime.
  - `tracing`/`on`: Use tracing JIT. Enabled by default and recommended for most users.
  - `function`: Use function JIT.

  For advanced usage, this option accepts a 4-digit integer `CRTO`, where the digits mean:

  `C` (CPU-specific optimization flags)
    - `0`: Disable CPU-specific optimization.
    - `1`: Enable use of AVX, if the CPU supports it.
  `R` (register allocation)
    - `0`: Don't perform register allocation.
    - `1`: Perform block-local register allocation.
    - `2`: Perform global register allocation.
  `T` (trigger)
    - `0`: Compile all functions on script load.
    - `1`: Compile functions on first execution.
    - `2`: Profile functions on first request and compile the hottest functions afterwards.
    - `3`: Profile on the fly and compile hot functions.
    - `4`: Currently unused.
    - `5`: Use tracing JIT. Profile on the fly and compile traces for hot code segments.
  `O` (optimization level)
    - `0`: No JIT.
    - `1`: Minimal JIT (call standard VM handlers).
    - `2`: Inline VM handlers.
    - `3`: Use type inference.
    - `4`: Use call graph.
    - `5`: Optimize whole script.
  The `"tracing"` mode corresponds to `CRTO = 1254`, the `"function"` mode corresponds to `CRTO = 1205`.
`opcache.jit_buffer_size` int
  The amount of shared memory to reserve for compiled JIT code. A zero value disables the JIT. Wird ein Wert vom Typ int verwendet, wird dieser Wert in Bytes gemessen. Es kann auch die Kurzschreibweise verwendet werden, wie in dieser FAQ beschrieben.
`opcache.jit_debug` int
  A bit mask specifying which JIT debug output to enable. For possible values, please consult » zend_jit.h (search for macro definitions beginning with `ZEND_JIT_DEBUG`).
`opcache.jit_bisect_limit` int
  Debugging option that disables JIT compilation after compiling a certain number of functions. This may be helpful to bisect the source of a JIT miscompilation. Note: this option only works when JIT trigger is set to 0 (compile on script load) or 1 (compile on first execution), e.g. `opcache.jit=1215`. See more in opcache.jit option.
`opcache.jit_prof_threshold` float
  When using the "profile on first request" trigger mode, this threshold determines whether a function is considered hot. The number of calls to the function divided by the number of calls to all functions must be above the threshold. For example, a threshold of 0.005 means that functions that made up more than 0.5% of all calls will be JIT compiled.
`opcache.jit_max_root_traces` int
  Maximum number of root traces. The root trace is an execution flow taking one path through the code firstly, which is a unit of JIT compilation. JIT will not compile new code if it reaches this limit.
`opcache.jit_max_side_traces` int
  Maximum number of side traces a root trace may have. The side trace is another execution flow that does not follow the path of compiled root trace. Side traces belonging to the same root trace will not be compiled if it reaches this limit.
`opcache.jit_max_exit_counters` int
  Maximum number of side trace exit counters. This limits the total number of side traces there may be, across all root traces.
`opcache.jit_hot_loop` int
  After how many iterations a loop is considered hot. Valid value range is `[0,255]`; for any setting out of this range, e.g. `-1` or `256`, default value will be used instead. `0` will disable JIT to trace and compile any loops.

  > Hinweis: It is recommended that this parameter is set to a prime number, to prevent it from being a multiple of loop iteration counts.

`opcache.jit_hot_func` int
  After how many calls a function is considered hot. Valid value range is `[0,255]`; for any setting out of this range, e.g. `-1` or `256`, default value will be used instead. `0` will disable JIT to trace and compile any functions.
`opcache.jit_hot_return` int
  After how many returns a return is considered hot. Valid value range is `[0,255]`; for any setting out of this range, e.g. `-1` or `256`, default value will be used instead. `0` will disable JIT to trace and compile any returns.
`opcache.jit_hot_side_exit` int
  After how many exits a side exit is considered hot. Valid value range is `[0,255]`; for any setting out of this range, e.g. `-1` or `256`, default value will be used instead. `0` will disable JIT to trace and compile any side exits.
`opcache.jit_blacklist_root_trace` int
  Maximum number of times the compilation of a root trace is attempted before it is blacklisted.
`opcache.jit_blacklist_side_trace` int
  Maximum number of times the compilation of a side trace is attempted before it is blacklisted.
`opcache.jit_max_loop_unrolls` int
  Maximum number of attempts to unroll a loop in a side trace, trying to reach the root trace and close the outer loop.
`opcache.jit_max_recursive_calls` int
  Maximum number of unrolled recursive call loops.
`opcache.jit_max_recursive_returns` int
  Maximum number of unrolled recursive return loops.
`opcache.jit_max_polymorphic_calls` int
  Maximum number of attempts to inline polymorphic (dynamic or method) calls. Calls above this limit are treated as megamorphic and are not inlined.

# Preloading

As of PHP 7.4.0, PHP can be configured to preload scripts into the opcache when the engine starts. Any functions, classes, interfaces, or traits (but not constants) in those files will then become globally available for all requests without needing to be explicitly included. That trades convenience and performance (because the code is always available) for baseline memory usage. It also requires restarting the PHP process to clear pre-loaded scripts, meaning this feature is only practical to use in production, not in a development environment.

Note that the optimal tradeoff between performance and memory may vary with the application. "Preload everything" may be the easiest strategy, but not necessarily the best strategy. Additionally, preloading is only useful when there is a persistent process from one request to another. That means while it can work in a CLI script if the opcache is enabled, it's generally pointless. The exception is when using preloading on FFI libraries.

> Hinweis: Preloading is not supported on Windows.

Configuring preloading involves two steps, and requires that the opcache be enabled. First, set the opcache.preload value in php.ini:

    opcache.preload=preload.php

preload.php is an arbitrary file that will run once at server startup (PHP-FPM, mod_php, etc.) and load code into persistent memory. In servers that startup as root before switching to an unprivileged system user, or if PHP will be run as root (not recommended), the opcache.preload_user value can specify the system user to run the preloading. Running preloading as root is not allowed by default. Set `opcache.preload_user=root` to explicitly allow it.

In the preload.php script, any file referenced by include, include_once, require, require_once, or opcache_compile_file() will be parsed into persistent memory. In the following example, all .php files in the src directory will be preloaded, unless they are a `Test` file.

    <?php
    $directory = new RecursiveDirectoryIterator(__DIR__ . '/src');
    $fullTree = new RecursiveIteratorIterator($directory);
    $phpFiles = new RegexIterator($fullTree, '/.+((?<!Test)+\.php$)/i', RecursiveRegexIterator::GET_MATCH);

    foreach ($phpFiles as $key => $file) {
        require_once $file[0];
    }
    ?>

Both include and opcache_compile_file() will work, but have different implications for how code gets handled.

- include will execute code in the file, while opcache_compile_file() will not. That means only the former supports conditional declaration (functions declared inside an if-block).
- Because include will execute code, nested included files will also be parsed and their declarations preloaded.
- opcache_compile_file() can load files in any order. That is, if a.php defines class `A` and b.php defines class `B` that extends `A`, then opcache_compile_file() can load those two files in any order. When using include, however, a.php must be included first.
- In either case, if a later script includes a file that has already been preloaded then its contents will still execute, but any symbols it defines will not be re-defined. Using include_once will not prevent the file from being included a second time. It may be necessary to load a file again in order to include global constants defined in it, as those are not handled by preloading.

Which approach is better therefore depends on the desired behavior. With code that would otherwise use an autoloader, opcache_compile_file() allows for greater flexibility. With code that would otherwise be loaded manually, include will be more robust.

# OPcache Funktionen

# opcache_compile_file

(PHP 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_file — Compiles and caches a PHP script without executing it

### Beschreibung

function opcache_compile_file(string `$filename`): bool

This function compiles a PHP script and adds it to the opcode cache without executing it. This can be used to prime the cache after a Web server restart by pre-caching files that will be included in later requests.

### Parameter-Liste

`filename`
  The path to the PHP script to be compiled.

### Rückgabewerte

Returns `true` if `filename` was compiled successfully Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

If `filename` cannot be loaded or compiled, an error of level `E_WARNING` is generated. You may use @ to suppress this warning.

### Siehe auch

- opcache_invalidate() - Invalidates a cached script

# opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configuration — Get configuration information about the cache

### Beschreibung

function opcache_get_configuration(): array|false

This function returns configuration information about the cache instance

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of information, including ini, blacklist and version

### Fehler/Exceptions

If `opcache.restrict_api` is in use and the current path is in violation of the rule, an E_WARNING will be raised; no status information will be returned.

### Siehe auch

- opcache_get_status() - Liefert Statusinformationen über den Opcode-Cache

# opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_status — Liefert Statusinformationen über den Opcode-Cache

### Beschreibung

function opcache_get_status(bool `$include_scripts` = `true`): array|false

Diese Funktion gibt Statusinformationen über die Cache-Instanz im Speicher zurück. Sie gibt keine Informationen über den Dateicache zurück.

### Parameter-Liste

`include_scripts`
  Skriptspezifische Statusinformationen einbeziehen.

### Rückgabewerte

Gibt ein Array mit Informationen zurück, das optional skriptspezifische Statusinformationen enthält. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn `opcache.restrict_api` benutzt wird und der aktuelle Pfad eine Verletzung dieser Regel ist, wird eine E_WARNING-Meldung ausgelöst und es werden keine Statusinformationen zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PHP 8.3.0 | `opcache_get_status()['scripts'][n]['revalidate']` enthält nun einen Unix-Zeitstempel, der angibt, wann die nächste Überprüfung des Skript-Zeitstempels gemäß der INI-Direktive `opcache.revalidate_freq` fällig ist.

### Beispiele

Beispiel #1 Ein opcache_get_status()-Beispiel

    <?php
    var_dump(opcache_get_status());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(9) {
      'opcache_enabled' =>
      bool(true)
      'cache_full' =>
      bool(false)
      'restart_pending' =>
      bool(false)
      'restart_in_progress' =>
      bool(false)
      'memory_usage' =>
      array(4) {
        'used_memory' =>
        int(9167936)
        'free_memory' =>
        int(125049792)
        'wasted_memory' =>
        int(0)
        'current_wasted_percentage' =>
        double(0)
      }
      'interned_strings_usage' =>
      array(4) {
        'buffer_size' =>
        int(8388608)
        'used_memory' =>
        int(2593616)
        'free_memory' =>
        int(5794992)
        'number_of_strings' =>
        int(10358)
      }
      'opcache_statistics' =>
      array(13) {
        'num_cached_scripts' =>
        int(0)
        'num_cached_keys' =>
        int(0)
        'max_cached_keys' =>
        int(16229)
        'hits' =>
        int(0)
        'start_time' =>
        int(1733310010)
        'last_restart_time' =>
        int(0)
        'oom_restarts' =>
        int(0)
        'hash_restarts' =>
        int(0)
        'manual_restarts' =>
        int(0)
        'misses' =>
        int(0)
        'blacklist_misses' =>
        int(0)
        'blacklist_miss_ratio' =>
        double(0)
        'opcache_hit_rate' =>
        double(0)
      }
      'scripts' =>
      array(0) {
      }
      'jit' =>
      array(7) {
        'enabled' =>
        bool(false)
        'on' =>
        bool(false)
        'kind' =>
        int(5)
        'opt_level' =>
        int(4)
        'opt_flags' =>
        int(6)
        'buffer_size' =>
        int(0)
        'buffer_free' =>
        int(0)
      }
    }

### Siehe auch

- opcache_get_configuration() - Get configuration information about the cache

# opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidate — Invalidates a cached script

### Beschreibung

function opcache_invalidate(string `$filename`, bool `$force` = `false`): bool

This function invalidates a particular script from the opcode cache. If `force` is unset or `false`, the script will only be invalidated if the modification time of the script is newer than the cached opcodes. This function only invalidates in-memory cache and not file cache.

### Parameter-Liste

`filename`
  The path to the script being invalidated.
`force`
  If set to `true`, the script will be invalidated regardless of whether invalidation is necessary.

### Rückgabewerte

Returns `true` if the opcode cache for `filename` was invalidated or if there was nothing to invalidate, or `false` if the opcode cache is disabled.

### Siehe auch

- opcache_compile_file() - Compiles and caches a PHP script without executing it
- opcache_reset() - Setzt den Inhalt des Opcode-Caches zurück

# opcache_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cached — Tells whether a script is cached in OPCache

### Beschreibung

function opcache_is_script_cached(string `$filename`): bool

This function checks if a PHP script has been cached in OPCache. This can be used to more easily detect the "warming" of the cache for a particular script. This function only checks in-memory cache, not file cache. In order to check file cache, use opcache_is_script_cached_in_file_cache().

### Parameter-Liste

`filename`
  The path to the PHP script to be checked.

### Rückgabewerte

Returns `true` if `filename` is cached in OPCache in-memory cache, `false` otherwise.

### Siehe auch

- opcache_compile_file() - Compiles and caches a PHP script without executing it
- opcache_is_script_cached_in_file_cache() - Tells whether a script is cached in OPCache file cache

# opcache_is_script_cached_in_file_cache

(PHP 8 >= 8.5.0)

opcache_is_script_cached_in_file_cache — Tells whether a script is cached in OPCache file cache

### Beschreibung

function opcache_is_script_cached_in_file_cache(string `$filename`): bool

This function checks if a PHP script has been cached in OPCache. This can be used to more easily detect the "warming" of the cache for a particular script. This function only checks file cache, not in-memory cache. In order to check in-memory cache, use opcache_is_script_cached().

### Parameter-Liste

`filename`
  The path to the PHP script to be checked.

### Rückgabewerte

Returns `true` if `filename` is cached in OPCache, `false` otherwise.

### Siehe auch

- opcache_compile_file() - Compiles and caches a PHP script without executing it
- opcache_is_script_cached() - Tells whether a script is cached in OPCache

# opcache_jit_blacklist

(PHP 8 >= 8.4.0)

opcache_jit_blacklist — Blacklists a function from being JIT compiled

### Beschreibung

function opcache_jit_blacklist( Closure `$closure` ): void

This function blacklists a particular function from being JIT compiled when Tracing JIT is in use. The function is specified using a Closure.

Warnung

Any parts of the function that were already JIT compiled remain unaffected and will still be JIT compiled.

### Parameter-Liste

`closure`
  The function to blacklist, represented as a first class callable. It is also possible to pass an anonymous function, in which case the anonymous function itself is blacklisted.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 opcache_jit_blacklist() basic example

    <?php
    function foo() {
        $x = 1;
        $x += 0;
        ++$x;
        var_dump($x);
    }
    opcache_jit_blacklist(foo(...));
    foo();
    ?>

### Siehe auch

- opcache_invalidate() - Invalidates a cached script
- opcache_reset() - Setzt den Inhalt des Opcode-Caches zurück

# opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_reset — Setzt den Inhalt des Opcode-Caches zurück

### Beschreibung

function opcache_reset(): bool

Diese Funktion setzt den gesamten OPcode-Cache zurück. Nach dem Aufrufen von opcache_reset() werden alle Skripte beim nächsten Aufruf neu geladen und geparst. Diese Funktion setzt nur den Cache im Speicher zurück, nicht den Dateicache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn der OPcode-Cache zurückgesetzt wurde, oder `false` wenn der OPcode-Cache deaktiviert ist oder der Neustart ansteht oder gerade läuft (siehe opcache_get_status()).

### Siehe auch

- opcache_invalidate() - Invalidates a cached script
- opcache_get_status() - Liefert Statusinformationen über den Opcode-Cache

## Inhaltsverzeichnis

- opcache_compile_file — Compiles and caches a PHP script without executing it
- opcache_get_configuration — Get configuration information about the cache
- opcache_get_status — Liefert Statusinformationen über den Opcode-Cache
- opcache_invalidate — Invalidates a cached script
- opcache_is_script_cached — Tells whether a script is cached in OPCache
- opcache_is_script_cached_in_file_cache — Tells whether a script is cached in OPCache file cache
- opcache_jit_blacklist — Blacklists a function from being JIT compiled
- opcache_reset — Setzt den Inhalt des Opcode-Caches zurück

- Installation/Konfiguration
  - Installation
  - Laufzeit-Konfiguration
- Preloading
- OPcache Funktionen
  - opcache_compile_file — Compiles and caches a PHP script without executing it
  - opcache_get_configuration — Get configuration information about the cache
  - opcache_get_status — Liefert Statusinformationen über den Opcode-Cache
  - opcache_invalidate — Invalidates a cached script
  - opcache_is_script_cached — Tells whether a script is cached in OPCache
  - opcache_is_script_cached_in_file_cache — Tells whether a script is cached in OPCache file cache
  - opcache_jit_blacklist — Blacklists a function from being JIT compiled
  - opcache_reset — Setzt den Inhalt des Opcode-Caches zurück

# Operator Overloading for Objects

# Einführung

This extension defines and implements operator overloading for objects. It allows defining how an object reacts when an operator is used on it.

One example of this is creating a collection type object that has the addition operator overloaded to allow adding elements to the collection or adding two collections together.

Another example is creating an enhanced string class that has the multiplication operator overloaded to allow repeating the string a certain number of times.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/operator.

Windows users can download prebuilt release binaries from the » PECL website.

operator releases are hosted by PECL and the source code by » github.

# Operator Overloading Magic Methods

The operator overloading extension allows you to define how an object reacts to operators. This is done by implementing the following magic methods:

Arithmetic operators:

- `$a::__add($b)`
- `$a::__sub($b)`
- `$a::__mul($b)`
- `$a::__div($b)`
- `$a::__mod($b)`
- `$a::__pow($b)`

Assignment operators:

- `$a::__assign($b)`
- `$a::__assign_add($b)`
- `$a::__assign_sub($b)`
- `$a::__assign_mul($b)`
- `$a::__assign_div($b)`
- `$a::__assign_mod($b)`
- `$a::__assign_pow($b)`
- `$a::__assign_bw_and($b)`
- `$a::__assign_bw_or($b)`
- `$a::__assign_bw_xor($b)`
- `$a::__assign_sl($b)`
- `$a::__assign_sr($b)`
- `$a::__assign_concat($b)`

Bitwise operators:

- `$a::__bw_and($b)`
- `$a::__bw_or($b)`
- `$a::__bw_xor($b)`
- `$a::__bw_not()`
- `$a::__sl($b)`
- `$a::__sr($b)`

Comparison operators:

- `$a::__is_equal($b)`
- `$a::__is_not_equal($b)`
- `$a::__is_identical($b)`
- `$a::__is_not_identical($b)`
- `$a::__is_smaller($b)`
- `$a::__is_smaller_or_equal($b)`
- `$a::__is_greater($b)`
- `$a::__is_greater_or_equal($b)`
- `$a::__spaceship($b)`

Incrementing and decrementing operators:

- `$a::__pre_inc()`
- `$a::__post_inc()`
- `$a::__pre_dec()`
- `$a::__post_dec()`

String operators:

- `$a::__concat($b)`

## Operator Overloading Examples

The following is the class that is used in the testing of the operator overloading extension. It overloads all of the possible operators that can be overloaded for testing.

Beispiel #1 Complete class for operator overloading

    <?php
    class OperatorOverloading {
        protected mixed $value;

        //region Standard magic methods
        public function __get(string $name)
        {
            return $this->value;
        }

        public function __set(string $name, mixed $value)
        {
            $this->value = $value;
        }

        public function __construct(mixed $init = null)
        {
            $this->value = $init;
        }
        //endregion

        //region Arithmetic Operators
        public function __add(mixed $val): int|float
        {
            return $this->value + $val;
        }

        public function __div(mixed $val): int|float
        {
            return $this->value / $val;
        }

        public function __mod(mixed $val): int
        {
            return $this->value % $val;
        }

        public function __mul(mixed $val): int|float
        {
            return $this->value * $val;
        }

        public function __pow(mixed $val): int|float
        {
            return $this->value ** $val;
        }

        public function __sub(mixed $val): int|float
        {
            return $this->value - $val;
        }
        //endregion

        //region Assignment Operators
        public function __assign(mixed $val): mixed
        {
            return $this->value = $val;
        }

        public function __assign_add(mixed $val): mixed
        {
            return $this->value += $val;
        }

        public function __assign_bw_and(mixed $val): mixed
        {
            return $this->value &= $val;
        }

        public function __assign_bw_or(mixed $val): mixed
        {
            return $this->value |= $val;
        }

        public function __assign_concat(mixed $val): string
        {
            return $this->value .= $val;
        }

        public function __assign_div(mixed $val): mixed
        {
            return $this->value /= $val;
        }

        public function __assign_mod(mixed $val): mixed
        {
            return $this->value %= $val;
        }

        public function __assign_mul(mixed $val): mixed
        {
            return $this->value *= $val;
        }

        public function __assign_pow(mixed $val): mixed
        {
            return $this->value **= $val;
        }

        public function __assign_sl(mixed $val): mixed
        {
            return $this->value <<= $val;
        }

        public function __assign_sr(mixed $val): mixed
        {
            return $this->value >>= $val;
        }

        public function __assign_sub(mixed $val): mixed
        {
            return $this->value -= $val;
        }
        //endregion

        //region Bitwise Operators
        public function __bw_and(mixed $val): int
        {
            return $this->value & $val;
        }

        public function __bw_not(): int|string
        {
            return ~$this->value;
        }

        public function __bw_or(mixed $val): int
        {
            return $this->value | $val;
        }

        public function __bw_xor(mixed $val): int
        {
            return $this->value ^ $val;
        }

        public function __sl(mixed $val): int
        {
            return $this->value << $val;
        }

        public function __sr(mixed $val): int
        {
            return $this->value >> $val;
        }
        //endregion

        //region Comparison Operators
        public function __is_equal(mixed $val): bool
        {
            return $this->value == $val;
        }

        public function __is_greater(mixed $val): bool
        {
            return $this->value > $val;
        }

        public function __is_greater_or_equal(mixed $val): bool
        {
            return $this->value >= $val;
        }

        public function __is_identical(mixed $val): bool
        {
            return $this->value === $val;
        }

        public function __is_not_equal(mixed $val): bool
        {
            return $this->value != $val;
        }

        public function __is_not_identical(mixed $val): bool
        {
            return $this->value !== $val;
        }

        public function __is_smaller(mixed $val): bool
        {
            return $this->value < $val;
        }

        public function __is_smaller_or_equal(mixed $val): bool
        {
            return $this->value <= $val;
        }

        public function __spaceship(mixed $val): int
        {
            return $this->value <=> $val;
        }
        //endregion

        //region Incrementing/Decrementing Operators
        public function __post_dec(): mixed
        {
            return $this->value--;
        }

        public function __post_inc(): mixed
        {
            return $this->value++;
        }

        public function __pre_dec(): mixed
        {
            return --$this->value;
        }

        public function __pre_inc(): mixed
        {
            return ++$this->value;
        }
        //endregion

        //region String Operators
        public function __concat(mixed $val): string
        {
            return $this->value . $val;
        }
        //endregion

    }

Using the above class, you can overload the operators as follows:

    <?php
    $a = new OperatorOverloading(5);
    var_dump($a + 10);
    var_dump($a - 10);
    $b = new OperatorOverloading("Hello");
    var_dump($b . " World");

The above code will output:

    int(15)
    int(-5)
    string(11) "Hello World"

- Installation/Konfiguration
  - Installation
- Operator Overloading Magic Methods

# Ausgabepufferung

# Einführung

Mit den Funktionen zur Ausgabesteuerung kann die Ausgabe eines Skripts gesteuert werden. Dies kann in verschiedenen Situationen ganz nützlich sein, besonders wenn Header an den Browser gesendet werden müssen, nachdem das Skript bereits etwas ausgegeben hat. Die Ausgabesteuerungsfunktionen gelten nicht für Header, die mit header() oder setcookie() gesendet wurden, sondern nur für Daten, die mit echo gesendet wurden oder für Daten zwischen PHP-Codeblöcken.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Laufzeit-Konfiguration

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Konfigurationsoptionen für die Ausgabekontrolle
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
output_buffering | `"0"` | `INI_PERDIR` |
output_handler | `null` | `INI_PERDIR` |
implicit_flush | `"0"` | `INI_ALL` |
url_rewriter.tags | `"form="` | `INI_ALL` | Seit PHP 7.1.0 wirkt sich diese INI-Einstellung nur auf die Funktion output_add_rewrite_var() aus. Vor PHP 7.1.0 konnte damit die Unterstützung für transparente Session-IDs aktiviert werden (siehe session.trans_sid_tags).
url_rewriter.hosts | `$_SERVER['HTTP_HOST']` | `INI_ALL` | Verfügbar von PHP 7.1.0 an

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`output_buffering` bool/int

  Die Ausgabepufferung für alle Dateien kann aktiviert werden, indem diese Direktive auf `"On"` gesetzt wird. Um die Größe des Puffers zu begrenzen, kann anstelle von `"On"` eine Zahl angegeben werden, die der maximal zulässigen Anzahl von Bytes entspricht. (z. B. `output_buffering=4096`). Diese Direktive ist für den PHP-CLI-Kommandozeileninterpreter grundsätzlich "Off".

`output_handler` string

  Die Ausgaben eines Skripts kann an eine Funktion weitergeleitet werden. Wenn `output_handler` z. B. auf mb_output_handler() gesetzt wird, wird die Zeichenkodierung transparent in die angegebene Kodierung umgewandelt. Durch das Setzen einer beliebigen Ausgabesteuerung wird die Ausgabepufferung automatisch aktiviert.

  > Hinweis:

  > Die Funktionen mb_output_handler() und ob_iconv_handler() können nicht zusammen verwendet werden und die Funktion ob_gzhandler() und die Direktive zlib.output_compression können nicht zusammen mit einer der folgenden Funktionen und Direktiven verwendet werden: mb_output_handler(), ob_gzhandler(), zlib.output_compression und "URL-Rewriter"-Handler (siehe session.use_trans_sid und output_add_rewrite_var()).

  > Hinweis:

  > Es können nur eingebaute Funktionen mit dieser Direktive verwendet werden. Benutzerdefinierte Funktionen können mit Hilfe der Funktion ob_start() genutzt werden.

`implicit_flush` bool

  Diese Option ist standardmäßig `false`. Wenn implicit_flush auf `true` gesetzt wird, wird PHP angewiesen, den Ausgabepuffer nach jedem Ausgabeblock automatisch zu leeren. Dies entspricht dem Aufruf der Funktion flush() nach jedem Aufruf einer Funktion, die eine Ausgabe erzeugt (wie print oder echo) und nach jedem HTML-Block.

  In Webanwendungen führt diese Option zu erheblichen Leistungseinbußen und wird im Allgemeinen nur für Debugging-Zwecke empfohlen. In der `CLI-SAPI` (Kommandozeileninterpreter) dagegen ist diese Option standardmäßig `true`.

  Siehe auch ob_implicit_flush().

`url_rewriter.tags` string
  `url_rewriter.tags` definiert die HTML-Tags und Attribute, in welchen URLs durch output_add_rewrite_var() umgeschrieben werden. Die Voreinstellung ist `"form="`. Durch Hinzufügen des Wertes `"form="` oder eines beliebigen `form`-Attributs wird `form` ein verstecktes `input`-Element hinzugefügt, das für jedes an output_add_rewrite_var() übergebene Name-Wert-Paar ein Name- und ein Wert-Attribut enthält.
  Achtung

  Wird dasselbe Tag mehr als einmal zu `url_rewriter.tags` hinzugefügt, wird nur der erste Eintrag beim Umschreiben der URL verwendet.

  > Hinweis: Vor PHP 7.1.0 wurde url_rewriter.tags verwendet, um session.trans_sid_tags anzugeben.

`url_rewriter.hosts` string
  `url_rewriter.hosts` gibt an, welche Hosts umgeschrieben werden, um output_add_rewrite_var()-Werte aufzunehmen. Standardmäßig ist das `$_SERVER['HTTP_HOST']`. Mehrere Hosts können mit einer durch Kommas getrennte Liste angegeben werden, die keine Leerzeichen enthält, z. B. `"php.net,wiki.php.net,bugs.php.net"`.

# Vordefinierte Konstanten

Die aufgelisteten Konstanten stehen immer zur Verfügung, da sie zum Grundbestand von PHP gehören.

Status-Flags, die an den Ausgabe-Handler übergeben werden

Die folgenden Flags werden als Teil einer Bitmaske an den zweiten Parameter (`phase`) des von ob_start() gesetzten Ausgabe-Handlers übergeben:

`PHP_OUTPUT_HANDLER_START` (int)

  Zeigt an, dass die Pufferung der Ausgabe begann.

`PHP_OUTPUT_HANDLER_WRITE` (int)

  Zeigt an, dass der Ausgabepuffer geleert wird und Daten zur Ausgabe bereitstehen.

`PHP_OUTPUT_HANDLER_FLUSH` (int)

  Zeigt an, dass der Ausgabepuffer geleert und ausgegeben wurde.

`PHP_OUTPUT_HANDLER_CLEAN` (int)

  Zeigt an, dass der Ausgabepuffer gelöscht wurde.

`PHP_OUTPUT_HANDLER_FINAL` (int)

  Zeigt an, dass dies die letzte Operation des Ausgabepuffers ist.

`PHP_OUTPUT_HANDLER_CONT` (int)

  Zeigt an, dass der Ausgabepuffer geleert und ausgegeben wurde, aber die Pufferung fortgesetzt wird.

  Es ist ein Alias für `PHP_OUTPUT_HANDLER_WRITE`.

`PHP_OUTPUT_HANDLER_END` (int)

  Zeigt an, dass die Ausgabepufferung endete.

  Es ist ein Alias für `PHP_OUTPUT_HANDLER_FINAL`.

Flags für die Steuerung des Ausgabepuffers

Die folgenden Flags können dem dritten Parameter (`flags`) des von ob_start() gesetzten Ausgabe-Handlers als Bitmaske übergeben werden:

`PHP_OUTPUT_HANDLER_CLEANABLE` (int)

  Steuert, ob ein durch ob_start() erzeugter Ausgabepuffer durch ob_clean() gelöscht werden kann. Dieses Flag kontrolliert nicht das Verhalten von ob_end_clean() oder ob_get_clean().

`PHP_OUTPUT_HANDLER_FLUSHABLE` (int)

  Steuert, ob ein durch ob_start() erzeugter Ausgabepuffer durch ob_flush() geleert und ausgegeben werden kann. Dieses Flag kontrolliert nicht das Verhalten von ob_end_flush() oder ob_get_flush().

`PHP_OUTPUT_HANDLER_REMOVABLE` (int)

  Steuert, ob ein durch ob_start() erzeugter Ausgabepuffer vor Ende der Skriptlaufzeit oder beim Aufruf von ob_end_clean(), ob_end_flush(), ob_get_clean() oder ob_get_flush() entfernt werden kann.

`PHP_OUTPUT_HANDLER_STDFLAGS` (int)

  Die Flags für die Standardeinstellungen des Puffers. Derzeit gleichbedeutend mit `PHP_OUTPUT_HANDLER_CLEANABLE` | `PHP_OUTPUT_HANDLER_FLUSHABLE` | `PHP_OUTPUT_HANDLER_REMOVABLE`.

Statusflags des Ausgabe-Handlers

Die folgenden Flags sind Teil der `flags` Bitmaske, die von der ob_get_status() zurückgegeben wird:

`PHP_OUTPUT_HANDLER_STARTED` (int)

  Zeigt an, dass der Ausgabe-Handler aufgerufen wurde.

`PHP_OUTPUT_HANDLER_DISABLED` (int)

  Zeigt an, dass der Ausgabe-Handler deaktiviert ist. Dieses Flag wird gesetzt, wenn der Ausgabe-Handler `false` zurückgibt oder bei der Verarbeitung des Puffers fehlschlägt. Vor PHP 8.4.0 konnte dieses Flag beim Starten eines Ausgabepuffers gesetzt werden.

`PHP_OUTPUT_HANDLER_PROCESSED` (int)

  Zeigt an, dass der Ausgabe-Handler den Puffer erfolgreich verarbeitet hat. Verfügbar von PHP 8.4.0 an.

# Output Buffering

Output buffering is the buffering (temporary storage) of output before it is flushed (sent and discarded) to the browser (in a web context) or to the shell (on the command line). While output buffering is active no output is sent from the script, instead the output is stored in an internal buffer.

## Buffering Affecting PHP

PHP relies on the underlying software/hardware infrastructure when flushing output. Buffering implemented by consoles on the command line (e.g. line buffered) or web servers and browser in a web context (e.g. fully buffered) do affect when output is displayed to the end-user. Some of these effects can be eliminated by fine-tuning server settings and/or aligning buffer sizes of the various layers.

## Output Buffering Control In PHP

PHP provides a fully buffered user-level output buffer with functions to start, manipulate and turn off the buffer (most ob_* functions), and two functions to flush the underlying system buffers (flush() and ob_implicit_flush()). Some of this functionality can be set and/or configured using the appropriate php.ini settings as well.

## Use Cases

Output buffering is generally useful in situations when the buffered output is modified or inspected, or it is used more than once in a request; or when the controlled flushing of output is desired. Specific use cases include:

- caching the result of compute/time intensive scripts for example by generating static `HTML` pages
- re-using the generated output by displaying it, saving it to a file and/or sending it by email
- flushing the `head` of an `HTML` page separate from the `body` allows browsers to load external resources while the script executes potentially more time consuming processes (e.g. database/file access, external network connection). This is only useful if the `HTTP` status code cannot change after the headers are sent
- extracting information from functions that would otherwise produce output (e.g. phpinfo())
- controlling the output of third-party code by modifying/using parts (e.g. extracting data, replacing words/phrases, adding missing `HTML` tags), or discarding it entirely under certain conditions (e.g. errors)
- polyfilling certain unavailable web server functionality (e.g. compressing or encoding output)

# Flushing System Buffers

PHP provides two related ways to flush (send and discard the contents of) system buffers: through calling flush() and through enabling implicit flushing with ob_implicit_flush() or the implicit_flush php.ini setting.

## Output Flushing Behaviour

With implicit flushing disabled, PHP will flush output only when flush() is called or when the script ends.

With implicit flushing enabled, PHP will attempt to flush after every block of code resulting in output. Output in this context is non-zero length data that is:

- outside of the `<?php ?>` tags
- printed by language constructs and functions whose explicit purpose is to output user provided variables or strings such as echo, print, printf(), var_dump(), var_export(), vprintf()
- printed by functions whose purpose is to collect and output data/information on the running script or PHP such as debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info()
- printed by PHP on an uncaught exception or an unhandled error (subject to the settings of display_errors and error_reporting)
- anything written to `php://output`

> Hinweis: Printing empty strings or sending headers is not considered output and will not result in a flush operation.

Warnung

If implicit flushing is enabled, control characters (e.g. `"\n"`, `"\r"`, `"\0"`) will trigger flushing as well.

## Limitations

This functionality cannot flush user-level output buffers. To use these together, user-level output buffers must be flushed before flushing system buffers in order for PHP to produce any output.

Warnung

Calling flush() or implicit flushing being enabled can interfere with output handlers of user-level output buffers that set and send headers in a web context (e.g. ob_gzhandler()) by sending headers before these handlers can do so.

Buffering implemented by the underlying software/hardware cannot be overridden by PHP and should be taken into account when working with PHP's buffer control functions. Checking the web servers/browsers/consoles buffering settings and working with these can alleviate possible issues. Working in a web context, either the web server's buffering settings or the script's buffering could be adjusted to work in tandem whereas working around the buffering strategies of various browsers can be achieved by adjusting buffering in the PHP script. On consoles that implement line buffering, newline characters could be inserted in the appropriate places before flushing output.

## SAPI Differences In Flushing

Although flushing is implemented by each SAPI in a slightly different way, these implementations fall in one of two categories:

- SAPIs used in a web context will flush headers first followed by the output. `Apache2Handler`, `CGI`, `FastCGI` and `FPM` are such SAPIs
- other SAPIs such as `CLI` and `embed` will flush output only

# User-Level Output Buffers

## Inhaltsverzeichnis

- What Output Is Buffered?
- Nesting Output Buffers
- Buffer Size
- Operations Allowed On Buffers
- Output Handlers
- Working With Output Handlers
- Flags Passed To Output Handlers
- Output Handler Return Values

User-level output buffers can be started, manipulated and terminated from PHP code. Each of these buffers includes an output buffer and an associated output handler function.

## What Output Is Buffered?

PHP's user-level output buffers buffer all output after they are started until they are turned off or the script ends. Output in the context of PHP's user-level output buffer is everything that PHP would display or send back to the browser. In practical terms, output is non-zero length data that is:

- outside of the `<?php ?>` tags
- printed by language constructs and functions whose explicit purpose is to output user provided variables or strings such as echo, print, printf(), var_dump(), var_export(), vprintf()
- printed by functions whose purpose is to collect and output data/information on the running script or PHP such as debug_print_backtrace(), phpcredits(), phpinfo(), ReflectionExtension::info()
- printed by PHP on an uncaught exception or an unhandled error (subject to the settings of display_errors and error_reporting)
- anything written to `php://output`

> Hinweis: Data that is written directly to `stdout` or passed to an SAPI function with a similar functionality will not be captured by user-level output buffers. This includes writing data to `stdout` with fwrite() or sending headers using header() or setcookie().

## Turning Output Buffering On

Output buffering can be turned on by using the ob_start() function or by setting the output_buffering and output_handler php.ini settings. While both can create output buffers, ob_start() is more flexible as it accepts user-defined functions as output handlers and the operations allowed on the buffer (flush, clean, remove) can be set as well. Buffers started with ob_start() will be active from the line the function was called, while those started with output_buffering will be buffering output from the first line of the script.

PHP is also shipped with a built-in `"URL-Rewriter"` output handler which starts its own output buffer and only allows up to two instances of it running at any time (one for user-level URL-rewriting and one for transparent session id support). These buffers can be started by calling the output_add_rewrite_var() function and/or by enabling the session.use_trans_sid php.ini setting.

The bundled `zlib` extension has its own output buffer which can be enabled by using the zlib.output_compression php.ini setting.

> Hinweis: While `"URL-Rewriter"` is special in that it only allows up to two instances of it running at any one time, all user-level output buffers use the same underlying buffers used by ob_start() with their functionality implemented by a custom output handler function. As such, all of their functionality can be emulated by userland code.

## Nesting Output Buffers

If there is an output buffer active when a new buffer is started, the new buffer will be nested inside the previously active buffer. The inner buffer will behave the same way regardless whether it is nested but output buffered by it will not be buffered by the outer buffer. Only output flushed by the inner buffer will be buffered by the outer buffer.

Most `ob_*` functions only work with the active output buffer (the last one started) therefore only the active buffer can be flushed, cleaned and turned off. The functions that work with other buffers are ob_list_handlers() which returns the list of all output handlers in use and ob_get_status() which can return information on the active buffer only or on all buffers in use.

Calling ob_get_level() or ob_get_status() will return the nesting level of the active output buffer.

Achtung

The value for identical levels between ob_get_level() and ob_get_status() is off by one. For ob_get_level() the first level is `1`, whereas for ob_get_status() the first level is `0`.

## Buffer Size

Buffer sizes are expressed by integers and represent the number of bytes the buffer can store without flushing. When the size of output in the buffer exceeds the size of the buffer, the contents of the buffer are sent to the output handler, its return value is flushed and the buffer is cleared.

With the exception of `"URL-Rewriter"`, the size of output buffers can be set when the buffer is started. If set to `0`, the output buffer is only limited by the memory available to PHP. If set to `1`, the buffer is flushed after every block of code producing any non-zero length output.

The size of output buffers can be retrieved by calling ob_get_status().

Output buffers started with ob_start() will have their buffer sizes set to the integer value passed to the function's second `chunk_size` parameter. If omitted, it is set to `0`.

The output buffer started with output_buffering set to `"On"` will have its buffer size set to 0. If set to an integer than buffer size will correspond to that number.

`"URL-Rewriter"`'s buffer size is set to `0`, therefore it is only limited by the memory available to PHP.

The size of `zlib`'s output buffer is controlled by the zlib.output_compression php.ini setting. If set to `"On"` the buffer size will be `"16K"`/`16384`. If set to an integer then buffer size will correspond to that number in bytes.

## Operations Allowed On Buffers

The operations allowed on buffers can be controlled by passing one of the buffer control flags to ob_start()'s third `flags` parameter. If omitted, all operations are allowed by default. If `0` is used instead, the buffer cannot be flushed, cleaned or removed but its contents can still be retrieved.

`PHP_OUTPUT_HANDLER_CLEANABLE` allows ob_clean() to clean the contents of the buffer.

Warnung

The absence of the `PHP_OUTPUT_HANDLER_CLEANABLE` flag will not prevent ob_end_clean() or ob_get_clean() from clearing the contents of the buffer.

`PHP_OUTPUT_HANDLER_FLUSHABLE` allows ob_flush() to flush the contents of the buffer.

Warnung

The absence of the `PHP_OUTPUT_HANDLER_FLUSHABLE` flag will not prevent ob_end_flush() or ob_get_flush() from flushing the contents of the buffer.

`PHP_OUTPUT_HANDLER_REMOVABLE` allows ob_end_clean(), ob_end_flush(), ob_get_clean() or ob_get_flush() to turn off the buffer.

`PHP_OUTPUT_HANDLER_STDFLAGS`, the combination of the three flags will allow each of the three operations to be performed on the buffer.

## Flushing, Accessing And Cleaning Buffer Contents

Flushing sends and discards the contents of the active buffer. Output buffers get flushed when the size of the output exceeds the size of the buffer; the script ends or ob_flush(), ob_end_flush() or ob_get_flush() is called.

Achtung

Calling ob_end_flush() or ob_get_flush() will turn off the active buffer.

Achtung

Flushing buffers will flush the return value of the output handler which can differ from the contents of the buffer. For example, using ob_gzhandler() will compress the output and flush the compressed output.

The contents of the active buffer can be retrieved by calling ob_get_contents(), ob_get_clean() or ob_get_flush().

If only the length of the buffer's contents are needed, ob_get_length() or ob_get_status() will return the length of the contents in bytes.

Achtung

Calling ob_get_clean() or ob_get_flush() will turn off the active buffer after returning the its contents.

The contents of the active buffer can be cleaned by calling ob_clean(), ob_end_clean() or ob_get_clean().

Achtung

Calling ob_end_clean() or ob_get_clean() will turn off the active buffer.

## Turning Buffers Off

Output buffers can be turned off by calling ob_end_clean(), ob_end_flush(), ob_get_flush() or ob_get_clean().

Warnung

Output buffers started without the `PHP_OUTPUT_HANDLER_REMOVABLE` flag cannot be turned off and may generate an `E_NOTICE`.

Every output buffer that has not been closed by the end of the script or when exit() is called will be flushed and turned off by PHP's shutdown process. The buffers will be flushed and turned off in reverse order of their starting up. The last buffered started will be first, the first buffer started will be last to be flushed and turned off.

Achtung

If flushing of the buffer's contents is not desired, a custom output handler should be used to prevent flushing during shutdown.

## Output Handlers

Output handlers are callables associated with output buffers that are invoked by calling ob_clean(), ob_flush(), ob_end_flush(), ob_get_flush(), ob_end_clean(), ob_get_clean() or during PHP's shutdown process.

> Hinweis: The shutdown process will flush the return value of the handler.

If omitted or `null` when starting the output buffer the internal `"default output handler"` will be used which returns the unmodified contents of the buffer when invoked. Output handlers can be used to return a modified version of the buffer's contents and/or have side-effects (e.g. send headers).

PHP comes with two internal output handlers: `"default output handler"` and `"URL-Rewriter"` (which is integrated into its own output buffer and only up to two instances of it can be started).

The bundled extensions include four additional output handlers: mb_output_handler(), ob_gzhandler(), ob_iconv_handler(), ob_tidyhandler().

## Working With Output Handlers

When invoked, output handlers are passed the contents of the buffer and a bitmask indicating the status of output buffering.

function handler ( string `$buffer` , int `$phase` = ?): string

`buffer`
  Contents of the output buffer.
`phase`
  Bitmask of `PHP_OUTPUT_HANDLER_*` constants .

Warnung

Calling any of the following functions from within an output handler will result in a fatal error: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

> Hinweis: If the `PHP_OUTPUT_HANDLER_DISABLED` of a handler is set, the handler will not be invoked by calling ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() or during PHP's shutdown process. Prior to PHP 8.4.0, this flag had no effect when calling ob_clean() or ob_flush().

> Hinweis: The working directory of the script can change inside the shutdown function under some web servers, e.g. Apache or the built-in web server.

## Flags Passed To Output Handlers

The bitmask passed to the second `phase` parameter of the output handler provides information on the invocation of the handler.

> Hinweis: The bitmask can include more than one flag and the bitwise `&` operator should be used to check whether a flag is set.

Warnung

The value of `PHP_OUTPUT_HANDLER_WRITE` and its alias `PHP_OUTPUT_HANDLER_CONT` is `0` therefore whether it is set can only be determined by using an equality operator (`==` or `===`).

The following flags are set in a specific phase of the handler's lifecycle: `PHP_OUTPUT_HANDLER_START` is set when a handler is invoked for the first time. `PHP_OUTPUT_HANDLER_FINAL` or its alias `PHP_OUTPUT_HANDLER_END` is set when a handler is invoked for the last time, i.e. it is being turned off. This flag is also set when buffers are being turned off by PHP's shutdown process.

The following flags are set by a specific invocation of the handler: `PHP_OUTPUT_HANDLER_FLUSH` is set when the handler is invoked by calling ob_flush(). `PHP_OUTPUT_HANDLER_WRITE` or its alias `PHP_OUTPUT_HANDLER_CONT` is set when the size of its contents equals or exceeds the size of the buffer and the handler is invoked while the buffer is being automatically flushed. `PHP_OUTPUT_HANDLER_FLUSH` is set when the handler is invoked by calling ob_clean(), ob_end_clean() or ob_get_clean(). When ob_end_clean() or ob_get_clean() is called, `PHP_OUTPUT_HANDLER_FINAL` is set as well.

> Hinweis: When ob_end_flush() or ob_get_flush() is called, `PHP_OUTPUT_HANDLER_FINAL` is set but `PHP_OUTPUT_HANDLER_FLUSH` is not.

## Output Handler Return Values

The return value of the output handler is internally coerced into a string following standard PHP type semantics, with two exceptions: arrays and booleans.

Arrays are converted into the string `"Array"` but the `Array to string conversion` warning is not triggered.

If the handler returns `false` the contents of the buffer are returned. If the handler returns `true` an empty string is returned.

> Hinweis: If a handler returns `false` or throws an exception its `PHP_OUTPUT_HANDLER_DISABLED` status flag is set.

## Exceptions Thrown In Output Handlers

If an uncaught exception is thrown in an output handler the program terminates and the handler is invoked by the shutdown process after which the `"Uncaught Exception"` error message is flushed.

If the uncaught exception is thrown in a handler invoked by ob_flush(), ob_end_flush() or ob_get_flush(), the contents of the buffer are flushed before the error message.

If an uncaught exception is thrown in an output handler during shutdown, the handler is terminated and neither the contents of the buffer nor the error message is flushed.

> Hinweis: If a handler throws an exception its `PHP_OUTPUT_HANDLER_DISABLED` status flag is set.

## Errors Raised In Output Handlers

If a non-fatal error is raised in an output handler the program continues execution.

If the non-fatal error is raised in a handler invoked by ob_flush(), ob_end_flush() or ob_get_flush(), the buffer flushes certain data depending on the return value of the handler. If the handler returns `false` the buffer and the error message are flushed. If the returns anything else the handler return value is flushed but not the error message.

> Hinweis: If a handler returns `false` its `PHP_OUTPUT_HANDLER_DISABLED` status flag is set.

If a fatal error is raised in an output handler the program terminates and the handler is invoked by the shutdown process after which the error message is flushed.

If the fatal error is raised in a handler invoked by ob_flush(), ob_end_flush() or ob_get_flush(), the contents of the buffers are flushed before the error message.

If a fatal error is raised in an output handler during shutdown the program terminates without flushing the buffer or the error message.

## Output In Output Handlers

In specific circumstances, output produced in the handler is flushed along with the contents of the buffer. This output is not appended to the buffer and is not part of the string returned by ob_get_flush().

During flush operations (calling ob_flush(), ob_end_flush(), ob_get_flush() and during shutdown) if the return value of a handler is `false` the contents of the buffer are flushed followed by the output. If the handler is not invoked during shutdown the handler throwing an exception or exit() being called results in the same behavior.

> Hinweis: If a handler returns `false` its `PHP_OUTPUT_HANDLER_DISABLED` status flag is set.

## Output Handler Status Flags

The handler status flags of the buffer's `flags` bitmask are set every time to the output handler is invoked and are part of the `flags` returned by ob_get_status(). If the handler successfully executes and does not return `false`, `PHP_OUTPUT_HANDLER_STARTED` and `PHP_OUTPUT_HANDLER_PROCESSED` is set. If the handler returns `false` or throws an exception while executing, `PHP_OUTPUT_HANDLER_STARTED` and `PHP_OUTPUT_HANDLER_DISABLED` is set.

> Hinweis: If the `PHP_OUTPUT_HANDLER_DISABLED` of a handler is set, the handler will not be invoked by calling ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() or during PHP's shutdown process. Prior to PHP 8.4.0, this flag had no effect when calling ob_clean() or ob_flush().

# Beispiele

## Inhaltsverzeichnis

- Einsatzgrundlagen
- Verwendung des URL-Rewriters

## Einsatzgrundlagen

Beispiel #1 Output-Control-Beispiel

    <?php

    ob_start();
    echo "Hello\n";

    setcookie("cookiename", "cookiedata");

    ob_end_flush();

    ?>

Im obigen Beispiel wird die Ausgabe der echo solange im Ausgabepuffer zwischengespeichert, bis die Funktion ob_end_flush() aufgerufen wird. In der Zwischenzeit speichert der Aufruf von setcookie() erfolgreich einen Cookie, ohne einen Fehler zu erzeugen. (Normalerweise können keine Header an den Browser mehr gesendet werden, wenn schon Daten ausgegeben wurden.)

## Verwendung des URL-Rewriters

Von PHP 7.1.0 an verwenden output_add_rewrite_var() und output_reset_rewrite_vars() einen eigenen Ausgabepuffer, d. h. der trans sid Ausgabepuffer wird von diesen Funktionen nicht mehr verwendet.

Beispiel #1 URL-Rewriter-Beispiel

    <?php
    // Dieser Code funktioniert mit PHP 7.1.0, 7.0.10, 5.6.25 und höher.

    // HTTP_HOST ist der Standard-Zielhost. Wir setzen ihn händisch, damit das
    // Beispiel funktioniert.
    $_SERVER['HTTP_HOST'] = 'php.net';

    // Der URL-Rewriter soll nur form und a=href umschreiben.
    // Elemente können durch tag_name=url_attr angegeben werden,
    // z. B. img=src,iframe=src
    // Zwischen diesen Angaben sind keine Leerzeichen erlaubt.
    // Das Form-Element ist besonders, da ihm ein verstecktes Eingabefeld
    // hinzugefügt wird.
    ini_set('url_rewriter.tags','a=href,form=');
    var_dump(ini_get('url_rewriter.tags'));

    // Dies wird zu URL und dem Form-Element hinzugefügt
    output_add_rewrite_var('test', 'value');
    ?>
    <a href="//php.net/index.php?bug=1234">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post">
     <input type="text" name="title" />
    </form>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    <a href="//php.net/?bug=1234&test=value">bug1234</a>
    <form action="https://php.net/?bug=1234&edit=1" method="post"><input type="hidden" name="test" value="value" />
     <input type="text" name="title" />
    </form>

Von PHP 7.1.0 haben die URL-Rewriter-Funktionen eigene INI Einstellungen: url_rewriter.tags und url_rewriter.hosts.

# Output-Control-Funktionen

# Siehe auch

Siehe auch header() und setcookie().

# flush

(PHP 4, PHP 5, PHP 7, PHP 8)

flush — Leert (sendet) den System-Ausgabepuffer

### Beschreibung

function flush(): void

Leert die Ausgabepuffer des PHP-Systems und des von PHP verwendeten Backends (z. B. CGI, Webserver). In einer Kommandozeilenumgebung versucht flush() nur den Inhalt der Puffer zu leeren, während in einem webbasierten Kontext auch die Header geleert werden.

> Hinweis: flush() ist möglicherweise nicht in der Lage, das Pufferverhalten des Webservers zu beeinflussen und hat keine Auswirkungen auf die clientseitige Pufferung im Browser.

> Hinweis: Diese Funktion hat keine Auswirkungen benutzerdefinierte Ausgabe-Handler, also z. B. solche, die durch ob_start() oder output_add_rewrite_var() gestartet werden.

Warnung

flush() kann Ausgabe-Handler stören, die Header in einem Web-Kontext setzen und senden (z. B. ob_gzhandler()), indem sie Header senden, bevor diese Handler dies tun können.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Header können nun auch im FastCGI-Modus ohne Body geleert werden.

### Siehe auch

- ob_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers
- ob_clean() - Löscht den Inhalt des aktiven Ausgabepuffer
- ob_end_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer
- ob_end_clean() - Löscht den Inhalt des aktiven Ausgabepuffers und deaktiviert ihn

# ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_clean — Löscht den Inhalt des aktiven Ausgabepuffer

### Beschreibung

function ob_clean(): bool

Diese Funktion ruft den Ausgabe-Handler auf (mit dem Flag `PHP_OUTPUT_HANDLER_CLEAN`), verwirft dessen Rückgabewert und bereinigt (löscht) den Inhalt des aktiven Ausgabepuffers.

Im Gegensatz zu ob_end_clean() und ob_get_clean() deaktiviert diese Funktion den aktiven Ausgangspuffer nicht.

Wenn es keinen aktiven Ausgabepuffer gibt, der mit dem Flag `PHP_OUTPUT_HANDLER_CLEANABLE` gestartet wurde, schlägt ob_clean() fehl.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn die Funktion fehlschlägt, erzeugt sie eine `E_NOTICE`-Meldung.

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_get_contents() - Liefert den Inhalt des Ausgabepuffers
- ob_end_clean() - Löscht den Inhalt des aktiven Ausgabepuffers und deaktiviert ihn
- ob_get_clean() - Get the contents of the active output buffer and turn it off
- ob_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers

# ob_end_clean

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_clean — Löscht den Inhalt des aktiven Ausgabepuffers und deaktiviert ihn

### Beschreibung

function ob_end_clean(): bool

Diese Funktion ruft den Ausgabe-Handler auf (mit den Flags `PHP_OUTPUT_HANDLER_CLEAN` und `PHP_OUTPUT_HANDLER_FINAL`), verwirft dessen Rückgabewert, verwirft den Inhalt des aktiven Ausgabepuffers und deaktiviert den aktiven Ausgabepuffer.

Wenn es keinen aktiven Ausgabepuffer gibt, der mit dem Flag `PHP_OUTPUT_HANDLER_REMOVABLE` gestartet wurde, schlägt ob_end_clean() fehl.

ob_end_clean() verwirft den Inhalt des aktiven Ausgabepuffers, auch wenn er ohne das Flag `PHP_OUTPUT_HANDLER_CLEANABLE` gestartet wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn die Funktion fehlschlägt, erzeugt sie eine `E_NOTICE`-Meldung.

### Beispiele

Das folgende Beispiel zeigt eine einfache Möglichkeit, den Inhalt des aktiven Ausgabepuffers loszuwerden:

Beispiel #1 ob_end_clean()-Beispiel

    <?php
    ob_start();
    echo 'Text der nicht ausgegeben wird.';
    ob_end_clean();
    ?>

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_get_contents() - Liefert den Inhalt des Ausgabepuffers
- ob_clean() - Löscht den Inhalt des aktiven Ausgabepuffer
- ob_get_clean() - Get the contents of the active output buffer and turn it off
- ob_end_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer

# ob_end_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_flush — Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer

### Beschreibung

function ob_end_flush(): bool

Diese Funktion ruft den Ausgabe-Handler auf (mit dem Flag `PHP_OUTPUT_HANDLER_FINAL`), leert (sendet) seinen Rückgabewert, verwirft den Inhalt des aktiven Ausgabepuffers und deaktiviert den aktiven Ausgabepuffer.

Wenn es keinen aktiven Ausgabepuffer gibt, der mit dem Flag `PHP_OUTPUT_HANDLER_REMOVABLE` gestartet wurde, schlägt ob_end_flush() fehl.

ob_end_flush() leert (sendet) den Rückgabewert des Ausgabe-Handlers, auch wenn der aktive Ausgabepuffer ohne das Flag `PHP_OUTPUT_HANDLER_FLUSHABLE` gestartet wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn die Funktion fehlschlägt, erzeugt sie eine `E_NOTICE`-Meldung.

### Beispiele

Beispiel #1 ob_end_flush()-Beispiel

Das folgende Beispiel zeigt eine einfache Möglichkeit, alle Ausgabepuffer zu leeren und zu beenden:

    <?php
      while (@ob_end_flush());
    ?>

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_get_contents() - Liefert den Inhalt des Ausgabepuffers
- ob_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers
- ob_get_flush() - Flush (send) the return value of the active output handler, return the contents of the active output buffer and turn it off
- ob_end_clean() - Löscht den Inhalt des aktiven Ausgabepuffers und deaktiviert ihn

# ob_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flush — Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers

### Beschreibung

function ob_flush(): bool

Diese Funktion ruft den Ausgabe-Handler auf (mit dem Flag `PHP_OUTPUT_HANDLER_FLUSH`), leert (sendet) seinen Rückgabewert und verwirft den Inhalt des aktiven Ausgabepuffers.

Im Gegensatz zu ob_end_flush() und ob_get_flush() deaktiviert diese Funktion den aktiven Ausgangspuffer nicht.

Wenn es keinen aktiven Ausgabepuffer gibt, der mit dem Flag `PHP_OUTPUT_HANDLER_FLUSHABLE` gestartet wurde, schlägt ob_flush() fehl.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn die Funktion fehlschlägt, erzeugt sie eine `E_NOTICE`-Meldung.

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_get_contents() - Liefert den Inhalt des Ausgabepuffers
- ob_end_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer
- ob_get_flush() - Flush (send) the return value of the active output handler, return the contents of the active output buffer and turn it off
- ob_clean() - Löscht den Inhalt des aktiven Ausgabepuffer

# ob_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_clean — Get the contents of the active output buffer and turn it off

### Beschreibung

function ob_get_clean(): string|false

This function calls the output handler (with the `PHP_OUTPUT_HANDLER_CLEAN` and `PHP_OUTPUT_HANDLER_FINAL` flags), discards it's return value, returns the contents of the active output buffer and turns off the active output buffer.

ob_get_clean() will fail without an active output buffer started with the `PHP_OUTPUT_HANDLER_REMOVABLE` flag.

ob_get_clean() will discard the contents of the active output buffer even if it was started without the `PHP_OUTPUT_HANDLER_CLEANABLE` flag.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the contents of the active output buffer on success or `false` on failure.

Achtung

ob_get_clean() will return false but will not generate an `E_NOTICE` if there is no active output buffer.

### Fehler/Exceptions

If the function fails it generates an `E_NOTICE`.

### Beispiele

Beispiel #1 A simple ob_get_clean() example

    <?php

    ob_start();

    echo "Hello World";

    $out = ob_get_clean();
    $out = strtolower($out);

    var_dump($out);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(11) "hello world"

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_get_contents() - Liefert den Inhalt des Ausgabepuffers
- ob_clean() - Löscht den Inhalt des aktiven Ausgabepuffer
- ob_end_clean() - Löscht den Inhalt des aktiven Ausgabepuffers und deaktiviert ihn
- ob_get_flush() - Flush (send) the return value of the active output handler, return the contents of the active output buffer and turn it off

# ob_get_contents

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_get_contents — Liefert den Inhalt des Ausgabepuffers

### Beschreibung

function ob_get_contents(): string|false

Gibt den Inhalt des Ausgabepuffers ohne Löschung zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

ob_get_contents() gibt den Inhalt des Ausgabepuffers zurück oder `false`, wenn die Ausgabepufferung nicht aktiv ist.

### Beispiele

Beispiel #1 Ein einfaches ob_get_contents()-Beispiel

    <?php

    ob_start();

    echo "Hallo ";

    $out1 = ob_get_contents();

    echo "Welt";

    $out2 = ob_get_contents();

    ob_end_clean();

    var_dump($out1, $out2);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(6) "Hallo "
    string(11) "Hallo Welt"

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_get_length() - Return the length of the output buffer

# ob_get_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flush — Flush (send) the return value of the active output handler, return the contents of the active output buffer and turn it off

### Beschreibung

function ob_get_flush(): string|false

This function calls the output handler (with the `PHP_OUTPUT_HANDLER_FINAL` flag), flushes (sends) it's return value, returns the contents of the active output buffer and turns off the active output buffer.

ob_get_flush() will fail without an active output buffer started with the `PHP_OUTPUT_HANDLER_REMOVABLE` flag.

ob_get_flush() will flush (send) the return value of the output handler even if the active output buffer was started without the `PHP_OUTPUT_HANDLER_FLUSHABLE` flag.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the contents of the active output buffer on success or `false` on failure.

### Fehler/Exceptions

If the function fails it generates an `E_NOTICE`.

### Beispiele

Beispiel #1 ob_get_flush() example

    <?php
    //using output_buffering=On
    print_r(ob_list_handlers());

    //save buffer in a file
    $buffer = ob_get_flush();
    file_put_contents('buffer.txt', $buffer);

    print_r(ob_list_handlers());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => default output handler
    )
    Array
    (
    )

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_get_contents() - Liefert den Inhalt des Ausgabepuffers
- ob_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers
- ob_end_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer
- ob_get_clean() - Get the contents of the active output buffer and turn it off

# ob_get_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_length — Return the length of the output buffer

### Beschreibung

function ob_get_length(): int|false

This will return the length of the contents in the output buffer, in bytes.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the length of the output buffer contents, in bytes, or `false` if no buffering is active.

### Beispiele

Beispiel #1 A simple ob_get_length() example

    <?php

    ob_start();

    echo "Hello ";

    $len1 = ob_get_length();

    echo "World";

    $len2 = ob_get_length();

    ob_end_clean();

    echo $len1 . ", " . $len2;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    6, 11

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_get_contents() - Liefert den Inhalt des Ausgabepuffers

# ob_get_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_level — Anzahl der aktiven Ausgabepuffer

### Beschreibung

function ob_get_level(): int

ob_get_level() liefert die Anzahl der zur Zeit gleichzeitig (übereinanderliegend) aktiven Ausgabepuffer oder 0, wenn keine Ausgabepufferung genutzt wird.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahle der aktiven Ausgabepuffer zurück. Wenn keine Ausgabepufferung aktiv ist, wird 0 zurückgegeben.

Achtung

Der Wert für identische Ebenen ist zwischen ob_get_level() und ob_get_status() um eins versetzt. Für ob_get_level() ist die erste Stufe `1`, während für ob_get_status() die erste Stufe `0` ist.

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_get_status() - Get status of output buffers
- ob_get_contents() - Liefert den Inhalt des Ausgabepuffers

# ob_get_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_status — Get status of output buffers

### Beschreibung

function ob_get_status(bool `$full_status` = `false`): array

ob_get_status() returns status information on either the top level output buffer or all active output buffer levels if `full_status` is set to `true`.

### Parameter-Liste

`full_status`

  `true` to return all active output buffer levels. If `false` or not set, only the top level output buffer is returned.

### Rückgabewerte

If `full_status` is omitted or `false` a simple array holding status information on the active output level is returned.

If `full_status` is `true` an array with one element for each active output buffer level is returned. The output level is used as key of the top level array and each array element itself is another array holding status information on one active output level.

An empty array is returned if output buffering is not turned on.

ob_get_status() return array elements
Key | Value
--- | ---
name | Name of active output handler (see the return values of ob_list_handlers() for details)
type | `0` (internal handler) or `1` (user supplied handler)
flags | Bitmask of flags set by ob_start(), the type of output handler (see above) and the status of the buffering process ( `PHP_OUTPUT_HANDLER_*` constants). If the handler successfully processed the buffer and did not return `false`, `PHP_OUTPUT_HANDLER_STARTED` and `PHP_OUTPUT_HANDLER_PROCESSED` will be set. If the handler failed while processing the buffer or returned `false`, `PHP_OUTPUT_HANDLER_STARTED` and `PHP_OUTPUT_HANDLER_DISABLED` will be set.
level | Output nesting level (zero based). Note that the value returned for the same level by ob_get_level() is off by one. The first level is `0` for ob_get_status(), and `1` for ob_get_level().
chunk_size | Chunk size in bytes. Set by ob_start() or output_buffering is enabled and its value is set to a positive integer
buffer_size | Output buffer size in bytes
buffer_used | Size of data in output buffer in bytes (the same as the integer return value of ob_get_length())

### Beispiele

Beispiel #1 Array returned when `full_status` is `false`

    Array
    (
        [name] => URL-Rewriter
        [type] => 0
        [flags] => 112
        [level] => 2
        [chunk_size] => 0
        [buffer_size] => 16384
        [buffer_used] => 1024
    )

Beispiel #2 Array returned when `full_status` is `true`

    Array
    (
        [0] => Array
            (
                [name] => default output handler
                [type] => 0
                [flags] => 112
                [level] => 1
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 2048
            )

        [1] => Array
            (
                [name] => URL-Rewriter
                [type] => 0
                [flags] => 112
                [level] => 2
                [chunk_size] => 0
                [buffer_size] => 16384
                [buffer_used] => 1024
            )

    )

### Siehe auch

- ob_get_level() - Anzahl der aktiven Ausgabepuffer
- ob_list_handlers() - List all output handlers in use
- ob_get_length() - Return the length of the output buffer
- ob_start() - Ausgabepufferung aktivieren

# ob_implicit_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_implicit_flush — Schaltet die implizite Ausgabe ein bzw. aus

### Beschreibung

function ob_implicit_flush(bool `$enable` = `true`): void

ob_implicit_flush() schaltet die implizite Ausgabe an oder aus. Die implizite Pufferausgabe erzeugt eine Ausgabe nach jedem Codeblock, der zu einer Ausgabe führt, sodass keine expliziten Aufrufe von flush() mehr erforderlich sind.

> Hinweis: Wenn leere Zeichenketten ausgegeben oder Kopfzeilen gesendet werden, wird dies nicht als Ausgabe betrachtet und führt auch nicht zu einer Ausgabeoperation.

> Hinweis: Diese Funktion hat keine Auswirkungen benutzerdefinierte Ausgabe-Handler, also z. B. solche, die durch ob_start() oder output_add_rewrite_var() gestartet werden.

### Parameter-Liste

`enable`

  `true` schaltet die implizite Ausgabe ein, `false` schaltet sie aus.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `enable` erwartet nun einen bool-Wert; vorher wurde ein int erwartet.

### Siehe auch

- flush() - Leert (sendet) den System-Ausgabepuffer
- ob_start() - Ausgabepufferung aktivieren
- ob_end_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer

# ob_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlers — List all output handlers in use

### Beschreibung

function ob_list_handlers(): array

Lists all output handlers in use.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

This will return an array with the output handlers in use (if any).

If output_buffering is enabled and no output_handler is set, or no callback or `null` was passed to ob_start(), `"default output handler"` is returned. Enabling output_buffering and setting an output_handler is equivalent to passing an internal (built-in) function to ob_start().

If a callable was passed to ob_start(), the fully qualified name of the callable is returned. If the callable is an object implementing __invoke(), the fully qualified name of the object's __invoke() method is returned. If the callable is a Closure, `"Closure::__invoke"` is returned.

### Beispiele

Beispiel #1 ob_list_handlers() example

    <?php
    // using output_buffering=On, no output_handler set
    var_dump(ob_list_handlers());
    ob_end_flush();

    // no callback or null
    ob_start();
    var_dump(ob_list_handlers());
    ob_end_flush();

    // anonymous function
    ob_start(function($string) { return $string; });
    var_dump(ob_list_handlers());
    ob_end_flush();

    // arrow function
    ob_start(fn($string) => $string);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // first class callable
    $firstClassCallable = userDefinedFunction(...);

    ob_start([$firstClassCallable, '__invoke']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // internal (built-in) function
    ob_start('print_r');
    var_dump(ob_list_handlers());
    ob_end_flush();

    // user-defined function
    function userDefinedFunction($string, $flags) { return $string; };

    ob_start('userDefinedFunction');
    var_dump(ob_list_handlers());
    ob_end_flush();

    class MyClass {
        public static function staticHandle($string) {
            return $string;
        }

        public static function handle($string) {
            return $string;
        }

        public function __invoke($string) {
            return $string;
        }
    }

    // class and static method
    ob_start(['MyClass','staticHandle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // object and non-static method
    ob_start([new MyClass,'handle']);
    var_dump(ob_list_handlers());
    ob_end_flush();

    // invokable object
    ob_start(new MyClass);
    var_dump(ob_list_handlers());
    ob_end_flush();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(22) "default output handler"
    }
    array(1) {
      [0]=>
      string(7) "print_r"
    }
    array(1) {
      [0]=>
      string(19) "userDefinedFunction"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(17) "Closure::__invoke"
    }
    array(1) {
      [0]=>
      string(21) "MyClass::staticHandle"
    }
    array(1) {
      [0]=>
      string(15) "MyClass::handle"
    }
    array(1) {
      [0]=>
      string(17) "MyClass::__invoke"
    }

### Siehe auch

- ob_end_clean() - Löscht den Inhalt des aktiven Ausgabepuffers und deaktiviert ihn
- ob_end_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer
- ob_get_flush() - Flush (send) the return value of the active output handler, return the contents of the active output buffer and turn it off
- ob_start() - Ausgabepufferung aktivieren

# ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — Ausgabepufferung aktivieren

### Beschreibung

function ob_start(?callable `$callback` = `null`, int `$chunk_size` = 0, int `$flags` = `PHP_OUTPUT_HANDLER_STDFLAGS`): bool

Diese Funktion aktiviert die Ausgabepufferung. Während die Ausgabepufferung aktiv ist, werden Skriptausgaben nicht direkt an den Client weitergegeben, sondern in einem internen Puffer gesammelt. Welche Ausgaben genau betroffen sind, ist unter What Output Is Buffered? beschrieben.

Ausgabepuffer können verschachtelt werden, d. h. ob_start() kann erneut aufgerufen werden, während bereits ein anderer Puffer aktiv ist. Sind mehrere Ausgabepuffer aktiv, wird die Ausgabe in der Reihenfolge der Verschachtelung durch jeden dieser Puffer gefiltert. Siehe Nesting Output Buffers für weitere Einzelheiten.

Eine ausführliche Beschreibung der Ausgabepuffer ist unter User-Level Output Buffers zu finden.

### Parameter-Liste

`callback`

  Optional kann ein `callback`-Callable angegeben werden. Dieses kann auch durch Übergabe von `null` umgangen werden.

  `callback` wird aufgerufen, wenn der Ausgabepuffer geleert (gesendet), bereinigt oder am Ende des Skripts geleert wird.

  Die Signatur von `callback` ist wie folgt:

  function handler(string `$buffer`, int `$phase` = ?): string
  `buffer`
    Der Inhalt des Ausgabepuffers.
  `phase`
    Eine Bitmaske von `PHP_OUTPUT_HANDLER_*`-Konstanten . Weitere Einzelheiten sind unter Flags Passed To Output Handlers zu finden.

  Wenn `callback` `false` zurückgibt, wird der Inhalt des Puffers zurückgegeben. Weitere Einzelheiten sind unter Output Handler Return Values zu finden.

  Warnung

  Wenn eine der folgenden Funktionen innerhalb eines Ausgabe-Handlers aufgerufen wird, führt dies zu einem schwerwiegenden Fehler: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

  Weitere Einzelheiten zu `callback`s (Ausgabe-Handler) sind unter Output Handlers und Working With Output Handlers zu finden.

`chunk_size`

  Wird der optionale Parameter `chunk_size` übergeben, dann wird der Puffer nach jedem Codeblock geleert, der zu einer Ausgabe führt, durch die der Puffer die Größe von `chunk_size` erreicht oder überschreitet. Der Vorgabewert `0` bedeutet, dass die gesamte Ausgabe gepuffert wird, bis der Puffer ausgeschaltet wird. Weitere Einzelheiten sind unter Buffer Size zu finden.

`flags`

  Beim Parameter `flags` handelt es sich um eine Bitmaske, die die Operationen steuert, die mit dem Ausgabepuffer durchgeführt werden können. Die Vorgabe ist, zu erlauben, dass Ausgabepuffer bereinigt, geleert und entfernt werden dürfen, was ausdrücklich mit den Flags für die Steuerung des Ausgabepuffers . eingestellt werden kann. Weitere Einzelheiten sind unter Operations Allowed On Buffers zu finden.

  Jedes Flag steuert den Zugriff auf einen Satz von Funktionen, wie im Folgenden beschrieben:

  Konstante | Funktionen
  --- | ---
  `PHP_OUTPUT_HANDLER_CLEANABLE` | ob_clean()
  `PHP_OUTPUT_HANDLER_FLUSHABLE` | ob_flush()
  `PHP_OUTPUT_HANDLER_REMOVABLE` | ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush()

  > Hinweis: Vor PHP 8.4.0 konnte der Parameter flags auch die Statusflags des Ausgabe-Handlers setzen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Beispiel einer benutzerdefinierten Callback-Funktion

    <?php

    function callback($buffer)
    {
      // ersetzt alle Äpfel mit Birnen
      return (str_replace("Äpfel", "Birnen", $buffer));
    }

    ob_start("callback");

    ?>
    <html>
    <body>
    <p>Das ist wie Äpfel mit Birnen zu vergleichen.</p>
    </body>
    </html>
    <?php

    ob_end_flush();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    <html>
    <body>
    <p>Das ist wie Birnen mit Birnen zu vergleichen.</p>
    </body>
    </html>

Beispiel #2 Erzeugen eines nicht löschbaren Ausgabepuffers

    <?php

    ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

    ?>

### Siehe auch

- ob_get_contents() - Liefert den Inhalt des Ausgabepuffers
- ob_end_clean() - Löscht den Inhalt des aktiven Ausgabepuffers und deaktiviert ihn
- ob_end_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer
- ob_implicit_flush() - Schaltet die implizite Ausgabe ein bzw. aus
- ob_gzhandler() - ob_start callback function to gzip output buffer
- ob_iconv_handler() - Konvertiert Zeichensatzkodierung als Ausgabepuffer-Handler (output buffer handler)
- mb_output_handler() - Callback function converts character encoding in output buffer
- ob_tidyhandler() - ob_start callback function to repair the buffer

# output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_add_rewrite_var — Fügt Werte zum URL-Rewriter hinzu

### Beschreibung

function output_add_rewrite_var(string `$name`, string `$value`): bool

Diese Funktion startet den `"URL-Rewriter"`-Ausgabepuffer-Handler, wenn dieser nicht aktiv ist, speichert die Parameter `name` und `value` und schreibt die URLs und Formulare basierend auf den entsprechenden INI-Einstellungen neu, wenn der Puffer geleert wird. Nachfolgende Aufrufe dieser Funktion speichern alle zusätzlichen Name/Wert-Paare, bis der Handler beendet wird.

Wenn der Ausgabepuffer geleert wird (durch Aufruf von ob_flush(), ob_end_flush(), ob_get_flush() oder am Ende des Skripts), fügt der `"URL-Rewriter"`-Handler die Name/Wert-Paare entsprechend den Werten der Konfigurationsanweisungen url_rewriter.tags und url_rewriter.hosts als Abfrageparameter zu URLs in Attributen von HTML-Tags und als versteckte Felder zu Formularen hinzu.

Jedes Name/Wert-Paar, das dem `"URL-Rewriter"`-Handler hinzugefügt wird, wird zu den URLs und/oder Formularen hinzugefügt, auch wenn dies zu doppelten URL-Abfrageparametern oder Elementen mit denselben Namensattributen führt.

> Hinweis: Wenn der `"URL-Rewriter"`-Handler deaktiviert wird, kann er nicht mehr gestartet werden.

Warnung

Vor PHP 8.4.0 wurden die umzuschreibenden Hosts in session.trans_sid_hosts gesetzt statt in url_rewriter.hosts.

### Parameter-Liste

`name`

  Der Variablenname.

`value`

  Der Variablenwert.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
7.1.0 | Seit PHP 7.1.0 verwendet die Funktion einen eigenen Ausgabepuffer; url_rewriter.tags wird nun nur noch für die Ausgabefunktionen verwendet und die Direktive url_rewriter.hosts wurde hinzugefügt. Vor PHP 7.1.0 teilten sich die Rewrite-Variablen, die mit output_add_rewrite_var() gesetzt wurden, einen Ausgabepuffer mit der transparenten Session-ID-Unterstützung (siehe session.trans_sid_tags).

### Beispiele

Beispiel #1 output_add_rewrite_var()-Beispiel

    <?php
    ini_set('url_rewriter.tags', 'a=href,form=');

    output_add_rewrite_var('var', 'value');

    // ein paar Links
    echo '<a href="file.php">link</a>
    <a href="http://example.com">link2</a>';

    // ein Formular
    echo '<form action="script.php" method="post">
    <input type="text" name="var2" />
    </form>';

    print_r(ob_list_handlers());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    <a href="file.php?var=value">link</a>
    <a href="http://example.com">link2</a>

    <form action="script.php" method="post">
    <input type="hidden" name="var" value="value" />
    <input type="text" name="var2" />
    </form>

    Array
    (
        [0] => URL-Rewriter
    )

### Siehe auch

- output_reset_rewrite_vars() - Reset URL rewriter values
- ob_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers
- ob_list_handlers() - List all output handlers in use
- url_rewriter.tags
- url_rewriter.hosts

# output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_reset_rewrite_vars — Reset URL rewriter values

### Beschreibung

function output_reset_rewrite_vars(): bool

This function removes all rewrite variables previously set by the output_add_rewrite_var() function.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
7.1.0 | Before PHP 7.1.0, rewrite vars set by output_add_rewrite_var() use the same Session module trans sid output buffer. Since PHP 7.1.0, dedicated output buffer is used and output_reset_rewrite_vars() only removes rewrite vars defined by output_add_rewrite_var().

### Beispiele

Beispiel #1 output_reset_rewrite_vars() example

    <?php
    ini_set('url_rewriter.tags', 'a=href');

    output_add_rewrite_var('var', 'value');

    echo '<a href="file.php">link</a>';
    ob_flush();

    output_reset_rewrite_vars();
    echo '<a href="file.php">link</a>';
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    <a href="file.php?var=value">link</a>
    <a href="file.php">link</a>

### Siehe auch

- output_add_rewrite_var() - Fügt Werte zum URL-Rewriter hinzu
- ob_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers
- ob_list_handlers() - List all output handlers in use
- url_rewriter.tags
- url_rewriter.hosts
- session.trans_sid_tags
- session.trans_sid_hosts

## Inhaltsverzeichnis

- flush — Leert (sendet) den System-Ausgabepuffer
- ob_clean — Löscht den Inhalt des aktiven Ausgabepuffer
- ob_end_clean — Löscht den Inhalt des aktiven Ausgabepuffers und deaktiviert ihn
- ob_end_flush — Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer
- ob_flush — Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers
- ob_get_clean — Get the contents of the active output buffer and turn it off
- ob_get_contents — Liefert den Inhalt des Ausgabepuffers
- ob_get_flush — Flush (send) the return value of the active output handler, return the contents of the active output buffer and turn it off
- ob_get_length — Return the length of the output buffer
- ob_get_level — Anzahl der aktiven Ausgabepuffer
- ob_get_status — Get status of output buffers
- ob_implicit_flush — Schaltet die implizite Ausgabe ein bzw. aus
- ob_list_handlers — List all output handlers in use
- ob_start — Ausgabepufferung aktivieren
- output_add_rewrite_var — Fügt Werte zum URL-Rewriter hinzu
- output_reset_rewrite_vars — Reset URL rewriter values

- Installation/Konfiguration
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Output Buffering
- Flushing System Buffers
- User-Level Output Buffers
  - What Output Is Buffered?
  - Nesting Output Buffers
  - Buffer Size
  - Operations Allowed On Buffers
  - Output Handlers
  - Working With Output Handlers
  - Flags Passed To Output Handlers
  - Output Handler Return Values
- Beispiele
  - Einsatzgrundlagen
  - Verwendung des URL-Rewriters
- Output-Control-Funktionen
  - flush — Leert (sendet) den System-Ausgabepuffer
  - ob_clean — Löscht den Inhalt des aktiven Ausgabepuffer
  - ob_end_clean — Löscht den Inhalt des aktiven Ausgabepuffers und deaktiviert ihn
  - ob_end_flush — Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer
  - ob_flush — Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers
  - ob_get_clean — Get the contents of the active output buffer and turn it off
  - ob_get_contents — Liefert den Inhalt des Ausgabepuffers
  - ob_get_flush — Flush (send) the return value of the active output handler, return the contents of the active output buffer and turn it off
  - ob_get_length — Return the length of the output buffer
  - ob_get_level — Anzahl der aktiven Ausgabepuffer
  - ob_get_status — Get status of output buffers
  - ob_implicit_flush — Schaltet die implizite Ausgabe ein bzw. aus
  - ob_list_handlers — List all output handlers in use
  - ob_start — Ausgabepufferung aktivieren
  - output_add_rewrite_var — Fügt Werte zum URL-Rewriter hinzu
  - output_reset_rewrite_vars — Reset URL rewriter values

# PHP-Optionen und -Informationen

# Einführung

Diese Funktionen ermöglichen Ihnen, eine Menge an nützlichen Informationen über PHP selbst zu erhalten, z. B. die Konfiguration zur Laufzeit, geladene Erweiterungen, Angaben zur Version und vieles mehr. Sie finden hier auch Funktionen, die es Ihnen ermöglichen, Optionen für Ihr laufendes PHP zu setzen. Die vermutlich bekannteste Funktion von PHP - phpinfo() - finden Sie hier.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Laufzeit-Konfiguration

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Konfigurationsoptionen für PHP-Optionen/Info
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
assert.active | "1" | `INI_ALL` | Seit PHP 8.3.0 veraltet.
assert.bail | "0" | `INI_ALL` | Seit PHP 8.3.0 veraltet.
assert.warning | "1" | `INI_ALL` | Seit PHP 8.3.0 veraltet.
assert.callback | NULL | `INI_ALL` | Seit PHP 8.3.0 veraltet.
assert.quiet_eval | "0" | `INI_ALL` | Entfernt in PHP 8.0.0
assert.exception | "1" | `INI_ALL` | Vor PHP 8.0.0 war der Standardwert `"0"` Seit PHP 8.3.0 veraltet.
enable_dl | "1" | `INI_SYSTEM` | Dieses veraltete Feature wird in der Zukunft sicherlich entfernt.
max_execution_time | "30" | `INI_ALL` |
max_input_time | "-1" | `INI_PERDIR` |
max_input_nesting_level | "64" | `INI_PERDIR` |
max_input_vars | 1000 | `INI_PERDIR` |
zend.enable_gc | "1" | `INI_ALL` |
zend.max_allowed_stack_size | "0" | `INI_SYSTEM` | Verfügbar seit PHP 8.3.0.
zend.reserved_stack_size | "0" | `INI_SYSTEM` | Verfügbar seit PHP 8.3.0.
fiber.stack_size |  | `INI_ALL` | Verfügbar seit PHP 8.1.0.

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`assert.active` bool

  Aktiviert die assert()-Auswertung. Um das Verhalten von assert() zu kontrollieren, sollte stattdessen zend.assertions verwendet werden.

  Warnung

  Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

`assert.bail` bool

  Beendet bei fehlgeschlagener Assertion die Ausführung eines Skripts.

  Warnung

  Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

`assert.warning` bool

  Erzeugt bei jeder fehlgeschlagenen Assertion eine PHP-Warnung.

  Warnung

  Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

`assert.callback` string

  Eine benutzerdefinierte Funktion, die bei fehlgeschlagenen Assertions ausgeführt wird.

  Warnung

  Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

`assert.quiet_eval` bool
  Warnung

  Dieses Feature wurde in PHP 8.0.0 ENTFERNT.

  Verwendet während der Auswertung eines Assertion-Ausdrucks die aktuelle Einstellung von error_reporting(). Ist diese Einstellung aktiviert, werden während der Auswertung keine Fehler angezeigt (implizit error_reporting(0)). Falls deaktiviert, werden Fehler entsprechend der Einstellung von error_reporting() angezeigt.

`assert.exception` bool

  Erzeugt eine AssertionError-Exception für die fehlgeschlagene Assertion.

  Warnung

  Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

`enable_dl` bool

  Mit dieser Direktive kann das dynamische Laden von PHP-Erweiterungen mittels dl() ein- und ausgeschaltet werden.

  Der Hauptgrund, das dynmische Laden abzustellen, sind Sicherheitsüberlegungen. Mit dem dynamischen Laden ist es möglich, alle open_basedir-Einschränkungen zu umgehen. Der Standardwert ist, das dynamische Laden zuzulassen.

`max_execution_time` int

  Legt die maximale Zeit in Sekunden fest, die ein Skript laufen darf, bevor der Parser die Ausführung stoppt. Diese Einstellung hilft zu verhindern, dass schlampig geschriebene Skripte Ihren Server lahmlegen. Der Standardwert für diese Einstellung ist `30` Sekunden. Wird PHP von der Kommandozeile ausgeführt, so ist der Standardwert `0`.

  Auf Nicht-Windows-Systemen beeinhaltet die maximale Ausführungszeit keine Systemaufrufe, Streamoperationen usw. Weitere Details finden Sie bei der Funktion set_time_limit().

  Ihr Webbserver kann andere Timeout-Einstellungen haben, die ebenfalls die PHP-Ausführung unterbrechen können. Apache hat eine `TimeOut`-Direktive und IIS hat eine CGI-Timeout-Funktion. Beide sind als Standardwert auf 300 Sekunden eingestellt. Genauere Informationen finden Sie in der Dokumentation Ihres Webservers.

`max_input_time` int

  Legt die maximale Zeit in Sekunden fest, die ein Skript verbrauchen darf, um Eingabedaten wie POST, GET und Dateiuploads zu verarbeiten. Die Zeitmessung beginnt, sobald PHP auf dem Server aufgerufen wird, und endet, wenn die Ausführung beginnt. Der Standardwert ist `-1`, was bedeutet, dass stattdessen max_execution_time verwendet wird. Der Wert `0` bedeutet kein Zeitlimit.

`max_input_nesting_level` int

  Legt die maximale Verschachtelungtiefe für Eingabevariablen (z. B. $_GET, $_POST) fest.

`max_input_vars` int

  Wie viele Eingabe-Variablen maximal angenommen werden (dieses Limit wird auf die superglobalen $_GET, $_POST und $_COOKIE separat angewandt). Die Verwendung dieser Einstellung verringert die Möglichkeit von Denial-of-Service-Angriffen, die Hash-Kollisionen nutzen. Wenn mehr Eingabe-Variablen gesendet werden, als mit dieser Einstellung erlaubt ist, wird ein Fehler der Stufe `E_WARNING` ausgelöst und weitere Eingabe-Variablen werden nicht angenommen.

`zend.enable_gc` bool

  Aktiviert bzw. deaktiviert die Speicherbereinigung zirkulär abhängiger Referenzen.

`zend.max_allowed_stack_size` int

  Der maximale native Stack-Speicherplatz, die das Betriebssystem dem Programm zugesteht. Der Versuch, mehr zu verbrauchen, führt typischerweise zu einem harten Absturz ohne leicht verfügbare Debugging-Informationen. Um die Fehlersuche zu erleichtern, löst die Engine einen Error aus, bevor es zu dem Absturz kommt (wenn das Programm mehr als zend.max_allowed_stack_size-zend.reserved_stack_size Bytes des Stacks verwendet).

  Rekursive Aufrufe im benutzerdefinierten Code verbrauchen keinen nativen Stack-Speicher. Bei internen Funktionen und magischen Methoden ist dies jedoch der Fall. Eine sehr tiefe Rekursion, die diese Funktionen einbezieht, kann dazu führen, dass der gesamte verfügbare native Stack-Speicher aufgebraucht wird.

  Mögliche Werte für diesen Parameter sind:

  - `0`: Automatische Erkennung des maximalen nativen Stack-Speicherplatzes, den das Betriebssystem für das Programm zulässt. Dies ist die Standardeinstellung. Wenn die Erkennung nicht möglich ist, wird eine bekannte Systemvorgabe verwendet.
  - `-1`: Deaktiviert die Überprüfung der Größe des Stacks in der Engine.
  - Positive Ganzzahl: Eine feste Größe, in Bytes. Wird dieser Wert zu hoch eingestellt, hat dies den gleichen Effekt wie die Deaktivierung der Überprüfung der Stackgröße.

  Da die Größe des Stacks von Fibers durch fiber.stack_size bestimmt wird, wird der Wert dieses Parameters anstelle von zend.max_allowed_stack_size verwendet, wenn die Stack-Nutzung während der Ausführung einer Fiber überprüft wird.

  > Hinweis:

  > Dies hat nichts mit Stack-Pufferüberläufen zu tun und stellt kein Sicherheitsfeature dar.

`zend.reserved_stack_size` int

  Die reservierte Größe des Stacks, in Bytes. Diese wird als Puffer von der maximal erlaubten Größe des Stacks subtrahiert, wenn die Größe des Stacks überprüft wird.

  Mögliche Werte für diesen Parameter sind:

  - Automatische Erkennung einer sinnvollen Größe.
  - Positive Ganzzahl: Eine feste Größe, in Bytes.
`fiber.stack_size` int

  Die native Größe des Stacks, die für jede Fiber zugewiesen wird, in Bytes.

  Bei Systemen mit einer Zeigergröße von weniger als 8 Byte beträgt der Standardwert 1MiB, ansonsten 2MiB.

# Vordefinierte Konstanten

Die aufgelisteten Konstanten stehen immer zur Verfügung, da sie zum Grundbestand von PHP gehören.

Konstanten | Beschreibung
--- | ---
Vordefinierte Konstanten für phpcredits()
`CREDITS_GROUP` (int) | Eine Liste der Kernentwickler
`CREDITS_GENERAL` (int) | Allgemeine Credits: Sprachentwurf und -konzept, PHP-Autoren und@ SAPI-Module.
`CREDITS_SAPI` (int) | Eine Liste der Server-API-Module für PHP und deren Autoren.
`CREDITS_MODULES` (int) | Eine Liste der Erweiterungsmodule für PHP und deren Autoren.
`CREDITS_DOCS` (int) | Die Credits für das Dokumentationsteam.
`CREDITS_FULLPAGE` (int) | Wird üblicherweise in Verbindung mit den anderen Konstanten verwendet. Gibt an, dass eine komplette, eigenständige HTML-Seite ausgegeben wird, die alle Informationen enthält, die mit anderen Konstanten angefordert wurden.
`CREDITS_QA` (int) | Die Credits für das Qualitätssicherungsteam.
`CREDITS_ALL` (int) | Alle Credits. Dies entspricht der Angabe von: `CREDITS_DOCS | CREDITS_GENERAL | CREDITS_GROUP | CREDITS_MODULES | CREDITS_QA | CREDITS_FULLPAGE`. Eine komplette, eigenständige HTML-Seite mit den entsprechenden Tags wird erzeugt und ausgegeben. Das ist der Standardwert.

Konstanten | Beschreibung
--- | ---
phpinfo()-Konstanten
`INFO_GENERAL` (int) | Die Konfigurationsangaben, php.ini-Speicherort, Builddatum, Webserver, Betriebssystem und mehr.
`INFO_CREDITS` (int) | PHP-Credits. Siehe auch phpcredits().
`INFO_CONFIGURATION` (int) | Gegenwärtige lokale und Master-Werte für PHP-Einstellungen. Siehe auch ini_get().
`INFO_MODULES` (int) | Geladene Module und ihre entsprechenden Einstellungen.
`INFO_ENVIRONMENT` (int) | Informationen über Umgebungsvariablen, die auch in $_ENV zur Verfügung stehen.
`INFO_VARIABLES` (int) | Zeigt alle vordefinierten Variablen von EGPCS (Environment, GET, POST, Cookie, Server) an.
`INFO_LICENSE` (int) | PHP-Lizenz-Informationen. Siehe auch die » Lizenz-FAQ.
`INFO_ALL` (int) | Zeigt alle oben genannten Einträge. Das ist der Standardwert.

Konstanten | Beschreibung
--- | ---
Konstanten für den INI-Modus
`INI_USER` (int) | Entry can be set in user scripts (like with ini_set()) or in the Windows registry. Entry can be set in .user.ini
`INI_PERDIR` (int) | Entry can be set in php.ini, .htaccess, httpd.conf or .user.ini
`INI_SYSTEM` (int) | Entry can be set in php.ini or httpd.conf
`INI_ALL` (int) | Entry can be set anywhere

Assert-Konstantent; diese Werte werden verwendet, um die Assertion-Optionen in assert_options() anzugeben.

Konstanten | Beschreibung
--- | ---
assert()-Konstanten
`ASSERT_ACTIVE` (int) | Aktiviert die assert()-Auswertung. Warnung Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.
`ASSERT_CALLBACK` (int) | Callback, der bei fehlgeschlagenen Assertions aufgerufen wird. Warnung Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.
`ASSERT_BAIL` (int) | Bricht die Ausführung bei fehlgeschlagenen Assertions ab. Warnung Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.
`ASSERT_EXCEPTION` (int) | Wirft für jede fehlgeschlagene Assertion einen AssertionError Warnung Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.
`ASSERT_WARNING` (int) | Löst eine PHP-Warnung für jede fehlgeschlagene Assertion aus. Warnung Dieses Feature ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.
`ASSERT_QUIET_EVAL` (int) | Deaktiviert `error_reporting` während der Auswertung von Assertion-Ausdrücken. Warnung Dieses Feature wurde in PHP 8.0.0 ENTFERNT.

Die folgenden Konstanten sind nur verfügbar, wenn das Host-Betriebssystem Windows ist; sie liefern unterschiedliche Versionsinformationen, so dass es möglich ist, verschiedene Features zu erkennen, und sie zu verwenden.

Konstanten | Beschreibung
--- | ---
Windows-spezifische Konstanten
`PHP_WINDOWS_VERSION_MAJOR` (int) | Die Hauptversion von Windows, also entweder `4` (NT4/Me/98/95), `5` (XP/2003 R2/2003/2000) oder `6` (Vista/2008/7/8/8.1).
`PHP_WINDOWS_VERSION_MINOR` (int) | Die Nebenversion von Windows, also entweder `0` (Vista/2008/2000/NT4/95), `1` (XP), `2` (2003 R2/2003/XP x64), `10` (98) oder `90` (ME).
`PHP_WINDOWS_VERSION_BUILD` (int) | Die Windows-Buildnummer (beispielsweise ist Windows Vista mit SP1 Build 6001).
`PHP_WINDOWS_VERSION_PLATFORM` (int) | Die Plattform, auf der PHP ausgeführt wird, also `2` unter Windows Vista/XP/2000/NT4 und Server 2008/2003 und `1` unter Windows ME/98/95.
`PHP_WINDOWS_VERSION_SP_MAJOR` (int) | Die Hauptversion des installierten Service-Packs; dieser Wert ist `0`, wenn kein Service-Pack installiert ist. Beispielsweise ist dieser Wert unter Windows XP mit Service-Pack 3 `3`.
`PHP_WINDOWS_VERSION_SP_MINOR` (int) | Die Nebenversion des installierten Service-Packs; dieser Wert ist `0`, wenn kein Service-Pack installiert ist.
`PHP_WINDOWS_VERSION_SUITEMASK` (int) | Die Suitemask ist eine Bitmaske, die angibt, ob verschiedene Windows-Features installiert sind. In der Tabelle weiter unten werden die möglichen Bitfeldwerte angeführt.
`PHP_WINDOWS_VERSION_PRODUCTTYPE` (int) | Diese enthält den Wert, der verwendet wird, um die `PHP_WINDOWS_NT_*`-Konstanten zu bestimmen. Dieser Wert kann eine der `PHP_WINDOWS_NT_*`-Konstanten sein, die den Plattformtyp anzeigen.
`PHP_WINDOWS_NT_DOMAIN_CONTROLLER` (int) | Der Domänen-Controller
`PHP_WINDOWS_NT_SERVER` (int) | Es handelt sich um ein Serversystem (z. B. Server 2008/2003/2000); es ist zu beachten, dass Domänen-Controller als `PHP_WINDOWS_NT_DOMAIN_CONTROLLER` gemeldet werden.
`PHP_WINDOWS_NT_WORKSTATION` (int) | Es handelt sich um ein Arbeitsplatzsystem (z. B. Vista/XP/2000/NT4).

Diese Tabelle listet eine Reihe von Features auf, die unter Verwendung der Bitmaske `PHP_WINDOWS_VERSION_SUITEMASK` geprüft werden können.

Windows Suitemask Bitfelder
Bits | Beschreibung
--- | ---
`0x00000004` | Die Microsoft BackOffice Komponenten sind installiert.
`0x00000400` | Windows Server 2003, Web Edition ist installiert.
`0x00004000` | Windows Server 2003, Compute Cluster Edition ist installiert.
`0x00000080` | Windows Server 2008 Datacenter, Windows Server 2003, Datacenter Edition oder Windows 2000 Datacenter Server ist installiert.
`0x00000002` | Windows Server 2008 Enterprise, Windows Server 2003, Enterprise Edition, Windows 2000 Advanced Server oder Windows NT Server 4.0 Enterprise Edition ist installiert.
`0x00000040` | Windows XP Embedded ist installiert.
`0x00000200` | Windows Vista Home Premium, Windows Vista Home Basic, oder Windows XP Home Edition ist installiert.
`0x00000100` | Remote Desktop wird unterstützt, aber nur eine interaktive Sitzung ist erlaubt. Dieser Wert ist gesetzt, falls das System nicht im Anwendungsserver-Modus läuft.
`0x00000001` | Microsoft Small Business Server war einst auf dem System installiert, wurde aber möglicherweise auf eine andere Windows-Version aktualisiert.
`0x00000020` | Microsoft Small Business Server ist mit der restriktiven Client-Lizenz installiert.
`0x00002000` | Windows Storage Server 2003 R2 oder Windows Storage Server 2003 ist installiert.
`0x00000010` | Terminal-Dienste sind installiert. Dieser Wert ist immer gesetzt. Ist dieser Wert gesetzt, aber `0x00000100` nicht, dann läuft das System im Anwendungsservermodus.
`0x00008000` | Windows Home Server ist installiert.

# PHP-Optionen-/-Informationen-Funktionen

# assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assert — Überprüft eine Assertion (Zusicherung)

### Beschreibung

function assert(mixed `$assertion`, Throwable|string|null `$description` = `null`): bool

assert() ermöglicht es, Expectations (Annahmen) zu definieren: Zusicherungen, die in Entwicklungs- und Testumgebungen wirken, aber so optimiert sind, dass sie in Produktionsumgebungen keinen Mehraufwand verursachen.

Zusicherungen können zur Unterstützung der Fehlersuche verwendet werden. So können sie z. B. für Plausibilitätsprüfungen für Vorbedingungen verwendet werden, die immer `true` sein sollten, und die andernfalls auf Programmierfehler hinweisen. Ein weiterer Anwendungsfall ist, sicherzustellen, dass bestimmte Merkmale wie Funktionen von Erweiterungen oder bestimmte Grenzwerte und Eigenschaften des Systems vorhanden sind.

Da Zusicherungen so konfiguriert werden können, dass sie deaktiviert werden, sollten sie nicht für normale Laufzeitoperationen wie die Überprüfung von Eingabeparametern verwendet werden. Als Faustregel gilt, dass sich der Code auch bei deaktivierter Zusicherungsüberprüfung so verhalten sollte wie erwartet.

assert() prüft, ob die in `assertion` angegebene Annahme zutrifft. Wenn dies nicht der Fall ist und das Ergebnis somit `false` ist, werden die entsprechenden Maßnahmen ergriffen, je nachdem wie assert() konfiguriert wurde.

Das Verhalten von assert() wird durch die folgenden INI-Einstellungen bestimmt:

Konfigurationsoptionen für assert
Name | Standard | Beschreibung | Changelog
--- | --- | --- | ---
zend.assertions | `1` | `1`: erzeugt Code und führt ihn aus (Entwicklungsmodus). `0`: erzeugt Code, aber führt ihn zur Laufzeit nicht aus. `-1`: erzeugt keinen Code (Produktionsmodus). |
assert.active | `true` | Wenn `false`, prüft assert() die Annahme nicht und gibt automatisch `true` zurück. | Seit PHP 8.3.0 veraltet.
assert.callback | `null` | Eine benutzerdefinierte Funktion, die aufgerufen wird, wenn eine Zusicherung fehlschlägt. Sie sollte die folgende Signatur haben: function assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void | Vor PHP 8.0.0 musste die Signatur des Callbacks wie folgt lauten: function assert_callback( string `$file`, int `$line`, string `$assertion`, string `$description` = ? ): void Seit PHP 8.3.0 veraltet.
assert.exception | `true` | Wenn `true`, wird ein AssertionError ausgelöst, wenn die Erwartung nicht erfüllt wird. | Seit PHP 8.3.0 veraltet.
assert.bail | `false` | Wenn `true`, wird die Ausführung des PHP-Skripts gestoppt, wenn die Erwartung nicht erfüllt wird. | Seit PHP 8.3.0 veraltet.
assert.warning | `true` | Wenn `true`, wird eine `E_WARNING` ausgegeben, wenn die Erwartung nicht erfüllt wird. Diese INI-Einstellung hat keine Auswirkung, wenn assert.exception aktiviert ist. | Seit PHP 8.3.0 veraltet.

### Parameter-Liste

`assertion`

  Dies ist ein beliebiger Ausdruck, der einen Wert zurückgibt, der ausgeführt wird und dessen Ergebnis verwendet wird, um anzuzeigen, ob die Zusicherung erfolgreich war oder fehlschlug.

  Warnung

  Vor PHP 8.0.0 wurde `assertion`, wenn es vom Typ string war, als PHP-Code interpretiert und über eval() ausgeführt. Diese Zeichenkette wurde dann als drittes Argument an den Callback übergeben. Dieses Verhalten war in PHP 7.2.0 MISSBILLIGT, und wurde in PHP 8.0.0 ENTFERNT.

`description`

  Wenn `description` eine Instanz von Throwable ist, wird sie nur ausgelöst, wenn die `assertion` ausgeführt wird und fehlschlägt.

  > Hinweis:

  > Seit PHP 8.0.0 wird dies durchgeführt bevor ein möglicherweise definierter Zusicherungs-Callback aufgerufen wird.

  > Hinweis:

  > Seit PHP 8.0.0 wird das Objekt unabhängig von der Einstellung von assert.exception ausgelöst.

  > Hinweis:

  > Seit PHP 8.0.0 hat die Einstellung von assert.bail in diesem Fall keine Wirkung mehr.

  Wenn `description` vom Typ String ist, wird diese Nachricht verwendet, wenn eine Exception oder eine Warnung ausgegeben wird. Eine optionale Beschreibung, die in die Fehlermeldung aufgenommen wird, wenn die `assertion` fehlschlägt.

  `description` kann weggelassen werden. Die Standardbeschreibung entspricht dem Quellcode für den Aufruf von assert() und wird zur Kompilierzeit erstellt.

### Rückgabewerte

Wenn mindestens eine der folgenden Bedingungen erfüllt ist, gibt assert() immer `true` zurück:

- `zend.assertions=0`
- `zend.assertions=-1`
- `assert.active=0`
- `assert.exception=1`
- `assert.bail=1`
- An `description` wird ein benutzerdefiniertes Exception-Objekt übergeben.

Wenn keine der Bedingungen wahr ist, gibt assert() `true` zurück, sofern `assertion` wahr ist, ansonsten `false`.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Alle INI-Einstellungen für `assert.` sind veraltet.
8.0.0 | assert() wertet Zeichenketten nicht mehr aus, sondern behandelt sie stattdessen wie jeden anderen Parameter. Anstelle von `assert('$a == $b')` sollte `assert($a == $b)` verwendet werden. Die php.ini-Direktive `assert.quiet_eval` und die Konstante `ASSERT_QUIET_EVAL` wurden ebenfalls entfernt, da sie keine Auswirkungen mehr haben.
8.0.0 | Wenn `description` eine Instanz von Throwable ist, wird nun ein Objekt ausgelöst, wenn die Zusicherung fehlschlägt, unabhängig vom Wert von assert.exception.
8.0.0 | Wenn `description` eine Instanz von Throwable ist, wird kein Benutzer-Callback aufgerufen, auch wenn er gesetzt ist.
8.0.0 | Die Deklaration einer Funktion namens `assert()` innerhalb eines Namensraums ist nicht mehr erlaubt und führt zu einem Fehler der Stufe `E_COMPILE_ERROR`.
7.3.0 | Die Deklaration einer Funktion namens `assert()` innerhalb eines Namensraums ist veraltet und gibt nun einen `E_DEPRECATED`-Hinweis aus.
7.2.0 | Die Verwendung eines Strings als `assertion` wird missbilligt. Dies erzeugt nun einen `E_DEPRECATED`-Hinweis, wenn sowohl assert.active als auch zend.assertions auf `1` gesetzt sind.

### Beispiele

Beispiel #1 assert()-Beispiel

    <?php
    assert(1 > 2);
    echo 'Hi!';

Falls Zusicherungen aktiviert sind (`zend.assertions=1`), gibt das obige Beispiel folgendes aus:

    Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'assert(1 > 2)')
    #1 {main}
      thrown in example.php on line 2

Falls Zusicherungen deaktiviert sind (`zend.assertions=0` oder `zend.assertions=-1`), gibt das obige Beispiel folgendes aus:

    Hi!

Beispiel #2 Verwenden einer benutzerdefinierten Meldung

    <?php
    assert(1 > 2, "Es wurde erwartet, dass eins größer ist als zwei");
    echo 'Hi!';

Falls Zusicherungen aktiviert sind, gibt das obige Beispiel folgendes aus:

    Fatal error: Uncaught AssertionError: Es wurde erwartet, dass eins größer ist als zwei in example.php:2
    Stack trace:
    #0 example.php(2): assert(false, 'Es wurde erwartet,...')
    #1 {main}
      thrown in example.php on line 2

Falls Zusicherungen deaktiviert sind, gibt das obige Beispiel folgendes aus:

    Hi!

Beispiel #3 Verwenden einer benutzerdefinierten Exception-Klasse

    <?php
    class ArithmeticAssertionError extends AssertionError {}

    assert(1 > 2, new ArithmeticAssertionError("Es wurde erwartet, dass eins größer ist als zwei"));
    echo 'Hi!';

Falls Zusicherungen aktiviert sind, gibt das obige Beispiel folgendes aus:

    Fatal error: Uncaught ArithmeticAssertionError: Es wurde erwartet, dass eins größer ist als zwei in example.php:4
    Stack trace:
    #0 {main}
      thrown in example.php on line 4

Falls Zusicherungen deaktiviert sind, gibt das obige Beispiel folgendes aus:

    Hi!

### Siehe auch

- assert_options() - Setzt oder liefert Assert-Optionen

# assert_options

(PHP 4, PHP 5, PHP 7, PHP 8)

assert_options — Setzt oder liefert Assert-Optionen

Warnung

Diese Funktion ist seit PHP 8.3.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function assert_options(int `$option`, mixed `$value` = ?): mixed

assert_options() ermöglicht es, die verschiedenen assert()-Optionen zu setzen, oder abzufragen, welche Optionen gesetzt sind.

> Hinweis: Von der Verwendung von assert_options() wird abgeraten; stattdessen sollten die php.ini-Optionen zend.assertions und assert.exception durch ini_set() und ini_get() gesetzt bzw. gelesen werden.

### Parameter-Liste

`option`

  Assert-Optionen
  Option | INI-Option | Standardwert | Beschreibung
  --- | --- | --- | ---
  ASSERT_ACTIVE | assert.active | 1 | Aktiviert die assert()-Überprüfung.
  ASSERT_EXCEPTION | assert.exception | 1 | Löst für jede fehlgeschlagene Assertion einen AssertionError aus
  ASSERT_WARNING | assert.warning | 1 | Gibt eine PHP-Warnung für jede fehlgeschlagene Überprüfung aus.
  ASSERT_BAIL | assert.bail | 0 | Beendet das Programm bei fehlgeschlagener Überprüfung.
  ASSERT_QUIET_EVAL | assert.quiet_eval | 0 | Unterdrückt die Fehlerausgabe während der Überprüfung. Entfernt in PHP 8.0.0.
  ASSERT_CALLBACK | assert.callback | (`null`) | Die Funktion, die bei fehlgeschlagener Überprüfung aufgerufen wird.

`value`

  Ein optionaler neuer Wert für die Option.

  Die Callback-Funktion, die per `ASSERT_CALLBACK` oder assert.callback gesetzt wurde, sollte folgende Signatur haben:

  function assert_callback(
  string `$file`,
  int `$line`,
  ?string `$assertion`,
  string `$description` = ?
  ): void
  `file`
    Die Datei, in der assert() aufgerufen wurde.
  `line`
    Die Zeile, in der assert() aufgerufen wurde.
  `assertion`
    Vor PHP 8.0.0 die Assertion, die an assert() übergeben wurde, aber nur wenn die Assertion als Zeichenkette angegeben wird (ist die Assertion eine boolesche Bedingung, dann ist dieser Parameter eine leere Zeichenkette). Seit PHP 8.0.0 ist dieser Parameter immer `null`.
  `description`
    Die Beschreibung, die an assert() übergeben wurde.

Die Übergabe einer leeren Zeichenkette als `value` setzt den Assert-Callback zurück.

### Rückgabewerte

Gibt die Einstellung der gesetzten Optionen zurück.

### Fehler/Exceptions

Wenn `option` keine gültige Option ist, wird ein ValueError ausgelöst.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | assert_options() ist nun veraltet.
8.0.0 | Wenn `option` keine gültige Option ist, wird ein ValueError ausgelöst; zuvor wurde `false` zurückgegeben.

### Beispiele

Beispiel #1 assert_options()-Beispiel

    <?php
    // Das ist unsere Funktion zur Behandlung von
    // fehlgeschlagenen Überprüfungen
    function assert_failure($file, $line, $assertion, $message)
    {
        echo "Die Assertion $assertion in $file in Zeile $line schlug fehl: $message";
    }

    // Das ist unsere Testfunktion
    function test_assert($parameter)
    {
        assert(is_bool($parameter));
    }

    // Wir setzen unsere Assert-Optionen
    assert_options(ASSERT_ACTIVE,   true);
    assert_options(ASSERT_BAIL,     true);
    assert_options(ASSERT_WARNING,  false);
    assert_options(ASSERT_CALLBACK, 'assert_failure');

    // Wir führen eine Überprüfung durch, die fehlschlägt
    test_assert(1);

    // Dies wird nie erreicht, weil ASSERT_BAIL
    // true ist
    echo 'Unerreicht';
    ?>

### Siehe auch

- assert() - Überprüft eine Assertion (Zusicherung)

# cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_title — Returns the current process title

### Beschreibung

function cli_get_process_title(): ?string

Returns the current process title, as set by cli_set_process_title(). Note that this may not exactly match what is shown in ps or top, depending on your operating system.

This function is available only in CLI mode.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Return a string with the current process title or `null` on error.

### Fehler/Exceptions

An `E_WARNING` will be generated if the operating system is unsupported.

### Beispiele

Beispiel #1 cli_get_process_title() example

    <?php
    echo "Process title: " . cli_get_process_title() . "\n";
    ?>

### Siehe auch

- cli_set_process_title() - Sets the process title

# cli_set_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_set_process_title — Sets the process title

### Beschreibung

function cli_set_process_title(string `$title`): bool

Sets the process title visible in tools such as top and ps. This function is available only in CLI mode.

### Parameter-Liste

`title`
  The new title.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

An `E_WARNING` will be generated if the operating system is unsupported.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | cli_set_process_title() will now emit an `E_WARNING` when setting a process title that is too long; previously the title would be truncated.

### Beispiele

    <?php
    $title = "My Amazing PHP Script";
    $pid = getmypid(); // you can use this to see your process title in ps

    if (!cli_set_process_title($title)) {
        echo "Unable to set process title for PID $pid...\n";
        exit(1);
    } else {
        echo "The process title '$title' for PID $pid has been set for your process!\n";
        sleep(5);
    }
    ?>

### Siehe auch

- cli_get_process_title() - Returns the current process title

# dl

(PHP 4, PHP 5, PHP 7, PHP 8)

dl — Lädt eine PHP-Erweiterung zur Laufzeit

### Beschreibung

function dl(string `$extension_filename`): bool

Lädt die im Parameter `extension_filename` angegebene PHP-Erweiterung.

Verwenden Sie extension_loaded() um zu testen, ob die gewünschte Erweiterung bereits verfügbar ist oder nicht. Dies funktioniert sowohl bei eingebauten, als auch bei dynamisch geladenen Erweiterungen (entweder durch die php.ini, oder mittels dl()).

Warnung

Diese Funktion ist nur für die CLI- und die eingebetteten SAPIs sowie für die CGI-SAPI verfügbar, sofern sie über die Befehlszeile ausgeführt wird.

### Parameter-Liste

`extension_filename`

  Dieser Parameter ist nur der Dateiname der zu ladenden Erweiterung, welcher von der Plattform abhängig ist, z. B. würde die Erweiterung sockets (wenn als shared module kompiliert, nicht standardmäßig!) auf Unix-Plattformen sockets.so heißen, und auf Windows-Plattformen php_sockets.dll.

  Das Verzeichnis, von wo aus die Erweiterung geladen wird, hängt von der Plattform ab:

  Windows - Wenn nicht explizit in der php.ini angegeben, wird die Erweiterung standardmäßig von c:\php5\ geladen.

  Unix - Wenn nicht explizit in der php.ini angegeben, hängt das standardmäßige Verzeichnis ab von:

  - ob PHP mit `--enable-debug` erstellt wurde oder nicht
  - ob PHP mit ZTS- (Zend Thread Safety) Unterstützung erstellt wurde oder nicht
  - der aktuellen internen `ZEND_MODULE_API_NO` (Zend-interne Modul-API-Nummer, welche im Grunde das Datum der letzten größeren Modul-API-Änderung darstellt, z. B. `20010901`).
  Das obige in Betracht gezogen, ist das standardmäßige Verzeichnis `<install-dir>/lib/php/extensions/<debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO`, z. B. /usr/local/php/lib/php/extensions/debug-non-zts-20010901 oder /usr/local/php/lib/php/extensions/no-debug-zts-20010901.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. Ist die Funktionalität des Ladens von Modulen nicht verfügbar, oder wurde sie deaktiviert (durch Deaktivieren von enable_dl in der php.ini), wird ein `E_ERROR` ausgegeben, und die Ausführung gestoppt. Scheitert dl(), weil die angegebene Erweiterung nicht geladen werden konnte, wird zusätzlich zu `false` eine `E_WARNING`-Meldung ausgegeben.

### Beispiele

Beispiel #1 dl()-Beispiele

    <?php
    // Beispiel für das Laden einer Erweiterung je nach Betriebssystem
    if (!extension_loaded('sqlite')) {
        if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
            dl('php_sqlite.dll');
        } else {
            dl('sqlite.so');
        }
    }

    // Oder unter Verwendung der Konstante PHP_SHLIB_SUFFIX
    if (!extension_loaded('sqlite')) {
        $prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
        dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
    }
    ?>

### Anmerkungen

> Hinweis:

> dl() unterscheidet auf Unix-Plattformen zwischen Groß- und Kleinschreibung.

### Siehe auch

- Direktiven zum Laden von Erweiterungen
- extension_loaded() - Prüft, ob eine Erweiterung geladen ist

# extension_loaded

(PHP 4, PHP 5, PHP 7, PHP 8)

extension_loaded — Prüft, ob eine Erweiterung geladen ist

### Beschreibung

function extension_loaded(string `$extension`): bool

Prüft, ob eine Erweiterung geladen ist.

### Parameter-Liste

`extension`

  Der Name der Erweiterung. Bei diesem Parameter wird die Groß-/Kleinschreibung nicht berücksichtigt.

  Eine Liste der Namen verschiedener Erweiterungen finden Sie in der Ausgabe von phpinfo() oder Sie können das `CGI`- oder `CLI`-Binary mit der Option -m aufrufen:

      $ php -m
      [PHP Modules]
      xml
      tokenizer
      standard
      sockets
      session
      posix
      pcre
      overload
      mysql
      mbstring
      ctype

      [Zend Modules]

### Rückgabewerte

Gibt `true` zurück, wenn die durch `extension` identifizierte Erweiterung geladen ist, andernfalls `false`.

### Beispiele

Beispiel #1 extension_loaded()-Beispiel

    <?php
    if (!extension_loaded('gd')) {
        if (!dl('gd.so')) {
            exit;
        }
    }
    ?>

### Siehe auch

- get_loaded_extensions() - Liefert ein Array mit den Namen aller einkompilierten und geladenen Erweiterungen
- get_extension_funcs() - Liefert die Namen der Funktionen einer Erweiterung
- phpinfo() - Liefert Informationen zur PHP-Konfiguration
- dl() - Lädt eine PHP-Erweiterung zur Laufzeit
- function_exists() - Falls die angegebene Funktion definiert ist, wird true zurück gegeben

# gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cycles — Forces collection of any existing garbage cycles

### Beschreibung

function gc_collect_cycles(): int

Forces collection of any existing garbage cycles.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns number of collected cycles.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The return value no longer includes strings and resources that were indirectly collected through cycles.

### Siehe auch

- Garbage Collection

# gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disable — Deactivates the circular reference collector

### Beschreibung

function gc_disable(): void

Deactivates the circular reference collector, setting zend.enable_gc to `0`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- Garbage Collection

# gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enable — Activates the circular reference collector

### Beschreibung

function gc_enable(): void

Activates the circular reference collector, setting zend.enable_gc to `1`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- Garbage Collection

# gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabled — Returns status of the circular reference collector

### Beschreibung

function gc_enabled(): bool

Returns status of the circular reference collector.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the garbage collector is enabled, `false` otherwise.

### Beispiele

Beispiel #1 A gc_enabled() example

    <?php
    if(gc_enabled()) gc_collect_cycles();
    ?>

### Siehe auch

- Garbage Collection

# gc_mem_caches

(PHP 7, PHP 8)

gc_mem_caches — Reclaims memory used by the Zend Engine memory manager

### Beschreibung

function gc_mem_caches(): int

Reclaims memory used by the Zend Engine memory manager.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of bytes freed.

### Siehe auch

- Garbage Collection

# gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_status — Gets information about the garbage collector

### Beschreibung

function gc_status(): array

Gets information about the current state of the garbage collector.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an associative array with the following elements:

- `"runs"`
- `"collected"`
- `"threshold"`
- `"roots"`
- `"running"`
- `"protected"`
- `"full"`
- `"buffer_size"`
- `"application_time"`
- `"collector_time"`
- `"destructor_time"`
- `"free_time"`

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | gc_status() now returns the following additional fields: `"running"`, `"protected"`, `"full"`, `"buffer_size"`, `"application_time"`, `"collector_time"`, `"destructor_time"`, and `"free_time"`.

### Beispiele

Beispiel #1 gc_status() Usage

    <?php

    // create object tree that needs gc collection
    $a = new stdClass();
    $a->b = [];
    for ($i = 0; $i < 100000; $i++) {
        $b = new stdClass();
        $b->a = $a;
        $a->b[] = $b;
    }
    unset($a);
    unset($b);
    gc_collect_cycles();

    var_dump(gc_status());

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(4) {
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["roots"]=>
      int(0)
    }

Das oben gezeigte Beispiel erzeugt mit PHP 8.3 eine ähnliche Ausgabe wie:

    array(12) {
      ["running"]=>
      bool(false)
      ["protected"]=>
      bool(false)
      ["full"]=>
      bool(false)
      ["runs"]=>
      int(5)
      ["collected"]=>
      int(100002)
      ["threshold"]=>
      int(50001)
      ["buffer_size"]=>
      int(131072)
      ["roots"]=>
      int(0)
      ["application_time"]=>
      float(0.031182458)
      ["collector_time"]=>
      float(0.020106291)
      ["destructor_time"]=>
      float(0)
      ["free_time"]=>
      float(0.003707167)
    }

### Siehe auch

- Garbage Collection

# get_cfg_var

(PHP 4, PHP 5, PHP 7, PHP 8)

get_cfg_var — Liefert den Wert einer Konfigurationsoption

### Beschreibung

function get_cfg_var(string `$option`): string|array|false

Ermittelt den aktuellen Wert der Konfigurationsoption `option`.

Diese Funktion gibt keine Konfigurationsinformationen zurück, die beim Kompilieren von PHP gesetzt oder aus den Apache-Konfigurationsdateien gelesen wurden.

Um zu prüfen, ob das System eine Konfigurationsdatei verwendet, können Sie versuchen, den Wert der cfg_file_path Einstellung abzufragen. Wenn dieser verfügbar ist, wird eine Konfigurationsdatei verwendet.

### Parameter-Liste

`option`

  Der Name der Konfigurationsvariable.

### Rückgabewerte

Gibt den aktuellen Wert der mit `option` angegebenen Konfigurationsvariable zurück. Tritt ein Fehler auf, so wird `false` zurückgegeben.

### Siehe auch

- ini_get() - Gets the value of a configuration option
- ini_get_all() - Gets all configuration options

# get_current_user

(PHP 4, PHP 5, PHP 7, PHP 8)

get_current_user — Liefert den Benutzernamen des Besitzers des aktuellen PHP-Skripts

### Beschreibung

function get_current_user(): string

Liefert den Namen des Benutzers, welcher der Besitzer der aktuell ausgeführten PHP-Skriptdatei ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert den Benutzernamen als Zeichenkette.

### Beispiele

Beispiel #1 get_current_user()-Beispiel

    <?php
    echo 'Name des Benutzers: ' . get_current_user();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Name des Benutzers: SYSTEM

### Siehe auch

- getmyuid() - Liefert die User-ID des Besitzers eines PHP-Skripts
- getmygid() - Get PHP script owner's GID
- getmypid() - Liefert die Prozess-ID eines Skripts
- getmyinode() - Liefert den Inode des aktuellen Skripts
- getlastmod() - Liefert die Uhrzeit der letzten Änderung eines Skripts

# get_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constants — Returns an associative array with the names of all the constants and their values

### Beschreibung

function get_defined_constants(bool `$categorize` = `false`): array

Returns the names and values of all the constants currently defined. This includes those created by extensions as well as those created with the define() function.

### Parameter-Liste

`categorize`

  Causing this function to return a multi-dimensional array with categories in the keys of the first dimension and constants and their values in the second dimension.

      <?php
      define("MY_CONSTANT", 1);
      print_r(get_defined_constants(true));
      ?>

  Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

      Array
      (
          [Core] => Array
              (
                  [E_ERROR] => 1
                  [E_WARNING] => 2
                  [E_PARSE] => 4
                  [E_NOTICE] => 8
                  [E_CORE_ERROR] => 16
                  [E_CORE_WARNING] => 32
                  [E_COMPILE_ERROR] => 64
                  [E_COMPILE_WARNING] => 128
                  [E_USER_ERROR] => 256
                  [E_USER_WARNING] => 512
                  [E_USER_NOTICE] => 1024
                  [E_ALL] => 2047
                  [TRUE] => 1
              )

          [pcre] => Array
              (
                  [PREG_PATTERN_ORDER] => 1
                  [PREG_SET_ORDER] => 2
                  [PREG_OFFSET_CAPTURE] => 256
                  [PREG_SPLIT_NO_EMPTY] => 1
                  [PREG_SPLIT_DELIM_CAPTURE] => 2
                  [PREG_SPLIT_OFFSET_CAPTURE] => 4
                  [PREG_GREP_INVERT] => 1
              )

          [user] => Array
              (
                  [MY_CONSTANT] => 1
              )

      )

### Rückgabewerte

Returns an array of constant name => constant value array, optionally grouped by extension name registering the constant.

### Beispiele

Beispiel #1 get_defined_constants() Example

    <?php
    print_r(get_defined_constants());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [E_ERROR] => 1
        [E_WARNING] => 2
        [E_PARSE] => 4
        [E_NOTICE] => 8
        [E_CORE_ERROR] => 16
        [E_CORE_WARNING] => 32
        [E_COMPILE_ERROR] => 64
        [E_COMPILE_WARNING] => 128
        [E_USER_ERROR] => 256
        [E_USER_WARNING] => 512
        [E_USER_NOTICE] => 1024
        [E_ALL] => 2047
        [TRUE] => 1
    )

### Siehe auch

- defined() - Prüft, ob eine Konstante mit dem angegebenen Namen existiert
- constant() - Liefert den Wert einer Konstante
- get_loaded_extensions() - Liefert ein Array mit den Namen aller einkompilierten und geladenen Erweiterungen
- get_defined_functions() - Liefert ein Array aller definierten Funktionen
- get_defined_vars() - Gibt ein Array aller definierten Variablen zurück

# get_extension_funcs

(PHP 4, PHP 5, PHP 7, PHP 8)

get_extension_funcs — Liefert die Namen der Funktionen einer Erweiterung

### Beschreibung

function get_extension_funcs(string `$extension`): array|false

Diese Funktion gibt die Namen aller im angegebenen Modul `extension` definierten Funktionen zurück.

### Parameter-Liste

`extension`

  Der Name der Erweiterung.

  > Hinweis:

  > Der Name muss kleingeschrieben werden.

### Rückgabewerte

Gibt ein Array mit den Namen aller Funktionen zurück oder `false`, wenn keine Erweiterung mit dem Namen `extension` geladen ist.

### Beispiele

Beispiel #1 Gibt alle XML-Funktionen aus

    <?php
    print_r(get_extension_funcs("xml"));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => xml_parser_create
        [1] => xml_parser_create_ns
        [2] => xml_set_object
        [3] => xml_set_element_handler
        [4] => xml_set_character_data_handler
        [5] => xml_set_processing_instruction_handler
        [6] => xml_set_default_handler
        [7] => xml_set_unparsed_entity_decl_handler
        [8] => xml_set_notation_decl_handler
        [9] => xml_set_external_entity_ref_handler
        [10] => xml_set_start_namespace_decl_handler
        [11] => xml_set_end_namespace_decl_handler
        [12] => xml_parse
        [13] => xml_parse_into_struct
        [14] => xml_get_error_code
        [15] => xml_error_string
        [16] => xml_get_current_line_number
        [17] => xml_get_current_column_number
        [18] => xml_get_current_byte_index
        [19] => xml_parser_free
        [20] => xml_parser_set_option
        [21] => xml_parser_get_option
    )

### Siehe auch

- get_loaded_extensions() - Liefert ein Array mit den Namen aller einkompilierten und geladenen Erweiterungen
- ReflectionExtension::getFunctions() - Gets extension functions

# get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_path — Gets the current include_path configuration option

### Beschreibung

function get_include_path(): string|false

Gets the current include_path configuration option value.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the path, as a string, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 get_include_path() example

    <?php
    echo get_include_path();

    // Or using ini_get()
    echo ini_get('include_path');
    ?>

### Siehe auch

- ini_get() - Gets the value of a configuration option
- restore_include_path() - Restores the value of the include_path configuration option
- set_include_path() - Setzt die Konfigurationsoption include_path
- include - include

# get_included_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_included_files — Liefert ein Array mit den Namen der eingebundenen Dateien

### Beschreibung

function get_included_files(): array

Gibt die Namen aller Dateien zurück, die mit include, include_once, require oder require_once eingebunden wurden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array mit den Namen aller Dateien zurück.

Das ursprünglich aufgerufene Skript wird auch als eingebundene Datei angesehen und damit zusammen mit den Namen der tatäschlich mit include etc. eingebundenen Dateien zurückgegeben.

Dateien, die mehrfach eingebunden werden, erscheinen nur einmal im Ergebnisarray.

### Beispiele

Beispiel #1 get_included_files()-Beispiel

    <?php
    // Diese Datei ist abc.php

    include 'test1.php';
    include_once 'test2.php';
    require 'test3.php';
    require_once 'test4.php';

    $included_files = get_included_files();

    foreach ($included_files as $filename) {
        echo "$filename\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    /pfad/zu/abc.php
    /pfad/zu/test1.php
    /pfad/zu/test2.php
    /pfad/zu/test3.php
    /pfad/zu/test4.php

### Siehe auch

- include - include
- include_once - include_once
- require - require
- require_once - require_once
- get_required_files() - Alias von get_included_files

# get_loaded_extensions

(PHP 4, PHP 5, PHP 7, PHP 8)

get_loaded_extensions — Liefert ein Array mit den Namen aller einkompilierten und geladenen Erweiterungen

### Beschreibung

function get_loaded_extensions(bool `$zend_extensions` = `false`): array

Diese Funktion gibt die Namen aller in den PHP-Interpreter einkompilierten und geladenen Erweiterungen aus.

### Parameter-Liste

`zend_extensions`

  Legt fest, ob nur Zend-Erweiterungen zurückgegeben werden sollen. Vorgabewert ist `false`, d.h., es werden reguläre Erweiterungen zurückgegeben.

### Rückgabewerte

Gibt ein Array mit den Namen aller Erweiterungen zurück.

### Beispiele

Beispiel #1 get_loaded_extensions()-Beispiel

    <?php
    print_r(get_loaded_extensions());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Core
        [1] => date
        [2] => libxml
        [3] => pcre
        [4] => sqlite3
        [5] => zlib
        [6] => ctype
        [7] => dom
        [8] => fileinfo
        [9] => filter
        [10] => hash
        [11] => json
        [12] => mbstring
        [13] => SPL
        [14] => PDO
        [15] => session
        [16] => posix
        [17] => Reflection
        [18] => standard
        [19] => SimpleXML
        [20] => pdo_sqlite
        [21] => Phar
        [22] => tokenizer
        [23] => xml
        [24] => xmlreader
        [25] => xmlwriter
        [26] => gmp
        [27] => iconv
        [28] => intl
        [29] => bcmath
        [30] => sodium
        [31] => Zend OPcache
    )

### Siehe auch

- get_extension_funcs() - Liefert die Namen der Funktionen einer Erweiterung
- extension_loaded() - Prüft, ob eine Erweiterung geladen ist
- dl() - Lädt eine PHP-Erweiterung zur Laufzeit
- phpinfo() - Liefert Informationen zur PHP-Konfiguration

# get_magic_quotes_gpc

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_gpc — Liefert die aktuelle Konfiguration von magic_quotes_gpc

Warnung

Diese Funktion ist seit PHP 7.4.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function get_magic_quotes_gpc(): false

Gibt immer `false` zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion wurde entfernt.
7.4.0 | Diese Funktion wurde als veraltet eingestuft.

### Siehe auch

- addslashes() - Stellt bestimmten Zeichen eines Strings ein "\" voran
- stripslashes() - Entfernt Maskierungszeichen aus einem String
- get_magic_quotes_runtime() - Liefert die aktuelle Konfiguration von magic_quotes_runtime
- ini_get() - Gets the value of a configuration option

# get_magic_quotes_runtime

(PHP 4, PHP 5, PHP 7)

get_magic_quotes_runtime — Liefert die aktuelle Konfiguration von magic_quotes_runtime

Warnung

Diese Funktion ist seit PHP 7.4.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function get_magic_quotes_runtime(): false

Gibt immer `false` zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion wurde entfernt.
7.4.0 | Diese Funktion wurde als veraltet eingestuft.

### Siehe auch

- get_magic_quotes_gpc() - Liefert die aktuelle Konfiguration von magic_quotes_gpc

# get_required_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_required_files — Alias von get_included_files()

### Beschreibung

Diese Funktion ist ein Alias für: get_included_files().

# get_resources

(PHP 7, PHP 8)

get_resources — Returns active resources

### Beschreibung

function get_resources(?string `$type` = `null`): array

Returns an array of all currently active resources, optionally filtered by resource type.

> Hinweis: This function is meant for debugging and testing purposes. It is not supposed to be used in production environments, especially not to access or even manipulate resources which are normally not accessible (e.g. the underlying stream resource of SplFileObject instances).

### Parameter-Liste

`type`

  If defined, this will cause get_resources() to only return resources of the given type. A list of resource types is available.

  If the string `Unknown` is provided as the type, then only resources that are of an unknown type will be returned.

  If omitted, all resources will be returned.

### Rückgabewerte

Returns an array of currently active resources, indexed by resource number.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `type` is nullable now.

### Beispiele

Beispiel #1 Unfiltered get_resources()

    <?php
    $fp = tmpfile();
    var_dump(get_resources());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }

Beispiel #2 Filtered get_resources()

    <?php
    $fp = tmpfile();
    var_dump(get_resources('stream'));
    var_dump(get_resources('curl'));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [1]=>
      resource(1) of type (stream)
    }
    array(0) {
    }

### Siehe auch

- get_loaded_extensions() - Liefert ein Array mit den Namen aller einkompilierten und geladenen Erweiterungen
- get_defined_constants() - Returns an associative array with the names of all the constants and their values
- get_defined_functions() - Liefert ein Array aller definierten Funktionen
- get_defined_vars() - Gibt ein Array aller definierten Variablen zurück

# getenv

(PHP 4, PHP 5, PHP 7, PHP 8)

getenv — Liefert den Wert einer einzelnen oder aller Umgebungsvariablen

### Beschreibung

function getenv(?string `$name` = `null`, bool `$local_only` = `false`): string|array|false

Gibt den Wert einer einzelnen oder aller Umgebungsvariablen zurück.

Eine Liste aller Umgebungsvariablen lässt sich mit der Funktion phpinfo() anzeigen. Viele dieser Variablen sind im » RFC 3875, insbesondere im Abschnitt 4.1, "Request Meta-Variables", aufgeführt.

### Parameter-Liste

`name`

  Der Variablenname als String oder `null`.

`local_only`

  Bei `true` werden nur lokale Umgebungsvariablen zurückgegeben, die vom Betriebsystem oder durch putenv() gesetzt wurden. Es hat nur dann eine Auswirkung, wenn `name` ein String ist.

### Rückgabewerte

Gibt den Wert der Umgebungsvariable `varname` zurück oder `false`, wenn die Umgebungsvariable `name` nicht existiert. Ist `name` `null`, werden alle Umgebungsvariablen als assoziatives Array zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `name` ist nun nullable (akzeptiert den `null`-Wert).
7.1.0 | Der Parameter `name` kann nun ausgelassen werden, um ein assoziatives Array aller Umgebungsvariablen abzurufen.
7.0.9 | Der Parameter `local_only` wurde hinzugefügt.

### Beispiele

Beispiel #1 getenv()-Beispiel

    <?php
    // Verwendung von getenv() ...
    $ip = getenv('REMOTE_ADDR');

    // ... oder einfach eines superglobalen Arrays ($_SERVER oder $_ENV)
    $ip = $_SERVER['REMOTE_ADDR'];

    // Sicheres Lesen eines Wertes einer Umgebungsvariablen, wobei ignoriert wird,
    // ob sie durch die SAPI gesetzt oder durch putenv geändert wurde
    $ip = getenv('REMOTE_ADDR', true) ?: getenv('REMOTE_ADDR')
    ?>

### Anmerkungen

Warnung

Wird PHP in einer SAPI wie Fast CGI ausgeführt, gibt diese Funktion immer den Wert einer Umgebungsvariablenzurück, die von der SAPI gesetzt wurde, selbst wenn putenv() verwendet wurde, um eine lokale Umgebungsvariable mit dem selben Namen zu setzen. Verwenden Sie `local_only`, um den Wert einer lokal gesetzten Umgebungsvariable zurückzugeben.

### Siehe auch

- putenv() - Setzt den Wert einer Umgebungsvariablen
- apache_getenv() - Liefert eine Apache-Subprocess_env-Variable
- Superglobals

# getlastmod

(PHP 4, PHP 5, PHP 7, PHP 8)

getlastmod — Liefert die Uhrzeit der letzten Änderung eines Skripts

### Beschreibung

function getlastmod(): int|false

Ermittelt die Uhrzeit der letzten Änderung des ausgeführten Skripts.

Wenn Sie sich für das Änderungsdatum einer anderen Datei interessieren, verwenden Sie stattdessen filemtime().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert die Zeit der letzten Änderung des ausgeführten Skripts. Der Wert wird als Unix Timestamp zurückgegeben und kann mit Hilfe der Funktion date() verarbeitet werden. Im Fehlerfall wird `false` zurückgegeben.

### Beispiele

Beispiel #1 getlastmod()-Beispiel

    <?php
    // Liefert z. B. 'Letzte Änderung: March 04 1998 20:43:59.'
    echo "Letzte Änderung: " . date ("F d Y H:i:s.", getlastmod());
    ?>

### Siehe auch

- date() - Formatiert einen Unix-Zeitstempel
- getmyuid() - Liefert die User-ID des Besitzers eines PHP-Skripts
- getmygid() - Get PHP script owner's GID
- get_current_user() - Liefert den Benutzernamen des Besitzers des aktuellen PHP-Skripts
- getmyinode() - Liefert den Inode des aktuellen Skripts
- getmypid() - Liefert die Prozess-ID eines Skripts
- filemtime() - Liefert die Zeit der letzten Dateiänderung

# getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygid — Get PHP script owner's GID

### Beschreibung

function getmygid(): int|false

Gets the group ID of the current script.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the group ID of the current script, or `false` on error.

### Siehe auch

- getmyuid() - Liefert die User-ID des Besitzers eines PHP-Skripts
- getmypid() - Liefert die Prozess-ID eines Skripts
- get_current_user() - Liefert den Benutzernamen des Besitzers des aktuellen PHP-Skripts
- getmyinode() - Liefert den Inode des aktuellen Skripts
- getlastmod() - Liefert die Uhrzeit der letzten Änderung eines Skripts

# getmyinode

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyinode — Liefert den Inode des aktuellen Skripts

### Beschreibung

function getmyinode(): int|false

Ermittelt den Inode der aktuell ausgeführten Skriptdatei.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Inode-Nummer der aktuellen Skriptdatei als Integer zurück oder `false` im Fehlerfall.

### Siehe auch

- getmygid() - Get PHP script owner's GID
- getmyuid() - Liefert die User-ID des Besitzers eines PHP-Skripts
- getmypid() - Liefert die Prozess-ID eines Skripts
- get_current_user() - Liefert den Benutzernamen des Besitzers des aktuellen PHP-Skripts
- getlastmod() - Liefert die Uhrzeit der letzten Änderung eines Skripts

# getmypid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmypid — Liefert die Prozess-ID eines Skripts

### Beschreibung

function getmypid(): int|false

Gibt die Prozess-ID zurück, unter der das Skript ausgeführt wird.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Prozess-ID zurück, unter der das Skript ausgeführt wird, oder `false` bei Fehlern.

### Anmerkungen

Warnung

Prozess-IDs sind nicht eindeutig, sie sind daher eine schwache Entropiequelle. Wir raten davon ab, sich in sicherheitsrelevanten Bereichen auf Prozess-IDs zu verlassen.

### Siehe auch

- getmygid() - Get PHP script owner's GID
- getmyuid() - Liefert die User-ID des Besitzers eines PHP-Skripts
- get_current_user() - Liefert den Benutzernamen des Besitzers des aktuellen PHP-Skripts
- getmyinode() - Liefert den Inode des aktuellen Skripts
- getlastmod() - Liefert die Uhrzeit der letzten Änderung eines Skripts

# getmyuid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyuid — Liefert die User-ID des Besitzers eines PHP-Skripts

### Beschreibung

function getmyuid(): int|false

Gibt die User-ID des Besitzers des aktuellen Skripts zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die User-ID des aktuellen Skripts zurück oder `false` bei einem Fehler.

### Siehe auch

- getmygid() - Get PHP script owner's GID
- getmypid() - Liefert die Prozess-ID eines Skripts
- get_current_user() - Liefert den Benutzernamen des Besitzers des aktuellen PHP-Skripts
- getmyinode() - Liefert den Inode des aktuellen Skripts
- getlastmod() - Liefert die Uhrzeit der letzten Änderung eines Skripts

# getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getopt — Gets options from the command line argument list

### Beschreibung

function getopt(string `$short_options`, array `$long_options` = [], int `&$rest_index` = `null`): array|false

Parses options passed to the script.

### Parameter-Liste

`short_options`
  Each character in this string will be used as option characters and matched against options passed to the script starting with a single hyphen (`-`). For example, an option string `"x"` recognizes an option `-x`. Only a-z, A-Z and 0-9 are allowed.
`long_options`
  An array of options. Each element in this array will be used as option strings and matched against options passed to the script starting with two hyphens (`--`). For example, an longopts element `"opt"` recognizes an option `--opt`.
`rest_index`
  If the `rest_index` parameter is present, then the index where argument parsing stopped will be written to this variable.

The `short_options` parameter may contain the following elements:

- Individual characters (do not accept values)
- Characters followed by a colon (parameter requires value)
- Characters followed by two colons (optional value)

Option values are the first argument after the string. If a value is required, it does not matter whether the value has leading white space or not. See note.

> Hinweis: Optional values do not accept `" "` (space) as a separator.

The `long_options` array values may contain:

- String (parameter does not accept any value)
- String followed by a colon (parameter requires value)
- String followed by two colons (optional value)

> Hinweis:

> The format for the `short_options` and `long_options` is almost the same, the only difference is that `long_options` takes an array of options (where each element is the option) whereas `short_options` takes a string (where each character is the option).

### Rückgabewerte

This function will return an array of option / argument pairs, Bei einem Fehler wird `false` zurückgegeben..

> Hinweis:

> The parsing of options will end at the first non-option found, anything that follows is discarded.

### Changelog

Version | Beschreibung
--- | ---
7.1.0 | Added the `rest_index` parameter.

### Beispiele

Beispiel #1 getopt() example: The basics

    <?php
    // Script example.php
    $options = getopt("f:hp:");
    var_dump($options);
    ?>

    shell> php example.php -fvalue -h

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      ["f"]=>
      string(5) "value"
      ["h"]=>
      bool(false)
    }

Beispiel #2 getopt() example: Introducing long options

    <?php
    // Script example.php
    $shortopts  = "";
    $shortopts .= "f:";  // Required value
    $shortopts .= "v::"; // Optional value
    $shortopts .= "abc"; // These options do not accept values

    $longopts  = array(
        "required:",     // Required value
        "optional::",    // Optional value
        "option",        // No value
        "opt",           // No value
    );
    $options = getopt($shortopts, $longopts);
    var_dump($options);
    ?>

    shell> php example.php -f "value for f" -v -a --required value --optional="optional value" --option

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(6) {
      ["f"]=>
      string(11) "value for f"
      ["v"]=>
      bool(false)
      ["a"]=>
      bool(false)
      ["required"]=>
      string(5) "value"
      ["optional"]=>
      string(14) "optional value"
      ["option"]=>
      bool(false)
    }

Beispiel #3 getopt() example: Passing multiple options as one

    <?php
    // Script example.php
    $options = getopt("abc");
    var_dump($options);
    ?>

    shell> php example.php -aaac

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      ["a"]=>
      array(3) {
        [0]=>
        bool(false)
        [1]=>
        bool(false)
        [2]=>
        bool(false)
      }
      ["c"]=>
      bool(false)
    }

Beispiel #4 getopt() example: Using `rest_index`

    <?php
    // Script example.php
    $rest_index = null;
    $opts = getopt('a:b:', [], $rest_index);
    $pos_args = array_slice($argv, $rest_index);
    var_dump($pos_args);

    shell> php example.php -a 1 -b 2 -- test

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      [0]=>
      string(4) "test"
    }

### Siehe auch

- $argv

# getrusage

(PHP 4, PHP 5, PHP 7, PHP 8)

getrusage — Liefert den aktuellen Wert der Ressourcenauslastung

### Beschreibung

function getrusage(int `$mode` = 0): array|false

Dies ist eine Schnittstelle zu getrusage(2). Sie gibt die Daten des Systemaufrufs zurück.

### Parameter-Liste

`mode`

  Ist `mode` 1, wird getrusage mit `RUSAGE_CHILDREN` aufgerufen.

### Rückgabewerte

Gibt ein assoziatives Array mit den Daten zurück, die der Systemaufruf ausgibt. Alle Elemente sind unter Verwendung ihres dokumentierten Feldnamens zugreifbar.

### Beispiele

Beispiel #1 getrusage()-Beispiel

    <?php
    $dat = getrusage();
    echo $dat["ru_oublock"];       // Anzahl der Blockausgabeoperationen
    echo $dat["ru_inblock"];       // Anzahl der Blockeingabeoperationen
    echo $dat["ru_msgsnd"];        // Anzahl der gesendeten IPC-Nachrichten
    echo $dat["ru_msgrcv"];        // Anzahl der empfangenen IPC-Nachrichten
    echo $dat["ru_maxrss"];        // maximale Größe des residenten Speichers im RAM
    echo $dat["ru_ixrss"];         // Gesamtgröße des gemeinsam genutzen Speichers
    echo $dat["ru_idrss"];         // Gesamtgröße der nicht gemeinsam genutzten Daten
    echo $dat["ru_minflt"];        // Anzahl der wiederhergestellten Seiten (Soft Page Faults)
    echo $dat["ru_majflt"];        // Anzahl der Seitenfehler (Hard Page Faults)
    echo $dat["ru_nsignals"];      // Anzahl der empfangenen Signale
    echo $dat["ru_nvcsw"];         // Anzahl der freiwilligen Kontextwechsel
    echo $dat["ru_nivcsw"];        // Anzahl der unfreiwilligen Kontextwechsel
    echo $dat["ru_nswap"];         // Anzahl der Auslagerungen (Swaps)
    echo $dat["ru_utime.tv_usec"]; // verwendete Benutzerzeit (Mikrosekunden)
    echo $dat["ru_utime.tv_sec"];  // verwendete Benutzerzeit (Sekunden)
    echo $dat["ru_stime.tv_usec"]; // verwendete Systemzeit (Mikrosekunden)
    echo $dat["ru_stime.tv_sec"];  // verwendete Systemzeit (Sekunden)
    ?>

### Anmerkungen

> Hinweis:

> Unter Windows gibt getrusage() nur folgende Elemente zurück:

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`
> - `"ru_majflt"` (nur wenn `mode` `RUSAGE_SELF` ist).
> - `"ru_maxrss"` (nur wenn `mode` `RUSAGE_SELF` ist).

> Wird getrusage() mit `mode` als `1` (`RUSAGE_CHILDREN`) aufgerufen, dann wird der Ressourcenverbrauch der Threads zusammengefasst (was bedeutet, dass die Funktion intern mit `RUSAGE_THREAD` aufgerufen wird).

> Hinweis:

> Unter BeOS 2000 werden nur folgende Element zurückgegeben:

> - `"ru_stime.tv_sec"`
> - `"ru_stime.tv_usec"`
> - `"ru_utime.tv_sec"`
> - `"ru_utime.tv_usec"`

### Siehe auch

- Die Manpage zu getrusage(2)

# ini_alter

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_alter — Alias von ini_set()

### Beschreibung

Diese Funktion ist ein Alias für: ini_set().

# ini_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_get — Gets the value of a configuration option

### Beschreibung

function ini_get(string `$option`): string|false

Returns the value of the configuration option on success.

### Parameter-Liste

`option`

  The configuration option name.

### Rückgabewerte

Returns the value of the configuration option as a string on success, or an empty string for `null` values. Returns `false` if the configuration option doesn't exist.

### Beispiele

Beispiel #1 A few ini_get() examples

    <?php

    /*
    Our php.ini contains the following settings:

    display_errors = On
    opcache.enable_cli = Off
    post_max_size = 8M
    */

    echo 'display_errors = ' . ini_get('display_errors') . "\n";
    echo 'opcache.enable_cli = ' . (int) ini_get('opcache.enable_cli') . "\n";
    echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
    echo 'post_max_size + 1 = ' . (rtrim(ini_get('post_max_size'), 'KMG') + 1) . "\n";
    echo 'post_max_size in bytes = ' . ini_parse_quantity(ini_get('post_max_size'));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    display_errors = 1
    opcache.enable_cli = 0
    post_max_size = 8M
    post_max_size+1 = 9
    post_max_size in bytes = 8388608

### Anmerkungen

> Hinweis: When querying boolean values

> A boolean ini value of `off` will be returned as an empty string or "0" while a boolean ini value of `on` will be returned as "1". The function can also return the literal string of INI value.

> Hinweis: When querying memory size values

> Many ini memory size values, such as upload_max_filesize, are stored in the php.ini file in shorthand notation. ini_get() will return the exact string stored in the php.ini file and NOT its int equivalent. Attempting normal arithmetic functions on these values will not have otherwise expected results. The ini_parse_quantity() function can be used to convert the shorthand notation into bytes.

> Hinweis:

> ini_get() can't read "array" ini options such as `pdo.dsn.*`, and returns `false` in this case.

### Siehe auch

- get_cfg_var() - Liefert den Wert einer Konfigurationsoption
- ini_get_all() - Gets all configuration options
- ini_parse_quantity() - Get interpreted size from ini shorthand syntax
- ini_restore() - Restores the value of a configuration option
- ini_set() - Sets the value of a configuration option

# ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_all — Gets all configuration options

### Beschreibung

function ini_get_all(?string `$extension` = `null`, bool `$details` = `true`): array|false

Returns all the registered configuration options.

### Parameter-Liste

`extension`

  An optional extension name. If not `null` or the String `core`, the function returns only options specific for that extension.

`details`

  Retrieve details settings or only the current value for each setting. Default is `true` (retrieve details).

### Rückgabewerte

Returns an associative array with directive name as the array key. Returns `false` and raises an `E_WARNING` level error if the `extension` doesn't exist.

When `details` is `true` (default) the array will contain `global_value` (set in php.ini), `local_value` (perhaps set with ini_set() or .htaccess), and `access` (the access level).

When `details` is `false` the value will be the current value of the option.

See the manual section for information on what access levels mean.

> Hinweis:

> It's possible for a directive to have multiple access levels, which is why `access` shows the appropriate bitmask values.

### Beispiele

Beispiel #1 ini_get_all() examples

    <?php
    print_r(ini_get_all("pcre"));
    print_r(ini_get_all());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [pcre.backtrack_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

        [pcre.recursion_limit] => Array
            (
                [global_value] => 100000
                [local_value] => 100000
                [access] => 7
            )

    )
    Array
    (
        [allow_call_time_pass_reference] => Array
            (
                [global_value] => 0
                [local_value] => 0
                [access] => 6
            )

        [allow_url_fopen] => Array
            (
                [global_value] => 1
                [local_value] => 1
                [access] => 4
            )

        ...

    )

Beispiel #2 Disabling `details`

    <?php
    print_r(ini_get_all("pcre", false)); // Added in PHP 5.3.0
    print_r(ini_get_all(null, false)); // Added in PHP 5.3.0
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [pcre.backtrack_limit] => 100000
        [pcre.recursion_limit] => 100000
    )
    Array
    (
        [allow_call_time_pass_reference] => 0
        [allow_url_fopen] => 1
        ...
    )

### Anmerkungen

> Hinweis:

> ini_get_all() ignores "array" ini options such as `pdo.dsn.*`.

### Siehe auch

- Wie man Konfigurationseinstellungen ändert
- ini_get() - Gets the value of a configuration option
- ini_restore() - Restores the value of a configuration option
- ini_set() - Sets the value of a configuration option
- get_loaded_extensions() - Liefert ein Array mit den Namen aller einkompilierten und geladenen Erweiterungen
- phpinfo() - Liefert Informationen zur PHP-Konfiguration
- ReflectionExtension::getINIEntries() - Gets extension ini entries

# ini_parse_quantity

(PHP 8 >= 8.2.0)

ini_parse_quantity — Get interpreted size from ini shorthand syntax

### Beschreibung

function ini_parse_quantity(string `$shorthand`): int

Returns the interpreted size in bytes on success from an ini shorthand.

### Parameter-Liste

`shorthand`

  Ini shorthand to parse, must be a number followed by an optional multiplier. The following multipliers are supported: `k`/`K` (`1024`), `m`/`M` (`1048576`), `g`/`G` (`1073741824`). The number can be a decimal, hex (prefixed with `0x` or `0X`), octal (prefixed with `0o`, `0O` or `0`) or binary (prefixed with `0b` or `0B`)

### Rückgabewerte

Returns the interpreted size in bytes as an Integer.

### Fehler/Exceptions

If the value cannot be parsed, or an invalid multiplier is used, an `E_WARNING` is raised.

### Beispiele

Beispiel #1 A few ini_parse_quantity() examples

    <?php

    var_dump(ini_parse_quantity('1024'));
    var_dump(ini_parse_quantity('1024M'));
    var_dump(ini_parse_quantity('512K'));
    var_dump(ini_parse_quantity('0xFFk'));
    var_dump(ini_parse_quantity('0b1010k'));
    var_dump(ini_parse_quantity('0o1024'));
    var_dump(ini_parse_quantity('01024'));
    var_dump(ini_parse_quantity('Foobar'));
    var_dump(ini_parse_quantity('10F'));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1024)
    int(1073741824)
    int(524288)
    int(261120)
    int(10240)
    int(532)
    int(532)

    Warning: Invalid quantity "Foobar": no valid leading digits, interpreting as "0" for backwards compatibility
    int(0)

    Warning: Invalid quantity "10F": unknown multiplier "F", interpreting as "10" for backwards compatibility
    int(10)

### Siehe auch

- ini_get() - Gets the value of a configuration option

# ini_restore

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_restore — Restores the value of a configuration option

### Beschreibung

function ini_restore(string `$option`): void

Restores a given configuration option to its original value.

### Parameter-Liste

`option`

  The configuration option name.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ini_restore() example

    <?php
    $setting = 'html_errors';

    echo 'Current value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_set($setting, ini_get($setting) ? 0 : 1);
    echo 'New value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;

    ini_restore($setting);
    echo 'Original value for \'' . $setting . '\': ' . ini_get($setting), PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Current value for 'html_errors': 1
    New value for 'html_errors': 0
    Original value for 'html_errors': 1

### Siehe auch

- ini_get() - Gets the value of a configuration option
- ini_get_all() - Gets all configuration options
- ini_set() - Sets the value of a configuration option

# ini_set

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_set — Sets the value of a configuration option

### Beschreibung

function ini_set(string `$option`, string|int|float|bool|null `$value`): string|false

Sets the value of the given configuration option. The configuration option will keep this new value during the script's execution, and will be restored at the script's ending.

### Parameter-Liste

`option`

  Not all the available options can be changed using ini_set(). There is a list of all available options in the appendix.

`value`

  The new value for the option.

### Rückgabewerte

Returns the old value on success, `false` on failure.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | `value` now accepts any scalar type (including `null`). Previously, only String values were accepted.

### Beispiele

Beispiel #1 Setting an ini option

    <?php
    echo ini_get('display_errors');

    if (!ini_get('display_errors')) {
        ini_set('display_errors', '1');
    }

    echo ini_get('display_errors');
    ?>

### Siehe auch

- get_cfg_var() - Liefert den Wert einer Konfigurationsoption
- ini_get() - Gets the value of a configuration option
- ini_get_all() - Gets all configuration options
- ini_restore() - Restores the value of a configuration option
- How to change configuration settings

# memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usage — Returns the peak of memory allocated by PHP

### Beschreibung

function memory_get_peak_usage(bool `$real_usage` = `false`): int

Returns the peak of memory, in bytes, that's been allocated to your PHP script.

### Parameter-Liste

`real_usage`

  Set this to `true` to get the real size of memory allocated from system. If not set or `false` only the memory used by `emalloc()` is reported.

### Rückgabewerte

Returns the memory peak in bytes.

### Siehe auch

- memory_get_usage() - Returns the amount of memory allocated to PHP
- memory_reset_peak_usage() - Reset the peak memory usage
- memory_limit

# memory_get_usage

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

memory_get_usage — Returns the amount of memory allocated to PHP

### Beschreibung

function memory_get_usage(bool `$real_usage` = `false`): int

Returns the amount of memory, in bytes, that's currently being allocated to your PHP script.

### Parameter-Liste

`real_usage`

  Set this to `true` to get total memory allocated from system, including unused pages. If not set or `false` only the used memory is reported.

> Hinweis:

> PHP does not track memory that is not allocated by `emalloc()`

### Rückgabewerte

Returns the memory amount in bytes.

### Beispiele

Beispiel #1 A memory_get_usage() example

    <?php
    // This is only an example, the numbers below will
    // differ depending on your system

    echo memory_get_usage() . "\n"; // 36640

    $a = str_repeat("Hello", 4242);

    echo memory_get_usage() . "\n"; // 57960

    unset($a);

    echo memory_get_usage() . "\n"; // 36744

    ?>

### Siehe auch

- memory_get_peak_usage() - Returns the peak of memory allocated by PHP
- memory_limit

# memory_reset_peak_usage

(PHP 8 >= 8.2.0)

memory_reset_peak_usage — Reset the peak memory usage

### Beschreibung

function memory_reset_peak_usage(): void

Resets the peak memory usage returned by the memory_get_peak_usage() function.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 memory_reset_peak_usage() example

    <?php

    var_dump(memory_get_peak_usage());

    $a = str_repeat("Hello", 424242);
    var_dump(memory_get_peak_usage());

    unset($a);
    memory_reset_peak_usage();

    $a = str_repeat("Hello", 2424);
    var_dump(memory_get_peak_usage());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(422440)
    int(2508672)
    int(399208)

### Siehe auch

- memory_get_peak_usage() - Returns the peak of memory allocated by PHP

# php_ini_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_file — Retrieve a path to the loaded php.ini file

### Beschreibung

function php_ini_loaded_file(): string|false

Check if a php.ini file is loaded, and retrieve its path.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The loaded php.ini path, or `false` if one is not loaded.

### Beispiele

Beispiel #1 php_ini_loaded_file() example

    <?php
    $inipath = php_ini_loaded_file();

    if ($inipath) {
        echo 'Loaded php.ini: ' . $inipath;
    } else {
        echo 'A php.ini file is not loaded';
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Loaded php.ini: /usr/local/php/php.ini

### Siehe auch

- php_ini_scanned_files() - Liefert eine Liste von analysierten .ini-Dateien aus einem zusätzlichen ini-Verzeichnis
- phpinfo() - Liefert Informationen zur PHP-Konfiguration
- The configuration file

# php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_files — Liefert eine Liste von analysierten .ini-Dateien aus einem zusätzlichen ini-Verzeichnis

### Beschreibung

function php_ini_scanned_files(): string|false

php_ini_scanned_files() gibt eine durch Kommata getrennte Liste von Konfigurationsdateien zurück, die nach php.ini analysiert wurden. Die durchsuchten Verzeichnisse werden mittels Option während des Kompilierens angegeben und optional zur Laufzeit mittels Umgebungsvariable. Weitere Informationen gibt es in der Installationsanleitung.

Die zurückgegebenen Konfigurationsdateien enthalten den kompletten Pfad.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg eine durch Kommata getrennte Liste von .ini-Dateien zurück. Jedes Komma wird gefolgt von einem Zeilenumbruch. Falls die Konfigurationsanweisung --with-config-file-scan-dir und die Umgebungsvariable PHP_INI_SCAN_DIR nicht gesetzt wurden, wird `false` zurückgegeben. Falls sie gesetzt wurden und das Verzeichnis leer ist, wird eine leere Zeichenkette zurückgegeben. Falls eine Datei unkenntlich ist, erscheint sie trotzdem in der Liste, erzeugt aber auch einen PHP-Fehler. Dieser PHP-Fehler wird sowohl bei der Kompilierung als auch bei der Verwendung von php_ini_scanned_files() angezeigt.

### Beispiele

Beispiel #1 Ein einfaches Beispiel um zurückgegebene ini-Dateien aufzulisten

    <?php
    if ($dateiliste = php_ini_scanned_files()) {
        if (strlen($dateiliste) > 0) {
            $dateien = explode(',', $dateiliste);

            foreach ($dateien as $datei) {
                echo "<li>" . trim($datei) . "</li>\n";
            }
        }
    }
    ?>

### Siehe auch

- ini_set() - Sets the value of a configuration option
- phpinfo() - Liefert Informationen zur PHP-Konfiguration
- php_ini_loaded_file() - Retrieve a path to the loaded php.ini file

# php_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_name — Liefert das zwischen PHP und Webserver verwendete Interface

### Beschreibung

function php_sapi_name(): string|false

Gibt eine Zeichenkette in Kleinbuchstaben zurück, die die von PHP verwendete Schnittstelle (das Server-API, SAPI) beschreibt. Diese Zeichenkette ist z. B. "cli" für den PHP-Kommandozeileninterpreter CLI, während beim Einsatz mit Apache unterschiedliche Werte zurückgegeben werden können, je nachdem welches SAPI verwendet wird. Die möglichen Rückgabewerte sind weiter unten aufgelistet.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Schnittstellentyp als Zeichenkette in Kleinbuchstaben zurück. Bei einem Fehler wird `false` zurückgegeben.

Mögliche Werte sind unter anderem `apache`, `apache2handler`, `cgi` (bis PHP 5.3), `cgi-fcgi`, `cli`, `cli-server`, `embed`, `fpm-fcgi`, `litespeed` und `phpdbg`.

### Beispiele

Beispiel #1 php_sapi_name()-Beispiel

Dieses Beispiel prüft auf die Teilzeichenkette `cgi`, da es auch `cgi-fcgi` sein könnte.

    <?php
    $sapi_type = php_sapi_name();
    if (substr($sapi_type, 0, 3) == 'cgi') {
        echo "Sie benutzen CGI-PHP\n";
    } else {
        echo "Sie benutzen nicht CGI-PHP\n";
    }
    ?>

### Anmerkungen

> Hinweis: Ein alternativer Ansatz

> Die PHP-Konstante `PHP_SAPI` hat den gleichen Wert wie php_sapi_name().

Tipp

# Eine mögliche Überraschung

Die definierte SAPI muss nicht naheliegend sein, denn zum Beispiel anstatt als `apache` kann sie als `apache2handler` definiert sein.

### Siehe auch

- PHP_SAPI

# php_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_uname — Returns information about the operating system PHP is running on

### Beschreibung

function php_uname(string `$mode` = "a"): string

php_uname() returns a description of the operating system PHP is running on. This is the same string you see at the very top of the phpinfo() output. For the name of just the operating system, consider using the `PHP_OS` constant, but keep in mind this constant will contain the operating system PHP was built on.

On some older UNIX platforms, it may not be able to determine the current OS information in which case it will revert to displaying the OS PHP was built on. This will only happen if your uname() library call either doesn't exist or doesn't work.

### Parameter-Liste

`mode`

  `mode` is a single character that defines what information is returned:

  - `'a'`: This is the default. Returns the same information as the individual modes `'s'`, `'n'`, `'r'`, `'v'`, `'m'` separated by spaces.

  - `'s'`: Operating system name. eg. `FreeBSD`.
  - `'n'`: Host name. eg. `localhost.example.com`.
  - `'r'`: Release name. eg. `5.1.2-RELEASE`.
  - `'v'`: Version information. Varies a lot between operating systems.
  - `'m'`: Machine type. eg. `i386`.

### Rückgabewerte

Returns the description, as a string.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Throws a ValueError when an invalid `mode` is specified.

### Beispiele

Beispiel #1 Some php_uname() examples

    <?php
    echo php_uname();
    echo PHP_OS;

    /* Some possible outputs:
    Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
    Linux

    FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
    FreeBSD

    Windows NT XN1 5.1 build 2600
    WINNT
    */

    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
        echo 'This is a server using Windows!';
    } else {
        echo 'This is a server not using Windows!';
    }

    ?>

There are also some related Predefined PHP constants that may come in handy, for example:

Beispiel #2 A few OS related constant examples

    <?php
    // *nix
    echo DIRECTORY_SEPARATOR; // /
    echo PHP_SHLIB_SUFFIX;    // so
    echo PATH_SEPARATOR;      // :

    // Win*
    echo DIRECTORY_SEPARATOR; // \
    echo PHP_SHLIB_SUFFIX;    // dll
    echo PATH_SEPARATOR;      // ;
    ?>

### Siehe auch

- phpversion() - Liefert die aktuelle PHP-Version
- php_sapi_name() - Liefert das zwischen PHP und Webserver verwendete Interface
- phpinfo() - Liefert Informationen zur PHP-Konfiguration

# phpcredits

(PHP 4, PHP 5, PHP 7, PHP 8)

phpcredits — Prints out the credits for PHP

### Beschreibung

function phpcredits(int `$flags` = `CREDITS_ALL`): true

This function prints out the credits listing the PHP developers, modules, etc. It generates the appropriate HTML codes to insert the information in a page.

### Parameter-Liste

`flags`

  To generate a custom credits page, you may want to use the `flags` parameter.

  Pre-defined phpcredits() flags
  name | description
  --- | ---
  CREDITS_ALL | All the credits, equivalent to using: `CREDITS_DOCS` + `CREDITS_GENERAL` + `CREDITS_GROUP` + `CREDITS_MODULES` + `CREDITS_FULLPAGE`. It generates a complete stand-alone HTML page with the appropriate tags.
  CREDITS_DOCS | The credits for the documentation team
  CREDITS_FULLPAGE | Usually used in combination with the other flags. Indicates that a complete stand-alone HTML page needs to be printed including the information indicated by the other flags.
  CREDITS_GENERAL | General credits: Language design and concept, PHP authors and SAPI module.
  CREDITS_GROUP | A list of the core developers
  CREDITS_MODULES | A list of the extension modules for PHP, and their authors
  CREDITS_SAPI | A list of the server API modules for PHP, and their authors

### Rückgabewerte

Gibt immer `true` zurück.

### Beispiele

Beispiel #1 Prints the general credits

    <?php
    phpcredits(CREDITS_GENERAL);
    ?>

Beispiel #2 Prints the core developers and the documentation group

    <?php
    phpcredits(CREDITS_GROUP | CREDITS_DOCS | CREDITS_FULLPAGE);
    ?>

Beispiel #3 Printing all the credits

    <html>
     <head>
      <title>My credits page</title>
     </head>
     <body>
    <?php
    // some code of your own
    phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
    // some more code
    ?>
     </body>
    </html>

### Anmerkungen

> Hinweis:

> phpcredits() outputs plain text instead of HTML when using the CLI mode.

### Siehe auch

- phpversion() - Liefert die aktuelle PHP-Version
- phpinfo() - Liefert Informationen zur PHP-Konfiguration

# phpinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

phpinfo — Liefert Informationen zur PHP-Konfiguration

### Beschreibung

function phpinfo(int `$flags` = `INFO_ALL`): true

Zeigt eine große Anzahl von Informationen über den aktuellen Zustand von PHP an. Dies umfasst Informationen über die Optionen während des Kompilierens und die Erweiterungen, die PHP-Version, Server-Informationen und -Umgebung (falls als Modul kompiliert), die PHP-Umgebung, Versionsinformationen zum Betriebssystem, Pfade, Master- und lokale Werte der Konfigurationsoptionen, HTTP-Header und die PHP-Lizenz.

Weil jedes System anders installiert ist, wird phpinfo() oft genutzt, um die Konfigurationseinstellungen und die verfügbaren vordefinierten Variablen auf einem System zu prüfen.

phpinfo() ist außerdem ein wertvolles Debugging-Tool, da es alle EGPCS-Daten (Environment, GET, POST, Cookie, Server) enthält.

### Parameter-Liste

`flags`

  Die Ausgabe kann durch die bitweise summierte Angabe von einer oder mehrerer der folgenden Konstanten im optionalen Parameter `flags` angepasst werden. Die Konstanten oder Bitwerte können auch mit dem binären Oder-Operator kombiniert werden.

  phpinfo()-Optionen
  Name (Konstante) | Wert | Beschreibung
  --- | --- | ---
  INFO_GENERAL | 1 | Die Konfigurationszeile, der Ort der php.ini, das Übersetzungsdatum, der Webserver, das System und mehr.
  INFO_CREDITS | 2 | PHP-Credits. Siehe auch phpcredits().
  INFO_CONFIGURATION | 4 | Aktueller lokaler und Master-Wert der PHP-Direktiven. Siehe auch ini_get().
  INFO_MODULES | 8 | Die geladenenen Module und ihre jeweiligen Einstellungen. Siehe auch get_loaded_extensions().
  INFO_ENVIRONMENT | 16 | Informationen über die Umgebungsvariablen, die auch in $_ENV verfügbar sind.
  INFO_VARIABLES | 32 | Zeigt alle vordefinierten Variablen aus EGPCS (Environment, GET, POST, Cookie, Server).
  INFO_LICENSE | 64 | PHP-Lizenz-Informationen. Siehe auch » Lizenz-FAQ.
  INFO_ALL | -1 | Zeigt alle genannten Informationen.

### Rückgabewerte

Gibt immer `true` zurück.

### Beispiele

Beispiel #1 phpinfo()-Beispiel

    <?php

    // Zeigt alle Informationen (Standardwert ist INFO_ALL)
    phpinfo();

    // Zeigt nur die Modul-Informationen.
    // phpinfo(8) führt zum gleichen Ergebnis.
    phpinfo(INFO_MODULES);

    ?>

### Anmerkungen

> Hinweis:

> In PHP-Versionen vor 5.5 sind Teile der angezeigten Informationen deaktiviert, wenn die Konfigurationseinstellung expose_php auf `off` eingestellt ist. Das beinhaltet die PHP- und Zend-Logos und die Danksagung.

> Hinweis:

> Wenn phpinfo() im CLI-Modus verwendet wird, gibt es reinen Text statt HTML aus.

### Siehe auch

- phpversion() - Liefert die aktuelle PHP-Version
- phpcredits() - Prints out the credits for PHP
- ini_get() - Gets the value of a configuration option
- ini_set() - Sets the value of a configuration option
- get_loaded_extensions() - Liefert ein Array mit den Namen aller einkompilierten und geladenen Erweiterungen
- vordefinierte Variable

# phpversion

(PHP 4, PHP 5, PHP 7, PHP 8)

phpversion — Liefert die aktuelle PHP-Version

### Beschreibung

function phpversion(?string `$extension` = `null`): string|false

Gibt die Versionsnummer der gerade laufenden PHP-Version oder der angegebenen Erweiterung als Zeichenkette zurück.

### Parameter-Liste

`extension`

  Der optionale Name einer Erweiterung.

### Rückgabewerte

Gibt die Versionsnummer der gerade laufenden PHP-Version als String zurück. Wenn ein String-Argument für den Parameter `extension` angegeben wurde, wird die Versionsnummer dieser Erweiterung zurückgegeben, oder `false`, falls die Erweiterung nicht geladen ist oder keine Versionsinformationen enthält.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `extension` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 phpversion()-Beispiel

    <?php

    // gibt z. B. 'Die aktuelle PHP-Version ist 8.3.12' aus
    echo 'Die aktuelle PHP Version ist ' . phpversion();

    // Gibt z. B. '1.22.3' aus oder nichts, falls die Erweiterung nicht aktiviert ist
    echo phpversion('zip');

    ?>

Beispiel #2 `PHP_VERSION_ID`-Beispiel und -Verwendung

    <?php

    /**
     * PHP_VERSION_ID ist als Zahl definiert; je höher diese ist,
     * desto neuer ist die PHP-Version. Es ist wie oben angegeben definiert:
     *
     * $version_id = $major_version * 10000 + $minor_version * 100 + $release_version;
     *
     * Nun kann PHP_VERSION_ID verwendet werden, um zu prüfen, ob diese PHP-Version
     * bestimmte Features unterstützt, ohne jedesmal version_compare() verwenden zu
     * müssen, um zu prüfen, ob die aktuelle PHP-Version bestimmte Features nicht
     * unterstützt.
     *
     * Beispielsweise können wir so die PHP_*_VERSION-Konstanten definieren,
     * die in Versionen vor 5.2.7 nicht verfügbar waren.
     */

    if (PHP_VERSION_ID < 50207) {
        define('PHP_MAJOR_VERSION',   $version[0]);
        define('PHP_MINOR_VERSION',   $version[1]);
        define('PHP_RELEASE_VERSION', $version[2]);

        // und so weiter, ...
    }

    ?>

### Anmerkungen

> Hinweis:

> Diese Information ist ebenfalls in der vordefinierten Konstante `PHP_VERSION` verfügbar. Weitere Versionsinformationen sind durch die Verwendung der `PHP_*_VERSION`-Konstanten verfügbar.

> Hinweis:

> Manche Erweiterungen definieren zwar ihre eigene Versionsnummer, aber die meisten der integrierten Erweiterungen verwenden die PHP-Version als Versionsnummer.

### Siehe auch

- PHP_VERSION-Konstanten
- version_compare() - Vergleicht zwei Versionsnummer-Zeichenketten im PHP-Versionsformat
- phpinfo() - Liefert Informationen zur PHP-Konfiguration
- phpcredits() - Prints out the credits for PHP
- zend_version() - Liefert die aktuelle Version der Zend-Engine

# putenv

(PHP 4, PHP 5, PHP 7, PHP 8)

putenv — Setzt den Wert einer Umgebungsvariablen

### Beschreibung

function putenv(string `$assignment`): bool

Fügt `assignment` zur Server-Umgebung hinzu. Die Umgebungsvariable existiert nur für die Dauer der aktuellen Anfrage. Am Ende der Anfrage wird der Originalzustand der Umgebung wiederhergestellt.

### Parameter-Liste

`assignment`

  Die Einstellung, beispielsweise `"FOO=BAR"`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Setzen einer Umgebungsvariablen

    <?php
    putenv("UNIQID=$uniqid");
    ?>

### Siehe auch

- getenv() - Liefert den Wert einer einzelnen oder aller Umgebungsvariablen
- apache_setenv() - Setzt eine Apache-Subprocess_env-Variable

# restore_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

restore_include_path — Restores the value of the include_path configuration option

Warnung

Diese Funktion ist seit PHP 7.4.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function restore_include_path(): void

Restores the include_path configuration option back to its original master value as set in php.ini

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion wurde entfernt.
7.4.0 | Diese Funktion wurde als veraltet eingestuft.

### Beispiele

Beispiel #1 restore_include_path() example

    <?php

    echo get_include_path();  // .:/usr/local/lib/php

    set_include_path('/inc');

    echo get_include_path();  // /inc

    restore_include_path();

    // Or using ini_restore()
    ini_restore('include_path');

    echo get_include_path();  // .:/usr/local/lib/php

    ?>

### Siehe auch

- ini_restore() - Restores the value of a configuration option
- get_include_path() - Gets the current include_path configuration option
- set_include_path() - Setzt die Konfigurationsoption include_path
- include - include

# set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_path — Setzt die Konfigurationsoption include_path

### Beschreibung

function set_include_path(string `$include_path`): string|false

Setzt die Konfigurationsoption include_path für die Dauer der Ausführung des Skripts.

### Parameter-Liste

`include_path`

  Der neue Wert für den include_path.

### Rückgabewerte

Gibt bei Erfolg den alten include_path zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 set_include_path()-Beispiel

    <?php
    set_include_path('/usr/lib/pear');

    // Oder mit ini_set()
    ini_set('include_path', '/usr/lib/pear');
    ?>

Beispiel #2 Den include-path erweitern

Wenn man die Konstante `PATH_SEPARATOR` verwendet, ist es möglich, den `include_path` ohne Kenntnis des verwendeten Betriebssystems zu erweitern.

In diesem Beispiel fügen wir /usr/lib/pear ans Ende des vorhandenen `include_path` an.

    <?php
    $path = '/usr/lib/pear';
    set_include_path(get_include_path() . PATH_SEPARATOR . $path);
    ?>

### Siehe auch

- ini_set() - Sets the value of a configuration option
- get_include_path() - Gets the current include_path configuration option
- restore_include_path() - Restores the value of the include_path configuration option
- include - include

# set_time_limit

(PHP 4, PHP 5, PHP 7, PHP 8)

set_time_limit — Beschränkt die maximale Ausführungszeit

### Beschreibung

function set_time_limit(int `$seconds`): bool

Legt die Zeit in Sekunden fest, die ein Skript laufen darf. Ist diese Zeit abgelaufen, wird ein schwerwiegender Fehler zurückgegeben. Der Standard liegt bei 30 Sekunden, es sei denn `max_execution_time` wurde in php.ini gesetzt.

Wenn set_time_limit() aufgerufen wird, dann startet der Zähler neu. Das heißt, wenn die Standardeinstellung 30 Sekunden beträgt und nach 25 Sekunden durch ein Skript ein Aufruf wie z. B. `set_time_limit(20)` erfolgt, darf das Skript insgesamt 45 Sekunden laufen, bevor eine Fehlermeldung ausgegeben wird.

### Parameter-Liste

`seconds`

  Die maximale Ausführungszeit in Sekunden oder 0, wenn die Ausführungszeit nicht limitiert werden soll.

### Rückgabewerte

Gibt im Erfolgsfall `true` zurück oder `false` bei einem Fehler.

### Anmerkungen

> Hinweis:

> Die Funktion set_time_limit() und die Konfigurationsdirektive max_execution_time beschränken nur die Ausführungszeit des Skripts selbst. Die Zeit, die für Aktivitäten außerhalb des Skripts aufgebracht wird, wie z. B. die Ausführung von Systemaufrufen mit system(), Streamoperationen, Datenbankabfragen usw., wird nicht in die Berechnung der Ausführungszeit mit einbezogen.

### Siehe auch

- max_execution_time
- max_input_time

# sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dir — Returns directory path used for temporary files

### Beschreibung

function sys_get_temp_dir(): string

Returns the path of the directory PHP stores temporary files in by default.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the path of the temporary directory.

### Beispiele

Beispiel #1 sys_get_temp_dir() example

    <?php
    // Create a temporary file in the temporary
    // files directory using sys_get_temp_dir()
    $temp_file = tempnam(sys_get_temp_dir(), 'Tux');

    echo $temp_file;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    C:\Windows\Temp\TuxA318.tmp

### Siehe auch

- tmpfile() - Erstellt eine temporäre Datei
- tempnam() - Erzeugt eine Datei mit eindeutigem Dateinamen

# version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compare — Vergleicht zwei Versionsnummer-Zeichenketten im PHP-Versionsformat

### Beschreibung

function version_compare(string `$version1`, string `$version2`, ?string `$operator` = `null`): int|bool

version_compare() vergleicht zwei dem PHP-Versionsformat angeglichene Versionsnummer-Zeichenketten.

Zuerst ersetzt die Funktion `_`, `-` und `+` durch einen Punkt `.` in den Versionsangaben und setzt vor und nach jeder Kette aus nicht-numerischen Zeichen Punkte ein, sodass beispielsweise '4.3.2RC1' zu '4.3.2.RC.1' wird. Anschließend werden von links nach rechts die Teile verglichen. Wenn ein Teil spezielle Zeichen enthält, werden diese nach der folgenden Reihenfolge behandelt: `jede Zeichenkette, die nicht in dieser Liste vorkommt` < `dev` < `alpha` = `a` < `beta` = `b` < `RC` = `rc` < `#` < `pl` = `p`. Auf diese Weise können nicht nur Versionen verschiedener Tiefe wie '4.1' und '4.1.2', sondern auch alle anderen Versionen verglichen werden, die sich auf bestimmte Entwicklungsstadien von PHP beziehen.

### Parameter-Liste

`version1`

  Die erste Versionsnummer.

`version2`

  Die zweite Versionsnummer.

`operator`

  Ein optionaler Parameter; mögliche Operatoren sind: `<`, `lt`, `<=`, `le`, `>`, `gt`, `>=`, `ge`, `==`, `=`, `eq`, `!=`, `<>` und `ne`.

  Dieser Parameter berücksicht die Groß- und Kleinschreibung. Die Werte sollten alle kleingeschrieben werden.

### Rückgabewerte

Standardmäßig gibt version_compare() `-1` zurück, wenn die erste Version kleiner ist als die zweite, `0`, wenn die Versionen gleich sind und `1`, wenn die zweite Version kleiner ist.

Wenn der optionale Parameter `operator` übergeben wurde, gibt die Funktion `true` oder `false` zurück, je nach dem, ob das mit dem Operator definierte Verhältnis der Wahrheit entspricht oder nicht.

### Beispiele

Das untenstehende Beispiel verwendet die Konstante `PHP_VERSION`, die die Version des aktuell ausführenden PHP-Interpreters enthält.

Beispiel #1 version_compare()-Beispiele

    <?php
    if (version_compare(PHP_VERSION, '7.0.0') >= 0) {
        echo 'Ich bin mindestens PHP 7.0.0, meine Version: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
        echo 'Ich bin mindestens PHP 5.3.0, meine Version: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '>=')) {
        echo 'Ich bin mindestens PHP 5.0.0, meine Version: ' . PHP_VERSION . "\n";
    }

    if (version_compare(PHP_VERSION, '5.0.0', '<')) {
        echo 'Ich bin noch PHP 4, meine Version: ' . PHP_VERSION . "\n";
    }
    ?>

### Anmerkungen

> Hinweis:

> Die Konstante `PHP_VERSION` enthält die aktuelle PHP-Version

> Hinweis:

> Vorveröffentlichte Versionen wie 5.3.0-dev werden als kleiner erkannt als ihre finalen Veröffentlichungen (wie 5.3.0).

> Hinweis:

> Bei besonderen Versionszeichenketten wie `alpha` und `beta` wird zwischen Groß-/Kleinschreibung unterschieden. Versionszeichenketten aus beliebigen Quellen, die nicht den PHP-Standard einhalten, müssen bei Bedarf mit strtolower() in Kleinschreibung umgewandelt werden, bevor version_compare() aufgerufen wird.

### Siehe auch

- phpversion() - Liefert die aktuelle PHP-Version
- php_uname() - Returns information about the operating system PHP is running on
- function_exists() - Falls die angegebene Funktion definiert ist, wird true zurück gegeben

# zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_id — Liefert eine eindeutige ID für den aktuellen Thread

### Beschreibung

function zend_thread_id(): int

Diese Funktion gibt eine eindeutige ID für den aktuellen Thread zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Thread-ID als Integer zurück.

### Beispiele

Beispiel #1 zend_thread_id()-Beispiel

    <?php
    $thread_id = zend_thread_id();

    echo 'Der aktuelle Thread ist: ' . $thread_id;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Der aktuelle Thread ist: 7864

### Anmerkungen

> Hinweis:

> Diese Funktion ist nur verfügbar, wenn PHP mit ZTS- (Zend Thread Safety) und Debug- (`--enable-debug`) Unterstützung kompiliert wurde.

# zend_version

(PHP 4, PHP 5, PHP 7, PHP 8)

zend_version — Liefert die aktuelle Version der Zend-Engine

### Beschreibung

function zend_version(): string

Liefert die Versionsnummer der aktuell laufenden Zend-Engine als Zeichenkette.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert die Versionsnummer der Zend-Engine als Zeichenkette.

### Beispiele

Beispiel #1 zend_version()-Beispiel

    <?php
    echo "Zend-Engine-Version: " . zend_version();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Zend-Engine-Version: 2.2.0

### Siehe auch

- phpinfo() - Liefert Informationen zur PHP-Konfiguration
- phpcredits() - Prints out the credits for PHP
- phpversion() - Liefert die aktuelle PHP-Version

## Inhaltsverzeichnis

- assert — Überprüft eine Assertion (Zusicherung)
- assert_options — Setzt oder liefert Assert-Optionen
- cli_get_process_title — Returns the current process title
- cli_set_process_title — Sets the process title
- dl — Lädt eine PHP-Erweiterung zur Laufzeit
- extension_loaded — Prüft, ob eine Erweiterung geladen ist
- gc_collect_cycles — Forces collection of any existing garbage cycles
- gc_disable — Deactivates the circular reference collector
- gc_enable — Activates the circular reference collector
- gc_enabled — Returns status of the circular reference collector
- gc_mem_caches — Reclaims memory used by the Zend Engine memory manager
- gc_status — Gets information about the garbage collector
- get_cfg_var — Liefert den Wert einer Konfigurationsoption
- get_current_user — Liefert den Benutzernamen des Besitzers des aktuellen PHP-Skripts
- get_defined_constants — Returns an associative array with the names of all the constants and their values
- get_extension_funcs — Liefert die Namen der Funktionen einer Erweiterung
- get_include_path — Gets the current include_path configuration option
- get_included_files — Liefert ein Array mit den Namen der eingebundenen Dateien
- get_loaded_extensions — Liefert ein Array mit den Namen aller einkompilierten und geladenen Erweiterungen
- get_magic_quotes_gpc — Liefert die aktuelle Konfiguration von magic_quotes_gpc
- get_magic_quotes_runtime — Liefert die aktuelle Konfiguration von magic_quotes_runtime
- get_required_files — Alias von get_included_files
- get_resources — Returns active resources
- getenv — Liefert den Wert einer einzelnen oder aller Umgebungsvariablen
- getlastmod — Liefert die Uhrzeit der letzten Änderung eines Skripts
- getmygid — Get PHP script owner's GID
- getmyinode — Liefert den Inode des aktuellen Skripts
- getmypid — Liefert die Prozess-ID eines Skripts
- getmyuid — Liefert die User-ID des Besitzers eines PHP-Skripts
- getopt — Gets options from the command line argument list
- getrusage — Liefert den aktuellen Wert der Ressourcenauslastung
- ini_alter — Alias von ini_set
- ini_get — Gets the value of a configuration option
- ini_get_all — Gets all configuration options
- ini_parse_quantity — Get interpreted size from ini shorthand syntax
- ini_restore — Restores the value of a configuration option
- ini_set — Sets the value of a configuration option
- memory_get_peak_usage — Returns the peak of memory allocated by PHP
- memory_get_usage — Returns the amount of memory allocated to PHP
- memory_reset_peak_usage — Reset the peak memory usage
- php_ini_loaded_file — Retrieve a path to the loaded php.ini file
- php_ini_scanned_files — Liefert eine Liste von analysierten .ini-Dateien aus einem zusätzlichen ini-Verzeichnis
- php_sapi_name — Liefert das zwischen PHP und Webserver verwendete Interface
- php_uname — Returns information about the operating system PHP is running on
- phpcredits — Prints out the credits for PHP
- phpinfo — Liefert Informationen zur PHP-Konfiguration
- phpversion — Liefert die aktuelle PHP-Version
- putenv — Setzt den Wert einer Umgebungsvariablen
- restore_include_path — Restores the value of the include_path configuration option
- set_include_path — Setzt die Konfigurationsoption include_path
- set_time_limit — Beschränkt die maximale Ausführungszeit
- sys_get_temp_dir — Returns directory path used for temporary files
- version_compare — Vergleicht zwei Versionsnummer-Zeichenketten im PHP-Versionsformat
- zend_thread_id — Liefert eine eindeutige ID für den aktuellen Thread
- zend_version — Liefert die aktuelle Version der Zend-Engine

- Installation/Konfiguration
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- PHP-Optionen-/-Informationen-Funktionen
  - assert — Überprüft eine Assertion (Zusicherung)
  - assert_options — Setzt oder liefert Assert-Optionen
  - cli_get_process_title — Returns the current process title
  - cli_set_process_title — Sets the process title
  - dl — Lädt eine PHP-Erweiterung zur Laufzeit
  - extension_loaded — Prüft, ob eine Erweiterung geladen ist
  - gc_collect_cycles — Forces collection of any existing garbage cycles
  - gc_disable — Deactivates the circular reference collector
  - gc_enable — Activates the circular reference collector
  - gc_enabled — Returns status of the circular reference collector
  - gc_mem_caches — Reclaims memory used by the Zend Engine memory manager
  - gc_status — Gets information about the garbage collector
  - get_cfg_var — Liefert den Wert einer Konfigurationsoption
  - get_current_user — Liefert den Benutzernamen des Besitzers des aktuellen PHP-Skripts
  - get_defined_constants — Returns an associative array with the names of all the constants and their values
  - get_extension_funcs — Liefert die Namen der Funktionen einer Erweiterung
  - get_include_path — Gets the current include_path configuration option
  - get_included_files — Liefert ein Array mit den Namen der eingebundenen Dateien
  - get_loaded_extensions — Liefert ein Array mit den Namen aller einkompilierten und geladenen Erweiterungen
  - get_magic_quotes_gpc — Liefert die aktuelle Konfiguration von magic_quotes_gpc
  - get_magic_quotes_runtime — Liefert die aktuelle Konfiguration von magic_quotes_runtime
  - get_required_files — Alias von get_included_files
  - get_resources — Returns active resources
  - getenv — Liefert den Wert einer einzelnen oder aller Umgebungsvariablen
  - getlastmod — Liefert die Uhrzeit der letzten Änderung eines Skripts
  - getmygid — Get PHP script owner's GID
  - getmyinode — Liefert den Inode des aktuellen Skripts
  - getmypid — Liefert die Prozess-ID eines Skripts
  - getmyuid — Liefert die User-ID des Besitzers eines PHP-Skripts
  - getopt — Gets options from the command line argument list
  - getrusage — Liefert den aktuellen Wert der Ressourcenauslastung
  - ini_alter — Alias von ini_set
  - ini_get — Gets the value of a configuration option
  - ini_get_all — Gets all configuration options
  - ini_parse_quantity — Get interpreted size from ini shorthand syntax
  - ini_restore — Restores the value of a configuration option
  - ini_set — Sets the value of a configuration option
  - memory_get_peak_usage — Returns the peak of memory allocated by PHP
  - memory_get_usage — Returns the amount of memory allocated to PHP
  - memory_reset_peak_usage — Reset the peak memory usage
  - php_ini_loaded_file — Retrieve a path to the loaded php.ini file
  - php_ini_scanned_files — Liefert eine Liste von analysierten .ini-Dateien aus einem zusätzlichen ini-Verzeichnis
  - php_sapi_name — Liefert das zwischen PHP und Webserver verwendete Interface
  - php_uname — Returns information about the operating system PHP is running on
  - phpcredits — Prints out the credits for PHP
  - phpinfo — Liefert Informationen zur PHP-Konfiguration
  - phpversion — Liefert die aktuelle PHP-Version
  - putenv — Setzt den Wert einer Umgebungsvariablen
  - restore_include_path — Restores the value of the include_path configuration option
  - set_include_path — Setzt die Konfigurationsoption include_path
  - set_time_limit — Beschränkt die maximale Ausführungszeit
  - sys_get_temp_dir — Returns directory path used for temporary files
  - version_compare — Vergleicht zwei Versionsnummer-Zeichenketten im PHP-Versionsformat
  - zend_thread_id — Liefert eine eindeutige ID für den aktuellen Thread
  - zend_version — Liefert die aktuelle Version der Zend-Engine

# Interactive PHP Debugger

# Einführung

Implemented as a SAPI module, phpdbg can exert complete control over the environment without impacting the functionality or performance of your code.

phpdbg aims to be a lightweight, powerful, easy to use debugging platform for PHP. It offers the following features:

- Step-Through Debugging
- Flexible Breakpoints (Class Method, Function, File:Line, Address, Opcode)
- Easy Access to PHP with built-in eval()
- Userland API
- SAPI Agnostic - Easily Integrated
- PHP Configuration File Support
- JIT Super Globals - Set Your Own !!
- Optional readline Support - Comfortable Terminal Operation
- Easy Operation - See Help :)

Command line options
Option | Example Argument | Description
--- | --- | ---
-c | -c/my/php.ini | Set php.ini file to load
-d | -dmemory_limit=4G | Set a php.ini directive
-n |  | Disable default php.ini
-q |  | Suppress welcome banner
-v |  | Enable oplog output
-b |  | Disable color
-i | -imy.init | Set .phpdbginit file
-I |  | Ignore default .phpdbginit
-O | -Omy.oplog | Set oplog output file
-r |  | Run execution context
-rr |  | Run execution context and quit after execution (not respecting breakpoints)
-e |  | Generate extended information for debugger/profiler
-E |  | Enable step through eval, careful!
-s | -s=, -s=foo | Read code to execute from stdin with an optional delimiter
-S | -Scli | Override SAPI name, careful!
-l | -l4000 | Setup remote console ports
-a | -a192.168.0.3 | Setup remote console bind address
-x |  | Enable xml output (instead of normal text output)
-p | -p, -p=func, -p* | Output opcodes and quit
-h |  | Print the help overview
-V |  | Print version number
-- | -- arg1 arg2 | Use to delimit phpdbg arguments and php $argv; append any $argv argument after it

# Installation/Konfiguration

## Inhaltsverzeichnis

- Laufzeit-Konfiguration

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

phpdbg Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
phpdbg.eol | 2 | `INI_ALL` | Removed as of PHP 8.1.0
phpdbg.path |  | 6 | Removed as of PHP 8.1.0

Hier eine kurze Erklärung der Konfigurationsoptionen:

`phpdbg.eol` mixed

  The kind of line ending to use for output. For setting the value, one of the string aliases must be used.

  int Value | string Alias
  --- | ---
  `0` | `CRLF`, `crlf`, `DOS`, `dos`
  `1` | `LF`, `lf`, `UNIX`, `unix`
  `2` | `CR`, `cr`, `MAC`, `mac`

`phpdbg.path` string

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`PHPDBG_VERSION` (string)
`PHPDBG_FILE` (int)
  Removed as of PHP 7.3.0.
`PHPDBG_METHOD` (int)
  Removed as of PHP 7.3.0.
`PHPDBG_LINENO` (int)
  Removed as of PHP 7.3.0.
`PHPDBG_FUNC` (int)
  Removed as of PHP 7.3.0.
`PHPDBG_COLOR_PROMPT` (int)
`PHPDBG_COLOR_NOTICE` (int)
`PHPDBG_COLOR_ERROR` (int)

# phpdbg Funktionen

# phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_file — Inserts a breakpoint at a line in a file

### Beschreibung

function phpdbg_break_file(string `$file`, int `$line`): void

Insert a breakpoint at the given `line` in the given `file`.

### Parameter-Liste

`file`
  The name of the file.
`line`
  The line number.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- phpdbg_break_function() - Inserts a breakpoint at entry to a function
- phpdbg_break_method() - Inserts a breakpoint at entry to a method
- phpdbg_break_next() - Inserts a breakpoint at the next opcode
- phpdbg_clear() - Clears all breakpoints

# phpdbg_break_function

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_function — Inserts a breakpoint at entry to a function

### Beschreibung

function phpdbg_break_function(string `$function`): void

Insert a breakpoint at the entry to the given `function`.

### Parameter-Liste

`function`
  The name of the function.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- phpdbg_break_file() - Inserts a breakpoint at a line in a file
- phpdbg_break_method() - Inserts a breakpoint at entry to a method
- phpdbg_break_next() - Inserts a breakpoint at the next opcode
- phpdbg_clear() - Clears all breakpoints

# phpdbg_break_method

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_method — Inserts a breakpoint at entry to a method

### Beschreibung

function phpdbg_break_method(string `$class`, string `$method`): void

Insert a breakpoint at the entry to the given `method` of the given `class`.

### Parameter-Liste

`class`
  The name of the class.
`method`
  The name of the method.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- phpdbg_break_file() - Inserts a breakpoint at a line in a file
- phpdbg_break_function() - Inserts a breakpoint at entry to a function
- phpdbg_break_next() - Inserts a breakpoint at the next opcode
- phpdbg_clear() - Clears all breakpoints

# phpdbg_break_next

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_next — Inserts a breakpoint at the next opcode

### Beschreibung

function phpdbg_break_next(): void

Insert a breakpoint at the next opcode.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- phpdbg_break_file() - Inserts a breakpoint at a line in a file
- phpdbg_break_function() - Inserts a breakpoint at entry to a function
- phpdbg_break_method() - Inserts a breakpoint at entry to a method
- phpdbg_clear() - Clears all breakpoints

# phpdbg_clear

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_clear — Clears all breakpoints

### Beschreibung

function phpdbg_clear(): void

Clear all breakpoints that have been set, either via one of the phpdbg_break_*() functions or interactively in the console.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- phpdbg_break_file() - Inserts a breakpoint at a line in a file
- phpdbg_break_function() - Inserts a breakpoint at entry to a function
- phpdbg_break_method() - Inserts a breakpoint at entry to a method
- phpdbg_break_next() - Inserts a breakpoint at the next opcode

# phpdbg_color

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_color — Sets the color of certain elements

### Beschreibung

function phpdbg_color(int `$element`, string `$color`): void

Set the `color` of the given `element`.

### Parameter-Liste

`element`
  One of the `PHPDBG_COLOR_*` constants.
`color`
  The name of the color. One of `white`, `red`, `green`, `yellow`, `blue`, `purple`, `cyan` or `black`, optionally with either a trailing `-bold` or `-underline`, for instance, `white-bold` or `green-underline`.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- phpdbg_prompt() - Sets the command prompt

# phpdbg_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog — Ends an oplog

### Beschreibung

function phpdbg_end_oplog(array `$options` = []): ?array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`options`

### Rückgabewerte

# phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_exec — Attempts to set the execution context

### Beschreibung

function phpdbg_exec(string `$context`): string|bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`context`

### Rückgabewerte

If the execution context was set previously it is returned. If the execution context was not set previously `true` is returned. If the request to set the context fails, `false` is returned, and an `E_WARNING` raised.

# phpdbg_get_executable

(PHP 7, PHP 8)

phpdbg_get_executable — Gets executable

### Beschreibung

function phpdbg_get_executable(array `$options` = []): array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`options`

### Rückgabewerte

# phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_prompt — Sets the command prompt

### Beschreibung

function phpdbg_prompt(string `$string`): void

Set the command prompt to the given `string`.

### Parameter-Liste

`string`
  The string to use as command prompt.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- phpdbg_color() - Sets the color of certain elements

# phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog — Startet ein Oplog

### Beschreibung

function phpdbg_start_oplog(): void

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

## Inhaltsverzeichnis

- phpdbg_break_file — Inserts a breakpoint at a line in a file
- phpdbg_break_function — Inserts a breakpoint at entry to a function
- phpdbg_break_method — Inserts a breakpoint at entry to a method
- phpdbg_break_next — Inserts a breakpoint at the next opcode
- phpdbg_clear — Clears all breakpoints
- phpdbg_color — Sets the color of certain elements
- phpdbg_end_oplog — Ends an oplog
- phpdbg_exec — Attempts to set the execution context
- phpdbg_get_executable — Gets executable
- phpdbg_prompt — Sets the command prompt
- phpdbg_start_oplog — Startet ein Oplog

- Installation/Konfiguration
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- phpdbg Funktionen
  - phpdbg_break_file — Inserts a breakpoint at a line in a file
  - phpdbg_break_function — Inserts a breakpoint at entry to a function
  - phpdbg_break_method — Inserts a breakpoint at entry to a method
  - phpdbg_break_next — Inserts a breakpoint at the next opcode
  - phpdbg_clear — Clears all breakpoints
  - phpdbg_color — Sets the color of certain elements
  - phpdbg_end_oplog — Ends an oplog
  - phpdbg_exec — Attempts to set the execution context
  - phpdbg_get_executable — Gets executable
  - phpdbg_prompt — Sets the command prompt
  - phpdbg_start_oplog — Startet ein Oplog

# runkit7

# Einführung

The runkit7 extension provides means to modify constants, user-defined functions, and user-defined classes. It also provides for custom superglobal variables.

This package is a fork of the » runkit package providing PHP 7 support.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

Modifying Constants, Functions, Classes, and Methods as well as Custom Superglobals works with all releases of PHP 7. No special requirements are necessary.

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/runkit7.

Windows-Binaries (DLL-Dateien) für diese PECL-Erweiterung sind auf der PECL-Website erhältlich.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Runkit Configuration Options
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
runkit.superglobal | "" | `INI_PERDIR` |
runkit.internal_override | "0" | `INI_SYSTEM` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`runkit.superglobal` string
  Comma-separated list of variable names to be treated as superglobals. This value should be set in the systemwide php.ini file, but may work in perdir configuration contexts depending on your SAPI.

  Beispiel #1 Custom Superglobals with runkit.superglobal=_FOO,_BAR in php.ini

      <?php
      function show_values() {
        echo "Foo is $_FOO\n";
        echo "Bar is $_BAR\n";
        echo "Baz is $_BAZ\n";
      }

      $_FOO = 'foo';
      $_BAR = 'bar';
      $_BAZ = 'baz';

      /* Displays foo and bar, but not baz */
      show_values();
      ?>

`runkit.internal_override` bool
  Enables ability to modify/rename/remove internal functions.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`RUNKIT7_IMPORT_FUNCTIONS` (int)
  runkit7_import() flag indicating that normal functions should be imported from the specified file.
`RUNKIT7_IMPORT_CLASS_METHODS` (int)
  runkit7_import() flag indicating that class methods should be imported from the specified file.
`RUNKIT7_IMPORT_CLASS_CONSTS` (int)
  runkit7_import() flag indicating that class constants should be imported from the specified file.
`RUNKIT7_IMPORT_CLASS_PROPS` (int)
  runkit7_import() flag indicating that class standard properties should be imported from the specified file.
`RUNKIT7_IMPORT_CLASS_STATIC_PROPS` (int)
  runkit7_import() flag indicating that class static properties should be imported from the specified file. Available since Runkit 1.0.1.
`RUNKIT7_IMPORT_CLASSES` (int)
  runkit7_import() flag representing a bitwise OR of the `RUNKIT7_IMPORT_CLASS_*` constants.
`RUNKIT7_IMPORT_OVERRIDE` (int)
  runkit7_import() flag indicating that if any of the imported functions, methods, constants, or properties already exist, they should be replaced with the new definitions. If this flag is not set, then any imported definitions which already exist will be discarded.
`RUNKIT7_ACC_RETURN_REFERENCE` (int)
  Include this flag to make the function or method being created or redeclared return a reference.
`RUNKIT7_ACC_PUBLIC` (int)
  Flag for runkit7_method_add() and runkit7_method_redefine() to make the method public.
`RUNKIT7_ACC_PROTECTED` (int)
  Flag for runkit7_method_add() and runkit7_method_redefine() to make the method protected.
`RUNKIT7_ACC_PRIVATE` (int)
  Flag for runkit7_method_add() and runkit7_method_redefine() to make the method private.
`RUNKIT7_ACC_STATIC` (int)
  Flag for runkit7_method_add() and runkit7_method_redefine() to make the method static.
`RUNKIT7_FEATURE_MANIPULATION` (int)
  Equal to 1 if runtime manipulation is enabled, and 0 otherwise.
`RUNKIT7_FEATURE_SUPERGLOBALS` (int)
  Equal to 1 if custom superglobals are enabled, and 0 otherwise.
`RUNKIT7_FEATURE_SANDBOX` (int)
  Always 0, it's impractical to implement the sandbox feature in php 7.

# runkit7 Funktionen

# runkit7_constant_add

(PECL runkit7 >= Unknown)

runkit7_constant_add — Similar to define(), but allows defining in class definitions as well

### Beschreibung

function runkit7_constant_add(string `$constant_name`, mixed `$value`, int `$newVisibility` = ?): bool

### Parameter-Liste

`constant_name`
  Name of constant to declare. Either a string to indicate a global constant, or `classname::constname` to indicate a class constant.
`value`
  NULL, Bool, Long, Double, String, Array, or Resource value to store in the new constant.
`newVisibility`
  Visibility of the constant, for class constants. Public by default. One of the `RUNKIT7_ACC_*` constants.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- define() - Definiert eine benannte Konstante
- runkit7_constant_redefine() - Redefine an already defined constant
- runkit7_constant_remove() - Remove/Delete an already defined constant

# runkit7_constant_redefine

(PECL runkit7 >= Unknown)

runkit7_constant_redefine — Redefine an already defined constant

### Beschreibung

function runkit7_constant_redefine(string `$constant_name`, mixed `$value`, int `$new_visibility` = ?): bool

### Parameter-Liste

`constant_name`
  Constant to redefine. Either the name of a global constant, or `classname::constname` indicating class constant.
`value`
  Value to assign to the constant.
`new_visibility`
  The new visibility of the constant, for class constants. Unchanged by default. One of the `RUNKIT7_ACC_*` constants.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- runkit7_constant_add() - Similar to define(), but allows defining in class definitions as well
- runkit7_constant_remove() - Remove/Delete an already defined constant

# runkit7_constant_remove

(PECL runkit7 >= Unknown)

runkit7_constant_remove — Remove/Delete an already defined constant

### Beschreibung

function runkit7_constant_remove(string `$constant_name`): bool

### Parameter-Liste

`constant_name`
  Name of the constant to remove. Either the name of a global constant, or `classname::constname` indicating a class constant.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- define() - Definiert eine benannte Konstante
- runkit7_constant_add() - Similar to define(), but allows defining in class definitions as well
- runkit7_constant_redefine() - Redefine an already defined constant

# runkit7_function_add

(PECL runkit7 >= Unknown)

runkit7_function_add — Add a new function, similar to create_function()

### Beschreibung

function runkit7_function_add(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_add(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Parameter-Liste

`function_name`
  Name of the function to be created
`argument_list`
  Comma separated argument list
`code`
  Code making up the function
`closure`
  A closure that defines the function.
`return_by_reference`
  Whether the function should return by reference.
`doc_comment`
  The doc comment of the function.
`return_type`
  The return type of the function.
`is_strict`
  Whether the function should behave as if it were declared in a file with `strict_types=1`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 A runkit7_function_add() example

    <?php
    runkit7_function_add('testme','$a,$b','echo "The value of a is $a\n"; echo "The value of b is $b\n";');
    testme(1,2);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    The value of a is 1
    The value of b is 2

### Siehe auch

- create_function() - Erzeugt eine Funktion dynamisch durch Auswertung einer Zeichenkette mit Code
- runkit7_function_redefine() - Replace a function definition with a new implementation
- runkit7_function_copy() - Copy a function to a new function name
- runkit7_function_rename() - Change a function's name
- runkit7_function_remove() - Remove a function definition
- runkit7_method_add() - Dynamically adds a new method to a given class

# runkit7_function_copy

(PECL runkit7 >= Unknown)

runkit7_function_copy — Copy a function to a new function name

### Beschreibung

function runkit7_function_copy(string `$source_name`, string `$target_name`): bool

### Parameter-Liste

`source_name`
  Name of the existing function
`target_name`
  Name of the new function to copy the definition to

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 A runkit7_function_copy() example

    <?php
    function original() {
      echo "In a function\n";
    }
    runkit7_function_copy('original','duplicate');
    original();
    duplicate();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    In a function
    In a function

### Siehe auch

- runkit7_function_add() - Add a new function, similar to create_function
- runkit7_function_redefine() - Replace a function definition with a new implementation
- runkit7_function_rename() - Change a function's name
- runkit7_function_remove() - Remove a function definition

# runkit7_function_redefine

(PECL runkit7 >= Unknown)

runkit7_function_redefine — Replace a function definition with a new implementation

### Beschreibung

function runkit7_function_redefine(
string `$function_name`,
string `$argument_list`,
string `$code`,
bool `$return_by_reference` = `null`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_function_redefine(
string `$function_name`,
Closure `$closure`,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

> Hinweis: Normalerweise können nur benutzerdefinierte Funktionen gelöscht, umbenannt oder modifiziert werden. Wenn Sie auch interne Funktionen übersteuern wollen, müssen Sie `runkit.internal_override` in Ihrer php.ini aktivieren.

### Parameter-Liste

`function_name`
  Name of function to redefine
`argument_list`
  New list of arguments to be accepted by function
`code`
  New code implementation
`closure`
  A closure that defines the function.
`return_by_reference`
  Whether the function should return by reference.
`doc_comment`
  The doc comment of the function.
`return_type`
  The return type of the function.
`is_strict`
  Whether the function behaves as if it was declared in a file with `strict_types=1`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 A runkit7_function_redefine() example

    <?php
    function testme() {
      echo "Original Testme Implementation\n";
    }
    testme();
    runkit7_function_redefine('testme','','echo "New Testme Implementation\n";');
    testme();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Original Testme Implementation
    New Testme Implementation

### Siehe auch

- runkit7_function_add() - Add a new function, similar to create_function
- runkit7_function_copy() - Copy a function to a new function name
- runkit7_function_rename() - Change a function's name
- runkit7_function_remove() - Remove a function definition
- runkit7_method_redefine() - Dynamically changes the code of the given method

# runkit7_function_remove

(PECL runkit7 >= Unknown)

runkit7_function_remove — Remove a function definition

### Beschreibung

function runkit7_function_remove(string `$function_name`): bool

> Hinweis: Normalerweise können nur benutzerdefinierte Funktionen gelöscht, umbenannt oder modifiziert werden. Wenn Sie auch interne Funktionen übersteuern wollen, müssen Sie `runkit.internal_override` in Ihrer php.ini aktivieren.

### Parameter-Liste

`function_name`
  Name of the function to be deleted

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- runkit7_function_add() - Add a new function, similar to create_function
- runkit7_function_copy() - Copy a function to a new function name
- runkit7_function_redefine() - Replace a function definition with a new implementation
- runkit7_function_rename() - Change a function's name

# runkit7_function_rename

(PECL runkit7 >= Unknown)

runkit7_function_rename — Change a function's name

### Beschreibung

function runkit7_function_rename(string `$source_name`, string `$target_name`): bool

> Hinweis: Normalerweise können nur benutzerdefinierte Funktionen gelöscht, umbenannt oder modifiziert werden. Wenn Sie auch interne Funktionen übersteuern wollen, müssen Sie `runkit.internal_override` in Ihrer php.ini aktivieren.

### Parameter-Liste

`source_name`
  Current function name
`target_name`
  New function name

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- runkit7_function_add() - Add a new function, similar to create_function
- runkit7_function_copy() - Copy a function to a new function name
- runkit7_function_redefine() - Replace a function definition with a new implementation
- runkit7_function_remove() - Remove a function definition

# runkit7_import

(PECL runkit7 >= Unknown)

runkit7_import — Process a PHP file importing function and class definitions, overwriting where appropriate

Warnung

This feature has been removed in PECL runkit7 4.0.0.

### Beschreibung

function runkit7_import(string `$filename`, int `$flags` = ?): bool

Similar to include. However, any code residing outside of a function or class is simply ignored. Additionally, depending on the value of `flags`, any functions or classes which already exist in the currently running environment may be automatically overwritten by their new definitions.

### Parameter-Liste

`filename`
  Filename to import function and class definitions from
`flags`
  Bitwise OR of the `RUNKIT7_IMPORT_*` family of constants.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# runkit7_method_add

(PECL runkit7 >= Unknown)

runkit7_method_add — Dynamically adds a new method to a given class

### Beschreibung

function runkit7_method_add(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_add(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Parameter-Liste

`class_name`
  The class to which this method will be added
`method_name`
  The name of the method to add
`argument_list`
  Comma-delimited list of arguments for the newly-created method
`code`
  The code to be evaluated when `method_name` is called
`closure`
  A closure that defines the method.
`flags`
  The type of method to create, can be `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` or `RUNKIT7_ACC_PRIVATE` optionally combined via bitwise OR with `RUNKIT7_ACC_STATIC`
`doc_comment`
  The doc comment of the method.
`return_type`
  The return type of the method.
`is_strict`
  Whether the method behaves as if it were declared in a file with `strict_types=1`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 runkit7_method_add() example

    <?php
    class Example {
        function foo() {
            echo "foo!\n";
        }
    }

    // create an Example object
    $e = new Example();

    // Add a new public method
    runkit7_method_add(
        'Example',
        'add',
        '$num1, $num2',
        'return $num1 + $num2;',
        RUNKIT7_ACC_PUBLIC
    );

    // add 12 + 4
    echo $e->add(12, 4);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    16

### Siehe auch

- runkit7_method_copy() - Copies a method from class to another
- runkit7_method_redefine() - Dynamically changes the code of the given method
- runkit7_method_remove() - Dynamically removes the given method
- runkit7_method_rename() - Dynamically changes the name of the given method
- runkit7_function_add() - Add a new function, similar to create_function

# runkit7_method_copy

(PECL runkit7 >= Unknown)

runkit7_method_copy — Copies a method from class to another

### Beschreibung

function runkit7_method_copy(
string `$destination_class`,
string `$destination_method_name`,
string `$source_class`,
string `$source_method_name` = ?
): bool

### Parameter-Liste

`destination_class`
  Destination class for copied method
`destination_method_name`
  Destination method name
`source_class`
  Source class of the method to copy
`source_method_name`
  Name of the method to copy from the source class. If this parameter is omitted, the value of `destination_method_name` is assumed.

### Rückgabewerte

### Beispiele

Beispiel #1 runkit7_method_copy() example

    <?php
    class Foo {
        function example() {
            return "foo!\n";
        }
    }

    class Bar {
        // initially, no methods
    }

    // copy the example() method from the Foo class to the Bar class, as baz()
    runkit7_method_copy('Bar', 'baz', 'Foo', 'example');

    // output copied function
    echo Bar::baz();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    foo!

### Siehe auch

- runkit7_method_add() - Dynamically adds a new method to a given class
- runkit7_method_redefine() - Dynamically changes the code of the given method
- runkit7_method_remove() - Dynamically removes the given method
- runkit7_method_rename() - Dynamically changes the name of the given method
- runkit7_function_copy() - Copy a function to a new function name

# runkit7_method_redefine

(PECL runkit7 >= Unknown)

runkit7_method_redefine — Dynamically changes the code of the given method

### Beschreibung

function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
string `$argument_list`,
string `$code`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool
function runkit7_method_redefine(
string `$class_name`,
string `$method_name`,
Closure `$closure`,
int `$flags` = RUNKIT7_ACC_PUBLIC,
string `$doc_comment` = `null`,
string `$return_type` = ?,
bool `$is_strict` = ?
): bool

### Parameter-Liste

`class_name`
  The class in which to redefine the method
`method_name`
  The name of the method to redefine
`argument_list`
  Comma-delimited list of arguments for the redefined method
`code`
  The new code to be evaluated when `method_name` is called
`closure`
  A closure that defines the method.
`flags`
  The redefined method can be `RUNKIT7_ACC_PUBLIC`, `RUNKIT7_ACC_PROTECTED` or `RUNKIT7_ACC_PRIVATE` optionally combined via bitwise OR with `RUNKIT7_ACC_STATIC`
`doc_comment`
  The doc comment of the method.
`return_type`
  The return type of the method.
`is_strict`
  Whether the method behaves as if it was declared in a file with `strict_types=1`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 runkit7_method_redefine() example

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // create an Example object
    $e = new Example();

    // output Example::foo() (before redefine)
    echo "Before: " . $e->foo();

    // Redefine the 'foo' method
    runkit7_method_redefine(
        'Example',
        'foo',
        '',
        'return "bar!\n";',
        RUNKIT7_ACC_PUBLIC
    );

    // output Example::foo() (after redefine)
    echo "After: " . $e->foo();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Before: foo!
    After: bar!

### Siehe auch

- runkit7_method_add() - Dynamically adds a new method to a given class
- runkit7_method_copy() - Copies a method from class to another
- runkit7_method_remove() - Dynamically removes the given method
- runkit7_method_rename() - Dynamically changes the name of the given method
- runkit7_function_redefine() - Replace a function definition with a new implementation

# runkit7_method_remove

(PECL runkit7 >= Unknown)

runkit7_method_remove — Dynamically removes the given method

### Beschreibung

function runkit7_method_remove(string `$class_name`, string `$method_name`): bool

> Hinweis: Diese Funktion kann nicht genutzt werden, um die aktuell ausgeführte (oder verkette) Methode zu manipulieren.

### Parameter-Liste

`class_name`
  The class in which to remove the method
`method_name`
  The name of the method to remove

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 runkit7_method_remove() example

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }

        function bar() {
            return "bar!\n";
        }
    }

    // Remove the 'foo' method
    runkit7_method_remove(
        'Example',
        'foo'
    );

    echo implode(' ', get_class_methods('Example'));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bar

### Siehe auch

- runkit7_method_add() - Dynamically adds a new method to a given class
- runkit7_method_copy() - Copies a method from class to another
- runkit7_method_redefine() - Dynamically changes the code of the given method
- runkit7_method_rename() - Dynamically changes the name of the given method
- runkit7_function_remove() - Remove a function definition

# runkit7_method_rename

(PECL runkit7 >= Unknown)

runkit7_method_rename — Dynamically changes the name of the given method

### Beschreibung

function runkit7_method_rename(string `$class_name`, string `$source_method_name`, string `$target_method_name`): bool

> Hinweis: Diese Funktion kann nicht genutzt werden, um die aktuell ausgeführte (oder verkette) Methode zu manipulieren.

### Parameter-Liste

`class_name`
  The class in which to rename the method
`source_method_name`
  The name of the method to rename
`target_method_name`
  The new name to give to the renamed method

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 runkit7_method_rename() example

    <?php
    class Example {
        function foo() {
            return "foo!\n";
        }
    }

    // Rename the 'foo' method to 'bar'
    runkit7_method_rename(
        'Example',
        'foo',
        'bar'
    );

    // output renamed function
    echo (new Example)->bar();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    foo!

### Siehe auch

- runkit7_method_add() - Dynamically adds a new method to a given class
- runkit7_method_copy() - Copies a method from class to another
- runkit7_method_redefine() - Dynamically changes the code of the given method
- runkit7_method_remove() - Dynamically removes the given method
- runkit7_function_rename() - Change a function's name

# runkit7_object_id

(PECL runkit7 >= Unknown)

runkit7_object_id — Return the integer object handle for given object

### Beschreibung

function runkit7_object_id(object `$obj`): int

This function is equivalent to spl_object_id().

This function returns a unique identifier for the object. The object id is unique for the lifetime of the object. Once the object is destroyed, its id may be reused for other objects. This behavior is similar to spl_object_hash().

### Parameter-Liste

`obj`
  Any object.

### Rückgabewerte

An integer identifier that is unique for each currently existing object and is always the same for each object.

### Anmerkungen

> Hinweis: When an object is destroyed, its id may be reused for other objects.

### Siehe auch

- spl_object_id() - Return the integer object handle for given object

# runkit7_superglobals

(PECL runkit7 >= Unknown)

runkit7_superglobals — Return numerically indexed array of registered superglobals

### Beschreibung

function runkit7_superglobals(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a numerically indexed array of the currently registered superglobals. i.e. _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES

### Siehe auch

- Variable Scope

# runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc

### Beschreibung

function runkit7_zval_inspect(string `$value`): array

### Parameter-Liste

`value`
  The value to return the representation of

### Rückgabewerte

The array returned by this function contains the following elements:

- `address`
- `refcount` (optional)
- `is_ref` (optional)
- `type`

### Beispiele

Beispiel #1 runkit7_zval_inspect() example

    <?php

    $var = new DateTime();
    var_dump(runkit7_zval_inspect($var));

    $var = 1;
    var_dump(runkit7_zval_inspect($var));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["refcount"]=>
      int(2)
      ["is_ref"]=>
      bool(false)
      ["type"]=>
      int(8)
    }

    array(2) {
      ["address"]=>
      string(14) "0x7f45ab21b1e0"
      ["type"]=>
      int(4)
    }

### Siehe auch

- References Explained
- » References Explained (by Derick Rethans)

## Inhaltsverzeichnis

- runkit7_constant_add — Similar to define(), but allows defining in class definitions as well
- runkit7_constant_redefine — Redefine an already defined constant
- runkit7_constant_remove — Remove/Delete an already defined constant
- runkit7_function_add — Add a new function, similar to create_function
- runkit7_function_copy — Copy a function to a new function name
- runkit7_function_redefine — Replace a function definition with a new implementation
- runkit7_function_remove — Remove a function definition
- runkit7_function_rename — Change a function's name
- runkit7_import — Process a PHP file importing function and class definitions, overwriting where appropriate
- runkit7_method_add — Dynamically adds a new method to a given class
- runkit7_method_copy — Copies a method from class to another
- runkit7_method_redefine — Dynamically changes the code of the given method
- runkit7_method_remove — Dynamically removes the given method
- runkit7_method_rename — Dynamically changes the name of the given method
- runkit7_object_id — Return the integer object handle for given object
- runkit7_superglobals — Return numerically indexed array of registered superglobals
- runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- runkit7 Funktionen
  - runkit7_constant_add — Similar to define(), but allows defining in class definitions as well
  - runkit7_constant_redefine — Redefine an already defined constant
  - runkit7_constant_remove — Remove/Delete an already defined constant
  - runkit7_function_add — Add a new function, similar to create_function
  - runkit7_function_copy — Copy a function to a new function name
  - runkit7_function_redefine — Replace a function definition with a new implementation
  - runkit7_function_remove — Remove a function definition
  - runkit7_function_rename — Change a function's name
  - runkit7_import — Process a PHP file importing function and class definitions, overwriting where appropriate
  - runkit7_method_add — Dynamically adds a new method to a given class
  - runkit7_method_copy — Copies a method from class to another
  - runkit7_method_redefine — Dynamically changes the code of the given method
  - runkit7_method_remove — Dynamically removes the given method
  - runkit7_method_rename — Dynamically changes the name of the given method
  - runkit7_object_id — Return the integer object handle for given object
  - runkit7_superglobals — Return numerically indexed array of registered superglobals
  - runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc

# User Operations for Zend

# Einführung

The uopz - User Operations for Zend - extension exposes Zend Engine functionality normally used at compilation and execution time in order to allow modification of the internal structures that represent PHP code, and for user code to interact with the VM.

uopz supports the following activities:

- Overloading some opcodes including ZEND_EXIT and ZEND_NEW
- Backup and restore functions and methods
- Renaming functions and methods
- Copying of functions and methods
- Deletion of functions and methods
- Redefinition of global and class constants
- Deletion of global and class constants
- Runtime composition and modification of classes

> Hinweis:

> All of the activities supported are compatible with opcache

Achtung

PECL uopz 6.1.1 is not compatible with Xdebug >= 2.9.4. Later uopz versions are not compatible with Xdebug < 2.9.4.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

As of uopz 5.0 PHP 7.0 is required. As of uopz 5.1, PHP 7.1+ is required.

## Installation

uopz releases are hosted by PECL and the source code by » github, the easiest route to installation is the normal PECL route: » https://pecl.php.net/package/uopz.

Windows users can download prebuilt release binaries from the » PECL website.

As of uopz 5.0.0 the extension must be loaded as extension. Before this version it must be loaded as zend_extension.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

uopz Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
uopz.disable | "0" | `INI_SYSTEM` | Available as of uopz 5.0.2
uopz.exit | "0" | `INI_SYSTEM` | Available as of uopz 6.0.1
uopz.overloads | "1" | `INI_SYSTEM` | Available as of uopz 2.0.2. Removed as of uopz 5.0.0.

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`uopz.disable` bool

  If enabled, uopz should stop having any effect on the engine.

`uopz.exit` bool

  Whether to allow the execution of exit opcodes or not. This setting can be overridden during runtime by calling uopz_allow_exit().

`uopz.overloads` bool

  Enables the ability to use uopz_overload().

> Hinweis: When running with OPcache enabled, it may be necessary to disable all OPcache optimizations (`opcache.optimization_level=0`).

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

The following opcodes are defined as constants by uopz before 5.0.0:

`ZEND_EXIT` (int)
  Invoked by exit() and die(), receives no arguments. Return boolean `true` to exit, `false` to continue
`ZEND_NEW` (int)
  Invoked by object construction, receives the class of object being created as the only argument
`ZEND_THROW` (int)
  Invoked by the throw construct, receives the class of exception being thrown as the only argument
`ZEND_FETCH_CLASS` (int)
  Invoked upon composure, receives the class the name of the class being fetched as the only argument
`ZEND_ADD_TRAIT` (int)
  Invoked upon composure, receives the class the trait is being added to as the first argument, and the name of the trait as the second argument
`ZEND_ADD_INTERFACE` (int)
  Invoked upon composure, receives the class the interface is being added to as the first argument, and the name of the interface as the second argument
`ZEND_INSTANCEOF` (int)
  Invoked by instanceof operator, receives the object being verified as the first argument, and the name of the class which that object should be as the second argument

The following constants control the VM's behaviour after a user handler is invoked, be extremely careful! These constants are removed as of uopz 5.0.0.

`ZEND_USER_OPCODE_CONTINUE` (int)
  Advance 1 opcode and continuue
`ZEND_USER_OPCODE_ENTER` (int)
  Enter into new op_array without recursion
`ZEND_USER_OPCODE_LEAVE` (int)
  Return to calling op_array within the same executor
`ZEND_USER_OPCODE_DISPATCH` (int)
  Dispatch to original opcode handler
`ZEND_USER_OPCODE_DISPATCH_TO` (int)
  Dispatch to a specific handler (OR'd with ZEND opcode constant)
`ZEND_USER_OPCODE_RETURN` (int)
  Exit from executor (return from function)

The following modifiers are registered as constants by uopz

`ZEND_ACC_PUBLIC` (int)
  Mark function as public, the default
`ZEND_ACC_PROTECTED` (int)
  Mark function as protected
`ZEND_ACC_PRIVATE` (int)
  Mark function as private
`ZEND_ACC_STATIC` (int)
  Mark function as static
`ZEND_ACC_FINAL` (int)
  Mark function as final
`ZEND_ACC_ABSTRACT` (int)
  Mark function as abstract
`ZEND_ACC_CLASS` (int)
  Dummy registered for consistency, the default kind of class entry. Removed as of uopz 5.0.0.
`ZEND_ACC_INTERFACE` (int)
  Mark class as interface. Removed as of uopz 5.0.0.
`ZEND_ACC_TRAIT` (int)
  Mark class as trait. Removed as of uopz 5.0.0.
`ZEND_ACC_FETCH` (int)
  Used for getting flags only. Removed as of uopz 5.0.0.

# Uopz Funktionen

# uopz_add_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_add_function — Adds non-existent function or method

### Beschreibung

function uopz_add_function(string `$function`, Closure `$handler`, int `&$flags` = ZEND_ACC_PUBLIC): bool
function uopz_add_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `&$flags` = ZEND_ACC_PUBLIC,
int `&$all` = `true`
): bool

Adds a non-existent function or method.

### Parameter-Liste

`class`

  The name of the class.

`function`

  The name of the function or method.

`handler`

  The Closure that defines the new function or method.

`flags`

  Flags to set for the new function or method.

`all`

  Whether all classes that descend from `class` will also be affected.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

uopz_add_function() throws a RuntimeException if the function or method to add already exists.

### Beispiele

Beispiel #1 Basic uopz_add_function() Usage

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    foo();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bar

### Siehe auch

- uopz_del_function() - Deletes previously added function or method
- uopz_set_return() - Provide a return value for an existing function

# uopz_allow_exit

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_allow_exit — Allows control over disabled exit opcode

### Beschreibung

function uopz_allow_exit(bool `$allow`): void

By default uopz disables the exit opcode, so exit() calls are practically ignored. uopz_allow_exit() allows to control this behavior.

### Parameter-Liste

`allow`

  Whether to allow the execution of exit opcodes or not.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 uopz_allow_exit() example

    <?php
    exit(1);
    echo 1;
    uopz_allow_exit(true);
    exit(2);
    echo 2;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1

### Anmerkungen

Achtung

OPcache optimizes away dead code after unconditional exit.

### Siehe auch

- uopz_get_exit_status() - Retrieve the last set exit status

# uopz_backup

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_backup — Backup a function

Warnung

Diese Funktion wurde mit PECL uopz 5.0.0 ENTFERNT.

### Beschreibung

function uopz_backup(string `$function`): void
function uopz_backup(string `$class`, string `$function`): void

Backup a function at runtime, to be restored on shutdown

### Parameter-Liste

`class`

  The name of the class containing the function to backup

`function`

  The name of the function

### Rückgabewerte

### Beispiele

Beispiel #1 uopz_backup() example

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

# uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_compose — Compose a class

Warnung

Diese Funktion wurde mit PECL uopz 5.0.0 ENTFERNT.

### Beschreibung

function uopz_compose(
string `$name`,
array `$classes`,
array `$methods` = ?,
array `$properties` = ?,
int `$flags` = ?
): void

Creates a new class of the given name that implements, extends, or uses all of the provided classes

### Parameter-Liste

`name`

  A legal class name

`classes`

  An array of class, interface and trait names

`methods`

  An associative array of methods, values are either closures or [modifiers => closure]

`properties`

  An associative array of properties, keys are names, values are modifiers

`flags`

  Entry type, by default ZEND_ACC_CLASS

### Rückgabewerte

### Beispiele

Beispiel #1 uopz_compose() example

    <?php
    class myClass {}
    trait myTrait {}
    interface myInterface {}

    uopz_compose(
        Composed::class, [
            myClass::class,
            myTrait::class,
            myInterface::class
        ], [
        "__construct" => function() {
            /* ... */
        }
    ]);

    var_dump(
     class_uses(Composed::class),
     class_parents(Composed::class),
     class_implements(Composed::class));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["myTrait"]=>
      string(7) "myTrait"
    }
    array(1) {
      ["myClass"]=>
      string(7) "myClass"
    }
    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_copy

(PECL uopz 1 >= 1.0.4, PECL uopz 2)

uopz_copy — Copy a function

Warnung

Diese Funktion wurde mit PECL uopz 5.0.0 ENTFERNT.

### Beschreibung

function uopz_copy(string `$function`): Closure
function uopz_copy(string `$class`, string `$function`): Closure

Copy a function by name

### Parameter-Liste

`class`

  The name of the class containing the function to copy

`function`

  The name of the function

### Rückgabewerte

A Closure for the specified function

### Beispiele

Beispiel #1 uopz_copy() example

    <?php
    $strtotime = uopz_copy('strtotime');

    uopz_function("strtotime", function($arg1, $arg2) use($strtotime) {
        /* can call original strtotime from here */
        var_dump($arg1);
    });

    var_dump(strtotime('dummy'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(5) "dummy"

# uopz_del_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_del_function — Deletes previously added function or method

### Beschreibung

function uopz_del_function(string `$function`): bool
function uopz_del_function(string `$class`, string `$function`, int `&$all` = `true`): bool

Deletes a previously added function or method.

### Parameter-Liste

`class`

  The name of the class.

`function`

  The name of the function or method.

`all`

  Whether all classes that descend from `class` will also be affected.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

uopz_del_function() throws a RuntimeException if the function or method to delete has not been added by uopz_add_function().

### Beispiele

Beispiel #1 Basic uopz_del_function() Usage

    <?php
    uopz_add_function('foo', function () {echo 'bar';});
    var_dump(function_exists('foo'));
    uopz_del_function('foo');
    var_dump(function_exists('foo'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)

### Siehe auch

- uopz_add_function() - Adds non-existent function or method
- uopz_unset_return() - Unsets a previously set return value for a function

# uopz_delete

(PECL uopz 1, PECL uopz 2)

uopz_delete — Delete a function

Warnung

Diese Funktion wurde mit PECL uopz 5.0.0 ENTFERNT.

### Beschreibung

function uopz_delete(string `$function`): void
function uopz_delete(string `$class`, string `$function`): void

Deletes a function or method

### Parameter-Liste

`class`

`function`

### Rückgabewerte

### Beispiele

Beispiel #1 uopz_delete() example

    <?php
    uopz_delete("strlen");

    echo strlen("Hello World");
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    PHP Fatal error: Call to undefined function strlen() in /path/to/script.php on line 4

Beispiel #2 uopz_delete() class example

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_delete(My::class, "strlen");

    echo My::strlen("Hello World");
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    PHP Fatal error: Call to undefined method My::strlen() in /path/to/script.php on line 10

# uopz_extend

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_extend — Extend a class at runtime

### Beschreibung

function uopz_extend(string `$class`, string `$parent`): bool

Makes `class` extend `parent`

### Parameter-Liste

`class`

  The name of the class to extend

`parent`

  The name of the class to inherit

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

As of PHP 7.4.0, uopz_extend() throws a RuntimeException, if OPcache is enabled, and the class entry of either `class` or `parent` (if it is a trait) is immutable.

### Beispiele

Beispiel #1 uopz_extend() example

    <?php
    class A {}
    class B {}

    uopz_extend(A::class, B::class);

    var_dump(class_parents(A::class));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["B"]=>
      string(1) "B"
    }

# uopz_flags

(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_flags — Get or set flags on function or class

### Beschreibung

function uopz_flags(string `$function`, int `$flags` = PHP_INT_MAX): int
function uopz_flags(string `$class`, string `$function`, int `$flags` = PHP_INT_MAX): int

Get or set the flags on a class or function entry at runtime

### Parameter-Liste

`class`

  The name of a class

`function`

  The name of the function. If `class` is given and an empty string is passed as `function`, uopz_flags() gets or sets the flags of the class entry.

`flags`

  A valid set of ZEND_ACC_ flags. If omitted, uopz_flags() acts as getter.

### Rückgabewerte

If setting, returns old flags, else returns flags

### Fehler/Exceptions

As of PHP 7.4.0, if the parameter `flags` is passed, uopz_flags() throws a RuntimeException, if OPcache is enabled, and the class entry of `class` or the function entry of `function` is immutable.

### Changelog

Version | Beschreibung
--- | ---
PECL uopz 5.0.0 | The `flags` parameter is now optional. Formerly, `ZEND_ACC_FETCH` had to be passed to use uopz_flags() as getter.

### Beispiele

Beispiel #1 uopz_flags() example

    <?php
    class Test {
        public function method() {
            return __CLASS__;
        }
    }

    $flags = uopz_flags("Test", "method");

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));

    var_dump(uopz_flags("Test", "method", $flags|ZEND_ACC_STATIC|ZEND_ACC_PRIVATE));

    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_PRIVATE));
    var_dump((bool) (uopz_flags("Test", "method") & ZEND_ACC_STATIC));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(false)
    int(1234567890)
    bool(true)
    bool(true)

Beispiel #2 "Unfinalize" a Class

    <?php
    final class MyClass
    {
    }

    $flags = uopz_flags(MyClass::class, '');
    uopz_flags(MyClass::class, '', $flags & ~ZEND_ACC_FINAL);
    var_dump((new ReflectionClass(MyClass::class))->isFinal());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)

# uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_function — Creates a function at runtime

Warnung

Diese Funktion wurde mit PECL uopz 5.0.0 ENTFERNT.

### Beschreibung

function uopz_function(string `$function`, Closure `$handler`, int `$modifiers` = ?): void
function uopz_function(
string `$class`,
string `$function`,
Closure `$handler`,
int `$modifiers` = ?
): void

Creates a function at runtime

### Parameter-Liste

`class`

  The name of the class to receive the new function

`function`

  The name of the function

`handler`

  The Closure for the function

`modifiers`

  The modifiers for the function, by default copied or ZEND_ACC_PUBLIC

### Rückgabewerte

### Beispiele

Beispiel #1 uopz_function() example

    <?php
    uopz_function("my_strlen", function($arg) {
        return strlen($arg);
    });
    echo my_strlen("Hello World");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    11

Beispiel #2 uopz_function() class example

    <?php
    class My {}

    uopz_function(My::class, "strlen", function($arg) {
        return strlen($arg);
    }, ZEND_ACC_STATIC);

    echo My::strlen("Hello World");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    11

# uopz_get_exit_status

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_get_exit_status — Retrieve the last set exit status

### Beschreibung

function uopz_get_exit_status(): mixed

Retrieves the last set exit status, i.e. the value passed to exit().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

This function returns the last exit status, or `null` if exit() has not been called.

### Beispiele

Beispiel #1 uopz_get_exit_status() example

    <?php
    exit(123);
    echo uopz_get_exit_status();?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    123

### Anmerkungen

Achtung

OPcache optimizes away dead code after unconditional exit.

### Siehe auch

- uopz_allow_exit() - Allows control over disabled exit opcode

# uopz_get_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_hook — Gets previously set hook on function or method

### Beschreibung

function uopz_get_hook(string `$function`): Closure
function uopz_get_hook(string `$class`, string `$function`): Closure

Gets the previously set hook on a function or method.

### Parameter-Liste

`class`

  The name of the class.

`function`

  The name of the function or method.

### Rückgabewerte

Returns the previously set hook on a function or method, or `null` if no hook has been set.

### Beispiele

Beispiel #1 Basic uopz_get_hook() Usage

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    var_dump(uopz_get_hook('foo'));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(Closure)#2 (0) {
    }

### Siehe auch

- uopz_set_hook() - Sets hook to execute when entering a function or method
- uopz_unset_hook() - Removes previously set hook on function or method

# uopz_get_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_mock — Get the current mock for a class

### Beschreibung

function uopz_get_mock(string `$class`): mixed

Returns the current mock for `class`.

### Parameter-Liste

`class`

  The name of the mocked class.

### Rückgabewerte

Either a string containing the name of the mock, or an object, or `null` if no mock has been set.

### Beispiele

Beispiel #1 uopz_get_mock() example

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    echo uopz_get_mock(A::class);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    mockA

### Siehe auch

- uopz_set_mock() - Use mock instead of class for new objects
- uopz_unset_mock() - Unset previously set mock

# uopz_get_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_property — Gets value of class or instance property

### Beschreibung

function uopz_get_property(string `$class`, string `$property`): mixed
function uopz_get_property(object `$instance`, string `$property`): mixed

Gets the value of a static class property, if `class` is given, or the value of an instance property, if `instance` is given.

### Parameter-Liste

`class`

  The name of the class.

`instance`

  The object instance.

`property`

  The name of the property.

### Rückgabewerte

Returns the value of the class or instance property, or `null` if the property is not defined.

### Beispiele

Beispiel #1 Basic uopz_get_property() Usage

    <?php
    class Foo {
        private static $staticBar = 10;
        private $bar = 100;
    }
    $foo = new Foo;
    var_dump(uopz_get_property('Foo', 'staticBar'));
    var_dump(uopz_get_property($foo, 'bar'));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(10)
    int(100)

### Siehe auch

- uopz_set_property() - Sets value of existing class or instance property

# uopz_get_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_return — Gets a previous set return value for a function

### Beschreibung

function uopz_get_return(string `$function`): mixed
function uopz_get_return(string `$class`, string `$function`): mixed

Gets the return value of the `function` previously set by uopz_set_return().

### Parameter-Liste

`class`

  The name of the class containing the function

`function`

  The name of the function

### Rückgabewerte

The return value or Closure previously set.

### Beispiele

Beispiel #1 uopz_get_return() example

    <?php
    uopz_set_return("strlen", 42);
    echo uopz_get_return("strlen");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    42

# uopz_get_static

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_static — Gets the static variables from function or method scope

### Beschreibung

function uopz_get_static(string `$class`, string `$function`): array
function uopz_get_static(string `$function`): array

Gets the static variables from function or method scope.

### Parameter-Liste

`class`

  The name of the class.

`function`

  The name of the function or method.

### Rückgabewerte

Returns an associative array of variable names mapped to their current values on success, or `null` if the function or method does not exist.

As of PHP 8.3.0, static initializers are either computed during compile time, or if that is not possible, only when the function or method is run the first time, in which case the value of the static variable is reported as `null` prior to the first invocation.

### Beispiele

Beispiel #1 Basic uopz_get_static() Usage

    <?php
    function foo() {
        static $bar = 'baz';
    }
    var_dump(uopz_get_static('foo'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }

### Siehe auch

- ReflectionFunctionAbstract::getStaticVariables() - Gets static variables
- uopz_set_static() - Sets the static variables in function or method scope

# uopz_implement

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_implement — Implements an interface at runtime

### Beschreibung

function uopz_implement(string `$class`, string `$interface`): bool

Makes `class` implement `interface`

### Parameter-Liste

`class`

`interface`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

As of PHP 7.4.0, uopz_implement() throws a RuntimeException, if OPcache is enabled, and the class entry of `class` is immutable.

### Beispiele

Beispiel #1 uopz_implement() example

    <?php
    interface myInterface {}

    class myClass {}

    uopz_implement(myClass::class, myInterface::class);

    var_dump(class_implements(myClass::class));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["myInterface"]=>
      string(11) "myInterface"
    }

# uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overload — Overload a VM opcode

Warnung

Diese Funktion wurde mit PECL uopz 5.0.0 ENTFERNT.

### Beschreibung

function uopz_overload(int `$opcode`, Callable `$callable`): void

Overloads the specified `opcode` with the user defined function

### Parameter-Liste

`opcode`

  A valid opcode, see constants for details of supported codes

`callable`

### Rückgabewerte

### Beispiele

Beispiel #1 uopz_overload() example

    <?php
    uopz_overload(ZEND_EXIT, function(){});

    exit();
    echo "Hello World";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hello World

# uopz_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_redefine — Redefine a constant

### Beschreibung

function uopz_redefine(string `$constant`, mixed `$value`): bool
function uopz_redefine(string `$class`, string `$constant`, mixed `$value`): bool

Redefines the given `constant` as `value`

### Parameter-Liste

`class`

  The name of the class containing the constant

`constant`

  The name of the constant

`value`

  The new value for the constant, must be a valid type for a constant variable

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 uopz_redefine() example

    <?php
    define("MY", 100);

    uopz_redefine("MY", 1000);

    echo MY;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1000

# uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_rename — Rename a function at runtime

Warnung

Diese Funktion wurde mit PECL uopz 5.0.0 ENTFERNT.

### Beschreibung

function uopz_rename(string `$function`, string `$rename`): void
function uopz_rename(string `$class`, string `$function`, string `$rename`): void

Renames `function` to `rename`

> Hinweis:

> If both functions exist, this effectively swaps their names

### Parameter-Liste

`class`

  The name of the class containing the function

`function`

  The name of an existing function

`rename`

  The new name for the function

### Rückgabewerte

### Beispiele

Beispiel #1 uopz_rename() example

    <?php
    uopz_rename("strlen", "original_strlen");

    echo original_strlen("Hello World");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    11

Beispiel #2 uopz_rename() class example

    <?php
    class My {
        public function strlen($arg) {
            return strlen($arg);
        }
    }

    uopz_rename(My::class, "strlen", "original_strlen");

    echo My::original_strlen("Hello World");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    11

# uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restore — Restore a previously backed up function

Warnung

Diese Funktion wurde mit PECL uopz 5.0.0 ENTFERNT.

### Beschreibung

function uopz_restore(string `$function`): void
function uopz_restore(string `$class`, string `$function`): void

Restore a previously backed up function

### Parameter-Liste

`class`

  The name of the class containing the function to restore

`function`

  The name of the function

### Rückgabewerte

### Beispiele

Beispiel #1 uopz_restore() example

    <?php
    uopz_backup("fgets");
    uopz_function("fgets", function(){
        return true;
    });
    var_dump(fgets());
    uopz_restore('fgets');
    fgets();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Warning: fgets() expects at least 1 parameter, 0 given in /path/to/script.php on line 8

# uopz_set_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_hook — Sets hook to execute when entering a function or method

### Beschreibung

function uopz_set_hook(string `$function`, Closure `$hook`): bool
function uopz_set_hook(string `$class`, string `$function`, Closure `$hook`): bool

Sets a hook to execute when entering a function or method.

### Parameter-Liste

`class`

  The name of the class.

`function`

  The name of the function or method.

`hook`

  A closure to execute when entering the function or method.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Basic uopz_set_hook() Usage

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    barfoo

### Siehe auch

- uopz_get_hook() - Gets previously set hook on function or method
- uopz_unset_hook() - Removes previously set hook on function or method

# uopz_set_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_mock — Use mock instead of class for new objects

### Beschreibung

function uopz_set_mock(string `$class`, mixed `$mock`): void

If `mock` is a string containing the name of a class then it will be instantiated instead of `class`. `mock` can also be an object.

> Hinweis:

> Only dynamic access to properties and methods will use the `mock` object. Static access still uses the original `class`. See example below.

### Parameter-Liste

`class`

  The name of the class to be mocked.

`mock`

  The mock to use in the form of a string containing the name of the class to use or an object. If a string is passed, it has to be the fully qualified class name. It is recommended to use the `::class` magic constant in this case.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL uopz 6.0.0 | Mocking static members is no longer supported by this function. uopz_redefine() and uopz_set_return(), or Componere can be used instead.

### Beispiele

Beispiel #1 uopz_set_mock() example

    <?php
    class A {
        public function who() {
            echo "A";
        }
    }

    class mockA {
        public function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    (new A)->who();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    mockA

Beispiel #2 uopz_set_mock() example

    <?php
    class A {
        public function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                public function who() {
                                    echo "mockA";
                                }
                            });
    (new A)->who();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    mockA

Beispiel #3 uopz_set_mock() and static members

As of uopz 6.0.0 mocking static members is no longer supported.

    <?php
    class A {
        const CON = 'A';
        public static function who() {
            echo "A";
        }
    }

    uopz_set_mock(A::class, new class {
                                const CON = 'mockA';
                                public static function who() {
                                    echo "mockA";
                                }
                            });
    echo A::CON, PHP_EOL;
    A::who();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    A
    A

Output of the above example in uopz 5:

    mockA
    mockA

### Siehe auch

- uopz_get_mock() - Get the current mock for a class
- uopz_unset_mock() - Unset previously set mock

# uopz_set_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_property — Sets value of existing class or instance property

### Beschreibung

function uopz_set_property(string `$class`, string `$property`, mixed `$value`): void
function uopz_set_property(object `$instance`, string `$property`, mixed `$value`): void

Sets the value of an existing static class property, if `class` is given, or the value of an instance property (regardless whether the instance property already exists), if `instance` is given.

### Parameter-Liste

`class`

  The name of the class.

`instance`

  The object instance.

`property`

  The name of the property.

`value`

  The value to assign to the property.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 Basic uopz_set_property() Usage

    <?php
    class Foo {
       private static $staticBar;
       private $bar;
       public static function testStaticBar() {
          return self::$staticBar;
       }
       public function testBar() {
          return $this->bar;
       }
    }
    $foo = new Foo;
    uopz_set_property('Foo', 'staticBar', 10);
    uopz_set_property($foo, 'bar', 100);
    var_dump(Foo::testStaticBar());
    var_dump($foo->testBar());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(10)

### Siehe auch

- uopz_get_property() - Gets value of class or instance property

# uopz_set_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_return — Provide a return value for an existing function

### Beschreibung

function uopz_set_return(string `$function`, mixed `$value`, bool `$execute` = `false`): bool
function uopz_set_return(
string `$class`,
string `$function`,
mixed `$value`,
bool `$execute` = `false`
): bool

Sets the return value of the `function` to `value`. If `value` is a Closure and `execute` is set, the Closure will be executed in place of the original function. It is possible to call the original function from the Closure.

> Hinweis:

> This function replaces uopz_rename().

### Parameter-Liste

`class`

  The name of the class containing the function

`function`

  The name of an existing function

`value`

  The value the function should return. If a Closure is provided and the execute flag is set, the Closure will be executed in place of the original function.

`execute`

  If true, and a Closure was provided as the value, the Closure will be executed in place of the original function.

### Rückgabewerte

True if succeeded, false otherwise.

### Beispiele

Beispiel #1 uopz_set_return() example

    <?php
    uopz_set_return("strlen", 42);
    echo strlen("Banana");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    42

Beispiel #2 uopz_set_return() example

    <?php
    uopz_set_return("strlen", function($str) { return strlen($str) * 2; }, true );
    echo strlen("Banana");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    12

Beispiel #3 uopz_set_return() class example

    <?php
    class My {
        public static function strlen($arg) {
            return strlen($arg);
        }
    }
    uopz_set_return(My::class, "strlen", function($str) { return strlen($str) * 2; }, true );
    echo My::strlen("Banana");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    12

# uopz_set_static

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_set_static — Sets the static variables in function or method scope

### Beschreibung

function uopz_set_static(string `$function`, array `$static`): void
function uopz_set_static(string `$class`, string `$function`, array `$static`): void

Sets the static variables in function or method scope.

### Parameter-Liste

`class`

  The name of the class.

`function`

  The name of the function or method.

`static`

  The associative array of variable names mapped to their values.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 Basic uopz_set_static() Usage

    <?php
    function foo() {
        static $bar = 'baz';
        var_dump($bar);
    }
    uopz_set_static('foo', ['bar' => 'qux']);
    foo();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "qux"

### Siehe auch

- uopz_get_static() - Gets the static variables from function or method scope

# uopz_undefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_undefine — Undefine a constant

### Beschreibung

function uopz_undefine(string `$constant`): bool
function uopz_undefine(string `$class`, string `$constant`): bool

Removes the constant at runtime

### Parameter-Liste

`class`

  The name of the class containing `constant`

`constant`

  The name of an existing constant

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 uopz_undefine() example

    <?php
    define("MY", true);

    uopz_undefine("MY");

    var_dump(defined("MY"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)

# uopz_unset_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_hook — Removes previously set hook on function or method

### Beschreibung

function uopz_unset_hook(string `$function`): bool
function uopz_unset_hook(string `$class`, string `$function`): bool

Removes the previously set hook on a function or method.

### Parameter-Liste

`class`

  The name of the class.

`function`

  The name of the function or method.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Basic uopz_unset_hook() Usage

    <?php
    function foo() {
        echo 'foo';
    }
    uopz_set_hook('foo', function () {echo 'bar';});
    foo();
    echo PHP_EOL;
    uopz_unset_hook('foo');
    foo();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    barfoo
    foo

### Siehe auch

- uopz_set_hook() - Sets hook to execute when entering a function or method
- uopz_get_hook() - Gets previously set hook on function or method

# uopz_unset_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_mock — Unset previously set mock

### Beschreibung

function uopz_unset_mock(string `$class`): void

Unsets the previously set mock for `class`.

### Parameter-Liste

`class`

  The name of the mocked class.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

A RuntimeException is thrown, if no mock was previously set for `class`.

### Beispiele

Beispiel #1 uopz_unset_mock() example

    <?php
    class A {
        public static function who() {
            echo "A";
        }
    }

    class mockA {
        public static function who() {
            echo "mockA";
        }
    }

    uopz_set_mock(A::class, mockA::class);
    uopz_unset_mock(A::class);
    A::who();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    A

### Siehe auch

- uopz_set_mock() - Use mock instead of class for new objects
- uopz_get_mock() - Get the current mock for a class

# uopz_unset_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_return — Unsets a previously set return value for a function

### Beschreibung

function uopz_unset_return(string `$function`): bool
function uopz_unset_return(string `$class`, string `$function`): bool

Unsets the return value of the `function` previously set by uopz_set_return().

### Parameter-Liste

`class`

  The name of the class containing the function

`function`

  The name of the function

### Rückgabewerte

True on success

### Beispiele

Beispiel #1 uopz_unset_return() example

    <?php
    uopz_set_return("strlen", 42);
    $len = strlen("Banana");
    uopz_unset_return("strlen");
    echo $len + strlen("Banana");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    48

## Inhaltsverzeichnis

- uopz_add_function — Adds non-existent function or method
- uopz_allow_exit — Allows control over disabled exit opcode
- uopz_backup — Backup a function
- uopz_compose — Compose a class
- uopz_copy — Copy a function
- uopz_del_function — Deletes previously added function or method
- uopz_delete — Delete a function
- uopz_extend — Extend a class at runtime
- uopz_flags — Get or set flags on function or class
- uopz_function — Creates a function at runtime
- uopz_get_exit_status — Retrieve the last set exit status
- uopz_get_hook — Gets previously set hook on function or method
- uopz_get_mock — Get the current mock for a class
- uopz_get_property — Gets value of class or instance property
- uopz_get_return — Gets a previous set return value for a function
- uopz_get_static — Gets the static variables from function or method scope
- uopz_implement — Implements an interface at runtime
- uopz_overload — Overload a VM opcode
- uopz_redefine — Redefine a constant
- uopz_rename — Rename a function at runtime
- uopz_restore — Restore a previously backed up function
- uopz_set_hook — Sets hook to execute when entering a function or method
- uopz_set_mock — Use mock instead of class for new objects
- uopz_set_property — Sets value of existing class or instance property
- uopz_set_return — Provide a return value for an existing function
- uopz_set_static — Sets the static variables in function or method scope
- uopz_undefine — Undefine a constant
- uopz_unset_hook — Removes previously set hook on function or method
- uopz_unset_mock — Unset previously set mock
- uopz_unset_return — Unsets a previously set return value for a function

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Uopz Funktionen
  - uopz_add_function — Adds non-existent function or method
  - uopz_allow_exit — Allows control over disabled exit opcode
  - uopz_backup — Backup a function
  - uopz_compose — Compose a class
  - uopz_copy — Copy a function
  - uopz_del_function — Deletes previously added function or method
  - uopz_delete — Delete a function
  - uopz_extend — Extend a class at runtime
  - uopz_flags — Get or set flags on function or class
  - uopz_function — Creates a function at runtime
  - uopz_get_exit_status — Retrieve the last set exit status
  - uopz_get_hook — Gets previously set hook on function or method
  - uopz_get_mock — Get the current mock for a class
  - uopz_get_property — Gets value of class or instance property
  - uopz_get_return — Gets a previous set return value for a function
  - uopz_get_static — Gets the static variables from function or method scope
  - uopz_implement — Implements an interface at runtime
  - uopz_overload — Overload a VM opcode
  - uopz_redefine — Redefine a constant
  - uopz_rename — Rename a function at runtime
  - uopz_restore — Restore a previously backed up function
  - uopz_set_hook — Sets hook to execute when entering a function or method
  - uopz_set_mock — Use mock instead of class for new objects
  - uopz_set_property — Sets value of existing class or instance property
  - uopz_set_return — Provide a return value for an existing function
  - uopz_set_static — Sets the static variables in function or method scope
  - uopz_undefine — Undefine a constant
  - uopz_unset_hook — Removes previously set hook on function or method
  - uopz_unset_mock — Unset previously set mock
  - uopz_unset_return — Unsets a previously set return value for a function

# Windows Cache for PHP

# Einführung

Windows Cache Extension for PHP is a PHP accelerator that is used to increase the speed of PHP applications running on Windows and Windows Server. Once the Windows Cache Extension for PHP is enabled and loaded by the PHP engine, PHP applications can take advantage of the functionality without any code modifications.

The Windows Cache Extension includes 5 different types of caches. The following describes the purpose of each cache type and the benefits it provides.

- PHP Opcode Cache - PHP is a script processing engine, which reads an input stream of data that contains text and/or PHP instructions and produces another stream of data, most commonly in the HTML format. This means that on a web server the PHP engine reads, parses, compiles and executes a PHP script each time that it is requested by a Web client. The reading, parsing and compilation operations put additional load on the web server's CPU and file system and thus affect the overall performance of a PHP web application. The PHP bytecode (opcode) cache is used to store the compiled script bytecode in shared memory so that it can be re-used by PHP engine for subsequent executions of the same script.

  Support for opcode caching was removed in `Wincache 2.0.0`, all users who wish to have an opcache should use the OPcache extension that is included with PHP.

- File Cache - Even with the PHP opcode cache enabled, the PHP engine has to accesses the script files on a file system. When PHP scripts are stored on a remote UNC file share, the file operations introduce a significant performance overhead. The Windows Cache Extension for PHP includes a file cache that is used to store the content of the PHP script files in shared memory, which reduces the amount of file system operations performed by PHP engine.

- Resolve File Path Cache - PHP scripts very often include or operate with files by using relative file paths. Every file path has to be normalized to an absolute file path by the PHP engine. When a PHP application uses many PHP files and accesses them by relative paths, the operation of resolving the paths may negatively impact the application's performance. The Windows Cache Extension for PHP provides a Resolve File Path cache, which is used to store the mappings between relative and absolute file paths, thereby reducing the number of path resolutions that the PHP engine has to perform.

- User Cache (available since version 1.1.0) - PHP scripts can take advantage of the shared memory cache by using the user cache API's. PHP objects and variables can be stored in the user cache and then re-used on subsequent requests. This can be used to improve performance of PHP scripts and to share the data across multiple PHP processes.

- Session Handler (available since version 1.1.0) - The WinCache session handler can be used to store the PHP session data in the shared memory cache. This avoids file system operations for reading and writing session data, which improves performance when large amount of data is stored in PHP session.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- WinCache Statistics Script
- WinCache Session Handler
- WinCache Functions Reroutes

## Anforderungen

The extension is currently supported only on the following configurations:

Windows OS:

- Windows XP SP3 with IIS 5.1 and » FastCGI Extension
- Windows Server 2003 with IIS 6.0 and » FastCGI Extension
- Windows Vista SP1 with IIS 7.0 and FastCGI Module
- Windows Server 2008 with IIS 7.0 and FastCGI Module
- Windows 7 with IIS 7.5 and FastCGI Module
- Windows Server 2008 R2 with IIS 7.5 and FastCGI Module

PHP:

- PHP 5.2.X, Non-thread-safe build
- PHP 5.3 X86, Non-thread-safe VC9 build

> Hinweis: The WinCache Extension can only be used when IIS is configured to run PHP via FastCGI.

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/wincache.

There are two packages for this extension: one package is for PHP versions 5.2.X, and the other package is for PHP 5.3.X. Select the package that is appropriate for the PHP version being used.

To install and enable the extension, follow these steps:

1. Unpack the package into some temporary location.

2. Copy the php_wincache.dll file into the PHP extensions folder. Typically this folder is called "ext" and it is located in the same folder with all PHP binary files. For example: C:\Program Files\PHP\ext.

3. Using a text editor, open the php.ini file, which is usually located in the same folder where all PHP binary files are. For example: C:\Program Files\PHP\php.ini.

4. Add the following line at the end of the php.ini file: `extension = php_wincache.dll`.

5. Save and close the php.ini file.

6. Recycle the IIS Application Pools for PHP to pick up the configuration changes. To check that the extension has been enabled, create a file called phpinfo.php with a PHP code that calls phpinfo function.

7. Save the phpinfo.php file in the root folder of a IIS web site that uses PHP, then open a browser and make a request to http://localhost/phpinfo.php. Search within the returned web page for a section called `wincache`. If the extension is enabled, then the phpinfo output will list the configuration settings provided by the WinCache.

> Hinweis: Do not forget to remove phpinfo.php file from the web site's root folder after verifying that extension has been enabled.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

The following table lists and explains the configuration settings provided by the WinCache extension:

WinCache configuration options
Name | Standard | Minimum | Maximum | Veränderbar | Changelog
--- | --- | --- | --- | --- | ---
wincache.fcenabled | "1" | "0" | "1" | `INI_ALL` | Available as of WinCache 1.0.0
wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Available as of WinCache 1.0.0
wincache.fcachesize | "24" | "5" | "255" | `INI_SYSTEM` | Available as of WinCache 1.0.0
wincache.fcndetect | "1" | "0" | "1" | `INI_SYSTEM` | Available as of WinCache 1.1.0
wincache.maxfilesize | "256" | "10" | "2048" | `INI_SYSTEM` | Available as of WinCache 1.0.0
wincache.ocenabled | "1" | "0" | "1" | `INI_ALL` | Available as of WinCache 1.0.0. Removed as of 2.0.0.0
wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | `INI_SYSTEM` | Available as of WinCache 1.0.0. Removed as of 2.0.0.0
wincache.ocachesize | "96" | "15" | "255" | `INI_SYSTEM` | Available as of WinCache 1.0.0. Removed as of 2.0.0.0
wincache.filecount | "4096" | "1024" | "16384" | `INI_SYSTEM` | Available as of WinCache 1.0.0
wincache.chkinterval | "30" | "0" | "300" | `INI_SYSTEM` | Available as of WinCache 1.0.0
wincache.ttlmax | "1200" | "0" | "7200" | `INI_SYSTEM` | Available as of WinCache 1.0.0
wincache.enablecli | 0 | 0 | 1 | `INI_SYSTEM` | Available as of WinCache 1.0.0
wincache.ignorelist | NULL | NULL | NULL | `INI_ALL` | Available as of WinCache 1.0.0
wincache.namesalt | NULL | NULL | NULL | `INI_SYSTEM` | Available as of WinCache 1.0.0
wincache.ucenabled | 1 | 0 | 1 | `INI_SYSTEM` | Available as of WinCache 1.1.0
wincache.ucachesize | 8 | 5 | 85 | `INI_SYSTEM` | Available as of WinCache 1.1.0
wincache.scachesize | 8 | 5 | 85 | `INI_SYSTEM` | Available as of WinCache 1.1.0
wincache.rerouteini | NULL | NULL | NULL | `INI_SYSTEM` | Available as of WinCache 1.2.0. Removed as of 1.3.7
wincache.reroute_enabled | 1 | 0 | 1 | `INI_SYSTEM`|`INI_PERDIR` | Available as of WinCache 1.3.7
wincache.srwlocks | 1 | 0 | 1 | `INI_SYSTEM` | Available as of WinCache 1.3.6.3. Removed as of 2.0.0.0
wincache.filemapdir | NULL | NULL | NULL | `INI_SYSTEM` | Available as of WinCache 1.3.7.4

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`wincache.fcenabled` bool
  Enables or disables the file cache functionality.
`wincache.fcenabledfilter` string
  Defines a comma-separated list of IIS web site identifiers where file cache should be enabled or disabled. This setting works in conjunction with `wincache.fcenabled`: if `wincache.fcenabled` is set to 1, then the sites listed in the `wincache.fcenabledfilter` will have the file cache turned off; if `wincache.fcenabled` is set to 0, then the sites listed in the `wincache.fcenabledfilter` will have the file cache turned on.
`wincache.fcachesize` int
  Defines the maximum memory size (in megabytes) that is allocated for the file cache. If the total size of all the cached files exceeds the value specified in this setting, then most stale files will be removed from the file cache.
`wincache.fcndetect` bool
  Enables or disables the file change notification detection functionality. If file change notification is supported then it will be used to refresh the opcode and file cache entries as soon as the corresponding files are modified on a file system. If file change notification is not supported, for example when using network file shares, then wincache will poll for file changes at regular time intervals specified by `wincache.chkinterval`.
`wincache.maxfilesize` int
  Defines the maximum allowed size (in kilobytes) for a single file to be cached. If a file size exceeds the specified value, the file will not be cached. This setting applies to the file cache only.
`wincache.ocenabled` bool
  Warnung

  This option has been REMOVED as of 2.0.0.0

  Enables or disables the opcode cache functionality
`wincache.ocenabledfilter` string
  Warnung

  This option has been REMOVED as of 2.0.0.0

  Defines a comma-separated list of IIS web site identifiers where opcode cache should be enabled or disabled. This setting works in conjunction with `wincache.ocenabled`: if `wincache.ocenabled` is set to 1, then the sites listed in the `wincache.ocenabledfilter` will have the opcode cache turned off; if `wincache.ocenabled` is set to 0, then the sites listed in the `wincache.ocenabledfilter` will have the opcode cache turned on.
`wincache.ocachesize` int
  Warnung

  This option has been REMOVED as of 2.0.0.0

  Defines the maximum memory size (in megabytes) that is allocated for the opcode cache. If the cached opcode size exceeds the specified value, then most stale opcode will be removed from the cache. Note that the opcode cache size must be at least 3 times bigger than file cache size. If that is not the case the opcode cache size will be automatically increased.
`wincache.filecount` int
  Defines how many files are expected to be cached by the extension, so that appropriate memory size is allocated at the startup time. If the number of files exceeds the specified value, the WinCache will re-allocate more memory as needed.
`wincache.chkinterval` int
  Defines how often (in seconds) the extension checks for file changes in order to refresh the cache. Setting it to 0 will disable the refreshing of the cache. The file changes will not be reflected in the cache unless the cache entry for that file is removed by scavenger or IIS application pool is recycled or wincache_refresh_if_changed function is called.
`wincache.ttlmax` int
  Defines the maximum time to live (in seconds) for a cached entry without being used. Setting it to 0 will disable the cache scavenger, so the cached entries will never be removed from the cache during the lifetime of the IIS worker process.
`wincache.enablecli` bool
  Defines if caching is enabled when PHP is running in command line (CLI) mode.
`wincache.ignorelist` string

  Defines a list of files that should not be cached by the extension. The files list is specified by using file names only, separated by the pipe symbol - "|".

  Beispiel #1 `wincache.ignorelist` example

      wincache.ignorelist = "index.php|misc.php|admin.php"

`wincache.namesalt` string
  Defines a string that will be used when naming the extension specific objects that are stored in shared memory. This is used to avoid conflicts that may be caused if other applications within an IIS worker process tries to access shared memory. The length of the namesalt string cannot exceed 8 characters.
`wincache.ucenabled` bool
  Enables or disables the user cache functionality.
`wincache.ucachesize` int
  Defines the maximum memory size in megabytes that is allocated for the user cache. If the total size of variables stored in the user cache exceeds the specified value, then the most stale variables will be removed from the cache.
`wincache.scachesize` int
  Defines the maximum memory size in megabytes that is allocated for the session cache. If the total size of data stored in the session cache exceeds the specified value, then the most stale data will be removed from the cache.
`wincache.rerouteini` string
  Warnung

  This option has been REMOVED as of 1.3.7. See `wincache.reroute_enabled` for similar functionality as of 1.3.7.

  Specifies an absolute or a relateve path to the reroute.ini file that contains the list of PHP functions whose implementation should be replaced with the WinCache function equivalents. If a relative path is specified then it is assumed to be relative to the location of php-cgi.exe file.
`wincache.reroute_enabled` bool
  Enables or disables the rerouting of certain file I/O functions through the file cache.
`wincache.srwlocks` bool
  Warnung

  This option has been REMOVED as of 2.0.0.0

  Enables or disables the use of shared reader/writer locks. Disabling is useful when troubleshooting deadlock conditions in WinCache.
`wincache.filemapdir` string
  Specifies an absolute path to a directory where WinCache will store the temporary files used for shared memory segments. This directory must be on the local machine and not on a networked file system. If the directory is not specified, WinCache will use the Windows System Page File for all shared memory segments.

## WinCache Statistics Script

The installation package for WinCache includes a PHP script, wincache.php, that can be used to obtain cache information and statistics.

If the WinCache extension was installed via the Microsoft Web Platform Installer, then this script is located in %SystemDrive%\Program Files\IIS\Windows Cache for PHP\. On a 64-bit version of the Windows Server operating system, the script is located in %SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP. If the extension was installed manually, then the wincache.php will be located in the same folder from which the content of the installation package was extracted.

To use wincache.php, copy it into a root folder of a Web site or into any subfolder. To protect the script, open it in any text editor and replace the values for USERNAME and PASSWORD constants. If any other IIS authentication is enabled on the server, then follow the instructions in the comments:

Beispiel #1 Authentication configuration for wincache.php

    <?php
    /**
     * ======================== CONFIGURATION SETTINGS ==============================
     * If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
     * If you use authentication then replace the default password.
     */
    define('USE_AUTHENTICATION', 1);
    define('USERNAME', 'wincache');
    define('PASSWORD', 'wincache');

    /**
     * The Basic PHP authentication will work only when IIS is configured to support
     * Anonymous Authentication' and nothing else. If IIS is configured to support/use
     * any other kind of authentication like Basic/Negotiate/Digest etc, this will not work.
     * In that case use the array below to define the names of users in your
     * domain/network/workgroup which you want to grant access to.
     */
    $user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');

    /**
     * If the array contains string 'all', then all the users authenticated by IIS
     * will have access to the page. Uncomment the below line and comment above line
     * to grant access to all users who gets authenticated by IIS.
     */
    /* $user_allowed = array('all'); */

    /** ===================== END OF CONFIGURATION SETTINGS ========================== */
    ?>

> Hinweis: Always protect the wincache.php script by using either the built-in authentication or the server's authentication mechanism. Leaving this script unprotected may compromise the security of your web application and web server.

## WinCache Session Handler

The WinCache session handler (available since WinCache 1.1.0) can be used to configure PHP to store the session data in shared memory session cache. Using shared memory instead of the default file session storage helps improve performance of PHP applications that store large amount of data in session objects. Wincache session cache uses file-backed shared memory, which ensures that the session data is not lost during recycling of IIS application pools.

To configure PHP to use WinCache session handler set the php.ini setting session.save_handler to wincache. By default the Windows temporary file location is used for storing the session data. To change the location of the session file use session.save_path directive.

Beispiel #1 Enabling WinCache session handler

    session.save_handler = wincache
    session.save_path = C:\inetpub\temp\session\

## WinCache Functions Reroutes

NOTE: wincache.rerouteini was removed as of WinCache 1.3.7.0. It has been replaced with automatic function reroutes. See: wincache.reroute_enabled.

The WinCache functions reroutes (available since WinCache 1.2.0, removed since WinCache 1.3.7.0) can be used to replace built-in PHP functions with their equivalents that are optimized for a particular purpose. WinCache extension includes Windows-optimized implementation of PHP file functions that may improve performance of PHP applications in cases when PHP has to access files on network shares. The optimized implementation is provided for the following functions:

- file_exists
- file_get_contents
- readfile
- is_readable
- is_writable
- is_dir
- realpath
- filesize

To configure WinCache to use the functions reroutes use the file reroute.ini that is included in WinCache installation package. Copy this file into the same directory where php.ini file is located. After that add the wincache.rerouteini setting in php.ini and specify an absolute or relative path to the reroute.ini file.

Beispiel #1 Enabling WinCache functions reroutes

    wincache.rerouteini = C:\PHP\reroute.ini

> Hinweis: If WinCache functions reroutes are enabled it is recommended to increase the WinCache file cache size. This can be done by using wincache.fcachesize setting.

The reroute.ini file contains the mappings between the native PHP functions and their equivalents in WinCache. Each line in the file defines a mapping by using the following syntax:

`<PHP function name>:[<number of function parameters>]=<wincache function name>`

The example of the file is shown below. In this example the calls to PHP function file_get_contents() will be replaced with calls to wincache_file_get_contents() only if the number of parameters passed to the function is less than or equals to 2. Specifying the number of parameters is useful when replacement function does not handle all the function's parameters.

Beispiel #2 Reroute.ini file content

    [FunctionRerouteList]
    file_exists=wincache_file_exists
    file_get_contents:2=wincache_file_get_contents
    readfile:2=wincache_readfile
    is_readable=wincache_is_readable
    is_writable=wincache_is_writable
    is_writeable=wincache_is_writable
    is_file=wincache_is_file
    is_dir=wincache_is_dir
    realpath=wincache_realpath
    filesize=wincache_filesize

# WinCache Funktionen

# wincache_fcache_fileinfo

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — Retrieves information about files cached in the file cache

### Beschreibung

function wincache_fcache_fileinfo(bool `$summaryonly` = `false`): array|false

Retrieves information about file cache content and its usage.

### Parameter-Liste

`summaryonly`

  Controls whether the returned array will contain information about individual cache entries along with the file cache summary.

### Rückgabewerte

Array of meta data about file cache Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `total_cache_uptime` - total time in seconds that the file cache has been active
- `total_file_count` - total number of files that are currently in the file cache
- `total_hit_count` - number of times the files have been served from the file cache
- `total_miss_count` - number of times the files have not been found in the file cache

- `file_entries` - an array that contains the information about all the cached files:

  - `file_name` - absolute file name of the cached file
  - `add_time` - time in seconds since the file has been added to the file cache
  - `use_time` - time in seconds since the file has been accessed in the file cache
  - `last_check` - time in seconds since the file has been checked for modifications
  - `hit_count` - number of times the file has been served from the cache
  - `file_size` - size of the cached file in bytes

### Beispiele

Beispiel #1 A wincache_fcache_fileinfo() example

    <pre>
    <?php
    print_r(wincache_fcache_fileinfo());
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (   [total_cache_uptime] => 3234
        [total_file_count] => 5
        [total_hit_count] => 0
        [total_miss_count] => 1
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 1
                        [use_time] => 0
                        [last_check] => 1
                        [hit_count] => 1
                        [file_size] => 2435
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Siehe auch

- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage

# wincache_fcache_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfo — Retrieves information about file cache memory usage

### Beschreibung

function wincache_fcache_meminfo(): array|false

Retrieves information about memory usage by file cache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Array of meta data about file cache memory usage Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `memory_total` - amount of memory in bytes allocated for the file cache
- `memory_free` - amount of free memory in bytes available for the file cache
- `num_used_blks` - number of memory blocks used by the file cache
- `num_free_blks` - number of free memory blocks available for the file cache
- `memory_overhead` - amount of memory in bytes used for the file cache internal structures

### Beispiele

Beispiel #1 A wincache_fcache_meminfo() example

    <pre>
    <?php
    print_r(wincache_fcache_meminfo());
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 131339120
        [num_used_blks] => 361
        [num_free_blks] => 3
        [memory_overhead] => 5856
    )

### Siehe auch

- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage

# wincache_lock

(PECL wincache >= 1.1.0)

wincache_lock — Acquires an exclusive lock on a given key

### Beschreibung

function wincache_lock(string `$key`, bool `$isglobal` = `false`): bool

Obtains an exclusive lock on a given key. The execution of the current script will be blocked until the lock can be obtained. Once the lock is obtained, the other scripts that try to request the lock by using the same key will be blocked, until the current script releases the lock by using wincache_unlock().

Warnung

Using of the wincache_lock() and wincache_unlock() can cause deadlocks when executing PHP scripts in a multi-process environment like FastCGI. Do not use these functions unless you are absolutely sure you need to use them. For the majority of the operations on the user cache it is not necessary to use these functions.

### Parameter-Liste

`key`

  Name of the key in the cache to get the lock on.

`isglobal`

  Controls whether the scope of the lock is system-wide or local. Local locks are scoped to the application pool in IIS FastCGI case or to all php processes that have the same parent process identifier.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Using wincache_lock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // do an exclusive lock
        ftruncate($fp, 0); // truncate file
        fwrite($fp, "Write something here\n");
        wincache_unlock(“lock_txt_lock”); // release the lock
    } else {
        echo "Couldn't get the lock!";
    }
    fclose($fp);
    ?>

### Siehe auch

- wincache_unlock() - Releases an exclusive lock on a given key
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache

# wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfo — Retrieves information about files cached in the opcode cache

### Beschreibung

function wincache_ocache_fileinfo(bool `$summaryonly` = `false`): array|false

Retrieves information about opcode cache content and its usage.

Warnung

Diese Funktion wurde in PHP 7.0.0 ENTFERNT.

### Parameter-Liste

`summaryonly`

  Controls whether the returned array will contain information about individual cache entries along with the opcode cache summary.

### Rückgabewerte

Array of meta data about opcode cache Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `total_cache_uptime` - total time in seconds that the opcode cache has been active
- `total_file_count` - total number of files that are currently in the opcode cache
- `total_hit_count` - number of times the compiled opcode have been served from the cache
- `total_miss_count` - number of times the compiled opcode have not been found in the cache
- `is_local_cache` - true is the cache metadata is for a local cache instance, false if the metadata is for the global cache

- `file_entries` - an array that contains the information about all the cached files:

  - `file_name` - absolute file name of the cached file
  - `add_time` - time in seconds since the file has been added to the opcode cache
  - `use_time` - time in seconds since the file has been accessed in the opcode cache
  - `last_check` - time in seconds since the file has been checked for modifications
  - `hit_count` - number of times the file has been served from the cache
  - `function_count` - number of functions in the cached file
  - `class_count` - number of classes in the cached file

### Beispiele

Beispiel #1 A wincache_ocache_fileinfo() example

    <pre>
    <?php
    print_r(wincache_ocache_fileinfo());
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [file_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Siehe auch

- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage

# wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfo — Retrieves information about opcode cache memory usage

### Beschreibung

function wincache_ocache_meminfo(): array|false

Retrieves information about memory usage by opcode cache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Array of meta data about opcode cache memory usage Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `memory_total` - amount of memory in bytes allocated for the opcode cache
- `memory_free` - amount of free memory in bytes available for the opcode cache
- `num_used_blks` - number of memory blocks used by the opcode cache
- `num_free_blks` - number of free memory blocks available for the opcode cache
- `memory_overhead` - amount of memory in bytes used for the opcode cache internal structures

Warnung

Diese Funktion wurde in PHP 7.0.0 ENTFERNT.

### Beispiele

Beispiel #1 A wincache_ocache_meminfo() example

    <pre>
    <?php
    print_r(wincache_ocache_meminfo());
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [memory_total] => 134217728
        [memory_free] => 112106972
        [num_used_blks] => 15469
        [num_free_blks] => 4
        [memory_overhead] => 247600
    )

### Siehe auch

- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage

# wincache_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changed — Refreshes the cache entries for the cached files

### Beschreibung

function wincache_refresh_if_changed(array `$files` = NULL): bool

Refreshes the cache entries for the files, whose names were passed in the input argument. If no argument is specified then refreshes all the entries in the cache.

### Parameter-Liste

`files`

  An array of file names for files that need to be refreshed. An absolute or relative file paths can be used.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

WinCache performs regular checks on the cached files to ensure that if any file has changed then the corresponding entry in the cache is updated. By default this check is performed every 30 seconds. If, for example, a PHP script updates another PHP script where the application's configuration settings are stored, then it may happen that after the configuration settings have been saved to a file, the application is still using old settings for some time until the cache is refreshed. In those cases it may be preferrable to refresh the cache right after the file has been changed. The following example shows how this can be done.

Beispiel #1 A wincache_refresh_if_changed() example

    <?php
    $filename = 'C:\inetpub\wwwroot\config.php';
    $handle = fopen($filename, 'w+');
    if ($handle === FALSE) die('Failed to open file '.$filename.' for writing');
    fwrite($handle, '<?php $setting=something; ?>');
    fclose($handle);
    wincache_refresh_if_changed(array($filename));
    ?>

### Siehe auch

- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache

# wincache_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfo — Retrieves information about resolve file path cache

### Beschreibung

function wincache_rplist_fileinfo(bool `$summaryonly` = `false`): array|false

Retrieves information about cached mappings between relative file paths and corresponding absolute file paths.

### Parameter-Liste

`summaryonly`

### Rückgabewerte

Array of meta data about the resolve file path cache Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `total_file_count` - total number of file path mappings stored in the cache

- `rplist_entries` - an array that contains the information about all the cached file paths:

  - `resolve_path` - path to a file
  - `subkey_data` - corresponding absolute path to a file

### Beispiele

Beispiel #1 A wincache_rplist_fileinfo() example

    <pre>
    <?php
    print_r(wincache_rplist_fileinfo());
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [total_file_count] => 5
        [rplist_entries] => Array
            (
                [1] => Array
                    (
                        [resolve_path] => checkcache.php
                        [subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
                    )

                [2] => Array (...iterates for each cached file)
            )
    )

### Siehe auch

- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage

# wincache_rplist_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfo — Retrieves information about memory usage by the resolve file path cache

### Beschreibung

function wincache_rplist_meminfo(): array|false

Retrieves information about memory usage by resolve file path cache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Array of meta data that describes memory usage by resolve file path cache. Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `memory_total` - amount of memory in bytes allocated for the resolve file path cache
- `memory_free` - amount of free memory in bytes available for the resolve file path cache
- `num_used_blks` - number of memory blocks used by the resolve file path cache
- `num_free_blks` - number of free memory blocks available for the resolve file path cache
- `memory_overhead` - amount of memory in bytes used for the internal structures of resolve file path cache

### Beispiele

Beispiel #1 A wincache_rplist_meminfo() example

    <pre>
    <?php
    print_r(wincache_rplist_meminfo());
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [memory_total] => 9437184
        [memory_free] => 9416744
        [num_used_blks] => 23
        [num_free_blks] => 1
        [memory_overhead] => 416
    )

### Siehe auch

- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage

# wincache_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_info — Retrieves information about files cached in the session cache

### Beschreibung

function wincache_scache_info(bool `$summaryonly` = `false`): array|false

Retrieves information about session cache content and its usage.

### Parameter-Liste

`summaryonly`

  Controls whether the returned array will contain information about individual cache entries along with the session cache summary.

### Rückgabewerte

Array of meta data about session cache Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `total_cache_uptime` - total time in seconds that the session cache has been active
- `total_item_count` - total number of elements that are currently in the session cache
- `is_local_cache` - true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
- `total_hit_count` - number of times the data has been served from the cache
- `total_miss_count` - number of times the data has not been found in the cache

- `scache_entries` - an array that contains the information about all the cached items:

  - `key_name` - name of the key which is used to store the data
  - `value_type` - type of value stored by the key
  - `use_time` - time in seconds since the file has been accessed in the opcode cache
  - `last_check` - time in seconds since the file has been checked for modifications
  - `ttl_seconds` - time remaining for the data to live in the cache, 0 meaning infinite
  - `age_seconds` - time elapsed from the time data has been added in the cache
  - `hitcount` - number of times data has been served from the cache

### Beispiele

Beispiel #1 A wincache_scache_info() example

    <pre>
    <?php
    print_r(wincache_scache_info());
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [total_cache_uptime] => 17357
        [total_file_count] => 121
        [total_hit_count] => 36562
        [total_miss_count] => 201
        [scache_entries] => Array
            (
                [1] => Array
                    (
                        [file_name] => c:\inetpub\wwwroot\checkcache.php
                        [add_time] => 17356
                        [use_time] => 7
                        [last_check] => 10
                        [hit_count] => 454
                        [function_count] => 0
                        [class_count] => 1
                    )
                [2] => Array (...iterates for each cached file)
            )
    )

### Siehe auch

- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage

# wincache_scache_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfo — Retrieves information about session cache memory usage

### Beschreibung

function wincache_scache_meminfo(): array|false

Retrieves information about memory usage by session cache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Array of meta data about session cache memory usage Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `memory_total` - amount of memory in bytes allocated for the session cache
- `memory_free` - amount of free memory in bytes available for the session cache
- `num_used_blks` - number of memory blocks used by the session cache
- `num_free_blks` - number of free memory blocks available for the session cache
- `memory_overhead` - amount of memory in bytes used for the session cache internal structures

### Beispiele

Beispiel #1 A wincache_scache_meminfo() example

    <pre>
    <?php
    print_r(wincache_scache_meminfo());
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Siehe auch

- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache

# wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — Adds a variable in user cache only if variable does not already exist in the cache

### Beschreibung

function wincache_ucache_add(string `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_add(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Adds a variable in user cache, only if this variable doesn't already exist in the cache. The added variable remains in the user cache unless its time to live expires or it is deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.

### Parameter-Liste

`key`

  Store the variable using this `key` name. If a variable with same key is already present the function will fail and return `false`. `key` is case sensitive. To override the value even if `key` is present use wincache_ucache_set() function instad. `key` can also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition.

`value`

  Value of a variable to store. `Value` supports all data types except resources, such as file handles. This parameter is ignored if first argument is an array. A general guidance is to pass `null` as `value` while using array as `key`. If `value` is an object, or an array containing objects, then the objects will be serialized. See __sleep() for details on serializing objects.

`values`

  Associative array of keys and values.

`ttl`

  Time for the variable to live in the cache in seconds. After the value specified in `ttl` has passed the stored variable will be deleted from the cache. This parameter takes a default value of `0` which means the variable will stay in the cache unless explicitly deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.

### Rückgabewerte

If `key` is string, the function returns `true` on success and `false` on failure.

If `key` is an array, the function returns:

- If all the name => value pairs in the array can be set, function returns an empty array;
- If all the name => value pairs in the array cannot be set, function returns `false`;
- If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.

### Beispiele

Beispiel #1 wincache_ucache_add() with `key` as a string

    <?php
    $bar = 'BAR';
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_add('foo', $bar));
    var_dump(wincache_ucache_get('foo'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    string(3) "BAR"

Beispiel #2 wincache_ucache_add() with `key` as an array

    <?php
    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_add($colors_array));
    var_dump(wincache_ucache_get('Blue'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(0) { }
    array(4) {
      ["green"]=> int(-1)
      ["Blue"]=> int(-1)
      ["yellow"]=> int(-1)
      ["cyan"]=> int(-1)
    }
    string(1) "6"

### Siehe auch

- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- __sleep()

# wincache_ucache_cas

(PECL wincache >= 1.1.0)

wincache_ucache_cas — Compares the variable with old value and assigns new value to it

### Beschreibung

function wincache_ucache_cas(string `$key`, int `$old_value`, int `$new_value`): bool

Compares the variable associated with the `key` with `old_value` and if it matches then assigns the `new_value` to it.

### Parameter-Liste

`key`

  The `key` that is used to store the variable in the cache. `key` is case sensitive.

`old_value`

  Old value of the variable pointed by `key` in the user cache. The value should be of type `long`, otherwise the function returns `false`.

`new_value`

  New value which will get assigned to variable pointer by `key` if a match is found. The value should be of type `long`, otherwise the function returns `false`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Using wincache_ucache_cas()

    <?php
    wincache_ucache_set('counter', 2922);
    var_dump(wincache_ucache_cas('counter', 2922, 1));
    var_dump(wincache_ucache_get('counter'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    int(1)

### Siehe auch

- wincache_ucache_inc() - Increments the value associated with the key
- wincache_ucache_dec() - Decrements the value associated with the key

# wincache_ucache_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clear — Deletes entire content of the user cache

### Beschreibung

function wincache_ucache_clear(): bool

Clears/deletes all the values stored in the user cache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 using wincache_ucache_clear()

    <?php
    wincache_ucache_set('green', 1);
    wincache_ucache_set('red', 2);
    wincache_ucache_set('orange', 4);
    wincache_ucache_set('blue', 8);
    wincache_ucache_set('cyan', 16);
    $array1 = array('green', 'red', 'orange', 'blue', 'cyan');
    var_dump(wincache_ucache_get($array1));
    var_dump(wincache_ucache_clear());
    var_dump(wincache_ucache_get($array1));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(5) { ["green"]=> int(1)
               ["red"]=> int(2)
               ["orange"]=> int(4)
               ["blue"]=> int(8)
               ["cyan"]=> int(16) }
    bool(true)
    bool(false)

### Siehe auch

- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache

# wincache_ucache_dec

(PECL wincache >= 1.1.0)

wincache_ucache_dec — Decrements the value associated with the key

### Beschreibung

function wincache_ucache_dec(string `$key`, int `$dec_by` = 1, bool `&$success` = ?): mixed

Decrements the value associated with the `key` by 1 or as specified by `dec_by`.

### Parameter-Liste

`key`

  The `key` that was used to store the variable in the cache. `key` is case sensitive.

`dec_by`

  The value by which the variable associated with the `key` will get decremented. If the argument is a floating point number it will be truncated to nearest integer. The variable associated with the `key` should be of type `long`, otherwise the function fails and returns `false`.

`success`

  Will be set to `true` on success and `false` on failure.

### Rückgabewerte

Returns the decremented value on success and `false` on failure.

### Beispiele

Beispiel #1 Using wincache_ucache_dec()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_dec('counter', 2923, $success));
    var_dump($success);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(2922)
    bool(true)

### Siehe auch

- wincache_ucache_inc() - Increments the value associated with the key
- wincache_ucache_cas() - Compares the variable with old value and assigns new value to it

# wincache_ucache_delete

(PECL wincache >= 1.1.0)

wincache_ucache_delete — Deletes variables from the user cache

### Beschreibung

function wincache_ucache_delete(mixed `$key`): bool

Deletes the elements in the user cache pointed by `key`.

### Parameter-Liste

`key`

  The `key` that was used to store the variable in the cache. `key` is case sensitive. `key` can be an array of keys.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

If `key` is an array then the function returns `false` if every element of the array fails to get deleted from the user cache, otherwise returns an array which consists of all the keys that are deleted.

### Beispiele

Beispiel #1 Using wincache_ucache_delete() with `key` as a string

    <?php
    wincache_ucache_set('foo', 'bar');
    var_dump(wincache_ucache_delete('foo'));
    var_dump(wincache_ucache_exists('foo'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)

Beispiel #2 Usingwincache_ucache_delete() with `key` as an array

    <?php
    $array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('green', 'blue', 'yellow', 'cyan');
    var_dump(wincache_ucache_delete($array2));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) { [0]=> string(5) "green"
               [1]=> string(4) "blue"
               [2]=> string(6) "yellow"
               [3]=> string(4) "cyan" }

Beispiel #3 Using wincache_ucache_delete() with `key` as an array where some elements cannot be deleted

    <?php
    $array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('orange', 'red', 'yellow', 'cyan');
    var_dump(wincache_ucache_delete($array2));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) { [0]=> string(6) "yellow"
               [1]=> string(4) "cyan" }

### Siehe auch

- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache

# wincache_ucache_exists

(PECL wincache >= 1.1.0)

wincache_ucache_exists — Checks if a variable exists in the user cache

### Beschreibung

function wincache_ucache_exists(string `$key`): bool

Checks if a variable with the `key` exists in the user cache or not.

### Parameter-Liste

`key`

  The `key` that was used to store the variable in the cache. `key` is case sensitive.

### Rückgabewerte

Returns `true` if variable with the `key` exitsts, otherwise returns `false`.

### Beispiele

Beispiel #1 Using wincache_ucache_exists()

    <?php
    if (!wincache_ucache_exists('green'))
        wincache_ucache_set('green', 1);
    var_dump(wincache_ucache_exists('green'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache

# wincache_ucache_get

(PECL wincache >= 1.1.0)

wincache_ucache_get — Gets a variable stored in the user cache

### Beschreibung

function wincache_ucache_get(mixed `$key`, bool `&$success` = ?): mixed

Gets a variable stored in the user cache.

### Parameter-Liste

`key`

  The `key` that was used to store the variable in the cache. `key` is case sensitive. `key` can be an array of keys. In this case the return value will be an array of values of each element in the `key` array. If an object, or an array containing objects, is returned, then the objects will be unserialized. See __wakeup() for details on unserializing objects.

`success`

  Will be set to `true` on success and `false` on failure.

### Rückgabewerte

If `key` is a string, the function returns the value of the variable stored with that key. The `success` is set to `true` on success and to `false` on failure.

The `key` is an array, the parameter `success` is always set to `true`. The returned array (name => value pairs) will contain only those name => value pairs for which the get operation in user cache was successful. If none of the keys in the key array finds a match in the user cache an empty array will be returned.

### Beispiele

Beispiel #1 wincache_ucache_get() with `key` as a string

    <?php
    wincache_ucache_add('color', 'blue');
    var_dump(wincache_ucache_get('color', $success));
    var_dump($success);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(4) "blue"
    bool(true)

Beispiel #2 wincache_ucache_get() with `key` as an array

    <?php
    $array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    wincache_ucache_set($array1);
    $array2 = array('green', 'Blue', 'yellow', 'cyan');
    var_dump(wincache_ucache_get($array2, $success));
    var_dump($success);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) { ["green"]=> string(1) "5"
               ["Blue"]=> string(1) "6"
               ["yellow"]=> string(1) "7"
               ["cyan"]=> string(1) "8" }
    bool(true)

### Siehe auch

- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- __wakeup()

# wincache_ucache_inc

(PECL wincache >= 1.1.0)

wincache_ucache_inc — Increments the value associated with the key

### Beschreibung

function wincache_ucache_inc(string `$key`, int `$inc_by` = 1, bool `&$success` = ?): mixed

Increments the value associated with the `key` by 1 or as specified by `inc_by`.

### Parameter-Liste

`key`

  The `key` that was used to store the variable in the cache. `key` is case sensitive.

`inc_by`

  The value by which the variable associated with the `key` will get incremented. If the argument is a floating point number it will be truncated to nearest integer. The variable associated with the `key` should be of type `long`, otherwise the function fails and returns `false`.

`success`

  Will be set to `true` on success and `false` on failure.

### Rückgabewerte

Returns the incremented value on success and `false` on failure.

### Beispiele

Beispiel #1 Using wincache_ucache_inc()

    <?php
    wincache_ucache_set('counter', 1);
    var_dump(wincache_ucache_inc('counter', 2921, $success));
    var_dump($success);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(2922)
    bool(true)

### Siehe auch

- wincache_ucache_dec() - Decrements the value associated with the key
- wincache_ucache_cas() - Compares the variable with old value and assigns new value to it

# wincache_ucache_info

(PECL wincache >= 1.1.0)

wincache_ucache_info — Retrieves information about data stored in the user cache

### Beschreibung

function wincache_ucache_info(bool `$summaryonly` = `false`, string `$key` = NULL): array|false

Retrieves information about data stored in the user cache.

### Parameter-Liste

`summaryonly`

  Controls whether the returned array will contain information about individual cache entries along with the user cache summary.

`key`

  The key of an entry in the user cache. If specified then the returned array will contain information only about that cache entry. If not specified and `summaryonly` is set to `false` then the returned array will contain information about all entries in the cache.

### Rückgabewerte

Array of meta data about user cache Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `total_cache_uptime` - total time in seconds that the user cache has been active
- `total_item_count` - total number of elements that are currently in the user cache
- `is_local_cache` - true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
- `total_hit_count` - number of times the data has been served from the cache
- `total_miss_count` - number of times the data has not been found in the cache

- `ucache_entries` - an array that contains the information about all the cached items:

  - `key_name` - name of the key which is used to store the data
  - `value_type` - type of value stored by the key
  - `use_time` - time in seconds since the file has been accessed in the opcode cache
  - `last_check` - time in seconds since the file has been checked for modifications
  - `is_session` - indicates if the data is a session variable
  - `ttl_seconds` - time remaining for the data to live in the cache, 0 meaning infinite
  - `age_seconds` - time elapsed from the time data has been added in the cache
  - `hitcount` - number of times data has been served from the cache

### Beispiele

Beispiel #1 Using wincache_ucache_info()

    <?php
    wincache_ucache_get('green');
    wincache_ucache_set('green', 2922);
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    wincache_ucache_get('green');
    print_r(wincache_ucache_info());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    ( ["total_cache_uptime"] => int(0)
      ["is_local_cache"] => bool(false)
      ["total_item_count"] => int(1)
      ["total_hit_count"] => int(3)
      ["total_miss_count"] => int(1)
      ["ucache_entries"] => Array(1)
        ( [1] => Array(6)
          (
            ["key_name"] => string(5) "green"
            ["value_type"] => string(4) "long"
            ["is_session"] => int(0)
            ["ttl_seconds"] => int(0)
            ["age_seconds"] => int(0)
            ["hitcount"] => int(3)
           )
        )
    )

### Siehe auch

- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage

# wincache_ucache_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfo — Retrieves information about user cache memory usage

### Beschreibung

function wincache_ucache_meminfo(): array|false

Retrieves information about memory usage by user cache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Array of meta data about user cache memory usage Bei einem Fehler wird `false` zurückgegeben.

The array returned by this function contains the following elements:

- `memory_total` - amount of memory in bytes allocated for the user cache
- `memory_free` - amount of free memory in bytes available for the user cache
- `num_used_blks` - number of memory blocks used by the user cache
- `num_free_blks` - number of free memory blocks available for the user cache
- `memory_overhead` - amount of memory in bytes used for the user cache internal structures

### Beispiele

Beispiel #1 A wincache_ucache_meminfo() example

    <pre>
    <?php
    print_r(wincache_ucache_meminfo());
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [memory_total] => 5242880
        [memory_free] => 5215056
        [num_used_blks] => 6
        [num_free_blks] => 3
        [memory_overhead] => 176
    )

### Siehe auch

- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage

# wincache_ucache_set

(PECL wincache >= 1.1.0)

wincache_ucache_set — Adds a variable in user cache and overwrites a variable if it already exists in the cache

### Beschreibung

function wincache_ucache_set(mixed `$key`, mixed `$value`, int `$ttl` = 0): bool
function wincache_ucache_set(array `$values`, mixed `$unused` = NULL, int `$ttl` = 0): bool

Adds a variable in user cache. Overwrites a variable if it already exists in the cache. The added or updated variable remains in the user cache unless its time to live expires or it is deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.

### Parameter-Liste

`key`

  Store the variable using this `key` name. If a variable with same `key` is already present the function will overwrite the previous value with the new one. `key` is case sensitive. `key` can also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition.

`value`

  Value of a variable to store. `Value` supports all data types except resources, such as file handles. This parameter is ignored if first argument is an array. A general guidance is to pass `null` as `value` while using array as `key`. If `value` is an object, or an array containing objects, then the objects will be serialized. See __sleep() for details on serializing objects.

`values`

  Associative array of keys and values.

`ttl`

  Time for the variable to live in the cache in seconds. After the value specified in `ttl` has passed the stored variable will be deleted from the cache. This parameter takes a default value of `0` which means the variable will stay in the cache unless explicitly deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.

### Rückgabewerte

If `key` is string, the function returns `true` on success and `false` on failure.

If `key` is an array, the function returns:

- If all the name => value pairs in the array can be set, function returns an empty array;
- If all the name => value pairs in the array cannot be set, function returns `false`;
- If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.

### Beispiele

Beispiel #1 wincache_ucache_set() with `key` as a string

    <?php
    $bar = 'BAR';
    var_dump(wincache_ucache_set('foo', $bar));
    var_dump(wincache_ucache_get('foo'));
    $bar1 = 'BAR1';
    var_dump(wincache_ucache_set('foo', $bar1));
    var_dump(wincache_ucache_get('foo'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    string(3) "BAR"
    bool(true)
    string(3) "BAR1"

Beispiel #2 wincache_ucache_set() with `key` as an array

    <?php
    $colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_set($colors_array));
    var_dump(wincache_ucache_get('Blue'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(0) {}
    array(0) {}
    string(1) "6"

### Siehe auch

- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- __sleep()

# wincache_unlock

(PECL wincache >= 1.1.0)

wincache_unlock — Releases an exclusive lock on a given key

### Beschreibung

function wincache_unlock(string `$key`): bool

Releases an exclusive lock that was obtained on a given key by using wincache_lock(). If any other process was blocked waiting for the lock on this key, that process will be able to obtain the lock.

Warnung

Using of the wincache_lock() and wincache_unlock() can cause deadlocks when executing PHP scripts in a multi-process environment like FastCGI. Do not use these functions unless you are absolutely sure you need to use them. For the majority of the operations on the user cache it is not necessary to use these functions.

### Parameter-Liste

`key`

  Name of the key in the cache to release the lock on.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Using wincache_unlock()

    <?php
    $fp = fopen("/tmp/lock.txt", "r+");
    if (wincache_lock(“lock_txt_lock”)) { // do an exclusive lock
        ftruncate($fp, 0); // truncate file
        fwrite($fp, "Write something here\n");
        wincache_unlock(“lock_txt_lock”); // release the lock
    } else {
        echo "Couldn't get the lock!";
    }
    fclose($fp);
    ?>

### Siehe auch

- wincache_lock() - Acquires an exclusive lock on a given key
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache

## Inhaltsverzeichnis

- wincache_fcache_fileinfo — Retrieves information about files cached in the file cache
- wincache_fcache_meminfo — Retrieves information about file cache memory usage
- wincache_lock — Acquires an exclusive lock on a given key
- wincache_ocache_fileinfo — Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo — Retrieves information about opcode cache memory usage
- wincache_refresh_if_changed — Refreshes the cache entries for the cached files
- wincache_rplist_fileinfo — Retrieves information about resolve file path cache
- wincache_rplist_meminfo — Retrieves information about memory usage by the resolve file path cache
- wincache_scache_info — Retrieves information about files cached in the session cache
- wincache_scache_meminfo — Retrieves information about session cache memory usage
- wincache_ucache_add — Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_cas — Compares the variable with old value and assigns new value to it
- wincache_ucache_clear — Deletes entire content of the user cache
- wincache_ucache_dec — Decrements the value associated with the key
- wincache_ucache_delete — Deletes variables from the user cache
- wincache_ucache_exists — Checks if a variable exists in the user cache
- wincache_ucache_get — Gets a variable stored in the user cache
- wincache_ucache_inc — Increments the value associated with the key
- wincache_ucache_info — Retrieves information about data stored in the user cache
- wincache_ucache_meminfo — Retrieves information about user cache memory usage
- wincache_ucache_set — Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_unlock — Releases an exclusive lock on a given key

# Building for Windows

## Inhaltsverzeichnis

- Prerequisites
- Compiling and building
- Verifying the build

## Prerequisites

Building WinCache extension will require:

1. PHP source code
2. PHP build environment
3. WinCache source code

For completing first two steps, follow the step-by-step guide for how to » build PHP on Windows.

For getting the WinCache source code follow the instructions described in Downloading PECL extensions.

## Compiling and building

The following steps describe how to compile and build WinCache on Windows OS:

1. Open a command prompt which is used to build PHP

2. Go to the root folder where PHP sources are present

3. Run the command:

       cscript.exe win32\build\buildconf.js

4. Run the command:

       configure.bat --help

   The output will contain a new flag `--enable-wincache`.

5. Run the command:

       configure.js [all options used to build PHP] --enable-wincache

   `--enable-wincache` is the only extra option which is required to ensure that WinCache extension gets built properly. This option will build WinCache and will statically link it with PHP dll. To build WinCache extension as a stand-alone DLL use the option `--enable-wincache=shared`.

6. Run the command:

       nmake

## Verifying the build

The following steps describe how to verify that WinCache has been built correctly:

1. Go to the folder where the PHP binaries are built

2. Run the command:

       php.exe -n -d extension=php_wincache.dll -re wincache

   If WinCache has been built properly, the output of this command will list the INI directives and functions supported by WinCache.

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - WinCache Statistics Script
  - WinCache Session Handler
  - WinCache Functions Reroutes
- WinCache Funktionen
  - wincache_fcache_fileinfo — Retrieves information about files cached in the file cache
  - wincache_fcache_meminfo — Retrieves information about file cache memory usage
  - wincache_lock — Acquires an exclusive lock on a given key
  - wincache_ocache_fileinfo — Retrieves information about files cached in the opcode cache
  - wincache_ocache_meminfo — Retrieves information about opcode cache memory usage
  - wincache_refresh_if_changed — Refreshes the cache entries for the cached files
  - wincache_rplist_fileinfo — Retrieves information about resolve file path cache
  - wincache_rplist_meminfo — Retrieves information about memory usage by the resolve file path cache
  - wincache_scache_info — Retrieves information about files cached in the session cache
  - wincache_scache_meminfo — Retrieves information about session cache memory usage
  - wincache_ucache_add — Adds a variable in user cache only if variable does not already exist in the cache
  - wincache_ucache_cas — Compares the variable with old value and assigns new value to it
  - wincache_ucache_clear — Deletes entire content of the user cache
  - wincache_ucache_dec — Decrements the value associated with the key
  - wincache_ucache_delete — Deletes variables from the user cache
  - wincache_ucache_exists — Checks if a variable exists in the user cache
  - wincache_ucache_get — Gets a variable stored in the user cache
  - wincache_ucache_inc — Increments the value associated with the key
  - wincache_ucache_info — Retrieves information about data stored in the user cache
  - wincache_ucache_meminfo — Retrieves information about user cache memory usage
  - wincache_ucache_set — Adds a variable in user cache and overwrites a variable if it already exists in the cache
  - wincache_unlock — Releases an exclusive lock on a given key
- Building for Windows
  - Prerequisites
  - Compiling and building
  - Verifying the build

# Hierarchical Profiler

# Einführung

XHProf is a light-weight hierarchical and instrumentation based profiler. During the data collection phase, it keeps track of call counts and inclusive metrics for arcs in the dynamic callgraph of a program. It computes exclusive metrics in the reporting/post processing phase, such as wall (elapsed) time, CPU time and memory usage. A functions profile can be broken down by callers or callees. XHProf handles recursive functions by detecting cycles in the callgraph at data collection time itself and avoiding the cycles by giving unique depth qualified names for the recursive invocations.

XHProf includes a simple HTML based user interface (written in PHP). The browser based UI for viewing profiler results makes it easy to view results or to share results with peers. A callgraph image view is also supported.

XHProf reports can often be helpful in understanding the structure of the code being executed. The hierarchical nature of the reports can be used to determine, for example, what chain of calls led to a particular function getting called.

XHProf supports ability to compare two runs (a.k.a. "diff" reports) or aggregate data from multiple runs. Diff and aggregate reports, much like single run reports, offer "flat" as well as "hierarchical" views of the profile.

Additional documentation can be found via the » facebook xhprof website.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

Although not required, xhprof includes an interface that's written in PHP. It's used to save and display the profiled data in a usable way, where viewing is done via a web browser. So, a PHP enabled web server will likely make the xhprof experience more useful.

There's also a fork of the GUI interface at » http://github.com/preinheimer/xhprof

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/xhprof

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Xhprof Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
xhprof.output_dir | "" | `INI_ALL` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`xhprof.output_dir` string

  Directory used by the default implementation of the iXHProfRuns interface (namely, the XHProfRuns_Default class) for storing XHProf runs.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`XHPROF_FLAGS_NO_BUILTINS` (int)
  Used to skip all built-in (internal) functions.
`XHPROF_FLAGS_CPU` (int)
  Used to add CPU profiling information to the output.
`XHPROF_FLAGS_MEMORY` (int)
  Used to add memory profiling information to the output.

# Beispiele

Beispiel #1 Xhprof example with the optional GUI

This example starts and stops the profiler, then uses the bundled GUI interface to save and parse the results. In other words, the code from the extension itself ends at the call to xhprof_disable().

    <?php
    xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);

    for ($i = 0; $i <= 1000; $i++) {
        $a = $i * $i;
    }

    $xhprof_data = xhprof_disable();

    $XHPROF_ROOT = "/tools/xhprof/";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_lib.php";
    include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_runs.php";

    $xhprof_runs = new XHProfRuns_Default();
    $run_id = $xhprof_runs->save_run($xhprof_data, "xhprof_testing");

    echo "http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing

# Xhprof Funktionen

# xhprof_disable

(PECL xhprof >= 0.9.0)

xhprof_disable — Stops xhprof profiler

### Beschreibung

function xhprof_disable(): ?array

Stops the profiler, and returns xhprof data from the run.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array of xhprof data, from the run. Returns `null` if profiling is not enabled.

### Beispiele

Beispiel #1 xhprof_disable() example

    <?php
    xhprof_enable();

    $foo = strlen("foo bar");

    $xhprof_data = xhprof_disable();

    print_r($xhprof_data);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [main()==>strlen] => Array
            (
                [ct] => 1
                [wt] => 279
            )

        [main()==>xhprof_disable] => Array
            (
                [ct] => 1
                [wt] => 9
            )

        [main()] => Array
            (
                [ct] => 1
                [wt] => 610
            )

    )

# xhprof_enable

(PECL xhprof >= 0.9.0)

xhprof_enable — Start xhprof profiler

### Beschreibung

function xhprof_enable(int `$flags` = 0, array `$options` = ?): void

Start xhprof profiling.

### Parameter-Liste

`flags`

  Optional flags to add additional information to the profiling. See the XHprof constants for further information about these flags, e.g., `XHPROF_FLAGS_MEMORY` to enable memory profiling.

`options`

  An array of optional options, namely, the 'ignored_functions' option to pass in functions to be ignored during profiling.

### Rückgabewerte

`null`

### Changelog

Version | Beschreibung
--- | ---
PECL xhprof 0.9.2 | The optional `options` parameter was added.

### Beispiele

Beispiel #1 xhprof_enable() examples

    <?php
    // 1. elapsed time + memory + CPU profiling; and ignore built-in (internal) functions
    xhprof_enable(XHPROF_FLAGS_NO_BUILTINS | XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);

    // 2. elapsed time profiling; ignore call_user_func* during profiling
    xhprof_enable(
        0,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));

    // 3. elapsed time + memory profiling; ignore call_user_func* during profiling
    xhprof_enable(
        XHPROF_FLAGS_MEMORY,
        array('ignored_functions' =>  array('call_user_func',
                                            'call_user_func_array')));
    ?>

### Siehe auch

- xhprof_disable() - Stops xhprof profiler
- xhprof_sample_enable() - Start XHProf profiling in sampling mode
- memory_get_usage() - Returns the amount of memory allocated to PHP
- getrusage() - Liefert den aktuellen Wert der Ressourcenauslastung

# xhprof_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — Stops xhprof sample profiler

### Beschreibung

function xhprof_sample_disable(): ?array

Stops the sample mode xhprof profiler, and returns the profile info.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array of xhprof sample data, from the run. Returns `null` if profiling is not enabled.

### Beispiele

Beispiel #1 xhprof_sample_disable() example

    <?php
    xhprof_sample_enable();

    for ($i = 0; $i <= 10000; $i++) {
        $a = strlen($i);
        $b = $i * $a;
        $c = rand();
    }

    $xhprof_data = xhprof_sample_disable();

    print_r($xhprof_data);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [1272935300.800000] => main()
        [1272935300.900000] => main()
    )

# xhprof_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — Start XHProf profiling in sampling mode

### Beschreibung

function xhprof_sample_enable(): void

Starts profiling in sample mode, which is a lighter weight version of xhprof_enable(). The sampling interval is 0.1 seconds, and samples record the full function call stack. The main use case is when lower overhead is required when doing performance monitoring and diagnostics.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

`null`

### Siehe auch

- xhprof_sample_disable() - Stops xhprof sample profiler
- xhprof_enable() - Start xhprof profiler
- memory_get_usage() - Returns the amount of memory allocated to PHP
- getrusage() - Liefert den aktuellen Wert der Ressourcenauslastung

## Inhaltsverzeichnis

- xhprof_disable — Stops xhprof profiler
- xhprof_enable — Start xhprof profiler
- xhprof_sample_disable — Stops xhprof sample profiler
- xhprof_sample_enable — Start XHProf profiling in sampling mode

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Beispiele
- Xhprof Funktionen
  - xhprof_disable — Stops xhprof profiler
  - xhprof_enable — Start xhprof profiler
  - xhprof_sample_disable — Stops xhprof sample profiler
  - xhprof_sample_enable — Start XHProf profiling in sampling mode

# Yac

# Einführung

Yac (Yet Another cache), is a lock-free, shared memory user data cache, could be used to replace APC, local memcache.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/yac.

Windows-Binaries (DLL-Dateien) für diese PECL-Erweiterung sind auf der PECL-Website erhältlich.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Yac Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
yac.compress_threshold | -1 | `INI_SYSTEM` |
yac.debug | 0 | `INI_ALL` |
yac.enable | 1 | `INI_SYSTEM` |
yac.enable_cli | 0 | `INI_SYSTEM` |
yac.keys_memory_size | 4M | `INI_SYSTEM` |
yac.serializer | php | `INI_SYSTEM` |
yac.values_memory_size | 64M | `INI_SYSTEM` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`yac.compress_threshold` int

`yac.debug` int

`yac.enable` int

`yac.enable_cli` int

`yac.keys_memory_size` string

`yac.serializer` string

`yac.values_memory_size` string

## Ressource-Typen

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`YAC_VERSION` (string)
`YAC_MAX_KEY_LEN` (int)
  Max length of a key could be, it is 48 bytes.
`YAC_MAX_VALUE_RAW_LEN` (int)
`YAC_MAX_RAW_COMPRESSED_LEN` (int)
`YAC_SERIALIZER_PHP` (int)
  Use php serialize as serializer
`YAC_SERIALIZER_JSON` (int)
  Use json as serializer(requrie --enable-json)
`YAC_SERIALIZER_IGBINARY` (int)
  Use igbinary as serializer(require --enable-igbinary)
`YAC_SERIALIZER_MSGPACK` (int)
  Use msgpack as serializer(require --enable-msgpack)
`YAC_SERIALIZER` (string)
  Which serialzier is yac used

# The Yac class

(PECL yac >= 1.0.0)

## Einführung

## Klassenbeschreibung

class Yac {
/* Eigenschaften */
protected $_prefix;
/* Methoden */
public function __construct(string `$prefix` = "")
public function add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function delete(string|array `$keys`, int `$ttl` = ?): bool
public function dump(int `$$num`): mixed
public function flush(): bool
public function get(string|array `$key`, int `&$cas` = `null`): mixed
public function __get(string `$key`): mixed
public function info(): array
public function set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function __set(string `$keys`, mixed `$value`): mixed
}

## Eigenschaften

_prefix

# Yac::add

(PECL yac >= 1.0.0)

Yac::add — Store into cache

### Beschreibung

public function Yac::add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Added a item into cache.

### Parameter-Liste

`keys`

  String key

`value`

  mixed value, All php value type could be stored except Ressource

`ttl`

  expire time

### Rückgabewerte

Boolean, `true` on success, `false` on failure

> Hinweis:

> Yac::add() may fail if cas lock could not obtain, so, if you need the value to be stored properly, you may write codes like:

> Beispiel #1 Make sure the item is stored

>     while(!$yac->set("key", "value"));

# Yac::__construct

(PECL yac >= 1.0.0)

Yac::__construct — Constructor

### Beschreibung

public function Yac::__construct(string `$prefix` = "")

prefix is used to prepended to keys, this could be used to avoiding conflicts between apps.

### Parameter-Liste

`prefix`

  String prefix

### Fehler/Exceptions

Throws an Exception if Yac is not enabled. Throws Exception if `prefix` exceeds max key length of 48 (`YAC_MAX_KEY_LEN`) bytes.

# Yac::delete

(PECL yac >= 1.0.0)

Yac::delete — Remove items from cache

### Beschreibung

public function Yac::delete(string|array `$keys`, int `$ttl` = ?): bool

remove items from cache

### Parameter-Liste

`keys`

  string key, or array of multiple keys to be removed

`ttl`

  if delay is set, delete will mark the items to be invalid in ttl second.

### Rückgabewerte

# Yac::dump

(PECL yac >= 1.0.0)

Yac::dump — Dump cache

### Beschreibung

public function Yac::dump(int `$$num`): mixed

Dump values stored in cache

### Parameter-Liste

`num`

  Maximum number of items should be returned

### Rückgabewerte

mixed

# Yac::flush

(PECL yac >= 1.0.0)

Yac::flush — Flush the cache

### Beschreibung

public function Yac::flush(): bool

Remove all cached values

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

bool, always true

# Yac::get

(PECL yac >= 1.0.0)

Yac::get — Retrieve values from cache

### Beschreibung

public function Yac::get(string|array `$key`, int `&$cas` = `null`): mixed

Retrieve values from cache

### Parameter-Liste

`key`

  String keys, or Array of multiple keys.

`cas`

  if not `null`, it will be set to the retrieved item's cas.

### Rückgabewerte

mixed on success, false on failure

# Yac::__get

(PECL yac >= 1.0.0)

Yac::__get — Getter

### Beschreibung

public function Yac::__get(string `$key`): mixed

Retrieve values from cache

### Parameter-Liste

`key`

  String key

### Rückgabewerte

mixed on success, `null` on failure

# Yac::info

(PECL yac >= 1.0.0)

Yac::info — Status of cache

### Beschreibung

public function Yac::info(): array

Get status of cache system

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Return an array, consistent with: "memory_size", "slots_memory_size", "values_memory_size", "segment_size", "segment_num", "miss", "hits", "fails", "kicks", "recycles", "slots_size", "slots_used"

# Yac::set

(PECL yac >= 1.0.0)

Yac::set — Store into cache

### Beschreibung

public function Yac::set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function Yac::add(array `$key_vals`): bool

Add a item into cache, it the key is already exists, override it.

### Parameter-Liste

`keys`

  String key

`value`

  mixed value, All php value type could be stored except Ressource

`ttl`

  expire time

### Rückgabewerte

the value self

# Yac::__set

(PECL yac >= 1.0.0)

Yac::__set — Setter

### Beschreibung

public function Yac::__set(string `$keys`, mixed `$value`): mixed

store a item into cache

### Parameter-Liste

`keys`

  String key

`value`

  mixed value, All php value type could be stored except Ressource

### Rückgabewerte

Always return the value self

## Inhaltsverzeichnis

- Yac::add — Store into cache
- Yac::__construct — Constructor
- Yac::delete — Remove items from cache
- Yac::dump — Dump cache
- Yac::flush — Flush the cache
- Yac::get — Retrieve values from cache
- Yac::__get — Getter
- Yac::info — Status of cache
- Yac::set — Store into cache
- Yac::__set — Setter

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Yac — The Yac class
  - Yac::add — Store into cache
  - Yac::__construct — Constructor
  - Yac::delete — Remove items from cache
  - Yac::dump — Dump cache
  - Yac::flush — Flush the cache
  - Yac::get — Retrieve values from cache
  - Yac::__get — Getter
  - Yac::info — Status of cache
  - Yac::set — Store into cache
  - Yac::__set — Setter

- APCu — APC User Cache
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - APCu Funktionen
  - APCUIterator — The APCUIterator class
- Componere
  - Installation/Konfiguration
  - Componere\Abstract\Definition — The Componere\Abstract\Definition class
  - Componere\Definition — The Componere\Definition class
  - Componere\Patch — The Componere\Patch class
  - Componere\Method — The Componere\Method class
  - Componere\Value — The Componere\Value class
  - Componere Funktionen
- Fehlerbehandlung — Fehlerbehandlung und Protokollierung
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Fehlerbehandlungsfunktionen
- FFI — Foreign Function Interface
  - Installation/Konfiguration
  - Beispiele
  - FFI — Main interface to C code and data
  - FFI\CData — C Data Handles
  - FFI\CType — C Type Handles
  - FFI\Exception — FFI Exceptions
  - FFI\ParserException — FFI Parser Exceptions
- OPcache
  - Installation/Konfiguration
  - Preloading
  - OPcache Funktionen
- Operator Overloading — Operator Overloading for Objects
  - Installation/Konfiguration
  - Operator Overloading Magic Methods
- Ausgabekontrolle — Ausgabepufferung
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Output Buffering
  - Flushing System Buffers
  - User-Level Output Buffers
  - Beispiele
  - Output-Control-Funktionen
- PHP-Optionen/-Informationen — PHP-Optionen und -Informationen
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - PHP-Optionen-/-Informationen-Funktionen
- phpdbg — Interactive PHP Debugger
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - phpdbg Funktionen
- runkit7
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - runkit7 Funktionen
- uopz — User Operations for Zend
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Uopz Funktionen
- WinCache — Windows Cache for PHP
  - Installation/Konfiguration
  - WinCache Funktionen
  - Building for Windows
- Xhprof — Hierarchical Profiler
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Xhprof Funktionen
- Yac
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Yac — The Yac class

# Manipulation von Audioformaten

# OpenAL Audio Bindings

# Einführung

Platform independent audio bindings. Requires the » OpenAL library.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Ressource-Typen

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/openal.

Eine DLL-Datei für diese PECL-Erweiterung steht derzeit nicht zur Verfügung. Weitere Details finden Sie im Abschnitt zum Kompilieren für Windows.

## Ressource-Typen

This extension defines four resource types: Open AL(Device) - Returned by openal_device_open(), Open AL(Context) - Returned by openal_context_create(), Open AL(Buffer) - Returned by openal_buffer_create(), and Open AL(Source) - Returned by openal_source_create().

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`ALC_FREQUENCY` (int)
  Context Attribute
`ALC_REFRESH` (int)
  Context Attribute
`ALC_SYNC` (int)
  Context Attribute
`AL_FREQUENCY` (int)
  Buffer Setting
`AL_BITS` (int)
  Buffer Setting
`AL_CHANNELS` (int)
  Buffer Setting
`AL_SIZE` (int)
  Buffer Setting
`AL_BUFFER` (int)
  Source/Listener Setting (Integer)
`AL_SOURCE_RELATIVE` (int)
  Source/Listener Setting (Integer)
`AL_SOURCE_STATE` (int)
  Source/Listener Setting (Integer)
`AL_PITCH` (int)
  Source/Listener Setting (Float)
`AL_GAIN` (int)
  Source/Listener Setting (Float)
`AL_MIN_GAIN` (int)
  Source/Listener Setting (Float)
`AL_MAX_GAIN` (int)
  Source/Listener Setting (Float)
`AL_MAX_DISTANCE` (int)
  Source/Listener Setting (Float)
`AL_ROLLOFF_FACTOR` (int)
  Source/Listener Setting (Float)
`AL_CONE_OUTER_GAIN` (int)
  Source/Listener Setting (Float)
`AL_CONE_INNER_ANGLE` (int)
  Source/Listener Setting (Float)
`AL_CONE_OUTER_ANGLE` (int)
  Source/Listener Setting (Float)
`AL_REFERENCE_DISTANCE` (int)
  Source/Listener Setting (Float)
`AL_POSITION` (int)
  Source/Listener Setting (Float Vector)
`AL_VELOCITY` (int)
  Source/Listener Setting (Float Vector)
`AL_DIRECTION` (int)
  Source/Listener Setting (Float Vector)
`AL_ORIENTATION` (int)
  Source/Listener Setting (Float Vector)
`AL_FORMAT_MONO8` (int)
  PCM Format
`AL_FORMAT_MONO16` (int)
  PCM Format
`AL_FORMAT_STEREO8` (int)
  PCM Format
`AL_FORMAT_STEREO16` (int)
  PCM Format
`AL_INITIAL` (int)
  Source State
`AL_PLAYING` (int)
  Source State
`AL_PAUSED` (int)
  Source State
`AL_STOPPED` (int)
  Source State
`AL_LOOPING` (int)
  Source State
`AL_TRUE` (int)
  Boolean value recognized by OpenAL
`AL_FALSE` (int)
  Boolean value recognized by OpenAL

# OpenAL Funktionen

# openal_buffer_create

(PECL openal >= 0.1.0)

openal_buffer_create — Generate OpenAL buffer

### Beschreibung

function openal_buffer_create(): resource

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an Open AL(Buffer) resource on success or `false` on failure.

### Siehe auch

- openal_buffer_loadwav() - Load a .wav file into a buffer
- openal_buffer_data() - Load a buffer with data

# openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_data — Load a buffer with data

### Beschreibung

function openal_buffer_data(
resource `$buffer`,
int `$format`,
string `$data`,
int `$freq`
): bool

### Parameter-Liste

`buffer`
  An Open AL(Buffer) resource (previously created by openal_buffer_create()).
`format`
  Format of `data`, one of: `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` und `AL_FORMAT_STEREO16`
`data`
  Block of binary audio data in the `format` and `freq` specified.
`freq`
  Frequency of `data` given in Hz.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_buffer_loadwav() - Load a .wav file into a buffer
- openal_stream() - Begin streaming on a source

# openal_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroy — Destroys an OpenAL buffer

### Beschreibung

function openal_buffer_destroy(resource `$buffer`): bool

### Parameter-Liste

`buffer`
  An Open AL(Buffer) resource (previously created by openal_buffer_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_buffer_create() - Generate OpenAL buffer

# openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — Retrieve an OpenAL buffer property

### Beschreibung

function openal_buffer_get(resource `$buffer`, int `$property`): int|false

### Parameter-Liste

`buffer`
  An Open AL(Buffer) resource (previously created by openal_buffer_create()).
`property`
  Specific property, one of: `AL_FREQUENCY`, `AL_BITS`, `AL_CHANNELS` und `AL_SIZE`.

### Rückgabewerte

Returns an integer value appropriate to the `property` requestedBei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- openal_buffer_create() - Generate OpenAL buffer

# openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — Load a .wav file into a buffer

### Beschreibung

function openal_buffer_loadwav(resource `$buffer`, string `$wavfile`): bool

### Parameter-Liste

`buffer`
  An Open AL(Buffer) resource (previously created by openal_buffer_create()).
`wavfile`
  Path to .wav file on local file system.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_buffer_data() - Load a buffer with data
- openal_stream() - Begin streaming on a source

# openal_context_create

(PECL openal >= 0.1.0)

openal_context_create — Create an audio processing context

### Beschreibung

function openal_context_create(resource `$device`): resource

### Parameter-Liste

`device`
  An Open AL(Device) resource (previously created by openal_device_open()).

### Rückgabewerte

Returns an Open AL(Context) resource on success or `false` on failure.

### Siehe auch

- openal_device_open() - Initialize the OpenAL audio layer
- openal_context_destroy() - Destroys a context

# openal_context_current

(PECL openal >= 0.1.0)

openal_context_current — Make the specified context current

### Beschreibung

function openal_context_current(resource `$context`): bool

### Parameter-Liste

`context`
  An Open AL(Context) resource (previously created by openal_context_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_context_create() - Create an audio processing context

# openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — Destroys a context

### Beschreibung

function openal_context_destroy(resource `$context`): bool

### Parameter-Liste

`context`
  An Open AL(Context) resource (previously created by openal_context_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_context_create() - Create an audio processing context

# openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — Process the specified context

### Beschreibung

function openal_context_process(resource `$context`): bool

### Parameter-Liste

`context`
  An Open AL(Context) resource (previously created by openal_context_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_context_create() - Create an audio processing context
- openal_context_current() - Make the specified context current
- openal_context_suspend() - Suspend the specified context

# openal_context_suspend

(PECL openal >= 0.1.0)

openal_context_suspend — Suspend the specified context

### Beschreibung

function openal_context_suspend(resource `$context`): bool

### Parameter-Liste

`context`
  An Open AL(Context) resource (previously created by openal_context_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_context_create() - Create an audio processing context
- openal_context_current() - Make the specified context current
- openal_context_process() - Process the specified context

# openal_device_close

(PECL openal >= 0.1.0)

openal_device_close — Close an OpenAL device

### Beschreibung

function openal_device_close(resource `$device`): bool

### Parameter-Liste

`device`
  An Open AL(Device) resource (previously created by openal_device_open()) to be closed.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_device_open() - Initialize the OpenAL audio layer

# openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — Initialize the OpenAL audio layer

### Beschreibung

function openal_device_open(string `$device_desc` = ?): resource

### Parameter-Liste

`device_desc`
  Open an audio device optionally specified by `device_desc`. If `device_desc` is not specified the first available audio device will be used.

### Rückgabewerte

Returns an Open AL(Device) resource on success or `false` on failure.

### Siehe auch

- openal_device_close() - Close an OpenAL device
- openal_context_create() - Create an audio processing context

# openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_get — Retrieve a listener property

### Beschreibung

function openal_listener_get(int `$property`): mixed

### Parameter-Liste

`property`
  Property to retrieve, one of: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) und `AL_ORIENTATION` (array(float,float,float)).

### Rückgabewerte

Returns a float or array of floats (as appropriate)Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- openal_listener_set() - Set a listener property

# openal_listener_set

(PECL openal >= 0.1.0)

openal_listener_set — Set a listener property

### Beschreibung

function openal_listener_set(int `$property`, mixed `$setting`): bool

### Parameter-Liste

`property`
  Property to set, one of: `AL_GAIN` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)) und `AL_ORIENTATION` (array(float,float,float)).
`setting`
  Value to set, either float, or an array of floats as appropriate.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_listener_get() - Retrieve a listener property

# openal_source_create

(PECL openal >= 0.1.0)

openal_source_create — Generate a source resource

### Beschreibung

function openal_source_create(): resource

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an Open AL(Source) resource on success or `false` on failure.

### Siehe auch

- openal_source_set() - Set source property
- openal_source_play() - Start playing the source
- openal_source_destroy() - Destroy a source resource

# openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroy — Destroy a source resource

### Beschreibung

function openal_source_destroy(resource `$source`): bool

### Parameter-Liste

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_source_create() - Generate a source resource

# openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — Retrieve an OpenAL source property

### Beschreibung

function openal_source_get(resource `$source`, int `$property`): mixed

### Parameter-Liste

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).
`property`
  Property to get, one of: `AL_SOURCE_RELATIVE` (int), `AL_SOURCE_STATE` (int), `AL_PITCH` (float), `AL_GAIN` (float), `AL_MIN_GAIN` (float), `AL_MAX_GAIN` (float), `AL_MAX_DISTANCE` (float), `AL_ROLLOFF_FACTOR` (float), `AL_CONE_OUTER_GAIN` (float), `AL_CONE_INNER_ANGLE` (float), `AL_CONE_OUTER_ANGLE` (float), `AL_REFERENCE_DISTANCE` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).

### Rückgabewerte

Returns the type associated with the property being retrieved Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- openal_source_create() - Generate a source resource
- openal_source_set() - Set source property
- openal_source_play() - Start playing the source

# openal_source_pause

(PECL openal >= 0.1.0)

openal_source_pause — Pause the source

### Beschreibung

function openal_source_pause(resource `$source`): bool

### Parameter-Liste

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_source_stop() - Stop playing the source
- openal_source_play() - Start playing the source
- openal_source_rewind() - Rewind the source

# openal_source_play

(PECL openal >= 0.1.0)

openal_source_play — Start playing the source

### Beschreibung

function openal_source_play(resource `$source`): bool

### Parameter-Liste

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_source_stop() - Stop playing the source
- openal_source_pause() - Pause the source
- openal_source_rewind() - Rewind the source

# openal_source_rewind

(PECL openal >= 0.1.0)

openal_source_rewind — Rewind the source

### Beschreibung

function openal_source_rewind(resource `$source`): bool

### Parameter-Liste

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_source_stop() - Stop playing the source
- openal_source_pause() - Pause the source
- openal_source_play() - Start playing the source

# openal_source_set

(PECL openal >= 0.1.0)

openal_source_set — Set source property

### Beschreibung

function openal_source_set(resource `$source`, int `$property`, mixed `$setting`): bool

### Parameter-Liste

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).
`property`
  Property to set, one of: `AL_BUFFER` (OpenAL(Source)), `AL_LOOPING` (bool), `AL_SOURCE_RELATIVE` (int), `AL_SOURCE_STATE` (int), `AL_PITCH` (float), `AL_GAIN` (float), `AL_MIN_GAIN` (float), `AL_MAX_GAIN` (float), `AL_MAX_DISTANCE` (float), `AL_ROLLOFF_FACTOR` (float), `AL_CONE_OUTER_GAIN` (float), `AL_CONE_INNER_ANGLE` (float), `AL_CONE_OUTER_ANGLE` (float), `AL_REFERENCE_DISTANCE` (float), `AL_POSITION` (array(float,float,float)), `AL_VELOCITY` (array(float,float,float)), `AL_DIRECTION` (array(float,float,float)).
`setting`
  Value to assign to specified `property`. Refer to the description of `property` for a description of the value(s) expected.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_source_create() - Generate a source resource
- openal_source_get() - Retrieve an OpenAL source property
- openal_source_play() - Start playing the source

# openal_source_stop

(PECL openal >= 0.1.0)

openal_source_stop — Stop playing the source

### Beschreibung

function openal_source_stop(resource `$source`): bool

### Parameter-Liste

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- openal_source_play() - Start playing the source
- openal_source_pause() - Pause the source
- openal_source_rewind() - Rewind the source

# openal_stream

(PECL openal >= 0.1.0)

openal_stream — Begin streaming on a source

### Beschreibung

function openal_stream(resource `$source`, int `$format`, int `$rate`): resource|false

### Parameter-Liste

`source`
  An Open AL(Source) resource (previously created by openal_source_create()).
`format`
  Format of `data`, one of: `AL_FORMAT_MONO8`, `AL_FORMAT_MONO16`, `AL_FORMAT_STEREO8` und `AL_FORMAT_STEREO16`
`rate`
  Frequency of data to stream given in Hz.

### Rückgabewerte

Returns a stream resource on successBei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- openal_source_create() - Generate a source resource
- fwrite() - Binär-sicheres Dateischreiben

## Inhaltsverzeichnis

- openal_buffer_create — Generate OpenAL buffer
- openal_buffer_data — Load a buffer with data
- openal_buffer_destroy — Destroys an OpenAL buffer
- openal_buffer_get — Retrieve an OpenAL buffer property
- openal_buffer_loadwav — Load a .wav file into a buffer
- openal_context_create — Create an audio processing context
- openal_context_current — Make the specified context current
- openal_context_destroy — Destroys a context
- openal_context_process — Process the specified context
- openal_context_suspend — Suspend the specified context
- openal_device_close — Close an OpenAL device
- openal_device_open — Initialize the OpenAL audio layer
- openal_listener_get — Retrieve a listener property
- openal_listener_set — Set a listener property
- openal_source_create — Generate a source resource
- openal_source_destroy — Destroy a source resource
- openal_source_get — Retrieve an OpenAL source property
- openal_source_pause — Pause the source
- openal_source_play — Start playing the source
- openal_source_rewind — Rewind the source
- openal_source_set — Set source property
- openal_source_stop — Stop playing the source
- openal_stream — Begin streaming on a source

- Installation/Konfiguration
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- OpenAL Funktionen
  - openal_buffer_create — Generate OpenAL buffer
  - openal_buffer_data — Load a buffer with data
  - openal_buffer_destroy — Destroys an OpenAL buffer
  - openal_buffer_get — Retrieve an OpenAL buffer property
  - openal_buffer_loadwav — Load a .wav file into a buffer
  - openal_context_create — Create an audio processing context
  - openal_context_current — Make the specified context current
  - openal_context_destroy — Destroys a context
  - openal_context_process — Process the specified context
  - openal_context_suspend — Suspend the specified context
  - openal_device_close — Close an OpenAL device
  - openal_device_open — Initialize the OpenAL audio layer
  - openal_listener_get — Retrieve a listener property
  - openal_listener_set — Set a listener property
  - openal_source_create — Generate a source resource
  - openal_source_destroy — Destroy a source resource
  - openal_source_get — Retrieve an OpenAL source property
  - openal_source_pause — Pause the source
  - openal_source_play — Start playing the source
  - openal_source_rewind — Rewind the source
  - openal_source_set — Set source property
  - openal_source_stop — Stop playing the source
  - openal_stream — Begin streaming on a source

- OpenAL — OpenAL Audio Bindings
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - OpenAL Funktionen

# Authentifizierungsdienste

# Radius

# Einführung

This package is based on the libradius (Remote Authentication Dial In User Service) of FreeBSD. It allows clients to perform authentication and accounting by means of network requests to remote servers.

This PECL extension adds full support for Radius Authentication (» RFC 2865) and Radius Accounting (» RFC 2866). This package is available for Unix (tested on FreeBSD and Linux) and for Windows.

> Hinweis: An exact description for libradius can be found » here. A detailed description of the configuration file can be found » here.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/radius.

# Vordefinierte Konstanten

## Inhaltsverzeichnis

- RADIUS Options
- RADIUS Packet Types
- RADIUS Attribute Types
- RADIUS Vendor Specific Attribute Types

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`RADIUS_MPPE_KEY_LEN` (int)
  The maximum length of MPPE keys.

## RADIUS Options

Several RADIUS functions accept option flags as bitmasks. The constants representing those flags are listed below.

`RADIUS_OPTION_SALT` (int)
  When set, this option will result in the attribute value being salt-encrypted.
`RADIUS_OPTION_TAGGED` (int)
  When set, this option will result in the attribute value being tagged with the value of the tag parameter.

## RADIUS Packet Types

RADIUS packets, whether requests or responses, always include a type. These constants are provided to make it easier to specify types when using radius_create_request() and when comparing the result of radius_send_request().

`RADIUS_ACCESS_REQUEST` (int)
  An Access-Request, used to authenticate a user against a RADIUS server. Access request packets must include a `RADIUS_NAS_IP_ADDRESS` or a `RADIUS_NAS_IDENTIFIER` attribute, must also include a `RADIUS_USER_PASSWORD`, `RADIUS_CHAP_PASSWORD` or a `RADIUS_STATE` attribute, and should include a `RADIUS_USER_NAME` attribute.
`RADIUS_ACCESS_ACCEPT` (int)
  An Access-Accept response to an Access-Request indicating that the RADIUS server authenticated the user successfully.
`RADIUS_ACCESS_REJECT` (int)
  An Access-Reject response to an Access-Request indicating that the RADIUS server could not authenticate the user.
`RADIUS_ACCESS_CHALLENGE` (int)
  An Access-Challenge response to an Access-Request indicating that the RADIUS server requires further information in another Access-Request before authenticating the user.
`RADIUS_ACCOUNTING_REQUEST` (int)
  An Accounting-Request, used to convey accounting information for a service to the RADIUS server.
`RADIUS_ACCOUNTING_RESPONSE` (int)
  An Accounting-Response response to an Accounting-Request.
`RADIUS_COA_REQUEST` (int)
  A CoA-Request, sent from the RADIUS server to indicate that the authorisations within the user session have changed. A response must be sent in the form of a CoA-ACK or a CoA-NAK. This constant is available in PECL radius 1.3.0 and later.
`RADIUS_COA_ACK` (int)
  A CoA-ACK, sent to the RADIUS server to indicate that the user authorisations have been updated. This constant is available in PECL radius 1.3.0 and later.
`RADIUS_COA_NAK` (int)
  A CoA-NAK, sent to the RADIUS server to indicate that the user authorisations could not be updated. This constant is available in PECL radius 1.3.0 and later.
`RADIUS_DISCONNECT_REQUEST` (int)
  A Disconnect-Request, sent from the RADIUS server to indicate that the user session must be terminated. This constant is available in PECL radius 1.3.0 and later.
`RADIUS_DISCONNECT_ACK` (int)
  A Disconnect-ACK, sent to the RADIUS server to indicate that the user session has been terminated. This constant is available in PECL radius 1.3.0 and later.
`RADIUS_DISCONNECT_NAK` (int)
  A Disconnect-NAK, sent to the RADIUS server to indicate that the user session could not be terminated. This constant is available in PECL radius 1.3.0 and later.

## RADIUS Attribute Types

These constants define RADIUS attribute types that can be used with radius_put_addr(), radius_put_attr(), radius_put_int() and radius_put_string().

`RADIUS_USER_NAME` (int)
  The User-Name attribute. The attribute value is expected to be a string containing the name of the user being authenticated, and can be set using radius_put_attr().
`RADIUS_USER_PASSWORD` (int)
  The User-Password attribute. The attribute value is expected to be a string containing the user's password, and can be set using radius_put_attr(). This value will be obfuscated on transmission as described in » section 5.2 of RFC 2865.
`RADIUS_CHAP_PASSWORD` (int)
  The Chap-Password attribute. The attribute value is expected to be a string with the first byte containing the CHAP identifier, and the subsequent 16 bytes containing the MD5 hash of the CHAP identifier, the plaintext password and the CHAP challenge value concatenated together. Note that the CHAP challenge value should also be sent separately in a `RADIUS_CHAP_CHALLENGE` attribute.

  Beispiel #1 Using CHAP passwords

      <?php
      // Firstly, we'll create an authentication handle and request.
      $radh = radius_auth_open();
      radius_add_server($radh, $server, $port, $secret, 3, 3);
      radius_create_request($radh, RADIUS_ACCESS_REQUEST);

      // Assuming $password contains the plaintext password, we now:

      // Generate a challenge.
      $challenge = mt_rand();

      // Specify a CHAP identifier.
      $ident = 1;

      // Add the Chap-Password attribute.
      $cp = hash('md5', pack('Ca*', $ident, $password.$challenge), true);
      radius_put_attr($radh, RADIUS_CHAP_PASSWORD, pack('C', $ident).$cp);

      // Add the Chap-Challenge attribute.
      radius_put_attr($radh, RADIUS_CHAP_CHALLENGE, $challenge);

      /* From here, you would add the remaining attributes and
       * call radius_send_request(). */
      ?>

`RADIUS_NAS_IP_ADDRESS` (int)
  The NAS-IP-Address attribute. The attribute value is expected to the IP address of the RADIUS client encoded as an int, which can be set using radius_put_addr().
`RADIUS_NAS_PORT` (int)
  The NAS-Port attribute. The attribute value is expected to be the physical port of the user on the RADIUS client encoded as an int, which can be set using radius_put_int().
`RADIUS_SERVICE_TYPE` (int)
  The Service-Type attribute. The attribute value indicates the service type the user is requesting, and is expected to be an int, which can be set using radius_put_int().

  A number of constants are provided to represent the possible values of this attribute. They include:

  - `RADIUS_LOGIN`
  - `RADIUS_FRAMED`
  - `RADIUS_CALLBACK_LOGIN`
  - `RADIUS_CALLBACK_FRAMED`
  - `RADIUS_OUTBOUND`
  - `RADIUS_ADMINISTRATIVE`
  - `RADIUS_NAS_PROMPT`
  - `RADIUS_AUTHENTICATE_ONLY`
  - `RADIUS_CALLBACK_NAS_PROMPT`
`RADIUS_FRAMED_PROTOCOL` (int)

  The Framed-Protocol attribute. The attribute value is expected to be an int indicating the framing to be used for framed access, and can be set using radius_put_int(). The possible attribute values include these constants:

  - `RADIUS_PPP`
  - `RADIUS_SLIP`
  - `RADIUS_ARAP`
  - `RADIUS_GANDALF`
  - `RADIUS_XYLOGICS`
`RADIUS_FRAMED_IP_ADDRESS` (int)
  The Framed-IP-Address attribute. The attribute value is expected to be the address of the user's network encoded as an int, which can be set using radius_put_addr() and retrieved using radius_cvt_addr().
`RADIUS_FRAMED_IP_NETMASK` (int)
  The Framed-IP-Netmask attribute. The attribute value is expected to be the netmask of the user's network encoded as an int, which can be set using radius_put_addr() and retrieved using radius_cvt_addr().
`RADIUS_FRAMED_ROUTING` (int)
  The Framed-Routing attribute. The attribute value is expected to be an int indicating the routing method for the user, which can be set using radius_put_int().

  Possible values include:

  - `0`: No routing
  - `1`: Send routing packets
  - `2`: Listen for routing packets
  - `3`: Send and listen
`RADIUS_FILTER_ID` (int)
  The Filter-ID attribute. The attribute value is expected to be an implementation-specific, human-readable string of filters, which can be set using radius_put_attr().
`RADIUS_FRAMED_MTU` (int)
  The Framed-MTU attribute. The attribute value is expected to be an int indicating the MTU to be configured for the user, and can be set using radius_put_int().
`RADIUS_FRAMED_COMPRESSION` (int)

  The Framed-Compression attribute. The attribute value is expected to be an int indicating the compression protocol to be used, and can be set using radius_put_int(). Possible values include these constants:

  - `RADIUS_COMP_NONE`: No compression
  - `RADIUS_COMP_VJ`: VJ TCP/IP header compression
  - `RADIUS_COMP_IPXHDR`: IPX header compression
  - `RADIUS_COMP_STAC_LZS`: Stac-LZS compression (added in PECL radius 1.3.0b2)
`RADIUS_LOGIN_IP_HOST` (int)
  The Login-IP-Host attribute. The attribute value is expected to the IP address to connect the user to, encoded as an int, which can be set using radius_put_addr().
`RADIUS_LOGIN_SERVICE` (int)
  The Login-Service attribute. The attribute value is an int indicating the service to connect the user to on the login host. The value can be converted to a PHP integer via radius_cvt_int().
`RADIUS_LOGIN_TCP_PORT` (int)
  The Login-TCP-Port attribute. The attribute value is an int indicating the port to connect the user to on the login host. The value can be converted to a PHP integer via radius_cvt_int().
`RADIUS_REPLY_MESSAGE` (int)
  The Reply-Message attribute. The attribute value is a string containing text that may be displayed to the user in response to an access request.
`RADIUS_CALLBACK_NUMBER` (int)
  The Callback-Number attribute. The attribute value is a string containing the dialing string to use for callback.
`RADIUS_CALLBACK_ID` (int)
  The Callback-Id attribute. The attribute value is a string containing an implementation-specific name of the place to be called.
`RADIUS_FRAMED_ROUTE` (int)
  The Framed-Route attribute. The attribute value is a string containing an implementation-specific set of routes to be configured for the user.
`RADIUS_FRAMED_IPX_NETWORK` (int)
  The Framed-IPX-Network attribute. The attribute value is an int containing the IPX network to be configured for the user, or `0xFFFFFFFE` to indicate that the RADIUS client should select the network, and can be accessed via radius_cvt_int().
`RADIUS_STATE` (int)
  The State attribute. The attribute value is an implementation-defined string included in an Access-Challenge from a server that must be included in the subsequent Access-Request, and can be set using radius_put_attr().
`RADIUS_CLASS` (int)
  The Class attribute. The attribute value is an arbitrary string included in an Access-Accept message that should then be sent to the accounting server in Accounting-Request messages, and can be set using radius_put_attr().
`RADIUS_VENDOR_SPECIFIC` (int)
  The Vendor-Specific attribute. In general, vendor attribute values should be set using radius_put_vendor_addr(), radius_put_vendor_attr(), radius_put_vendor_int() and radius_put_vendor_string(), rather than directly. This constant is mostly useful when interpreting vendor specific attributes in responses from a RADIUS server; when a vendor specific attribute is received, the radius_get_vendor_attr() function should be used to access the vendor ID, attribute type and attribute value.
`RADIUS_SESSION_TIMEOUT` (int)
  Session timeout
`RADIUS_IDLE_TIMEOUT` (int)
  Idle timeout
`RADIUS_TERMINATION_ACTION` (int)
  Termination action
`RADIUS_CALLED_STATION_ID` (int)
  Called Station Id
`RADIUS_CALLING_STATION_ID` (int)
  Calling Station Id
`RADIUS_NAS_IDENTIFIER` (int)
  NAS ID
`RADIUS_PROXY_STATE` (int)
  Proxy State
`RADIUS_LOGIN_LAT_SERVICE` (int)
  Login LAT Service
`RADIUS_LOGIN_LAT_NODE` (int)
  Login LAT Node
`RADIUS_LOGIN_LAT_GROUP` (int)
  Login LAT Group
`RADIUS_FRAMED_APPLETALK_LINK` (int)
  Framed Appletalk Link
`RADIUS_FRAMED_APPLETALK_NETWORK` (int)
  Framed Appletalk Network
`RADIUS_FRAMED_APPLETALK_ZONE` (int)
  Framed Appletalk Zone
`RADIUS_CHAP_CHALLENGE` (int)
  Challenge
`RADIUS_NAS_PORT_TYPE` (int)

  NAS port type, one of:

  - `RADIUS_ASYNC`
  - `RADIUS_SYNC`
  - `RADIUS_ISDN_SYNC`
  - `RADIUS_ISDN_ASYNC_V120`
  - `RADIUS_ISDN_ASYNC_V110`
  - `RADIUS_VIRTUAL`
  - `RADIUS_PIAFS`
  - `RADIUS_HDLC_CLEAR_CHANNEL`
  - `RADIUS_X_25`
  - `RADIUS_X_75`
  - `RADIUS_G_3_FAX`
  - `RADIUS_SDSL`
  - `RADIUS_ADSL_CAP`
  - `RADIUS_ADSL_DMT`
  - `RADIUS_IDSL`
  - `RADIUS_ETHERNET`
  - `RADIUS_XDSL`
  - `RADIUS_CABLE`
  - `RADIUS_WIRELESS_OTHER`
  - `RADIUS_WIRELESS_IEEE_802_11`
`RADIUS_PORT_LIMIT` (int)
  Port Limit
`RADIUS_LOGIN_LAT_PORT` (int)
  Login LAT Port
`RADIUS_CONNECT_INFO` (int)
  Connect info
`RADIUS_ACCT_STATUS_TYPE` (int)

  Accounting status type, one of:

  - `RADIUS_START`
  - `RADIUS_STOP`
  - `RADIUS_ACCOUNTING_ON`
  - `RADIUS_ACCOUNTING_OFF`
`RADIUS_ACCT_DELAY_TIME` (int)
  Accounting delay time
`RADIUS_ACCT_INPUT_OCTETS` (int)
  Accounting input bytes
`RADIUS_ACCT_OUTPUT_OCTETS` (int)
  Accounting output bytes
`RADIUS_ACCT_SESSION_ID` (int)
  Accounting session ID
`RADIUS_ACCT_AUTHENTIC` (int)

  Accounting authentic, one of:

  - `RADIUS_AUTH_RADIUS`
  - `RADIUS_AUTH_LOCAL`
  - `RADIUS_AUTH_REMOTE`
`RADIUS_ACCT_SESSION_TIME` (int)
  Accounting session time
`RADIUS_ACCT_INPUT_PACKETS` (int)
  Accounting input packets
`RADIUS_ACCT_OUTPUT_PACKETS` (int)
  Accounting output packets
`RADIUS_ACCT_TERMINATE_CAUSE` (int)

  Accounting terminate cause, one of:

  - `RADIUS_TERM_USER_REQUEST`
  - `RADIUS_TERM_LOST_CARRIER`
  - `RADIUS_TERM_LOST_SERVICE`
  - `RADIUS_TERM_IDLE_TIMEOUT`
  - `RADIUS_TERM_SESSION_TIMEOUT`
  - `RADIUS_TERM_ADMIN_RESET`
  - `RADIUS_TERM_ADMIN_REBOOT`
  - `RADIUS_TERM_PORT_ERROR`
  - `RADIUS_TERM_NAS_ERROR`
  - `RADIUS_TERM_NAS_REQUEST`
  - `RADIUS_TERM_NAS_REBOOT`
  - `RADIUS_TERM_PORT_UNNEEDED`
  - `RADIUS_TERM_PORT_PREEMPTED`
  - `RADIUS_TERM_PORT_SUSPENDED`
  - `RADIUS_TERM_SERVICE_UNAVAILABLE`
  - `RADIUS_TERM_CALLBACK`
  - `RADIUS_TERM_USER_ERROR`
  - `RADIUS_TERM_HOST_REQUEST`
`RADIUS_ACCT_MULTI_SESSION_ID` (int)
  Accounting multi session ID
`RADIUS_ACCT_LINK_COUNT` (int)
  Accounting link count

Service-Type Constants
`RADIUS_LOGIN`
`RADIUS_FRAMED`
`RADIUS_CALLBACK_LOGIN`
`RADIUS_CALLBACK_FRAMED`
`RADIUS_OUTBOUND`
`RADIUS_ADMINISTRATIVE`
`RADIUS_NAS_PROMPT`
`RADIUS_AUTHENTICATE_ONLY`
`RADIUS_CALLBACK_NAS_PROMPT`

Framed-Protocol Constants
`RADIUS_PPP`
`RADIUS_SLIP`
`RADIUS_ARAP`
`RADIUS_GANDALF`
`RADIUS_XYLOGICS`

Framed-Compression Constants
`RADIUS_COMP_NONE`
`RADIUS_COMP_VJ`
`RADIUS_COMP_IPXHDR`
`RADIUS_COMP_STAC_LZS`

NAS Port Type Constants
`RADIUS_ASYNC`
`RADIUS_SYNC`
`RADIUS_ISDN_SYNC`
`RADIUS_ISDN_ASYNC_V120`
`RADIUS_ISDN_ASYNC_V110`
`RADIUS_VIRTUAL`
`RADIUS_PIAFS`
`RADIUS_HDLC_CLEAR_CHANNEL`
`RADIUS_X_25`
`RADIUS_X_75`
`RADIUS_G_3_FAX`
`RADIUS_SDSL`
`RADIUS_ADSL_CAP`
`RADIUS_ADSL_DMT`
`RADIUS_IDSL`
`RADIUS_ETHERNET`
`RADIUS_XDSL`
`RADIUS_CABLE`
`RADIUS_WIRELESS_OTHER`
`RADIUS_WIRELESS_IEEE_802_11`

Accounting Status Type Constants
`RADIUS_START`
`RADIUS_STOP`
`RADIUS_ACCOUNTING_ON`
`RADIUS_ACCOUNTING_OFF`

Accounting Authentic Constants
`RADIUS_AUTH_RADIUS`
`RADIUS_AUTH_LOCAL`
`RADIUS_AUTH_REMOTE`

Accounting Terminate Cause Constants
`RADIUS_TERM_USER_REQUEST`
`RADIUS_TERM_LOST_CARRIER`
`RADIUS_TERM_LOST_SERVICE`
`RADIUS_TERM_IDLE_TIMEOUT`
`RADIUS_TERM_SESSION_TIMEOUT`
`RADIUS_TERM_ADMIN_RESET`
`RADIUS_TERM_ADMIN_REBOOT`
`RADIUS_TERM_PORT_ERROR`
`RADIUS_TERM_NAS_ERROR`
`RADIUS_TERM_NAS_REQUEST`
`RADIUS_TERM_NAS_REBOOT`
`RADIUS_TERM_PORT_UNNEEDED`
`RADIUS_TERM_PORT_PREEMPTED`
`RADIUS_TERM_PORT_SUSPENDED`
`RADIUS_TERM_SERVICE_UNAVAILABLE`
`RADIUS_TERM_CALLBACK`
`RADIUS_TERM_USER_ERROR`
`RADIUS_TERM_HOST_REQUEST`

## RADIUS Vendor Specific Attribute Types

`RADIUS_VENDOR_MICROSOFT` (int)

  Microsoft specific vendor attributes (» RFC 2548), one of:

  - `RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP_ERROR`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_1`
  - `RADIUS_MICROSOFT_MS_CHAP_PW_2`
  - `RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
  - `RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
  - `RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
  - `RADIUS_MICROSOFT_MS_RAS_VENDOR`
  - `RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
  - `RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
  - `RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
  - `RADIUS_MICROSOFT_MS_BAP_USAGE`
  - `RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
  - `RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
  - `RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
  - `RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
  - `RADIUS_MICROSOFT_MS_RAS_VERSION`
  - `RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
  - `RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
  - `RADIUS_MICROSOFT_MS_FILTER`
  - `RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
  - `RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
  - `RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
  - `RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
  - `RADIUS_MICROSOFT_MS_CHAP2_PW`
  - `RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
  - `RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
  - `RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`
`RADIUS_MICROSOFT_MS_CHAP_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP_ERROR`
`RADIUS_MICROSOFT_MS_CHAP_PW_1`
`RADIUS_MICROSOFT_MS_CHAP_PW_2`
`RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW`
`RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY`
`RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES`
`RADIUS_MICROSOFT_MS_RAS_VENDOR`
`RADIUS_MICROSOFT_MS_CHAP_DOMAIN`
`RADIUS_MICROSOFT_MS_CHAP_CHALLENGE`
`RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS`
`RADIUS_MICROSOFT_MS_BAP_USAGE`
`RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD`
`RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT`
`RADIUS_MICROSOFT_MS_MPPE_SEND_KEY`
`RADIUS_MICROSOFT_MS_MPPE_RECV_KEY`
`RADIUS_MICROSOFT_MS_RAS_VERSION`
`RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD`
`RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON`
`RADIUS_MICROSOFT_MS_FILTER`
`RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE`
`RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE`
`RADIUS_MICROSOFT_MS_CHAP2_RESPONSE`
`RADIUS_MICROSOFT_MS_CHAP2_SUCCESS`
`RADIUS_MICROSOFT_MS_CHAP2_PW`
`RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER`
`RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER`
`RADIUS_MICROSOFT_MS_ARAP_CHALLENGE`

# Beispiele

Howto start?

- get a radius resource
- configure the library
- create the request
- put attributes
- send the request
- receive attributes
- close the radius resource (optional)

Take also a look at the examples in this package.

The package contains an example php script. This script demonstrates howto authenticate with radius using PAP or CHAP (md5). If you authenticate with Microsoft Radius servers then its not possible to use CHAP (md5). If you would like to authenticate with Microsoft Servers you have to use MS-CHAPv1 or MS-CHAPv2, but its more complicated, because you need md4, sha1 and des to generate the right data. The enclosed examples demonstrate all authentication-methods, including MS-CHAPv1 and MS-CHAPv2. To get the MS-CHAP to work you need the mcrypt and the mhash extension, starting with version 1.2 of the package, the mcrypt extension is no longer needed.

# Radius Funktionen

# radius_acct_open

(PECL radius >= 1.1.0)

radius_acct_open — Creates a Radius handle for accounting

### Beschreibung

function radius_acct_open(): resource

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a handle on success, `false` on error. This function only fails if insufficient memory is available.

### Beispiele

Beispiel #1 radius_acct_open() example

    <?php
    $res = radius_acct_open ()
        or die ("Could not create handle");
    print "Handle successfully created";
    ?>

# radius_add_server

(PECL radius >= 1.1.0)

radius_add_server — Adds a server

### Beschreibung

function radius_add_server(
resource `$radius_handle`,
string `$hostname`,
int `$port`,
string `$secret`,
int `$timeout`,
int `$max_tries`
): bool

radius_add_server() may be called multiple times, and it may be used together with radius_config(). At most 10 servers may be specified. When multiple servers are given, they are tried in round-robin fashion until a valid response is received, or until each server's `max_tries` limit has been reached.

### Parameter-Liste

`radius_handle`
`hostname`
  The `hostname` parameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form.
`port`

  The `port` specifies the UDP port to contact on the server. If port is given as 0, the library looks up the `radius/udp` or `radacct/udp` service in the network services database, and uses the port found there. If no entry is found, the library uses the standard Radius ports, 1812 for authentication and 1813 for accounting.

`secret`
  The shared secret for the server host is passed to the `secret` parameter. The Radius protocol ignores all but the leading 128 bytes of the shared secret.
`timeout`
  The timeout for receiving replies from the server is passed to the `timeout` parameter, in units of seconds.
`max_tries`
  The maximum number of repeated requests to make before giving up is passed into the `max_tries`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 radius_add_server() example

    <?php
    if (!radius_add_server($res, 'radius.example.com', 1812, 'testing123', 3, 3)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br>";
        exit;
    }
    ?>

### Siehe auch

- radius_config() - Causes the library to read the given configuration file

# radius_auth_open

(PECL radius >= 1.1.0)

radius_auth_open — Creates a Radius handle for authentication

### Beschreibung

function radius_auth_open(): resource

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a handle on success, `false` on error. This function only fails if insufficient memory is available.

### Beispiele

Beispiel #1 radius_auth_open() example

    <?php
    $radh = radius_auth_open()
        or die ("Could not create handle");
    echo "Handle successfully created";
    ?>

# radius_close

(PECL radius >= 1.1.0)

radius_close — Gibt alle Ressourcen frei

### Beschreibung

function radius_close(resource `$radius_handle`): bool

Es ist nicht notwendig, diese Funktion aufzurufen, da PHP alle Ressourcen am Ende jeder Anfrage freigibt.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# radius_config

(PECL radius >= 1.1.0)

radius_config — Causes the library to read the given configuration file

### Beschreibung

function radius_config(resource `$radius_handle`, string `$file`): bool

Before issuing any Radius requests, the library must be made aware of the servers it can contact. The easiest way to configure the library is to call radius_config(). radius_config() causes the library to read a configuration file whose format is described in » radius.conf.

### Parameter-Liste

`radius_handle`
`file`
  The pathname of the configuration file is passed as the file argument to radius_config(). The library can also be configured programmatically by calls to radius_add_server().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- radius_add_server() - Adds a server

# radius_create_request

(PECL radius >= 1.1.0)

radius_create_request — Create accounting or authentication request

### Beschreibung

function radius_create_request(resource `$radius_handle`, int `$type`): bool

A Radius request consists of a code specifying the kind of request, and zero or more attributes which provide additional information. To begin constructing a new request, call radius_create_request().

> Hinweis: Attention: You must call this function, before you can put any attribute!

### Parameter-Liste

`radius_handle`
`type`
  Type is `RADIUS_ACCESS_REQUEST` or `RADIUS_ACCOUNTING_REQUEST`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 radius_create_request() example

    <?php
    if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Siehe auch

- radius_send_request() - Sends the request and waits for a reply

# radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addr — Converts raw data to IP-Address

### Beschreibung

function radius_cvt_addr(string `$data`): string

Converts raw data to IP-Address

### Parameter-Liste

`data`
  Input data

### Rückgabewerte

Returns the IP-Address.

### Beispiele

Beispiel #1 radius_cvt_addr() example

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Error getting attribute: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_IP_ADDRESS:
            $ip = radius_cvt_addr($data);
            echo "IP: $ip<br>\n";
            break;

        case RADIUS_FRAMED_IP_NETMASK:
            $mask = radius_cvt_addr($data);
            echo "MASK: $mask<br>\n";
            break;
        }
    }
    ?>

### Siehe auch

- radius_cvt_int() - Converts raw data to integer
- radius_cvt_string() - Converts raw data to string

# radius_cvt_int

(PECL radius >= 1.1.0)

radius_cvt_int — Converts raw data to integer

### Beschreibung

function radius_cvt_int(string `$data`): int

Converts raw data to integer

### Parameter-Liste

`data`
  Input data

### Rückgabewerte

Returns the integer, retrieved from data.

### Beispiele

Beispiel #1 radius_cvt_int() example

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Error getting attribute: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FRAMED_MTU:
            $mtu = radius_cvt_int($data);
            echo "MTU: $mtu<br>\n";
            break;
        }
    }
    ?>

### Siehe auch

- radius_cvt_addr() - Converts raw data to IP-Address
- radius_cvt_string() - Converts raw data to string

# radius_cvt_string

(PECL radius >= 1.1.0)

radius_cvt_string — Converts raw data to string

### Beschreibung

function radius_cvt_string(string `$data`): string

Converts raw data to string

### Parameter-Liste

`data`
  Input data

### Rückgabewerte

Returns the string, retrieved from data.

### Beispiele

Beispiel #1 radius_cvt_string() example

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Error getting attribute: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        switch ($attr) {

        case RADIUS_FILTER_ID:
            $id = radius_cvt_string($data);
            echo "Filter ID: $id<br>\n";
            break;
        }
    }
    ?>

### Siehe auch

- radius_cvt_addr() - Converts raw data to IP-Address
- radius_cvt_int() - Converts raw data to integer

# radius_demangle

(PECL radius >= 1.2.0)

radius_demangle — Demangles data

### Beschreibung

function radius_demangle(resource `$radius_handle`, string `$mangled`): string

Some data (Passwords, MS-CHAPv1 MPPE-Keys) is mangled for security reasons, and must be demangled before you can use them.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`mangled`
  The mangled data to demangle

### Rückgabewerte

Returns the demangled string, or `false` on error.

# radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_key — Derives mppe-keys from mangled data

### Beschreibung

function radius_demangle_mppe_key(resource `$radius_handle`, string `$mangled`): string

When using MPPE with MS-CHAPv2, the send- and recv-keys are mangled (see » RFC 2548), however this function is useless, because I don't think that there is or will be a PPTP-MPPE implementation in PHP.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`mangled`
  The mangled data to demangle

### Rückgabewerte

Returns the demangled string, or `false` on error.

# radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — Extracts an attribute

### Beschreibung

function radius_get_attr(resource `$radius_handle`): mixed

Like Radius requests, each response may contain zero or more attributes. After a response has been received successfully by radius_send_request(), its attributes can be extracted one by one using radius_get_attr(). Each time radius_get_attr() is called, it gets the next attribute from the current response.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

### Rückgabewerte

Returns an associative array containing the attribute-type and the data, or error number <= 0.

### Beispiele

Beispiel #1 radius_get_attr() example

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf("Error getting attribute: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Got Attr:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
    }
    ?>

### Siehe auch

- radius_put_attr() - Attaches a binary attribute
- radius_get_vendor_attr() - Extracts a vendor specific attribute
- radius_put_vendor_attr() - Attaches a vendor specific binary attribute
- radius_send_request() - Sends the request and waits for a reply

# radius_get_tagged_attr_data

(PECL radius >= 1.3.0)

radius_get_tagged_attr_data — Extracts the data from a tagged attribute

### Beschreibung

function radius_get_tagged_attr_data(string `$data`): string|false

If a tagged attribute has been returned from radius_get_attr(), radius_get_tagged_attr_data() will return the data from the attribute.

### Parameter-Liste

`data`
  The tagged attribute to be decoded.

### Rückgabewerte

Returns the data from the tagged attribute Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 radius_get_tagged_attr_data() example

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Error getting attribute: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Got tagged attribute with tag %d and value %s\n", $tag, $value);
    }
    ?>

### Siehe auch

- radius_get_attr() - Extracts an attribute
- radius_get_tagged_attr_tag() - Extracts the tag from a tagged attribute

# radius_get_tagged_attr_tag

(PECL radius >= 1.3.0)

radius_get_tagged_attr_tag — Extracts the tag from a tagged attribute

### Beschreibung

function radius_get_tagged_attr_tag(string `$data`): int|false

If a tagged attribute has been returned from radius_get_attr(), radius_get_tagged_attr_data() will return the tag from the attribute.

### Parameter-Liste

`data`
  The tagged attribute to be decoded.

### Rückgabewerte

Returns the tag from the tagged attribute Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 radius_get_tagged_attr_tag() example

    <?php
    while ($resa = radius_get_attr($res)) {
        if (!is_array($resa)) {
            printf ("Error getting attribute: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];

        $tag = radius_get_tagged_attr_tag($data);
        $value = radius_get_tagged_attr_data($data);

        printf("Got tagged attribute with tag %d and value %s\n", $tag, $value);
    }
    ?>

### Siehe auch

- radius_get_attr() - Extracts an attribute
- radius_get_tagged_attr_data() - Extracts the data from a tagged attribute

# radius_get_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attr — Extracts a vendor specific attribute

### Beschreibung

function radius_get_vendor_attr(string `$data`): array|false

If radius_get_attr() returns `RADIUS_VENDOR_SPECIFIC`, radius_get_vendor_attr() may be called to determine the vendor.

### Parameter-Liste

`data`
  Input data

### Rückgabewerte

Returns an associative array containing the attribute-type, vendor and the data, or `false` on error.

### Beispiele

Beispiel #1 radius_get_vendor_attr() example

    <?php
    while ($resa = radius_get_attr($res)) {

        if (!is_array($resa)) {
            printf ("Error getting attribute: %s\n",  radius_strerror($res));
            exit;
        }

        $attr = $resa['attr'];
        $data = $resa['data'];
        printf("Got Attr:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
        if ($attr == RADIUS_VENDOR_SPECIFIC) {

            $resv = radius_get_vendor_attr($data);
            if (is_array($resv)) {
                $vendor = $resv['vendor'];
                $attrv = $resv['attr'];
                $datav = $resv['data'];
                printf("Got Vendor Attr:%d %d Bytes %s\n", $attrv, strlen($datav), bin2hex($datav));
            }

        }
    }
    ?>

### Siehe auch

- radius_get_attr() - Extracts an attribute
- radius_put_vendor_attr() - Attaches a vendor specific binary attribute

# radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addr — Attaches an IP address attribute

### Beschreibung

function radius_put_addr(
resource `$radius_handle`,
int `$type`,
string `$addr`,
int `$options` = 0,
int `$tag` = ?
): bool

Attaches an IP address attribute to the current RADIUS request.

> Hinweis:

> Bevor diese Funktion aufgerufen werden kann, muss mittels radius_create_request() eine Anfrage erstellt werden.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`type`

  Der Typ des Attributs.

`addr`
  An IPv4 address in string form, such as `10.0.0.1`.
`options`

  Eine Bitmaske der Attribut-Optionen; zur Verfügung stehen die Optionen `RADIUS_OPTION_TAGGED` und `RADIUS_OPTION_SALT`.

`tag`

  Das Attribut-Tag. Dieser Parameter wird nur berücksichtigt, wenn die Option `RADIUS_OPTION_TAGGED` gesetzt ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

# radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attr — Attaches a binary attribute

### Beschreibung

function radius_put_attr(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attaches a binary attribute to the current RADIUS request.

> Hinweis:

> Bevor diese Funktion aufgerufen werden kann, muss mittels radius_create_request() eine Anfrage erstellt werden.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`type`

  Der Typ des Attributs.

`value`
  The attribute value, which will be treated as a raw binary string.
`options`

  Eine Bitmaske der Attribut-Optionen; zur Verfügung stehen die Optionen `RADIUS_OPTION_TAGGED` und `RADIUS_OPTION_SALT`.

`tag`

  Das Attribut-Tag. Dieser Parameter wird nur berücksichtigt, wenn die Option `RADIUS_OPTION_TAGGED` gesetzt ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### Beispiele

Beispiel #1 radius_put_attr() example

    <?php
    mt_srand(time());
    $chall = mt_rand();
    $chapval = hash('md5', pack('Ca*',1 , 'sepp' . $chall));
    $pass = pack('CH*', 1, $chapval);
    if (!radius_put_attr($res, RADIUS_CHAP_PASSWORD, $pass)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Siehe auch

- radius_get_attr() - Extracts an attribute
- radius_get_vendor_attr() - Extracts a vendor specific attribute
- radius_put_vendor_attr() - Attaches a vendor specific binary attribute

# radius_put_int

(PECL radius >= 1.1.0)

radius_put_int — Attaches an integer attribute

### Beschreibung

function radius_put_int(
resource `$radius_handle`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attaches an integer attribute to the current RADIUS request.

> Hinweis:

> Bevor diese Funktion aufgerufen werden kann, muss mittels radius_create_request() eine Anfrage erstellt werden.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`type`

  Der Typ des Attributs.

`value`
  The attribute value.
`options`

  Eine Bitmaske der Attribut-Optionen; zur Verfügung stehen die Optionen `RADIUS_OPTION_TAGGED` und `RADIUS_OPTION_SALT`.

`tag`

  Das Attribut-Tag. Dieser Parameter wird nur berücksichtigt, wenn die Option `RADIUS_OPTION_TAGGED` gesetzt ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### Beispiele

Beispiel #1 radius_put_int() example

    <?php
    if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) {
       echo 'RadiusError:' . radius_strerror($res). "\n<br />";
       exit;
    }
    ?>

### Siehe auch

- radius_put_string() - Attaches a string attribute
- radius_put_vendor_int() - Attaches a vendor specific integer attribute
- radius_put_vendor_string() - Attaches a vendor specific string attribute

# radius_put_string

(PECL radius >= 1.1.0)

radius_put_string — Attaches a string attribute

### Beschreibung

function radius_put_string(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attaches a string attribute to the current RADIUS request. In general, radius_put_attr() is a more useful function for attaching string attributes, as it is binary safe.

> Hinweis:

> Bevor diese Funktion aufgerufen werden kann, muss mittels radius_create_request() eine Anfrage erstellt werden.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`type`

  Der Typ des Attributs.

`value`
  The attribute value. This value is expected by the underlying library to be null terminated, therefore this parameter is not binary safe.
`options`

  Eine Bitmaske der Attribut-Optionen; zur Verfügung stehen die Optionen `RADIUS_OPTION_TAGGED` und `RADIUS_OPTION_SALT`.

`tag`

  Das Attribut-Tag. Dieser Parameter wird nur berücksichtigt, wenn die Option `RADIUS_OPTION_TAGGED` gesetzt ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### Beispiele

Beispiel #1 radius_put_string() example

    <?php
    if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Siehe auch

- radius_put_int() - Attaches an integer attribute
- radius_put_vendor_int() - Attaches a vendor specific integer attribute
- radius_put_vendor_string() - Attaches a vendor specific string attribute

# radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addr — Attaches a vendor specific IP address attribute

### Beschreibung

function radius_put_vendor_addr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$addr`
): bool

Attaches an IP address vendor specific attribute to the current RADIUS request.

> Hinweis:

> Bevor diese Funktion aufgerufen werden kann, muss mittels radius_create_request() eine Anfrage erstellt werden.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`vendor`

  Die Anbieter-ID.

`type`

  Der Typ des Attributs.

`addr`
  An IPv4 address in string form, such as `10.0.0.1`.
`options`

  Eine Bitmaske der Attribut-Optionen; zur Verfügung stehen die Optionen `RADIUS_OPTION_TAGGED` und `RADIUS_OPTION_SALT`.

`tag`

  Das Attribut-Tag. Dieser Parameter wird nur berücksichtigt, wenn die Option `RADIUS_OPTION_TAGGED` gesetzt ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

# radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attr — Attaches a vendor specific binary attribute

### Beschreibung

function radius_put_vendor_attr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attaches a vendor specific binary attribute to the current RADIUS request.

> Hinweis:

> Bevor diese Funktion aufgerufen werden kann, muss mittels radius_create_request() eine Anfrage erstellt werden.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`vendor`

  Die Anbieter-ID.

`type`

  Der Typ des Attributs.

`value`
  The attribute value, which will be treated as a raw binary string.
`options`

  Eine Bitmaske der Attribut-Optionen; zur Verfügung stehen die Optionen `RADIUS_OPTION_TAGGED` und `RADIUS_OPTION_SALT`.

`tag`

  Das Attribut-Tag. Dieser Parameter wird nur berücksichtigt, wenn die Option `RADIUS_OPTION_TAGGED` gesetzt ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### Beispiele

Beispiel #1 radius_put_vendor_attr() example

    <?php
    if (!radius_put_vendor_attr($res, RADIUS_VENDOR_MICROSOFT, RAD_MICROSOFT_MS_CHAP_CHALLENGE, $challenge)) {
        echo 'RadiusError:' . radius_strerror($res). "\n<br />";
        exit;
    }
    ?>

### Siehe auch

- radius_get_vendor_attr() - Extracts a vendor specific attribute

# radius_put_vendor_int

(PECL radius >= 1.1.0)

radius_put_vendor_int — Attaches a vendor specific integer attribute

### Beschreibung

function radius_put_vendor_int(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attaches a vendor specific integer attribute to the current RADIUS request.

> Hinweis:

> Bevor diese Funktion aufgerufen werden kann, muss mittels radius_create_request() eine Anfrage erstellt werden.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`vendor`

  Die Anbieter-ID.

`type`

  Der Typ des Attributs.

`value`
  The attribute value.
`options`

  Eine Bitmaske der Attribut-Optionen; zur Verfügung stehen die Optionen `RADIUS_OPTION_TAGGED` und `RADIUS_OPTION_SALT`.

`tag`

  Das Attribut-Tag. Dieser Parameter wird nur berücksichtigt, wenn die Option `RADIUS_OPTION_TAGGED` gesetzt ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### Siehe auch

- radius_put_vendor_string() - Attaches a vendor specific string attribute

# radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_string — Attaches a vendor specific string attribute

### Beschreibung

function radius_put_vendor_string(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

Attaches a vendor specific string attribute to the current RADIUS request. In general, radius_put_vendor_attr() is a more useful function for attaching string attributes, as it is binary safe.

> Hinweis:

> Bevor diese Funktion aufgerufen werden kann, muss mittels radius_create_request() eine Anfrage erstellt werden.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

`vendor`

  Die Anbieter-ID.

`type`

  Der Typ des Attributs.

`value`
  The attribute value. This value is expected by the underlying library to be null terminated, therefore this parameter is not binary safe.
`options`

  Eine Bitmaske der Attribut-Optionen; zur Verfügung stehen die Optionen `RADIUS_OPTION_TAGGED` und `RADIUS_OPTION_SALT`.

`tag`

  Das Attribut-Tag. Dieser Parameter wird nur berücksichtigt, wenn die Option `RADIUS_OPTION_TAGGED` gesetzt ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL radius 1.3.0 | The `options` and `tag` parameters were added.

### Siehe auch

- radius_put_vendor_int() - Attaches a vendor specific integer attribute

# radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticator — Returns the request authenticator

### Beschreibung

function radius_request_authenticator(resource `$radius_handle`): string

The request authenticator is needed for demangling mangled data like passwords and encryption-keys.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

### Rückgabewerte

Returns the request authenticator as string, or `false` on error.

### Siehe auch

- radius_demangle() - Demangles data

# radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attr — Salt-encrypts a value

### Beschreibung

function radius_salt_encrypt_attr(resource `$radius_handle`, string `$data`): string|false

Applies the RADIUS salt-encryption algorithm to the given value.

In general, this is achieved automatically by providing the `RADIUS_OPTION_SALT` option to an attribute setter function, but this function can be used if low-level request construction is required.

### Parameter-Liste

`data`
  The data to be salt-encrypted.

### Rückgabewerte

Returns the salt-encrypted data Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- radius_put_addr() - Attaches an IP address attribute
- radius_put_attr() - Attaches a binary attribute
- radius_put_int() - Attaches an integer attribute
- radius_put_string() - Attaches a string attribute

# radius_send_request

(PECL radius >= 1.1.0)

radius_send_request — Sends the request and waits for a reply

### Beschreibung

function radius_send_request(resource `$radius_handle`): int

After the Radius request has been constructed, it is sent by radius_send_request().

The radius_send_request() function sends the request and waits for a valid reply, retrying the defined servers in round-robin fashion as necessary.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

### Rückgabewerte

If a valid response is received, radius_send_request() returns the Radius code which specifies the type of the response. This will typically be `RADIUS_ACCESS_ACCEPT`, `RADIUS_ACCESS_REJECT`, or `RADIUS_ACCESS_CHALLENGE`. If no valid response is received, radius_send_request() returns `false`.

### Siehe auch

- radius_create_request() - Create accounting or authentication request

# radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — Returns the shared secret

### Beschreibung

function radius_server_secret(resource `$radius_handle`): string

The shared secret is needed as salt for demangling mangled data like passwords and encryption-keys.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

### Rückgabewerte

Returns the server's shared secret as string, or `false` on error.

# radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — Gibt eine Fehlermeldung zurück

### Beschreibung

function radius_strerror(resource `$radius_handle`): string

Wenn Radius-Funktionen fehlschlagen, wird eine Fehlermeldung aufgezeichnet. Diese Fehlermeldung kann mit dieser Funktion abgerufen werden.

### Parameter-Liste

`radius_handle`

  Die RADIUS-Ressource.

### Rückgabewerte

Gibt Fehlermeldungen als Zeichenkette von fehlgeschlagenen Radius-Funktionen zurück.

## Inhaltsverzeichnis

- radius_acct_open — Creates a Radius handle for accounting
- radius_add_server — Adds a server
- radius_auth_open — Creates a Radius handle for authentication
- radius_close — Gibt alle Ressourcen frei
- radius_config — Causes the library to read the given configuration file
- radius_create_request — Create accounting or authentication request
- radius_cvt_addr — Converts raw data to IP-Address
- radius_cvt_int — Converts raw data to integer
- radius_cvt_string — Converts raw data to string
- radius_demangle — Demangles data
- radius_demangle_mppe_key — Derives mppe-keys from mangled data
- radius_get_attr — Extracts an attribute
- radius_get_tagged_attr_data — Extracts the data from a tagged attribute
- radius_get_tagged_attr_tag — Extracts the tag from a tagged attribute
- radius_get_vendor_attr — Extracts a vendor specific attribute
- radius_put_addr — Attaches an IP address attribute
- radius_put_attr — Attaches a binary attribute
- radius_put_int — Attaches an integer attribute
- radius_put_string — Attaches a string attribute
- radius_put_vendor_addr — Attaches a vendor specific IP address attribute
- radius_put_vendor_attr — Attaches a vendor specific binary attribute
- radius_put_vendor_int — Attaches a vendor specific integer attribute
- radius_put_vendor_string — Attaches a vendor specific string attribute
- radius_request_authenticator — Returns the request authenticator
- radius_salt_encrypt_attr — Salt-encrypts a value
- radius_send_request — Sends the request and waits for a reply
- radius_server_secret — Returns the shared secret
- radius_strerror — Gibt eine Fehlermeldung zurück

- Installation/Konfiguration
  - Installation
- Vordefinierte Konstanten
  - RADIUS Options
  - RADIUS Packet Types
  - RADIUS Attribute Types
  - RADIUS Vendor Specific Attribute Types
- Beispiele
- Radius Funktionen
  - radius_acct_open — Creates a Radius handle for accounting
  - radius_add_server — Adds a server
  - radius_auth_open — Creates a Radius handle for authentication
  - radius_close — Gibt alle Ressourcen frei
  - radius_config — Causes the library to read the given configuration file
  - radius_create_request — Create accounting or authentication request
  - radius_cvt_addr — Converts raw data to IP-Address
  - radius_cvt_int — Converts raw data to integer
  - radius_cvt_string — Converts raw data to string
  - radius_demangle — Demangles data
  - radius_demangle_mppe_key — Derives mppe-keys from mangled data
  - radius_get_attr — Extracts an attribute
  - radius_get_tagged_attr_data — Extracts the data from a tagged attribute
  - radius_get_tagged_attr_tag — Extracts the tag from a tagged attribute
  - radius_get_vendor_attr — Extracts a vendor specific attribute
  - radius_put_addr — Attaches an IP address attribute
  - radius_put_attr — Attaches a binary attribute
  - radius_put_int — Attaches an integer attribute
  - radius_put_string — Attaches a string attribute
  - radius_put_vendor_addr — Attaches a vendor specific IP address attribute
  - radius_put_vendor_attr — Attaches a vendor specific binary attribute
  - radius_put_vendor_int — Attaches a vendor specific integer attribute
  - radius_put_vendor_string — Attaches a vendor specific string attribute
  - radius_request_authenticator — Returns the request authenticator
  - radius_salt_encrypt_attr — Salt-encrypts a value
  - radius_send_request — Sends the request and waits for a reply
  - radius_server_secret — Returns the shared secret
  - radius_strerror — Gibt eine Fehlermeldung zurück

- Radius
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Radius Funktionen

# Eingabezeilenspezifische Erweiterungen

# GNU-Readline

# Einführung

Die readline-Funktionen implementieren eine Schnittstelle zur GNU-Readline-Bibliothek. Diese Funktionen bieten die Möglichkeit, Kommandozeilen zu editieren. Ein Beispiel für die Anwendung ist die Art und Weise, wie die Bash es erlaubt, die Pfeiltasten zu benutzen, um Schriftzeichen einzufügen oder durch die Kommando-History zu scrollen. Auf Grund des interaktiven Charakters dieser Bibliothek ist diese beim Programmieren von Webanwendungen von geringem Nutzen, kann aber nützlich sein, wenn Sie Skripte schreiben, die dafür gedacht sind, PHP von der Kommandozeile auszuführen.

Von PHP 7.1.0 an wird diese Erweiterung unter Windows unterstützt.

Achtung

Die Erweiterung readline ist nicht threadsicher! Daher wird von der Verwendung mit jeglicher threadsicheren SAPI (wie Apaches mod_winnt) unbedingt abgeraten.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

Um die Funktionen von readline nutzen zu können, müssen Sie libreadline installieren. Sie finden libreadline auf der Homepage des GNU-Readline-Projekts unter » https://tiswww.case.edu/php/chet/readline/rltop.html. Es wird von Chet Ramey betreut, der auch der Autor von Bash ist.

Sie können diese Funktionen auch mit der libedit-Bibliothek verwenden, einem nicht unter der GPL stehenden Ersatz für die readline-Bibliothek. Die libedit-Bibliothek steht unter BSD-Lizenz und kann unter » http://www.thrysoee.dk/editline/ heruntergeladen werden.

## Installation

Um diese Funktionen benutzten zu können, müssen Sie die CLI- oder CGI-Version von PHP mit readline-Unterstützung kompiliert sein. Dazu müssen Sie PHP mit der Option --with-readline konfigurieren. Wenn Sie libedit als readline-Ersatz verwendet wollen, konfigurieren Sie PHP mit --with-libedit[=DIR].

Unter Windows ist diese Erweiterung von PHP 7.1.0 an standardmäßig verfügbar.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Readline-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
cli.pager | "" | `INI_ALL` |
cli.prompt | "\\b \\> " | `INI_ALL` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`cli.pager` string
  Das externe Programm für die Ausgabe der Kommandozeile.
`cli.prompt` string
  Die Eingabeaufforderung der Kommandozeile.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`READLINE_LIB` (string)
  Die Bibliothek, die für die readline-Unterstützung verwendet wird; derzeit entweder `readline` oder `libedit`.

# Readline-Funktionen

# readline

(PHP 4, PHP 5, PHP 7, PHP 8)

readline — Liest eine Zeile

### Beschreibung

function readline(?string `$prompt` = `null`): string|false

Liest eine einzelne Zeile vom Benutzer ein. Sie müssen diese Zeile selbst mittels readline_add_history() zur History hinzufügen.

### Parameter-Liste

`prompt`
  Sie können eine Zeichenkette angeben, mit dem Sie den Benutzer zur Eingabe auffordern.

### Rückgabewerte

Gibt eine einzelne Zeile des Benutzers zurück. Der Zeile, die zurückgegeben wird, fehlt das abschließende Zeichen für einen Zeilenvorschub. Können keine weiteren Daten gelesen werden, wird `false` zurückgegeben.

### Beispiele

Beispiel #1 readline()-Beispiel

    <?php
    // Drei Kommandos vom Benutzer abfragen
    for ($i=0; $i < 3; $i++) {
            $line = readline("Command: ");
            readline_add_history($line);
    }

    // History ausgeben
    print_r(readline_list_history());

    // Variablen ausgeben
    print_r(readline_info());
    ?>

# readline_add_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_add_history — Fügt eine Zeile zur History hinzu

### Beschreibung

function readline_add_history(string `$prompt`): true

Diese Funktion fügt eine Zeile zur Kommandozeilen-History hinzu.

### Parameter-Liste

`prompt`
  Die zur History hinzuzufügende Zeile.

### Rückgabewerte

Gibt immer `true` zurück.

# readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_install — Initialisiert das readline-Callback-Interface und das Terminal, gibt den Prompt aus und springt direkt zurück

### Beschreibung

function readline_callback_handler_install(string `$prompt`, callable `$callback`): true

Initialisiert ein readline-Callback-Interface, gibt danach den `prompt` aus und springt direkt zurück. Der doppelte Aufruf der Funktion ohne Zurücksetzen des verwendeten Callback-Interfaces wird automatisch und in geeigneter Weise das alte Interface überschreiben.

Die Callback-Fähigkeiten sind hilfreich, wenn sie mit stream_select() kombiniert werden, da dies eine Verschränkung von IO und Benutzereingaben wie mittels readline() ermöglicht.

### Parameter-Liste

`prompt`
  Die Prompt-Message.
`callback`
  Die `callback`-Funktion benötigt einen Parameter; die Benutzereingabe wird zurückgegeben.

### Rückgabewerte

Gibt immer `true` zurück.

### Beispiele

Beispiel #1 Readline-Callback-Interface-Beispiel

    <?php
    function rl_callback($ret)
    {
        global $c, $prompting;

        echo "Sie haben eingegeben: $ret\n";
        $c++;

        if ($c > 10) {
            $prompting = false;
            readline_callback_handler_remove();
        } else {
            readline_callback_handler_install("[$c] Geben Sie etwas ein: ", 'rl_callback');
        }
    }

    $c = 1;
    $prompting = true;

    readline_callback_handler_install("[$c] Geben Sie etwas ein: ", 'rl_callback');

    while ($prompting) {
        $w = NULL;
        $e = NULL;
        $n = stream_select($r = array(STDIN), $w, $e, null);
        if ($n && in_array(STDIN, $r)) {
            // Liest das aktuelle Zeichen und ruft die Callbackfunktion auf, wenn ein
            // Newline-Zeichen eingegeben wurde
            readline_callback_read_char();
        }
    }

    echo "Eingabe deaktiviert. Komplett ausgeführt.\n";
    ?>

### Siehe auch

- readline_callback_handler_remove() - Entfernt den letztdefinierten Callbackhandler und setzt die Terminalumgebung auf die Ursprungswerte zurück
- readline_callback_read_char() - Liest ein Zeichen und informiert das readline-Callback-Interface, wenn die Eingabezeile abgeschlossen wurde
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by seconds and microseconds

# readline_callback_handler_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_remove — Entfernt den letztdefinierten Callbackhandler und setzt die Terminalumgebung auf die Ursprungswerte zurück

### Beschreibung

function readline_callback_handler_remove(): bool

Entfernt den letztdefinierten Callbackhandler und setzt die Terminalumgebung auf die Ursprungswerte zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn der letztdefinierte Callbackhandler zurückgesetzt wurde; falls dieser nicht gefunden wurde, wird `false` zurückgegeben.

### Beispiele

Werfen Sie auch einen Blick auf die Dokumentation der Funktion readline_callback_handler_install(), dort finden Sie ein Beispiel zur Verwendung des readline-Callback-Interfaces.

### Siehe auch

- readline_callback_handler_install() - Initialisiert das readline-Callback-Interface und das Terminal, gibt den Prompt aus und springt direkt zurück
- readline_callback_read_char() - Liest ein Zeichen und informiert das readline-Callback-Interface, wenn die Eingabezeile abgeschlossen wurde

# readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_char — Liest ein Zeichen und informiert das readline-Callback-Interface, wenn die Eingabezeile abgeschlossen wurde

### Beschreibung

function readline_callback_read_char(): void

Liest ein Zeichen der Benutzereingabe ein. Wenn eine Eingabezeile abgeschlossen ist, informiert diese Funktion das readline-Callback-Interface, das mittels readline_callback_handler_install()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Werfen Sie auch einen Blick auf die Dokumentation der Funktion readline_callback_handler_install(), dort finden Sie ein Beispiel zur Verwendung des readline-Callback-Interfaces.

### Siehe auch

- readline_callback_handler_install() - Initialisiert das readline-Callback-Interface und das Terminal, gibt den Prompt aus und springt direkt zurück
- readline_callback_handler_remove() - Entfernt den letztdefinierten Callbackhandler und setzt die Terminalumgebung auf die Ursprungswerte zurück

# readline_clear_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_clear_history — Löscht die History

### Beschreibung

function readline_clear_history(): true

Diese Funktion löscht die gesamte Kommandozeilen-History.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `true` zurück.

# readline_completion_function

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_completion_function — Registriert eine Vervollständigungsfunktion

### Beschreibung

function readline_completion_function(callable `$callback`): bool

Diese Funktion registriert eine Vervollständigungsfunktion. Das ist die gleiche Art von Funktionalität, die sie erhalten, wenn Sie die Tab-Taste benutzen, während Sie in der Bash arbeiten.

### Parameter-Liste

`callback`
  Sie müssen den Namen einer existierenden Funktion angeben, die einen Teil einer Kommandozeile akzeptiert und ein Array möglicher Übereinstimmungen zurückgibt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# readline_info

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_info — Liest/Setzt verschiedene interne readline-Variablen

### Beschreibung

function readline_info(?string `$var_name` = `null`, int|string|bool|null `$value` = `null`): mixed

Liest/Setzt verschiedene interne readline-Variablen.

### Parameter-Liste

`var_name`
  Ein Variablenname.
`value`
  Sofern unterstützt, entspricht der Parameter dem neuen gesetzten Wert.

### Rückgabewerte

Wenn diese Funktion ohne Parameter aufgerufen wird, gibt sie ein Array von Werten für alle Einstellungen zurück, die readline benutzen. Die Elemente werden durch die folgenden Werte indiziert: `done`, `end`, `erase_empty_line`, `library_version`, `line_buffer`, `mark`, `pending_input`, `point`, `prompt`, `readline_name` und `terminal_name`. Das Array enthält nur die Elemente, die von der Bibliothek unterstützt werden, mit der die Erweiterung readline erstellt wurde.

Wird die Funktion mit einem oder zwei Parametern aufgerufen, wird der alte Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `var_name` und `value` sind nun Nullable-Typen.

# readline_list_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_list_history — Auflistung der History

### Beschreibung

function readline_list_history(): array

Gibt die vollständige Kommandozeilen-History zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Diese Funktion gibt ein Array der gesamten Kommandozeilen-History zurück. Die Elemente sind numerisch indiziert, beginnend bei Null.

# readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_line — Informiert readline, dass der Cursor in eine neue Zeile bewegt wurde

### Beschreibung

function readline_on_new_line(): void

Informiert readline, dass der Cursor in eine neue Zeile bewegt wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Anmerkungen

> Hinweis: Diese Funktion ist nur verfügbar, wenn sie von der zugrunde liegenden readline-Bibliothek unterstützt wird. Sie wird unter Windows nicht unterstützt.

# readline_read_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_read_history — Liest die History

### Beschreibung

function readline_read_history(?string `$filename` = `null`): bool

Diese Funktion liest eine Kommandozeilen-History aus einer Datei.

### Parameter-Liste

`filename`
  Pfad zur Datei, die die Kommandozeilen-History enthält.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `filename` ist nun ein Nullable-Typ.

# readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplay — Zeichnet den Bildschirm neu

### Beschreibung

function readline_redisplay(): void

Zeichnet die Eingabezeile neu um den Bildschirm neu aufzubauen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# readline_write_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_write_history — Schreibt die History

### Beschreibung

function readline_write_history(?string `$filename` = `null`): bool

Diese Funktion schreibt die Kommandozeilen-History in eine Datei.

### Parameter-Liste

`filename`
  Pfad zur Datei, in der gespeichert werden soll.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `filename` ist nun ein Nullable-Typ.

## Inhaltsverzeichnis

- readline — Liest eine Zeile
- readline_add_history — Fügt eine Zeile zur History hinzu
- readline_callback_handler_install — Initialisiert das readline-Callback-Interface und das Terminal, gibt den Prompt aus und springt direkt zurück
- readline_callback_handler_remove — Entfernt den letztdefinierten Callbackhandler und setzt die Terminalumgebung auf die Ursprungswerte zurück
- readline_callback_read_char — Liest ein Zeichen und informiert das readline-Callback-Interface, wenn die Eingabezeile abgeschlossen wurde
- readline_clear_history — Löscht die History
- readline_completion_function — Registriert eine Vervollständigungsfunktion
- readline_info — Liest/Setzt verschiedene interne readline-Variablen
- readline_list_history — Auflistung der History
- readline_on_new_line — Informiert readline, dass der Cursor in eine neue Zeile bewegt wurde
- readline_read_history — Liest die History
- readline_redisplay — Zeichnet den Bildschirm neu
- readline_write_history — Schreibt die History

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Readline-Funktionen
  - readline — Liest eine Zeile
  - readline_add_history — Fügt eine Zeile zur History hinzu
  - readline_callback_handler_install — Initialisiert das readline-Callback-Interface und das Terminal, gibt den Prompt aus und springt direkt zurück
  - readline_callback_handler_remove — Entfernt den letztdefinierten Callbackhandler und setzt die Terminalumgebung auf die Ursprungswerte zurück
  - readline_callback_read_char — Liest ein Zeichen und informiert das readline-Callback-Interface, wenn die Eingabezeile abgeschlossen wurde
  - readline_clear_history — Löscht die History
  - readline_completion_function — Registriert eine Vervollständigungsfunktion
  - readline_info — Liest/Setzt verschiedene interne readline-Variablen
  - readline_list_history — Auflistung der History
  - readline_on_new_line — Informiert readline, dass der Cursor in eine neue Zeile bewegt wurde
  - readline_read_history — Liest die History
  - readline_redisplay — Zeichnet den Bildschirm neu
  - readline_write_history — Schreibt die History

- Readline — GNU-Readline
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Readline-Funktionen

# Erweiterungen zur Datenkompression und Archivierung

# Bzip2

# Einführung

Die bzip2-Funktionen werden benutzt, um transparent bzip2 (.bz2)-komprimierte Dateien lesen und schreiben zu können.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Ressource-Typen

## Anforderungen

Dieses Module nutzt die Funktionen der » bzip2-Bibliothek von Julian Seward. Dabei benötigt das Modul eine Version der bzip2/libbzip2 >= 1.0.x.

## Installation

Die Bzip2-Unterstützung ist in PHP nicht standardmäßig aktiviert. Es ist erforderlich, die Option --with-bz2[=DIR] beim Kompilieren von PHP anzugeben.

## Ressource-Typen

This extension defines one resource type: a file pointer identifying the bz2-file to work on.

# Beispiele

Dieses Beispiel öffnet eine temporäre Datei und schreibt einen Teststring in diese, danach wird der Inhalt der Datei ausgegeben.

Beispiel #1 Ein kleines bzip2()-Beispiel

    <?php

    $filename = "/tmp/testfile.bz2";
    $str = "Das ist ein Test.\n";

    // Datei zum Schreiben öffnen
    $bz = bzopen($filename, "w");

    // Zeichenkette in Datei schreiben
    bzwrite($bz, $str);

    // Datei schließen
    bzclose($bz);

    // Datei zum Lesen öffnen
    $bz = bzopen($filename, "r");

    // 10 Zeichen lesen
    echo bzread($bz, 10);

    /* Ausgabe bis zum Dateiende (oder der nächsten 1024 Zeichen) und schließen
    der Datei. */
    echo bzread($bz);

    bzclose($bz);

    ?>

# Bzip2 Funktionen

# bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzclose — Schließt eine bzip2-Datei

### Beschreibung

function bzclose(resource `$bz`): bool

Schließt die vom übergebenen Dateizeiger bezeichnete bzip2-Datei.

### Parameter-Liste

`bz`
  Der Dateizeiger. Dieser muss eine valide Ressource sein und muss auf eine Datei zeigen, die erfolgreich mittels bzopen() geöffnet wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- bzopen() - Öffnet eine bzip2-komprimierte Datei

# bzcompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcompress — Komprimiert eine Zeichenkette in bzip2-encodierte Daten

### Beschreibung

function bzcompress(string `$data`, int `$block_size` = 4, int `$work_factor` = 0): string|int

bzcompress() komprimiert den übergebenen String und gibt ihn als bzip2-komprimierte Daten zurück.

### Parameter-Liste

`data`
  Die zu komprimierende Zeichenkette.
`block_size`
  Spezifiziert die Blockgröße während der Komprierung und darf zwischen 1 und 9 liegen. 9 ist dabei die beste Komprimierung, die allerdings mehr Ressourcen benötigt.
`work_factor`
  Bestimmt, wie die Funktion sich im schlimmsten Fall, sich stark wiederholender Eingabedaten, verhält. Der Wert darf zwischen 0 und 250 liegen, wobei 0 ein spezieller Wert ist. Unabhängig vom `work_factor`-Parameter wird die generierte Ausgabe stets gleich bleiben.

### Rückgabewerte

Die komprimierte Zeichenkette oder die Fehlernummer im Falle eines Fehlers.

### Beispiele

Beispiel #1 Komprimierung von Daten

    <?php
    $str = "sample data";
    $bzstr = bzcompress($str, 9);
    echo $bzstr;
    ?>

### Siehe auch

- bzdecompress() - Dekomprimiert bzip2-kodierte Daten

# bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompress — Dekomprimiert bzip2-kodierte Daten

### Beschreibung

function bzdecompress(string `$data`, bool `$use_less_memory` = `false`): string|int|false

bzdecompress() dekomprimiert die übergebene Zeichenkette, die bzip2-kodierte Daten enthält.

### Parameter-Liste

`data`
  Zu dekomprimierende Zeichenkette
`use_less_memory`
  Wenn `true`, wird ein alternativer Dekompressionsalgorithmus verwendet, der weniger Speicher benötigt. Es werden dann nur maximal etwa 2300K benötigt, allerdings findet die Dekompression nur mit etwa halber Geschwindigkeit statt. Weitere Details finden sich in der » bzip2-Dokumentation.

### Rückgabewerte

Die dekomprimierte Zeichenfolge oder `false` oder eine Fehlernummer, wenn ein Fehler aufgetreten ist.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Typ von `use_less_memory` wurde von int in bool geändert. Bisher war der Standardwert `0`.

### Beispiele

Beispiel #1 Dekomprimieren einer Zeichenkette

    <?php
    $start_str = "Ist dies nicht ein ernstes Gesicht?";
    $bzstr = bzcompress($start_str);

    echo "Komprimierte Zeichenkette: ";
    echo $bzstr;
    echo "\n<br />\n";

    $str = bzdecompress($bzstr);
    echo "Dekomprimierte Zeichenkette: ";
    echo $str;
    echo "\n<br />\n";
    ?>

### Siehe auch

- bzcompress() - Komprimiert eine Zeichenkette in bzip2-encodierte Daten

# bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrno — Gibt eine bzip2-Fehlernummer zurück

### Beschreibung

function bzerrno(resource `$bz`): int

Gibt die Fehlernummer eines beliebigen bzip2-Fehlers, der von übergebenen Dateizeiger zurückgegeben wird.

### Parameter-Liste

`bz`
  Zeiger auf eine erfolgreich mittels bzopen() geöffnete Datei.

### Rückgabewerte

Gibt die Fehlernummer als Integer zurück.

### Siehe auch

- bzerror() - Gibt die bzip2-Fehlernummer und die -Fehlermeldung in einem Array zurück
- bzerrstr() - Gibt eine bzip2-Fehlermeldung zurück

# bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerror — Gibt die bzip2-Fehlernummer und die -Fehlermeldung in einem Array zurück

### Beschreibung

function bzerror(resource `$bz`): array

Gibt die Fehlernummer und die Fehlermeldung eines beliebigen vom gegebenen Dateizeiger gelieferten bzip2-Fehlers zurück.

### Parameter-Liste

`bz`
  Zeiger auf eine erfolgreich mittels bzopen() geöffnete Datei.

### Rückgabewerte

Gibt ein assoziatives Array zurück, das die Fehlernummer im `errno`-Eintrag und die Fehlermeldung im `errstr`-Eintrag enthält.

### Beispiele

Beispiel #1 bzerror()-Beispiel

    <?php
    $error = bzerror($bz);

    echo $error["errno"];
    echo $error["errstr"];
    ?>

### Siehe auch

- bzerrno() - Gibt eine bzip2-Fehlernummer zurück
- bzerrstr() - Gibt eine bzip2-Fehlermeldung zurück

# bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstr — Gibt eine bzip2-Fehlermeldung zurück

### Beschreibung

function bzerrstr(resource `$bz`): string

Gibt die Fehlermeldung eines bzip2-Fehlers zurück, der vom gegebenen Dateizeiger zurückgegeben wird.

### Parameter-Liste

`bz`
  Zeiger auf eine erfolgreich mittels bzopen() geöffnete Datei.

### Rückgabewerte

Gibt eine Zeichenkette mit der Fehlermeldung zurück.

### Siehe auch

- bzerrno() - Gibt eine bzip2-Fehlernummer zurück
- bzerror() - Gibt die bzip2-Fehlernummer und die -Fehlermeldung in einem Array zurück

# bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflush — Nichts tun

### Beschreibung

function bzflush(resource `$bz`): bool

Diese Funktion soll ein Schreiben aller gepufferten bzip2-Daten für den Dateizeiger `bz` erzwingen, ist aber in libbz2 als Nullfunktion implementiert und tut als solche nichts.

### Parameter-Liste

`bz`
  Zeiger auf eine erfolgreich mittels bzopen() geöffnete Datei.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- bzread() - Binär-sicheres Lesen aus einer bzip2-Datei
- bzwrite() - Binär-sicheres Schreiben einer bzip2-Datei

# bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopen — Öffnet eine bzip2-komprimierte Datei

### Beschreibung

function bzopen(string|resource `$file`, string `$mode`): resource|false

Öffnet eine bzip2-Datei (.bz2) zum Lesen oder Schreiben.

### Parameter-Liste

`file`
  Name der zu öffnenden Datei, oder eine bestehende Stream-Ressource.
`mode`
  Die Modi `'r'` und `'w'` werden unterstützt. Andere Werte führen dazu, daß bzopen `false` zurückgibt.

### Rückgabewerte

Wenn das Öffnen fehlschlägt, gibt bzopen() `false` zurück, andernfalls wird ein Zeiger auf die geöffnete Datei zurückgegeben.

### Beispiele

Beispiel #1 bzopen()-Beispiel

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("$file konnte nicht zum Lesen geöffnet werden");

    bzclose($bz);

    ?>

### Siehe auch

- bzclose() - Schließt eine bzip2-Datei

# bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzread — Binär-sicheres Lesen aus einer bzip2-Datei

### Beschreibung

function bzread(resource `$bz`, int `$length` = 1024): string|false

bzread() liest Daten vom übergebenen bzip2-Dateizeiger.

Das Lesen wird beendet, wenn `length` (unkomprimierte) Bytes gelesen wurden oder das Ende der Datei (EOF) erreicht ist, je nachdem, welcher Fall zuerst auftritt.

### Parameter-Liste

`bz`
  Der Dateizeiger. Es muss ein valider Zeiger sein und auf eine Datei zeigen, die erfolgreich mittels bzopen() geöffnet wurde.
`length`
  Wenn nichts angegeben ist, liest bzread() 1024 (unkomprimierte) Bytes auf einmal. Maximal 8192 unkomprimierte Bytes können auf einmal gelesen werden.

### Rückgabewerte

Gibt die unkomprimierten Daten oder im Fehlerfall `false` zurück.

### Beispiele

Beispiel #1 bzread()-Beispiel

    <?php

    $file = "/tmp/foo.bz2";
    $bz = bzopen($file, "r") or die("Konnte $file nicht öffnen");

    $decompressed_file = '';
    while (!feof($bz)) {
      $decompressed_file .= bzread($bz, 4096);
    }
    bzclose($bz);

    echo "Der Inhalt von $file ist: <br />\n";
    echo $decompressed_file;

    ?>

### Siehe auch

- bzwrite() - Binär-sicheres Schreiben einer bzip2-Datei
- feof() - Prüft, ob ein Dateizeiger am Ende der Datei steht
- bzopen() - Öffnet eine bzip2-komprimierte Datei

# bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwrite — Binär-sicheres Schreiben einer bzip2-Datei

### Beschreibung

function bzwrite(resource `$bz`, string `$data`, ?int `$length` = `null`): int|false

bzwrite() schreibt eine Zeichenkette in den übergebenen bzip2-Dateistream.

### Parameter-Liste

`bz`
  Der Dateizeiger. Muss gültig sein und auf eine erfolgreich von bzopen() geöffnete Datei zeigen.
`data`
  Die zu schreibenden Daten.
`length`
  Wird dieser Parameter übergeben, stoppt das Schreiben nach `length` (unkomprimiert) geschriebenen Bytes oder wenn alle Bytes aus `data` geschrieben wurden, je nachdem, welcher Fall zuerst auftritt.

### Rückgabewerte

Gibt die Anzahl der geschriebenen Bytes bzw. `false` im Falle eines Fehlers zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `length` ist jetzt nullbar.

### Beispiele

Beispiel #1 bzwrite()-Beispiel

    <?php
    $str = "uncompressed data";
    $bz = bzopen("/tmp/foo.bz2", "w");
    bzwrite($bz, $str, strlen($str));
    bzclose($bz);
    ?>

### Siehe auch

- bzread() - Binär-sicheres Lesen aus einer bzip2-Datei
- bzopen() - Öffnet eine bzip2-komprimierte Datei

## Inhaltsverzeichnis

- bzclose — Schließt eine bzip2-Datei
- bzcompress — Komprimiert eine Zeichenkette in bzip2-encodierte Daten
- bzdecompress — Dekomprimiert bzip2-kodierte Daten
- bzerrno — Gibt eine bzip2-Fehlernummer zurück
- bzerror — Gibt die bzip2-Fehlernummer und die -Fehlermeldung in einem Array zurück
- bzerrstr — Gibt eine bzip2-Fehlermeldung zurück
- bzflush — Nichts tun
- bzopen — Öffnet eine bzip2-komprimierte Datei
- bzread — Binär-sicheres Lesen aus einer bzip2-Datei
- bzwrite — Binär-sicheres Schreiben einer bzip2-Datei

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Ressource-Typen
- Beispiele
- Bzip2 Funktionen
  - bzclose — Schließt eine bzip2-Datei
  - bzcompress — Komprimiert eine Zeichenkette in bzip2-encodierte Daten
  - bzdecompress — Dekomprimiert bzip2-kodierte Daten
  - bzerrno — Gibt eine bzip2-Fehlernummer zurück
  - bzerror — Gibt die bzip2-Fehlernummer und die -Fehlermeldung in einem Array zurück
  - bzerrstr — Gibt eine bzip2-Fehlermeldung zurück
  - bzflush — Nichts tun
  - bzopen — Öffnet eine bzip2-komprimierte Datei
  - bzread — Binär-sicheres Lesen aus einer bzip2-Datei
  - bzwrite — Binär-sicheres Schreiben einer bzip2-Datei

# LZF

# Einführung

LZF is a very fast compression algorithm, ideal for saving space with only slight speed cost. It can be optimized for speed or space at the time of compilation. This extension is using » liblzf library by Marc Lehmann for its operations.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP. Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/lzf.

In order to use these functions you must compile PHP with lzf support by using the --with-lzf[=DIR] configure option. You may also pass --enable-lzf-better-compression to optimize LZF for space rather than speed.

Windows users will enable php_lzf.dll inside of php.ini in order to use these functions.

# LZF Funktionen

# lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — LZF compression

### Beschreibung

function lzf_compress(string `$data`): string

lzf_compress() compresses the given `data` string using LZF encoding.

### Parameter-Liste

`data`
  The string to compress.

### Rückgabewerte

Returns the compressed data or `false` if an error occurred.

### Siehe auch

- lzf_decompress() - LZF decompression

# lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — LZF decompression

### Beschreibung

function lzf_decompress(string `$data`): string

lzf_compress() decompresses the given `data` string containing lzf encoded data.

### Parameter-Liste

`data`
  The compressed string.

### Rückgabewerte

Returns the decompressed data or `false` if an error occurred.

### Siehe auch

- lzf_compress() - LZF compression

# lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — Ermittelt, wofür die LZF-Erweiterung optimiert wurde

### Beschreibung

function lzf_optimized_for(): int

Ermittelt, wofür die LZF-Erweiterung bei der Kompilierung optimiert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt 1 zurück, wenn LZF für Geschwindigkeit optimiert wurde, 0 für Komprimierung.

## Inhaltsverzeichnis

- lzf_compress — LZF compression
- lzf_decompress — LZF decompression
- lzf_optimized_for — Ermittelt, wofür die LZF-Erweiterung optimiert wurde

- Installation/Konfiguration
  - Installation
- LZF Funktionen
  - lzf_compress — LZF compression
  - lzf_decompress — LZF decompression
  - lzf_optimized_for — Ermittelt, wofür die LZF-Erweiterung optimiert wurde

# Phar

# Einführung

The phar extension provides a way to put entire PHP applications into a single file called a "phar" (PHP Archive) for easy distribution and installation. In addition to providing this service, the phar extension also provides a file-format abstraction method for creating and manipulating tar and zip files through the PharData class, much as PDO provides a unified interface for accessing different databases. Unlike PDO, which cannot convert between different databases, Phar also can convert between tar, zip and phar file formats with a single line of code. see Phar::convertToExecutable() for one example.

What is phar? Phar archives are best characterized as a convenient way to group several files into a single file. As such, a phar archive provides a way to distribute a complete PHP application in a single file and run it from that file without the need to extract it to disk. Additionally, phar archives can be executed by PHP as easily as any other file, both on the commandline and from a web server. Phar is kind of like a thumb drive for PHP applications.

Phar implements this functionality through a Stream Wrapper. Normally, to use an external file within a PHP script, you would use include:

Beispiel #1 Using an external file

    <?php
     include '/path/to/external/file.php';
     ?>

PHP can be thought of as actually translating `/path/to/external/file.php` into a stream wrapper as `file:///path/to/external/file.php`, and under the hood it does in fact use the plain file stream wrapper stream functions to access all local files.

To use a file named `file.php` contained with a phar archive `/path/to/myphar.phar`, the syntax is very similar to the `file://` syntax above.

Beispiel #2 Using a file within a phar archive

    <?php
     include 'phar:///path/to/myphar.phar/file.php';
     ?>

In fact, one can treat a phar archive exactly as if it were an external disk, using any of fopen()-related functions, opendir() and mkdir()-related functions to read, change, or create new files and directories within the phar archive. This allows complete PHP applications to be distributed in a single file and run directly from that file.

The most common usage for a phar archive is to distribute a complete application in a single file. For instance, the PEAR Installer that is bundled with PHP versions is distributed as a phar archive. To use a phar archive distributed in this way, the archive can be executed on the command-line or via a web server.

Phar archives can be distributed as `tar` archives, `zip` archives, or as the custom `phar` file format designed specifically for the phar extension. Each file format has advantages and disadvantages. The tar and zip file formats can be read or extracted by any third-party tool that can read the format, but require the phar extension in order to run with PHP. The phar file format is customized and unique to the phar extension, and can only be created by the phar extension or the PEAR package » PHP_Archive, but has the advantage that applications created in this format will run even if the phar extension is not enabled.

In other words, even with the phar extension disabled, one can execute or include a phar-based archive. Accessing individual files within a phar archive is only possible with the phar extension unless the phar archive was created by PHP_Archive.

The phar extension is also capable of converting a phar archive from tar to zip or to phar file format in a single command:

Beispiel #3 Converting a phar archive from phar to tar file format

    <?php
     $phar = new Phar('myphar.phar');
     $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // makes myphar.phar.tar.gz
     ?>

Phar can compress individual files or an entire archive using gzip compression or bzip2 compression, and can verify archive integrity automatically through the use of MD5, SHA-1, SHA-256 or SHA-512 signatures.

Lastly, the Phar extension is security-conscious, and disables write access to executable phar archives by default, and requires system-level disabling of the `phar.readonly` php.ini setting in order to create or modify phar archives. Normal tar and zip archives without an executable stub can always be created or modified using the PharData class.

If you are creating applications for distribution, you will want to read How to create Phar Archives. If you want more information on the differences between the three file formats that phar supports, you should read Phar, Tar and Zip.

If you are using phar applications, there are helpful tips in How to use Phar Archives.

The word `phar` is a portmanteau of `PHP` and `Archive` and is based loosely on the `jar` (Java Archive) familiar to Java developers.

The implementation for Phar archives is based on the PEAR package » PHP_Archive, and the implementation details are similar, although the Phar extension is much more powerful. In addition, the Phar extension allows most PHP applications to be run unmodified while PHP_Archive-based phar archives often require extensive modification in order to work.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

You may optionally wish to enable the zlib and bzip2 extensions to take advantage of compressed phar support. In addition, to take advantage of OpenSSL signing, the OpenSSL extension must be enabled.

If zend.multibyte is enabled, zend.detect_unicode must be enabled as well.

## Installation

The Phar extension is bundled with PHP, and enabled by default. To disable Phar support, use --disable-phar.

Phar may be installed via the PECL extension with previous PHP versions, and the » Phar PECL page contains further information and history.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Filesystem and Streams Configuration Options
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
phar.readonly | "1" | `INI_ALL` |
phar.require_hash | "1" | `INI_ALL` |
phar.cache_list | "" | `INI_SYSTEM` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`phar.readonly` bool

  This option disables creation or modification of Phar archives using the `phar` stream or Phar object's write support. This setting should always be enabled on production machines, as the phar extension's convenient write support could allow straightforward creation of a php-based virus when coupled with other common security vulnerabilities.

  > Hinweis:

  > This setting can only be unset in php.ini due to security reasons. If `phar.readonly` is disabled in php.ini, the user may enable `phar.readonly` in a script or disable it later. If `phar.readonly` is enabled in php.ini, a script may harmlessly "re-enable" the INI variable, but may not disable it.

`phar.require_hash` bool

  This option will force all opened Phar archives to contain some kind of signature (currently MD5, SHA1, SHA256, SHA512 and OpenSSL are supported), and will refuse to process any Phar archive that does not contain a signature.

  > Hinweis:

  > This setting can only be unset in php.ini. If `phar.require_hash` is disabled in php.ini, the user may enable `phar.require_hash` in a script or disable it later. If `phar.require_hash` is enabled in php.ini, a script may harmlessly "re-enable" the INI variable, but may not disable it.

  > This setting does not affect reading plain tar files with the PharData class.

  Achtung

  `phar.require_hash` does not provide any security per se, it is merely a measure against running accidentally corrupted Phar archives, because anyone who would be able to tamper with the Phar could easily fix the signature afterwards.

`phar.cache_list` string

  Allows mapping phar archives to be pre-parsed at web server startup, providing a performance improvement that brings running files out of a phar archive very close to the speed of running those files from a traditional disk-based installation.

  Beispiel #1 phar.cache_list usage example

      in php.ini (windows):
      phar.cache_list =C:\path\to\phar1.phar;C:\path\to\phar2.phar
      in php.ini (unix):
      phar.cache_list =/path/to/phar1.phar:/path/to/phar2.phar

## Ressource-Typen

The Phar extension provides the `phar` stream, which allows accessing files contained within a phar transparently. See also the description of the Phar file format.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

Phar compression constants
Constant | Value | Description
--- | --- | ---
`Phar::NONE` (int) | 0x00000000 | no compression
`Phar::COMPRESSED` (int) | 0x0000F000 | bitmask that can be used with file flags to determine if any compression is present
`Phar::GZ` (int) | 0x00001000 | zlib (gzip) compression
`Phar::BZ2` (int) | 0x00002000 | bzip2 compression

Phar file format constants
Constant | Value | Description
--- | --- | ---
`Phar::PHAR` (int) | 1 | phar file format
`Phar::TAR` (int) | 2 | tar file format
`Phar::ZIP` (int) | 3 | zip file format

Phar signature constants
Constant | Value | Description
--- | --- | ---
`Phar::MD5` (int) | 0x0001 | signature with md5 hash algorithm
`Phar::SHA1` (int) | 0x0002 | signature with sha1 hash algorithm
`Phar::SHA256` (int) | 0x0003 | signature with sha256 hash algorithm (requires hash extension)
`Phar::SHA512` (int) | 0x0004 | signature with sha512 hash algorithm (requires hash extension)
`Phar::OPENSSL` (int) | 0x0010 | signature with OpenSSL public/private key pair. This is a true, asymmetric key signature.
`Phar::OPENSSL_SHA256` (int) |  |
`Phar::OPENSSL_SHA512` (int) |  |

Phar webPhar mime override constants
Constant | Value | Description
--- | --- | ---
`Phar::PHP` (int) | 0 | used to instruct the mimeoverrides parameter of Phar::webPhar() that the extension should be parsed as a PHP file
`Phar::PHPS` (int) | 1 | used to instruct the mimeoverrides parameter of Phar::webPhar() that the extension should be parsed as a PHP source file through highlight_file()

# Using Phar Archives

## Inhaltsverzeichnis

- Using Phar Archives: Introduction
- Using Phar Archives: the phar stream wrapper
- Using Phar Archives: the Phar and PharData class

## Using Phar Archives: Introduction

Phar archives are similar in concept to Java JAR archives, but are tailored to the needs and to the flexibility of PHP applications. A Phar archive is used to distribute a complete PHP application or library in a single file. A Phar archive application is used exactly like any other PHP application:

    php coolapplication.phar

Using a Phar archive library is identical to using any other PHP library:

    <?php
    include 'coollibrary.phar';
    ?>

The `phar` stream wrapper provides the core of the phar extension, and is explained in detail here. The phar stream wrapper allows accessing the files within a phar archive using PHP's standard file functions fopen(), opendir(), and others that work on regular files. The `phar` stream wrapper supports all read/write operations on both files and directories.

    <?php
    include 'phar://coollibrary.phar/internal/file.php';
    header('Content-type: image/jpeg');
    // phars can be accessed by full path or by alias
    echo file_get_contents('phar:///fullpath/to/coollibrary.phar/images/wow.jpg');
    ?>

The Phar class implements advanced functionality for accessing files and for creating phar archives. The Phar class is explained in detail here.

    <?php
    try {
        // open an existing phar
        $p = new Phar('coollibrary.phar', 0);
        // Phar extends SPL's DirectoryIterator class
        foreach (new RecursiveIteratorIterator($p) as $file) {
            // $file is a PharFileInfo class, and inherits from SplFileInfo
            echo $file->getFileName() . "\n";
            echo file_get_contents($file->getPathName()) . "\n"; // display contents;
        }
        if (isset($p['internal/file.php'])) {
            var_dump($p['internal/file.php']->getMetadata());
        }

        // create a new phar - phar.readonly must be 0 in php.ini
        // phar.readonly is enabled by default for security reasons.
        // On production servers, Phars need never be created,
        // only executed.
        if (Phar::canWrite()) {
            $p = new Phar('newphar.tar.phar', 0, 'newphar.tar.phar');
            // make this a tar-based phar archive, compressed with gzip compression (.tar.gz)
            $p = $p->convertToExecutable(Phar::TAR, Phar::GZ);

            // create transaction - nothing is written to newphar.phar
            // until stopBuffering() is called, although temporary storage is needed
            $p->startBuffering();
            // add all files in /path/to/project, saving in the phar with the prefix "project"
            $p->buildFromIterator(new RecursiveIteratorIterator(new RecursiveDirectoryIterator('/path/to/project')), '/path/to/');

            // add a new file via the array access API
            $p['file1.txt'] = 'Information';
            $fp = fopen('hugefile.dat', 'rb');
            // copy all data from the stream
            $p['data/hugefile.dat'] = $fp;

            if (Phar::canCompress(Phar::GZ)) {
                $p['data/hugefile.dat']->compress(Phar::GZ);
            }

            $p['images/wow.jpg'] = file_get_contents('images/wow.jpg');
            // any value can be saved as file-specific meta-data
            $p['images/wow.jpg']->setMetadata(array('mime-type' => 'image/jpeg'));
            $p['index.php'] = file_get_contents('index.php');
            $p->setMetadata(array('bootstrap' => 'index.php'));

            // save the phar archive to disk
            $p->stopBuffering();
        }
    } catch (Exception $e) {
        echo 'Could not open Phar: ', $e;
    }
    ?>

In addition, verification of phar file contents can be done using any of the supported symmetric hash algorithms (MD5, SHA1, SHA256 and SHA512 if ext/hash is enabled) and using asymmetric public/private key signing using OpenSSL. To take advantage of OpenSSL signing, you need to generate a public/private key pair, and use the private key to set the signature using Phar::setSignatureAlgorithm(). In addition, the public key as extracted using this code:

    <?php
    $public = openssl_get_publickey(file_get_contents('private.pem'));
    $pkey = '';
    openssl_pkey_export($public, $pkey);
    ?>

must be saved adjacent to the phar archive it verifies. If the phar archive is saved as `/path/to/my.phar`, the public key must be saved as `/path/to/my.phar.pubkey`, or phar will be unable to verify the OpenSSL signature.

The Phar class also provides 3 static methods, Phar::webPhar(), Phar::mungServer() and Phar::interceptFileFuncs() that are crucial to packaging up PHP applications designed for usage on regular filesystems and for web-based applications. Phar::webPhar() implements a front controller that routes HTTP calls to the correct location within the phar archive. Phar::mungServer() is used to modify the values of the $_SERVER array to trick applications that process these values. Phar::interceptFileFuncs() instructs Phar to intercept calls to fopen(), file_get_contents(), opendir(), and all of the stat-based functions (file_exists(), is_readable() and so on) and route all relative paths to locations within the phar archive.

As an example, packaging up a release of the popular phpMyAdmin application for use as a phar archive requires only this simple script and then `phpMyAdmin.phar.tar.php` can be accessed as a regular file from your web server after modifying the user/password:

    <?php
    @unlink('phpMyAdmin.phar.tar.php');
    copy('phpMyAdmin-2.11.3-english.tar.gz', 'phpMyAdmin.phar.tar.php');
    $a = new Phar('phpMyAdmin.phar.tar.php');
    $a->startBuffering();
    $a["phpMyAdmin-2.11.3-english/config.inc.php"] = '<?php
    /* Servers configuration */
    $i = 0;

    /* Server localhost (config:root) [1] */
    $i++;
    $cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
    $cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
    $cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
    $cfg[\'Servers\'][$i][\'compress\'] = false;
    $cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
    $cfg[\'Servers\'][$i][\'user\'] = \'root\';
    $cfg[\'Servers\'][$i][\'password\'] = \'\';

    /* End of servers configuration */
    if (strpos(PHP_OS, \'WIN\') !== false) {
        $cfg[\'UploadDir\'] = getcwd();
    } else {
        $cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
        @mkdir(\'/tmp/pharphpmyadmin\');
        @chmod(\'/tmp/pharphpmyadmin\', 0777);
    }';
    $a->setStub('<?php
    Phar::interceptFileFuncs();
    Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
    echo "phpMyAdmin is intended to be executed from a web browser\n";
    exit -1;
    __HALT_COMPILER();
    ');
    $a->stopBuffering();
    ?>

## Using Phar Archives: the phar stream wrapper

The Phar stream wrapper fully supports fopen() for read and write (not append), unlink(), stat(), fstat(), fseek(), rename() and directory stream operations opendir() and rmdir() and mkdir().

Individual file compression and per-file metadata can also be manipulated in a Phar archive using stream contexts:

    <?php
    $context = stream_context_create(array('phar' =>
                                        array('compress' => Phar::GZ)),
                                        array('metadata' => array('user' => 'cellog')));
    file_put_contents('phar://my.phar/somefile.php', 0, $context);
    ?>

The `phar` stream wrapper does not operate on remote files, and cannot operate on remote files, and so is allowed even when the allow_url_fopen and allow_url_include INI options are disabled.

Although it is possible to create phar archives from scratch just using stream operations, it is best to use the functionality built into the Phar class. The stream wrapper is best used for read-only operations.

## Using Phar Archives: the Phar and PharData class

The Phar class supports reading and manipulation of Phar archives, as well as iteration through inherited functionality of the RecursiveDirectoryIterator class. With support for the ArrayAccess interface, files inside a Phar archive can be accessed as if they were part of an associative array.

The PharData class extends the Phar, and allows creating and modifying non-executable (data) tar and zip archives even if `phar.readonly`=1 in php.ini. As such, PharData::setAlias() and PharData::setStub() are both disabled as the concept of alias and stub are unique to executable phar archives.

It is important to note that when creating a Phar archive, the full path should be passed to the Phar object constructor. Relative paths will fail to initialize.

Assuming that `$p` is a Phar object initialized as follows:

    <?php
    $p = new Phar('/path/to/myphar.phar', 0, 'myphar.phar');
    ?>

An empty Phar archive will be created at `/path/to/myphar.phar`, or if `/path/to/myphar.phar` already exists, it will be opened again. The literal `myphar.phar` demonstrates the concept of an alias that can be used to reference `/path/to/myphar.phar` in URLs as in:

    <?php
    // these two calls to file_get_contents() are equivalent if
    // /path/to/myphar.phar has an explicit alias of "myphar.phar"
    // in its manifest, or if the phar was initialized with the
    // previous example's Phar object setup
    $f = file_get_contents('phar:///path/to/myphar.phar/whatever.txt');
    $f = file_get_contents('phar://myphar.phar/whatever.txt');
    ?>

With the newly created `$p` Phar object, the following is possible:

- `$a = $p['file.php']` creates a PharFileInfo class that refers to the contents of `phar://myphar.phar/file.php`
- `$p['file.php'] = $v` creates a new file (`phar://myphar.phar/file.php`), or overwrites an existing file within `myphar.phar`. `$v` can be either a string or an open file pointer, in which case the entire contents of the file will be used to create the new file. Note that `$p->addFromString('file.php', $v)` is functionally equivalent to the above. Also possible is to add the contents of a file with `$p->addFile('/path/to/file.php', 'file.php')`. Lastly, an empty directory can be created with `$p->addEmptyDir('empty')`.
- `isset($p['file.php'])` can be used to determine whether `phar://myphar.phar/file.php` exists within `myphar.phar`.
- `unset($p['file.php'])` erases `phar://myphar.phar/file.php` from `myphar.phar`.

In addition, the Phar object is the only way to access Phar-specific metadata, through Phar::getMetadata(), and the only way to set or retrieve a Phar archive's PHP loader stub through Phar::getStub() and Phar::setStub(). Additionally, compression for the entire Phar archive at once can only be manipulated using the Phar class.

The full list of Phar object functionality is documented below.

The PharFileInfo class extends the SplFileInfo class, and adds several methods for manipulating Phar-specific details of a file contained within a Phar, such as manipulating compression and metadata.

# Creating Phar Archives

## Inhaltsverzeichnis

- Creating Phar Archives: Introduction

## Creating Phar Archives: Introduction

To be written fully in the near future. Before reading this, be sure to read How to use Phar Archives.

A great place to start is by reading about Phar::buildFromIterator(), and the specifics of the file format choices available for archives. A healthy understanding of what a stub is and does is crucial to phar archive creation, and so Phar::setStub() and Phar::createDefaultStub() are good places to start as well. If you are distributing a web-based application, it is crucial to know about Phar::webPhar() and related method Phar::mungServer(). Any application that accesses its own files should also consider using Phar::interceptFileFuncs().

# What makes a phar a phar and not a tar or a zip?

## Inhaltsverzeichnis

- Ingredients of all Phar archives, independent of file format
- Phar file stub
- Head-to-head comparison of Phar, Tar and Zip
- Tar-based phars
- Zip-based phars
- Phar File Format
- Global Phar bitmapped flags
- Phar manifest file entry definition
- Phar Signature format

## Ingredients of all Phar archives, independent of file format

All Phar archives contain three to four sections:

1. a stub

2. a manifest describing the contents

3. the file contents

4. [optional] a signature for verifying Phar integrity (phar file format only)

## Phar file stub

A Phar's stub is a simple PHP file. The smallest possible stub follows:

    <?php __HALT_COMPILER();

A stub must contain as a minimum, the `__HALT_COMPILER();` token at its conclusion. Typically, a stub will contain loader functionality like so:

    <?php
    Phar::mapPhar();
    include 'phar://myphar.phar/index.php';
    __HALT_COMPILER();

There are no restrictions on the contents of a Phar stub, except for the requirement that it conclude with `__HALT_COMPILER();`. The closing PHP tag ``

    ?>

may be included or omitted, but there can be no more than 1 space between the `;` and the close tag `

    ?>

` or the phar extension will be unable to process the Phar archive's manifest.

In a tar or zip-based phar archive, the stub is stored in the `.phar/stub.php` file. The default stub for phar-based Phar archives contains approximately 7k of code to extract the contents of the phar and execute them. See Phar::createDefaultStub() for more detail.

The phar alias is stored in a tar or zip-based phar archive in the `.phar/alias.txt` file as plain text.

## Head-to-head comparison of Phar, Tar and Zip

What are the good and the bad things about the three supported file formats in the phar extension? This table attempts to address that question.

Feature matrix: Phar vs. Tar vs. Zip
Feature | Phar | Tar | Zip
--- | --- | --- | ---
Standard File Format | No | Yes | Yes
Can be executed without the Phar Extension [1] | Yes | No | No
Per-file compression | Yes | No | Yes
Whole-archive compression | Yes | Yes | No
Whole-archive signature validation | Yes | Yes | Yes
Web-specific application support | Yes | Yes | Yes
Per-file Meta-data | Yes | Yes | Yes
Whole-Archive Meta-data | Yes | Yes | Yes
Archive creation/modification [2] | Yes | Yes | Yes
Full support for all stream wrapper functions | Yes | Yes | Yes
Can be created/modified even if phar.readonly=1 [3] | No | Yes | Yes

Tipp

[1] PHP can only directly access the contents of a Phar archive without the Phar extension if it is using a `stub` that extracts the contents of the phar archive. The stub created by Phar::createDefaultStub() extracts the phar archive and runs its contents from a temporary directory if no phar extension is found.

Tipp

[2] All write access requires `phar.readonly` to be disabled in php.ini or on the command-line directly.

Tipp

[3] Only tar and zip archives without `.phar` in their filename and without an executable stub `.phar/stub.php` can be created if phar.readonly=1.

## Tar-based phars

Archives based on the tar file format follow the more modern USTAR file format. The design of the tar file header makes them more efficient to access than the zip file format, and almost as efficient as the phar file format. File names are limited to 255 bytes, including full path within the phar archive. There is no limit on the number of files within a tar-based phar archive. These archives can fully compressed in gzip or bzip2 format and still be executed by the Phar extension.

There is limited support for reading tarballs in pax interchange format, but all recognized pax headers (currently, typeflag `x` and `g`) are silently ignored. There is also limited support for GNU Tar Archives; currently, `././@LongLink` headers are resolved.

To compress an entire archive, use Phar::compress(). To decompress an entire archive, use Phar::decompress().

## Zip-based phars

Archives based on the zip file format support several features built into the zip file format. Per-file and whole-archive metadata is stored in the zip file comment and zip archive comment as a serialized string. Pre-existing zip comments will be successfully read as a string. Per-file compression read/write is supported with zlib DEFLATE compression, and read access is supported with bzip2 compression. There is no limit on the number of files within a zip-based phar archive. Empty directories are stored in the zip archive as files with a trailing slash like `my/directory/`

## Phar File Format

The phar file format is literally laid out as stub/manifest/contents/signature, and stores the crucial information of what is included in the phar archive in its `manifest`.

The Phar manifest is a highly optimized format that allows per-file specification of file compression, file permissions, and even user-defined meta-data such as file user or group. All values greater than 1 byte are stored in little-endian byte order, with the exception of the API version, which for historical reasons is stored as 3 nibbles in big-endian order.

All unused flags are reserved for future use, and must not be used to store custom information. Use the per-file meta-data facility to store customized information about particular files.

The basic file format of a Phar archive manifest is as follows:

Global Phar manifest format
Size in bytes | Description
--- | ---
4 bytes | Length of manifest in bytes (1 MB limit)
4 bytes | Number of files in the Phar
2 bytes | API version of the Phar manifest (currently 1.0.0)
4 bytes | Global Phar bitmapped flags
4 bytes | Length of Phar alias
?? | Phar alias (length based on previous)
4 bytes | Length of Phar metadata (`0` for none)
?? | Serialized Phar Meta-data, stored in serialize() format
at least 24 * number of entries bytes | entries for each file

## Global Phar bitmapped flags

Here are the bitmapped flags currently recognized by the Phar extension for the global Phar flat bitmap:

Bitmap values recognized
Value | Description
--- | ---
`0x00010000` | If set, this Phar contains a verification signature
`0x00001000` | If set, this Phar contains at least 1 file that is compressed with zlib DEFLATE compression
`0x00002000` | If set, this Phar contains at least 1 file that is compressed with bzip2 compression

## Phar manifest file entry definition

Each file in the manifest contains the following information:

Phar Manifest file entry
Size in bytes | Description
--- | ---
4 bytes | Filename length in bytes
?? | Filename (length specified in previous)
4 bytes | Un-compressed file size in bytes
4 bytes | Unix timestamp of file
4 bytes | Compressed file size in bytes
4 bytes | CRC32 checksum of un-compressed file contents
4 bytes | Bit-mapped File-specific flags
4 bytes | Serialized File Meta-data length (`0` for none)
?? | Serialized File Meta-data, stored in serialize() format

Note that as of API version 1.1.1, empty directories are stored as filenames with a trailing slash like `my/directory/`

The File-specific bitmap values recognized are:

Bitmap values recognized
Value | Description
--- | ---
`0x000001FF` | These bits are reserved for defining specific file permissions of a file. Permissions are used for fstat() and can be used to recreate desired permissions upon extraction.
`0x00001000` | If set, this file is compressed with zlib DEFLATE compression
`0x00002000` | If set, this file is compressed with bzip2 compression

## Phar Signature format

Phars containing a signature always have the signature appended to the end of the Phar archive after the loader, manifest, and file contents. The signature formats supported at this time are MD5, SHA1, SHA256, SHA512, and OPENSSL.

Signature format
Length in bytes | Description
--- | ---
varying | The actual signature, 20 bytes for an SHA1 signature, 16 bytes for an MD5 signature, 32 bytes for an SHA256 signature, and 64 bytes for an SHA512 signature. The length of an OPENSSL signature depends on the size of the private key.
4 bytes | Signature flags. `0x0001` is used to define an MD5 signature, `0x0002` is used to define an SHA1 signature, `0x0003` is used to define an SHA256 signature, and `0x0004` is used to define an SHA512 signature. The SHA256 and SHA512 signature support is available as of API version 1.1.0. `0x0010` is used to define an OPENSSL signature, what is available as of API version 1.1.1, if OpenSSL is available.
4 bytes | Magic `GBMB` used to define the presence of a signature.

# Die Klasse Phar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Einführung

Die Klasse Phar bietet ein High-Level-Interface zum Zugreifen auf und Erstellen von Phar-Archiven.

## Klassenbeschreibung

class Phar extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Geerbte Konstanten */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Konstanten */
const int BZ2;
const int GZ;
const int NONE;
const int PHAR;
const int TAR;
const int ZIP;
const int COMPRESSED;
const int PHP;
const int PHPS;
const int MD5;
const int OPENSSL;
const int OPENSSL_SHA256;
const int OPENSSL_SHA512;
const int SHA1;
const int SHA256;
const int SHA512;
/* Methoden */
public function __construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
final public static function apiVersion(): string
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
final public static function canCompress(int `$compression` = 0): bool
final public static function canWrite(): bool
public function compress(int `$compression`, ?string `$extension` = `null`): ?Phar
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function count(int `$mode` = `COUNT_NORMAL`): int
final public static function createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string
public function decompress(?string `$extension` = `null`): ?Phar
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function getAlias(): ?string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getModified(): bool
public function getPath(): string
public function getSignature(): array|false
public function getStub(): string
final public static function getSupportedCompression(): array
final public static function getSupportedSignatures(): array
public function getVersion(): string
public function hasMetadata(): bool
final public static function interceptFileFuncs(): void
public function isBuffering(): bool
public function isCompressed(): int|false
public function isFileFormat(int `$format`): bool
final public static function isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool
public function isWritable(): bool
final public static function loadPhar(string `$filename`, ?string `$alias` = `null`): bool
final public static function mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool
final public static function mount(string `$pharPath`, string `$externalPath`): void
final public static function mungServer(array `$variables`): void
public function offsetExists(string `$localName`): bool
public function offsetGet(string `$localName`): SplFileInfo
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
final public static function running(bool `$returnPhar` = `true`): string
public function setAlias(string `$alias`): true
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function startBuffering(): void
public function stopBuffering(): void
final public static function unlinkArchive(string `$filename`): true
final public static function webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void
public function __destruct()
/* Geerbte Methoden */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Unterstützung für die Unix-Zeitstempel-Erweiterung für Zip-basierte Archive hinzugefügt.

# Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addEmptyDir — Add an empty directory to the phar archive

### Beschreibung

public function Phar::addEmptyDir(string `$directory`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

With this method, an empty directory is created with path `dirname`. This method is similar to ZipArchive::addEmptyDir().

### Parameter-Liste

`directory`

  The name of the empty directory to create in the phar archive

### Rückgabewerte

no return value, exception is thrown on failure.

### Beispiele

Beispiel #1 A Phar::addEmptyDir() example

    <?php
    try {
        $a = new Phar('/path/to/phar.phar');

        $a->addEmptyDir('/full/path/to/file');
        // demonstrates how this file is stored
        $b = $a['full/path/to/file']->isDir();
    } catch (Exception $e) {
        // handle errors here
    }
    ?>

### Siehe auch

- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive
- Phar::addFile() - Add a file from the filesystem to the phar archive
- Phar::addFromString() - Add a file from a string to the phar archive

# Phar::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFile — Add a file from the filesystem to the phar archive

### Beschreibung

public function Phar::addFile(string `$filename`, ?string `$localName` = `null`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

With this method, any file or URL can be added to the phar archive. If the optional second parameter `localName` is a String, the file will be stored in the archive with that name, otherwise the `file` parameter is used as the path to store within the archive. URLs must have a localname or an exception is thrown. This method is similar to ZipArchive::addFile().

### Parameter-Liste

`filename`

  Full or relative path to a file on disk to be added to the phar archive.

`localName`

  Path that the file will be stored in the archive.

### Rückgabewerte

no return value, exception is thrown on failure.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `localName` is now nullable.

### Beispiele

Beispiel #1 A Phar::addFile() example

    <?php
    try {
        $a = new Phar('/path/to/phar.phar');

        $a->addFile('/full/path/to/file');
        // demonstrates how this file is stored
        $b = $a['full/path/to/file']->getContent();

        $a->addFile('/full/path/to/file', 'my/file.txt');
        $c = $a['my/file.txt']->getContent();

        // demonstrate URL usage
        $a->addFile('http://www.example.com', 'example.html');
    } catch (Exception $e) {
        // handle errors here
    }
    ?>

### Anmerkungen

> Hinweis: Die Funktionen Phar::addFile(), Phar::addFromString() und Phar::offsetSet() speichern bei jedem Aufruf ein neues phar-Archiv. Wenn die Leistung ein wichtiger Faktor ist, sollte stattdessen Phar::buildFromDirectory() oder Phar::buildFromIterator() verwendet werden.

### Siehe auch

- Phar::offsetSet() - Set the contents of an internal file to those of an external file
- PharData::addFile() - Add a file from the filesystem to the tar/zip archive
- Phar::addFromString() - Add a file from a string to the phar archive
- Phar::addEmptyDir() - Add an empty directory to the phar archive

# Phar::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFromString — Add a file from a string to the phar archive

### Beschreibung

public function Phar::addFromString(string `$localName`, string `$contents`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

With this method, any string can be added to the phar archive. The file will be stored in the archive with `localname` as its path. This method is similar to ZipArchive::addFromString().

### Parameter-Liste

`localName`

  Path that the file will be stored in the archive.

`contents`

  The file contents to store

### Rückgabewerte

no return value, exception is thrown on failure.

### Beispiele

Beispiel #1 A Phar::addFromString() example

    <?php
    try {
        $a = new Phar('/path/to/phar.phar');

        $a->addFromString('path/to/file.txt', 'my simple file');
        $b = $a['path/to/file.txt']->getContent();

        // to add contents from a stream handle for large files, use offsetSet()
        $c = fopen('/path/to/hugefile.bin');
        $a['largefile.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // handle errors here
    }
    ?>

### Anmerkungen

> Hinweis: Die Funktionen Phar::addFile(), Phar::addFromString() und Phar::offsetSet() speichern bei jedem Aufruf ein neues phar-Archiv. Wenn die Leistung ein wichtiger Faktor ist, sollte stattdessen Phar::buildFromDirectory() oder Phar::buildFromIterator() verwendet werden.

### Siehe auch

- Phar::offsetSet() - Set the contents of an internal file to those of an external file
- PharData::addFromString() - Add a file from a string to the tar/zip archive
- Phar::addFile() - Add a file from the filesystem to the phar archive
- Phar::addEmptyDir() - Add an empty directory to the phar archive

# Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::apiVersion — Returns the api version

### Beschreibung

final public static function Phar::apiVersion(): string

Return the API version of the phar file format that will be used when creating phars. The Phar extension supports reading API version 1.0.0 or newer. API version 1.1.0 is required for SHA-256 and SHA-512 hash, and API version 1.1.1 is required to store empty directories.

### Parameter-Liste

### Rückgabewerte

The API version string as in `"1.0.0"`.

### Beispiele

Beispiel #1 A Phar::apiVersion() example

    <?php
    echo Phar::apiVersion();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1.1.1

# Phar::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromDirectory — Construct a phar archive from the files within a directory

### Beschreibung

public function Phar::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Populate a phar archive from directory contents. The optional second parameter is a regular expression (pcre) that is used to exclude files. Any filename that matches the regular expression will be included, all others will be excluded. For more fine-grained control, use Phar::buildFromIterator().

### Parameter-Liste

`directory`

  The full or relative path to the directory that contains all files to add to the archive.

`pattern`

  An optional pcre regular expression that is used to filter the list of files. Only file paths matching the regular expression will be included in the archive.

### Rückgabewerte

Phar::buildFromDirectory() returns an associative array mapping internal path of file to the full path of the file on the filesystem.

### Fehler/Exceptions

This method throws BadMethodCallException when unable to instantiate the internal directory iterators, or a PharException if there were errors saving the phar archive.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Phar::buildFromDirectory() no longer returns `false`.

### Beispiele

Beispiel #1 A Phar::buildFromDirectory() example

    <?php
    // create with alias "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    // add all files in the project
    $phar->buildFromDirectory(dirname(__FILE__) . '/project');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));

    $phar2 = new Phar('project2.phar', 0, 'project2.phar');
    // add all files in the project, only include php files
    $phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
    $phar2->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

### Siehe auch

- Phar::buildFromIterator() - Construct a phar archive from an iterator

# Phar::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromIterator — Construct a phar archive from an iterator

### Beschreibung

public function Phar::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Populate a phar archive from an iterator. Two styles of iterators are supported, iterators that map the filename within the phar to the name of a file on disk, and iterators like DirectoryIterator that return SplFileInfo objects. For iterators that return SplFileInfo objects, the second parameter is required.

### Parameter-Liste

`iterator`

  Any iterator that either associatively maps phar file to location or returns SplFileInfo objects

`baseDirectory`

  For iterators that return SplFileInfo objects, the portion of each file's full path to remove when adding to the phar archive

### Rückgabewerte

Phar::buildFromIterator() returns an associative array mapping internal path of file to the full path of the file on the filesystem.

### Fehler/Exceptions

This method returns UnexpectedValueException when the iterator returns incorrect values, such as an integer key instead of a string, a BadMethodCallException when an SplFileInfo-based iterator is passed without a `baseDirectory` parameter, or a PharException if there were errors saving the phar archive.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Phar::buildFromIterator() no longer returns `false`.
8.0.0 | `baseDirectory` is now nullable.

### Beispiele

Beispiel #1 A Phar::buildFromIterator() with SplFileInfo

For most phar archives, the archive will reflect an actual directory layout, and the second style is the most useful. For instance, to create a phar archive containing the files in this sample directory layout:

    /path/to/project/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         file1.php
                         file2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

This code could be used to add these files to the "project.phar" phar archive:

    <?php
    // create with alias "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/path/to/project')),
        '/path/to/project');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

The file project.phar can then be used immediately. Phar::buildFromIterator() does not set values such as compression, metadata, and this can be done after creating the phar archive.

As an interesting note, Phar::buildFromIterator() can also be used to copy the contents of an existing phar archive, as the Phar object descends from DirectoryIterator:

    <?php
    // create with alias "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/path/to/anotherphar.phar')),
        'phar:///path/to/anotherphar.phar/path/to/project');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

Beispiel #2 A Phar::buildFromIterator() with other iterators

The second form of the iterator can be used with any iterator that returns a key => value mapping, such as an ArrayIterator:

    <?php
    // create with alias "project.phar"
    $phar = new Phar('project.phar', 0, 'project.phar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'internal/file.php' => dirname(__FILE__) . '/somefile.php',
            'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
         )));
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

### Siehe auch

- Phar::buildFromDirectory() - Construct a phar archive from the files within a directory

# Phar::canCompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canCompress — Returns whether phar extension supports compression using either zlib or bzip2

### Beschreibung

final public static function Phar::canCompress(int `$compression` = 0): bool

This should be used to test whether compression is possible prior to loading a phar archive containing compressed files.

### Parameter-Liste

`compression`

  Either `Phar::GZ` or `Phar::BZ2` can be used to test whether compression is possible with a specific compression algorithm (zlib or bzip2).

### Rückgabewerte

`true` if compression/decompression is available, `false` if not.

### Beispiele

Beispiel #1 A Phar::canCompress() example

    <?php
    if (Phar::canCompress()) {
        echo file_get_contents('phar://compressedphar.phar/internal/file.txt');
    } else {
        echo 'no compression available';
    }
    ?>

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file

# Phar::canWrite

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canWrite — Returns whether phar extension supports writing and creating phars

### Beschreibung

final public static function Phar::canWrite(): bool

This static method determines whether write access has been disabled in the system php.ini via the phar.readonly ini variable.

### Parameter-Liste

### Rückgabewerte

`true` if write access is enabled, `false` if it is disabled.

### Beispiele

Beispiel #1 A Phar::canWrite() example

    <?php
    if (Phar::canWrite()) {
        file_put_contents('phar://myphar.phar/file.txt', 'hi there');
    }
    ?>

### Siehe auch

- phar.readonly
- Phar::isWritable() - Returns true if the phar archive can be modified

# Phar::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compress — Compresses the entire Phar archive using Gzip or Bzip2 compression

### Beschreibung

public function Phar::compress(int `$compression`, ?string `$extension` = `null`): ?Phar

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

For tar-based and phar-based phar archives, this method compresses the entire archive using gzip compression or bzip2 compression. The resulting file can be processed with the gunzip command/bunzip command, or accessed directly and transparently with the Phar extension.

For Zip-based phar archives, this method fails with an exception. The zlib extension must be enabled to compress with gzip compression, the bzip2 extension must be enabled in order to compress with bzip2 compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.

In addition, this method automatically renames the archive, appending `.gz`, `.bz2` or removing the extension if passed `Phar::NONE` to remove compression. Alternatively, a file extension may be specified with the second parameter.

### Parameter-Liste

`compression`

  Compression must be one of `Phar::GZ`, `Phar::BZ2` to add compression, or `Phar::NONE` to remove compression.

`extension`

  By default, the extension is `.phar.gz` or `.phar.bz2` for compressing phar archives, and `.phar.tar.gz` or `.phar.tar.bz2` for compressing tar archives. For decompressing, the default file extensions are `.phar` and `.phar.tar`.

### Rückgabewerte

Returns a Phar object, or `null` on failure.

### Fehler/Exceptions

Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or the bzip2 extension is not enabled.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `extension` is now nullable.

### Beispiele

Beispiel #1 A Phar::compress() example

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    $p1 = $p->compress(Phar::GZ); // copies to /path/to/my.phar.gz
    $p2 = $p->compress(Phar::BZ2); // copies to /path/to/my.phar.bz2
    $p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists
    ?>

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive

# Phar::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compressFiles — Compresses all files in the current Phar archive

### Beschreibung

public function Phar::compressFiles(int `$compression`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

For tar-based phar archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use Phar::compress() to compress an entire tar-based phar archive.

For Zip-based and phar-based phar archives, this method compresses all files in the Phar archive using the specified compression. The zlib or bzip2 extensions must be enabled to take advantage of this feature. In addition, if any files are already compressed using bzip2/zlib compression, the respective extension must be enabled in order to decompress the files prior to re-compressing. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.

### Parameter-Liste

`compression`

  Compression must be one of `Phar::GZ`, `Phar::BZ2` to add compression, or `Phar::NONE` to remove compression.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.

### Beispiele

Beispiel #1 A Phar::compressFiles() example

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(10) "myfile.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "myfile2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(10) "myfile.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "myfile2.txt"
    int(4096)
    bool(false)
    bool(true)

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive

# Phar::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__construct — Construct a Phar archive object

### Beschreibung

public function Phar::__construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)

### Parameter-Liste

`filename`

  Path to an existing Phar archive or to-be-created archive. The file name's extension must contain .phar.

`flags`

  Flags to pass to parent class RecursiveDirectoryIterator.

`alias`

  Alias with which this Phar archive should be referred to in calls to stream functionality.

### Fehler/Exceptions

Throws BadMethodCallException if called twice, UnexpectedValueException if the phar archive can't be opened.

### Beispiele

Beispiel #1 A Phar::__construct() example

    <?php
    try {
        $p = new Phar('/path/to/my.phar', FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::KEY_AS_FILENAME,
                      'my.phar');
    } catch (UnexpectedValueException $e) {
        die('Could not open my.phar');
    } catch (BadMethodCallException $e) {
        echo 'technically, this cannot happen';
    }
    // this works now
    echo file_get_contents('phar://my.phar/example.txt');
    // and works as if we had typed
    echo file_get_contents('phar:///path/to/my.phar/example.txt');
    ?>

# Phar::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToData — Convert a phar archive to a non-executable tar or zip file

### Beschreibung

public function Phar::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

This method is used to convert an executable phar archive to either a tar or zip file. To make the tar or zip non-executable, the phar stub and phar alias files are removed from the newly created archive.

If no changes are specified, this method throws a BadMethodCallException if the archive is in phar file format. For archives in tar or zip file format, this method converts the archive to a non-executable archive.

If successful, the method creates a new archive on disk and returns a PharData object. The old archive is not removed from disk, and should be done manually after the process has finished.

### Parameter-Liste

`format`

  This should be one of `Phar::TAR` or `Phar::ZIP`. If set to `null`, the existing file format will be preserved.

`compression`

  This should be one of `Phar::NONE` for no whole-archive compression, `Phar::GZ` for zlib-based compression, and `Phar::BZ2` for bzip-based compression.

`extension`

  This parameter is used to override the default file extension for a converted archive. Note that `.phar` cannot be used anywhere in the filename for a non-executable tar or zip archive.

  If converting to a tar-based phar archive, the default extensions are `.tar`, `.tar.gz`, and `.tar.bz2` depending on specified compression. For zip-based archives, the default extension is `.zip`.

### Rückgabewerte

The method returns a PharData object on success, or `null` on failure.

### Fehler/Exceptions

This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), and a PharException if any problems are encountered during the phar creation process.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `format`, `compression`, and `extension` are now nullable.

### Beispiele

Beispiel #1 A Phar::convertToData() example

Using Phar::convertToData():

    <?php
    try {
        $tarphar = new Phar('myphar.phar.tar');
        // note that myphar.phar.tar is *not* unlinked
        // convert it to the non-executable tar file format
        // creates myphar.tar
        $tar = $tarphar->convertToData();
        // convert to non-executable zip format, creates myphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // create myphar.tbz
        $tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // creates myphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // throws exception
    } catch (Exception $e) {
        // handle the error here
    }
    ?>

### Siehe auch

- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- PharData::convertToExecutable() - Convert a non-executable tar/zip archive to an executable phar archive
- PharData::convertToData() - Convert a phar archive to a non-executable tar or zip file

# Phar::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToExecutable — Convert a phar archive to another executable phar archive file format

### Beschreibung

public function Phar::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

This method is used to convert a phar archive to another file format. For instance, it can be used to create a tar-based executable phar archive from a zip-based executable phar archive, or from an executable phar archive in the phar file format. In addition, it can be used to apply whole-archive compression to a tar or phar-based archive.

If no changes are specified, this method throws a BadMethodCallException.

If successful, the method creates a new archive on disk and returns a Phar object. The old archive is not removed from disk, and should be done manually after the process has finished.

### Parameter-Liste

`format`

  This should be one of `Phar::PHAR`, `Phar::TAR`, or `Phar::ZIP`. If set to `null`, the existing file format will be preserved.

`compression`

  This should be one of `Phar::NONE` for no whole-archive compression, `Phar::GZ` for zlib-based compression, and `Phar::BZ2` for bzip-based compression.

`extension`

  This parameter is used to override the default file extension for a converted archive. Note that all zip- and tar-based phar archives must contain `.phar` in their file extension in order to be processed as a phar archive.

  If converting to a phar-based archive, the default extensions are `.phar`, `.phar.gz`, or `.phar.bz2` depending on the specified compression. For tar-based phar archives, the default extensions are `.phar.tar`, `.phar.tar.gz`, and `.phar.tar.bz2`. For zip-based phar archives, the default extension is `.phar.zip`.

### Rückgabewerte

The method returns a Phar object on success, or `null` on failure.

### Fehler/Exceptions

This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), an UnexpectedValueException if write support is disabled, and a PharException if any problems are encountered during the phar creation process.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `format`, `compression`, and `extension` are now nullable.

### Beispiele

Beispiel #1 A Phar::convertToExecutable() example

Using Phar::convertToExecutable():

    <?php
    try {
        $tarphar = new Phar('myphar.phar.tar');
        // convert it to the phar file format
        // note that myphar.phar.tar is *not* unlinked
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // creates myphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // creates myphar.phar.tgz
        $compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // handle the error here
    }
    ?>

### Siehe auch

- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable() - Convert a non-executable tar/zip archive to an executable phar archive
- PharData::convertToData() - Convert a phar archive to a non-executable tar or zip file

# Phar::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::copy — Copy a file internal to the phar archive to another new file within the phar

### Beschreibung

public function Phar::copy(string `$from`, string `$to`): true

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Copy a file internal to the phar archive to another new file within the phar. This is an object-oriented alternative to using copy() with the phar stream wrapper.

### Parameter-Liste

`from`

`to`

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws UnexpectedValueException if the source file does not exist, the destination file already exists, write access is disabled, opening either file fails, reading the source file fails, or a PharException if writing the changes to the phar fails.

### Beispiele

Beispiel #1 A Phar::copy() example

This example shows using Phar::copy() and the equivalent stream wrapper performance of the same thing. The primary difference between the two approaches is error handling. All Phar methods throw exceptions, whereas the stream wrapper uses trigger_error().

    <?php

    try {
        $phar = new Phar('myphar.phar');

        $phar['a'] = 'hi';
        $phar->copy('a', 'b');

        echo $phar['b']; // Outputs "phar://myphar.phar/b"
    } catch (Exception $e) {
        // Handle error
    }

    // The stream wrapper equivalent of the above code.
    // E_WARNING are triggered on error rather than exceptions
    copy('phar://myphar.phar/a', 'phar//myphar.phar/c');
    echo file_get_contents('phar://myphar.phar/c'); // Outputs "hi"

    ?>

# Phar::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::count — Returns the number of entries (files) in the Phar archive

### Beschreibung

public function Phar::count(int `$mode` = `COUNT_NORMAL`): int

### Parameter-Liste

`mode`

  `mode` is an integer value specifying the counting mode to be used. By default, it is set to `COUNT_NORMAL`, which counts only the number of items in the archive that have not been deleted or hidden. When set to `COUNT_RECURSIVE`, it counts all items in the archive, including those that have been deleted or hidden.

### Rückgabewerte

The number of files contained within this phar, or `0` (the number zero) if none.

### Beispiele

Beispiel #1 A Phar::count() example

    <?php
    // make sure it doesn't exist
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    } catch (Exception $e) {
        echo 'Could not create phar:', $e;
    }
    echo 'The new phar has ' . $p->count() . " entries\n";
    $p['file.txt'] = 'hi';
    echo 'The new phar has ' . $p->count() . " entries\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    The new phar has 0 entries
    The new phar has 1 entries

# Phar::createDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::createDefaultStub — Create a phar-file format specific stub

### Beschreibung

final public static function Phar::createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string

This method is intended for creation of phar-file format-specific stubs, and is not intended for use with tar- or zip-based phar archives.

Phar archives contain a bootstrap loader, or `stub` written in PHP that is executed when the archive is executed in PHP either via include:

    <?php
    include 'myphar.phar';
    ?>

or by simple execution:

    php myphar.phar

This method provides a simple and easy method to create a stub that will run a startup file from the phar archive. In addition, different files can be specified for running the phar archive from the command line versus through a web server. The loader stub also calls Phar::interceptFileFuncs() to allow easy bundling of a PHP application that accesses the file system. If the phar extension is not present, the loader stub will extract the phar archive to a temporary directory and then operate on the files. A shutdown function erases the temporary files on exit.

### Parameter-Liste

`index`

  Relative path within the phar archive to run if accessed on the command-line

`webIndex`

  Relative path within the phar archive to run if accessed through a web browser

### Rückgabewerte

Returns a string containing the contents of a customized bootstrap loader (stub) that allows the created Phar archive to work with or without the Phar extension enabled.

### Fehler/Exceptions

Throws UnexpectedValueException if either parameter is longer than 400 bytes.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `index` and `webIndex` are now nullable.

### Beispiele

Beispiel #1 A Phar::createDefaultStub() example

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // handle errors
    }
    ?>

### Siehe auch

- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::getStub() - Return the PHP loader or bootstrap stub of a Phar archive

# Phar::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompress — Decompresses the entire Phar archive

### Beschreibung

public function Phar::decompress(?string `$extension` = `null`): ?Phar

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

For tar-based and phar-based phar archives, this method decompresses the entire archive.

For Zip-based phar archives, this method fails with an exception. The zlib extension must be enabled to decompress an archive compressed with gzip compression, and the bzip2 extension must be enabled in order to decompress an archive compressed with bzip2 compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.

In addition, this method automatically changes the file extension of the archive, `.phar` by default for phar archives, or `.phar.tar` for tar-based phar archives. Alternatively, a file extension may be specified with the second parameter.

### Parameter-Liste

`extension`

  For decompressing, the default file extensions are `.phar` and `.phar.tar`. Use this parameter to specify another file extension. Be aware that all executable phar archives must contain `.phar` in their filename.

### Rückgabewerte

A Phar object is returned on success, and `null` on failure.

### Fehler/Exceptions

Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or the bzip2 extension is not enabled.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `extension` is now nullable.

### Beispiele

Beispiel #1 A Phar::decompress() example

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar.gz');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    $p3 = $p2->decompress(); // creates /path/to/my.phar
    ?>

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive

# Phar::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompressFiles — Decompresses all files in the current Phar archive

### Beschreibung

public function Phar::decompressFiles(): true

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

For tar-based phar archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use Phar::compress() to compress an entire tar-based phar archive.

For Zip-based and phar-based phar archives, this method decompresses all files in the Phar archive. The zlib or bzip2 extensions must be enabled to take advantage of this feature if any files are compressed using bzip2/zlib compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.

### Beispiele

Beispiel #1 A Phar::decompressFiles() example

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->decompressFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(10) "myfile.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "myfile2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(10) "myfile.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "myfile2.txt"
    bool(false)
    bool(false)
    bool(false)

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive

# Phar::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::delMetadata — Deletes the global metadata of the phar

### Beschreibung

public function Phar::delMetadata(): true

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Deletes the global metadata of the phar

### Parameter-Liste

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws PharException if errors occur while flushing changes to disk.

### Beispiele

Beispiel #1 A Phar::delMetaData() example

    <?php
    try {
        $phar = new Phar('myphar.phar');
        var_dump($phar->getMetadata());
        $phar->setMetadata("hi there");
        var_dump($phar->getMetadata());
        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // handle errors
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL
    string(8) "hi there"
    NULL

### Siehe auch

- Phar::getMetadata() - Returns phar archive meta-data
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data

# Phar::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::delete — Delete a file within a phar archive

### Beschreibung

public function Phar::delete(string `$localName`): true

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Delete a file within an archive. This is the functional equivalent of calling unlink() on the stream wrapper equivalent, as shown in the example below.

### Parameter-Liste

`localName`

  Path within an archive to the file to delete.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws PharException if errors occur while flushing changes to disk.

### Beispiele

Beispiel #1 A Phar::delete() example

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->delete('unlink/me.php');
        // this is equivalent to:
        unlink('phar://myphar.phar/unlink/me.php');
    } catch (Exception $e) {
        // handle errors
    }
    ?>

### Siehe auch

- PharData::delete() - Delete a file within a tar/zip archive
- Phar::unlinkArchive() - Completely remove a phar archive from disk and from memory

# Phar::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__destruct — Destructs a Phar archive object

### Beschreibung

public function Phar::__destruct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# Phar::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::extractTo — Extract the contents of a phar archive to a directory

### Beschreibung

public function Phar::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Extract all files within a phar archive to disk. Extracted files and directories preserve permissions as stored in the archive. The optional parameters allow optional control over which files are extracted, and whether existing files on disk can be overwritten. The second parameter `files` can be either the name of a file or directory to extract, or an array of names of files and directories to extract. By default, this method will not overwrite existing files, the third parameter can be set to true to enable overwriting of files. This method is similar to ZipArchive::extractTo().

### Parameter-Liste

`directory`

  Path to extract the given `files` to

`files`

  The name of a file or directory to extract, or an array of files/directories to extract, `null` to skip this param

`overwrite`

  Set to `true` to enable overwriting existing files

### Rückgabewerte

returns `true` on success, but it is better to check for thrown exception, and assume success if none is thrown.

### Fehler/Exceptions

Throws PharException if errors occur while flushing changes to disk.

### Beispiele

Beispiel #1 A Phar::extractTo() example

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->extractTo('/full/path'); // extract all files
        $phar->extractTo('/another/path', 'file.txt'); // extract only file.txt
        $phar->extractTo('/this/path',
            array('file1.txt', 'file2.txt')); // extract 2 files only
        $phar->extractTo('/third/path', null, true); // extract all files, and overwrite
    } catch (Exception $e) {
        // handle errors
    }
    ?>

### Anmerkungen

> Hinweis:

> Windows NTFS-Dateisysteme unterstützen einige Zeichen in Dateinamen nicht, nämlich `<|>*?":`. Dateinamen mit einem Punkt am Ende werden ebenfalls nicht unterstützt. Im Gegensatz zu einigen Extraktionswerkzeugen ersetzt diese Methode diese Zeichen nicht durch einen Unterstrich, sondern extrahiert solche Dateien nicht.

### Siehe auch

- PharData::extractTo() - Extract the contents of a tar/zip archive to a directory

# Phar::getAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::getAlias — Get the alias for Phar

### Beschreibung

public function Phar::getAlias(): ?string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the alias or `null` if there's no alias.

# Phar::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getMetadata — Returns phar archive meta-data

### Beschreibung

public function Phar::getMetadata(array `$unserializeOptions` = []): mixed

Retrieve archive meta-data. Meta-data can be any PHP variable that can be serialized.

Achtung

Accessing the meta-data will trigger deserialization, which can trigger the execution of arbitrary PHP code. Do not use this on untrusted phar archives, or configure the `unserializeOptions` in a secure manner.

### Parameter-Liste

No parameters.

### Rückgabewerte

Any PHP value that can be serialized and is stored as meta-data for the Phar archive, or `null` if no meta-data is stored.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | The parameter `unserializeOptions` has been added.

### Beispiele

Beispiel #1 A Phar::getMetadata() example

    <?php
    // make sure it doesn't exist
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.php'] = '<?php echo "hello";';
        $p->setMetadata(array('bootstrap' => 'file.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Could not modify phar:', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["bootstrap"]=>
      string(8) "file.php"
    }

### Siehe auch

- Phar::setMetadata() - Sets phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
- Phar::hasMetadata() - Returns whether phar has global meta-data

# Phar::getModified

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getModified — Return whether phar was modified

### Beschreibung

public function Phar::getModified(): bool

This method can be used to determine whether a phar has either had an internal file deleted, or contents of a file changed in some way.

### Parameter-Liste

No parameters.

### Rückgabewerte

`true` if the phar has been modified since opened, `false` if not.

# Phar::getPath

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Phar::getPath — Get the real path to the Phar archive on disk

### Beschreibung

public function Phar::getPath(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# Phar::getSignature

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getSignature — Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive

### Beschreibung

public function Phar::getSignature(): array|false

Returns the verification signature of a phar archive in a hexadecimal string.

### Parameter-Liste

### Rückgabewerte

Array with the opened archive's signature in `hash` key and `MD5`, `SHA-1`, `SHA-256`, `SHA-512`, or `OpenSSL` in `hash_type`. This signature is a hash calculated on the entire phar's contents, and may be used to verify the integrity of the archive. A valid signature is absolutely required of all executable phar archives if the phar.require_hash INI variable is set to true. If there is no signature, the function returns `false`.

# Phar::getStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getStub — Return the PHP loader or bootstrap stub of a Phar archive

### Beschreibung

public function Phar::getStub(): string

Phar archives contain a bootstrap loader, or `stub` written in PHP that is executed when the archive is executed in PHP either via include:

    <?php
    include 'myphar.phar';
    ?>

or by simple execution:

    php myphar.phar

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the contents of the bootstrap loader (stub) of the current Phar archive.

### Fehler/Exceptions

Throws RuntimeException if it is not possible to read the stub from the Phar archive.

### Beispiele

Beispiel #1 A Phar::getStub() example

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    echo $p->getStub();
    echo "==NEXT==\n";
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('myphar.phar');
    include 'phar://myphar.phar/startup.php';
    __HALT_COMPILER(); ?>");
    echo $p->getStub();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    <?php __HALT_COMPILER(); ?>
    ==NEXT==
    <?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('myphar.phar');
    include 'phar://myphar.phar/startup.php';
    __HALT_COMPILER(); ?>

### Siehe auch

- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::createDefaultStub() - Create a phar-file format specific stub

# Phar::getSupportedCompression

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::getSupportedCompression — Return array of supported compression algorithms

### Beschreibung

final public static function Phar::getSupportedCompression(): array

### Parameter-Liste

No parameters.

### Rückgabewerte

Returns an array containing any of `Phar::GZ` or `Phar::BZ2`, depending on the availability of the zlib extension or the bz2 extension.

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive

# Phar::getSupportedSignatures

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::getSupportedSignatures — Return array of supported signature types

### Beschreibung

final public static function Phar::getSupportedSignatures(): array

Return array of supported signature types

### Parameter-Liste

No parameters.

### Rückgabewerte

Returns an array containing any of `MD5`, `SHA-1`, `SHA-256`, `SHA-512`, or `OpenSSL`.

### Siehe auch

- Phar::getSignature() - Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
- Phar::setSignatureAlgorithm() - Set the signature algorithm for a phar and apply it

# Phar::getVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getVersion — Return version info of Phar archive

### Beschreibung

public function Phar::getVersion(): string

Returns the API version of an opened Phar archive.

### Parameter-Liste

### Rückgabewerte

The opened archive's API version. This is not to be confused with the API version that the loaded phar extension will use to create new phars. Each Phar archive has the API version hard-coded into its manifest. See Phar file format documentation for more information.

### Siehe auch

- Phar::apiVersion() - Returns the api version

# Phar::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::hasMetadata — Returns whether phar has global meta-data

### Beschreibung

public function Phar::hasMetadata(): bool

Returns whether phar has global meta-data set.

### Parameter-Liste

No parameters.

### Rückgabewerte

Returns `true` if meta-data has been set, and `false` if not.

### Beispiele

Beispiel #1 A Phar::hasMetadata() example

    <?php
    try {
        $phar = new Phar('myphar.phar');
        var_dump($phar->hasMetadata());
        $phar->setMetadata(array('thing' => 'hi'));
        var_dump($phar->hasMetadata());
        $phar->delMetadata();
        var_dump($phar->hasMetadata());
    } catch (Exception $e) {
        // handle error
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(false)

### Siehe auch

- Phar::getMetadata() - Returns phar archive meta-data
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar

# Phar::interceptFileFuncs

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::interceptFileFuncs — Instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions

### Beschreibung

final public static function Phar::interceptFileFuncs(): void

instructs phar to intercept fopen(), readfile(), file_get_contents(), opendir(), and all of the stat-related functions. If any of these functions is called from within a phar archive with a relative path, the call is modified to access a file within the phar archive. Absolute paths are assumed to be attempts to load external files from the filesystem.

This function makes it possible to run PHP applications designed to run off of a hard disk as a phar application.

### Parameter-Liste

No parameters.

### Rückgabewerte

### Beispiele

Beispiel #1 A Phar::interceptFileFuncs() example

    <?php
    Phar::interceptFileFuncs();
    include 'phar://' . __FILE__ . '/file.php';
    ?>

Assuming that this phar is at `/path/to/myphar.phar` and it contains `file.php` and `file2.txt`, if `file.php` contains this code:

Beispiel #2 A Phar::interceptFileFuncs() example

    <?php
    echo file_get_contents('file2.txt');
    ?>

Normally PHP would search the current directory for `file2.txt`, which would translate as the directory of file.php, or the current directory of a command-line user. Phar::interceptFileFuncs() instructs PHP to consider the current directory to be `phar:///path/to/myphar.phar/` and so opens `phar:///path/to/myphar.phar/file2.txt` in the above example code.

# Phar::isBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::isBuffering — Used to determine whether Phar write operations are being buffered, or are flushing directly to disk

### Beschreibung

public function Phar::isBuffering(): bool

This method can be used to determine whether a Phar will save changes to disk immediately, or whether a call to Phar::stopBuffering() is needed to enable saving changes.

Phar write buffering is per-archive, buffering active for the `foo.phar` Phar archive does not affect changes to the `bar.phar` Phar archive.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the write operations are being buffer, `false` otherwise.

### Beispiele

Beispiel #1 A Phar::isBuffering() example

    <?php
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p2 = new Phar('existingphar.phar');
    $p['file1.txt'] = 'hi';
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>
    =2=
    <?php
    $p->startBuffering();
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    $p->stopBuffering();
    ?>
    =3=
    <?php
    var_dump($p->isBuffering());
    var_dump($p2->isBuffering());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(false)
    =2=
    bool(true)
    bool(false)
    =3=
    bool(false)
    bool(false)

### Siehe auch

- Phar::startBuffering() - Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::stopBuffering() - Stop buffering write requests to the Phar archive, and save changes to disk

# Phar::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isCompressed — Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)

### Beschreibung

public function Phar::isCompressed(): int|false

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on). Zip-based phar archives cannot be compressed as a file, and so this method will always return `false` if a zip-based phar archive is queried.

### Parameter-Liste

No parameters.

### Rückgabewerte

`Phar::GZ`, `Phar::BZ2` or `false`.

### Beispiele

Beispiel #1 A Phar::isCompressed() example

    <?php
    try {
        $phar1 = new Phar('myphar.zip.phar');
        var_dump($phar1->isCompressed());
        $phar2 = new Phar('myuncompressed.tar.phar');
        var_dump($phar2->isCompressed());
        $phar2->compress(Phar::GZ);
        var_dump($phar2->isCompressed() == Phar::GZ);
    } catch (Exception $e) {
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(false)
    bool(true)

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms

# Phar::isFileFormat

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isFileFormat — Returns true if the phar archive is based on the tar/phar/zip file format depending on the parameter

### Beschreibung

public function Phar::isFileFormat(int `$format`): bool

### Parameter-Liste

`format`

  Either `Phar::PHAR`, `Phar::TAR`, or `Phar::ZIP` to test for the format of the archive.

### Rückgabewerte

Returns `true` if the phar archive matches the file format requested by the parameter

### Fehler/Exceptions

PharException is thrown if the parameter is an unknown file format specifier.

### Siehe auch

- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file

# Phar::isValidPharFilename

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::isValidPharFilename — Returns whether the given filename is a valid phar filename

### Beschreibung

final public static function Phar::isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool

Returns whether the given filename is a valid phar filename that will be recognized as a phar archive by the phar extension. This can be used to test a name without having to instantiate a phar archive and catch the inevitable Exception that will be thrown if an invalid name is specified.

### Parameter-Liste

`filename`

  The name or full path to a phar archive not yet created

`executable`

  This parameter determines whether the filename should be treated as a phar executable archive, or a data non-executable archive

### Rückgabewerte

Returns `true` if the filename is valid, `false` if not.

# Phar::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isWritable — Returns true if the phar archive can be modified

### Beschreibung

public function Phar::isWritable(): bool

This method returns `true` if `phar.readonly` is `0`, and the actual phar archive on disk is not read-only.

### Parameter-Liste

No parameters.

### Rückgabewerte

Returns `true` if the phar archive can be modified

### Siehe auch

- Phar::canWrite() - Returns whether phar extension supports writing and creating phars
- PharData::isWritable() - Returns true if the tar/zip archive can be modified

# Phar::loadPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::loadPhar — Loads any phar archive with an alias

### Beschreibung

final public static function Phar::loadPhar(string `$filename`, ?string `$alias` = `null`): bool

This can be used to read the contents of an external Phar archive. This is most useful for assigning an alias to a phar so that subsequent references to the phar can use the shorter alias, or for loading Phar archives that only contain data and are not intended for execution/inclusion in PHP scripts.

### Parameter-Liste

`filename`

  the full or relative path to the phar archive to open

`alias`

  The alias that may be used to refer to the phar archive. Note that many phar archives specify an explicit alias inside the phar archive, and a PharException will be thrown if a new alias is specified in this case.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

PharException is thrown if an alias is passed in and the phar archive already has an explicit alias

### Beispiele

Beispiel #1 A Phar::loadPhar() example

Phar::loadPhar can be used anywhere to load an external Phar archive, whereas Phar::mapPhar should be used in a loader stub for a Phar.

    <?php
    try {
        Phar::loadPhar('/path/to/phar.phar', 'my.phar');
        echo file_get_contents('phar://my.phar/file.txt');
    } catch (PharException $e) {
        echo $e;
    }
    ?>

### Siehe auch

- Phar::mapPhar() - Reads the currently executed file (a phar) and registers its manifest

# Phar::mapPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::mapPhar — Reads the currently executed file (a phar) and registers its manifest

### Beschreibung

final public static function Phar::mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool

This static method can only be used inside a Phar archive's loader stub in order to initialize the phar when it is directly executed, or when it is included in another script.

### Parameter-Liste

`alias`

  The alias that can be used in `phar://` URLs to refer to this archive, rather than its full path.

`offset`

  Unused variable, here for compatibility with PEAR's PHP_Archive.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

PharException is thrown if not called directly within PHP execution, if no __HALT_COMPILER(); token is found in the current source file, or if the file cannot be opened for reading.

### Beispiele

Beispiel #1 A Phar::mapPhar() example

mapPhar should be used only inside a phar's loader stub. Use loadPhar to load an external phar into memory.

Here is a sample Phar loader stub that uses mapPhar.

    <?php
    function __autoload($class)
    {
        include 'phar://me.phar/' . str_replace('_', '/', $class) . '.php';
    }
    try {
        Phar::mapPhar('me.phar');
        include 'phar://me.phar/startup.php';
    } catch (PharException $e) {
        echo $e->getMessage();
        die('Cannot initialize Phar');
    }
    __HALT_COMPILER();

### Siehe auch

- Phar::loadPhar() - Loads any phar archive with an alias

# Phar::mount

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mount — Mount an external path or file to a virtual location within the phar archive

### Beschreibung

final public static function Phar::mount(string `$pharPath`, string `$externalPath`): void

Much like the unix file system concept of mounting external devices to paths within the directory tree, Phar::mount() allows referring to external files and directories as if they were inside of an archive. This allows powerful abstraction such as referring to external configuration files as if they were inside the archive.

### Parameter-Liste

`pharPath`

  The internal path within the phar archive to use as the mounted path location. This must be a relative path within the phar archive, and must not already exist.

`externalPath`

  A path or URL to an external file or directory to mount within the phar archive

### Rückgabewerte

No return. PharException is thrown on failure.

### Fehler/Exceptions

Throws PharException if any problems occur mounting the path.

### Beispiele

Beispiel #1 A Phar::mount() example

The following example shows accessing an external configuration file as if it were a path within a phar archive.

First, the code inside of a phar archive:

    <?php
    $configuration = simplexml_load_string(file_get_contents(
        Phar::running(false) . '/config.xml'));
    ?>

Next the external code used to mount the configuration file:

    <?php
    // first set up the association between the abstract config.xml
    // and the actual one on disk
    Phar::mount('phar://config.xml', '/home/example/config.xml');
    // now run the application
    include '/path/to/archive.phar';
    ?>

Another method is to put the mounting code inside the stub of the phar archive. Here is an example of setting up a default configuration file if no user configuration is specified:

    <?php
    // first set up the association between the abstract config.xml
    // and the actual one on disk
    if (defined('EXTERNAL_CONFIG')) {
        Phar::mount('config.xml', EXTERNAL_CONFIG);
        if (file_exists(__DIR__ . '/extra_config.xml')) {
            Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
        }
    } else {
        Phar::mount('config.xml', 'phar://' . __FILE__ . '/default_config.xml');
        Phar::mount('extra.xml', 'phar://' . __FILE__ . '/default_extra.xml');
    }
    // now run the application
    include 'phar://' . __FILE__ . '/index.php';
    __HALT_COMPILER();
    ?>

...and the code externally to load this phar archive:

    <?php
    define('EXTERNAL_CONFIG', '/home/example/config.xml');
    // now run the application
    include '/path/to/archive.phar';
    ?>

# Phar::mungServer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mungServer — Defines a list of up to 4 $_SERVER variables that should be modified for execution

### Beschreibung

final public static function Phar::mungServer(array `$variables`): void

Phar::mungServer() should only be called within the stub of a phar archive.

Defines a list of up to 4 $_SERVER variables that should be modified for execution. Variables that can be modified to remove traces of phar execution are `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` and `SCRIPT_FILENAME`.

On its own, this method does nothing. Only when combined with Phar::webPhar() does it take effect, and only when the requested file is a PHP file to be parsed. Note that the `PATH_INFO` and `PATH_TRANSLATED` variables are always modified.

The original values of variables that are modified are stored in the SERVER array with `PHAR_` prepended, so for instance `SCRIPT_NAME` would be saved as `PHAR_SCRIPT_NAME`.

### Parameter-Liste

`variables`

  An array of any of the strings `REQUEST_URI`, `PHP_SELF`, `SCRIPT_NAME` and `SCRIPT_FILENAME`. Other values trigger an exception, and Phar::mungServer() is case-sensitive.

### Rückgabewerte

No return.

### Fehler/Exceptions

Throws UnexpectedValueException if any problems are found with the passed in data.

### Beispiele

Beispiel #1 A Phar::mungServer() example

    <?php
    // example stub
    Phar::mungServer(array('REQUEST_URI'));
    Phar::webPhar();
    __HALT_COMPILER();
    ?>

### Siehe auch

- Phar::webPhar() - Routes a request from a web browser to an internal file within the phar archive
- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive

# Phar::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetExists — Determines whether a file exists in the phar

### Beschreibung

public function Phar::offsetExists(string `$localName`): bool

This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets.

offsetExists() is called whenever isset() is called.

### Parameter-Liste

`localName`

  The filename (relative path) to look for in a Phar.

### Rückgabewerte

Returns `true` if the file exists within the phar, or `false` if not.

### Beispiele

Beispiel #1 A Phar::offsetExists() example

    <?php
    $p = new Phar(dirname(__FILE__) . '/my.phar', 0, 'my.phar');
    $p['firstfile.txt'] = 'first file';
    $p['secondfile.txt'] = 'second file';
    // the next set of lines call offsetExists() indirectly
    var_dump(isset($p['firstfile.txt']));
    var_dump(isset($p['nothere.txt']));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)

### Siehe auch

- Phar::offsetGet() - Gets a PharFileInfo object for a specific file
- Phar::offsetSet() - Set the contents of an internal file to those of an external file
- Phar::offsetUnset() - Remove a file from a phar

# Phar::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetGet — Gets a PharFileInfo object for a specific file

### Beschreibung

public function Phar::offsetGet(string `$localName`): SplFileInfo

This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. Phar::offsetGet() is used for retrieving files from a Phar archive.

### Parameter-Liste

`localName`

  The filename (relative path) to look for in a Phar.

### Rückgabewerte

A PharFileInfo object is returned that can be used to iterate over a file's contents or to retrieve information about the current file.

### Fehler/Exceptions

This method throws BadMethodCallException if the file does not exist in the Phar archive.

### Beispiele

Beispiel #1 Phar::offsetGet() example

As with all classes that implement the ArrayAccess interface, Phar::offsetGet() is automatically called when using the `[]` angle bracket operator.

    <?php
    $p = new Phar(dirname(__FILE__) . '/myphar.phar', 0, 'myphar.phar');
    $p['exists.txt'] = "file exists\n";
    try {
        // automatically calls offsetGet()
        echo $p['exists.txt'];
        echo $p['doesnotexist.txt'];
    } catch (BadMethodCallException $e) {
        echo $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    file exists
    Entry doesnotexist.txt does not exist

### Siehe auch

- Phar::offsetExists() - Determines whether a file exists in the phar
- Phar::offsetSet() - Set the contents of an internal file to those of an external file
- Phar::offsetUnset() - Remove a file from a phar

# Phar::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetSet — Set the contents of an internal file to those of an external file

### Beschreibung

public function Phar::offsetSet(string `$localName`, resource|string `$value`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. offsetSet is used for modifying an existing file, or adding a new file to a Phar archive.

### Parameter-Liste

`localName`

  The filename (relative path) to modify in a Phar.

`value`

  Content of the file.

### Rückgabewerte

No return values.

### Fehler/Exceptions

if phar.readonly is `1`, BadMethodCallException is thrown, as modifying a Phar is only allowed when phar.readonly is set to `0`. Throws PharException if there are any problems flushing changes made to the Phar archive to disk.

### Beispiele

Beispiel #1 A Phar::offsetSet() example

offsetSet should not be accessed directly, but instead used via array access with the `[]` operator.

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    try {
        // calls offsetSet
        $p['file.txt'] = 'Hi there';
    } catch (Exception $e) {
        echo 'Could not modify file.txt:', $e;
    }
    ?>

### Anmerkungen

> Hinweis: Die Funktionen Phar::addFile(), Phar::addFromString() und Phar::offsetSet() speichern bei jedem Aufruf ein neues phar-Archiv. Wenn die Leistung ein wichtiger Faktor ist, sollte stattdessen Phar::buildFromDirectory() oder Phar::buildFromIterator() verwendet werden.

### Siehe auch

- Phar::offsetExists() - Determines whether a file exists in the phar
- Phar::offsetGet() - Gets a PharFileInfo object for a specific file
- Phar::offsetUnset() - Remove a file from a phar

# Phar::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetUnset — Remove a file from a phar

### Beschreibung

public function Phar::offsetUnset(string `$localName`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. offsetUnset is used for deleting an existing file, and is called by the unset() language construct.

### Parameter-Liste

`localName`

  The filename (relative path) to modify in a Phar.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

if phar.readonly is `1`, BadMethodCallException is thrown, as modifying a Phar is only allowed when phar.readonly is set to `0`. Throws PharException if there are any problems flushing changes made to the Phar archive to disk.

### Beispiele

Beispiel #1 A Phar::offsetUnset() example

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    try {
        // deletes file.txt from my.phar by calling offsetUnset
        unset($p['file.txt']);
    } catch (Exception $e) {
        echo 'Could not delete file.txt: ', $e;
    }
    ?>

### Siehe auch

- Phar::offsetExists() - Determines whether a file exists in the phar
- Phar::offsetGet() - Gets a PharFileInfo object for a specific file
- Phar::offsetSet() - Set the contents of an internal file to those of an external file
- Phar::unlinkArchive() - Completely remove a phar archive from disk and from memory
- Phar::delete() - Delete a file within a phar archive

# Phar::running

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::running — Returns the full path on disk or full phar URL to the currently executing Phar archive

### Beschreibung

final public static function Phar::running(bool `$returnPhar` = `true`): string

Returns the full path to the running phar archive. This is intended for use much like the `__FILE__` magic constant, and only has effect inside an executing phar archive.

Inside the stub of an archive, Phar::running() returns `""`. Simply use `__FILE__` to access the current running phar inside a stub.

### Parameter-Liste

`returnPhar`

  If `false`, the full path on disk to the phar archive is returned. If `true`, a full phar URL is returned.

### Rückgabewerte

Returns the filename if valid, empty string otherwise.

### Beispiele

Beispiel #1 A Phar::running() example

For the following example, assume the phar archive is located at `/path/to/phar/my.phar`.

    <?php
    $a = Phar::running(); // $a is "phar:///path/to/my.phar"
    $b = Phar::running(false); // $b is "/path/to/my.phar"
    ?>

# Phar::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::setAlias — Set the alias for the Phar archive

### Beschreibung

public function Phar::setAlias(string `$alias`): true

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Set the alias for the Phar archive, and write it as the permanent alias for this phar archive. An alias can be used internally to a phar archive to ensure that use of the `phar` stream wrapper to access internal files always works regardless of the location of the phar archive on the filesystem. Another alternative is to rely upon Phar's interception of include or to use Phar::interceptFileFuncs() and use relative paths.

### Parameter-Liste

`alias`

  A shorthand string that this archive can be referred to in `phar` stream wrapper access.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws UnexpectedValueException when write access is disabled, and PharException if the alias is already in use or any problems were encountered flushing changes to disk.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Phar::setAlias() now has a tentative return of true.

### Beispiele

Beispiel #1 A Phar::setAlias() example

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->setAlias('myp.phar');
    } catch (Exception $e) {
        // handle error
    }
    ?>

### Siehe auch

- Phar::__construct() - Construct a Phar archive object
- Phar::interceptFileFuncs() - Instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions

# Phar::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::setDefaultStub — Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader

### Beschreibung

public function Phar::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

This method is a convenience method that combines the functionality of Phar::createDefaultStub() and Phar::setStub().

### Parameter-Liste

`index`

  Relative path within the phar archive to run if accessed on the command-line

`webIndex`

  Relative path within the phar archive to run if accessed through a web browser

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

UnexpectedValueException is thrown if phar.readonly is enabled in php.ini. PharException is thrown if any problems are encountered flushing changes to disk.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Phar::setDefaultStub() now has a tentative return of true.
8.0.0 | `webIndex` is nullable now.

### Beispiele

Beispiel #1 A Phar::setDefaultStub() example

    <?php
    try {
        $phar = new Phar('myphar.phar');
        $phar->setDefaultStub('cli.php', 'web/index.php');
        // this is the same as:
        // $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
    } catch (Exception $e) {
        // handle errors
    }
    ?>

### Siehe auch

- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::createDefaultStub() - Create a phar-file format specific stub

# Phar::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setMetadata — Sets phar archive meta-data

### Beschreibung

public function Phar::setMetadata(mixed `$metadata`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Phar::setMetadata() should be used to store customized data that describes something about the phar archive as a complete entity. PharFileInfo::setMetadata() should be used for file-specific meta-data. Meta-data can slow down the performance of loading a phar archive if the data is large.

Some possible uses for meta-data include specifying which file within the archive should be used to bootstrap the archive, or the location of a file manifest like » PEAR's package.xml file. However, any useful data that describes the phar archive may be stored.

### Parameter-Liste

`metadata`

  Any PHP variable containing information to store that describes the phar archive

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 A Phar::setMetadata() example

    <?php
    // make sure it doesn't exist
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.php'] = '<?php echo "hello"';
        $p->setMetadata(array('bootstrap' => 'file.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Could not create and/or modify phar:', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["bootstrap"]=>
      string(8) "file.php"
    }

### Siehe auch

- Phar::getMetadata() - Returns phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
- Phar::hasMetadata() - Returns whether phar has global meta-data

# Phar::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithm — Set the signature algorithm for a phar and apply it

### Beschreibung

public function Phar::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

set the signature algorithm for a phar and apply it. The signature algorithm must be one of `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, or `Phar::OPENSSL`.

Note that all executable phar archives have a signature created automatically, `SHA1` by default. data tar- or zip-based archives (archives created with the PharData class) must have their signature created and set explicitly via Phar::setSignatureAlgorithm().

### Parameter-Liste

`algo`

  One of `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, or `Phar::OPENSSL`

`privateKey`

  The contents of an OpenSSL private key, as extracted from a certificate or OpenSSL key file:

      <?php
      $private = openssl_get_privatekey(file_get_contents('private.pem'));
      $pkey = '';
      openssl_pkey_export($private, $pkey);
      $p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
      ?>

  See phar introduction for instructions on naming and placement of the public key file.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

Throws UnexpectedValueException for many errors, and a PharException if any problems occur flushing changes to disk.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `privateKey` is now nullable.

### Siehe auch

- Phar::getSupportedSignatures() - Return array of supported signature types
- Phar::getSignature() - Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive

# Phar::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStub — Used to set the PHP loader or bootstrap stub of a Phar archive

### Beschreibung

public function Phar::setStub(resource|string `$stub`, int `$length` = -1): true

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

This method is used to add a PHP bootstrap loader stub to a new Phar archive, or to replace the loader stub in an existing Phar archive.

The loader stub for a Phar archive is used whenever an archive is included directly as in this example:

    <?php
    include 'myphar.phar';
    ?>

or by simple execution:

    php myphar.phar

The loader is not accessed when including a file through the `phar` stream wrapper like so:

    <?php
    include 'phar://myphar.phar/somefile.php';
    ?>

### Parameter-Liste

`stub`

  A string or an open stream handle to use as the executable stub for this phar archive.

`length`
  Length of `stub` in bytes.
  Warnung

  Passing the `length` argument with a Ressource in the first argument is DEPRECATED as of PHP 8.3.0. Use `$phar->setStub(stream_get_contents($resource))` instead.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

UnexpectedValueException is thrown if phar.readonly is enabled in php.ini. PharException is thrown if any problems are encountered flushing changes to disk.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Rückgabewert ist nun `true`; vorher war es bool.
8.3.0 | Calling Phar::setStub() with a resource and a `length` is now deprecated. Such calls should be replaced by: `$phar->setStub(stream_get_contents($resource));`

### Beispiele

Beispiel #1 A Phar::setStub() example

    <?php

    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['a.php'] = '<?php var_dump("Hello");';
        $p->setStub('<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
        include 'phar://brandnewphar.phar/a.php';
        var_dump($p->getStub());

        $p['b.php'] = '<?php var_dump("World");';
        $p->setStub('<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
        include 'phar://brandnewphar.phar/b.php';
        var_dump($p->getStub());
    } catch (Exception $e) {
        echo 'Write operations failed on brandnewphar.phar: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(5) "Hello"
    string(82) "<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
    string(5) "World"
    string(83) "<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"

### Siehe auch

- Phar::getStub() - Return the PHP loader or bootstrap stub of a Phar archive
- Phar::createDefaultStub() - Create a phar-file format specific stub

# Phar::startBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::startBuffering — Start buffering Phar write operations, do not modify the Phar object on disk

### Beschreibung

public function Phar::startBuffering(): void

Although technically unnecessary, the Phar::startBuffering() method can provide a significant performance boost when creating or modifying a Phar archive with a large number of files. Ordinarily, every time a file within a Phar archive is created or modified in any way, the entire Phar archive will be recreated with the changes. In this way, the archive will be up-to-date with the activity performed on it.

However, this can be unnecessary when simply creating a new Phar archive, when it would make more sense to write the entire archive out at once. Similarly, it is often necessary to make a series of changes and to ensure that they all are possible before making any changes on disk, similar to the relational database concept of transactions. the Phar::startBuffering()/Phar::stopBuffering() pair of methods is provided for this purpose.

Phar write buffering is per-archive, buffering active for the `foo.phar` Phar archive does not affect changes to the `bar.phar` Phar archive.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 A Phar::startBuffering() example

    <?php
    // make sure it doesn't exist
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    } catch (Exception $e) {
        echo 'Could not create phar:', $e;
    }
    echo 'The new phar has ' . $p->count() . " entries\n";
    $p->startBuffering();
    $p['file.txt'] = 'hi';
    $p['file2.txt'] = 'there';
    $p['file2.txt']->setCompressedGZ();
    $p['file3.txt'] = 'babyface';
    $p['file3.txt']->setMetadata(42);
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://myphar.phar/' . str_replace('_', '/', $class) . '.php';
    }
    Phar::mapPhar('myphar.phar');
    include 'phar://myphar.phar/startup.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    ?>

### Siehe auch

- Phar::stopBuffering() - Stop buffering write requests to the Phar archive, and save changes to disk
- Phar::isBuffering() - Used to determine whether Phar write operations are being buffered, or are flushing directly to disk

# Phar::stopBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::stopBuffering — Stop buffering write requests to the Phar archive, and save changes to disk

### Beschreibung

public function Phar::stopBuffering(): void

Phar::stopBuffering() is used in conjunction with the Phar::startBuffering() method. Phar::startBuffering() can provide a significant performance boost when creating or modifying a Phar archive with a large number of files. Ordinarily, every time a file within a Phar archive is created or modified in any way, the entire Phar archive will be recreated with the changes. In this way, the archive will be up-to-date with the activity performed on it.

However, this can be unnecessary when simply creating a new Phar archive, when it would make more sense to write the entire archive out at once. Similarly, it is often necessary to make a series of changes and to ensure that they all are possible before making any changes on disk, similar to the relational database concept of transactions. The Phar::startBuffering()/Phar::stopBuffering() pair of methods is provided for this purpose.

Phar write buffering is per-archive, buffering active for the `foo.phar` Phar archive does not affect changes to the `bar.phar` Phar archive.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

PharException is thrown if any problems are encountered flushing changes to disk.

### Beispiele

Beispiel #1 A Phar::stopBuffering() example

    <?php
    $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    $p['file1.txt'] = 'hi';
    $p->startBuffering();
    var_dump($p->getStub());
    $p->setStub("<?php
    function __autoload(\$class)
    {
        include 'phar://brandnewphar.phar/' . str_replace('_', '/', \$class) . '.php';
    }
    Phar::mapPhar('brandnewphar.phar');
    include 'phar://brandnewphar.phar/startup.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    var_dump($p->getStub());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(24) "<?php __HALT_COMPILER();"
    string(195) "<?php
    function __autoload($class)
    {
        include 'phar://' . str_replace('_', '/', $class);
    }
    Phar::mapPhar('brandnewphar.phar');
    include 'phar://brandnewphar.phar/startup.php';
    __HALT_COMPILER();"

### Siehe auch

- Phar::startBuffering() - Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::isBuffering() - Used to determine whether Phar write operations are being buffered, or are flushing directly to disk

# Phar::unlinkArchive

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::unlinkArchive — Completely remove a phar archive from disk and from memory

### Beschreibung

final public static function Phar::unlinkArchive(string `$filename`): true

Removes a phar archive from disk and memory.

### Parameter-Liste

`filename`

  The path on disk to the phar archive.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

PharException is thrown if there are any open file pointers to the phar archive, or any existing Phar, PharData, or PharFileInfo objects referring to the phar archive.

### Beispiele

Beispiel #1 A Phar::unlinkArchive() example

    <?php
    // simple usage
    Phar::unlinkArchive('/path/to/my.phar');

    // more common example:
    $p = new Phar('my.phar');
    $fp = fopen('phar://my.phar/file.txt', 'r');
    // this creates 'my.phar.gz'
    $gp = $p->compress(Phar::GZ);
    // remove all references to the archive
    unset($p);
    fclose($fp);
    // now remove all traces of the archive
    Phar::unlinkArchive('my.phar');
    ?>

### Siehe auch

- Phar::delete() - Delete a file within a phar archive
- Phar::offsetUnset() - Remove a file from a phar

# Phar::webPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::webPhar — Routes a request from a web browser to an internal file within the phar archive

### Beschreibung

final public static function Phar::webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void

Phar::webPhar() serves as Phar::mapPhar() for web-based phars. This method parses $_SERVER['REQUEST_URI'] and routes a request from a web browser to an internal file within the phar archive. It simulates a web server, routing requests to the correct file, echoing the correct headers and parsing PHP files as needed. Combined with Phar::mungServer() and Phar::interceptFileFuncs(), any web application can be used unmodified from a phar archive.

Phar::webPhar() should only be called from the stub of a phar archive (see here for more information on what a stub is).

### Parameter-Liste

`alias`

  The alias that can be used in `phar://` URLs to refer to this archive, rather than its full path.

`index`

  The location within the phar of the directory index.

`fileNotFoundScript`

  The location of the script to run when a file is not found. This script should output the proper HTTP 404 headers.

`mimeTypes`

  An array mapping additional file extensions to MIME type. If the default mapping is sufficient, pass an empty array. By default, these extensions are mapped to these MIME types:

      <?php
      $mimes = array(
          'phps' => Phar::PHPS, // pass to highlight_file()
          'c' => 'text/plain',
          'cc' => 'text/plain',
          'cpp' => 'text/plain',
          'c++' => 'text/plain',
          'dtd' => 'text/plain',
          'h' => 'text/plain',
          'log' => 'text/plain',
          'rng' => 'text/plain',
          'txt' => 'text/plain',
          'xsd' => 'text/plain',
          'php' => Phar::PHP, // parse as PHP
          'inc' => Phar::PHP, // parse as PHP
          'avi' => 'video/avi',
          'bmp' => 'image/bmp',
          'css' => 'text/css',
          'gif' => 'image/gif',
          'htm' => 'text/html',
          'html' => 'text/html',
          'htmls' => 'text/html',
          'ico' => 'image/x-ico',
          'jpe' => 'image/jpeg',
          'jpg' => 'image/jpeg',
          'jpeg' => 'image/jpeg',
          'js' => 'application/x-javascript',
          'midi' => 'audio/midi',
          'mid' => 'audio/midi',
          'mod' => 'audio/mod',
          'mov' => 'movie/quicktime',
          'mp3' => 'audio/mp3',
          'mpg' => 'video/mpeg',
          'mpeg' => 'video/mpeg',
          'pdf' => 'application/pdf',
          'png' => 'image/png',
          'swf' => 'application/shockwave-flash',
          'tif' => 'image/tiff',
          'tiff' => 'image/tiff',
          'wav' => 'audio/wav',
          'xbm' => 'image/xbm',
          'xml' => 'text/xml',
      );
      ?>

`rewrite`

  The rewrites function is passed a string as its only parameter and must return a string or `false`.

  If you are using fast-cgi or cgi then the parameter passed to the function is the value of the $_SERVER['PATH_INFO'] variable. Otherwise, the parameter passed to the function is the value of the $_SERVER['REQUEST_URI'] variable.

  If a string is returned it is used as the internal file path. If `false` is returned then webPhar() will send a HTTP 403 Denied Code.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

Throws PharException when unable to open the internal file to output, or if called from a non-stub. If an invalid array value is passed into `mimeTypes` or an invalid callback is passed into `rewrite`, then UnexpectedValueException is thrown.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `fileNotFoundScript` and `rewrite` are nullable now.

### Beispiele

Beispiel #1 A Phar::webPhar() example

With the example below, the created phar will display `Hello World` if one browses to `/myphar.phar/index.php` or to `/myphar.phar`, and will display the source of `index.phps` if one browses to `/myphar.phar/index.phps`.

    <?php
    // creating the phar archive:
    try {
        $phar = new Phar('myphar.phar');
        $phar['index.php'] = '<?php echo "Hello World"; ?>';
        $phar['index.phps'] = '<?php echo "Hello World"; ?>';
        $phar->setStub('<?php
    Phar::webPhar();
    __HALT_COMPILER(); ?>');
    } catch (Exception $e) {
        // handle error here
    }
    ?>

### Siehe auch

- Phar::mungServer() - Defines a list of up to 4 $_SERVER variables that should be modified for execution
- Phar::interceptFileFuncs() - Instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions

## Inhaltsverzeichnis

- Phar::addEmptyDir — Add an empty directory to the phar archive
- Phar::addFile — Add a file from the filesystem to the phar archive
- Phar::addFromString — Add a file from a string to the phar archive
- Phar::apiVersion — Returns the api version
- Phar::buildFromDirectory — Construct a phar archive from the files within a directory
- Phar::buildFromIterator — Construct a phar archive from an iterator
- Phar::canCompress — Returns whether phar extension supports compression using either zlib or bzip2
- Phar::canWrite — Returns whether phar extension supports writing and creating phars
- Phar::compress — Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::compressFiles — Compresses all files in the current Phar archive
- Phar::__construct — Construct a Phar archive object
- Phar::convertToData — Convert a phar archive to a non-executable tar or zip file
- Phar::convertToExecutable — Convert a phar archive to another executable phar archive file format
- Phar::copy — Copy a file internal to the phar archive to another new file within the phar
- Phar::count — Returns the number of entries (files) in the Phar archive
- Phar::createDefaultStub — Create a phar-file format specific stub
- Phar::decompress — Decompresses the entire Phar archive
- Phar::decompressFiles — Decompresses all files in the current Phar archive
- Phar::delMetadata — Deletes the global metadata of the phar
- Phar::delete — Delete a file within a phar archive
- Phar::__destruct — Destructs a Phar archive object
- Phar::extractTo — Extract the contents of a phar archive to a directory
- Phar::getAlias — Get the alias for Phar
- Phar::getMetadata — Returns phar archive meta-data
- Phar::getModified — Return whether phar was modified
- Phar::getPath — Get the real path to the Phar archive on disk
- Phar::getSignature — Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
- Phar::getStub — Return the PHP loader or bootstrap stub of a Phar archive
- Phar::getSupportedCompression — Return array of supported compression algorithms
- Phar::getSupportedSignatures — Return array of supported signature types
- Phar::getVersion — Return version info of Phar archive
- Phar::hasMetadata — Returns whether phar has global meta-data
- Phar::interceptFileFuncs — Instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
- Phar::isBuffering — Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
- Phar::isCompressed — Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::isFileFormat — Returns true if the phar archive is based on the tar/phar/zip file format depending on the parameter
- Phar::isValidPharFilename — Returns whether the given filename is a valid phar filename
- Phar::isWritable — Returns true if the phar archive can be modified
- Phar::loadPhar — Loads any phar archive with an alias
- Phar::mapPhar — Reads the currently executed file (a phar) and registers its manifest
- Phar::mount — Mount an external path or file to a virtual location within the phar archive
- Phar::mungServer — Defines a list of up to 4 $_SERVER variables that should be modified for execution
- Phar::offsetExists — Determines whether a file exists in the phar
- Phar::offsetGet — Gets a PharFileInfo object for a specific file
- Phar::offsetSet — Set the contents of an internal file to those of an external file
- Phar::offsetUnset — Remove a file from a phar
- Phar::running — Returns the full path on disk or full phar URL to the currently executing Phar archive
- Phar::setAlias — Set the alias for the Phar archive
- Phar::setDefaultStub — Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
- Phar::setMetadata — Sets phar archive meta-data
- Phar::setSignatureAlgorithm — Set the signature algorithm for a phar and apply it
- Phar::setStub — Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::startBuffering — Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::stopBuffering — Stop buffering write requests to the Phar archive, and save changes to disk
- Phar::unlinkArchive — Completely remove a phar archive from disk and from memory
- Phar::webPhar — Routes a request from a web browser to an internal file within the phar archive

# The PharData class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

## Einführung

The PharData class provides a high-level interface to accessing and creating non-executable tar and zip archives. Because these archives do not contain a stub and cannot be executed by the phar extension, it is possible to create and manipulate regular zip and tar files using the PharData class even if `phar.readonly` php.ini setting is `1`.

## Klassenbeschreibung

class PharData extends RecursiveDirectoryIterator implements Countable, ArrayAccess {
/* Geerbte Konstanten */
public const int FilesystemIterator::CURRENT_MODE_MASK;
public const int FilesystemIterator::CURRENT_AS_PATHNAME;
public const int FilesystemIterator::CURRENT_AS_FILEINFO;
public const int FilesystemIterator::CURRENT_AS_SELF;
public const int FilesystemIterator::KEY_MODE_MASK;
public const int FilesystemIterator::KEY_AS_PATHNAME;
public const int FilesystemIterator::FOLLOW_SYMLINKS;
public const int FilesystemIterator::KEY_AS_FILENAME;
public const int FilesystemIterator::NEW_CURRENT_AND_KEY;
public const int FilesystemIterator::OTHER_MODE_MASK;
public const int FilesystemIterator::SKIP_DOTS;
public const int FilesystemIterator::UNIX_PATHS;
/* Methoden */
public function __construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
public function compress(int `$compression`, ?string `$extension` = `null`): ?PharData
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function decompress(?string `$extension` = `null`): ?PharData
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function isWritable(): bool
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
public function setAlias(string `$alias`): bool
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function __destruct()
/* Geerbte Methoden */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharData::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addEmptyDir — Add an empty directory to the tar/zip archive

### Beschreibung

public function PharData::addEmptyDir(string `$directory`): void

With this method, an empty directory is created with path `dirname`. This method is similar to ZipArchive::addEmptyDir().

### Parameter-Liste

`directory`

  The name of the empty directory to create in the phar archive

### Rückgabewerte

no return value, exception is thrown on failure.

### Beispiele

Beispiel #1 A PharData::addEmptyDir() example

    <?php
    try {
        $a = new PharData('/path/to/my.tar');

        $a->addEmptyDir('/full/path/to/file');
        // demonstrates how this file is stored
        $b = $a['full/path/to/file']->isDir();
    } catch (Exception $e) {
        // handle errors here
    }
    ?>

### Siehe auch

- Phar::addEmptyDir() - Add an empty directory to the phar archive
- PharData::addFile() - Add a file from the filesystem to the tar/zip archive
- PharData::addFromString() - Add a file from a string to the tar/zip archive

# PharData::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFile — Add a file from the filesystem to the tar/zip archive

### Beschreibung

public function PharData::addFile(string `$filename`, ?string `$localName` = `null`): void

With this method, any file or URL can be added to the tar/zip archive. If the optional second parameter `localname` is specified, the file will be stored in the archive with that name, otherwise the `file` parameter is used as the path to store within the archive. URLs must have a localname or an exception is thrown. This method is similar to ZipArchive::addFile().

### Parameter-Liste

`filename`

  Full or relative path to a file on disk to be added to the phar archive.

`localName`

  Path that the file will be stored in the archive.

### Rückgabewerte

no return value, exception is thrown on failure.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `localName` is now nullable.

### Beispiele

Beispiel #1 A PharData::addFile() example

    <?php
    try {
        $a = new PharData('/path/to/my.tar');

        $a->addFile('/full/path/to/file');
        // demonstrates how this file is stored
        $b = $a['full/path/to/file']->getContent();

        $a->addFile('/full/path/to/file', 'my/file.txt');
        $c = $a['my/file.txt']->getContent();

        // demonstrate URL usage
        $a->addFile('http://www.example.com', 'example.html');
    } catch (Exception $e) {
        // handle errors here
    }
    ?>

### Anmerkungen

> Hinweis: Die Funktionen PharData::addFile(), PharData::addFromString() und PharData::offsetSet() speichern bei jedem Aufruf ein neues phar-Archiv. Wenn die Leistung ein wichtiger Faktor ist, sollte stattdessen PharData::buildFromDirectory() oder PharData::buildFromIterator() verwendet werden.

### Siehe auch

- PharData::offsetSet() - Set the contents of a file within the tar/zip to those of an external file or string
- Phar::addFile() - Add a file from the filesystem to the phar archive
- PharData::addFromString() - Add a file from a string to the tar/zip archive
- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive

# PharData::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFromString — Add a file from a string to the tar/zip archive

### Beschreibung

public function PharData::addFromString(string `$localName`, string `$contents`): void

With this method, any string can be added to the tar/zip archive. The file will be stored in the archive with `localname` as its path. This method is similar to ZipArchive::addFromString().

### Parameter-Liste

`localName`

  Path that the file will be stored in the archive.

`contents`

  The file contents to store

### Rückgabewerte

no return value, exception is thrown on failure.

### Beispiele

Beispiel #1 A PharData::addFromString() example

    <?php
    try {
        $a = new PharData('/path/to/my.tar');

        $a->addFromString('path/to/file.txt', 'my simple file');
        $b = $a['path/to/file.txt']->getContent();

        // to add contents from a stream handle for large files, use offsetSet()
        $c = fopen('/path/to/hugefile.bin');
        $a['largefile.bin'] = $c;
        fclose($c);
    } catch (Exception $e) {
        // handle errors here
    }
    ?>

### Anmerkungen

> Hinweis: Die Funktionen PharData::addFile(), PharData::addFromString() und PharData::offsetSet() speichern bei jedem Aufruf ein neues phar-Archiv. Wenn die Leistung ein wichtiger Faktor ist, sollte stattdessen PharData::buildFromDirectory() oder PharData::buildFromIterator() verwendet werden.

### Siehe auch

- PharData::offsetSet() - Set the contents of a file within the tar/zip to those of an external file or string
- Phar::addFromString() - Add a file from a string to the phar archive
- PharData::addFile() - Add a file from the filesystem to the tar/zip archive
- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive

# PharData::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromDirectory — Construct a tar/zip archive from the files within a directory

### Beschreibung

public function PharData::buildFromDirectory(string `$directory`, string `$pattern` = ""): array

Populate a tar/zip archive from directory contents. The optional second parameter is a regular expression (pcre) that is used to exclude files. Any filename that matches the regular expression will be included, all others will be excluded. For more fine-grained control, use PharData::buildFromIterator().

### Parameter-Liste

`directory`

  The full or relative path to the directory that contains all files to add to the archive.

`pattern`

  An optional pcre regular expression that is used to filter the list of files. Only file paths matching the regular expression will be included in the archive.

### Rückgabewerte

Phar::buildFromDirectory() returns an associative array mapping internal path of file to the full path of the file on the filesystem, Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

This method throws BadMethodCallException when unable to instantiate the internal directory iterators, or a PharException if there were errors saving the phar archive.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | PharData::buildFromDirectory() no longer returns `false`.

### Beispiele

Beispiel #1 A PharData::buildFromDirectory() example

    <?php
    $phar = new PharData('project.tar');
    // add all files in the project
    $phar->buildFromDirectory(dirname(__FILE__) . '/project');

    $phar2 = new PharData('project2.zip');
    // add all files in the project, only include php files
    $phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
    ?>

### Siehe auch

- Phar::buildFromDirectory() - Construct a phar archive from the files within a directory
- PharData::buildFromIterator() - Construct a tar or zip archive from an iterator

# PharData::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromIterator — Construct a tar or zip archive from an iterator

### Beschreibung

public function PharData::buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array

Populate a tar or zip archive from an iterator. Two styles of iterators are supported, iterators that map the filename within the tar/zip to the name of a file on disk, and iterators like DirectoryIterator that return SplFileInfo objects. For iterators that return SplFileInfo objects, the second parameter is required.

### Parameter-Liste

`iterator`

  Any iterator that either associatively maps tar/zip file to location or returns SplFileInfo objects

`baseDirectory`

  For iterators that return SplFileInfo objects, the portion of each file's full path to remove when adding to the tar/zip archive

### Rückgabewerte

PharData::buildFromIterator() returns an associative array mapping internal path of file to the full path of the file on the filesystem.

### Fehler/Exceptions

This method returns UnexpectedValueException when the iterator returns incorrect values, such as an integer key instead of a string, a BadMethodCallException when an SplFileInfo-based iterator is passed without a `baseDirectory` parameter, or a PharException if there were errors saving the phar archive.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | PharData::buildFromIterator() no longer returns `false`.
8.0.0 | `baseDirectory` is now nullable.

### Beispiele

Beispiel #1 A PharData::buildFromIterator() with SplFileInfo

For most tar/zip archives, the archive will reflect an actual directory layout, and the second style is the most useful. For instance, to create a tar/zip archive containing the files in this sample directory layout:

    /path/to/project/
                     config/
                            dist.xml
                            debug.xml
                     lib/
                         file1.php
                         file2.php
                     src/
                         processthing.php
                     www/
                         index.php
                     cli/
                         index.php

This code could be used to add these files to the "project.tar" tar archive:

    <?php
    $phar = new PharData('project.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new RecursiveDirectoryIterator('/path/to/project')),
        '/path/to/project');
    ?>

The file `project.tar` can then be used immediately. PharData::buildFromIterator() does not set values such as compression, metadata, and this can be done after creating the tar/zip archive.

As an interesting note, PharData::buildFromIterator() can also be used to copy the contents of an existing phar, tar or zip archive, as the PharData object descends from DirectoryIterator:

    <?php
    $phar = new PharData('project.tar');
    $phar->buildFromIterator(
        new RecursiveIteratorIterator(
         new Phar('/path/to/anotherphar.phar')),
        'phar:///path/to/anotherphar.phar/path/to/project');
    $phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
    ?>

Beispiel #2 A PharData::buildFromIterator() with other iterators

The second form of the iterator can be used with any iterator that returns a key => value mapping, such as an ArrayIterator:

    <?php
    $phar = new PharData('project.tar');
    $phar->buildFromIterator(
        new ArrayIterator(
         array(
            'internal/file.php' => dirname(__FILE__) . '/somefile.php',
            'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
         )));
    ?>

### Siehe auch

- Phar::buildFromIterator() - Construct a phar archive from an iterator

# PharData::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compress — Compresses the entire tar/zip archive using Gzip or Bzip2 compression

### Beschreibung

public function PharData::compress(int `$compression`, ?string `$extension` = `null`): ?PharData

For tar archives, this method compresses the entire archive using gzip compression or bzip2 compression. The resulting file can be processed with the gunzip command/bunzip command, or accessed directly and transparently with the Phar extension.

For zip archives, this method fails with an exception. The zlib extension must be enabled to compress with gzip compression, the bzip2 extension must be enabled in order to compress with bzip2 compression.

In addition, this method automatically renames the archive, appending `.gz`, `.bz2` or removing the extension if passed `Phar::NONE` to remove compression. Alternatively, a file extension may be specified with the second parameter.

### Parameter-Liste

`compression`

  Compression must be one of `Phar::GZ`, `Phar::BZ2` to add compression, or `Phar::NONE` to remove compression.

`extension`

  By default, the extension is `.tar.gz` or `.tar.bz2` for compressing a tar, and `.tar` for decompressing.

### Rückgabewerte

A PharData object is returned on success, or `null` on failure.

### Fehler/Exceptions

Throws BadMethodCallException if the zlib extension is not available, or the bzip2 extension is not enabled.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `extension` is now nullable.

### Beispiele

Beispiel #1 A PharData::compress() example

    <?php
    $p = new PharData('/path/to/my.tar');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    $p1 = $p->compress(Phar::GZ); // copies to /path/to/my.tar.gz
    $p2 = $p->compress(Phar::BZ2); // copies to /path/to/my.tar.bz2
    $p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.tar already exists
    ?>

### Siehe auch

- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression

# PharData::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compressFiles — Compresses all files in the current tar/zip archive

### Beschreibung

public function PharData::compressFiles(int `$compression`): void

For tar-based archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use PharData::compress() to compress an entire tar-based archive.

For Zip-based archives, this method compresses all files in the archive using the specified compression. The zlib or bzip2 extensions must be enabled to take advantage of this feature. In addition, if any files are already compressed using bzip2/zlib compression, the respective extension must be enabled in order to decompress the files prior to re-compressing.

### Parameter-Liste

`compression`

  Compression must be one of `Phar::GZ`, `Phar::BZ2` to add compression, or `Phar::NONE` to remove compression.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.

### Beispiele

Beispiel #1 A PharData::compressFiles() example

    <?php
    $p = new Phar('/path/to/my.phar', 0, 'my.phar');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(10) "myfile.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "myfile2.txt"
    bool(false)
    bool(false)
    bool(false)
    string(10) "myfile.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "myfile2.txt"
    int(4096)
    bool(false)
    bool(true)

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- PharData::decompressFiles() - Decompresses all files in the current zip archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::decompress() - Decompresses the entire Phar archive

# PharData::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__construct — Construct a non-executable tar or zip archive object

### Beschreibung

public function PharData::__construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)

### Parameter-Liste

`filename`

  Path to an existing tar/zip archive or to-be-created archive

`flags`

  Flags to pass to Phar parent class RecursiveDirectoryIterator.

`alias`

  Alias with which this Phar archive should be referred to in calls to stream functionality.

`format`

  One of the file format constants available within the Phar class.

### Fehler/Exceptions

Throws BadMethodCallException if called twice; UnexpectedValueException if the Phar archive can't be opened.

### Beispiele

Beispiel #1 A PharData::__construct() example

    <?php
    try {
        $p = new PharData('/path/to/my.tar', Phar::CURRENT_AS_FILEINFO | Phar::KEY_AS_FILENAME);
    } catch (UnexpectedValueException $e) {
        die('Could not open my.tar');
    } catch (BadMethodCallException $e) {
        echo 'technically, this cannot happen';
    }
    echo file_get_contents('phar:///path/to/my.tar/example.txt');
    ?>

# PharData::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToData — Convert a phar archive to a non-executable tar or zip file

### Beschreibung

public function PharData::convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData

This method is used to convert a non-executable tar or zip archive to another non-executable format.

If no changes are specified, this method throws a BadMethodCallException. This method should be used to convert a tar archive to zip format or vice-versa. Although it is possible to simply change the compression of a tar archive using this method, it is better to use the PharData::compress() method for logical consistency.

If successful, the method creates a new archive on disk and returns a PharData object. The old archive is not removed from disk, and should be done manually after the process has finished.

### Parameter-Liste

`format`

  This should be one of `Phar::TAR` or `Phar::ZIP`. If set to `null`, the existing file format will be preserved.

`compression`

  This should be one of `Phar::NONE` for no whole-archive compression, `Phar::GZ` for zlib-based compression, and `Phar::BZ2` for bzip-based compression.

`extension`

  This parameter is used to override the default file extension for a converted archive. Note that `.phar` cannot be used anywhere in the filename for a non-executable tar or zip archive.

  If converting to a tar-based phar archive, the default extensions are `.tar`, `.tar.gz`, and `.tar.bz2` depending on specified compression. For zip-based archives, the default extension is `.zip`.

### Rückgabewerte

The method returns a PharData object on success, or `null` on failure.

### Fehler/Exceptions

This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), and a PharException if any problems are encountered during the phar creation process.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `format`, `compression`, and `extension` are now nullable.

### Beispiele

Beispiel #1 A PharData::convertToData() example

Using PharData::convertToData():

    <?php
    try {
        $tarphar = new PharData('myphar.tar');
        // note that myphar.tar is *not* unlinked
        // convert it to the non-executable tar file format
        // creates myphar.zip
        $zip = $tarphar->convertToData(Phar::ZIP);
        // create myphar.tbz
        $tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
        // creates myphar.phar.tgz
        $phar = $tarphar->convertToData(Phar::PHAR); // throws exception
    } catch (Exception $e) {
        // handle the error here
    }
    ?>

### Siehe auch

- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable() - Convert a non-executable tar/zip archive to an executable phar archive

# PharData::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToExecutable — Convert a non-executable tar/zip archive to an executable phar archive

### Beschreibung

public function PharData::convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

This method is used to convert a non-executable tar or zip archive to an executable phar archive. Any of the three executable file formats (phar, tar or zip) can be used, and whole-archive compression can also be performed.

If no changes are specified, this method throws a BadMethodCallException.

If successful, the method creates a new archive on disk and returns a Phar object. The old archive is not removed from disk, and should be done manually after the process has finished.

### Parameter-Liste

`format`

  This should be one of `Phar::PHAR`, `Phar::TAR`, or `Phar::ZIP`. If set to `null`, the existing file format will be preserved.

`compression`

  This should be one of `Phar::NONE` for no whole-archive compression, `Phar::GZ` for zlib-based compression, and `Phar::BZ2` for bzip-based compression.

`extension`

  This parameter is used to override the default file extension for a converted archive. Note that all zip- and tar-based phar archives must contain `.phar` in their file extension in order to be processed as a phar archive.

  If converting to a phar-based archive, the default extensions are `.phar`, `.phar.gz`, or `.phar.bz2` depending on the specified compression. For tar-based phar archives, the default extensions are `.phar.tar`, `.phar.tar.gz`, and `.phar.tar.bz2`. For zip-based phar archives, the default extension is `.phar.zip`.

### Rückgabewerte

The method returns a Phar object on success, or `null` on failure.

### Fehler/Exceptions

This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), an UnexpectedValueException if write support is disabled, and a PharException if any problems are encountered during the phar creation process.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `format`, `compression`, and `localName` are now nullable.

### Beispiele

Beispiel #1 A PharData::convertToExecutable() example

Using PharData::convertToExecutable():

    <?php
    try {
        $tarphar = new PharData('myphar.tar');
        // convert it to the phar file format
        // note that myphar.tar is *not* unlinked
        $phar = $tarphar->convertToExecutable(Phar::PHAR); // creates myphar.phar
        $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
        // creates myphar.phar.tgz
        $compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
    } catch (Exception $e) {
        // handle the error here
    }
    ?>

### Siehe auch

- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
- PharData::convertToData() - Convert a phar archive to a non-executable tar or zip file

# PharData::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::copy — Copy a file internal to the tar/zip archive to another new file within the same archive

### Beschreibung

public function PharData::copy(string `$from`, string `$to`): true

Copy a file internal to the tar/zip archive to another new file within the same archive. This is an object-oriented alternative to using copy() with the phar stream wrapper.

### Parameter-Liste

`from`

`to`

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws UnexpectedValueException if the source file does not exist, the destination file already exists, write access is disabled, opening either file fails, reading the source file fails, or a PharException if writing the changes to the phar fails.

### Beispiele

Beispiel #1 A PharData::copy() example

This example shows using PharData::copy() and the equivalent stream wrapper performance of the same thing. The primary difference between the two approaches is error handling. All PharData methods throw exceptions, whereas the stream wrapper uses trigger_error().

    <?php

    try {
        $phar = new PharData('myphar.tar');

        $phar['a'] = 'hi';
        $phar->copy('a', 'b');

        echo $phar['b']; // Outputs "phar://myphar.tar/b"
    } catch (Exception $e) {
        // Handle error
    }

    // The stream wrapper equivalent of the above code.
    // E_WARNING are triggered on error rather than exceptions
    copy('phar://myphar.tar/a', 'phar//myphar.tar/c');
    echo file_get_contents('phar://myphar.tar/c'); // Outputs "hi"

    ?>

# PharData::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompress — Decompresses the entire Phar archive

### Beschreibung

public function PharData::decompress(?string `$extension` = `null`): ?PharData

For tar-based archives, this method decompresses the entire archive.

For Zip-based archives, this method fails with an exception. The zlib extension must be enabled to decompress an archive compressed with gzip compression, and the bzip2 extension must be enabled in order to decompress an archive compressed with bzip2 compression.

In addition, this method automatically renames the file extension of the archive, `.tar` by default. Alternatively, a file extension may be specified with the `extension` parameter.

### Parameter-Liste

`extension`

  For decompressing, the default file extension is `.tar`. Use this parameter to specify another file extension. Be aware that only executable archives can contain `.phar` in their filename.

### Rückgabewerte

A PharData object is returned on success, or `null` on failure.

### Fehler/Exceptions

Throws BadMethodCallException if the zlib extension is not available, or the bzip2 extension is not enabled.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `extension` is now nullable.

### Beispiele

Beispiel #1 A PharData::decompress() example

    <?php
    $p = new PharData('/path/to/my.tar.gz');
    $p->decompress(); // creates /path/to/my.tar
    ?>

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- PharData::compressFiles() - Compresses all files in the current tar/zip archive
- PharData::decompressFiles() - Decompresses all files in the current zip archive

# PharData::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompressFiles — Decompresses all files in the current zip archive

### Beschreibung

public function PharData::decompressFiles(): true

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

For tar-based archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use PharData::compress() to compress an entire tar-based archive.

For Zip-based archives, this method decompresses all files in the archive. The zlib or bzip2 extensions must be enabled to take advantage of this feature if any files are compressed using bzip2/zlib compression.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws BadMethodCallException if the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.

### Beispiele

Beispiel #1 A PharData::decompressFiles() example

    <?php
    $p = new PharData('/path/to/my.zip');
    $p['myfile.txt'] = 'hi';
    $p['myfile2.txt'] = 'hi';
    $p->compressFiles(Phar::GZ);
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    $p->decompressFiles();
    foreach ($p as $file) {
        var_dump($file->getFileName());
        var_dump($file->isCompressed());
        var_dump($file->isCompressed(Phar::BZ2));
        var_dump($file->isCompressed(Phar::GZ));
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(10) "myfile.txt"
    int(4096)
    bool(false)
    bool(true)
    string(11) "myfile2.txt"
    int(4096)
    bool(false)
    bool(true)
    string(10) "myfile.txt"
    bool(false)
    bool(false)
    bool(false)
    string(11) "myfile2.txt"
    bool(false)
    bool(false)
    bool(false)

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- PharData::compressFiles() - Compresses all files in the current tar/zip archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::decompress() - Decompresses the entire Phar archive

# PharData::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delMetadata — Deletes the global metadata of a zip archive

### Beschreibung

public function PharData::delMetadata(): true

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Deletes the global metadata of the zip archive

### Parameter-Liste

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws PharException if errors occur while flushing changes to disk.

### Beispiele

Beispiel #1 A PharData::delMetaData() example

    <?php
    try {
        $phar = new PharData('myphar.zip');
        var_dump($phar->getMetadata());
        $phar->setMetadata("hi there");
        var_dump($phar->getMetadata());
        $phar->delMetadata();
        var_dump($phar->getMetadata());
    } catch (Exception $e) {
        // handle errors
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL
    string(8) "hi there"
    NULL

### Siehe auch

- Phar::delMetadata() - Deletes the global metadata of the phar

# PharData::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delete — Delete a file within a tar/zip archive

### Beschreibung

public function PharData::delete(string `$localName`): true

Delete a file within an archive. This is the functional equivalent of calling unlink() on the stream wrapper equivalent, as shown in the example below.

### Parameter-Liste

`localName`

  Path within an archive to the file to delete.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws PharException if errors occur while flushing changes to disk.

### Beispiele

Beispiel #1 A PharData::delete() example

    <?php
    try {
        $phar = new PharData('myphar.zip');
        $phar->delete('unlink/me.php');
        // this is equivalent to:
        unlink('phar://myphar.phar/unlink/me.php');
    } catch (Exception $e) {
        // handle errors
    }
    ?>

### Siehe auch

- Phar::delete() - Delete a file within a phar archive

# PharData::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__destruct — Destructs a non-executable tar or zip archive object

### Beschreibung

public function PharData::__destruct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# PharData::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::extractTo — Extract the contents of a tar/zip archive to a directory

### Beschreibung

public function PharData::extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool

Extract all files within a tar/zip archive to disk. Extracted files and directories preserve permissions as stored in the archive. The optional parameters allow optional control over which files are extracted, and whether existing files on disk can be overwritten. The second parameter `files` can be either the name of a file or directory to extract, or an array of names of files and directories to extract. By default, this method will not overwrite existing files, the third parameter can be set to true to enable overwriting of files. This method is similar to ZipArchive::extractTo().

### Parameter-Liste

`directory`

  Path to extract the given `files` to

`files`

  The name of a file or directory to extract, or an array of files/directories to extract

`overwrite`

  Set to `true` to enable overwriting existing files

### Rückgabewerte

returns `true` on success, but it is better to check for thrown exception, and assume success if none is thrown.

### Fehler/Exceptions

Throws PharException if errors occur while flushing changes to disk.

### Beispiele

Beispiel #1 A PharData::extractTo() example

    <?php
    try {
        $phar = new PharData('myphar.tar');
        $phar->extractTo('/full/path'); // extract all files
        $phar->extractTo('/another/path', 'file.txt'); // extract only file.txt
        $phar->extractTo('/this/path',
            array('file1.txt', 'file2.txt')); // extract 2 files only
        $phar->extractTo('/third/path', null, true); // extract all files, and overwrite
    } catch (Exception $e) {
        // handle errors
    }
    ?>

### Anmerkungen

> Hinweis:

> Windows NTFS-Dateisysteme unterstützen einige Zeichen in Dateinamen nicht, nämlich `<|>*?":`. Dateinamen mit einem Punkt am Ende werden ebenfalls nicht unterstützt. Im Gegensatz zu einigen Extraktionswerkzeugen ersetzt diese Methode diese Zeichen nicht durch einen Unterstrich, sondern extrahiert solche Dateien nicht.

### Siehe auch

- Phar::extractTo() - Extract the contents of a phar archive to a directory

# PharData::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::isWritable — Returns true if the tar/zip archive can be modified

### Beschreibung

public function PharData::isWritable(): bool

This method returns `true` if the tar/zip archive on disk is not read-only. Unlike Phar::isWritable(), data-only tar/zip archives can be modified even if `phar.readonly` is set to `1`.

### Parameter-Liste

No parameters.

### Rückgabewerte

Returns `true` if the tar/zip archive can be modified

### Siehe auch

- Phar::canWrite() - Returns whether phar extension supports writing and creating phars
- Phar::isWritable() - Returns true if the phar archive can be modified

# PharData::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetSet — Set the contents of a file within the tar/zip to those of an external file or string

### Beschreibung

public function PharData::offsetSet(string `$localName`, resource|string `$value`): void

This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a tar/zip archive using array access brackets. offsetSet is used for modifying an existing file, or adding a new file to a tar/zip archive.

### Parameter-Liste

`localName`

  The filename (relative path) to modify in a tar or zip archive.

`value`

  Content of the file.

### Rückgabewerte

No return values.

### Fehler/Exceptions

Throws PharException if there are any problems flushing changes made to the tar/zip archive to disk.

### Beispiele

Beispiel #1 A PharData::offsetSet() example

offsetSet should not be accessed directly, but instead used via array access with the `[]` operator.

    <?php
    $p = new PharData('/path/to/my.tar');
    try {
        // calls offsetSet
        $p['file.txt'] = 'Hi there';
    } catch (Exception $e) {
        echo 'Could not modify file.txt:', $e;
    }
    ?>

### Anmerkungen

> Hinweis: Die Funktionen PharData::addFile(), PharData::addFromString() und PharData::offsetSet() speichern bei jedem Aufruf ein neues phar-Archiv. Wenn die Leistung ein wichtiger Faktor ist, sollte stattdessen PharData::buildFromDirectory() oder PharData::buildFromIterator() verwendet werden.

### Siehe auch

- Phar::offsetSet() - Set the contents of an internal file to those of an external file

# PharData::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetUnset — Remove a file from a tar/zip archive

### Beschreibung

public function PharData::offsetUnset(string `$localName`): void

This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a tar/zip archive using array access brackets. offsetUnset is used for deleting an existing file, and is called by the unset() language construct.

### Parameter-Liste

`localName`

  The filename (relative path) to modify in the tar/zip archive.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

Throws PharException if there are any problems flushing changes made to the tar/zip archive to disk.

### Beispiele

Beispiel #1 A PharData::offsetUnset() example

    <?php
    $p = new PharData('/path/to/my.zip');
    try {
        // deletes file.txt from my.zip by calling offsetUnset
        unset($p['file.txt']);
    } catch (Exception $e) {
        echo 'Could not delete file.txt: ', $e;
    }
    ?>

### Siehe auch

- Phar::offsetUnset() - Remove a file from a phar

# PharData::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setAlias — Dummy function (Phar::setAlias is not valid for PharData)

### Beschreibung

public function PharData::setAlias(string `$alias`): bool

Non-executable tar/zip archives cannot have an alias, so this method simply throws an exception.

### Parameter-Liste

`alias`

  A shorthand string that this archive can be referred to in `phar` stream wrapper access. This parameter is ignored.

### Rückgabewerte

### Fehler/Exceptions

Throws PharException on all method calls

### Siehe auch

- Phar::setAlias() - Set the alias for the Phar archive

# PharData::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setDefaultStub — Dummy function (Phar::setDefaultStub is not valid for PharData)

### Beschreibung

public function PharData::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool

Non-executable tar/zip archives cannot have a stub, so this method simply throws an exception.

### Parameter-Liste

`index`

  Relative path within the phar archive to run if accessed on the command-line

`webIndex`

  Relative path within the phar archive to run if accessed through a web browser

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Throws PharException on all method calls

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `webIndex` is nullable now.

### Siehe auch

- Phar::setDefaultStub() - Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader

# PharData::setMetadata

(No version information available, might only be in Git)

PharData::setMetadata — Sets phar archive meta-data

### Beschreibung

public function PharData::setMetadata(mixed `$metadata`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Phar::setMetadata() should be used to store customized data that describes something about the phar archive as a complete entity. PharFileInfo::setMetadata() should be used for file-specific meta-data. Meta-data can slow down the performance of loading a phar archive if the data is large.

Some possible uses for meta-data include specifying which file within the archive should be used to bootstrap the archive, or the location of a file manifest like » PEAR's package.xml file. However, any useful data that describes the phar archive may be stored.

### Parameter-Liste

`metadata`

  Any PHP variable containing information to store that describes the phar archive

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 A Phar::setMetadata() example

    <?php
    // make sure it doesn't exist
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.php'] = '<?php echo "hello"';
        $p->setMetadata(array('bootstrap' => 'file.php'));
        var_dump($p->getMetadata());
    } catch (Exception $e) {
        echo 'Could not create and/or modify phar:', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["bootstrap"]=>
      string(8) "file.php"
    }

### Siehe auch

- Phar::getMetadata() - Returns phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
- Phar::hasMetadata() - Returns whether phar has global meta-data

# PharData::setSignatureAlgorithm

(No version information available, might only be in Git)

PharData::setSignatureAlgorithm — Set the signature algorithm for a phar and apply it

### Beschreibung

public function PharData::setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void

> Hinweis:

> Diese Methode des Phar-Objekts funktioniert nur wenn die php.ini-Einstellung `phar.readonly` auf 0 gesetzt ist, sonst wird eine PharException geworfen.

Set the signature algorithm for a phar and apply it. The signature algorithm must be one of `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, or `Phar::OPENSSL`.

### Parameter-Liste

`algo`

  One of `Phar::MD5`, `Phar::SHA1`, `Phar::SHA256`, `Phar::SHA512`, or `Phar::OPENSSL`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

Throws UnexpectedValueException for many errors, BadMethodCallException if called for a zip- or a tar-based phar archive, and a PharException if any problems occur flushing changes to disk.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `privateKey` is now nullable.

### Siehe auch

- Phar::getSupportedSignatures() - Return array of supported signature types
- Phar::getSignature() - Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive

# PharData::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setStub — Dummy function (Phar::setStub is not valid for PharData)

### Beschreibung

public function PharData::setStub(resource|string `$stub`, int `$length` = -1): true

Non-executable tar/zip archives cannot have a stub, so this method simply throws an exception.

### Parameter-Liste

`stub`
  Formally, a string or an open stream handle to use as the executable stub for this phar archive. This parameter is ignored.
`length`
  `stub` in bytes. This parameter is ignored.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws PharException on all method calls

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Rückgabewert ist nun `true`; vorher war es bool.

### Siehe auch

- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive

## Inhaltsverzeichnis

- PharData::addEmptyDir — Add an empty directory to the tar/zip archive
- PharData::addFile — Add a file from the filesystem to the tar/zip archive
- PharData::addFromString — Add a file from a string to the tar/zip archive
- PharData::buildFromDirectory — Construct a tar/zip archive from the files within a directory
- PharData::buildFromIterator — Construct a tar or zip archive from an iterator
- PharData::compress — Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::compressFiles — Compresses all files in the current tar/zip archive
- PharData::__construct — Construct a non-executable tar or zip archive object
- PharData::convertToData — Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable — Convert a non-executable tar/zip archive to an executable phar archive
- PharData::copy — Copy a file internal to the tar/zip archive to another new file within the same archive
- PharData::decompress — Decompresses the entire Phar archive
- PharData::decompressFiles — Decompresses all files in the current zip archive
- PharData::delMetadata — Deletes the global metadata of a zip archive
- PharData::delete — Delete a file within a tar/zip archive
- PharData::__destruct — Destructs a non-executable tar or zip archive object
- PharData::extractTo — Extract the contents of a tar/zip archive to a directory
- PharData::isWritable — Returns true if the tar/zip archive can be modified
- PharData::offsetSet — Set the contents of a file within the tar/zip to those of an external file or string
- PharData::offsetUnset — Remove a file from a tar/zip archive
- PharData::setAlias — Dummy function (Phar::setAlias is not valid for PharData)
- PharData::setDefaultStub — Dummy function (Phar::setDefaultStub is not valid for PharData)
- PharData::setMetadata — Sets phar archive meta-data
- PharData::setSignatureAlgorithm — Set the signature algorithm for a phar and apply it
- PharData::setStub — Dummy function (Phar::setStub is not valid for PharData)

# The PharFileInfo class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Einführung

The PharFileInfo class provides a high-level interface to the contents and attributes of a single file within a phar archive.

## Klassenbeschreibung

class PharFileInfo extends SplFileInfo {
/* Methoden */
public function __construct(string `$filename`)
public function chmod(int `$perms`): void
public function compress(int `$compression`): true
public function decompress(): true
public function delMetadata(): true
public function getCRC32(): int
public function getCompressedSize(): int
public function getContent(): string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getPharFlags(): int
public function hasMetadata(): bool
public function isCRCChecked(): bool
public function isCompressed(?int `$compression` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function __destruct()
/* Geerbte Methoden */
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharFileInfo::chmod

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::chmod — Sets file-specific permission bits

### Beschreibung

public function PharFileInfo::chmod(int `$perms`): void

PharFileInfo::chmod() allows setting of the executable file permissions bit, as well as read-only bits. Writeable bits are ignored, and set at runtime based on the phar.readonly INI variable. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.

### Parameter-Liste

`perms`

  permissions (see chmod())

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 A PharFileInfo::chmod() example

    <?php
    // make sure it doesn't exist
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar('brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.sh'] = '#!/usr/local/lib/php
        <?php echo "hi"; ?>';
        // set executable bit
        $p['file.sh']->chmod(0555);
        var_dump($p['file.sh']->isExecutable());
    } catch (Exception $e) {
        echo 'Could not create/modify phar: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

# PharFileInfo::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::compress — Compresses the current Phar entry with either zlib or bzip2 compression

### Beschreibung

public function PharFileInfo::compress(int `$compression`): true

This method compresses the file inside the Phar archive using either bzip2 compression or zlib compression. The bzip2 or zlib extension must be enabled to take advantage of this feature. In addition, if the file is already compressed, the respective extension must be enabled in order to decompress the file. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.

### Parameter-Liste

`compression`

  Compression must be `Phar::GZ` or `Phar::BZ2`.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.

### Beispiele

Beispiel #1 A PharFileInfo::compress() example

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        var_dump($file->isCompressed(Phar::BZ2));
        $p['myfile.txt']->compress(Phar::BZ2);
        var_dump($file->isCompressed(Phar::BZ2));
    } catch (Exception $e) {
        echo 'Create/modify operations on my.phar failed: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms

# PharFileInfo::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__construct — Construct a Phar entry object

### Beschreibung

public function PharFileInfo::__construct(string `$filename`)

This should not be called directly. Instead, a PharFileInfo object is initialized by calling Phar::offsetGet() through array access.

### Parameter-Liste

`filename`

  The full url to retrieve a file. If you wish to retrieve the information for the file `my/file.php` from the phar `boo.phar`, the entry should be `phar://boo.phar/my/file.php`.

### Fehler/Exceptions

Throws BadMethodCallException if __construct() is called twice. Throws UnexpectedValueException if the phar URL requested is malformed, the requested phar cannot be opened, or the file can't be found within the phar.

### Beispiele

Beispiel #1 A PharFileInfo::__construct() example

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['testfile.txt'] = "hi\nthere\ndude";
        $file = $p['testfile.txt'];
        foreach ($file as $line => $text) {
            echo "line number $line: $text";
        }
        // this also works
        $file = new PharFileInfo('phar:///path/to/my.phar/testfile.txt');
        foreach ($file as $line => $text) {
            echo "line number $line: $text";
        }
    } catch (Exception $e) {
        echo 'Phar operations failed: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    line number 1: hi
    line number 2: there
    line number 3: dude
    line number 1: hi
    line number 2: there
    line number 3: dude

# PharFileInfo::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::decompress — Decompresses the current Phar entry within the phar

### Beschreibung

public function PharFileInfo::decompress(): true

This method decompresses the file inside the Phar archive. Depending on how the file is compressed, the bzip2 or zlib extensions must be enabled to take advantage of this feature. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.

### Beispiele

Beispiel #1 A PharFileInfo::decompress() example

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        $file->compress(Phar::GZ);
        var_dump($file->isCompressed());
        $p['myfile.txt']->decompress();
        var_dump($file->isCompressed());
    } catch (Exception $e) {
        echo 'Create/modify failed for my.phar: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(4096)
    bool(false)

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms

# PharFileInfo::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::delMetadata — Deletes the metadata of the entry

### Beschreibung

public function PharFileInfo::delMetadata(): true

Deletes the metadata of the entry, if any.

### Parameter-Liste

No parameters.

### Rückgabewerte

Gibt immer `true` zurück. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.

### Fehler/Exceptions

Throws PharException if errors occurred while flushing changes to disk, and BadMethodCallException if write access is disabled.

### Beispiele

Beispiel #1 A PharFileInfo::delMetaData() example

    <?php
    try {
        $a = new Phar('myphar.phar');
        $a['hi'] = 'hi';
        var_dump($a['hi']->delMetadata());
        $a['hi']->setMetadata('there');
        var_dump($a['hi']->delMetadata());
        var_dump($a['hi']->delMetadata());
    } catch (Exception $e) {
        // handle errors
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(false)

### Siehe auch

- PharFileInfo::setMetadata() - Sets file-specific meta-data saved with a file
- PharFileInfo::hasMetadata() - Returns the metadata of the entry
- PharFileInfo::getMetadata() - Returns file-specific meta-data saved with a file
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data

# PharFileInfo::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__destruct — Destructs a Phar entry object

### Beschreibung

public function PharFileInfo::__destruct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# PharFileInfo::getCRC32

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCRC32 — Returns CRC32 code or throws an exception if CRC has not been verified

### Beschreibung

public function PharFileInfo::getCRC32(): int

This returns the crc32() checksum of the file within the Phar archive.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The crc32() checksum of the file within the Phar archive.

### Fehler/Exceptions

Throws BadMethodCallException if the file has not yet had its CRC32 verified. This should be impossible with normal use, as the CRC is verified upon opening the file for reading or writing.

### Beispiele

Beispiel #1 A PharFileInfo::getCRC32() example

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        echo $file->getCRC32();
    } catch (Exception $e) {
        echo 'Write operations on my.phar.phar failed: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3633523372

# PharFileInfo::getCompressedSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCompressedSize — Returns the actual size of the file (with compression) inside the Phar archive

### Beschreibung

public function PharFileInfo::getCompressedSize(): int

This returns the size of the file within the Phar archive. Uncompressed files will return the same value for getCompressedSize as they will with filesize()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The size in bytes of the file within the Phar archive on disk.

### Beispiele

Beispiel #1 A PharFileInfo::getCompressedSize() example

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        echo $file->getCompressedSize();
    } catch (Exception $e) {
        echo 'Write operations failed on my.phar: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2

### Siehe auch

- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compressFiles() - Compresses all files in the current Phar archive

# PharFileInfo::getContent

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PharFileInfo::getContent — Get the complete file contents of the entry

### Beschreibung

public function PharFileInfo::getContent(): string

This function behaves like file_get_contents() but for Phar.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the file contents.

# PharFileInfo::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getMetadata — Returns file-specific meta-data saved with a file

### Beschreibung

public function PharFileInfo::getMetadata(array `$unserializeOptions` = []): mixed

Return meta-data that was saved in the Phar archive's manifest for this file.

### Parameter-Liste

### Rückgabewerte

any PHP variable that can be serialized and is stored as meta-data for the file, or `null` if no meta-data is stored.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | The parameter `unserializeOptions` has been added.

### Beispiele

Beispiel #1 A PharFileInfo::getMetadata() example

    <?php
    // make sure it doesn't exist
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.txt'] = 'hello';
        $p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
        var_dump($p['file.txt']->getMetadata());
    } catch (Exception $e) {
        echo 'Could not create/modify brandnewphar.phar: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      ["user"]=>
      string(4) "bill"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Siehe auch

- PharFileInfo::setMetadata() - Sets file-specific meta-data saved with a file
- PharFileInfo::hasMetadata() - Returns the metadata of the entry
- PharFileInfo::delMetadata() - Deletes the metadata of the entry
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data

# PharFileInfo::getPharFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getPharFlags — Returns the Phar file entry flags

### Beschreibung

public function PharFileInfo::getPharFlags(): int

This returns the flags set in the manifest for a Phar. This will always return `0` in the current implementation.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The Phar flags (always `0` in the current implementation)

### Beispiele

Beispiel #1 A PharFileInfo::getPharFlags() example

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        var_dump($file->getPharFlags());
    } catch (Exception $e) {
        echo 'Could not create/modify my.phar: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)

# PharFileInfo::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::hasMetadata — Returns the metadata of the entry

### Beschreibung

public function PharFileInfo::hasMetadata(): bool

Returns the metadata of a file within a phar archive.

### Parameter-Liste

No parameters.

### Rückgabewerte

Returns `false` if no metadata is set or is `null`, `true` if metadata is not `null`

### Siehe auch

- PharFileInfo::setMetadata() - Sets file-specific meta-data saved with a file
- PharFileInfo::getMetadata() - Returns file-specific meta-data saved with a file
- PharFileInfo::delMetadata() - Deletes the metadata of the entry
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data

# PharFileInfo::isCRCChecked

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCRCChecked — Returns whether file entry has had its CRC verified

### Beschreibung

public function PharFileInfo::isCRCChecked(): bool

This returns whether a file within a Phar archive has had its CRC verified.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

`true` if the file has had its CRC verified, `false` if not.

### Beispiele

Beispiel #1 A PharFileInfo::isCRCChecked() example

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $file = $p['myfile.txt'];
        var_dump($file->isCRCChecked());
    } catch (Exception $e) {
        echo 'Create/modify operations failed on my.phar: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

# PharFileInfo::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCompressed — Returns whether the entry is compressed

### Beschreibung

public function PharFileInfo::isCompressed(?int `$compression` = `null`): bool

This returns whether a file is compressed within a Phar archive with either Gzip or Bzip2 compression.

### Parameter-Liste

`compression`

  One of `Phar::GZ` or `Phar::BZ2`, defaults to any compression.

### Rückgabewerte

`true` if the file is compressed within the Phar archive, `false` if not.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `compression` is now nullable.

### Beispiele

Beispiel #1 A PharFileInfo::isCompressed() example

    <?php
    try {
        $p = new Phar('/path/to/my.phar', 0, 'my.phar');
        $p['myfile.txt'] = 'hi';
        $p['myfile2.txt'] = 'hi';
        $p['myfile2.txt']->setCompressedGZ();
        $file = $p['myfile.txt'];
        $file2 = $p['myfile2.txt'];
        var_dump($file->isCompressed());
        var_dump($file2->isCompressed());
    } catch (Exception $e) {
        echo 'Create/modify on phar my.phar failed: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)

### Siehe auch

- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compressFiles() - Compresses all files in the current Phar archive

# PharFileInfo::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::setMetadata — Sets file-specific meta-data saved with a file

### Beschreibung

public function PharFileInfo::setMetadata(mixed `$metadata`): void

PharFileInfo::setMetadata() should only be used to store customized data in a file that cannot be represented with existing information stored with a file. Meta-data can significantly slow down the performance of loading a phar archive if the data is large, or if there are many files containing meta-data. It is important to note that file permissions are natively supported inside a phar; it is possible to set them with the PharFileInfo::chmod() method. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.

Some possible uses for meta-data include passing a user/group that should be set when a file is extracted from the phar to disk. Other uses could include explicitly specifying a MIME type to return. However, any useful data that describes a file, but should not be contained inside of it may be stored.

### Parameter-Liste

`metadata`

  Any PHP variable containing information to store alongside a file

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 A PharFileInfo::setMetadata() example

    <?php
    // make sure it doesn't exist
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
        $p['file.txt'] = 'hello';
        $p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
        var_dump($p['file.txt']->getMetaData());
    } catch (Exception $e) {
        echo 'Could not create/modify phar: ', $e;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      ["user"]=>
      string(4) "bill"
      ["mime-type"]=>
      string(10) "text/plain"
    }

### Siehe auch

- PharFileInfo::hasMetadata() - Returns the metadata of the entry
- PharFileInfo::getMetadata() - Returns file-specific meta-data saved with a file
- PharFileInfo::delMetadata() - Deletes the metadata of the entry
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data

## Inhaltsverzeichnis

- PharFileInfo::chmod — Sets file-specific permission bits
- PharFileInfo::compress — Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::__construct — Construct a Phar entry object
- PharFileInfo::decompress — Decompresses the current Phar entry within the phar
- PharFileInfo::delMetadata — Deletes the metadata of the entry
- PharFileInfo::__destruct — Destructs a Phar entry object
- PharFileInfo::getCRC32 — Returns CRC32 code or throws an exception if CRC has not been verified
- PharFileInfo::getCompressedSize — Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::getContent — Get the complete file contents of the entry
- PharFileInfo::getMetadata — Returns file-specific meta-data saved with a file
- PharFileInfo::getPharFlags — Returns the Phar file entry flags
- PharFileInfo::hasMetadata — Returns the metadata of the entry
- PharFileInfo::isCRCChecked — Returns whether file entry has had its CRC verified
- PharFileInfo::isCompressed — Returns whether the entry is compressed
- PharFileInfo::setMetadata — Sets file-specific meta-data saved with a file

# The PharException class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## Einführung

The PharException class provides a phar-specific exception class for try/catch blocks.

## Klassenbeschreibung

class PharException extends Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Using Phar Archives
  - Using Phar Archives: Introduction
  - Using Phar Archives: the phar stream wrapper
  - Using Phar Archives: the Phar and PharData class
- Creating Phar Archives
  - Creating Phar Archives: Introduction
- What makes a phar a phar and not a tar or a zip?
  - Ingredients of all Phar archives, independent of file format
  - Phar file stub
  - Head-to-head comparison of Phar, Tar and Zip
  - Tar-based phars
  - Zip-based phars
  - Phar File Format
  - Global Phar bitmapped flags
  - Phar manifest file entry definition
  - Phar Signature format
- Phar — Die Klasse Phar
  - Phar::addEmptyDir — Add an empty directory to the phar archive
  - Phar::addFile — Add a file from the filesystem to the phar archive
  - Phar::addFromString — Add a file from a string to the phar archive
  - Phar::apiVersion — Returns the api version
  - Phar::buildFromDirectory — Construct a phar archive from the files within a directory
  - Phar::buildFromIterator — Construct a phar archive from an iterator
  - Phar::canCompress — Returns whether phar extension supports compression using either zlib or bzip2
  - Phar::canWrite — Returns whether phar extension supports writing and creating phars
  - Phar::compress — Compresses the entire Phar archive using Gzip or Bzip2 compression
  - Phar::compressFiles — Compresses all files in the current Phar archive
  - Phar::__construct — Construct a Phar archive object
  - Phar::convertToData — Convert a phar archive to a non-executable tar or zip file
  - Phar::convertToExecutable — Convert a phar archive to another executable phar archive file format
  - Phar::copy — Copy a file internal to the phar archive to another new file within the phar
  - Phar::count — Returns the number of entries (files) in the Phar archive
  - Phar::createDefaultStub — Create a phar-file format specific stub
  - Phar::decompress — Decompresses the entire Phar archive
  - Phar::decompressFiles — Decompresses all files in the current Phar archive
  - Phar::delMetadata — Deletes the global metadata of the phar
  - Phar::delete — Delete a file within a phar archive
  - Phar::__destruct — Destructs a Phar archive object
  - Phar::extractTo — Extract the contents of a phar archive to a directory
  - Phar::getAlias — Get the alias for Phar
  - Phar::getMetadata — Returns phar archive meta-data
  - Phar::getModified — Return whether phar was modified
  - Phar::getPath — Get the real path to the Phar archive on disk
  - Phar::getSignature — Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
  - Phar::getStub — Return the PHP loader or bootstrap stub of a Phar archive
  - Phar::getSupportedCompression — Return array of supported compression algorithms
  - Phar::getSupportedSignatures — Return array of supported signature types
  - Phar::getVersion — Return version info of Phar archive
  - Phar::hasMetadata — Returns whether phar has global meta-data
  - Phar::interceptFileFuncs — Instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
  - Phar::isBuffering — Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
  - Phar::isCompressed — Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
  - Phar::isFileFormat — Returns true if the phar archive is based on the tar/phar/zip file format depending on the parameter
  - Phar::isValidPharFilename — Returns whether the given filename is a valid phar filename
  - Phar::isWritable — Returns true if the phar archive can be modified
  - Phar::loadPhar — Loads any phar archive with an alias
  - Phar::mapPhar — Reads the currently executed file (a phar) and registers its manifest
  - Phar::mount — Mount an external path or file to a virtual location within the phar archive
  - Phar::mungServer — Defines a list of up to 4 $_SERVER variables that should be modified for execution
  - Phar::offsetExists — Determines whether a file exists in the phar
  - Phar::offsetGet — Gets a PharFileInfo object for a specific file
  - Phar::offsetSet — Set the contents of an internal file to those of an external file
  - Phar::offsetUnset — Remove a file from a phar
  - Phar::running — Returns the full path on disk or full phar URL to the currently executing Phar archive
  - Phar::setAlias — Set the alias for the Phar archive
  - Phar::setDefaultStub — Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
  - Phar::setMetadata — Sets phar archive meta-data
  - Phar::setSignatureAlgorithm — Set the signature algorithm for a phar and apply it
  - Phar::setStub — Used to set the PHP loader or bootstrap stub of a Phar archive
  - Phar::startBuffering — Start buffering Phar write operations, do not modify the Phar object on disk
  - Phar::stopBuffering — Stop buffering write requests to the Phar archive, and save changes to disk
  - Phar::unlinkArchive — Completely remove a phar archive from disk and from memory
  - Phar::webPhar — Routes a request from a web browser to an internal file within the phar archive
- PharData — The PharData class
  - PharData::addEmptyDir — Add an empty directory to the tar/zip archive
  - PharData::addFile — Add a file from the filesystem to the tar/zip archive
  - PharData::addFromString — Add a file from a string to the tar/zip archive
  - PharData::buildFromDirectory — Construct a tar/zip archive from the files within a directory
  - PharData::buildFromIterator — Construct a tar or zip archive from an iterator
  - PharData::compress — Compresses the entire tar/zip archive using Gzip or Bzip2 compression
  - PharData::compressFiles — Compresses all files in the current tar/zip archive
  - PharData::__construct — Construct a non-executable tar or zip archive object
  - PharData::convertToData — Convert a phar archive to a non-executable tar or zip file
  - PharData::convertToExecutable — Convert a non-executable tar/zip archive to an executable phar archive
  - PharData::copy — Copy a file internal to the tar/zip archive to another new file within the same archive
  - PharData::decompress — Decompresses the entire Phar archive
  - PharData::decompressFiles — Decompresses all files in the current zip archive
  - PharData::delMetadata — Deletes the global metadata of a zip archive
  - PharData::delete — Delete a file within a tar/zip archive
  - PharData::__destruct — Destructs a non-executable tar or zip archive object
  - PharData::extractTo — Extract the contents of a tar/zip archive to a directory
  - PharData::isWritable — Returns true if the tar/zip archive can be modified
  - PharData::offsetSet — Set the contents of a file within the tar/zip to those of an external file or string
  - PharData::offsetUnset — Remove a file from a tar/zip archive
  - PharData::setAlias — Dummy function (Phar::setAlias is not valid for PharData)
  - PharData::setDefaultStub — Dummy function (Phar::setDefaultStub is not valid for PharData)
  - PharData::setMetadata — Sets phar archive meta-data
  - PharData::setSignatureAlgorithm — Set the signature algorithm for a phar and apply it
  - PharData::setStub — Dummy function (Phar::setStub is not valid for PharData)
- PharFileInfo — The PharFileInfo class
  - PharFileInfo::chmod — Sets file-specific permission bits
  - PharFileInfo::compress — Compresses the current Phar entry with either zlib or bzip2 compression
  - PharFileInfo::__construct — Construct a Phar entry object
  - PharFileInfo::decompress — Decompresses the current Phar entry within the phar
  - PharFileInfo::delMetadata — Deletes the metadata of the entry
  - PharFileInfo::__destruct — Destructs a Phar entry object
  - PharFileInfo::getCRC32 — Returns CRC32 code or throws an exception if CRC has not been verified
  - PharFileInfo::getCompressedSize — Returns the actual size of the file (with compression) inside the Phar archive
  - PharFileInfo::getContent — Get the complete file contents of the entry
  - PharFileInfo::getMetadata — Returns file-specific meta-data saved with a file
  - PharFileInfo::getPharFlags — Returns the Phar file entry flags
  - PharFileInfo::hasMetadata — Returns the metadata of the entry
  - PharFileInfo::isCRCChecked — Returns whether file entry has had its CRC verified
  - PharFileInfo::isCompressed — Returns whether the entry is compressed
  - PharFileInfo::setMetadata — Sets file-specific meta-data saved with a file
- PharException — The PharException class

# Rar Archiving

# Einführung

RAR ist ein von Eugene Roshal erstellter machtvoller und effektiver Archiver. Diese Erweiterung erlaubt es, RAR-Archive auszulesen, aber nicht, diese zu erstellen, da dies von der UnRAR-Bibliothek nicht unterstützt und auch durch dessen Lizenz direkt verboten ist.

Mehr Information über RAR und UnRAR kann unter » http://www.rarlabs.com/ gefunden werden.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Ressource-Typen

## Installation

RAR ist aktuell verfügbar durch PECL » https://pecl.php.net/package/rar.

Sie können den PECL-Installer benutzen, um die RAR-Erweiterung zu installieren, mit diesem Befehl: pecl -v install rar.

Sie können jederzeit das tar.gz-Paket herunterladen und RAR manuell installieren.:

Beispiel #1 Rar Installation

    gunzip rar-xxx.tgz
    tar -xvf rar-xxx.tar
    cd rar-xxx
    phpize
    ./configure && make && make install

Windows-Benutzer müssen php_rar.dll in der php.ini aktivieren, um diese Funktionen verwenden zu können.

## Ressource-Typen

Diese Erweiterung registriert drei interne Klassen: die von rar_open() zurückgegebenen Archiv-Darstellungen - RarArchive, die von rar_list() und rar_entry_get() zurückgegebenen Eintragsdarstellungen - RarEntry und den Exception-Typ RarException.

Diese Erweiterung registriert auch eine Stream-Ressource, "rar" genannt und einen URL-Wrapper, "rar wrapper" genannt, registriert unter dem Präfix "rar".

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`RAR_HOST_MSDOS` (int)
  Use `RarEntry::HOST_MSDOS` instead.
`RAR_HOST_OS2` (int)
  Use `RarEntry::HOST_OS2` instead.
`RAR_HOST_WIN32` (int)
  Use `RarEntry::HOST_WIN32` instead.
`RAR_HOST_UNIX` (int)
  Use `RarEntry::HOST_UNIX` instead.
`RAR_HOST_BEOS` (int)
  Use `RarEntry::HOST_BEOS` instead.

# Beispiele

See also the examples under `rar://` wrapper.

Beispiel #1 On-the-fly decompression

    <?php

    if (!array_key_exists("i", $_GET) || !is_numeric($_GET["i"]))
        die("Index unspecified or non-numeric");
    $index = (int) $_GET["i"];

    $arch = RarArchive::open("example.rar");
    if ($arch === FALSE)
        die("Cannot open example.rar");

    $entries = $arch->getEntries();
    if ($entries === FALSE)
        die("Cannot retrieve entries");

    if (!array_key_exists($index, $entries))
        die("No such index: $index");

    $orfilename = $entries[$index]->getName(); //UTF-8 encoded

    $filesize = $entries[$index]->getUnpackedSize();

    /* you could check HTTP_IF_MODIFIED_SINCE here and compare with
     * $entries[$index]->getFileTime(). You could also send a
     * "Last modified" header */

    $fp = $entries[$index]->getStream();
    if ($fp === FALSE)
        die("Cannot open file with index $index insided the archive.");

    $arch->close(); //no longer needed; stream is independent

    function detectUserAgent() {
        if (!array_key_exists('HTTP_USER_AGENT', $_SERVER))
            return "Other";

        $uas = $_SERVER['HTTP_USER_AGENT'];
        if (preg_match("@Opera/@", $uas))
            return "Opera";
        if (preg_match("@Firefox/@", $uas))
            return "Firefox";
        if (preg_match("@Chrome/@", $uas))
            return "Chrome";
        if (preg_match("@MSIE ([0-9.]+);@", $uas, $matches)) {
            if (((float) $matches[1]) >= 7.0)
                return "IE";
        }

        return "Other";
    }

    /*
     * We have 3 options:
     * - For FF and Opera, which support RFC 2231, use that format.
     * - For IE and Chrome, use attwithfnrawpctenclong
     *   (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
     * - For the others, convert to ISO-8859-1, if possible
     */
    $formatRFC2231 = 'Content-Disposition: attachment; filename*=UTF-8\'\'%s';
    $formatDef = 'Content-Disposition: attachment; filename="%s"';

    switch (detectUserAgent()) {
        case "Opera":
        case "Firefox":
            $orfilename = rawurlencode($orfilename);
            $format = $formatRFC2231;
            break;

        case "IE":
        case "Chrome":
            $orfilename = rawurlencode($orfilename);
            $format = $formatDef;
            break;
        default:
            if (function_exists('iconv'))
                $orfilename =
                    @iconv("UTF-8", "ISO-8859-1//TRANSLIT", $orfilename);
            $format = $formatDef;
    }

    header(sprintf($format, $orfilename));
    //cannot send error messages from now on (headers already sent)

    //replace by real content type, perhaps infering from the file extension
    $contentType = "application/octet-stream";
    header("Content-Type: $contentType");

    header("Content-Transfer-Encoding: binary");

    header("Content-Length: $filesize");

    if ($_SERVER['REQUEST_METHOD'] == "HEAD")
        die();

    while (!feof($fp)) {
        $s = @fread($fp, 8192);
        if ($s === false)
            break; //useless to send error messages

        echo $s;
    }
    ?>

This example opens a RAR file and presents the requested file inside the RAR archive for download to the client.

Beispiel #2 RAR extension filesystem extraction example

    <?php

    $rar_file = rar_open('example.rar') or die("Can't open Rar archive");

    $entries = rar_list($rar_file);

    foreach ($entries as $entry) {
        echo 'Filename: ' . $entry->getName() . "\n";
        echo 'Packed size: ' . $entry->getPackedSize() . "\n";
        echo 'Unpacked size: ' . $entry->getUnpackedSize() . "\n";

        $entry->extract('/dir/extract/to/');
    }

    rar_close($rar_file);

    ?>

This example opens a RAR file archive and extracts each entry to the specified directory.

# RAR Funktionen

# rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_stats — Cache-Treffer und -Fehlschläge für den URL-Wrapper

### Beschreibung

function rar_wrapper_cache_stats(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

## Inhaltsverzeichnis

- rar_wrapper_cache_stats — Cache-Treffer und -Fehlschläge für den URL-Wrapper

# The RarArchive class

(PECL rar >= 2.0.0)

## Einführung

This class represents a RAR archive, which may be formed by several volumes (parts) and which contains a number of RAR entries (i.e., files, directories and other special objects such as symbolic links).

Objects of this class can be traversed, yielding the entries stored in the respective RAR archive. Those entries can also be obtained through RarArchive::getEntry() and RarArchive::getEntries().

## Klassenbeschreibung

final class RarArchive implements Traversable {
/* Methoden */
public function close(): bool
public function getComment(): string
public function getEntries(): array|false
public function getEntry(string `$entryname`): RarEntry|false
public function isBroken(): bool
public function isSolid(): bool
public static function open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false
public function setAllowBroken(bool `$allow_broken`): bool
public function __toString(): string
}

# RarArchive::close

# rar_close

(PECL rar >= 2.0.0)

RarArchive::close -- rar_close — Close RAR archive and free all resources

### Beschreibung

Objektorientierter Stil (method):

public function RarArchive::close(): bool

Prozeduraler Stil:

function rar_close(RarArchive `$rarfile`): bool

Close RAR archive and free all allocated resources.

### Parameter-Liste

`rarfile`
  A RarArchive object, opened with rar_open().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL rar 2.0.0 | The RAR entries returned by RarArchive::getEntry() and RarArchive::getEntries() are now invalidated when calling this method. This means that all instance methods called for such entries and not guaranteed to succeed.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

Beispiel #2 Prozeduraler Stil

    <?php
    $rar_arch = rar_open('latest_winrar.rar');
    echo $rar_arch."\n";
    rar_close($rar_arch);
    echo $rar_arch."\n";
    ?>

# RarArchive::getComment

# rar_comment_get

(PECL rar >= 2.0.0)

RarArchive::getComment -- rar_comment_get — Get comment text from the RAR archive

### Beschreibung

Objektorientierter Stil (method):

public function RarArchive::getComment(): string

Prozeduraler Stil:

function rar_comment_get(RarArchive `$rarfile`): string

Get the (global) comment stored in the RAR archive. It may be up to 64 KiB long.

> Hinweis: This extension does not support comments at the entry level.

### Parameter-Liste

`rarfile`
  A RarArchive object, opened with rar_open().

### Rückgabewerte

Returns the comment or `null` if there is none.

> Hinweis: RAR has currently no support for unicode comments. The encoding of the result of this function is not specified, but it will probably be Windows-1252.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $rar_arch = RarArchive::open('commented.rar');
    echo $rar_arch->getComment();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    This is the comment of the file commented.rar.

Beispiel #2 Prozeduraler Stil

    <?php
    $rar_arch = rar_open('commented.rar');
    echo rar_comment_get($rar_arch);
    ?>

# RarArchive::getEntries

# rar_list

(PECL rar >= 2.0.0)

RarArchive::getEntries -- rar_list — Get full list of entries from the RAR archive

### Beschreibung

Objektorientierter Stil (method):

public function RarArchive::getEntries(): array|false

Prozeduraler Stil:

function rar_list(RarArchive `$rarfile`): array|false

Get entries list (files and directories) from the RAR archive.

> Hinweis: If the archive has entries with the same name, this method, together with RarArchive `foreach` iteration and array-like access with numeric indexes, are the only ones to access all the entries (i.e., RarArchive::getEntry() and the `rar://` wrapper are insufficient).

### Parameter-Liste

`rarfile`
  A RarArchive object, opened with rar_open().

### Rückgabewerte

rar_list() returns array of RarEntry objects Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
PECL rar 3.0.0 | Support for RAR archives with repeated entry names is no longer defective.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Could not open RAR archive.");

    $rar_entries = $rar_arch->getEntries();
    if ($rar_entries === FALSE)
        die("Could not retrieve entries.");

    echo "Found " . count($rar_entries) . " entries.\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    $rar_arch->close();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Found 2 entries.
    RarEntry for file "tese.txt" (23b93a7a)
    RarEntry for file "unrardll.txt" (2ed64b6e)

Beispiel #2 Prozeduraler Stil

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Could not open RAR archive.");

    $rar_entries = rar_list($rar_arch);
    if ($rar_entries === FALSE)
        die("Could retrieve entries.");

    echo "Found " . count($rar_entries) . " entries.\n";

    foreach ($rar_entries as $e) {
        echo $e;
        echo "\n";
    }
    rar_close($rar_arch);
    ?>

### Siehe auch

- RarArchive::getEntry() - Get entry object from the RAR archive
- `rar://` wrapper

# RarArchive::getEntry

# rar_entry_get

(PECL rar >= 2.0.0)

RarArchive::getEntry -- rar_entry_get — Get entry object from the RAR archive

### Beschreibung

Objektorientierter Stil (method):

public function RarArchive::getEntry(string `$entryname`): RarEntry|false

Prozeduraler Stil:

function rar_entry_get(RarArchive `$rarfile`, string `$entryname`): RarEntry|false

Get entry object (file or directory) from the RAR archive.

> Hinweis: You can also get entry objects using RarArchive::getEntries(). Note that a RAR archive can have multiple entries with the same name; this method will retrieve only the first.

### Parameter-Liste

`rarfile`
  A RarArchive object, opened with rar_open().
`entryname`
  Path to the entry within the RAR archive.

  > Hinweis: The path must be the same returned by RarEntry::getName().

### Rückgabewerte

Returns the matching RarEntry object Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $rar_arch = RarArchive::open('solid.rar');
    if ($rar_arch === FALSE)
        die("Could not open RAR archive.");
    $rar_entry = $rar_arch->getEntry('tese.txt');
    if ($rar_entry === FALSE)
        die("Could not get such entry");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    $rar_arch->close();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    RarEntry
    RarEntry for file "tese.txt" (23b93a7a)

Beispiel #2 Prozeduraler Stil

    <?php
    $rar_arch = rar_open('solid.rar');
    if ($rar_arch === FALSE)
        die("Could not open RAR archive.");
    $rar_entry = rar_entry_get($rar_arch, 'tese.txt');
    if ($rar_entry === FALSE)
        die("Could not get such entry");
    echo get_class($rar_entry)."\n";
    echo $rar_entry;
    rar_close($rar_arch);
    ?>

### Siehe auch

- RarArchive::getEntries() - Get full list of entries from the RAR archive
- `rar://` wrapper

# RarArchive::isBroken

# rar_broken_is

(PECL rar >= 3.0.0)

RarArchive::isBroken -- rar_broken_is — Test whether an archive is broken (incomplete)

### Beschreibung

Objektorientierter Stil (method):

public function RarArchive::isBroken(): bool

Prozeduraler Stil:

function rar_broken_is(RarArchive `$rarfile`): bool

This function determines whether an archive is incomplete, i.e., if a volume is missing or a volume is truncated.

### Parameter-Liste

`rarfile`
  A RarArchive object, opened with rar_open().

### Rückgabewerte

Returns `true` if the archive is broken, `false` otherwise. This function may also return `false` if the passed file has already been closed. The only way to tell the two cases apart is to enable exceptions with RarException::setUsingExceptions(); however, this should be unnecessary as a program should not operate on closed files.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* Third argument is used to omit notice */
    $arch = RarArchive::open($file, null, 'retnull');
    var_dump($arch->isBroken());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    bool(true)

Beispiel #2 Prozeduraler Stil

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* Third argument is used to omit notice */
    $arch = rar_open($file, null, 'retnull');
    var_dump(rar_broken_is($arch));
    ?>

### Siehe auch

- RarArchive::setAllowBroken() - Whether opening broken archives is allowed

# RarArchive::isSolid

# rar_solid_is

(PECL rar >= 2.0.0)

RarArchive::isSolid -- rar_solid_is — Check whether the RAR archive is solid

### Beschreibung

Objektorientierter Stil (method):

public function RarArchive::isSolid(): bool

Prozeduraler Stil:

function rar_solid_is(RarArchive `$rarfile`): bool

Check whether the RAR archive is solid. Individual file extraction is slower on solid archives.

### Parameter-Liste

`rarfile`
  A RarArchive object, opened with rar_open().

### Rückgabewerte

Returns `true` if the archive is solid, `false` otherwise.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $arch1 = RarArchive::open("store_method.rar");
    $arch2 = RarArchive::open("solid.rar");
    echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
    echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
    RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes

Beispiel #2 Prozeduraler Stil

    <?php
    $arch1 = rar_open("store_method.rar");
    $arch2 = rar_open("solid.rar");
    echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
    echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
    ?>

# RarArchive::open

# rar_open

(PECL rar >= 2.0.0)

RarArchive::open -- rar_open — Open RAR archive

### Beschreibung

Objektorientierter Stil (method):

public static function RarArchive::open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Prozeduraler Stil:

function rar_open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

Open specified RAR archive and return RarArchive instance representing it.

> Hinweis: If opening a multi-volume archive, the path of the first volume should be passed as the first parameter. Otherwise, not all files will be shown. This is by design.

### Parameter-Liste

`filename`
  Path to the Rar archive.
`password`
  A plain password, if needed to decrypt the headers. It will also be used by default if encrypted files are found. Note that the files may have different passwords in respect to the headers and among them.
`volume_callback`
  A function that receives one parameter – the path of the volume that was not found – and returns a string with the correct path for such volume or `null` if such volume does not exist or is not known. The programmer should ensure the passed function doesn't cause loops as this function is called repeatedly if the path returned in a previous call did not correspond to the needed volume. Specifying this parameter omits the notice that would otherwise be emitted whenever a volume is not found; an implementation that only returns `null` can therefore be used to merely omit such notices.

Warnung

Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath() as a workaround.

### Rückgabewerte

Returns the requested RarArchive instance Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
PECL rar 3.0.0 | `volume_callback` was added.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Failed opening file");

    $entries = $rar_arch->getEntries();
    if ($entries === FALSE)
        die("Failed fetching entries");

    echo "Found " . count($entries) . " files.\n";

    if (empty($entries))
        die("No valid entries found.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Failed opening first file");

    $rar_arch->close();

    echo "Content of first one follows:\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Found 2 files.
    Content of first one follows:
    Encrypted file 1 contents.

Beispiel #2 Prozeduraler Stil

    <?php
    $rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
    if ($rar_arch === FALSE)
        die("Failed opening file");

    $entries = rar_list($rar_arch);
    if ($entries === FALSE)
        die("Failed fetching entries");

    echo "Found " . count($entries) . " files.\n";

    if (empty($entries))
        die("No valid entries found.");

    $stream = reset($entries)->getStream();
    if ($stream === FALSE)
        die("Failed opening first file");

    rar_close($rar_arch);

    echo "Content of first one follows:\n";
    echo stream_get_contents($stream);

    fclose($stream);
    ?>

Beispiel #3 Volume Callback

    <?php
    /* In this example, there's a volume named multi_broken.part1.rar
     * whose next volume is named multi.part2.rar */
    function resolve($vol) {
        if (preg_match('/_broken/', $vol))
            return str_replace('_broken', '', $vol);
        else
            return null;
    }
    $rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
    $entry = $rar_file1->getEntry('file2.txt');
    $entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
    ?>

### Siehe auch

- `rar://` wrapper

# RarArchive::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBroken — Whether opening broken archives is allowed

### Beschreibung

Objektorientierter Stil (method):

public function RarArchive::setAllowBroken(bool `$allow_broken`): bool

Prozeduraler Stil:

function rar_allow_broken_set(RarArchive `$rarfile`, bool `$allow_broken`): bool

This method defines whether broken archives can be read or all the operations that attempt to extract the archive entries will fail. Broken archives are archives for which no error is detected when the file is opened but an error occurs when reading the entries.

### Parameter-Liste

`rarfile`
  A RarArchive object, opened with rar_open().
`allow_broken`
  Whether to allow reading broken files (`true`) or not (`false`).

### Rückgabewerte

Returns `true` Bei einem Fehler wird `false` zurückgegeben.. It will only fail if the file has already been closed.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* Third argument omits "volume not found" message */
    $a = RarArchive::open($file, null, 'retnull');
    $a->setAllowBroken(true);
    foreach ($a->getEntries() as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    RarEntry for file "file1.txt" (52b28202)
    int(1)

Beispiel #2 Prozeduraler Stil

    <?php
    function retnull() { return null; }
    $file = dirname(__FILE__) . "/multi_broken.part1.rar";
    /* Third argument omits "volume not found" message */
    $a = rar_open($file, null, 'retnull');
    rar_allow_broken_set($a, true);
    foreach (rar_list($a) as $e) {
        echo "$e\n";
    }
    var_dump(count($a));
    ?>

### Siehe auch

- RarArchive::isBroken() - Test whether an archive is broken (incomplete)

# RarArchive::__toString

(PECL rar >= 2.0.0)

RarArchive::__toString — Get text representation

### Beschreibung

public function RarArchive::__toString(): string

Provides a string representation for this RarArchive object. It currently shows the full path name of the archive volume that was opened and whether the resource is valid or was already closed through a call to RarArchive::close().

This method may be used only for debugging purposes, as there are no guarantees as to which information the result contains or how it is formatted.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

A textual representation of this RarArchive object. The content of this representation is unspecified.

### Beispiele

Beispiel #1 RarArchive::__toString() example

    <?php
    $rar_arch = RarArchive::open('latest_winrar.rar');
    echo $rar_arch."\n";
    $rar_arch->close();
    echo $rar_arch."\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
    RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

## Inhaltsverzeichnis

- RarArchive::close — Close RAR archive and free all resources
- RarArchive::getComment — Get comment text from the RAR archive
- RarArchive::getEntries — Get full list of entries from the RAR archive
- RarArchive::getEntry — Get entry object from the RAR archive
- RarArchive::isBroken — Test whether an archive is broken (incomplete)
- RarArchive::isSolid — Check whether the RAR archive is solid
- RarArchive::open — Open RAR archive
- RarArchive::setAllowBroken — Whether opening broken archives is allowed
- RarArchive::__toString — Get text representation

# The RarEntry class

(PECL rar >= 0.1)

## Einführung

A RAR entry, representing a directory or a compressed file inside a RAR archive.

## Klassenbeschreibung

final class RarEntry {
/* Konstanten */
const int HOST_MSDOS = 0;
const int HOST_OS2 = 1;
const int HOST_WIN32 = 2;
const int HOST_UNIX = 3;
const int HOST_MACOS = 4;
const int HOST_BEOS = 5;
const int ATTRIBUTE_WIN_READONLY = 1;
const int ATTRIBUTE_WIN_HIDDEN = 2;
const int ATTRIBUTE_WIN_SYSTEM = 4;
const int ATTRIBUTE_WIN_DIRECTORY = 16;
const int ATTRIBUTE_WIN_ARCHIVE = 32;
const int ATTRIBUTE_WIN_DEVICE = 64;
const int ATTRIBUTE_WIN_NORMAL = 128;
const int ATTRIBUTE_WIN_TEMPORARY = 256;
const int ATTRIBUTE_WIN_SPARSE_FILE = 512;
const int ATTRIBUTE_WIN_REPARSE_POINT = 1024;
const int ATTRIBUTE_WIN_COMPRESSED = 2048;
const int ATTRIBUTE_WIN_OFFLINE = 4096;
const int ATTRIBUTE_WIN_NOT_CONTENT_INDEXED = 8192;
const int ATTRIBUTE_WIN_ENCRYPTED = 16384;
const int ATTRIBUTE_WIN_VIRTUAL = 65536;
const int ATTRIBUTE_UNIX_WORLD_EXECUTE = 1;
const int ATTRIBUTE_UNIX_WORLD_WRITE = 2;
const int ATTRIBUTE_UNIX_WORLD_READ = 4;
const int ATTRIBUTE_UNIX_GROUP_EXECUTE = 8;
const int ATTRIBUTE_UNIX_GROUP_WRITE = 16;
const int ATTRIBUTE_UNIX_GROUP_READ = 32;
const int ATTRIBUTE_UNIX_OWNER_EXECUTE = 64;
const int ATTRIBUTE_UNIX_OWNER_WRITE = 128;
const int ATTRIBUTE_UNIX_OWNER_READ = 256;
const int ATTRIBUTE_UNIX_STICKY = 512;
const int ATTRIBUTE_UNIX_SETGID = 1024;
const int ATTRIBUTE_UNIX_SETUID = 2048;
const int ATTRIBUTE_UNIX_FINAL_QUARTET = 61440;
const int ATTRIBUTE_UNIX_FIFO = 4096;
const int ATTRIBUTE_UNIX_CHAR_DEV = 8192;
const int ATTRIBUTE_UNIX_DIRECTORY = 16384;
const int ATTRIBUTE_UNIX_BLOCK_DEV = 24576;
const int ATTRIBUTE_UNIX_REGULAR_FILE = 32768;
const int ATTRIBUTE_UNIX_SYM_LINK = 40960;
const int ATTRIBUTE_UNIX_SOCKET = 49152;
/* Methoden */
public function extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool
public function getAttr(): int
public function getCrc(): string
public function getFileTime(): string
public function getHostOs(): int
public function getMethod(): int
public function getName(): string
public function getPackedSize(): int
public function getStream(string `$password` = ?): resource|false
public function getUnpackedSize(): int
public function getVersion(): int
public function isDirectory(): bool
public function isEncrypted(): bool
public function __toString(): string
}

## Vordefinierte Konstanten

`RarEntry::HOST_MSDOS`
  If the return value of RarEntry::getHostOs() equals this constant, MS-DOS was used to add this entry. Use instead of `RAR_HOST_MSDOS`.
`RarEntry::HOST_OS2`
  If the return value of RarEntry::getHostOs() equals this constant, OS/2 was used to add this entry. Intended to replace `RAR_HOST_OS2`.
`RarEntry::HOST_WIN32`
  If the return value of RarEntry::getHostOs() equals this constant, Microsoft Windows was used to add this entry. Intended to replace `RAR_HOST_WIN32`.
`RarEntry::HOST_UNIX`
  If the return value of RarEntry::getHostOs() equals this constant, an unspecified UNIX OS was used to add this entry. Intended to replace `RAR_HOST_UNIX`.
`RarEntry::HOST_MACOS`
  If the return value of RarEntry::getHostOs() equals this constant, Mac OS was used to add this entry.
`RarEntry::HOST_BEOS`
  If the return value of RarEntry::getHostOs() equals this constant, BeOS was used to add this entry. Intended to replace `RAR_HOST_BEOS`.
`RarEntry::ATTRIBUTE_WIN_READONLY`
  Bit that represents a Windows entry with a read-only attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_HIDDEN`
  Bit that represents a Windows entry with a hidden attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_SYSTEM`
  Bit that represents a Windows entry with a system attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_DIRECTORY`
  Bit that represents a Windows entry with a directory attribute (entry is a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.
`RarEntry::ATTRIBUTE_WIN_ARCHIVE`
  Bit that represents a Windows entry with an archive attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_DEVICE`
  Bit that represents a Windows entry with a device attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_NORMAL`
  Bit that represents a Windows entry with a normal file attribute (entry is NOT a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.
`RarEntry::ATTRIBUTE_WIN_TEMPORARY`
  Bit that represents a Windows entry with a temporary attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_SPARSE_FILE`
  Bit that represents a Windows entry with a sparse file attribute (file is an NTFS sparse file). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_REPARSE_POINT`
  Bit that represents a Windows entry with a reparse point attribute (entry is an NTFS reparse point, e.g. a directory junction or a mount file system). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_COMPRESSED`
  Bit that represents a Windows entry with a compressed attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_OFFLINE`
  Bit that represents a Windows entry with an offline attribute (entry is offline and not accessible). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED`
  Bit that represents a Windows entry with a not content indexed attribute (entry is to be indexed). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_ENCRYPTED`
  Bit that represents a Windows entry with an encrypted attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_WIN_VIRTUAL`
  Bit that represents a Windows entry with a virtual attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
`RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE`
  Bit that represents a UNIX entry that is world executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE`
  Bit that represents a UNIX entry that is world writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_WORLD_READ`
  Bit that represents a UNIX entry that is world readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE`
  Bit that represents a UNIX entry that is group executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE`
  Bit that represents a UNIX entry that is group writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_GROUP_READ`
  Bit that represents a UNIX entry that is group readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE`
  Bit that represents a UNIX entry that is owner executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE`
  Bit that represents a UNIX entry that is owner writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_OWNER_READ`
  Bit that represents a UNIX entry that is owner readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_STICKY`
  Bit that represents the UNIX sticky bit. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETGID`
  Bit that represents the UNIX setgid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_SETUID`
  Bit that represents the UNIX setuid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
`RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`
  Mask to isolate the last four bits (nibble) of UNIX attributes (_S_IFMT, the type of file mask). To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constants `RarEntry::ATTRIBUTE_UNIX_FIFO`, `RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`, `RarEntry::ATTRIBUTE_UNIX_DIRECTORY`, `RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`, `RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`, `RarEntry::ATTRIBUTE_UNIX_SYM_LINK` and `RarEntry::ATTRIBUTE_UNIX_SOCKET`.
`RarEntry::ATTRIBUTE_UNIX_FIFO`
  Unix FIFOs will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_CHAR_DEV`
  Unix character devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_DIRECTORY`
  Unix directories will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems.
`RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV`
  Unix block devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE`
  Unix regular files (not directories) will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems.
`RarEntry::ATTRIBUTE_UNIX_SYM_LINK`
  Unix symbolic links will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.
`RarEntry::ATTRIBUTE_UNIX_SOCKET`
  Unix sockets will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant `RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET`.

# RarEntry::extract

(PECL rar >= 0.1)

RarEntry::extract — Extract entry from the archive

### Beschreibung

public function RarEntry::extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool

RarEntry::extract() extracts the entry's data. It will create new file in the specified `dir` with the name identical to the entry's name, unless the second argument is specified. See below for more information.

### Parameter-Liste

`dir`
  Path to the directory where files should be extracted. This parameter is considered if and only if `filepath` is not. If both parameters are empty an extraction to the current directory will be attempted.
`filepath`
  Path (relative or absolute) containing the directory and filename of the extracted file. This parameter overrides both the parameter `dir` and the original file name.
`password`
  The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can be omitted. If this parameter is omitted and the entry is encrypted, the password given to rar_open(), if any, will be used. If a wrong password is given, either explicitly or implicitly via rar_open(), CRC checking will fail and this method will fail and return `false`. If no password is given and one is required, this method will fail and return `false`. You can check whether an entry is encrypted with RarEntry::isEncrypted().
`extended_data`
  If `true`, extended information such as NTFS ACLs and Unix owner information will be set in the extract files, as long as it's present in the archive.

Warnung

Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath() as a workaround.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL rar 3.0.0 | `extended_data` was added.
PECL rar 3.0.0 | Support for RAR archives with repeated entry names is no longer defective.

### Beispiele

Beispiel #1 RarEntry::extract() example

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    $entry->extract('/dir/to'); // create /dir/to/Dir/file.txt
    $entry->extract(false, '/dir/to/new_name.txt'); // create /dir/to/new_name.txt

    ?>

Beispiel #2 How to extract all files in archive:

    <?php

    /* example by Erik Jenssen aka erix */

    $filename = "foobar.rar";
    $filepath = "/home/foo/bar/";

    $rar_file = rar_open($filepath.$filename);
    $list = rar_list($rar_file);
    foreach($list as $file) {
        $entry = rar_entry_get($rar_file, $file);
        $entry->extract("."); // extract to the current dir
    }
    rar_close($rar_file);

    ?>

### Siehe auch

- RarEntry::getStream() - Get file handler for entry
- `rar://` wrapper

# RarEntry::getAttr

(PECL rar >= 0.1)

RarEntry::getAttr — Get attributes of the entry

### Beschreibung

public function RarEntry::getAttr(): int

Returns the OS-dependent attributes of the archive entry.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the attributes or `false` on error.

### Beispiele

Beispiel #1 RarEntry::getAttr() example

    <?php

    $rar_file = rar_open('example.rar') or die("Can't open Rar archive");

    $entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("Can't find such entry");

    $host_os = $entry->getHostOs();
    $attr = $entry->getAttr();

    switch($host_os) {
        case RAR_HOST_MSDOS:
        case RAR_HOST_OS2:
        case RAR_HOST_WIN32:
        case RAR_HOST_MACOS:
            printf("%c%c%c%c%c%c\n",
                    ($attr & 0x08) ? 'V' : '.',
                    ($attr & 0x10) ? 'D' : '.',
                    ($attr & 0x01) ? 'R' : '.',
                    ($attr & 0x02) ? 'H' : '.',
                    ($attr & 0x04) ? 'S' : '.',
                    ($attr & 0x20) ? 'A' : '.');
            break;
        case RAR_HOST_UNIX:
        case RAR_HOST_BEOS:
            switch ($attr & 0xF000)
            {
                case 0x4000:
                    printf("d");
                    break;
                case 0xA000:
                    printf("l");
                    break;
                default:
                    printf("-");
                    break;
            }
            printf("%c%c%c%c%c%c%c%c%c\n",
                    ($attr & 0x0100) ? 'r' : '-',
                    ($attr & 0x0080) ? 'w' : '-',
                    ($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
                    ($attr & 0x0020) ? 'r' : '-',
                    ($attr & 0x0010) ? 'w' : '-',
                    ($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
                    ($attr & 0x0004) ? 'r' : '-',
                    ($attr & 0x0002) ? 'w' : '-',
                    ($attr & 0x0001) ? 'x' : '-');
            break;
    }

    rar_close($rar_file);

    ?>

### Siehe auch

- RarEntry::getHostOs() - Get entry host OS
- The constants in RarEntry

# RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrc — Get CRC of the entry

### Beschreibung

public function RarEntry::getCrc(): string

Returns an hexadecimal string representation of the CRC of the archive entry.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the CRC of the archive entry or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
PECL rar 2.0.0 | This method now returns correct values for multiple volume archives.

# RarEntry::getFileTime

(PECL rar >= 0.1)

RarEntry::getFileTime — Get entry last modification time

### Beschreibung

public function RarEntry::getFileTime(): string

Gets entry last modification time.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns entry last modification time as string in format `YYYY-MM-DD HH:II:SS`, or `false` on error.

# RarEntry::getHostOs

(PECL rar >= 0.1)

RarEntry::getHostOs — Get entry host OS

### Beschreibung

public function RarEntry::getHostOs(): int

Returns the code of the host OS of the archive entry.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the code of the host OS, or `false` on error.

### Beispiele

Beispiel #1 RarEntry::getHostOs() example (version >= 2.0.0)

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    switch ($entry->getHostOs()) {
        case RarEntry::HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RarEntry::HOST_OS2:
            echo "OS2\n";
            break;
        case RarEntry::HOST_WIN32:
            echo "Win32\n";
            break;
        case RarEntry::HOST_MACOS:
            echo "MacOS\n";
            break;
        case RarEntry::HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RarEntry::HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

Beispiel #2 RarEntry::getHostOs() example (version <= 1.0.0)

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    switch ($entry->getHostOs()) {
        case RAR_HOST_MSDOS:
            echo "MS-DOS\n";
            break;
        case RAR_HOST_OS2:
            echo "OS2\n";
            break;
        case RAR_HOST_WIN32:
            echo "Win32\n";
            break;
        case RAR_HOST_MACOS:
            echo "MacOS\n";
            break;
        case RAR_HOST_UNIX:
            echo "Unix/Linux\n";
            break;
        case RAR_HOST_BEOS:
            echo "BeOS\n";
            break;
    }

    ?>

### Siehe auch

- RarEntry::extract() - Extract entry from the archive

# RarEntry::getMethod

(PECL rar >= 0.1)

RarEntry::getMethod — Get pack method of the entry

### Beschreibung

public function RarEntry::getMethod(): int

RarEntry::getMethod() returns number of the method used when adding current archive entry.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the method number or `false` on error.

### Beispiele

Beispiel #1 RarEntry::getMethod() example

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Method number: " . $entry->getMethod();

    ?>

# RarEntry::getName

(PECL rar >= 0.1)

RarEntry::getName — Get name of the entry

### Beschreibung

public function RarEntry::getName(): string

Returns the name (with path) of the archive entry.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the entry name as a string, or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
PECL rar 2.0.0 | As of version 2.0.0, the returned string is encoded in Unicode/UTF-8.

### Beispiele

Beispiel #1 RarEntry::getName() example

    <?php

    //this example is safe even in pages not encoded in UTF-8
    //for those encoded in UTF-8, the call to mb_convert_encoding is unnecessary

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Entry name: " . mb_convert_encoding(
        htmlentities(
            $entry->getName(),
            ENT_COMPAT,
            "UTF-8"
        ),
        "HTML-ENTITIES",
        "UTF-8"
    );

    ?>

# RarEntry::getPackedSize

(PECL rar >= 0.1)

RarEntry::getPackedSize — Get packed size of the entry

### Beschreibung

public function RarEntry::getPackedSize(): int

Get packed size of the archive entry.

> Hinweis: Note that on platforms with 32-bit longs (that includes Windows x64), the maximum size returned is capped at 2 GiB. Check the constant `PHP_INT_MAX`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the packed size, or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
PECL rar 2.0.0 | This method now returns correct values of packed sizes bigger than 2 GiB on platforms with 64-bit ints and never returns negative values on other platforms.

### Beispiele

Beispiel #1 RarEntry::getPackedSize() example

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Packed size of " . $entry->getName() . " = " . $entry->getPackedSize() . " bytes";

    ?>

# RarEntry::getStream

(PECL rar >= 2.0.0)

RarEntry::getStream — Get file handler for entry

### Beschreibung

public function RarEntry::getStream(string `$password` = ?): resource|false

Returns a file handler that supports read operations. This handler provides on-the-fly decompression for this entry.

The handler is not invalidated by calling rar_close().

Warnung

The resulting stream has no integrity verification. In particular, file corruption and decryption with a wrong a key will not be detected. It is the programmer's responsability to use the entry's CRC to check for integrity, if he so wishes.

### Parameter-Liste

`password`
  The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can be omitted. If this parameter is omitted and the entry is encrypted, the password given to rar_open(), if any, will be used. If a wrong password is given, either explicitly or implicitly via rar_open(), this method's resulting stream will produce wrong output. If no password is given and one is required, this method will fail and return `false`. You can check whether an entry is encrypted with RarEntry::isEncrypted().

### Rückgabewerte

The file handler Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
PECL rar 3.0.0 | Support for RAR archives with repeated entry names is no longer defective.

### Beispiele

Beispiel #1 RarEntry::getStream() example

    <?php

    $rar_file = rar_open('example.rar');
    if ($rar_file === false)
        die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt');
    if ($entry === false)
        die("Failed to find such entry");

    $stream = $entry->getStream();
    if ($stream === false)
        die("Failed to obtain stream.");

    rar_close($rar_file); //stream is independent from file

    while (!feof($stream)) {
        $buff = fread($stream, 8192);
        if ($buff !== false)
            echo $buff;
        else
            break; //fread error
    }

    fclose($stream);

    ?>

### Siehe auch

- RarEntry::extract() - Extract entry from the archive
- `rar://` wrapper

# RarEntry::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSize — Get unpacked size of the entry

### Beschreibung

public function RarEntry::getUnpackedSize(): int

Get unpacked size of the archive entry.

> Hinweis: Note that on platforms with 32-bit longs (that includes Windows x64), the maximum size returned is capped at 2 GiB. Check the constant `PHP_INT_MAX`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the unpacked size, or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
PECL rar 2.0.0 | This method now returns correct values of unpacked sizes bigger than 2 GiB on platforms with 64-bit ints and never returns negative values on other platforms.

### Rückgabewerte

Beispiel #1 RarEntry::getUnpackedSize() example

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Unpacked size of " . $entry->getName() . " = " . $entry->getUnpackedSize() . " bytes";

    ?>

# RarEntry::getVersion

(PECL rar >= 0.1)

RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry

### Beschreibung

public function RarEntry::getVersion(): int

Returns minimum version of RAR program (e.g. WinRAR) required to unpack the entry. It is encoded as 10 * major version + minor version.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the version or `false` on error.

### Beispiele

Beispiel #1 RarEntry::getVersion() example

    <?php

    $rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

    $entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

    echo "Rar version required for unpacking: " . $entry->getVersion();

    ?>

# RarEntry::isDirectory

(PECL rar >= 2.0.0)

RarEntry::isDirectory — Test whether an entry represents a directory

### Beschreibung

public function RarEntry::isDirectory(): bool

Tests whether the current entry is a directory.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if this entry is a directory and `false` otherwise.

### Anmerkungen

This function is only available starting with version 2.0.0, but one can also test whether an entry is a directory by checking the entry attributes, like this (only works for files compressed in RAR for Windows or Unix):

    <?php
    //...
    //Open file, get entry and store in variable $e...
    //...

    $isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
        (($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
    ?>

# RarEntry::isEncrypted

(PECL rar >= 2.0.0)

RarEntry::isEncrypted — Test whether an entry is encrypted

### Beschreibung

public function RarEntry::isEncrypted(): bool

Tests whether the current entry contents are encrypted.

> Hinweis: The password used may differ between files inside the same RAR archive.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the current entry is encrypted and `false` otherwise.

# RarEntry::__toString

(PECL rar >= 2.0.0)

RarEntry::__toString — Get text representation of entry

### Beschreibung

public function RarEntry::__toString(): string

RarEntry::__toString() returns a textual representation for this entry. It includes whether the entry is a file or a directory (symbolic links and other special objects will be treated as files), the UTF-8 name of the entry and its CRC. The form and content of this representation may be changed in the future, so they cannot be relied upon.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

A textual representation for the entry.

## Inhaltsverzeichnis

- RarEntry::extract — Extract entry from the archive
- RarEntry::getAttr — Get attributes of the entry
- RarEntry::getCrc — Get CRC of the entry
- RarEntry::getFileTime — Get entry last modification time
- RarEntry::getHostOs — Get entry host OS
- RarEntry::getMethod — Get pack method of the entry
- RarEntry::getName — Get name of the entry
- RarEntry::getPackedSize — Get packed size of the entry
- RarEntry::getStream — Get file handler for entry
- RarEntry::getUnpackedSize — Get unpacked size of the entry
- RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry
- RarEntry::isDirectory — Test whether an entry represents a directory
- RarEntry::isEncrypted — Test whether an entry is encrypted
- RarEntry::__toString — Get text representation of entry

# The RarException class

(PECL rar >= 2.0.0)

## Einführung

This class serves two purposes: it is the type of the exceptions thrown by the RAR extension functions and methods and it allows, through static methods to query and define the error behaviour of the extension, i.e., whether exceptions are thrown or only warnings are emitted.

The following error codes are used:

- -1 - error outside UnRAR library
- 11 - insufficient memory
- 12 - bad data
- 13 - bad archive
- 14 - unknown format
- 15 - file open error
- 16 - file create error
- 17 - file close error
- 18 - read error
- 19 - write error
- 20 - buffer too small
- 21 - unknown RAR error
- 22 - password required but not given

## Klassenbeschreibung

final class RarException extends Exception {
/* Methoden */
public static function isUsingExceptions(): bool
public static function setUsingExceptions(bool `$using_exceptions`): void
/* Geerbte Methoden */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# RarException::isUsingExceptions

(PECL rar >= 2.0.0)

RarException::isUsingExceptions — Check whether error handling with exceptions is in use

### Beschreibung

public static function RarException::isUsingExceptions(): bool

Checks whether the RAR functions will emit warnings and return error values or whether they will throw exceptions in most of the circumstances (does not include some programmatic errors such as passing the wrong type of arguments).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if exceptions are being used, `false` otherwise.

### Beispiele

Beispiel #1 RarException::isUsingExceptions() example

    <?php
    //The default is not to use exceptions
    var_dump(RarException::isUsingExceptions());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    bool(false)

### Siehe auch

- RarException::setUsingExceptions() - Activate and deactivate error handling with exceptions

# RarException::setUsingExceptions

(PECL rar >= 2.0.0)

RarException::setUsingExceptions — Activate and deactivate error handling with exceptions

### Beschreibung

public static function RarException::setUsingExceptions(bool `$using_exceptions`): void

If and only if the argument is `true`, then, instead of emitting warnings and returning a special value indicating error when the UnRAR library encounters an error, an exception of type RarException will be thrown.

Exceptions will also be thrown for the following errors, which occur outside the library (their error code will be -1):

- attempting some operations on a closed RarArchive object or a RarEntry object relative to the first;
- attempting to get an entry that does not exist with RarArchive::getEntry().

### Parameter-Liste

`using_exceptions`
  Should be `true` to activate exception throwing, `false` to deactivate (the default).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 RarException::setUsingExceptions() example

    <?php
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("does_not_exist.rar");
    var_dump($arch);

    RarException::setUsingExceptions(true);
    var_dump(RarException::isUsingExceptions());
    $arch = RarArchive::open("does_not_exist.rar");
    var_dump($arch); //not reached
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    bool(false)

    Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
    bool(false)
    bool(true)

    Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
    Stack trace:
    #0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
    #1 {main}
      thrown in C:\php_rar\trunk\tests\test.php on line 8

### Siehe auch

- RarException::isUsingExceptions() - Check whether error handling with exceptions is in use

## Inhaltsverzeichnis

- RarException::isUsingExceptions — Check whether error handling with exceptions is in use
- RarException::setUsingExceptions — Activate and deactivate error handling with exceptions

- Installation/Konfiguration
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- Beispiele
- RAR Funktionen
  - rar_wrapper_cache_stats — Cache-Treffer und -Fehlschläge für den URL-Wrapper
- RarArchive — The RarArchive class
  - RarArchive::close — Close RAR archive and free all resources
  - RarArchive::getComment — Get comment text from the RAR archive
  - RarArchive::getEntries — Get full list of entries from the RAR archive
  - RarArchive::getEntry — Get entry object from the RAR archive
  - RarArchive::isBroken — Test whether an archive is broken (incomplete)
  - RarArchive::isSolid — Check whether the RAR archive is solid
  - RarArchive::open — Open RAR archive
  - RarArchive::setAllowBroken — Whether opening broken archives is allowed
  - RarArchive::__toString — Get text representation
- RarEntry — The RarEntry class
  - RarEntry::extract — Extract entry from the archive
  - RarEntry::getAttr — Get attributes of the entry
  - RarEntry::getCrc — Get CRC of the entry
  - RarEntry::getFileTime — Get entry last modification time
  - RarEntry::getHostOs — Get entry host OS
  - RarEntry::getMethod — Get pack method of the entry
  - RarEntry::getName — Get name of the entry
  - RarEntry::getPackedSize — Get packed size of the entry
  - RarEntry::getStream — Get file handler for entry
  - RarEntry::getUnpackedSize — Get unpacked size of the entry
  - RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry
  - RarEntry::isDirectory — Test whether an entry represents a directory
  - RarEntry::isEncrypted — Test whether an entry is encrypted
  - RarEntry::__toString — Get text representation of entry
- RarException — The RarException class
  - RarException::isUsingExceptions — Check whether error handling with exceptions is in use
  - RarException::setUsingExceptions — Activate and deactivate error handling with exceptions

# Zip

# Einführung

Diese Extension ermöglicht den transparenten Lese- und Schreibzugriff auf ZIP-komprimierte Archive und die darin enthaltenen Dateien.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Ressource-Typen

## Anforderungen

Diese Extension benötigt » libzip. Version 1.1.2 wurde mit PHP bis Version 7.3 ausgeliefert.

Die Mindestanforderung ist Version 0.11, aber neuere werden dringend empfohlen.

- Version 1.2 wird für Verschlüsselungsunterstützung benötigt, siehe ZipArchive::setEncryptionIndex()
- Version 1.3 wird für Fortschrittsunterstüzung benötigt, siehe ZipArchive::registerProgressCallback()
- Version 1.6 wird für Abbruchsunterstüztung benötigt, siehe ZipArchive::registerCancelCallback()

## Installation

## Linux-Systeme

Um diese Funktionen nutzen zu können, muss PHP mit der Option --with-zip kompiliert werden.

Vor PHP 7.4.0 war libzip Teil von PHP, und um die Erweiterung zu kompilieren, musste man die Konfigurationsoption --enable-zip verwenden. Von PHP 7.3.0 an wurde davon abgeraten, mit der mitgelieferten libzip zu kompilieren, aber es war immer noch möglich, indem die Konfigurationsoption --without-libzip verwendet wurde.

Die Konfigurationsoption --with-libzip=DIR wurde hinzugefügt, um eine System-Installation von libzip zu verwenden. Benötigt wird libzip 0.11, aber 0.11.2 oder höher werden empfohlen.

## Windows

Von PHP 8.2.0 an muss die DLL php_zip.dll in der php.ini aktiviert werden. Vorher war diese Erweiterung eingebaut.

## Installation via PECL

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/zip.

## Ressource-Typen

Die Zip Extension benutzt zwei Resourcetypen, einen für Verzeichnisse innerhalb eines Zip-Archivs und einen für die eigentlichen Dateieinträge innerhalb des Archivs.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

ZipArchive nutzt Klassenkonstanten. Es gibt mehrere Arten von Konstanten: für Flags (mit dem Präfix `FL_`), globale Flags (mit dem Präfix `AFL_`), Fehler (mit dem Präfix `ER_`) und Modus (ohne Präfix).

Archive open modes
`ZipArchive::CREATE` (int)
  Archiv anlegen, wenn es noch nicht existiert.
`ZipArchive::OVERWRITE` (int)
  Existiert das Archiv, dann ignoriere den aktuellen Inhalt. Anders ausgedrückt, behandle es auf dieselbe Weise, wie ein leeres Archiv.
`ZipArchive::EXCL` (int)
  Mit einer Fehlermeldung abbrechen, falls das Archiv bereits existiert.
`ZipArchive::RDONLY` (int)
  Öffnet Archiv im Nurlesemodus. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.17.1 an, wenn mit libzip ≥ 1.0.0 kompiliert.
`ZipArchive::CHECKCONS` (int)
  Prüft zusätzliche Konsistenzbedingungen und bricht mit einem Fehler ab, wenn diese nicht erfüllt sind.

Globale Archiv-Flags
`ZipArchive::AFL_RDONLY` (int)
  Das Archiv ist schreibgeschützt und kann nicht gelöscht werden. Verfügbar ab PHP 8.3.0 bzw. PECL zip 1.22.0, wenn mit libzip ≥ 1.10.0 kompiliert.
`ZipArchive::AFL_IS_TORRENTZIP` (int)
  Das aktuelle Archiv wurde mit torrentzip komprimiert. Verfügbar ab PHP 8.3.0 bzw. PECL zip 1.22.0, wenn mit libzip ≥ 1.10.0 kompiliert.
`ZipArchive::AFL_WANT_TORRENTZIP` (int)
  Schreibt das Archiv im torrentzip-Format. Verfügbar ab PHP 8.3.0 bzw. PECL zip 1.22.0, wenn mit libzip ≥ 1.10.0 kompiliert.
`ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` (int)
  Entfernt die Datei nicht, wenn das Archiv leer ist. Verfügbar ab PHP 8.3.0 bzw. PECL zip 1.22.0, wenn mit libzip ≥ 1.10.0 kompiliert.

Archiv-Flags
`ZipArchive::FL_NOCASE` (int)
  Namensvergleiche ohne Beachtung von Groß- und Kleinschreibung.
`ZipArchive::FL_NODIR` (int)
  Verzeichniskomponenten ignorieren.
`ZipArchive::FL_COMPRESSED` (int)
  Komprimierte Daten lesen.
`ZipArchive::FL_UNCHANGED` (int)
  Orginaldaten benutzen und Änderungen ignorieren.
`ZipArchive::FL_RECOMPRESS` (int)
  Erzwingt die Neukomprimierung der Daten. Verfügbar von PHP 8.0.0 und PECL zip 1.18.0 an. Veraltet von PHP 8.3.0 und PECL zip 1.22.1 an; wird in einer zukünftigen Version von libzip entfernt.
`ZipArchive::FL_ENCRYPTED` (int)
  Liest verschlüsselte Daten (impliziert FL_COMPRESSED). Verfügbar von PHP 8.0.0 und PECL zip 1.18.0 an.
`ZipArchive::FL_OVERWRITE` (int)
  Existiert die Datei mit diesem Namen bereits, wird sie überschrieben (ersetzt). Verfügbar von PHP 8.0.0 und PECL zip 1.18.0 an.
`ZipArchive::FL_LOCAL` (int)
  In den lokalen Headern. Verfügbar von PHP 8.0.0 und PECL zip 1.18.0 an.
`ZipArchive::FL_CENTRAL` (int)
  Im zentralen Verzeichnis. Verfügbar von PHP 8.0.0 und PECL zip 1.18.0 an.
`ZipArchive::FL_ENC_GUESS` (int)
  Versuche die String-Kodierung zu erraten (Standardwert). Verfügbar ab PHP 7.0.8.
`ZipArchive::FL_ENC_RAW` (int)
  Lies unmodifizierten String. Verfügbar ab PHP 7.0.8.
`ZipArchive::FL_ENC_STRICT` (int)
  Folge streng der Spezifikation. Verfügbar ab PHP 7.0.8.
`ZipArchive::FL_ENC_UTF_8` (int)
  Der String ist UTF-8-kodiert. Verfügbar ab PHP 7.0.8.
`ZipArchive::FL_ENC_CP437` (int)
  Der String ist CP437-kodiert. Verfügbar ab PHP 7.0.8.
`ZipArchive::FL_OPEN_FILE_NOW` (int)
  Öffnet die Datei, wenn sie hinzugefügt wird, anstatt zu warten, bis das Archiv geschlossen wird. Achten Sie auf den Verbrauch von Dateideskriptoren. Verfügbar ab PHP 8.3.0 und PECL zip 1.22.1.

Komprimierungsmethoden
`ZipArchive::CM_DEFAULT` (int)
  Benutze "deflate" oder "store", je nachdem, was effektiver ist.
`ZipArchive::CM_STORE` (int)
  Daten unkomprimiert mit der "store"-Methode ablegen
`ZipArchive::CM_SHRINK` (int)
  Daten mit der "shrink"-Methode ablegen
`ZipArchive::CM_REDUCE_1` (int)
  Daten mit Faktor 1 reduzieren
`ZipArchive::CM_REDUCE_2` (int)
  Daten mit Faktor 2 reduzieren
`ZipArchive::CM_REDUCE_3` (int)
  Daten mit Faktor 3 reduzieren
`ZipArchive::CM_REDUCE_4` (int)
  Daten mit Faktor 4 reduzieren
`ZipArchive::CM_IMPLODE` (int)
  Daten mit der "implode"-Methode ablegen
`ZipArchive::CM_DEFLATE` (int)
  Daten mit der "deflate"-Methode ablegen
`ZipArchive::CM_DEFLATE64` (int)
  Daten mit der "deflate64"-Methode ablegen
`ZipArchive::CM_PKWARE_IMPLODE` (int)
  Daten mit der PKWARE-Implode-Methode ablegen
`ZipArchive::CM_BZIP2` (int)
  Daten mit dem Bzip2-Algorithmus ablegen
`ZipArchive::CM_LZMA` (int)
  LZMA-Algorithmus
`ZipArchive::CM_LZMA2` (int)
  LZMA2-Algorithmus. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.0, wenn mit libzip >= 1.6.0 kompiliert.
`ZipArchive::CM_ZSTD` (int)
  Zstandard-Algorithmus. Verfügbar von PHP 8.0.0, bzw. PECL zip 1.19.1 an, wenn gegen libzip ≥ 1.8.0 kompiliert wurde.
`ZipArchive::CM_XZ` (int)
  XZ-Algorithmus. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an, wenn mit libzip >= 1.6.0 kompiliert.
`ZipArchive::CM_TERSE` (int)
`ZipArchive::CM_LZ77` (int)
`ZipArchive::CM_WAVPACK` (int)
`ZipArchive::CM_PPMD` (int)

Fehler
`ZipArchive::ER_OK` (int)
  Kein Fehler.
`ZipArchive::ER_MULTIDISK` (int)
  ZIP-Archiv über mehrere Datenträger nicht unterstützt.
`ZipArchive::ER_RENAME` (int)
  Umbenennung einer temporären Datei fehlgeschlagen.
`ZipArchive::ER_CLOSE` (int)
  Schließen eines Archivs fehlgeschlagen.
`ZipArchive::ER_SEEK` (int)
  Positionierungsfehler
`ZipArchive::ER_READ` (int)
  Lesefehler
`ZipArchive::ER_WRITE` (int)
  Schreibfehler
`ZipArchive::ER_CRC` (int)
  CRC-Prüfsummenfehler
`ZipArchive::ER_ZIPCLOSED` (int)
  Das die Datei enthaltende Archiv wurde geschlossen.
`ZipArchive::ER_NOENT` (int)
  Datei nicht gefunden.
`ZipArchive::ER_EXISTS` (int)
  Datei existiert bereits.
`ZipArchive::ER_OPEN` (int)
  Datei kann nicht geöffnet werden.
`ZipArchive::ER_TMPOPEN` (int)
  Temporäre Datei kann nicht angelegt werden.
`ZipArchive::ER_ZLIB` (int)
  Zlib-Fehler
`ZipArchive::ER_MEMORY` (int)
  Speicheranforderung fehlgeschlagen
`ZipArchive::ER_CHANGED` (int)
  Eintrag wurde geändert.
`ZipArchive::ER_COMPNOTSUPP` (int)
  Kompressionsmethode nicht unterstützt.
`ZipArchive::ER_EOF` (int)
  Unerwartetes Dateiende.
`ZipArchive::ER_INVAL` (int)
  Ungültiges Argument.
`ZipArchive::ER_NOZIP` (int)
  Kein Zip-Archiv.
`ZipArchive::ER_INTERNAL` (int)
  Interner Fehler.
`ZipArchive::ER_INCONS` (int)
  Zip-Archiv inkonsistent.
`ZipArchive::ER_REMOVE` (int)
  Datei kann nicht entfernt werden.
`ZipArchive::ER_DELETED` (int)
  Eintrag wurde entfernt.
`ZipArchive::ER_ENCRNOTSUPP` (int)
  Verschlüsselungsmethode nicht unterstützt. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an.
`ZipArchive::ER_RDONLY` (int)
  Nurlese-Archiv. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an.
`ZipArchive::ER_NOPASSWD` (int)
  Kein Passwort angegeben. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an.
`ZipArchive::ER_WRONGPASSWD` (int)
  Falsches Passwort angegeben. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an.
`ZipArchive::ER_OPNOTSUPP` (int)
  Nurlese-Archiv. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an, wenn mit libzip ≥ 1.0.0 kompiliert.
`ZipArchive::ER_INUSE` (int)
  Ressource wird noch verwendet. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an, wenn mit libzip ≥ 1.0.0 kompiliert.
`ZipArchive::ER_TELL` (int)
  Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an, wenn mit libzip ≥ 1.0.0 kompiliert.
`ZipArchive::ER_COMPRESSED_DATA` (int)
  Komprimierte Daten ungültig. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an, wenn mit libzip ≥ 1.0.0 kompiliert.
`ZipArchive::ER_CANCELLED` (int)
  Operation abgebrochen. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.1 an, wenn mit libzip ≥ 1.0.0 kompiliert.
`ZipArchive::ER_DATA_LENGTH` (int)
  Unerwartete Länge der Daten. Verfügbar ab PHP 8.3.0 bzw. PECL zip 1.22.0, wenn mit libzip ≥ 1.10.0 kompiliert.
`ZipArchive::ER_NOT_ALLOWED` (int)
  In torrentzip nicht erlaubt. Verfügbar ab PHP 8.3.0 bzw. PECL zip 1.22.0, wenn mit libzip ≥ 1.10.0 kompiliert.
`ZipArchive::ER_TRUNCATED_ZIP` (int)
  Möglicherweise abgeschnittenes oder beschädigtes Zip-Archiv. Verfügbar ab PHP 8.4.0 bzw. PECL zip 1.22.4, wenn mit libzip ≥ 1.11.1 kompiliert.

Verschlüsselungsmethoden
`ZipArchive::EM_NONE` (int)
  Keine Verschlüsselung. Verfügbar von PHP 7.2.0, bzw. PECL zip 1.14.0 an.
`ZipArchive::EM_TRAD_PKWARE` (int)
  Traditionelle PKWARE-Verschlüsselung. Verfügbar von PHP 8.0.0, bzw. PECL zip 1.19.0 an.
`ZipArchive::EM_AES_128` (int)
  AES-128-Verschlüsselung. Verfügbar von PHP 7.2.0, bzw. PECL zip 1.14.0 an, wenn mit libzip ≥ 1.2.0 kompiliert.
`ZipArchive::EM_AES_192` (int)
  AES-192-Verschlüsselung. Verfügbar von PHP 7.2.0, bzw. PECL zip 1.14.0 an, wenn mit libzip ≥ 1.2.0 kompiliert.
`ZipArchive::EM_AES_256` (int)
  AES-256-Verschlüsselung. Verfügbar von PHP 7.2.0, bzw. PECL zip 1.14.0 an, wenn mit libzip ≥ 1.2.0 kompiliert.
`ZipArchive::EM_UNKNOWN` (int)
  Unbekannter Verschlüsselungsalgorithmus. Verfügbar von PHP 8.0.0, bzw. PECL zip 1.19.0 an.

Length parameter constants
`ZipArchive::LENGTH_TO_END` (int)
  Verwendet die Dateigröße. Wenn die Datei wächst, werden die zusätzlichen Daten ignoriert, wenn die Datei schrumpft, wird ein Fehler ausgegeben (`ZipArchive::ER_DATA_LENGTH`). Verfügbar von PHP 8.3.0 und PECL zip 1.22.2 an.
`ZipArchive::LENGTH_UNCHECKED` (int)
  Verwendet alle verfügbaren Daten. Verfügbar von PHP 8.3.0 und PECL zip 1.22.2 an, wenn mit libzip ≥ 1.10.1 kompiliert.

Sonstige Konstanten
`ZipArchive::LIBZIP_VERSION` (string)
  Die Version der Zip-Bibliothek. Verfügbar von PHP 7.4.3, bzw. PECL zip 1.16.0 an.

Betriebssystemkonstanten für externe Attribute
`ZipArchive::OPSYS_DOS` (int)
`ZipArchive::OPSYS_AMIGA` (int)
`ZipArchive::OPSYS_OPENVMS` (int)
`ZipArchive::OPSYS_UNIX` (int)
`ZipArchive::OPSYS_VM_CMS` (int)
`ZipArchive::OPSYS_ATARI_ST` (int)
`ZipArchive::OPSYS_OS_2` (int)
`ZipArchive::OPSYS_MACINTOSH` (int)
`ZipArchive::OPSYS_Z_SYSTEM` (int)
`ZipArchive::OPSYS_CPM` (int)
`ZipArchive::OPSYS_WINDOWS_NTFS` (int)
`ZipArchive::OPSYS_MVS` (int)
`ZipArchive::OPSYS_VSE` (int)
`ZipArchive::OPSYS_ACORN_RISC` (int)
`ZipArchive::OPSYS_VFAT` (int)
`ZipArchive::OPSYS_ALTERNATE_MVS` (int)
`ZipArchive::OPSYS_BEOS` (int)
`ZipArchive::OPSYS_TANDEM` (int)
`ZipArchive::OPSYS_OS_400` (int)
`ZipArchive::OPSYS_OS_X` (int)
`ZipArchive::OPSYS_DEFAULT` (int)
  Seit PECL zip 1.12.4

# Beispiele

Beispiel #1 Erstellen eines Zip-Archivs

    <?php

    $zip = new ZipArchive();
    $filename = "./test112.zip";

    if ($zip->open($filename, ZipArchive::CREATE)!==TRUE) {
        exit("cannot open <$filename>\n");
    }

    $zip->addFromString("testfilephp.txt" . time(), "#1 This is a test string added as testfilephp.txt.\n");
    $zip->addFromString("testfilephp2.txt" . time(), "#2 This is a test string added as testfilephp2.txt.\n");
    $zip->addFile($thisdir . "/too.php","/testfromfile.php");
    echo "numfiles: " . $zip->numFiles . "\n";
    echo "status:" . $zip->status . "\n";
    $zip->close();
    ?>

Beispiel #2 Ausgabe eines detailierten Archivlistings

    <?php
    $za = new ZipArchive();

    $za->open('test_with_comment.zip');
    print_r($za);
    var_dump($za);
    echo "numFiles: " . $za->numFiles . "\n";
    echo "status: " . $za->status  . "\n";
    echo "statusSys: " . $za->statusSys . "\n";
    echo "filename: " . $za->filename . "\n";
    echo "comment: " . $za->comment . "\n";

    for ($i=0; $i<$za->numFiles;$i++) {
        echo "index: $i\n";
        print_r($za->statIndex($i));
    }
    echo "numFile:" . $za->numFiles . "\n";
    ?>

Beispiel #3 Zip Stream Wrapper, Auslesen von OpenOffice Metainformationen

    <?php
    $reader = new XMLReader();

    $reader->open('zip://' . dirname(__FILE__) . '/test.odt#meta.xml');
    $odt_meta = array();
    while ($reader->read()) {
        if ($reader->nodeType == XMLREADER::ELEMENT) {
            $elm = $reader->name;
        } else {
            if ($reader->nodeType == XMLREADER::END_ELEMENT && $reader->name == 'office:meta') {
                break;
            }
            if (!trim($reader->value)) {
                continue;
            }
            $odt_meta[$elm] = $reader->value;
        }
    }
    print_r($odt_meta);
    ?>

Das folgende Beispiel benutzt das alte PHP 4 API, es öffnet eine Zip-Datei, liest jede einzelne Datei im Archiv und gibt deren Inhalt aus. Die in diesem Beispiel genutzte test2.zip Datei ist Teil des Testarchivs des ZZIPlib Quellcodes.

Beispiel #4 Zip Beispiel

    <?php

    $zip = zip_open("/tmp/test2.zip");

    if ($zip) {
        while ($zip_entry = zip_read($zip)) {
            echo "Name:               " . zip_entry_name($zip_entry) . "\n";
            echo "Actual Filesize:    " . zip_entry_filesize($zip_entry) . "\n";
            echo "Compressed Size:    " . zip_entry_compressedsize($zip_entry) . "\n";
            echo "Compression Method: " . zip_entry_compressionmethod($zip_entry) . "\n";

            if (zip_entry_open($zip, $zip_entry, "r")) {
                echo "File Contents:\n";
                $buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
                echo "$buf\n";

                zip_entry_close($zip_entry);
            }
            echo "\n";

        }

        zip_close($zip);

    }
    ?>

# Die Klasse ZipArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

## Einführung

Ein Dateiarchiv, komprimiert mit Zip.

## Klassenbeschreibung

class ZipArchive implements Countable {
/* Konstanten */
public const int CREATE;
public const int EXCL;
public const int CHECKCONS;
public const int OVERWRITE;
public const int RDONLY;
public const int FL_NOCASE;
public const int FL_NODIR;
public const int FL_COMPRESSED;
public const int FL_UNCHANGED;
public const int FL_RECOMPRESS;
public const int FL_ENCRYPTED;
public const int FL_OVERWRITE;
public const int FL_LOCAL;
public const int FL_CENTRAL;
public const int FL_ENC_GUESS;
public const int FL_ENC_RAW;
public const int FL_ENC_STRICT;
public const int FL_ENC_UTF_8;
public const int FL_ENC_CP437;
public const int FL_OPEN_FILE_NOW;
public const int CM_DEFAULT;
public const int CM_STORE;
public const int CM_SHRINK;
public const int CM_REDUCE_1;
public const int CM_REDUCE_2;
public const int CM_REDUCE_3;
public const int CM_REDUCE_4;
public const int CM_IMPLODE;
public const int CM_DEFLATE;
public const int CM_DEFLATE64;
public const int CM_PKWARE_IMPLODE;
public const int CM_BZIP2;
public const int CM_LZMA;
public const int CM_LZMA2;
public const int CM_ZSTD;
public const int CM_XZ;
public const int CM_TERSE;
public const int CM_LZ77;
public const int CM_WAVPACK;
public const int CM_PPMD;
public const int ER_OK;
public const int ER_MULTIDISK;
public const int ER_RENAME;
public const int ER_CLOSE;
public const int ER_SEEK;
public const int ER_READ;
public const int ER_WRITE;
public const int ER_CRC;
public const int ER_ZIPCLOSED;
public const int ER_NOENT;
public const int ER_EXISTS;
public const int ER_OPEN;
public const int ER_TMPOPEN;
public const int ER_ZLIB;
public const int ER_MEMORY;
public const int ER_CHANGED;
public const int ER_COMPNOTSUPP;
public const int ER_EOF;
public const int ER_INVAL;
public const int ER_NOZIP;
public const int ER_INTERNAL;
public const int ER_INCONS;
public const int ER_REMOVE;
public const int ER_DELETED;
public const int ER_ENCRNOTSUPP;
public const int ER_RDONLY;
public const int ER_NOPASSWD;
public const int ER_WRONGPASSWD;
public const int ER_OPNOTSUPP;
public const int ER_INUSE;
public const int ER_TELL;
public const int ER_COMPRESSED_DATA;
public const int ER_CANCELLED;
public const int ER_DATA_LENGTH;
public const int ER_NOT_ALLOWED;
public const int ER_TRUNCATED_ZIP;
public const int AFL_RDONLY;
public const int AFL_IS_TORRENTZIP;
public const int AFL_WANT_TORRENTZIP;
public const int AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE;
public const int OPSYS_DOS;
public const int OPSYS_AMIGA;
public const int OPSYS_OPENVMS;
public const int OPSYS_UNIX;
public const int OPSYS_VM_CMS;
public const int OPSYS_ATARI_ST;
public const int OPSYS_OS_2;
public const int OPSYS_MACINTOSH;
public const int OPSYS_Z_SYSTEM;
public const int OPSYS_CPM;
public const int OPSYS_WINDOWS_NTFS;
public const int OPSYS_MVS;
public const int OPSYS_VSE;
public const int OPSYS_ACORN_RISC;
public const int OPSYS_VFAT;
public const int OPSYS_ALTERNATE_MVS;
public const int OPSYS_BEOS;
public const int OPSYS_TANDEM;
public const int OPSYS_OS_400;
public const int OPSYS_OS_X;
public const int OPSYS_DEFAULT;
public const int EM_NONE;
public const int EM_TRAD_PKWARE;
public const int EM_AES_128;
public const int EM_AES_192;
public const int EM_AES_256;
public const int EM_UNKNOWN;
public const string LIBZIP_VERSION;
public const int LENGTH_TO_END;
public const int LENGTH_UNCHECKED;
/* Eigenschaften */
public readonly int $lastId;
public readonly int $status;
public readonly int $statusSys;
public readonly int $numFiles;
public readonly string $filename;
public readonly string $comment;
/* Methoden */
public function addEmptyDir(string `$dirname`, int `$flags` = 0): bool
public function addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool
public function addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool
public function addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false
public function addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false
public function clearError(): void
public function close(): bool
public function count(): int
public function deleteIndex(int `$index`): bool
public function deleteName(string `$name`): bool
public function extractTo(string `$pathto`, array|string|null `$files` = `null`): bool
public function getArchiveComment(int `$flags` = 0): string|false
public function getArchiveFlag(int `$flag`, int `$flags` = 0): int
public function getCommentIndex(int `$index`, int `$flags` = 0): string|false
public function getCommentName(string `$name`, int `$flags` = 0): string|false
public function getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false
public function getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false
public function getNameIndex(int `$index`, int `$flags` = 0): string|false
public function getStatusString(): string
public function getStream(string `$name`): resource|false
public function getStreamIndex(int `$index`, int `$flags` = 0): resource|false
public function getStreamName(string `$name`, int `$flags` = 0): resource|false
public static function isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public static function isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public function locateName(string `$name`, int `$flags` = 0): int|false
public function open(string `$filename`, int `$flags` = 0): bool|int
public function registerCancelCallback(callable `$callback`): bool
public function registerProgressCallback(float `$rate`, callable `$callback`): bool
public function renameIndex(int `$index`, string `$new_name`): bool
public function renameName(string `$name`, string `$new_name`): bool
public function replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool
public function setArchiveComment(string `$comment`): bool
public function setArchiveFlag(int `$flag`, int `$value`): bool
public function setCommentIndex(int `$index`, string `$comment`): bool
public function setCommentName(string `$name`, string `$comment`): bool
public function setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool
public function setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool
public function setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool
public function setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool
public function setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool
public function setPassword(#[\SensitiveParameter]string `$password`): bool
public function statIndex(int `$index`, int `$flags` = 0): array|false
public function statName(string `$name`, int `$flags` = 0): array|false
public function unchangeAll(): bool
public function unchangeArchive(): bool
public function unchangeIndex(int `$index`): bool
public function unchangeName(string `$name`): bool
}

## Eigenschaften

lastId

  Index des zuletzt hinzugefügten Eintrags (Datei oder Verzeichnis). Verfügbar von PHP 8.0.0 und PECL zip 1.18.0 an.

status

  Status des Zip-Archives. Verfügbar für geschlossene Archive von PHP 8.0.0 und PECL zip 1.18.0 an.

statusSys

  System-Status des Zip-Archives. Verfügbar für geschlossene Archive von PHP 8.0.0 und PECL zip 1.18.0 an.

numFiles

  Anzahl Dateien im Archiv

filename

  Dateiname im Dateisystem

comment

  Kommentar für das Archiv

# ZipArchive::addEmptyDir

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDir — Fügt ein neues Verzeichnis hinzu

### Beschreibung

public function ZipArchive::addEmptyDir(string `$dirname`, int `$flags` = 0): bool

Fügt dem Archiv ein neues Verzeichnis hinzu.

### Parameter-Liste

`dirname`

  Das hinzuzufügende Verzeichnis.

`flags`

  Eine Bitmaske bestehend aus `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. Das Verhalten dieser Konstanten wird in der ZIP Konstanten Seite beschrieben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` wurde hinzugefügt.

### Beispiele

Beispiel #1 Erstellt ein neues Verzeichnis im Archiv

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        if($zip->addEmptyDir('newDirectory')) {
            echo 'Neues Rootverzeichnis erstellt.';
        } else {
            echo 'Konnte Verzeichnis nicht erstellen.';
        }
        $zip->close();
    } else {
        echo 'Fehler';
    }
    ?>

# ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFile — Fügt eine Datei von einem gegebenen Pfad zu einem ZIP-Archiv hinzu

### Beschreibung

public function ZipArchive::addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool

Fügt eine Datei von einem gegebenen Pfad zu einem ZIP-Archiv hinzu.

> Hinweis: Für maximale Portierbarkeit wird empfohlen, in ZIP-Dateinamen immer Schrägstriche (`/`) als Verzeichnis-Trennzeichen zu verwenden.

### Parameter-Liste

`filepath`

  Der Pfad zur hinzuzufügenden Datei.

`entryname`

  Falls übergeben und nicht leer, ist dies der lokale Name innerhalb des ZIP-Archives, der den `filepath` überschreibt.

`start`

  Die Startposition für partielles Kopieren.

`length`

  Die Länge für partielles Kopieren; bei `ZipArchive::LENGTH_TO_END` (0) wird die Dateigröße verwendet, bei `ZipArchive::LENGTH_UNCHECKED` wird die gesamte Datei verwendet (beginnend bei `start`).

`flags`

  Eine Bitmaske bestehend aus `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. Das Verhalten dieser Konstanten wird auf der Seite ZIP-Konstanten beschrieben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` wurde hinzugefügt.
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` wurde hinzugefügt.
8.3.0, PECL zip 1.22.2 | `ZipArchive::LENGTH_TO_END` und `ZipArchive::LENGTH_UNCHECKED` wurden hinzugefügt.

### Beispiele

Dieses Beispiel öffnet ein ZIP-Dateiarchiv test.zip und fügt die Datei /pfad/zur/datei.txt als neuername.txt hinzu.

Beispiel #1 Öffnen und hinzufügen

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->addFile('/pfad/zur/datei.txt', 'neuername.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

### Anmerkungen

> Hinweis:

> Falls eine Datei zu einem Archiv hinzugefügt werden soll, wird PHP die Datei sperren; die Sperre wird erst gelöst, nachdem das ZipArchive-Objekt geschlossen wurde, entweder per ZipArchive::close(), oder weil das ZipArchive-Objekt zerstört wurde. Dies kann dazu führen, dass die hinzuzufügende Datei erst gelöscht werden kann, nachdem die Sperre gelöst wurde.

### Siehe auch

- ZipArchive::replaceFile() - Replace file in ZIP archive with a given path

# ZipArchive::addFromString

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFromString — Fügt eine Datei unter Verwendung ihres Inhalts zu einem ZIP-Archiv hinzu

### Beschreibung

public function ZipArchive::addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool

Fügt eine Datei unter Verwendung ihres Inhalts zu einem ZIP-Archiv hinzu.

> Hinweis: Für maximale Portierbarkeit wird empfohlen, in ZIP-Dateinamen immer Schrägstriche (`/`) als Verzeichnis-Trennzeichen zu verwenden.

### Parameter-Liste

`name`

  Der Name des anzulegenden Eintrags.

`content`

  Der Inhalt, der zum Erstellen des Eintrags verwendet werden soll. Dieser wird im Binary-safe-Modus verwendet.

`flags`

  Eine Bitmaske bestehend aus `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`. Das Verhalten dieser Konstanten wird in der ZIP-Konstanten Seite beschrieben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL zip 1.18.0 | `flags` wurde hinzugefügt.

### Beispiele

Beispiel #1 Einen Eintrag zu einem neuen Archiv hinzufügen

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'Dateiinhalt kommt hier');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

Beispiel #2 Eine Datei zu einem Verzeichnis innerhalb eines Archivs hinzufügen

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->addFromString('dir/test.txt', 'file content goes here');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

# ZipArchive::addGlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addGlob — Add files from a directory by glob pattern

### Beschreibung

public function ZipArchive::addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false

Add files from a directory which match the glob `pattern`.

> Hinweis: Für maximale Portierbarkeit wird empfohlen, in ZIP-Dateinamen immer Schrägstriche (`/`) als Verzeichnis-Trennzeichen zu verwenden.

### Parameter-Liste

`pattern`
  A glob() pattern against which files will be matched.
`flags`
  A bit mask of `glob()` flags.
`options`

  An associative array of options. Available options are:

  - `"add_path"` Prefix to prepend when translating to the local path of the file within the archive. This is applied after any remove operations defined by the `"remove_path"` or `"remove_all_path"` options.
  - `"remove_path"` Prefix to remove from matching file paths before adding to the archive.
  - `"remove_all_path"` `true` to use the file name only and add to the root of the archive.
  - `"flags"` Bitmask consisting of `ZipArchive::FL_OVERWRITE`, `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. The behaviour of these constants is described on the ZIP constants page.
  - `"comp_method"` Compression method, one of the `ZipArchive::CM_*` constants.
  - `"comp_flags"` Compression level.
  - `"enc_method"` Encryption method, one of the `ZipArchive::EM_*` constants.
  - `"enc_password"` Password used for encryption.

### Rückgabewerte

An array of added files on success Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL zip 1.18.0 | `"flags"` in `options` was added.
8.0.0, PECL zip 1.18.1 | `"comp_method"`, `"comp_flags"`, `"enc_method"` and `"enc_password"` in `options` were added.
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` was added.

### Beispiele

Beispiel #1 ZipArchive::addGlob() example

Add all php scripts and text files from current working directory

    <?php
    $zip = new ZipArchive();
    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
    if ($ret !== TRUE) {
        printf('Failed with code %d', $ret);
    } else {
        $options = array('add_path' => 'sources/', 'remove_all_path' => TRUE);
        $zip->addGlob('*.{php,txt}', GLOB_BRACE, $options);
        $zip->close();
    }
    ?>

### Siehe auch

- ZipArchive::addFile() - Fügt eine Datei von einem gegebenen Pfad zu einem ZIP-Archiv hinzu
- ZipArchive::addPattern() - Add files from a directory by PCRE pattern

# ZipArchive::addPattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addPattern — Add files from a directory by PCRE pattern

### Beschreibung

public function ZipArchive::addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false

Add files from a directory which match the regular expression `pattern`. The operation is not recursive. The pattern will be matched against the file name only.

### Parameter-Liste

`pattern`
  A PCRE pattern against which files will be matched.
`path`
  The directory that will be scanned. Defaults to the current working directory.
`options`
  An associative array of options accepted by ZipArchive::addGlob().

### Rückgabewerte

An array of added files on success Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 ZipArchive::addPattern() example

Add all php scripts and text files from current directory

    <?php
    $zip = new ZipArchive();
    $ret = $zip->open('application.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
    if ($ret !== TRUE) {
        printf('Failed with code %d', $ret);
    } else {
        $directory = realpath('.');
        $options = array('add_path' => 'sources/', 'remove_path' => $directory);
        $zip->addPattern('/\.(?:php|txt)$/', $directory, $options);
        $zip->close();
    }
    ?>

### Siehe auch

- ZipArchive::addFile() - Fügt eine Datei von einem gegebenen Pfad zu einem ZIP-Archiv hinzu
- ZipArchive::addGlob() - Add files from a directory by glob pattern

# ZipArchive::clearError

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::clearError — Clear the status error message, system and/or zip messages

### Beschreibung

public function ZipArchive::clearError(): void

Clear the status error message, system and/or zip messages.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- ZipArchive::getStatusString() - Gibt die Statusfehlermeldung sowie System- oder ZIP-Meldungen zurück

# ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::close — Schließt das aktive Archiv (geöffnet oder neu erstellt)

### Beschreibung

public function ZipArchive::close(): bool

Schließt das geöffnete oder neu erstellte Archiv und speichert die Änderungen. Diese Methode wird am Ende des Skripts automatisch aufgerufen.

Wenn das Archiv keine Dateien enthält, wird die Datei standardmäßig entsprechend dem Wert des globalen Flags `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` vollständig entfernt (es wird kein leeres Archiv gespeichert).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ZipArchive::setArchiveFlag() - Set a global flag of a ZIP archive

# ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::count — Counts the number of files in the archive

### Beschreibung

public function ZipArchive::count(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of files in the archive.

# ZipArchive::deleteIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteIndex — Löscht einen Archiveintrag unter Verwendung seines Index

### Beschreibung

public function ZipArchive::deleteIndex(int `$index`): bool

Löscht einen Archiveintrag unter Verwendung seines Index.

### Parameter-Liste

`index`

  Index des zu löschenden Eintrags.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Löschen einer Datei aus dem Archiv unter Verwendung ihres Index

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->deleteIndex(2);
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

# ZipArchive::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteName — Löscht einen Archiveintrag unter Verwendung seines Namens

### Beschreibung

public function ZipArchive::deleteName(string `$name`): bool

Löscht einen Archiveintrag unter Verwendung seines Namens.

### Parameter-Liste

`name`

  Name des zu löschenden Eintrags.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Eine Datei und ein Verzeichnis unter Verwendung ihrer Namen aus einem Archiv löschen

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        $zip->deleteName('testfromfile.php');
        $zip->deleteName('testDir/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

# ZipArchive::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractTo — Extrahiert den Archivinhalt

### Beschreibung

public function ZipArchive::extractTo(string `$pathto`, array|string|null `$files` = `null`): bool

Extrahiert das komplette Archiv oder die angegebenen Dateien in das angegebene Ziel.

Warnung

Die Standardberechtigungen für extrahierte Dateien und Verzeichnisse sind maximal großzügig ausgelegt. Dies kann eingeschränkt werden, wenn die aktuelle umask durch Verwendung von umask() gesetzt wird.

Aus Sicherheitsgründen werden die ursprünglichen Berechtigungen nicht wiederhergestellt. Wie diese wiederhergestellt werden können, zeigt das Codebeispiel auf der Seite ZipArchive::getExternalAttributesIndex().

### Parameter-Liste

`pathto`

  Stelle, an die die Dateien extrahiert werden sollen.

`files`

  Die zu extrahierenden Einträge. Es wird entweder ein einzelner Eintragsname oder ein Array von Namen akzeptiert.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Alle Einträge extrahieren

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->extractTo('/mein/ziel/verzeichnis/');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

Beispiel #2 Zwei Einträge extrahieren

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_im.zip');
    if ($res === TRUE) {
        $zip->extractTo('/mein/ziel/verzeichnis/', array('pear_item.gif', 'testfromfile.php'));
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

### Anmerkungen

> Hinweis:

> Windows NTFS-Dateisysteme unterstützen einige Zeichen in Dateinamen nicht, nämlich `<|>*?":`. Dateinamen mit einem Punkt am Ende werden ebenfalls nicht unterstützt. Im Gegensatz zu einigen Extraktionswerkzeugen ersetzt diese Methode diese Zeichen nicht durch einen Unterstrich, sondern extrahiert solche Dateien nicht.

# ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveComment — Gibt den ZIP-Archiv-Kommentar zurück

### Beschreibung

public function ZipArchive::getArchiveComment(int `$flags` = 0): string|false

Gibt den ZIP-Archiv-Kommentar zurück.

### Parameter-Liste

`flags`

  Ist flags auf`ZipArchive::FL_UNCHANGED` gesetzt, wird der originale unveränderte Kommentar zurückgegeben.

### Rückgabewerte

Gibt bei Erfolg den ZIP-Archiv-Kommentar zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Einen Archivkommentar ausgeben

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test_with_comment.zip');
    if ($res === TRUE) {
        var_dump($zip->getArchiveComment());
        /* Oder die Archiveigenschaft verwenden */
        var_dump($zip->comment);
    } else {
        echo 'Fehler, Code:' . $res;
    }
    ?>

# ZipArchive::getArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::getArchiveFlag — Returns the value of a Zip archive global flag

### Beschreibung

public function ZipArchive::getArchiveFlag(int `$flag`, int `$flags` = 0): int

Returns a Zip archive global flag value.

### Parameter-Liste

`flag`

  The global flag to retrieve, among `AFL_*` constants:

  - `ZipArchive::AFL_RDONLY`
  - `ZipArchive::AFL_IS_TORRENTZIP`
  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`flags`
  If `flags` is set to `ZipArchive::FL_UNCHANGED`, the original unchanged flag is returned.

### Rückgabewerte

Returns 1 if flag is set for archive, 0 if not, and -1 if an error occurred.

### Beispiele

Beispiel #1 Test if archive is a torrentzip format

    <?php

    $zip = new ZipArchive();
    $res = $zip->open('test.zip');

    if ($res === true) {
        var_dump($zip->getArchiveFlag(ZipArchive::AFL_IS_TORRENTZIP));
    } else {
        echo 'Failed, code: ' . $res;
    }

    ?>

### Siehe auch

- ZipArchive::setArchiveFlag() - Set a global flag of a ZIP archive

# ZipArchive::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndex — Gibt den Kommentar zu einem Eintrag unter Verwendung des Eintragsindex zurück

### Beschreibung

public function ZipArchive::getCommentIndex(int `$index`, int `$flags` = 0): string|false

Gibt den Kommentar zu einem Eintrag unter Verwendung des Eintragsindex zurück.

### Parameter-Liste

`index`

  Index des Eintrags.

`flags`

  Wenn das Flag auf `ZipArchive::FL_UNCHANGED` gesetzt ist, wird der originale Kommentar unverändert zurückgegeben.

### Rückgabewerte

Gibt bei Erfolg den Kommentar zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Einen Eintragskommentar ausgeben

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentIndex(1));
    } else {
        echo 'Fehler, Code:' . $res;
    }
    ?>

# ZipArchive::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentName — Gibt den Kommentar zu einem Eintrag unter Verwendung des Eintragsnamens zurück

### Beschreibung

public function ZipArchive::getCommentName(string `$name`, int `$flags` = 0): string|false

Gibt den Kommentar zu einem Eintrag unter Verwendung des Eintragsnamens zurück.

### Parameter-Liste

`name`

  Name des Eintrags.

`flags`

  Wenn das Flag auf `ZipArchive::FL_UNCHANGED` gesetzt ist, wird der originale Kommentar unverändert zurückgegeben.

### Rückgabewerte

Gibt bei Erfolg den Kommentar zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Einen Eintragskommentar ausgeben

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test1.zip');
    if ($res === TRUE) {
        var_dump($zip->getCommentName('test/eintrag1.txt'));
    } else {
        echo 'Fehler, Code:' . $res;
    }
    ?>

# ZipArchive::getExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesIndex — Retrieve the external attributes of an entry defined by its index

### Beschreibung

public function ZipArchive::getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Retrieve the external attributes of an entry defined by its index.

### Parameter-Liste

`index`
  Index of the entry.
`opsys`
  On success, receive the operating system code defined by one of the ZipArchive::OPSYS_ constants.
`attr`
  On success, receive the external attributes. Value depends on operating system.
`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged attributes are returned.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

This example extract all the entries of a ZIP archive test.zip and set the Unix rights from external attributes.

Beispiel #1 Extract all entries with Unix rights

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip') === TRUE) {
        for ($idx=0 ; $s = $zip->statIndex($idx) ; $idx++) {
            if ($zip->extractTo('.', $s['name'])) {
                if ($zip->getExternalAttributesIndex($idx, $opsys, $attr)
                    && $opsys==ZipArchive::OPSYS_UNIX) {
                   chmod($s['name'], ($attr >> 16) & 0777);
                }
            }
        }
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

# ZipArchive::getExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesName — Retrieve the external attributes of an entry defined by its name

### Beschreibung

public function ZipArchive::getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

Retrieve the external attributes of an entry defined by its name.

### Parameter-Liste

`name`
  Name of the entry.
`opsys`
  On success, receive the operating system code defined by one of the ZipArchive::OPSYS_ constants.
`attr`
  On success, receive the external attributes. Value depends on operating system.
`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged attributes are returned.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndex — Gibt den Inhalt eines Eintrags unter Verwendung seines Index zurück

### Beschreibung

public function ZipArchive::getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false

Gibt den Inhalt eines Eintrags unter Verwendung seines Index zurück.

### Parameter-Liste

`index`

  Index des Eintrags

`len`

  Die von dem Eintrag zu lesende Länge. Falls `0`, wird der gesamte Eintrag gelesen.

`flags`

  Die Flags, die beim Öffnen des Archivs verwendet werden können. Die folgenden Werte können darauf angewendet werden (ODER verknüpft):

  - `ZipArchive::FL_UNCHANGED`

  - `ZipArchive::FL_COMPRESSED`

### Rückgabewerte

Gibt im Erfolgsfall den Inhalt des Eintrags zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Den Dateiinhalt auslesen

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        echo $zip->getFromIndex(2);
        $zip->close();
    } else {
        echo 'Fehler';
    }
    ?>

### Siehe auch

- ZipArchive::getFromName() - Gibt den Inhalt eines Eintrags unter Verwendung seines Namens zurück

# ZipArchive::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromName — Gibt den Inhalt eines Eintrags unter Verwendung seines Namens zurück

### Beschreibung

public function ZipArchive::getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false

Gibt den Inhalt eines Eintrags unter Verwendung seines Namens zurück.

### Parameter-Liste

`name`

  Name des Eintrags

`len`

  Die von dem Eintrag zu lesende Länge. Falls `0`, wird der gesamte Eintrag gelesen.

`flags`

  Die Flags, die beim Suchen des Eintrags verwendet werden können. Die folgenden Werte können darauf angewendet werden (ODER-verknüpft):

  - `ZipArchive::FL_UNCHANGED`

  - `ZipArchive::FL_COMPRESSED`

  - `ZipArchive::FL_NOCASE`

### Rückgabewerte

Gibt im Erfolgsfall den Inhalt des Eintrags zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Den Dateiinhalt auslesen

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test1.zip') === TRUE) {
        echo $zip->getFromName('testfromfile.php');
        $zip->close();
    } else {
        echo 'Fehler';
    }
    ?>

Beispiel #2 Ein Bild aus einem ZIP-Eintrag konvertieren

    <?php
    $z = new ZipArchive();
    if ($z->open(dirname(__FILE__) . '/test_im.zip')) {
        $im_string = $z->getFromName("pear_item.gif");
        $im = imagecreatefromstring($im_string);
        imagepng($im, 'b.png');
    }
    ?>

### Siehe auch

- ZipArchive::getFromIndex() - Gibt den Inhalt eines Eintrags unter Verwendung seines Index zurück

# ZipArchive::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndex — Gibt den Namen eines Eintrags unter Verwendung seines Index zurück

### Beschreibung

public function ZipArchive::getNameIndex(int `$index`, int `$flags` = 0): string|false

Gibt den Namen eines Eintrags unter Verwendung seines Index zurück.

### Parameter-Liste

`index`

  Index des Eintrags.

`flags`

  Ist flags auf`ZipArchive::FL_UNCHANGED` gesetzt, wird der originale unveränderte Name zurückgegeben.

### Rückgabewerte

Gibt im Erfolgsfall den Namen zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 ZipArchive::getNameIndex()-Beispiel

    <?php
    if ($zip->open('test.zip') == TRUE) {
     for ($i = 0; $i < $zip->numFiles; $i++) {
         $filename = $zip->getNameIndex($i);
         // ...
     }
    }
    ?>

# ZipArchive::getStatusString

(PHP 5 >= 5.2.7, PHP 7, PHP 8)

ZipArchive::getStatusString — Gibt die Statusfehlermeldung sowie System- oder ZIP-Meldungen zurück

### Beschreibung

public function ZipArchive::getStatusString(): string

Gibt die Statusfehlermeldung sowie System- oder ZIP-Meldungen zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert einen string mit der Statusmeldung.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL zip 1.18.0 | Diese Methode kann für ein geschlossenes Archiv aufgerufen werden.
8.0.0, PECL zip 1.18.0 | Diese Methode gibt im Fall eines Fehlers nicht mehr `false` zurück.

# ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStream — Erzeugt einen Dateizeiger zu dem per Name bestimmten Eintrag (nur lesend)

### Beschreibung

public function ZipArchive::getStream(string `$name`): resource|false

Erzeugt einen Dateizeiger zu dem per Name bestimmten Eintrag. Derzeit werden nur Leseoperationen unterstützt.

### Parameter-Liste

`name`

  Der Name des zu verwendenden Eintrags.

### Rückgabewerte

Gibt im Erfolgsfall einen Dateizeiger (Ressource) zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Den Eintragsinhalt mit fread() abrufen und speichern

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStream('test');
        if(!$fp) exit("Fehler\n");

        while (!feof($fp)) {
            $contents .= fread($fp, 2);
        }

        fclose($fp);
        file_put_contents('t',$contents);
        echo "Erledigt.\n";
    }
    ?>

Beispiel #2 Das gleiche wie im vorigen Beispiel aber mit fopen() und dem ZIP-Streamwrapper

    <?php
    $contents = '';
    $fp = fopen('zip://' . dirname(__FILE__) . '/test.zip#test', 'r');
    if (!$fp) {
        exit("Datei kann nicht geöffnet werden\n");
    }
    while (!feof($fp)) {
        $contents .= fread($fp, 2);
    }
    echo "$contents\n";
    fclose($fp);
    echo "Erledigt.\n";
    ?>

Beispiel #3 Streamwrapper und Bild, kann auch mit der XML-Funktion verwendet werden

    <?php
    $im = imagecreatefromgif('zip://' . dirname(__FILE__) . '/test_im.zip#pear_item.gif');
    imagepng($im, 'a.png');
    ?>

### Siehe auch

- ZipArchive::getStreamIndex() - Get a file handler to the entry defined by its index (read only)
- ZipArchive::getStreamName() - Get a file handler to the entry defined by its name (read only)
- Datenkomprimierungsströme

# ZipArchive::getStreamIndex

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamIndex — Get a file handler to the entry defined by its index (read only)

### Beschreibung

public function ZipArchive::getStreamIndex(int `$index`, int `$flags` = 0): resource|false

Get a file handler to the entry defined by its index. For now, it only supports read operations.

### Parameter-Liste

`index`
  Index of the entry
`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged stream is returned.

### Rückgabewerte

Returns a file pointer (resource) on successBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Get the entry contents with fread() and store it

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamIndex(1, ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Siehe auch

- ZipArchive::getStreamName() - Get a file handler to the entry defined by its name (read only)

# ZipArchive::getStreamName

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamName — Get a file handler to the entry defined by its name (read only)

### Beschreibung

public function ZipArchive::getStreamName(string `$name`, int `$flags` = 0): resource|false

Get a file handler to the entry defined by its name. For now, it only supports read operations.

### Parameter-Liste

`name`
  The name of the entry to use.
`flags`
  If flags is set to `ZipArchive::FL_UNCHANGED`, the original unchanged stream is returned.

### Rückgabewerte

Returns a file pointer (resource) on successBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Get the entry contents with fread() and store it

    <?php
    $contents = '';
    $z = new ZipArchive();
    if ($z->open('test.zip')) {
        $fp = $z->getStreamName('test', ZipArchive::FL_UNCHANGED);
        if(!$fp) die($z->getStatusString());

        echo stream_get_contents($fp);

        fclose($fp);
    }
    ?>

### Siehe auch

- ZipArchive::getStreamIndex() - Get a file handler to the entry defined by its index (read only)

# ZipArchive::isCompressionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isCompressionMethodSupported — Check if a compression method is supported by libzip

### Beschreibung

public static function ZipArchive::isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Check if a compression method is supported by libzip.

### Parameter-Liste

`method`
  The compression method, one of the `ZipArchive::CM_*` constants.
`enc`
  If `true` check for compression, else check for decompression.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Anmerkungen

> Hinweis: This function is only available if built against libzip ≥ 1.7.0.

### Siehe auch

- ZipArchive::setCompressionIndex() - Set the compression method of an entry defined by its index
- ZipArchive::setCompressionName() - Set the compression method of an entry defined by its name

# ZipArchive::isEncryptionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isEncryptionMethodSupported — Check if a encryption method is supported by libzip

### Beschreibung

public static function ZipArchive::isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool

Check if a compression method is supported by libzip.

### Parameter-Liste

`method`
  The encryption method, one of the `ZipArchive::EM_*` constants.
`enc`
  If `true` check for encryption, else check for decryption.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Anmerkungen

> Hinweis: This function is only available if built against libzip ≥ 1.7.0.

### Siehe auch

- ZipArchive::setEncryptionIndex() - Set the encryption method of an entry defined by its index
- ZipArchive::setEncryptionName() - Set the encryption method of an entry defined by its name

# ZipArchive::locateName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::locateName — Gibt den Index eines Archiveintrags zurück

### Beschreibung

public function ZipArchive::locateName(string `$name`, int `$flags` = 0): int|false

Lokalisiert einen Eintrag unter Verwendung seines Namens.

### Parameter-Liste

`name`

  Der Name des Eintrags, nach dem gesucht werden soll.

`flags`

  Die Funktion gibt den Index der Datei namens fname im Archiv zurück. Die Flags können miteinander kombiniert werden, soll keines davon genutzt werden, sollte 0 verwendet werden.

  - `ZipArchive::FL_NOCASE`

  - `ZipArchive::FL_NODIR`

### Rückgabewerte

Gibt im Erfolgsfall den Index eines Eintrags zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Ein Archiv erstellen und es mit locateName verwenden

    <?php
    $file = 'testlocate.zip';

    $zip = new ZipArchive;
    if ($zip->open($file, ZipArchive::CREATE) !== TRUE) {
        exit('Fehler');
    }

    $zip->addFromString('eintrag1.txt', 'Eintrag #1');
    $zip->addFromString('eintrag2.txt', 'Eintrag #2');
    $zip->addFromString('dir/eintrag2d.txt', 'Eintrag #2');

    if ($zip->status == ZipArchive::ER_OK) {
        echo "Fehler beim Schreiben des ZIP\n";
    }
    $zip->close();

    if ($zip->open($file) !== TRUE) {
        exit('Fehler');
    }

    echo $zip->locateName('eintrag1.txt') . "\n";
    echo $zip->locateName('eiNtrag2.txt') . "\n";
    echo $zip->locateName('eiNtrag2.txt', ZipArchive::FL_NOCASE) . "\n";
    echo $zip->locateName('einTRag2d.txt', ZipArchive::FL_NOCASE|ZipArchive::FL_NODIR) . "\n";
    $zip->close();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0

    1
    2

# ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::open — Öffnet ein ZIP-Dateiarchiv

### Beschreibung

public function ZipArchive::open(string `$filename`, int `$flags` = 0): bool|int

Öffnet ein neues oder existierendes ZIP-Archiv für Lese-, Schreib- und Veränderungszugriffe.

Seit libzip 1.6.0 wird eine leere Datei nicht länger als gültiges Archiv angesehen.

### Parameter-Liste

`filename`

  Der Name des zu öffnenden ZIP-Archivs.

`flags`

  Der Modus, in dem das zu öffnende Archiv verwendet werden soll.

  - `ZipArchive::OVERWRITE`

  - `ZipArchive::CREATE`

  - `ZipArchive::RDONLY`

  - `ZipArchive::EXCL`

  - `ZipArchive::CHECKCONS`

### Rückgabewerte

Gibt bei Erfolg `true` zurück, bei einem Fehler `false` oder einen der folgenden Fehlercodes:

`ZipArchive::ER_EXISTS`
  Die Datei existiert bereits.
`ZipArchive::ER_INCONS`
  Das Zip-Archiv ist inkonsistent.
`ZipArchive::ER_INVAL`
  Ungültiges Argument.
`ZipArchive::ER_MEMORY`
  Malloc-Fehler.
`ZipArchive::ER_NOENT`
  Keine solche Datei.
`ZipArchive::ER_NOZIP`
  Kein ZIP-Archiv.
`ZipArchive::ER_OPEN`
  Datei konnte nicht geöffnet werden.
`ZipArchive::ER_READ`
  Lesefehler.
`ZipArchive::ER_SEEK`
  Positionierungsfehler.

### Beispiele

Beispiel #1 Öffnen und extrahieren

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        echo 'ok';
        $zip->extractTo('test');
        $zip->close();
    } else {
        echo 'Fehler, Code:' . $res;
    }
    ?>

Beispiel #2 Ein Archiv erstellen

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'Der Dateiinhalt kommt hier');
        $zip->addFile('data.txt', 'eintragsname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

Beispiel #3 Erstellen eines temporären Archivs

    <?php
    $name = tempnam(sys_get_temp_dir(), "FOO");
    $zip = new ZipArchive;
    $res = $zip->open($name, ZipArchive::OVERWRITE); /* trunkieren, da eine leere Datei nicht gültig ist */
    if ($res === TRUE) {
        $zip->addFile('data.txt', 'eintragsname.txt');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

# ZipArchive::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallback — Register a callback to allow cancellation during archive close.

### Beschreibung

public function ZipArchive::registerCancelCallback(callable `$callback`): bool

Register a `callback` function to allow cancellation during archive close.

### Parameter-Liste

`callback`
  If this function return 0 operation will continue, other value it will be cancelled.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

This example creates a ZIP file archive php.zip and cancel operation on some run condition.

Beispiel #1 Archive a file

    <?php
    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerCancelCallback(function () {
            return ($someruncondition ? -1 : 0);
        });
        $zip->close();
    }

### Anmerkungen

> Hinweis: This function is only available if built against libzip ≥ 1.6.0.

### Siehe auch

- ZipArchive::registerProgressCallback() - Register a callback to provide updates during archive close.

# ZipArchive::registerProgressCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerProgressCallback — Register a callback to provide updates during archive close.

### Beschreibung

public function ZipArchive::registerProgressCallback(float `$rate`, callable `$callback`): bool

Register a `callback` function to provide updates during archive close.

### Parameter-Liste

`rate`
  Change between each call of the callback (from 0.0 to 1.0).
`callback`
  This function will receive the current `state` as a float (from 0.0 to 1.0).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

This example creates a ZIP file archive php.zip and show progression.

Beispiel #1 Archive a file

    $zip = new ZipArchive();
    if ($zip->open('php.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE)) {
        $zip->addFile(PHP_BINARY, 'php');
        $zip->registerProgressCallback(0.05, function ($r) {
            printf("%d%%\n", $r * 100);
        });
        $zip->close();
    }

### Anmerkungen

> Hinweis: This function is only available if built against libzip ≥ 1.3.0.

### Siehe auch

- ZipArchive::registerCancelCallback() - Register a callback to allow cancellation during archive close.

# ZipArchive::renameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameIndex — Benennt einen durch seinen Index bestimmten Eintrag um

### Beschreibung

public function ZipArchive::renameIndex(int `$index`, string `$new_name`): bool

Benennt einen durch seinen Index bestimmten Eintrag um.

### Parameter-Liste

`index`

  Index des umzubenennenden Eintrags.

`new-name`

  Neuer Name.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Einen Eintrag umbenennen

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameIndex(2,'neuer_name.txt');
        $zip->close();
    } else {
        echo 'Fehler, Code:' . $res;
    }
    ?>

# ZipArchive::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameName — Benennt einen durch seinen Namen bestimmten Eintrag um

### Beschreibung

public function ZipArchive::renameName(string `$name`, string `$new_name`): bool

Benennt einen durch seinen Namen bestimmten Eintrag um.

### Parameter-Liste

`name`

  Name des umzubenennenden Eintrags.

`new_name`

  Neuer Name.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Einen Eintrag umbenennen

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->renameName('aktueller_name.txt','neuer_name.txt');
        $zip->close();
    } else {
        echo 'Fehler, Code:' . $res;
    }
    ?>

# ZipArchive::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFile — Replace file in ZIP archive with a given path

### Beschreibung

public function ZipArchive::replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool

Replace file in ZIP archive with a given path.

> Hinweis: Für maximale Portierbarkeit wird empfohlen, in ZIP-Dateinamen immer Schrägstriche (`/`) als Verzeichnis-Trennzeichen zu verwenden.

### Parameter-Liste

`filepath`
  The path to the file to add.
`index`
  The index of the file to be replaced, its name is unchanged.
`start`
  For partial copy, start position.
`length`
  For partial copy, length to be copied, if `ZipArchive::LENGTH_TO_END` (0) the file size is used, if `ZipArchive::LENGTH_UNCHECKED` the whole file is used (starting from `start`).
`flags`
  Bitmask consisting of `ZipArchive::FL_ENC_GUESS`, `ZipArchive::FL_ENC_UTF_8`, `ZipArchive::FL_ENC_CP437`, `ZipArchive::FL_OPEN_FILE_NOW`. The behaviour of these constants is described on the ZIP constants page.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` was added.
8.3.0, PECL zip 1.22.2 | `ZipArchive::LENGTH_TO_END` and `ZipArchive::LENGTH_UNCHECKED` were added.

### Beispiele

This example opens a ZIP file archive test.zip and replaces index 1 entry with /path/to/index.txt.

Beispiel #1 Open and replace

    <?php
    $zip = new ZipArchive;
    if ($zip->open('test.zip') === TRUE) {
        $zip->replaceFile('/path/to/index.txt', 1);
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

### Siehe auch

- ZipArchive::addFile() - Fügt eine Datei von einem gegebenen Pfad zu einem ZIP-Archiv hinzu

# ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveComment — Setzt einen Kommentar zu einem ZIP-Archiv

### Beschreibung

public function ZipArchive::setArchiveComment(string `$comment`): bool

Setzt einen Kommentar zu einem ZIP-Archiv.

### Parameter-Liste

`comment`

  Der Inhalt des Kommentars.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Ein Archiv erstellen und einen Kommentar hinzufügen

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('test.txt', 'Der Dateiinhalt kommt hier');
        $zip->setArchiveComment('Neuer Archivkommentar');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

# ZipArchive::setArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::setArchiveFlag — Set a global flag of a ZIP archive

### Beschreibung

public function ZipArchive::setArchiveFlag(int `$flag`, int `$value`): bool

Set a global flag of a ZIP archive.

### Parameter-Liste

`flag`

  The global flag to change, among `AFL_*` constants.

  - `ZipArchive::AFL_WANT_TORRENTZIP`
  - `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE`
`value`
  The new value of the flag.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Create a torrentzip archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->setArchiveFlag(ZipArchive::AFL_WANT_TORRENTZIP, 1);
        $zip->addFromString('test.txt', 'file content goes here');
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

### Siehe auch

- ZipArchive::getArchiveFlag() - Returns the value of a Zip archive global flag

# ZipArchive::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndex — Setzt einen Eintragskommentar, der via Eintragsindex bestimmt wird

### Beschreibung

public function ZipArchive::setCommentIndex(int `$index`, string `$comment`): bool

Setzt einen Eintragskommentar, der via Eintragsindex bestimmt wird.

### Parameter-Liste

`index`

  Index des Eintrags.

`comment`

  Der Inhalt des Kommentars.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Ein Archiv öffnen und für einen Eintrag einen Kommentar hinzufügen

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentIndex(2, 'Neuer Eintragskommentar');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

# ZipArchive::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentName — Setzt einen Eintragskommentar, der via Eintragsnamen bestimmt wird

### Beschreibung

public function ZipArchive::setCommentName(string `$name`, string `$comment`): bool

Setzt einen Eintragskommentar, der via Eintragsnamen bestimmt wird.

### Parameter-Liste

`name`

  Name des Eintrags.

`comment`

  Der Inhalt des Kommentars.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Ein Archiv öffnen und für einen Eintrag einen Kommentar hinzufügen

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        $zip->setCommentName('eintrag1.txt', 'Neuer Eintragskommentar');
        $zip->close();
        echo 'ok';
    } else {
        echo 'Fehler';
    }
    ?>

# ZipArchive::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndex — Set the compression method of an entry defined by its index

### Beschreibung

public function ZipArchive::setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool

Set the compression method of an entry defined by its index.

### Parameter-Liste

`index`
  Index of the entry.
`method`
  The compression method, one of the `ZipArchive::CM_*` constants.
`compflags`
  Compression level.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Add files with different compression methods to an archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('foo', 'Some text');
        $zip->addFromString('bar', 'Some other text');
        $zip->setCompressionIndex(0, ZipArchive::CM_STORE);
        $zip->setCompressionIndex(1, ZipArchive::CM_DEFLATE);
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::setCompressionName

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionName — Set the compression method of an entry defined by its name

### Beschreibung

public function ZipArchive::setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool

Set the compression method of an entry defined by its name.

### Parameter-Liste

`name`
  Name of the entry.
`method`
  The compression method, one of the `ZipArchive::CM_*` constants.
`compflags`
  Compression level.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Add files with different compression methods to an archive

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFromString('foo', 'Some text');
        $zip->addFromString('bar', 'Some other text');
        $zip->setCompressionName('foo', ZipArchive::CM_STORE);
        $zip->setCompressionName('bar', ZipArchive::CM_DEFLATE);
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

Beispiel #2 Add file and set compression method

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip', ZipArchive::CREATE);
    if ($res === TRUE) {
        $zip->addFile('foo.jpg', 'bar.jpg');
        $zip->setCompressionName('bar.jpg', ZipArchive::CM_XZ);
        $zip->close();
        echo 'ok';
    } else {
        echo 'failed';
    }
    ?>

# ZipArchive::setEncryptionIndex

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionIndex — Set the encryption method of an entry defined by its index

### Beschreibung

public function ZipArchive::setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Set the encryption method of an entry defined by its index.

### Parameter-Liste

`index`
  Index of the entry.
`method`
  The encryption method defined by one of the ZipArchive::EM_ constants.
`password`
  Optional password, default used when missing.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `password` is now nullable.

### Anmerkungen

> Hinweis: This function is only available if built against libzip ≥ 1.2.0.

### Siehe auch

- ZipArchive::setPassword() - Set the password for the active archive
- ZipArchive::setEncryptionName() - Set the encryption method of an entry defined by its name

# ZipArchive::setEncryptionName

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionName — Set the encryption method of an entry defined by its name

### Beschreibung

public function ZipArchive::setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter]?string `$password` = `null`): bool

Set the encryption method of an entry defined by its name.

### Parameter-Liste

`name`
  Name of the entry.
`method`
  The encryption method defined by one of the ZipArchive::EM_ constants.
`password`
  Optional password, default used when missing.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `password` is now nullable.

### Beispiele

This example creates a ZIP file archive test.zip and add the file test.txt encrypted using the AES 256 method.

Beispiel #1 Archive and encrypt a file

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->setPassword('secret');
        $zip->addFile('text.txt');
        $zip->setEncryptionName('text.txt', ZipArchive::EM_AES_256);
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Anmerkungen

> Hinweis: This function is only available if built against libzip ≥ 1.2.0.

### Siehe auch

- ZipArchive::setPassword() - Set the password for the active archive
- ZipArchive::setEncryptionIndex() - Set the encryption method of an entry defined by its index

# ZipArchive::setExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesIndex — Set the external attributes of an entry defined by its index

### Beschreibung

public function ZipArchive::setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Set the external attributes of an entry defined by its index.

### Parameter-Liste

`index`
  Index of the entry.
`opsys`
  The operating system code defined by one of the ZipArchive::OPSYS_ constants.
`attr`
  The external attributes. Value depends on operating system.
`flags`
  Optional flags. Currently unused.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ZipArchive::setExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesName — Set the external attributes of an entry defined by its name

### Beschreibung

public function ZipArchive::setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

Set the external attributes of an entry defined by its name.

### Parameter-Liste

`name`
  Name of the entry.
`opsys`
  The operating system code defined by one of the ZipArchive::OPSYS_ constants.
`attr`
  The external attributes. Value depends on operating system.
`flags`
  Optional flags. Currently unused.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

This example opens a ZIP file archive test.zip and add the file test.txt with its Unix rights as external attributes.

Beispiel #1 Archive a file, with its Unix rights

    <?php
    $zip = new ZipArchive();
    $stat = stat($filename='test.txt');
    if (is_array($stat) && $zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile($filename);
        $zip->setExternalAttributesName($filename, ZipArchive::OPSYS_UNIX, $stat['mode'] << 16);
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

# ZipArchive::setMtimeIndex

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeIndex — Set the modification time of an entry defined by its index

### Beschreibung

public function ZipArchive::setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool

Set the modification time of an entry defined by its index.

### Parameter-Liste

`index`
  Index of the entry.
`timestamp`
  The modification time (unix timestamp) of the file.
`flags`
  Optional flags, unused for now.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

This example creates a ZIP file archive test.zip and add the file test.txt with its modification date.

Beispiel #1 Archive a file

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeIndex(0, mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Anmerkungen

> Hinweis: This function is only available if built against libzip ≥ 1.0.0.

### Siehe auch

- ZipArchive::setMtimeName() - Set the modification time of an entry defined by its name

# ZipArchive::setMtimeName

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeName — Set the modification time of an entry defined by its name

### Beschreibung

public function ZipArchive::setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool

Set the modification time of an entry defined by its name.

### Parameter-Liste

`name`
  Name of the entry.
`timestamp`
  The modification time (unix timestamp) of the file.
`flags`
  Optional flags, unused for now.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

This example creates a ZIP file archive test.zip and add the file test.txt with its modification date.

Beispiel #1 Archive a file

    <?php
    $zip = new ZipArchive();
    if ($zip->open('test.zip', ZipArchive::CREATE) === TRUE) {
        $zip->addFile('text.txt');
        $zip->setMtimeName('text.txt', mktime(0,0,0,12,25,2019));
        $zip->close();
        echo "Ok\n";
    } else {
        echo "KO\n";
    }
    ?>

### Anmerkungen

> Hinweis: This function is only available if built against libzip ≥ 1.0.0.

### Siehe auch

- ZipArchive::setMtimeIndex() - Set the modification time of an entry defined by its index

# ZipArchive::setPassword

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setPassword — Set the password for the active archive

### Beschreibung

public function ZipArchive::setPassword(#[\SensitiveParameter]string `$password`): bool

Sets the password for the active archive.

### Parameter-Liste

`password`
  The password to be used for the archive.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Anmerkungen

> Hinweis: As of PHP 7.2.0 and libzip 1.2.0 the password is used to decompress the archive, and is also the default password for ZipArchive::setEncryptionName() and ZipArchive::setEncryptionIndex(). Formerly, this function only set the password to be used to decompress the archive; it did not turn a non-password-protected ZipArchive into a password-protected ZipArchive.

### Siehe auch

- ZipArchive::setEncryptionIndex() - Set the encryption method of an entry defined by its index
- ZipArchive::setEncryptionName() - Set the encryption method of an entry defined by its name

# ZipArchive::statIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::statIndex — Gibt die Details eines via Index bestimmten Eintrags zurück

### Beschreibung

public function ZipArchive::statIndex(int `$index`, int `$flags` = 0): array|false

Die Funktion erhält Informationen über einen Eintrag, der mittels seines Index bestimmt wird.

### Parameter-Liste

`index`

  Index des Eintrags.

`flags`

  `ZipArchive::FL_UNCHANGED` kann angewendet werden, um ohne Berücksichtigung eventueller Veränderungen Informationen über die originale Datei im Archiv zu erhalten.

### Rückgabewerte

Gibt ein Array zurück, das die Eintragsdetails enthält. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Die Statusinformation eines Eintrags ausgeben

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statIndex(3));
        $zip->close();
    } else {
        echo 'Fehler, Code:' . $res;
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::statName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::statName — Gibt die Details eines via Namen bestimmten Eintrags zurück

### Beschreibung

public function ZipArchive::statName(string `$name`, int `$flags` = 0): array|false

Die Funktion erhält Informationen über einen Eintrag, der mittels seines Namens bestimmt wird.

### Parameter-Liste

`name`

  Name des Eintrags

`flags`

  Das flags-Argument gibt an, wie die Namensauflösung durchgeführt werden soll. Außerdem kann `ZipArchive::FL_UNCHANGED` angewendet werden, um ohne Berücksichtigung eventueller Veränderungen Informationen über die originale Datei im Archiv zu erhalten.

  - `ZipArchive::FL_NOCASE`

  - `ZipArchive::FL_NODIR`

  - `ZipArchive::FL_UNCHANGED`

### Rückgabewerte

Gibt ein Array zurück, das die Eintragsdetails enthält. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Die Statusinformation eines Eintrags ausgeben

    <?php
    $zip = new ZipArchive;
    $res = $zip->open('test.zip');
    if ($res === TRUE) {
        print_r($zip->statName('foobar/baz'));
        $zip->close();
    } else {
        echo 'Fehler, Code:' . $res;
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [name] => foobar/baz
        [index] => 3
        [crc] => 499465816
        [size] => 27
        [mtime] => 1123164748
        [comp_size] => 24
        [comp_method] => 8
    )

# ZipArchive::unchangeAll

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeAll — Setzt alle im Archiv durchgeführten Änderungen zurück

### Beschreibung

public function ZipArchive::unchangeAll(): bool

Setzt alle im Archiv durchgeführten Änderungen zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchive — Nimmt alle globalen Änderungen zurück, die im Archiv durchgeführt wurden

### Beschreibung

public function ZipArchive::unchangeArchive(): bool

Nimmt alle globalen Änderungen zurück, die im Archiv durchführt wurden. Derzeit bedeutet das, dass nur Änderungen an Archivkommentaren zurückgenommen werden können.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndex — Nimmt alle Änderungen zurück, die auf dem Eintrag mit dem gegebenen Index gemacht wurden

### Beschreibung

public function ZipArchive::unchangeIndex(int `$index`): bool

Nimmt alle Änderungen zurück, die auf dem Eintrag mit dem gegebenen Index gemacht wurden.

### Parameter-Liste

`index`

  Index des Eintrags.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeName — Nimmt alle Änderungen zurück, die auf dem Eintrag mit dem gegebenen Namen gemacht wurden

### Beschreibung

public function ZipArchive::unchangeName(string `$name`): bool

Nimmt alle zu einem Eintrag gehörenden Veränderungen zurück.

### Parameter-Liste

`name`

  Name des Eintrags.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

## Inhaltsverzeichnis

- ZipArchive::addEmptyDir — Fügt ein neues Verzeichnis hinzu
- ZipArchive::addFile — Fügt eine Datei von einem gegebenen Pfad zu einem ZIP-Archiv hinzu
- ZipArchive::addFromString — Fügt eine Datei unter Verwendung ihres Inhalts zu einem ZIP-Archiv hinzu
- ZipArchive::addGlob — Add files from a directory by glob pattern
- ZipArchive::addPattern — Add files from a directory by PCRE pattern
- ZipArchive::clearError — Clear the status error message, system and/or zip messages
- ZipArchive::close — Schließt das aktive Archiv (geöffnet oder neu erstellt)
- ZipArchive::count — Counts the number of files in the archive
- ZipArchive::deleteIndex — Löscht einen Archiveintrag unter Verwendung seines Index
- ZipArchive::deleteName — Löscht einen Archiveintrag unter Verwendung seines Namens
- ZipArchive::extractTo — Extrahiert den Archivinhalt
- ZipArchive::getArchiveComment — Gibt den ZIP-Archiv-Kommentar zurück
- ZipArchive::getArchiveFlag — Returns the value of a Zip archive global flag
- ZipArchive::getCommentIndex — Gibt den Kommentar zu einem Eintrag unter Verwendung des Eintragsindex zurück
- ZipArchive::getCommentName — Gibt den Kommentar zu einem Eintrag unter Verwendung des Eintragsnamens zurück
- ZipArchive::getExternalAttributesIndex — Retrieve the external attributes of an entry defined by its index
- ZipArchive::getExternalAttributesName — Retrieve the external attributes of an entry defined by its name
- ZipArchive::getFromIndex — Gibt den Inhalt eines Eintrags unter Verwendung seines Index zurück
- ZipArchive::getFromName — Gibt den Inhalt eines Eintrags unter Verwendung seines Namens zurück
- ZipArchive::getNameIndex — Gibt den Namen eines Eintrags unter Verwendung seines Index zurück
- ZipArchive::getStatusString — Gibt die Statusfehlermeldung sowie System- oder ZIP-Meldungen zurück
- ZipArchive::getStream — Erzeugt einen Dateizeiger zu dem per Name bestimmten Eintrag (nur lesend)
- ZipArchive::getStreamIndex — Get a file handler to the entry defined by its index (read only)
- ZipArchive::getStreamName — Get a file handler to the entry defined by its name (read only)
- ZipArchive::isCompressionMethodSupported — Check if a compression method is supported by libzip
- ZipArchive::isEncryptionMethodSupported — Check if a encryption method is supported by libzip
- ZipArchive::locateName — Gibt den Index eines Archiveintrags zurück
- ZipArchive::open — Öffnet ein ZIP-Dateiarchiv
- ZipArchive::registerCancelCallback — Register a callback to allow cancellation during archive close.
- ZipArchive::registerProgressCallback — Register a callback to provide updates during archive close.
- ZipArchive::renameIndex — Benennt einen durch seinen Index bestimmten Eintrag um
- ZipArchive::renameName — Benennt einen durch seinen Namen bestimmten Eintrag um
- ZipArchive::replaceFile — Replace file in ZIP archive with a given path
- ZipArchive::setArchiveComment — Setzt einen Kommentar zu einem ZIP-Archiv
- ZipArchive::setArchiveFlag — Set a global flag of a ZIP archive
- ZipArchive::setCommentIndex — Setzt einen Eintragskommentar, der via Eintragsindex bestimmt wird
- ZipArchive::setCommentName — Setzt einen Eintragskommentar, der via Eintragsnamen bestimmt wird
- ZipArchive::setCompressionIndex — Set the compression method of an entry defined by its index
- ZipArchive::setCompressionName — Set the compression method of an entry defined by its name
- ZipArchive::setEncryptionIndex — Set the encryption method of an entry defined by its index
- ZipArchive::setEncryptionName — Set the encryption method of an entry defined by its name
- ZipArchive::setExternalAttributesIndex — Set the external attributes of an entry defined by its index
- ZipArchive::setExternalAttributesName — Set the external attributes of an entry defined by its name
- ZipArchive::setMtimeIndex — Set the modification time of an entry defined by its index
- ZipArchive::setMtimeName — Set the modification time of an entry defined by its name
- ZipArchive::setPassword — Set the password for the active archive
- ZipArchive::statIndex — Gibt die Details eines via Index bestimmten Eintrags zurück
- ZipArchive::statName — Gibt die Details eines via Namen bestimmten Eintrags zurück
- ZipArchive::unchangeAll — Setzt alle im Archiv durchgeführten Änderungen zurück
- ZipArchive::unchangeArchive — Nimmt alle globalen Änderungen zurück, die im Archiv durchgeführt wurden
- ZipArchive::unchangeIndex — Nimmt alle Änderungen zurück, die auf dem Eintrag mit dem gegebenen Index gemacht wurden
- ZipArchive::unchangeName — Nimmt alle Änderungen zurück, die auf dem Eintrag mit dem gegebenen Namen gemacht wurden

# Zip Funktionen

Warnung

Die procedurale API sollte ab PHP 8.0.0 nicht mehr verwendet werden. Stattdessen sollte ZipArchive verwendet werden.

# zip_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_close — Schließt ein ZIP-Archiv

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_close(resource `$zip`): void

Schließt das übergebene ZIP-Archiv.

### Parameter-Liste

`zip`

  Eine ZIP-Datei, die zuvor mittels zip_open() geöffnet wurde.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt; siehe ZipArchive::close().

### Siehe auch

- zip_open() - Öffnet ein ZIP-Archiv
- zip_read() - Liest den nächsten Eintrag innerhalb des ZIP-Archivs

# zip_entry_close

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_close — Schließt einen Verzeichniseintrag

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_entry_close(resource `$zip_entry`): bool

Schließt den angegebenen Verzeichniseintrag.

### Parameter-Liste

`zip_entry`

  Ein Verzeichniseintrag, der zuvor mit zip_entry_open() geöffnet wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt.

### Siehe auch

- zip_entry_open() - Öffnet einen Verzeichniseintrag für den Lesezugriff
- zip_entry_read() - Liest einen geöffneten Verzeichniseintrag aus

# zip_entry_compressedsize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressedsize — Ermittelt die komprimierte Größe eines Verzeichniseintrages

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_entry_compressedsize(resource `$zip_entry`): int|false

Gibt die komprimierte Größe des angegebenen Verzeichniseintrages zurück.

### Parameter-Liste

`zip_entry`

  Ein von zip_read() zurückgegebener Verzeichniseintrag.

### Rückgabewerte

Die komprimierte Größe. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt; siehe ZipArchive::statIndex().

### Siehe auch

- zip_open() - Öffnet ein ZIP-Archiv
- zip_read() - Liest den nächsten Eintrag innerhalb des ZIP-Archivs

# zip_entry_compressionmethod

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_compressionmethod — Ermittelt die Komprimierungsmethode eines Verzeichniseintrags

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_entry_compressionmethod(resource `$zip_entry`): string|false

Gibt die Komprimierungsmethode des von `zip_entry` angegebenen Verzeichniseintrages zurück.

### Parameter-Liste

`zip_entry`

  Ein von zip_read() zurückgegebener Verzeichniseintrag.

### Rückgabewerte

Die Komprimierungsmethode. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt; siehe ZipArchive::statIndex().

### Siehe auch

- zip_open() - Öffnet ein ZIP-Archiv
- zip_read() - Liest den nächsten Eintrag innerhalb des ZIP-Archivs

# zip_entry_filesize

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_filesize — Ermittelt die effektive Größe eines Verzeichniseintrages

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_entry_filesize(resource `$zip_entry`): int|false

Gibt die effektive Größe des angegebenen Verzeichniseintrags zurück.

### Parameter-Liste

`zip_entry`

  Ein von zip_read() zurückgegebener Verzeichniseintrag.

### Rückgabewerte

Die Größe des Verzeichniseintrags. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt; siehe ZipArchive::statIndex().

### Siehe auch

- zip_open() - Öffnet ein ZIP-Archiv
- zip_read() - Liest den nächsten Eintrag innerhalb des ZIP-Archivs

# zip_entry_name

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_name — Gibt den Namen eines Verzeichniseintrages zurück

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_entry_name(resource `$zip_entry`): string|false

Gibt den Names eines angegebenen Verzeichniseintrags zurück.

### Parameter-Liste

`zip_entry`

  Ein von zip_read() zurückgegebener Verzeichniseintrag.

### Rückgabewerte

Der Name des Verzeichniseintrags. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt; siehe ZipArchive::statIndex().

### Siehe auch

- zip_open() - Öffnet ein ZIP-Archiv
- zip_read() - Liest den nächsten Eintrag innerhalb des ZIP-Archivs

# zip_entry_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_open — Öffnet einen Verzeichniseintrag für den Lesezugriff

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_entry_open(resource `$zip_dp`, resource `$zip_entry`, string `$mode` = "rb"): bool

Öffnet einen Verzeichniseintrag für den Lesezugriff.

### Parameter-Liste

`zip_dp`

  Ein valides Ressource-Handle, das von der zip_open() zurückgegeben wurde.

`zip_entry`

  Ein Verzeichniseintrag, der von zip_read() zurückgegeben wurde.

`mode`

  Einer der in der Dokumentation zu fopen() angegebenen Modi.

  > Hinweis:

  > Derzeit wird `mode` ignoriert und statt dessen standardmäßig `"rb"` verwendet. Dies ist dadurch bedingt, dass der ZIP-Support in PHP nur den Nur-Lesen-Modus unterstützt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

> Hinweis:

> Im Gegensatz zu fopen() und vergleichbaren Funktionen zeigt der Rückgabewert von zip_entry_open() nur das Gelingen an und wird nicht für weitere Operationen benötigt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt.

### Siehe auch

- zip_entry_close() - Schließt einen Verzeichniseintrag
- zip_entry_read() - Liest einen geöffneten Verzeichniseintrag aus

# zip_entry_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_entry_read — Liest einen geöffneten Verzeichniseintrag aus

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_entry_read(resource `$zip_entry`, int `$len` = 1024): string|false

Liest aus einem geöffneten Verzeichniseintrag.

### Parameter-Liste

`zip_entry`

  Ein von zip_read() zurückgegebener Verzeichniseintrag.

`len`

  Die Anzahl der zurückzugebenden Bytes.

  > Hinweis:

  > Dies sollte die Länge der der unkomprimierten Daten sein, die Sie auslesen möchten.

### Rückgabewerte

Gibt die gelesenen Daten zurück oder einen leeren String, wenn das Ende der Datei erreicht ist oder `false`, bei einem Fehler.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt; siehe ZipArchive::open().

### Siehe auch

- zip_entry_open() - Öffnet einen Verzeichniseintrag für den Lesezugriff
- zip_entry_close() - Schließt einen Verzeichniseintrag
- zip_entry_filesize() - Ermittelt die effektive Größe eines Verzeichniseintrages

# zip_open

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_open — Öffnet ein ZIP-Archiv

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_open(string `$filename`): resource|int|false

Öffnet ein ZIP-Archiv für den Lesezugriff.

### Parameter-Liste

`filename`

  Der Name der zu öffnenden ZIP-Datei.

### Rückgabewerte

Gibt einen Dateizeiger für die spätere Verwendung mit zip_read() und zip_close() zurück. Ist `filename` nicht vorhanden oder tritt ein anderer Fehler auf, wird entweder `false` oder die Fehlernummer zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt; siehe ZipArchive::open().

### Siehe auch

- zip_read() - Liest den nächsten Eintrag innerhalb des ZIP-Archivs
- zip_close() - Schließt ein ZIP-Archiv

# zip_read

(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.0.0)

zip_read — Liest den nächsten Eintrag innerhalb des ZIP-Archivs

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function zip_read(resource `$zip`): resource|false

Liest den nächsten Eintrag innerhalb des ZIP-Archivs.

### Parameter-Liste

`zip`

  Eine ZIP-Datei, die zuvor mittels zip_open() geöffnet wurde.

### Rückgabewerte

Gibt im Erfolgsfall einen Verzeichniseintrag zur späteren Benutzung mit den `zip_entry_...`-Funktionen zurück. Wenn keine weiteren Einträge vorhanden sind, wird `false` zurückgegeben. Tritt ein Fehler auf, ist der Rückgabewert die entsprechende Fehlernummer.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist zugunsten der Objekt-API missbilligt; siehe ZipArchive::statIndex().

### Siehe auch

- zip_open() - Öffnet ein ZIP-Archiv
- zip_close() - Schließt ein ZIP-Archiv
- zip_entry_open() - Öffnet einen Verzeichniseintrag für den Lesezugriff
- zip_entry_read() - Liest einen geöffneten Verzeichniseintrag aus

## Inhaltsverzeichnis

- zip_close — Schließt ein ZIP-Archiv
- zip_entry_close — Schließt einen Verzeichniseintrag
- zip_entry_compressedsize — Ermittelt die komprimierte Größe eines Verzeichniseintrages
- zip_entry_compressionmethod — Ermittelt die Komprimierungsmethode eines Verzeichniseintrags
- zip_entry_filesize — Ermittelt die effektive Größe eines Verzeichniseintrages
- zip_entry_name — Gibt den Namen eines Verzeichniseintrages zurück
- zip_entry_open — Öffnet einen Verzeichniseintrag für den Lesezugriff
- zip_entry_read — Liest einen geöffneten Verzeichniseintrag aus
- zip_open — Öffnet ein ZIP-Archiv
- zip_read — Liest den nächsten Eintrag innerhalb des ZIP-Archivs

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- Beispiele
- ZipArchive — Die Klasse ZipArchive
  - ZipArchive::addEmptyDir — Fügt ein neues Verzeichnis hinzu
  - ZipArchive::addFile — Fügt eine Datei von einem gegebenen Pfad zu einem ZIP-Archiv hinzu
  - ZipArchive::addFromString — Fügt eine Datei unter Verwendung ihres Inhalts zu einem ZIP-Archiv hinzu
  - ZipArchive::addGlob — Add files from a directory by glob pattern
  - ZipArchive::addPattern — Add files from a directory by PCRE pattern
  - ZipArchive::clearError — Clear the status error message, system and/or zip messages
  - ZipArchive::close — Schließt das aktive Archiv (geöffnet oder neu erstellt)
  - ZipArchive::count — Counts the number of files in the archive
  - ZipArchive::deleteIndex — Löscht einen Archiveintrag unter Verwendung seines Index
  - ZipArchive::deleteName — Löscht einen Archiveintrag unter Verwendung seines Namens
  - ZipArchive::extractTo — Extrahiert den Archivinhalt
  - ZipArchive::getArchiveComment — Gibt den ZIP-Archiv-Kommentar zurück
  - ZipArchive::getArchiveFlag — Returns the value of a Zip archive global flag
  - ZipArchive::getCommentIndex — Gibt den Kommentar zu einem Eintrag unter Verwendung des Eintragsindex zurück
  - ZipArchive::getCommentName — Gibt den Kommentar zu einem Eintrag unter Verwendung des Eintragsnamens zurück
  - ZipArchive::getExternalAttributesIndex — Retrieve the external attributes of an entry defined by its index
  - ZipArchive::getExternalAttributesName — Retrieve the external attributes of an entry defined by its name
  - ZipArchive::getFromIndex — Gibt den Inhalt eines Eintrags unter Verwendung seines Index zurück
  - ZipArchive::getFromName — Gibt den Inhalt eines Eintrags unter Verwendung seines Namens zurück
  - ZipArchive::getNameIndex — Gibt den Namen eines Eintrags unter Verwendung seines Index zurück
  - ZipArchive::getStatusString — Gibt die Statusfehlermeldung sowie System- oder ZIP-Meldungen zurück
  - ZipArchive::getStream — Erzeugt einen Dateizeiger zu dem per Name bestimmten Eintrag (nur lesend)
  - ZipArchive::getStreamIndex — Get a file handler to the entry defined by its index (read only)
  - ZipArchive::getStreamName — Get a file handler to the entry defined by its name (read only)
  - ZipArchive::isCompressionMethodSupported — Check if a compression method is supported by libzip
  - ZipArchive::isEncryptionMethodSupported — Check if a encryption method is supported by libzip
  - ZipArchive::locateName — Gibt den Index eines Archiveintrags zurück
  - ZipArchive::open — Öffnet ein ZIP-Dateiarchiv
  - ZipArchive::registerCancelCallback — Register a callback to allow cancellation during archive close.
  - ZipArchive::registerProgressCallback — Register a callback to provide updates during archive close.
  - ZipArchive::renameIndex — Benennt einen durch seinen Index bestimmten Eintrag um
  - ZipArchive::renameName — Benennt einen durch seinen Namen bestimmten Eintrag um
  - ZipArchive::replaceFile — Replace file in ZIP archive with a given path
  - ZipArchive::setArchiveComment — Setzt einen Kommentar zu einem ZIP-Archiv
  - ZipArchive::setArchiveFlag — Set a global flag of a ZIP archive
  - ZipArchive::setCommentIndex — Setzt einen Eintragskommentar, der via Eintragsindex bestimmt wird
  - ZipArchive::setCommentName — Setzt einen Eintragskommentar, der via Eintragsnamen bestimmt wird
  - ZipArchive::setCompressionIndex — Set the compression method of an entry defined by its index
  - ZipArchive::setCompressionName — Set the compression method of an entry defined by its name
  - ZipArchive::setEncryptionIndex — Set the encryption method of an entry defined by its index
  - ZipArchive::setEncryptionName — Set the encryption method of an entry defined by its name
  - ZipArchive::setExternalAttributesIndex — Set the external attributes of an entry defined by its index
  - ZipArchive::setExternalAttributesName — Set the external attributes of an entry defined by its name
  - ZipArchive::setMtimeIndex — Set the modification time of an entry defined by its index
  - ZipArchive::setMtimeName — Set the modification time of an entry defined by its name
  - ZipArchive::setPassword — Set the password for the active archive
  - ZipArchive::statIndex — Gibt die Details eines via Index bestimmten Eintrags zurück
  - ZipArchive::statName — Gibt die Details eines via Namen bestimmten Eintrags zurück
  - ZipArchive::unchangeAll — Setzt alle im Archiv durchgeführten Änderungen zurück
  - ZipArchive::unchangeArchive — Nimmt alle globalen Änderungen zurück, die im Archiv durchgeführt wurden
  - ZipArchive::unchangeIndex — Nimmt alle Änderungen zurück, die auf dem Eintrag mit dem gegebenen Index gemacht wurden
  - ZipArchive::unchangeName — Nimmt alle Änderungen zurück, die auf dem Eintrag mit dem gegebenen Namen gemacht wurden
- Zip Funktionen
  - zip_close — Schließt ein ZIP-Archiv
  - zip_entry_close — Schließt einen Verzeichniseintrag
  - zip_entry_compressedsize — Ermittelt die komprimierte Größe eines Verzeichniseintrages
  - zip_entry_compressionmethod — Ermittelt die Komprimierungsmethode eines Verzeichniseintrags
  - zip_entry_filesize — Ermittelt die effektive Größe eines Verzeichniseintrages
  - zip_entry_name — Gibt den Namen eines Verzeichniseintrages zurück
  - zip_entry_open — Öffnet einen Verzeichniseintrag für den Lesezugriff
  - zip_entry_read — Liest einen geöffneten Verzeichniseintrag aus
  - zip_open — Öffnet ein ZIP-Archiv
  - zip_read — Liest den nächsten Eintrag innerhalb des ZIP-Archivs

# Zlib-Komprimierung

# Einführung

Dieses Modul gibt Ihnen die Möglichkeit, transparent gzip-komprimierte Dateien (*.gz) zu lesen und zu schreiben. Hierfür bietet die Erweiterung die Versionen der meisten Dateisystem-Funktionen, die mit gzip-komprimierten (und unkomprimierten) Dateien, jedoch nicht mit Sockets funktionieren.

> Hinweis:

> PHP kommt mit einem fopen-wrapper für .gz-Dateien. Mehr Information hierzu finden Sie im Abschnitt über zlib://.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

Diese Erweiterung nutzt die Funktionen der » zlib-Bibliothek von Jean-loup Gailly und Mark Adler. Seit PHP 8.4.0 wird mindestens zlib Version 1.2.11 benötigt. Vor PHP 8.4.0 war mindestens zlib Version 1.2.0.4 erforderlich.

## Installation

Die Unterstützung für zlib ist in PHP nicht standardmäßig aktiviert. Es ist erforderlich, die Option --with-zlib[=DIR] beim Kompilieren von PHP anzugeben.

Die Windowsversion von PHP enthält diese Erweiterung. Um diese Funktionen zu verwenden, müssen Sie keine zusätzlichen Erweiterungen aktivieren.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Die zlib-Erweiterung gibt Ihnen die Möglichkeit, Ihre Seiten on-the-fly transparent zu komprimieren, wenn der Browser dies unterstützt. Dafür gibt es drei Optionen in der Konfigurationsdatei php.ini.

Zlib-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
zlib.output_compression | "0" | `INI_ALL` |
zlib.output_compression_level | "-1" | `INI_ALL` |
zlib.output_handler | "" | `INI_ALL` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`zlib.output_compression` bool/int

  Wenn diese Option in der php.ini oder der Apachekonfiguration auf "On" gesetzt ist, werden die Seiten komprimiert, wenn der Browser einen "Accept-Encoding: gzip"- oder einen "deflate"-Header sendet. Zu den normalerweise vom Server gesendeten Headern werden nun "Content-Encoding: gzip" (respektive "deflate") und "Vary: Accept-Encoding" hinzugefügt. Zur Laufzeit kann die Option nur gesetzt werden, bevor irgendeine Ausgabe gesendet wurde.

  Diese Option akzeptiert auch Integerwerte anstelle des boolschen On/Off. Wenn Sie diese verwenden, können Sie die Ausgabepuffergröße festlegen (der Standardwert ist 4KB).

  > Hinweis:

  > output_handler muss leer sein, wenn diese Option den Wert "On" hat! Verwenden Sie statt dessen `zlib.output_handler`.

`zlib.output_compression_level` int

  Der Kompressionsgrad für die transparente Ausgabekomprimierung. Geben Sie einen Wert zwischen 0 (keine Kompression) und 9 (stärkste Kompressionsrate) an. Der Vorgabewert -1 lässt den Server darüber entscheiden, welcher Kompressionsgrad zu verwenden ist.

`zlib.output_handler` string

  Sie können keine zusätzlichen Outputhandler angeben, wenn Sie zlib.output_compression aktiviert haben. Diese Einstellung tut das Gleiche wie output_handler, allerdings in einer anderen Reihenfolge.

## Ressource-Typen

Diese Erweiterung definiert eine Dateizeiger-Ressource, die von gzopen() zurückgegeben wird. Vor PHP 8.0.0 wurden auch die Ressourcen `zlib.deflate` und `zlib.inflate` definiert.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`FORCE_GZIP` (int)
`FORCE_DEFLATE` (int)
`ZLIB_ENCODING_RAW` (int)
  DEFLATE-Algorithmus gemäß RFC 1951.
`ZLIB_ENCODING_DEFLATE` (int)
  ZLIB-Komprimierungsalgorithmus gemäß RFC 1950.
`ZLIB_ENCODING_GZIP` (int)
  GZIP-Algorithmus gemäß RFC 1952.
`ZLIB_FILTERED` (int)
`ZLIB_HUFFMAN_ONLY` (int)
`ZLIB_FIXED` (int)
`ZLIB_RLE` (int)
`ZLIB_DEFAULT_STRATEGY` (int)
`ZLIB_BLOCK` (int)
`ZLIB_NO_FLUSH` (int)
`ZLIB_PARTIAL_FLUSH` (int)
`ZLIB_SYNC_FLUSH` (int)
`ZLIB_FULL_FLUSH` (int)
`ZLIB_FINISH` (int)
`ZLIB_VERSION` (string)
  Die `zlib`-Versionsnummer als string.
`ZLIB_VERNUM` (int)
  Die `zlib`-Versionsnummer als int.
`ZLIB_OK` (int)
  Keine Fehler und keine weiteren Statusinformationen.
`ZLIB_STREAM_END` (int)
  Der Stream wurde erfolgreich beendet.
`ZLIB_NEED_DICT` (int)
  Es wird ein vordefiniertes Dictionary benötigt.
`ZLIB_ERRNO` (int)
  Fehler bei der Verarbeitung der Datei.
`ZLIB_STREAM_ERROR` (int)
  Der Status des Streams ist inkonsistent oder ein Parameter ist ungültig.
`ZLIB_DATA_ERROR` (int)
  Die Eingabedaten sind beschädigt.
`ZLIB_MEM_ERROR` (int)
  Zu wenig Speicher.
`ZLIB_BUF_ERROR` (int)
  Es ist kein Fortschritt möglich, weil der Pufferspeicher nicht ausreicht oder ein Eingabestream unerwartet endet.
`ZLIB_VERSION_ERROR` (int)
  Die Version der `zlib`-Bibliothek ist nicht kompatibel mit der vom Aufrufer angenommenen Version.

# Beispiele

Dieses Beispiel öffnet eine temporäre Datei und schreibt einen Teststring in die Datei, dann wird der Inhalt dieser Datei zweimal ausgegeben.

Beispiel #1 Ein kleines Beispiel zu Zlib

    <?php

    $filename = tempnam('/tmp', 'zlibtest') . '.gz';
    echo "<html>\n<head></head>\n<body>\n<pre>\n";
    $s = "Nur ein test, test, test, test, test, test, test, test!\n";

    // Temporäre Datei zum Schreiben mit der maximalen Kompressionsstufe öffnen
    $zp = gzopen($filename, "w9");

    // String in die Datei schreiben
    gzwrite($zp, $s);

    // Datei schließen
    gzclose($zp);

    // Datei zum Lesen öffnen
    $zp = gzopen($filename, "r");

    // 3 Zeichen einlesen und ausgeben
    echo gzread($zp, 3);

    // Inhalt der Datei ausgeben und die Datei schließen
    gzpassthru($zp);
    gzclose($zp);

    echo "\n";

    // Öffne die Datei und gib den Inhalt zum zweiten Mal aus
    if (readgzfile($filename) != strlen($s)) {
            echo "Error with zlib functions!";
    }
    unlink($filename);
    echo "</pre>\n</body>\n</html>\n";

    ?>

Beispiel #2 Arbeiten mit den inkrementellen Kompriemierungs- und Dekomprimierungs-API

    <?php
    // führe GZIP-Komprimierung durch:
    $deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
    $compressed = deflate_add($deflateContext, "Zu komprimierende Daten", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", weitere Daten", ZLIB_NO_FLUSH);
    $compressed .= deflate_add($deflateContext, ", und noch mehr Daten!", ZLIB_FINISH);

    // führe GZIP-Dekomprimierung durch:
    $inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
    $uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
    $uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
    echo $uncompressed;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Zu komprimierende Daten, weitere Daten, und noch mehr Daten!

# Zlib-Funktionen

# deflate_add

(PHP 7, PHP 8)

deflate_add — Incrementally deflate data

### Beschreibung

function deflate_add(DeflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Incrementally deflates data in the specified context.

### Parameter-Liste

`context`

  A context created with deflate_init().

`data`

  A chunk of data to compress.

`flush_mode`

  One of `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (default), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Normally you will want to set `ZLIB_NO_FLUSH` to maximize compression, and `ZLIB_FINISH` to terminate with the last chunk of data. See the » zlib manual for a detailed description of these constants.

### Rückgabewerte

Returns a chunk of compressed data, Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

If invalid arguments are given, an error of level `E_WARNING` is generated.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `context` expects a DeflateContext instance now; previously, a resource was expected.

### Siehe auch

- deflate_init() - Initialize an incremental deflate context

# deflate_init

(PHP 7, PHP 8)

deflate_init — Initialize an incremental deflate context

### Beschreibung

function deflate_init(int `$encoding`, array|object `$options` = []): DeflateContext|false

Initializes an incremental deflate context using the specified `encoding`.

Note that the `window` option here only sets the window size of the algorithm, differently from the zlib filters where the same parameter also sets the encoding to use; the encoding must be set with the `encoding` parameter.

Limitation: there is currently no way to set the header information on a GZIP compressed stream, which are set as follows: GZIP signature (`\x1f\x8B`); compression method (`\x08` == DEFLATE); 6 zero bytes; the operating system set to the current system (`\x00` = Windows, `\x03` = Unix, etc.)

### Parameter-Liste

`encoding`

  One of the `ZLIB_ENCODING_*` constants.

`options`

  An associative array which may contain the following elements:

  level

    The compression level in range -1..9; defaults to -1.

  memory

    The compression memory level in range 1..9; defaults to 8.

  window

    The zlib window size (logarithmic) in range `8`..`15`; defaults to `15`. zlib changes a window size of `8` to `9`, and as of zlib 1.2.8 fails with a warning, if a window size of `8` is requested for `ZLIB_ENCODING_RAW` or `ZLIB_ENCODING_GZIP`.

  strategy

    One of `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` or `ZLIB_DEFAULT_STRATEGY` (the default).

  dictionary

    A string or an array of strings of the preset dictionary (default: no preset dictionary).

### Rückgabewerte

Returns a deflate context resource (`zlib.deflate`) on success, Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

If an invalid option is passed to `options` or the context couldn't be created, an error of level `E_WARNING` is generated.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a DeflateContext instance now; previously, a resource was returned.

### Siehe auch

- deflate_add() - Incrementally deflate data
- inflate_init() - Initialize an incremental inflate context

# gzclose

(PHP 4, PHP 5, PHP 7, PHP 8)

gzclose — Schließt einen geöffnete gz-Dateizeiger

### Beschreibung

function gzclose(resource `$stream`): bool

Schließt den angegeben gz-Dateizeiger.

### Parameter-Liste

`stream`

  Der gz-Dateizeiger. Dieser muss auf eine gültige, erfolgreich mit gzopen() geöffnete Datei zeigen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 gzclose()-Beispiel

    <?php
    $gz = gzopen('somefile.gz','w9');
    gzputs ($gz, 'Ich wurde zu somefile.gz hinzugefügt');
    gzclose($gz);
    ?>

### Siehe auch

- gzopen() - Öffnet eine gz-Datei

# gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompress — Komprimiert einen String

### Beschreibung

function gzcompress(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_DEFLATE`): string|false

Diese Funktion komprimiert den gegebenen String mittels des `ZLIB`-Datenformats.

Details zum ZLIB-Kompressionsalgorithmus finden Sie im Dokument "» ZLIB Compressed Data Format Specification version 3.3" (RFC 1950).

> Hinweis:

> Dies entspricht nicht der gzip-Kompression, welche zusätzliche Kopfdaten enthält. Für gzip-Kompression nutzen Sie bitte gzencode().

### Parameter-Liste

`data`

  Die zu komprimierenden Daten.

`level`

  Der Kompressionsgrad. Dieser reicht von 0 für keine Kompression bis 9 für maximale Kompression.

  Wird -1 angegeben, wird die Standardkompression der zlib-Bibliothek verwendet, die 6 ist.

`encoding`

  Eine der `ZLIB_ENCODING_*`-Konstanten.

### Rückgabewerte

Der komprimierte String oder `false`, falls ein Fehler aufgetreten ist.

### Beispiele

Beispiel #1 gzcompress()-Beispiel

    <?php
    $compressed = gzcompress('Komprimiere mich', 9);
    echo $compressed;
    ?>

### Siehe auch

- gzdeflate() - Komprimiert eine Zeichenkette
- gzinflate() - Dekomprimiert eine komprimierte Zeichenkette
- gzuncompress() - Dekomprimiert einen komprimierten String
- gzencode() - Create a gzip compressed string

# gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecode — Dekodiert eine gzip-komprimierte Zeichenkette

### Beschreibung

function gzdecode(string `$data`, int `$max_length` = 0): string|false

Diese Funktion gibt die dekodierte Version von `data` zurück.

### Parameter-Liste

`data`

  Die zu dekodierenden Daten, die mittels gzencode() kodiert wurden.

`max_length`

  Die maximale Länge der zu dekodierenden Daten.

### Rückgabewerte

Die dekodierte Zeichenkette, oder `false`, wenn ein Fehler auftrat.

### Fehler/Exceptions

Im Falle eines Fehlers wird ein Fehler der Stufe `E_WARNING` ausgegeben.

### Siehe auch

- gzencode() - Create a gzip compressed string

# gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflate — Komprimiert eine Zeichenkette

### Beschreibung

function gzdeflate(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_RAW`): string|false

Diese Funktion komprimiert die übergebene Zeichenkette mit dem `DEFLATE`-Datenformat.

Zu Einzelheiten bezüglich des DEFLATE-Kompressions-Algorithmus siehe das Dokument "» DEFLATE Compressed Data Format Specification version 1.3" (RFC 1951).

### Parameter-Liste

`data`

  Die zu komprimierenden (deflate == entleeren) Daten.

`level`

  Der Komprimierungsfaktor. Kann von 0 für keine Kompression bis 9 für maximale Kompression übergeben werden. Wird er nicht übergeben, ist der Standard-Komprimierungsfaktor der Standard-Komprimierungsfaktor der zlib-Bibliothek.

`encoding`

  Eine der `ZLIB_ENCODING_*`-Konstanten.

### Rückgabewerte

Die komprimierte (entleerte) Zeichenkette, oder `false`, wenn ein Fehler auftrat.

### Beispiele

Beispiel #1 gzdeflate()-Beispiel

    <?php
    $compressed = gzdeflate('Compress me', 9);
    echo $compressed;
    ?>

### Siehe auch

- gzinflate() - Dekomprimiert eine komprimierte Zeichenkette
- gzcompress() - Komprimiert einen String
- gzuncompress() - Dekomprimiert einen komprimierten String
- gzencode() - Create a gzip compressed string

# gzencode

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzencode — Create a gzip compressed string

### Beschreibung

function gzencode(string `$data`, int `$level` = -1, int `$encoding` = `ZLIB_ENCODING_GZIP`): string|false

This function returns a compressed version of the input `data` compatible with the output of the gzip program.

For more information on the GZIP file format, see the document: » GZIP file format specification version 4.3 (RFC 1952).

### Parameter-Liste

`data`

  The data to encode.

`level`

  The level of compression. Can be given as 0 for no compression up to 9 for maximum compression. If not given, the default compression level will be the default compression level of the zlib library.

`encoding`

  The encoding mode. Can be `FORCE_GZIP` (the default) or `FORCE_DEFLATE`.

  `FORCE_DEFLATE` generates RFC 1950 compliant output, consisting of a zlib header, the deflated data, and an Adler checksum.

### Rückgabewerte

The encoded string, or `false` if an error occurred.

### Beispiele

The resulting data contains the appropriate headers and data structure to make a standard .gz file, e.g.:

Beispiel #1 Creating a gzip file

    <?php
    $data = file_get_contents("bigfile.txt");
    $gzdata = gzencode($data, 9);
    file_put_contents("bigfile.txt.gz", $gzdata);
    ?>

### Siehe auch

- gzdecode() - Dekodiert eine gzip-komprimierte Zeichenkette
- gzdeflate() - Komprimiert eine Zeichenkette
- gzinflate() - Dekomprimiert eine komprimierte Zeichenkette
- gzuncompress() - Dekomprimiert einen komprimierten String
- gzcompress() - Komprimiert einen String
- » ZLIB Compressed Data Format Specification (RFC 1950)

# gzeof

(PHP 4, PHP 5, PHP 7, PHP 8)

gzeof — Prüft bei einem gz-Dateizeiger auf EOF

### Beschreibung

function gzeof(resource `$stream`): bool

Prüft den übergebenen gz-Dateizeiger auf EOF.

### Parameter-Liste

`stream`

  Der gz-Dateizeiger. Er muss gültig sein und muss auf eine Datei zeigen, die erfolgreich mit gzopen() geöffnet wurde.

### Rückgabewerte

Gibt `true` zurück wenn der gz-Dateizeiger bei EOF (Dateiende) ist oder ein Fehler auftritt; gibt ansonsten `false` zurück.

### Beispiele

Beispiel #1 gzeof()-Beispiel

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

# gzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

gzfile — Liest eine ganze gz-Datei in ein Array

### Beschreibung

function gzfile(string `$filename`, int `$use_include_path` = 0): array|false

Diese Funktion entspricht weitgehend readgzfile(), gibt die Datei aber in einem Array zurück.

### Parameter-Liste

`filename`

  Der Dateiname.

`use_include_path`

  Sie können diesen optionalen Parameter auf `1` setzen, wenn Sie die Datei auch im include_path suchen lassen wollen.

### Rückgabewerte

Ein Array, das die Zeilen der Datei als Elemente enthält. Leere Zeilen sind enthalten, und Zeilenumbrüche sind noch angefügt. Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 gzfile()-Beispiel

    <?php
    $lines = gzfile('somefile.gz');
    foreach ($lines as $line) {
        echo $line;
    }
    ?>

### Siehe auch

- readgzfile() - Gibt eine gz-komprimierte Datei aus
- gzopen() - Öffnet eine gz-Datei

# gzgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetc — Holt Zeichen vom gz-Dateizeiger

### Beschreibung

function gzgetc(resource `$stream`): string|false

Gibt eine Zeichenkette zurück, die ein einzelnes von dem übergebenen gz-Dateizeiger gelesenes (unkomprimiertes) Zeichen enthält.

### Parameter-Liste

`stream`

  Der gz-Dateizeiger. Er muss gültig sein und auf eine mit gzopen() erfolgreiche geöffnete Datei zeigen.

### Rückgabewerte

Das unkomprimierte Zeichen oder `false` bei EOF (ungleich gzeof()).

### Beispiele

Beispiel #1 gzgetc()-Beispiel

    <?php
    $gz = gzopen('somefile.gz', 'r');
    while (!gzeof($gz)) {
      echo gzgetc($gz);
    }
    gzclose($gz);
    ?>

### Siehe auch

- gzopen() - Öffnet eine gz-Datei
- gzgets() - Get line from file pointer

# gzgets

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgets — Get line from file pointer

### Beschreibung

function gzgets(resource `$stream`, ?int `$length` = `null`): string|false

Gets a (uncompressed) string of up to length - 1 bytes read from the given file pointer. Reading ends when length - 1 bytes have been read, on a newline, or on EOF (whichever comes first).

### Parameter-Liste

`stream`

  The gz-file pointer. It must be valid, and must point to a file successfully opened by gzopen().

`length`

  The length of data to get.

### Rückgabewerte

The uncompressed string, or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `length` is nullable now; previously, the default was `1024`.

### Beispiele

Beispiel #1 gzgets() example

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgets($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Siehe auch

- gzopen() - Öffnet eine gz-Datei
- gzgetc() - Holt Zeichen vom gz-Dateizeiger
- gzwrite() - Ausgabe in gz-komprimierte Dateien

# gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetss — Holt eine Zeile vom gz-Dateizeiger und entfernt die HTML-Tags

Warnung

Diese Funktion ist seit PHP 7.3.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function gzgetss(resource `$zp`, int `$length`, string `$allowable_tags` = ?): string

Identisch zu gzgets(), außer dass gzgetss() versucht, HTML- und PHP-Tags aus dem gelesenen Text zu entfernen.

### Parameter-Liste

`zp`

  Der gz-Dateizeiger. Er muss gültig sein und auf eine mit gzopen() erfolgreiche geöffnete Datei zeigen.

`length`

  Die Länge der zu erhaltenden Daten.

`allowable_tags`

  Dieser optionale Parameter kann genutzt werden, um Tags anzugeben, die nicht entfernt werden sollen.

### Rückgabewerte

Die unkomprimierte und bereinigte Zeichenkette oder `false` bei Fehlern.

### Beispiele

Beispiel #1 gzgetss()-Beispiel

    <?php
    $handle = gzopen('somefile.gz', 'r');
    while (!gzeof($handle)) {
       $buffer = gzgetss($handle, 4096);
       echo $buffer;
    }
    gzclose($handle);
    ?>

### Siehe auch

- gzopen() - Öffnet eine gz-Datei
- gzgets() - Get line from file pointer
- strip_tags() - Entfernt HTML- und PHP-Tags aus einem String

# gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflate — Dekomprimiert eine komprimierte Zeichenkette

### Beschreibung

function gzinflate(string `$data`, int `$max_length` = 0): string|false

Diese Funktion dekomprimiert eine Zeichenkette, die mit dem DEFLATE-Kompressions-Algorithmus komprimiert wurde.

### Parameter-Liste

`data`

  Die Daten, die mitgzdeflate() komprimiert wurden.

`max_length`

  Die maximale Länge der dekodierten Daten.

### Rückgabewerte

Die originalen unkomprimierten Daten oder `false` bei Fehlern.

Diese Funktion gibt einen Fehler zurück, wenn die dekomprimierten Daten mehr als 32768-mal länger sind als die komprimierte Eingabezeichenkette `data` oder, sofern `max_length` nicht `0` ist, größer als der optionale Parameter `max_length`.

### Beispiele

Beispiel #1 gzinflate()-Beispiel

    <?php
    $compressed   = gzdeflate('Compress me', 9);
    $uncompressed = gzinflate($compressed);
    echo $uncompressed;
    ?>

### Siehe auch

- gzdeflate() - Komprimiert eine Zeichenkette
- gzcompress() - Komprimiert einen String
- gzuncompress() - Dekomprimiert einen komprimierten String
- gzencode() - Create a gzip compressed string

# gzopen

(PHP 4, PHP 5, PHP 7, PHP 8)

gzopen — Öffnet eine gz-Datei

### Beschreibung

function gzopen(string `$filename`, string `$mode`, int `$use_include_path` = 0): resource|false

Öffnet eine gzip- (.gz) Datei zum Lesen oder Schreiben.

gzopen() kann auch Dateien lesen, die nicht im gzip-Format vorliegen. In diesem Fall liest gzread() direkt aus der Datei ohne zu entpacken.

### Parameter-Liste

`filename`

  Der Dateiname.

`mode`

  Wie in fopen() (`rb` oder `wb`), allerdings kann auch der Kompressionsgrad (`wb9`) oder die Strategie angegeben werden: `f` für gefilterte Daten (`wb6f`) oder `h` für Huffman-Kompression (`wb1h`). (Weitere Informationen über den Strategieparameter finden Sie in der Beschreibung zu `deflateInit2` in zlib.h.)

`use_include_path`

  Sie können diesen optionalen Parameter auf `1` setzen, um die Datei auch im include_path suchen zu lassen.

### Rückgabewerte

Gibt einen Dateizeiger auf die geöffnete Datei zurück. Alles, was Sie von nun an hieraus lesen, wird transparent entpackt und alles, was Sie schreiben, wird komprimiert.

Schlägt das Öffnen fehl, so gibt die Funktion `false` zurück.

### Beispiele

Beispiel #1 gzopen()-Beispiel

    <?php
    $fp = gzopen("/tmp/file.gz", "r");
    ?>

### Siehe auch

- gzclose() - Schließt einen geöffnete gz-Dateizeiger

# gzpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

gzpassthru — Gibt alle verbleibenden Daten eines gz-Dateizeigers aus

### Beschreibung

function gzpassthru(resource `$stream`): int

Liest bis EOF von der aktuellen Position auf dem übergebenen gz-Dateizeiger und schreibt die (unkomprimierten) Ergebnisse auf die Standardausgabe.

> Hinweis:

> Eventuell müssen sie gzrewind() aufrufen, um den Dateizeiger auf den Anfang der Datei zurückzusetzen, falls sie schon Daten dorthin geschrieben haben.

Tipp

Wenn sie einfach den Inhalt einer Datei in den Ausgabepuffer ausgeben wollen, ohne sie zuerst zu verändern oder zu einem bestimmten Offset zu springen (seek), können sie readgzfile() nutzen, was den gzopen()-Aufruf spart.

### Parameter-Liste

`stream`

  Der gz-Dateizeiger. Er muss gültig sein und auf eine mit gzopen() erfolgreiche geöffnete Datei zeigen.

### Rückgabewerte

Die Anzahl umkomprimierter Zeichen, gelesen von `gz` und durchgereicht zu der Eingabe.

### Beispiele

Beispiel #1 gzpassthru()-Beispiel

    <?php
    $fp = gzopen('file.gz', 'r');
    gzpassthru($fp);
    gzclose($fp);
    ?>

# gzputs

(PHP 4, PHP 5, PHP 7, PHP 8)

gzputs — Alias von gzwrite()

### Beschreibung

Diese Funktion ist ein Alias für: gzwrite().

# gzread

(PHP 4, PHP 5, PHP 7, PHP 8)

gzread — Liest binary-safe aus einer gz-Datei

### Beschreibung

function gzread(resource `$stream`, int `$length`): string|false

gzread() liest bis zu `length` Bytes vom angegebenen gz-Dateizeiger. Das Lesen stoppt, wenn `length` (unkomprimierte) Bytes gelesen wurden oder EOF (Dateiende) erreicht wurde, je nachdem, was zuerst eintrifft.

### Parameter-Liste

`stream`

  Der gz-Dateizeiger. Dieser muss auf eine gültige, erfolgreich mit gzopen() geöffnete Datei zeigen.

`length`

  Die Anzahl der zu lesenden Bytes.

### Rückgabewerte

Die gelesenen Daten. Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Diese Funktion gibt jetzt bei einem Fehler `false` zurück; vorher wurde `0` zurückgegeben.

### Beispiele

Beispiel #1 gzread()-Beispiel

    <?php
    // Liest den Inhalt einer gz-Datei in einen String
    $filename = "/usr/local/something.txt.gz";
    $zd = gzopen($filename, "r");
    $contents = gzread($zd, 10000);
    gzclose($zd);
    ?>

### Siehe auch

- gzwrite() - Ausgabe in gz-komprimierte Dateien
- gzopen() - Öffnet eine gz-Datei
- gzgets() - Get line from file pointer
- gzgetss() - Holt eine Zeile vom gz-Dateizeiger und entfernt die HTML-Tags
- gzfile() - Liest eine ganze gz-Datei in ein Array
- gzpassthru() - Gibt alle verbleibenden Daten eines gz-Dateizeigers aus

# gzrewind

(PHP 4, PHP 5, PHP 7, PHP 8)

gzrewind — Setzt den gz-Dateizeiger auf den Anfang zurück

### Beschreibung

function gzrewind(resource `$stream`): bool

Setzt die Schreib-/Leseposition des gz-Dateizeigers auf den Anfang des Streams zurück.

### Parameter-Liste

`stream`

  Der gz-Dateizeiger. Dies muss auf eine gültige, erfolgreich mit gzopen() geöffnete Datei zeigen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- gzseek() - Positioniert den gz-Dateizeiger
- gztell() - Ermittelt die aktuelle Position eines gz-Dateizeigers

# gzseek

(PHP 4, PHP 5, PHP 7, PHP 8)

gzseek — Positioniert den gz-Dateizeiger

### Beschreibung

function gzseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Setzt die Schreib-/Leseposition für die angegebene Datei. Dies entspricht dem C-API Aufruf `gzseek(zp, offset, SEEK_SET)`.

Wenn die Datei für Lesezugriffe geöffnet ist, wird diese Funktion emuliert und kann sehr langsam sein. Wenn die Datei zum Schreiben geöffnet ist, kann nur vorwärts positioniert werden; die Funktion komprimiert dann eine Sequenz von Nullbytes, um die gewünschte Position zu erreichen.

### Parameter-Liste

`stream`

  Der gz-Dateizeiger. Dieser muss auf eine gültige, erfolgreich mit gzopen() geöffnete Datei zeigen.

`offset`

  Die gewünschte Position.

`whence`

  `whence` gibt an, auf welche Anfangsposition sich `offset` bezieht. Mögliche Werte sind:

  - `SEEK_SET` - Setzt die Position auf `offset` Bytes vom Dataianfang.
  - `SEEK_CUR` - Verschiebt die Position um `offset` Bytes ausgehend von der aktuellen Position.

  Wird `whence` nicht angegeben, so wird `SEEK_SET` angenommen.

### Rückgabewerte

Gibt 0 bei Erfolg und -1 bei Fehlern zurück. Beachten Sie, dass eine Suche über das Dateiende hinaus nicht als Fehler gilt.

### Beispiele

Beispiel #1 gzseek()-Beispiel

    <?php
    $gz = gzopen('somefile.gz', 'r');
    gzseek($gz,2);
    echo gzgetc($gz);
    gzclose($gz);
    ?>

### Siehe auch

- gztell() - Ermittelt die aktuelle Position eines gz-Dateizeigers
- gzrewind() - Setzt den gz-Dateizeiger auf den Anfang zurück

# gztell

(PHP 4, PHP 5, PHP 7, PHP 8)

gztell — Ermittelt die aktuelle Position eines gz-Dateizeigers

### Beschreibung

function gztell(resource `$stream`): int|false

Gibt die aktuelle Schreib-/Leseposition des angegebenen gz-Dateizeigers zurück. Diese entspricht dem Offset in die nicht komprimierten Dateidaten.

### Parameter-Liste

`stream`

  Der gz-Dateizeiger. Dieser muss auf eine gültige, erfolgreich mit gzopen() geöffnete Datei zeigen.

### Rückgabewerte

Die aktuelle Dateiposition oder `false` bei Fehlern.

### Siehe auch

- gzopen() - Öffnet eine gz-Datei
- gzseek() - Positioniert den gz-Dateizeiger
- gzrewind() - Setzt den gz-Dateizeiger auf den Anfang zurück

# gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompress — Dekomprimiert einen komprimierten String

### Beschreibung

function gzuncompress(string `$data`, int `$max_length` = 0): string|false

Diese Funktion dekomprimiert einen komprimierten String.

### Parameter-Liste

`data`

  Mit gzcompress() komprimierte Daten.

`max_length`

  Die maximale Länge der dekodierten Daten.

### Rückgabewerte

Die ursprünglichen nicht komprimierten Daten, oder `false` bei Fehlern.

Die Funktion gibt einen Fehler zurück, wenn die unkomprimierten Daten mehr als 32768 mal so lang sind wie die komprimierte Eingabe oder länger, als mit dem optionalen Parameter `max_length` angegeben.

### Beispiele

Beispiel #1 gzuncompress()-Beispiel

    <?php
    $compressed   = gzcompress('Compress me', 9);
    $uncompressed = gzuncompress($compressed);
    echo $uncompressed;
    ?>

### Siehe auch

- gzcompress() - Komprimiert einen String
- gzinflate() - Dekomprimiert eine komprimierte Zeichenkette
- gzdeflate() - Komprimiert eine Zeichenkette
- gzencode() - Create a gzip compressed string

# gzwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

gzwrite — Ausgabe in gz-komprimierte Dateien

### Beschreibung

function gzwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

gzwrite() schreibt den Inhalt von `data` in die angegebene gz-Datei aus.

### Parameter-Liste

`stream`

  Ein gz-Dateizeiger. Dieser muss gültig sein und auf eine Datei zeigen, die erfolgreich mit gzopen() geöffnet wurde.

`data`

  Der auszugebende String.

`length`

  Die Anzahl unkomprimierter Bytes, die ausgegeben werden sollen. Wenn angegeben, wird nach `length` aus `data` geschriebenen Bytes abgebrochen, wenn bis dahin das Ende des Strings nicht erreicht ist.

### Rückgabewerte

Gibt die Anzahl der (unkomprimierten) Bytes zurück, die auf den gegebenen gz-Stream ausgegeben wurden. Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `length` ist jetzt ein Nullable-Typ; vorher war der Standardwert `0`.
7.4.0 | Falls ein Fehler auftritt, gibt diese Funktion jetzt `false` zurück; vorher wurde `0` zurückgegeben.

### Beispiele

Beispiel #1 gzwrite()-Beispiel

    <?php
    $string = 'Zu komprimierende Daten';
    $gz = gzopen('somefile.gz','w9');
    gzwrite($gz, $string);
    gzclose($gz);
    ?>

### Siehe auch

- gzread() - Liest binary-safe aus einer gz-Datei
- gzopen() - Öffnet eine gz-Datei

# inflate_add

(PHP 7, PHP 8)

inflate_add — Incrementally inflate encoded data

### Beschreibung

function inflate_add(InflateContext `$context`, string `$data`, int `$flush_mode` = `ZLIB_SYNC_FLUSH`): string|false

Incrementally inflates encoded data in the specified `context`.

Limitation: header information from GZIP compressed data are not made available.

### Parameter-Liste

`context`

  A context created with inflate_init().

`data`

  A chunk of compressed data.

`flush_mode`

  One of `ZLIB_BLOCK`, `ZLIB_NO_FLUSH`, `ZLIB_PARTIAL_FLUSH`, `ZLIB_SYNC_FLUSH` (default), `ZLIB_FULL_FLUSH`, `ZLIB_FINISH`. Normally you will want to set `ZLIB_NO_FLUSH` to maximize compression, and `ZLIB_FINISH` to terminate with the last chunk of data. See the » zlib manual for a detailed description of these constants.

### Rückgabewerte

Returns a chunk of uncompressed data, Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

If invalid parameters are given, inflating the data requires a preset dictionary, but none is specified, the compressed stream is corrupt or has an invalid checksum, an error of level `E_WARNING` is generated.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `context` expects an InflateContext instance now; previously, a resource was expected.

### Siehe auch

- inflate_init() - Initialize an incremental inflate context

# inflate_get_read_len

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_read_len — Get number of bytes read so far

### Beschreibung

function inflate_get_read_len(InflateContext `$context`): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`context`

### Rückgabewerte

Returns number of bytes read so farBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `context` expects an InflateContext instance now; previously, a resource was expected.

# inflate_get_status

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_status — Get decompression status

### Beschreibung

function inflate_get_status(InflateContext `$context`): int

Usually returns either `ZLIB_OK` or `ZLIB_STREAM_END`.

### Parameter-Liste

`context`

### Rückgabewerte

Returns decompression status.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `context` expects an InflateContext instance now; previously, a resource was expected.

# inflate_init

(PHP 7, PHP 8)

inflate_init — Initialize an incremental inflate context

### Beschreibung

function inflate_init(int `$encoding`, array|object `$options` = []): InflateContext|false

Initialize an incremental inflate context with the specified `encoding`.

### Parameter-Liste

`encoding`

  One of the `ZLIB_ENCODING_*` constants.

`options`

  An associative array which may contain the following elements:

  level

    The compression level in range -1..9; defaults to -1.

  memory

    The compression memory level in range 1..9; defaults to 8.

  window

    The zlib window size (logarithmic) in range 8..15; defaults to 15.

  strategy

    One of `ZLIB_FILTERED`, `ZLIB_HUFFMAN_ONLY`, `ZLIB_RLE`, `ZLIB_FIXED` or `ZLIB_DEFAULT_STRATEGY` (the default).

  dictionary

    A string or an array of strings of the preset dictionary (default: no preset dictionary).

### Rückgabewerte

Returns an inflate context resource (`zlib.inflate`) on success, Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

If an invalid encoding or option is passed to `options`, or the context couldn't be created, an error of level `E_WARNING` is generated.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns an InflateContext instance now; previously, a resource was returned.

### Anmerkungen

Achtung

Unlike gzinflate(), incremental inflate contexts do not constrain the length of the decoded data, so provide no automatic protection against Zip bombs.

### Siehe auch

- inflate_add() - Incrementally inflate encoded data
- deflate_init() - Initialize an incremental deflate context

# ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ob_gzhandler — ob_start callback function to gzip output buffer

### Beschreibung

function ob_gzhandler(string `$data`, int `$flags`): string|false

ob_gzhandler() is intended to be used as a callback function for ob_start() to help facilitate sending gz-encoded data to web browsers that support compressed web pages. Before ob_gzhandler() actually sends compressed data, it determines what type of content encoding the browser will accept ("gzip", "deflate" or none at all) and will return its output accordingly. All browsers are supported since it's up to the browser to send the correct header saying that it accepts compressed web pages. If a browser doesn't support compressed pages this function returns `false`.

### Parameter-Liste

`data`

`flags`

### Rückgabewerte

### Beispiele

Beispiel #1 ob_gzhandler() example

    <?php

    ob_start("ob_gzhandler");

    ?>
    <html>
    <body>
    <p>This should be a compressed page.</p>
    </body>
    </html>

### Anmerkungen

> Hinweis:

> ob_gzhandler() requires the zlib extension.

> Hinweis:

> You cannot use both ob_gzhandler() and zlib.output_compression. Also note that using zlib.output_compression is preferred over ob_gzhandler().

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren
- ob_end_flush() - Leert (sendet) den Rückgabewert des aktiven Ausgabe-Handlers und deaktiviert den aktiven Ausgabepuffer

# readgzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readgzfile — Gibt eine gz-komprimierte Datei aus

### Beschreibung

function readgzfile(string `$filename`, int `$use_include_path` = 0): int|false

Liest eine Datei, dekomprimiert sie und gibt das Ergebnis auf die Standardausgabe aus.

readgzfile() kann auch Dateien lesen, die nicht im gzip-Format vorliegen; in diesem Fall wird der Inhalt der Datei direkt ohne Dekomprimierung ausgegeben.

### Parameter-Liste

`filename`

  Der Dateiname. Die Datei wird geöffnet und ihr Inhalt auf die Standardausgabe ausgegeben.

`use_include_path`

  Dieser Parameter kann auf `1` gesetzt werden, wenn die Datei auch im include_path gesucht werden soll.

### Rückgabewerte

Gibt im Erfolgsfall die Anzahl der ausgegebenen Zeichen zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Siehe auch

- gzpassthru() - Gibt alle verbleibenden Daten eines gz-Dateizeigers aus
- gzfile() - Liest eine ganze gz-Datei in ein Array
- gzopen() - Öffnet eine gz-Datei

# zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decode — Dekomprimiert raw-/gzip-/zlib-kodierte Daten

### Beschreibung

function zlib_decode(string `$data`, int `$max_length` = 0): string|false

Dekomprimiert raw-/gzip-/zlib-kodierte Daten.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`data`

`max_length`

### Rückgabewerte

Gibt die unkomprimierten Daten zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- zlib_encode() - Komprimiert Daten mit der gewählten Kodierung

# zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encode — Komprimiert Daten mit der gewählten Kodierung

### Beschreibung

function zlib_encode(string `$data`, int `$encoding`, int `$level` = -1): string|false

Komprimiert Daten mit der gewählten Kodierung.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`data`

  Die zu komprimierenden Daten.

`encoding`

  Der Komprimierungsalgorithmus. Entweder `ZLIB_ENCODING_RAW`, `ZLIB_ENCODING_DEFLATE` oder `ZLIB_ENCODING_GZIP`.

`level`

### Rückgabewerte

### Beispiele

Beispiel #1 zlib_encode()-Beispiel

    <?php
    $str = 'hallo welt';
    $enc = zlib_encode($str, ZLIB_ENCODING_DEFLATE);
    echo bin2hex($enc);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    789ccb48ccc9c957284fcd290100156803ed

### Siehe auch

- zlib_decode() - Dekomprimiert raw-/gzip-/zlib-kodierte Daten

# zlib_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_type — Gibt die für Ausgabekomprimierung genutzte Methode zurück

### Beschreibung

function zlib_get_coding_type(): string|false

Gibt die für Ausgabekomprimierung genutzte Methode zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Mögliche Ergebnisse sind `gzip`, `deflate` oder `false`.

### Siehe auch

- Die zlib.output_compression-Direktive.

## Inhaltsverzeichnis

- deflate_add — Incrementally deflate data
- deflate_init — Initialize an incremental deflate context
- gzclose — Schließt einen geöffnete gz-Dateizeiger
- gzcompress — Komprimiert einen String
- gzdecode — Dekodiert eine gzip-komprimierte Zeichenkette
- gzdeflate — Komprimiert eine Zeichenkette
- gzencode — Create a gzip compressed string
- gzeof — Prüft bei einem gz-Dateizeiger auf EOF
- gzfile — Liest eine ganze gz-Datei in ein Array
- gzgetc — Holt Zeichen vom gz-Dateizeiger
- gzgets — Get line from file pointer
- gzgetss — Holt eine Zeile vom gz-Dateizeiger und entfernt die HTML-Tags
- gzinflate — Dekomprimiert eine komprimierte Zeichenkette
- gzopen — Öffnet eine gz-Datei
- gzpassthru — Gibt alle verbleibenden Daten eines gz-Dateizeigers aus
- gzputs — Alias von gzwrite
- gzread — Liest binary-safe aus einer gz-Datei
- gzrewind — Setzt den gz-Dateizeiger auf den Anfang zurück
- gzseek — Positioniert den gz-Dateizeiger
- gztell — Ermittelt die aktuelle Position eines gz-Dateizeigers
- gzuncompress — Dekomprimiert einen komprimierten String
- gzwrite — Ausgabe in gz-komprimierte Dateien
- inflate_add — Incrementally inflate encoded data
- inflate_get_read_len — Get number of bytes read so far
- inflate_get_status — Get decompression status
- inflate_init — Initialize an incremental inflate context
- ob_gzhandler — ob_start callback function to gzip output buffer
- readgzfile — Gibt eine gz-komprimierte Datei aus
- zlib_decode — Dekomprimiert raw-/gzip-/zlib-kodierte Daten
- zlib_encode — Komprimiert Daten mit der gewählten Kodierung
- zlib_get_coding_type — Gibt die für Ausgabekomprimierung genutzte Methode zurück

# The DeflateContext class

(PHP 8)

## Einführung

A fully opaque class which replaces `zlib.deflate` resources as of PHP 8.0.0.

## Klassenbeschreibung

final class DeflateContext {
}

# The InflateContext class

(PHP 8)

## Einführung

A fully opaque class which replaces `zlib.inflate` resources as of PHP 8.0.0.

## Klassenbeschreibung

final class InflateContext {
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Beispiele
- Zlib-Funktionen
  - deflate_add — Incrementally deflate data
  - deflate_init — Initialize an incremental deflate context
  - gzclose — Schließt einen geöffnete gz-Dateizeiger
  - gzcompress — Komprimiert einen String
  - gzdecode — Dekodiert eine gzip-komprimierte Zeichenkette
  - gzdeflate — Komprimiert eine Zeichenkette
  - gzencode — Create a gzip compressed string
  - gzeof — Prüft bei einem gz-Dateizeiger auf EOF
  - gzfile — Liest eine ganze gz-Datei in ein Array
  - gzgetc — Holt Zeichen vom gz-Dateizeiger
  - gzgets — Get line from file pointer
  - gzgetss — Holt eine Zeile vom gz-Dateizeiger und entfernt die HTML-Tags
  - gzinflate — Dekomprimiert eine komprimierte Zeichenkette
  - gzopen — Öffnet eine gz-Datei
  - gzpassthru — Gibt alle verbleibenden Daten eines gz-Dateizeigers aus
  - gzputs — Alias von gzwrite
  - gzread — Liest binary-safe aus einer gz-Datei
  - gzrewind — Setzt den gz-Dateizeiger auf den Anfang zurück
  - gzseek — Positioniert den gz-Dateizeiger
  - gztell — Ermittelt die aktuelle Position eines gz-Dateizeigers
  - gzuncompress — Dekomprimiert einen komprimierten String
  - gzwrite — Ausgabe in gz-komprimierte Dateien
  - inflate_add — Incrementally inflate encoded data
  - inflate_get_read_len — Get number of bytes read so far
  - inflate_get_status — Get decompression status
  - inflate_init — Initialize an incremental inflate context
  - ob_gzhandler — ob_start callback function to gzip output buffer
  - readgzfile — Gibt eine gz-komprimierte Datei aus
  - zlib_decode — Dekomprimiert raw-/gzip-/zlib-kodierte Daten
  - zlib_encode — Komprimiert Daten mit der gewählten Kodierung
  - zlib_get_coding_type — Gibt die für Ausgabekomprimierung genutzte Methode zurück
- DeflateContext — The DeflateContext class
- InflateContext — The InflateContext class

- Bzip2
  - Installation/Konfiguration
  - Beispiele
  - Bzip2 Funktionen
- LZF
  - Installation/Konfiguration
  - LZF Funktionen
- Phar
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Using Phar Archives
  - Creating Phar Archives
  - What makes a phar a phar and not a tar or a zip?
  - Phar — Die Klasse Phar
  - PharData — The PharData class
  - PharFileInfo — The PharFileInfo class
  - PharException — The PharException class
- Rar — Rar Archiving
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - RAR Funktionen
  - RarArchive — The RarArchive class
  - RarEntry — The RarEntry class
  - RarException — The RarException class
- Zip
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - ZipArchive — Die Klasse ZipArchive
  - Zip Funktionen
- Zlib — Zlib-Komprimierung
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Zlib-Funktionen
  - DeflateContext — The DeflateContext class
  - InflateContext — The InflateContext class

# Kryptografische Erweiterungen

# HASH Message Digest Framework

# Einführung

Diese Erweiterung bietet Funktionen für die direkte oder inkrementelle Verarbeitung von Nachrichten beliebiger Länge unter Verwendung verschiedener Hash-Algorithmen. Dazu gehören auch die Erzeugung von HMAC-Werten und Schlüsselableitungen einschließlich HKDF und PBKDF2.

Es gibt im Wesentlichen drei Kategorien von Hash-Algorithmen. Siehe hash_algos() für eine vollständige Liste.

- Prüfsummenalgorithmen (z. B. `"crc32b"` oder `"adler32"`): Diese werden zur Berechnung von Prüfsummen verwendet, was z. B. nützlich ist, um Übertragungsfehler zu erkennen. Sie sind in der Regel sehr schnell. Da diese Algorithmen oft Werte erzeugen, die leicht zu "erraten" sind oder manipuliert werden können, um Kollisionen zu erzeugen, sind sie für kryptografische Zwecke völlig ungeeignet.
- Nicht-kryptografische Algorithmen (z. B. die xxHash-Familie): Diese Algorithmen werden häufig zur Berechnung von Hashwerten für Hashtabellen verwendet, weil sie darauf ausgelegt sind, eine gute Verteilung über beliebige Zeichenketten zu erzeugen. Auch sie sind im Allgemeinen schnell, aber ebenfalls nicht für kryptografische Zwecke geeignet.
- Kryptographische Algorithmen (z. B. die SHA-2-Familie): Diese Algorithmen wurden entwickelt, um Hashwerte zu erzeugen, die die Eingaben darstellen, aber weder erraten werden können noch anfällig für Kollisionen sind. Die Leistung ist oft zweitrangig, aber moderne Hardware unterstützt oft eine spezielle Handhabung für diese Algorithmen, die PHP zu nutzen versucht, wenn sie verfügbar ist. Das Computer Security Resource Center des NIST bietet eine » Beschreibung der Algorithmen, die derzeit von den United States Federal Information Processing Standards (FIPS) zugelassen sind.
  Achtung

  Einige der frühen kryptographischen Algorithmen wie `"md4"`, `"md5"` und `"sha1"` haben sich als anfällig für Kollisionsangriffe erwiesen und es wird allgemein empfohlen, diese nicht mehr für kryptographische Anwendungen zu verwenden.

Siehe auch die FAQ zum sicheren Hashing von Passwörtern für Informationen über bewährte Verfahren bei der Verwendung von Hash-Funktionen im Umgang mit Passwörtern.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Ressource-Typen

## Installation

Die Hash-Erweiterung ist eine PHP-Core-Erweiterung und daher immer aktiviert.

Vor PHP 7.4.0 wurde die Hash-Erweiterung standardmäßig mitgeliefert und in PHP einkompiliert, konnte aber mit --disable-hash explizit deaktiviert werden.

Vor PHP 5.1.2 wurde die Hash-Erweiterung als » PECL-Modul installiert.

## Ressource-Typen

Diese Erweiterung stellt eine Kontextressource für Hashs bereit, die von hash_init() zurückgegeben wird.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`HASH_HMAC` (int)
  Optionales Symbol für hash_init(). Es bewirkt, dass der HMAC-digest-keying-Algorithmus auf den aktuellen Hashing-Kontext angewendet werden soll.

# The HashContext class

(PHP 7 >= 7.2.0, PHP 8)

## Einführung

## Klassenbeschreibung

final class HashContext {
/* Methoden */
private function __construct()
public function __debugInfo(): array
public function __serialize(): array
public function __unserialize(array `$data`): void
}

# HashContext::__construct

(PHP 7 >= 7.2.0, PHP 8)

HashContext::__construct — Private constructor to disallow direct instantiation

### Beschreibung

private function HashContext::__construct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# HashContext::__debugInfo

(PHP 8 >= 8.4.0)

HashContext::__debugInfo — Returns debugging information about the hashing context

### Beschreibung

public function HashContext::__debugInfo(): array

This method is not meant to be called directly; it is invoked by var_dump() and related functions when inspecting a HashContext instance.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an associative array of debugging information. It contains an `algo` key holding the name of the hashing algorithm in use by the context.

### Beispiele

Beispiel #1 HashContext::__debugInfo() example

    <?php
    $ctx = hash_init('sha256');
    var_dump($ctx);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(HashContext)#1 (1) {
      ["algo"]=>
      string(6) "sha256"
    }

### Siehe auch

- hash_init() - Initialisiert einen schrittweisen Hashing-Kontext
- var_dump() - Gibt alle Informationen zu einer Variablen aus

# HashContext::__serialize

(PHP 8)

HashContext::__serialize — Serializes the HashContext object

### Beschreibung

public function HashContext::__serialize(): array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# HashContext::__unserialize

(PHP 8)

HashContext::__unserialize — Deserializes the `data` parameter into a HashContext object

### Beschreibung

public function HashContext::__unserialize(array `$data`): void

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`data`

  The value being deserialized.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

## Inhaltsverzeichnis

- HashContext::__construct — Private constructor to disallow direct instantiation
- HashContext::__debugInfo — Returns debugging information about the hashing context
- HashContext::__serialize — Serializes the HashContext object
- HashContext::__unserialize — Deserializes the data parameter into a HashContext object

# Hash-Funktionen

# hash

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash — Berechnet den Hash einer Nachricht

### Beschreibung

function hash(
string `$algo`,
string `$data`,
bool `$binary` = `false`,
array `$options` = []
): string

### Parameter-Liste

`algo`

  Der Name des gewählten Hash-Algorithmus (z. B. `"sha256"`). Für eine Liste der unterstützten Algorithmen, siehe hash_algos().

`data`

  Die Nachricht, die gehasht werden soll.

`binary`

  Ist dieser Parameter auf `true` gesetzt, werden direkt Binärdaten zurückgegeben. Bei `false` werden kleingeschriebene Hexadezimalzeichen zurückgegeben.

`options`

  Ein Array mit Optionen für die verschiedenen Hash-Algorithmen. Derzeit wird von den MurmurHash-Varianten nur der Parameter `"seed"` unterstützt.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die den berechneten Hash als kleingeschriebene Hexadezimalzeichen enthält, außer `binary` ist auf true gesetzt, in diesem Fall wird die binäre Darstellung des Hashes zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `options` wurde hinzugefügt.
8.0.0 | Wenn `algo` unbekannt ist, löst hash() nun eine ValueError-Exception aus; zuvor wurde stattdessen `false` zurückgegeben.

### Beispiele

Beispiel #1 hash()-Beispiel

    <?php
    echo hash('sha256', 'Franz jagt im komplett verwahrlosten Taxi quer durch Bayern.');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0b3a381e71cda8f3abe88b1dc3eb9aa2a53fa033e9802878edd1959c267281a2

### Siehe auch

- hash_init() - Initialisiert einen schrittweisen Hashing-Kontext
- hash_file() - Berechnet den Hash des Inhalts einer Datei
- hash_hmac() - Berechnet einen Hash mit Schlüssel unter Verwendung von HMAC

# hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algos — Liefert eine Liste der verfügbaren Hashing-Algorithmen

### Beschreibung

function hash_algos(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein nicht-assoziatives Array mit allen unterstützten Hashing-Algorithmen zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Die Unterstützung für die Algorithmen MurmurHash3 und xxHash wurde hinzugefügt.
7.4.0 | Die Ünterstützung für crc32c wurde hinzugefügt.
7.1.0 | Die Unterstützung für sha512/224, sha512/256, sha3-224, sha3-256, sha3-384 und sha3-512 wurde hinzugefügt.

### Beispiele

Beispiel #1 hash_algos()-Beispiel

Von PHP 8.1.0 an gibt hash_algos() die folgende Liste von Algorithmen zurück:

    <?php
    print_r(hash_algos());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => adler32
        [30] => crc32
        [31] => crc32b
        [32] => crc32c
        [33] => fnv132
        [34] => fnv1a32
        [35] => fnv164
        [36] => fnv1a64
        [37] => joaat
        [38] => murmur3a
        [39] => murmur3c
        [40] => murmur3f
        [41] => xxh32
        [42] => xxh64
        [43] => xxh3
        [44] => xxh128
        [45] => haval128,3
        [46] => haval160,3
        [47] => haval192,3
        [48] => haval224,3
        [49] => haval256,3
        [50] => haval128,4
        [51] => haval160,4
        [52] => haval192,4
        [53] => haval224,4
        [54] => haval256,4
        [55] => haval128,5
        [56] => haval160,5
        [57] => haval192,5
        [58] => haval224,5
        [59] => haval256,5
    )

### Siehe auch

- hash() - Berechnet den Hash einer Nachricht
- hash_hmac_algos() - Return a list of registered hashing algorithms suitable for hash_hmac

# hash_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copy — Dupliziert einen Hash-Kontext

### Beschreibung

function hash_copy(HashContext `$context`): HashContext

### Parameter-Liste

`context`

  Von hash_init() zurückgegebener Hash-Kontext.

### Rückgabewerte

Gibt eine Kopie des Hash-Kontexts zurück.

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | Erwartet und liefert nun einen HashContext anstatt einer Ressource.

### Beispiele

Beispiel #1 hash_copy()-Beispiel

    <?php
    $context = hash_init("sha256");
    hash_update($context, "Franz jagt im komplett verwahrlosten ");

    /* Dupliziere Kontext um ihn weiter nutzen zu können */
    $copy_context = hash_copy($context);

    echo hash_final($context), "\n";

    hash_update($copy_context, "Taxi quer durch Bayern.");
    echo hash_final($copy_context), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    6fed266d6c619258547eb7578a1e730b5fbd95405ef52b83339e0a7f9bf263fb
    0b3a381e71cda8f3abe88b1dc3eb9aa2a53fa033e9802878edd1959c267281a2

# hash_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equals — Timing attack safe string comparison

### Beschreibung

function hash_equals(#[\SensitiveParameter]string `$known_string`, #[\SensitiveParameter]string `$user_string`): bool

Checks whether two strings are equal without leaking information about the contents of `known_string` via the execution time.

This function can be used to mitigate timing attacks. Performing a regular comparison with `===` will take more or less time to execute depending on whether the two values are different or not and at which position the first difference can be found, thus leaking information about the contents of the secret `known_string`.

Achtung

It is important to provide the user-supplied string as the second parameter, rather than the first.

### Parameter-Liste

`known_string`

  The known String that must be kept secret.

`user_string`

  The user-supplied String to compare against.

### Rückgabewerte

Returns `true` when the two strings are equal, `false` otherwise.

### Beispiele

Beispiel #1 hash_equals() example

    <?php
    $secretKey = '8uRhAeH89naXfFXKGOEj';

    // Value and signature are provided by the user, e.g. within the URL
    // and retrieved using $_GET.
    $value = 'username=rasmuslerdorf';
    $signature = '8c35009d3b50caf7f5d2c1e031842e6b7823a1bb781d33c5237cd27b57b5f327';

    if (hash_equals(hash_hmac('sha256', $value, $secretKey), $signature)) {
        echo "The value is correctly signed.", PHP_EOL;
    } else {
        echo "The value was tampered with.", PHP_EOL;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    The value is correctly signed.

### Anmerkungen

> Hinweis:

> Both arguments must be of the same length to be compared successfully. When arguments of differing length are supplied, `false` is returned immediately and the length of the known string may be leaked in case of a timing attack.

### Siehe auch

- hash_hmac() - Berechnet einen Hash mit Schlüssel unter Verwendung von HMAC

# hash_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_file — Berechnet den Hash des Inhalts einer Datei

### Beschreibung

function hash_file(
string `$algo`,
string `$filename`,
bool `$binary` = `false`,
array `$options` = []
): string|false

### Parameter-Liste

`algo`

  Der Name des gewählten Hash-Algorithmus (z. B. `"sha256"`). Für eine Liste der unterstützten Algorithmen siehe hash_algos().

`filename`

  Die URL der Datei, die gehasht werden soll; fopen()-Wrapper werden unterstützt.

`binary`

  Ist dieser Parameter auf `true` gesetzt, werden direkt Binärdaten zurückgegeben, andernfalls werden kleingeschriebene Hexadezimalziffern zurückgegeben.

`options`

  Ein Array mit Optionen für die verschiedenen Hash-Algorithmen. Derzeit wird von den MurmurHash-Varianten nur der Parameter `"seed"` unterstützt.

### Rückgabewerte

Gibt den berechneten Hash als Hexadezimalzahl zurück, außer `binary` ist auf `true` gesetzt, in diesem Fall wird die binäre Darstellung des Hashes zurückgegeben. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `options` wurde hinzugefügt.

### Beispiele

Beispiel #1 hash_file()-Beispiel

    <?php
    /* Erstelle die Datei, deren Inhalt gehasht werden soll */
    file_put_contents('example.txt', 'Franz jagt im komplett verwahrlosten Taxi quer durch Bayern.');

    echo hash_file('sha256', 'example.txt');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0b3a381e71cda8f3abe88b1dc3eb9aa2a53fa033e9802878edd1959c267281a2

### Siehe auch

- hash_init() - Initialisiert einen schrittweisen Hashing-Kontext
- hash_hmac_file() - Berechnet einen Hash einer Datei mit Schlüssel unter Verwendung von HMAC

# hash_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_final — Schließt einen schrittweisen Hashing-Vorgang ab und liefert sein Ergebnis

### Beschreibung

function hash_final(HashContext `$context`, bool `$binary` = `false`): string

### Parameter-Liste

`context`

  Der Hashing-Kontext, zurückgegeben von hash_init().

`binary`

  Ist dieser Parameter auf `true` gesetzt, werden direkt Binärdaten zurückgegeben, andernfalls werden kleingeschriebene Hexadezimalziffern zurückgegeben.

### Rückgabewerte

Gibt den berechneten Hash als Hexadezimalzahl zurück, außer `binary` ist auf `true` gesetzt, in diesem Fall wird die binäre Darstellung des Hashes zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | Erwartet nun einen HashContext anstatt einer Ressource.

### Siehe auch

- hash_init() - Initialisiert einen schrittweisen Hashing-Kontext
- hash_update() - Fügt Daten an einen aktiven Hash-Kontext an
- hash_update_stream() - Fügt Daten aus einem Stream an einen aktiven Hash-Kontext an
- hash_update_file() - Fügt Daten aus einer Datei an einen aktiven Hash-Kontext an

# hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdf — Generate a HKDF key derivation of a supplied key input

### Beschreibung

function hash_hkdf(
string `$algo`,
#[\SensitiveParameter]string `$key`,
int `$length` = 0,
string `$info` = "",
string `$salt` = ""
): string

### Parameter-Liste

`algo`

  Name of selected hashing algorithm (e.g. `"sha256"`). For a list of supported algorithms see hash_hmac_algos().

  > Hinweis:

  > Non-cryptographic hash functions are not allowed.

`key`

  Input keying material (raw binary). Cannot be empty.

`length`

  Desired output length in bytes. Cannot be greater than 255 times the chosen hash function size.

  If `length` is `0`, the output length will default to the chosen hash function size.

`info`

  Application/context-specific info string.

`salt`

  Salt to use during derivation.

  While optional, adding random salt significantly improves the strength of HKDF.

### Rückgabewerte

Returns a string containing a raw binary representation of the derived key (also known as output keying material - OKM).

### Fehler/Exceptions

Throws a ValueError exception if `key` is empty, `algo` is unknown/non-cryptographic, `length` is less than `0` or too large (greater than 255 times the size of the hash function).

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Now throws a ValueError exception on error. Previously, `false` was returned and an `E_WARNING` message was emitted.

### Beispiele

The example below produces a pair of separate keys, suitable for creation of an encrypt-then-HMAC construct, using AES-256 and SHA-256 for encryption and authentication respectively.

Beispiel #1 hash_hkdf() example

    <?php
    // Generate a random key, and salt to strengthen it during derivation.
    $inputKey = random_bytes(32);
    $salt = random_bytes(16);

    // Derive a pair of separate keys, using the same input created above.
    $encryptionKey = hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption', $salt);
    $authenticationKey = hash_hkdf('sha256', $inputKey, 32, 'sha-256-authentication', $salt);

    var_dump($encryptionKey !== $authenticationKey); // bool(true)
    ?>

### Siehe auch

- hash_pbkdf2() - Generate a PBKDF2 key derivation of a supplied password
- » RFC 5869
- » userland implementation

# hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac — Berechnet einen Hash mit Schlüssel unter Verwendung von HMAC

### Beschreibung

function hash_hmac(
string `$algo`,
string `$data`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string

### Parameter-Liste

`algo`

  Der Name des gewählten Hash-Algorithmus (z. B. `"sha256"`). Für eine Liste der unterstützten Algorithmen, siehe hash_hmac_algos().

  > Hinweis:

  > Nicht-kryptografische Hash-Funktionen sind nicht erlaubt.

`data`

  Die Nachricht, die gehasht werden soll.

`key`

  Ein geheimer Schlüssel für die Berechnung der HMAC-Variante des Hashes.

`binary`

  Ist dieser Parameter auf `true` gesetzt, werden direkt Binärdaten zurückgegeben, andernfalls werden kleingeschriebene Hexadezimalziffern zurückgegeben.

### Rückgabewerte

Gibt den berechneten Hash als Hexadezimalzahl zurück, außer `binary` ist auf `true` gesetzt, in diesem Fall wird die binäre Darstellung des Hashes zurückgegeben.

### Fehler/Exceptions

Löst eine ValueError-Exception aus, wenn `algo` nicht bekannt ist oder eine nicht-kryptographische Hash-Funktion ist.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Löst nun eine ValueError-Exception aus, wenn `algo` nicht bekannt ist oder eine nicht-kryptographische Hash-Funktion ist; zuvor wurde `false` zurückgegeben und eine `E_WARNING`-Meldung wurde ausgegeben.
7.2.0 | Die Verwendung nicht-kryptografischer Hashfunktionen (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) ist nicht mehr möglich.

### Beispiele

Beispiel #1 hash_hmac()-Beispiel

    <?php
    echo hash_hmac('sha256', 'Franz jagt im komplett verwahrlosten Taxi quer durch Bayern.', 'geheimnis');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    b34775b66659af83b5e51064aa61e6f09df258b78842b4347e46b5028da8b021

### Siehe auch

- hash_hmac_algos() - Return a list of registered hashing algorithms suitable for hash_hmac
- hash_hmac_file() - Berechnet einen Hash einer Datei mit Schlüssel unter Verwendung von HMAC
- hash_equals() - Timing attack safe string comparison

# hash_hmac_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algos — Return a list of registered hashing algorithms suitable for hash_hmac

### Beschreibung

function hash_hmac_algos(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a numerically indexed array containing the list of supported hashing algorithms suitable for hash_hmac().

### Beispiele

Beispiel #1 hash_hmac_algos() example

    <?php
    print_r(hash_hmac_algos());

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => md2
        [1] => md4
        [2] => md5
        [3] => sha1
        [4] => sha224
        [5] => sha256
        [6] => sha384
        [7] => sha512/224
        [8] => sha512/256
        [9] => sha512
        [10] => sha3-224
        [11] => sha3-256
        [12] => sha3-384
        [13] => sha3-512
        [14] => ripemd128
        [15] => ripemd160
        [16] => ripemd256
        [17] => ripemd320
        [18] => whirlpool
        [19] => tiger128,3
        [20] => tiger160,3
        [21] => tiger192,3
        [22] => tiger128,4
        [23] => tiger160,4
        [24] => tiger192,4
        [25] => snefru
        [26] => snefru256
        [27] => gost
        [28] => gost-crypto
        [29] => haval128,3
        [30] => haval160,3
        [31] => haval192,3
        [32] => haval224,3
        [33] => haval256,3
        [34] => haval128,4
        [35] => haval160,4
        [36] => haval192,4
        [37] => haval224,4
        [38] => haval256,4
        [39] => haval128,5
        [40] => haval160,5
        [41] => haval192,5
        [42] => haval224,5
        [43] => haval256,5
    )

### Anmerkungen

> Hinweis:

> Before PHP 7.2.0 the only means to get a list of supported hash algorithms has been to call hash_algos() which also returns hash algorithms that are not suitable for hash_hmac().

### Siehe auch

- hash_hmac() - Berechnet einen Hash mit Schlüssel unter Verwendung von HMAC
- hash_algos() - Liefert eine Liste der verfügbaren Hashing-Algorithmen

# hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_file — Berechnet einen Hash einer Datei mit Schlüssel unter Verwendung von HMAC

### Beschreibung

function hash_hmac_file(
string `$algo`,
string `$filename`,
#[\SensitiveParameter]string `$key`,
bool `$binary` = `false`
): string|false

### Parameter-Liste

`algo`

  Der Name des gewählten Hash-Algorithmus (z. B. `"sha256"`). Für eine Liste der unterstützten Algorithmen, siehe hash_hmac_algos().

  > Hinweis:

  > Nicht-kryptografische Hash-Funktionen sind nicht erlaubt.

`filename`

  Die URL der Datei, die gehasht werden soll; fopen-Wrapper werden unterstützt.

`key`

  Ein geheimer Schlüssel für die Berechnung der HMAC-Variante des Hashes.

`binary`

  Ist dieser Parameter auf `true` gesetzt, werden direkt Binärdaten zurückgegeben, andernfalls werden kleingeschriebene Hexadezimalziffern zurückgegeben.

### Rückgabewerte

Gibt den berechneten Hash als Hexadezimalzahl zurück, außer `binary` ist auf `true` gesetzt. In diesem Fall wird die binäre Darstellung des Hashes zurückgegeben. Gibt `false` zurück, wenn die Datei `filename` nicht gelesen werden kann.

### Fehler/Exceptions

Löst eine ValueError-Exception aus, wenn `algo` nicht bekannt ist oder eine nicht-kryptographische Hash-Funktion ist.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Es wird nun eine ValueError-Exception geworfen, wenn `algo` unbekannt ist oder eine nicht-kryptografische Hash-Funktion darstellt; zuvor wurde `false` zurückgegeben und eine `E_WARNING`-Meldung ausgegeben.
7.2.0 | Die Verwendung von nicht-kryptographischen Hashfunktionen (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) wurde deaktiviert.

### Beispiele

Beispiel #1 hash_hmac_file()-Beispiel

    <?php
    /* Erstelle die Datei, deren Inhalt gehasht werden soll */
    file_put_contents('example.txt', 'Franz jagt im komplett verwahrlosten Taxi quer durch Bayern.');

    echo hash_hmac_file('sha256', 'example.txt', 'geheimnis');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    b34775b66659af83b5e51064aa61e6f09df258b78842b4347e46b5028da8b021

### Siehe auch

- hash_hmac() - Berechnet einen Hash mit Schlüssel unter Verwendung von HMAC
- hash_hmac_algos() - Return a list of registered hashing algorithms suitable for hash_hmac
- hash_init() - Initialisiert einen schrittweisen Hashing-Kontext
- hash_equals() - Timing attack safe string comparison

# hash_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_init — Initialisiert einen schrittweisen Hashing-Kontext

### Beschreibung

function hash_init(
string `$algo`,
int `$flags` = 0,
#[\SensitiveParameter]string `$key` = "",
array `$options` = []
): HashContext

### Parameter-Liste

`algo`

  Der Name des gewählten Hash-Algorithmus (z. B. `"sha256"`). Für eine Liste der unterstützten Algorithmen, siehe hash_algos().

  > Hinweis:

  > Wenn das Flag `HASH_HMAC` angegeben ist, sind nicht-kryptografische Hash-Funktionen nicht erlaubt.

`flags`

  Optionale Einstellungen für die Erzeugung von Hashes. Aktuell wird nur eine Option unterstützt: `HASH_HMAC`. Wenn diese gesetzt ist, muss der Parameter `key` angegeben werden.

`key`

  Ein geheimer Schlüssel zur Verwendung mit dem HMAC-Verfahren. Wenn `HASH_HMAC` bei `flags` angegeben ist, muss `key` angegeben werden.

`options`

  Ein Array mit Optionen für die verschiedenen Hash-Algorithmen. Derzeit wird von den MurmurHash-Varianten nur der Parameter `"seed"` unterstützt.

### Rückgabewerte

Gibt einen Hashing-Kontext zur Nutzung mit hash_update(), hash_update_stream(), hash_update_file(), und hash_final() zurück.

### Fehler/Exceptions

- Löst eine ValueError-Exception aus, wenn `algo` nicht bekannt ist oder eine nicht-kryptographische Hash-Funktion ist oder wenn `key` leer ist.
- Wenn in `options` Konfigurationsoptionen vom falschen Typ übergeben werden, wird nun ein Fehler der Stufe `E_DEPRECATED` ausgegeben, da sie falsch interpretiert werden können. In Zukunft wird dies ein ValueError sein.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Übergabe von Optionen eines falschen Typs ist nun veraltet.
8.1.0 | Der Parameter `options` wurde hinzugefügt.
8.0.0 | Löst nun eine ValueError-Exception aus, wenn `algo` unbekannt ist oder eine nicht kryptographische Hash-Funktion ist oder wenn `key` leer ist. Zuvor wurde `false` zurückgegeben und eine Meldung der Stufe `E_WARNING` ausgegeben.
7.2.0 | Die Verwendung nicht-kryptografischer Hashfunktionen (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) mit `HASH_HMAC` ist nicht mehr möglich.
7.2.0 | Gibt nun einen HashContext anstatt einer Ressource zurück.

### Beispiele

Beispiel #1 Beispiel für schrittweises Hashing

    <?php
    $hash = hash('sha256', 'Franz jagt im komplett verwahrlosten Taxi quer durch Bayern.');

    $ctx = hash_init('sha256');
    hash_update($ctx, 'Franz jagt im komplett verwahrlosten ');
    hash_update($ctx, 'Taxi quer durch Bayern.');
    $incremental_hash = hash_final($ctx);

    echo $incremental_hash, PHP_EOL;
    var_dump($hash === $incremental_hash);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0b3a381e71cda8f3abe88b1dc3eb9aa2a53fa033e9802878edd1959c267281a2
    bool(true)

### Siehe auch

- hash_algos() - Liefert eine Liste der verfügbaren Hashing-Algorithmen
- hash_update() - Fügt Daten an einen aktiven Hash-Kontext an
- hash_update_file() - Fügt Daten aus einer Datei an einen aktiven Hash-Kontext an
- hash_update_stream() - Fügt Daten aus einem Stream an einen aktiven Hash-Kontext an
- hash_final() - Schließt einen schrittweisen Hashing-Vorgang ab und liefert sein Ergebnis

# hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — Generate a PBKDF2 key derivation of a supplied password

### Beschreibung

function hash_pbkdf2(
string `$algo`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$iterations`,
int `$length` = 0,
bool `$binary` = `false`,
array `$options` = []
): string

### Parameter-Liste

`algo`

  Name of selected hashing algorithm (e.g. `"sha256"`). For a list of supported algorithms see hash_hmac_algos().

  > Hinweis:

  > Non-cryptographic hash functions are not allowed.

`password`

  The password to use for the derivation.

`salt`

  The salt to use for the derivation. This value should be generated randomly.

`iterations`

  The number of internal iterations to perform for the derivation.

`length`

  The length of the output string. If `binary` is `true` this corresponds to the byte-length of the derived key, if `binary` is `false` this corresponds to twice the byte-length of the derived key (as every byte of the key is returned as two hexits).

  If `0` is passed, the entire output of the supplied algorithm is used.

`binary`

  When set to `true`, outputs raw binary data. `false` outputs lowercase hexits.

`options`

  An array of options for the various hashing algorithms. Currently, only the `"seed"` key is supported by the MurmurHash variants.

### Rückgabewerte

Returns a string containing the derived key as lowercase hexits unless `binary` is set to `true` in which case the raw binary representation of the derived key is returned.

### Fehler/Exceptions

Throws a ValueError exception if the algorithm is unknown, the `iterations` parameter is less than or equal to `0`, the `length` is less than `0` or the `salt` is too long (greater than `INT_MAX``- 4`).

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Now throws a ValueError exception on error. Previously, `false` was returned and an `E_WARNING` message was emitted.
7.2.0 | Usage of non-cryptographic hash functions (adler32, crc32, crc32b, fnv132, fnv1a32, fnv164, fnv1a64, joaat) was disabled.

### Beispiele

Beispiel #1 hash_pbkdf2() example, basic usage

    <?php
    $password = "password";
    $iterations = 600000;

    // Generate a cryptographically secure random salt using random_bytes()
    $salt = random_bytes(16);

    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 20);
    var_dump($hash);

    // for raw binary, the $length needs to be halved for equivalent results
    $hash = hash_pbkdf2("sha256", $password, $salt, $iterations, 10, true);
    var_dump(bin2hex($hash));?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(20) "120fb6cffcf8b32c43e7"
    string(20) "120fb6cffcf8b32c43e7"

### Anmerkungen

Achtung

The PBKDF2 method can be used for hashing passwords for storage. However, it should be noted that password_hash() or crypt() with `CRYPT_BLOWFISH` are better suited for password storage.

### Siehe auch

- password_hash() - Erstellt einen Passwort-Hash
- hash_hkdf() - Generate a HKDF key derivation of a supplied key input
- sodium_crypto_pwhash() - Derive a key from a password, using Argon2

# hash_update

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update — Fügt Daten an einen aktiven Hash-Kontext an

### Beschreibung

function hash_update(HashContext `$context`, string `$data`): true

### Parameter-Liste

`context`

  Der Hashing-Kontext, zurückgegeben von hash_init().

`data`

  Die Nachricht, die in den Hash-Kontext eingefügt wird.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Hat nun den Rückgabetyp true anstelle von bool.
7.2.0 | Erwartet nun einen HashContext anstatt einer Ressource.

### Siehe auch

- hash_init() - Initialisiert einen schrittweisen Hashing-Kontext
- hash_update_file() - Fügt Daten aus einer Datei an einen aktiven Hash-Kontext an
- hash_update_stream() - Fügt Daten aus einem Stream an einen aktiven Hash-Kontext an
- hash_final() - Schließt einen schrittweisen Hashing-Vorgang ab und liefert sein Ergebnis

# hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_file — Fügt Daten aus einer Datei an einen aktiven Hash-Kontext an

### Beschreibung

function hash_update_file(HashContext `$context`, string `$filename`, ?resource `$stream_context` = `null`): bool

### Parameter-Liste

`context`

  Der Hashing-Kontext, zurückgegeben von hash_init().

`filename`

  Die URL der Datei, die zum Kontext hinzugefügt werden soll; fopen()-Wrapper werden unterstützt.

`stream_context`

  Der Stream-Kontext, wie von stream_context_create() zurückgegeben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `stream_context` ist nun ein Nullable-Typ.
7.2.0 | Erwartet nun einen HashContext anstatt einer Ressource.

### Siehe auch

- hash_init() - Initialisiert einen schrittweisen Hashing-Kontext
- hash_update() - Fügt Daten an einen aktiven Hash-Kontext an
- hash_update_stream() - Fügt Daten aus einem Stream an einen aktiven Hash-Kontext an
- hash_final() - Schließt einen schrittweisen Hashing-Vorgang ab und liefert sein Ergebnis
- hash_file() - Berechnet den Hash des Inhalts einer Datei

# hash_update_stream

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_stream — Fügt Daten aus einem Stream an einen aktiven Hash-Kontext an

### Beschreibung

function hash_update_stream(HashContext `$context`, resource `$stream`, int `$length` = -1): int

### Parameter-Liste

`context`

  Der Hashing-Kontext, zurückgegeben von hash_init().

`stream`

  Die Ressource einer geöffneten Datei, wie sie von einer beliebigen Funktion zur Stream-Erstellung zurückgegeben wird.

`length`

  Die maximale Anzahl an Zeichen, die von `stream` in den Hashing-Kontext kopiert werden.

### Rückgabewerte

Die Anzahl an Bytes, die dem Hashing-Kontext von `stream` hinzugefügt wurden.

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | Erwartet nun einen HashContext anstatt einer Ressource.

### Beispiele

Beispiel #1 hash_update_stream()-Beispiel

    <?php
    $fp = tmpfile();
    fwrite($fp, 'Taxi quer durch Bayern.');
    rewind($fp);

    $ctx = hash_init('sha256');
    hash_update($ctx, 'Franz jagt im komplett verwahrlosten ');
    hash_update_stream($ctx, $fp);
    echo hash_final($ctx);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0b3a381e71cda8f3abe88b1dc3eb9aa2a53fa033e9802878edd1959c267281a2

### Siehe auch

- hash_init() - Initialisiert einen schrittweisen Hashing-Kontext
- hash_update() - Fügt Daten an einen aktiven Hash-Kontext an
- hash_final() - Schließt einen schrittweisen Hashing-Vorgang ab und liefert sein Ergebnis

## Inhaltsverzeichnis

- hash — Berechnet den Hash einer Nachricht
- hash_algos — Liefert eine Liste der verfügbaren Hashing-Algorithmen
- hash_copy — Dupliziert einen Hash-Kontext
- hash_equals — Timing attack safe string comparison
- hash_file — Berechnet den Hash des Inhalts einer Datei
- hash_final — Schließt einen schrittweisen Hashing-Vorgang ab und liefert sein Ergebnis
- hash_hkdf — Generate a HKDF key derivation of a supplied key input
- hash_hmac — Berechnet einen Hash mit Schlüssel unter Verwendung von HMAC
- hash_hmac_algos — Return a list of registered hashing algorithms suitable for hash_hmac
- hash_hmac_file — Berechnet einen Hash einer Datei mit Schlüssel unter Verwendung von HMAC
- hash_init — Initialisiert einen schrittweisen Hashing-Kontext
- hash_pbkdf2 — Generate a PBKDF2 key derivation of a supplied password
- hash_update — Fügt Daten an einen aktiven Hash-Kontext an
- hash_update_file — Fügt Daten aus einer Datei an einen aktiven Hash-Kontext an
- hash_update_stream — Fügt Daten aus einem Stream an einen aktiven Hash-Kontext an

- Installation/Konfiguration
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- HashContext — The HashContext class
  - HashContext::__construct — Private constructor to disallow direct instantiation
  - HashContext::__debugInfo — Returns debugging information about the hashing context
  - HashContext::__serialize — Serializes the HashContext object
  - HashContext::__unserialize — Deserializes the data parameter into a HashContext object
- Hash-Funktionen
  - hash — Berechnet den Hash einer Nachricht
  - hash_algos — Liefert eine Liste der verfügbaren Hashing-Algorithmen
  - hash_copy — Dupliziert einen Hash-Kontext
  - hash_equals — Timing attack safe string comparison
  - hash_file — Berechnet den Hash des Inhalts einer Datei
  - hash_final — Schließt einen schrittweisen Hashing-Vorgang ab und liefert sein Ergebnis
  - hash_hkdf — Generate a HKDF key derivation of a supplied key input
  - hash_hmac — Berechnet einen Hash mit Schlüssel unter Verwendung von HMAC
  - hash_hmac_algos — Return a list of registered hashing algorithms suitable for hash_hmac
  - hash_hmac_file — Berechnet einen Hash einer Datei mit Schlüssel unter Verwendung von HMAC
  - hash_init — Initialisiert einen schrittweisen Hashing-Kontext
  - hash_pbkdf2 — Generate a PBKDF2 key derivation of a supplied password
  - hash_update — Fügt Daten an einen aktiven Hash-Kontext an
  - hash_update_file — Fügt Daten aus einer Datei an einen aktiven Hash-Kontext an
  - hash_update_stream — Fügt Daten aus einem Stream an einen aktiven Hash-Kontext an

# Mcrypt

# Einführung

Warnung

Dieses Feature wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und in PHP 7.2.0 REMOVED (entfernt).

Alternativ können die folgenden Features verwendet werden:

- Sodium (verfügbar von PHP 7.2.0 an)
- OpenSSL

> Hinweis: Diese Erweiterung wurde ins » PECL-Repositorium verschoben und ist nicht mehr Teil von PHP ab PHP 7.2.0.

Dies ist eine Schnittstelle zur mcrypt Bibliothek, welche eine breite Spanne von Block-Algorythmen wie DES, TripleDES, Blowfish(standard), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 und GOST in den Chiffriermodi CBC, CFB, CFB und ECB unterstützt. Darüber hinaus unterstützt es auch RC6 und IDEA, welche als "nicht frei" gelten. CFB/OFB sind standardmäßig 8bit.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

Diese Funktionen arbeiten mit mcrypt. Um es zu verwenden, laden Sie libmcrypt-x.x.tar.gz von » http://mcrypt.sourceforge.net/ herunter und folgen den beiliegenden Installationsanweisungen.

libmcrypt Version 2.5.6 oder höher wird benötigt.

Windows-Benutzer werden die Bibliothek in den veröffentlichten PHP 5.2 Windows-Binärdateien finden. Die PHP 5.3 Windows-Binärdateien verwenden die statische Version der Mcrypt-Bibliothek, es werden keine DLLs benötigt.

Wenn Sie libmcrypt 2.4.x oder höher verwenden, werden die folgenden zusätzlichen Blockalgorythmen unterstützt: CASE, LOKI97, RIJNDAEL, SAFERPLUS, SERPENT und die folgenden Chiffren: ENIGMA (crypt), PANAMA, RC4 und WAKE. Mit libmcrypt 2.4.x oder höher ist ein weiterer Chiffriermodus verfügbar; nOFB.

## Installation

Diese Erweiterung wurde ins » PECL-Repositorium verschoben und ist nicht mehr Teil von PHP ab PHP 7.2.0

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/mcrypt.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Mcrypt-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
mcrypt.algorithms_dir | `null` | `INI_ALL` |
mcrypt.modes_dir | `null` | `INI_ALL` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`mcrypt.algorithms_dir` string
  Das Verzeichnis, das die Algorithmen enthält. Standardmäßig ist dies der beim Kompilieren von libmcrypt angegebene Ordner, typischerweise /usr/local/lib/libmcrypt. Siehe mcrypt_list_algorithms() für weitere Informationen.
`mcrypt.modes_dir` string
  Das Verzeichnis, das die Modi enthält. Standardmäßig ist dies der beim Kompilieren von libmcrypt angegebene Ordner, typischerweise. /usr/local/lib/libmcrypt Siehe mcrypt_list_modes() für weitere Informationen.

## Ressource-Typen

mcrypt_module_open() gibt einen Verschlüsselungs-Deskriptor zurück.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

Mcrypt kann in vier Blockchiffriermodi arbeiten: `CBC`, `OFB`, `CFB` und `ECB`. Wenn es gegen libmcrypt-2.4.x oder höher gelinkt ist, können die Funktionen auch in den Blockchiffriermodi `nOFB` und `STREAM` arbeiten. Unten finden Sie eine Liste mit allen unterstützten Verschlüsselungsmodi zusammen mit den für die Verschlüsselung definierten Konstanten. Für eine vollständige Referenz und Diskussionen siehe Applied Cryptography by Schneier (ISBN 0-471-11709-9).

- `MCRYPT_MODE_ECB` (`electronic codebook`) ist ein Blockchiffremodus, der grundsätzlich für die meisten Zwecke ungeeignet ist. Die Verwendung dieses Modus wird nicht empfohlen.
- `MCRYPT_MODE_CBC` (`cipher block chaining`) ist ein Blockchiffremodus, der erheblich sicherer ist als der `ECB`-Modus.
- `MCRYPT_MODE_CFB` (`cipher feedback, im 8bit-Modus`) ist ein Stromchiffremodus. Es wird empfohlen, `NCFB` statt des `CFB`-Modus zu verwenden.
- `MCRYPT_MODE_OFB` (`output feedback, im 8bit-Modus`) ist ein mit `CFB` vergleichbarer Stromchiffremodus, kann aber in Anwendungen verwendet werden, in denen Fehlerfortplanzung nicht toleriert werden kann. Es wird empfohlen den `NOFB`-Modus statt des `OFB`-Modus zu verwenden.
- `MCRYPT_MODE_NOFB` (`output feedback, im n-bit-Modus`) ist mit dem `OFB`-Modus vergleichbar, arbeitet aber auf der vollständigen Blockgröße des Algorithmus.
- `MCRYPT_MODE_STREAM` ist ein extra Modus zum Einbinden einiger Stream-Algorithmen wie `"WAKE"` oder `"RC4"`.

Mcrypt unterstützt einige weitere Betriebmodi, für die es keine vordefinierten Konstanten gibt. Sie können genutzt werden, indem eine Zeichenkette anstelle der fehlenden Konstante übergebene wird.

- `"ctr"` (`counter-Modus`) ist ein Stromchiffremodus.
- `"ncfb"` (`cipher feedback, im n-bit-Modus`) ist vergleichbar mit dem `CFB`-Modus, arbeitet aber auf der vollständigen Blockgröße des Algorithmus.

Weitere Modus- und Zufallsgeräte-Konstanten:

`MCRYPT_ENCRYPT` (int)
`MCRYPT_DECRYPT` (int)
`MCRYPT_DEV_RANDOM` (int)
`MCRYPT_DEV_URANDOM` (int)
`MCRYPT_RAND` (int)

# Mcrypt Chiffren

Hier ist eine Liste der Chiffren, die aktuell von der mcrypt-Erweiterung unterstützt werden. Für eine komplette Liste der unterstützten Chiffren siehe die Definitionen am Ende der Datei mcrypt.h. Im allgemeinen gilt für die mcrypt-2.2.x API, dass auf die Chiffre mit MCRYPT_[chiffrename] zugegriffen werden kann. Diese Konstanten funktionieren ebenfalls mit der libmcrypt-2.4.x und libmcrypt-2.5.x API, jedoch ist es möglich, den Namen der Chiffre als String mit einem Aufruf der Funktion mcrypt_module_open() anzugeben.

- MCRYPT_3DES
- MCRYPT_ARCFOUR_IV (nur libmcrypt > 2.4.x)
- MCRYPT_ARCFOUR (nur libmcrypt > 2.4.x)
- MCRYPT_BLOWFISH
- MCRYPT_CAST_128
- MCRYPT_CAST_256
- MCRYPT_CRYPT
- MCRYPT_DES
- MCRYPT_DES_COMPAT (nur libmcrypt 2.2.x)
- MCRYPT_ENIGMA (nur libmcrypt > 2.4.x, Aliase für MCRYPT_CRYPT)
- MCRYPT_GOST
- MCRYPT_IDEA (nicht frei)
- MCRYPT_LOKI97 (nur libmcrypt > 2.4.x)
- MCRYPT_MARS (nur libmcrypt > 2.4.x, nicht frei)
- MCRYPT_PANAMA (nur libmcrypt > 2.4.x)
- MCRYPT_RIJNDAEL_128 (nur libmcrypt > 2.4.x)
- MCRYPT_RIJNDAEL_192 (nur libmcrypt > 2.4.x)
- MCRYPT_RIJNDAEL_256 (nur libmcrypt > 2.4.x)
- MCRYPT_RC2
- MCRYPT_RC4 (nur libmcrypt 2.2.x)
- MCRYPT_RC6 (nur libmcrypt > 2.4.x)
- MCRYPT_RC6_128 (nur libmcrypt 2.2.x)
- MCRYPT_RC6_192 (nur libmcrypt 2.2.x)
- MCRYPT_RC6_256 (nur libmcrypt 2.2.x)
- MCRYPT_SAFER64
- MCRYPT_SAFER128
- MCRYPT_SAFERPLUS (nur libmcrypt > 2.4.x)
- MCRYPT_SERPENT(nur libmcrypt > 2.4.x)
- MCRYPT_SERPENT_128 (nur libmcrypt 2.2.x)
- MCRYPT_SERPENT_192 (nur libmcrypt 2.2.x)
- MCRYPT_SERPENT_256 (nur libmcrypt 2.2.x)
- MCRYPT_SKIPJACK (nur libmcrypt > 2.4.x)
- MCRYPT_TEAN (nur libmcrypt 2.2.x)
- MCRYPT_THREEWAY
- MCRYPT_TRIPLEDES (nur libmcrypt > 2.4.x)
- MCRYPT_TWOFISH (für ältere mcrypt 2.x Versionen, oder mcrypt > 2.4.x )
- MCRYPT_TWOFISH128 (TWOFISHxxx sind verfügbar in neueren 2.x Versionen, aber nicht in den 2.4.x Versionen)
- MCRYPT_TWOFISH192
- MCRYPT_TWOFISH256
- MCRYPT_WAKE (nur libmcrypt > 2.4.x)
- MCRYPT_XTEA (nur libmcrypt > 2.4.x)

Sie müssen (im `CFB` und `OFB` Modus) oder können (im `CBC` Modus) die jeweiligen Chiffrierfunktionen mit einem Initialierungs-Vektor versorgen (initialization vector, IV). Der IV muss einmalig und sowohl für die Verschlüsselung als auch für die Entschlüsselung gleich sein. Bei Daten, die verschlüsselt gespeichert werden, können Sie die Ausgabe einer Funktion des Indexes verwenden, unter welcher die Daten gespeichert werden (z. B. der MD5-Hash des Dateinamens). Alternativ können die den IV zusammen mit den verschlüsselten Daten übermitteln (siehe Kapitel 9.3 aus Applied Cryptography by Schneier (ISBN 0-471-11709-9) für eine Diskussion zu diesem Thema).

# Mcrypt Funktionen

# mcrypt_create_iv

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_create_iv — Creates an initialization vector (IV) from a random source

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und in PHP 7.2.0 REMOVED (entfernt).

Alternativ können die folgenden Funktionen verwendet werden:

- random_bytes()

### Beschreibung

function mcrypt_create_iv(int `$size`, int `$source` = MCRYPT_DEV_URANDOM): string

Creates an initialization vector (IV) from a random source.

The IV is only meant to give an alternative seed to the encryption routines. This IV does not need to be secret at all, though it can be desirable. You even can send it along with your ciphertext without losing security.

### Parameter-Liste

`size`
  The size of the IV.
`source`
  The source of the IV. The source can be `MCRYPT_RAND` (system random number generator), `MCRYPT_DEV_RANDOM` (read data from /dev/random) and `MCRYPT_DEV_URANDOM` (read data from /dev/urandom). Prior to 5.3.0, `MCRYPT_RAND` was the only one supported on Windows. Note that the default value of this parameter was `MCRYPT_DEV_RANDOM` prior to PHP 5.6.0.

  > Hinweis: Note that `MCRYPT_DEV_RANDOM` may block until more entropy is available.

### Rückgabewerte

Returns the initialization vector, or `false` on error.

### Beispiele

Beispiel #1 mcrypt_create_iv() Example

    <?php
        $size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
        $iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);
    ?>

### Siehe auch

- » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
- » http://www.quadibloc.com/crypto/co0409.htm
- Chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9)
- random_bytes() - Get cryptographically secure random bytes

# mcrypt_decrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_decrypt — Decrypts crypttext with given parameters

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_decrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

Decrypts the `data` and returns the unencrypted data.

### Parameter-Liste

`cipher`

  Eine der Konstanten von `MCRYPT_ciphername` oder der Name eines Algorithmus als Zeichenkette.

`key`
  The key with which the data was encrypted. If the provided key size is not supported by the cipher, the function will emit a warning and return `false`
`data`
  The data that will be decrypted with the given `cipher` and `mode`. If the size of the data is not n * blocksize, the data will be padded with '`\0`'.
`mode`

  Eine der `MCRYPT_MODE_modename`-Konstanten oder eine der folgenden Zeichenketten: "ecb", "cbc", "cfb", "ofb", "nofb" oder "stream".

`iv`

  Wird für die Initialisierung in den Modi CBC, CFB oder OFB und von einigen Algorithmen im STREAM-Modus verwendet. Wird die Länge des angegebenen IV vom Betriebsmodus nicht unterstützt, oder wurde kein IV angegeben aber der Betriebsmodus benötigt einen, so wird diese Funktion eine Warnung ausgeben und `false` zurückgeben.

### Rückgabewerte

Returns the decrypted data as a string Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- mcrypt_encrypt() - Encrypts plaintext with given parameters

# mcrypt_enc_get_algorithms_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_get_algorithms_name(resource `$td`): string

This function returns the name of the algorithm.

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns the name of the opened algorithm as a string.

### Beispiele

Beispiel #1 mcrypt_enc_get_algorithms_name() example

    <?php
    $td = mcrypt_module_open(MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_algorithms_name($td). "\n";

    $td = mcrypt_module_open('cast-256', '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_algorithms_name($td). "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CAST-256
    CAST-256

# mcrypt_enc_get_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_get_block_size(resource `$td`): int

Gets the blocksize of the opened algorithm.

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns the block size of the specified algorithm in bytes.

# mcrypt_enc_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_iv_size — Returns the size of the IV of the opened algorithm

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_get_iv_size(resource `$td`): int

This function returns the size of the IV of the algorithm specified by the encryption descriptor in bytes. An IV is used in cbc, cfb and ofb modes, and in some algorithms in stream mode.

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns the size of the IV, or 0 if the IV is ignored by the algorithm.

# mcrypt_enc_get_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_key_size — Returns the maximum supported keysize of the opened mode

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_get_key_size(resource `$td`): int

Gets the maximum supported key size of the algorithm in bytes.

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns the maximum supported key size of the algorithm in bytes.

# mcrypt_enc_get_modes_name

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_modes_name — Returns the name of the opened mode

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_get_modes_name(resource `$td`): string

This function returns the name of the mode.

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns the name as a string.

### Beispiele

Beispiel #1 mcrypt_enc_get_modes_name() example

    <?php
    $td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
    echo mcrypt_enc_get_modes_name($td). "\n";

    $td = mcrypt_module_open ('cast-256', '', 'ecb', '');
    echo mcrypt_enc_get_modes_name($td). "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CFB
    ECB

# mcrypt_enc_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_get_supported_key_sizes(resource `$td`): array

Gets the supported key sizes of the opened algorithm.

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns an array with the key sizes supported by the algorithm specified by the encryption descriptor. If it returns an empty array then all key sizes between 1 and mcrypt_enc_get_key_size() are supported by the algorithm.

### Beispiele

Beispiel #1 mcrypt_enc_get_supported_key_sizes() example

    <?php
        $td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
        var_dump(mcrypt_enc_get_supported_key_sizes($td));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      int(16)
      [1]=>
      int(24)
      [2]=>
      int(32)
    }

# mcrypt_enc_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm — Checks whether the algorithm of the opened mode is a block algorithm

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_is_block_algorithm(resource `$td`): bool

Tells whether the algorithm of the opened mode is a block algorithm.

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns `true` if the algorithm is a block algorithm or `false` if it is a stream one.

# mcrypt_enc_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_algorithm_mode — Checks whether the encryption of the opened mode works on blocks

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_is_block_algorithm_mode(resource `$td`): bool

Tells whether the algorithm of the opened mode works on blocks (e.g. `false` for stream, and `true` for cbc, cfb, ofb)..

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns `true` if the mode is for use with block algorithms, otherwise it returns `false`.

# mcrypt_enc_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_is_block_mode — Checks whether the opened mode outputs blocks

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_is_block_mode(resource `$td`): bool

Tells whether the opened mode outputs blocks (e.g. `true` for cbc and ecb, and `false` for cfb and stream).

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns `true` if the mode outputs blocks of bytes, or `false` if it outputs just bytes.

# mcrypt_enc_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_enc_self_test — Runs a self test on the opened module

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_enc_self_test(resource `$td`): int

This function runs the self test on the algorithm specified by the descriptor `td`.

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Returns `0` on success and a negative Integer on failure.

# mcrypt_encrypt

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_encrypt — Encrypts plaintext with given parameters

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_encrypt(
string `$cipher`,
string `$key`,
string `$data`,
string `$mode`,
string `$iv` = ?
): string|false

Encrypts the data and returns it.

### Parameter-Liste

`cipher`

  Eine der Konstanten von `MCRYPT_ciphername` oder der Name eines Algorithmus als Zeichenkette.

`key`
  The key with which the data will be encrypted. If the provided key size is not supported by the cipher, the function will emit a warning and return `false`
`data`
  The data that will be encrypted with the given `cipher` and `mode`. If the size of the data is not n * blocksize, the data will be padded with '`\0`'. The returned crypttext can be larger than the size of the data that was given by `data`.
`mode`

  Eine der `MCRYPT_MODE_modename`-Konstanten oder eine der folgenden Zeichenketten: "ecb", "cbc", "cfb", "ofb", "nofb" oder "stream".

`iv`

  Wird für die Initialisierung in den Modi CBC, CFB oder OFB und von einigen Algorithmen im STREAM-Modus verwendet. Wird die Länge des angegebenen IV vom Betriebsmodus nicht unterstützt, oder wurde kein IV angegeben aber der Betriebsmodus benötigt einen, so wird diese Funktion eine Warnung ausgeben und `false` zurückgeben.

### Rückgabewerte

Returns the encrypted data as a string Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 mcrypt_encrypt() Example

    <?php
        # --- ENCRYPTION ---

        # the key should be random binary, use scrypt, bcrypt or PBKDF2 to
        # convert a string into a key
        # key is specified using hexadecimal
        $key = pack('H*', "bcb04b7e103a0cd8b54763051cef08bc55abe029fdebae5e1d417e2ffb2a00a3");

        # show key size use either 16, 24 or 32 byte keys for AES-128, 192
        # and 256 respectively
        $key_size =  strlen($key);
        echo "Key size: " . $key_size . "\n";

        $plaintext = "This string was AES-256 / CBC / ZeroBytePadding encrypted.";

        # create a random IV to use with CBC encoding
        $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
        $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

        # creates a cipher text compatible with AES (Rijndael block size = 128)
        # to keep the text confidential
        # only suitable for encoded input that never ends with value 00h
        # (because of default zero padding)
        $ciphertext = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key,
                                     $plaintext, MCRYPT_MODE_CBC, $iv);

        # prepend the IV for it to be available for decryption
        $ciphertext = $iv . $ciphertext;

        # encode the resulting cipher text so it can be represented by a string
        $ciphertext_base64 = base64_encode($ciphertext);

        echo  $ciphertext_base64 . "\n";

        # === WARNING ===

        # Resulting cipher text has no integrity or authenticity added
        # and is not protected against padding oracle attacks.

        # --- DECRYPTION ---

        $ciphertext_dec = base64_decode($ciphertext_base64);

        # retrieves the IV, iv_size should be created using mcrypt_get_iv_size()
        $iv_dec = substr($ciphertext_dec, 0, $iv_size);

        # retrieves the cipher text (everything except the $iv_size in the front)
        $ciphertext_dec = substr($ciphertext_dec, $iv_size);

        # may remove 00h valued characters from end of plain text
        $plaintext_dec = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key,
                                        $ciphertext_dec, MCRYPT_MODE_CBC, $iv_dec);

        echo  $plaintext_dec . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Key size: 32
    ENJW8mS2KaJoNB5E5CoSAAu0xARgsR1bdzFWpEn+poYw45q+73az5kYi4j+0haevext1dGrcW8Qi59txfCBV8BBj3bzRP3dFCp3CPQSJ8eU=
    This string was AES-256 / CBC / ZeroBytePadding encrypted.

### Siehe auch

- mcrypt_decrypt() - Decrypts crypttext with given parameters
- mcrypt_module_open() - Opens the module of the algorithm and the mode to be used

# mcrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic — This function encrypts data

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_generic(resource `$td`, string `$data`): string

This function encrypts data. The data is padded with "`\0`" to make sure the length of the data is n * blocksize. This function returns the encrypted data. Note that the length of the returned string can in fact be longer than the input, due to the padding of the data.

If you want to store the encrypted data in a database make sure to store the entire string as returned by mcrypt_generic, or the string will not entirely decrypt properly. If your original string is 10 characters long and the block size is 8 (use mcrypt_enc_get_block_size() to determine the blocksize), you would need at least 16 characters in your database field. Note the string returned by mdecrypt_generic() will be 16 characters as well...use rtrim($str, "\0") to remove the padding.

If you are for example storing the data in a MySQL database remember that varchar fields automatically have trailing spaces removed during insertion. As encrypted data can end in a space (ASCII 32), the data will be damaged by this removal. Store data in a tinyblob/tinytext (or larger) field instead.

### Parameter-Liste

`td`
  The encryption descriptor. The encryption handle should always be initialized with mcrypt_generic_init() with a key and an IV before calling this function. Where the encryption is done, you should free the encryption buffers by calling mcrypt_generic_deinit(). See mcrypt_module_open() for an example.
`data`
  The data to encrypt.

### Rückgabewerte

Returns the encrypted data.

### Siehe auch

- mdecrypt_generic() - Decrypts data
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
- mcrypt_generic_deinit() - This function deinitializes an encryption module

# mcrypt_generic_deinit

(PHP 4 >= 4.0.7, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_deinit — This function deinitializes an encryption module

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_generic_deinit(resource `$td`): bool

This function terminates encryption specified by the encryption descriptor (`td`). It clears all buffers, but does not close the module. You need to call mcrypt_module_close() yourself. (But PHP does this for you at the end of the script.)

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- mcrypt_module_open() - Opens the module of the algorithm and the mode to be used
- mcrypt_generic_init() - This function initializes all buffers needed for encryption

# mcrypt_generic_init

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_generic_init — This function initializes all buffers needed for encryption

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_generic_init(resource `$td`, string `$key`, string `$iv`): int

You need to call this function before every call to mcrypt_generic() or mdecrypt_generic().

### Parameter-Liste

`td`
  The encryption descriptor.
`key`
  The maximum length of the key should be the one obtained by calling mcrypt_enc_get_key_size() and every value smaller than this is legal.
`iv`
  The IV should normally have the size of the algorithms block size, but you must obtain the size by calling mcrypt_enc_get_iv_size(). IV is ignored in ECB. IV MUST exist in CFB, CBC, STREAM, nOFB and OFB modes. It needs to be random and unique (but not secret). The same IV must be used for encryption/decryption. If you do not want to use it you should set it to zeros, but this is not recommended.

### Rückgabewerte

The function returns a negative value on error: -3 when the key length was incorrect, -4 when there was a memory allocation problem and any other return value is an unknown error. If an error occurs a warning will be displayed accordingly. `false` is returned if incorrect parameters were passed.

### Siehe auch

- mcrypt_module_open() - Opens the module of the algorithm and the mode to be used

# mcrypt_get_block_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_block_size — Gets the block size of the specified cipher

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_get_block_size(int `$cipher`): int|false
function mcrypt_get_block_size(string `$cipher`, string `$mode`): int|false

The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or 2.5.x.

mcrypt_get_block_size() is used to get the size of a block of the specified `cipher` (in combination with an encryption mode).

It is more useful to use the mcrypt_enc_get_block_size() function as this uses the resource returned by mcrypt_module_open().

### Parameter-Liste

`cipher`

  Eine der Konstanten von `MCRYPT_ciphername` oder der Name eines Algorithmus als Zeichenkette.

`mode`

  Eine der `MCRYPT_MODE_modename`-Konstanten oder eine der folgenden Zeichenketten: "ecb", "cbc", "cfb", "ofb", "nofb" oder "stream".

### Rückgabewerte

Returns the algorithm block size in bytes Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 mcrypt_get_block_size() example

This example shows how to use this function when linked against libmcrypt 2.4.x and 2.5.x.

    <?php

    echo mcrypt_get_block_size('tripledes', 'ecb'); // 8

    ?>

### Siehe auch

- mcrypt_get_key_size() - Gets the key size of the specified cipher
- mcrypt_enc_get_block_size() - Returns the blocksize of the opened algorithm
- mcrypt_encrypt() - Encrypts plaintext with given parameters

# mcrypt_get_cipher_name

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_cipher_name — Gets the name of the specified cipher

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_get_cipher_name(int `$cipher`): string
function mcrypt_get_cipher_name(string `$cipher`): string

mcrypt_get_cipher_name() is used to get the name of the specified cipher.

mcrypt_get_cipher_name() takes the cipher number as an argument (libmcrypt 2.2.x) or takes the cipher name as an argument (libmcrypt 2.4.x or higher) and returns the name of the cipher or `false`, if the cipher does not exist.

### Parameter-Liste

`cipher`

  Eine der Konstanten von `MCRYPT_ciphername` oder der Name eines Algorithmus als Zeichenkette.

### Rückgabewerte

This function returns the name of the cipher or `false` if the cipher does not exist.

### Beispiele

Beispiel #1 mcrypt_get_cipher_name() Example

    <?php
       $cipher = MCRYPT_TripleDES;

       echo mcrypt_get_cipher_name($cipher);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3DES

# mcrypt_get_iv_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_iv_size — Returns the size of the IV belonging to a specific cipher/mode combination

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_get_iv_size(string `$cipher`, string `$mode`): int

Gets the size of the IV belonging to a specific `cipher`/`mode` combination.

It is more useful to use the mcrypt_enc_get_iv_size() function as this uses the resource returned by mcrypt_module_open().

### Parameter-Liste

`cipher`

  Eine der Konstanten von `MCRYPT_ciphername` oder der Name eines Algorithmus als Zeichenkette.

`mode`

  Eine der `MCRYPT_MODE_modename`-Konstanten oder eine der folgenden Zeichenketten: "ecb", "cbc", "cfb", "ofb", "nofb" oder "stream".

  The IV is ignored in ECB mode as this mode does not require it. You will need to have the same IV (think: starting point) both at encryption and decryption stages, otherwise your encryption will fail.

### Rückgabewerte

Returns the size of the Initialization Vector (IV) in bytes. On error the function returns `false`. If the IV is ignored in the specified cipher/mode combination zero is returned.

### Beispiele

Beispiel #1 mcrypt_get_iv_size() Example

    <?php
        echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";

        echo mcrypt_get_iv_size('des', 'ecb') . "\n";
    ?>

### Siehe auch

- mcrypt_get_block_size() - Gets the block size of the specified cipher
- mcrypt_enc_get_iv_size() - Returns the size of the IV of the opened algorithm
- mcrypt_create_iv() - Creates an initialization vector (IV) from a random source

# mcrypt_get_key_size

(PHP 4, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_get_key_size — Gets the key size of the specified cipher

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_get_key_size(int `$cipher`): int|false
function mcrypt_get_key_size(string `$cipher`, string `$mode`): int|false

The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or 2.5.x.

mcrypt_get_key_size() is used to get the size of a key of the specified `cipher` (in combination with an encryption mode).

It is more useful to use the mcrypt_enc_get_key_size() function as this uses the resource returned by mcrypt_module_open().

### Parameter-Liste

`cipher`

  Eine der Konstanten von `MCRYPT_ciphername` oder der Name eines Algorithmus als Zeichenkette.

`mode`

  Eine der `MCRYPT_MODE_modename`-Konstanten oder eine der folgenden Zeichenketten: "ecb", "cbc", "cfb", "ofb", "nofb" oder "stream".

### Rückgabewerte

Returns the maximum supported key size of the algorithm in bytes Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 mcrypt_get_key_size() Example

    <?php
        echo mcrypt_get_key_size('tripledes', 'ecb');
    ?>

The example above shows how to use this function when linked against libmcrypt 2.4.x or 2.5.x.

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    24

### Siehe auch

- mcrypt_get_block_size() - Gets the block size of the specified cipher
- mcrypt_enc_get_key_size() - Returns the maximum supported keysize of the opened mode
- mcrypt_encrypt() - Encrypts plaintext with given parameters

# mcrypt_list_algorithms

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_algorithms — Gets an array of all supported ciphers

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_list_algorithms(string `$lib_dir` = ini_get("mcrypt.algorithms_dir")): array

Gets the list of all supported algorithms in the `lib_dir` parameter.

### Parameter-Liste

`lib_dir`
  Specifies the directory where all algorithms are located. If not specified, the value of the `mcrypt.algorithms_dir` php.ini directive is used.

### Rückgabewerte

Returns an array with all the supported algorithms.

### Beispiele

Beispiel #1 mcrypt_list_algorithms() Example

    <?php
    $algorithms = mcrypt_list_algorithms();
    print_r($algorithms);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => cast-128
        [1] => gost
        [2] => rijndael-128
        [3] => twofish
        [4] => arcfour
        [5] => cast-256
        [6] => loki97
        [7] => rijndael-192
        [8] => saferplus
        [9] => wake
        [10] => blowfish-compat
        [11] => des
        [12] => rijndael-256
        [13] => serpent
        [14] => xtea
        [15] => blowfish
        [16] => enigma
        [17] => rc2
        [18] => tripledes
    )

# mcrypt_list_modes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_list_modes — Gets an array of all supported modes

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_list_modes(string `$lib_dir` = ini_get("mcrypt.modes_dir")): array

Gets the list of all supported modes in the `lib_dir` parameter.

### Parameter-Liste

`lib_dir`
  Specifies the directory where all modes are located. If not specified, the value of the `mcrypt.modes_dir` php.ini directive is used.

### Rückgabewerte

Returns an array with all the supported modes.

### Beispiele

Beispiel #1 mcrypt_list_modes() Example

    <?php
        $modes = mcrypt_list_modes();

        foreach ($modes as $mode) {
            echo "$mode <br />\n";
        }
    ?>

The example above will produce a list with all supported algorithms in the default mode directory. If it is not set with the `mcrypt.modes_dir` php.ini directive, the default directory of mcrypt is used (which is /usr/local/lib/libmcrypt).

# mcrypt_module_close

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_close — Closes the mcrypt module

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_module_close(resource `$td`): bool

Closes the specified encryption handle.

### Parameter-Liste

`td`
  The encryption descriptor.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- mcrypt_module_open() - Opens the module of the algorithm and the mode to be used

# mcrypt_module_get_algo_block_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_block_size — Returns the blocksize of the specified algorithm

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_module_get_algo_block_size(string `$algorithm`, string `$lib_dir` = ?): int

Gets the blocksize of the specified algorithm.

### Parameter-Liste

`algorithm`
  The algorithm name.
`lib_dir`
  This optional parameter can contain the location where the mode module is on the system.

### Rückgabewerte

Returns the block size of the algorithm specified in bytes.

# mcrypt_module_get_algo_key_size

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_algo_key_size — Returns the maximum supported keysize of the opened mode

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_module_get_algo_key_size(string `$algorithm`, string `$lib_dir` = ?): int

Gets the maximum supported keysize of the opened mode.

### Parameter-Liste

`algorithm`
  The algorithm name.
`lib_dir`
  This optional parameter can contain the location where the mode module is on the system.

### Rückgabewerte

This function returns the maximum supported key size of the algorithm specified in bytes.

# mcrypt_module_get_supported_key_sizes

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_module_get_supported_key_sizes(string `$algorithm`, string `$lib_dir` = ?): array

Returns an array with the key sizes supported by the specified algorithm. If it returns an empty array then all key sizes between 1 and mcrypt_module_get_algo_key_size() are supported by the algorithm.

### Parameter-Liste

`algorithm`
  The algorithm to be used.
`lib_dir`
  The optional `lib_dir` parameter can contain the location where the algorithm module is on the system.

### Rückgabewerte

Returns an array with the key sizes supported by the specified algorithm. If it returns an empty array then all key sizes between 1 and mcrypt_module_get_algo_key_size() are supported by the algorithm.

### Siehe auch

- mcrypt_enc_get_supported_key_sizes() - Returns an array with the supported keysizes of the opened algorithm

# mcrypt_module_is_block_algorithm

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm — This function checks whether the specified algorithm is a block algorithm

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_module_is_block_algorithm(string `$algorithm`, string `$lib_dir` = ?): bool

This function returns `true` if the specified algorithm is a block algorithm, or `false` if it is a stream one.

### Parameter-Liste

`algorithm`
  The algorithm to check.
`lib_dir`
  The optional `lib_dir` parameter can contain the location where the algorithm module is on the system.

### Rückgabewerte

This function returns `true` if the specified algorithm is a block algorithm, or `false` if it is a stream one.

# mcrypt_module_is_block_algorithm_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_algorithm_mode — Returns if the specified module is a block algorithm or not

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_module_is_block_algorithm_mode(string `$mode`, string `$lib_dir` = ?): bool

This function returns `true` if the mode is for use with block algorithms, otherwise it returns `false`. (e.g. `false` for stream, and `true` for cbc, cfb, ofb).

### Parameter-Liste

`mode`
  The mode to check.
`lib_dir`
  The optional `lib_dir` parameter can contain the location where the algorithm module is on the system.

### Rückgabewerte

This function returns `true` if the mode is for use with block algorithms, otherwise it returns `false`. (e.g. `false` for stream, and `true` for cbc, cfb, ofb).

# mcrypt_module_is_block_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_is_block_mode — Returns if the specified mode outputs blocks or not

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_module_is_block_mode(string `$mode`, string `$lib_dir` = ?): bool

This function returns `true` if the mode outputs blocks of bytes or `false` if it outputs just bytes. (e.g. `true` for cbc and ecb, and `false` for cfb and stream).

### Parameter-Liste

`mode`

  Eine der `MCRYPT_MODE_modename`-Konstanten oder eine der folgenden Zeichenketten: "ecb", "cbc", "cfb", "ofb", "nofb" oder "stream".

`lib_dir`
  The optional `lib_dir` parameter can contain the location where the algorithm module is on the system.

### Rückgabewerte

This function returns `true` if the mode outputs blocks of bytes or `false` if it outputs just bytes. (e.g. `true` for cbc and ecb, and `false` for cfb and stream).

# mcrypt_module_open

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_open — Opens the module of the algorithm and the mode to be used

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_module_open(
string `$algorithm`,
string `$algorithm_directory`,
string `$mode`,
string `$mode_directory`
): resource

This function opens the module of the algorithm and the mode to be used. The name of the algorithm is specified in algorithm, e.g. `"twofish"` or is one of the `MCRYPT_ciphername` constants. The module is closed by calling mcrypt_module_close().

### Parameter-Liste

`algorithm`

  Eine der Konstanten von `MCRYPT_ciphername` oder der Name eines Algorithmus als Zeichenkette.

`algorithm_directory`
  The `algorithm_directory` parameter is used to locate the encryption module. When you supply a directory name, it is used. When you set it to an empty string (`""`), the value set by the `mcrypt.algorithms_dir` php.ini directive is used. When it is not set, the default directory that is used is the one that was compiled into libmcrypt (usually /usr/local/lib/libmcrypt).
`mode`

  Eine der `MCRYPT_MODE_modename`-Konstanten oder eine der folgenden Zeichenketten: "ecb", "cbc", "cfb", "ofb", "nofb" oder "stream".

`mode_directory`
  The `mode_directory` parameter is used to locate the encryption module. When you supply a directory name, it is used. When you set it to an empty string (`""`), the value set by the `mcrypt.modes_dir` php.ini directive is used. When it is not set, the default directory that is used is the one that was compiled-in into libmcrypt (usually /usr/local/lib/libmcrypt).

### Rückgabewerte

Normally it returns an encryption descriptor, or `false` on error.

### Beispiele

Beispiel #1 mcrypt_module_open() Examples

    <?php
        $td = mcrypt_module_open(MCRYPT_DES, '',
            MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');

        $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
    ?>

The first line in the example above will try to open the `DES` cipher from the default directory and the `ECB` mode from the directory /usr/lib/mcrypt-modes. The second example uses strings as name for the cipher and mode, this only works when the extension is linked against libmcrypt 2.4.x or 2.5.x.

Beispiel #2 Using mcrypt_module_open() in encryption

    <?php
        /* Open the cipher */
        $td = mcrypt_module_open('rijndael-256', '', 'ofb', '');

        /* Create the IV and determine the keysize length, use MCRYPT_RAND
         * on Windows instead */
        $iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
        $ks = mcrypt_enc_get_key_size($td);

        /* Create key (example only: MD5 is not a good hash algorithm for this) */
        $key = substr(hash('md5', 'very secret key'), 0, $ks);

        /* Intialize encryption */
        mcrypt_generic_init($td, $key, $iv);

        /* Encrypt data */
        $encrypted = mcrypt_generic($td, 'This is very important data');

        /* Terminate encryption handler */
        mcrypt_generic_deinit($td);

        /* Initialize encryption module for decryption */
        mcrypt_generic_init($td, $key, $iv);

        /* Decrypt encrypted string */
        $decrypted = mdecrypt_generic($td, $encrypted);

        /* Terminate decryption handle and close module */
        mcrypt_generic_deinit($td);
        mcrypt_module_close($td);

        /* Show string */
        echo trim($decrypted) . "\n";
    ?>

### Siehe auch

- mcrypt_module_close() - Closes the mcrypt module
- mcrypt_generic() - This function encrypts data
- mdecrypt_generic() - Decrypts data
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
- mcrypt_generic_deinit() - This function deinitializes an encryption module

# mcrypt_module_self_test

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mcrypt_module_self_test — This function runs a self test on the specified module

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mcrypt_module_self_test(string `$algorithm`, string `$lib_dir` = ?): bool

This function runs the self test on the algorithm specified.

### Parameter-Liste

`algorithm`

  Eine der Konstanten von `MCRYPT_ciphername` oder der Name eines Algorithmus als Zeichenkette.

`lib_dir`
  The optional `lib_dir` parameter can contain the location where the algorithm module is on the system.

### Rückgabewerte

The function returns `true` if the self test succeeds, or `false` when it fails.

### Beispiele

Beispiel #1 mcrypt_module_self_test() example

    <?php
    var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
    var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)

# mdecrypt_generic

(PHP 4 >= 4.0.2, PHP 5, PHP 7 < 7.2.0, PECL mcrypt >= 1.0.0)

mdecrypt_generic — Decrypts data

Warnung

Diese Funktion wurde in PHP 7.1.0 als DEPRECATED (veraltet) markiert und wurde in PHP 7.2.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function mdecrypt_generic(resource `$td`, string `$data`): string

This function decrypts data. Note that the length of the returned string can in fact be longer than the unencrypted string, due to the padding of the data.

### Parameter-Liste

`td`
  An encryption descriptor returned by mcrypt_module_open()
`data`
  Encrypted data.

### Rückgabewerte

Returns decrypted string.

### Beispiele

Beispiel #1 mdecrypt_generic() Example

    <?php
        /* Data */
        $key = 'this is a very long key, even too long for the cipher';
        $plain_text = 'very important data';

        /* Open module, and create IV */
        $td = mcrypt_module_open('des', '', 'ecb', '');
        $key = substr($key, 0, mcrypt_enc_get_key_size($td));
        $iv_size = mcrypt_enc_get_iv_size($td);
        $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);

        /* Initialize encryption handle */
        if (mcrypt_generic_init($td, $key, $iv) != -1) {

            /* Encrypt data */
            $c_t = mcrypt_generic($td, $plain_text);
            mcrypt_generic_deinit($td);

            /* Reinitialize buffers for decryption */
            mcrypt_generic_init($td, $key, $iv);
            $p_t = mdecrypt_generic($td, $c_t);

            /* Clean up */
            mcrypt_generic_deinit($td);
            mcrypt_module_close($td);
        }

        if (strncmp($p_t, $plain_text, strlen($plain_text)) == 0) {
            echo "ok\n";
        } else {
            echo "error\n";
        }
    ?>

The example above shows how to check if the data before the encryption is the same as the data after the decryption. It is very important to reinitialize the encryption buffer with mcrypt_generic_init() before you try to decrypt the data.

The decryption handle should always be initialized with mcrypt_generic_init() with a key and an IV before calling this function. Where the encryption is done, you should free the encryption buffers by calling mcrypt_generic_deinit(). See mcrypt_module_open() for an example.

### Siehe auch

- mcrypt_generic() - This function encrypts data
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
- mcrypt_generic_deinit() - This function deinitializes an encryption module

## Inhaltsverzeichnis

- mcrypt_create_iv — Creates an initialization vector (IV) from a random source
- mcrypt_decrypt — Decrypts crypttext with given parameters
- mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
- mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
- mcrypt_enc_get_iv_size — Returns the size of the IV of the opened algorithm
- mcrypt_enc_get_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_enc_get_modes_name — Returns the name of the opened mode
- mcrypt_enc_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_enc_is_block_algorithm — Checks whether the algorithm of the opened mode is a block algorithm
- mcrypt_enc_is_block_algorithm_mode — Checks whether the encryption of the opened mode works on blocks
- mcrypt_enc_is_block_mode — Checks whether the opened mode outputs blocks
- mcrypt_enc_self_test — Runs a self test on the opened module
- mcrypt_encrypt — Encrypts plaintext with given parameters
- mcrypt_generic — This function encrypts data
- mcrypt_generic_deinit — This function deinitializes an encryption module
- mcrypt_generic_init — This function initializes all buffers needed for encryption
- mcrypt_get_block_size — Gets the block size of the specified cipher
- mcrypt_get_cipher_name — Gets the name of the specified cipher
- mcrypt_get_iv_size — Returns the size of the IV belonging to a specific cipher/mode combination
- mcrypt_get_key_size — Gets the key size of the specified cipher
- mcrypt_list_algorithms — Gets an array of all supported ciphers
- mcrypt_list_modes — Gets an array of all supported modes
- mcrypt_module_close — Closes the mcrypt module
- mcrypt_module_get_algo_block_size — Returns the blocksize of the specified algorithm
- mcrypt_module_get_algo_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_module_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_module_is_block_algorithm — This function checks whether the specified algorithm is a block algorithm
- mcrypt_module_is_block_algorithm_mode — Returns if the specified module is a block algorithm or not
- mcrypt_module_is_block_mode — Returns if the specified mode outputs blocks or not
- mcrypt_module_open — Opens the module of the algorithm and the mode to be used
- mcrypt_module_self_test — This function runs a self test on the specified module
- mdecrypt_generic — Decrypts data

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Mcrypt Chiffren
- Mcrypt Funktionen
  - mcrypt_create_iv — Creates an initialization vector (IV) from a random source
  - mcrypt_decrypt — Decrypts crypttext with given parameters
  - mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
  - mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
  - mcrypt_enc_get_iv_size — Returns the size of the IV of the opened algorithm
  - mcrypt_enc_get_key_size — Returns the maximum supported keysize of the opened mode
  - mcrypt_enc_get_modes_name — Returns the name of the opened mode
  - mcrypt_enc_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
  - mcrypt_enc_is_block_algorithm — Checks whether the algorithm of the opened mode is a block algorithm
  - mcrypt_enc_is_block_algorithm_mode — Checks whether the encryption of the opened mode works on blocks
  - mcrypt_enc_is_block_mode — Checks whether the opened mode outputs blocks
  - mcrypt_enc_self_test — Runs a self test on the opened module
  - mcrypt_encrypt — Encrypts plaintext with given parameters
  - mcrypt_generic — This function encrypts data
  - mcrypt_generic_deinit — This function deinitializes an encryption module
  - mcrypt_generic_init — This function initializes all buffers needed for encryption
  - mcrypt_get_block_size — Gets the block size of the specified cipher
  - mcrypt_get_cipher_name — Gets the name of the specified cipher
  - mcrypt_get_iv_size — Returns the size of the IV belonging to a specific cipher/mode combination
  - mcrypt_get_key_size — Gets the key size of the specified cipher
  - mcrypt_list_algorithms — Gets an array of all supported ciphers
  - mcrypt_list_modes — Gets an array of all supported modes
  - mcrypt_module_close — Closes the mcrypt module
  - mcrypt_module_get_algo_block_size — Returns the blocksize of the specified algorithm
  - mcrypt_module_get_algo_key_size — Returns the maximum supported keysize of the opened mode
  - mcrypt_module_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
  - mcrypt_module_is_block_algorithm — This function checks whether the specified algorithm is a block algorithm
  - mcrypt_module_is_block_algorithm_mode — Returns if the specified module is a block algorithm or not
  - mcrypt_module_is_block_mode — Returns if the specified mode outputs blocks or not
  - mcrypt_module_open — Opens the module of the algorithm and the mode to be used
  - mcrypt_module_self_test — This function runs a self test on the specified module
  - mdecrypt_generic — Decrypts data

# Mhash

# Einführung

These functions are intended to work with » mhash. Mhash can be used to create checksums, message digests, message authentication codes, and more.

This is an interface to the mhash library. Mhash supports a wide variety of hash algorithms such as MD5, SHA1, GOST, and many others. For a complete list of supported hashes, refer to the constants page. The general rule is that you can access the hash algorithm from PHP with `MHASH_hashname`. For example, to access TIGER you use the PHP constant `MHASH_TIGER`.

> Hinweis:

> This extension is obsoleted by Hash.

> Hinweis:

> As of PHP 7.0.0 the Mhash extension has been fully integrated into the Hash extension. Therefore, it is no longer possible to detect Mhash support with extension_loaded(); use function_exists() instead. Furthermore, Mhash is no longer reported by get_loaded_extensions() and related features.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

To use it, download the mhash distribution from » its web site and follow the included installation instructions.

## Installation

You need to compile PHP with the --with-mhash[=DIR] parameter to enable this extension. DIR is the mhash installation directory.

As of PHP 5.3.0, the mhash extension is emulated thru the Hash extension. This makes the mhash installation directory have no effect, and requires the hash extension enabled to make the mhash support available.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

Here is a list of hashes which are currently supported by mhash. If a hash is not listed here, but it is listed in the mhash documentation as supported, you can safely assume that this documentation is outdated.

`MHASH_ADLER32` (int)
`MHASH_CRC32` (int)
`MHASH_CRC32B` (int)
`MHASH_CRC32C` (int)
  Available as of PHP 7.4.0.
`MHASH_FNV132` (int)
`MHASH_FNV1A32` (int)
`MHASH_FNV164` (int)
`MHASH_FNV1A64` (int)
`MHASH_GOST` (int)
`MHASH_HAVAL128` (int)
`MHASH_HAVAL160` (int)
`MHASH_HAVAL192` (int)
`MHASH_HAVAL224` (int)
`MHASH_HAVAL256` (int)
`MHASH_JOAAT` (int)
`MHASH_MD2` (int)
`MHASH_MD4` (int)
`MHASH_MD5` (int)
`MHASH_MURMUR3A` (int)
  Available as of PHP 8.1.0.
`MHASH_MURMUR3C` (int)
  Available as of PHP 8.1.0.
`MHASH_MURMUR3F` (int)
  Available as of PHP 8.1.0.
`MHASH_RIPEMD128` (int)
`MHASH_RIPEMD160` (int)
`MHASH_RIPEMD256` (int)
`MHASH_RIPEMD320` (int)
`MHASH_SHA1` (int)
`MHASH_SHA224` (int)
`MHASH_SHA256` (int)
`MHASH_SHA384` (int)
`MHASH_SHA512` (int)
`MHASH_SNEFRU256` (int)
`MHASH_TIGER` (int)
`MHASH_TIGER128` (int)
`MHASH_TIGER160` (int)
`MHASH_WHIRLPOOL` (int)
`MHASH_XXH32` (int)
`MHASH_XXH64` (int)
`MHASH_XXH3` (int)
`MHASH_XXH128` (int)

# Beispiele

Beispiel #1 Computes the MD5 digest and hmac and print it out as hex

    <?php
    $input = "what do ya want for nothing?";
    $hash = mhash(MHASH_MD5, $input);
    echo "The hash is " . bin2hex($hash) . "<br />\n";
    $hash = mhash(MHASH_MD5, $input, "Jefe");
    echo "The hmac is " . bin2hex($hash) . "<br />\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    The hash is d03cb659cbf9192dcd066272249f8412
    The hmac is 750c783e6ab0b503eaa86e310a5db738

# Mhash Funktionen

# mhash

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash — Berechnet einen Hash

Warnung

Diese Funktion ist seit PHP 8.1.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function mhash(int `$algo`, string `$data`, ?string `$key` = null): string|false

mhash() wendet eine Hash-Funktion abhängig von `algo` auf `data` an.

### Parameter-Liste

`algo`

  Die Hashkennung. Eine der `MHASH_hashname`-Konstanten.

`data`

  Die Nutzereingabe als Zeichenkette.

`key`

  Wenn angegeben, wird die Funktion den resultierenden HMAC statt des Hashs zurückgeben. HMAC ist ein Keyed-Hashing für Nachrichtenauthentifizierung, oder anders ausgedrückt, ein Message-Digest, der vom angegeben Schlüssel abhängt. Nicht alle von MHash unterstützten Algorithmen können im HMAC-Modus verwendet werden.

### Rückgabewerte

Gibt den resultieren Hash (auch Digest genannt) oder HMAC als Zeichenkette zurück oder `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Diese Funktion ist veraltet. Stattdessen sollten die `hash_*()`-Funktionen verwendet werden.
8.0.0 | `key` ist nun nullable (akzeptiert den `null`-Wert).

# mhash_count

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_count — Liefert die höchstmögliche Hash-ID

Warnung

Diese Funktion ist seit PHP 8.1.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function mhash_count(): int

Gibt die höchste verfügbare Hash-ID zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die höchste verfügbare Hash-ID zurück. Hashes sind von 0 bis zu dieser Hash-ID nummeriert.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Diese Funktion ist veraltet. Stattdessen sollten die `hash_*()`-Funktionen verwendet werden.

### Beispiele

Beispiel #1 Alle Hashes durchlaufen

    <?php

    $nr = mhash_count();

    for ($i = 0; $i <= $nr; $i++) {
        echo sprintf("Die Blockgröße von %s ist %d\n",
            mhash_get_hash_name($i),
            mhash_get_block_size($i));
    }
    ?>

# mhash_get_block_size

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_block_size — Liefert die Blockgröße des übergebenen Hashes

Warnung

Diese Funktion ist seit PHP 8.1.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function mhash_get_block_size(int `$algo`): int|false

Gibt die Blockgröße des übergebenen `algo` zurück.

### Parameter-Liste

`algo`

  Die Hashkennung. Eine der `MHASH_hashname`-Konstanten.

### Rückgabewerte

Gibt die Größe in Bytes zurück oder `false`, wenn der `algo` nicht existiert.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Diese Funktion ist veraltet. Stattdessen sollten die `hash_*()`-Funktionen verwendet werden.

### Beispiele

Beispiel #1 mhash_get_block_size()-Beispiel

    <?php

    echo mhash_get_block_size(MHASH_MD5); // 16

    ?>

# mhash_get_hash_name

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_hash_name — Liefert den Namen eines Hashes

Warnung

Diese Funktion ist seit PHP 8.1.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function mhash_get_hash_name(int `$algo`): string|false

Gibt den Namen des angegebenen `algo` zurück.

### Parameter-Liste

`algo`

  Die Hashkennung. Eine der `MHASH_hashname`-Konstanten.

### Rückgabewerte

Gibt den Namen des Hashes zurück oder `false`, wenn der Hash nicht existiert.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Diese Funktion ist veraltet. Stattdessen sollten die `hash_*()`-Funktionen verwendet werden.

### Beispiele

Beispiel #1 mhash_get_hash_name()-Beispiel

    <?php

    echo mhash_get_hash_name(MHASH_MD5); // MD5

    ?>

# mhash_keygen_s2k

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

mhash_keygen_s2k — Generates a key

Warnung

Diese Funktion ist seit PHP 8.1.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function mhash_keygen_s2k(
int `$algo`,
string `$password`,
string `$salt`,
int `$length`
): string|false

Generates a key according to the given `algo`, using an user provided `password`.

This is the Salted S2K algorithm as specified in the OpenPGP document (» RFC 2440).

Keep in mind that user supplied passwords are not really suitable to be used as keys in cryptographic algorithms, since users normally choose keys they can write on keyboard. These passwords use only 6 to 7 bits per character (or less). It is highly recommended to use some kind of transformation (like this function) to the user supplied key.

### Parameter-Liste

`algo`

  The hash ID used to create the key. One of the `MHASH_hashname` constants.

`password`

  An user supplied password.

`salt`

  Must be different and random enough for every key you generate in order to create different keys. Because `salt` must be known when you check the keys, it is a good idea to append the key to it. Salt has a fixed length of 8 bytes and will be padded with zeros if you supply less bytes.

`length`

  The key length, in bytes.

### Rückgabewerte

Returns the generated key as a string, or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | This function has been deprecated. Use the `hash_*()` functions instead.

## Inhaltsverzeichnis

- mhash — Berechnet einen Hash
- mhash_count — Liefert die höchstmögliche Hash-ID
- mhash_get_block_size — Liefert die Blockgröße des übergebenen Hashes
- mhash_get_hash_name — Liefert den Namen eines Hashes
- mhash_keygen_s2k — Generates a key

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Vordefinierte Konstanten
- Beispiele
- Mhash Funktionen
  - mhash — Berechnet einen Hash
  - mhash_count — Liefert die höchstmögliche Hash-ID
  - mhash_get_block_size — Liefert die Blockgröße des übergebenen Hashes
  - mhash_get_hash_name — Liefert den Namen eines Hashes
  - mhash_keygen_s2k — Generates a key

# OpenSSL

# Einführung

Diese Erweiterung verbindet die Funktionen der » OpenSSL-Bibliothek für symmetrische und asymmetrische Verschlüsselung und Entschlüsselung, PBKDF2, PKCS7, PKCS12, X509 und andere Krypto-Operationen. Darüber hinaus stellt sie die Implementierung von TLS-Streams zur Verfügung.

OpenSSL bietet viele Möglichkeiten, die dieses Modul zum jetzigen Zeitpunkt nicht unterstützt. Einige dieser Möglichkeiten werden vielleicht in zukünftigen Versionen zur Verfügung stehen.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

Bevor die Openssl-Funktionen verwendet werden können, muss die » OpenSSL-Bibliothek installiert werden. PHP 7 benötigt OpenSSL >= 0.9.8, < 1.2. PHP 7.1-8.0 benötigt OpenSSL >= 1.0.1, < 3.0. PHP >= 8.1 benötigt OpenSSL >= 1.0.2, < 4.0. PHP >= 8.4 benötigt OpenSSL >= 1.1.1, < 4.0.

Warnung

Es wird dringend empfohlen, eine OpenSSL-Version zu verwenden, die gewartet wird, anderenfalls könnte der Webserver anfällig für Angriffe sein.

## Installation

Um OpenSSL mit PHP nutzen zu können, muss PHP mit der Option --with-openssl kompiliert werden.

Die OpenSSL-Bibliothek stellt einige weitere Bedingungen, um zur Laufzeit korrekt funktionieren zu können. Insbesondere benötigt OpenSSL Zugang zu einer Quelle für zufällige oder pseudo-zufällige Zahlen. Auf Unix und Unix-ähnlichen Systemen bedeutet dies, dass OpenSSL Zugang zu `/dev/urandom` oder `/dev/random` haben muss.

Die Konfigurationsoption --with-system-ciphers, die bewirkt, dass PHP statt einer voreingestellten Standardliste die Chiffreliste des Systems verwendet, steht zur Verfügung.

> Hinweis: Hinweis für Win32-Benutzer

> Diese Erweiterung benötigt DLL-Dateien. die für Windows verfügbar seien müssen. Der FAQ-Eintrag " Wie füge ich unter Windows PATH mein PHP-Verzeichnis hinzu?" gibt hierzu weitere Informationen. Obwohl ein einfaches Kopieren der DLL-Dateien vom PHP-Verzeichnis in den Windows-Systemordner auch funktioniert (weil der Systemordner immer im PATH enthalten ist), ist dieses Vorgehen nicht empfehlenswert. Diese Erweiterung benötigt die folgenden Dateien im PATH: libeay32.dll oder, von OpenSLL 1.1 an, libcrypto-*.dll

> Wenn Sie vorhaben, Funktionen zur Schlüsselerzeugung und zum Signieren von Zertifikaten zu verwenden, müssen Sie eine gültige Konfigurationsdatei für OpenSSL, openssl.cnf, installieren. Wir fügen der Win32-Binärdistribution eine Beispielkonfigurationsdatei bei, die Sie im Verzeichnis extras/ssl finden.

> PHP verwendet folgende Logik, um die openssl.cnf zu finden:

> - Die Umgebungsvariable `OPENSSL_CONF` wird, falls gesetzt, als Pfad zur Konfigurationsdatei verwendet (den Dateinamen mit eingeschlossen).
> - Die Umgebungsvariable `SSLEAY_CONF` wird, falls gesetzt, als Pfad zur Konfigurationsdatei verwendet (den Dateinamen mit eingeschlossen).
> - PHP sucht die Datei openssl.cnf an dem Ort, der bei der Kompilierung der OpenSSL-DLL als Speicherort für Zertifikate angegeben wurde. Üblicherweise ist der Standard-Dateiname C:\Program Files\Common Files\SSL\openssl.cnf (x64) oder C:\Program Files (x86)\Common Files\SSL\openssl.cnf (x86) oder, vor PHP 7.4.0, C:\usr\local\ssl\openssl.cnf.
> Bei der Installation müssen Sie entscheiden, ob Sie die Konfigurationsdatei in den Standardpfad installieren oder ob Sie sie an einem anderen Ort installieren und Umgebungsvariablen verwenden (möglicherweise auf Basis einzelner virtueller Hosts), um die Konfigurationsdatei zu finden. Bei Funktionen, die diese Konfigurationsdatei benötigen, ist es möglich, durch die Angabe des Parameters `options` den Standardpfad zu dieser Datei in einem Skript zu überschreiben.
> Achtung

> Es ist sicherzustellen, dass es nicht-privilegierten Nutzern nicht erlaubt ist openssl.cnf zu ändern.

> Seit OpenSSL 3.0.0, das unter Windows ab PHP 8.2.0 standardmäßig verwendet wird, gelten mehrere Algorithmen als veraltet. Diese werden in der Regel nicht mehr verwendet, werden von der Kryptographie-Community als unsicher eingestuft oder ähnliches. Diese Algorithmen sind weiterhin über den Legacy-Provider (extras/ssl/legacy.dll) verfügbar, dessen Verwendung im Abschnitt » Provider-Konfiguration des OpenSSL-Handbuchs beschrieben wird.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Die --with-openssl akzeptiert kein Verzeichnis-Argument mehr. Stattdessen muss die pkg-config-Variable PKG_CONFIG_PATH auf das OpenSSL-Verzeichnis gesetzt werden, oder es müssen die Variablen OPENSSL_LIBS und OPENSSL_CFLAGS angegeben werden.
7.4.0 | Der OpenSSL-Standard-Konfigurationspfad wurde von C:\usr\local\ssl zu C:\Program Files\Common Files\SSL bzw. C:\Program Files (x86)\Common Files\SSL geändert.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

openssl Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
openssl.cafile | "" | `INI_PERDIR` |
openssl.capath | "" | `INI_PERDIR` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`openssl.cafile` string

  Speicherort der Datei mit der Zertifizierungsstelle im lokalen Dateisystem, die mit der Kontextoption verify_peer verwendet werden soll, um die Identität der Gegenstelle zu authentifizieren.

`openssl.capath` string

  Wenn cafile nicht angegeben wurde oder das Zertifikat dort nicht gefunden wird, wird das Verzeichnis, auf das capath verweist, nach einem passenden Zertifikat durchsucht. capath muss ein korrekt gehashtes Zertifikatsverzeichnis sein.

Siehe auch die SSL-Stream-Kontext-Optionen.

## Ressource-Typen

Vor PHP 8.0.0 gab es 3 Ressourcentypen, die im OpenSSL-Modul definiert waren:

- `OpenSSL-Schlüssel`
- `OpenSSL X.509`
- `OpenSSL X.509 CSR`

# Vordefinierte Konstanten

## Inhaltsverzeichnis

- Zweckprüfende Flags
- Padding-Flags für asymmetrische Verschlüsselung
- Schlüsseltypen
- PKCS7-Flags/Konstanten
- CMS-Flags/Konstanten
- Signatur-Algorithmen
- Ciphers
- Versions-Konstanten
- Konstanten zur Identifizierung des Servernamens (Server Name Indication)
- Andere Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

## Zweckprüfende Flags

`X509_PURPOSE_SSL_CLIENT` (int)
`X509_PURPOSE_SSL_SERVER` (int)
`X509_PURPOSE_NS_SSL_SERVER` (int)
`X509_PURPOSE_SMIME_SIGN` (int)
`X509_PURPOSE_SMIME_ENCRYPT` (int)
`X509_PURPOSE_CRL_SIGN` (int)
`X509_PURPOSE_ANY` (int)

## Padding-Flags für asymmetrische Verschlüsselung

`OPENSSL_PKCS1_PADDING` (int)
`OPENSSL_SSLV23_PADDING` (int)
`OPENSSL_NO_PADDING` (int)
`OPENSSL_PKCS1_OAEP_PADDING` (int)

## Schlüsseltypen

`OPENSSL_KEYTYPE_RSA` (int)
  Schlüsseltyp RSA.
`OPENSSL_KEYTYPE_DSA` (int)
  Schlüsseltyp DSA.
`OPENSSL_KEYTYPE_DH` (int)
  Schlüsseltyp DH (Diffie-Hellman).
`OPENSSL_KEYTYPE_EC` (int)
  Schlüsseltyp elliptische Kurve.
`OPENSSL_KEYTYPE_X25519` (int)
  Schlüsseltyp X25519-Kurve. Diese Konstante ist nur verfügbar, wenn PHP mit OpenSSL 3.0+ kompiliert wurde.
`OPENSSL_KEYTYPE_ED25519` (int)
  Schlüsseltyp Ed25519-Kurve. Diese Konstante ist nur verfügbar, wenn PHP mit OpenSSL 3.0+ kompiliert wurde.
`OPENSSL_KEYTYPE_X448` (int)
  Schlüsseltyp X448-Kurve. Diese Konstante ist nur verfügbar, wenn PHP mit OpenSSL 3.0+ kompiliert wurde.
`OPENSSL_KEYTYPE_ED448` (int)
  Schlüsseltyp Ed448-Kurve. Diese Konstante ist nur verfügbar, wenn PHP mit OpenSSL 3.0+ kompiliert wurde.

## PKCS7-Flags/Konstanten

Die S/MIME-Funktionen nutzen Flags, die durch ein Bitfeld angegeben werden. Dieses Bitfeld kann einen oder mehrere der folgenden Werte enthalten:

PKCS7-Konstanten
Konstante | Beschreibung
--- | ---
`PKCS7_TEXT` (int) | Fügt einer verschlüsselten/signierten Nachricht den Inhaltstyp-Header `text/plain` zu hinzu. Beim Entschlüsseln oder Überprüfen wird dieser Header aus der Ausgabe entfernt. Entspricht die entschlüsselte oder geprüfte Nachricht nicht dem MIME-Typ `text/plain`, tritt ein Fehler auf.
`PKCS7_BINARY` (int) | Normalerweise wird die Nachricht in ein "kanonisches" Format konvertiert, das effektiv `CR` und `LF` als Zeilende verwendet, wie von der S/MIME-Spezifikation gefordert. Wird diese Option angegeben, findet keine Konvertierung statt. Dies ist nützlich beim Umgang mit Binärdaten, die nicht im MIME-Format vorliegen.
`PKCS7_NOINTERN` (int) | Beim Überprüfen einer Nachricht werden in der Nachricht enthaltene Zertifikate (falls vorhanden) nach dem Signatur-Zertifikat durchsucht. Mit dieser Option werden nur Zertifikate verwendet, die mit dem Parameter `untrusted_certificates_filename` in der Funktion openssl_pkcs7_verify() angegeben wurden. Die mitgelieferten Zertifikate können aber dennoch verwendet werden, allerdings als nicht vertrauenswürdige CAs.
`PKCS7_NOVERIFY` (int) | Das Zertifikat des Unterzeichners einer signierten Nachricht nicht überprüfen.
`PKCS7_NOCHAIN` (int) | Die Überprüfung der Zertifikate des Unterzeichners nicht verketten, das bedeutet, die Zertifikate in der signierten Nachricht werden nicht als nicht vertrauenswürdige CAs verwendet.
`PKCS7_NOCERTS` (int) | Beim Signieren einer Nachricht wird normalerweise das Zertifikat des Unterzeichnenden mit in die Nachricht aufgenommen. Mit dieser Option wird das Zertifikat nicht mit aufgenommen. Diese Option verringert die Größe der signierten Nachricht, aber der Überprüfende muss eine lokale Kopie des Zertifikats vom Unterzeichnenden besitzen (zum Beispiel durch Angabe des Parameters `untrusted_certificates_filename` in der Funktion openssl_pkcs7_verify()).
`PKCS7_NOATTR` (int) | Beim Signieren einer Nachricht wird normalerweise eine Reihe von Attributen mit angehängt. Diese enthalten die Zeit der Signierung und die unterstützen symmetrischen Algorithmen. Mit dieser Option werden diese Attribute nicht mit aufgenommen.
`PKCS7_DETACHED` (int) | Beim Signieren einer Nachricht wird die Klartext-Signierung mit dem MIME-Typ `"multipart/signed"` verwendet. Das ist der Standard, wenn in `flags` keine optionalen Parameter an die Funktion openssl_pkcs7_sign() übergeben werden. Wenn Sie diese Option ausschalten, wird die Nachricht mit einer intransparenten Signatur unterzeichnet. Dieses Verhalten ist robuster gegenüber der Übersetzung durch Mail-Relays, kann aber nicht mit Mailprogrammen gelesen werden, die den S/Mime-Standard nicht unterstützen.
`PKCS7_NOSIGS` (int) | Die Signaturen einer Nachricht nicht überprüfen.
`PKCS7_NOOLDMIMETYPE` (int) | Verfügbar ab PHP 8.3.0. Setzt den Inhaltstyp auf `application/pkcs7-mime` anstelle von `application/x-pkcs7-mime`, um eine Nachricht zu verschlüsseln.

## CMS-Flags/Konstanten

Die CMS-Funktionen verwenden Flags, die über ein Bitfeld angegeben werden, das einen oder mehrere der folgenden Werte enthalten kann:

CMS-Konstanten
Konstante | Beschreibung
--- | ---
`OPENSSL_CMS_TEXT` (int) | Fügt einer verschlüsselten/signierten Nachricht den Inhaltstyp-Header text/plain zu hinzu. Beim Entschlüsseln oder Überprüfen wird dieser Header aus der Ausgabe entfernt. Entspricht die entschlüsselte oder geprüfte Nachricht nicht dem MIME-Typ text/plain, tritt ein Fehler auf.
`OPENSSL_CMS_BINARY` (int) | Normalerweise wird die Nachricht in ein "kanonisches" Format konvertiert, das effektiv `CR` und `LF` als Zeilende verwendet, wie von der CMS-Spezifikation gefordert. Wird diese Option angegeben, findet keine Konvertierung statt. Dies ist nützlich beim Umgang mit Binärdaten, die nicht im CMS-Format vorliegen.
`OPENSSL_CMS_NOINTERN` (int) | Beim Überprüfen einer Nachricht werden in der Nachricht enthaltene Zertifikate (falls vorhanden) nach dem Signatur-Zertifikat durchsucht. Mit dieser Option werden nur Zertifikate verwendet, die mit dem Parameter `untrusted_certificates_filename` in der Funktion openssl_cms_verify() angegeben wurden. Die mitgelieferten Zertifikate können aber dennoch verwendet werden, allerdings als nicht vertrauenswürdige CAs.
`OPENSSL_CMS_NOVERIFY` (int) | Das Zertifikat des Unterzeichners einer signierten Nachricht nicht überprüfen.
`OPENSSL_CMS_NOCERTS` (int) | Beim Signieren einer Nachricht wird normalerweise das Zertifikat des Unterzeichnenden mit in die Nachricht aufgenommen. Mit dieser Option wird das Zertifikat nicht mit aufgenommen. Diese Option verringert die Größe der signierten Nachricht, aber der Überprüfende muss eine lokale Kopie des Zertifikats vom Unterzeichnenden besitzen (zum Beispiel durch Angabe des Parameters `untrusted_certificates_filename` in der Funktion openssl_cms_verify()).
`OPENSSL_CMS_NOATTR` (int) | Beim Signieren einer Nachricht wird normalerweise eine Reihe von Attributen mit angehängt. Diese enthalten die Zeit der Signierung und die unterstützen symmetrischen Algorithmen. Mit dieser Option werden diese Attribute nicht mit aufgenommen.
`OPENSSL_CMS_DETACHED` (int) | Beim Signieren einer Nachricht wird die Klartext-Signierung mit dem MIME-Typ `"multipart/signed"` verwendet. Das ist der Standard, wenn in `flags` keine optionalen Parameter an die Funktion openssl_cms_sign() übergeben werden. Wenn Sie diese Option ausschalten, wird die Nachricht mit einer intransparenten Signatur unterzeichnet. Dieses Verhalten ist robuster gegenüber der Übersetzung durch Mail-Relays, kann aber nicht mit Mailprogrammen gelesen werden, die den S/Mime-Standard nicht unterstützen.
`OPENSSL_CMS_NOSIGS` (int) | Die Signaturen einer Nachricht nicht überprüfen.
`OPENSSL_CMS_OLDMIMETYPE` (int) | Verfügbar ab PHP 8.3.0. Setzt den Inhaltstyp auf `application/x-pkcs7-mime` anstelle von `application/pkcs7-mime`, um eine Nachricht zu verschlüsseln.

## Signatur-Algorithmen

`OPENSSL_ALGO_DSS1` (int)
`OPENSSL_ALGO_SHA1` (int)
  Wird als Standard-Algorithmus für die Funktionen openssl_sign() und openssl_verify() verwendet.
`OPENSSL_ALGO_SHA224` (int)
`OPENSSL_ALGO_SHA256` (int)
`OPENSSL_ALGO_SHA384` (int)
`OPENSSL_ALGO_SHA512` (int)
`OPENSSL_ALGO_RMD160` (int)
`OPENSSL_ALGO_MD5` (int)
`OPENSSL_ALGO_MD4` (int)
`OPENSSL_ALGO_MD2` (int)
  Diese Konstante ist nur verfügbar, wenn PHP mit MD2-Unterstützung kompiliert wurde. Dies erfordert die Übergabe des CFLAGs `-DHAVE_OPENSSL_MD2_H`, wenn PHP kompiliert wird, und `enable-md2`, wenn OpenSSL 1.0.0+ kompiliert wird.

## Ciphers

`OPENSSL_DEFAULT_STREAM_CIPHERS` (string)
  Die Liste der Standardverschlüsselungen.
`OPENSSL_CIPHER_RC2_40` (int)
`OPENSSL_CIPHER_RC2_128` (int)
`OPENSSL_CIPHER_RC2_64` (int)
`OPENSSL_CIPHER_DES` (int)
`OPENSSL_CIPHER_3DES` (int)

`OPENSSL_CIPHER_AES_128_CBC` (int)
`OPENSSL_CIPHER_AES_192_CBC` (int)
`OPENSSL_CIPHER_AES_256_CBC` (int)

## Versions-Konstanten

`OPENSSL_VERSION_TEXT` (string)
`OPENSSL_VERSION_NUMBER` (int)

## Konstanten zur Identifizierung des Servernamens (Server Name Indication)

`OPENSSL_TLSEXT_SERVER_NAME` (int)
  Ob SNI unterstützt wird oder nicht.

> Hinweis:

> Diese Konstante erfordert, dass PHP mit OpenSSL 0.9.8j oder höher kompiliert wurde.

## Andere Konstanten

`OPENSSL_RAW_DATA` (int)
  Wenn `OPENSSL_RAW_DATA` in den Funktionen openssl_encrypt() oder openssl_decrypt() im Parameter `options` angegeben ist, werden die Daten so zurückgegeben, wie sie sind. Ist es nicht angegeben, werden Base64-kodierte Daten an den Aufrufenden zurückgegeben.
`OPENSSL_DONT_ZERO_PAD_KEY` (int)
  Verhindert, dass openssl_encrypt() Schlüssel auffüllt, die kürzer als die Standardschlüssellänge sind.
`OPENSSL_ZERO_PADDING` (int)
  Standardmäßig wird bei Verschlüsselungsvorgängen mit Standard-Blockpadding aufgefüllt und das Padding wird beim Entschlüsseln geprüft und entfernt. Wenn `OPENSSL_ZERO_PADDING` in den Funktionen openssl_encrypt() oder openssl_decrypt() im Parameter `options` angegeben ist, wird kein Padding durchgeführt und die Gesamtmenge der verschlüsselten oder entschlüsselten Daten muss ein Vielfaches der Blockgröße sein, sonst tritt ein Fehler auf.
`OPENSSL_ENCODING_SMIME` (int)
  Gibt an, dass die Kodierung im S/MIME-Format erfolgt.
`OPENSSL_ENCODING_DER` (int)
  Gibt an, dass die Kodierung im DER-Format (Distinguished Encoding Rules) erfolgt.
`OPENSSL_ENCODING_PEM` (int)
  Gibt an, dass die Kodierung im PEM-Format (Privacy-Enhanced Mail) erfolgt.

# Schlüssel-/Zertifikatparameter

Ziemlich viele der OpenSSL-Funktionen benötigen einen Schlüssel- oder Zertifikatparameter. Folgende Methoden können genutzt werden, um solche zu erhalten:

- Zertifikate

  1. Eine OpenSSLCertificate-Instanz (oder vor PHP 8.0.0 eine Ressource vom Typ `OpenSSL X.509`), die von openssl_x509_read() zurückgegeben wurde.
  2. Eine Zeichenkette mit dem Format file://pfad/zu/cert.pem; die angegebene Datei muss ein PEM-kodiertes Zertifikat enthalten.
  3. Eine Zeichenkette, die den Inhalt eines Zertifikats in PEM-Kodierung enthält. Sie kann mit `-----BEGIN CERTIFICATE-----` beginnen.

- Zertifikat-Signierungsanforderungen (Certificate Signing Requests, CSRs)

  1. Eine OpenSSLCertificateSigningRequest-Instanz (oder vor PHP 8.0.0 eine Ressource vom Typ `OpenSSL X.509 CSR`), die von openssl_csr_new() zurückgegeben wurde.
  2. Eine Zeichenkette mit dem Format file://path/to/csr.pem; die benannte Datei muss einen PEM-kodierten CSR enthalten.
  3. Eine Zeichenkette, die den Inhalt eines CSRs in PEM-Kodierung enthält. Sie kann mit `-----BEGIN CERTIFICATE REQUEST-----` beginnen.

- Öffentliche/Private Schlüssel

  1. Eine OpenSSLAsymmetricKey-Instanz (oder vor PHP 8.0.0 eine Ressource vom Typ `OpenSSL-Schlüssel`), die von openssl_get_publickey() oder openssl_get_privatekey() zurückgegeben wurde.
  2. Nur für öffentliche Schlüssel: eine OpenSSLCertificate-Instanz (oder vor PHP 8.0.0 eine Ressource vom Typ `OpenSSL X.509`).
  3. Eine Zeichenkette mit dem Format file://pfad/zu/datei.pem - die angegebene Datei muss ein PEM-kodiertes Zertifikat und/oder einen PEM-kodierten privaten Schlüssel enthalten.
  4. Eine Zeichenkette, die den Inhalt eines Zertifikats/Schlüssels in PEM-Kodierung enthält. Sie kann mit `-----BEGIN PUBLIC KEY-----` beginnen.
  5. Für private Schlüssel können Sie auch die Syntax `array($key, $passphrase)` verwenden. $key repräsentiert einen Schlüssel, den Sie entweder mit der Notation file:// oder dem textlichen Inhalt wie oben angeben. $passphrase ist eine Zeichenfolge, die die Passphrase für den privaten Schlüssel enthält.

# Überprüfung von Zertifikaten

Wenn Sie eine Funktion aufrufen, die eine Signatur/ein Zertifikat überprüft, ist der Parameter `ca_info` ein Array, das Datei- und Verzeichnisnamen enthält, die auf vertrauenswürdige CA-Dateien verweisen. Falls Sie ein Verzeichnis angeben, muss dies ein korrekt geformtes gehashtes Verzeichnis in der Art sein, wie es der Befehl openssl verwenden würde.

# OpenSSL-Funktionen

# openssl_cipher_iv_length

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

openssl_cipher_iv_length — Ermittelt die Länge des Initialisierungsvektors einer Verschlüsselungsmethode

### Beschreibung

function openssl_cipher_iv_length(string `$cipher_algo`): int|false

Ermittelt die Länge des Initialisierungsvektors (IV) einer Verschlüsselungsmethode.

### Parameter-Liste

`cipher_algo`

  Die Verschlüsselungsmethode; openssl_get_cipher_methods() liefert eine Liste der möglichen Werte.

### Rückgabewerte

Gibt bei Erfolg die Länge des Initialisierungsvektors zurück, im Fehlerfall `false`.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn die Verschlüsselungsmethode unbekannt ist.

### Beispiele

Beispiel #1 Beispiel für openssl_cipher_iv_length()

    <?php
    $method = 'AES-128-CBC';
    $ivlen = openssl_cipher_iv_length($method);

    echo $ivlen;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    16

# openssl_cipher_key_length

(PHP 8 >= 8.2.0)

openssl_cipher_key_length — Ermittelt die Schlüssellänge einer Verschlüsselungsmethode

### Beschreibung

function openssl_cipher_key_length(string `$cipher_algo`): int|false

Ermittelt die Schlüssellänge einer Verschlüsselungsmethode.

### Parameter-Liste

`cipher_algo`

  Die Verschlüsselungsmethode; openssl_get_cipher_methods() liefert eine Liste der möglichen Werte.

### Rückgabewerte

Gibt bei Erfolg die Schlüssellänge zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn die Verschlüsselungsmethode unbekannt ist.

### Beispiele

Beispiel #1 Beispiel für openssl_cipher_key_length()

    <?php
    $method = 'AES-128-CBC';

    var_dump(openssl_cipher_key_length($method));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(16)

# openssl_cms_decrypt

(PHP 8)

openssl_cms_decrypt — Decrypt a CMS message

### Beschreibung

function openssl_cms_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

Decrypts a CMS message.

### Parameter-Liste

`input_filename`

  The name of a file containing encrypted content.

`output_filename`

  The name of the file to deposit the decrypted content.

`certificate`

  The name of the file containing a certificate of the recipient.

`private_key`

  The name of the file containing a PKCS#8 key.

`encoding`

  The encoding of the input file. One of `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` or `OPENSSL_ENCODING_PEM`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# openssl_cms_encrypt

(PHP 8)

openssl_cms_encrypt — Encrypt a CMS message

### Beschreibung

function openssl_cms_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
string|int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

This function encrypts content to one or more recipients, based on the certificates that are passed to it.

### Parameter-Liste

`input_filename`

  The file to be encrypted.

`output_filename`

  The output file.

`certificate`

  Recipients to encrypt to.

`headers`

  Headers to include when S/MIME is used.

`flags`

  Flags to be passed to CMS_sign.

`encoding`

  An encoding to output. One of `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` or `OPENSSL_ENCODING_PEM`.

`cipher_algo`

  A cipher to use.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | `cipher_algo` is now of type int or string. Previously, it was of type int.
8.1.0 | The default cipher algorithm (`cipher_algo`) is now AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`). Previously, PKCS7/CMS was used (`OPENSSL_CIPHER_RC2_40`).

# openssl_cms_read

(PHP 8)

openssl_cms_read — Export the CMS file to an array of PEM certificates

### Beschreibung

function openssl_cms_read(string `$input_filename`, array `&$certificates`): bool

Performs the exact analog to openssl_pkcs7_read().

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`input_filename`

`certificates`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# openssl_cms_sign

(PHP 8)

openssl_cms_sign — Sign a file

### Beschreibung

function openssl_cms_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
?string `$untrusted_certificates_filename` = `null`
): bool

This function signs a file with an X.509 certificate and key.

### Parameter-Liste

`input_filename`

  The name of the file to be signed.

`output_filename`

  The name of the file to deposit the results.

`certificate`

  The signing certificate. See Key/Certificate parameters for a list of valid values.

`private_key`

  The key associated with `certificate`. See Key/Certificate parameters for a list of valid values.

`headers`

  An array of headers to be included in S/MIME output.

`flags`

  Flags to be passed to cms_sign().

`encoding`

  The encoding of the output file. One of `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` or `OPENSSL_ENCODING_PEM`.

`untrusted_certificates_filename`

  Intermediate certificates to be included in the signature.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 openssl_cms_sign() example

    <?php

    openssl_cms_sign('input.txt', 'output.txt', 'file://cert.pem', 'file://privkey.pem', null, OPENSSL_CMS_BINARY, OPENSSL_ENCODING_DER, 'chain.pem');
    ?>

# openssl_cms_verify

(PHP 8)

openssl_cms_verify — Verify a CMS signature

### Beschreibung

function openssl_cms_verify(
string `$input_filename`,
int `$flags` = 0,
?string `$certificates` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$pk7` = `null`,
?string `$sigfile` = `null`,
int `$encoding` = `OPENSSL_ENCODING_SMIME`
): bool

This function verifies a CMS signature, either attached or detached, with the specified encoding.

### Parameter-Liste

`input_filename`

  The input file.

`flags`

  Flags to pass to cms_verify().

`certificates`

  A file with the signer certificate and optionally intermediate certificates.

`ca_info`

  An array containing self-signed certificate authority certificates.

`untrusted_certificates_filename`

  A file containing additional intermediate certificates.

`content`

  A file pointing to the content when signatures are detached.

`pk7`

`sigfile`

  A file to save the signature to.

`encoding`

  The encoding of the input file. One of `OPENSSL_ENCODING_SMIME`, `OPENSSL_ENCODING_DER` or `OPENSSL_ENCODING_PEM`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# openssl_csr_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export — Exportiert einen CSR als Zeichenkette

### Beschreibung

function openssl_csr_export(OpenSSLCertificateSigningRequest|string `$csr`, string `&$output`, bool `$no_text` = `true`): bool

openssl_csr_export() exportiert die mit dem Parameter `csr` angegebene Zertifikats-Signierungsanfrage und speichert diese im PEM-Format in der Zeichenkette `output`, die per Referenz übergeben wird.

### Parameter-Liste

`csr`

  Eine Liste der gültigen Werte ist unter CSR-Parameter zu finden.

`output`

  Im Erfolgsfall enthält diese Zeichenkette den PEM-kodierten CSR.

`no_text`

  Der optionale Parameter`notext` beinflusst die Ausführlichkeit der Ausgabe. Wenn er auf `false` gesetzt wird, werden zusätzliche lesbare Informationen in die Ausgabe aufgenommen. Der Vorgabewert für `notext` ist `true`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `csr` akzeptiert nun eine OpenSSLCertificateSigningRequest-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` akzeptiert.

### Beispiele

Beispiel #1 openssl_csr_export()-Beispiel

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha256WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $private_key, $configargs);
    openssl_csr_export($csr, $csr_string);
    echo $csr_string;
    ?>

### Siehe auch

- openssl_csr_export_to_file() - Exportiert einen CSR in eine Datei
- openssl_csr_new() - Erzeugt einen CSR
- openssl_csr_sign() - Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat

# openssl_csr_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export_to_file — Exportiert einen CSR in eine Datei

### Beschreibung

function openssl_csr_export_to_file(OpenSSLCertificateSigningRequest|string `$csr`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_csr_export_to_file() exportiert die mit dem Parameter `csr` angegebene Zertifikats-Signierungsanfrage und speichert diese im PEM-Format in der Datei mit dem Namen `output_filename`.

### Parameter-Liste

`csr`

  Eine Liste der gültigen Werte ist unter CSR-Parameter zu finden.

`output_filename`

  Pfad zur Ausgabedatei.

`no_text`

  Der optionale Parameter`notext` beinflusst die Ausführlichkeit der Ausgabe. Wenn er auf `false` gesetzt wird, werden zusätzliche lesbare Informationen in die Ausgabe aufgenommen. Der Vorgabewert für `notext` ist `true`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `csr` akzeptiert nun eine OpenSSLCertificateSigningRequest-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` akzeptiert.

### Beispiele

Beispiel #1 openssl_csr_export_to_file()-Beispiel

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384') );
    openssl_pkey_export_to_file($private_key, 'example-priv.key');
    // Nebst dem Subjekt enthält der CSR den zum privaten Schlüssel gehörenden
    // öffentlichen Schlüssel
    openssl_csr_export_to_file($csr, 'example-csr.pem');
    ?>

### Siehe auch

- openssl_csr_export() - Exportiert einen CSR als Zeichenkette
- openssl_csr_new() - Erzeugt einen CSR
- openssl_csr_sign() - Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat

# openssl_csr_get_public_key

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_public_key — Liefert den öffentlichen Schlüssel eines CSR

### Beschreibung

function openssl_csr_get_public_key(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): OpenSSLAsymmetricKey|false

openssl_csr_get_public_key() extrahiert den öffentlichen Schlüssel aus `csr` und bereitet ihn für die Verwendung mit anderen Funktionen vor.

### Parameter-Liste

`csr`

  Eine Liste der gültigen Werte ist unter CSR-Parameter zu finden.

`short_names`
  Warnung

  Dieser Parameter wird ignoriert.

### Rückgabewerte

Gibt bei Erfolg eine OpenSSLAsymmetricKey-Instanz zurück oder `false` bei einem Fehler.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Bei Erfolg gibt diese Funktion nun eine OpenSSLAsymmetricKey-Instanz zurück; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` zurückgegeben.
8.0.0 | `csr` akzeptiert nun eine OpenSSLCertificateSigningRequest-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` akzeptiert.

### Beispiele

Beispiel #1 openssl_csr_get_public_key()-Beispiel

    <?php
    $subject = array(
        "commonName" => "example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha256') );
    $public_key = openssl_csr_get_public_key($csr);
    $info = openssl_pkey_get_details($public_key);
    echo $info['key'];
    ?>

### Siehe auch

- openssl_csr_get_subject() - Liefert das Subjekt eines CSR
- openssl_csr_new() - Erzeugt einen CSR
- openssl_pkey_get_details() - Liefert ein Array mit Schlüssel-Details
- openssl_pkey_export_to_file() - Speichert einen Schlüssel in einem exportierbaren Format in einer Datei
- openssl_pkey_export() - Speichert ein exportierbares Format eines Schlüssels in einer Zeichenkette

# openssl_csr_get_subject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_subject — Liefert das Subjekt eines CSR

### Beschreibung

function openssl_csr_get_subject(OpenSSLCertificateSigningRequest|string `$csr`, bool `$short_names` = `true`): array|false

openssl_csr_get_subject() gibt Informationen zum Distinguished Name des Subjekts zurück, die im `csr` kodiert sind, was Felder wie commonName (CN), organizationName (O), countryName (C) usw. einschließt.

### Parameter-Liste

`csr`

  Eine Liste der gültigen Werte ist unter CSR-Parameter zu finden.

`short_names`

  `short_names` steuert, wie die Daten im Array indexiert sind. Wenn `short_names` `true` ist (Standardwert), dann werden die Felder mit ihrer kurzen Namensform indexiert; andernfalls wird die lange Namensform verwendet - z. B. ist CN die kurze Namensform von commonName.

### Rückgabewerte

Gibt ein assoziatives Array mit der Beschreibung des Subjekts zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `csr` akzeptiert nun eine OpenSSLCertificateSigningRequest-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` akzeptiert.

### Beispiele

Beispiel #1 openssl_csr_get_subject()-Beispiel

    <?php
    $subject = array(
        "countryName" => "CA",
        "stateOrProvinceName" => "Alberta",
        "localityName" => "Calgary",
        "organizationName" => "XYZ Widgets Inc",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com",
    );
    $private_key = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $configargs = array(
        'digest_alg' => 'sha512WithRSAEncryption'
    );
    $csr = openssl_csr_new($subject, $privkey, $configargs);
    print_r(openssl_csr_get_subject($csr));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [C] => CA
        [ST] => Alberta
        [L] => Calgary
        [O] => XYZ Widgets Inc
        [OU] => PHP Documentation Team
        [CN] => Wez Furlong
        [emailAddress] => wez@example.com
    )

### Siehe auch

- openssl_csr_new() - Erzeugt einen CSR
- openssl_csr_get_public_key() - Liefert den öffentlichen Schlüssel eines CSR
- openssl_x509_parse() - Parst ein X.509-Zertifikat und liefert die Informationen als Array

# openssl_csr_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_new — Erzeugt einen CSR

### Beschreibung

function openssl_csr_new(
array `$distinguished_names`,
#[\SensitiveParameter]?OpenSSLAsymmetricKey `&$private_key`,
?array `$options` = `null`,
?array `$extra_attributes` = `null`
): OpenSSLCertificateSigningRequest|bool

openssl_csr_new() erzeugt einen neuen CSR (Certificate Signing Request, Zertifikats-Signierungsanfrage) basierend auf den Informationen, die mit dem Parameter `distinguished_names` angegeben werden.

> Hinweis: Die ordnungsgemäße Ausführung dieser Funktion setzt die Installation einer gültigen openssl.cnf-Datei voraus. Mehr Information hierzu sind im Abschnitt Installation zu finden.

### Parameter-Liste

`distinguished_names`

  Der Distinguished Name oder die Subjekt-Felder, die in das Zertifikat aufgenommen werden sollen. `distinguished_names` ist ein assoziatives Array, in dem die Schlüssel die Attributnamen der Distinguished Names darstellen und die Werte entweder Zeichenketten (für einen einzelnen Wert) oder Arrays (wenn mehrere Werte festgelegt werden müssen) sein können.

`private_key`

  `private_key` muss auf einen zuvor mit openssl_pkey_new() erzeugten (oder anderweitig von der openssl_pkey-Familie erhaltenen) privaten Schlüssel oder auf eine `null`-Variable gesetzt werden. Wenn der Wert `null` ist, wird ein neuer privater Schlüssel basierend auf den übergebenen `options` erzeugt und der übergebenen Variablen zugewiesen. Der zugehörige öffentliche Teil des Schlüssels wird zum Signieren des CSR verwendet.

`options`

  In der Standardeinstellung werden die Informationen für die Anfrage aus der `openssl.conf` des Systems verwendet; ein Abschnitt der Konfigurationsdatei kann durch Setzen des Schlüssels `config_section` in `options` angegeben werden. Außerdem kann eine alternative OpenSSL-Konfigurationsdatei angegeben, indem der Wert des Schlüssels `config` auf den Pfad der zu verwendenden Datei gesetzt wird. Die unten in der Tabelle aufgeführten Schlüssel, soweit in `options` vorhanden, verhalten sich genau gleich wie die entsprechenden Werte in der `openssl.conf`.

  Überschreiben der Konfiguration
  `options`-Schlüssel | Typ | `openssl.conf`-Entsprechung | Beschreibung
  --- | --- | --- | ---
  digest_alg | string | default_md | Digest-Methode oder Signaturhash, üblicherweise eins von openssl_get_md_methods().
  x509_extensions | string | x509_extensions | Bestimmt, welche Erweiterung verwendet werden soll, wenn ein x509-Zertifikat erzeugt werden soll.
  req_extensions | string | req_extensions | Bestimmt welche Erweiterung verwendet werden soll, wenn eine Zertifikats-Signierungsanfrage (CSR) erzeugt werden soll.
  private_key_bits | int | default_bits | Bestimmt wieviele Bits verwendet werden sollen, um einen privaten Schlüssel zu erzeugen.
  private_key_type | int | keine | Bestimmt den Typ des privaten Schlüssels, der erzeugt werden soll. Der Typ kann einer der folgenden sein: `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_RSA` oder `OPENSSL_KEYTYPE_EC`. Der Standardwert ist `OPENSSL_KEYTYPE_RSA`.
  encrypt_key | bool | encrypt_key | Soll ein exportierter Schlüssel (mit Passphrase) verschlüsselt werden?
  encrypt_key_cipher | int | keine | Eine der Ziffer-Konstanten.
  curve_name | string | none | Einer der openssl_get_curve_names().
  config | string | N/A | Pfad zur eigenen alternativen openssl.conf-Datei.

`extra_attributes`

  `extra_attributes` wird verwendet, um zusätzliche Attribute für den CSR anzugeben. Es handelt sich um ein assoziatives Array, dessen Schlüssel in OIDs umgewandelt und als CSR-Attribute verwendet werden.

### Rückgabewerte

Gibt bei Erfolg den CSR zurück; `true` wenn die CSR-Erstellung erfolgreich war, aber das Signieren fehlgeschlagen ist. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Das assoziative Array `distinguished_names` unterstützt nun Arrays als Werte, sodass mehrere Werte für ein einzelnes Attribut angegeben werden können.
8.4.0 | Der Parameter `extra_attributes` setzt nun korrekt die CSR-Attribute, anstatt wie bisher fälschlicherweise den Distinguished Name des Subjekts zu ändern.
8.0.0 | Bei Erfolg gibt diese Funktion nun eine OpenSSLCertificateSigningRequest-Instanz zurück; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` zurückgegeben.
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` akzeptiert.
7.1.0 | `options` unterstützt nun auch `curve_name`.

### Beispiele

Beispiel #1 Erzeugen eines selbstsignierten Zertifikats

    <?php
    // bei SSL-Zertifikate ist der commonName der zu sichernde Domain-Name
    // bei S/MIME-Zertifikate ist der commonName der Eigentümer der E-Mail-Adresse
    // die Felder location und identification beziehen sich auf den Eigentümer der
    // zu sichernden Domain oder des E-Mail-Eigentümers
    $dn = array(
        "countryName" => "GB",
        "stateOrProvinceName" => "Somerset",
        "localityName" => "Glastonbury",
        "organizationName" => "The Brain Room Limited",
        "organizationalUnitName" => "PHP Documentation Team",
        "commonName" => "Wez Furlong",
        "emailAddress" => "wez@example.com"
    );

    // Erzeugen eines neuen privaten (und öffentlichen) Schlüsselpaars
    $privkey = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));

    // Erzeugen einer Zertifikats-Signierungsanfrage
    $csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

    // Erzeugen eines selbstsignierten Zertifikats, das für die Dauer von 365 Tagen
    // gültig ist.
    $x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

    // Sichern des privaten Schlüssels, des CSR und des selbstsignierten
    // Zertifikats für die spätere Verwendung
    openssl_csr_export($csr, $csrout) and var_dump($csrout);
    openssl_x509_export($x509, $certout) and var_dump($certout);
    openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);

    // Anzeigen aller aufgetretenen Fehler
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

Beispiel #2 Erzeugen eines selbstsignierten ECC-Zertifikats (von PHP 7.1.0 an)

    <?php
    $subject = array(
        "commonName" => "docs.php.net",
    );

    // Erzeugen eines neuen privaten (und öffentlichen) Schlüsselpaars
    $private_key = openssl_pkey_new(array(
        "private_key_type" => OPENSSL_KEYTYPE_EC,
        "curve_name" => 'prime256v1',
    ));

    // Erzeugen einer Zertifikats-Signierungsanfrage
    $csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

    // Erzeugen eines selbstsignierten EC-Zertifikats
    $x509 = openssl_csr_sign($csr, null, $private_key, $days=365, array('digest_alg' => 'sha384'));
    openssl_x509_export_to_file($x509, 'ecc-cert.pem');
    openssl_pkey_export_to_file($private_key, 'ecc-private.key');
    ?>

### Siehe auch

- openssl_csr_sign() - Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat

# openssl_csr_sign

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_sign — Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat

### Beschreibung

function openssl_csr_sign(
OpenSSLCertificateSigningRequest|string `$csr`,
OpenSSLCertificate|string|null `$ca_certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$days`,
?array `$options` = `null`,
int `$serial` = 0,
?string `$serial_hex` = `null`
): OpenSSLCertificate|false

openssl_csr_sign() erzeugt eine x509-Zertifikatressource aus dem übergebenen CSR.

> Hinweis: Die ordnungsgemäße Ausführung dieser Funktion setzt die Installation einer gültigen openssl.cnf-Datei voraus. Mehr Information hierzu sind im Abschnitt Installation zu finden.

### Parameter-Liste

`csr`

  Ein zuvor mit openssl_csr_new() erzeugter CSR. Es kann sich aber auch um den Pfad zu einer PEM-kodierten CSR-Datei in der Form file://path/to/csr handeln, oder eine Zeichenkette wie von openssl_csr_export() zurückgegeben.

`ca_certificate`

  Das generierte Zertifikat wird mit `ca_certificate` signiert. Falls hier `null` angegeben wird, wird ein selbstsigniertes Zertifikat erstellt.

`private_key`

  `private_key` ist der zu `ca_certificate` gehörende private Schlüssel.

`days`

  `days` gibt die Gültigkeitsdauer des Zertifikats in Tagen an.

`options`

  Mit `options` kann die Signierung des CSR feiner abgestimmt werden. Weitere Informationen zu `options` sind openssl_csr_new() zu entnehmen.

`serial`

  Eine optionale Seriennummer für das ausgestellte Zertifikat. Wenn nicht angegeben, wird der Standardwert 0 verwendet.

`serial_hex`

  Eine optionale hexadezimale Zeichenkette, die die Seriennummer des ausgestellten Zertifikats angibt. Wenn sie angegeben wird, hat sie Vorrang vor dem Wert des Parameters `serial`. Wird sie nicht angegeben oder auf `null` gesetzt, wird stattdessen der Wert des Parameters `serial` verwendet. instead.

### Rückgabewerte

Gibt bei Erfolg ein OpenSSLCertificate zurück, `false` bei einem Fehler.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Den Parameter `serial_hex` hinzugefügt.
8.0.0 | Bei Erfolg gibt diese Funktion nun eine OpenSSLCertificate-Instanz zurück; vorher wurde eine Ressource vom Typ `OpenSSL X.509` zurückgegeben.
8.0.0 | `csr` akzeptiert nun eine OpenSSLCertificateSigningRequest-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` akzeptiert.
8.0.0 | `ca_certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509` akzeptiert.
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

### Beispiele

Beispiel #1 openssl_csr_sign()-Beispiel - Signieren eines CSR (wie eine eigene CA implementiert wird)

    <?php
    // Annahme: dieses Skript erhält einen CSR, der auf einer anderen Seite in
    // eine Textarea eingegeben wurde.
    $csrdata = $_POST["CSR"];

    // Wir werden die Anfrage mit unserem eigenen
    // "certificate authority"-Zertifikat signieren. Sie können jedes beliebige
    // Zertifikat verwenden, um ein anderes zu signieren. Aber das Ganze ist
    // ziemlich nutzlos, solange die Software/Benutzer, die dieses neu signierte
    // Zertifikat nutzen werden, dem signierenden Zertifikat nicht vertrauen.

    // Wir benötigen unser CA-Zertifikat und dessen privaten Schlüssel
    $cacert = "file://path/to/ca.crt";
    $privkey = array("file://path/to/ca.key", "your_ca_key_passphrase");

    $usercert = openssl_csr_sign($csrdata, $cacert, $privkey, 365, array('digest_alg'=>'sha256') );

    // Jetzt zeigen wir das generierte Zertifikat an, damit die Benutzer es
    // kopieren und in ihre lokale Konfiguration einfügen können (wie z.B. eine
    // Datei, die das Zertifikat für ihren SSL-Server enthalten soll.
    openssl_x509_export($usercert, $certout);
    echo $certout;

    // Anzeigen aller aufgetretenen Fehler
    while (($e = openssl_error_string()) !== false) {
        echo $e . "\n";
    }
    ?>

# openssl_decrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_decrypt — Entschlüsselt Daten

### Beschreibung

function openssl_decrypt(
string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
?string `$tag` = `null`,
string `$aad` = ""
): string|false

Entschlüsselt eine unbearbeitete oder base64-kodierte Zeichenkette mit der angegebenen Methode und der angegebenen Passphrase.

### Parameter-Liste

`data`

  Die zu entschlüsselnde verschlüsselte Nachricht.

`cipher_algo`

  Die Verschlüsselungsmethode. openssl_get_cipher_methods() liefert eine Liste der verfügbaren Verschlüsselungsmethoden.

`passphrase`

  Die Passphrase. Ist die Passphrase kürzer als erwartet, wird sie stillschweigend mit `NUL`-Zeichen aufgefüllt; ist die Passphrase länger als erwartet, wird sie stillschweigend abgeschnitten.

  Achtung

  Für `passphrase` wird keine Funktion zur Ableitung eines Schlüssels verwendet, wie der Name vielleicht vermuten lässt. Die einzige Operation, die verwendet wird, ist das Auffüllen mit `NUL`-Zeichen oder das Abschneiden, wenn die Länge anders ist als erwartet.

`options`

  `options` kann einer der Werte `OPENSSL_RAW_DATA`, `OPENSSL_ZERO_PADDING` oder `OPENSSL_DONT_ZERO_PAD_KEY` sein.

`iv`

  Der Initialisierungsvektor (darf nicht `null` sein). Ist der IV kürzer als erwartet, wird er mit `NUL`-Zeichen aufgefüllt und eine Warnung ausgegeben; ist die Passphrase länger als erwartet, wird sie abgeschnitten und eine Warnung ausgegeben.

`tag`

  Das Authentifizierungskennzeichen im AEAD-Verschlüsselungsmodus. Ist es falsch, schlägt die Authentifizierung fehl und die Funktion gibt `false` zurück.

  Achtung

  Die Länge des Parameters `tag` wird von der Funktion nicht überprüft. Es liegt in der Verantwortung des Aufrufers sicherzustellen, dass die Länge des Kennzeichens mit der Länge des Kennzeichens übereinstimmt, das beim Aufruf von openssl_encrypt() zurückgegeben wurde. Andernfalls kann die Entschlüsselung auch dann erfolgreich sein, wenn das übergebene Kennzeichen nur dem Anfang des korrekten Kennzeichens entspricht.

`aad`

  Zusätzliche authentifizierte Daten.

### Rückgabewerte

Gibt bei Erfolg die entschlüsselte Zeichenkette zurück, Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn eine unbekannte Verschlüsselungsmethode über den Parameter `cipher_algo` übergeben wird.

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn eine leere Zeichenkette über den Parameter `iv` übergeben wird.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `tag` ist nun nullable.
7.1.0 | Die Parameter `tag` und `aad` wurden hinzugefügt.

### Siehe auch

- openssl_encrypt() - Verschlüsselt Daten

# openssl_dh_compute_key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_dh_compute_key — Computes shared secret for public value of remote DH public key and local DH key

### Beschreibung

function openssl_dh_compute_key(string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey `$private_key`): string|false

The shared secret returned by openssl_dh_compute_key() is often used as an encryption key to secretly communicate with a remote party. This is known as the Diffie-Hellman key exchange.

Achtung

It is important to use the same DH parameters for remote and local key pairs; otherwise, the generated secret between the two parties will not match.

> Hinweis: ECDH is only supported as of PHP 8.1.0 and OpenSSL 3.0.0.

### Parameter-Liste

`public_key`

  DH Public key of the remote party.

`private_key`

  A local DH private key, corresponding to the public key to be shared with the remote party.

### Rückgabewerte

Returns shared secret on successBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `private_key` accepts an OpenSSLAsymmetricKey now; previously, a Ressource of type `OpenSSL key` was accepted.

### Beispiele

Beispiel #1 Compute a shared secret

First generate a public/private DH keypair locally, and have the remote party do the same. We need to use the `openssl` command-line utility.

    # generate private/public key keypair
    openssl dhparam -out dhparam.pem 2048
    openssl genpkey -paramfile dhparam.pem -out privatekey.pem

    # extract public key only
    openssl pkey -in privatekey.pem -pubout -out publickey.pem

Next, send your public key to the remote party. Use the `openssl pkey` command to view the public key you will be sent from the remote party.

    openssl pkey -pubin -in remotepublickey.pem -text -noout

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    PKCS#3 DH Public-Key: (2048 bit)
        public-key:
            67:e5:e5:fa:e0:7b:0f:96:2c:dc:96:44:5f:50:02:
            9e:8d:c2:6c:04:68:b0:d1:1d:75:66:fc:63:f5:e3:
            42:30:b8:96:c1:45:cc:08:60:b4:21:3b:dd:ee:66:
            88:db:77:d9:1e:11:89:d4:5c:f2:7a:f2:f1:fe:1c:
            77:9d:6f:13:b8:b2:56:00:ef:cb:3b:60:79:74:02:
            98:f5:f9:8e:3e:b5:62:08:de:ca:8c:c3:40:4a:80:
            79:d5:43:06:17:a8:19:56:af:cc:95:5e:e2:32:2d:
            d2:14:7b:76:5a:9a:f1:3c:76:76:35:cc:7b:c1:a5:
            f4:39:e5:b6:ca:71:3f:7c:3f:97:e5:ab:86:c1:cd:
            0e:e6:ee:04:c9:e6:2d:80:7e:59:c0:49:eb:b6:64:
            4f:a8:f9:bb:a3:87:b3:3d:76:01:9e:2b:16:94:a4:
            37:30:fb:35:e2:63:be:23:90:b9:ef:3f:46:46:04:
            94:8f:60:79:7a:51:55:d6:1a:1d:f5:d9:7f:4a:3e:
            aa:ac:b0:d0:82:cc:c2:e0:94:e0:54:c1:17:83:0b:
            74:08:4d:5a:79:ae:ff:7f:1c:04:ab:23:39:4a:ae:
            87:83:55:43:ab:7a:7c:04:9d:20:80:bb:af:5f:16:
            a3:e3:20:b9:21:47:8c:f8:7f:a8:60:80:9e:61:77:
            36
     [...abbreviated...]

Use this public key as a parameter to openssl_dh_compute_key() in order to compute the shared secret.

    <?php
    $remote_public_key = '67e5e5fae07b0f962cdc96445f50029e8dc26c0468b0d11d7566fc63f5e34230b896c145cc0860b4213bddee6688db77d91e1189d45cf27af2f1fe1c779d6f13b8b25600efcb3b6079740298f5f98e3eb56208deca8cc3404a8079d5430617a81956afcc955ee2322dd2147b765a9af13c767635cc7bc1a5f439e5b6ca713f7c3f97e5ab86c1cd0ee6ee04c9e62d807e59c049ebb6644fa8f9bba387b33d76019e2b1694a43730fb35e263be2390b9ef3f464604948f60797a5155d61a1df5d97f4a3eaaacb0d082ccc2e094e054c117830b74084d5a79aeff7f1c04ab23394aae87835543ab7a7c049d2080bbaf5f16a3e320b921478cf87fa860809e617736';

    $local_priv_key = openssl_pkey_get_private('file://privatekey.pem');

    $shared_secret = openssl_dh_compute_key(hex2bin($remote_public_key), $local_priv_key);
    echo bin2hex($shared_secret)."\n";
    ?>

Beispiel #2 Generate a DH public/private keypair in php

First, generate the DH prime number

    openssl dhparam -out dhparam.pem 2048
    openssl dh -in dhparam.pem -noout  -text

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    PKCS#3 DH Parameters: (2048 bit)
            prime:
                00:a3:25:1e:73:3f:44:b9:2b:ee:f4:9d:9f:37:6a:
                4b:fd:1d:bd:f4:af:da:c8:10:77:59:41:c6:5f:73:
                d2:88:29:39:cd:1c:5f:c3:9f:0f:22:d2:9c:20:c1:
                e4:c0:18:03:b8:b6:d8:da:ad:3b:39:a6:da:8e:fe:
                12:30:e9:03:5d:22:ba:ef:18:d2:7b:69:f9:5b:cb:
                78:c6:0c:8c:6b:f2:49:92:c2:49:e0:45:77:72:b3:
                55:36:30:f2:40:17:89:18:50:03:fa:2d:54:7a:7f:
                34:4c:73:32:b6:88:14:51:14:be:80:57:95:e6:a3:
                f6:51:ff:17:47:4f:15:d6:0e:6c:47:53:72:2c:2a:
                4c:21:cb:7d:f3:49:97:c9:47:5e:40:33:7b:99:52:
                7e:7a:f3:52:27:80:de:1b:26:6b:40:bb:14:11:0b:
                fb:e6:d8:2f:cf:a0:06:2f:96:b9:1c:0b:b4:cb:d3:
                a6:62:9c:48:67:f6:81:f2:c6:ff:45:03:0a:9d:67:
                9d:ce:27:d9:6b:48:5d:ca:fb:c2:5d:84:9b:8b:cb:
                40:c7:a4:0c:8a:6e:f4:ab:ba:b6:10:c3:b8:25:4d:
                cf:60:96:f4:db:e8:00:1c:58:47:7a:fb:51:86:d1:
                22:d7:4e:94:31:7a:d5:da:3d:53:de:da:bb:64:8d:
                62:6b
            generator: 2 (0x2)

Prime and generator values ares passed as p and g into openssl_pkey_new()

    <?php
    $configargs = array();
    $configargs['p'] = hex2bin('00a3251e733f44b92beef49d9f376a4bfd1dbdf4afdac810775941c65f73d2882939cd1c5fc39f0f22d29c20c1e4c01803b8b6d8daad3b39a6da8efe1230e9035d22baef18d27b69f95bcb78c60c8c6bf24992c249e0457772b3553630f2401789185003fa2d547a7f344c7332b688145114be805795e6a3f651ff17474f15d60e6c4753722c2a4c21cb7df34997c9475e40337b99527e7af3522780de1b266b40bb14110bfbe6d82fcfa0062f96b91c0bb4cbd3a6629c4867f681f2c6ff45030a9d679dce27d96b485dcafbc25d849b8bcb40c7a40c8a6ef4abbab610c3b8254dcf6096f4dbe8001c58477afb5186d122d74e94317ad5da3d53dedabb648d626b');
    $configargs['g'] = hex2bin('02');
    $private_key = openssl_pkey_new(array('dh' => $configargs));
    openssl_pkey_export_to_file($private_key,'privatekey.pem',$passphrase='y0urp@s5phr@se');

    $details = openssl_pkey_get_details($private_key);
    $local_pub_key = $details['dh']['pub_key'];
    echo bin2hex($local_pub_key)."\n";//you can send your public key to the remote party

    $details = openssl_pkey_get_details(openssl_pkey_get_public("file://remotepublickey.pem"));
    $remote_public_key = $details['dh']['pub_key'];
    $shared_secret = openssl_dh_compute_key($remote_public_key, $private_key);
    echo bin2hex($shared_secret)."\n";
    ?>

### Siehe auch

- openssl_pkey_new() - Erzeugt einen neuen privaten Schlüssel
- openssl_pkey_get_details() - Liefert ein Array mit Schlüssel-Details
- openssl_pkey_get_private() - Liefert einen privaten Schlüssel
- openssl_pkey_get_public() - Extrahiert einen öffentlichen Schlüssel aus einem Zertifikat und bereitet diesen zur Verwendung vor

# openssl_digest

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_digest — Berechnet einen Hashwert (Digest)

### Beschreibung

function openssl_digest(string `$data`, string `$digest_algo`, bool `$binary` = `false`): string|false

Berechnet einen Hashwert (Digest) für die übergebenen Daten mit der angegebenen Methode und gibt das Ergebnis als unbearbeitete oder hexadezimal kodierte Zeichenkette zurück.

### Parameter-Liste

`data`

  Die Daten.

`digest_algo`

  Die zu verwendende Hash-Methode, z. B. "sha256"; openssl_get_md_methods() liefert eine Liste der verfügbaren Hash-Methoden.

`binary`

  Wird der Wert auf `true` gesetzt, werden die Daten unbearbeitet zurückgegeben, andernfalls hexadezimal kodiert.

### Rückgabewerte

Gibt bei Erfolg den berechneten Hashwert zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn eine unbekannte Signaturmethode über den Parameter `digest_algo` übergeben wird.

### Siehe auch

- openssl_get_md_methods() - Gets available digest methods

# openssl_encrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_encrypt — Verschlüsselt Daten

### Beschreibung

function openssl_encrypt(
#[\SensitiveParameter]string `$data`,
string `$cipher_algo`,
#[\SensitiveParameter]string `$passphrase`,
int `$options` = 0,
string `$iv` = "",
string `&$tag` = `null`,
string `$aad` = "",
int `$tag_length` = 16
): string|false

Verschlüsselt die Daten mit der angegebenen Methode und der angegebenen Passphrase. Die Rückgabe kann aus einer unbearbeiteten oder base64-kodierten Zeichenkette bestehen.

### Parameter-Liste

`data`

  Die zu verschlüsselnde Klartextnachricht.

`cipher_algo`

  Die Verschlüsselungsmethode. openssl_get_cipher_methods() liefert eine Liste der verfügbaren Verschlüsselungsmethoden.

`passphrase`

  Die Passphrase. Ist die Passphrase kürzer als erwartet, wird sie stillschweigend mit `NUL`-Zeichen aufgefüllt; ist die Passphrase länger als erwartet, wird sie stillschweigend abgeschnitten.

  Achtung

  Für `passphrase` wird keine Funktion zur Ableitung eines Schlüssels verwendet, wie der Name vielleicht vermuten lässt. Die einzige Operation, die verwendet wird, ist das Auffüllen mit `NUL`-Zeichen oder das Abschneiden, wenn die Länge anders ist als erwartet.

`options`

  `options` ist eine bitweise Verknüpfung der Flags `OPENSSL_RAW_DATA` und `OPENSSL_ZERO_PADDING` oder `OPENSSL_DONT_ZERO_PAD_KEY`.

`iv`

  Der Initialisierungsvektor (darf nicht `null` sein). Ist der IV kürzer als erwartet, wird er mit `NUL`-Zeichen aufgefüllt und eine Warnung ausgegeben; ist die Passphrase länger als erwartet, wird sie abgeschnitten und eine Warnung ausgegeben.

`tag`

  Das Authentifizierungskennzeichen das per Referenz übergeben wird, wenn der AEAD-Verschlüsselungsmodus (GCM oder CCM) verwendet wird.

`aad`

  Zusätzliche authentifizierte Daten.

`tag_length`

  Die Länge des Authentifizierungskennzeichens `tag`. Der Wert liegt beim GCM-Modus zwischen 4 und 16.

### Rückgabewerte

Gibt nach erfolgreicher Verarbeitung die verschlüsselte Zeichenkette zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn eine unbekannte Verschlüsselungsmethode über den Parameter `cipher_algo` übergeben wurde.

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn eine leere Zeichenkette über den Parameter `iv` übergeben wurde.

### Changelog

Version | Beschreibung
--- | ---
7.1.0 | Die Parameter `tag`, `aad` und `tag_length` wurden hinzugefügt.

### Beispiele

Beispiel #1 AES Authenticated Encryption im GCM-Modus, Beispiel für PHP 7.1+

    <?php
    // $key sollte zuvor auf eine kryptographisch sichere Weise erzeugt worden
    // sein, z. B. per openssl_random_pseudo_bytes
    $plaintext = "zu verschlüsselnde Nachricht";
    $cipher = "aes-128-gcm";
    if (in_array($cipher, openssl_get_cipher_methods()))
    {
        $ivlen = openssl_cipher_iv_length($cipher);
        $iv = openssl_random_pseudo_bytes($ivlen);
        $ciphertext = openssl_encrypt($plaintext, $cipher, $key, $options=0, $iv, $tag);
        // speichere $cipher, $iv und $tag für spätere Entschlüsselung
        $original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);
        echo $original_plaintext."\n";
    }
    ?>

Beispiel #2 AES Authenticated Encryption, Beispiel vor PHP 7.1

    <?php
    // $key sollte zuvor auf eine kryptographisch sichere Weise erzeugt worden
    // sein, z. B. per openssl_random_pseudo_bytes
    $plaintext = "zu verschlüsselnde Nachricht";
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = openssl_random_pseudo_bytes($ivlen);
    $ciphertext_raw = openssl_encrypt($plaintext, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $hmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
    $ciphertext = base64_encode( $iv.$hmac.$ciphertext_raw );

    // spätere Entschlüsselung ...
    $c = base64_decode($ciphertext);
    $ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
    $iv = substr($c, 0, $ivlen);
    $hmac = substr($c, $ivlen, $sha2len=32);
    $ciphertext_raw = substr($c, $ivlen+$sha2len);
    $original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
    $calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
    if (hash_equals($hmac, $calcmac)) // Rechenzeitangriff-sicherer Vergleich
    {
        echo $original_plaintext."\n";
    }
    ?>

### Siehe auch

- openssl_decrypt() - Entschlüsselt Daten

# openssl_error_string

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_error_string — Liefert eine OpenSSL-Fehlermeldung

### Beschreibung

function openssl_error_string(): string|false

openssl_error_string() gibt den letzten Fehlertext der OpenSSL-Bibliothek zurück. Fehler werden in einer Queue gesammelt, daher sollte diese Funktion mehrmals aufgerufen werden, um alle Informationen zu erhalten. Der letzte Fehler ist der zuletzt aufgetretene.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt eine Fehlermeldung als Zeichenkette zurück oder `false`, sofern keine weiteren Fehlermeldungen vorliegen.

### Beispiele

Beispiel #1 openssl_error_string()-Beispiel

    <?php
    // Annahme: Sie haben eine openssl-Funktion aufgerufen, die einen Fehler
    // verursacht hat.
    while ($msg = openssl_error_string())
        echo $msg . "<br />\n";
    ?>

# openssl_free_key

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_free_key — Gibt eine Schlüssel-Ressource frei

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function openssl_free_key(OpenSSLAsymmetricKey `$key`): void

openssl_free_key() gibt den Speicher des über den Parameter `key` identifizierten Schlüssels frei.

### Parameter-Liste

`key`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist nun veraltet, da sie keine Auswirkung mehr hat.
8.0.0 | `key` akzeptiert nun eine OpenSSLAsymmetricKey-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` akzeptiert.

# openssl_get_cert_locations

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_get_cert_locations — Retrieve the available certificate locations

### Beschreibung

function openssl_get_cert_locations(): array

openssl_get_cert_locations() returns an array with information about the available certificate locations that will be searched for SSL certificates.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array with the available certificate locations.

### Beispiele

Beispiel #1 openssl_get_cert_locations() example

    <?php
    var_dump(openssl_get_cert_locations());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(8) {
      ["default_cert_file"]=>
      string(21) "/usr/lib/ssl/cert.pem"
      ["default_cert_file_env"]=>
      string(13) "SSL_CERT_FILE"
      ["default_cert_dir"]=>
      string(18) "/usr/lib/ssl/certs"
      ["default_cert_dir_env"]=>
      string(12) "SSL_CERT_DIR"
      ["default_private_dir"]=>
      string(20) "/usr/lib/ssl/private"
      ["default_default_cert_area"]=>
      string(12) "/usr/lib/ssl"
      ["ini_cafile"]=>
      string(0) ""
      ["ini_capath"]=>
      string(0) ""
    }

# openssl_get_cipher_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_cipher_methods — Liefert die verfügbaren Verschlüsselungsmethoden

### Beschreibung

function openssl_get_cipher_methods(bool `$aliases` = `false`): array

Liefert eine Liste der verfügbaren Verschlüsselungsmethoden.

### Parameter-Liste

`aliases`

  Auf `true` setzen, wenn Aliase der Verschlüsselungsmethoden im zurückgegebenen array enthalten sein sollen.

### Rückgabewerte

Ein array der verfügbaren Verschlüsselungsmethoden. Es ist zu beachten, dass vor OpenSSL 1.1.1 die Verschlüsselungsmethoden in Groß- und Kleinschreibung zurückgegeben wurden; ab OpenSSL 1.1.1 werden nur die Varianten in Kleinschreibung zurückgegeben.

### Beispiele

Beispiel #1 Beispiel für openssl_get_cipher_methods()

Zeigt, wie die verfügbaren Verschlüsselungsmethoden aussehen können und welche Aliase verfügbar sein können.

    <?php
    $ciphers             = openssl_get_cipher_methods();
    $ciphers_and_aliases = openssl_get_cipher_methods(true);
    $cipher_aliases      = array_diff($ciphers_and_aliases, $ciphers);

    // Der ECB-Modus sollte vermieden werden
    $ciphers = array_filter( $ciphers, function($n) { return stripos($n,"ecb")===FALSE; } );

    // Spätestens seit August 2016 stuft OpenSSL die folgenden Verfahren als schwach ein: RC2, RC4, DES, 3DES, MD5-basierte
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"des")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc2")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"rc4")===FALSE; } );
    $ciphers = array_filter( $ciphers, function($c) { return stripos($c,"md5")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"des")===FALSE; } );
    $cipher_aliases = array_filter($cipher_aliases,function($c) { return stripos($c,"rc2")===FALSE; } );

    print_r($ciphers);
    print_r($cipher_aliases);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => aes-128-cbc
        [1] => aes-128-cbc-hmac-sha1
        [2] => aes-128-cbc-hmac-sha256
        [3] => aes-128-ccm
        [4] => aes-128-cfb
        [5] => aes-128-cfb1
        [6] => aes-128-cfb8
        [7] => aes-128-ctr
        [9] => aes-128-gcm
        [10] => aes-128-ocb
        [11] => aes-128-ofb
        [12] => aes-128-xts
        [13] => aes-192-cbc
        [14] => aes-192-ccm
        [15] => aes-192-cfb
        [16] => aes-192-cfb1
        [17] => aes-192-cfb8
        [18] => aes-192-ctr
        [20] => aes-192-gcm
        [21] => aes-192-ocb
        [22] => aes-192-ofb
        [23] => aes-256-cbc
        [24] => aes-256-cbc-hmac-sha1
        [25] => aes-256-cbc-hmac-sha256
        [26] => aes-256-ccm
        [27] => aes-256-cfb
        [28] => aes-256-cfb1
        [29] => aes-256-cfb8
        [30] => aes-256-ctr
        [32] => aes-256-gcm
        [33] => aes-256-ocb
        [34] => aes-256-ofb
        [35] => aes-256-xts
        [36] => aria-128-cbc
        [37] => aria-128-ccm
        [38] => aria-128-cfb
        [39] => aria-128-cfb1
        [40] => aria-128-cfb8
        [41] => aria-128-ctr
        [43] => aria-128-gcm
        [44] => aria-128-ofb
        [45] => aria-192-cbc
        [46] => aria-192-ccm
        [47] => aria-192-cfb
        [48] => aria-192-cfb1
        [49] => aria-192-cfb8
        [50] => aria-192-ctr
        [52] => aria-192-gcm
        [53] => aria-192-ofb
        [54] => aria-256-cbc
        [55] => aria-256-ccm
        [56] => aria-256-cfb
        [57] => aria-256-cfb1
        [58] => aria-256-cfb8
        [59] => aria-256-ctr
        [61] => aria-256-gcm
        [62] => aria-256-ofb
        [63] => bf-cbc
        [64] => bf-cfb
        [66] => bf-ofb
        [67] => camellia-128-cbc
        [68] => camellia-128-cfb
        [69] => camellia-128-cfb1
        [70] => camellia-128-cfb8
        [71] => camellia-128-ctr
        [73] => camellia-128-ofb
        [74] => camellia-192-cbc
        [75] => camellia-192-cfb
        [76] => camellia-192-cfb1
        [77] => camellia-192-cfb8
        [78] => camellia-192-ctr
        [80] => camellia-192-ofb
        [81] => camellia-256-cbc
        [82] => camellia-256-cfb
        [83] => camellia-256-cfb1
        [84] => camellia-256-cfb8
        [85] => camellia-256-ctr
        [87] => camellia-256-ofb
        [88] => cast5-cbc
        [89] => cast5-cfb
        [91] => cast5-ofb
        [92] => chacha20
        [93] => chacha20-poly1305
        [111] => id-aes128-CCM
        [112] => id-aes128-GCM
        [113] => id-aes128-wrap
        [114] => id-aes128-wrap-pad
        [115] => id-aes192-CCM
        [116] => id-aes192-GCM
        [117] => id-aes192-wrap
        [118] => id-aes192-wrap-pad
        [119] => id-aes256-CCM
        [120] => id-aes256-GCM
        [121] => id-aes256-wrap
        [122] => id-aes256-wrap-pad
        [124] => idea-cbc
        [125] => idea-cfb
        [127] => idea-ofb
        [137] => seed-cbc
        [138] => seed-cfb
        [140] => seed-ofb
        [141] => sm4-cbc
        [142] => sm4-cfb
        [143] => sm4-ctr
        [145] => sm4-ofb
    )
    Array
    (
        [36] => aes128
        [37] => aes128-wrap
        [38] => aes192
        [39] => aes192-wrap
        [40] => aes256
        [41] => aes256-wrap
        [69] => aria128
        [70] => aria192
        [71] => aria256
        [72] => bf
        [77] => blowfish
        [99] => camellia128
        [100] => camellia192
        [101] => camellia256
        [102] => cast
        [103] => cast-cbc
        [146] => idea
        [164] => seed
        [169] => sm4
    )

### Siehe auch

- openssl_get_md_methods() - Gets available digest methods

# openssl_get_curve_names

(PHP 7 >= 7.1.0, PHP 8)

openssl_get_curve_names — Gets list of available curve names for ECC

### Beschreibung

function openssl_get_curve_names(): array|false

Gets the list of available curve names for use in Elliptic curve cryptography (ECC) for public/private key operations. The two most widely standardized/supported curves are prime256v1 (NIST P-256) and secp384r1 (NIST P-384).

Approximate Equivalancies of AES, RSA, DSA and ECC Keysizes
AES Symmetric Keysize (Bits) | RSA and DSA Keysize (Bits) | ECC Keysize (Bits)
--- | --- | ---
80 | 1024 | 160
112 | 2048 | 224
128 | 3072 | 256
192 | 7680 | 384
256 | 15360 | 512

» NIST recommends using ECC curves with at least 256 bits.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array of available curve names, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 openssl_get_curve_names() example

    <?php
    $curve_names = openssl_get_curve_names();
    print_r($curve_names);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => secp112r1
        [1] => secp112r2
        [2] => secp128r1
        [3] => secp128r2
        [4] => secp160k1
        [5] => secp160r1
        [6] => secp160r2
        [7] => secp192k1
        [8] => secp224k1
        [9] => secp224r1
        [10] => secp256k1
        [11] => secp384r1
        [12] => secp521r1
        [13] => prime192v1
        [14] => prime192v2
        [15] => prime192v3
        [16] => prime239v1
        [17] => prime239v2
        [18] => prime239v3
        [19] => prime256v1
        [20] => sect113r1
        [21] => sect113r2
        [22] => sect131r1
        [23] => sect131r2
        [24] => sect163k1
        [25] => sect163r1
        [26] => sect163r2
        [27] => sect193r1
        [28] => sect193r2
        [29] => sect233k1
        [30] => sect233r1
        [31] => sect239k1
        [32] => sect283k1
        [33] => sect283r1
        [34] => sect409k1
        [35] => sect409r1
        [36] => sect571k1
        [37] => sect571r1
        [38] => c2pnb163v1
        [39] => c2pnb163v2
        [40] => c2pnb163v3
        [41] => c2pnb176v1
        [42] => c2tnb191v1
        [43] => c2tnb191v2
        [44] => c2tnb191v3
        [45] => c2pnb208w1
        [46] => c2tnb239v1
        [47] => c2tnb239v2
        [48] => c2tnb239v3
        [49] => c2pnb272w1
        [50] => c2pnb304w1
        [51] => c2tnb359v1
        [52] => c2pnb368w1
        [53] => c2tnb431r1
        [54] => wap-wsg-idm-ecid-wtls1
        [55] => wap-wsg-idm-ecid-wtls3
        [56] => wap-wsg-idm-ecid-wtls4
        [57] => wap-wsg-idm-ecid-wtls5
        [58] => wap-wsg-idm-ecid-wtls6
        [59] => wap-wsg-idm-ecid-wtls7
        [60] => wap-wsg-idm-ecid-wtls8
        [61] => wap-wsg-idm-ecid-wtls9
        [62] => wap-wsg-idm-ecid-wtls10
        [63] => wap-wsg-idm-ecid-wtls11
        [64] => wap-wsg-idm-ecid-wtls12
        [65] => Oakley-EC2N-3
        [66] => Oakley-EC2N-4
        [67] => brainpoolP160r1
        [68] => brainpoolP160t1
        [69] => brainpoolP192r1
        [70] => brainpoolP192t1
        [71] => brainpoolP224r1
        [72] => brainpoolP224t1
        [73] => brainpoolP256r1
        [74] => brainpoolP256t1
        [75] => brainpoolP320r1
        [76] => brainpoolP320t1
        [77] => brainpoolP384r1
        [78] => brainpoolP384t1
        [79] => brainpoolP512r1
        [80] => brainpoolP512t1
    )

# openssl_get_md_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_md_methods — Gets available digest methods

### Beschreibung

function openssl_get_md_methods(bool `$aliases` = `false`): array

Gets a list of available digest methods.

### Parameter-Liste

`aliases`

  Set to `true` if digest aliases should be included within the returned array.

### Rückgabewerte

An array of available digest methods.

### Beispiele

Beispiel #1 openssl_get_md_methods() example

Shows how the available digests might look, and also which aliases might be available.

    <?php
    $digests             = openssl_get_md_methods();
    $digests_and_aliases = openssl_get_md_methods(true);
    $digest_aliases      = array_diff($digests_and_aliases, $digests);

    print_r($digests);

    print_r($digest_aliases);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => DSA
        [1] => DSA-SHA
        [2] => MD2
        [3] => MD4
        [4] => MD5
        [5] => RIPEMD160
        [6] => SHA
        [7] => SHA1
        [8] => SHA224
        [9] => SHA256
        [10] => SHA384
        [11] => SHA512
        [12] => dsaEncryption
        [13] => dsaWithSHA
        [14] => ecdsa-with-SHA1
        [15] => md2
        [16] => md4
        [17] => md5
        [18] => ripemd160
        [19] => sha
        [20] => sha1
        [21] => sha224
        [22] => sha256
        [23] => sha384
        [24] => sha512
    )
    Array
    (
        [2] => DSA-SHA1
        [3] => DSA-SHA1-old
        [4] => DSS1
        [9] => RSA-MD2
        [10] => RSA-MD4
        [11] => RSA-MD5
        [12] => RSA-RIPEMD160
        [13] => RSA-SHA
        [14] => RSA-SHA1
        [15] => RSA-SHA1-2
        [16] => RSA-SHA224
        [17] => RSA-SHA256
        [18] => RSA-SHA384
        [19] => RSA-SHA512
        [28] => dsaWithSHA1
        [29] => dss1
        [32] => md2WithRSAEncryption
        [34] => md4WithRSAEncryption
        [36] => md5WithRSAEncryption
        [37] => ripemd
        [39] => ripemd160WithRSA
        [40] => rmd160
        [43] => sha1WithRSAEncryption
        [45] => sha224WithRSAEncryption
        [47] => sha256WithRSAEncryption
        [49] => sha384WithRSAEncryption
        [51] => sha512WithRSAEncryption
        [52] => shaWithRSAEncryption
        [53] => ssl2-md5
        [54] => ssl3-md5
        [55] => ssl3-sha1
    )

### Siehe auch

- openssl_digest() - Berechnet einen Hashwert (Digest)
- openssl_get_cipher_methods() - Liefert die verfügbaren Verschlüsselungsmethoden

# openssl_get_privatekey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_privatekey — Alias von openssl_pkey_get_private()

### Beschreibung

Diese Funktion ist ein Alias für: openssl_pkey_get_private().

# openssl_get_publickey

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_get_publickey — Alias von openssl_pkey_get_public()

### Beschreibung

Diese Funktion ist ein Alias für: openssl_pkey_get_public().

# openssl_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_open — Öffnet versiegelte Daten

### Beschreibung

function openssl_open(
string `$data`,
#[\SensitiveParameter]string `&$output`,
string `$encrypted_key`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string `$cipher_algo`,
?string `$iv` = `null`
): bool

openssl_open() öffnet (entschlüsselt) `data` mit einem Umschlagschlüssel, der mit `private_key` aus `encrypted_key` entschlüsselt wird. Die Entschlüsselung erfolgt mit `cipher_algo` und `iv`. Der IV wird nur benötigt, wenn die Verschlüsselungsmethode dies erfordert. Die Funktion füllt `output` mit den entschlüsselten Daten. Der Umschlagschlüssel wird normalerweise erzeugt, wenn die Daten mit einem öffentlichen Schlüssel versiegelt werden, der mit dem privaten Schlüssel verknüpft ist. Siehe openssl_seal() für weitere Informationen.

### Parameter-Liste

`data`

  Die versiegelten Daten.

`output`

  Bei erfolgreicher Ausführung werden die geöffneten Daten in diesem Parameter zurückgegeben.

`encrypted_key`

  Der verschlüsselte symmetrische Schlüssel, der mit `private_key` entschlüsselt werden kann.

`private_key`

  Der private Schlüssel, der für die Entschlüsselung von `encrypted_key` verwendet wird.

`cipher_algo`

  Die Verschlüsselungsmethode, die für die Entschlüsselung von `data` verwendet wird.

  Achtung

  Der Standardwert für PHP-Versionen vor 8.0 ist `'RC4'`, was als unsicher gilt. Es wird dringend empfohlen, explizit eine sichere Verschlüsselungsmethode anzugeben.

`iv`

  Der Initialisierungsvektor, der für die Entschlüsselung von `data` verwendet wird. Er wird benötigt, wenn die Verschlüsselungsmethode einen IV erfordert. Dies kann durch den Aufruf von openssl_cipher_iv_length() mit `cipher_algo` ermittelt werden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL key` oder `OpenSSL X.509 CSR` akzeptiert.
8.0.0 | Der Parameter `cipher_algo` ist nicht mehr optional.

### Beispiele

Beispiel #1 openssl_open()-Beispiel

    <?php

    // Holen des privaten Schlüssels aus der Datei private_key.pem
    $pkey = openssl_get_privatekey("file://private_key.pem");

    // Entschlüsseln der Daten und speichern in $open
    if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
        echo "Das sind die geöffneten Daten: ", $open;
    } else {
        echo "Öffnen der Daten nicht möglich!";
    }

    ?>

### Siehe auch

- openssl_seal() - Versiegelt (verschlüsselt) Daten

# openssl_password_hash

(PHP 8 >= 8.4.0)

openssl_password_hash — Create a password hash using OpenSSL's Argon2 implementation

### Beschreibung

function openssl_password_hash(string `$algo`, string `$password`, array `$options` = []): string

Creates a password hash using OpenSSL's Argon2 implementation. This is an alternative to password_hash() that uses OpenSSL as the backend, which may offer hardware acceleration on some platforms.

This function is only available when PHP is compiled with OpenSSL support that includes Argon2 (`HAVE_OPENSSL_ARGON2`).

### Parameter-Liste

`algo`

  The password hashing algorithm. Supported values: `"argon2id"` and `"argon2i"`.

`password`

  The user's password.

`options`

  An associative Array of options. Supported keys:

  - `memory_cost` - Maximum memory (in KiB) that may be used to compute the hash
  - `time_cost` - Maximum amount of time it may take to compute the hash
  - `threads` - Number of threads to use for computing the hash

### Rückgabewerte

Returns the password hash as a String.

### Fehler/Exceptions

Throws a ValueError if `algo` is not one of the supported values (`"argon2i"` or `"argon2id"`).

Throws an Error if the hashing operation fails for an unknown reason.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Function added.

### Beispiele

Beispiel #1 openssl_password_hash() example

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');
    echo $hash;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    $argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$hashvalue...

Beispiel #2 openssl_password_hash() with custom options

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password', [
        'memory_cost' => 65536,
        'time_cost'   => 4,
        'threads'     => 1,
    ]);
    ?>

### Siehe auch

- openssl_password_verify() - Verify a password against a hash using OpenSSL's Argon2 implementation
- password_hash() - Erstellt einen Passwort-Hash

# openssl_password_verify

(PHP 8 >= 8.4.0)

openssl_password_verify — Verify a password against a hash using OpenSSL's Argon2 implementation

### Beschreibung

function openssl_password_verify(string `$algo`, string `$password`, string `$hash`): bool

Verifies that a password matches a hash created by openssl_password_hash().

This function is only available when PHP is compiled with OpenSSL support that includes Argon2 (`HAVE_OPENSSL_ARGON2`).

### Parameter-Liste

`algo`

  The password hashing algorithm. Supported values: `"argon2id"` and `"argon2i"`.

`password`

  The user's password.

`hash`

  A hash created by openssl_password_hash().

### Rückgabewerte

Returns `true` if the password and hash match, or `false` otherwise.

### Fehler/Exceptions

Throws a ValueError if `algo` is not one of the supported values (`"argon2i"` or `"argon2id"`).

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Function added.

### Beispiele

Beispiel #1 openssl_password_verify() example

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');

    if (openssl_password_verify('argon2id', 'my-secret-password', $hash)) {
        echo 'Password matches.';
    } else {
        echo 'Password does not match.';
    }
    ?>

### Siehe auch

- openssl_password_hash() - Create a password hash using OpenSSL's Argon2 implementation
- password_verify() - Überprüft, ob ein Passwort und ein Hash zusammenpassen

# openssl_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

openssl_pbkdf2 — Generates a PKCS5 v2 PBKDF2 string

### Beschreibung

function openssl_pbkdf2(
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$key_length`,
int `$iterations`,
string `$digest_algo` = "sha1"
): string|false

openssl_pbkdf2() computes PBKDF2 (Password-Based Key Derivation Function 2), a key derivation function defined in PKCS5 v2.

### Parameter-Liste

`password`

  Password from which the derived key is generated.

`salt`
  PBKDF2 recommends a cryptographic salt of at least 128 bits (16 bytes).
`key_length`

  Length of desired output key.

`iterations`

  The number of iterations desired. » NIST recommends at least 1,000. As of 2023, OWASP recommends 600,000 iterations for PBKDF2-HMAC-SHA256 and 210,000 for PBKDF2-HMAC-SHA512.

`digest_algo`

  Optional hash or digest algorithm from openssl_get_md_methods(). Defaults to SHA-1. It is recommended to set it to SHA-256 or SHA-512.

### Rückgabewerte

Returns raw binary stringBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 openssl_pbkdf2() example

    <?php
    $password = 'password';
    $salt = openssl_random_pseudo_bytes(16);
    $keyLength = 20;
    $iterations = 600000;
    $generated_key = openssl_pbkdf2($password, $salt, $keyLength, $iterations, 'sha256');
    echo bin2hex($generated_key)."\n";
    echo base64_encode($generated_key)."\n";
    ?>

### Siehe auch

- hash_pbkdf2() - Generate a PBKDF2 key derivation of a supplied password
- openssl_get_md_methods() - Gets available digest methods

# openssl_pkcs12_export

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export — Exportiert eine PKCS#12-kompatible Zertifikats-Datei in eine Variable

### Beschreibung

function openssl_pkcs12_export(
OpenSSLCertificate|string `$certificate`,
string `&$output`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

openssl_pkcs12_export() speichert `certificate` als Zeichenkette im PKCS#12-Format in der Variable `output`.

### Parameter-Liste

`x509`

  Siehe Schlüssel-/Zertifikatsparameter für eine Auflistung der gültigen Werte.

`output`

  Bei Erfolg enthält diese Variable die PKCS#12-Zeichenkette.

`private_key`

  Der private Schlüsel zur PKCS#12-Datei. Siehe Schlüssel/Zertifikat-Parameter für eine Liste gültiger Werte.

`passphrase`

  Das Passwort zum Entschlüsseln der PKCS#12-Datei.

`options`

  Ein optionales Array; andere Schlüssel werden ignoriert.

  Key | Beschreibung
  --- | ---
  `"extracerts"` | Ein Array von zusätzlichen Zertifikaten oder ein einzelnes Zertifikat, das in der PKCS#12-Datei enthalten sein soll.
  `"friendly_name"` | Die Zeichenkette, die für das bereitgestellte Zertifikat und den Schlüssel verwendet werden soll.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` akzeptiert.
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

# openssl_pkcs12_export_to_file

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export_to_file — Exportiert in eine PKCS#12-kompatible Zertifikats-Datei

### Beschreibung

function openssl_pkcs12_export_to_file(
OpenSSLCertificate|string `$certificate`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
#[\SensitiveParameter]string `$passphrase`,
array `$options` = []
): bool

openssl_pkcs12_export_to_file() speichert `certificate` in der in `output_filename` angegebenen Datei im Format PKCS#12.

### Parameter-Liste

`x509`

  Siehe Schlüssel-/Zertifikatsparameter für eine Auflistung der gültigen Werte.

`output_filename`

  Der Pfad zur Ausgabe-Datei.

`private_key`

  Der private Schlüssel der PKCS#12-Datei. Siehe Schlüssel/Zertifikat-Parameter für eine Liste gültiger Werte.

`passphrase`

  Das Passwort, um die PKCS#12-Datei zu entschlüsseln.

`options`

  Ein optionales Array; andere Schlüssel werden ignoriert.

  Schlüssel | Beschreibung
  --- | ---
  `"extracerts"` | Ein Array von zusätzlichen Zertifikaten oder ein einzelnes Zertifikat, das in der PKCS#12-Datei enthalten sein soll.
  `"friendly_name"` | Zeichenkette, die für das bereitgestellte Zertifikat und den Schlüssel verwendet werden soll.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` akzeptiert.
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

# openssl_pkcs12_read

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_read — Parst eine PKCS#12-Zertifikats-Datei in ein Array

### Beschreibung

function openssl_pkcs12_read(string `$pkcs12`, array `&$certificates`, #[\SensitiveParameter]string `$passphrase`): bool

openssl_pkcs12_read() parst den im Parameter `pkcs12` übergebenen Inhalt der PKCS#12-Zertifikats-Datei in das im Parameter `certificates` angegebene Array.

### Parameter-Liste

`pkcs12`

  Der Inhalt der Zertifikats-Datei, nicht ihr Dateiname.

`certificates`

  Enthält im Erfolgsfall die Daten der Zertifikats-Datei als Array.

`passphrase`

  Das Passwort zum Entschlüsseln der PKCS#12-Datei.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 openssl_pkcs12_read()-Beispiel

    <?php
    if (!$cert_store = file_get_contents("/certs/file.p12")) {
        echo "Fehler: die Zertifikats-Datei kann nicht gelesen werden\n";
        exit;
    }

    if (openssl_pkcs12_read($cert_store, $cert_info, "my_secret_pass")) {
        echo "Zertifikatsinformationen\n";
        print_r($cert_info);
    } else {
        echo "Fehler: das Zertifikats-Datei kann nicht gelesen werden.\n";
        exit;
    }
    ?>

# openssl_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_decrypt — Entschlüsselt eine S/MIME-verschlüsselte Nachricht

### Beschreibung

function openssl_pkcs7_decrypt(
string `$input_filename`,
string `$output_filename`,
#[\SensitiveParameter]OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string|null `$private_key` = `null`
): bool

Die Funktion openssl_pkcs7_decrypt() entschlüsselt die mit S/MIME verschlüsselte Nachricht, die sich in der mit dem Parameter `input_filename` angegeben Datei befindet. Verwendet werden dafür das durch `certificate` angegebene Zertifikat und der damit verknüpfte private Schlüssel, angegeben durch `private_key`.

### Parameter-Liste

`input_filename`

`output_filename`

  Die entschlüsselte Nachricht wird in die Datei namens `output_filename` geschrieben.

`certificate`

`private_key`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509 CSR` akzeptiert.

### Beispiele

Beispiel #1 openssl_pkcs7_decrypt()-Beispiel

    <?php
    // Annahme: $cert enthält Ihr persönliches Zertifikat und
    // $key Ihr privates Schlüsselpaar. Sie erhalten eine S/MIME-Nachricht.
    $infilename = "encrypted.msg";  // diese Datei enthält ihre verschlüsselte Nachricht
    $outfilename = "decrypted.msg"; // stellen Sie sicher, dass Sie Schreibrechte haben!

    if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key)) {
        echo "entschlüsselt!";
    } else {
        echo "entschlüsseln fehlgeschlagen!";
    }
    ?>

# openssl_pkcs7_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_encrypt — Verschlüsselt eine S/MIME-Nachricht

### Beschreibung

function openssl_pkcs7_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$cipher_algo` = `OPENSSL_CIPHER_AES_128_CBC`
): bool

Die Funktion openssl_pkcs7_encrypt() nimmt den Inhalt der durch `input_filename` angegebenen Datei und verschlüsselt ihn unter Verwendung eines RC2-40-Bit-Schlüssels. Der Inhalt kann anschließend nur von den im Parameter `certificate` angegebenen Empfängern gelesen werden.

### Parameter-Liste

`input_filename`

`output_filename`

`certificate`

  Entweder ein einzelnes X.509-Zertifikat oder ein Array solcher Zertifikate.

`headers`

  `headers` ist ein Array von Headern, die den Daten nach der Verschlüsselung vorangestellt werden.

  Bei `headers` handelt es sich entweder um ein assoziatives Array mit den Header-Namen als Schlüssel, oder um ein indiziertes Array, bei dem jedes Element eine einzelne Headerzeile enthält.

`flags`

  Mittels `flags` können Optionen angegeben werden, die den Verschlüsselungsprozess beeinflussen. Siehe PKCS7-Konstanten.

`cipher_algo`

  Eine der Verschlüsselungskonstanten.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Standard-Verschlüsselungsalgorithmus (`cipher_algo`) ist jetzt AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`). Zuvor wurde PKCS7/CMS (`OPENSSL_CIPHER_RC2_40`) verwendet.
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` akzeptiert.

### Beispiele

Beispiel #1 openssl_pkcs7_encrypt()-Beispiel

    <?php
    // die zu verschlüsselnde Nachricht, die Sie Ihrem als "Nighthawk" bekanntem
    // Geheimagenten im Einsatz schicken wollen.
    // Sein Zertifikat liegt in der Datei nighthawk.pem vor
    $data = <<<EOD
    Nighthawk,

    Streng geheim (For Your Eyes Only)!

    Der Feind rückt näher. Treffen Sie mich im Cafè um 0830,
    um ihren gefälschten Pass abzuholen.

    HQ
    EOD;

    // Schlüssel laden
    $key = file_get_contents("nighthawk.pem");

    // Nachricht in Datei speichern
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);

    // Verschlüsseln
    if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
        array("To" => "nighthawk@example.com", // keyed syntax
              "From: HQ <hq@example.com>", // indexed syntax
              "Subject" => "Streng geheim!"))) {
        // Nachricht verschlüsselt - abschicken!
        exec(ini_get("sendmail_path") . " < enc.txt");
    }
    ?>

# openssl_pkcs7_read

(PHP 7 >= 7.2.0, PHP 8)

openssl_pkcs7_read — Export the PKCS7 file to an array of PEM certificates

### Beschreibung

function openssl_pkcs7_read(string `$data`, array `&$certificates`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`data`

  The string of data you wish to parse (p7b format).

`certificates`

  The array of PEM certificates from the p7b input data.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Get a PEM array from a P7B file

    <?php

    $file = 'certs.p7b';

    $f = file_get_contents($file);
    $p7 = array();
    $r = openssl_pkcs7_read($f, $p7);

    if ($r === false) {
        printf("ERROR: %s is not a proper p7b file".PHP_EOL, $file);
            for($e = openssl_error_string(), $i = 0; $e; $e = openssl_error_string(), $i++)
                printf("SSL l%d: %s".PHP_EOL, $i, $e);
        exit(1);
    }

    print_r($p7);
    ?>

### Siehe auch

- openssl_csr_sign() - Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat

# openssl_pkcs7_sign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_sign — Signiert eine S/MIME-Nachricht

### Beschreibung

function openssl_pkcs7_sign(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|string `$certificate`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
?array `$headers`,
int `$flags` = `PKCS7_DETACHED`,
?string `$untrusted_certificates_filename` = `null`
): bool

Die Funktion openssl_pkcs7_sign() nimmt den Inhalt der durch `input_filename` angegebenen Datei und signiert ihn. Verwendet werden dafür das Zertifikat, angegeben durch `certificate`, und der dazugehörige private Schlüssel `private_key`.

### Parameter-Liste

`input_filename`

  Die Eingabedatei, die digital signiert werden soll.

`output_filename`

  Die Datei, in die die digitale Signatur geschrieben werden soll.

`certificate`

  Das X.509-Zertifikat, das für die digitale Signierung von `input_filename` verwendet werden soll. Gültige Werte sind dem Abschnitt Schlüssel/Zertifikat-Parameter zu entnehmen.

`private_key`

  `private_key` ist der private Schlüssel, der zu `certificate` gehört. Gültige Werte sind dem Abschnitt Öffentliche/Private Schlüssel-Parameter zu entnehmen.

`headers`

  `headers` ist ein Array aus Headern, die den Daten vorangestellt werden, nachdem diese signiert wurden (weitere Informationen über das Format dieses Parameters sind der Dokumentation zu openssl_pkcs7_encrypt() zu entnehmen).

`flags`

  `flags` kann zur Änderung der Ausgabe verwendet werden - siehe die PKCS7-Konstanten.

`untrusted_certificates_filename`

  `untrusted_certificates_filename` gibt den Namen einer Datei an, die ein oder mehrere extra Zertifikate enthält, die in die Signatur mit eingefügt werden. Das kann zum Beispiel als Hilfe für einen Empfänger dienen, das von Ihnen verwendete Zertifikat zu überprüfen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509 CSR` akzeptiert.
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509 CSR` akzeptiert.

### Beispiele

Beispiel #1 openssl_pkcs7_sign()-Beispiel

    <?php
    // Die Nachricht,  die Sie signieren möchten, damit der Empfänger sicher
    // sein kann, dass diese Nachricht von Ihnen stammt.

    $data = <<<EOD

    Sie haben meine Erlaubnis 10.000 EUR für Essen auszugeben.

    Der CEO
    EOD;
    // Nachricht in einer Datei speichern
    $fp = fopen("msg.txt", "w");
    fwrite($fp, $data);
    fclose($fp);
    // Verschlüsseln
    if (openssl_pkcs7_sign("msg.txt", "signed.txt", "mycert.pem",
        array("file://mycert.pem", "mypassphrase"),
        array("To" => "joes@example.com", // keyed syntax
              "From: HQ <ceo@example.com>", // indexed syntax
              "Subject" => "Eyes only")
        )) {
        // Nachricht signiert - abschicken!
        exec(ini_get("sendmail_path") . " < signed.txt");
    }
    ?>

# openssl_pkcs7_verify

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_verify — Überprüft die Signatur einer mit S/MIME signierten Nachricht

### Beschreibung

function openssl_pkcs7_verify(
string `$input_filename`,
int `$flags`,
?string `$signers_certificates_filename` = `null`,
array `$ca_info` = [],
?string `$untrusted_certificates_filename` = `null`,
?string `$content` = `null`,
?string `$output_filename` = `null`
): bool|int

openssl_pkcs7_verify() liest die in der angegebenen Datei enthaltene S/MIME-Nachricht und untersucht die digitale Signatur.

### Parameter-Liste

`input_filename`

  Der Pfad zur Datei.

`flags`

  Mit dem Parameter `flags` wird beeinflusst, auf welche Art die Signatur verifiziert wird. Für mehr Informationen siehe PKCS7-Konstanten

`signers_certificates_filename`

  Wird der Parameter `signers_certificates_filename` angegeben, muss dies eine Zeichenkette sein, die den Namen einer Datei enthält, in der das Zertifikat der unterzeichnenden Person im PEM-Format gespeichert wird.

`ca_info`

  Wird der Parameter `ca_info` angegeben, muss er Informationen über die vertrauenswürdigen CA-Zertifikate enthalten, die für den Überprüfungsprozess verwendet werden. Für weitere Informationen siehe Überprüfung von Zertifikaten.

`untrusted_certificates_filename`

  Wird der Parameter `untrusted_certificates_filename` angegeben, ist es der Name einer Datei, die mehrere extra Zertifikate enthält, die als nicht vertrauenswürdige CAs verwendet werden.

`content`

  Mit `content` kann der Name einer Datei angegeben werden, die mit den verifizierten Daten gefüllt wird, wobei die Signaturinformationen entfernt werden.

`output_filename`

### Rückgabewerte

Gibt `true` zurück, wenn die Signatur verifiziert werden konnte, `false` wenn die Signatur nicht korrekt ist (die Daten wurden verändert oder das signierende Zertifikat ist ungültig), oder -1 im Falle eines Fehlers.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `signers_certificates_filename`, `untrusted_certificates_filename`, `Inhalt` und `Ausgabedateiname` sind nun vom Typ Nullable.
7.2.0 | Der Parameter `output_filename` wurde hinzugefügt.

### Anmerkungen

> Hinweis: Wie in RFC 2045 spezifiziert, dürfen die Zeilen im Parameter `input_filename` nicht länger als 76 Zeichen sein.

# openssl_pkey_derive

(PHP 7 >= 7.3.0, PHP 8)

openssl_pkey_derive — Computes shared secret for public value of remote and local DH or ECDH key

### Beschreibung

function openssl_pkey_derive(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, int `$key_length` = 0): string|false

openssl_pkey_derive() takes a set of a `public_key` and `private_key` and derives a shared secret, for either DH or EC keys.

### Parameter-Liste

`public_key`

  `public_key` is the public key for the derivation. See Public/Private Key parameters for a list of valid values.

`private_key`

  `private_key` is the private key for the derivation. See Public/Private Key parameters for a list of valid values.

`key_length`

  If not zero, will attempt to set the desired length of the derived secret.

  Achtung

  This parameter is deprecated and should not be used, as it does not work as expected. It never returns a secret longer than the size of the prime. If the desired length is smaller than the size of the prime, it truncates the length only for ECDH keys but fails for DH keys.

### Rückgabewerte

The derived secret on successBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The parameter `key_length` is now deprecated.

### Beispiele

Beispiel #1 openssl_pkey_derive() example

    <?php
    // Load in private key
    $priv = openssl_pkey_get_private("-----BEGIN PRIVATE KEY-----
    MIICJgIBADCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDy
    upojBIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2f
    VtCEMPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC
    0DCNt4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2
    197JGZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/
    HnyfVCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsC
    AQIEggEEAoIBAGwAYC2E81Y1U2Aox0U7u1+vBcbht/OO87tutMvc4NTLf6NLPHsW
    cPqBixs+3rSn4fADzAIvdLBmogjtiIZoB6qyHrllF/2xwTVGEeYaZIupQH3bMK2b
    6eUvnpuu4Ytksiz6VpXBBRMrIsj3frM+zUtnq8vKUr+TbjV2qyKR8l3eNDwzqz30
    dlbKh9kIhZafclHfRVfyp+fVSKPfgrRAcLUgAbsVjOjPeJ90xQ4DTMZ6vjiv6tHM
    hkSjJIcGhRtSBzVF/cT38GyCeTmiIA/dRz2d70lWrqDQCdp9ArijgnpjNKAAulSY
    CirnMsGZTDGmLOHg4xOZ5FEAzZI2sFNLlcw=
    -----END PRIVATE KEY-----
    ");

    // Load in public key
    $pub = openssl_pkey_get_public("-----BEGIN PUBLIC KEY-----
    MIICJDCCARcGCSqGSIb3DQEDATCCAQgCggEBAJLxRCaZ933uW+AXmabHFDDyupoj
    BIRlbmQLJZfigDaSA1f9YOTsIv+WwVFTX/J1mtCyx9uBcz0Nt2kmVwxWuc2fVtCE
    MPsmLsVXX7xRUFLpyX1Y1IYGBVXQOoOvLWYQjpZgnx47Pkh1Ok1+smffztfC0DCN
    t4KorWrbsPcmqBejXHN79KvWFjZmXOksRiNu/Bn76RiqvofC4z8Ri3kHXQG2197J
    GZzzFXHadGC3xbkg8UxsNbYhVMKbm0iANfafUH7/hoS9UjAVQYtvwe7YNiW/Hnyf
    VCrKwcc7sadd8Iphh+3lf5P1AhaQEAMytanrzq9RDXKBxuvpSJifRYasZYsCAQID
    ggEFAAKCAQAiCSBpxvGgsTorxAWtcAlSmzAJnJxFgSPef0g7OjhESytnc8G2QYmx
    ovMt5KVergcitztWh08hZQUdAYm4rI+zMlAFDdN8LWwBT/mGKSzRkWeprd8E7mvy
    ucqC1YXCMqmIwPySvLQUB/Dl8kgau7BLAnIJm8VP+MVrn8g9gghD0qRCgPgtEaDV
    vocfgnOU43rhKnIgO0cHOKtw2qybSFB8QuZrYugq4j8Bwkrzh6rdMMeyMl/ej5Aj
    c0wamOzuBDtXt0T9+Fx3khHaowjCc7xJZRgZCxg43SbqMWJ9lUg94I7+LTX61Gyv
    dtlkbGbtoDOnxeNnN93gwQZngGYZYciu
    -----END PUBLIC KEY-----
    ");

    // Outputs the hex version of the derived key
    echo bin2hex(openssl_pkey_derive($pub,$priv));

# openssl_pkey_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export — Speichert ein exportierbares Format eines Schlüssels in einer Zeichenkette

### Beschreibung

function openssl_pkey_export(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `&$output`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

openssl_pkey_export() exportiert `key` als eine PEM-kodierte Zeichenkette und speichert diese in `output` (welcher per Referenz übergeben wird).

> Hinweis: Die ordnungsgemäße Ausführung dieser Funktion setzt die Installation einer gültigen openssl.cnf-Datei voraus. Mehr Information hierzu sind im Abschnitt Installation zu finden.

### Parameter-Liste

`key`

`output`

`passphrase`

  Der Schlüssel wird optional von einer `passphrase` geschützt.

`options`

  `options` können Sie verwenden, um den Export feiner abzustimmen. Sie können damit Optionen für die OpenSSL-Konfigurationsdatei bestimmen und/oder überschreiben. Weitere Informationen über `options` sind der Dokumentation zu openssl_csr_new() entnehmen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

# openssl_pkey_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export_to_file — Speichert einen Schlüssel in einem exportierbaren Format in einer Datei

### Beschreibung

function openssl_pkey_export_to_file(
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$key`,
string `$output_filename`,
#[\SensitiveParameter]?string `$passphrase` = `null`,
?array `$options` = `null`
): bool

openssl_pkey_export_to_file() speichert den ASCII-verschlüsselten (PEM-kodierten) Schlüssel `key` in der in `output_filename` angegebenen Datei.

> Hinweis: Die ordnungsgemäße Ausführung dieser Funktion setzt die Installation einer gültigen openssl.cnf-Datei voraus. Mehr Information hierzu sind im Abschnitt Installation zu finden.

### Parameter-Liste

`key`

`output_filename`

  Der Pfad zur Ausgabedatei.

`passphrase`

  Der Schlüssel wird optional von einer `passphrase` geschützt.

`options`

  `options` können Sie verwenden, um den Export feiner abzustimmen. Sie können damit Optionen für die OpenSSL-Konfigurationsdatei bestimmen und/oder überschreiben. Weitere Informationen über `options` sind der Dokumentation zu openssl_csr_new() zu entnehmen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

# openssl_pkey_free

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_free — Gibt einen privaten Schlüssel frei

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function openssl_pkey_free(OpenSSLAsymmetricKey `$key`): void

> Hinweis:

> Diese Funktion hat keine Auswirkung. Vor PHP 8.0.0 wurde sie verwendet, um die Ressource zu schließen.

Diese Funktion gibt einen privaten Schlüssel frei, der mittels openssl_pkey_new() erstellt wurde.

### Parameter-Liste

`key`

  Die Ressource, die den Schlüssel enthält.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist nun veraltet, da sie keine Auswirkung mehr hat.
8.0.0 | `key` akzeptiert nun eine OpenSSLAsymmetricKey-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` akzeptiert.

# openssl_pkey_get_details

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_pkey_get_details — Liefert ein Array mit Schlüssel-Details

### Beschreibung

function openssl_pkey_get_details(OpenSSLAsymmetricKey `$key`): array|false

Diese Funktion gibt die Schlüssel-Details zurück (Bits, Schlüssel, Typ).

### Parameter-Liste

`key`

  Die Ressource, die den Schlüssel enthält.

### Rückgabewerte

Gibt bei Erfolg ein Array mit den Schlüssel-Details zurück oder `false` im Fehlerfall. Das zurückgegebene Array enthält die Indizes `bits` (Anzahl der Bits), `key` (der öffentliche Schlüssel als Zeichenkette) und `type` (Typ des Schlüssels, eine der Konstanten `OPENSSL_KEYTYPE_RSA`, `OPENSSL_KEYTYPE_DSA`, `OPENSSL_KEYTYPE_DH`, `OPENSSL_KEYTYPE_EC`, `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, `OPENSSL_KEYTYPE_ED448` oder -1 für einen unbekannten Typ).

In Abhängigkeit vom verwendeten Schlüssel-Typ können zusätzliche Details zurückgegeben werden. Es ist zu beachten, dass manche Elemente u.U. nicht immer verfügbar sind.

- `OPENSSL_KEYTYPE_RSA`: ein zusätzlicher Array-Schlüssel mit dem Namen `"rsa"`, der die Schlüssel-Daten enthält, wird zurückgegeben.

  Schlüssel | Beschreibung
  --- | ---
  `"n"` | Modul
  `"e"` | Öffentlicher Exponent
  `"d"` | Privater Exponent
  `"p"` | Primzahl 1
  `"q"` | Primzahl 2
  `"dmp1"` | Exponent 1, d mod (p-1)
  `"dmq1"` | Exponent 2, d mod (q-1)
  `"iqmp"` | Koeffizient, (Kehrwert von q) mod p

- `OPENSSL_KEYTYPE_DSA`: ein zusätzlicher Array-Schlüssel mit dem Namen `"dsa"`, der die Schlüssel-Daten enthält, wird zurückgegeben.

  Schlüssel | Beschreibung
  --- | ---
  `"p"` | Primzahl (öffentlich)
  `"q"` | 160-bit Unterprimzahl, q | p-1 (öffentlich)
  `"g"` | Generator der Untergruppe (öffentlich)
  `"priv_key"` | privater Schlüssel
  `"pub_key"` | öffentlicher Schlüssel y = g^x

- `OPENSSL_KEYTYPE_DH`: ein zusätzlicher Array-Schlüssel mit dem Namen `"dh"`, der die Schlüssel-Daten enthält, wird zurückgegeben.

  Schlüssel | Beschreibung
  --- | ---
  `"p"` | Primzahl (geteilt)
  `"g"` | Generator von Z_p (geteilt)
  `"priv_key"` | privater DH-Wert x
  `"pub_key"` | öffentlicher DH-Wert g^x

- `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448` oder `OPENSSL_KEYTYPE_ED448`: ein zusätzlicher Array-Schlüssel mit dem Namen `"x25519"`, `"ed25519"`, `"x448"`, bzw. `"ed448"`, der die Schlüssel-Daten enthält, wird zurückgegeben.

  Key | Beschreibung
  --- | ---
  `"priv_key"` | privater Schlüssel
  `"pub_key"` | öffentlicher Schlüssel

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Unterstützung für Schlüssel, die auf Curve25519 und Curve448 basieren, hinzugefügt. Insbesondere wurden die Felder `x25519`, `ed25519`, `x448` und `ed448` eingeführt.
8.0.0 | `key` akzeptiert nun eine OpenSSLAsymmetricKey-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` akzeptiert.

# openssl_pkey_get_private

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_private — Liefert einen privaten Schlüssel

### Beschreibung

function openssl_pkey_get_private(#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`, #[\SensitiveParameter]?string `$passphrase` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_get_private() parst `private_key` und bereitet ihn zur Verwendung durch andere Funktionen vor.

### Parameter-Liste

`private_key`

  Als `private_key` kann angegeben werden:

  1. Eine Zeichenkette im Format file://path/to/file.pem. Die angegebene Datei muss ein PEM-kodiertes Zertifikat und/oder einen privaten Schlüssel enthalten.
  2. Ein privater Schlüssel im PEM-Format.
`passphrase`

  Der optionale Parameter `passphrase` muss angegeben werden, falls der Schlüssel selbst verschlüsselt ist (durch eine Passphrase geschützt).

### Rückgabewerte

Gibt bei Erfolg eine OpenSSLAsymmetricKey-Instanz zurück oder `false`, wenn ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Bei Erfolg gibt diese Funktion nun eine OpenSSLAsymmetricKey-Instanz zurück; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` zurückgegeben.
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.
8.0.0 | `passphrase` ist nun ein Nullable-Typ.

# openssl_pkey_get_public

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_public — Extrahiert einen öffentlichen Schlüssel aus einem Zertifikat und bereitet diesen zur Verwendung vor

### Beschreibung

function openssl_pkey_get_public(OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): OpenSSLAsymmetricKey|false

openssl_pkey_get_public() extrahiert den öffentlichen Schlüssel aus `public_key` und bereitet ihn für die Verwendung durch andere Funktionen vor.

### Parameter-Liste

`public_key`

  `public_key` kann folgendes sein:

  1. Eine OpenSSLAsymmetricKey-Instanz.
  2. Eine Zeichenkette im Format file://path/to/file.pem. Die angegebene Datei muss ein PEM-kodiertes Zertifikat und/oder einen öffentlichen Schlüssel enthalten.
  3. Ein öffentlicher Schlüssel im PEM-Format.

### Rückgabewerte

Gibt bei Erfolg eine OpenSSLAsymmetricKey-Instanz zurück oder `false`, wenn ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Bei Erfolg gibt diese Funktion nun eine OpenSSLAsymmetricKey-Instanz zurück; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` zurückgegeben.
8.0.0 | `public_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

# openssl_pkey_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_new — Erzeugt einen neuen privaten Schlüssel

### Beschreibung

function openssl_pkey_new(?array `$options` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_new() erzeugt einen neuen privaten Schlüssel. Wie man den öffentlichen Teil des Schlüssels erhält, wird in einem Beispiel unten gezeigt.

> Hinweis: Die ordnungsgemäße Ausführung dieser Funktion setzt die Installation einer gültigen openssl.cnf-Datei voraus. Mehr Information hierzu sind im Abschnitt Installation zu finden.

### Parameter-Liste

`options`

  Die Schlüsselerzeugung kann mit `options` feiner abgestimmt werden (z. B. durch die Angabe der verwendeten Bits oder Parameter). Diese Optionen können entweder Algorithmus-spezifische Parameter sein, die bei der Schlüsselerzeugung verwendet werden, oder generische Optionen, die auch bei der Erzeugung eines CSR verwendet werden, wenn sie nicht angegeben werden. Weitere Informationen über die Verwendung von `options` für ein CSR sind der Dokumentation zu openssl_csr_new() zu entnehmen. Von diesen Optionen werden nur `private_key_bits`, `private_key_type`, `curve_name`, und `config` für die Schlüsselerzeugung verwendet. Die Algorithmus-spezifischen Optionen werden verwendet, wenn das assoziative Array einen der spezifischen Schlüssel enthält.

  - Der Schlüssel `"rsa"` zur Einstellung der RSA-Parameter.

    Optionen | Typ | Format | Erforderlich | Beschreibung
    --- | --- | --- | --- | ---
    `"n"` | string | Binärzahl | ja | Modul
    `"e"` | string | Binärzahl | nein | öffentlicher Exponent
    `"d"` | string | Binärzahl | ja | privater Exponent
    `"p"` | string | Binärzahl | nein | Primzahl 1
    `"q"` | string | Binärzahl | nein | Primzahl 2
    `"dmp1"` | string | Binärzahl | nein | Exponent1, d mod (p-1)
    `"dmq1"` | string | Binärzahl | nein | Exponent2, d mod (q-1)
    `"iqmp"` | string | Binärzahl | nein | Koeffizient, (Inverse von q) mod p

  - Der Schlüssel `"dsa"` zur Einstellung der DSA-Parameter.

    Optionen | Typ | Format | Erforderlich | Beschreibung
    --- | --- | --- | --- | ---
    `"p"` | string | Binärzahl | nein | Primzahl (öffentlich)
    `"q"` | string | Binärzahl | nein | 160-Bit Unterprimzahl (Subprime), q | p-1 (öffentlich)
    `"g"` | string | Binärzahl | nein | Generator der Untergruppe (öffentlich)
    `"priv_key"` | string | PEM-Schlüssel | nein | privater Schlüssel x
    `"pub_key"` | string | PEM-Schlüssel | nein | öffentlicher Schlüssel y = g^x

  - Der Schlüssel `"rsa"` zur Einstellung der RSA-Parameter.

    Optionen | Typ | Format | Erforderlich | Beschreibung
    --- | --- | --- | --- | ---
    `"p"` | string | Binärzahl | nein | Primzahl (gemeinsam genutzt)
    `"g"` | string | Binärzahl | nein | Generator von Z_p (gemeinsam genutzt)
    `"priv_key"` | string | PEM-Schlüssel | nein | privater DH-Wert x
    `"pub_key"` | string | PEM-Schlüssel | nein | öffentlicher DH-Wert g^x

  - Der Schlüssel `"ec"` für die Parameter der elliptischen Kurve

    Optionen | Typ | Format | Erforderlich | Beschreibung
    --- | --- | --- | --- | ---
    `"curve_name"` | string | Name | nein | Name der Kurve, siehe openssl_get_curve_names()
    `"p"` | string | Binärzahl | nein | Primzahl des Feldes (mathematisch: Körpers) für die Kurve über Fp
    `"a"` | string | Binärzahl | nein | Koeffizient a der Kurve für Fp: y^2 mod p = x^3 + ax + b mod p
    `"b"` | string | Binärzahl | nein | Koeffizient b der Kurve für Fp: y^2 mod p = x^3 + ax + b mod p
    `"seed"` | string | Binärzahl | nein | optionaler Zufallszahlen-Seed für die Generierung von Koeffizient b
    `"generator"` | string | binär kodierter Punkt | nein | Generatorpunkt der Kurve
    `"g_x"` | string | Binärzahl | nein | x-Koordinate des Generatorpunkts
    `"g_y"` | string | Binärzahl | nein | y-Koordinate des Generatorpunkts
    `"cofactor"` | string | Binärzahl | nein | Kurvenkoeffizient
    `"order"` | string | Binärzahl | nein | Ordnung der Kurve
    `"x"` | string | Binärzahl | nein | x-Koordinate (öffentlich)
    `"y"` | string | Binärzahl | nein | y-Koordinate (öffentlich)
    `"d"` | string | Binärzahl | nein | privater Schlüssel

  - Die Schlüssel `"x25519"`, `"x448"`, `"ed25519"` und `"ed448"` für die Curve25519- und Curve448-Parameter.

    Optionen | Typ | Format | Erforderlich | Beschreibung
    --- | --- | --- | --- | ---
    `"priv_key"` | string | PEM-Schlüssel | nein | privater Schlüssel
    `"pub_key"` | string | PEM-Schlüssel | nein | öffentlicher Schlüssel

### Rückgabewerte

Gibt bei Erfolg eine OpenSSLAsymmetricKey-Instanz zurück oder `false`, wenn ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Unterstützung für Schlüssel, die auf Curve25519 und Curve448 basieren, wurde mit der Einführung der Felder `x25519`, `ed25519`, `x448` und `ed448` hinzugefügt.
8.3.0 | Unterstützung für die Generierung von EC-Schlüsseln mit benutzerdefinierten EC-Parametern hinzugefügt. Insbesondere mit der Einführung der EC-Optionen: `p`, `a`, `b`, `seed`, `generator`, `g_x`, `g_y`, `cofactor` und `order`.
8.0.0 | Bei Erfolg gibt diese Funktion nun eine OpenSSLAsymmetricKey-Instanz zurück; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` zurückgegeben.
7.1.0 | Der Parameter `options` wurde um den Schlüssel `curve_name` erweitert, damit EC-Schlüssel basierend auf Algorithmen für elliptische Kurven erzeugt werden können.

### Beispiele

Beispiel #1 Aus einem privaten Schlüssel den öffentlichen Schlüssel gewinnen

    <?php

    $private_key = openssl_pkey_new();

    $public_key_pem = openssl_pkey_get_details($private_key)['key'];
    echo $public_key_pem, PHP_EOL;

    $public_key = openssl_pkey_get_public($public_key_pem);
    var_dump($public_key);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    // Ausgabe vor PHP 8.0.0; Hinweis: Die Funktion gibt eine Ressource zurück
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    resource(6) of type (OpenSSL key)

    // Ausgabe seit PHP 8.0.0; Hinweis: Die Funktion gibt ein Objekt zurück
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    object(OpenSSLAsymmetricKey)#2 (0) {
    }

Beispiel #2 Erzeugen eines RSA-Schlüssels aus Parametern

    <?php

    $nhex = "BBF82F090682CE9C2338AC2B9DA871F7368D07EED41043A440D6B6F07454F51F" .
            "B8DFBAAF035C02AB61EA48CEEB6FCD4876ED520D60E1EC4619719D8A5B8B807F" .
            "AFB8E0A3DFC737723EE6B4B7D93A2584EE6A649D060953748834B2454598394E" .
            "E0AAB12D7B61A51F527A9A41F6C1687FE2537298CA2A8F5946F8E5FD091DBDCB";

    $ehex = "11";
    $dhex = "A5DAFC5341FAF289C4B988DB30C1CDF83F31251E0668B42784813801579641B2" .
            "9410B3C7998D6BC465745E5C392669D6870DA2C082A939E37FDCB82EC93EDAC9" .
            "7FF3AD5950ACCFBC111C76F1A9529444E56AAF68C56C092CD38DC3BEF5D20A93" .
            "9926ED4F74A13EDDFBE1A1CECC4894AF9428C2B7B8883FE4463A4BC85B1CB3C1";

    $phex = "EECFAE81B1B9B3C908810B10A1B5600199EB9F44AEF4FDA493B81A9E3D84F632" .
            "124EF0236E5D1E3B7E28FAE7AA040A2D5B252176459D1F397541BA2A58FB6599";

    $qhex = "C97FB1F027F453F6341233EAAAD1D9353F6C42D08866B1D05A0F2035028B9D86" .
            "9840B41666B42E92EA0DA3B43204B5CFCE3352524D0416A5A441E700AF461503";

    $dphex = "11";
    $dqhex = "11";
    $qinvhex = "b06c4fdabb6301198d265bdbae9423b380f271f73453885093077fcd39e2119f" .
               "c98632154f5883b167a967bf402b4e9e2e0f9656e698ea3666edfb25798039f7";

    $rsa= openssl_pkey_new([
        'rsa' => [
            'n' => hex2bin($nhex),
            'e' => hex2bin($ehex),
            'd' => hex2bin($dhex),
            'p' => hex2bin($phex),
            'q' => hex2bin($qhex),
            'dmp1' => hex2bin($dphex),
            'dmq1' => hex2bin($dqhex),
            'iqmp' => hex2bin($qinvhex),
        ],
    ]);
    $details = openssl_pkey_get_details($rsa);
    var_dump($details);

    ?>

# openssl_private_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_decrypt — Entschlüsselt Daten mit einem privaten Schlüssel

### Beschreibung

function openssl_private_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

openssl_private_decrypt() entschlüsselt `data`, das zuvor mit openssl_public_encrypt() verschlüsselt wurde, und speichert das Ergebnis in `decrypted_data`.

Mit dieser Funktion können beispielweise Daten entschlüsselt werden, die nur für einen bestimmten Empfänger gedacht sind.

### Parameter-Liste

`data`

`decrypted_data`

`private_key`

  `public_key` muss der öffentliche Schlüssel sein, der zu dem privaten Schlüssel gehört, mit dem die Daten verschlüsselt wurden.

`padding`

  `padding` kann eine der Konstanten `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING` und `OPENSSL_NO_PADDING` sein.

`digest_algo`
  Der Digest-Algorithmus für OAEP-Padding oder `null`, um den Standardalgorithmus zu verwenden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | Der optionale Parameter `digest_algo` wurde hinzugefügt.
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

### Siehe auch

- openssl_public_encrypt() - Verschlüsselt Daten mit einem öffentlichen Schlüssel
- openssl_public_decrypt() - Entschlüsselt Daten mit einem öffentlichen Schlüssel

# openssl_private_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_encrypt — Verschlüsselt Daten mit einem privaten Schlüssel

### Beschreibung

function openssl_private_encrypt(
#[\SensitiveParameter]string `$data`,
string `&$encrypted_data`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

openssl_private_encrypt() verschlüsselt `data` mit dem privaten Schlüssel `private_key`, und speichert das Ergebnis in `encrypted_data`. Verschlüsselte Daten können mit openssl_public_decrypt() entschlüsselt werden.

Diese Funktion kann z. B. verwendet werden, um Daten (oder deren Hashwert) zu signieren um damit sicherzustellen, dass diese Daten wirklich von einem bestimmten Sender stammen, und nicht von jemand anderem.

### Parameter-Liste

`data`

`encrypted_data`

`private_key`

  `public_key` muss der öffentliche Schlüssel sein, der zu dem privaten Schlüssel gehört, mit dem die Daten verschlüsselt wurden.

`padding`

  `padding` kann entweder `OPENSSL_PKCS1_PADDING` oder `OPENSSL_NO_PADDING` sein.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

### Siehe auch

- openssl_public_encrypt() - Verschlüsselt Daten mit einem öffentlichen Schlüssel
- openssl_public_decrypt() - Entschlüsselt Daten mit einem öffentlichen Schlüssel

# openssl_public_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_decrypt — Entschlüsselt Daten mit einem öffentlichen Schlüssel

### Beschreibung

function openssl_public_decrypt(
string `$data`,
#[\SensitiveParameter]string `&$decrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`
): bool

openssl_public_decrypt() entschlüsselt `data`, das zuvor mit openssl_private_encrypt() verschlüsselt wurde, und speichert das Ergebnis in `decrypted_data`.

Diese Funktion kann z. B. verwendet werden, um zu überprüfen, ob eine Nachricht wirklich vom Eigentümer des privaten Schlüssels geschrieben wurde.

### Parameter-Liste

`data`

`decrypted_data`

`public_key`

  `public_key` muss der öffentliche Schlüssel sein, der zu dem privaten Schlüssel gehört, mit dem die Daten verschlüsselt wurden.

`padding`

  `padding` kann entweder `OPENSSL_PKCS1_PADDING` oder `OPENSSL_NO_PADDING` sein.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `public_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

### Siehe auch

- openssl_private_encrypt() - Verschlüsselt Daten mit einem privaten Schlüssel
- openssl_private_decrypt() - Entschlüsselt Daten mit einem privaten Schlüssel

# openssl_public_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_encrypt — Verschlüsselt Daten mit einem öffentlichen Schlüssel

### Beschreibung

function openssl_public_encrypt(
#[\SensitiveParameter]string `$data`,
string `&$encrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

openssl_public_encrypt() verschlüsselt `data` mit dem öffentlichen Schlüssel `public_key`, und speichert das Ergebnis in `encrypted_data`. Verschlüsselte Daten können mittels openssl_private_decrypt() entschlüsselt werden.

Diese Funktion kann beispielsweise verwendet werden, um eine Nachricht zu verschlüsseln, die dann nur vom Eigentümer des privaten Schlüssels gelesen werden kann. Sie kann ebenfalls verwendet werden, um Daten sicher in einer Datenbank zu speichern.

### Parameter-Liste

`data`

`encrypted_data`

  Hier werden die verschlüsselten Daten abgelegt.

`public_key`

  `public_key` muss der öffentliche Schlüssel sein, der zu dem privaten Schlüssel gehört, mit dem die Daten verschlüsselt wurden.

`padding`

  `padding` kann entweder `OPENSSL_PKCS1_PADDING`, `OPENSSL_SSLV23_PADDING`, `OPENSSL_PKCS1_OAEP_PADDING` oder `OPENSSL_NO_PADDING` sein.

`digest_algo`
  Der Digest-Algorithmus für OAEP-Padding oder `null`, um den Standardalgorithmus zu verwenden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | Der optionale Parameter `digest_algo` wurde hinzugefügt.
8.0.0 | `public_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

### Siehe auch

- openssl_private_encrypt() - Verschlüsselt Daten mit einem privaten Schlüssel
- openssl_private_decrypt() - Entschlüsselt Daten mit einem privaten Schlüssel

# openssl_random_pseudo_bytes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_random_pseudo_bytes — Generate a pseudo-random string of bytes

### Beschreibung

function openssl_random_pseudo_bytes(int `$length`, bool `&$strong_result` = `null`): string

Generates a string of pseudo-random bytes, with the number of bytes determined by the `length` parameter.

It also indicates if a cryptographically strong algorithm was used to produce the pseudo-random bytes, and does this via the optional `strong_result` parameter. It's rare for this to be `false`, but some systems may be broken or old.

### Parameter-Liste

`length`

  The length of the desired string of bytes. Must be a positive integer less than or equal to `2147483647`. PHP will try to cast this parameter to a non-null integer to use it.

`strong_result`

  If passed into the function, this will hold a bool value that determines if the algorithm used was "cryptographically strong", e.g., safe for usage with GPG, passwords, etc. `true` if it did, otherwise `false`

### Rückgabewerte

Returns the generated String of bytes.

### Fehler/Exceptions

openssl_random_pseudo_bytes() throws an Exception on failure.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `strong_result` is nullable now.
7.4.0 | The function no longer returns `false` on failure, but throws an Exception instead.

### Beispiele

Beispiel #1 openssl_random_pseudo_bytes() example

    <?php
    for ($i = 1; $i <= 4; $i++) {
        $bytes = openssl_random_pseudo_bytes($i, $cstrong);
        $hex   = bin2hex($bytes);

        echo "Lengths: Bytes: $i and Hex: " . strlen($hex) . PHP_EOL;
        var_dump($hex);
        var_dump($cstrong);
        echo PHP_EOL;
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Lengths: Bytes: 1 and Hex: 2
    string(2) "42"
    bool(true)

    Lengths: Bytes: 2 and Hex: 4
    string(4) "dc6e"
    bool(true)

    Lengths: Bytes: 3 and Hex: 6
    string(6) "288591"
    bool(true)

    Lengths: Bytes: 4 and Hex: 8
    string(8) "ab86d144"
    bool(true)

### Siehe auch

- random_bytes() - Get cryptographically secure random bytes
- bin2hex() - Wandelt Binär-Daten in ihre hexadezimale Entsprechung um
- crypt() - Einweg-String-Hashing
- random_int() - Get a cryptographically secure, uniformly selected integer

# openssl_seal

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_seal — Versiegelt (verschlüsselt) Daten

### Beschreibung

function openssl_seal(
#[\SensitiveParameter]string `$data`,
string `&$sealed_data`,
array `&$encrypted_keys`,
array `$public_key`,
string `$cipher_algo`,
string `&$iv` = `null`
): int|false

Die Funktion openssl_seal() versiegelt (verschlüsselt) `data` unter Verwendung des angegebenen `cipher_algo` mit einem zufällig erzeugten geheimen Schlüssel. Dieser Schlüssel wird dann mit jedem öffentlichen Schlüssel aus dem Array `public_key` verschlüsselt und jeder verschlüsselte Umschlagschlüssel wird in `encrypted_keys` zurückgegeben. Auf diese Weise können versiegelte Daten an mehrere Empfänger gesendet werden (sofern deren öffentliche Schlüssel verfügbar sind). Jeder Empfänger muss sowohl die versiegelten Daten als auch den entsprechenden Umschlagschlüssel erhalten, der mit dem öffentlichen Schlüssel des Empfängers versiegelt wurde. Der IV (Initialisierungsvektor) wird erzeugt, und sein Wert wird in `iv` zurückgegeben.

### Parameter-Liste

`data`

  Die zu versiegelten Daten.

`sealed_data`

  Die versiegelten Daten.

`encrypted_keys`

  Das Array verschlüsselter Schlüssel.

`public_key`

  Das Array von OpenSSLAsymmetricKey-Instanzen, das öffentliche Schlüssel enthält.

`cipher_algo`

  Die Verschlüsselungsmethode.

  Achtung

  Der Standardwert für PHP-Versionen vor 8.0 ist `'RC4'`, was als unsicher gilt. Es wird dringend empfohlen, explizit eine sichere Verschlüsselungsmethode anzugeben.

`iv`

  Der Initialisierungsvektor für die Entschlüsselung von `data`. Er wird benötigt, wenn die Verschlüsselungsmethode einen IV erfordert. Dies kann durch den Aufruf von openssl_cipher_iv_length() mit `cipher_algo` ermittelt werden.

  Achtung

  Der IV kann nicht explizit festgelegt werden. Jeder darin eingestellte Wert wird durch einen zufällig generierten Wert überschrieben.

### Rückgabewerte

Gibt bei Erfolg die Länge der versiegelten Daten zurück; in diesem Fall sind die versiegelten Daten in `sealed_data` enthalten und `encrypted_keys` enthält die Umschlagschlüssel. Wenn ein Fehler aufgetreten ist, gibt die Funktion `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `public_key` akzeptiert nun ein Array von OpenSSLAsymmetricKey-Instanzen; vorher wurde ein Array von Ressourcen vom Typ `OpenSSL key` akzeptiert.
8.0.0 | Der Parameter `cipher_algo` ist nicht mehr optional.
8.0.0 | `iv` ist nun ein Nullable-Typ.

### Beispiele

Beispiel #1 openssl_seal()-Beispiel

    <?php
    // Annahme: $data enthält die zu versiegelnden Daten
    $data = "test";

    // Holen der öffentlichen Schlüssel
    $pk1 = openssl_get_publickey("file://cert1.pem");
    $pk2 = openssl_get_publickey("file://cert2.pem");

    // Versiegeln der Nachricht, nur Besitzer von $pk1 und $pk2 können $sealed
    // mit den Schlüsseln $ekeys[0] bzw. $ekeys[1] entschlüsseln.
    if (openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2), 'AES256', $iv) > 0) {
        // Gegebenenfalls die Werte von $sealed und $iv speichern und später
        // in openssl_open verwenden
        echo "Erfolg\n";
    }
    ?>

### Siehe auch

- openssl_open() - Öffnet versiegelte Daten

# openssl_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_sign — Erzeugt eine Signatur

### Beschreibung

function openssl_sign(
string `$data`,
string `&$signature`,
#[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): bool

Die Funktion openssl_sign() errechnet die Signatur für die im Parameter `data` angegebenen Daten, indem sie unter Verwendung des privaten Schlüssels `private_key` eine kryptographische digitale Signatur erzeugt. Es ist zu beachten, dass die Daten selbst nicht verschlüsselt werden.

### Parameter-Liste

`data`

  Die zu verschlüsselnden Daten.

`signature`

  Nach erfolgreicher Ausführung wird die Signatur im Parameter `signature` zurückgegeben.

`private_key`

  OpenSSLAsymmetricKey - ein von openssl_get_privatekey() zurückgegebener Schlüssel.

  string - ein Schlüssel im PEM-Format.

`algorithm`

  int - einer dieser Signatur-Algorithmen.

  string - eine von openssl_get_md_methods() zurückgegebene gültige Zeichenkette, beispielsweise "sha256WithRSAEncryption" oder "sha384".

`padding`
  Das zu verwendende RSA-PSS-Padding.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | Der optionale Parameter `padding` wurde hinzugefügt.
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

### Beispiele

Beispiel #1 openssl_sign()-Beispiel

    <?php
    // Annahme: $data enthält die Daten, die signiert werden sollen

    // holen und vorbereiten des privaten Schlüssels aus einer Datei
    $pkeyid = openssl_pkey_get_private("file://src/openssl-0.9.6/demos/sign/key.pem");

    // errechnen der Signatur
    openssl_sign($data, $signature, $pkeyid);

    // löschen des Schlüssels aus dem Speicher
    openssl_free_key($pkeyid);
    ?>

Beispiel #2 openssl_sign()-Beispiel

    <?php
    // die zu verschlüssenlnden Daten
    $data = 'my data';

    // erzeuge einen neuen privaten und öffentlichen Schlüssel
    $new_key_pair = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    openssl_pkey_export($new_key_pair, $private_key_pem);

    $details = openssl_pkey_get_details($new_key_pair);
    $public_key_pem = $details['key'];

    // erzeuge die Signatur
    openssl_sign($data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);

    // für spätere Verwendung speichern
    file_put_contents('private_key.pem', $private_key_pem);
    file_put_contents('public_key.pem', $public_key_pem);
    file_put_contents('signature.dat', $signature);

    // Signatur überprüfen
    $r = openssl_verify($data, $signature, $public_key_pem, "sha256WithRSAEncryption");
    var_dump($r);
    ?>

### Siehe auch

- openssl_verify() - Überprüft eine Signatur

# openssl_spki_export

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export — Exports a valid PEM formatted public key signed public key and challenge

### Beschreibung

function openssl_spki_export(string `$spki`): string|false

Exports PEM formatted public key from encoded signed public key and challenge

### Parameter-Liste

`spki`

  Expects a valid signed public key and challenge

### Rückgabewerte

Returns the associated PEM formatted public key or `false` on failure.

### Fehler/Exceptions

Emits an `E_WARNING` level error if an invalid argument is passed via the `spki` parameter.

### Beispiele

Beispiel #1 openssl_spki_export() example

Extracts the associated PEM formatted public key or `null` on failure.

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');
    $pubKey = openssl_spki_export(preg_replace('/SPKAC=/', '', $spkac));

    if ($pubKey) {
        echo $pubKey;
    }
    ?>

Beispiel #2 openssl_spki_export() example from <keygen>

Extracts the associated PEM formatted public key issued from the <keygen> element

    <?php
    $spkac = openssl_spki_export(preg_replace('/SPKAC=/', '', $_POST['spkac']));
    if ($spkac != NULL) {
        echo $spkac;
    } else {
        echo "Extraction of pub key failed";
    }
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Siehe auch

- openssl_spki_new() - Generate a new signed public key and challenge
- openssl_spki_verify() - Verifies a signed public key and challenge
- openssl_spki_export_challenge() - Exports the challenge associated with a signed public key and challenge
- openssl_get_md_methods() - Gets available digest methods
- openssl_csr_new() - Erzeugt einen CSR
- openssl_csr_sign() - Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat

# openssl_spki_export_challenge

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export_challenge — Exports the challenge associated with a signed public key and challenge

### Beschreibung

function openssl_spki_export_challenge(string `$spki`): string|false

Exports challenge from encoded signed public key and challenge

### Parameter-Liste

`spki`

  Expects a valid signed public key and challenge

### Rückgabewerte

Returns the associated challenge string or `false` on failure.

### Fehler/Exceptions

Emits an `E_WARNING` level error if an invalid argument is passed via the `spki` parameter.

### Beispiele

Beispiel #1 openssl_spki_export_challenge() example

Extracts the associated challenge string or NULL on failure.

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $spkac));
    ?>

Beispiel #2 openssl_spki_export_challenge() example from <keygen>

Extracts the associated challenge string issued from the <keygen> element

    <?php
    $challenge = openssl_spki_export_challenge(preg_replace('/SPKAC=/', '', $_POST['spkac']));
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Siehe auch

- openssl_spki_new() - Generate a new signed public key and challenge
- openssl_spki_verify() - Verifies a signed public key and challenge
- openssl_spki_export() - Exports a valid PEM formatted public key signed public key and challenge
- openssl_get_md_methods() - Gets available digest methods
- openssl_csr_new() - Erzeugt einen CSR
- openssl_csr_sign() - Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat

# openssl_spki_new

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_new — Generate a new signed public key and challenge

### Beschreibung

function openssl_spki_new(#[\SensitiveParameter]OpenSSLAsymmetricKey `$private_key`, string `$challenge`, int `$digest_algo` = `OPENSSL_ALGO_MD5`): string|false

Generates a signed public key and challenge using specified hashing algorithm

### Parameter-Liste

`private_key`

  `private_key` should be set to a private key that was previously generated by openssl_pkey_new() (or otherwise obtained from the other openssl_pkey family of functions). The corresponding public portion of the key will be used to sign the CSR.

`challenge`

  The challenge associated to associate with the SPKAC

`digest_algo`

  The digest algorithm. See openssl_get_md_method().

### Rückgabewerte

Returns a signed public key and challenge string or `false` on failure.

### Fehler/Exceptions

Emits an `E_WARNING` level error if an unknown signature algorithm is passed via the `digest_algo` parameter.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `private_key` accepts an OpenSSLAsymmetricKey instance now; previously, a Ressource of type `OpenSSL key` was accepted.

### Beispiele

Beispiel #1 openssl_spki_new() example

Generate a new SPKAC with the default digest (MD5)

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'testing');

    if ($spkac !== NULL) {
        echo $spkac;
    } else {
        echo "SPKAC generation failed";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    MIICRzCCAS8wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDM3V3sS4o4
    mB9dczziRnjGAmSp+JwPrHoYMAFGvDNmZGyiWfU586X4BKs++BAj7e/FsAfno0Hd
    hN9FwpCNFSox30L03nQvLYJE7f/WqigwBeMRT7Op/xvFks4sT70xP2HRYv4KqP9a
    WRcKU6cFH8VxhFhqM2txEIxZKdFLaL28yT7bEDmcglf4JLDdgNMb9rET1dkgtKE6
    dOaJHPGjf1uvnOH4YwkQr7n4sLUR3Kdbh0ZJAFuQVDZulo+LLzxBBkqJJcB6FhF+
    oXCdHTKZnqAhpWDz+NXYytAmevab6IYm5TWPWsJUv1YKJA5lg2mXbbloIZlN9Mgc
    i9fi03bdw+crAgMBAAEWB3Rlc3RpbmcwDQYJKoZIhvcNAQEEBQADggEBALyUvP/o
    pPSoWBlorFyZ2RnGwKf9qMpE0q2IJP7G3oDR4LyK/m933DUiZ+YnqThrH/CWb4Ek
    y5I3OCyl3S4wCuU1ibZZwDVwYShr5ELp0J9PEf7qMQZOhNsizoC7k+Czb2xB6hYW
    sKfsfTKm3cXBtH3fdgc/Z1Z7VSWnAzYo38snqm72NTf5yFRnrQdphNNXi+kn1zHA
    lxXRyFDXHOcYsOnwAWfyXFA4QDHQ0ezz0UoCY8gJXovcZb4GRYqOLUAsF2HcNboy
    29WN8VqE29sL9QxVZFlwMcqyoLcNnyw38GvNvAGqSvzzbnEFP2MAQXJVe0H0hdp/
    MML5G2iNVgNozAo=

### Siehe auch

- openssl_spki_verify() - Verifies a signed public key and challenge
- openssl_spki_export_challenge() - Exports the challenge associated with a signed public key and challenge
- openssl_spki_export() - Exports a valid PEM formatted public key signed public key and challenge
- openssl_get_md_methods() - Gets available digest methods
- openssl_csr_new() - Erzeugt einen CSR
- openssl_csr_sign() - Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat

# openssl_spki_verify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_verify — Verifies a signed public key and challenge

### Beschreibung

function openssl_spki_verify(string `$spki`): bool

Validates the supplied signed public key and challenge

### Parameter-Liste

`spki`

  Expects a valid signed public key and challenge

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Emits an `E_WARNING` level error if an invalid argument is passed via the `spki` parameter.

### Beispiele

Beispiel #1 openssl_spki_verify() example

Validates an existing signed public key and challenge

    <?php
    $pkey = openssl_pkey_new('secret password');
    $spkac = openssl_spki_new($pkey, 'challenge string');

    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $spkac))) {
        echo $spkac;
    } else {
        echo "SPKAC validation failed";
    }
    ?>

Beispiel #2 openssl_spki_verify() example from <keygen>

Validates an existing signed public key and challenge issued from the <keygen> element

    <?php
    if (openssl_spki_verify(preg_replace('/SPKAC=/', '', $_POST['spkac']))) {
        echo $spkac;
    } else {
        echo "SPKAC validation failed";
    }
    ?>
    <keygen name="spkac" challenge="challenge string" keytype="RSA">

### Siehe auch

- openssl_spki_new() - Generate a new signed public key and challenge
- openssl_spki_export_challenge() - Exports the challenge associated with a signed public key and challenge
- openssl_spki_export() - Exports a valid PEM formatted public key signed public key and challenge
- openssl_get_md_methods() - Gets available digest methods
- openssl_csr_new() - Erzeugt einen CSR
- openssl_csr_sign() - Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat

# openssl_verify

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_verify — Überprüft eine Signatur

### Beschreibung

function openssl_verify(
string `$data`,
string `$signature`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): int|false

Die Funktion openssl_verify() überprüft die Korrektheit der Signatur `signature` für die angegebenen Daten `data` mit Hilfe des öffentlichen Schlüssels `public_key`. Dieser muss der zum privaten Schlüssel passende öffentliche sein, der für die Signatur verwendet wurde.

### Parameter-Liste

`data`

  Die Zeichenkette der Daten, mit denen die Signatur zuvor erzeugt wurde.

`signature`

  Eine rohe binäre Zeichenkette, erzeugt durch openssl_sign() oder ähnliche Mittel.

`public_key`

  OpenSSLAsymmetricKey - ein von openssl_get_publickey() zurückgegebener Schlüssel.

  string - ein PEM-formatierter Schlüssel (z. B. `-----BEGIN PUBLIC KEY----- MIIBCgK...`).

`algorithm`

  int - einer dieser Signatur-Algorithmen.

  string - eine von openssl_get_md_methods() zurückgegebene gültige Zeichenkette, beispielsweise "sha1WithRSAEncryption" oder "sha512".

`padding`
  Das zu verwendende RSA-PSS-Padding.

### Rückgabewerte

Gibt bei einer korrekten Signatur 1 zurück, 0 bei einer unkorrekten und -1 oder `false`, falls ein Fehler aufgetreten ist.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | Der optionale Parameter `padding` wurde hinzugefügt.
8.0.0 | `public_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

### Beispiele

Beispiel #1 openssl_verify()-Beispiel

    <?php
    // Annahme: $data und $signature enthalten die Daten und die Signatur

    // holen des öffentlichen Schlüssels aus dem Zertifikat und vorbereiten
    $pubkeyid = openssl_pkey_get_public("file://src/openssl-0.9.6/demos/sign/cert.pem");

    // feststellen, ob die Signatur ok ist oder nicht
    $ok = openssl_verify($data, $signature, $pubkeyid);
    if ($ok == 1) {
        echo "gut";
    } elseif ($ok == 0) {
        echo "schlecht";
    } else {
        echo "Mist, Fehler beim überprüfen der Signatur";
    }

    // Löschen des Schlüssels aus dem Speicher
    openssl_free_key($pubkeyid);
    ?>

Beispiel #2 openssl_verify()-Beispiel

    <?php
    // die zu signierenden Daten
    $data = 'my data';

    // erzeuge neuen privaten und öffentlichen Schlüssel
    $private_key_res = openssl_pkey_new(array(
        "private_key_bits" => 2048,
        "private_key_type" => OPENSSL_KEYTYPE_RSA,
    ));
    $details = openssl_pkey_get_details($private_key_res);
    $public_key_res = openssl_pkey_get_public($details['key']);

    // erzeuge Signatur
    openssl_sign($data, $signature, $private_key_res, "sha256WithRSAEncryption");

    // überprüfe Signatur
    $ok = openssl_verify($data, $signature, $public_key_res, OPENSSL_ALGO_SHA256);
    if ($ok == 1) {
        echo "gültig";
    } elseif ($ok == 0) {
        echo "ungültig";
    } else {
        echo "Fehler: ".openssl_error_string();
    }
    ?>

### Siehe auch

- openssl_sign() - Erzeugt eine Signatur

# openssl_x509_check_private_key

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_check_private_key — Überprüft, ob ein privater Schlüssel zu einem Zertifikat passt

### Beschreibung

function openssl_x509_check_private_key(OpenSSLCertificate|string `$certificate`, #[\SensitiveParameter]OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`): bool

Prüft, ob der übergebene Schlüssel `private_key` der private Schlüssel zum Zertifikat `certificate` ist.

Warnung

Die Funktion überprüft nicht, ob `private_key` tatsächlich ein privater Schlüssel ist. Sie vergleicht lediglich die öffentlichen Bestandteile (z. B. Exponent und Modulus eines RSA-Schlüssels) und/oder die Schlüsselparameter (z. B. die EC-Parameter eines EC-Schlüssels).

Dies bedeutet beispielsweise, dass ein öffentlicher Schlüssel als `private_key` angegeben werden kann, woraufhin die Funktion möglicherweise `true` zurückgibt.

### Parameter-Liste

`certificate`

  Das Zertifikat.

`private_key`

  Der private Schlüssel.

### Rückgabewerte

Gibt `true` zurück, wenn `private_key` der private Schlüssel zum Zertifikat `certificate`ist, andernfalls `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509` akzeptiert.
8.0.0 | `private_key` akzeptiert nun eine OpenSSLAsymmetricKey- oder OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL-Schlüssel` oder `OpenSSL X.509` akzeptiert.

# openssl_x509_checkpurpose

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_checkpurpose — Überprüft, ob ein Zertifikat für einen bestimmten Zweck verwendet werden kann

### Beschreibung

function openssl_x509_checkpurpose(
OpenSSLCertificate|string `$certificate`,
int `$purpose`,
array `$ca_info` = [],
?string `$untrusted_certificates_file` = `null`
): bool|int

openssl_x509_checkpurpose() überprüft ein Zertifikat, um festzustellen, ob es für den in `purpose` angegebenen Zweck eingesetzt werden kann.

### Parameter-Liste

`certificate`

  Das zu prüfende Zertifikat.

`purpose`

  openssl_x509_checkpurpose()-Verwendungszwecke
  Konstante | Beschreibung
  --- | ---
  X509_PURPOSE_SSL_CLIENT | Kann das Zertifikat für die Clientseite einer SSL-Verbindung verwendet werden?
  X509_PURPOSE_SSL_SERVER | Kann das Zertifikat für die Serverseite einer SSL-Verbindung verwendet werden?
  X509_PURPOSE_NS_SSL_SERVER | Kann das Zertifikat für den Netscape SSL-Server verwendet werden?
  X509_PURPOSE_SMIME_SIGN | Kann das Zertifikat zum Signieren einer S/MIME-E-Mail verwendet werden?
  X509_PURPOSE_SMIME_ENCRYPT | Kann das Zertifikat zum Verschlüsseln einer S/MIME-E-Mail verwendet werden?
  X509_PURPOSE_CRL_SIGN | Kann das Zertifikat zum Signieren einer Zertifikats-Widerrufliste (CRL) verwendet werden?
  X509_PURPOSE_ANY | Kann das Zertifikat für beliebige/alle Zwecke verwendet werden?

  Diese Optionen sind keine Bitfelder, nur eine kann angegeben werden!
`ca_info`

  `ca_info` sollte ein Array von vertrauenswürdigen CA-Dateien/-Verzeichnissen sein, wie in Überprüfung von Zertifikaten beschrieben.

`untrusted_certificates_file`

  Wenn angegeben, sollte dies der Name einer PEM-kodierten Datei sein, die Zertifikate enthält, die bei der Prüfung des Zertifikats helfen können. Die Zertifikate aus dieser Datei werden als nicht vertrauenswürdig erachtet.

### Rückgabewerte

Gibt `true` zurück, falls das Zertifikat für den angegebenen Zweck verwendet werden kann, `false`, falls nicht, und -1 im Falle eines Fehlers.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509` akzeptiert.
8.0.0 | `untrusted_certificates_file` ist nun ein Nullable-Typ.

# openssl_x509_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export — Exportiert ein Zertifikat als Zeichenkette

### Beschreibung

function openssl_x509_export(OpenSSLCertificate|string `$certificate`, string `&$output`, bool `$no_text` = `true`): bool

openssl_x509_export() speichert `certificate` im PEM-kodierten Format in einer Zeichenkette mit dem Namen `output`.

### Parameter-Liste

`x509`

  Siehe Schlüssel-/Zertifikatsparameter für eine Auflistung der gültigen Werte.

`output`

  Enhält bei Erfolg das PEM.

`no_text`

  Der optionale Parameter`notext` beinflusst die Ausführlichkeit der Ausgabe. Wenn er auf `false` gesetzt wird, werden zusätzliche lesbare Informationen in die Ausgabe aufgenommen. Der Vorgabewert für `notext` ist `true`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509` akzeptiert.

# openssl_x509_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export_to_file — Exportiert ein Zertifikat in eine Datei

### Beschreibung

function openssl_x509_export_to_file(OpenSSLCertificate|string `$certificate`, string `$output_filename`, bool `$no_text` = `true`): bool

openssl_x509_export_to_file() speichert ein `certificate` im PEM-kodierten Format in einer Datei mit Namen `output_filename`.

### Parameter-Liste

`x509`

  Siehe Schlüssel-/Zertifikatsparameter für eine Auflistung der gültigen Werte.

`output_filename`

  Pfad zur Ausgabe-Datei.

`no_text`

  Der optionale Parameter`notext` beinflusst die Ausführlichkeit der Ausgabe. Wenn er auf `false` gesetzt wird, werden zusätzliche lesbare Informationen in die Ausgabe aufgenommen. Der Vorgabewert für `notext` ist `true`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509` akzeptiert.

# openssl_x509_fingerprint

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_x509_fingerprint — Calculates the fingerprint, or digest, of a given X.509 certificate

### Beschreibung

function openssl_x509_fingerprint(OpenSSLCertificate|string `$certificate`, string `$digest_algo` = "sha1", bool `$binary` = `false`): string|false

openssl_x509_fingerprint() returns the digest of `certificate` as a string.

### Parameter-Liste

`x509`

  Siehe Schlüssel-/Zertifikatsparameter für eine Auflistung der gültigen Werte.

`digest_algo`

  The digest method or hash algorithm to use, e.g. "sha256", one of openssl_get_md_methods().

`binary`

  When set to `true`, outputs raw binary data. `false` outputs lowercase hexits.

### Rückgabewerte

Returns a string containing the calculated certificate fingerprint as lowercase hexits unless `binary` is set to `true` in which case the raw binary representation of the message digest is returned.

Returns `false` on failure.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `certificate` accepts an OpenSSLCertificate instance now; previously, a Ressource of type `OpenSSL X.509` was accepted.

# openssl_x509_free

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_free — Gibt eine Zertifikats-Ressource frei

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function openssl_x509_free(OpenSSLCertificate `$certificate`): void

> Hinweis:

> Diese Funktion hat keine Auswirkung. Vor PHP 8.0.0 wurde sie verwendet, um die Ressource zu schließen.

Die Funktion openssl_x509_free() gibt den Speicherbereich frei, der von der Zertifikatsressource `certificate` belegt wird.

### Parameter-Liste

`certificate`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion ist nun veraltet, da sie keine Auswirkung mehr hat.
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509` akzeptiert.

# openssl_x509_parse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_parse — Parst ein X.509-Zertifikat und liefert die Informationen als Array

### Beschreibung

function openssl_x509_parse(OpenSSLCertificate|string `$certificate`, bool `$short_names` = `true`): array|false

openssl_x509_parse() gibt Informationen über das per `certificate` übergebene Zertifikat zurück, einschließlich Name des Subjekts, Name des Herausgebers, Verwendungszwecke, Zeitangaben zur Gültigkeit etc.

### Parameter-Liste

`certificate`

  Das X509-Zertifikat. Siehe Schlüssel/Zertifikat-Parameter für eine Liste gültiger Werte.

`short_names`

  Der Parameter `short_names` kontrolliert, wie die Daten im Array indiziert werden. Wenn `short_names` `true` ist (Standard), dann wird die Kurzform verwendet, andernfalls werden die langen Bezeichner verwendet; CN ist beispielsweise die Kurzform zu commonName.

### Rückgabewerte

Die Struktur der zurückgegeben Daten ist absichtlich noch nicht dokumentiert, da es noch Änderungen geben wird.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Das Parsen von Zertifikaten ohne Sekunden in UTC ist nicht mehr für jede OpenSSL-Version erlaubt. Es war bereits für OpenSSL Version 3.3+ nicht erlaubt.
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509` akzeptiert.

# openssl_x509_read

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_read — Parst ein X.509-Zertitifikat und gibt ein Objekt dafür zurück

### Beschreibung

function openssl_x509_read(OpenSSLCertificate|string `$certificate`): OpenSSLCertificate|false

Die Funktion openssl_x509_read() parst das in `certificate` übergebene Zertifikat und gibt ein OpenSSLCertificate-Objekt dafür zurück.

### Parameter-Liste

`certificate`

  X509-Zertifikat. Siehe Schlüssel/Zertifikat-Parameter für eine Liste gültiger Werte.

### Rückgabewerte

Gibt im Erfolgsfall ein OpenSSLCertificate-Objekt zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Bei Erfolg gibt diese Funktion nun eine OpenSSLCertificate-Instanz zurück; vorher wurde eine Ressource vom Typ `OpenSSL X.509` zurückgegeben.
8.0.0 | `certificate` akzeptiert nun eine OpenSSLCertificate-Instanz; vorher wurde eine Ressource vom Typ `OpenSSL X.509` akzeptiert.

# openssl_x509_verify

(PHP 7 >= 7.4.0, PHP 8)

openssl_x509_verify — Verifies digital signature of x509 certificate against a public key

### Beschreibung

function openssl_x509_verify(OpenSSLCertificate|string `$certificate`, OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): int

openssl_x509_verify() verifies that the `certificate` certificate was signed by the private key corresponding to public key `public_key`.

### Parameter-Liste

`x509`

  Siehe Schlüssel-/Zertifikatsparameter für eine Auflistung der gültigen Werte.

`public_key`

  OpenSSLAsymmetricKey - a key, returned by openssl_get_publickey()

  string - a PEM formatted key (e.g. `-----BEGIN PUBLIC KEY----- MIIBCgK...`)

### Rückgabewerte

Returns 1 if the signature is correct, 0 if it is incorrect, and -1 on error.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `certificate` accepts an OpenSSLCertificate instance now; previously, a Ressource of type `OpenSSL X.509` was accepted.
8.0.0 | `public_key` accepts an OpenSSLAsymmetricKey or OpenSSLCertificate instance now; previously, a Ressource of type `OpenSSL key` or `OpenSSL X.509` was accepted.

### Beispiele

Beispiel #1 openssl_x509_verify() example

    <?php
    $hostname = "news.php.net";
    $ssloptions = array(
        "capture_peer_cert" => true,
        "capture_peer_cert_chain" => true,
        "allow_self_signed"=> false,
        "CN_match" => $hostname,
        "verify_peer" => true,
        "SNI_enabled" => true,
        "SNI_server_name" => $hostname,
    );

    $ctx = stream_context_create( array("ssl" => $ssloptions) );
    $result = stream_socket_client("ssl://$hostname:443", $errno, $errstr, 30, STREAM_CLIENT_CONNECT, $ctx);
    $cont = stream_context_get_params($result);
    $x509 = $cont["options"]["ssl"]["peer_certificate"];
    $certparsed = openssl_x509_parse($x509);

    foreach($cont["options"]["ssl"]["peer_certificate_chain"] as $chaincert)
    {
        $chainparsed = openssl_x509_parse($chaincert);
        $chain_public_key = openssl_get_publickey($chaincert);
        $r = openssl_x509_verify($x509, $chain_public_key);
        if ($r==1)
        {
            echo $certparsed['subject']['CN'];
            echo " was digitally signed by ";
            echo $chainparsed['subject']['CN']."\n";
        }
    }
    ?>

### Siehe auch

- openssl_verify() - Überprüft eine Signatur
- openssl_get_publickey() - Alias von openssl_pkey_get_public

## Inhaltsverzeichnis

- openssl_cipher_iv_length — Ermittelt die Länge des Initialisierungsvektors einer Verschlüsselungsmethode
- openssl_cipher_key_length — Ermittelt die Schlüssellänge einer Verschlüsselungsmethode
- openssl_cms_decrypt — Decrypt a CMS message
- openssl_cms_encrypt — Encrypt a CMS message
- openssl_cms_read — Export the CMS file to an array of PEM certificates
- openssl_cms_sign — Sign a file
- openssl_cms_verify — Verify a CMS signature
- openssl_csr_export — Exportiert einen CSR als Zeichenkette
- openssl_csr_export_to_file — Exportiert einen CSR in eine Datei
- openssl_csr_get_public_key — Liefert den öffentlichen Schlüssel eines CSR
- openssl_csr_get_subject — Liefert das Subjekt eines CSR
- openssl_csr_new — Erzeugt einen CSR
- openssl_csr_sign — Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat
- openssl_decrypt — Entschlüsselt Daten
- openssl_dh_compute_key — Computes shared secret for public value of remote DH public key and local DH key
- openssl_digest — Berechnet einen Hashwert (Digest)
- openssl_encrypt — Verschlüsselt Daten
- openssl_error_string — Liefert eine OpenSSL-Fehlermeldung
- openssl_free_key — Gibt eine Schlüssel-Ressource frei
- openssl_get_cert_locations — Retrieve the available certificate locations
- openssl_get_cipher_methods — Liefert die verfügbaren Verschlüsselungsmethoden
- openssl_get_curve_names — Gets list of available curve names for ECC
- openssl_get_md_methods — Gets available digest methods
- openssl_get_privatekey — Alias von openssl_pkey_get_private
- openssl_get_publickey — Alias von openssl_pkey_get_public
- openssl_open — Öffnet versiegelte Daten
- openssl_password_hash — Create a password hash using OpenSSL's Argon2 implementation
- openssl_password_verify — Verify a password against a hash using OpenSSL's Argon2 implementation
- openssl_pbkdf2 — Generates a PKCS5 v2 PBKDF2 string
- openssl_pkcs12_export — Exportiert eine PKCS#12-kompatible Zertifikats-Datei in eine Variable
- openssl_pkcs12_export_to_file — Exportiert in eine PKCS#12-kompatible Zertifikats-Datei
- openssl_pkcs12_read — Parst eine PKCS#12-Zertifikats-Datei in ein Array
- openssl_pkcs7_decrypt — Entschlüsselt eine S/MIME-verschlüsselte Nachricht
- openssl_pkcs7_encrypt — Verschlüsselt eine S/MIME-Nachricht
- openssl_pkcs7_read — Export the PKCS7 file to an array of PEM certificates
- openssl_pkcs7_sign — Signiert eine S/MIME-Nachricht
- openssl_pkcs7_verify — Überprüft die Signatur einer mit S/MIME signierten Nachricht
- openssl_pkey_derive — Computes shared secret for public value of remote and local DH or ECDH key
- openssl_pkey_export — Speichert ein exportierbares Format eines Schlüssels in einer Zeichenkette
- openssl_pkey_export_to_file — Speichert einen Schlüssel in einem exportierbaren Format in einer Datei
- openssl_pkey_free — Gibt einen privaten Schlüssel frei
- openssl_pkey_get_details — Liefert ein Array mit Schlüssel-Details
- openssl_pkey_get_private — Liefert einen privaten Schlüssel
- openssl_pkey_get_public — Extrahiert einen öffentlichen Schlüssel aus einem Zertifikat und bereitet diesen zur Verwendung vor
- openssl_pkey_new — Erzeugt einen neuen privaten Schlüssel
- openssl_private_decrypt — Entschlüsselt Daten mit einem privaten Schlüssel
- openssl_private_encrypt — Verschlüsselt Daten mit einem privaten Schlüssel
- openssl_public_decrypt — Entschlüsselt Daten mit einem öffentlichen Schlüssel
- openssl_public_encrypt — Verschlüsselt Daten mit einem öffentlichen Schlüssel
- openssl_random_pseudo_bytes — Generate a pseudo-random string of bytes
- openssl_seal — Versiegelt (verschlüsselt) Daten
- openssl_sign — Erzeugt eine Signatur
- openssl_spki_export — Exports a valid PEM formatted public key signed public key and challenge
- openssl_spki_export_challenge — Exports the challenge associated with a signed public key and challenge
- openssl_spki_new — Generate a new signed public key and challenge
- openssl_spki_verify — Verifies a signed public key and challenge
- openssl_verify — Überprüft eine Signatur
- openssl_x509_check_private_key — Überprüft, ob ein privater Schlüssel zu einem Zertifikat passt
- openssl_x509_checkpurpose — Überprüft, ob ein Zertifikat für einen bestimmten Zweck verwendet werden kann
- openssl_x509_export — Exportiert ein Zertifikat als Zeichenkette
- openssl_x509_export_to_file — Exportiert ein Zertifikat in eine Datei
- openssl_x509_fingerprint — Calculates the fingerprint, or digest, of a given X.509 certificate
- openssl_x509_free — Gibt eine Zertifikats-Ressource frei
- openssl_x509_parse — Parst ein X.509-Zertifikat und liefert die Informationen als Array
- openssl_x509_read — Parst ein X.509-Zertitifikat und gibt ein Objekt dafür zurück
- openssl_x509_verify — Verifies digital signature of x509 certificate against a public key

# The OpenSSLCertificate class

(PHP 8)

## Einführung

A fully opaque class which replaces `OpenSSL X.509` resources as of PHP 8.0.0.

## Klassenbeschreibung

final class OpenSSLCertificate {
}

# The OpenSSLCertificateSigningRequest class

(PHP 8)

## Einführung

A fully opaque class which replaces `OpenSSL X.509 CSR` resources as of PHP 8.0.0.

## Klassenbeschreibung

final class OpenSSLCertificateSigningRequest {
}

# The OpenSSLAsymmetricKey class

(PHP 8)

## Einführung

A fully opaque class which replaces `OpenSSL key` resources as of PHP 8.0.0.

## Klassenbeschreibung

final class OpenSSLAsymmetricKey {
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
  - Zweckprüfende Flags
  - Padding-Flags für asymmetrische Verschlüsselung
  - Schlüsseltypen
  - PKCS7-Flags/Konstanten
  - CMS-Flags/Konstanten
  - Signatur-Algorithmen
  - Ciphers
  - Versions-Konstanten
  - Konstanten zur Identifizierung des Servernamens (Server Name Indication)
  - Andere Konstanten
- Schlüssel-/Zertifikatparameter
- Überprüfung von Zertifikaten
- OpenSSL-Funktionen
  - openssl_cipher_iv_length — Ermittelt die Länge des Initialisierungsvektors einer Verschlüsselungsmethode
  - openssl_cipher_key_length — Ermittelt die Schlüssellänge einer Verschlüsselungsmethode
  - openssl_cms_decrypt — Decrypt a CMS message
  - openssl_cms_encrypt — Encrypt a CMS message
  - openssl_cms_read — Export the CMS file to an array of PEM certificates
  - openssl_cms_sign — Sign a file
  - openssl_cms_verify — Verify a CMS signature
  - openssl_csr_export — Exportiert einen CSR als Zeichenkette
  - openssl_csr_export_to_file — Exportiert einen CSR in eine Datei
  - openssl_csr_get_public_key — Liefert den öffentlichen Schlüssel eines CSR
  - openssl_csr_get_subject — Liefert das Subjekt eines CSR
  - openssl_csr_new — Erzeugt einen CSR
  - openssl_csr_sign — Signiert einen CSR mit einem anderen Zertifikat (oder sich selbst) und generiert ein Zertifikat
  - openssl_decrypt — Entschlüsselt Daten
  - openssl_dh_compute_key — Computes shared secret for public value of remote DH public key and local DH key
  - openssl_digest — Berechnet einen Hashwert (Digest)
  - openssl_encrypt — Verschlüsselt Daten
  - openssl_error_string — Liefert eine OpenSSL-Fehlermeldung
  - openssl_free_key — Gibt eine Schlüssel-Ressource frei
  - openssl_get_cert_locations — Retrieve the available certificate locations
  - openssl_get_cipher_methods — Liefert die verfügbaren Verschlüsselungsmethoden
  - openssl_get_curve_names — Gets list of available curve names for ECC
  - openssl_get_md_methods — Gets available digest methods
  - openssl_get_privatekey — Alias von openssl_pkey_get_private
  - openssl_get_publickey — Alias von openssl_pkey_get_public
  - openssl_open — Öffnet versiegelte Daten
  - openssl_password_hash — Create a password hash using OpenSSL's Argon2 implementation
  - openssl_password_verify — Verify a password against a hash using OpenSSL's Argon2 implementation
  - openssl_pbkdf2 — Generates a PKCS5 v2 PBKDF2 string
  - openssl_pkcs12_export — Exportiert eine PKCS#12-kompatible Zertifikats-Datei in eine Variable
  - openssl_pkcs12_export_to_file — Exportiert in eine PKCS#12-kompatible Zertifikats-Datei
  - openssl_pkcs12_read — Parst eine PKCS#12-Zertifikats-Datei in ein Array
  - openssl_pkcs7_decrypt — Entschlüsselt eine S/MIME-verschlüsselte Nachricht
  - openssl_pkcs7_encrypt — Verschlüsselt eine S/MIME-Nachricht
  - openssl_pkcs7_read — Export the PKCS7 file to an array of PEM certificates
  - openssl_pkcs7_sign — Signiert eine S/MIME-Nachricht
  - openssl_pkcs7_verify — Überprüft die Signatur einer mit S/MIME signierten Nachricht
  - openssl_pkey_derive — Computes shared secret for public value of remote and local DH or ECDH key
  - openssl_pkey_export — Speichert ein exportierbares Format eines Schlüssels in einer Zeichenkette
  - openssl_pkey_export_to_file — Speichert einen Schlüssel in einem exportierbaren Format in einer Datei
  - openssl_pkey_free — Gibt einen privaten Schlüssel frei
  - openssl_pkey_get_details — Liefert ein Array mit Schlüssel-Details
  - openssl_pkey_get_private — Liefert einen privaten Schlüssel
  - openssl_pkey_get_public — Extrahiert einen öffentlichen Schlüssel aus einem Zertifikat und bereitet diesen zur Verwendung vor
  - openssl_pkey_new — Erzeugt einen neuen privaten Schlüssel
  - openssl_private_decrypt — Entschlüsselt Daten mit einem privaten Schlüssel
  - openssl_private_encrypt — Verschlüsselt Daten mit einem privaten Schlüssel
  - openssl_public_decrypt — Entschlüsselt Daten mit einem öffentlichen Schlüssel
  - openssl_public_encrypt — Verschlüsselt Daten mit einem öffentlichen Schlüssel
  - openssl_random_pseudo_bytes — Generate a pseudo-random string of bytes
  - openssl_seal — Versiegelt (verschlüsselt) Daten
  - openssl_sign — Erzeugt eine Signatur
  - openssl_spki_export — Exports a valid PEM formatted public key signed public key and challenge
  - openssl_spki_export_challenge — Exports the challenge associated with a signed public key and challenge
  - openssl_spki_new — Generate a new signed public key and challenge
  - openssl_spki_verify — Verifies a signed public key and challenge
  - openssl_verify — Überprüft eine Signatur
  - openssl_x509_check_private_key — Überprüft, ob ein privater Schlüssel zu einem Zertifikat passt
  - openssl_x509_checkpurpose — Überprüft, ob ein Zertifikat für einen bestimmten Zweck verwendet werden kann
  - openssl_x509_export — Exportiert ein Zertifikat als Zeichenkette
  - openssl_x509_export_to_file — Exportiert ein Zertifikat in eine Datei
  - openssl_x509_fingerprint — Calculates the fingerprint, or digest, of a given X.509 certificate
  - openssl_x509_free — Gibt eine Zertifikats-Ressource frei
  - openssl_x509_parse — Parst ein X.509-Zertifikat und liefert die Informationen als Array
  - openssl_x509_read — Parst ein X.509-Zertitifikat und gibt ein Objekt dafür zurück
  - openssl_x509_verify — Verifies digital signature of x509 certificate against a public key
- OpenSSLCertificate — The OpenSSLCertificate class
- OpenSSLCertificateSigningRequest — The OpenSSLCertificateSigningRequest class
- OpenSSLAsymmetricKey — The OpenSSLAsymmetricKey class

# Password Hashing

# Einführung

Die Passwort-Hashing-API stellt einen einfach zu benutzenden Wrapper über der Funktion crypt() und einigen anderen Password-Hash-Algorithmen zur einfachen Erstellung und Verwaltung von Passwörtern zur Verfügung.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

Diese Erweiterung benötigt für die Kompilierung keine externen Bibliotheken.

Für Argon2 Passwort-Hashing wird entweder » libargon2 oder, von PHP 8.4.0 an, OpenSSL Version 3.2 oder neuer benötigt. Von PHP 7.3.0 an wird libargon2 Version 20161029 oder neuer benötigt.

## Installation

Für diese Funktionen ist keine Installation erforderlich, diese gehören zum Grundbestand von PHP.

Um Argon2-Passwort-Hashing zu aktivieren, muss PHP jedoch entweder mit Unterstützung für libargon2 gebaut werden, indem die Konfigurationsoption --with-password-argon2 verwendet wird, oder, beginnend mit PHP 8.4.0, mit OpenSSL, indem --with-openssl und --with-openssl-argon2 verwendet wird.

Vor PHP 8.1.0 war es möglich, das argon2-Verzeichnis mit --with-password-argon2[=DIR] anzugeben.

# Vordefinierte Konstanten

Die aufgelisteten Konstanten stehen immer zur Verfügung, da sie zum Grundbestand von PHP gehören.

`PASSWORD_BCRYPT` (string)

  `PASSWORD_BCRYPT` wird verwendet, um neue Passwort-Hashes unter Verwendung des `CRYPT_BLOWFISH` Algorithmus zu erzeugen.

  Dies ergibt immer einen Hash, der das "$2y$"-Crypt-Format verwendet und immer 60 Zeichen lang ist.

  Unterstützte Optionen:

  - `salt` (string) - um manuell ein Salt anzugeben, das beim Hashing des Passworts verwendet wird. Es ist zu beachten, dass dies die automatische Erzeugung des Salt verhindert.

    Wird diese Option ausgelassen, dann wird von password_hash() ein zufälliges Salt für jedes gehashte Passwort erzeugt. Dies ist die vorgesehene Funktionsweise, und von PHP 7.0.0 an wird die salt-Option missbilligt.

  - `cost` (int) - bezeichnet den algorithmischen Aufwand, der angewendet werden soll. Beispiele dieses Wertes können der crypt()-Dokumentation entnommen werden.

    Wird diese Option ausgelassen, dann wird der Standardwert `12` verwendet. Das ist eine gute Ausgangsbasis, aber es ist zu erwägen, diesen Wert in Abhängigkeit von der Hardware zu erhöhen.

`PASSWORD_BCRYPT_DEFAULT_COST` (int)

`PASSWORD_ARGON2I` (string)

  `PASSWORD_ARGON2I` wird verwendet, um neue Passwort-Hashes unter Verwendung des Argon2i-Algorithmus zu erzeugen.

  Unterstützte Optionen:

  - `memory_cost` (int) - die Obergrenze des Speichers (in Kibibytes), der verwendet werden darf, um den Argon2-Hash zu berechnen. Der Vorgabewert ist `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

  - `time_cost` (int) - die Höchstdauer der Berechnung des Argon2-Hashs. Der Vorgabewert ist `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

  - `threads` (int) - Die Anzahl der Threads, die für die Berechnung des Argon2-Hashs verwendet werden. Der Vorgabewert ist `PASSWORD_ARGON2_DEFAULT_THREADS`. Nur mit libargon2 verfügbar, nicht mit der libsodium-Implementierung.

  Verfügbar von PHP 7.2.0 an.

`PASSWORD_ARGON2ID` (string)

  `PASSWORD_ARGON2ID` wird verwendet, um neue Passwort-Hashes unter Verwendung des Argon2id-Algorithmus zu erzeugen. Es werden dieselben Optionen wie bei `PASSWORD_ARGON2I` unterstützt.

  Verfügbar von PHP 7.3.0 an.

`PASSWORD_ARGON2_DEFAULT_MEMORY_COST` (int)

  Der Vorgabewert des Speichers in Bytes, der beim Versuch, den Hash zu berechnen, verwenden wird.

  Verfügbar von PHP 7.2.0 an.

`PASSWORD_ARGON2_DEFAULT_TIME_COST` (int)

  Der Vorgabewert der Dauer, die beim Versuch, den Hash zu berechnen, verwenden wird.

  Verfügbar von PHP 7.2.0 an.

`PASSWORD_ARGON2_DEFAULT_THREADS` (int)

  Der Vorgabewert der Anzahl Threads, die Argon2lib verwenden wird.

  Verfügbar von PHP 7.2.0 an.

`PASSWORD_ARGON2_PROVIDER` (string)

  Verfügbar von PHP 7.4.0 an.

`PASSWORD_DEFAULT` (string)

  Der Vorgabewert des Algorithmus, der für das Hashing verwendet wird, wenn kein Algorithmus angegeben wird. Dies kann sich in neueren PHP-Releases ändern, wenn neuere, stärkere Hash-Algorithmen unterstützt werden.

  Es ist zu betonen, dass sich diese Konstante im Lauf der Zeit ändern kann. Daher ist es wichtig zu beachten, dass sich die Länge des resultierenden Hashs ändern kann. Also sollte bei Verwendung von `PASSWORD_DEFAULT` der sich ergebende Hash so gespeichert werden, dass beliebige Hashes gespeichert werden können; die empfohlene Breite ist `255` Bytes.

  Derzeit ist dies ein Alias für `PASSWORD_BCRYPT`.

##### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Die Werte der Passwort-Algorithmen-IDs (`PASSWORD_BCRYPT`, `PASSWORD_ARGON2I`, `PASSWORD_ARGON2ID` und `PASSWORD_DEFAULT`) sind nun Strings. Zuvor waren es Integer.

# Passwort-Hashing-Funktionen

# password_algos

(PHP 7 >= 7.4.0, PHP 8)

password_algos — Get available password hashing algorithm IDs

### Beschreibung

function password_algos(): array

Returns a complete list of all registered password hashing algorithm IDs as an Array of Strings.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the available password hashing algorithm IDs.

### Beispiele

Beispiel #1 Basic password_algos() usage

    <?php
    print_r(password_algos());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 2y
        [1] => argon2i
        [2] => argon2id
    )

# password_get_info

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_get_info — Gibt Informationen über einen Hash zurück

### Beschreibung

function password_get_info(string `$hash`): array

Falls ein gültiger Hash übergeben wird, der durch einen von password_hash() unterstützen Algorithmus erzeugt wurde, gibt diese Funktion ein Array mit Informationen über diesen Hash zurück.

### Parameter-Liste

`hash`

  Ein Hash, der durch password_hash() erzeugt wurde.

### Rückgabewerte

Gibt ein assoziatives Array mit drei Elementen zurück:

- `algo`, dies ist eine der Passwort-Algorithmus-Konstanten
- `algoName`, dies ist der lesbare Name des Algorithmus
- `options`, dies enthält die Optionen, die password_hash() übergeben wurden

# password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — Erstellt einen Passwort-Hash

### Beschreibung

function password_hash(#[\SensitiveParameter]string `$password`, string|int|null `$algo`, array `$options` = []): string

password_hash() erstellt einen neuen Passwort-Hash und benutzt dabei einen starken Einweg-Hashing-Algorithmus.

Die folgenden Algorithmen werden zur Zeit unterstützt:

- `PASSWORD_DEFAULT` - Verwendet den bcrypt-Algorithmus (Standard in PHP 5.5.0). Es ist zu beachten, dass sich diese Konstante mit der Zeit ändern wird, wenn stärkere Algorithmen in PHP implementiert werden. Aus diesem Grund kann sich die Länge des zurückgegebenen Strings mit der Zeit ändern. Es wird deshalb empfohlen das Ergebnis in einem Datenbankfeld zu speichern, das mehr als 60 Bytes speichern kann (255 Bytes wären eine gute Wahl).
- `PASSWORD_BCRYPT` - Verwendet den bcrypt-Algorithmus zum Erstellen des Hashes. Dieser erstellt einen crypt()-kompatiblen Hash und benutzt die `$2y$`-Kennung.
- `PASSWORD_ARGON2I` - Verwendet den Argon2i-Algorithmus zur Erstellung des Hashes. Dieser Algorithmus ist nur verfügbar, wenn PHP mit Argon2-Unterstützung kompiliert wurde.
- `PASSWORD_ARGON2ID` - Verwendet den Argon2id-Algorithmus zur Erstellung des Hashes. Dieser Algorithmus ist nur verfügbar, wenn PHP mit Argon2-Unterstützung kompiliert wurde.

Unterstützte Optionen für `PASSWORD_BCRYPT`:

- `salt` (string) - um manuell ein Salt anzugeben, das beim Hashing des Passworts verwendet wird. Es ist zu beachten, dass diese Option die automatische Generierung des Salt verhindert.

  Wenn diese Option nicht angegeben wird, erzeugt die Funktion password_hash() für jedes gehashte Passwort ein zufälliges Salt. Dies ist die vorgesehene Funktionsweise.

  Warnung

  Die salt-Option wird missbilligt. Es wird nun empfohlen, einfach das Salt zu verwenden, das standardmäßig erzeugt wird. Ab PHP 8.0.0 wird ein explizit angegebenes Salt ignoriert.

- `cost` (int) - bezeichnet die algorithmischen Kosten, die verwendet werden sollen. Beispiele für diesen Wert finden Sie finden Sie auf der Seite crypt().

  Wenn diese Option nicht angegeben wird, wird ein Standardwert von `12` verwendet. Dies ist eine gute Basis für die Kosten, sollte aber der verwendeten Hardware entsprechend angepasst werden.

Unterstützte Optionen für `PASSWORD_ARGON2I` und `PASSWORD_ARGON2ID`:

- `memory_cost` (int) - Maximaler Speicher (in Kibibytes), der zum Berechnen des Argon2-Hashes verwendet werden darf. Der Standardwert ist `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`.

- `time_cost` (int) - Maximale Zeit, die die das Berechnen des Argon2-Hashes dauern darf. Der Standardwert ist `PASSWORD_ARGON2_DEFAULT_TIME_COST`.

- `threads` (int) - Anzahl der zu verwendenden Threads zum Berechnen des Argon2-Hashes. Der Standardwert ist `PASSWORD_ARGON2_DEFAULT_THREADS`.

  Warnung

  Nur verfügbar, wenn PHP libargon2 verwendet, nicht für libsodium-Implementierungen.

### Parameter-Liste

`password`

  Das Passwort des Benutzers.

  Achtung

  Die Verwendung von `PASSWORD_BCRYPT` als Algorithmus führt dazu, dass der Parameter `password` auf eine Höchstlänge von 72 Bytes gekürzt wird.

`algo`

  Eine Konstante für den Passwort-Algorithmus, die den Algorithmus zum hashen des Passwortes angibt.

`options`

  Ein assoziatives Array mit Optionen. Siehe auch Konstanten für Passwort-Algorithmen für Informationen zu den von den jeweiligen Algorithmen unterstützten Optionen.

### Rückgabewerte

Gibt den Passwort-Hash zurück.

Der verwendete Algorithmus, der Aufwand und das Salt werden als Teil des Hashes zurückgegeben. Daher sind alle Informationen, die benötigt werden, um den Hash zu verifizieren, darin enthalten. Dies erlaubt es der Funktion password_verify() den Hash zu überprüfen, ohne dass eine separate Speicherung für das Salt oder die Algorithmus-Informationen erforderlich ist.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Standardwert der Option `cost` des `PASSWORD_BCRYPT`-Algorithmus wurde von `10` auf `12` erhöht.
8.3.0 | password_hash() setzt nun die zugrundeliegende Random\RandomException als Exception::$previous-Exception, wenn aufgrund eines Fehlers bei der Erzeugung des Salt ein ValueError ausgelöst wird.
8.0.0 | password_hash() gibt im Fehlerfall nicht mehr `false` zurück; stattdessens wird ein ValueError ausgelöst, wenn der Passwort-Hashing-Algorithmus ungültig ist, oder ein Error, wenn das Passwort-Hashing aufgrund eines unbekannten Fehlers fehlschlug.
8.0.0 | Der Parameter `algo` ist jetzt nullable (akzeptiert den NULL-Wert).
7.4.0 | Der Parameter `algo` erwartet nun einen String, akzeptiert aber aus Gründen der Abwärtskompatibilität noch immer Integer.
7.4.0 | Die Sodium-Erweiterung bietet eine alternative Implementierung für Argon2-Passwörter.
7.3.0 | Mit `PASSWORD_ARGON2ID` wurde die Unterstützung für Argon2id-Passwörter hinzugefügt.
7.2.0 | Mit `PASSWORD_ARGON2I` wurde die Unterstützung für Argon2i-Passwörter hinzugefügt.

### Beispiele

Beispiel #1 password_hash()-Beispiel

    <?php
    echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    $2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

Beispiel #2 password_hash()-Beispiel mit manuell festgelegten Kosten

    <?php
    $optionen = [
        // Erhöhen der bcrypt-Kosten von 12 auf 13.
        'cost' => 13,
    ];
    echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $optionen);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    $2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

Beispiel #3 password_hash()-Beispiel für die Suche nach angemessenen Kosten

Mit diesem Code wird ein Benchmarking des Rechners durchgeführt, um festzustellen, wie hoch die Kosten sein dürfen, ohne die Benutzerfreundlichkeit zu beeinträchtigen. Es wird empfohlen, die höchsten Kosten festzulegen, die andere Operationen, die der Rechner ausführen soll, nicht verlangsamen. 11 ist ein guter Richtwert, mehr ist besser, wenn der Rechner schnell genug ist. Der nachstehende Code zielt auf eine Ausführungszeit von ≤ 350 Millisekunden ab, was für Systeme, die interaktive Anmeldungen verarbeiten, eine angemessene Verzögerung darstellt.

    <?php
    $zeitZiel = 0.350; // 350 Millisekunden

    $kosten = 11;
    do {
        $kosten++;
        $start = microtime(true);
        password_hash("test", PASSWORD_BCRYPT, ["cost" => $kosten]);
        $ende = microtime(true);
    } while (($ende - $start) < $zeitZiel);

    echo "Ermittelte angemessene Kosten: " . $kosten - 1;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Ermittelte angemessene Kosten: 13

Beispiel #4 password_hash()-Beispiel, das Argon2i verwendet

    <?php
    echo 'Argon2i-Hash: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Argon2i-Hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

### Anmerkungen

Achtung

Es wird dringend empfohlen, kein explizites Salt für diese Funktion anzugeben. Wenn kein Salt angegeben wird, wird automatisch ein sicheres Salt erstellt.

Wie oben erwähnt, erzeugt die Angabe der Option `salt` in PHP 7.0.0 eine Missbilligungs-Warnung. Die Unterstützung für die manuelle Angabe eines Salzes wurde in PHP 8.0.0 entfernt.

> Hinweis:

> Es wird empfohlen, diese Funktion auf dem verwendeten Rechner zu testen und den Kostenparameter so einzustellen, dass die Ausführung der Funktion bei interaktiven Anmeldungen weniger als 350 Millisekunden dauert. Das Skript im obigen Beispiel hilft bei der Auswahl eines geeigneten bcrypt-Kostenwerts für den jeweiligen Rechner.

> Hinweis: Aktualisierungen der unterstützten Algorithmen durch diese Funktion (oder Änderungen am Standardalgorithmus) müssen den folgenden Regeln folgen:

> - Jeder neue Algorithmus muss für mindestens 1 Vollversion im Core von PHP sein, bevor er zum Standard wird. Wenn also z. B. ein neuer Algorithmus in 7.5.5 hinzugefügt wird, wäre er erst in 7.7 als Standard geeignet (da 7.6 die erste Vollversion wäre). Wenn aber ein anderer Algorithmus in 7.6.0 hinzugefügt würde, wäre auch dieser für die Standardeinstellung in 7.7.0 freigegeben.
> - Die Voreinstellung sollte sich nur bei einer Vollversion (7.3.0, 8.0.0, etc) ändern und nicht bei einer Korrekturversion. Die einzige Ausnahme hiervon ist in einem Notfall, wenn eine kritische Sicherheitslücke in der aktuellen Voreinstellung gefunden wurde.

### Siehe auch

- password_verify() - Überprüft, ob ein Passwort und ein Hash zusammenpassen
- password_needs_rehash() - Überprüft, ob der übergebene Hash mit den übergebenen Optionen übereinstimmt
- crypt() - Einweg-String-Hashing
- sodium_crypto_pwhash_str() - Get an ASCII-encoded hash

# password_needs_rehash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_needs_rehash — Überprüft, ob der übergebene Hash mit den übergebenen Optionen übereinstimmt

### Beschreibung

function password_needs_rehash(string `$hash`, string|int|null `$algo`, array `$options` = []): bool

Diese Funktion überprüft, ob der übergebene Hash den gleichen Algorithmus und die gleichen Optionen nutzt, wie in den übergebenen Optionen abgegeben. Falls nicht, wird angenommen, dass erneutes Hashen notwendig ist.

### Parameter-Liste

`hash`

  Ein Hash, der durch password_hash() erzeugt wurde.

`algo`

  Eine Konstante für den Passwort-Algorithmus, die den Algorithmus zum hashen des Passwortes angibt.

`options`

  Ein assoziatives Array mit Optionen. Siehe auch Konstanten für Passwort-Algorithmen für Informationen zu den von den jeweiligen Algorithmen unterstützten Optionen.

### Rückgabewerte

Gibt `true` zurück, falls der Hash erneut gehasht werden muss, damit die übergebenen Parameter `algo` und `options` übereinstimmen, sonst `false`.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Der Parameter `algo` erwartet nun einen String, akzeptiert aber aus Gründen der Abwärtskompatibilität noch immer Integer.

### Beispiele

Beispiel #1 Die Verwendung von password_needs_rehash()

    <?php

    $password = 'rasmuslerdorf';
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    $algorithm = PASSWORD_BCRYPT;
    // Der Aufwand-Parameter cost von bcrypt kann sich im Lauf der Zeit ändern,
    // da die Hardware besser wird
    $options = ['cost' => 13];

    // Überprüfe den gespeicherten Hash gegen das Klartextkennwort
    if (password_verify($password, $hash)) {
        // Prüfe, ob sich der Algorithmus oder die Optionen geändert haben.
        if (password_needs_rehash($hash, $algorithm, $options)) {
            // Falls ja, dann erzeuge einen neuen Hash und ersetze den alten
            $newHash = password_hash($password, $algorithm, $options);

            // Aktualisiere den Benutzerdatensatz mit dem $newHash
        }

        // Führe die Anmeldung durch.
    }
    ?>

# password_verify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_verify — Überprüft, ob ein Passwort und ein Hash zusammenpassen

### Beschreibung

function password_verify(#[\SensitiveParameter]string `$password`, string `$hash`): bool

Überprüft, ob ein Passwort und ein Hash zusammenpassen. password_verify() ist kompatibel zu crypt(). Daher können Passwort-Hashes, die mit crypt() erzeugt wurden, mit password_verify() verwendet werden.

Es ist zu beachten, dass password_hash() den Algorithmus, den Aufwand und den Salt als Teil des Hashes zurückgibt. Somit sind in Hash alle Informationen enthalten, die für die Überprüfung des Hashes erforderlich sind. Dies erlaubt es der Funktion, den Hash zu prüfen, ohne dass Informationen über den Salt oder den Algorithmus an anderer Stelle gespeichert werden müssen.

Diese Funktion ist vor Timing-Angriffen sicher.

### Parameter-Liste

`password`

  Das Passwort des Benutzers.

`hash`

  Ein Hash, der durch password_hash() erzeugt wurde.

### Rückgabewerte

Gibt `true` zurück, falls Passwort und Hash zusammenpassen, sonst `false`.

### Beispiele

Beispiel #1 password_verify()-Beispiel

Dies ist ein vereinfachtes Beispiel; es wird empfohlen, ein korrektes Passwort bei Bedarf noch einmal zu hashen; siehe password_needs_rehash() für ein Beispiel.

    <?php
    // Siehe auch das password_hash()-Beispiel in diesem Kontext
    $hash = '$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    if (password_verify('rasmuslerdorf', $hash)) {
        echo 'Valides Passwort!';
    } else {
        echo 'Invalides Passwort.';
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Valides Passwort!

### Siehe auch

- password_needs_rehash() - Überprüft, ob der übergebene Hash mit den übergebenen Optionen übereinstimmt
- password_hash() - Erstellt einen Passwort-Hash
- sodium_crypto_pwhash_str_verify() - Verifies that a password matches a hash

## Inhaltsverzeichnis

- password_algos — Get available password hashing algorithm IDs
- password_get_info — Gibt Informationen über einen Hash zurück
- password_hash — Erstellt einen Passwort-Hash
- password_needs_rehash — Überprüft, ob der übergebene Hash mit den übergebenen Optionen übereinstimmt
- password_verify — Überprüft, ob ein Passwort und ein Hash zusammenpassen

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Vordefinierte Konstanten
- Passwort-Hashing-Funktionen
  - password_algos — Get available password hashing algorithm IDs
  - password_get_info — Gibt Informationen über einen Hash zurück
  - password_hash — Erstellt einen Passwort-Hash
  - password_needs_rehash — Überprüft, ob der übergebene Hash mit den übergebenen Optionen übereinstimmt
  - password_verify — Überprüft, ob ein Passwort und ein Hash zusammenpassen

# Rnp

# Einführung

Warnung

Diese Erweiterung ist EXPERIMENTELL. Das Verhalten dieser Erweiterung, einschließlich der Funktionsnamen, und alles Andere, was hier dokumentiert ist, kann sich in zukünftigen PHP-Versionen ohne Ankündigung ändern. Seien Sie gewarnt und verwenden Sie diese Erweiterung auf eigenes Risiko.

This module allows you to use » RNP library. RNP is a high performance C++ OpenPGP library used by Mozilla Thunderbird.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

In order to use RNP library functions you need to install the» RNP library. RNP library version >= 0.16.2 is required.

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/rnp

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`RNP_KEYSTORE_GPG` (string)
  Keystore format "GPG".
`RNP_KEYSTORE_KBX` (string)
  Keystore format "KBX". For public keys only. A keybox is a file format used to store public keys along with meta information and indices.
`RNP_KEYSTORE_G10` (string)
  Keystore format "G10". For private keys.
`RNP_LOAD_SAVE_PUBLIC_KEYS` (integer)
  Load or save public keys only. Can be OR-ed with `RNP_LOAD_SAVE_SECRET_KEYS` to load both public and private keys to the FFI context or save them from the context.
`RNP_LOAD_SAVE_SECRET_KEYS` (integer)
  Load or save secret keys only. Can be OR-ed with `RNP_LOAD_SAVE_PUBLIC_KEYS` to load both public and private keys to the FFI context or save them from the context.
`RNP_LOAD_SAVE_PERMISSIVE` (integer)
  Allows to ignore bad signature/key/subkey packets during key import.
`RNP_LOAD_SAVE_SINGLE` (integer)
  If set, only the first key will be loaded.
`RNP_LOAD_SAVE_BASE64` (integer)
  Allow import of base64-encoded keys (autocrypt ones).
`RNP_FEATURE_SYMM_ALG` (string)
  List available symmetric encryption algorithms.
`RNP_FEATURE_AEAD_ALG` (string)
  List available AEAD algorithms.
`RNP_FEATURE_PROT_MODE` (string)
  List available protection modes.
`RNP_FEATURE_PK_ALG` (string)
  List available public key algorithms.
`RNP_FEATURE_HASH_ALG` (string)
  List available hash algorithms.
`RNP_FEATURE_COMP_ALG` (string)
  List available compression algorithms.
`RNP_FEATURE_CURVE` (string)
  List available elliptic curves.
`RNP_DUMP_MPI` (integer)
  Dump MPI (Multi-precision integer) values.
`RNP_DUMP_RAW` (integer)
  Dump raw packet contents as well.
`RNP_DUMP_GRIP` (integer)
  Dump key fingerprints and grips.
`RNP_JSON_DUMP_MPI` (integer)
  Dump MPI (Multi-precision integer) values.
`RNP_JSON_DUMP_RAW` (integer)
  Dump raw packet contents as well.
`RNP_JSON_DUMP_GRIP` (integer)
  Dump key fingerprints and grips.
`RNP_ENCRYPT_NOWRAP` (integer)
  Allows encryption of signed message. Message is not wrapped into literal data packet.
`RNP_KEY_EXPORT_ARMORED` (integer)
  Enable ASCII-armoring of exported data.
`RNP_KEY_EXPORT_PUBLIC` (integer)
  Export public key.
`RNP_KEY_EXPORT_SECRET` (integer)
  Export secret key.
`RNP_KEY_EXPORT_SUBKEYS` (integer)
  If primary key is being exported, all subkeys will be exported too.
`RNP_KEY_EXPORT_BASE64` (integer)
  Export base64-encoded autocrypt key instead of binary.
`RNP_KEY_REMOVE_PUBLIC` (integer)
  Remove public key.
`RNP_KEY_REMOVE_SECRET` (integer)
  Remove secret key.
`RNP_KEY_REMOVE_SUBKEYS` (integer)
  If primary key is being deleted, all of its subkeys will be removed too.

# Beispiele

## Inhaltsverzeichnis

- Clearsign text

## Clearsign text

This example will clearsign a given text.

Beispiel #1 RNP clearsign example

    <?php
    // init FFI object
    $ffi = rnp_ffi_create('GPG', 'GPG');

    // generate RSA key
    $key = rnp_op_generate_key($ffi, 'test@example.com', 'RSA');

    // sign
    $data = "Example text to sign";
    $signature = rnp_op_sign_cleartext($ffi, $data, array($key));

    echo $signature;

    // destroy FFI object
    rnp_ffi_destroy($ffi);
    ?>

# Rnp Funktionen

# rnp_backend_string

(PECL rnp >= 0.1.1)

rnp_backend_string — Return cryptographic backend library name

### Beschreibung

function rnp_backend_string(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Backend name string. Currently supported backends are "Botan" and "OpenSSL".

# rnp_backend_version

(PECL rnp >= 0.1.1)

rnp_backend_version — Gibt die Version der kryptographischen Backend-Bibliothek zurück

### Beschreibung

function rnp_backend_version(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Versionszeichenkette.

# rnp_decrypt

(PECL rnp >= 0.1.1)

rnp_decrypt — Decrypt PGP message

### Beschreibung

function rnp_decrypt(RnpFFI `$ffi`, string `$input`): string|false

Private keys used for decryption should be loaded into the FFI object before calling this function. If password encryption was used, then password provider should be set by calling rnp_ffi_set_pass_provider().

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`input`
  Encrypted message.

### Rückgabewerte

Decrypted message on successBei einem Fehler wird `false` zurückgegeben..

# rnp_dump_packets

(PECL rnp >= 0.1.1)

rnp_dump_packets — Dump OpenPGP packets stream information in humand-readable format

### Beschreibung

function rnp_dump_packets(string `$input`, int `$flags`): string|false

### Parameter-Liste

`input`
  Input string containing OpenPGP data, either in binary or ASCII-armored format.
`flags`
  See `RNP_DUMP_*` predefined constants.

### Rückgabewerte

Text describing packet sequenceBei einem Fehler wird `false` zurückgegeben..

# rnp_dump_packets_to_json

(PECL rnp >= 0.1.1)

rnp_dump_packets_to_json — Dump OpenPGP packets stream information to the JSON string

### Beschreibung

function rnp_dump_packets_to_json(string `$input`, int `$flags`): string|false

### Parameter-Liste

`input`
  Input string containing OpenPGP data, either in binary or ASCII-armored format.
`flags`
  See `RNP_JSON_DUMP_*` predefined constants.

### Rückgabewerte

JSON string with dumpBei einem Fehler wird `false` zurückgegeben..

# rnp_ffi_create

(PECL rnp >= 0.1.1)

rnp_ffi_create — Create the top-level object used for interacting with the library

### Beschreibung

function rnp_ffi_create(string `$pub_format`, string `$sec_format`): RnpFFI|false

### Parameter-Liste

`pub_format`
  the format of the public keyring, RNP_KEYSTORE_GPG or other RNP_KEYSTORE_* constant.
`sec_format`
  the format of the secret keyring, RNP_KEYSTORE_GPG or other RNP_KEYSTORE_* constant

### Rückgabewerte

Returns RnpFFI object on successBei einem Fehler wird `false` zurückgegeben..

# rnp_ffi_destroy

(PECL rnp >= 0.1.1)

rnp_ffi_destroy — Destroy the top-level object used for interacting with the library

### Beschreibung

function rnp_ffi_destroy(RnpFFI `$ffi`): void

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.

### Rückgabewerte

# rnp_ffi_set_pass_provider

(PECL rnp >= 0.1.1)

rnp_ffi_set_pass_provider — Set password provider callback function

### Beschreibung

function rnp_ffi_set_pass_provider(RnpFFI `$ffi`, callable `$password_callback`): bool

Sets password provider function. This function can ask for the password on a standard input (if PHP script is executed in a command line environment), display GUI dialog or provide password in any other possible ways. Requested passwords are used to encrypt or decrypt secret keys or perform symmetric encryption/decryption operations.

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`password_callback`

  The function that is to be called for every password request. It has the following signature:

  function password_callback(string `$key_fp`, string `$pgp_context`, string `&$password`): bool
  - `$key_fp` - The key fingerprint, if any. Can be empty.
  - `$pgp_context` - String describing why the key is being requested.
  - `$password` - Password string reference where provided password should be stored to.
  Callback function should return `true` if password was successfully setBei einem Fehler wird `false` zurückgegeben..

### Rückgabewerte

Returns `true` on successBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 simple callback function example

    <?php
    function password_callback(string $key_fp, string $pgp_context, string &$password)
    {
        $password = "password";

        return true;
    }

    $ffi = rnp_ffi_create('GPG', 'GPG');

    rnp_ffi_set_pass_provider($ffi, 'password_callback');

# rnp_import_keys

(PECL rnp >= 0.1.1)

rnp_import_keys — Import keys from PHP string to the keyring and receive JSON describing new/updated keys

### Beschreibung

function rnp_import_keys(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`input`
  OpenPGP packets containing key(s) to be loaded. Can be either binary or ASCII armored.
`flags`
  See `RNP_LOAD_SAVE_*` predefined constants.

### Rückgabewerte

JSON string with information about new and updated keys on successBei einem Fehler wird `false` zurückgegeben..

# rnp_import_signatures

(PECL rnp >= 0.1.1)

rnp_import_signatures — Import standalone signatures to the keyring and receive JSON describing updated keys

### Beschreibung

function rnp_import_signatures(RnpFFI `$ffi`, string `$input`, int `$flags`): string|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`input`
  OpenPGP packets containing signatures to be imported. Can be either binary or ASCII armored.
`flags`
  Currently must be 0.

### Rückgabewerte

JSON string with information about updated keys on successBei einem Fehler wird `false` zurückgegeben..

# rnp_key_export

(PECL rnp >= 0.1.1)

rnp_key_export — Export a key

### Beschreibung

function rnp_key_export(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): string|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`key_fp`
  Key fingerprint.
`flags`
  See `RNP_KEY_EXPORT_*` predefined constants (except `RNP_KEY_EXPORT_BASE64`).

### Rückgabewerte

OpenPGP packets of exported key (binary or ASCII-armored) on successBei einem Fehler wird `false` zurückgegeben..

# rnp_key_export_autocrypt

(PECL rnp >= 0.1.1)

rnp_key_export_autocrypt — Export minimal key for autocrypt feature (just 5 packets: key, uid, signature, encryption subkey, signature)

### Beschreibung

function rnp_key_export_autocrypt(
RnpFFI `$ffi`,
string `$key_fp`,
string `$subkey_fp`,
string `$uid`,
int `$flags`
): string|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`key_fp`
  Primary key fingerprint.
`subkey_fp`
  Subkey to export. Can be an empty string to pick the first suitable subkey.
`uid`
  User ID to export. Can be an empty string if exported key has only one uid.
`flags`
  Only `RNP_KEY_EXPORT_BASE64` is currently supported. Enabling it would export base64-encoded key data instead of binary.

### Rückgabewerte

OpenPGP packets of exported key on successBei einem Fehler wird `false` zurückgegeben..

# rnp_key_export_revocation

(PECL rnp >= 0.1.1)

rnp_key_export_revocation — Generate and export primary key revocation signature

### Beschreibung

function rnp_key_export_revocation(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): string|false

Note: to revoke a key you'll need to import this signature into the keystore or use rnp_key_revoke() function.

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`key_fp`
  Key fingerprint of the primary key to be revoked.
`flags`
  `RNP_KEY_EXPORT_ARMORED` or 0.
`options`
  An associative array with options.

  Key | Data type | Beschreibung
  --- | --- | ---
  `"hash"` | string | Set hash algorithm used during signature calculation.
  `"code"` | string | Code reason for revocation code. Possible values: 'no', 'superseded', 'compromised', 'retired'. If not defined, then value 'no' will be used by default.
  `"reason"` | string | Textual representation of the reason for revocation.

### Rückgabewerte

Exported revocation signature on successBei einem Fehler wird `false` zurückgegeben..

# rnp_key_get_info

(PECL rnp >= 0.1.1)

rnp_key_get_info — Get information about the key

### Beschreibung

function rnp_key_get_info(RnpFFI `$ffi`, string `$key_fp`): array|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`key_fp`
  Key fingerprint.

### Rückgabewerte

An associative array with information about the keyBei einem Fehler wird `false` zurückgegeben..

Key | Data type | Beschreibung
--- | --- | ---
`"is_primary"` | boolean | `true` if this key is the primary key.
`"is_sub"` | boolean | `true` if this key is a subkey.
`"is_valid"` | boolean | `true` if public key is valid. This includes checks of the self-signatures, expiration times, revocations and so on.
`"is_revoked"` | boolean | `true` if this key is revoked.
`"is_superseded"` | boolean | `true` if this key is superseded. Present only if the key is revoked.
`"is_compromised"` | boolean | `true` if this key is compromised. Present only if the key is revoked.
`"is_retired"` | boolean | `true` if this key is retired. Present only if the key is revoked.
`"is_expired"` | boolean | `true` if this key is expired.
`"have_secret"` | boolean | `true` if this key has secret part.
`"is_locked"` | boolean | `true` if this key is currently locked. Only present for secret keys.
`"is_protected"` | boolean | `true` if this key is protected. Only present for secret keys. A protected key is one that is encrypted and can be safely held in memory and locked/unlocked as needed.
`"have_public"` | boolean | `true` if this key has public part. Generally all keys would have public part.
`"valid_till"` | integer | The timestamp till which key can be considered as valid. Note: this will take into account not only key's expiration, but revocations as well. For the subkey primary key's validity time will be also checked.
`"bits"` | integer | Number of bits in the key. For EC-based keys it will contain size of the curve.
`"alg"` | string | Key algorithm name.
`"subkeys"` | array | An indexed array containing fingerprint strings of subkeys. Only present for primary keys. Could be empty if primary key has no subkeys.
`"uids"` | array | An indexed array containing user ID strings. Only present for primary keys. Could be empty if primary key has no user ID-s.

# rnp_key_remove

(PECL rnp >= 0.1.1)

rnp_key_remove — Remove a key from keyring(s)

### Beschreibung

function rnp_key_remove(RnpFFI `$ffi`, string `$key_fp`, int `$flags`): bool

Note: you need to call rnp_save_keys() to write updated keyring(s) out.

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`key_fp`
  Key fingerprint.
`flags`
  See `RNP_KEY_REMOVE_*` constants. Flag `RNP_KEY_REMOVE_SUBKEYS` will work only for the primary key and will remove all of its subkeys as well.

### Rückgabewerte

Returns `true` on successBei einem Fehler wird `false` zurückgegeben..

# rnp_key_revoke

(PECL rnp >= 0.1.1)

rnp_key_revoke — Revoke a key or subkey by generating and adding revocation signature

### Beschreibung

function rnp_key_revoke(
RnpFFI `$ffi`,
string `$key_fp`,
int `$flags`,
array `$options` = ?
): bool

Note: you need to call rnp_save_keys() to write updated keyring(s) out.

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`key_fp`
  Key fingerprint.
`flags`
  Currently must be 0.
`options`
  An associative array with options.

  Key | Data type | Beschreibung
  --- | --- | ---
  `"hash"` | string | Set hash algorithm used during signature calculation.
  `"code"` | string | Code reason for revocation code. Possible values: 'no', 'superseded', 'compromised', 'retired'. If not defined, then value 'no' will be used by default.
  `"reason"` | string | Textual representation of the reason for revocation.

### Rückgabewerte

Returns `true` on successBei einem Fehler wird `false` zurückgegeben..

# rnp_list_keys

(PECL rnp >= 0.1.1)

rnp_list_keys — Enumerate all keys present in a keyring by specified identifer type

### Beschreibung

function rnp_list_keys(RnpFFI `$ffi`, string `$identifier_type`): array|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`identifier_type`
  Key identifier type ("userid", "keyid", "grip", "fingerprint").

### Rückgabewerte

An associative array where key is an identifier string and value is a PGP key fingerprintBei einem Fehler wird `false` zurückgegeben..

# rnp_load_keys

(PECL rnp >= 0.1.1)

rnp_load_keys — Load keys from PHP string

### Beschreibung

function rnp_load_keys(
RnpFFI `$ffi`,
string `$format`,
string `$input`,
int `$flags`
): bool

Note that for G10, the input must be a directory (which must already exist).

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`format`
  Das Schlüsselformat der Daten (GPG, KBX, G10).
`input`
  OpenPGP packets containing key(s) to be loaded. Can be either binary or ASCII armored.
`flags`
  Siehe die Beschreibung der `RNP_LOAD_SAVE_*`-Flags.

### Rückgabewerte

Returns `true` on successBei einem Fehler wird `false` zurückgegeben..

# rnp_load_keys_from_path

(PECL rnp >= 0.1.1)

rnp_load_keys_from_path — Load keys from specified path

### Beschreibung

function rnp_load_keys_from_path(
RnpFFI `$ffi`,
string `$format`,
string `$input_path`,
int `$flags`
): bool

Note that for G10, the input must be a directory (which must already exist).

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`format`
  Das Schlüsselformat der Daten (GPG, KBX, G10).
`input_path`
  file or directory containing the keys.
`flags`
  Siehe die Beschreibung der `RNP_LOAD_SAVE_*`-Flags.

### Rückgabewerte

Returns `true` on successBei einem Fehler wird `false` zurückgegeben..

# rnp_locate_key

(PECL rnp >= 0.1.1)

rnp_locate_key — Search for the key

### Beschreibung

function rnp_locate_key(RnpFFI `$ffi`, string `$identifier_type`, string `$identifier`): string|false

Note: only valid userids are checked while searching by userid.

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`identifier_type`
  Identifier type string: "userid", "keyid", "fingerprint", "grip".
`identifier`
  PGP User ID (name and email) for "userid" type, hexadecimal string that represents key id, fingerprint or key grip correspondingly.

### Rückgabewerte

Returns hexadecimal fingerprint of the key found on successBei einem Fehler wird `false` zurückgegeben..

# rnp_op_encrypt

(PECL rnp >= 0.1.1)

rnp_op_encrypt — Encrypt message

### Beschreibung

function rnp_op_encrypt(
RnpFFI `$ffi`,
string `$message`,
array `$recipient_keys_fp`,
array `$options` = ?
): string|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`message`
  Message to be encrypted.
`recipient_keys_fp`
  Array with fingerprints of recipient's keys. At least one key must be present.
`options`
  An associative array with options.

  Key | Data type | Beschreibung
  --- | --- | ---
  `"compression_alg"` | string | Compression algorithm. Both `"compression_alg"` and `"compression_level"` must be set in order to enable data compression.
  `"compression_level"` | integer | Compression level, 0-9. 0 disables compression.
  `"armor"` | boolean | Enable ASCII-armored output. Disabled by default.
  `"add_signature"` | boolean | Encrypted message will be also signed.
  `"hash"` | string | Set hash algorithm used during signature calculation. "add_signature" option should be set to `true`
  `"creation_time"` | integer | Set signature creation time in seconds since Jan, 1 1970 UTC. By default current time is used.
  `"expiration_time"` | integer | Set signature expiration time in seconds since the creation time. 0 value is used to mark signature as non-expiring (default value).
  `"password"` | string | Add password which is used to encrypt data.
  `"cipher"` | string | Set symmetric encryption algorithm. Possible values are "IDEA", "TRIPLEDES", "CAST5", "BLOWFISH", "AES128", "AES192", "AES256", "TWOFISH", "CAMELLIA128", "CAMELLIA192", "CAMELLIA256", "SM4".
  `"aead"` | string | Set AEAD mode algorithm. Possible values are "None" to disable AEAD, "EAX", "OCB".
  `"aead_bits"` | integer | Set chunk length for AEAD mode via number of chunk size bits. Must be between 0 to 56.
  `"flags"` | integer | Set additional encryption flags. Supported flags: RNP_ENCRYPT_NOWRAP - do not wrap the data in a literal data packet. This would allow to encrypt already signed data.
  `"file_name"` | string | Set the internally stored file name for the data being encrypted. Special value _CONSOLE may be used to mark message as 'for your eyes only', i.e. it should not be stored anywhere but only displayed to the receiver. Default is the empty string.
  `"file_mtime"` | integer | Set input file modification date in seconds since Jan, 1 1970 UTC.

### Rückgabewerte

Encrypted data on successBei einem Fehler wird `false` zurückgegeben..

# rnp_op_generate_key

(PECL rnp >= 0.1.1)

rnp_op_generate_key — Generate key

### Beschreibung

function rnp_op_generate_key(
RnpFFI `$ffi`,
string `$userid`,
string `$key_alg`,
string `$sub_alg` = ?,
array `$options` = ?
): string|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`userid`
  PGP User ID - text that is intended to represent the name and email address of the key holder.
`key_alg`
  Primary key algorithm (i.e. 'RSA', 'DSA', etc).
`sub_alg`
  Subkey algorithm. If not set, subkey will not be generated.
`options`
  An associative array with options.

  Key | Data type | Beschreibung
  --- | --- | ---
  `"bits"` | integer | Primary key size in bits. Applicable only to RSA, DSA and El-Gamal keys.
  `"hash"` | string | Hash algorithm used in self signature or subkey binding signature.
  `"dsa_qbits"` | integer | Set size of a `q` parameter for DSA key. Note: appropriate default value will be set, depending on key bits. However you may override it if needed.
  `"curve"` | string | Set the curve used for ECC key. Note: this is only applicable for ECDSA, ECDH and SM2 keys.
  `"request_password"` | boolean | Enable requesting password via password provider. This password will be used for key encryption. Password provider callback function should be set in advance by calling rnp_ffi_set_pass_provider(). Note: this setting will be ignored if password was set via`"password"`
  `"password"` | string | Set the password used to encrypt the secret key data.
  `"expiration"` | integer | Set the key and subkey expiration time in seconds.
  `"sub_bits"` | integer | Subkey size in bits. Applicable only to RSA, DSA and El-Gamal keys.
  `"sub_hash"` | string | Hash algorithm used in subkey self signature or subkey binding signature.
  `"sub_curve"` | string | Set the curve used for ECC subkey. Note: this is only applicable for ECDSA, ECDH and SM2 keys.

### Rückgabewerte

Fingerprint of the generated primary keyBei einem Fehler wird `false` zurückgegeben.. This fingerprint can be used later to reference the key in sign and encrypt operations. The key data is stored in FFI memory context and can be saved using rnp_save_keys() or rnp_save_keys_to_path().

# rnp_op_sign

(PECL rnp >= 0.1.1)

rnp_op_sign — Perform signing operation on a binary data, return embedded signature(s)

### Beschreibung

function rnp_op_sign(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`data`
  Data to be signed.
`keys_fp`
  Array with key fingerprints. At least one key must be provided. Keys should be present in `ffi`.
`options`
  An associative array with options.

  Key | Data type | Beschreibung
  --- | --- | ---
  `"compression_alg"` | string | Compression algorithm. Both `"compression_alg"` and `"compression_level"` must be set in order to enable data compression.
  `"compression_level"` | integer | Compression level, 0-9. 0 disables compression.
  `"armor"` | boolean | Enable ASCII-armored output. Disabled by default.
  `"hash"` | string | Set hash algorithm used during signature calculation.
  `"creation_time"` | integer | Set signature creation time in seconds since Jan, 1 1970 UTC. By default current time is used.
  `"expiration_time"` | integer | Set signature expiration time in seconds since the creation time. 0 value is used to mark signature as non-expiring (default value).
  `"file_name"` | string | Set input file name.Special value _CONSOLE may be used to mark message as 'for your eyes only', i.e. it should not be stored anywhere but only displayed to the receiver. Default is the empty string.
  `"file_mtime"` | integer | Set input file modification date in seconds since Jan, 1 1970 UTC.

### Rückgabewerte

Data with embedded signature(s) on successBei einem Fehler wird `false` zurückgegeben..

# rnp_op_sign_cleartext

(PECL rnp >= 0.1.1)

rnp_op_sign_cleartext — Perform signing operation on a textual data, return cleartext signed message

### Beschreibung

function rnp_op_sign_cleartext(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`data`
  Data to be signed.
`keys_fp`
  Array with key fingerprints. At least one key must be provided. Keys should be present in `ffi`.
`options`
  An associative array with options.

  Key | Data type | Beschreibung
  --- | --- | ---
  `"armor"` | boolean | Enable ASCII-armored output. Disabled by default.
  `"hash"` | string | Set hash algorithm used during signature calculation.
  `"creation_time"` | integer | Set signature creation time in seconds since Jan, 1 1970 UTC. By default current time is used.
  `"expiration_time"` | integer | Set signature expiration time in seconds since the creation time. 0 value is used to mark signature as non-expiring (default value).

### Rückgabewerte

Cleartext signed message containing source data with additional headers and ASCII-armored signature on successBei einem Fehler wird `false` zurückgegeben..

# rnp_op_sign_detached

(PECL rnp >= 0.1.1)

rnp_op_sign_detached — Perform signing operation, return detached signature(s)

### Beschreibung

function rnp_op_sign_detached(
RnpFFI `$ffi`,
string `$data`,
array `$keys_fp`,
array `$options` = ?
): string|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`data`
  Data to be signed.
`keys_fp`
  Array with key fingerprints. At least one key must be provided. Keys should be present in `ffi`.
`options`
  An associative array with options.

  Key | Data type | Beschreibung
  --- | --- | ---
  `"armor"` | boolean | Enable ASCII-armored output. Disabled by default.
  `"hash"` | string | Set hash algorithm used during signature calculation.
  `"creation_time"` | integer | Set signature creation time in seconds since Jan, 1 1970 UTC. By default current time is used.
  `"expiration_time"` | integer | Set signature expiration time in seconds since the creation time. 0 value is used to mark signature as non-expiring (default value).

### Rückgabewerte

Detached signature(s) data on successBei einem Fehler wird `false` zurückgegeben..

# rnp_op_verify

(PECL rnp >= 0.1.1)

rnp_op_verify — Verify embedded or cleartext signatures

### Beschreibung

function rnp_op_verify(RnpFFI `$ffi`, string `$data`): array|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`data`
  Signed data.

### Rückgabewerte

An associative array with information about verification resultsBei einem Fehler wird `false` zurückgegeben..

Key | Data type | Beschreibung
--- | --- | ---
`"verification_status"` | string | Overall verification result, either "Success" string or appropriate error message. "Success" result is set when at least one signature is valid and successfully verified. Individual verification results for each signature can be checked in the "signatures" array.
`"file_name"` | string | File name.
`"file_mtime"` | integer | File modification time.
`"mode"` | string | Data protection (encryption) mode used in processed message. Currently defined values are "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
`"cipher"` | string | Symmetric cipher used for data encryption.
`"valid_integrity"` | boolean | `true` if message integrity protection was used (i.e. MDC or AEAD) and it was validated successfully.
`"signatures"` | array | An associative array describing each signature found. See description below.

"signatures" sub-array.

Key | Data type | Beschreibung
--- | --- | ---
"verification_status" | string | Signature verification status, either "Success" string or appropriate error message.
"creation_time" | integer | Signature creation time in seconds since Jan, 1 1970 UTC.
"expiration_time" | integer | Signature expiration time in seconds since the creation time or 0 if signature never expires.
"hash" | string | Hash function algorithm used to calculate the signature.
"signing_key" | string | Fingerprint of the key used for signing. Could be "Not found" if corresponding public key is not loaded to the FFI object.
"signature_type" | string | Signature type. Currently defined values are: 'binary', 'text', 'standalone', 'certification (generic)', 'certification (persona)', 'certification (casual)', 'certification (positive)', 'subkey binding', 'primary key binding', 'direct', 'key revocation', 'subkey revocation', 'certification revocation', 'timestamp', 'uknown: 0..255'.

# rnp_op_verify_detached

(PECL rnp >= 0.1.1)

rnp_op_verify_detached — Verify detached signatures

### Beschreibung

function rnp_op_verify_detached(RnpFFI `$ffi`, string `$data`, string `$signature`): array|false

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`data`
  Source data.
`signature`
  Detached signature data.

### Rückgabewerte

An associative array with information about verification resultsBei einem Fehler wird `false` zurückgegeben..

Key | Data type | Beschreibung
--- | --- | ---
`"verification_status"` | string | Overall verification result, either "Success" string or appropriate error message. "Success" result is set when at least one signature is valid and successfully verified. Individual verification results for each signature can be checked in the "signatures" array.
`"file_name"` | string | File name.
`"file_mtime"` | integer | File modification time.
`"mode"` | string | Data protection (encryption) mode used in processed message. Currently defined values are "none", "cfb", "cfb-mdc", "aead-ocb", "aead-eax".
`"cipher"` | string | Symmetric cipher used for data encryption.
`"valid_integrity"` | boolean | `true` if message integrity protection was used (i.e. MDC or AEAD) and it was validated successfully.
`"signatures"` | array | An associative array describing each signature found. See description below.

"signatures" sub-array.

Key | Data type | Beschreibung
--- | --- | ---
"verification_status" | string | Signature verification status, either "Success" string or appropriate error message.
"creation_time" | integer | Signature creation time in seconds since Jan, 1 1970 UTC.
"expiration_time" | integer | Signature expiration time in seconds since the creation time or 0 if signature never expires.
"hash" | string | Hash function algorithm used to calculate the signature.
"signing_key" | string | Fingerprint of the key used for signing. Could be "Not found" if corresponding public key is not loaded to the FFI object.
"signature_type" | string | Signature type. Currently defined values are: 'binary', 'text', 'standalone', 'certification (generic)', 'certification (persona)', 'certification (casual)', 'certification (positive)', 'subkey binding', 'primary key binding', 'direct', 'key revocation', 'subkey revocation', 'certification revocation', 'timestamp', 'uknown: 0..255'.

# rnp_save_keys

(PECL rnp >= 0.1.1)

rnp_save_keys — Save keys to PHP string

### Beschreibung

function rnp_save_keys(
RnpFFI `$ffi`,
string `$format`,
string `&$output`,
int `$flags`
): bool

Note that for G10, the output must be a directory (which must already exist).

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`format`
  Das Schlüsselformat der Daten (GPG, KBX, G10).
`output`
  key packets will be saved to the string referenced by `output`.
`flags`
  Siehe die Beschreibung der `RNP_LOAD_SAVE_*`-Flags.

### Rückgabewerte

Returns `true` on successBei einem Fehler wird `false` zurückgegeben..

# rnp_save_keys_to_path

(PECL rnp >= 0.1.1)

rnp_save_keys_to_path — Save keys to specified path

### Beschreibung

function rnp_save_keys_to_path(
RnpFFI `$ffi`,
string `$format`,
string `$output_path`,
int `$flags`
): bool

Saves keys present in the FFI object (loaded or generated) to the specified file or directory.

### Parameter-Liste

`ffi`
  Das von rnp_ffi_create() zurückgegebene FFI-Objekt.
`format`
  Das Schlüsselformat der Daten (GPG, KBX, G10).
`output_path`
  File or directory path where keys should be saved to.
`flags`
  Siehe die Beschreibung der `RNP_LOAD_SAVE_*`-Flags.

### Rückgabewerte

Returns `true` on successBei einem Fehler wird `false` zurückgegeben..

# rnp_supported_features

(PECL rnp >= 0.1.1)

rnp_supported_features — Get supported features in JSON format

### Beschreibung

function rnp_supported_features(string `$type`): string|false

Get the JSON formatted string containing array of supported rnp feature values (algorithms, curves, etc) by type.

### Parameter-Liste

`type`
  See RNP_FEATURE_* constants for supported values.

### Rückgabewerte

String containing JSON formatted array of supported algorithms, curves, etcBei einem Fehler wird `false` zurückgegeben..

# rnp_version_string

(PECL rnp >= 0.1.1)

rnp_version_string — Version der RNP-Bibliothek

### Beschreibung

function rnp_version_string(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Versionszeichenkette der RNP-Bibliothek zurück.

# rnp_version_string_full

(PECL rnp >= 0.1.1)

rnp_version_string_full — Vollständige Versionszeichenkette der RNP-Bibliothek

### Beschreibung

function rnp_version_string_full(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die vollständige Versionszeichenkette der RNP-Bibliothek zurück.

## Inhaltsverzeichnis

- rnp_backend_string — Return cryptographic backend library name
- rnp_backend_version — Gibt die Version der kryptographischen Backend-Bibliothek zurück
- rnp_decrypt — Decrypt PGP message
- rnp_dump_packets — Dump OpenPGP packets stream information in humand-readable format
- rnp_dump_packets_to_json — Dump OpenPGP packets stream information to the JSON string
- rnp_ffi_create — Create the top-level object used for interacting with the library
- rnp_ffi_destroy — Destroy the top-level object used for interacting with the library
- rnp_ffi_set_pass_provider — Set password provider callback function
- rnp_import_keys — Import keys from PHP string to the keyring and receive JSON describing new/updated keys
- rnp_import_signatures — Import standalone signatures to the keyring and receive JSON describing updated keys
- rnp_key_export — Export a key
- rnp_key_export_autocrypt — Export minimal key for autocrypt feature (just 5 packets: key, uid, signature, encryption subkey, signature)
- rnp_key_export_revocation — Generate and export primary key revocation signature
- rnp_key_get_info — Get information about the key
- rnp_key_remove — Remove a key from keyring(s)
- rnp_key_revoke — Revoke a key or subkey by generating and adding revocation signature
- rnp_list_keys — Enumerate all keys present in a keyring by specified identifer type
- rnp_load_keys — Load keys from PHP string
- rnp_load_keys_from_path — Load keys from specified path
- rnp_locate_key — Search for the key
- rnp_op_encrypt — Encrypt message
- rnp_op_generate_key — Generate key
- rnp_op_sign — Perform signing operation on a binary data, return embedded signature(s)
- rnp_op_sign_cleartext — Perform signing operation on a textual data, return cleartext signed message
- rnp_op_sign_detached — Perform signing operation, return detached signature(s)
- rnp_op_verify — Verify embedded or cleartext signatures
- rnp_op_verify_detached — Verify detached signatures
- rnp_save_keys — Save keys to PHP string
- rnp_save_keys_to_path — Save keys to specified path
- rnp_supported_features — Get supported features in JSON format
- rnp_version_string — Version der RNP-Bibliothek
- rnp_version_string_full — Vollständige Versionszeichenkette der RNP-Bibliothek

# The RnpFFI class

(PECL rnp >= 0.1.1)

## Einführung

## Klassenbeschreibung

class RnpFFI {
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Vordefinierte Konstanten
- Beispiele
  - Clearsign text
- Rnp Funktionen
  - rnp_backend_string — Return cryptographic backend library name
  - rnp_backend_version — Gibt die Version der kryptographischen Backend-Bibliothek zurück
  - rnp_decrypt — Decrypt PGP message
  - rnp_dump_packets — Dump OpenPGP packets stream information in humand-readable format
  - rnp_dump_packets_to_json — Dump OpenPGP packets stream information to the JSON string
  - rnp_ffi_create — Create the top-level object used for interacting with the library
  - rnp_ffi_destroy — Destroy the top-level object used for interacting with the library
  - rnp_ffi_set_pass_provider — Set password provider callback function
  - rnp_import_keys — Import keys from PHP string to the keyring and receive JSON describing new/updated keys
  - rnp_import_signatures — Import standalone signatures to the keyring and receive JSON describing updated keys
  - rnp_key_export — Export a key
  - rnp_key_export_autocrypt — Export minimal key for autocrypt feature (just 5 packets: key, uid, signature, encryption subkey, signature)
  - rnp_key_export_revocation — Generate and export primary key revocation signature
  - rnp_key_get_info — Get information about the key
  - rnp_key_remove — Remove a key from keyring(s)
  - rnp_key_revoke — Revoke a key or subkey by generating and adding revocation signature
  - rnp_list_keys — Enumerate all keys present in a keyring by specified identifer type
  - rnp_load_keys — Load keys from PHP string
  - rnp_load_keys_from_path — Load keys from specified path
  - rnp_locate_key — Search for the key
  - rnp_op_encrypt — Encrypt message
  - rnp_op_generate_key — Generate key
  - rnp_op_sign — Perform signing operation on a binary data, return embedded signature(s)
  - rnp_op_sign_cleartext — Perform signing operation on a textual data, return cleartext signed message
  - rnp_op_sign_detached — Perform signing operation, return detached signature(s)
  - rnp_op_verify — Verify embedded or cleartext signatures
  - rnp_op_verify_detached — Verify detached signatures
  - rnp_save_keys — Save keys to PHP string
  - rnp_save_keys_to_path — Save keys to specified path
  - rnp_supported_features — Get supported features in JSON format
  - rnp_version_string — Version der RNP-Bibliothek
  - rnp_version_string_full — Vollständige Versionszeichenkette der RNP-Bibliothek
- RnpFFI — The RnpFFI class

# Sodium

# Einführung

Sodium ist eine moderne und einfach zu bedienende Software-Bibliothek für Verschlüsselungen, Entschlüsselungen, Signaturen, Passwort-Hashing und mehr. Ihr Ziel ist es, alle grundlegenden Operationen zur Verfügung zu stellen, die für die Entwicklung von kryptographischen Werkzeugen auf höherer Ebene erforderlich sind.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

Diese Erweiterung benötigt » libsodium ≥ 1.0.8.

## Installation

Ab PHP 7.2.0 ist diese Erweiterung im Lieferumfang von PHP enthalten. Für ältere PHP-Versionen ist diese Erweiterung über PECL verfügbar.

## Linux-Systeme

Um diese Erweiterung nutzen zu können, muss PHP mit Sodium-Unterstützung kompiliert werden, indem die --with-sodium[=DIR]-Option verwendet wird.

## Windows

Um die Erweiterung zu nutzen muss php_sodium.dll in die php.ini hinzugefügt werden.

## Installation mittels PECL

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/libsodium

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`SODIUM_LIBRARY_VERSION` (string)
`SODIUM_LIBRARY_MAJOR_VERSION` (int)
`SODIUM_LIBRARY_MINOR_VERSION` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL` (int)
`SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` (int)
`SODIUM_BASE64_VARIANT_URLSAFE` (int)
`SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` (int)
`SODIUM_CRYPTO_AEAD_AEGIS128L_KEYBYTES` (int)
  Verfügbar ab PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NSECBYTES` (int)
  Verfügbar ab PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES` (int)
  Verfügbar ab PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS128L_ABYTES` (int)
  Verfügbar ab PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES` (int)
  Verfügbar ab PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NSECBYTES` (int)
  Verfügbar ab PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES` (int)
  Verfügbar ab PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AEGIS256_ABYTES` (int)
  Verfügbar ab PHP 8.4.0.
`SODIUM_CRYPTO_AEAD_AES256GCM_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_AES256GCM_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_CHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_ABYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES` (int)
`SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NSECBYTES` (int)
`SODIUM_CRYPTO_AUTH_BYTES` (int)
`SODIUM_CRYPTO_AUTH_KEYBYTES` (int)
`SODIUM_CRYPTO_BOX_SEALBYTES` (int)
`SODIUM_CRYPTO_BOX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_BOX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_BOX_MACBYTES` (int)
`SODIUM_CRYPTO_BOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_BOX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KDF_BYTES_MIN` (int)
`SODIUM_CRYPTO_KDF_BYTES_MAX` (int)
`SODIUM_CRYPTO_KDF_CONTEXTBYTES` (int)
`SODIUM_CRYPTO_KDF_KEYBYTES` (int)
`SODIUM_CRYPTO_KX_SEEDBYTES` (int)
`SODIUM_CRYPTO_KX_SESSIONKEYBYTES` (int)
`SODIUM_CRYPTO_KX_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_KX_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_KX_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_BYTES_MAX` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MIN` (int)
`SODIUM_CRYPTO_GENERICHASH_KEYBYTES_MAX` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13` (int)
`SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (int)
`SODIUM_CRYPTO_PWHASH_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_STRPREFIX` (string)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE` (int)
`SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_STRPREFIX` (string)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE` (int)
`SODIUM_CRYPTO_CORE_RISTRETTO255_BYTES` (int)
  Verfügbar ab PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_HASHBYTES` (int)
  Verfügbar ab PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_NONREDUCEDSCALARBYTES` (int)
  Verfügbar ab PHP 8.1.0.
`SODIUM_CRYPTO_CORE_RISTRETTO255_SCALARBYTES` (int)
  Verfügbar ab PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_BYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_SCALARBYTES` (int)
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_BYTES` (int)
  Verfügbar ab PHP 8.1.0.
`SODIUM_CRYPTO_SCALARMULT_RISTRETTO255_SCALARBYTES` (int)
  Verfügbar ab PHP 8.1.0.
`SODIUM_CRYPTO_SHORTHASH_BYTES` (int)
`SODIUM_CRYPTO_SHORTHASH_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_MACBYTES` (int)
`SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_ABYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_HEADERBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_KEYBYTES` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_MESSAGEBYTES_MAX` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH` (int)
`SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY` (int)
`SODIUM_CRYPTO_SIGN_BYTES` (int)
`SODIUM_CRYPTO_SIGN_SEEDBYTES` (int)
`SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_SECRETKEYBYTES` (int)
`SODIUM_CRYPTO_SIGN_KEYPAIRBYTES` (int)
`SODIUM_CRYPTO_STREAM_NONCEBYTES` (int)
`SODIUM_CRYPTO_STREAM_KEYBYTES` (int)
`SODIUM_CRYPTO_STREAM_XCHACHA20_KEYBYTES` (int)
  Verfügbar ab PHP 8.1.0.
`SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES` (int)
  Verfügbar ab PHP 8.1.0.

# Sodium Funktionen

# sodium_add

(PHP 7 >= 7.2.0, PHP 8)

sodium_add — Addition großer Zahlen

### Beschreibung

function sodium_add(string `&$string1`, string `$string2`): void

Diese Funktion addiert den Parameter `string2` zu `string1` hinzu und überschreibt den in `string1` gespeicherten Wert. Diese Funktion geht davon aus, dass beide Parameter binäre Zeichenketten (Strings) sind, die vorzeichenlose Ganzzahlen in Little-Endian-Byte-Reihenfolge darstellen.

### Parameter-Liste

`string1`
  Eine Zeichenkette, die eine vorzeichenlose Ganzzahl beliebiger Länge in Little-Endian-Byte-Reihenfolge darstellt. Dieser Parameter wird als Referenz übergeben und enthält die Summe der beiden Parameter.
`string2`
  Eine Zeichenkette, die eine vorzeichenlose Ganzzahl beliebiger Länge in Little-Endian-Byte-Reihenfolge darstellt.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# sodium_base642bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_base642bin — Dekodiert eine Base64-kodierte Zeichenkette in das Binärformat.

### Beschreibung

function sodium_base642bin(#[\SensitiveParameter]string `$string`, int `$id`, string `$ignore` = ""): string

Konvertiert eine Base64-kodierte Zeichenkette in das Binärformat. Anders als base64_decode() und sodium_base642bin() ist die Funktion zeitkonstant (eine Eigenschaft, welche für jeden Programmcode wichtig ist, der kryptographische Eingaben wie Klartexte oder Schlüssel verarbeitet) und unterstützt mehrere Zeichensätze.

### Parameter-Liste

`string`
  string; Kodierte Zeichenfolge.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` für die Standard-Base64-Kodierung (`A-Za-z0-9/\+`).
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` für die Standard-Base64-Kodierung (`A-Za-z0-9/\+`), ohne `=`-Auffüllzeichen.
  - `SODIUM_BASE64_VARIANT_URLSAFE` für URL-sichere (URL-safe) (`A-Za-z0-9\-_`) Base64-Kodierung.
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` für URL-sichere (URL-safe) (`A-Za-z0-9\-_`) Base64-Kodierung, ohne `=`-Auffüllzeichen.
`ignore`
  Zeichen, die bei der Dekodierung ignoriert werden sollen (z. B. Leerzeichen).

### Rückgabewerte

Dekodierte Zeichenkette.

# sodium_bin2base64

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2base64 — Kodiert eine binäre Zeichenkette mit Base64.

### Beschreibung

function sodium_bin2base64(#[\SensitiveParameter]string `$string`, int `$id`): string

Konvertiert eine Zeichenkette in eine Base64-kodierte Zeichenkette. Anders als base64_encode() und sodium_bin2base64() ist die Funktion zeitkonstant (eine Eigenschaft, welche für jeden Programmcode wichtig ist, der kryptographische Eingaben, wie Klartexte oder Schlüssel, verarbeitet) und unterstützt mehrere Zeichensätze.

### Parameter-Liste

`string`
  Rohbinäre Zeichenfolge.
`id`
  - `SODIUM_BASE64_VARIANT_ORIGINAL` für die Standard-Base64-Kodierung (`A-Za-z0-9/\+`).
  - `SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING` für die Standard-Base64-Kodierung (`A-Za-z0-9/\+`), ohne `=`-Auffüllzeichen.
  - `SODIUM_BASE64_VARIANT_URLSAFE` für URL-sichere (URL-safe) (`A-Za-z0-9\-_`) Base64-Kodierung.
  - `SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING` für URL-sichere (URL-safe) (`A-Za-z0-9\-_`) Base64-Kodierung, ohne `=`-Auffüllzeichen.

### Rückgabewerte

Base64-enkodierte Zeichenkette.

# sodium_bin2hex

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2hex — Kodiert in Hexadezimal

### Beschreibung

function sodium_bin2hex(#[\SensitiveParameter]string `$string`): string

Konvertiert eine rohbinäre Zeichenkette in eine hexadezimal kodierte Zeichenkette. Anders als sodium_bin2hex() ist die Funktion zeitkonstant (eine Eigenschaft, welche für jeden Programmcode wichtig ist, der kryptographische Eingaben, wie Klartexte oder Schlüssel, verarbeitet).

### Parameter-Liste

`string`
  Rohbinäre Zeichenfolge.

### Rückgabewerte

Hexadezimal kodierte Zeichenkette.

# sodium_compare

(PHP 7 >= 7.2.0, PHP 8)

sodium_compare — Vergleicht große Zahlen

### Beschreibung

function sodium_compare(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

Vergleicht zwei Zeichenketten, als ob sie beliebig lange, vorzeichenlose Little-Endian-Ganzzahlen wären, ohne dass eine Seitenkanalattacke möglich ist.

### Parameter-Liste

`string1`
  Linker Operand
`string2`
  Rechter Operand

### Rückgabewerte

Gibt `-1` zurück, wenn `string1` kleiner als `string2` ist.

Gibt `1` zurück, wenn `string1` größer als `string2` ist.

Gibt `0` zurück, wenn beide Zeichenketten identisch sind.

# sodium_crypto_aead_aegis128l_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_decrypt — Verify then decrypt a message with AEGIS-128L

### Beschreibung

function sodium_crypto_aead_aegis128l_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verify then decrypt a message with AEGIS-128L.

### Parameter-Liste

`ciphertext`
  Must be in the format provided by sodium_crypto_aead_aegis128l_encrypt().
`additional_data`
  Additional, authenticated data. This is used in the verification of the authentication tag appended to the ciphertext, but it is not encrypted or stored in the ciphertext.
`nonce`
  A number that must be only used once, per message.
`key`
  Encryption key (128-bit).

### Rückgabewerte

Returns the plaintext on success, Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- sodium_crypto_aead_aegis128l_encrypt() - Encrypt then authenticate a message with AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Generate a random AEGIS-128L key

# sodium_crypto_aead_aegis128l_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_encrypt — Encrypt then authenticate a message with AEGIS-128L

### Beschreibung

function sodium_crypto_aead_aegis128l_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Encrypt then authenticate a message with AEGIS-128L.

### Parameter-Liste

`message`
  The plaintext message to encrypt.
`additional_data`
  Additional, authenticated data. This is used in the verification of the authentication tag appended to the ciphertext, but it is not encrypted or stored in the ciphertext.
`nonce`
  A number that must be only used once, per message.
`key`
  Encryption key (128-bit).

### Rückgabewerte

Returns the ciphertext and authentication tag as a string of raw binary bytes.

### Siehe auch

- sodium_crypto_aead_aegis128l_decrypt() - Verify then decrypt a message with AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen() - Generate a random AEGIS-128L key

# sodium_crypto_aead_aegis128l_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_keygen — Generate a random AEGIS-128L key

### Beschreibung

function sodium_crypto_aead_aegis128l_keygen(): string

Generate a random key for use with sodium_crypto_aead_aegis128l_encrypt() and sodium_crypto_aead_aegis128l_decrypt().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a 128-bit random key.

### Siehe auch

- sodium_crypto_aead_aegis128l_decrypt() - Verify then decrypt a message with AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt() - Encrypt then authenticate a message with AEGIS-128L

# sodium_crypto_aead_aegis256_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_decrypt — Verify then decrypt a message with AEGIS-256

### Beschreibung

function sodium_crypto_aead_aegis256_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verify then decrypt a message with AEGIS-256.

### Parameter-Liste

`ciphertext`
  Must be in the format provided by sodium_crypto_aead_aegis256_encrypt().
`additional_data`
  Additional, authenticated data. This is used in the verification of the authentication tag appended to the ciphertext, but it is not encrypted or stored in the ciphertext.
`nonce`
  A number that must be only used once, per message.
`key`
  Encryption key (256-bit).

### Rückgabewerte

Returns the plaintext on success, Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- sodium_crypto_aead_aegis256_encrypt() - Encrypt then authenticate a message with AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Generate a random AEGIS-256 key

# sodium_crypto_aead_aegis256_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_encrypt — Encrypt then authenticate a message with AEGIS-256

### Beschreibung

function sodium_crypto_aead_aegis256_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Encrypt then authenticate a message with AEGIS-256.

### Parameter-Liste

`message`
  The plaintext message to encrypt.
`additional_data`
  Additional, authenticated data. This is used in the verification of the authentication tag appended to the ciphertext, but it is not encrypted or stored in the ciphertext.
`nonce`
  A number that must be only used once, per message.
`key`
  Encryption key (256-bit).

### Rückgabewerte

Returns the ciphertext and authentication tag as a string of raw binary bytes.

### Siehe auch

- sodium_crypto_aead_aegis256_decrypt() - Verify then decrypt a message with AEGIS-256
- sodium_crypto_aead_aegis256_keygen() - Generate a random AEGIS-256 key

# sodium_crypto_aead_aegis256_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_keygen — Generate a random AEGIS-256 key

### Beschreibung

function sodium_crypto_aead_aegis256_keygen(): string

Generate a random key for use with sodium_crypto_aead_aegis256_encrypt() and sodium_crypto_aead_aegis256_decrypt().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a 256-bit random key.

### Siehe auch

- sodium_crypto_aead_aegis256_decrypt() - Verify then decrypt a message with AEGIS-256
- sodium_crypto_aead_aegis256_encrypt() - Encrypt then authenticate a message with AEGIS-256

# sodium_crypto_aead_aes256gcm_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_decrypt — Überprüft und entschlüsselt eine Nachricht mit AES-256-GCM

### Beschreibung

function sodium_crypto_aead_aes256gcm_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Überprüft und entschlüsselt eine Nachricht mit AES-256-GCM. Nur verfügbar, wenn sodium_crypto_aead_aes256gcm_is_available() `true` zurückgibt.

### Parameter-Liste

`ciphertext`
  Muss das von der Funktion sodium_crypto_aead_aes256gcm_encrypt() bereitgestellte Format haben (Chiffretext und Tag, verknüpft).
`additional_data`
  Zusätzliche, zu authentifizierende Daten. Diese Daten werden weder verschlüsselt, noch an den Chiffriertext angehängt.
`nonce`
  Eine Nummer, die nur einmal pro Nachricht verwendet werden darf; 12 Bytes lang.
`key`
  Schlüssel für die Entschlüsselung (256-bit).

### Rückgabewerte

Gibt im Erfolgsfall den Klartext zurück. Bei einem Fehler wird `false` zurückgegeben.

# sodium_crypto_aead_aes256gcm_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_encrypt — Verschlüsselt und authentifiziert eine Nachricht mit AES-256-GCM

### Beschreibung

function sodium_crypto_aead_aes256gcm_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Verschlüsselt und authentifiziert eine Nachricht mit AES-256-GCM. Nur verfügbar, wenn sodium_crypto_aead_aes256gcm_is_available() `true` zurückgibt.

### Parameter-Liste

`message`
  Der Klartext, welcher verschlüsselt werden soll.
`additional_data`
  Zusätzliche, zu authentifizierende Daten. Diese Daten werden weder verschlüsselt, noch an den Chiffriertext angehängt.
`nonce`
  Eine Nummer, die nur einmal pro Nachricht verwendet werden darf; 12 Bytes lang.
`key`
  Schlüssel für die Verschlüsselung (256-bit).

### Rückgabewerte

Gibt den Chiffriertext und das Authentifizierungskennzeichen als rohbinäre Zeichenfolge zurück. (Format: Chiffriertext, dann Tag).

# sodium_crypto_aead_aes256gcm_is_available

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_is_available — Prüft, ob die Hardware AES256-GCM unterstützt

### Beschreibung

function sodium_crypto_aead_aes256gcm_is_available(): bool

Der Rückgabewert dieser Funktion hängt davon ab, ob die Hardware hardwarebeschleunigtes AES unterstützt oder nicht.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn es ist sicher ist mit AES-256-GCM zu verschlüsseln, und `false` wenn nicht.

# sodium_crypto_aead_aes256gcm_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_keygen — Generiert einen zufälligen AES-256-GCM-Schlüssel

### Beschreibung

function sodium_crypto_aead_aes256gcm_keygen(): string

Generiert einen zufälligen Schlüssel für die Nutzung von sodium_crypto_aead_aes256gcm_encrypt() und sodium_crypto_aead_aes256gcm_decrypt().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen 256-Bit-Zufallsschlüssel zurück.

# sodium_crypto_aead_chacha20poly1305_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_decrypt — Überprüft und entschlüsselt eine Nachricht mit ChaCha20-Poly1305

### Beschreibung

function sodium_crypto_aead_chacha20poly1305_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Überprüft und entschlüsselt eine Nachricht mit ChaCha20-Poly1305.

### Parameter-Liste

`ciphertext`
  Muss das von der Funktion sodium_crypto_aead_chacha20poly1305_encrypt() bereitgestellte Format haben (Chiffretext und Tag, verknüpft).
`additional_data`
  Zusätzliche, zu authentifizierende Daten. Diese Daten werden weder verschlüsselt, noch an den Chiffriertext angehängt.
`nonce`
  Eine Nummer, die nur einmal pro Nachricht verwendet werden darf; 8 Bytes lang.
`key`
  Schlüssel für die Entschlüsselung (256-bit).

### Rückgabewerte

Gibt im Erfolgsfall den Klartext zurück. Bei einem Fehler wird `false` zurückgegeben.

# sodium_crypto_aead_chacha20poly1305_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_encrypt — Verschlüsselt und authentifiziert eine Nachricht mit ChaCha20-Poly1305

### Beschreibung

function sodium_crypto_aead_chacha20poly1305_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Verschlüsselt und authentifiziert eine Nachricht mit ChaCha20-Poly1305.

### Parameter-Liste

`message`
  Der Klartext, welcher verschlüsselt werden soll.
`additional_data`
  Zusätzliche, zu authentifizierende Daten. Diese Daten werden weder verschlüsselt, noch an den Chiffriertext angehängt.
`nonce`
  Eine Nummer, die nur einmal pro Nachricht verwendet werden darf; 8 Bytes lang.
`key`
  Schlüssel für die Verschlüsselung (256-bit).

### Rückgabewerte

Gibt bei Erfolg den Chiffriertext und das Tag zurück. Bei einem Fehler wird `false` zurückgegeben.

# sodium_crypto_aead_chacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Überprüft, ob der Chiffriertext ein gültiges Tag enthält

### Beschreibung

function sodium_crypto_aead_chacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Verschlüsselt und authentifiziert eine Nachricht mit ChaCha20-Poly1305 (IETF-Variante).

Die IETF-Variante verwendet 96-Bit-Nonces und interne 32-Bit Zähler anstelle von 64-Bit für beides.

### Parameter-Liste

`ciphertext`
  Muss das von der Funktion sodium_crypto_aead_chacha20poly1305_ietf_encrypt() bereitgestellte Format haben (Chiffretext und Tag, verknüpft).
`additional_data`
  Zusätzliche, zu authentifizierende Daten. Diese Daten werden weder verschlüsselt, noch an den Chiffriertext angehängt.
`nonce`
  Eine Nummer, die nur einmal pro Nachricht verwendet werden darf; 12 Bytes lang.
`key`
  Schlüssel für die Entschlüsselung (256-bit).

### Rückgabewerte

Gibt im Erfolgsfall den Klartext zurück. Bei einem Fehler wird `false` zurückgegeben.

# sodium_crypto_aead_chacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Verschlüsselt eine Nachricht

### Beschreibung

function sodium_crypto_aead_chacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Verschlüsselt und authentifiziert eine Nachricht mit ChaCha20-Poly1305 (IETF-Variante).

Die IETF-Variante verwendet 96-Bit-Nonces und interne 32-Bit Zähler anstelle von 64-Bit für beides.

### Parameter-Liste

`message`
  Der Klartext, welcher verschlüsselt werden soll.
`additional_data`
  Zusätzliche, zu authentifizierende Daten. Diese Daten werden weder verschlüsselt, noch an den Chiffriertext angehängt.
`nonce`
  Eine Nummer, die nur einmal pro Nachricht verwendet werden darf; 12 Bytes lang.
`key`
  Schlüssel für die Verschlüsselung (256-bit).

### Rückgabewerte

Gibt bei Erfolg den Chiffriertext und das Tag zurück. Bei einem Fehler wird `false` zurückgegeben.

# sodium_crypto_aead_chacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_keygen — Generiert einen zufälligen ChaCha20-Poly1305-IETF-Schlüssel.

### Beschreibung

function sodium_crypto_aead_chacha20poly1305_ietf_keygen(): string

Generiert einen zufälligen Schlüssel für die Nutzung von sodium_crypto_aead_chacha20poly1305_ietf_encrypt() und sodium_crypto_aead_chacha20poly1305_ietf_decrypt().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen 256-Bit-Zufallsschlüssel zurück.

# sodium_crypto_aead_chacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_keygen — Generiert einen zufälligen ChaCha20-Poly1305-Schlüssel

### Beschreibung

function sodium_crypto_aead_chacha20poly1305_keygen(): string

Generiert einen zufälligen Schlüssel für die Nutzung von sodium_crypto_aead_chacha20poly1305_encrypt() und sodium_crypto_aead_chacha20poly1305_decrypt().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen 256-Bit-Zufallsschlüssel zurück.

# sodium_crypto_aead_xchacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Empfohlen) Überprüft und entschlüsselt eine Nachricht mit XChaCha20-Poly1305

### Beschreibung

function sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string|false

Überprüft und entschlüsselt eine Nachricht mit ChaCha20-Poly1305 (Erweiterte-Nonce-Variante).

Im Allgemeinen ist XChaCha20-Poly1305 der beste der angebotenen AEAD-Modi.

### Parameter-Liste

`ciphertext`
  Muss das von der Funktion sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() bereitgestellte Format haben (Chiffretext und Tag, verknüpft).
`additional_data`
  Zusätzliche, zu authentifizierende Daten. Diese Daten werden weder verschlüsselt, noch an den Chiffriertext angehängt.
`nonce`
  Eine Nummer, die nur einmal pro Nachricht verwendet werden darf; 24 Bytes lang. Diese Größe ist groß genug, um sie zufällig zu erzeugen (z. B. mit random_bytes()).
`key`
  Schlüssel für die Entschlüsselung (256-bit).

### Rückgabewerte

Gibt im Erfolgsfall den Klartext zurück. Bei einem Fehler wird `false` zurückgegeben.

# sodium_crypto_aead_xchacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Empfohlen) Verschlüsselt und authentifiziert eine Nachricht mit XChaCha20-Poly1305

### Beschreibung

function sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
#[\SensitiveParameter]string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter]string `$key`
): string

Verschlüsselt und authentifiziert eine Nachricht mit XChaCha20-Poly1305 (Erweiterte-Nonce-Variante).

Im Allgemeinen ist XChaCha20-Poly1305 der beste der angebotenen AEAD-Modi.

### Parameter-Liste

`message`
  Der Klartext, welcher verschlüsselt werden soll.
`additional_data`
  Zusätzliche, zu authentifizierende Daten. Diese Daten werden weder verschlüsselt, noch an den Chiffriertext angehängt.
`nonce`
  Eine Nummer, die nur einmal pro Nachricht verwendet werden darf; 24 Bytes lang. Diese Größe ist groß genug, um sie zufällig zu erzeugen (z. B. mit random_bytes()).
`key`
  Schlüssel für die Verschlüsselung (256-bit).

### Rückgabewerte

Gibt bei Erfolg den Chiffriertext und das Tag zurück. Bei einem Fehler wird `false` zurückgegeben.

# sodium_crypto_aead_xchacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Generiert einen zufälligen XChaCha20-Poly1305-Schlüssel.

### Beschreibung

function sodium_crypto_aead_xchacha20poly1305_ietf_keygen(): string

Generiert einen zufälligen Schlüssel für die Nutzung von sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() und sodium_crypto_aead_xchacha20poly1305_ietf_decrypt().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen 256-Bit-Zufallsschlüssel zurück.

# sodium_crypto_auth

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth — Compute a tag for the message

### Beschreibung

function sodium_crypto_auth(string `$message`, #[\SensitiveParameter]string `$key`): string

Symmetric message authentication via sodium_crypto_auth() provides integrity, but not confidentiality.

Unlike with digital signatures (e.g. sodium_crypto_sign_detached()), any party capable of verifying a message is also capable of authenticating their own messages. (Hence, symmetric authentication.)

### Parameter-Liste

`message`
  The message you intend to authenticate
`key`
  Authentication key

### Rückgabewerte

Authentication tag

# sodium_crypto_auth_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_keygen — Erzeugt einen zufälligen Schlüssel für sodium_crypto_auth

### Beschreibung

function sodium_crypto_auth_keygen(): string

Erzeugt einen Schlüssel zur Verwendung mit sodium_crypto_auth() und sodium_crypto_auth_verify().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen zufälligen 256-Bit-Schlüssel zurück.

# sodium_crypto_auth_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_verify — Verifies that the tag is valid for the message

### Beschreibung

function sodium_crypto_auth_verify(string `$mac`, string `$message`, #[\SensitiveParameter]string `$key`): bool

Verify the authentication tag is valid for a given message and key.

Unlike with digital signatures (e.g. sodium_crypto_sign_verify_detached()), any party capable of verifying a message is also capable of authenticating their own messages. (Hence, symmetric authentication.)

### Parameter-Liste

`mac`
  Authentication tag produced by sodium_crypto_auth()
`message`
  Message
`key`
  Authentication key

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# sodium_crypto_box

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box — Authenticated public-key encryption

### Beschreibung

function sodium_crypto_box(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string

Encrypt a message using asymmetric (public key) cryptography.

The algorithm used by functions prefixed with sodium_crypto_box() are Elliptic Curve Diffie-Hellman over the Montgomery curve, Curve25519; usually abbreviated as X25519.

### Parameter-Liste

`message`
  The message to be encrypted.
`nonce`
  A number that must be only used once, per message. 24 bytes long. This is a large enough bound to generate randomly (i.e. random_bytes()).
`key_pair`
  See sodium_crypto_box_keypair_from_secretkey_and_publickey(). This should include the sender's X25519 secret key and the recipient's X25519 public key.

### Rückgabewerte

Returns the encrypted message (ciphertext plus authentication tag). The ciphertext will be 16 bytes longer than the plaintext, and a raw binary string. See sodium_bin2base64() for safe encoding for storage.

# sodium_crypto_box_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair — Erzeugt einen zufälligen geheimen Schlüssel und einen zugehörigen öffentlichen Schlüssel

### Beschreibung

function sodium_crypto_box_keypair(): string

Erzeugt einen geheimen Schlüssel und einen öffentlichen Schlüssel als eine Zeichenkette.

Um den geheimen Schlüssel aus dieser vereinigten Schlüsselpaar-Zeichenkette zu extrahieren, siehe sodium_crypto_box_secretkey(). Um den öffentlichen Schlüssel aus dieser vereinigten Schlüsselpaar-Zeichenkette zu extrahieren, siehe sodium_crypto_box_publickey().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Eine Zeichenkette, die sowohl den geheimen X25519-Schlüssel als auch den zugehörigen öffentlichen X25519-Schlüssel enthält.

# sodium_crypto_box_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair_from_secretkey_and_publickey — Create a unified keypair string from a secret key and public key

### Beschreibung

function sodium_crypto_box_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

This function exists to satisfy the API requirements of e.g. crypto_box(). Pass in one party's secret key and the other's public key, and you will obtain a "keypair" for your conversation.

### Parameter-Liste

`secret_key`
  Secret key.
`public_key`
  Public key.

### Rückgabewerte

X25519 Keypair.

# sodium_crypto_box_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_open — Authenticated public-key decryption

### Beschreibung

function sodium_crypto_box_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key_pair`): string|false

Decrypt a message using asymmetric (public key) cryptography.

### Parameter-Liste

`ciphertext`
  The encrypted message to attempt to decrypt.
`nonce`
  A number that must be only used once, per message. 24 bytes long. This is a large enough bound to generate randomly (i.e. random_bytes()).
`key_pair`
  See sodium_crypto_box_keypair_from_secretkey_and_publickey(). This should include the sender's public key and the recipient's secret key.

### Rückgabewerte

Returns the plaintext message on success, Bei einem Fehler wird `false` zurückgegeben..

# sodium_crypto_box_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey — Extract the public key from a crypto_box keypair

### Beschreibung

function sodium_crypto_box_publickey(#[\SensitiveParameter]string `$key_pair`): string

Given a keypair, fetch only the public key.

### Parameter-Liste

`key_pair`
  A keypair, such as one generated by sodium_crypto_box_keypair() or sodium_crypto_box_seed_keypair()

### Rückgabewerte

X25519 public key.

# sodium_crypto_box_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey_from_secretkey — Calculate the public key from a secret key

### Beschreibung

function sodium_crypto_box_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Given a secret key, calculate the corresponding public key.

This only works with the type of keys intended for use with crypto_box() (which uses Elliptic Curve Diffie-Hellman over the Montgomery curve, Curve25519; abbreviated as X25519), not crypto_sign() (which uses Edwards Digital Signature Algorithm over the Edwards Curve with the corresponding parameters; abbreviated Ed25519).

### Parameter-Liste

`secret_key`
  X25519 secret key

### Rückgabewerte

X25519 public key.

# sodium_crypto_box_seal

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal — Anonymous public-key encryption

### Beschreibung

function sodium_crypto_box_seal(#[\SensitiveParameter]string `$message`, string `$public_key`): string

Encrypt a message such that only the recipient can decrypt it.

Unlike with sodium_crypto_box(), you only need to know the recipient's public key to use sodium_crypto_box_seal(). One consequence of this convenience, however, is that the ciphertext isn't bound to a static public key, and is therefore not authenticated. Hence, anonymous public-key encryption.

sodium_crypto_box_seal() still provides ciphertext integrity. Just not sender identity authentication.

If you also need sender authentication, the sodium_crypto_sign() functions are likely the best place to start.

### Parameter-Liste

`message`
  The message to encrypt.
`public_key`
  The public key that corresponds to the only key that can decrypt the message.

### Rückgabewerte

A ciphertext string in the format of (one-time public key, encrypted message, authentication tag).

### Beispiele

Beispiel #1 sodium_crypto_box_seal() example

    <?php
    $keypair = sodium_crypto_box_keypair();
    $public_key = sodium_crypto_box_publickey($keypair);

    // Obfuscated plaintext to make the example more fun
    $plaintext_b64 = "V3JpdGluZyBzb2Z0d2FyZSBpbiBQSFAgY2FuIGJlIGEgZGVsaWdodCE=";
    $decoded_plaintext = sodium_base642bin($plaintext_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $sealed = sodium_crypto_box_seal($decoded_plaintext, $public_key);
    var_dump(base64_encode($sealed));

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(120) "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw="
    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_seal_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal_open — Anonymous public-key decryption

### Beschreibung

function sodium_crypto_box_seal_open(string `$ciphertext`, #[\SensitiveParameter]string `$key_pair`): string|false

Decrypt a message that was encrypted with sodium_crypto_box_seal()

### Parameter-Liste

`ciphertext`
  The encrypted message
`key_pair`
  The keypair of the recipient. Must include the secret key.

### Rückgabewerte

The plaintext on success, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 sodium_crypto_box_seal_open() example

    <?php
    // Ciphertext is not sensitive; base64_decode is fine
    $sealed_b64 = "oRBXXAV4iQBrxlV4A21Bord8Yo/D8ZlrIIGNyaRCcGBfpz0map52I3xq6l+CST+1NSgQkbV+HiYyFjXWiWiaCGupGf+zl4bgWj/A9Adtem7Jt3h3emrMsLw=";
    $sealed = base64_decode($sealed_b64);

    // Keypair contains a cryptographic secret; use a timing-safe decoder
    $keypair_b64 = "KZkF8wnB7bnC2aXB3lFOqCTc0Z6MllvaQb9ASVG8o2/MsewkuE4u1uaEgTzSakeiYyIW8DGj+02/L3cWIbs9bQ==";
    $keypair = sodium_base642bin($keypair_b64, SODIUM_BASE64_VARIANT_ORIGINAL);

    $opened = sodium_crypto_box_seal_open($sealed, $keypair);
    var_dump($opened);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(41) "Writing software in PHP can be a delight!"

# sodium_crypto_box_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_secretkey — Extracts the secret key from a crypto_box keypair

### Beschreibung

function sodium_crypto_box_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Given a keypair, fetch only the secret key.

### Parameter-Liste

`key_pair`
  A keypair, such as one generated by sodium_crypto_box_keypair() or sodium_crypto_box_seed_keypair()

### Rückgabewerte

X25519 secret key.

# sodium_crypto_box_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seed_keypair — Deterministically derive the key pair from a single key

### Beschreibung

function sodium_crypto_box_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Clamps the seed to form a secret key, derives the public key, and returns the two as a keypair.

The `*_seed_keypair` functions are ideal for generating a keypair from a password and salt. Use the result as a `seed` to generate the desired keys.

### Parameter-Liste

`seed`
  Some cryptographic input. Must be 32 bytes.

### Rückgabewerte

X25519 Keypair (secret key and public key).

# sodium_crypto_core_ristretto255_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_add — Adds an element

### Beschreibung

function sodium_crypto_core_ristretto255_add(string `$p`, string `$q`): string

Adds an element `q` to `p`. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`p`
  An element.
`q`
  An element.

### Rückgabewerte

Returns a 32-byte random String.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_add() example

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_crypto_core_ristretto255_random() - Generates a random key
- sodium_crypto_core_ristretto255_sub() - Subtracts an element

# sodium_crypto_core_ristretto255_from_hash

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_from_hash — Maps a vector

### Beschreibung

function sodium_crypto_core_ristretto255_from_hash(string `$s`): string

Maps a 64-bytes vector `s` to a group element. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`s`
  A 64-bytes vector.

### Rückgabewerte

Returns a 32-byte random String.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_from_hash() example

    <?php

    $hashes = sodium_hex2bin(
        '5d1be09e3d0c82fc538112490e35701979d99e06ca3e2b5b54bffe8b4dc772c1' .
        '4d98b696a1bbfb5ca32c436cc61c16563790306c79eaca7705668b47dffe5bb6'
    );
    var_dump(sodium_bin2hex(sodium_crypto_core_ristretto255_from_hash($hashes)));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(64) "3066f82a1a747d45120d1740f14358531a8f04bbffe6a819f86dfe50f44a0a46"

### Siehe auch

- sodium_hex2bin() - Dekodiert eine hexadezimal kodierte binäre Zeichenkette
- sodium_bin2hex() - Kodiert in Hexadezimal
- sodium_crypto_core_ristretto255_from_hash()

# sodium_crypto_core_ristretto255_is_valid_point

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_is_valid_point — Determines if a point on the ristretto255 curve

### Beschreibung

function sodium_crypto_core_ristretto255_is_valid_point(string `$s`): bool

Determines if a point on the ristretto255 curve, in canonical form, on the main subgroup, and that the point doesn't have a small order. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`s`
  An Elliptic-curve point.

### Rückgabewerte

Returns `true` if `s` is on the ristretto255 curve, `false` otherwise.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_is_valid_point() example

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_scalarmult_ristretto255_base($foo);

    var_dump(sodium_crypto_core_ristretto255_is_valid_point($bar));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_crypto_core_ristretto255_scalar_random() - Generates a random key
- sodium_crypto_scalarmult_ristretto255_base() - Calculates the public key from a secret key

# sodium_crypto_core_ristretto255_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_random — Generates a random key

### Beschreibung

function sodium_crypto_core_ristretto255_random(): string

Generates a random key. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a 32-byte random String.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_random() example

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_crypto_core_ristretto255_add() - Adds an element
- sodium_crypto_core_ristretto255_sub() - Subtracts an element

# sodium_crypto_core_ristretto255_scalar_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_add — Adds a scalar value

### Beschreibung

function sodium_crypto_core_ristretto255_scalar_add(string `$x`, string `$y`): string

Adds an element `y` to `x`. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`x`
  Scalar, representing the X coordinate.
`y`
  Scalar, representing the Y coordinate.

### Rückgabewerte

Returns a 32-byte random String.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_scalar_add() example

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_crypto_core_ristretto255_scalar_random() - Generates a random key
- sodium_crypto_core_ristretto255_scalar_sub() - Subtracts a scalar value

# sodium_crypto_core_ristretto255_scalar_complement

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_complement — The sodium_crypto_core_ristretto255_scalar_complement purpose

### Beschreibung

function sodium_crypto_core_ristretto255_scalar_complement(string `$s`): string

Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`s`
  Scalar value.

### Rückgabewerte

Returns a 32-byte random String.

### Siehe auch

- sodium_crypto_core_ristretto255_scalar_random() - Generates a random key

# sodium_crypto_core_ristretto255_scalar_invert

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_invert — Inverts a scalar value

### Beschreibung

function sodium_crypto_core_ristretto255_scalar_invert(string `$s`): string

Inverts a scalar value. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`s`
  Scalar value.

### Rückgabewerte

Returns a 32-byte random String.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_scalar_invert() example

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $inverted = sodium_crypto_core_ristretto255_scalar_invert($foo);
    $reInverted = sodium_crypto_core_ristretto255_scalar_invert($inverted);

    var_dump(hash_equals($foo, $reInverted));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_crypto_core_ristretto255_scalar_random() - Generates a random key

# sodium_crypto_core_ristretto255_scalar_mul

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_mul — Multiplies a scalar value

### Beschreibung

function sodium_crypto_core_ristretto255_scalar_mul(string `$x`, string `$y`): string

Multiplies a scalar value. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`x`
  Scalar, representing the X coordinate.
`y`
  Scalar, representing the Y coordinate.

### Rückgabewerte

Returns a 32-byte random String.

### Siehe auch

- sodium_crypto_core_ristretto255_scalar_random() - Generates a random key

# sodium_crypto_core_ristretto255_scalar_negate

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_negate — Negates a scalar value

### Beschreibung

function sodium_crypto_core_ristretto255_scalar_negate(string `$s`): string

Negates a scalar value. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`s`
  Scalar value.

### Rückgabewerte

Returns a 32-byte random String.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_scalar_negate() example

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();

    $negate = sodium_crypto_core_ristretto255_scalar_negate($foo);
    $reNegate = sodium_crypto_core_ristretto255_scalar_negate($negate);

    var_dump(hash_equals($foo, $reNegate));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_crypto_core_ristretto255_scalar_random() - Generates a random key

# sodium_crypto_core_ristretto255_scalar_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_random — Generates a random key

### Beschreibung

function sodium_crypto_core_ristretto255_scalar_random(): string

Generates a random key. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a 32-byte random String.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_scalar_random() example

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_crypto_core_ristretto255_scalar_add() - Adds a scalar value
- sodium_crypto_core_ristretto255_scalar_sub() - Subtracts a scalar value

# sodium_crypto_core_ristretto255_scalar_reduce

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_reduce — Reduces a scalar value

### Beschreibung

function sodium_crypto_core_ristretto255_scalar_reduce(string `$s`): string

Reduces a scalar value. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`s`
  Scalar value.

### Rückgabewerte

Returns a 32-byte random String.

### Siehe auch

- sodium_crypto_core_ristretto255_scalar_random() - Generates a random key

# sodium_crypto_core_ristretto255_scalar_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_sub — Subtracts a scalar value

### Beschreibung

function sodium_crypto_core_ristretto255_scalar_sub(string `$x`, string `$y`): string

Subtracts a scalar `y` from `x`. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`x`
  Scalar, representing the X coordinate.
`y`
  Scalar, representing the Y coordinate.

### Rückgabewerte

Returns a 32-byte random String.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_scalar_sub() example

    <?php

    $foo = sodium_crypto_core_ristretto255_scalar_random();
    $bar = sodium_crypto_core_ristretto255_scalar_random();

    $value = sodium_crypto_core_ristretto255_scalar_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_scalar_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_crypto_core_ristretto255_scalar_random() - Generates a random key
- sodium_crypto_core_ristretto255_scalar_add() - Adds a scalar value

# sodium_crypto_core_ristretto255_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_sub — Subtracts an element

### Beschreibung

function sodium_crypto_core_ristretto255_sub(string `$p`, string `$q`): string

Subtracts an element `q` from `p`. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`p`
  An element.
`q`
  An element.

### Rückgabewerte

Returns a 32-byte random String.

### Beispiele

Beispiel #1 sodium_crypto_core_ristretto255_sub() example

    <?php

    $foo = sodium_crypto_core_ristretto255_random();
    $bar = sodium_crypto_core_ristretto255_random();

    $value = sodium_crypto_core_ristretto255_add($foo, $bar);
    $value = sodium_crypto_core_ristretto255_sub($value, $bar);

    var_dump(hash_equals($foo, $value));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_crypto_core_ristretto255_random() - Generates a random key
- sodium_crypto_core_ristretto255_add() - Adds an element

# sodium_crypto_generichash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash — Get a hash of the message

### Beschreibung

function sodium_crypto_generichash(string `$message`, #[\SensitiveParameter]string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

Hash a message with BLAKE2b.

### Parameter-Liste

`message`
  The message being hashed.
`key`
  (Optional) cryptographic key. This serves the same function as a HMAC key, but it's utilized as a reserved section of the internal BLAKE2 state.
`length`
  Output size.

### Rückgabewerte

The cryptographic hash as raw bytes. If a hex-encoded output is desired, the result can be passed to sodium_bin2hex().

# sodium_crypto_generichash_final

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_final — Complete the hash

### Beschreibung

function sodium_crypto_generichash_final(string `&$state`, int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

The finalization method for the streaming generichash API.

### Parameter-Liste

`state`
  Hash state returned from sodium_crypto_generichash_init()
`length`
  Output length.

### Rückgabewerte

Cryptographic hash.

### Beispiele

Beispiel #1 sodium_crypto_generichash_final() example

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }

    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_init

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_init — Initialize a hash for streaming

### Beschreibung

function sodium_crypto_generichash_init(#[\SensitiveParameter]string `$key` = "", int `$length` = `SODIUM_CRYPTO_GENERICHASH_BYTES`): string

The initialization method for the streaming generichash API.

### Parameter-Liste

`key`
  The generichash key.
`length`
  The expected output length of the hash function.

### Rückgabewerte

Returns a hash state, serialized as a raw binary string.

### Beispiele

Beispiel #1 sodium_crypto_generichash_init() example

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init('', 32);
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }
    $final = sodium_crypto_generichash_final($state, 32);
    var_dump(sodium_bin2hex($final));
    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"
    string(64) "a2939a9163cb7c796ec28e01028489e72475c136b2697ea59e3e760ab4a8ab20"

# sodium_crypto_generichash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_keygen — Erzeugt einen zufälligen Generichash-Schlüssel

### Beschreibung

function sodium_crypto_generichash_keygen(): string

Erzeugt einen zufälligen Schlüssel zur Verwendung mit der Generichash-API.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Ein zufälliger 256-Bit-Schlüssel.

# sodium_crypto_generichash_update

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_update — Add message to a hash

### Beschreibung

function sodium_crypto_generichash_update(string `&$state`, string `$message`): true

Appends a message to the internal hash state.

### Parameter-Liste

`state`
  The return value of sodium_crypto_generichash_init().
`message`
  Data to append to the hashing state.

### Rückgabewerte

Gibt immer `true` zurück.

### Beispiele

Beispiel #1 sodium_crypto_generichash_update() example

    <?php
    $messages = [random_bytes(32), random_bytes(32), random_bytes(16)];
    $state = sodium_crypto_generichash_init();
    foreach ($messages as $message) {
        sodium_crypto_generichash_update($state, $message);
    }
    $final = sodium_crypto_generichash_final($state);
    var_dump(sodium_bin2hex($final));

    $allAtOnce = sodium_crypto_generichash(implode('', $messages));
    var_dump(sodium_bin2hex($allAtOnce));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"
    string(64) "e16e28bbbbcc39d9f5b1cbc33c41f1d217808640103e57a41f24870f79831e04"

# sodium_crypto_kdf_derive_from_key

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_derive_from_key — Derive a subkey

### Beschreibung

function sodium_crypto_kdf_derive_from_key(
int `$subkey_length`,
int `$subkey_id`,
string `$context`,
#[\SensitiveParameter]string `$key`
): string

Derive a subkey from a root key and additional context.

Similar to hash_hkdf().

### Parameter-Liste

`subkey_length`
  Length of the key to return (in bytes)
`subkey_id`
  Return the Nth subkey from a given root key. Useful for seeking.
`context`
  Application-specific context.
`key`
  The root key from which the subkey is derived.

### Rückgabewerte

A string of pseudorandom (raw binary) bytes.

# sodium_crypto_kdf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_keygen — Erzeugt einen zufälligen Stammschlüssel für die KDF-Schnittstelle

### Beschreibung

function sodium_crypto_kdf_keygen(): string

Erzeugt einen zufälligen Schlüssel, der als Stammschlüssel für sodium_crypto_kdf_derive_from_key() verwendet werden kann.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Ein zufälliger 256-Bit-Schlüssel.

# sodium_crypto_kx_client_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_client_session_keys — Calculate the client-side session keys.

### Beschreibung

function sodium_crypto_kx_client_session_keys(#[\SensitiveParameter]string `$client_key_pair`, string `$server_key`): array

Calculate the client-side session keys, using the X25519 + BLAKE2b key-exchange method.

### Parameter-Liste

`client_key_pair`
  A crypto_kx keypair, such as one generated by sodium_crypto_kx_keypair().
`server_key`
  A crypto_kx public key.

### Rückgabewerte

An array consisting of two strings. The first should be used for receiving data from the server. The second should be used for sending data to the server.

# sodium_crypto_kx_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_keypair — Creates a new sodium keypair

### Beschreibung

function sodium_crypto_kx_keypair(): string

Create a new sodium keypair consisting of the secret key (32 bytes) followed by the public key (32 bytes). The keys can be retrieved by calling sodium_crypto_kx_secretkey() and sodium_crypto_kx_publickey(), respectively.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the new keypair on success; throws an exception otherwise.

### Beispiele

Beispiel #1 sodium_crypto_kx_keypair() usage

Create a new keypair and retrieve the secret and the public key from it.

    <?php
    $keypair = sodium_crypto_kx_keypair();
    $secret = sodium_crypto_kx_secretkey($keypair);
    $public = sodium_crypto_kx_publickey($keypair);
    printf("secret: %s\npublic: %s", sodium_bin2hex($secret), sodium_bin2hex($public));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    secret: e7c5c918fdc40762e6000542c0118f4368ce8fd242b0e48c1e17202797a25daf
    public: d1f59fda8652caf40ed1a01d2b6f3802b60846986372cd8fa337b7c12c428b18

# sodium_crypto_kx_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_publickey — Extract the public key from a crypto_kx keypair

### Beschreibung

function sodium_crypto_kx_publickey(#[\SensitiveParameter]string `$key_pair`): string

Extract the public key from a crypto_kx keypair.

### Parameter-Liste

`key_pair`
  X25519 keypair, such as one generated by sodium_crypto_kx_keypair().

### Rückgabewerte

X25519 public key.

# sodium_crypto_kx_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_secretkey — Extract the secret key from a crypto_kx keypair.

### Beschreibung

function sodium_crypto_kx_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Extract the secret key from a crypto_kx keypair.

### Parameter-Liste

`key_pair`
  X25519 keypair, such as one generated by sodium_crypto_kx_keypair().

### Rückgabewerte

X25519 secret key.

# sodium_crypto_kx_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_seed_keypair — Description

### Beschreibung

function sodium_crypto_kx_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`seed`

### Rückgabewerte

# sodium_crypto_kx_server_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_server_session_keys — Calculate the server-side session keys.

### Beschreibung

function sodium_crypto_kx_server_session_keys(#[\SensitiveParameter]string `$server_key_pair`, string `$client_key`): array

Calculate the server-side session keys, using the X25519 + BLAKE2b key-exchange method.

### Parameter-Liste

`server_key_pair`
  A crypto_kx keypair, such as one generated by sodium_crypto_kx_keypair().
`client_key`
  A crypto_kx public key.

### Rückgabewerte

An array consisting of two strings. The first should be used for receiving data from the client. The second should be used for sending data to the client.

# sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Derive a key from a password, using Argon2

### Beschreibung

function sodium_crypto_pwhash(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`,
int `$algo` = `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT`
): string

This function provides low-level access to libsodium's crypto_pwhash key derivation function. Unless you have specific reason to use this function, you should use sodium_crypto_pwhash_str() or password_hash() functions instead.

A common reason to use this particular function is to derive the seeds for cryptographic keys from a password and salt, and then use these seeds to generate the actual keys needed for some purpose (e.g. sodium_crypto_sign_detached()).

### Parameter-Liste

`length`
  int; The length of the password hash to generate, in bytes.
`password`
  string; The password to generate a hash for.
`salt`
  A salt to add to the password before hashing. The salt should be unpredictable, ideally generated from a good random number source such as random_bytes(), and have a length of exactly `SODIUM_CRYPTO_PWHASH_SALTBYTES` bytes.
`opslimit`
  Represents a maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. There are some constants available to set the operations limit to appropriate values depending on intended use, in order of strength: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` and `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  The maximum amount of RAM that the function will use, in bytes. There are constants to help you choose an appropriate value, in order of size: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE`, and `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Typically these should be paired with the matching `opslimit` values.
`algo`
  int A number indicating the hash algorithm to use. By default `SODIUM_CRYPTO_PWHASH_ALG_DEFAULT` (the currently recommended algorithm, which can change from one version of libsodium to another), or explicitly using `SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13`, representing the Argon2id algorithm version 1.3.

### Rückgabewerte

Returns the derived key. The return value is a binary string of the hash, not an ASCII-encoded representation, and does not contain additional information about the parameters used to create the hash, so you will need to keep that information if you are ever going to verify the password in future. Use sodium_crypto_pwhash_str() to avoid needing to do all that.

### Beispiele

Beispiel #1 sodium_crypto_pwhash() example

    <?php
    //Need to keep the salt if we're ever going to be able to check this password
    $salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
    //Using bin2hex to keep output readable
    echo bin2hex(
        sodium_crypto_pwhash(
            16, // == 128 bits
            'password',
            $salt,
            SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
            SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
        )
    );
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    a18f346ba57992eb7e4ae6abf3fd30ee

# sodium_crypto_pwhash_scryptsalsa208sha256

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256 — Derives a key from a password, using scrypt

### Beschreibung

function sodium_crypto_pwhash_scryptsalsa208sha256(
int `$length`,
#[\SensitiveParameter]string `$password`,
string `$salt`,
int `$opslimit`,
int `$memlimit`
): string

This is the scrypt counterpart to sodium_crypto_pwhash().

A common reason to use this particular function is to derive the seeds for cryptographic keys from a password and salt, and then use these seeds to generate the actual keys needed for some purpose (e.g. sodium_crypto_sign_detached()).

### Parameter-Liste

`length`
  The length of the password hash to generate, in bytes.
`password`
  The password to generate a hash for.
`salt`
  A salt to add to the password before hashing. The salt should be unpredictable, ideally generated from a good random number source such as random_bytes(), and have a length of at least `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_SALTBYTES` bytes.
`opslimit`
  Represents a maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. There are some constants available to set the operations limit to appropriate values depending on intended use, in order of strength: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_INTERACTIVE` and `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_OPSLIMIT_SENSITIVE`.
`memlimit`
  The maximum amount of RAM that the function will use, in bytes. There are constants to help you choose an appropriate value, in order of size: `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_INTERACTIVE` and `SODIUM_CRYPTO_PWHASH_SCRYPTSALSA208SHA256_MEMLIMIT_SENSITIVE`. Typically these should be paired with the matching `opslimit` values.

### Rückgabewerte

A string of bytes of the desired length.

# sodium_crypto_pwhash_scryptsalsa208sha256_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str — Get an ASCII encoded hash

### Beschreibung

function sodium_crypto_pwhash_scryptsalsa208sha256_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`password`
`opslimit`
`memlimit`

### Rückgabewerte

# sodium_crypto_pwhash_scryptsalsa208sha256_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verify that the password is a valid password verification string

### Beschreibung

function sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`hash`
`password`

### Rückgabewerte

# sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — Get an ASCII-encoded hash

### Beschreibung

function sodium_crypto_pwhash_str(#[\SensitiveParameter]string `$password`, int `$opslimit`, int `$memlimit`): string

Uses a CPU- and memory-hard hash algorithm along with a randomly-generated salt, and memory and CPU limits to generate an ASCII-encoded hash suitable for password storage.

### Parameter-Liste

`password`
  string; The password to generate a hash for.
`opslimit`
  Represents a maximum amount of computations to perform. Raising this number will make the function require more CPU cycles to compute a key. There are constants available to set the operations limit to appropriate values depending on intended use, in order of strength: `SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE` and `SODIUM_CRYPTO_PWHASH_OPSLIMIT_SENSITIVE`.
`memlimit`
  The maximum amount of RAM that the function will use, in bytes. There are constants to help you choose an appropriate value, in order of size: `SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE`, `SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE`, and `SODIUM_CRYPTO_PWHASH_MEMLIMIT_SENSITIVE`. Typically these should be paired with the matching opslimit values.

### Rückgabewerte

Returns the hashed password.

In order to produce the same password hash from the same password, the same values for `opslimit` and `memlimit` must be used. These are embedded within the generated hash, so everything that's needed to verify the hash is included. This allows the sodium_crypto_pwhash_str_verify() function to verify the hash without needing separate storage for the other parameters.

### Beispiele

Beispiel #1 sodium_crypto_pwhash_str() example

    <?php
    $password = 'password';
    echo sodium_crypto_pwhash_str(
        $password,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
    );

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    $argon2id$v=19$m=65536,t=2,p=1$oWIfdaXwWwhVmovOBc2NAQ$EbsZ+JnZyyavkafS0hoc4HdaOB0ILWZESAZ7kVGa+Iw

### Anmerkungen

> Hinweis: Hashes are calculated using the Argon2ID algorithm, providing resistance to both GPU and side-channel attacks. In contrast to the password_hash() function, there is no salt parameter (a salt is generated automatically), and the `opslimit` and `memlimit` parameters are not optional.

### Siehe auch

- sodium_crypto_pwhash_str_verify() - Verifies that a password matches a hash
- sodium_crypto_pwhash() - Derive a key from a password, using Argon2
- password_hash() - Erstellt einen Passwort-Hash
- password_verify() - Überprüft, ob ein Passwort und ein Hash zusammenpassen
- » Libsodium Argon2 docs

# sodium_crypto_pwhash_str_needs_rehash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_needs_rehash — Determine whether or not to rehash a password

### Beschreibung

function sodium_crypto_pwhash_str_needs_rehash(string `$password`, int `$opslimit`, int `$memlimit`): bool

Determine whether or not to rehash a password, based on the current hash `opslimit` and `memlimit`.

### Parameter-Liste

`password`
  Password hash
`opslimit`
  Configured opslimit; see sodium_crypto_pwhash_str()
`memlimit`
  Configured memlimit; see sodium_crypto_pwhash_str()

### Rückgabewerte

Returns `true` if the provided memlimit/opslimit do not match what's stored in the hash. Returns `false` if they match.

# sodium_crypto_pwhash_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_verify — Verifies that a password matches a hash

### Beschreibung

function sodium_crypto_pwhash_str_verify(string `$hash`, #[\SensitiveParameter]string `$password`): bool

Checks that a password hash created using sodium_crypto_pwhash_str() matches a given plain-text password. Note that the parameters are in the opposite order to the same parameters in the similar password_verify() function.

### Parameter-Liste

`hash`
  Ein Hash, der durch password_hash() erzeugt wurde.
`password`
  Das Passwort des Benutzers.

### Rückgabewerte

Returns `true` if the password and hash match, or `false` otherwise.

### Anmerkungen

> Hinweis: Hashes are calculated using the Argon2ID algorithm, providing resistance to both GPU and side-channel attacks.

### Siehe auch

- sodium_crypto_pwhash_str() - Get an ASCII-encoded hash
- password_hash() - Erstellt einen Passwort-Hash
- password_verify() - Überprüft, ob ein Passwort und ein Hash zusammenpassen

# sodium_crypto_scalarmult

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult — Compute a shared secret given a user's secret key and another user's public key

### Beschreibung

function sodium_crypto_scalarmult(string `$n`, string `$p`): string

Elliptic Curve Diffie-Hellman. Calculates scalar n times point p, on an elliptic curve.

### Parameter-Liste

`n`
  scalar, which is typically a secret key
`p`
  point (x-coordinate), which is typically a public key

### Rückgabewerte

A 32-byte random string.

# sodium_crypto_scalarmult_base

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult_base — Alias von sodium_crypto_box_publickey_from_secretkey()

### Beschreibung

Diese Funktion ist ein Alias für: sodium_crypto_box_publickey_from_secretkey().

# sodium_crypto_scalarmult_ristretto255

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255 — Computes a shared secret

### Beschreibung

function sodium_crypto_scalarmult_ristretto255(string `$n`, string `$p`): string

Calculates scalar `n` times point `p`. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`n`
  A scalar, which is typically a secret key.
`p`
  A point (x-coordinate), which is typically a public key.

### Rückgabewerte

Returns a 32-byte random String.

### Siehe auch

- sodium_crypto_scalarmult_ristretto255_base() - Calculates the public key from a secret key

# sodium_crypto_scalarmult_ristretto255_base

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255_base — Calculates the public key from a secret key

### Beschreibung

function sodium_crypto_scalarmult_ristretto255_base(string `$n`): string

Given a secret key, calculates the corresponding public key. Available as of libsodium 1.0.18.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`n`
  A secret key.

### Rückgabewerte

Returns a 32-byte random String.

### Siehe auch

- sodium_crypto_scalarmult_ristretto255() - Computes a shared secret

# sodium_crypto_secretbox

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox — Authenticated shared-key encryption

### Beschreibung

function sodium_crypto_secretbox(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Encrypt a message with a symmetric (shared) key.

### Parameter-Liste

`message`
  The plaintext message to encrypt.
`nonce`
  A number that must be only used once, per message. 24 bytes long. This is a large enough bound to generate randomly (i.e. random_bytes()).
`key`
  Encryption key (256-bit).

### Rückgabewerte

Returns the encrypted string.

### Fehler/Exceptions

- If `nonce` has a length of bytes different than `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 bytes), a SodiumException will be thrown.
- If `key` has a length of bytes different than `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 bytes), a SodiumException will be thrown.
- Throws a SodiumException on failure.

### Beispiele

Beispiel #1 sodium_crypto_secretbox() example

    <?php
    // The $key must be kept confidential
    $key = sodium_crypto_secretbox_keygen();
    // Do not reuse $nonce with the same key
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $plaintext = "message to be encrypted";
    $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);

    var_dump(bin2hex($ciphertext));
    // The same nonce and key are required to decrypt the $ciphertext
    var_dump(sodium_crypto_secretbox_open($ciphertext, $nonce, $key));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(78) "3a1fa3e9f7b72ef8be51d40abf8e296c6899c185d07b18b4c93e7f26aa776d24c50852cd6b1076"
    string(23) "message to be encrypted"

### Siehe auch

- sodium_crypto_secretbox_open() - Authenticated shared-key decryption
- sodium_crypto_secretbox_keygen() - Generate random key for sodium_crypto_secretbox
- random_bytes() - Get cryptographically secure random bytes

# sodium_crypto_secretbox_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_keygen — Generate random key for sodium_crypto_secretbox

### Beschreibung

function sodium_crypto_secretbox_keygen(): string

Generate a key for use with sodium_crypto_secretbox() and sodium_crypto_secretbox_open().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the generated string of cryptographically secure random bytes.

### Beispiele

Beispiel #1 sodium_crypto_secretbox_keygen() example

    <?php
    $key = sodium_crypto_secretbox_keygen();
    var_dump( sodium_bin2hex( $key ) );
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(64) "88bd1dc51ec81984f3ddc5a8f59a3d95b647e2da3e879f1b9ceb0abd89e7286c"

Beispiel #2 Comparing sodium_crypto_secretbox_keygen() with random_bytes()

    <?php
    $key = sodium_crypto_secretbox_keygen();
    $bytes = random_bytes( SODIUM_CRYPTO_SECRETBOX_KEYBYTES );
    var_dump( mb_strlen( $key, '8bit' ) === mb_strlen( $bytes, '8bit' ) );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- sodium_bin2hex() - Kodiert in Hexadezimal
- random_bytes() - Get cryptographically secure random bytes

# sodium_crypto_secretbox_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_open — Authenticated shared-key decryption

### Beschreibung

function sodium_crypto_secretbox_open(string `$ciphertext`, string `$nonce`, #[\SensitiveParameter]string `$key`): string|false

Decrypt an encrypted message with a symmetric (shared) key.

### Parameter-Liste

`ciphertext`
  Must be in the format provided by sodium_crypto_secretbox() (ciphertext and tag, concatenated).
`nonce`
  A number that must be only used once, per message. 24 bytes long. This is a large enough bound to generate randomly (i.e. random_bytes()).
`key`
  Encryption key (256-bit).

### Rückgabewerte

The decrypted string on successBei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

- If `nonce` has a length of bytes different than `SODIUM_CRYPTO_SECRETBOX_NONCEBYTES` (24 bytes), a SodiumException will be thrown.
- If `key` has a length of bytes different than `SODIUM_CRYPTO_SECRETBOX_KEYBYTES` (32 bytes), a SodiumException will be thrown.

### Beispiele

Beispiel #1 sodium_crypto_secretbox_open() example

    <?php
    // The $key must be kept confidential
    $key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES);
    // Do not reuse $nonce with the same key
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = sodium_crypto_secretbox('message to be encrypted', $nonce, $key);

    // The same nonce and key are required to decrypt the $ciphertext
    $plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
    if ($plaintext !== false) {
        echo $plaintext . PHP_EOL;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    message to be encrypted

### Siehe auch

- sodium_crypto_secretbox() - Authenticated shared-key encryption
- sodium_crypto_secretbox_keygen() - Generate random key for sodium_crypto_secretbox
- random_bytes() - Get cryptographically secure random bytes

# sodium_crypto_secretstream_xchacha20poly1305_init_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_pull — Initialize a secretstream context for decryption

### Beschreibung

function sodium_crypto_secretstream_xchacha20poly1305_init_pull(string `$header`, #[\SensitiveParameter]string `$key`): string

Initialize a secretstream context for decryption.

### Parameter-Liste

`header`
  The header of the secretstream. This should be one of the values produced by sodium_crypto_secretstream_xchacha20poly1305_init_push().
`key`
  Encryption key (256-bit).

### Rückgabewerte

Secretstream state.

### Beispiele

Beispiel #1 sodium_crypto_secretstream_xchacha20poly1305_init_pull() example

    <?php
    function decrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        $header = fread($inputFile, 24);

        $state = sodium_crypto_secretstream_xchacha20poly1305_init_pull($header, $key);
        $inputFileSize = fstat($inputFile)['size'];

        // Decrypt the file and write its contents to the output file:
        for ($i = 24; $i < $inputFileSize; $i += 8192) {
            $ctxt_chunk = fread($inputFile, 8192);

            // We're not using $tag, but in real protocols you can use this on encrypt to e.g.
            // trigger a re-key or indicate the end of file. Then, on decrypt, you can assert
            // this behavior.
            [$ptxt_chunk, $tag] = sodium_crypto_secretstream_xchacha20poly1305_pull($state, $ctxt_chunk);
            fwrite($outputFile, $ptxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    $example = sodium_hex2bin('971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c');
    file_put_contents('hello.enc', $example);
    decrypt_file('hello.enc', 'hello.txt.decrypted', $key);
    var_dump(file_get_contents('hello.txt.decrypted'));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(12) "Hello world!"

# sodium_crypto_secretstream_xchacha20poly1305_init_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_push — Initialize a secretstream context for encryption

### Beschreibung

function sodium_crypto_secretstream_xchacha20poly1305_init_push(#[\SensitiveParameter]string `$key`): array

Initialize a secretstream context for encryption.

### Parameter-Liste

`key`
  Cryptography key. See sodium_crypto_secretstream_xchacha20poly1305_keygen().

### Rückgabewerte

An array with two string values:

- The secretstream state, needed for further pushes
- The secretstream header, which needs to be provided to the recipient so they can pull data

### Beispiele

Beispiel #1 sodium_crypto_secretstream_xchacha20poly1305_init_push() example

    <?php
    function encrypt_file(string $inputFilePath, string $outputFilePath, string $key): void
    {
        [$state, $header] = sodium_crypto_secretstream_xchacha20poly1305_init_push($key);

        $inputFile = fopen($inputFilePath, 'rb');
        $outputFile = fopen($outputFilePath, 'wb');
        // Write the header:
        fwrite($outputFile, $header);
        $inputFileSize = fstat($inputFile)['size'];

        // Encrypt the file and write its contents to the output file:
        for ($i = 0; $i < $inputFileSize; $i += 8175) {
            $ptxt_chunk = fread($inputFile, 8175);
            $ctxt_chunk = sodium_crypto_secretstream_xchacha20poly1305_push($state, $ptxt_chunk);
            fwrite($outputFile, $ctxt_chunk);
        }

        sodium_memzero($state);
        fclose($inputFile);
        fclose($outputFile);
    }

    // sodium_crypto_secretstream_xchacha20poly1305_keygen()
    $key = sodium_base642bin('MS0lzb7HC+thY6jY01pkTE/cwsQxnRq0/2L1eL4Hxn8=', SODIUM_BASE64_VARIANT_ORIGINAL);

    file_put_contents('hello.txt', 'Hello world!');
    encrypt_file('hello.txt', 'hello.txt.encrypted', $key);
    var_dump(sodium_bin2hex(file_get_contents('hello.txt.encrypted')));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(106) "971e33b255f0990ef3931caf761c59136efa77b434832f28ec719e3ff73f5aec38b3bba1574ab5b70a8844d8da36a668e802cfea2c"

# sodium_crypto_secretstream_xchacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_keygen — Erzeugt einen zufälligen Secretstream-Schlüssel

### Beschreibung

function sodium_crypto_secretstream_xchacha20poly1305_keygen(): string

Erzeugt einen zufälligen Secretstream-Schlüssel.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt eine Zeichenkette aus zufälligen Bytes zurück.

# sodium_crypto_secretstream_xchacha20poly1305_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_pull — Decrypt a chunk of data from an encrypted stream

### Beschreibung

function sodium_crypto_secretstream_xchacha20poly1305_pull(string `&$state`, string `$ciphertext`, string `$additional_data` = ""): array|false

Decrypt a chunk of data from an encrypted stream.

### Parameter-Liste

`state`
  See sodium_crypto_secretstream_xchacha20poly1305_init_pull() and sodium_crypto_secretstream_xchacha20poly1305_init_push()
`ciphertext`
  The ciphertext chunk to decrypt.
`additional_data`
  Optional additional data to include in the authentication tag.

### Rückgabewerte

An array with two values:

- string; The decrypted chunk

- int; An optional tag (if provided during push). Possible values:

  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: the most common tag, that doesn't add any information about the nature of the message.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: indicates that the message marks the end of the stream, and erases the secret key used to encrypt the previous sequence.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: indicates that the message marks the end of a set of messages, but not the end of the stream. For example, a huge JSON string sent as multiple chunks can use this tag to indicate to the application that the string is complete and that it can be decoded. But the stream itself is not closed, and more data may follow.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: "forget" the key used to encrypt this message and the previous ones, and derive a new secret key.

# sodium_crypto_secretstream_xchacha20poly1305_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_push — Encrypt a chunk of data so that it can safely be decrypted in a streaming API

### Beschreibung

function sodium_crypto_secretstream_xchacha20poly1305_push(
string `&$state`,
#[\SensitiveParameter]string `$message`,
string `$additional_data` = "",
int `$tag` = `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`
): string

Encrypt a chunk of data so that it can safely be decrypted in a streaming API.

### Parameter-Liste

`state`
  See sodium_crypto_secretstream_xchacha20poly1305_init_pull() and sodium_crypto_secretstream_xchacha20poly1305_init_push()
`message`
`additional_data`
`tag`
  Optional. Can be used to assert decryption behavior (i.e. re-keying or indicating the final chunk in a stream).
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_MESSAGE`: the most common tag, that doesn't add any information about the nature of the message.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL`: indicates that the message marks the end of the stream, and erases the secret key used to encrypt the previous sequence.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_PUSH`: indicates that the message marks the end of a set of messages, but not the end of the stream. For example, a huge JSON string sent as multiple chunks can use this tag to indicate to the application that the string is complete and that it can be decoded. But the stream itself is not closed, and more data may follow.
  - `SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_REKEY`: "forget" the key used to encrypt this message and the previous ones, and derive a new secret key.

### Rückgabewerte

Returns the encrypted ciphertext.

# sodium_crypto_secretstream_xchacha20poly1305_rekey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_rekey — Explicitly rotate the key in the secretstream state

### Beschreibung

function sodium_crypto_secretstream_xchacha20poly1305_rekey(string `&$state`): void

Explicitly rotate the key in the secretstream state. Overwrites the value passed in.

### Parameter-Liste

`state`
  Secretstream state.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# sodium_crypto_shorthash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash — Compute a short hash of a message and key

### Beschreibung

function sodium_crypto_shorthash(string `$message`, #[\SensitiveParameter]string `$key`): string

sodium_crypto_shorthash() wraps a hash function called SipHash-2-4, which is ideal for implementing hash tables that are not susceptible to hash collision denial of service attacks (Hash-DoS).

SipHash-2-4 isn't a general purpose cryptographic hash function.

### Parameter-Liste

`message`
  The message to hash.
`key`
  The hash key.

### Rückgabewerte

# sodium_crypto_shorthash_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash_keygen — Erzeugt zufällige Bytes für einen Schlüssel

### Beschreibung

function sodium_crypto_shorthash_keygen(): string

Erzeugt einen Schlüssel zur Verwendung mit sodium_crypto_shorthash().

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# sodium_crypto_sign

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign — Sign a message

### Beschreibung

function sodium_crypto_sign(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Sign a message with a secret key, that can be verified by the corresponding public key. This function attaches the signature to the message. See sodium_crypto_sign_detached() for detached signatures.

### Parameter-Liste

`message`
  Message to sign.
`secret_key`
  Secret key. See sodium_crypto_sign_secretkey()

### Rückgabewerte

Signed message (not encrypted).

# sodium_crypto_sign_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_detached — Sign the message

### Beschreibung

function sodium_crypto_sign_detached(string `$message`, #[\SensitiveParameter]string `$secret_key`): string

Sign a message with a secret key, that can be verified by the corresponding public key. This function returns a detached signature.

### Parameter-Liste

`message`
  Message to sign.
`secret_key`
  Secret key. See sodium_crypto_sign_secretkey()

### Rückgabewerte

Cryptographic signature.

# sodium_crypto_sign_ed25519_pk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_pk_to_curve25519 — Convert an Ed25519 public key to a Curve25519 public key

### Beschreibung

function sodium_crypto_sign_ed25519_pk_to_curve25519(string `$public_key`): string

Given an Ed25519 public key, calculate the birationally equivalent X25519 public key.

### Parameter-Liste

`public_key`
  Public key suitable for the crypto_sign functions.

### Rückgabewerte

Public key suitable for the crypto_box functions.

# sodium_crypto_sign_ed25519_sk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_sk_to_curve25519 — Convert an Ed25519 secret key to a Curve25519 secret key

### Beschreibung

function sodium_crypto_sign_ed25519_sk_to_curve25519(#[\SensitiveParameter]string `$secret_key`): string

Given an Ed25519 secret key, calculate the birationally equivalent X25519 secret key.

### Parameter-Liste

`secret_key`
  Secret key suitable for the crypto_sign functions.

### Rückgabewerte

Secret key suitable for the crypto_box functions.

# sodium_crypto_sign_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair — Erzeugt einen zufälligen geheimen Schlüssel und einen zugehörigen öffentlichen Schlüssel

### Beschreibung

function sodium_crypto_sign_keypair(): string

Erzeugt ein zufälliges Ed25519-Schlüsselpaar als eine Zeichenkette.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Ed25519-Schlüsselpaar.

# sodium_crypto_sign_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair_from_secretkey_and_publickey — Join a secret key and public key together

### Beschreibung

function sodium_crypto_sign_keypair_from_secretkey_and_publickey(#[\SensitiveParameter]string `$secret_key`, string `$public_key`): string

Join a secret key and public key together.

### Parameter-Liste

`secret_key`
  Ed25519 secret key
`public_key`
  Ed25519 public key

### Rückgabewerte

Keypair

# sodium_crypto_sign_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_open — Check that the signed message has a valid signature

### Beschreibung

function sodium_crypto_sign_open(string `$signed_message`, string `$public_key`): string|false

Verify the signature attached to a message and return the message

### Parameter-Liste

`signed_message`
  A message signed with sodium_crypto_sign()
`public_key`
  An Ed25519 public key

### Rückgabewerte

Returns the original signed message on success, Bei einem Fehler wird `false` zurückgegeben..

# sodium_crypto_sign_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey — Extract the Ed25519 public key from a keypair

### Beschreibung

function sodium_crypto_sign_publickey(#[\SensitiveParameter]string `$key_pair`): string

Extract the Ed25519 public key from a keypair

### Parameter-Liste

`key_pair`
  Ed25519 keypair (see: sodium_crypto_sign_keypair())

### Rückgabewerte

Ed25519 public key

# sodium_crypto_sign_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey_from_secretkey — Extract the Ed25519 public key from the secret key

### Beschreibung

function sodium_crypto_sign_publickey_from_secretkey(#[\SensitiveParameter]string `$secret_key`): string

Extract the Ed25519 public key from the secret key

### Parameter-Liste

`secret_key`
  Ed25519 secret key

### Rückgabewerte

Ed25519 public key

# sodium_crypto_sign_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_secretkey — Extract the Ed25519 secret key from a keypair

### Beschreibung

function sodium_crypto_sign_secretkey(#[\SensitiveParameter]string `$key_pair`): string

Extract the Ed25519 secret key from a keypair

### Parameter-Liste

`key_pair`
  Ed25519 keypair (see: sodium_crypto_sign_keypair())

### Rückgabewerte

Ed25519 secret key

# sodium_crypto_sign_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_seed_keypair — Deterministically derive the key pair from a single key

### Beschreibung

function sodium_crypto_sign_seed_keypair(#[\SensitiveParameter]string `$seed`): string

Clamps the seed to form a secret key, derives the public key, and returns the two as a keypair.

The `*_seed_keypair` functions are ideal for generating a keypair from a password and salt. Use the result as a `seed` to generate the desired keys.

### Parameter-Liste

`seed`
  Some cryptographic input. Must be 32 bytes.

### Rückgabewerte

Keypair (secret key and public key)

# sodium_crypto_sign_verify_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_verify_detached — Verify signature for the message

### Beschreibung

function sodium_crypto_sign_verify_detached(string `$signature`, string `$message`, string `$public_key`): bool

Verify signature for the message

### Parameter-Liste

`signature`
  The cryptographic signature obtained from sodium_crypto_sign_detached()
`message`
  The message being verified
`public_key`
  Ed25519 public key

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# sodium_crypto_stream

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream — Generate a deterministic sequence of bytes from a seed

### Beschreibung

function sodium_crypto_stream(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Generate a deterministic sequence of bytes from a seed, using the XSalsa20 stream cipher.

### Parameter-Liste

`length`
  The number of bytes to return.
`nonce`
  A number that must be only used once, per message. 24 bytes long. This is a large enough bound to generate randomly (i.e. random_bytes()).
`key`
  Encryption key (256-bit).

### Rückgabewerte

String of pseudorandom bytes.

# sodium_crypto_stream_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_keygen — Erzeugt einen zufälligen sodium_crypto_stream-Schlüssel

### Beschreibung

function sodium_crypto_stream_keygen(): string

Erzeugt einen Schlüssel zur Verwendung mit sodium_crypto_stream() und sodium_crypto_stream_xor().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Verschlüsselungsschlüssel (256-Bit).

# sodium_crypto_stream_xchacha20

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20 — Expands the key and nonce into a keystream of pseudorandom bytes

### Beschreibung

function sodium_crypto_stream_xchacha20(int `$length`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Expands the `key` and `nonce` into a keystream of pseudorandom bytes.

### Parameter-Liste

`length`
  Number of bytes desired.
`nonce`
  24-byte nonce.
`key`
  Key, possibly generated from sodium_crypto_stream_xchacha20_keygen().

### Rückgabewerte

Returns a pseudorandom stream that can be used with sodium_crypto_stream_xchacha20_xor().

# sodium_crypto_stream_xchacha20_keygen

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_keygen — Gibt einen sicheren zufälligen Schlüssel zurück

### Beschreibung

function sodium_crypto_stream_xchacha20_keygen(): string

Gibt einen sicheren zufälligen Schlüssel zur Verwendung mit sodium_crypto_stream_xchacha20() zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen sicheren zufälligen 32-Byte-Schlüssel zur Verwendung mit sodium_crypto_stream_xchacha20() zurück.

# sodium_crypto_stream_xchacha20_xor

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_xor — Encrypts a message using a nonce and a secret key (no authentication)

### Beschreibung

function sodium_crypto_stream_xchacha20_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

Encrypts a `message` using a `nonce` and a secret `key` (no authentication).

Achtung

This encryption is unauthenticated, and does not prevent chosen-ciphertext attacks. Make sure to combine the ciphertext with a Message Authentication Code, for example with sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() function, or sodium_crypto_auth().

### Parameter-Liste

`message`
  The message to encrypt.
`nonce`
  24-byte nonce.
`key`
  Key, possibly generated from sodium_crypto_stream_xchacha20_keygen().

### Rückgabewerte

Encrypted message.

### Siehe auch

- sodium_crypto_stream_xchacha20_xor_ic() - Encrypts a message using a nonce and a secret key (no authentication)

# sodium_crypto_stream_xchacha20_xor_ic

(PHP 8 >= 8.2.0)

sodium_crypto_stream_xchacha20_xor_ic — Encrypts a message using a nonce and a secret key (no authentication)

### Beschreibung

function sodium_crypto_stream_xchacha20_xor_ic(
#[\SensitiveParameter]string `$message`,
string `$nonce`,
int `$counter`,
#[\SensitiveParameter]string `$key`
): string

The function is similar to sodium_crypto_stream_xchacha20_xor() but adds the ability to set the initial value of the block counter to a non-zero value. This permits direct access to any block without having to compute the previous ones.

Achtung

This encryption is unauthenticated, and does not prevent chosen-ciphertext attacks. Make sure to combine the ciphertext with a Message Authentication Code, for example with sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() function, or sodium_crypto_auth().

### Parameter-Liste

`message`
  The message to encrypt.
`nonce`
  24-byte nonce.
`counter`
  The initial value of the block counter.
`key`
  Key, possibly generated from sodium_crypto_stream_xchacha20_keygen().

### Rückgabewerte

Encrypted message, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 sodium_crypto_stream_xchacha20_xor_ic() example

    <?php
    $n2 = random_bytes(SODIUM_CRYPTO_STREAM_XCHACHA20_NONCEBYTES);
    $left  = str_repeat("\x01", 64);
    $right = str_repeat("\xfe", 64);

    // All at once:
    $stream7_unified = sodium_crypto_stream_xchacha20_xor($left . $right, $n2, $key);

    // Piecewise, with initial counter:
    $stream7_left  = sodium_crypto_stream_xchacha20_xor_ic($left, $n2, 0, $key);
    $stream7_right = sodium_crypto_stream_xchacha20_xor_ic($right, $n2, 1, $key);
    $stream7_concat = $stream7_left . $stream7_right;

    var_dump(strlen($stream7_concat));
    var_dump($stream7_unified === $stream7_concat);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(128)
    bool(true)

### Siehe auch

- sodium_crypto_stream_xchacha20_xor() - Encrypts a message using a nonce and a secret key (no authentication)

# sodium_crypto_stream_xor

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_xor — Encrypt a message without authentication

### Beschreibung

function sodium_crypto_stream_xor(#[\SensitiveParameter]string `$message`, string `$nonce`, #[\SensitiveParameter]string `$key`): string

This function encrypts a message with XSalsa20, but does not provide any ciphertext guarantees about the plaintext.

### Parameter-Liste

`message`
  The message to encrypt
`nonce`
  A number that must be only used once, per message. 24 bytes long. This is a large enough bound to generate randomly (i.e. random_bytes()).
`key`
  Encryption key (256-bit).

### Rückgabewerte

Encrypted message.

# sodium_hex2bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_hex2bin — Dekodiert eine hexadezimal kodierte binäre Zeichenkette

### Beschreibung

function sodium_hex2bin(#[\SensitiveParameter]string `$string`, string `$ignore` = ""): string

Dekodiert eine hexadezimal kodierte binäre Zeichenkette.

Wie sodium_bin2hex() ist auch sodium_hex2bin() resistent gegen Seitenkanalattacken, während hex2bin() dies nicht ist.

### Parameter-Liste

`string`
  Hexadezimale Darstellung der Daten.
`ignore`
  Optionales String-Argument für zu ignorierende Zeichen.

### Rückgabewerte

Gibt die binäre Darstellung der angegebenen Zeichenkette (`string`) zurück.

# sodium_increment

(PHP 7 >= 7.2.0, PHP 8)

sodium_increment — Inkrementieren einer großen Zahl

### Beschreibung

function sodium_increment(string `&$string`): void

Behandelt die gegebene Zeichenkette als Little-Endian-Ganzzahl ohne Vorzeichen und erhöht sie dann um 1. Diese Funktion läuft zeitkonstant.

### Parameter-Liste

`string`
  Zeichenkette, die erhöht werden soll.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# sodium_memcmp

(PHP 7 >= 7.2.0, PHP 8)

sodium_memcmp — Prüfung auf Gleichheit bei konstanter Zeit

### Beschreibung

function sodium_memcmp(#[\SensitiveParameter]string `$string1`, #[\SensitiveParameter]string `$string2`): int

Vergleich zweier Zeichenketten in konstanter Zeit.

In der Praxis sollte man statt dieser Funktion fast immer hash_equals() verwenden, da diese Funktion die gleiche Logik bietet, aber einen bool-Rückgabewert anstelle eines int-Rückgabewertes hat. Wenn der Rückgabewert des Vergleichs in einer Berechnung verwendet wird, welche zeitkonstant sein soll, und daher eine Typkonvertierung vermieden werden soll, ist sodium_memcmp() ein idealer Ersatz.

### Parameter-Liste

`string1`
  Zu vergleichende Zeichenkette
`string2`
  Andere Zeichenkette zum Vergleich

### Rückgabewerte

Gibt `0` zurück, wenn beide Zeichenketten gleich sind; `-1` im anderen Fall.

# sodium_memzero

(PHP 7 >= 7.2.0, PHP 8)

sodium_memzero — Überschreibt eine Zeichenkette mit einem Nullzeichen

### Beschreibung

function sodium_memzero(#[\SensitiveParameter]string `&$string`): void

sodium_memzero() überschreibt eine Zeichenkette mit Nullzeichen.

### Parameter-Liste

`string`
  Zeichenkette.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# sodium_pad

(PHP 7 >= 7.2.0, PHP 8)

sodium_pad — Fügt Fülldaten hinzu

### Beschreibung

function sodium_pad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Füllt den rechten Teil einer Zeichenkette mit Fülldaten auf. Diese Funktion arbeitet zeitkonstant.

### Parameter-Liste

`string`
  Zeichenkette ohne Fülldaten.
`block_size`
  Die Zeichenkette wird aufgefüllt, bis sie ein gerades Vielfaches der Blockgröße ist.

### Rückgabewerte

Zeichenkette mit Fülldaten.

# sodium_unpad

(PHP 7 >= 7.2.0, PHP 8)

sodium_unpad — Entfernt Fülldaten

### Beschreibung

function sodium_unpad(#[\SensitiveParameter]string `$string`, int `$block_size`): string

Entfernt Fülldaten von einer Zeichenkette. Diese Funktion arbeitet zeitkonstant.

### Parameter-Liste

`string`
  Zeichenkette mit Fülldaten.
`block_size`
  Die Blockgröße des Paddings.

### Rückgabewerte

Zeichenkette ohne Fülldaten.

## Inhaltsverzeichnis

- sodium_add — Addition großer Zahlen
- sodium_base642bin — Dekodiert eine Base64-kodierte Zeichenkette in das Binärformat.
- sodium_bin2base64 — Kodiert eine binäre Zeichenkette mit Base64.
- sodium_bin2hex — Kodiert in Hexadezimal
- sodium_compare — Vergleicht große Zahlen
- sodium_crypto_aead_aegis128l_decrypt — Verify then decrypt a message with AEGIS-128L
- sodium_crypto_aead_aegis128l_encrypt — Encrypt then authenticate a message with AEGIS-128L
- sodium_crypto_aead_aegis128l_keygen — Generate a random AEGIS-128L key
- sodium_crypto_aead_aegis256_decrypt — Verify then decrypt a message with AEGIS-256
- sodium_crypto_aead_aegis256_encrypt — Encrypt then authenticate a message with AEGIS-256
- sodium_crypto_aead_aegis256_keygen — Generate a random AEGIS-256 key
- sodium_crypto_aead_aes256gcm_decrypt — Überprüft und entschlüsselt eine Nachricht mit AES-256-GCM
- sodium_crypto_aead_aes256gcm_encrypt — Verschlüsselt und authentifiziert eine Nachricht mit AES-256-GCM
- sodium_crypto_aead_aes256gcm_is_available — Prüft, ob die Hardware AES256-GCM unterstützt
- sodium_crypto_aead_aes256gcm_keygen — Generiert einen zufälligen AES-256-GCM-Schlüssel
- sodium_crypto_aead_chacha20poly1305_decrypt — Überprüft und entschlüsselt eine Nachricht mit ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_encrypt — Verschlüsselt und authentifiziert eine Nachricht mit ChaCha20-Poly1305
- sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Überprüft, ob der Chiffriertext ein gültiges Tag enthält
- sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Verschlüsselt eine Nachricht
- sodium_crypto_aead_chacha20poly1305_ietf_keygen — Generiert einen zufälligen ChaCha20-Poly1305-IETF-Schlüssel.
- sodium_crypto_aead_chacha20poly1305_keygen — Generiert einen zufälligen ChaCha20-Poly1305-Schlüssel
- sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Empfohlen) Überprüft und entschlüsselt eine Nachricht mit XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Empfohlen) Verschlüsselt und authentifiziert eine Nachricht mit XChaCha20-Poly1305
- sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Generiert einen zufälligen XChaCha20-Poly1305-Schlüssel.
- sodium_crypto_auth — Compute a tag for the message
- sodium_crypto_auth_keygen — Erzeugt einen zufälligen Schlüssel für sodium_crypto_auth
- sodium_crypto_auth_verify — Verifies that the tag is valid for the message
- sodium_crypto_box — Authenticated public-key encryption
- sodium_crypto_box_keypair — Erzeugt einen zufälligen geheimen Schlüssel und einen zugehörigen öffentlichen Schlüssel
- sodium_crypto_box_keypair_from_secretkey_and_publickey — Create a unified keypair string from a secret key and public key
- sodium_crypto_box_open — Authenticated public-key decryption
- sodium_crypto_box_publickey — Extract the public key from a crypto_box keypair
- sodium_crypto_box_publickey_from_secretkey — Calculate the public key from a secret key
- sodium_crypto_box_seal — Anonymous public-key encryption
- sodium_crypto_box_seal_open — Anonymous public-key decryption
- sodium_crypto_box_secretkey — Extracts the secret key from a crypto_box keypair
- sodium_crypto_box_seed_keypair — Deterministically derive the key pair from a single key
- sodium_crypto_core_ristretto255_add — Adds an element
- sodium_crypto_core_ristretto255_from_hash — Maps a vector
- sodium_crypto_core_ristretto255_is_valid_point — Determines if a point on the ristretto255 curve
- sodium_crypto_core_ristretto255_random — Generates a random key
- sodium_crypto_core_ristretto255_scalar_add — Adds a scalar value
- sodium_crypto_core_ristretto255_scalar_complement — The sodium_crypto_core_ristretto255_scalar_complement purpose
- sodium_crypto_core_ristretto255_scalar_invert — Inverts a scalar value
- sodium_crypto_core_ristretto255_scalar_mul — Multiplies a scalar value
- sodium_crypto_core_ristretto255_scalar_negate — Negates a scalar value
- sodium_crypto_core_ristretto255_scalar_random — Generates a random key
- sodium_crypto_core_ristretto255_scalar_reduce — Reduces a scalar value
- sodium_crypto_core_ristretto255_scalar_sub — Subtracts a scalar value
- sodium_crypto_core_ristretto255_sub — Subtracts an element
- sodium_crypto_generichash — Get a hash of the message
- sodium_crypto_generichash_final — Complete the hash
- sodium_crypto_generichash_init — Initialize a hash for streaming
- sodium_crypto_generichash_keygen — Erzeugt einen zufälligen Generichash-Schlüssel
- sodium_crypto_generichash_update — Add message to a hash
- sodium_crypto_kdf_derive_from_key — Derive a subkey
- sodium_crypto_kdf_keygen — Erzeugt einen zufälligen Stammschlüssel für die KDF-Schnittstelle
- sodium_crypto_kx_client_session_keys — Calculate the client-side session keys.
- sodium_crypto_kx_keypair — Creates a new sodium keypair
- sodium_crypto_kx_publickey — Extract the public key from a crypto_kx keypair
- sodium_crypto_kx_secretkey — Extract the secret key from a crypto_kx keypair.
- sodium_crypto_kx_seed_keypair — Description
- sodium_crypto_kx_server_session_keys — Calculate the server-side session keys.
- sodium_crypto_pwhash — Derive a key from a password, using Argon2
- sodium_crypto_pwhash_scryptsalsa208sha256 — Derives a key from a password, using scrypt
- sodium_crypto_pwhash_scryptsalsa208sha256_str — Get an ASCII encoded hash
- sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verify that the password is a valid password verification string
- sodium_crypto_pwhash_str — Get an ASCII-encoded hash
- sodium_crypto_pwhash_str_needs_rehash — Determine whether or not to rehash a password
- sodium_crypto_pwhash_str_verify — Verifies that a password matches a hash
- sodium_crypto_scalarmult — Compute a shared secret given a user's secret key and another user's public key
- sodium_crypto_scalarmult_base — Alias von sodium_crypto_box_publickey_from_secretkey
- sodium_crypto_scalarmult_ristretto255 — Computes a shared secret
- sodium_crypto_scalarmult_ristretto255_base — Calculates the public key from a secret key
- sodium_crypto_secretbox — Authenticated shared-key encryption
- sodium_crypto_secretbox_keygen — Generate random key for sodium_crypto_secretbox
- sodium_crypto_secretbox_open — Authenticated shared-key decryption
- sodium_crypto_secretstream_xchacha20poly1305_init_pull — Initialize a secretstream context for decryption
- sodium_crypto_secretstream_xchacha20poly1305_init_push — Initialize a secretstream context for encryption
- sodium_crypto_secretstream_xchacha20poly1305_keygen — Erzeugt einen zufälligen Secretstream-Schlüssel
- sodium_crypto_secretstream_xchacha20poly1305_pull — Decrypt a chunk of data from an encrypted stream
- sodium_crypto_secretstream_xchacha20poly1305_push — Encrypt a chunk of data so that it can safely be decrypted in a streaming API
- sodium_crypto_secretstream_xchacha20poly1305_rekey — Explicitly rotate the key in the secretstream state
- sodium_crypto_shorthash — Compute a short hash of a message and key
- sodium_crypto_shorthash_keygen — Erzeugt zufällige Bytes für einen Schlüssel
- sodium_crypto_sign — Sign a message
- sodium_crypto_sign_detached — Sign the message
- sodium_crypto_sign_ed25519_pk_to_curve25519 — Convert an Ed25519 public key to a Curve25519 public key
- sodium_crypto_sign_ed25519_sk_to_curve25519 — Convert an Ed25519 secret key to a Curve25519 secret key
- sodium_crypto_sign_keypair — Erzeugt einen zufälligen geheimen Schlüssel und einen zugehörigen öffentlichen Schlüssel
- sodium_crypto_sign_keypair_from_secretkey_and_publickey — Join a secret key and public key together
- sodium_crypto_sign_open — Check that the signed message has a valid signature
- sodium_crypto_sign_publickey — Extract the Ed25519 public key from a keypair
- sodium_crypto_sign_publickey_from_secretkey — Extract the Ed25519 public key from the secret key
- sodium_crypto_sign_secretkey — Extract the Ed25519 secret key from a keypair
- sodium_crypto_sign_seed_keypair — Deterministically derive the key pair from a single key
- sodium_crypto_sign_verify_detached — Verify signature for the message
- sodium_crypto_stream — Generate a deterministic sequence of bytes from a seed
- sodium_crypto_stream_keygen — Erzeugt einen zufälligen sodium_crypto_stream-Schlüssel
- sodium_crypto_stream_xchacha20 — Expands the key and nonce into a keystream of pseudorandom bytes
- sodium_crypto_stream_xchacha20_keygen — Gibt einen sicheren zufälligen Schlüssel zurück
- sodium_crypto_stream_xchacha20_xor — Encrypts a message using a nonce and a secret key (no authentication)
- sodium_crypto_stream_xchacha20_xor_ic — Encrypts a message using a nonce and a secret key (no authentication)
- sodium_crypto_stream_xor — Encrypt a message without authentication
- sodium_hex2bin — Dekodiert eine hexadezimal kodierte binäre Zeichenkette
- sodium_increment — Inkrementieren einer großen Zahl
- sodium_memcmp — Prüfung auf Gleichheit bei konstanter Zeit
- sodium_memzero — Überschreibt eine Zeichenkette mit einem Nullzeichen
- sodium_pad — Fügt Fülldaten hinzu
- sodium_unpad — Entfernt Fülldaten

# Die SodiumException-Klasse

(PHP 7 >= 7.2.0, PHP 8)

## Einführung

Exceptions, die von den Sodium-Funktionen geworfen werden.

## Klassenbeschreibung

class SodiumException extends Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Vordefinierte Konstanten
- Sodium Funktionen
  - sodium_add — Addition großer Zahlen
  - sodium_base642bin — Dekodiert eine Base64-kodierte Zeichenkette in das Binärformat.
  - sodium_bin2base64 — Kodiert eine binäre Zeichenkette mit Base64.
  - sodium_bin2hex — Kodiert in Hexadezimal
  - sodium_compare — Vergleicht große Zahlen
  - sodium_crypto_aead_aegis128l_decrypt — Verify then decrypt a message with AEGIS-128L
  - sodium_crypto_aead_aegis128l_encrypt — Encrypt then authenticate a message with AEGIS-128L
  - sodium_crypto_aead_aegis128l_keygen — Generate a random AEGIS-128L key
  - sodium_crypto_aead_aegis256_decrypt — Verify then decrypt a message with AEGIS-256
  - sodium_crypto_aead_aegis256_encrypt — Encrypt then authenticate a message with AEGIS-256
  - sodium_crypto_aead_aegis256_keygen — Generate a random AEGIS-256 key
  - sodium_crypto_aead_aes256gcm_decrypt — Überprüft und entschlüsselt eine Nachricht mit AES-256-GCM
  - sodium_crypto_aead_aes256gcm_encrypt — Verschlüsselt und authentifiziert eine Nachricht mit AES-256-GCM
  - sodium_crypto_aead_aes256gcm_is_available — Prüft, ob die Hardware AES256-GCM unterstützt
  - sodium_crypto_aead_aes256gcm_keygen — Generiert einen zufälligen AES-256-GCM-Schlüssel
  - sodium_crypto_aead_chacha20poly1305_decrypt — Überprüft und entschlüsselt eine Nachricht mit ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_encrypt — Verschlüsselt und authentifiziert eine Nachricht mit ChaCha20-Poly1305
  - sodium_crypto_aead_chacha20poly1305_ietf_decrypt — Überprüft, ob der Chiffriertext ein gültiges Tag enthält
  - sodium_crypto_aead_chacha20poly1305_ietf_encrypt — Verschlüsselt eine Nachricht
  - sodium_crypto_aead_chacha20poly1305_ietf_keygen — Generiert einen zufälligen ChaCha20-Poly1305-IETF-Schlüssel.
  - sodium_crypto_aead_chacha20poly1305_keygen — Generiert einen zufälligen ChaCha20-Poly1305-Schlüssel
  - sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — (Empfohlen) Überprüft und entschlüsselt eine Nachricht mit XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — (Empfohlen) Verschlüsselt und authentifiziert eine Nachricht mit XChaCha20-Poly1305
  - sodium_crypto_aead_xchacha20poly1305_ietf_keygen — Generiert einen zufälligen XChaCha20-Poly1305-Schlüssel.
  - sodium_crypto_auth — Compute a tag for the message
  - sodium_crypto_auth_keygen — Erzeugt einen zufälligen Schlüssel für sodium_crypto_auth
  - sodium_crypto_auth_verify — Verifies that the tag is valid for the message
  - sodium_crypto_box — Authenticated public-key encryption
  - sodium_crypto_box_keypair — Erzeugt einen zufälligen geheimen Schlüssel und einen zugehörigen öffentlichen Schlüssel
  - sodium_crypto_box_keypair_from_secretkey_and_publickey — Create a unified keypair string from a secret key and public key
  - sodium_crypto_box_open — Authenticated public-key decryption
  - sodium_crypto_box_publickey — Extract the public key from a crypto_box keypair
  - sodium_crypto_box_publickey_from_secretkey — Calculate the public key from a secret key
  - sodium_crypto_box_seal — Anonymous public-key encryption
  - sodium_crypto_box_seal_open — Anonymous public-key decryption
  - sodium_crypto_box_secretkey — Extracts the secret key from a crypto_box keypair
  - sodium_crypto_box_seed_keypair — Deterministically derive the key pair from a single key
  - sodium_crypto_core_ristretto255_add — Adds an element
  - sodium_crypto_core_ristretto255_from_hash — Maps a vector
  - sodium_crypto_core_ristretto255_is_valid_point — Determines if a point on the ristretto255 curve
  - sodium_crypto_core_ristretto255_random — Generates a random key
  - sodium_crypto_core_ristretto255_scalar_add — Adds a scalar value
  - sodium_crypto_core_ristretto255_scalar_complement — The sodium_crypto_core_ristretto255_scalar_complement purpose
  - sodium_crypto_core_ristretto255_scalar_invert — Inverts a scalar value
  - sodium_crypto_core_ristretto255_scalar_mul — Multiplies a scalar value
  - sodium_crypto_core_ristretto255_scalar_negate — Negates a scalar value
  - sodium_crypto_core_ristretto255_scalar_random — Generates a random key
  - sodium_crypto_core_ristretto255_scalar_reduce — Reduces a scalar value
  - sodium_crypto_core_ristretto255_scalar_sub — Subtracts a scalar value
  - sodium_crypto_core_ristretto255_sub — Subtracts an element
  - sodium_crypto_generichash — Get a hash of the message
  - sodium_crypto_generichash_final — Complete the hash
  - sodium_crypto_generichash_init — Initialize a hash for streaming
  - sodium_crypto_generichash_keygen — Erzeugt einen zufälligen Generichash-Schlüssel
  - sodium_crypto_generichash_update — Add message to a hash
  - sodium_crypto_kdf_derive_from_key — Derive a subkey
  - sodium_crypto_kdf_keygen — Erzeugt einen zufälligen Stammschlüssel für die KDF-Schnittstelle
  - sodium_crypto_kx_client_session_keys — Calculate the client-side session keys.
  - sodium_crypto_kx_keypair — Creates a new sodium keypair
  - sodium_crypto_kx_publickey — Extract the public key from a crypto_kx keypair
  - sodium_crypto_kx_secretkey — Extract the secret key from a crypto_kx keypair.
  - sodium_crypto_kx_seed_keypair — Description
  - sodium_crypto_kx_server_session_keys — Calculate the server-side session keys.
  - sodium_crypto_pwhash — Derive a key from a password, using Argon2
  - sodium_crypto_pwhash_scryptsalsa208sha256 — Derives a key from a password, using scrypt
  - sodium_crypto_pwhash_scryptsalsa208sha256_str — Get an ASCII encoded hash
  - sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — Verify that the password is a valid password verification string
  - sodium_crypto_pwhash_str — Get an ASCII-encoded hash
  - sodium_crypto_pwhash_str_needs_rehash — Determine whether or not to rehash a password
  - sodium_crypto_pwhash_str_verify — Verifies that a password matches a hash
  - sodium_crypto_scalarmult — Compute a shared secret given a user's secret key and another user's public key
  - sodium_crypto_scalarmult_base — Alias von sodium_crypto_box_publickey_from_secretkey
  - sodium_crypto_scalarmult_ristretto255 — Computes a shared secret
  - sodium_crypto_scalarmult_ristretto255_base — Calculates the public key from a secret key
  - sodium_crypto_secretbox — Authenticated shared-key encryption
  - sodium_crypto_secretbox_keygen — Generate random key for sodium_crypto_secretbox
  - sodium_crypto_secretbox_open — Authenticated shared-key decryption
  - sodium_crypto_secretstream_xchacha20poly1305_init_pull — Initialize a secretstream context for decryption
  - sodium_crypto_secretstream_xchacha20poly1305_init_push — Initialize a secretstream context for encryption
  - sodium_crypto_secretstream_xchacha20poly1305_keygen — Erzeugt einen zufälligen Secretstream-Schlüssel
  - sodium_crypto_secretstream_xchacha20poly1305_pull — Decrypt a chunk of data from an encrypted stream
  - sodium_crypto_secretstream_xchacha20poly1305_push — Encrypt a chunk of data so that it can safely be decrypted in a streaming API
  - sodium_crypto_secretstream_xchacha20poly1305_rekey — Explicitly rotate the key in the secretstream state
  - sodium_crypto_shorthash — Compute a short hash of a message and key
  - sodium_crypto_shorthash_keygen — Erzeugt zufällige Bytes für einen Schlüssel
  - sodium_crypto_sign — Sign a message
  - sodium_crypto_sign_detached — Sign the message
  - sodium_crypto_sign_ed25519_pk_to_curve25519 — Convert an Ed25519 public key to a Curve25519 public key
  - sodium_crypto_sign_ed25519_sk_to_curve25519 — Convert an Ed25519 secret key to a Curve25519 secret key
  - sodium_crypto_sign_keypair — Erzeugt einen zufälligen geheimen Schlüssel und einen zugehörigen öffentlichen Schlüssel
  - sodium_crypto_sign_keypair_from_secretkey_and_publickey — Join a secret key and public key together
  - sodium_crypto_sign_open — Check that the signed message has a valid signature
  - sodium_crypto_sign_publickey — Extract the Ed25519 public key from a keypair
  - sodium_crypto_sign_publickey_from_secretkey — Extract the Ed25519 public key from the secret key
  - sodium_crypto_sign_secretkey — Extract the Ed25519 secret key from a keypair
  - sodium_crypto_sign_seed_keypair — Deterministically derive the key pair from a single key
  - sodium_crypto_sign_verify_detached — Verify signature for the message
  - sodium_crypto_stream — Generate a deterministic sequence of bytes from a seed
  - sodium_crypto_stream_keygen — Erzeugt einen zufälligen sodium_crypto_stream-Schlüssel
  - sodium_crypto_stream_xchacha20 — Expands the key and nonce into a keystream of pseudorandom bytes
  - sodium_crypto_stream_xchacha20_keygen — Gibt einen sicheren zufälligen Schlüssel zurück
  - sodium_crypto_stream_xchacha20_xor — Encrypts a message using a nonce and a secret key (no authentication)
  - sodium_crypto_stream_xchacha20_xor_ic — Encrypts a message using a nonce and a secret key (no authentication)
  - sodium_crypto_stream_xor — Encrypt a message without authentication
  - sodium_hex2bin — Dekodiert eine hexadezimal kodierte binäre Zeichenkette
  - sodium_increment — Inkrementieren einer großen Zahl
  - sodium_memcmp — Prüfung auf Gleichheit bei konstanter Zeit
  - sodium_memzero — Überschreibt eine Zeichenkette mit einem Nullzeichen
  - sodium_pad — Fügt Fülldaten hinzu
  - sodium_unpad — Entfernt Fülldaten
- SodiumException — Die SodiumException-Klasse

# Xpass

# Einführung

This extension provides password hashing algorithms used by Linux distributions, using extended crypt library.

It also provides additional functions from libxcrypt missing in core PHP.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation via PECL

## Anforderungen

This extension requires » libxcrypt version 4.4 or higher.

## Installation via PECL

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/xpass.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

Xpass extension provides various set of constants. Hash methods (`CRYPT_PREFIX_*`) for crypt_gensalt() prefix parameter. Error codes (`CRYPT_SALT_*`) returned by crypt_checksalt(). Password algorithms (`PASSWORD_*`) for password_hash() algo parameter.

Hashing methods
`CRYPT_PREFIX_STD_DES` (string)
  The original hashing method from Unix V7, based on the DES block cipher. Because DES is cheap on modern hardware, because there are only `4096` possible salts and 2**56 distinct passphrases, which it truncates to 8 characters, it is feasible to discover any passphrase hashed with this method. It should only be used when supporting old operating systems that support no other hash generation algorithm, due to how weak DES hashes are.
`CRYPT_PREFIX_EXT_DES` (string)
  An extension of traditional DES, which eliminates the length limit, increases the salt size, and makes the time cost tunable. It originates with BSDI BSD/OS and is also available on at least NetBSD, OpenBSD, and FreeBSD due to the use of David Burren's FreeSec library. It is much better than traditional DES and bigcrypt, but still should not be used for new hashes.
`CRYPT_PREFIX_MD5` (string)
  A hash based on the MD5 algorithm, originally developed by Poul-Henning Kamp for FreeBSD. Supported on most free Unixes and newer versions of Solaris. Not as weak as the DES-based hashes below, but MD5 is so cheap on modern hardware that it should not be used for new hashes. Processing cost is not adjustable.
`CRYPT_PREFIX_BLOWFISH` (string)
  A hash based on the Blowfish block cipher, modified to have an extra-expensive key schedule. Originally developed by Niels Provos and David Mazieres for OpenBSD and also supported on recent versions of FreeBSD and NetBSD, on Solaris 10 and newer, and on several GNU/*/Linux distributions.
`CRYPT_PREFIX_SHA256` (string)
  A hash based on SHA-2 with 256-bit output, originally developed by Ulrich Drepper for GNU libc. Supported on Linux but not common elsewhere. Acceptable for new hashes. The default processing cost parameter is `5000`, which is too low for modern hardware.
`CRYPT_PREFIX_SHA512` (string)
  A hash based on SHA-2 with 512-bit output, originally developed by Ulrich Drepper for GNU libc. Supported on Linux but not common elsewhere. Acceptable for new hashes. The default processing cost parameter is `5000`, which is too low for modern hardware.
`CRYPT_PREFIX_SCRYPT` (string)
  Scrypt is a password-based key derivation function created by Colin Percival, originally for the Tarsnap online backup service. The algorithm was specifically designed to make it costly to perform large-scale custom hardware attacks by requiring large amounts of memory. In 2016, the scrypt algorithm was published by IETF as RFC 7914.
`CRYPT_PREFIX_GOST_YESCRYPT` (string)
  Gost-yescrypt uses the output from yescrypt as an input message to HMAC with the GOST R 34.11-2012 (Streebog) hash function with a 256-bit digest. Thus, yescrypt's cryptographic properties are superseded by those of the GOST hash function. This hashing method is useful in applications that need modern passphrase hashing, but have to rely on GOST algorithms. The GOST R 34.11-2012 (Streebog) hash function has been published by the IETF as RFC 6986. Acceptable for new hashes where required.
`CRYPT_PREFIX_YESCRYPT` (string)
  Yescrypt is a scalable passphrase hashing scheme designed by Solar Designer, which is based on Colin Percival's scrypt. While yescrypt's strength against password guessing attacks comes from its algorithm design, its cryptographic security is guaranteed by its use of SHA-256 on the outer layer. The SHA-256 hash function has been published by NIST in FIPS PUB 180-2 (and its subsequent revisions such as FIPS PUB 180-4) and by the IETF as RFC 4634 (and subsequently RFC 6234). Recommended for new hashes.
`CRYPT_PREFIX_SM3CRYPT` (string)
  A hash based on the ShangMi 3 hash function with 256-bit output, that uses the same design as sha256crypt and/or sha512crypt. Supported on EulerOS, Kylin, openEuler, and openKylin, but not common elsewhere. Acceptable for new hashes where required. The default processing cost parameter is 5000, which is too low for modern hardware. Available as of 1.2.0 with libcxcrypt >= 4.5.0.
`CRYPT_PREFIX_SM3_YESCRYPT` (string)
  Sm3-yescrypt uses the output from yescrypt as an input message to HMAC with the ShangMi 3 hash function with a 256-bit digest. Thus, yescrypt's cryptographic properties are superseded by those of the ShangMi 3 hash function. This hashing method is useful in applications that need modern passphrase hashing, but have to rely on algorithms approved by the Chinese Office of State Commercial Cryptography Administration (OSCCA). The ShangMi 3 hash function has been published in Part 3: "Dedicated hash-functions" of the ISO/IEC 10118-3:2018. Acceptable for new hashes where required. Available as of 1.2.0 with libcxcrypt >= 4.5.0.

Error codes
`CRYPT_SALT_OK` (int)
  No error.
`CRYPT_SALT_INVALID` (int)
  Unknown hashing method or invalid parameters.
`CRYPT_SALT_METHOD_DISABLED` (int)
  Hashing method is no longer allowed to be used.
`CRYPT_SALT_METHOD_LEGACY` (int)
  Hashing method is no longer considered strong enough.
`CRYPT_SALT_TOO_CHEAP` (int)
  Cost parameters are considered too cheap.

Password algorithms
`PASSWORD_SHA512` (string)
  `PASSWORD_SHA512` is used to create new password hashes using the `CRYPT_PREFIX_SHA512` algorithm.
`PASSWORD_YESCRYPT` (string)
  `PASSWORD_YESCRYPT` is used to create new password hashes using the `CRYPT_PREFIX_YESCRYPT` algorithm.
`PASSWORD_SM3CRYPT` (string)
  `PASSWORD_SM3CRYPT` is used to create new password hashes using the `CRYPT_PREFIX_SM3CRYPT` algorithm. Available as of 1.2.0 with libcxcrypt >= 4.5.0.
`PASSWORD_SM3_YESCRYPT` (string)
  `PASSWORD_SM3_YESCRYPT` is used to create new password hashes using the `CRYPT_PREFIX_SM3_YESCRYPT` algorithm. Available as of 1.2.0 with libcxcrypt >= 4.5.0.

# Xpass Funktionen

# crypt_checksalt

(PECL xpass >= 1.1.0)

crypt_checksalt — Validate a crypt setting string

### Beschreibung

function crypt_checksalt(string `$salt`): ?string

Checks the salt string against the system configuration and reports whether the hashing method and parameters it specifies are acceptable. It is intended to be used to determine whether the user's passphrase should be re-hashed using the currently preferred hashing method.

### Parameter-Liste

`salt`
  Salt string to check.

### Rückgabewerte

Returns one of the `CRYPT_SALT_*` as an int.

### Beispiele

Beispiel #1 A crypt_checksalt() example

    <?php
    // Generate a salt for a legacy method
    $salt = crypt_gensalt(CRYPT_PREFIX_STD_DES);
    // Check the salt
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_METHOD_LEGACY);

    // Generate a salt for default method
    $salt = crypt_gensalt();
    // Check the salt
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_OK);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)

### Siehe auch

- crypt_gensalt() - Compile a string for use as the salt argument to crypt

# crypt_gensalt

(PECL xpass >= 1.1.0)

crypt_gensalt — Compile a string for use as the salt argument to crypt

### Beschreibung

function crypt_gensalt(string `$prefix` = `null`, int `$count` = 0): ?string

Compile a string for use as the salt argument to crypt().

### Parameter-Liste

`prefix`
  Hashing method. One of the `CRYPT_PREFIX_*` constant. If `null`, the best available hashing method will be selected.
`count`
  Controls the processing cost of the hash; the valid range and exact meaning of count depend on the hashing method, but larger numbers correspond to more costly hashes in terms of CPU time and possibly memory usage. If count is `0`, a low default cost will be selected.

### Rückgabewerte

Returns a string with the setting, or `null` in case of an error.

### Beispiele

Beispiel #1 A crypt_gensalt() example

    <?php
    // Generate the salt
    $salt = crypt_gensalt(CRYPT_PREFIX_BLOWFISH);
    // Hash the password
    $hash = crypt("secret", $salt);
    // Check the hash
    $test = hash_equals(crypt("secret", $hash), $hash);
    var_dump($salt, $hash, $test);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(29) "$2y$05$GcPykP.Am8C1.dGamdpwW."
    string(60) "$2y$05$GcPykP.Am8C1.dGamdpwW.1RR.7uicWvJPZfJfCEizZHqVWwuaJLm"
    bool(true)

### Siehe auch

- crypt_preferred_method() - Get the prefix of the preferred hash method
- crypt() - Einweg-String-Hashing
- hash_equals() - Timing attack safe string comparison

# crypt_preferred_method

(PECL xpass >= 1.1.0)

crypt_preferred_method — Get the prefix of the preferred hash method

### Beschreibung

function crypt_preferred_method(): ?string

Get the prefix of the preferred hash method.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string with the prefix, or `null` in case of an error.

### Beispiele

Beispiel #1 A crypt_preferred_method() example

    <?php
    var_dump(crypt_preferred_method());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "$y$"

### Siehe auch

- crypt_gensalt() - Compile a string for use as the salt argument to crypt

## Inhaltsverzeichnis

- crypt_checksalt — Validate a crypt setting string
- crypt_gensalt — Compile a string for use as the salt argument to crypt
- crypt_preferred_method — Get the prefix of the preferred hash method

- Installation/Konfiguration
  - Anforderungen
  - Installation via PECL
- Vordefinierte Konstanten
- Xpass Funktionen
  - crypt_checksalt — Validate a crypt setting string
  - crypt_gensalt — Compile a string for use as the salt argument to crypt
  - crypt_preferred_method — Get the prefix of the preferred hash method

- Hash — HASH Message Digest Framework
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - HashContext — The HashContext class
  - Hash-Funktionen
- Mcrypt
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Mcrypt Chiffren
  - Mcrypt Funktionen
- Mhash
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Mhash Funktionen
- OpenSSL
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Schlüssel-/Zertifikatparameter
  - Überprüfung von Zertifikaten
  - OpenSSL-Funktionen
  - OpenSSLCertificate — The OpenSSLCertificate class
  - OpenSSLCertificateSigningRequest — The OpenSSLCertificateSigningRequest class
  - OpenSSLAsymmetricKey — The OpenSSLAsymmetricKey class
- Password Hashing
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Passwort-Hashing-Funktionen
- Rnp
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Rnp Funktionen
  - RnpFFI — The RnpFFI class
- Sodium
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Sodium Funktionen
  - SodiumException — Die SodiumException-Klasse
- Xpass
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Xpass Funktionen

# Datenbankerweiterungen

# Abstraktionsebenen

# Abstraktionsschicht für dbm-style-Datenbanken

# Einführung

Diese Funktionen bilden die Basis für den Zugriff auf Datenbanken vom Typ "Berkeley DB".

"dba" implementiert eine generelle Abstraktionsschicht für verschiedene dateibasierte Datenbanken. Der Funktionsumfang ist daher beschränkt auf eine gemeinsame Teilmenge des Funktionsumfangs aktueller Datenbanken wie zum Beispiel » Oracle Berkeley DB.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

Das Verhalten der dba-Funktionen ist teilweise abhängig von der Implementation des zugrundeliegenden Datenbanksystems. Funktionen wie zum Beispiel dba_optimize() und dba_sync() funktionieren möglicherweise bei einem Datenbanksystem wie erwartet, während sie bei anderen nichts bewirken. Die unterstützten DBA-Treiber müssen heruntergeladen und installiert werden.

Liste der DBA-Treiber
Treiber | Hinweise
--- | ---
`dbm` | Dbm ist der ursprüngliche und älteste Typ der "Berkeley DB"-Datenbanken. Wenn möglich, sollten Sie diesen Typ vermeiden. Die in DB2 und gdbm enthaltenen Kompatibilitätsfunktionen werden nicht unterstützt, da sie nur auf Quellcode-Basis kompatibel sind, aber das original dbm-Format nicht bearbeiten können.
`ndbm` | Ndbm ist neuer und flexibler als Dbm. Er hat jedoch die meisten Einschränkungen von Dbm übernommen und ist daher ebenfalls nicht empfehlenswert.
`gdbm` | Gdbm ist der » GNU-Datenbank-Manager.
`db2` | DB2 ist für » Oracle Berkeley DB 2. Es wird beschrieben als "Werkzeugsatz mit eingebauter Hochleistungs-Unterstützung von Datenbanken sowohl für Standalone- als auch für Client/Server-Anwendungen".
`db3` | DB3 ist für » Oracle Berkeley DB 3.
`db4` | DB4 ist für » Oracle Berkeley DB 4 oder 5. Ab PHP 5.3.3 kann er mit BDB 5 verwendet werden.
`cdb` | Cdb ist "ein schnelles, zuverlässiges und kompaktes Paket zum Erstellen und Auslesen konstanter Datenbanken." Es stammt vom Autor von qmail und kann bei » http://cr.yp.to/cdb.html heruntergeladen werden. Da es für konstante Daten ausgelegt ist, werden nur lesende Operationen unterstützt. Durch die interne cdb-Bibliothek werden auch schreibende Operationen (aber keine Aktualisierungen) unterstützt.
`cdb_make` | Bei Verwendung der in PHP mitgelieferten cdb-Bibliothek können cdb-Dateien erzeugt (aber nicht aktualisiert) werden.
`flatfile` | Steht wegen der Kompatibilität mit der veralteten `dbm`-Erweiterung zur Verfügung und sollte vermieden werden. Sie können ihn aber bei Dateien verwenden, die in diesem Format erzeugt wurden. Das geschieht, wenn configure keine externe Bibliothek finden konnte.
`inifile` | Steht zur Verfügung, damit php.ini-Dateien über PHP-Skripte geändert werden können. Wenn mit ini-Dateien gearbeitet wird, können Arrays der Form array(0=>gruppe,1=>wert_name) oder Zeichenketten der Form "[gruppe]wert_name" (gruppe ist optional) übergeben werden. Da die Funktionen dba_firstkey() und dba_nextkey() die Zeichenketten-Darstellung des Schlüssels zurückgeben, steht die Funktion dba_key_split() zur Verfügung, die es ermöglicht, die Zeichenketten-Schlüssel in Array-Schlüssel umzuwandeln, ohne dass das `false` verloren geht.
`qdbm` | Die qdbm-Bibliothek kann bei » http://fallabs.com/qdbm/index.html heruntergeladen werden.
`tcadb` | Die Tokyo-Cabinet-Bibliothek kann von » http://fallabs.com/tokyocabinet/ heruntergeladen werden.
`lmdb` | Steht ab PHP 7.2.0 zur Verfügung. Die Lightning Memory-Mapped Database Bibliothek kann von » https://symas.com/lmdb/ heruntergeladen werden.

Beim Aufruf von dba_open() oder dba_popen() muss einer der Treibernamen als Argument angegeben werden. Die Liste der tatsächlich verfügbaren Treiber lässt sich mittlels phpinfo() oder dba_handlers() angezeigen.

## Installation

Durch die Verwendung der Konfigurationsoption --enable-dba=shared wird ein dynamisch ladbares Modul erstellt, mit dem PHP eine grundlegende Unterstützung von dbm-style-Datenbanken bietet. Es muss außerdem die Unterstützung für mindestens einen der folgenden Handler hinzugefügt werden, indem der configure-Schalter --with-XXXX oder --enable-XXXX im PHP-Konfigurationsaufruf angegegeben wird.

Warnung

Nachdem PHP konfiguriert und kompiliert wurde, muss in der Kommandozeile der folgende Test ausgeführt werden: `php run-tests.php ext/dba`. Damit zeigt sich, ob die Kombination der Handler funktioniert. Am problematischsten sind `dbm` und `ndbm`, die mit vielen Installationen kollidieren. Das liegt daran, dass diese Bibliotheken auf einigen Systemen Bestandteil von mehr als einer anderen Bibliothek sind. Der Konfigurationstest verhindert nur die Konfiguration fehlerhafter einzelner Handler, aber nicht die Konfiguration fehlerhafter Kombinationen.

Unterstützte DBA-Handler
Handler | Configure-Schalter
--- | ---
`dbm` | Fügen Sie --with-dbm[=DIR] hinzu, um die Unterstützung für dbm zu aktivieren. Hinweis: dbm ist für gewöhnlich ein Wrapper, der häufig zu Fehlern führt. Das bedeutet, dass Sie dbm nur benutzen sollten, wenn Sie sicher sind, dass er funktioniert und wenn Sie dieses Format wirklich benötigen.
`ndbm` | Fügen Sie --with-ndbm[=DIR] hinzu, um die Unterstützung für ndbm zu aktivieren. Hinweis: ndbm ist für gewöhnlich ein Wrapper, der häufig zu Fehlern führt. Das bedeutet, dass Sie ndbm nur verwenden sollten, wenn Sie sicher sind, dass er funktioniert und wenn Sie dieses Format wirklich benötigen.
`gdbm` | Fügen Sie --with-gdbm[=DIR] hinzu, um die Unterstützung für gdbm zu aktivieren.
`db2` | Fügen Sie --with-db2[=DIR] hinzu, um die Unterstützung für Oracle Berkeley DB 2 zu aktivieren. Hinweis: db2 kollidiert mit db3 und db4.
`db3` | Fügen Sie --with-db3[=DIR] hinzu, um die Unterstützung für Oracle Berkeley DB 3 zu aktivieren. Hinweis: db3 kollidiert mit db2 und db4.
`db4` | Fügen Sie --with-db4[=DIR] hinzu, um die Unterstützung für Oracle Berkeley DB 4 oder 5 zu aktivieren. Hinweis: db4 kollidiert mit db2 und db3. Hinweis: Die db-Bibliotheken von Version 4.1 bis 4.1.24 können mit keiner Version von PHP verwendet werden. Die Unterstützung für BDB 5 wurde in PHP 5.3.3 hinzugefügt.
`cdb` | Fügen Sie --with-cdb[=DIR] hinzu, um die Unterstützung für cdb zu aktivieren. Hinweis: DIR kann weggelassen werden um die in PHP enthaltene cdb-Bibliothek zu verwenden. Diese fügt den cdb_make-Handler hinzu, mit dem es möglich ist, cdb-Dateien zu erzeugen und über den Datenstrom von PHP auf cdb-Dateien im Netzwerk zuzugreifen.
`flatfile` | Fügen Sie --enable-flatfile hinzu, um die Unterstützung für flatfile zu aktivieren. Vor PHP 5.2.1 musste statt dessen --with-flatfile verwendet werden. Hinweis: Dies wurde für die Kompatibilität mit der veralteten `dbm`-Erweiterung hinzugefügt. Verwenden Sie diesen Handler nur dann, wenn Sie keine der Bibliotheken installieren können, die von anderen Handlern benötigt werden und den in PHP enthaltenen cdb-Handler nicht verwenden können.
`inifile` | Fügen Sie --enable-inifile hinzu, um die Unterstützung für `inifile` zu aktivieren. Vor PHP 5.2.1 musste statt dessen --with-inifile verwendet werden. Hinweis: Dies wurde hinzugefügt um es zu ermöglichen, .ini-Dateien im Microsoft-Stil (z. B. die php.ini) zu lesen und zu schreiben.
`qdbm` | Fügen Sie --with-qdbm[=DIR] hinzu, um die Unterstützung für qdbm zu aktivieren. Hinweis: qdbm kollidiert mit dbm und gdbm. Hinweis: Die qdbm-Bibliothek kann bei » http://fallabs.com/qdbm/index.html heruntergeladen werden.
`tcadb` | Um Unterstützung für Tokyo Cabinet zu aktivieren, muss --with-tcadb[=DIR] hinzugefügt werden. Hinweis: Die Tokyo Cabinet Bibliothek kann von » http://fallabs.com/tokyocabinet/ heruntergeladen werden.
`lmdb` | Um Unterstützung für die Lightning Memory-Mapped Database zu aktivieren, muss --with-lmdb[=DIR] hinzugefügt werden. Hinweis: Dies wurde in PHP 7.2.0 hinzugefügt. Die Lightning Memory-Mapped Database Bibliothek kann von » https://symas.com/lmdb/ heruntergeladen werden.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

DBA Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
dba.default_handler | DBA_DEFAULT | `INI_ALL` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`dba.default_handler` string
  Der Name der Standard-Verbindungskennung

## Ressource-Typen

Vor PHP 8.4.0 arbeiteten die meisten DBA-Funktionen mit Ressourcen oder gaben diese zurück (z. B. gibt dba_open() eine positive DBA-Verbindungskennung zurück, die von den meisten DBA-Funktionen benötigt wird).

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`DBA_LMDB_USE_SUB_DIR` (int)
  Das Flag für den LMDB-Treiber, das es erlaubt, ein Unterverzeichnis für die Datenbankdateien zu erstellen. Verfügbar ab PHP 8.2.0.
`DBA_LMDB_NO_SUB_DIR` (int)
  Das Flag für den LMDB-Treiber, das es verbietet, ein Unterverzeichnis für die Datenbankdateien zu erstellen. Verfügbar ab PHP 8.2.0.

# Beispiele

## Inhaltsverzeichnis

- Die grundlegende Verwendung

## Die grundlegende Verwendung

Beispiel #1 DBA Beispiel

    <?php

    $id = dba_open("/tmp/test.db", "n", "db2");

    if (!$id) {
        echo "dba_open schlug fehl\n";
        exit;
    }

    dba_replace("schluessel", "Dies ist ein Beispiel!", $id);

    if (dba_exists("schluessel", $id)) {
        echo dba_fetch("schluessel", $id);
        dba_delete("schluessel", $id);
    }

    dba_close($id);
    ?>

DBA arbeitet binärsicher und besitzt keine willkürlichen Limits. Es erbt allerdings alle Einschränkungen von der zugrundeliegenden Datenbank-Implementation.

Alle dateibasierten Datenbanken müssen, soweit es überhaupt möglich ist, einen Weg zur Verfügung stellen, um den Dateimodus einer neu erstellten Datenbank festzulegen. Der Dateimodus wird gewöhnlich als viertes Argument an die Funktionen dba_open() oder dba_popen() übergeben.

Sie können auf alle Einträge in einer Datenbank sequentiell durch die Verwendung von dba_firstkey() und dba_nextkey() zugreifen. Während die Datenbank so durchlaufen wird, darf sie nicht verändert werden.

Beispiel #2 Durchlaufen einer Datenbank

    <?php

    // ...Oeffnen der Datenbank...

    $schluessel = dba_firstkey($id);

    while ($schluessel !== false) {
        if (true) {          // den Schluessel fuer spaetere Aktionen merken
            $spaeter_bearbeiten[] = $schluessel;
        }
        $schluessel = dba_nextkey($id);
    }

    foreach ($spaeter_bearbeiten as $wert) {
        dba_delete($wert, $id);
    }

    ?>

# The Dba\Connection class

(PHP 8 >= 8.4.0)

## Einführung

A fully opaque class which replaces a `dba` resource as of PHP 8.4.0.

## Klassenbeschreibung

namespace Dba;
final class Connection {
}

# DBA-Funktionen

# dba_close

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_close — Schließt eine DBA-Datenbank

### Beschreibung

function dba_close(Dba\Connection `$dba`): void

dba_close() schließt die offene Datenbank und gibt alle Ressourcen der angegebenen Datenbank-Verbindungskennung frei.

### Parameter-Liste

`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.

### Siehe auch

- dba_open() - Öffnet eine Datenbank
- dba_popen() - Öffnet eine persistente Datenbank-Verbindung

# dba_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_delete — Löscht den zum angegebenen Schlüssel gehörigen DBA-Eintrag

### Beschreibung

function dba_delete(string|array `$key`, Dba\Connection `$dba`): bool

dba_delete() löscht den angegebenen Eintrag aus der Datenbank.

### Parameter-Liste

`key`
  Der Schlüssel des zu löschenden Eintrags.
`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.

### Siehe auch

- dba_exists() - Überprüft, ob ein angegebener Schlüssel existiert
- dba_fetch() - Liest die Daten zu einem angegebenen Schlüssel aus
- dba_insert() - Fügt einen Eintrag ein
- dba_replace() - Ersetzt einen Eintrag oder fügt ihn ein

# dba_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_exists — Überprüft, ob ein angegebener Schlüssel existiert

### Beschreibung

function dba_exists(string|array `$key`, Dba\Connection `$dba`): bool

dba_exists() überprüft, ob der angegebene `Schlüssel` in der Datenbank existiert.

### Parameter-Liste

`key`
  Der Schlüssel, für den die Überprüfung durchgeführt wird.
`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.

### Rückgabewerte

Gibt `true` zurück, falls der Schlüssel existiert und andernfalls `false`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.

### Siehe auch

- dba_delete() - Löscht den zum angegebenen Schlüssel gehörigen DBA-Eintrag
- dba_fetch() - Liest die Daten zu einem angegebenen Schlüssel aus
- dba_insert() - Fügt einen Eintrag ein
- dba_replace() - Ersetzt einen Eintrag oder fügt ihn ein

# dba_fetch

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_fetch — Liest die Daten zu einem angegebenen Schlüssel aus

### Beschreibung

function dba_fetch(string|array `$key`, Dba\Connection `$dba`, int `$skip` = 0): string|false

Seit PHP 8.3.0 ist die überladene Signatur veraltet:

function dba_fetch(string|array `$key`, int `$skip`, resource `$dba`): string

dba_fetch() liest die durch `key` festgelegten Daten aus der durch `dba` spezifizierten Datenbank aus.

### Parameter-Liste

`key`
  Der Schlüssel, durch den die Daten bestimmt sind.

  > Hinweis: Wenn mit ini-Dateien gearbeitet wird, akzeptiert diese Funktion Arrays als Schlüssel, wobei der Index 0 die Gruppe ist und der Index 1 der Name des Wertes. Siehe dba_key_split().

`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.
`skip`
  Die Anzahl der Schlüssel-Wert-Paare, die bei cdb-Datenbanken ignoriert werden sollen. Dieser Wert wird bei allen anderen Datenbanken, die keine Unterstützung für mehrere Schlüssel mit demselben Namen bieten, ignoriert.

### Rückgabewerte

Falls das Schlüssel/Wert-Paar gefunden wird, wird die zugehörige Zeichenkette zurückgegeben, andernfalls `false`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.
8.3.0 | Der Aufruf von dba_fetch() mit `dba` als drittes Argument ist nun veraltet.
8.2.0 | Das optionale Skip-Argument von dba_fetch() steht nun an letzter Stelle, was der Semantik benutzerdefinierter Funktionen in PHP entspricht. Die zuvor verwendete überladene Signatur ist nach wie vor zulässig, aber es wird empfohlen, sie nicht zu verwenden.

### Siehe auch

- dba_exists() - Überprüft, ob ein angegebener Schlüssel existiert
- dba_delete() - Löscht den zum angegebenen Schlüssel gehörigen DBA-Eintrag
- dba_insert() - Fügt einen Eintrag ein
- dba_replace() - Ersetzt einen Eintrag oder fügt ihn ein
- dba_key_split() - Zerlegt einen Schlüssel in Zeichenketten-Darstellung in eine Array-Darstellung

# dba_firstkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_firstkey — Liefert den ersten Schlüssel

### Beschreibung

function dba_firstkey(Dba\Connection `$dba`): string|false

dba_firstkey() gibt den ersten Schlüssel aus der Datenbank zurück und setzt den internen Schlüssel-Zeiger zurück. Dies erlaubt eine sequentielle Suche durch die gesamte Datenbank.

### Parameter-Liste

`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.

### Rückgabewerte

Gibt bei Erfolg den Schlüssel zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.

### Siehe auch

- dba_nextkey() - Liefert den nachfolgenden Schlüssel
- dba_key_split() - Zerlegt einen Schlüssel in Zeichenketten-Darstellung in eine Array-Darstellung
- Beispiel 2 der DBA-Beispiele

# dba_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_handlers — Listet alle verfügbaren Handler auf

### Beschreibung

function dba_handlers(bool `$full_info` = `false`): array

dba_handlers() listet alle Handler auf, die von dieser Erweiterung unterstützt werden.

### Parameter-Liste

`full_info`
  Schaltet die Anzeige der kompletten Information im Ergebnis ein/aus.

### Rückgabewerte

Gibt ein Array mit Datenbank-Handlern zurück. Falls `full_info` auf `true` gesetzt war, ist es ein assoziatives Array mit den Namen der Handler als Schlüssel und deren Versionsinformationen als Wert. Andernfalls ist das Ergebnis ein indiziertes Array mit den Namen der Handler.

> Hinweis: Falls die interne cdb-Bibliothek verwendet wird, sehen Sie `cdb` und `cdb_make`.

### Beispiele

Beispiel #1 dba_handlers()-Beispiel

    <?php

    echo "Verfügbare DBA-Handler:\n";
    foreach (dba_handlers(true) as $handler_name => $handler_version) {
      // die Versionen "säubern"
      $handler_version = str_replace('$', '', $handler_version);
      echo " - $handler_name: $handler_version\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Verfügbare DBA-Handler:
     - cdb: 0.75, Revision: 1.3.2.3
     - cdb_make: 0.75, Revision: 1.2.2.4
     - db2: Sleepycat Software: Berkeley DB 2.7.7: (08/20/99)
     - inifile: 1.0, Revision: 1.6.2.3
     - flatfile: 1.0, Revision: 1.5.2.4

# dba_insert

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_insert — Fügt einen Eintrag ein

### Beschreibung

function dba_insert(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_insert() fügt den Eintrag, der durch `key` und `value` beschrieben wird, in die Datenbank ein.

### Parameter-Liste

`key`
  Der Schlüssel des einzufügenden Eintrags. Die Aktion schlägt fehl, wenn es den Schlüssel schon in der Datenbank gibt. Verwenden Sie dba_replace(), falls Sie einen vorhandenen Schlüssel ersetzen wollen.
`value`
  Der Wert, der eingefügt werden soll.
`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.

### Siehe auch

- dba_exists() - Überprüft, ob ein angegebener Schlüssel existiert
- dba_delete() - Löscht den zum angegebenen Schlüssel gehörigen DBA-Eintrag
- dba_fetch() - Liest die Daten zu einem angegebenen Schlüssel aus
- dba_replace() - Ersetzt einen Eintrag oder fügt ihn ein

# dba_key_split

(PHP 5, PHP 7, PHP 8)

dba_key_split — Zerlegt einen Schlüssel in Zeichenketten-Darstellung in eine Array-Darstellung

### Beschreibung

function dba_key_split(string|false|null `$key`): array|false

dba_key_split() zerlegt einen Schlüssel, der in Zeichenketten-Darstellung vorliegt in eine Array-Darstellung.

### Parameter-Liste

`key`
  Der Schlüssel in Zeichenketten-Darstellung.

### Rückgabewerte

Gibt ein Array der Form `array(0 => gruppe, 1 => wert_name)` zurück. Falls `Schlüssel` `null` oder `false` ist, gibt diese Funktion `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Übergabe von `null` oder `false` an `key` ist nun veraltet.

### Siehe auch

- dba_firstkey() - Liefert den ersten Schlüssel
- dba_nextkey() - Liefert den nachfolgenden Schlüssel
- dba_fetch() - Liest die Daten zu einem angegebenen Schlüssel aus

# dba_list

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_list — Listet alle offenen Datenbank-Dateien auf

### Beschreibung

function dba_list(): array

dba_list() listet alle offenen Datenbank-Dateien auf.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Ein assoziatives Array der Form `Ressource-ID => Dateiname`.

# dba_nextkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_nextkey — Liefert den nachfolgenden Schlüssel

### Beschreibung

function dba_nextkey(Dba\Connection `$dba`): string|false

dba_nextkey() gibt den nachfolgenden Schlüssel aus der Datenbank zurück und erhöht den internen Schlüssel-Zeiger.

### Parameter-Liste

`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.

### Rückgabewerte

Gibt bei Erfolg den Schlüssel zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.

### Siehe auch

- dba_firstkey() - Liefert den ersten Schlüssel
- dba_key_split() - Zerlegt einen Schlüssel in Zeichenketten-Darstellung in eine Array-Darstellung
- Beispiel 2 der DBA-Beispiele

# dba_open

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_open — Öffnet eine Datenbank

### Beschreibung

function dba_open(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_open() stellt eine Datenbankinstanz für `path` mit `mode` her und verwendet dabei `handler`.

### Parameter-Liste

`path`
  Ein gültiger Pfad im Dateisystem.
`mode`
  Das ist `r` für lesenden Zugriff, `w` für lesenden und schreibenden Zugriff auf eine existierende Datenbank, `c` für lesenden und schreibenden Zugriff und Erstellen der Datenbank, falls sie noch nicht existiert, und `n` für das Erstellen einer Datenbank, bzw. deren Zurücksetzen auf die Größe 0, falls sie schon existiert, und lesenden und schreibenden Zugriff. Die Datenbank wird im BTree-Modus erzeugt. Andere Modi, wie Hash oder Queue, werden nicht unterstützt. Zusätzlich kann mit dem nächsten Buchstaben die Datenbank-Sperrmethode festgelegt werden. Verwenden Sie `l`, um die Datenbank mit einer .lck-Datei zu sperren, oder `d`, um die Datenbank-Datei selbst zu sperren. Es ist wichtig, dass alle Ihre Anwendungen das einheitlich machen. Falls Sie den Zugriff testen wollen, ohne auf die Sperrung zu warten, können Sie `t` als dritten Buchstaben anfügen. Wenn Sie sich absolut sicher sind, dass Sie keine Datenbanksperre benötigen, können Sie statt `l` oder `d` `-` verwenden. Wenn weder `d` oder `l` noch `-` verwendet werden, sperrt dba die Datenbank-Datei wie bei Verwendung von `d`.

  > Hinweis:

  > Es kann jeweils nur einen Schreibzugriff auf eine Datenbank-Datei geben. Wenn dba auf einem Webserver verwendet wird und mehr als eine Anfrage Schreibzugriff benötigt, kann nur einer nach dem anderen erledigt werden. Auch das Lesen ist während des Schreibens nicht erlaubt. Die DBA-Erweiterung verwendet Sperren, um dies zu verhindern. Siehe folgende Tabelle:

  > DBA-Sperrung
  > schon geöffnet | `mode` = "rl" | `mode` = "rlt" | `mode` = "wl" | `mode` = "wlt" | `mode` = "rd" | `mode` = "rdt" | `mode` = "wd" | `mode` = "wdt"
  > --- | --- | --- | --- | --- | --- | --- | --- | ---
  > nicht geöffnet | OK | OK | OK | OK | OK | OK | OK | OK
  > `mode` = "rl" | OK | OK | warten | `false` | unzulässig | unzulässig | unzulässig | unzulässig
  > `mode` = "wl" | warten | `false` | warten | `false` | unzulässig | unzulässig | unzulässig | unzulässig
  > `mode` = "rd" | unzulässig | unzulässig | unzulässig | unzulässig | OK | OK | warten | `false`
  > `mode` = "wd" | unzulässig | unzulässig | unzulässig | unzulässig | warten | `false` | warten | `false`

  > - OK: der zweite Aufruf ist erfolgreich.
  > - warten: der zweite Aufruf wartet bis für den ersten dba_close() aufgerufen wird.
  > - `false`: der zweite Aufruf gibt `false` zurück.
  > - unzulässig: Sie dürfen beim Parameter `mode` die Modifikatoren `"l"` und `"d"` nicht zusammen verwenden.

`handler`
  Der Name des Handlers, der für den Zugriff auf `path` benutzt werden soll. Er bekommt alle optionalen Argumente übergeben, die der Funktion dba_open() mitgegeben wurden, und kann damit in deren Name verfahren. Wenn `handler` `null` ist, wird der Standard-Handler aufgerufen.
`permission`
  Ein optionaler Integer-Parameter, der an den Treiber übergeben wird. Er hat dieselbe Bedeutung wie der Parameter `permissions` bei chmod(). Der Standardwert ist `0644`. Der Parameter `permission` wird vom `db1`-, `db2`-, `db3`-, `db4`-, `dbm`-, `gdbm`-, `ndbm`- und `lmdb`-Treiber unterstützt.
`map_size`
  Ein optionaler Integer-Parameter, der an den Treiber übergeben wird. Sein Wert sollte ein Vielfaches der Größe einer Speicherseite (Page Size) des Betriebssystems sein. Wenn Null angegeben wird, wird die Standard-Map-Size verwendet. Der Parameter `map_size` wird nur vom `lmdb`-Treiber akzeptiert.
`flags`
  Die Flags, die an den Datenbanktreiber übergeben werden. Falls `null`, werden die Standard-Flags bereitgestellt. Derzeit unterstützt nur der LMDB-Treiber die Flags `DBA_LMDB_USE_SUB_DIR` und `DBA_LMDB_NO_SUB_DIR`.

### Rückgabewerte

Gibt bei Erfolg eine Instanz von Dba\Connection zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn `handler` `null` ist, aber kein Standard-Handler zur Verfügung steht, wird `false` zurückgegeben und ein Fehler der Stufe `E_WARNING` ausgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Gibt nun eine Instanz von Dba\Connection zurück; zuvor wurde eine Ressource zurückgegeben.
8.2.0 | Der Parameter `flags` wurde hinzugefügt.
8.2.0 | Der Parameter `handler` ist nun nullable (akzeptiert den `null`-Wert).
7.3.14, 7.4.2 | Der `lmdb`-Treiber unterstützt nun zusätzlich den Parmeter `map_size`.

### Siehe auch

- dba_popen() - Öffnet eine persistente Datenbank-Verbindung
- dba_close() - Schließt eine DBA-Datenbank

# dba_optimize

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_optimize — Optimiert eine Datenbank

### Beschreibung

function dba_optimize(Dba\Connection `$dba`): bool

dba_optimize() optimiert die zugrunde liegende Datenbank.

### Parameter-Liste

`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.

### Siehe auch

- dba_sync() - Synchronisiert eine Datenbank

# dba_popen

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_popen — Öffnet eine persistente Datenbank-Verbindung

### Beschreibung

function dba_popen(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|false

dba_popen() stellt eine persistente Datenbankinstanz für `path` mit `mode` her und benutzt dabei den Handler `handler`.

### Parameter-Liste

`path`
  Ein gültiger Pfad im Dateisystem.
`mode`
  Das ist `r` für lesenden Zugriff, `w` für lesenden und schreibenden Zugriff auf eine existierende Datenbank, `c` für lesenden und schreibenden Zugriff und Erstellen der Datenbank, falls sie noch nicht existiert, und `n` für das Erstellen einer Datenbank, bzw. deren Zurücksetzen auf die Größe 0, falls sie schon existiert, und lesenden und schreibenden Zugriff.
`handler`
  Der Name des Handlers, der für den Zugriff auf `path` benutzt werden soll. Er bekommt alle optionalen Argumente übergeben, die der Funktion dba_popen() mitgegeben wurden, und kann damit in deren Name verfahren. Wenn `handler` `null` ist, wird der Standard-Handler aufgerufen.
`permission`
  Ein optionaler Integer-Parameter, der an den Treiber übergeben wird. Er hat dieselbe Bedeutung wie der Parameter `permissions` bei chmod(). Der Standardwert ist `0644`. Der Parameter `permission` wird vom `db1`-, `db2`-, `db3`-, `db4`-, `dbm`-, `gdbm`-, `ndbm`- und `lmdb`-Treiber unterstützt.
`map_size`
  Ein optionaler Integer-Parameter, der an den Treiber übergeben wird. Sein Wert sollte ein Vielfaches der Größe einer Speicherseite (Page Size) des Betriebssystems sein. Wenn Null angegeben wird, wird die Standard-Map-Size verwendet. Der Parameter `map_size` wird nur vom `lmdb`-Treiber akzeptiert.
`flags`
  Die Flags, die an den Datenbanktreiber übergeben werden. Derzeit unterstützt nur der LMDB-Treiber die Flags `DBA_LMDB_USE_SUB_DIR` und `DBA_LMDB_NO_SUB_DIR`.

### Rückgabewerte

Gibt bei Erfolg eine Instanz von Dba\Connection zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn `handler` `null` ist, aber kein Standard-Handler zur Verfügung steht, wird `false` zurückgegeben und ein Fehler der Stufe `E_WARNING` ausgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Gibt nun eine Instanz von Dba\Connection zurück; zuvor wurde eine Ressource zurückgegeben.
8.2.0 | Der Parameter `flags` wurde hinzugefügt.
8.1.0 | Der Parameter `handler` ist nun nullable (akzeptiert den `null`-Wert).
7.3.14, 7.4.2 | Der `lmdb`-Treiber unterstützt nun zusätzlich den Parmeter `map_size`.

### Siehe auch

- dba_open() - Öffnet eine Datenbank
- dba_close() - Schließt eine DBA-Datenbank

# dba_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_replace — Ersetzt einen Eintrag oder fügt ihn ein

### Beschreibung

function dba_replace(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_replace() ersetzt in der durch `dba` spezifizierten Datenbank den Eintrag, der durch `key` und `value` beschrieben wird, oder fügt ihn ein.

### Parameter-Liste

`key`
  Der Schlüssel des zu ersetzenden Eintrags.
`value`
  Der Wert, der ersetzt werden soll.
`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.

### Siehe auch

- dba_exists() - Überprüft, ob ein angegebener Schlüssel existiert
- dba_delete() - Löscht den zum angegebenen Schlüssel gehörigen DBA-Eintrag
- dba_fetch() - Liest die Daten zu einem angegebenen Schlüssel aus
- dba_insert() - Fügt einen Eintrag ein

# dba_sync

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_sync — Synchronisiert eine Datenbank

### Beschreibung

function dba_sync(Dba\Connection `$dba`): bool

dba_sync() synchronisiert die Datenbank. Dies kann möglicherweise einen physikalischen Schreibvorgang auf den Datenträger auslösen, falls dies unterstützt wird.

### Parameter-Liste

`dba`
  Eine von dba_open() oder dba_popen() zurückgegebene Instanz von Dba\Connection.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Parameter `dba` erwartet nun eine Instanz von Dba\Connection; zuvor wurde eine gültige `dba`-Ressource erwartet.

### Siehe auch

- dba_optimize() - Optimiert eine Datenbank

## Inhaltsverzeichnis

- dba_close — Schließt eine DBA-Datenbank
- dba_delete — Löscht den zum angegebenen Schlüssel gehörigen DBA-Eintrag
- dba_exists — Überprüft, ob ein angegebener Schlüssel existiert
- dba_fetch — Liest die Daten zu einem angegebenen Schlüssel aus
- dba_firstkey — Liefert den ersten Schlüssel
- dba_handlers — Listet alle verfügbaren Handler auf
- dba_insert — Fügt einen Eintrag ein
- dba_key_split — Zerlegt einen Schlüssel in Zeichenketten-Darstellung in eine Array-Darstellung
- dba_list — Listet alle offenen Datenbank-Dateien auf
- dba_nextkey — Liefert den nachfolgenden Schlüssel
- dba_open — Öffnet eine Datenbank
- dba_optimize — Optimiert eine Datenbank
- dba_popen — Öffnet eine persistente Datenbank-Verbindung
- dba_replace — Ersetzt einen Eintrag oder fügt ihn ein
- dba_sync — Synchronisiert eine Datenbank

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Beispiele
  - Die grundlegende Verwendung
- Dba\Connection — The Dba\Connection class
- DBA-Funktionen
  - dba_close — Schließt eine DBA-Datenbank
  - dba_delete — Löscht den zum angegebenen Schlüssel gehörigen DBA-Eintrag
  - dba_exists — Überprüft, ob ein angegebener Schlüssel existiert
  - dba_fetch — Liest die Daten zu einem angegebenen Schlüssel aus
  - dba_firstkey — Liefert den ersten Schlüssel
  - dba_handlers — Listet alle verfügbaren Handler auf
  - dba_insert — Fügt einen Eintrag ein
  - dba_key_split — Zerlegt einen Schlüssel in Zeichenketten-Darstellung in eine Array-Darstellung
  - dba_list — Listet alle offenen Datenbank-Dateien auf
  - dba_nextkey — Liefert den nachfolgenden Schlüssel
  - dba_open — Öffnet eine Datenbank
  - dba_optimize — Optimiert eine Datenbank
  - dba_popen — Öffnet eine persistente Datenbank-Verbindung
  - dba_replace — Ersetzt einen Eintrag oder fügt ihn ein
  - dba_sync — Synchronisiert eine Datenbank

# ODBC (Unified)

# Einführung

Zusätzlich zur normalen ODBC Unterstützung bieten die Unified ODBC Funktionen in PHP Zugriff auf Datenbanken die bei der Implementierung ihrer eigenen APIs die Semantik dem ODBC API entliehen haben. Statt mehrere beinahe identische Datenbankerweiterungen zu pflegen wurden all diese Treiber zu einem vereinheitlichten Satz von ODBC Funktione verschmolzen.

Die folgenden Datenbanken werden von Unified ODBC unterstützt: » Adabas D, » IBM DB2, » iODBC, » Solid, and » Sybase SQL Anywhere.

> Hinweis:

> Mit Ausnahme von iODBC erfolgt der Zugriff auf die genannten Datenbanken ohne dass ODBC selbst benötigt wird. Die Funktionen greifen direkt auf die jeweilige Datenbank zu, bieten aber die gleichen Funktionsnamen und Parameter wie die entsprechenden ODBC Funktionen. Wird PHP dagegen mit iODBC Unsterstützung kompiliert so ist es möglich jeden ODBC-konforme Treiber aus PHP Applikationen heraus zu nutzen. Weitere Informationen zu iODBC finden sich unter » www.iodbc.org und der Alternative unixODBC » www.unixodbc.org.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

Um auf eine der unterstützten Datenbanken zugreifen zu können, müssen die erforderlichen Bibliotheken installiert sein.

## Installation

--with-adabas[=DIR]

  Aktiviert die Adabas-D-Unterstützung. DIR ist das Adabas-Installationsverzeichnis oder /usr/local, wenn nicht angegeben.

--with-sapdb[=DIR]

  Aktiviert die SAP-DB-Unterstützung. DIR ist das SAP-DB-Installationsverzeichnis oder /usr/local, wenn nicht angegeben.

--with-solid[=DIR]

  Aktiviert die Solid-Unterstützung. DIR ist das Solid-Installationsverzeichnis oder /usr/local/solid, wenn nicht angegeben.

--with-ibm-db2[=DIR]

  Aktiviert die IBM-DB2-Unterstützung. DIR ist das IBM-DB2-Installationsverzeichnis oder /home/db2inst1/sqllib, wenn nicht angegeben.

--with-empress[=DIR]

  Aktiviert die Empress-Unterstützung. DIR ist das Empress-Installationsverzeichnis oder $EMPRESSPATH, wenn nicht angegeben. Es wird nur Empress Version 8.60 oder höher unterstützt.

--with-empress-bcs[=DIR]

  Aktiviert die `"Empress Local Access"`-Unterstützung. DIR ist das Empress-Installationsverzeichnis oder $EMPRESSPATH, wenn nicht angegeben. Es wird nur Empress Version 8.60 oder höher unterstützt.

--with-birdstep[=DIR]

  Aktiviert die Birdstep-Unterstützung. DIR ist das Birdstep-Installationsverzeichnis oder /usr/local/birdstep, wenn nicht angegeben.

--with-custom-odbc[=DIR]

  Aktiviert die benutzerdefinierte ODBC-Unterstützung. DIR ist das ODBC-Installationsverzeichnis oder /usr/local, wenn nicht angegeben. Es muss sichergestellt werden, dass CUSTOM_ODBC_LIBS definiert ist, und dass eine odbc.h-Datei im Includepfad existiert. Für Sybase SQL Anywhere 5.5.00 unter QNX sollten z. B. vor dem Aufruf des configure-Skripts folgende Umgebungsvariablen gesetzt werden:

         CPPFLAGS="-DODBC_QNX -DSQLANY_BUG"
         LDFLAGS=-lunix
         CUSTOM_ODBC_LIBS="-ldblib -lodbc".

--with-iodbc[=DIR]

  Aktiviert die iODBC-Unterstützung. DIR ist das iODBC-Installationsverzeichnis oder /usr/local, wenn nicht angegeben.

--with-esoob[=DIR]

  Aktiviert die Easysoft-OOB-Unterstützung. DIR ist das OOB-Installationsverzeichnis oder /usr/local/easysoft/oob/client, wenn nicht angegeben.

--with-unixODBC[=DIR]

  Aktiviert die unixODBC-Unterstützung. DIR ist das unixODBC-Installationsverzeichnis oder /usr/local, wenn nicht angegeben.

--with-openlink[=DIR]

  Aktiviert die OpenLink-ODBC-Unterstützung. DIR ist das OpenLink-Installationsverzeichnis oder /usr/local, wenn nicht angegeben. Dieses Modul entspricht iODBC.

--with-dbmaker[=DIR]

  Aktiviert die DBMaker-Unterstützung. DIR ist das DBMaker-Installationsverzeichnis oder das Verzeichnis, in dem die neueste DBMaker-Version installiert ist, wenn nicht angegeben (z. B. /home/dbmaker/3.6).

Windows-Benutzer müssen php_odbc.dll aktivieren, um diese Erweiterung zu verwenden.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Unified ODBC-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
odbc.allow_persistent | "1" | `INI_SYSTEM` |
odbc.check_persistent | "1" | `INI_SYSTEM` |
odbc.max_persistent | "-1" | `INI_SYSTEM` |
odbc.max_links | "-1" | `INI_SYSTEM` |
odbc.defaultlrl | "4096" | `INI_ALL` |
odbc.defaultbinmode | "1" | `INI_ALL` |
odbc.default_cursortype | "3" | `INI_ALL` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`odbc.default_db` string

  Zu verwendende ODBC-Datenquelle, falls keine mit odbc_connect() oder odbc_pconnect() angegeben wurde.

`odbc.default_user` string

  Zu verwendender Benutzername, falls keiner in odbc_connect() oder odbc_pconnect() angegeben wurde.

`odbc.default_pw` string

  Zu verwendendes Passwort, falls keines in odbc_connect() oder odbc_pconnect() angegeben wurde.

`odbc.allow_persistent` bool

  Gibt an, ob persistente ODBC-Verbindungen möglich sein sollen.

`odbc.check_persistent` bool

  Prüft vor der Benutzung, ob eine persistente Verbindung noch gültig ist.

`odbc.max_persistent` int

  Die maximale Anzahl persistenter ODBC-Verbindungen je Prozess.

`odbc.max_links` int

  Die maximale Anzahl der ODBC-Verbindungen je Prozess (inklusive persistenter Verbindungen).

`odbc.defaultlrl` int

  Behandlung von LONG-Feldern. Gibt die Anzahl der Bytes an, die an Variablen zurückgegeben werden. Siehe odbc_longreadlen() für Details.

  Wird ein Wert vom Typ int verwendet, wird dieser Wert in Bytes gemessen. Es kann auch die Kurzschreibweise verwendet werden, wie in dieser FAQ beschrieben.
`odbc.defaultbinmode` int

  Handhabung binärer Daten. Siehe odbc_binmode() für Details.

`odbc.default_cursortype` int

  Bestimmt das ODBC-Cursormodell. Mögliche Werte sind `SQL_CURSOR_FORWARD_ONLY`, `SQL_CURSOR_KEYSET_DRIVEN`, `SQL_CURSOR_DYNAMIC` und `SQL_CURSOR_STATIC` (Standardwert).

## Ressource-Typen

Vor PHP 8.4.0 definierte diese Erweiterung zwei Ressourcetypen: eine ODBC-Verbindungskennung und eine ODBC-Ergebniskennung.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`ODBC_TYPE` (string)
`ODBC_BINMODE_PASSTHRU` (int)
`ODBC_BINMODE_RETURN` (int)
`ODBC_BINMODE_CONVERT` (int)
`SQL_ODBC_CURSORS` (int)
`SQL_CUR_USE_DRIVER` (int)
`SQL_CUR_USE_IF_NEEDED` (int)
`SQL_CUR_USE_ODBC` (int)
`SQL_CONCURRENCY` (int)
`SQL_CONCUR_READ_ONLY` (int)
`SQL_CONCUR_LOCK` (int)
`SQL_CONCUR_ROWVER` (int)
`SQL_CONCUR_VALUES` (int)
`SQL_CURSOR_TYPE` (int)
`SQL_CURSOR_FORWARD_ONLY` (int)
`SQL_CURSOR_KEYSET_DRIVEN` (int)
`SQL_CURSOR_DYNAMIC` (int)
`SQL_CURSOR_STATIC` (int)
`SQL_KEYSET_SIZE` (int)
`SQL_CHAR` (int)
`SQL_VARCHAR` (int)
`SQL_LONGVARCHAR` (int)
`SQL_WCHAR` (int)
  Unicode-Zeichenkette mit fester Länge.
`SQL_WVARCHAR` (int)
  Unicode-Zeichenkette mit variabler Länge.
`SQL_WLONGVARCHAR` (int)
  Unicode-Zeichendaten mit variabler Länge. Die maximale Länge hängt von der Datenquelle ab.
`SQL_DECIMAL` (int)
`SQL_NUMERIC` (int)
`SQL_BIT` (int)
`SQL_TINYINT` (int)
`SQL_SMALLINT` (int)
`SQL_INTEGER` (int)
`SQL_BIGINT` (int)
`SQL_REAL` (int)
`SQL_FLOAT` (int)
`SQL_DOUBLE` (int)
`SQL_BINARY` (int)
`SQL_VARBINARY` (int)
`SQL_LONGVARBINARY` (int)
`SQL_DATE` (int)
`SQL_TIME` (int)
`SQL_TIMESTAMP` (int)
`SQL_TYPE_DATE` (int)
`SQL_TYPE_TIME` (int)
`SQL_TYPE_TIMESTAMP` (int)
`SQL_BEST_ROWID` (int)
`SQL_ROWVER` (int)
`SQL_SCOPE_CURROW` (int)
`SQL_SCOPE_TRANSACTION` (int)
`SQL_SCOPE_SESSION` (int)
`SQL_NO_NULLS` (int)
`SQL_NULLABLE` (int)
`SQL_INDEX_UNIQUE` (int)
`SQL_INDEX_ALL` (int)
`SQL_ENSURE` (int)
`SQL_QUICK` (int)
`SQL_FETCH_FIRST` (int)
  Gibt die erste Zeile des Ergebnisses zurück.
`SQL_FETCH_NEXT` (int)
  Gibt die nächste Zeile des Ergebnisses zurück.

# ODBC Funktionen

# odbc_autocommit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_autocommit — Ändert das Autocommit-Verhalten

### Beschreibung

function odbc_autocommit(Odbc\Connection `$odbc`, ?bool `$enable` = `null`): int|bool

Schaltet das Autocommit-Verhalten um.

In der Standardeinstellung ist autocommit für eine Datenbankverbindung aktiviert. Das Deaktivieren von autocommit enspricht dem Starten einer Transaktion.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`enable`

  Ist `enable` `true`, ist Autocommit aktiviert, ist es `false`, ist Autocommit deaktiviert. Wird `null` übergeben, gibt diese Funktion den Autocommit-Status für `odbc` zurück.

### Rückgabewerte

Wenn der Parameter `enable` `null` ist, gibt diese Funktion den aktuellen autocommit-Status für die Datenbankverbindung `odbc` zurück. Eine Zahl ungleich 0 wird zurückgegeben, wenn autocommit aktiviert ist, 0, wenn es deaktiviert ist, und `false`, im Fehlerfall.

Wenn `enable` nicht `null` ist, gibt diese Funktion im Erfolgsfall `true` zurück, und `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.3.0 | `enable` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- odbc_commit() - Schließt eine ODBC-Transaktion ab
- odbc_rollback() - Bricht eine Transaktion ab

# odbc_binmode

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_binmode — Behandlung von Binärdaten

### Beschreibung

function odbc_binmode(Odbc\Result `$statement`, int `$mode`): true

Steuert die Behandlung binärer Spaltendaten. Betroffene ODBC SQL Typen sind `BINARY`, `VARBINARY` und `LONGVARBINARY`. Der Standardmodus kann mit der php.ini-Anweisung uodbc.defaultbinmode festgelegt werden.

Werden SQL-Binärdaten in C-Zeichendaten konvertiert (`ODBC_BINMODE_CONVERT`), wird jedes Byte (8 Bits) der ursprünglichen Daten zu zwei ASCII-Zeichen, die der hexadezimalen Darstellung des Wertes entsprechen. Der Binärwert 00000001 wird zum Beispiel zu `"01"` gewandelt, der Binärwert 11111111 zu `"FF"`.

Während die Behandlung von `BINARY`- und `VARBINARY`-Spalten nur von binmode abhängt, hängt die Behandlung von `LONGVARBINARY`-Spalten auch von longreadlen ab:

Die Benutzung von LONGVARBINARY
binmode | longreadlen | Resultat
--- | --- | ---
`ODBC_BINMODE_PASSTHRU` | 0 | Direkte Ausgabe
`ODBC_BINMODE_RETURN` | 0 | Direkte Ausgabe
`ODBC_BINMODE_CONVERT` | 0 | Direkte Ausgabe
`ODBC_BINMODE_PASSTHRU` | >0 | Direkte Ausgabe
`ODBC_BINMODE_RETURN` | >0 | Direkte Ausgabe
`ODBC_BINMODE_CONVERT` | >0 | Rückgabe als CHAR-Werte

Wenn odbc_fetch_into() genutzt wird, wird bei direkter Ausgabe ein leerer String als Spaltenwert zurückgeliefert. Wenn odbc__result() genutzt wird, werden die Daten bei direkter Ausgabe direkt an den Client gesendet, d. h. ausgegeben.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`mode`

  Mögliche Werte für `mode` sind:

  - `ODBC_BINMODE_PASSTHRU`: schleift BINÄRE Daten durch
  - `ODBC_BINMODE_RETURN`: liefert die Binärdaten unverändert zurück
  - `ODBC_BINMODE_CONVERT`: konvertiert die Binärdaten zu Zeichen und liefert sie zurück

  > Hinweis: Die Behandlung von binary long Spalten wird ebenfalls durch odbc_longreadlen() beeinflusst.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

# odbc_close

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close — Schließ eine ODBC-Verbindung

### Beschreibung

function odbc_close(Odbc\Connection `$odbc`): void

Schließt die Verbindung zum Datenbankserver.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.

### Anmerkungen

> Hinweis:

> Diese Funktion scheitert, wenn auf dieser Datenbankverbindung noch Transaktionen ausstehen. In diesem Fall bleibt die Verbindung geöffnet.

# odbc_close_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close_all — Schließt alle ODBC-Verbindungen

### Beschreibung

function odbc_close_all(): void

odbc_close_all() schließt alle bestehenden Verbindungen zu den Datenbankservern.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Anmerkungen

> Hinweis:

> Diese Funktion schlägt fehl, wenn noch Transaktionen auf einer Verbindung aktiv sind. Diese Verbindung wird in diesem Fall geöffnet bleiben.

# odbc_columnprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columnprivileges — Liste Spalten und damit verbundene Rechte für die angegeben Tabelle auf

### Beschreibung

function odbc_columnprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
string `$column`
): Odbc\Result|false

Listet die Spalten und die mit ihnen verbundenen Rechte für die gegebene Tabelle auf.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`catalog`

  Der Katalog ('Kennzeichner' in ODBC 2 Terminologie).

`schema`

  Das Schema ('Besitzer' in ODBC 2 Terminologie). Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`table`

  Der Tabellenname. Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`column`

  Der Spaltenname. Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurückBei einem Fehler wird `false` zurückgegeben.. Das Ergebnis-Objekt kann verwendet werden, um eine Liste von Spalten und den zugehörigen Rechten zu erhalten.

Die Ergebnismenge enhält die folgenden Spalten:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Treiber können zusätzliche Spalten melden.

Die Ergebnis-Resource ist nach `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `COLUMN_NAME` und `PRIVILEGE` sortiert.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Zugriffsberechtigungen für eine Spalte auflisten

    <?php
    $conn = odbc_connect($dsn, $benutzer, $pass);
    $berechtigungen = odbc_columnprivileges($conn, 'TutorialDB', 'dbo', 'test', 'id');
    while (($row = odbc_fetch_array($berechtigungen))) {
        print_r($row);
        break; // weitere Zeilen der Kürze halber weggelassen
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => test
        [COLUMN_NAME] => id
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => INSERT
        [IS_GRANTABLE] => YES
    )

# odbc_columns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columns — Lists the column names in specified tables

### Beschreibung

function odbc_columns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Lists all columns in the requested range.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`catalog`

  Der Katalog ('Kennzeichner' in ODBC 2 Terminologie).

`schema`

  Das Schema ('Besitzer' in ODBC 2 Terminologie). Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`table`

  The table name. Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`column`

  The column name. Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurückBei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Treiber können zusätzliche Spalten melden.

The result set is ordered by `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` and `ORDINAL_POSITION`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.0.0 | `schema`, `table` and `column` are now nullable.

### Beispiele

Beispiel #1 List Columns of a Table

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $columns = odbc_columns($conn, 'TutorialDB', 'dbo', 'test', '%');
    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [DATA_TYPE] => 4
        [TYPE_NAME] => int
        [COLUMN_SIZE] => 10
        [BUFFER_LENGTH] => 4
        [DECIMAL_DIGITS] => 0
        [NUM_PREC_RADIX] => 10
        [NULLABLE] => 0
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => 4
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] =>
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => NO
    )

### Siehe auch

- odbc_columnprivileges() - Liste Spalten und damit verbundene Rechte für die angegeben Tabelle auf
- odbc_procedurecolumns() - Retrieve information about parameters to procedures

# odbc_commit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_commit — Schließt eine ODBC-Transaktion ab

### Beschreibung

function odbc_commit(Odbc\Connection `$odbc`): bool

Schließt alle ausstehenden Transaktion der Verbindung ab.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.

# odbc_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_connect — Verbindet mit einer Datenquelle

### Beschreibung

function odbc_connect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

Die Verbindungskennung, die von dieser Funktion zurückgegeben wird, wird von anderen ODBC-Funktionen benötigt. Es können mehrere Verbindungen nebeneinander bestehen, solange sie entweder unterschiedliche Datenbanken oder unterschiedliche Anmeldeinformation verwenden.

Bei einigen ODBC-Treibern können möglicherweise Probleme bei der Ausführung von komplexen Prozeduren auftreten. Die Fehlermeldung lautet dann etwa "Cannot open a cursor on a stored procedure that has anything other than a single select statement in it". Die Verwendung von SQL_CUR_USE_ODBC kann diesen Fehler verhindern. Weiterhin unterstützen einige ODBC-Treiber den optionalen Parameter row_number der Funktion odbc_fetch_row() nicht. Auch in diesem Fall kann SQL_CUR_USE_ODBC helfen.

### Parameter-Liste

`dsn`

  Der Datenquellenname für die Verbindung. Alternativ kann auch eine DSN-lose Verbindungszeichenkette verwendet werden.

`user`

  Der Benutzername. Dieser Parameter wird ignoriert, wenn `dsn` `uid` enthält. Um eine Verbindung herzustellen, ohne den Parameter `user` anzugeben, muss `null` verwendet werden.

`password`

  Das Passwort. Dieser Parameter wird ignoriert, wenn `dsn` `pwd` enthält. Um eine Verbindung herzustellen, ohne den Parameter `password` anzugeben, muss `null` verwendet werden.

`cursor_option`

  Dies setzt die Art des Cursors, der für diese Verbindung genutzt werden soll. Normalerweise wird er nicht benötigt, kann aber bei manchen ODBC-Treiberproblemen nützlich sein.

  Folgende Konstanten sind als Cursortyp definiert:

  - SQL_CUR_USE_IF_NEEDED
  - SQL_CUR_USE_ODBC
  - SQL_CUR_USE_DRIVER

### Rückgabewerte

Gibt eine ODBC-Verbindung zurück. Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Connection zurück; vorher wurde eine Ressource zurückgegeben.
8.4.0 | `user` und `password` sind nun nullable (akzeptieren den `null`-Wert); sie sind nun auch optional und standardmäßig auf `null` gesetzt.
8.4.0 | Bisher wurde bei der Verwendung einer leeren Zeichenkette für `password` `pwd` nicht in die generierte Verbindungszeichenkette für `dsn` aufgenommen. Jetzt wird ein `pwd` mit einer leeren Zeichenkette als Wert erzeugt. Um das vorherige Verhalten wiederherzustellen, kann `password` nun auf `null` gesetzt werden.
8.4.0 | Wenn `dsn` `uid` oder `pwd` enthielt, wurden bisher die Parameter `user` und `password` ignoriert. Jetzt wird `user` nur ignoriert, wenn `dsn` `uid` enthält, und `password` wird nur ignoriert, wenn `dsn` `pwd` enthält.

### Beispiele

Beispiel #1 DSN-lose Verbindung

    <?php
    // Microsoft SQL Server unter Verwendung des SQL Native Client 10.0 ODBC-Treibers - ermöglicht Verbindungen zu SQL 7, 2000, 2005 und 2008
    $connection = odbc_connect("Driver={SQL Server Native Client 10.0};Server=$server;Database=$database;", $user, $password);

    // Microsoft Access
    $connection = odbc_connect("Driver={Microsoft Access Driver (*.mdb)};Dbq=$mdbFilename", $user, $password);

    // Microsoft Excel
    $excelFile = realpath('C:/ExcelData.xls');
    $excelDir = dirname($excelFile);
    $connection = odbc_connect("Driver={Microsoft Excel Driver (*.xls)};DriverId=790;Dbq=$excelFile;DefaultDir=$excelDir" , '', '');
    ?>

### Siehe auch

- Für persistente Verbindungen: odbc_pconnect() - Öffnet eine persistente Datenbankverbindung

# odbc_connection_string_is_quoted

(PHP 8 >= 8.2.0)

odbc_connection_string_is_quoted — Determines if an ODBC connection string value is quoted

### Beschreibung

function odbc_connection_string_is_quoted(string `$str`): bool

Determines if a string is properly quoted for an ODBC connection string value. ODBC connection string quoting is performed using curly braces, and ending braces within a string must be escaped through repeating them twice, similar to SQL quoting.

### Parameter-Liste

`str`

  The string to check for quoting.

### Rückgabewerte

`true` if quoted properly, `false` if not.

### Siehe auch

- odbc_connection_string_quote() - Quotes an ODBC connection string value
- odbc_connection_string_should_quote() - Determines if an ODBC connection string value should be quoted

# odbc_connection_string_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_quote — Quotes an ODBC connection string value

### Beschreibung

function odbc_connection_string_quote(string `$str`): string

Quotes a value for a connection string, according to ODBC rules. That is, it will be surrounded by quotes, and any ending curly braces will be escaped. This should be done for any connection string values that come from user input. Not doing so can lead to issues with parsing the connection string, or values being injected into the connection string.

Note that this function does not check if the string is already quoted, nor if the string needs quoting. For that, call odbc_connection_string_is_quoted() and odbc_connection_string_should_quote().

### Parameter-Liste

`str`

  The unquoted string.

### Rückgabewerte

A quoted string, surrounded by curly braces, and properly escaped.

### Beispiele

Beispiel #1 odbc_connection_string_quote() example

This example quotes a string, then puts it in a connection string. Note that the string is quoted, and the ending quote character in the middle of the string has been escaped.

    <?php
    $value = odbc_connection_string_quote("foo}bar");
    $connection_string = "DSN=PHP;UserValue=$value";
    echo $connection_string;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    DSN=PHP;UserValue={foo}}bar}

### Siehe auch

- odbc_connection_string_is_quoted() - Determines if an ODBC connection string value is quoted
- odbc_connection_string_should_quote() - Determines if an ODBC connection string value should be quoted

# odbc_connection_string_should_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_should_quote — Determines if an ODBC connection string value should be quoted

### Beschreibung

function odbc_connection_string_should_quote(string `$str`): bool

Determines if a string needs to be quoted for an ODBC connection string value; that is, if it contains special characters.

Note that this does not check if the string is already quoted; an already quoted string will contain characters that will make this function return true. You should call odbc_connection_string_is_quoted() to check.

### Parameter-Liste

`str`

  The string to check for.

### Rückgabewerte

`true` if the string should be quoted; `false` otherwise.

### Siehe auch

- odbc_connection_string_quote() - Quotes an ODBC connection string value
- odbc_connection_string_is_quoted() - Determines if an ODBC connection string value is quoted

# odbc_cursor

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_cursor — Liefert den Cursornamen

### Beschreibung

function odbc_cursor(Odbc\Result `$statement`): string|false

Liefert den Cursornamen für die gegebene Ergebniskennung `result_id` zurück.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

### Rückgabewerte

Gibt den Cursornamen als Zeichenkette zurück. Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

# odbc_data_source

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

odbc_data_source — Returns information about available DSNs

### Beschreibung

function odbc_data_source(Odbc\Connection `$odbc`, int `$fetch_type`): array|null|false

This function will return the list of available DSN (after calling it several times).

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`fetch_type`

  The `fetch_type` can be one of two constant types: `SQL_FETCH_FIRST`, `SQL_FETCH_NEXT`. Use `SQL_FETCH_FIRST` the first time this function is called, thereafter use the `SQL_FETCH_NEXT`.

### Rückgabewerte

Returns `false` on error, an Array upon success, and `null` after fetching the last available DSN.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 List available DSNs

    <?php
    $conn = odbc_connect('dsn', 'user', 'pass');
    $dsn_info = odbc_data_source($conn, SQL_FETCH_FIRST);
    while ($dsn_info) {
        print_r($dsn_info);
        $dsn_info = odbc_data_source($conn, SQL_FETCH_NEXT);
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [server] => dsn
        [description] => ODBC Driver 17 for SQL Server
    )
    Array
    (
        [server] => other_dsn
        [description] => Microsoft Access Driver (*.mdb, *.accdb)
    )

# odbc_do

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_do — Alias von odbc_exec()

### Beschreibung

Diese Funktion ist ein Alias für: odbc_exec().

# odbc_error

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_error — Get the last error code

### Beschreibung

function odbc_error(?Odbc\Connection `$odbc` = `null`): string

Returns a six-digit ODBC state, or an empty string if there has been no errors.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

### Rückgabewerte

If `odbc` is specified, the last state of that connection is returned, else the last state of any connection is returned.

This function returns meaningful value only if last odbc query failed (i.e. odbc_exec() returned `false`).

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.0.0 | `odbc` is now nullable.

### Siehe auch

- odbc_errormsg() - Get the last error message
- odbc_exec() - Führt einen SQL-Befehl direkt aus

# odbc_errormsg

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_errormsg — Get the last error message

### Beschreibung

function odbc_errormsg(?Odbc\Connection `$odbc` = `null`): string

Returns a string containing the last ODBC error message, or an empty string if there has been no errors.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

### Rückgabewerte

If `odbc` is specified, the last state of that connection is returned, else the last state of any connection is returned.

This function returns meaningful value only if last odbc query failed (i.e. odbc_exec() returned `false`).

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.0.0 | `odbc` is now nullable.

### Siehe auch

- odbc_error() - Get the last error code
- odbc_exec() - Führt einen SQL-Befehl direkt aus

# odbc_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_exec — Führt einen SQL-Befehl direkt aus

### Beschreibung

function odbc_exec(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Sendet eine SQL-Anweisung an den Datenbankserver.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`query`

  Die SQL-Anweisung.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurück, wenn das SQL-Kommando erfolgreich ausgeführt wurde, oder `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.
8.0.0 | `flags` wurde entfernt.

### Siehe auch

- odbc_prepare() - Bereitet eine Anweisung für die Ausführung vor
- odbc_execute() - Führt einen vorbereiteten SQL-Befehl aus

# odbc_execute

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_execute — Führt einen vorbereiteten SQL-Befehl aus

### Beschreibung

function odbc_execute(Odbc\Result `$statement`, array `$params` = []): bool

Führt eine mit odbc_prepare() vorbereitete Anweisung aus.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt von odbc_prepare().

`params`

  Parameter in `params` werden für Platzhalter in der vorbereiteten Anweisung in der Reihenfolge ihres Vorkommens eingesetzt. Elemente dieses Array werden zu Zeichenketten konvertiert, wenn diese Funktion aufgerufen wird.

  Jegliche Parameter in `params`, die mit einfachen Anführungszeichen beginnen und enden, werden als Name einer Datei interpretiert, die gelesen und als Daten für den entsprechenden Platzhalter an den Server gesendet werden.

  Soll eine Zeichenkette, die tatsächlich mit einfachen Anführungszeichen beginnt und endet übergeben werden, muss ein Leerzeichen oder ein anderes Zeichen, das kein einfaches Anführungszeichen ist, am Anfang oder Ende der Zeichenkette eingefügt werden, was verhindert, dass der Parameter als Dateiname interpretiert wird. Ist dies keine Option, dann muss ein anderer Mechanismus verwendet werden, um die Zeichenkette zu übergeben, wie z. B. die Abfrage direkt per odbc_exec() auszuführen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.
8.0.0 | Der nicht verwendete Parameter `flags` wurde entfernt.

### Beispiele

Beispiel #1 Beispiel für odbc_execute() und odbc_prepare()

Im folgenden Code ist $success nur dann `true`, wenn alle drei Parameter für myproc Eingabeparameter (IN) sind:

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $success = odbc_execute($stmt, array($a, $b, $c));
    ?>

Wenn eine gespeicherte Prozedur aufgerufen werden soll, die Ein-Ausgabe- (INOUT) oder Ausgabeparameter (OUT) verwendet, wird als Workaround empfohlen, eine native Extension für die jeweilige Datenbank zu verwenden (beispielsweise oci8 für Oracle).

### Siehe auch

- odbc_prepare() - Bereitet eine Anweisung für die Ausführung vor

# odbc_fetch_array

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_array — Fetch a result row as an associative array

### Beschreibung

function odbc_fetch_array(Odbc\Result `$statement`, ?int `$row` = `null`): array|false

Fetch an associative array from an ODBC query.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt from odbc_exec().

`row`

  Optionally choose which row number to retrieve.

### Rückgabewerte

Returns an array that corresponds to the fetched row, or `false` if there are no more rows.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.
8.4.0 | `row` is now nullable.

### Anmerkungen

> Hinweis: This function exists when compiled with DBMaker, IBM DB2 or UnixODBC support.

### Siehe auch

- odbc_fetch_row() - Liefert eine Zeile zurück
- odbc_fetch_object() - Fetch a result row as an object
- odbc_num_rows() - Liefert die Zeilenzahl des Abfrageergebnisses

# odbc_fetch_into

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_into — Liest eine Ergebniszeile in ein Array

### Beschreibung

function odbc_fetch_into(Odbc\Result `$statement`, array `&$array`, ?int `$row` = `null`): int|false

Liest eine Ergebniszeile in ein Array.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`array`

  Das Array, welches das Ergebnis aufnehmen soll. Hier kann ein beliebiger Typ übergeben werden, da dies in ein Array konvertiert wird. Das Array wird die Werte der einzelnen Spalten ab der Arrayposition 0 enthalten.

`row`

  Die Zeilennummer.

### Rückgabewerte

Gibt die Anzahl der Spalten im Ergebnis zurück, `false` bei einem Fehler.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.
8.4.0 | `row` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 odbc_fetch_into()-Beispiele

    <?php
    $rc = odbc_fetch_into($res_id, $my_array);
    ?>

oder

    <?php
    $rc = odbc_fetch_into($res_id, $my_array, 2);
    ?>

# odbc_fetch_object

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_object — Fetch a result row as an object

### Beschreibung

function odbc_fetch_object(Odbc\Result `$statement`, ?int `$row` = `null`): stdClass|false

Fetch an object from an ODBC query.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt from odbc_exec().

`row`

  Optionally choose which row number to retrieve.

### Rückgabewerte

Returns an object that corresponds to the fetched row, or `false` if there are no more rows.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.
8.4.0 | `row` is now nullable.

### Anmerkungen

> Hinweis: This function exists when compiled with DBMaker, IBM DB2 or UnixODBC support.

### Siehe auch

- odbc_fetch_row() - Liefert eine Zeile zurück
- odbc_fetch_array() - Fetch a result row as an associative array
- odbc_num_rows() - Liefert die Zeilenzahl des Abfrageergebnisses

# odbc_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_row — Liefert eine Zeile zurück

### Beschreibung

function odbc_fetch_row(Odbc\Result `$statement`, ?int `$row` = `null`): bool

Stellt eine Zeile der von odbc_do() oder odbc_exec() zurückgegeben Daten bereit. Nachdem odbc_fetch_row() aufgerufen wurde, können die Felder dieser Zeile mit odbc_result() genutzt werden.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`row`

  Wenn `row` nicht definiert ist, versucht odbc_fetch_row() die nächste Zeile aus der Ergebnismenge zu holen. odbc_fetch_row() kann abwechselnd ohne und mit dem Parameter `row` genutzt werden.

  Um ein Abfrageergebnis mehrfach zu durchlaufen, kann odbc_fetch_row() mit `row` gleich 1 aufgerufen werden, um dann wie gewohnt mit odbc_fetch_row() ohne `row` fortzufahren. Wenn der ODBC-Treiber das Lesen von Zeilen nach Zeilennummer nicht unterstützt, wird der Parameter `row` ignoriert.

### Rückgabewerte

Gibt `true` zurück, wenn eine Zeile gelesen wurde, und `false` anderfalls.

### Fehler/Exceptions

Wenn `row` gleich oder kleiner Null ist, wird ein `E_WARNING` ausgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.
8.4.0 | Wenn `row` gleich oder kleiner Null ist, wird ein `E_WARNING` ausgegeben.
8.0.0 | `row` ist jetzt ein Nullable-Typ.

# odbc_field_len

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_len — Bestimmt die Länge (Präzision) eines Feldes

### Beschreibung

function odbc_field_len(Odbc\Result `$statement`, int `$field`): int|false

Gibt die Länge eines durch eine Feldnummer angegebenen Feldes in der angegebenen Ergebniskennung zurück.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`field`

  Die Feldnummer, wobei die Nummerierung mit 1 beginnt.

### Rückgabewerte

Gibt die Feldlänge zurück, oder `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

### Siehe auch

- odbc_field_scale() - Get the scale of a field, um die Dezimalstellen einer Gleitkommazahl zu erhalten

# odbc_field_name

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_name — Liefert den Spaltennamen

### Beschreibung

function odbc_field_name(Odbc\Result `$statement`, int `$field`): string|false

Liefert den Namen der Spalte, die die angegebe Spaltennummer im angegebenen Ergebnis-Objekt belegt.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`field`

  Die Feldnummer, wobei die Nummerierung mit 1 beginnt.

### Rückgabewerte

Gibt den Feldnamen als Zeichenkette zurück, oder `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

# odbc_field_num

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_num — Liefert die Spaltennummer

### Beschreibung

function odbc_field_num(Odbc\Result `$statement`, string `$field`): int|false

Liefert die Spaltennummer, die zum benannten Feld im angegebenen Ergebnis-Objekt gehört.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`field`

  Der Feldname.

### Rückgabewerte

Gibt die Feldnummer als Ganzzahl zurück, oder `false` im Fehlerfall. Die Feld-Nummerierung beginnt mit 1.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

# odbc_field_precision

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_precision — Alias von odbc_field_len()

### Beschreibung

Diese Funktion ist ein Alias für: odbc_field_len().

### Siehe auch

- odbc_field_scale() - Get the scale of a field to get the scale of a floating point number.

# odbc_field_scale

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_scale — Get the scale of a field

### Beschreibung

function odbc_field_scale(Odbc\Result `$statement`, int `$field`): int|false

Gets the scale of the field referenced by number in the given result identifier.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`field`

  The field number. Field numbering starts at 1.

### Rückgabewerte

Returns the field scale as an integer, or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

# odbc_field_type

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_type — Datentyp eines Feldes

### Beschreibung

function odbc_field_type(Odbc\Result `$statement`, int `$field`): string|false

Liefert den SQL-Datentypen des Feldes, das in der angegeben Ergebniskennung numerisch referenziert wird.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`field`

  Die Feldnummer. Die Nummerierung beginnt mit 1.

### Rückgabewerte

Gibt den Feldtyp als Zeichenkette zurück, oder `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

# odbc_foreignkeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_foreignkeys — Retrieves a list of foreign keys

### Beschreibung

function odbc_foreignkeys(
Odbc\Connection `$odbc`,
?string `$pk_catalog`,
string `$pk_schema`,
string `$pk_table`,
string `$fk_catalog`,
string `$fk_schema`,
string `$fk_table`
): Odbc\Result|false

Retrieves a list of foreign keys in the specified table or a list of foreign keys in other tables that refer to the primary key in the specified table

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`pk_catalog`

  The catalog ('qualifier' in ODBC 2 parlance) of the primary key table.

`pk_schema`

  The schema ('owner' in ODBC 2 parlance) of the primary key table.

`pk_table`

  The primary key table.

`fk_catalog`

  The catalog ('qualifier' in ODBC 2 parlance) of the foreign key table.

`fk_schema`

  The schema ('owner' in ODBC 2 parlance) of the foreign key table.

`fk_table`

  The foreign key table.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurückBei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- `PKTABLE_CAT`
- `PKTABLE_SCHEM`
- `PKTABLE_NAME`
- `PKCOLUMN_NAME`
- `FKTABLE_CAT`
- `FKTABLE_SCHEM`
- `FKTABLE_NAME`
- `FKCOLUMN_NAME`
- `KEY_SEQ`
- `UPDATE_RULE`
- `DELETE_RULE`
- `FK_NAME`
- `PK_NAME`
- `DEFERRABILITY`

Treiber können zusätzliche Spalten melden.

If the foreign keys associated with a primary key are requested, the result set is ordered by `FKTABLE_CAT`, `FKTABLE_SCHEM`, `FKTABLE_NAME` and `KEY_SEQ`. If the primary keys associated with a foreign key are requested, the result set is ordered by `PKTABLE_CAT`, `PKTABLE_SCHEM`, `PKTABLE_NAME` and `KEY_SEQ`.

If `pk_table` contains a table name, odbc_foreignkeys() returns a result set containing the primary key of the specified table and all of the foreign keys that refer to it.

If `fk_table` contains a table name, odbc_foreignkeys() returns a result set containing all of the foreign keys in the specified table and the primary keys (in other tables) to which they refer.

If both `pk_table` and `fk_table` contain table names, odbc_foreignkeys() returns the foreign keys in the table specified in `fk_table` that refer to the primary key of the table specified in `pk_table`. This should be one key at most.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.

### Siehe auch

- odbc_tables() - Get the list of table names stored in a specific data source
- odbc_primarykeys() - Gets the primary keys for a table

# odbc_free_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_free_result — Gibt die mit einem Ergebnis verbundenen Objekte frei

### Beschreibung

function odbc_free_result(Odbc\Result `$statement`): true

Gibt die mit einem Ergebnis verbundenen Objekte frei.

odbc_free_result() braucht nur aufgerufen zu werden, wenn Sie einen zu hohen Speicherverbrauch durch das aktuell laufende Skript vermeiden wollen. Das gesamte Abfrageergebnis wird automatisch nach Beendigung des Skriptes gelöscht.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

### Anmerkungen

> Hinweis:

> Wird odbc_free_result() bei deaktiviertem autocommit (siehe odbc_autocommit()) aufgerufen, bevor die Transaktion abgeschlossen wurde, werden alle austehenden Transaktionen zurückgenommen.

# odbc_gettypeinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_gettypeinfo — Retrieves information about data types supported by the data source

### Beschreibung

function odbc_gettypeinfo(Odbc\Connection `$odbc`, int `$data_type` = 0): Odbc\Result|false

Retrieves information about data types supported by the data source.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`data_type`

  The data type, which can be used to restrict the information to a single data type.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurückBei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- TYPE_NAME
- DATA_TYPE
- PRECISION
- LITERAL_PREFIX
- LITERAL_SUFFIX
- CREATE_PARAMS
- NULLABLE
- CASE_SENSITIVE
- SEARCHABLE
- UNSIGNED_ATTRIBUTE
- MONEY
- AUTO_INCREMENT
- LOCAL_TYPE_NAME
- MINIMUM_SCALE
- MAXIMUM_SCALE

The result set is ordered by DATA_TYPE and TYPE_NAME.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.

# odbc_longreadlen

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_longreadlen — Steuert die Behandlung von LONG-Spalten

### Beschreibung

function odbc_longreadlen(Odbc\Result `$statement`, int `$length`): true

Steuert die Behandlung von `LONG`- und `LONGVARCHAR`-Spalten. Die Standardlänge kann mit der php.ini-Anweisung uodbc.defaultlrl festgelegt werden.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`length`

  Die Anzahl von Bytes, die an PHP zurückgegeben werden, wird durch den Parameter length gesteuert. Ist er auf `0` gesetzt, werden die Daten von Long-Spalten an den Client durchgeschleift, d. h. ausgegeben, wenn sie mit odbc_result() abgerufen werden.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

### Anmerkungen

> Hinweis:

> Die Behandlung von `LONGVARBINARY`-Spalten wird auch durch odbc_binmode() beeinflusst.

# odbc_next_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_next_result — Checks if multiple results are available

### Beschreibung

function odbc_next_result(Odbc\Result `$statement`): bool

Checks if there are more result sets available as well as allowing access to the next result set via odbc_fetch_array(), odbc_fetch_row(), odbc_result(), etc.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

### Rückgabewerte

Returns `true` if there are more result sets, `false` otherwise.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 odbc_next_result()

    <?php
    $r_Connection = odbc_connect($dsn, $username, $password);

    $s_SQL = <<<END_SQL
    SELECT 'A'
    SELECT 'B'
    SELECT 'C'
    END_SQL;

    $r_Results = odbc_exec($r_Connection, $s_SQL);

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Dump first result set";
    var_dump($a_Row1, $a_Row2);

    echo "Get second results set ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Dump second result set ";
    var_dump($a_Row1, $a_Row2);

    echo "Get third results set ";
    var_dump(odbc_next_result($r_Results));

    $a_Row1 = odbc_fetch_array($r_Results);
    $a_Row2 = odbc_fetch_array($r_Results);
    echo "Dump third result set ";
    var_dump($a_Row1, $a_Row2);

    echo "Try for a fourth result set ";
    var_dump(odbc_next_result($r_Results));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Dump first result set array(1) {
      ["A"]=>
      string(1) "A"
    }
    bool(false)
    Get second results set bool(true)
    Dump second result set array(1) {
      ["B"]=>
      string(1) "B"
    }
    bool(false)
    Get third results set bool(true)
    Dump third result set array(1) {
      ["C"]=>
      string(1) "C"
    }
    bool(false)
    Try for a fourth result set bool(false)

# odbc_num_fields

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_fields — Liefert die Anzahl der Ergebnisspalten

### Beschreibung

function odbc_num_fields(Odbc\Result `$statement`): int

Liefert die Anzahl von Feldern (Spalten) in einem ODBC-Ergebnis.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt, das von odbc_exec() zurückgegeben wurde.

### Rückgabewerte

Gibt die Anzahl der Felder zurück, oder -1 im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

# odbc_num_rows

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_rows — Liefert die Zeilenzahl des Abfrageergebnisses

### Beschreibung

function odbc_num_rows(Odbc\Result `$statement`): int

Liefert die Anzahl der Zeilen eines Ergebnisses. Bei INSERT, UPDATE und DELETE-Anweisungen gibt odbc_num_rows() die Zahl der betroffenen Zeilen zurück. Bei einer SELECT-Abfrage kann dies die Anzahl der vorhanden Zeilen sein.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt, das von odbc_exec() zurückgegeben wurde.

### Rückgabewerte

Gibt die Anzahl der Zeilen in einem ODBC-Ergebnis zurück. Diese Funktion gibt im Fehlerfall -1 zurück.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

### Anmerkungen

> Hinweis:

> Die Verwendung von odbc_num_rows(), um die Anzahl der verfügbaren Zeilen nach einem SELECT zu ermittelnt, wird bei vielen Treibern -1 liefern.

# odbc_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_pconnect — Öffnet eine persistente Datenbankverbindung

### Beschreibung

function odbc_pconnect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

Öffnet eine persistente Datenbankverbindung.

Diese Funktion ist odbc_connect() sehr ähnlich. Der einzige Unterschied besteht darin, dass die Verbindung nach dem Ende des Skriptes erhalten bleibt. Folgende Verbindungen mit gleicher `dsn`, `user` und `password`-Kombination (über odbc_connect() und odbc_pconnect()) können dann die bestehende Verbindung weiterbenutzen.

### Parameter-Liste

Details können der odbc_connect()-Dokumentation entnommen werden.

### Rückgabewerte

Gibt eine ODBC-Verbindungskennung zurück. Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Connection zurück; vorher wurde eine Ressource zurückgegeben.
8.4.0 | `user` und `password` sind nun nullable (akzeptieren den `null`-Wert); sie sind nun auch optional und standardmäßig auf `null` gesetzt.
8.4.0 | Bisher wurde bei der Verwendung einer leeren Zeichenkette für `password` `pwd` nicht in die generierte Verbindungszeichenkette für `dsn` aufgenommen. Jetzt wird ein `pwd` mit einer leeren Zeichenkette als Wert erzeugt. Um das vorherige Verhalten wiederherzustellen, kann `password` nun auf `null` gesetzt werden.
8.4.0 | Wenn `dsn` `uid` oder `pwd` enthielt, wurden bisher die Parameter `user` und `password` ignoriert. Jetzt wird `user` nur ignoriert, wenn `dsn` `uid` enthält, und `password` wird nur ignoriert, wenn `dsn` `pwd` enthält.

### Anmerkungen

> Hinweis: Persistente Verbindungen wirken nicht, wenn PHP als CGI-Programm verwendet wird.

### Siehe auch

- odbc_connect() - Verbindet mit einer Datenquelle
- Persistente Datenbankverbindungen

# odbc_prepare

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_prepare — Bereitet eine Anweisung für die Ausführung vor

### Beschreibung

function odbc_prepare(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

Bereitet eine Anweisung für die Ausführung vor. Das Das ODBC-Ergebnis-Objekt kann später verwendet werden, um die Anweisung mit odbc_execute() auszuführen.

Einige Datenbanken (wie beispielsweise IBM DB2, MS SQL Server und Oracle) unterstützen gespeicherte Prozeduren, die Parameter vom Typ IN, INOUT und OUT akzeptieren können, wie von der ODBC-Spezifikation definiert. Allerdings unterstützt der Unified-ODBC-Treiber zurzeit nur Parameter vom Typ IN für gespeicherte Prozeduren.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`query`

  Die Abfrage-Anweisung, die vorbereitet werden soll, als Zeichenkette.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurück, wenn das SQL-Kommando erfolgreich vorbereitet wurde. Im Fehlerfall wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 Beispiel für odbc_execute() und odbc_prepare()

Im folgenden Code ist $success nur dann `true`, wenn alle drei Parameter für myproc Eingabeparameter (IN) sind:

    <?php
    $a = 1;
    $b = 2;
    $c = 3;
    $stmt    = odbc_prepare($conn, 'CALL myproc(?,?,?)');
    $success = odbc_execute($stmt, array($a, $b, $c));
    ?>

Wenn eine gespeicherte Prozedur aufgerufen werden soll, die Ein-Ausgabe- (INOUT) oder Ausgabeparameter (OUT) verwendet, wird als Workaround empfohlen, eine native Erweiterung für die jeweilige Datenbank zu verwenden (beispielsweise oci8 für Oracle).

### Siehe auch

- odbc_execute() - Führt einen vorbereiteten SQL-Befehl aus

# odbc_primarykeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_primarykeys — Gets the primary keys for a table

### Beschreibung

function odbc_primarykeys(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Returns a result object that can be used to fetch the column names that comprise the primary key for a table.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`catalog`

  Der Katalog ('Kennzeichner' in ODBC 2 Terminologie).

`schema`

  Das Schema ('Besitzer' in ODBC 2 Terminologie).

`table`

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurückBei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `KEY_SEQ`
- `PK_NAME`

Treiber können zusätzliche Spalten melden.

The result set is ordered by `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` and `KEY_SEQ`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 List primary Keys of a Column

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $primarykeys = odbc_primarykeys($conn, 'TutorialDB', 'dbo', 'TEST');
    while (($row = odbc_fetch_array($primarykeys))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [COLUMN_NAME] => id
        [KEY_SEQ] => 1
        [PK_NAME] => PK__TEST__3213E83FE141F843
    )

### Siehe auch

- odbc_tables() - Get the list of table names stored in a specific data source
- odbc_foreignkeys() - Retrieves a list of foreign keys

# odbc_procedurecolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedurecolumns — Retrieve information about parameters to procedures

### Beschreibung

function odbc_procedurecolumns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`,
?string `$column` = `null`
): Odbc\Result|false

Retrieve information about parameters to procedures.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`catalog`

  Der Katalog ('Kennzeichner' in ODBC 2 Terminologie).

`schema`

  Das Schema ('Besitzer' in ODBC 2 Terminologie). Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`procedure`

  The proc. Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`column`

  The column. Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

### Rückgabewerte

Returns the list of input and output parameters, as well as the columns that make up the result set for the specified procedures. Gibt ein ODBC-Ergebnis-Objekt zurückBei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `COLUMN_NAME`
- `COLUMN_TYPE`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `NUM_PREC_RADIX`
- `NULLABLE`
- `REMARKS`
- `COLUMN_DEF`
- `SQL_DATA_TYPE`
- `SQL_DATETIME_SUB`
- `CHAR_OCTET_LENGTH`
- `ORDINAL_POSITION`
- `IS_NULLABLE`

Treiber können zusätzliche Spalten melden.

The result set is ordered by `PROCEDURE_CAT`, `PROCEDURE_SCHEM`, `PROCEDURE_NAME` and `COLUMN_TYPE`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.
8.0.0 | Prior to this version, the function could only be called with either one or five arguments.

### Beispiele

Beispiel #1 List Columns of a stored Procedure

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $columns = odbc_procedurecolumns($conn, 'TutorialDB', 'dbo', 'GetEmployeeSalesYTD;1', '%');
    while (($row = odbc_fetch_array($columns))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [COLUMN_NAME] => @SalesPerson
        [COLUMN_TYPE] => 1
        [DATA_TYPE] => -9
        [TYPE_NAME] => nvarchar
        [COLUMN_SIZE] => 50
        [BUFFER_LENGTH] => 100
        [DECIMAL_DIGITS] =>
        [NUM_PREC_RADIX] =>
        [NULLABLE] => 1
        [REMARKS] =>
        [COLUMN_DEF] =>
        [SQL_DATA_TYPE] => -9
        [SQL_DATETIME_SUB] =>
        [CHAR_OCTET_LENGTH] => 100
        [ORDINAL_POSITION] => 1
        [IS_NULLABLE] => YES
    )

### Siehe auch

- odbc_columns() - Lists the column names in specified tables

# odbc_procedures

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedures — Get the list of procedures stored in a specific data source

### Beschreibung

function odbc_procedures(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`
): Odbc\Result|false

Lists all procedures in the requested range.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`catalog`

  Der Katalog ('Kennzeichner' in ODBC 2 Terminologie).

`schema`

  Das Schema ('Besitzer' in ODBC 2 Terminologie). Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`procedure`

  The name. Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurück containing the informationBei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- `PROCEDURE_CAT`
- `PROCEDURE_SCHEM`
- `PROCEDURE_NAME`
- `NUM_INPUT_PARAMS`
- `NUM_OUTPUT_PARAMS`
- `NUM_RESULT_SETS`
- `REMARKS`
- `PROCEDURE_TYPE`

Treiber können zusätzliche Spalten melden.

The result set is ordered by `PROCEDURE_CAT`, `PROCEDURE_SCHEMA` and `PROCEDURE_NAME`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.
8.0.0 | Prior to this version, the function could only be called with either one or four arguments.

### Beispiele

Beispiel #1 List stored Procedures of a Database

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $procedures = odbc_procedures($conn, $catalog, $schema, '%');
    while (($row = odbc_fetch_array($procedures))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [PROCEDURE_CAT] => TutorialDB
        [PROCEDURE_SCHEM] => dbo
        [PROCEDURE_NAME] => GetEmployeeSalesYTD;1
        [NUM_INPUT_PARAMS] => -1
        [NUM_OUTPUT_PARAMS] => -1
        [NUM_RESULT_SETS] => -1
        [REMARKS] =>
        [PROCEDURE_TYPE] => 2
    )

### Siehe auch

- odbc_procedurecolumns() - Retrieve information about parameters to procedures
- odbc_tables() - Get the list of table names stored in a specific data source

# odbc_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result — Liefert Ergebnisdaten

### Beschreibung

function odbc_result(Odbc\Result `$statement`, string|int `$field`): string|bool|null

Liefert Ergebnisdaten.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`field`

  Der Name des zu lesenden Feldes. Dies kann entweder eine Ganzzahl sein, die der Spaltennummer des Feldes entspricht, oder eine Zeichenkette, die den Namen des Feldes enthält.

### Rückgabewerte

Gibt den Zeichenketteninhalt des Feldes zurück, `false` im Fehlerfall, `null` bei NULL-Werten, oder `true` bei binären Daten.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.

### Beispiele

Der erste Aufruf von odbc_result() liefert den Wert des drittes Feldes im aktuellen Datensatz des Abfrageergebnisses zurück. Der zweite Funktionsaufruf von odbc_result() gibt den Wert der Spalte "wert" im aktuellen Datensatz zurück. Wenn die Spaltennummer kleiner als 1 oder größer als die Spaltenzahl ist, tritt ein Fehler auf. Gleiches gilt für einen Spaltennamen, der im Abfrageergebnis nicht vorkommt.

Beispiel #1 odbc_result()-Beispiele

    <?php
    $item_3   = odbc_result($Query_ID, 3);
    $item_val = odbc_result($Query_ID, "wert");
    ?>

### Anmerkungen

Feldindizes beginnen bei 1. Wie Binär- oder Long-Spaltendaten zurückgegeben werden, kann der odbc_binmode()- und odbc_longreadlen()-Dokumentation entnommen werden.

# odbc_result_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result_all — Gibt das aktuelle Abfrageergebnis als HTML-Tabelle aus

Warnung

Diese Funktion ist seit PHP 8.1.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function odbc_result_all(Odbc\Result `$statement`, string `$format` = ""): int|false

Gibt alle Zeilen eines Ergebnis-Objetks aus, das von odbc_exec() erstellt wurde. Das Ergebnis ist als HTML-Tabelle formatiert. Die Daten werden nicht maskiert.

Diese Funktion ist nicht für den Einsatz in Produktionsumgebungen gedacht; sie ist lediglich für Entwicklungszwecke gedacht, um schnell eine Ergebnisliste anzuzeigen.

### Parameter-Liste

`statement`

  Das ODBC-Ergebnis-Objekt.

`format`

  Zusätzliche allgemeine Tabellenformatierung.

### Rückgabewerte

Gibt die Anzahl der Zeilen in einem Ergebnis zurück oder `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `statement` erwartet nun eine Instanz von Odbc\Result; vorher wurde eine Ressource erwartet.
8.1.0 | Diese Funktion ist veraltet.

# odbc_rollback

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_rollback — Bricht eine Transaktion ab

### Beschreibung

function odbc_rollback(Odbc\Connection `$odbc`): bool

Bricht alle ausstehenden Transaktion der Verbindung ab.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.

# odbc_setoption

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_setoption — ODBC-Einstellungen anpassen

### Beschreibung

function odbc_setoption(
Odbc\Connection|Odbc\Result `$odbc`,
int `$which`,
int `$option`,
int `$value`
): bool

Diese Funktion erlaubt das Einstellen der ODBC-Optionen für eine einzelne Verbindung oder ein Abfrageergebnis. Sie soll beim Auffinden und Beheben von Problemen mit ODBC-Treibern helfen. Es empfiehlt sich, diese Funktion nur zu nutzen, wenn man einige Erfahrung mit ODBC-Programmierung gesammelt hat und die Wirkungen der einzelnen Parameter kennt. Es wird sicherlich nötig sein, eine gute ODBC-Referenz zur Hand zu haben, um all die unterschiedlichen Optionen und Werte, die verwendet werden können, zu erklären. Unterschiedliche Treiberversionen unterstützen unterschiedliche Optionen.

Weil die Effekte je nach ODBC-Treiber unterschiedlich sein können, wird unbedingt davon abgeraten, Skripte mit dieser Funktion zu veröffentlichen. Einige ODBC-Optionen stehen dieser Funktion nicht zur Verfügung, weil sie vor dem Aufbau einer ODBC-Verbindung oder vor der Vorbereitung der Abfrage eingestellt sein müssen. In einigen Fällen hilft diese Funktion allerdings zu vermeiden, dass man von seinem Vorgesetzten gezwungen wird, ein kommerzielles Programm einzusetzen - und darauf kommt es doch an.

### Parameter-Liste

`odbc`

  Ist die Verbindungs- oder Ergebniskennung, deren Einstellungen geändert werden sollen. Bei SQLSetConnectOption() ist es eine Verbindungskennung, bei SQLSetStmtOption() eine Ergebniskennung.

`which`

  Ist die ODBC-Funktion, die genutzt werden soll. Die Werte sind 1 für SQLSetConnectOption() und 2 für SQLSetStmtOption().

`option`

  Die zu ändernde Option.

`value`

  Der Wert für die angegebene `option`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection oder Odbc\Result; zuvor wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 odbc_setoption()-Beispiele

    <?php
    // 1. Option 102 von SQLSetConnectOption() ist SQL_AUTOCOMMIT.
    //    Wert 1 für SQL_AUTOCOMMIT entspricht SQL_AUTOCOMMIT_ON.
    //    Dieses Beispiel hat denselben Effekt wie
    //    odbc_autocommit($conn, true);

    odbc_setoption($conn, 1, 102, 1);

    // 2. Option 0 von SQLSetStmtOption() ist SQL_QUERY_TIMEOUT.
    //    Dieses Beispiel setzt den Timeout auf 30 Sekunden.

    $result = odbc_prepare($conn, $sql);
    odbc_setoption($result, 2, 0, 30);
    odbc_execute($result);
    ?>

# odbc_specialcolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_specialcolumns — Retrieves special columns

### Beschreibung

function odbc_specialcolumns(
Odbc\Connection `$odbc`,
int `$type`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$scope`,
int `$nullable`
): Odbc\Result|false

Retrieves either the optimal set of columns that uniquely identifies a row in the table, or columns that are automatically updated when any value in the row is updated by a transaction.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`type`
  When the type argument is `SQL_BEST_ROWID`, odbc_specialcolumns() returns the column or columns that uniquely identify each row in the table. When the type argument is `SQL_ROWVER`, odbc_specialcolumns() returns the column or columns in the specified table, if any, that are automatically updated by the data source when any value in the row is updated by any transaction.
`catalog`

  Der Katalog ('Kennzeichner' in ODBC 2 Terminologie).

`schema`

  Das Schema ('Besitzer' in ODBC 2 Terminologie).

`table`

  The table.

`scope`

  The scope, which orders the result set. One of `SQL_SCOPE_CURROW`, `SQL_SCOPE_TRANSACTION` or `SQL_SCOPE_SESSION`.

`nullable`

  Determines whether to return special columns that can have a NULL value. One of `SQL_NO_NULLS` or `SQL_NULLABLE`.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurückBei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- `SCOPE`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `PSEUDO_COLUMN`

Treiber können zusätzliche Spalten melden.

The result set is ordered by `SCOPE`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.

### Siehe auch

- odbc_tables() - Get the list of table names stored in a specific data source

# odbc_statistics

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_statistics — Retrieve statistics about a table

### Beschreibung

function odbc_statistics(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$unique`,
int `$accuracy`
): Odbc\Result|false

Get statistics about a table and its indexes.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`catalog`

  Der Katalog ('Kennzeichner' in ODBC 2 Terminologie).

`schema`

  Das Schema ('Besitzer' in ODBC 2 Terminologie).

`table`

  The table name.

`unique`

  The type of the index. One of `SQL_INDEX_UNIQUE` or `SQL_INDEX_ALL`.

`accuracy`

  One of `SQL_ENSURE` or `SQL_QUICK`. The latter requests that the driver retrieve the `CARDINALITY` and `PAGES` only if they are readily available from the server.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurückBei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `NON_UNIQUE`
- `INDEX_QUALIFIER`
- `INDEX_NAME`
- `TYPE`
- `ORDINAL_POSITION`
- `COLUMN_NAME`
- `ASC_OR_DESC`
- `CARDINALITY`
- `PAGES`
- `FILTER_CONDITION`

Treiber können zusätzliche Spalten melden.

The result set is ordered by `NON_UNIQUE`, `TYPE`, `INDEX_QUALIFIER`, `INDEX_NAME` and `ORDINAL_POSITION`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 List Statistics of a Table

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $statistics = odbc_statistics($conn, 'TutorialDB', 'dbo', 'TEST', SQL_INDEX_UNIQUE, SQL_QUICK);
    while (($row = odbc_fetch_array($statistics))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [TABLE_CAT] => TutorialDB
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => TEST
        [NON_UNIQUE] =>
        [INDEX_QUALIFIER] =>
        [INDEX_NAME] =>
        [TYPE] => 0
        [ORDINAL_POSITION] =>
        [COLUMN_NAME] =>
        [ASC_OR_DESC] =>
        [CARDINALITY] => 15
        [PAGES] => 3
        [FILTER_CONDITION] =>
    )

### Siehe auch

- odbc_tables() - Get the list of table names stored in a specific data source

# odbc_tableprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tableprivileges — Lists tables and the privileges associated with each table

### Beschreibung

function odbc_tableprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

Lists tables in the requested range and the privileges associated with each table.

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`catalog`

  Der Katalog ('Kennzeichner' in ODBC 2 Terminologie).

`schema`

  Das Schema ('Besitzer' in ODBC 2 Terminologie). Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`table`

  The name. Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurückBei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

Treiber können zusätzliche Spalten melden.

The result set is ordered by `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `PRIVILEGE` and `GRANTEE`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 List Privileges of a Table

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $privileges = odbc_tableprivileges($conn, 'SalesOrders', 'dbo', 'Orders');
    while (($row = odbc_fetch_array($privileges))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [GRANTOR] => dbo
        [GRANTEE] => dbo
        [PRIVILEGE] => DELETE
        [IS_GRANTABLE] => YES
    )

### Siehe auch

- odbc_tables() - Get the list of table names stored in a specific data source

# odbc_tables

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tables — Get the list of table names stored in a specific data source

### Beschreibung

function odbc_tables(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$types` = `null`
): Odbc\Result|false

Lists all tables in the requested range.

To support enumeration of qualifiers, owners, and table types, the following special semantics for the `catalog`, `schema`, `table`, and `table_type` are available:

- If `catalog` is a single percent character (%) and `schema` and `table` are empty strings, then the result set contains a list of valid qualifiers for the data source. (All columns except the TABLE_QUALIFIER column contain NULLs.)
- If `schema` is a single percent character (%) and `catalog` and `table` are empty strings, then the result set contains a list of valid owners for the data source. (All columns except the TABLE_OWNER column contain NULLs.)
- If `table_type` is a single percent character (%) and `catalog`, `schema` and `table` are empty strings, then the result set contains a list of valid table types for the data source. (All columns except the TABLE_TYPE column contain NULLs.)

### Parameter-Liste

`odbc`

  Das ODBC-Verbindungs-Objekt, siehe odbc_connect() für Details.

`catalog`

  Der Katalog ('Kennzeichner' in ODBC 2 Terminologie).

`schema`

  Das Schema ('Besitzer' in ODBC 2 Terminologie). Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`table`

  The name. Dieser Parameter akzeptiert die folgenden Suchmuster: `%` für 0 oder mehr Zeichen und `_` für genau ein beliebiges Zeichen.

`types`

  If `table_type` is not an empty string, it must contain a list of comma-separated values for the types of interest; each value may be enclosed in single quotes (`'`) or unquoted. For example, `'TABLE','VIEW'` or `TABLE, VIEW`. If the data source does not support a specified table type, odbc_tables() does not return any results for that type.

### Rückgabewerte

Gibt ein ODBC-Ergebnis-Objekt zurück containing the information Bei einem Fehler wird `false` zurückgegeben..

The result set has the following columns:

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `TABLE_TYPE`
- `REMARKS`

Treiber können zusätzliche Spalten melden.

The result set is ordered by `TABLE_TYPE`, `TABLE_CAT`, `TABLE_SCHEM` and `TABLE_NAME`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `odbc` erwartet nun eine Instanz von Odbc\Connection; vorher wurde eine Ressource erwartet.
8.4.0 | Diese Funktion gibt nun eine Instanz von Odbc\Result zurück; vorher wurde eine Ressource zurückgegeben.
8.0.0 | `schema`, `table` and `types` are now nullable.

### Beispiele

Beispiel #1 List Tables in a Catalog

    <?php
    $conn = odbc_connect($dsn, $user, $pass);
    $tables = odbc_tables($conn, 'SalesOrders', 'dbo', '%', 'TABLE');
    while (($row = odbc_fetch_array($tables))) {
        print_r($row);
        break; // further rows omitted for brevity
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [TABLE_CAT] => SalesOrders
        [TABLE_SCHEM] => dbo
        [TABLE_NAME] => Orders
        [TABLE_TYPE] => TABLE
        [REMARKS] =>
    )

### Siehe auch

- odbc_tableprivileges() - Lists tables and the privileges associated with each table
- odbc_columns() - Lists the column names in specified tables
- odbc_specialcolumns() - Retrieves special columns
- odbc_statistics() - Retrieve statistics about a table
- odbc_procedures() - Get the list of procedures stored in a specific data source

## Inhaltsverzeichnis

- odbc_autocommit — Ändert das Autocommit-Verhalten
- odbc_binmode — Behandlung von Binärdaten
- odbc_close — Schließ eine ODBC-Verbindung
- odbc_close_all — Schließt alle ODBC-Verbindungen
- odbc_columnprivileges — Liste Spalten und damit verbundene Rechte für die angegeben Tabelle auf
- odbc_columns — Lists the column names in specified tables
- odbc_commit — Schließt eine ODBC-Transaktion ab
- odbc_connect — Verbindet mit einer Datenquelle
- odbc_connection_string_is_quoted — Determines if an ODBC connection string value is quoted
- odbc_connection_string_quote — Quotes an ODBC connection string value
- odbc_connection_string_should_quote — Determines if an ODBC connection string value should be quoted
- odbc_cursor — Liefert den Cursornamen
- odbc_data_source — Returns information about available DSNs
- odbc_do — Alias von odbc_exec
- odbc_error — Get the last error code
- odbc_errormsg — Get the last error message
- odbc_exec — Führt einen SQL-Befehl direkt aus
- odbc_execute — Führt einen vorbereiteten SQL-Befehl aus
- odbc_fetch_array — Fetch a result row as an associative array
- odbc_fetch_into — Liest eine Ergebniszeile in ein Array
- odbc_fetch_object — Fetch a result row as an object
- odbc_fetch_row — Liefert eine Zeile zurück
- odbc_field_len — Bestimmt die Länge (Präzision) eines Feldes
- odbc_field_name — Liefert den Spaltennamen
- odbc_field_num — Liefert die Spaltennummer
- odbc_field_precision — Alias von odbc_field_len
- odbc_field_scale — Get the scale of a field
- odbc_field_type — Datentyp eines Feldes
- odbc_foreignkeys — Retrieves a list of foreign keys
- odbc_free_result — Gibt die mit einem Ergebnis verbundenen Objekte frei
- odbc_gettypeinfo — Retrieves information about data types supported by the data source
- odbc_longreadlen — Steuert die Behandlung von LONG-Spalten
- odbc_next_result — Checks if multiple results are available
- odbc_num_fields — Liefert die Anzahl der Ergebnisspalten
- odbc_num_rows — Liefert die Zeilenzahl des Abfrageergebnisses
- odbc_pconnect — Öffnet eine persistente Datenbankverbindung
- odbc_prepare — Bereitet eine Anweisung für die Ausführung vor
- odbc_primarykeys — Gets the primary keys for a table
- odbc_procedurecolumns — Retrieve information about parameters to procedures
- odbc_procedures — Get the list of procedures stored in a specific data source
- odbc_result — Liefert Ergebnisdaten
- odbc_result_all — Gibt das aktuelle Abfrageergebnis als HTML-Tabelle aus
- odbc_rollback — Bricht eine Transaktion ab
- odbc_setoption — ODBC-Einstellungen anpassen
- odbc_specialcolumns — Retrieves special columns
- odbc_statistics — Retrieve statistics about a table
- odbc_tableprivileges — Lists tables and the privileges associated with each table
- odbc_tables — Get the list of table names stored in a specific data source

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- ODBC Funktionen
  - odbc_autocommit — Ändert das Autocommit-Verhalten
  - odbc_binmode — Behandlung von Binärdaten
  - odbc_close — Schließ eine ODBC-Verbindung
  - odbc_close_all — Schließt alle ODBC-Verbindungen
  - odbc_columnprivileges — Liste Spalten und damit verbundene Rechte für die angegeben Tabelle auf
  - odbc_columns — Lists the column names in specified tables
  - odbc_commit — Schließt eine ODBC-Transaktion ab
  - odbc_connect — Verbindet mit einer Datenquelle
  - odbc_connection_string_is_quoted — Determines if an ODBC connection string value is quoted
  - odbc_connection_string_quote — Quotes an ODBC connection string value
  - odbc_connection_string_should_quote — Determines if an ODBC connection string value should be quoted
  - odbc_cursor — Liefert den Cursornamen
  - odbc_data_source — Returns information about available DSNs
  - odbc_do — Alias von odbc_exec
  - odbc_error — Get the last error code
  - odbc_errormsg — Get the last error message
  - odbc_exec — Führt einen SQL-Befehl direkt aus
  - odbc_execute — Führt einen vorbereiteten SQL-Befehl aus
  - odbc_fetch_array — Fetch a result row as an associative array
  - odbc_fetch_into — Liest eine Ergebniszeile in ein Array
  - odbc_fetch_object — Fetch a result row as an object
  - odbc_fetch_row — Liefert eine Zeile zurück
  - odbc_field_len — Bestimmt die Länge (Präzision) eines Feldes
  - odbc_field_name — Liefert den Spaltennamen
  - odbc_field_num — Liefert die Spaltennummer
  - odbc_field_precision — Alias von odbc_field_len
  - odbc_field_scale — Get the scale of a field
  - odbc_field_type — Datentyp eines Feldes
  - odbc_foreignkeys — Retrieves a list of foreign keys
  - odbc_free_result — Gibt die mit einem Ergebnis verbundenen Objekte frei
  - odbc_gettypeinfo — Retrieves information about data types supported by the data source
  - odbc_longreadlen — Steuert die Behandlung von LONG-Spalten
  - odbc_next_result — Checks if multiple results are available
  - odbc_num_fields — Liefert die Anzahl der Ergebnisspalten
  - odbc_num_rows — Liefert die Zeilenzahl des Abfrageergebnisses
  - odbc_pconnect — Öffnet eine persistente Datenbankverbindung
  - odbc_prepare — Bereitet eine Anweisung für die Ausführung vor
  - odbc_primarykeys — Gets the primary keys for a table
  - odbc_procedurecolumns — Retrieve information about parameters to procedures
  - odbc_procedures — Get the list of procedures stored in a specific data source
  - odbc_result — Liefert Ergebnisdaten
  - odbc_result_all — Gibt das aktuelle Abfrageergebnis als HTML-Tabelle aus
  - odbc_rollback — Bricht eine Transaktion ab
  - odbc_setoption — ODBC-Einstellungen anpassen
  - odbc_specialcolumns — Retrieves special columns
  - odbc_statistics — Retrieve statistics about a table
  - odbc_tableprivileges — Lists tables and the privileges associated with each table
  - odbc_tables — Get the list of table names stored in a specific data source

# PHP Data Objects

# Einführung

Die Erweiterung PHP Data Objects (PDO) stellt eine leichte, konsistente Schnittstelle bereit, um mit PHP auf Datenbanken zuzugreifen. Jeder Datenbanktreiber, der die PDO-Schnittstelle implementiert, kann spezifische Features als reguläre Funktionen der Erweiterung bereitstellen. Es ist zu beachten, dass keine Funktion einer Datenbank mit PDO allein benutzt werden kann; um auf eine Datenbank zugreifen zu können, muss ein datenbankspezifischer PDO-Treiber benutzt werden.

PDO bietet eine Abstraktionsschicht für den Datenzugriff, das bedeutet, dass unahängig von der verwendeten Datenbank dieselben Funktionen verwendet werden können, um Abfragen zu erstellen und Daten zu lesen. PDO bietet keine Abstraktion für Datenbanken. Es schreibt keine SQL-Abfragen um oder emuliert fehlende Features. Wenn diese Funktionalität benötigt wird, muss eine komplette Abstraktionsschicht verwendet werden.

PDO wird mit PHP ausgeliefert.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Laufzeit-Konfiguration

## Installation

Diese Erweiterung ist standardmäßig aktiviert. Sie kann bei der Kompilierung mit der folgenden Option ausgeschaltet werden: --disable-pdo

PDO auf Unix-Systemen installieren

1. PDO und der PDO_SQLITE-Treiber sind standardmäßig aktiviert. Es kann jedoch nötig sein, den PDO-Treiber für die gewünschte Datenbank manuell zu aktivieren. Weitere Informationen hierzu sind in der Dokumentation für datenbankspezifische PDO-Treiber zu finden.

   > Hinweis:

   > Wenn PDO als Shared Extension kompiliert wird (nicht empfohlen), müssen alle PDO-Treiber geladen werden, nachdem PDO selbst geladen wurde.

2. Wenn PDO als Shared Module installiert wurde, muss die php.ini-Datei dahingehend geändert werden, dass die PDO-Erweiterung automatisch geladen wird, wenn PHP ausgeführt wird. Dort müssen auch alle datenbankspezifischen Treiber aktiviert werden. Stellen Sie sicher, dass diese nach der Zeile extension=pdo stehen, da PDO initialisiert werden muss, bevor die datenbankspezifischen Erweiterungen geladen werden können. Wenn Sie PDO und die datenbankspezifischen Erweiterungen statisch kompiliert haben, können Sie diesen Schritt überspringen.

       extension=pdo

Installation auf Windows

1. PDO ist standardmäßig aktiviert. Wählen Sie die datenbankspezifischen DLL-Dateien und laden Sie diese entweder per dl() zur Laufzeit oder aktivieren Sie sie in der Datei php.ini. Zum Beispiel lädt folgendes den PDO_SQLITE-Treiber, lässt aber den PDO_ODBC-Treiber auskommentiert:

       ;extension=pdo_odbc
       extension=pdo_sqlite

   Diese DLLs sollten im extension_dir des Systems vorhanden sein.

> Hinweis:

> Nachdem Änderungen an der Datei php.ini vorgenommen wurden, muss PHP neu gestartet werden, damit die neuen Einstellungen wirksam werden.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

PDO-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
pdo.dsn.* |  | Nur php.ini |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`pdo.dsn.*` string

  Definiert den DSN-Alias. Für eine ausführliche Erklärung siehe PDO::__construct().

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`PDO::PARAM_BOOL` (int)
  Stellt den Datentyp Boolean dar.
`PDO::PARAM_NULL` (int)
  Stellt den Datentyp SQL-NULL dar.
`PDO::PARAM_INT` (int)
  Stellt den Datentyp SQL-INTEGER dar.
`PDO::PARAM_STR` (int)
  Stellt SQL-CHAR, VARCHAR und andere String-Datentypen dar.
`PDO::PARAM_STR_NATL` (int)
  Ein Flag, das angibt, dass eine Zeichenkette den nationalen Zeichensatz verwendet. Verfügbar seit PHP 7.2.0
`PDO::PARAM_STR_CHAR` (int)
  Ein Flag, das angibt, dass eine Zeichenkette den regulären Zeichensatz verwendet. Verfügbar seit PHP 7.2.0
`PDO::PARAM_LOB` (int)
  Stellt den SQL-Datentyp LOB (large object) dar.
`PDO::PARAM_STMT` (int)
  Stellt einen Datensatztyp dar. Wird derzeit von keinem Treiber unterstützt.
`PDO::PARAM_INPUT_OUTPUT` (int)
  Legt fest, dass der Parameter ein INOUT-Parameter für eine Stored Procedure sein muss. Auf den Wert muss ein bitweises OR mit einem eindeutigen PDO::PARAM_*-Parameter ausgeführt werden.
`PDO::FETCH_DEFAULT` (int)
  Legt fest, dass der standardmäßige Abrufmodus verwendet werden soll. Verfügbar seit PHP 8.0.7.
`PDO::FETCH_LAZY` (int)
  Legt fest, dass die Methode zum Abrufen von Daten jede Zeile als Objekt zurückgeben soll, dessen Eigenschaftsnamen den Spaltennamen aus der zurückgegebenen Ergebnismenge entsprechen. `PDO::FETCH_LAZY` gibt ein PDORow-Objekt zurück, das die Eigenschaftsnamen des Objekts erstellt, sobald auf diese zugegriffen wird. Ungültig innerhalb von PDOStatement::fetchAll().
`PDO::FETCH_ASSOC` (int)
  Legt fest, dass die Methode zum Abrufen von Daten jede Zeile in einem assoziativen Array zurückgibt, das mit den Spaltennamen aus der Ergebnismenge indiziert wird. Wenn die Ergebnismenge mehrere gleichlautende Spaltennamen enthält, gibt `PDO::FETCH_ASSOC` nur einen Wert pro Spaltenname zurück.
`PDO::FETCH_NAMED` (int)
  Legt fest, dass die Methode zum Abrufen von Daten jede Zeile als ein Array mit dem Index des Spaltennamens der entsprechenden Ergebnismenge zurückgeben soll. Wenn die Ergebnismenge mehrere Spalten mit dem gleichen Namen besitzt, gibt `PDO::FETCH_NAMED` ein Array von Werten pro Spaltenname zurück.
`PDO::FETCH_NUM` (int)
  Legt fest, dass die Methode zum Abrufen von Daten jede Zeile als Array zurückgeben soll, indiziert durch die Spaltennummer, wie sie in der entsprechenden Ergebnismenge zurückgegeben wird, beginnend bei Spalte 0.
`PDO::FETCH_BOTH` (int)
  Legt fest, dass die Methode zum Abrufen von Daten jede Zeile als Array zurückgeben soll, das durch den Spaltennamen und die Spaltennummer indiziert ist, wie sie in der entsprechenden Ergebnismenge zurückgegeben werden, beginnend bei Spalte 0.
`PDO::FETCH_OBJ` (int)
  Legt fest, dass die Methode zum Abrufen von Daten jede Zeile als ein Objekt mit Eigenschaftsnamen zurückgeben soll, die den in der Ergebnismenge zurückgegebenen Spaltennamen entsprechen.
`PDO::FETCH_BOUND` (int)
  Legt fest, dass die Methode zum Abrufen von Daten TRUE zurückgeben soll und die Werte der Spalten in der Ergebnismenge den PHP-Variablen zuweist, an die sie mit der Methode PDOStatement::bindParam() oder der Methode PDOStatement::bindColumn() gebunden wurden.
`PDO::FETCH_COLUMN` (int)
  Legt fest, dass die Methode zum Abrufen von Daten nur eine einzige angeforderte Spalte aus der nächsten Zeile in der Ergebnismenge zurückgeben soll.
`PDO::FETCH_CLASS` (int)
  Legt fest, dass die Methode zum Abrufen von Daten eine neue Instanz der angeforderten Klasse zurückgeben soll.

  > Hinweis: Das Objekt wird initialisiert, indem die Spalten der Ergebnismenge den Eigenschaften der Klasse zugewiesen werden. Dies geschieht vor dem Aufruf des Konstruktors und erlaubt die Belegung von Eigenschaften unabhängig von ihrer Sichtbarkeit oder davon, ob sie als `readonly` markiert sind. Wenn eine Eigenschaft in der Klasse nicht existiert, wird die magische Methode __set() aufgerufen, falls sie existiert; andernfalls wird eine dynamische öffentliche Eigenschaft erstellt. Wenn jedoch auch `PDO::FETCH_PROPS_LATE` angegeben ist, wird der Konstruktor vor dem Belegen der Eigenschaften aufgerufen.

`PDO::FETCH_INTO` (int)
  Legt fest, dass die Methode zum Abrufen von Daten eine vorhandene Instanz der angeforderten Klasse aktualisieren soll, indem die Spalten den benannten Eigenschaften der Klasse zugeordnet werden.
`PDO::FETCH_FUNC` (int)
  Ermöglicht die ad-hoc Anpassung der Daten (nur gültig innerhalb von PDOStatement::fetchAll()).
`PDO::FETCH_GROUP` (int)
  Gruppiert die Rückgabe nach den Werten. Üblicherweise in Verbindung mit `PDO::FETCH_COLUMN` oder `PDO::FETCH_KEY_PAIR`.
`PDO::FETCH_UNIQUE` (int)
  Ruft nur eindeutige Werte abrufen.
`PDO::FETCH_KEY_PAIR` (int)
  Liefert das Ergebnis von zwei Spalten als Array. Der Inhalt der ersten Spalte ist der Schlüssel und der Inhalt der zweiten Spalte ist der Wert.
`PDO::FETCH_CLASSTYPE` (int)
  Ermittelt den Klassennamen aus dem Wert der ersten Spalte.
`PDO::FETCH_SERIALIZE` (int)
  Ähnlich wie `PDO::FETCH_INTO`, liefert aber das Objekt als serialisierte Zeichenkette. Der Konstruktor wird nicht aufgerufen, wenn dieses Flag gesetzt ist. Ab PHP 8.1.0 veraltet.
`PDO::FETCH_PROPS_LATE` (int)
  Ruft den Konstrutor auf, bevor die Eigenschaften gesetzt werden.
`PDO::ATTR_AUTOCOMMIT` (int)
  Wenn dieser Wert `false` ist, versucht PDO, Autocommit zu deaktivieren, damit die Verbindung eine Transaktion starten kann.
`PDO::ATTR_PREFETCH` (int)
  Durch Ändern der Prefetch-Puffergröße können Sie die Balance zwischen Speicherverbrauch und Datenbankgeschwindigkeit einstellen. Nicht alle Datenbank/Treiber-Kombinationen unterstützen die Größenänderung dieses Puffers. Je größer der Puffer ist, desto höher ist die Leistung, aber auch der Speicherverbrauch.
`PDO::ATTR_TIMEOUT` (int)
  Legt den Timeout-Wert für die Kommunikation mit der Datenbank in Sekunden fest.
`PDO::ATTR_ERRMODE` (int)
  Informationen zu diesem Attribut finden Sie im Abschnitt Fehler und Fehlerbehandlung.
`PDO::ATTR_SERVER_VERSION` (int)
  Dieses Attribut ist schreibgeschützt; es gibt Informationen über die Version des Datenbankservers zurück, mit dem PDO verbunden ist.
`PDO::ATTR_CLIENT_VERSION` (int)
  Dieses Attribut ist schreibgeschützt; es gibt Informationen über die Versionen der Client-Bibliotheken zurück, die der PDO-Treiber verwendet.
`PDO::ATTR_SERVER_INFO` (int)
  Dieses Attribut ist schreibgeschützt; es gibt einige Metainformationen über den Datenbankserver zurück, mit dem PDO verbunden ist.
`PDO::ATTR_CONNECTION_STATUS` (int)
`PDO::ATTR_CASE` (int)
  Erzwingt die Zuordnung von Spaltennamen zur Groß- oder Kleinschreibung, die durch die `PDO::CASE_*`-Konstanten festgelegt wird.
`PDO::ATTR_CURSOR_NAME` (int)
  Liefert oder setzt den Namen, der für einen Cursor verwendet werden soll. Am nützlichsten bei der Verwendung von scrollbaren Cursorn und positionierten Aktualisierungen.
`PDO::ATTR_CURSOR` (int)
  Wählt den Cursortyp aus. PDO unterstützt derzeit entweder `PDO::CURSOR_FWDONLY` oder `PDO::CURSOR_SCROLL`. Bleiben Sie bei `PDO::CURSOR_FWDONLY`, es sei denn, Sie wissen, dass Sie einen scrollbaren Cursor benötigen.
`PDO::ATTR_DRIVER_NAME` (int)
  Gibt den Namen des Treibers zurück.

  Beispiel #1 Die Verwendung von `PDO::ATTR_DRIVER_NAME`

      <?php
      if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
        echo "Läuft auf MySQL; macht hier etwas MySQL-spezifisches\n";
      }
      ?>

`PDO::ATTR_ORACLE_NULLS` (int)
  Konvertiert leere Zeichenketten bei Datenabfragen in SQL-NULL-Werte.
`PDO::ATTR_PERSISTENT` (int)
  Fordert eine persistente Verbindung an, anstatt eine neue Verbindung zu erstellen. Weitere Informationen zu diesem Attribut finden Sie im Abschnitt Verbindungen und Verbindungsmanagement.
`PDO::ATTR_STATEMENT_CLASS` (int)
  Legt den Name der Klasse fest, die als Statement zurückgegeben wird.
`PDO::ATTR_FETCH_CATALOG_NAMES` (int)
  Stellt jedem Spaltennamen, der in der Ergebnismenge zurückgegeben wird, den Namen des enthaltenden Katalogs voran. Der Katalogname und der Spaltenname werden durch einen Punkt (.) getrennt. Die Unterstützung dieses Attributs liegt auf der Treiberebene; es kann sein, dass es von Ihrem Treiber nicht unterstützt wird.
`PDO::ATTR_FETCH_TABLE_NAMES` (int)
  Stellt jedem Spaltennamen, der in der Ergebnismenge zurückgegeben wird, den Namen der enthaltenden Tabelle voran. Der Tabellenname und der Spaltenname werden durch einen Punkt (.) getrennt. Die Unterstützung dieses Attributs liegt auf der Treiberebene; es kann sein, dass es von Ihrem Treiber nicht unterstützt wird.
`PDO::ATTR_STRINGIFY_FETCHES` (int)
  Erzwingt, dass alle Werte (außer `null`) als Zeichenkette abgerufen werden. Die `null`-Werte bleiben unverändert, es sei denn, `PDO::ATTR_ORACLE_NULLS` wird auf `PDO::NULL_TO_STRING` gesetzt.
`PDO::ATTR_MAX_COLUMN_LEN` (int)
  Legt die maximale Länge der Spaltennamen fest.
`PDO::ATTR_DEFAULT_FETCH_MODE` (int)
`PDO::ATTR_EMULATE_PREPARES` (int)
`PDO::ATTR_DEFAULT_STR_PARAM` (int)
  Legt den Standard-Zeichenketten-Parametertypen fest; entweder `PDO::PARAM_STR_NATL` oder `PDO::PARAM_STR_CHAR`. Verfügbar seit PHP 7.2.0.
`PDO::ERRMODE_SILENT` (int)
  Löst keinen Fehler und keine Ausnahme aus, wenn ein Fehler auftritt. Es wird erwartet, dass der Entwickler explizit auf Fehler prüft. Dies ist der Standardmodus. Weitere Informationen zu diesem Attribut finden Sie im Abschnitt Fehler und Fehlerbehandlung.
`PDO::ERRMODE_WARNING` (int)
  Gibt eine PHP-`E_WARNING`-Meldung aus, wenn ein Fehler auftritt. Weitere Informationen zu diesem Attribut finden Sie im Abschnitt Fehler und Fehlerbehandlung.
`PDO::ERRMODE_EXCEPTION` (int)
  Löst eine PDOException aus, wenn ein Fehler auftritt. Weitere Informationen zu diesem Attribut finden Sie im Abschnitt Fehler und Fehlerbehandlung.
`PDO::CASE_NATURAL` (int)
  Belässt die Spaltennamen so, wie sie vom Datenbanktreiber zurückgegeben werden.
`PDO::CASE_LOWER` (int)
  Erzwingt die Kleinschreibung von Spaltennamen.
`PDO::CASE_UPPER` (int)
  Erzwingt die Großschreibung von Spaltennamen.
`PDO::NULL_NATURAL` (int)
`PDO::NULL_EMPTY_STRING` (int)
`PDO::NULL_TO_STRING` (int)
`PDO::FETCH_ORI_NEXT` (int)
  Liefert die nächste Zeile aus der Ergebnismenge. Gilt nur für scrollbare Cursor.
`PDO::FETCH_ORI_PRIOR` (int)
  Liefert die vorherige Zeile aus der Ergebnismenge. Gilt nur für scrollbare Cursor.
`PDO::FETCH_ORI_FIRST` (int)
  Liefert die erste Zeile aus der Ergebnismenge. Gilt nur für scrollbare Cursor.
`PDO::FETCH_ORI_LAST` (int)
  Liefert die vorherige Zeile aus der Ergebnismenge. Gilt nur für scrollbare Cursor.
`PDO::FETCH_ORI_ABS` (int)
  Liefert die angeforderte Zeile anhand der Zeilennummer aus der Ergebnismenge. Gilt nur für scrollbare Cursor.
`PDO::FETCH_ORI_REL` (int)
  Liefert die angeforderte Zeile an einer Position relativ zur aktuellen Position des Cursors aus der Ergebnismenge. Gilt nur für scrollbare Cursor.
`PDO::CURSOR_FWDONLY` (int)
  Erzeugt ein PDOStatement-Objekt mit einem Nur-Vorwärts-Cursor. Dies ist die Standard-Cursor-Wahl, da es das schnellste und häufigste Datenzugriffsmuster in PHP ist.
`PDO::CURSOR_SCROLL` (int)
  Erzeugt ein PDOStatement-Objekt mit einem scrollbaren Cursor. Übergeben Sie die Konstante `PDO::FETCH_ORI_*`, um die aus der Ergebnismenge abgerufenen Zeilen zu steuern.
`PDO::ERR_NONE` (string)
  Entspricht dem SQLSTATE '00000', d. h. die SQL-Anweisung wurde erfolgreich und ohne Fehler oder Warnungen ausgegeben. Diese Konstante ist für die Unterstützung bei der Überprüfung von PDO::errorCode() oder PDOStatement::errorCode(), um festzustellen, ob ein Fehler aufgetreten ist. Normalerweise wissen Sie sowieso, ob dies der Fall ist, indem Sie den Rückgabewert der Methode untersuchen, die die Fehlerbedingung ausgelöst hat.
`PDO::PARAM_EVT_ALLOC` (int)
  Ein Zuweisungsereignis (Allocation).
`PDO::PARAM_EVT_FREE` (int)
  Ein Freigabe-Ereignis (Deallocation).
`PDO::PARAM_EVT_EXEC_PRE` (int)
  Löst ein Ereignis vor der Ausführung einer vorbereiteten Anweisung aus.
`PDO::PARAM_EVT_EXEC_POST` (int)
  Löst ein Ereignis nach der Ausführung einer vorbereiteten Anweisung aus.
`PDO::PARAM_EVT_FETCH_PRE` (int)
  Löst ein Ereignis vor dem Abrufen eines Ergebnisses aus einer Ergebnismenge aus.
`PDO::PARAM_EVT_FETCH_POST` (int)
  Löst ein Ereignis nach dem Abrufen eines Ergebnisses aus einer Ergebnismenge aus.
`PDO::PARAM_EVT_NORMALIZE` (int)
  Löst ein Ereignis während der Registrierung eines gebundenen Parameters aus, was es dem Treiber ermöglicht, den Parameternamen zu normalisieren.
`PDO::SQLITE_DETERMINISTIC` (int)
  Signalisiert, dass eine Funktion die mit PDO::sqliteCreateFunction() erzeugt wurde, deterministisch ist, d. h. dass sie immer dasselbe Ergebnis liefert, wenn sie innerhalb derselben SQL-Anweisung mit den gleichen Parametern aufgerufen wird. (Verfügbar seit PHP 7.1.4.)

# Verbindungen und Verbindungsmanagement

Verbindungen werden durch das Erstellen von Instanzen der PDO-Basisklasse erzeugt. Es ist unerheblich, welchen Treiber Sie benutzen wollen. Sie benutzen immer den PDO-Klassennamen. Der Konstruktor erwartet Parameter zur Angabe der Datenbankquelle (auch bekannt als DSN) und optional für Benutzername und Passwort (falls vorhanden).

Beispiel #1 Mit MySQL verbinden

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    ?>

Wenn es Fehler bei der Verbindung gibt, wird eine Ausnahme vom Typ `PDOException` geworfen. Sie können die Ausnahme abfangen, wenn Sie sich selbst um die Fehlerbedingung kümmern wollen, oder Sie können es einer globalen Routine zur Ausnahmebehandlung überlassen, die Sie mit set_exception_handler() konfigurieren.

Beispiel #2 Verbindungsfehler behandeln

    <?php
    try {
        $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    } catch (PDOException $e) {
        // z.B. nach einem Timeout versuchen, die Verbindung erneut aufzubauen
    }

Warnung

Wie jede andere Exception kann auch PDOException entweder explizit über eine `catch`-Anweisung oder implizit über set_exception_handler() abgefangen werden. Andernfalls ist das Standardverhalten, eine nicht abgefangene Exception in einen `E_FATAL_ERROR` umzuwandeln. Der fatale Fehler enthält einen Backtrace, der Verbindungsdetails preisgeben könnte. Deshalb sollte die php.ini-Option `display_errors` auf einem Produktionsserver auf `0` gesetzt werden.

Bei erfolgreicher Verbindung zur Datenbank wird eine Instanz der PDO-Klasse an Ihr Skript zurückgegeben. Die Verbindung bleibt während der Lebensdauer des PDO-Objekts aktiv. Um die Verbindung zu beenden, müssen Sie das Objekt löschen, indem Sie sicherstellen, dass alle Referenzen darauf gelöscht werden - das erreichen Sie, indem Sie der Variable, die das Objekt beinhaltet, `null` zuweisen. Wenn Sie das nicht explizit tun, schließt PHP die Verbindung automatisch, wenn Ihr Skript endet.

> Hinweis: Gibt es noch weitere Referenzen auf dieses PDO-Exemplar (wie etwa von einem PDOStatement-Exemplar, oder von anderen Variablen, die dasselbe PDO-Exemplar referenzieren), müssen diese ebenfalls entfernt werden (zum Beispiel durch die Zuweisung von `null` an die Variable, die das PDOStatement referenziert).

Beispiel #3 Eine Verbindung schließen

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
    // hier die Verbindung nutzen
    $sth = $dbh->query('SELECT * FROM foo');

    // und nachdem das erledigt ist, wird sie geschlossen
    $sth = null;
    $dbh = null;
    ?>

Viele Webanwendungen profitieren von persistenten Verbindungen zum Datenbankserver. Persistente Verbindungen werden nicht am Ende des Skripts geschlossen, sondern werden gecacht und wiederverwendet, wenn ein anderes Skript eine Verbindung mit denselben Daten anfordert. Der Cache an persistenten Verbindungen erlaubt Ihnen, den Overhead zu vermeiden, wenn jedesmal eine neue Verbindung geöffnet wird, sobald ein Skript mit der Datenbank kommunizieren muss, was sich in einer schnelleren Anwendung widerspiegelt.

Beispiel #4 Persistente Verbindungen

    <?php
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
      PDO::ATTR_PERSISTENT => true
    ));
    ?>

Der Wert der `PDO::ATTR_PERSISTENT` Option wird nach Boolean kovertiert (aktiviere/deaktiviere persistente Verbindungen), es sei denn es ist ein nicht-numerischer String; in diesem Fall ermöglicht es die Verwendung mehrerer persistenter Verbindungspools. Das ist nützlich, wenn unterschiedliche Verbindungen inkompatible Einstellungen verwenden, beispielsweise unterschiedliche Werte von `PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`.

> Hinweis:

> Wenn Sie persistente Verbindungen verwenden wollen, müssen Sie `PDO::ATTR_PERSISTENT` im Array von Treiberoptionen setzen, das an den PDO-Konstruktor übergeben wird. Wenn Sie dieses Attribut mittels PDO::setAttribute() nach der Instanziierung des Objekts setzen, verwendet der Treiber keine persistenten Verbindungen.

> Hinweis:

> Wenn Sie den PDO-ODBC-Treiber benutzen und Ihre ODBC-Bibliotheken ODBC Connection Pooling unterstützen (unixODBC und Windows etwa, es könnte auch andere geben), dann wird empfohlen, dass sie keine persistenten PDO-Verbindungen benutzen, sondern das Cachen der Verbindungen der ODBC Connection Pooling-Schicht überlassen. Der ODBC Connection Pool wird mit anderen Modulen im Prozess geteilt. Wenn PDO also angewiesen wird die Verbindung zu cachen, wird diese Verbindung nie dem ODBC Connection Pool zurückgegeben, was darin resultiert, dass zusätzliche Verbindungen aufgebaut werden, um jene anderen Module zu bedienen.

# Transaktionen und auto-commit

Jetzt, wo Sie via PDO verbunden sind, müssen Sie sich bewusst machen, wie PDO Transaktionen verwaltet, bevor Sie anfangen, Abfragen auszuführen. Falls Sie noch nie mit Transaktionen zu tun hatten, diese bieten 4 wichtige Features: Atomizität, Konsistenz (Consistency), Isolation und Dauerhaftigkeit (Durability) (ACID). Einfach gesagt wird alles in einer Transaktion, auch wenn es in Einzelschritten ausgeführt wird, garantiert in sicherer Weise in die Datenbank eingetragen, ohne Beeinträchtigung durch andere Verbindungen, wenn es abgeschickt wird. Aktivitäten in Transaktionen können auch automatisch annulliert werden (wenn Sie es noch nicht abgeschickt haben), was Fehlerbehandlung in Ihren Scripts einfacher macht.

Transaktionen werden typischerweise implementiert, indem Ihre Menge an Änderungen "aufgespart" wird und dann in einem Rutsch abgearbeitet werden. Das hat den netten Nebeneffekt, dass die Effizienz der Aktualisierungen drastisch erhöht wird. In anderen Worten können Transaktionen Ihre Scripts schneller und möglicherweise auch robuster machen. Aber Sie müssen sie korrekt verwenden, um davon zu profitieren.

Unglücklicherweise unterstützt nicht jede Datenbank Transaktionen, deswegen muss PDO in einem "auto-commit" genannten Modus laufen, wenn Sie die Verbindung zum ersten Mal öffnen. "Auto-commit" bedeutet, dass jede Abfrage, die Sie ausführen ihre eigene implizite Transaktion besitzt, wenn die Datenbank das unterstützt, oder keine Transaktion, wenn die Datenbank keine Transaktionen unterstützt. Wenn Sie eine Transaktion benötigen, müssen Sie eine mit der Methode PDO::beginTransaction() initiieren. Wenn der zu Grunde liegende Treiber keine Transaktionen unterstützt, wird eine `PDOException` geworfen (unbeachtet Ihrer Einstellungen zur Fehlerbehandlung: dies ist immer eine ernste Fehlerbedingung). Wenn Sie dann in einer Transaktion sind, können Sie PDO::commit() oder PDO::rollBack() benutzen, um die Transaktion abzuschließen, abhängig vom Erfolg des Codes, den Sie während der Transaktion ausgeführt haben.

Warnung

PDO überprüft nur auf Treiberebene auf Transaktionsfähigkeit. Wenn bestimmte Laufzeitbedingunen ergeben, dass Transaktionen nicht verfügbar sind, wird PDO::beginTransaction() trotzdem ohne Fehler `true` zurückgeben, wenn der Server die Anfrage zum Start einer Transaktion akzeptiert.

Ein Beispiel wäre es, Transaktionen auf MyISAM-Tabellen in einer MySQL-Datenbank zu verwenden

Warnung

Implicit Commits with DDL Statements: Some databases automatically issue an implicit `COMMIT` when a database definition language (DDL) statement, such as `DROP TABLE` or `CREATE TABLE`, is executed within a transaction. This means that any prior changes made within the same transaction will be automatically committed and cannot be rolled back.

`MySQL` and `Oracle` are example databases that exhibit this behavior.

Beispiel #1 Implicit Commit Example

    <?php
    $pdo->beginTransaction();
    $pdo->exec("INSERT INTO users (name) VALUES ('Rasmus')");
    $pdo->exec("CREATE TABLE test (id INT PRIMARY KEY)"); // Implicit COMMIT occurs here
    $pdo->rollBack(); // This will NOT undo the INSERT/CREATE for MySQL or Oracle
    ?>

Best Practice: Avoid executing DDL statements inside transactions if using databases that enforce this behavior. If necessary, separate DDL operations from transactional logic.

Wenn das Script endet oder die Verbindung im Begriff ist, geschlossen zu werden und Sie eine Transaktion ausstehen haben, wird PDO automatisch einen Rollback durchführen. Dies ist eine Sicherheitsmaßnahme, um Inkonsistenzen in dem Fall, dass das Script unerwartet beendet wird, zu vermeiden - wenn Sie die Transaktion nicht explizit ausgeführt haben, wird angenommen, dass etwas schiefgegangen ist, deswegen wird zur Sicherheit Ihrer Daten ein Rollback durchgeführt.

Warnung

Der automatische Rollback wird nur durchgeführt, wenn Sie die Transaktion per PDO::beginTransaction() starten. Wenn Sie manuell eine Abfrage ausführen, die eine Transaktion startet, kann PDO nichts davon wissen und kann deswegen auch keinen Rollback durchführen, wenn etwas schiefgeht.

Beispiel #2 Mehrere Abfragen in einer Transaktion

Im folgenden Beispiel nehmen wir an, dass wir einen Satz von Einträgen für einen neuen Angestellten eintragen wollen, dem die ID-Nummer 23 zugeordnet wurde. Zusätzlich zur Angabe der Basisdaten für diese Person müssen wir auch ihr Gehalt festhalten. Es ist ziemlich einfach, zwei getrennte Aktualisierungen durchzuführen, aber indem wir sie in PDO::beginTransaction() und PDO::commit() einschließen, garantieren wir, dass niemand anderes diese Änderungen sieht, bis sie komplett sind. Wenn etwas schiefgeht, wird der `catch`-Block alle seit Beginn der Transaktion durchgeführten Änderungen rückgängig machen und dann eine Fehlermeldung ausgeben.

    <?php
    try {
      $dbh = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2',
          array(PDO::ATTR_PERSISTENT => true));
      echo "Connected\n";
    } catch (Exception $e) {
      die("Unable to connect: " . $e->getMessage());
    }

    try {
      $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

      $dbh->beginTransaction();
      $dbh->exec("insert into staff (id, first, last) values (23, 'Joe', 'Bloggs')");
      $dbh->exec("insert into salarychange (id, amount, changedate)
          values (23, 50000, NOW())");
      $dbh->commit();

    } catch (Exception $e) {
      $dbh->rollBack();
      echo "Failed: " . $e->getMessage();
    }
    ?>

Sie sind nicht darauf beschränkt, Änderungen in einer Transaktion durchzuführen. Sie können auch komplexe Abfragen ausführen um Daten zu erhalten, und diese Informationen etwa dazu benutzen, mehr Änderungen und Abfragen zu erzeugen. Während die Transaktion aktiv ist, kann garantiert niemand anderes Änderungen durchführen, während Sie bei der Arbeit sind. Um ehrlich zu sein, stimmt das nicht 100%, aber es ist für den Anfang ausreichend, falls Sie noch nie von Transaktionen gehört haben.

# Prepared Statements und Stored Procedures

Viele der ausgereifteren Datenbanken unterstützen das Konzept der Prepared Statements. Was ist das? Man kann sie sich als eine Art von kompiliertem Template für das SQL, das eine Anwendung ausführen will, vorstellen, das durch variable Parameter angepasst werden kann. Prepared Statements haben zwei wichtige Vorteile:

- Die Abfrage muss nur einmal geparst (oder vorbereitet) werden, kann dann aber mehrere Male mit denselben oder anderen Parametern ausgeführt werden. Wenn die Abfrage vorbereitet wird, kann die Datenbank ihre Vorgehensweise zur Ausführung der Abfrage analysieren, kompilieren und optimieren. Für komplexe Abfragen kann dieser Vorgang genug Zeit benötigen, dass es eine Anwendung merklich verlangsamt, wenn dieselbe Abfrage oft mit verschiedenen Parametern wiederholt wird. Mit einem Prepared Statement vermeidet die Anwendung den Zyklus der Analyse/Kompilierung/Optimierung. Kurz gesagt benötigen Prepared Statements weniger Ressourcen und laufen deswegen schneller.
- Die Parameter für Prepared Statements müssen nicht maskiert werden. Der Treiber übernimmt das automatisch. Wenn eine Anwendung ausschließlich Prepared Statements benutzt, kann sich der Entwickler sicher sein, dass keine SQL-Injection auftreten wird. (Wenn aber trotzdem andere Teile der Abfrage aus nicht zuverlässigen Eingaben generiert werden, ist dies immer noch möglich.)

Prepared Statements sind so nützlich, dass sie das einzige Feature sind, das PDO auch für Treiber emulieren wird, die diese nicht unterstützen. Das garantiert, dass eine Anwendung unabhängig von den Möglichkeiten der Datenbank dieselbe Art des Datenzugriffs nutzen kann.

Beispiel #1 Wiederholte Inserts mit Prepared Statements

Dieses Beispiel führt eine INSERT-Abfrage durch, in der ein `name` und ein `value` für die benannten Platzhalter eingesetzt werden.

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (:name, :value)");
    $stmt->bindParam(':name', $name);
    $stmt->bindParam(':value', $value);

    // eine Zeile einfügen
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // eine weitere Zeile mit anderen Werten einfügen
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Beispiel #2 Wiederholte Inserts mit Prepared Statements

Dieses Beispiel führt eine INSERT-Abfrage durch, in der ein `name` und ein `value` für die positionsabhängigen `?`-Platzhalter eingesetzt werden.

    <?php
    $stmt = $dbh->prepare("INSERT INTO REGISTRY (name, value) VALUES (?, ?)");
    $stmt->bindParam(1, $name);
    $stmt->bindParam(2, $value);

    // eine Zeile einfügen
    $name = 'one';
    $value = 1;
    $stmt->execute();

    // eine weitere Zeile mit anderen Werten einfügen
    $name = 'two';
    $value = 2;
    $stmt->execute();
    ?>

Beispiel #3 Abfragen von Daten mit Prepared Statements

Dieses Beispiel ruft Daten basierend auf einem Schlüsselwert ab, der von einem Formular geliefert wird. Die Benutzereingabe wird automatisch maskiert, deswegen gibt es kein Risiko eines SQL-Injection-Angriffs.

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name = ?");
    $stmt->execute([$_GET['name']]);
    foreach ($stmt as $row) {
      print_r($row);
    }
    ?>

Beispiel #4 Eine Stored Procedure mit einem Ausgabeparameter aufrufen

Wenn es der Datenbanktreiber unterstützt, kann eine Anwendung auch Parameter für die Ausgabe einführen, ähnlich der Eingabe. Ausgabeparameter werden typischerweise benutzt, um Werte von Stored Procedures abzurufen. Ausgabeparameter sind etwas komplexer in der Verwendung als Eingabeparameter, weil der Entwickler wissen muss, wie groß ein gegebener Parameter sein könnte, wenn er ihn einführt. Wenn der Wert sich als größer herausstellt als die vorgeschlagene Größe, wird eine Fehlermeldung erzeugt.

    <?php
    $stmt = $dbh->prepare("CALL sp_returns_string(?)");
    $stmt->bindParam(1, $return_value, PDO::PARAM_STR, 4000);

    // Aufruf der Stored Procedure
    $stmt->execute();

    print "Rückgabewert der Stored Procedure: $return_value\n";
    ?>

Beispiel #5 Eine Stored Procedure mit einem Eingabe-/Ausgabe-Parameter aufrufen

Entwickler können auch Parameter angeben, die Werte für Eingabe und Ausgabe enthalten. Die Syntax ist ähnlich den Ausgabeparametern. In diesem nächsten Beispiel wird die Zeichenkette 'hallo' der Stored Procedure übergeben. Wenn diese etwas zurückgibt, wird 'hallo' durch den Rückgabewert der Stored Procedure ersetzt.

    <?php
    $stmt = $dbh->prepare("CALL sp_takes_string_returns_string(?)");
    $value = 'hallo';
    $stmt->bindParam(1, $value, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 4000);

    // Aufruf der Stored Procedure
    $stmt->execute();

    print "Rückgabewert der Stored Procedure: $value\n";
    ?>

Beispiel #6 Ungültige Verwendung von Platzhaltern

    <?php
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE '%?%'");
    $stmt->execute([$_GET['name']]);

    // Platzhalter müssen anstelle des ganzen Wertes verwendet werden
    $stmt = $dbh->prepare("SELECT * FROM REGISTRY where name LIKE ?");
    $stmt->execute(["%$_GET[name]%"]);
    ?>

# Fehler und Fehlerbehandlung

PDO bietet Ihnen die Wahl unter 3 verschiedenen Strategien zur Fehlerbehandlung, um Ihrem Stil der Anwendungsentwicklung gerecht zu werden.

- `PDO::ERRMODE_SILENT`

  Vor PHP 8.0.0 war das die Standardmethode. PDO setzt einfach den Fehler-Code, damit Sie ihn mit den Methoden PDO::errorCode() und PDO::errorInfo() sowohl im Statement- als auch im Datenbank-Objekt überprüfen können. Wenn der Fehler aus einem Aufruf eines Statement-Objekts hervorging, würden Sie die Methoden PDOStatement::errorCode() oder PDOStatement::errorInfo() des Objekts aufrufen. Wenn der Fehler aus einem Aufruf des Datenbank-Objekts hervorging, würden Sie diese Methoden stattdessen auf dem Datenbank-Objekt aufrufen.

- `PDO::ERRMODE_WARNING`

  Zusätzlich zum Setzen des Fehler-Codes wird PDO eine traditionelle E_WARNING-Nachricht ausgeben. Diese Einstellung ist nützlich während des Debuggens/Testens, wenn Sie sehen wollen, welche Probleme aufgetreten sind, ohne den Ablauf der Anwendung zu unterbrechen.

- `PDO::ERRMODE_EXCEPTION`

  Seit PHP 8.0.0 ist das die Standardmethode. Zusätzlich zum Setzen des Fehler-Codes wirft PDO eine PDOException und setzt deren Eigenschaften so, dass sie den Fehler-Code und Fehlerinformationen wiedergeben. Diese Einstellung ist auch nützlich während des Debuggens, da sie das Skript am Ort des Fehlers gewissermaßen "sprengt" und sehr schnell mögliche Problemstellen in Ihrem Code aufzeigt. (Zur Erinnerung: Transaktionen bekommen automatisch einen Rollback, wenn eine Ausnahme das Skript beendet.)

  Diese Einstellung ist auch nützlich, da Sie ihre Fehlerbehandlung klarer als mit traditionellen PHP-Warnungen strukturieren können und mit weniger Code und Verschachtelung als im stillen Modus mit expliziter Überprüfung des Rückgabewertes jedes einzelnen Datenbankaufrufes.

  Unter Ausnahmen finden Sie weitere Informationen über Ausnahmen in PHP.

PDO benutzt Fehler-Codes nach SQL-92 SQLSTATE. Individuelle PDO-Treiber sind selbst verantwortlich, ihre nativen Fehler-Codes in die entsprechenden SQLSTATE-Pendants umzuwandeln. Die Methode PDO::errorCode() gibt einen einzelnen SQLSTATE-Code zurück. Wenn Sie genauere Informationen über einen Fehler benötigen, bietet PDO auch die Methode PDO::errorInfo(), die ein Array zurückgibt, das den SQLSTATE-Code, den treiberspezifischen Fehler-Code und die treiberspezifische Fehlermeldung enthält.

Beispiel #1 Eine PDO Instanz erstellen und die Fehlermethode setzen

    <?php
    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);
    $dbh->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    // This will cause PDO to throw a PDOException (when the table doesn't exist)
    $dbh->query("SELECT wrongcolumn FROM wrongtable");

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Fatal error: Uncaught PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'testdb.wrongtable' doesn't exist in /tmp/pdo_test.php:10
    Stack trace:
    #0 /tmp/pdo_test.php(10): PDO->query('SELECT wrongcol...')
    #1 {main}
      thrown in /tmp/pdo_test.php on line 10

> Hinweis:

> PDO::__construct() wirft immer eine PDOException, wenn die Verbindung fehlschlägt unabhängig davon welcher `PDO::ATTR_ERRMODE` gerade eingestellt ist.

Beispiel #2 Erzeugen eines PDO-Exemplars und setzen der Fehlermethode per Konstruktor

    <?php
    $dsn = 'mysql:dbname=test;host=127.0.0.1';
    $user = 'googleguy';
    $password = 'googleguy';

    $dbh = new PDO($dsn, $user, $password, array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING));

    // Dies wird PDO veranlassen einen Fehler der Stufe E_WARNING anstelle einer
    // Exception auszulösen (falls die Tabelle nicht existiert)
    $dbh->query("SELECT wrongcolumn FROM wrongtable");

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Warning: PDO::query(): SQLSTATE[42S02]: Base table or view not found: 1146 Table 'test.wrongtable' doesn't exist in
    /tmp/pdo_test.php on line 9

# Large Objects (LOBs)

Es könnte an irgendeinem Punkt in Ihrer Anwendung passieren, dass Sie eine "große" Menge an Daten in Ihrer Datenbank ablegen müssen. Groß bedeutet typischerweise "etwa 4 kb oder mehr", obwohl manche Datenbanken spielend bis zu 32 kb bearbeiten können, bevor das als "groß" zählt. Large Objects können entweder textueller oder binärer Natur sein. PDO erlaubt Ihnen, mit diesem großen Datentyp zu arbeiten, indem Sie `PDO::PARAM_LOB` als Typ in Ihren Methodenaufrufen von PDOStatement::bindParam() oder PDOStatement::bindColumn() benutzen. `PDO::PARAM_LOB` veranlasst PDO, die Daten als Stream zu behandeln, so dass Sie diese mit Hilfe der PHP Streams-API bearbeiten können.

Beispiel #1 Ein Bild aus einer Datenbank anzeigen

Dieses Beispiel weist das LOB der Variable namens $lob zu und sendet es mittels fpassthru() an den Browser. Weil das LOB als Stream dargestellt wird, können Funktionen wie fgets(), fread() und stream_get_contents() damit benutzt werden.

    <?php
    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
    $stmt = $db->prepare("select contenttype, imagedata from images where id=?");
    $stmt->execute(array($_GET['id']));
    $stmt->bindColumn(1, $type, PDO::PARAM_STR, 256);
    $stmt->bindColumn(2, $lob, PDO::PARAM_LOB);
    $stmt->fetch(PDO::FETCH_BOUND);

    header("Content-Type: $type");
    fpassthru($lob);
    ?>

Beispiel #2 Ein Bild in eine Datenbank einfügen

Dieses Beispiel öffnet eine Datei und übergibt das File-Handle an PDO, damit sie als LOB eingefügt wird. PDO wird sein Möglichstes tun, den Inhalt der Datei auf möglichst effiziente Weise in die Datenbank zu bekommen.

    <?php
    $db = new PDO('odbc:SAMPLE', 'db2inst1', 'ibmdb2');
    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) values (?, ?, ?)");
    $id = get_new_id(); // Eine Funktion zum Allokieren der neuen ID

    // Wir nehmen an, das Skript läuft als Teil eines Datei-Upload-Formulars
    // Sie finden weitere Informationen in der PHP-Dokumentation

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();
    ?>

Beispiel #3 Ein Bild in eine Datenbank einfügen: Oracle

Oracle erfordert eine leicht unterschiedliche Syntax, um ein LOB aus einer Datei einzufügen. Es ist auch unumgänglich, dass Sie diesen Insert innerhalb einer Transaktion durchführen, andernfalls wird Ihr frisch eingefügtes LOB mit einer Länge von 0 als Teil des impliziten Commits, der beim Ausführen der Abfrage passiert, gespeichert.

    <?php
    $db = new PDO('oci:', 'scott', 'tiger');
    $stmt = $db->prepare("insert into images (id, contenttype, imagedata) " .
      "VALUES (?, ?, EMPTY_BLOB()) RETURNING imagedata INTO ?");
    $id = get_new_id(); // Eine Funktion zum Allokieren einer neuen ID

    // Wir nehmen an, das Skript läuft als Teil eines Datei-Upload-Formulars
    // Sie finden weitere Informationen in der PHP-Dokumentation

    $fp = fopen($_FILES['file']['tmp_name'], 'rb');

    $stmt->bindParam(1, $id);
    $stmt->bindParam(2, $_FILES['file']['type']);
    $stmt->bindParam(3, $fp, PDO::PARAM_LOB);

    $db->beginTransaction();
    $stmt->execute();
    $db->commit();
    ?>

# Die Klasse PDO

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

## Einführung

Repräsentiert eine Verbindung zwischen PHP und einem Datenbankserver.

## Klassenbeschreibung

class PDO {
/* Konstanten */
public const int PARAM_NULL;
public const int PARAM_BOOL = 5;
public const int PARAM_INT = 1;
public const int PARAM_STR = 2;
public const int PARAM_LOB = 3;
public const int PARAM_STMT = 4;
public const int PARAM_INPUT_OUTPUT;
public const int PARAM_STR_NATL;
public const int PARAM_STR_CHAR;
public const int PARAM_EVT_ALLOC;
public const int PARAM_EVT_FREE;
public const int PARAM_EVT_EXEC_PRE;
public const int PARAM_EVT_EXEC_POST;
public const int PARAM_EVT_FETCH_PRE;
public const int PARAM_EVT_FETCH_POST;
public const int PARAM_EVT_NORMALIZE;
public const int FETCH_DEFAULT;
public const int FETCH_LAZY;
public const int FETCH_ASSOC;
public const int FETCH_NUM;
public const int FETCH_BOTH;
public const int FETCH_OBJ;
public const int FETCH_BOUND;
public const int FETCH_COLUMN;
public const int FETCH_CLASS;
public const int FETCH_INTO;
public const int FETCH_FUNC;
public const int FETCH_GROUP;
public const int FETCH_UNIQUE;
public const int FETCH_KEY_PAIR;
public const int FETCH_CLASSTYPE;
public const int FETCH_SERIALIZE;
public const int FETCH_PROPS_LATE;
public const int FETCH_NAMED;
public const int ATTR_AUTOCOMMIT;
public const int ATTR_PREFETCH;
public const int ATTR_TIMEOUT;
public const int ATTR_ERRMODE;
public const int ATTR_SERVER_VERSION;
public const int ATTR_CLIENT_VERSION;
public const int ATTR_SERVER_INFO;
public const int ATTR_CONNECTION_STATUS;
public const int ATTR_CASE;
public const int ATTR_CURSOR_NAME;
public const int ATTR_CURSOR;
public const int ATTR_ORACLE_NULLS;
public const int ATTR_PERSISTENT;
public const int ATTR_STATEMENT_CLASS;
public const int ATTR_FETCH_TABLE_NAMES;
public const int ATTR_FETCH_CATALOG_NAMES;
public const int ATTR_DRIVER_NAME;
public const int ATTR_STRINGIFY_FETCHES;
public const int ATTR_MAX_COLUMN_LEN;
public const int ATTR_EMULATE_PREPARES;
public const int ATTR_DEFAULT_FETCH_MODE;
public const int ATTR_DEFAULT_STR_PARAM;
public const int ERRMODE_SILENT;
public const int ERRMODE_WARNING;
public const int ERRMODE_EXCEPTION;
public const int CASE_NATURAL;
public const int CASE_LOWER;
public const int CASE_UPPER;
public const int NULL_NATURAL;
public const int NULL_EMPTY_STRING;
public const int NULL_TO_STRING;
public const string ERR_NONE;
public const int FETCH_ORI_NEXT;
public const int FETCH_ORI_PRIOR;
public const int FETCH_ORI_FIRST;
public const int FETCH_ORI_LAST;
public const int FETCH_ORI_ABS;
public const int FETCH_ORI_REL;
public const int CURSOR_FWDONLY;
public const int CURSOR_SCROLL;
/* Methoden */
public function __construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function beginTransaction(): bool
public function commit(): bool
public static function connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function errorCode(): ?string
public function errorInfo(): array
public function exec(string `$statement`): int|false
public function getAttribute(int `$attribute`): mixed
public static function getAvailableDrivers(): array
public function inTransaction(): bool
public function lastInsertId(?string `$name` = `null`): string|false
public function prepare(string `$query`, array `$options` = []): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function rollBack(): bool
public function setAttribute(int `$attribute`, mixed `$value`): bool
}

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Klassenkonstanten sind nun typisiert.

# PDO::beginTransaction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::beginTransaction — Startet eine Transaktion

### Beschreibung

public function PDO::beginTransaction(): bool

Deaktiviert den Autocommit-Modus. Wenn der Autocommit-Modus deaktiviert ist, werden Änderungen, die über die Instanz eines PDO-Objekts an der Datenbank vorgenommen werden, erst dann bestätigt, wenn die Transaktion durch den Aufruf von PDO::commit() beendet wird. Wenn PDO::rollBack() aufgerufen wird, werden alle Änderungen an der Datenbank rückgängig gemacht und die Verbindung wird wieder in den Autocommit-Modus versetzt.

Einige Datenbanken, darunter auch MySQL, führen automatisch ein implizites COMMIT durch, wenn innerhalb einer Transaktion eine DDL- (Database Definition Language) Anweisung wie DROP TABLE oder CREATE TABLE ausgeführt wird. Durch das implizite COMMIT wird verhindert, dass andere Änderungen, die in dieser Transaktion vorgenommen wurden, rückgängig gemacht werden können.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn bereits eine Transaktion gestartet wurde oder der Treiber keine Transaktionen unterstützt, wird eine PDOException ausgelöst.

> Hinweis: Eine Exception wird auch dann ausgelöst, wenn das Attribut `PDO::ATTR_ERRMODE` nicht `PDO::ERRMODE_EXCEPTION` ist.

### Beispiele

Beispiel #1 Rückgängigmachen (Rollback) einer Transaktion

Im folgenden Beispiel wird eine Transaktion gestartet und es werden zwei Anweisungen ausgeführt, die die Datenbank verändern, bevor die Änderungen rückgängig gemacht werden. Bei MySQL wird die Transaktion jedoch durch die Anweisung DROP TABLE automatisch bestätigt, sodass keine der Änderungen dieser Transaktion rückgängig gemacht wird.

    <?php
    /* Starten einer Transaktion, wobei Autocommit deaktiviert wird */
    $dbh->beginTransaction();

    /* Ändern des Datenbankschemas und der Daten */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
        SET name = 'hamburger'");

    /* Erkennen eines Fehlers und Zurücknehmen der Änderungen */
    $dbh->rollBack();

    /* Die Datenbankverbindung ist nun wieder im Autocommit-Modus */
    ?>

### Siehe auch

- PDO::commit() - Bestätigt eine Transaktion
- PDO::rollBack() - Macht eine Transaktion rückgängig (Rollback)
- Transaktionen und Autocommit

# PDO::commit

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::commit — Bestätigt eine Transaktion

### Beschreibung

public function PDO::commit(): bool

Bestätigt eine Transaktion und versetzt die Datenbankverbindung wieder zurück in den Autocommit-Modus, bis mittels PDO::beginTransaction() eine neue Transaktion gestartet wird.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn es keine aktive Transaktion gibt, wird eine PDOException ausgelöst.

> Hinweis: Eine Exception wird auch dann ausgelöst, wenn das Attribut `PDO::ATTR_ERRMODE` nicht `PDO::ERRMODE_EXCEPTION` ist.

### Beispiele

Beispiel #1 Bestätigen einer gewöhnlichen Transaktion

    <?php
    /* Starten einer Transaktion, wobei Autocommit deaktiviert wird */
    $dbh->beginTransaction();

    /* Einfügen mehrerer Datensätze auf der Basis von Alles-oder-Nichts */
    $sql = 'INSERT INTO fruit
        (name, colour, calories)
        VALUES (?, ?, ?)';

    $sth = $dbh->prepare($sql);

    foreach ($fruits as $fruit) {
        $sth->execute(array(
            $fruit->name,
            $fruit->colour,
            $fruit->calories,
        ));
    }

    /* Bestätigen der Änderungen */
    $dbh->commit();

    /* Die Datenbankverbindung ist nun wieder im Autocommit-Modus */
    ?>

Beispiel #2 Bestätigen einer DDL-Transaktion

    <?php
    /* Starten einer Transaktion, wobei Autocommit deaktiviert wird */
    $dbh->beginTransaction();

    /* Ändern des Datenbankschemas */
    $sth = $dbh->exec("DROP TABLE fruit");

    /* Bestätigen der Änderungen */
    $dbh->commit();

    /* Die Datenbankverbindung ist nun wieder im Autocommit-Modus */
    ?>

> Hinweis: Nicht alle Datenbanken unterstützen Transaktionen mit DDL-Anweisungen: Bei einigen werden Fehler gemeldet, während bei anderen (einschließlich MySQL) die Transaktion nach der ersten DDL-Anweisung automatisch bestätigt wird.

### Siehe auch

- PDO::beginTransaction() - Startet eine Transaktion
- PDO::rollBack() - Macht eine Transaktion rückgängig (Rollback)
- Transaktionen und Autocommit

# PDO::connect

(PHP 8 >= 8.4.0)

PDO::connect — Connect to a database and return a PDO subclass for drivers that support it

### Beschreibung

public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static

Creates an instance of a PDO subclass for the database being connected to, if it exists, otherwise return a generic PDO instance.

### Parameter-Liste

`dsn`

  Der Name der Datenquelle (Data Source Name oder DSN) enthält die Informationen, die für die Verbindung mit der Datenbank erforderlich sind.

  Im Allgemeinen besteht ein DSN aus dem Namen des PDO-Treibers, gefolgt von einem Doppelpunkt, gefolgt von der treiberspezifischen PDO-Verbindungssyntax. Weitere Informationen sind in der Dokumentation des betreffenden PDO-Treibers zu finden.

  Der Parameter `dsn` unterstützt drei verschiedene Methoden, die für eine Datenbankverbindung benötigten Argumente anzugeben:

  Aufrufen eines Treibers

    `dsn` enthält den vollständigen DSN.

  Aufrufen eines URIs

    `dsn` besteht aus `uri:`, gefolgt von einem URI, der den Ort der Datei mit der DSN-Zeichenkette definiert. Der URI kann eine lokale Datei oder eine entfernte URL angeben.

    `uri:file:///pfad/zur/dsndatei`

  Über einen Alias

    `dsn` besteht aus einem Namen `name`, der auf `pdo.dsn.`name`` in der php.ini abgebildet wird, das die DSN-Zeichenkette definiert.

    > Hinweis:

    > Der Alias muss in der php.ini definiert werden, nicht in der .htaccess oder der httpd.conf

`username`

  Der Benutzername für die DSN-Zeichenkette. Dieser Parameter ist bei einigen PDO-Treibern optional.

`password`

  Das Passwort für die DSN-Zeichenkette. Dieser Parameter ist bei einigen PDO-Treibern optional.

`options`

  Ein Schlüssel=>Wert-Array mit treiberspezifischen Verbindungsoptionen.

### Rückgabewerte

Returns an instance of a PDO subclass for the corresponding PDO driver if it exists, or a generic PDO instance.

### Fehler/Exceptions

Wenn der Versuch, sich mit der angeforderten Datenbank zu verbinden, fehlschlägt, wird eine PDOException ausgelöst, unabhängig davon, welchen Wert `PDO::ATTR_ERRMODE` aktuell hat.

### Siehe auch

- Pdo\Dblib
- Pdo\Firebird
- Pdo\Mysql
- Pdo\Odbc
- Pdo\Pgsql
- Pdo\Sqlite
- PDO::__construct() - Erzeugt eine PDO-Instanz, die eine Datenbankverbindung darstellt

# PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::__construct — Erzeugt eine PDO-Instanz, die eine Datenbankverbindung darstellt

### Beschreibung

public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)

Erzeugt eine PDO-Instanz, die eine Verbindung zur angegebenen Datenbank darstellt.

### Parameter-Liste

`dsn`

  Der Name der Datenquelle (Data Source Name oder DSN) enthält die Informationen, die für die Verbindung mit der Datenbank erforderlich sind.

  Im Allgemeinen besteht ein DSN aus dem Namen des PDO-Treibers, gefolgt von einem Doppelpunkt, gefolgt von der treiberspezifischen PDO-Verbindungssyntax. Weitere Informationen sind in der Dokumentation des betreffenden PDO-Treibers zu finden.

  Der Parameter `dsn` unterstützt drei verschiedene Methoden, die für eine Datenbankverbindung benötigten Argumente anzugeben:

  Aufrufen eines Treibers

    `dsn` enthält den vollständigen DSN.

  Aufrufen eines URIs

    `dsn` besteht aus `uri:`, gefolgt von einem URI, der den Ort der Datei mit der DSN-Zeichenkette definiert. Der URI kann eine lokale Datei oder eine entfernte URL angeben.

    `uri:file:///pfad/zur/dsndatei`

  Über einen Alias

    `dsn` besteht aus einem Namen `name`, der auf `pdo.dsn.`name`` in der php.ini abgebildet wird, das die DSN-Zeichenkette definiert.

    > Hinweis:

    > Der Alias muss in der php.ini definiert werden, nicht in der .htaccess oder der httpd.conf

`username`

  Der Benutzername für die DSN-Zeichenkette. Dieser Parameter ist bei einigen PDO-Treibern optional.

`password`

  Das Passwort für die DSN-Zeichenkette. Dieser Parameter ist bei einigen PDO-Treibern optional.

`options`

  Ein Schlüssel=>Wert-Array mit treiberspezifischen Verbindungsoptionen.

### Fehler/Exceptions

Wenn der Versuch, sich mit der angeforderten Datenbank zu verbinden, fehlschlägt, wird eine PDOException ausgelöst, unabhängig davon, welchen Wert `PDO::ATTR_ERRMODE` aktuell hat.

### Beispiele

Beispiel #1 Erstellen einer PDO-Instanz über den Aufruf eines Treibers

    <?php

    $dsn = 'mysql:dbname=testdb;host=127.0.0.1';
    $user = 'dbuser';
    $password = 'dbpass';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Beispiel #2 Erstellen einer PDO-Instanz über den Aufruf eines URIs

Im folgenden Beispiel wird davon ausgegangen, dass die Datei /usr/local/dbconnect existiert und entsprechende Zugriffsrechte hat, sodass sie von PHP gelesen werden kann. Sie enthält den PDO-DSN für die Verbindung zu einer DB2-Datenbank über den PDO_ODBC-Treiber:

    odbc:DSN=SAMPLE;UID=john;PWD=mypass

Das PHP-Skript kann dann eine Verbindung zur Datenbank aufbauen, indem es einfach den Parameter `uri:` übergibt und auf die URI-Datei verweist:

    <?php

    $dsn = 'uri:file:///usr/local/dbconnect';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

Beispiel #3 Erstellen einer PDO-Instanz über einen Alias

Im folgenden Beispiel wird davon ausgegangen, dass die php.ini den folgenden Eintrag enthält, um mit nur dem Alias `mydb` eine Verbindung zu einer MySQL-Datenbank herzustellen:

    [PDO]
    pdo.dsn.mydb="mysql:dbname=testdb;host=localhost"

    <?php

    $dsn = 'mydb';
    $user = '';
    $password = '';

    $dbh = new PDO($dsn, $user, $password);

    ?>

# PDO::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorCode — Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Datenbank-Handle verknüpft ist

### Beschreibung

public function PDO::errorCode(): ?string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen SQLSTATE zurück, eine fünfstellige alphanumerische Kennung, die im ANSI SQL-92-Standard definiert ist. Kurz gesagt besteht ein SQLSTATE aus einem zweistelligen Klassenwert, gefolgt von einem dreistelligen Unterklassenwert. Ein Klassenwert von 01 steht für eine Warnung und wird vom Rückgabewert SQL_SUCCESS_WITH_INFO begleitet. Alle anderen Klassenwerte mit Ausnahme der Klasse "IM" weisen auf einen Fehler hin. Die Klasse "IM" ist spezifisch für Warnungen und Fehler, die sich aus der Implementierung von PDO (oder ODBC, wenn der ODBC-Treiber verwendet wird) selbst ergeben. Der Unterklassenwert "000" in einer Klasse zeigt an, dass es keine Unterklasse für diesen SQLSTATE gibt.

PDO::errorCode() ruft Fehlercodes nur bei Operationen ab, die direkt auf dem Datenbank-Handle ausgeführt werden. Wenn ein PDOStatement-Objekt mittels PDO::prepare() oder PDO::query() erzeugt wird und ein Fehler auf dem Anweisungs-Handle auftritt, zeigt PDO::errorCode() diesen Fehler nicht an. Um den Fehlercode einer Operation zu erhalten, die mit einem bestimmten Anweisungs-Handle durchgeführt wurde, muss PDOStatement::errorCode() aufgerufen werden.

Gibt `null` zurück, wenn keine Operation über das Datenbank-Handle ausgeführt wurde.

### Beispiele

Beispiel #1 Abrufen eines SQLSTATE-Codes

    <?php
    /* Auslösen eines Fehlers - die Tabelle BONES existiert nicht */
    $dbh->exec("INSERT INTO bones(skull) VALUES ('lucy')");

    echo "\nPDO::errorCode(): ", $dbh->errorCode();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    PDO::errorCode(): 42S02

### Siehe auch

- PDO::errorInfo() - Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Datenbank-Handle verknüpft sind
- PDOStatement::errorCode() - Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Anweisungs-Handle verknüpft ist
- PDOStatement::errorInfo() - Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Anweisungs-Handle verknüpft sind

# PDO::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorInfo — Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Datenbank-Handle verknüpft sind

### Beschreibung

public function PDO::errorInfo(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

PDO::errorInfo() gibt ein Array mit Informationen über den Fehler zurück, der bei der letzten über dieses Datenbank-Handle durchgeführte Operation aufgetreten ist. Das Array besteht mindestens aus den folgenden Feldern:

Element | Information
--- | ---
0 | SQLSTATE-Fehlercode (eine fünfstellige alphanumerische Kennung, die im ANSI-SQL-Standard definiert ist)
1 | Treiberspezifischer Fehlercode
2 | Treiberspezifische Fehlermeldung

> Hinweis:

> Wenn kein SQLSTATE-Fehlercode definiert ist oder kein treiberspezifischer Fehler vorliegt, werden die auf Element 0 folgenden Elemente auf `null` gesetzt.

PDO::errorInfo() ruft Informationen über Fehler nur bei Operationen ab, die direkt über das Datenbank-Handle ausgeführt werden. Wenn ein PDOStatement-Objekt mittels PDO::prepare() oder PDO::query() erzeugt wird und ein Fehler auf dem Anweisungs-Handle auftritt, zeigt PDO::errorInfo() diesen Fehler nicht an. Um Informationen über den Fehler einer Operation zu erhalten, die über ein bestimmtes Anweisungs-Handle durchgeführt wurde, muss PDOStatement::errorInfo() aufgerufen werden.

### Beispiele

Beispiel #1 Anzeigen der errorInfo()-Felder einer PDO_ODBC-Verbindung zu einer DB2-Datenbank

    <?php
    /* Auslösen eines Fehlers - fehlerhafte SQL-Syntax */
    $stmt = $dbh->prepare('bogus sql');
    if (!$stmt) {
        echo "\nPDO::errorInfo():\n";
        print_r($dbh->errorInfo());
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    PDO::errorInfo():
    Array
    (
        [0] => HY000
        [1] => 1
        [2] => near "bogus": syntax error
    )

### Siehe auch

- PDO::errorCode() - Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Datenbank-Handle verknüpft ist
- PDOStatement::errorCode() - Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Anweisungs-Handle verknüpft ist
- PDOStatement::errorInfo() - Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Anweisungs-Handle verknüpft sind

# PDO::exec

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::exec — Führt ein SQL-Statement aus und liefert die Anzahl der betroffenen Zeilen

### Beschreibung

public function PDO::exec(string `$statement`): int|false

PDO::exec() führt ein SQL-Statement aus und gibt die Anzahl der betroffenen Zeilen zurück.

PDO::exec() gibt nicht die Ergebnisse eines SELECT-Statements zurück. Um diese zu erhalten kann entweder PDO::query() genutzt werden, oder ein ein PDOStatement, welches über PDO::prepare() erstellt und über PDOStatement::execute() ausgeführt wird.

### Parameter-Liste

`statement`

  Das SQL-Statement, welches ausgeführt werden soll.

  Alle Usereingaben in diesem Query müssen maskiert werden.

### Rückgabewerte

PDO::exec() gibt die Anzahl von Zeilen zurück, welche durch diese Abfrage geändert oder gelöscht wurden. Wenn keine Zeilen geändert wurden, gibt PDO::exec() `0` zurück.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

Das folgende Beispiel verlässt sich fälschlicherweise auf den Rückgabewert von PDO::exec(), weswegen ein Statement, welches 0 Zeilen ändert, einen Aufruf von die() nach sich zieht:

    <?php
    $db->exec() or die(print_r($db->errorInfo(), true)); // unrichtig
    ?>

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Ein DELETE-Statement ausführen

Führt ein DELETE-Statement ohne WHERE-Klausel aus, und gibt die Anzahl der gelöschten Zeilen aus.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    /* Lösche alle Zeilen aus der FRUIT Tabelle */
    $count = $dbh->exec("DELETE FROM fruit");

    /* Und gebe die Anzahl an gelöschten Zeilen zurück */
    print "$count Zeilen wurden gelöscht.\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    10 Zeilen wurden gelöscht.

### Siehe auch

- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDO::query() - Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus
- PDOStatement::execute() - Führt ein Prepared Statement aus

# PDO::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::getAttribute — Ruft ein Attribut einer Datenbankverbindung ab

### Beschreibung

public function PDO::getAttribute(int `$attribute`): mixed

Diese Funktion gibt den Wert eines Attributs einer Datenbankverbindung zurück. Um PDOStatement-Attribute abzurufen, siehe PDOStatement::getAttribute().

Es ist zu beachten, dass einige Kombinationen von Datenbanken und Treibern möglicherweise nicht alle Attribute der Datenbankverbindung unterstützen.

### Parameter-Liste

`attribute`

  Eine der `PDO::ATTR_*`-Konstanten. Die folgenden generischen Attribute gelten für Datenbankverbindungen:

  - `PDO::ATTR_AUTOCOMMIT`
  - `PDO::ATTR_CASE`
  - `PDO::ATTR_CLIENT_VERSION`
  - `PDO::ATTR_CONNECTION_STATUS`
  - `PDO::ATTR_DRIVER_NAME`
  - `PDO::ATTR_ERRMODE`
  - `PDO::ATTR_ORACLE_NULLS`
  - `PDO::ATTR_PERSISTENT`
  - `PDO::ATTR_PREFETCH`
  - `PDO::ATTR_SERVER_INFO`
  - `PDO::ATTR_SERVER_VERSION`
  - `PDO::ATTR_TIMEOUT`
  Es ist zu beachten, dass einige Treiber möglicherweise zusätzliche treiberspezifische Attribute verwenden, die nicht mit anderen Treibern verwendet werden dürfen.

### Rückgabewerte

Gibt bei Erfolg den Wert des angeforderten PDO-Attributs zurück. Wenn der Aufruf fehlschlägt, wird `null` zurückgegeben.

### Fehler/Exceptions

Wenn der zugrundeliegende Treiber das angeforderte `attribute` nicht unterstützt, kann PDO::getAttribute() eine PDOException werfen.

### Beispiele

Beispiel #1 Abrufen von Attributen der Datenbankverbindung

    <?php
    $conn = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
    $attributes = array(
        "AUTOCOMMIT", "ERRMODE", "CASE", "CLIENT_VERSION", "CONNECTION_STATUS",
        "ORACLE_NULLS", "PERSISTENT", "PREFETCH", "SERVER_INFO", "SERVER_VERSION",
        "TIMEOUT"
    );

    foreach ($attributes as $val) {
        echo "PDO::ATTR_$val: ";
        echo $conn->getAttribute(constant("PDO::ATTR_$val")) . "\n";
    }
    ?>

### Siehe auch

- PDO::setAttribute() - Setzt ein Attribut
- PDOStatement::getAttribute() - Ruft ein Attribut einer Anweisung ab
- PDOStatement::setAttribute() - Setzt ein Anweisungsattribut

# PDO::getAvailableDrivers

# pdo_drivers

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.3)

PDO::getAvailableDrivers -- pdo_drivers — Liefert ein Array mit den verfügbaren PDO-Treibern

### Beschreibung

public static function PDO::getAvailableDrivers(): array
function pdo_drivers(): array

Diese Funktion gibt alle aktuell verfügbaren PDO-Treiber zurück, die bei der Methode PDO::__construct() im Parameter `DSN` verwendet werden können.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

PDO::getAvailableDrivers() gibt ein Array mit den Namen der PDO-Treiber zurück. Wenn keine Treiber verfügbar sind, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 PDO::getAvailableDrivers()-Beispiel

    <?php
    print_r(PDO::getAvailableDrivers());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => mysql
        [1] => sqlite
    )

# PDO::inTransaction

(PHP 5 >= 5.3.3, Bundled pdo_pgsql, PHP 7, PHP 8)

PDO::inTransaction — Prüft, ob es eine offene Transaktion gibt

### Beschreibung

public function PDO::inTransaction(): bool

Prüft, ob gerade eine Transaktion innerhalb des Treibers aktiv ist. Diese Methode funktioniert nur bei Datenbanktreibern, die Transaktionen unterstützen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn es eine aktive Transaktion gibt, und `false` wenn nicht.

# PDO::lastInsertId

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::lastInsertId — Liefert die ID der zuletzt eingefügten Zeile oder den Wert der zuletzt eingefügten Sequenz

### Beschreibung

public function PDO::lastInsertId(?string `$name` = `null`): string|false

Gibt je nach zugrundeliegendem Treiber die ID der zuletzt eingefügten Zeile oder den letzten Wert eines Sequenzobjekts zurück. Beispielsweise erlaubt PDO_PGSQL, für den Parameter `name` den Namen eines beliebigen Sequenzobjekts anzugeben.

> Hinweis:

> Es ist möglich, dass diese Methode bei verschiedenen PDO-Treibern nicht zu einem sinnvollen oder konsistenten Ergebnis führt, da die zugrundeliegende Datenbank unter Umständen nicht einmal das Konzept der automatischen Inkrementierung von Feldern oder Sequenzen unterstützt.

### Parameter-Liste

`name`

  Der Name des Sequenzobjekts, dessen ID zurückgegeben werden soll.

### Rückgabewerte

Wenn für den Parameter `name` kein Sequenzname angegeben wurde, gibt PDO::lastInsertId() eine Zeichenkette zurück, die die Zeilen-ID der zuletzt in die Datenbank eingefügten Zeile darstellt.

Wenn für den Parameter `name` ein Sequenzname angegeben wurde, gibt PDO::lastInsertId() eine Zeichenkette zurück, die den zuletzt aus dem angegebenen Sequenzobjekt abgerufenen Wert darstellt.

Wenn der PDO-Treiber diese Funktionalität nicht unterstützt, löst PDO::lastInsertId() den SQLSTATE `IM001` aus.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

# PDO::prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)

PDO::prepare — Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt

### Beschreibung

public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false

Bereitet eine SQL-Anweisung vor, die von der Methode PDOStatement::execute() ausgeführt werden soll. Die Vorlage für eine Anweisung kann null oder mehr benannte (:name) oder mit Fragezeichen (?) versehene Platzhalter für Parameter enthalten, die bei der Ausführung der Anweisung durch reale Werte ersetzt werden. Benannte und Fragezeichen-Parameter dürfen nicht gleichzeitig in derselben Anweisungsvorlage verwendet werden, sondern nur eine der beiden Varianten. Diese Parameter werden verwendet, um die Benutzereingaben zu binden. Benutzerangaben sollten niemals direkt in die Abfrage aufgenommen werden.

Für jeden Wert, der beim Aufruf von PDOStatement::execute() an die Anweisung übergeben werden soll, muss ein eindeutiger Platzhalter angegeben werden. Ein benannter Platzhalter darf nur dann mehrfach verwendet werden, wenn der Emulationsmodus aktiviert ist.

> Hinweis:

> Die Platzhalter für die Parameter können nur ein vollständiges Datenliteral darstellen. Es ist nicht möglich, einen Teil eines Literals, ein Schlüsselwort, einen Bezeichner oder einen beliebigen Teil einer Abfrage an einen Parameter zu binden. So können zum Beispiel in einer IN()-Klausel einer SQL-Anweisung nicht mehrere Werte an einen einzigen Parameter gebunden werden.

Mittels PDO::prepare() und PDOStatement::execute() kann der Treiber bei Anweisungen, die mehrfach mit unterschiedlichen Parameterwerten ausgeführt werden, die Leistung einer Anwendung optimieren, indem er die Zwischenspeicherung des Abfrageplans und der Metainformationen auf Client- und/oder Serverseite aushandelt. Außerdem trägt dies dazu bei, Angriffe durch SQL-Injection zu verhindern, weil die Parameter nicht mehr manuell maskiert und in Anführungszeichen gesetzt werden müssen.

Bei Treibern, die diese nicht unterstützen, emuliert PDO vorbereitete Anweisungen/gebundene Parameter und kann außerdem benannte oder mit Fragezeichen versehene Parametermarkierungen in eine geeignetere Form umwandeln, wenn der Treiber zwar die eine, nicht aber die andere Form unterstützt.

> Hinweis: Der Parser, der für emulierte vorbereitete Anweisungen verwendet wird und die benannten oder durch Fragezeichen angegebenen Parameter umschreibt, unterstützt die nicht standardmäßige Maskierung einfacher und doppelter Anführungszeichen durch Backslashes. Dies hat zur Folge, dass abschließende Anführungszeichen, denen ein Backslash unmittelbar vorausgeht, nicht als solche erkannt werden, was dazu führen kann, dass Parameter falsch erkannt werden und die vorbereitete Anweisung bei ihrer Ausführung fehlschlägt. Um dies zu umgehen, sollten für solche SQL-Abfragen keine emulierten vorbereiteten Anweisungen verwendet werden. Außerdem sollte ein vom Treiber nativ unterstützter Parameterstil verwendet werden, um ein Umschreiben der Parameter zu vermeiden.

Seit PHP 7.4.0 können Fragezeichen durch Verdoppeln maskiert werden. Das bedeutet, dass die Zeichenkette `??` beim Senden der Abfrage an die Datenbank in `?` übersetzt wird.

### Parameter-Liste

`query`

  Dies muss eine für den jeweiligen Datenbankserver gültige Vorlage für eine SQL-Anweisung sein.

`options`

  Dieses Array enthält ein oder mehrere Schlüssel=>Wert-Paare, um die Werte der Attribute des von dieser Methode zurückgegebenen PDOStatement-Objekts zu setzen. Am häufigsten wird dies verwendet, um den Wert von `PDO::ATTR_CURSOR` für einen scrollbaren Cursor auf `PDO::CURSOR_SCROLL` zu setzen. Einige Treiber haben treiberspezifische Optionen, die während der Vorbereitung gesetzt werden können.

### Rückgabewerte

Wenn der Datenbankserver die Anweisung erfolgreich vorbereitet hat, gibt PDO::prepare() ein PDOStatement-Objekt zurück. Schlägt die Vorbereitung fehl, gibt PDO::prepare() `false` zurück oder löst eine PDOException aus (abhängig von der Fehlerbehandlung).

> Hinweis:

> Da emulierte vorbereitete Anweisungen nicht mit dem Datenbankserver kommunizieren, überprüft PDO::prepare() die Anweisung nicht.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Vorlage für eine SQL-Anweisung mit benannten Parametern

    <?php
    /* Ausführen einer vorbereiteten Anweisung durch Übergabe eines Arrays von Werten */
    $sql = 'SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour';
    $sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
    $sth->execute(['calories' => 150, 'colour' => 'red']);
    $red = $sth->fetchAll();
    /* Den Array-Schlüsseln kann auch ein Doppelpunkt ":" vorangestellt werden (optional) */
    $sth->execute([':calories' => 175, ':colour' => 'yellow']);
    $yellow = $sth->fetchAll();
    ?>

Beispiel #2 Vorlage für eine SQL-Anweisung mit Fragezeichen als Platzhalter

    <?php
    /* Ausführen einer vorbereiteten Anweisung durch Übergabe eines Arrays von Werten */
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->execute([150, 'red']);
    $red = $sth->fetchAll();
    $sth->execute([175, 'yellow']);
    $yellow = $sth->fetchAll();
    ?>

Beispiel #3 Vorlage für eine SQL-Anweisung mit maskierten Fragezeichen

    <?php
    /* Hinweis: dies ist nur bei PostgreSQL-Datenbanken möglich */
    $sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
    $sth->execute(['feature']);
    $featureIssues = $sth->fetchAll();
    $sth->execute(['performance']);
    $performanceIssues = $sth->fetchAll();
    ?>

### Siehe auch

- PDO::exec() - Führt ein SQL-Statement aus und liefert die Anzahl der betroffenen Zeilen
- PDO::query() - Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus
- PDOStatement::execute() - Führt ein Prepared Statement aus

# PDO::query

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::query — Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus

### Beschreibung

public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false

Mit PDO::query() wird eine SQL-Anweisung in einem einzigen Funktionsaufruf vorbereitet und ausgeführt und die Anweisung als PDOStatement-Objekt zurückgegeben.

Bei einer Abfrage, die mehrmals ausgeführt werden soll, wird die Effizienz verbessert, indem ein PDOStatement-Objekt mit PDO::prepare() vorbereitet und die Anweisung mit mehreren Aufrufen von PDOStatement::execute() ausgeführt wird.

Wenn vor dem nächsten Aufruf von PDO::query() nicht alle Daten einer Ergebnismenge abgerufen werden, schlägt der Aufruf möglicherweise fehl. Deshalb sollten die mit dem PDOStatement-Objekt verbundenen Datenbankressourcen mittels PDOStatement::closeCursor() freigegeben werden, bevor PDO::query() erneut aufgerufen wird.

> Hinweis:

> Wenn `query` Platzhalter enthält, muss die Anweisung mit der Methode PDO::prepare() vorbereitet und mit der Methode PDOStatement::execute() ausgeführt werden.

### Parameter-Liste

`query`

  Die SQL-Anweisung, die vorbereitet und ausgeführt werden soll

  Wenn das SQL Platzhalter enthält, müssen stattdessen die Methoden PDO::prepare() und PDOStatement::execute() verwendet werden. Wenn es der Treiber unterstützt, kann das SQL alternativ mittels PDO::quote() mit korrekt formatierten Daten manuell vorbereitet werden, bevor PDO::query() aufgerufen wird.

`fetchMode`

  Der voreingestellte Abrufmodus für das zurückgegebene PDOStatement. Es muss eine der `PDO::FETCH_*`-Konstanten sein.

  Wenn dieses Argument an die Funktion übergeben wird, werden die restlichen Argumente so behandelt, als ob PDOStatement::setFetchMode() für das resultierende Anweisungsobjekt aufgerufen wurde. Die nachfolgenden Argumente hängen vom gewählten Abrufmodus ab.

### Rückgabewerte

Gibt ein PDOStatement-Objekt zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 SQL ohne Platzhalter kann mit PDO::query() ausgeführt werden

    <?php
    $sql = 'SELECT name, color, calories FROM fruit ORDER BY name';
    foreach ($conn->query($sql) as $row) {
        print $row['name'] . "\t";
        print $row['color'] . "\t";
        print $row['calories'] . "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    apple   red     150
    banana  yellow  250
    kiwi    brown   75
    lemon   yellow  25
    orange  orange  300
    pear    green   150
    watermelon      pink    90

### Siehe auch

- PDO::exec() - Führt ein SQL-Statement aus und liefert die Anzahl der betroffenen Zeilen
- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::execute() - Führt ein Prepared Statement aus

# PDO::quote

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.1)

PDO::quote — Setzt eine Zeichenkette für die Verwendung in einer Abfrage in Anführungszeichen

### Beschreibung

public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false

PDO::quote() schließt die angegebene Zeichenkette in Anführungszeichen ein und maskiert Sonderzeichen innerhalb der Zeichenkette, wobei ein für den zugrundeliegenden Treiber geeigneter Stil der Anführungszeichen verwendet wird.

Wenn SQL-Anweisungen mit dieser Funktion erstellt werden, wird dringend empfohlen, PDO::prepare() zu verwenden, um SQL-Anweisungen mit gebundenen Parametern vorzubereiten, anstatt PDO::quote() zu verwenden, um Benutzereingaben in eine SQL-Anweisung einzufügen. Vorbereitete Anweisungen mit gebundenen Parametern sind nicht nur portabler, bequemer und immun gegen SQL-Injections, sondern lassen sich oft auch viel schneller ausführen als interpolierte Abfragen, da sowohl der Server als auch der Client die Abfragen in einer bereits kompilierten Form zwischenspeichern können.

Diese Methode ist nicht bei allen PDO-Treibern implementiert (insbesondere nicht bei PDO_ODBC). In diesem Fall sollten stattdessen vorbereitete Anweisungen verwendet werden.

Achtung

# Sicherheit: Der voreingestellte Zeichensatz

Der Zeichensatz muss je nach Treiber entweder auf Serverebene oder in der Datenbankverbindung selbst eingestellt werden, damit er sich auf PDO::quote() auswirkt. Weitere Informationen sind in der Treiberspezifischen Dokumentation zu finden.

### Parameter-Liste

`string`

  Die Zeichenkette, die in Anführungszeichen gesetzt werden soll

`type`

  Gibt Treibern, die andere Anführungszeichen verwenden, einen Hinweis auf den Datentyp. Zum Beispiel teilt `PDO_PARAM_LOB` dem Treiber mit, dass er binäre Daten maskieren soll.

### Rückgabewerte

Gibt eine Zeichenkette in Anführungszeichen zurück, die theoretisch bedenkenlos an eine SQL-Anweisung übergeben werden kann, oder `false`, wenn der Treiber diese Anführungszeichen nicht unterstützt.

### Beispiele

Beispiel #1 Schützen einer normalen Zeichenkette

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Einfache Zeichenkette */
    $string = 'Nice';
    print "Nicht abgeschirmte Zeichenkette: $string\n";
    print "Abgeschirmte Zeichenkette: " . $conn->quote($string) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Nicht abgeschirmte Zeichenkette: Nice
    Abgeschirmte Zeichenkette: 'Nice'

Beispiel #2 Schützen einer gefährlichen Zeichenkette

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Gefährliche Zeichenkette */
    $string = 'Naughty \' string';
    print "Nicht abgeschirmte Zeichenkette: $string\n";
    print "Abgeschirmte Zeichenkette: " . $conn->quote($string) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Nicht abgeschirmte Zeichenkette: Naughty ' string
    Abgeschirmte Zeichenkette: 'Naughty '' string'

Beispiel #3 Schützen einer komplexen Zeichenkette

    <?php
    $conn = new PDO('sqlite:/home/lynn/music.sql3');

    /* Komplexe Zeichenkette */
    $string = "Co'mpl''ex \"st'\"ring";
    print "Nicht abgeschirmte Zeichenkette: $string\n";
    print "Abgeschirmte Zeichenkette: " . $conn->quote($string) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Nicht abgeschirmte Zeichenkette: Co'mpl''ex "st'"ring
    Abgeschirmte Zeichenkette: 'Co''mpl''''ex "st''"ring'

### Siehe auch

- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::execute() - Führt ein Prepared Statement aus

# PDO::rollBack

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::rollBack — Macht eine Transaktion rückgängig (Rollback)

### Beschreibung

public function PDO::rollBack(): bool

Macht die aktuelle durch PDO::beginTransaction() gestartete Transaktion rückgängig.

Falls die Datenbank auf den Autocommit-Modus eingestellt war, wird er wiederhergestellt, nachdem die Transaktion zurückgesetzt wurde.

Wenn im Rahmen einer Transaktion eine DDL- (Database Definition Language) Anweisung wie DROP TABLE oder CREATE TABLE ausgeführt wird, geben einige Datenbanken, darunter auch MySQL, ein implizites COMMIT aus. Durch das implizite COMMIT wird verhindert, dass weitere im Rahmen der Transaktion vorgenommene Änderungen rückgängig gemacht werden können.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn es keine aktive Transaktion gibt, wird eine PDOException ausgelöst.

> Hinweis: Eine Exception wird auch dann ausgelöst, wenn das Attribut `PDO::ATTR_ERRMODE` nicht `PDO::ERRMODE_EXCEPTION` ist.

### Beispiele

Beispiel #1 Rückgängigmachen einer Transaktion

Im folgenden Beispiel wird eine Transaktion gestartet und es werden zwei Anweisungen ausgeführt, die die Datenbank verändern, bevor die Änderungen rückgängig gemacht werden. Bei MySQL wird die Transaktion jedoch durch die Anweisung DROP TABLE automatisch bestätigt, sodass keine der Änderungen dieser Transaktion rückgängig gemacht wird.

    <?php
    /* Starten einer Transaktion, wobei Autocommit deaktiviert wird */
    $dbh->beginTransaction();

    /* Ändern des Datenbankschemas und der Daten */
    $sth = $dbh->exec("DROP TABLE fruit");
    $sth = $dbh->exec("UPDATE dessert
        SET name = 'hamburger'");

    /* Erkennen eines Fehlers und Zurücknehmen der Änderungen */
    $dbh->rollBack();

    /* Die Datenbankverbindung ist nun wieder im Autocommit-Modus */
    ?>

### Siehe auch

- PDO::beginTransaction() - Startet eine Transaktion
- PDO::commit() - Bestätigt eine Transaktion
- Transaktionen und Autocommit

# PDO::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::setAttribute — Setzt ein Attribut

### Beschreibung

public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool

Legt ein Attribut für eine Datenbankverbindung fest. Einige der allgemein verfügbaren Attribute sind unten aufgeführt; manche Treiber verwenden möglicherweise zusätzliche treiberspezifische Attribute. Es ist zu beachten, dass die treiberspezifischen Attribute nicht mit anderen Treibern verwendet werden dürfen.

`PDO::ATTR_CASE`

  Erzwingt, dass Spaltennamen eine bestimmte Groß-/Kleinschreibung aufweisen; kann einen der folgenden Werte annehmen:

  `PDO::CASE_LOWER`
    Erzwingt, dass Spaltennamen klein geschrieben werden.
  `PDO::CASE_NATURAL`
    Belässt die Spaltennamen so, wie sie vom Datenbanktreiber zurückgegeben werden.
  `PDO::CASE_UPPER`
    Erzwingt, dass Spaltennamen groß geschrieben werden.
`PDO::ATTR_ERRMODE`

  Modus der PDO-Fehlermeldung; kann einen der folgenden Werte annehmen:

  `PDO::ERRMODE_SILENT`
    Es werden nur Fehlercodes gesetzt.
  `PDO::ERRMODE_WARNING`
    Gibt einen Fehler der Stufe `E_WARNING` aus.
  `PDO::ERRMODE_EXCEPTION`
    Löst PDOExceptions aus.
`PDO::ATTR_ORACLE_NULLS`

  > Hinweis: Dieses Attribut ist für alle Treiber verfügbar, nicht nur für Oracle.

  Legt fest, ob und wie `null` und leere Strings umgewandelt werden sollen; kann einen der folgenden Werte annehmen:

  `PDO::NULL_NATURAL`
    Es findet keine Umwandlung statt.
  `PDO::NULL_EMPTY_STRING`
    Leere Zeichenketten werden in `null` umgewandelt.
  `PDO::NULL_TO_STRING`
    `null` wird in eine leere Zeichenkette umgewandelt.
`PDO::ATTR_STRINGIFY_FETCHES`

  Legt fest, ob abgerufene numerische Werte in Zeichenketten umgewandelt werden sollen; akzeptiert einen Wert vom Typ bool: `true` zum Aktivieren und `false` zum Deaktivieren (Voreinstellung). `null`-Werte bleiben unverändert, es sei denn, `PDO::ATTR_ORACLE_NULLS` wird auf `PDO::NULL_TO_STRING` gesetzt.

`PDO::ATTR_STATEMENT_CLASS`

  Legt die vom Benutzer bereitgestellte Anweisungsklasse fest, die von PDOStatement abgeleitet ist; muss das Format `array(string classname, array(mixed constructor_args))` haben.

  Achtung

  Kann nicht mit persistenten PDO-Instanzen verwendet werden.

`PDO::ATTR_TIMEOUT`

  Legt das Zeitlimit fest (in Sekunden); akzeptiert einen Wert vom Typ int.

  > Hinweis:

  > Diese Option wird nicht von allen Treibern unterstützt und ihre Bedeutung kann sich je nach Treiber unterscheiden. So wartet SQLite beispielsweise bis zu diesem Zeitwert, bevor es aufgibt, eine beschreibbare Sperre zu erhalten, aber andere Treiber können dies als Zeitlimit für den Verbindungsaufbau oder den Lesevorgang interpretieren.

`PDO::ATTR_AUTOCOMMIT`

  > Hinweis: Nur für die OCI-, Firebird- und MySQL-Treiber verfügbar.

  Legt fest, ob jede einzelne Anweisung automatisch bestätigt werden soll; akzeptiert einen Wert vom Typ bool: `true` zum Aktivieren und `false` zum Deaktivieren. Voreinstellung: `true`.

`PDO::ATTR_EMULATE_PREPARES`

  > Hinweis: Nur für die OCI-, Firebird- und MySQL-Treiber verfügbar.

  Aktiviert oder deaktiviert die Emulation vorbereiteter Anweisungen. Einige Treiber unterstützen vorbereitete Anweisungen nicht nativ oder nur eingeschränkt. Wenn es auf `true` gesetzt ist, werden vorbereitete Anweisungen immer emuliert, andernfalls versucht PDO, nativ vorbereitete Anweisungen zu verwenden. Falls der Treiber die aktuelle Abfrage nicht erfolgreich vorbereiten kann, greift PDO immer darauf zurück, die vorbereitete Anweisung zu emulieren.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY`

  > Hinweis: Nur für den MySQL-Treiber verfügbar.

  Legt fest, ob gepufferte Abfragen verwendet werden sollen; akzeptiert einen Wert vom Typ bool: `true` zum Aktivieren und `false` zum Deaktivieren. Voreinstellung: `true`.

`PDO::ATTR_DEFAULT_FETCH_MODE`

  Legt den standardmäßigen Abrufmodus fest. Eine Beschreibung der Modi und ihrer Verwendung ist in der Dokumentation zu PDOStatement::fetch() zu finden.

### Parameter-Liste

`attribute`

  Das Attribut, das geändert werden soll.

`value`

  Der Wert, auf den `attribute` gesetzt wird; je nach Attribut kann ein bestimmter Typ erforderlich sein.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- PDO::getAttribute() - Ruft ein Attribut einer Datenbankverbindung ab
- PDOStatement::getAttribute() - Ruft ein Attribut einer Anweisung ab
- PDOStatement::setAttribute() - Setzt ein Anweisungsattribut

## Inhaltsverzeichnis

- PDO::beginTransaction — Startet eine Transaktion
- PDO::commit — Bestätigt eine Transaktion
- PDO::connect — Connect to a database and return a PDO subclass for drivers that support it
- PDO::__construct — Erzeugt eine PDO-Instanz, die eine Datenbankverbindung darstellt
- PDO::errorCode — Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Datenbank-Handle verknüpft ist
- PDO::errorInfo — Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Datenbank-Handle verknüpft sind
- PDO::exec — Führt ein SQL-Statement aus und liefert die Anzahl der betroffenen Zeilen
- PDO::getAttribute — Ruft ein Attribut einer Datenbankverbindung ab
- PDO::getAvailableDrivers — Liefert ein Array mit den verfügbaren PDO-Treibern
- PDO::inTransaction — Prüft, ob es eine offene Transaktion gibt
- PDO::lastInsertId — Liefert die ID der zuletzt eingefügten Zeile oder den Wert der zuletzt eingefügten Sequenz
- PDO::prepare — Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDO::query — Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus
- PDO::quote — Setzt eine Zeichenkette für die Verwendung in einer Abfrage in Anführungszeichen
- PDO::rollBack — Macht eine Transaktion rückgängig (Rollback)
- PDO::setAttribute — Setzt ein Attribut

# Die Klasse PDOStatement

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Einführung

Repräsentiert ein Prepared Statement und, nachdem es ausgeführt wurde, die zugehörige Ergebnismenge.

## Klassenbeschreibung

class PDOStatement implements IteratorAggregate {
/* Eigenschaften */
public string $queryString;
/* Methoden */
public function bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool
public function closeCursor(): bool
public function columnCount(): int
public function debugDumpParams(): ?bool
public function errorCode(): ?string
public function errorInfo(): array
public function execute(?array `$params` = `null`): bool
public function fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed
public function fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array
public function fetchColumn(int `$column` = 0): mixed
public function fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false
public function getAttribute(int `$name`): mixed
public function getColumnMeta(int `$column`): array|false
public function getIterator(): Iterator
public function nextRowset(): bool
public function rowCount(): int
public function setAttribute(int `$attribute`, mixed `$value`): bool
public function setFetchMode(int `$mode`): true
public function setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true
}

## Eigenschaften

queryString

  Verwendete Abfragezeichenkette.

## Changelog

Version | Beschreibung
--- | ---
8.0.0 | PDOStatement implementiert jetzt IteratorAggregate anstelle von Traversable.

# PDOStatement::bindColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindColumn — Bindet eine Spalte an eine PHP-Variable

### Beschreibung

public function PDOStatement::bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

PDOStatement::bindColumn() bindet die angegebene Variable an die angegebene Spalte der Ergebnismenge einer Abfrage. Jedes Mal, wenn PDOStatement::fetch() oder PDOStatement::fetchAll() aufgerufen wird, werden alle an Spalten gebundenen Variablen aktualisiert.

> Hinweis:

> Da Informationen über die Spalten für PDO erst verfügbar sind, nachdem die Anweisung ausgeführt wurde, sollte diese Funktion in portablen Anwendungen nach PDOStatement::execute() aufgerufen werden.

> Um jedoch bei Verwendung des PgSQL-Treibers eine Spalte vom Typ LOB mit einem Stream verknüpfen zu können, muss diese Methode vor PDOStatement::execute() aufgerufen werden, weil die Anwendung das OID-Objekt ansonsten als Integer erhält.

### Parameter-Liste

`column`

  Die Spaltennummer (beginnend mit 1) oder der Spaltenname in der Ergebnismenge. Wird der Spaltenname verwendet, ist zu beachten, dass der Name mit der vom Treiber zurückgegebenen Groß-/Kleinschreibung der Spalte übereinstimmen muss.

`var`

  Der Name der PHP-Variable, an die die Spalte gebunden werden soll.

`type`

  Der Datentyp des Parameters, angegeben durch eine der `PDO::PARAM_*`-Konstanten.

`maxLength`

  Ein Hinweis, um Speicherplatz vorab zuzuweisen.

`driverOptions`

  Optionale Parameter für den Treiber.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Binden der Ergebnismenge an PHP-Variablen

Die Spalten einer Ergebnismenge an PHP-Variablen zu binden, ist eine effektive Methode, um die in jeder Zeile enthaltenen Daten sofort für eine Anwendung verfügbar zu machen. Im folgenden Beispiel wird gezeigt, wie Spalten mittels PDO mit einer ganzen Reihe von Optionen und sinnvollen Voreinstellungen gebunden und abgerufen werden können.

    <?php
    $stmt = $dbh->prepare('SELECT name, colour, calories FROM fruit');
    $stmt->execute();

    /* Binden anhand der Spaltennummer */
    $stmt->bindColumn(1, $name);
    $stmt->bindColumn(2, $colour);

    /* Binden anhand des Spaltennamens */
    $stmt->bindColumn('calories', $cals);

    while ($stmt->fetch(PDO::FETCH_BOUND)) {
        print $name . "\t" . $colour . "\t" . $cals . "\n";
    }

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    apple   red     150
    banana  yellow  175
    kiwi    green   75
    orange  orange  150
    mango   red     200
    strawberry      red     25

### Siehe auch

- PDOStatement::execute() - Führt ein Prepared Statement aus
- PDOStatement::fetch() - Ruft die nächste Zeile aus einer Ergebnismenge ab
- PDOStatement::fetchAll() - Ruft die verbleibenden Zeilen aus einer Ergebnismenge ab
- PDOStatement::fetchColumn() - Liefert eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge

# PDOStatement::bindParam

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindParam — Bindet einen Parameter an den angegebenen Variablennamen

### Beschreibung

public function PDOStatement::bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool

Bindet eine PHP-Variable an den entsprechenden benannten oder durch ein Fragezeichen gekennzeichneten Platzhalter der vorbereiteten SQL-Anweisung. Im Gegensatz zu PDOStatement::bindValue() wird die Variable als Referenz gebunden und wird erst ausgewertet, wenn PDOStatement::execute() aufgerufen wird.

Meistens handelt es sich bei den Parametern um Eingabeparameter, d. h. um Parameter, die nur lesend verwendet werden, um die Abfrage zu erstellen (sie können aber dennoch nach `type` umgewandelt werden). Einige Treiber ermöglichen jedoch die Ausführung gespeicherter Prozeduren, die Daten über Ausgabeparameter zurückgeben können. Solche Parameter werden häufig gleichzeitig als Ein- und Ausgabeparameter verwendet, die sowohl Daten senden als auch aktualisiert werden, um sie zu empfangen.

### Parameter-Liste

`param`

  Der Bezeichner des Parameters. Bei einer vorbereiteten Anweisung, die benannte Platzhalter verwendet, ist dies ein Parametername der Form :name. Bei einer vorbereiteten Anweisung mit Fragezeichen-Platzhaltern ist dies die Position des Parameters, beginnend mit 1 (1-indiziert).

`var`

  Der Name der PHP-Variable, die an den Parameter der SQL-Anweisung gebunden werden soll.

`type`

  Ein expliziter Datentyp für den Parameter, der durch eine der `PDO::PARAM_*`-Konstanten angegeben wird. Soll ein INOUT-Parameter von einer gespeicherten Prozedur zurückgegeben werden, muss der bitweise OR-Operator verwendet werden, um die `PDO::PARAM_INPUT_OUTPUT`-Bits für den Parameter `type` zu setzen.

`maxLength`

  Die Länge des Datentyps. Um anzuzeigen, dass ein Parameter ein OUT-Parameter einer gespeicherten Prozedur ist, muss die Länge explizit angegeben werden; nur sinnvoll, wenn der Parameter `type` `PDO::PARAM_INPUT_OUTPUT` ist.

`driverOptions`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Ausführen einer vorbereiteten Anweisung mit benannten Platzhaltern

    <?php
    /* Ausführen einer vorbereiteten Anweisung durch Binden von PHP-Variablen */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');
    $sth->bindParam('calories', $calories, PDO::PARAM_INT);
    /* Den Namen kann auch ein Doppelpunkt ":" vorangestellt werden (optional) */
    $sth->bindParam(':colour', $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

Beispiel #2 Ausführen einer vorbereiteten Anweisung mit Fragezeichen-Platzhaltern

    <?php
    /* Ausführen einer vorbereiteten Anweisung durch Binden von PHP-Variablen */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindParam(2, $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

Beispiel #3 Aufrufen einer gespeicherten Prozedur mit einem INOUT-Parameter

    <?php
    /* Aufrufen einer gespeicherten Prozedur mit einem INOUT-Parameter */
    $colour = 'rot';
    $sth = $dbh->prepare('CALL puree_fruit(?)');
    $sth->bindParam(1, $colour, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 12);
    $sth->execute();
    print "Nach dem Pürieren der Früchte, ist die Farbe: $colour";
    ?>

### Siehe auch

- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::execute() - Führt ein Prepared Statement aus
- PDOStatement::bindValue() - Bindet einen Wert an einen Parameter

# PDOStatement::bindValue

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

PDOStatement::bindValue — Bindet einen Wert an einen Parameter

### Beschreibung

public function PDOStatement::bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool

Bindet einen Wert an den entsprechend benannten oder durch ein Fragezeichen gekennzeichneten Platzhalter in der SQL-Anweisung, die zur Vorbereitung der Anweisung verwendet wurde.

### Parameter-Liste

`param`

  Der Bezeichner des Parameters. Bei einer vorbereiteten Anweisung, die benannte Platzhalter verwendet, ist dies ein Parametername der Form :name. Bei einer vorbereiteten Anweisung mit Fragezeichen-Platzhaltern ist dies die Position des Parameters, beginnend mit 1 (1-indiziert).

`value`

  Der Wert, der an den Parameter gebunden werden soll.

`type`

  Ein expliziter Datentyp für den Parameter, der durch eine der `PDO::PARAM_*`-Konstanten angegeben wird.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Ausführen einer vorbereiteten Anweisung mit benannten Platzhaltern

    <?php
    /* Ausführen einer vorbereiteten Anweisung durch Binden von PHP-Variablen */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');

    /* Setzt den Wert eines Parameters anhand seines Namens */
    $sth->bindValue('calories', $calories, PDO::PARAM_INT);
    /* Optional kann dem Namen auch ein Doppelpunkt ":" vorangestellt werden */
    $sth->bindValue(':colour', $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

Beispiel #2 Ausführen einer vorbereiteten Anweisung mit Fragezeichen-Platzhaltern

    <?php
    /* Ausführen einer vorbereiteten Anweisung durch Binden von PHP-Variablen */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindValue(1, $calories, PDO::PARAM_INT);
    $sth->bindValue(2, $colour, PDO::PARAM_STR);
    $sth->execute();
    ?>

### Siehe auch

- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::execute() - Führt ein Prepared Statement aus
- PDOStatement::bindParam() - Bindet einen Parameter an den angegebenen Variablennamen

# PDOStatement::closeCursor

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::closeCursor — Schließt den Cursor, damit die Anweisung erneut ausgeführt werden kann

### Beschreibung

public function PDOStatement::closeCursor(): bool

PDOStatement::closeCursor() gibt die Verbindung zum Server frei, damit andere SQL-Anweisungen ausgeführt werden können, belässt die Anweisung aber in einem Zustand, in dem sie erneut ausgeführt werden kann.

Diese Methode ist nützlich für Datenbanktreiber, die die Ausführung eines PDOStatement-Objekts nicht unterstützen, wenn ein zuvor ausgeführtes PDOStatement-Objekt noch nicht abgrufene Zeilen enthält. Wenn der Datenbanktreiber diese Einschränkung aufweist, kann es zu einem Out-of-Sequence-Fehler kommen.

PDOStatement::closeCursor() ist entweder als optionale treiberspezifische Methode implementiert (für maximale Effizienz), oder als generischer PDO-Fallback, wenn keine treiberspezifische Funktion installiert ist. Der generische PDO-Fallback ist semantisch dasselbe wie der folgende Code in einem PHP-Skript:

    <?php
    do {
        while ($stmt->fetch())
            ;
        if (!$stmt->nextRowset())
            break;
    } while (true);
    ?>

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 PDOStatement::closeCursor()-Beispiel

Im folgenden Beispiel gibt das PDOStatement-Objekt $stmt mehrere Zeilen zurück, aber die Anwendung ruft nur die erste Zeile ab, wodurch das PDOStatement-Objekt in einem Zustand mit nicht abgerufenen Zeilen verbleibt. Um sicherzustellen, dass die Anwendung mit allen Datenbanktreibern funktioniert, wird hier PDOStatement::closeCursor() für $stmt aufgerufen, bevor das PDOStatement-Objekt $otherStmt ausgeführt wird.

    <?php
    /* Erstellen eines PDOStatement-Objekts */
    $stmt = $dbh->prepare('SELECT foo FROM bar');

    /* Erstellen eines zweiten PDOStatement-Objekts */
    $otherStmt = $dbh->prepare('SELECT foobaz FROM foobar');

    /* Ausführen der ersten Anweisung */
    $stmt->execute();

    /* Nur die erste Zeile der Ergebnisse wird abgerufen */
    $stmt->fetch();

    /* Bei manchen Treibern kann der folgende Aufruf von closeCursor() erforderlich sein */
    $stmt->closeCursor();

    /* Nun kann die zweite Anweisung ausgeführt werden */
    $otherStmt->execute();
    ?>

### Siehe auch

- PDOStatement::execute() - Führt ein Prepared Statement aus

# PDOStatement::columnCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::columnCount — Liefert die Anzahl der Spalten in der Ergebnismenge

### Beschreibung

public function PDOStatement::columnCount(): int

PDOStatement::columnCount() gibt die Anzahl der Spalten in der Ergebnismenge zurück, die durch das PDOStatement-Objekt repräsentiert wird.

Wenn das PDOStatement-Objekt von PDO::query() zurückgegeben wurde, ist die Anzahl der Spalten sofort verfügbar.

Wurde das PDOStatement-Objekt von PDO::prepare() zurückgegeben, ist die genaue Anzahl der Spalten erst verfügbar, nachdem PDOStatement::execute() aufgerufen wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Spalten in der Ergebnismenge zurück, die durch das PDOStatement-Objekt repräsentiert wird, auch wenn die Ergebnismenge leer ist. Wenn es keine Ergebnismenge gibt, gibt PDOStatement::columnCount() `0` zurück.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Zählen der Spalten

In diesem Beispiel wird gezeigt, wie PDOStatement::columnCount() mit und ohne Ergebnismenge funktioniert.

    <?php
    $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");

    /* Zählen der Anzahl der Spalten in der (nicht vorhandenen) Ergebnismenge */
    $colcount = $sth->columnCount();
    print "Vor execute() hat die Ergebnismenge $colcount Spalten (sollte 0 sein)\n";

    $sth->execute();

    /* Zählen der Anzahl der Spalten in der Ergebnismenge */
    $colcount = $sth->columnCount();
    print "Nach execute() hat die Ergebnismenge $colcount Spalten (sollte 2 sein)\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Vor execute() hat die Ergebnismenge 0 Spalten (sollte 0 sein)
    Nach execute() hat die Ergebnismenge 2 Spalten (sollte 2 sein)

### Siehe auch

- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::execute() - Führt ein Prepared Statement aus
- PDOStatement::rowCount() - Liefert die Anzahl der von der letzten SQL-Anweisung betroffenen Zeilen

# PDOStatement::debugDumpParams

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::debugDumpParams — Gibt Informationen über einen vorbereiteten SQL-Befehl aus

### Beschreibung

public function PDOStatement::debugDumpParams(): ?bool

Scheibt die in einer vorbereiteten Anweisung enthaltenen Informationen direkt in die Ausgabe. Ausgegeben werden die verwendete `SQL`-Abfrage, die Anzahl der verwendeten Parameter (`Params`), die Liste der Parameter mit ihrem Schlüsselnamen oder ihrer Position, ihren Namen, ihre Position in der Abfrage (falls dies vom PDO-Treiber unterstützt wird, andernfalls ist es -1), ihren Typ (`param_type`) als Ganzzahl und einen booleschen Wert `is_param`.

Dies ist eine Debug-Funktion, die die Daten direkt in die normale Ausgabe schreibt.

Tipp

Bei allem, dessen Ergebnisausgabe direkt im Browser angezeigt wird, können Sie die Funktionen zur Ausgabesteuerung verwenden. Damit lässt sich die Ausgabe dieser Funktion erfassen, und - zum Beispiel - in einem string speichern.

Hierbei werden nur die Parameter ausgegeben, die zum Zeitpunkt der Ausgabe in der Anweisung enthalten sind. Überzählige Parameter werden nicht in der Anweisung gespeichert und daher auch nicht angezeigt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `null` zurück oder `false`, wenn ein Fehler aufgetreten ist.

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | PDOStatement::debugDumpParams() gibt nun den an die Datenbank gesendeten SQL-Befehl zurück, einschließlich der vollständigen, rohen Abfrage (einschließlich der ersetzten Platzhalter mit ihren gebundenen Werten). Zu beachten ist, dass dies nur zur Verfügung steht, wenn emulierte vorbereitete Anweisungen aktiviert sind.

### Beispiele

Beispiel #1 PDOStatement::debugDumpParams()-Beispiel mit benannten Parametern

    <?php
    /* Ausführen einer vorbereiteten Anweisung durch Binden von PHP-Variablen */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');
    $sth->bindParam(':calories', $calories, PDO::PARAM_INT);
    $sth->bindValue(':colour', $colour, PDO::PARAM_STR, 12);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    SQL: [96] SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour
    Params:  2
    Key: Name: [9] :calories
    paramno=-1
    name=[9] ":calories"
    is_param=1
    param_type=1
    Key: Name: [7] :colour
    paramno=-1
    name=[7] ":colour"
    is_param=1
    param_type=2

Beispiel #2 PDOStatement::debugDumpParams()-Beispiel mit Fragezeichen-Parametern

    <?php

    /* Ausführen einer vorbereiteten Anweisung durch Binden von PHP-Variablen */
    $calories = 150;
    $colour = 'red';
    $name = 'apple';

    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindValue(2, $colour, PDO::PARAM_STR);
    $sth->execute();

    $sth->debugDumpParams();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    SQL: [82] SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?
    Params:  2
    Key: Position #0:
    paramno=0
    name=[0] ""
    is_param=1
    param_type=1
    Key: Position #1:
    paramno=1
    name=[0] ""
    is_param=1
    param_type=2

### Siehe auch

- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::bindParam() - Bindet einen Parameter an den angegebenen Variablennamen
- PDOStatement::bindValue() - Bindet einen Wert an einen Parameter

# PDOStatement::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorCode — Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Anweisungs-Handle verknüpft ist

### Beschreibung

public function PDOStatement::errorCode(): ?string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Entspricht PDO::errorCode(), mit dem Unterschied, dass PDOStatement::errorCode() nur Fehlercodes für Operationen mit PDOStatement-Objekten abfragt.

### Beispiele

Beispiel #1 Abrufen eines SQLSTATE-Codes

    <?php
    /* Auslösen eines Fehlers - die Tabelle BONES existiert nicht */
    $err = $dbh->prepare('SELECT skull FROM bones');
    $err->execute();

    echo "\nPDOStatement::errorCode(): ";
    print $err->errorCode();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    PDOStatement::errorCode(): 42S02

### Siehe auch

- PDO::errorCode() - Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Datenbank-Handle verknüpft ist
- PDO::errorInfo() - Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Datenbank-Handle verknüpft sind
- PDOStatement::errorInfo() - Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Anweisungs-Handle verknüpft sind

# PDOStatement::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorInfo — Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Anweisungs-Handle verknüpft sind

### Beschreibung

public function PDOStatement::errorInfo(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

PDOStatement::errorInfo() gibt ein Array mit Informationen über den Fehler zurück, der bei der letzten über dieses Anweisungs-Handle durchgeführte Operation aufgetreten ist. Das Array besteht mindestens aus den folgenden Feldern:

Element | Information
--- | ---
0 | SQLSTATE-Fehlercode (eine fünfstellige alphanumerische Kennung, die im ANSI-SQL-Standard definiert ist)
1 | Treiberspezifischer Fehlercode
2 | Treiberspezifische Fehlermeldung

### Beispiele

Beispiel #1 Anzeigen der errorInfo()-Felder einer PDO_ODBC-Verbindung zu einer DB2-Datenbank

    <?php
    /* Auslösen eines Fehlers - die Tabelle BONES existiert nicht */
    $sth = $dbh->prepare('SELECT skull FROM bones');
    $sth->execute();

    echo "\nPDOStatement::errorInfo():\n";
    $arr = $sth->errorInfo();
    print_r($arr);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    PDOStatement::errorInfo():
    Array
    (
        [0] => 42S02
        [1] => -204
        [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N  "DANIELS.BONES" is an undefined name.  SQLSTATE=42704
    )

### Siehe auch

- PDO::errorCode() - Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Datenbank-Handle verknüpft ist
- PDO::errorInfo() - Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Datenbank-Handle verknüpft sind
- PDOStatement::errorCode() - Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Anweisungs-Handle verknüpft ist

# PDOStatement::execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::execute — Führt ein Prepared Statement aus

### Beschreibung

public function PDOStatement::execute(?array `$params` = `null`): bool

Führt das Prepared Statement aus. Falls das Prepared Statement Parameter-Marker enthält, muss entweder:

- PDOStatement::bindParam() und/oder PDOStatement::bindValue() müssen aufgerufen werden, um Variablen bzw. Werte an die Parameter-Marker zu binden. Gebundene Variablen übergeben ihren Wert als Eingabe und erhalten, falls vorhanden, den Ausgabewert ihrer zugehörigen Parameter-Marker.

- oder ein Array mit Nur-Eingabe-Parameterwerten übergeben werden.

### Parameter-Liste

`params`

  Ein Array von Werten mit so vielen Elementen, wie es gebundene Parameter in der auszuführenden SQL-Anweisung gibt. Alle Werte werden als `PDO::PARAM_STR` behandelt.

  An einen einzelnen Paramter können nicht mehrere Werte gebunden werden; es ist z. B. nicht gestattet, zwei Werte an einen einzelnen benannten Parameter in einer IN()-Klausel zu binden.

  Mehr Werte zu binden als festgelegt ist nicht möglich; wenn `params` mehr Parameter enthält als in PDO::prepare() definiert wurden, wird die Anweisung fehlschlagen und ein Fehler wird ausgegeben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Ein Prepared Statement mit Variablen- und Wertebindung ausführen

    <?php
    /* Ein Prepared Statement ausführen, in dem Variable und Wert zugewiesen werden */
    $calories = 150;
    $colour = 'gre';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour LIKE :colour');
    $sth->bindParam('calories', $calories, PDO::PARAM_INT);
    /* Den Namen können auch Doppelpunkte ":" vorangestellt werden (optional) */
    $sth->bindValue(':colour', "%$colour%");
    $sth->execute();
    ?>

Beispiel #2 Ein Prepared Statement mit einem Array von benannten Eingabewerten ausführen

    <?php
    /* Ein Prepared Statement ausführen, indem ein Array von Eingabewerten übergeben wird */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < :calories AND colour = :colour');
    $sth->execute(array('calories' => $calories, 'colour' => $colour));
    /* Den Array-Schlüsseln können auch Doppelpunkte ":" vorangestellt werden (optional) */
    $sth->execute(array(':calories' => $calories, ':colour' => $colour));
    ?>

Beispiel #3 Ein Prepared Statement mit einem Array von Positionswerten ausführen

    <?php
    /* Ein Prepared Statement ausführen, indem ein Array von Eingabewerten übergeben wird */
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->execute(array($calories, $colour));
    ?>

Beispiel #4 Ein Prepared Statement mit Variablen ausführen, die an positionale Platzhalter gebunden sind

    <?php
    /* Ein Prepared Statement durch das binden von PHP-Variablen ausführen*/
    $calories = 150;
    $colour = 'red';
    $sth = $dbh->prepare('SELECT name, colour, calories
        FROM fruit
        WHERE calories < ? AND colour = ?');
    $sth->bindParam(1, $calories, PDO::PARAM_INT);
    $sth->bindParam(2, $colour, PDO::PARAM_STR, 12);
    $sth->execute();
    ?>

Beispiel #5 Ein Prepared Statement mit einem Array für eine IN-Klausel ausführen

    <?php
    /* Führt ein Prepared Statement mit einem Array für eine IN-Klausel aus */
    $params = array(1, 21, 63, 171);
    /* Erstelle einen String für die Parameter-Platzhalter, gefüllt bis zur Anzahl Parameter */
    $place_holders = '?' . str_repeat(', ?', count($params) - 1);

    /*
        Das bereitet das Statement mit genügend unbenannten Platzhaltern
        für jeden Wert in unserem $params-Array vor. Die Werte aus dem
        $params-Array werden dann an die Platzhalter im Prepared Statement
        gebunden, wenn das Statement ausgeführt wird. Das ist nicht das
        gleiche wie PDOStatement::bindParam() zu verwenden, weil dies eine
        Referenz zur Variable benötigt. PDOStatement::execute() ordnet
        hingegen nur die Werte zu.
    */
    $sth = $dbh->prepare("SELECT id, name FROM contacts WHERE id IN ($place_holders)");
    $sth->execute($params);
    ?>

### Anmerkungen

> Hinweis:

> Manche Treiber verlangen die Ausführung von close cursor, bevor das nächste Statement ausgeführt wird.

### Siehe auch

- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::bindParam() - Bindet einen Parameter an den angegebenen Variablennamen
- PDOStatement::fetch() - Ruft die nächste Zeile aus einer Ergebnismenge ab
- PDOStatement::fetchAll() - Ruft die verbleibenden Zeilen aus einer Ergebnismenge ab
- PDOStatement::fetchColumn() - Liefert eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge

# PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — Ruft die nächste Zeile aus einer Ergebnismenge ab

### Beschreibung

public function PDOStatement::fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed

Ruft eine Zeile aus einer Ergebnismenge ab, die mit einem PDOStatement-Objekt verknüpft ist. Der Parameter `mode` bestimmt, wie PDO die Zeile zurückgibt.

### Parameter-Liste

`mode`

  Legt fest, wie die nächste Zeile an die aufrufende Methode zurückgegeben werden soll. Dieser Wert muss eine der `PDO::FETCH_*`-Konstanten sein. Voreingestellt ist `PDO::ATTR_DEFAULT_FETCH_MODE` (das standardmäßig auf `PDO::FETCH_BOTH` gesetzt ist).

  - `PDO::FETCH_ASSOC`: gibt ein Array zurück, das durch die Spaltennamen der Ergebnismenge indiziert ist.

  - `PDO::FETCH_BOTH` (Voreinstellung): gibt ein Array zurück, das sowohl durch die Spaltennamen der Ergebnismenge als auch durch deren Spaltennummern (beginnend bei 0) indiziert ist.

  - `PDO::FETCH_BOUND`: gibt `true` zurück und weist die Werte der Spalten der Ergebnismenge den PHP-Variablen zu, an die sie mit der Methode PDOStatement::bindColumn() gebunden wurden.

  - `PDO::FETCH_CLASS`: gibt eine neue Instanz der angeforderten Klasse zurück. Das Objekt wird initialisiert, indem die Spalten der Ergebnismenge den Eigenschaften der Klasse zugewiesen werden. Dies geschieht vor dem Aufruf des Konstruktors und erlaubt die Belegung von Eigenschaften unabhängig von ihrer Sichtbarkeit oder davon, ob sie als `readonly` markiert sind. Wenn eine Eigenschaft in der Klasse nicht existiert, wird die magische Methode __set() aufgerufen, falls sie existiert; andernfalls wird eine dynamische öffentliche Eigenschaft erstellt. Wenn jedoch auch `PDO::FETCH_PROPS_LATE` angegeben ist, wird der Konstruktor vor dem Belegen der Eigenschaften aufgerufen. Wenn `mode` das Attribut `PDO::FETCH_CLASSTYPE` enthält (z. B. `PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE`), wird der Name der Klasse aus einem Wert der ersten Spalte ermittelt.

  - `PDO::FETCH_INTO`: aktualisiert eine bestehende Instanz der angeforderten Klasse, wobei die Spalten der Ergebnismenge den benannten Eigenschaften der Klasse zugeordnet werden.

  - `PDO::FETCH_LAZY`: kombiniert `PDO::FETCH_BOTH` und `PDO::FETCH_OBJ` und gibt ein PDORow-Objekt zurück, das die Eigenschaftsnamen des Objekts erstellt, wenn auf sie zugegriffen wird.

  - `PDO::FETCH_NAMED`: gibt ein Array zurück, das die gleiche Form hat wie `PDO::FETCH_ASSOC`. Wenn es jedoch mehrere Spalten mit demselben Namen gibt, ist der Wert, auf den der betreffende Schlüssel verweist, ein Array mit allen Werten in der Zeile, die diesen Spaltennamen hatten.

  - `PDO::FETCH_NUM`: gibt ein Array zurück, das durch die Spaltennummer aus der Ergebnismenge indiziert ist (beginnend bei Spalte 0).

  - `PDO::FETCH_OBJ`: gibt ein anonymes Objekt mit Eigenschaftsnamen zurück, die den Spaltennamen aus der Ergebnismenge entsprechen.

  - `PDO::FETCH_PROPS_LATE`: in Kombination mit `PDO::FETCH_CLASS` wird der Konstruktor der Klasse aufgerufen, bevor die Eigenschaften aus den jeweiligen Spaltenwerten zugewiesen werden.

`cursorOrientation`

  Bei einem PDOStatement-Objekt, das einen scrollbaren Cursor repräsentiert, bestimmt dieser Wert, welche Zeile an die aufrufende Methode zurückgegeben werden soll. Dieser Wert muss eine der `PDO::FETCH_ORI_*`-Konstanten sein, wobei `PDO::FETCH_ORI_NEXT` voreingestellt ist. Wenn die SQL-Anweisung mit PDO::prepare() vorbereitet wird, muss das Attribut `PDO::ATTR_CURSOR` auf `PDO::CURSOR_SCROLL` gesetzt werden, um einen scrollbaren Cursor für das PDOStatement-Objekt zu erhalten.

`cursorOffset`

  Bei einem PDOStatement-Objekt, das einen scrollbaren Cursor repräsentiert, dessen Parameter `cursorOrientation` auf `PDO::FETCH_ORI_ABS` gesetzt ist, gibt dieser Wert die absolute Nummer der Zeile in der Ergebnismenge an, die abgerufen werden soll.

  Bei einem PDOStatement-Objekt, das einen scrollbaren Cursor repräsentiert, dessen Parameter `cursorOrientation` auf `PDO::FETCH_ORI_REL` gesetzt ist, gibt dieser Wert die abzurufende Zeile relativ zur Position des Zeigers vor dem Aufruf von PDOStatement::fetch() an.

### Rückgabewerte

Bei Erfolg hängt der Rückgabewert dieser Funktion von der Art des Abrufs ab. Bei einem Fehler oder wenn es keine weiteren Zeilen gibt, wird in jedem Fall `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Abrufen von Zeilen mit verschiedenen Arten des Abrufs

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Beispiele für die verschiedenen Arten von PDOStatement::fetch */
    print "PDO::FETCH_ASSOC: ";
    print "Die nächste Zeile als Array zurückgeben, das durch den Spaltennamen indiziert ist\n";
    $Ergebnis = $sth->fetch(PDO::FETCH_ASSOC);
    print_r($result);
    print "\n";

    print "PDO::FETCH_BOTH: ";
    print "Die nächste Zeile als Array zurückgeben, das sowohl durch den Spaltennamen als auch durch die Spaltennummer indiziert ist\n";
    $Ergebnis = $sth->fetch(PDO::FETCH_BOTH);
    print_r($result);
    print "\n";

    print "PDO::FETCH_LAZY: ";
    print "Die nächste Zeile als PDORow-Objekt mit den Spaltennamen als Eigenschaften zurückgeben\n";
    $Ergebnis = $sth->fetch(PDO::FETCH_LAZY);
    print_r($result);
    print "\n";

    print "PDO::FETCH_OBJ: ";
    print "Die nächste Zeile als PDORow-Objekt mit den Spaltennamen als Eigenschaften zurückgeben\n";
    $result = $sth->fetch(PDO::FETCH_OBJ);
    print $result->name;
    print "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    PDO::FETCH_ASSOC: Die nächste Zeile als Array zurückgeben, das durch den Spaltennamen indiziert ist
    Array
    (
        [name] => apple
        [colour] => red
    )

    PDO::FETCH_BOTH: Die nächste Zeile als Array zurückgeben, das sowohl durch den Spaltennamen als auch durch die Spaltennummer indiziert ist
    Array
    (
        [name] => banana
        [0] => banana
        [colour] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Die nächste Zeile als anonymes Objekt mit den Spaltennamen als Eigenschaften zurückgeben
    PDORow Object
    (
        [name] => orange
        [colour] => orange
    )

    PDO::FETCH_OBJ: Die nächste Zeile als anonymes Objekt mit den Spaltennamen als Eigenschaften zurückgeben
    kiwi

Beispiel #2 Abrufen von Zeilen mittels scrollbarem Cursor

    <?php
    function readDataForwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        }
    }
    function readDataBackwards($dbh) {
        $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
        do {
            $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
            print $data;
        } while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
    }

    print "Vorwärts ausgelesen:\n";
    readDataForwards($conn);

    print "Rückwärts ausgelesen:\n";
    readDataBackwards($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Vorwärts ausgelesen:
    21    10    5
    16    0     5
    19    20    10

    Rückwärts ausgelesen:
    19    20    10
    16    0     5
    21    10    5

Beispiel #3 Reihenfolge der Konstruktion

Wenn Objekte über `PDO::FETCH_CLASS` abgerufen werden, werden zuerst die Objekteigenschaften zugewiesen und dann der Konstruktor der Klasse aufgerufen. Wenn jedoch zusätzlich `PDO::FETCH_PROPS_LATE` angegeben wird, wird diese Reihenfolge umgekehrt, d. h. zuerst wird der Konstruktor aufgerufen und danach werden die Eigenschaften zugewiesen.

    <?php
    class Person
    {
        private $name;

        public function __construct()
        {
            $this->tell();
        }

        public function tell()
        {
            if (isset($this->name)) {
                echo "Ich heiße {$this->name}.\n";
            } else {
                echo "Ich habe noch keinen Namen.\n";
            }
        }
    }

    $sth = $dbh->query("SELECT * FROM people");
    $sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
    $person = $sth->fetch();
    $person->tell();
    $sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
    $person = $sth->fetch();
    $person->tell();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Ich heiße Alice.
    Ich heiße Alice.
    Ich habe noch keinen Namen.
    Ich heiße Bob.

### Siehe auch

- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::execute() - Führt ein Prepared Statement aus
- PDOStatement::fetchAll() - Ruft die verbleibenden Zeilen aus einer Ergebnismenge ab
- PDOStatement::fetchColumn() - Liefert eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge
- PDOStatement::fetchObject() - Ruft die nächste Zeile ab und liefert sie als Objekt
- PDOStatement::setFetchMode() - Legt den standardmäßigen Abrufmodus eine Anweisung fest

# PDOStatement::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetchAll — Ruft die verbleibenden Zeilen aus einer Ergebnismenge ab

### Beschreibung

public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array

### Parameter-Liste

`mode`

  Legt die Struktur des zurückgegebenen Arrays fest, wie in PDOStatement::fetch() dokumentiert. Voreingestellt ist `PDO::ATTR_DEFAULT_FETCH_MODE` (das standardmäßig auf `PDO::FETCH_BOTH` gesetzt ist).

  Damit ein Array zurückgegeben wird, das aus allen Werten einer einzelnen Spalte der Ergebnismenge besteht, muss `PDO::FETCH_COLUMN` verwendet werden. Die gewünschte Spalte kann mit dem Parameter `column` angegeben werden.

  Um das resultierende Array mit dem Wert einer bestimmten Spalte zu indizieren (anstatt mit fortlaufenden Zahlen), muss der Name dieser Spalte in SQL an erster Stelle der Liste der Spalten stehen und `PDO::FETCH_UNIQUE` verwendet werden. Diese Spalte darf nur eindeutige Werte enthalten, da sonst einige Daten verloren gehen.

  Um die Ergebnisse in Form eines dreidimensionalen Arrays zu gruppieren, das durch die Werte einer bestimmten Spalte indiziert ist, muss der Name dieser Spalte in SQL an erster Stelle der Liste der Spalten stehen und `PDO::FETCH_GROUP` verwendet werden.

  Um Ergebnisse in Form eines 2-dimensionalen Arrays zu gruppieren, muss die bitweise ODER-Verknüpfung von `PDO::FETCH_GROUP` und `PDO::FETCH_COLUMN` verwendet werden. Die Ergebnisse werden nach der ersten Spalte gruppiert, wobei der Wert des Array-Elements ein Listen-Array mit den entsprechenden Einträgen der zweiten Spalte ist.

Bei den folgenden Parametern handelt es sich um dynamische Parameter, die vom Abrufmodus abhängig sind. Sie können nicht in Verbindung mit benannten Parametern verwendet werden.

`column`

  Wird zusammen mit `PDO::FETCH_COLUMN` verwendet. Gibt die angegebene Spalte zurück (der Index beginnt bei 0).

`class`

  Wird zusammen mit `PDO::FETCH_CLASS` verwendet. Gibt Instanzen der angegebenen Klasse zurück, wobei die Spalten jeder Zeile auf benannte Eigenschaften der Klasse abgebildet werden.

`constructorArgs`

  Argumente des benutzerdefinierten Klassenkonstruktors, wenn der Parameter `mode` auf `PDO::FETCH_CLASS` gesetzt ist.

`callback`

  Wird zusammen mit `PDO::FETCH_FUNC` verwendet. Gibt die Ergebnisse des angegebenen Funktionsaufrufs zurück, wobei die Spalten jeder Zeile als Parameter für den Aufruf verwendet werden.

### Rückgabewerte

PDOStatement::fetchAll() gibt ein Array zurück, das die restlichen Zeilen der Ergebnismenge enthält. Das Array enthält jede Zeile entweder als Array von Spaltenwerten oder als Objekt mit Eigenschaften, die den einzelnen Spaltennamen entsprechen. Wenn es keine Ergebnisse gibt, die abgerufen werden können, wird ein leeres Array zurückgegeben.

Wenn diese Methode verwendet wird, um große Ergebnismengen abzurufen, kann dies zu einer hohen Beanspruchung der System- und Netzwerkressourcen führen. Anstatt alle Daten abzurufen und in PHP zu bearbeiten, sollte in Betracht gezogen werden, den Datenbankserver für die Bearbeitung der Ergebnismengen zu verwenden. Zum Beispiel könnten WHERE- und ORDER BY-Klauseln in SQL verwendet werden, um die Ergebnismenge einzuschränken, bevor sie mit PHP abgerufen und verarbeitet wird.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Methode gibt nun immer ein Array zurück, während zuvor bei einem Fehler möglicherweise `false` zurückgegeben wurde.

### Beispiele

Beispiel #1 Abrufen der restlichen Zeilen einer Ergebnismenge

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Abrufen der restlichen Zeilen der Ergebnismenge */
    print "Abrufen der restlichen Zeilen der Ergebnismenge:\n";
    $result = $sth->fetchAll();
    print_r($result);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Abrufen der restlichen Zeilen der Ergebnismenge:
    Array
    (
        [0] => Array
            (
                [name] => apple
                [0] => apple
                [colour] => red
                [1] => red
            )

        [1] => Array
            (
                [name] => pear
                [0] => pear
                [colour] => green
                [1] => green
            )

        [2] => Array
            (
                [name] => watermelon
                [0] => watermelon
                [colour] => pink
                [1] => pink
            )

    )

Beispiel #2 Abrufen aller Werte einer einzelnen Spalte einer Ergebnismenge

Das folgende Beispiel zeigt, wie alle Werte einer einzelnen Spalte aus einer Ergebnismenge abgerufen werden können, auch wenn die SQL-Anweisung selbst mehrere Spalten pro Zeile zurückgibt.

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Abrufen aller Werte der ersten Spalte */
    $result = $sth->fetchAll(PDO::FETCH_COLUMN, 0);
    var_dump($result);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array(3)
    (
        [0] =>
        string(5) => apple
        [1] =>
        string(4) => pear
        [2] =>
        string(10) => watermelon
    )

Beispiel #3 Gruppieren aller Werte nach einer einzelnen Spalte

Das folgende Beispiel zeigt, wie ein assoziatives Array abgerufen werden kann, das nach den Werten der angegebenen Spalte in der Ergebnismenge gruppiert ist. Das Array enthält drei Schlüssel: Die Werte `apple` und `pear` werden als Arrays zurückgegeben, die zwei verschiedene Farben enthalten, während `watermelon` als Array zurückgegeben wird, das nur eine Farbe enthält.

    <?php
    $insert = $dbh->prepare("INSERT INTO fruit(name, colour) VALUES (?, ?)");
    $insert->execute(array('apple', 'green'));
    $insert->execute(array('pear', 'yellow'));

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Gruppieren der Werte nach der ersten Spalte */
    var_dump($sth->fetchAll(PDO::FETCH_COLUMN|PDO::FETCH_GROUP));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(3) {
      ["apple"]=>
      array(2) {
        [0]=>
        string(5) "green"
        [1]=>
        string(3) "red"
      }
      ["pear"]=>
      array(2) {
        [0]=>
        string(5) "green"
        [1]=>
        string(6) "yellow"
      }
      ["watermelon"]=>
      array(1) {
        [0]=>
        string(5) "pink"
      }
    }

Beispiel #4 Instanziieren einer Klasse für jedes Ergebnis

Das folgende Beispiel zeigt das Verhalten im Modus `PDO::FETCH_CLASS`.

    <?php
    class fruit {
        public $name;
        public $colour;
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_CLASS, "fruit");
    var_dump($result);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(3) {
      [0]=>
      object(fruit)#1 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(5) "green"
      }
      [1]=>
      object(fruit)#2 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(6) "yellow"
      }
      [2]=>
      object(fruit)#3 (2) {
        ["name"]=>
        string(10) "watermelon"
        ["colour"]=>
        string(4) "pink"
      }
      [3]=>
      object(fruit)#4 (2) {
        ["name"]=>
        string(5) "apple"
        ["colour"]=>
        string(3) "red"
      }
      [4]=>
      object(fruit)#5 (2) {
        ["name"]=>
        string(4) "pear"
        ["colour"]=>
        string(5) "green"
      }
    }

Beispiel #5 Aufrufen einer Funktion für jedes Ergebnis

Das folgende Beispiel zeigt das Verhalten im Modus `PDO::FETCH_FUNC`.

    <?php
    function fruit($name, $colour) {
        return "{$name}: {$colour}";
    }

    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    $result = $sth->fetchAll(PDO::FETCH_FUNC, "fruit");
    var_dump($result);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(3) {
      [0]=>
      string(12) "apple: green"
      [1]=>
      string(12) "pear: yellow"
      [2]=>
      string(16) "watermelon: pink"
      [3]=>
      string(10) "apple: red"
      [4]=>
      string(11) "pear: green"
    }

### Siehe auch

- PDO::query() - Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus
- PDOStatement::fetch() - Ruft die nächste Zeile aus einer Ergebnismenge ab
- PDOStatement::fetchColumn() - Liefert eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge
- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::setFetchMode() - Legt den standardmäßigen Abrufmodus eine Anweisung fest

# PDOStatement::fetchColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::fetchColumn — Liefert eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge

### Beschreibung

public function PDOStatement::fetchColumn(int `$column` = 0): mixed

Gibt eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge zurück oder `false`, wenn es keine weiteren Zeilen gibt.

> Hinweis:

> PDOStatement::fetchColumn() sollte nicht verwendet werden, um boolesche Spalten abzurufen, da nicht unterschieden werden kann, ob der Wert `false` ist oder ob keine weiteren Zeilen abgerufen werden können. Stattdessen sollte PDOStatement::fetch() verwendet werden.

### Parameter-Liste

`column`

  Die Nummer der Spalte (beginnend bei 0), die aus der Zeile abgerufen werden soll. Wenn kein Wert angegeben wird, ruft PDOStatement::fetchColumn() die erste Spalte ab.

### Rückgabewerte

PDOStatement::fetchColumn() gibt eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge zurück oder `false`, wenn es keine weiteren Zeilen gibt.

Warnung

Wenn Daten mittels PDOStatement::fetchColumn() abgerufen werden, gibt es keine Möglichkeit, eine andere Spalte aus derselben Zeile abzurufen.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Abrufen der ersten Spalte aus der nächsten Zeile

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    print "Abrufen der ersten Spalte aus der ersten Zeile der Ergebnismenge:\n";
    $result = $sth->fetchColumn();
    print "name = $result\n";

    print "Abrufen der zweiten Spalte aus der zweiten Zeile der Ergebnismenge:\n";
    $result = $sth->fetchColumn(1);
    print "colour = $result\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Abrufen der ersten Spalte aus der ersten Zeile der Ergebnismenge:
    name = lemon
    Abrufen der zweiten Spalte aus der zweiten Zeile der Ergebnismenge:
    colour = red

### Siehe auch

- PDO::query() - Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus
- PDOStatement::fetch() - Ruft die nächste Zeile aus einer Ergebnismenge ab
- PDOStatement::fetchAll() - Ruft die verbleibenden Zeilen aus einer Ergebnismenge ab
- PDO::prepare() - Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
- PDOStatement::setFetchMode() - Legt den standardmäßigen Abrufmodus eine Anweisung fest

# PDOStatement::fetchObject

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.4)

PDOStatement::fetchObject — Ruft die nächste Zeile ab und liefert sie als Objekt

### Beschreibung

public function PDOStatement::fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false

Ruft die nächste Zeile ab und gibt sie als Objekt zurück. Diese Funktion ist eine Alternative zu PDOStatement::fetch() in Verbindung mit `PDO::FETCH_CLASS` oder `PDO::FETCH_OBJ`.

Wenn ein Objekt abgerufen wird, werden seinen Eigenschaften die jeweiligen Werte der Spalten zugewiesen, und anschließend wird sein Konstruktor aufgerufen.

### Parameter-Liste

`class`

  Der Name der erstellten Klasse

`constructorArgs`

  Die Elemente dieses Arrays werden an den Konstruktor übergeben.

### Rückgabewerte

Gibt eine Instanz der angegebenen Klasse zurück, deren Eigenschaftsnamen den Spaltennamen entsprechen. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Siehe auch

- PDOStatement::fetch() - Ruft die nächste Zeile aus einer Ergebnismenge ab

# PDOStatement::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getAttribute — Ruft ein Attribut einer Anweisung ab

### Beschreibung

public function PDOStatement::getAttribute(int `$name`): mixed

Ruft ein Attribut einer Anweisung ab. Derzeit gibt es keine allgemeinen Attribute, sondern nur treiberspezifische:

- `PDO::ATTR_CURSOR_NAME` (spezifisch für Firebird und ODBC): Ermittelt den Namen des Cursors für `UPDATE ... WHERE CURRENT OF`.

Es ist zu beachten, dass treiberspezifische Attribute nicht zusammen mit anderen Treibern verwendet werden dürfen.

### Parameter-Liste

`name`

  Das Attribut, das abgerufen werden soll

### Rückgabewerte

Gibt den Wert des Attributs zurück.

### Siehe auch

- PDO::getAttribute() - Ruft ein Attribut einer Datenbankverbindung ab
- PDO::setAttribute() - Setzt ein Attribut
- PDOStatement::setAttribute() - Setzt ein Anweisungsattribut

# PDOStatement::getColumnMeta

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getColumnMeta — Liefert die Metadaten zu einer Spalte einer Ergebnismenge

### Beschreibung

public function PDOStatement::getColumnMeta(int `$column`): array|false

Ruft die Metadaten für eine Spalte (beginnend bei 0) einer Ergebnismenge als assoziatives Array ab.

Warnung

Da PDOStatement::getColumnMeta() optional ist, kann es sein, dass manche Treiber es nicht implementieren. Allerdings wird diese Funktion von allen im Handbuch dokumentierten PDO-Treibern implementiert.

### Parameter-Liste

`column`

  Die Spalte der Ergebnismenge (beginnend bei 0)

### Rückgabewerte

Gibt ein assoziatives Array mit den folgenden Werten zurück, die die Metadaten für eine einzelne Spalte darstellen:

Die Metadaten einer Spalte
Name | Wert
--- | ---
`native_type` | Der PHP-eigene Typ, der zur Darstellung des Spaltenwerts verwendet wird
`driver:decl_type` | Der SQL-Typ, der verwendet wird, um den Spaltenwert in der Datenbank darzustellen. Wenn die Spalte in der Ergebnismenge das Ergebnis einer Funktion ist, wird dieser Wert nicht von PDOStatement::getColumnMeta() zurückgegeben.
`flags` | Alle für diese Spalte gesetzten Flags
`name` | Der Name der Spalte, wie er von der Datenbank zurückgegeben wird
`table` | Der Name der Tabelle der Spalte, wie er von der Datenbank zurückgegeben wird
`len` | Die Breite der Spalte. Für andere Typen als Gleitkommazahlen normalerweise `-1`.
`precision` | Die numerische Genauigkeit der Spalte. Für andere Typen als Gleitkommazahlen normalerweise `0`.
`pdo_type` | Der Typ der Spalte, wie er durch die `PDO::PARAM_*`-Konstanten dargestellt wird

Gibt `false` zurück, wenn die angeforderte Spalte in der Ergebnismenge nicht vorhanden ist, oder wenn es keine Ergebnismenge gibt.

### Beispiele

Beispiel #1 Abrufen der Metadaten einer Spalte

Das folgende Beispiel zeigt das Ergebnis des Abrufs von Metadaten für eine einzelne Spalte, die von der Funktion COUNT des PDO_SQLITE-Treibers erzeugt wurde.

    <?php
    $select = $DB->query('SELECT COUNT(*) FROM fruit');
    $meta = $select->getColumnMeta(0);
    var_dump($meta);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(6) {
      ["native_type"]=>
      string(7) "integer"
      ["flags"]=>
      array(0) {
      }
      ["name"]=>
      string(8) "COUNT(*)"
      ["len"]=>
      int(-1)
      ["precision"]=>
      int(0)
      ["pdo_type"]=>
      int(2)
    }

### Siehe auch

- PDOStatement::columnCount() - Liefert die Anzahl der Spalten in der Ergebnismenge
- PDOStatement::rowCount() - Liefert die Anzahl der von der letzten SQL-Anweisung betroffenen Zeilen

# PDOStatement::getIterator

(PHP 8)

PDOStatement::getIterator — Ermittelt den Iterator der Ergebnismenge

### Beschreibung

public function PDOStatement::getIterator(): Iterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# PDOStatement::nextRowset

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::nextRowset — Rückt in einem Anweisungshandle mit mehreren Sätzen von Zeilen (Rowsets) zum nächsten vor

### Beschreibung

public function PDOStatement::nextRowset(): bool

Einige Datenbankserver unterstützen gespeicherte Prozeduren, die mehr als einen Satz von Zeilen (sog. Rowsets, auch Ergebnismenge genannt) zurückgeben. PDOStatement::nextRowset() ermöglicht den Zugriff auf den zweiten und die folgenden Sätze von Zeilen, die zu einem PDOStatement-Objekt gehören. Jeder Zeilensatz kann einen anderen Satz von Spalten haben als der vorhergehende Zeilensatz.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Abrufen mehrerer von einer gespeicherten Prozedur zurückgegebener Zeilensätze

Das folgende Beispiel zeigt, wie man eine gespeicherte Prozedur, `MULTIPLE_ROWSETS`, aufruft, die drei Zeilensätze zurückgibt. Mit einer do-while-Schleife wird die Methode PDOStatement::nextRowset() so oft aufgerufen, bis sie `false` zurückgibt, und die Schleife beendet, wenn es keine weiteren Zeilensätze mehr gibt.

    <?php
    $sql = 'CALL multiple_rowsets()';
    $stmt = $conn->query($sql);
    $i = 1;
    do {
        $rowset = $stmt->fetchAll(PDO::FETCH_NUM);
        if ($rowset) {
            printResultSet($rowset, $i);
        }
        $i++;
    } while ($stmt->nextRowset());

    function printResultSet(&$rowset, $i) {
        print "Ergebnismenge $i:\n";
        foreach ($rowset as $row) {
            foreach ($row as $col) {
                print $col . "\t";
            }
            print "\n";
        }
        print "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ergebnismenge 1:
    apple    red
    banana   yellow

    Ergebnismenge 2:
    orange   orange    150
    banana   yellow    175

    Ergebnismenge 3:
    lime     green
    apple    red
    banana   yellow

### Siehe auch

- PDOStatement::columnCount() - Liefert die Anzahl der Spalten in der Ergebnismenge
- PDOStatement::execute() - Führt ein Prepared Statement aus
- PDOStatement::getColumnMeta() - Liefert die Metadaten zu einer Spalte einer Ergebnismenge
- PDO::query() - Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus

# PDOStatement::rowCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::rowCount — Liefert die Anzahl der von der letzten SQL-Anweisung betroffenen Zeilen

### Beschreibung

public function PDOStatement::rowCount(): int

PDOStatement::rowCount() gibt die Anzahl der Zeilen zurück, die von der letzten DELETE-, INSERT- oder UPDATE-Anweisung des zugehörigen `PDOStatement`-Objekts betroffen waren.

Bei Anweisungen, die Ergebnismengen erzeugen, z. B. `SELECT`, ist das Verhalten nicht definiert und kann je nach Treiber unterschiedlich sein. Einige Datenbanken können die Anzahl der von dieser Anweisung erzeugten Zeilen zurückgeben (z. B. MySQL im gepufferten Modus), aber dieses Verhalten ist nicht für alle Datenbanken garantiert und sollte nicht für portable Anwendungen verwendet werden.

> Hinweis:

> Diese Methode gibt beim PostgreSQL-Treiber "0" (Null) zurück, wenn das Statement-Attribut `PDO::ATTR_CURSOR` auf `PDO::CURSOR_SCROLL` gesetzt ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Zeilen zurück.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_WARNING` gesetzt ist.

Löst eine PDOException aus, wenn das Attribut `PDO::ATTR_ERRMODE` auf `PDO::ERRMODE_EXCEPTION` gesetzt ist.

### Beispiele

Beispiel #1 Ermitteln der Anzahl der gelöschten Zeilen

PDOStatement::rowCount() gibt die Anzahl der Zeilen zurück, die von einer DELETE-, INSERT- oder UPDATE-Anweisung betroffen sind.

    <?php
    /* Löschen aller Zeilen aus der Tabelle FRUIT */
    $del = $dbh->prepare('DELETE FROM fruit');
    $del->execute();

    /* Rückgabe der Anzahl der gelöschten Zeilen */
    print "Rückgabe der Anzahl der gelöschten Zeilen:\n";
    $count = $del->rowCount();
    print "Es wurden $count Zeilen gelöscht.\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Rückgabe der Anzahl der gelöschten Zeilen:
    Es wurden 9 Zeilen gelöscht.

Beispiel #2 Zählen der Zeilen, die von einer SELECT-Anweisung zurückgegeben wurden

Bei den meisten Datenbanken gibt PDOStatement::rowCount() die Anzahl der von einer SELECT-Anweisung betroffenen Zeilen nicht zurück. Stattdessen sollte mittels PDO::query() eine SELECT COUNT(*)-Anweisung ausgeführt werden, die dieselben Bedingungen erfüllt wie die gewünschte SELECT-Anweisung. Mit PDOStatement::fetchColumn() kann dann die Anzahl der betroffenen Zeilen ermittelt werden.

    <?php
    $sql = "SELECT COUNT(*) FROM fruit WHERE calories > 100";
    $res = $conn->query($sql);
    $count = $res->fetchColumn();

    print "Es gibt " .  $count . " übereinstimmende Datensätze.";

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Es gibt 2 übereinstimmende Datensätze.

### Siehe auch

- PDOStatement::columnCount() - Liefert die Anzahl der Spalten in der Ergebnismenge
- PDOStatement::fetchColumn() - Liefert eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge
- PDO::query() - Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus

# PDOStatement::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setAttribute — Setzt ein Anweisungsattribut

### Beschreibung

public function PDOStatement::setAttribute(int `$attribute`, mixed `$value`): bool

Setzt ein Attribut für eine Anweisung. Derzeit werden keine allgemeinen Attribute gesetzt, sondern nur treiberspezifische:

- `PDO::ATTR_CURSOR_NAME` (spezifisch für Firebird und ODBC): setzt den Namen des Cursors für `UPDATE ... WHERE CURRENT OF`.

Es ist zu beachten, dass treiberspezifische Attribute nicht zusammen mit anderen Treibern verwendet werden dürfen.

### Parameter-Liste

`attribute`

  Das zu ändernde Attribut

`value`

  Der Wert, auf den das `attribute` gesetzt werden soll, muss je nach Attribut möglicherweise einen bestimmten Typ haben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- PDO::getAttribute() - Ruft ein Attribut einer Datenbankverbindung ab
- PDO::setAttribute() - Setzt ein Attribut
- PDOStatement::getAttribute() - Ruft ein Attribut einer Anweisung ab

# PDOStatement::setFetchMode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setFetchMode — Legt den standardmäßigen Abrufmodus eine Anweisung fest

### Beschreibung

public function PDOStatement::setFetchMode(int `$mode`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true

### Parameter-Liste

`mode`

  Der Abrufmodus muss eine der `PDO::FETCH_*`-Konstanten sein.

`colno`

  Die Nummer der Spalte

`class`

  Der Name der Klasse

`constructorArgs`

  Konstruktorargumente

`object`

  Das Objekt

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Der Rückgabewert ist nun `true`; vorher war es bool.

### Beispiele

Beispiel #1 Festlegen des Abrufmodus

Das folgende Beispiel zeigt, wie PDOStatement::setFetchMode() den standardmäßigen Abrufmodus für ein PDOStatement-Objekt ändert.

    <?php
    $stmt = $dbh->query('SELECT name, colour, calories FROM fruit');
    $stmt->setFetchMode(PDO::FETCH_NUM);
    foreach ($stmt as $row) {
        print $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
    }

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    apple   red     150
    banana  yellow  250
    orange  orange  300
    kiwi    brown   75
    lemon   yellow  25
    pear    green   150

## Inhaltsverzeichnis

- PDOStatement::bindColumn — Bindet eine Spalte an eine PHP-Variable
- PDOStatement::bindParam — Bindet einen Parameter an den angegebenen Variablennamen
- PDOStatement::bindValue — Bindet einen Wert an einen Parameter
- PDOStatement::closeCursor — Schließt den Cursor, damit die Anweisung erneut ausgeführt werden kann
- PDOStatement::columnCount — Liefert die Anzahl der Spalten in der Ergebnismenge
- PDOStatement::debugDumpParams — Gibt Informationen über einen vorbereiteten SQL-Befehl aus
- PDOStatement::errorCode — Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Anweisungs-Handle verknüpft ist
- PDOStatement::errorInfo — Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Anweisungs-Handle verknüpft sind
- PDOStatement::execute — Führt ein Prepared Statement aus
- PDOStatement::fetch — Ruft die nächste Zeile aus einer Ergebnismenge ab
- PDOStatement::fetchAll — Ruft die verbleibenden Zeilen aus einer Ergebnismenge ab
- PDOStatement::fetchColumn — Liefert eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge
- PDOStatement::fetchObject — Ruft die nächste Zeile ab und liefert sie als Objekt
- PDOStatement::getAttribute — Ruft ein Attribut einer Anweisung ab
- PDOStatement::getColumnMeta — Liefert die Metadaten zu einer Spalte einer Ergebnismenge
- PDOStatement::getIterator — Ermittelt den Iterator der Ergebnismenge
- PDOStatement::nextRowset — Rückt in einem Anweisungshandle mit mehreren Sätzen von Zeilen (Rowsets) zum nächsten vor
- PDOStatement::rowCount — Liefert die Anzahl der von der letzten SQL-Anweisung betroffenen Zeilen
- PDOStatement::setAttribute — Setzt ein Anweisungsattribut
- PDOStatement::setFetchMode — Legt den standardmäßigen Abrufmodus eine Anweisung fest

# Die Klasse PDORow

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## Einführung

Stellt eine Zeile aus einer Ergebnismenge dar, die von PDOStatement::fetch() im Abrufmodus `PDO_FETCH_LAZY` zurückgegeben wurde.

Objekte dieser Klasse können weder instanziiert noch serialisiert werden.

Über das PDORow-Objekt kann auf die zurückgegebenen Daten zugegriffen werden, als ob sowohl der Modus `PDO::FETCH_OBJ` als auch `PDO::FETCH_BOTH` verwendet wurde. Das bedeutet, dass auf die zurückgegebenen Daten als Objekteigenschaften und als Array zugegriffen werden kann, das sowohl durch den Spaltennamen als auch durch die Nummer des Spaltenoffsets indiziert ist.

Achtung

Wenn auf eine undefinierte Eigenschaft zugegriffen wird, wird `null` zurückgegeben, ohne dass eine Warnung ausgegeben wird.

## Klassenbeschreibung

final class PDORow {
/* Eigenschaften */
public string $queryString;
}

## Eigenschaften

queryString

  Die Abfrage-Zeichenkette, die von dem PDOStatement verwendet wurde, das das PDORow-Objekt zurückgegeben hat.

## Fehler/Exceptions

Wenn versucht wird, in eine beliebige Eigenschaft zu schreiben oder sie mittels unset() zu löschen, wird ein Error geworfen.

# Die Klasse PDOException

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## Einführung

Stellt einen Fehler dar, der von PDO ausgelöst wird. Sie sollten selbst keine PDOException in Ihrem eigenen Code auslösen. Siehe Ausnahmen für weitere Informationen über Ausnahmen in PHP.

## Klassenbeschreibung

class PDOException extends RuntimeException {
/* Eigenschaften */
protected int|string $code;
public ?array $errorInfo = null;
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Eigenschaften

errorInfo

  Entspricht PDO::errorInfo() oder PDOStatement::errorInfo()

code

  `SQLSTATE`-Fehlercode. Zugriff via Exception::getCode().

# PDO-Treiber

## Inhaltsverzeichnis

- CUBRID PDO Driver
- MS SQL Server PDO Driver
- Pdo\Dblib
- Firebird PDO Driver
- Pdo\Firebird
- IBM PDO Driver
- Informix PDO Driver
- MySQL PDO-Treiber
- Pdo\Mysql
- MS SQL Server PDO Driver
- Oracle PDO Driver
- ODBC and DB2 PDO Driver
- Pdo\Odbc
- PostgreSQL PDO Driver
- Pdo\Pgsql
- SQLite PDO-Treiber
- Pdo\Sqlite

Die folgenden Treiber implementieren momentan die PDO-Schnittstelle:

Treibername | Unterstützte Datenbanken
--- | ---
PDO_CUBRID | Cubrid
PDO_DBLIB | FreeTDS / Microsoft SQL Server / Sybase
PDO_FIREBIRD | Firebird
PDO_IBM | IBM DB2
PDO_INFORMIX | IBM Informix Dynamic Server
PDO_MYSQL | MySQL 3.x/4.x/5.x/8.x
PDO_OCI | Oracle Call Interface
PDO_ODBC | ODBC v3 (IBM DB2, unixODBC und win32 ODBC)
PDO_PGSQL | PostgreSQL
PDO_SQLITE | SQLite 3 und SQLite 2
PDO_SQLSRV | Microsoft SQL Server / SQL Azure

# CUBRID PDO Driver (PDO_CUBRID)

## Einführung

PDO_CUBRID is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to CUBRID databases.

> Hinweis: Current version of PDO_CUBRID doesn't support persistent connection now.

## Installation

To build the PDO_CUBRID extension, the CUBRID DBMS must be installed on the same system as PHP. PDO_CUBRID is a » PECL extension, so follow the instructions in Installation der PECL-Erweiterungen to install the PDO_CUBRID extension. Issue the configure command to point to the location of the CUBRID base dir as follows:

       $ ./configure --with-pdo-cubrid=/path/to/CUBRID[,shared]

The configure command defaults to the value of the CUBRID environment variable.

Eine DLL-Datei für diese PECL-Erweiterung steht derzeit nicht zur Verfügung. Weitere Details finden Sie im Abschnitt zum Kompilieren für Windows. Detailed information about installation on Linux and Windows manually, please read build-guide.html in PECL package CUBRID for reference.

## PDO_CUBRID Features

## Scrollable cursors

PDO_CUBRID supports scrollable cursors. The default cursor type is forward only, and you can use parameter driver_options in PDO::prepare() to change cursor type.

## Timeout

PDO_CUBRID supports sql statement execution timeout setting; You can use PDO::setAttribute() to set timeout value.

## Autocommit_mode and Transaction

PDO_CUBRID supports both autocommit_mode and transaction, and autocommit_mode is enabled by default. You can use PDO::setAttribute() to change its state.

If you use PDO::beginTransaction() to begin a transaction, it will disable autocommit_mode automatically and restore it after PDO::commit() or PDO::rollBack().

> Hinweis: Prior do disabling autocommit_mode any pending work is automatically committed.

## Multiple SQL Statements

PDO_CUBRID supports Multiple SQL statements. Multiple SQL statements are separated by semicolons (`;`).

## Schema Information

PDO_CUBRID implements PDO::cubrid_schema() to get schema information.

## LOBs

PDO_CUBRID supports BLOB/CLOB data type. The LOB in PDO is represented as a stream, so you can insert LOBs by binding a stream, and get LOBs by reading a stream returned by CUBRID PDO. For example:

Beispiel #1 Insert LOBs in CUBRID PDO

    <?php
    $fp = fopen('lob_test.png', 'rb');

    $sql_stmt = "INSERT INTO lob_test(name, content) VALUES('lob_test.png', ?)";

    $stmt = $dbh->prepare($sql_stmt);
    $ret = $stmt->bindParam(1, $fp, PDO::PARAM_LOB);
    $ret = $stmt->execute();
    ?>

Beispiel #2 Fetch LOBs in CUBRID PDO

    <?php
    $sql_stmt = "SELECT content FROM lob_test WHERE name='lob_test.png'";

    $stmt = $dbh->prepare($sql_stmt);
    $stmt->execute();
    $result = $stmt->fetch(PDO::FETCH_NUM);

    header("Content-Type: image/png");
    fpassthru($result[0]);
    ?>

## Column meta

The PDOStatement::getColumnMeta() in CUBRID PDO will return an associative array containing the following values:

- type
- name
- table
- def
- precision
- scale
- not_null
- auto_increment
- unique_key
- multiple_key
- primary_key
- foreign_key
- reverse_index
- reverse_unique

## Collection Data Type

PDO_CUBRID supports SET/MULTISET/SEQUENCE data type. If you don't specify data type, the default data type is char. For example:

Beispiel #3 Insert set in CUBRID PDO with default data type.

    <?php
    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(VARCHAR))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);
    $data = array("abc","def","ghi");
    $ret = $stmt->bindParam(1, $data, PDO::PARAM_NULL);
    $ret = $stmt->execute();
    var_Dump($ret);
    ?>

Beispiel #4 Specify data type when insert set in CUBRID PDO

    <?php
    $conn_str ="cubrid:dbname=demodb;host=localhost;port=33000";
    $cubrid_pdo = new PDO($conn_str, 'dba', '');

    $cubrid_pdo->exec("DROP TABLE if exists test_tbl");
    $cubrid_pdo->exec("CREATE TABLE test_tbl (col_1 SET(int))");

    $sql_stmt_insert = "INSERT INTO test_tbl VALUES (?);";
    $stmt = $cubrid_pdo->prepare($sql_stmt_insert);
    $data = array(1,2,3,4);
    $ret = $stmt->bindParam(1, $data, 0,0,"int");
    $ret = $stmt->execute();
    var_Dump($ret);
    ?>

CUBRID Bind Data Types for the fifth parameter of PDOStatement::bindParam():

- CHAR
- STRING
- NCHAR
- VARNCHAR
- BIT
- VARBIT
- NUMERIC
- NUMBER
- INT
- SHORT
- BIGINT
- MONETARY
- FLOAT
- DOUBLE
- DATE
- TIME
- DATETIME
- TIMESTAMP

## Vordefinierte Konstanten

Die folgenden Konstanten werden von diesem Treiber definiert und sind nur verfügbar, wenn die Erweiterung entweder in PHP einkompiliert oder dynamisch zur Laufzeit geladen wurde. Darüber hinaus sind diese Konstanten treiberspezifisch und sollten nur mit diesem Treiber benutzt werden. Treiberspezifische Attribute mit einem anderen Treiber zu nutzen, kann zu unerwarteten Ergebnissen führen. Wenn der Code mit verschiedenen Treibern funktioniert, kann PDO::getAttribute() verwendet werden, um mit `PDO::ATTR_DRIVER_NAME` den aktuellen Treiber zu ermitteln.

The following constants can be used when setting the database attribute. They can be passed to PDO::getAttribute() or PDO::setAttribute().

PDO::CUBRID attribute flags
Constant | Description
--- | ---
`PDO::CUBRID_ATTR_ISOLATION_LEVEL` | Transaction isolation level for the database connection.
`PDO::CUBRID_ATTR_LOCK_TIMEOUT` | Transaction timeout in seconds.
`PDO::CUBRID_ATTR_MAX_STRING_LENGTH` | Read only. The maximum string length for bit, varbit, char, varchar, nchar, nchar varying data types when using CUBRID PDO API.

The following constants can be used when setting the transaction isolation level. They can be passed to PDO::getAttribute() or returned by PDO::setAttribute().

PDO::CUBRID isolation level flags
Constant | Description
--- | ---
`PDO::TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | The lowest isolation level (1). A dirty, non-repeatable or phantom read may occur for the tuple and a non-repeatable read may occur for the table as well.
`PDO::TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | A relatively low isolation level (2). A dirty read does not occur, but non-repeatable or phantom read may occur.
`PDO::TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | The default isolation of CUBRID (3). A dirty, non-repeatable or phantom read may occur for the tuple, but repeatable read is ensured for the table.
`PDO::TRAN_REP_CLASS_COMMIT_INSTANCE` | A relatively low isolation level (4). A dirty read does not occur, but non-repeatable or phantom read may.
`PDO::TRAN_REP_CLASS_REP_INSTANCE` | A relatively high isolation level (5). A dirty or non-repeatable read does not occur, but a phantom read may.
`PDO::TRAN_SERIALIZABLE` | The highest isolation level (6). Problems concerning concurrency (e.g. dirty read, non-repeatable read, phantom read, etc.) do not occur.

The following constants can be used when getting schema information. They can be passed to PDO::cubrid_schema().

PDO::CUBRID schema flags
Constant | Description
--- | ---
`PDO::CUBRID_SCH_TABLE` | Get name and type of table in CUBRID.
`PDO::CUBRID_SCH_VIEW` | Get name and type of view in CUBRID.
`PDO::CUBRID_SCH_QUERY_SPEC` | Get the query definition of view.
`PDO::CUBRID_SCH_ATTRIBUTE` | Get the attributes of table column.
`PDO::CUBRID_SCH_TABLE_ATTRIBUTE` | Get the attributes of table.
`PDO::CUBRID_SCH_METHOD` | Get the instance method. The instance method is a method called by a class instance. It is used more often than the class method because most operations are executed in the instance.
`PDO::CUBRID_SCH_TABLE_METHOD` | Get the class method. The class method is a method called by a class object. It is usually used to create a new class instance or to initialize it. It is also used to access or update class attributes.
`PDO::CUBRID_SCH_METHOD_FILE` | Get the information of the file where the method of the table is defined.
`PDO::CUBRID_SCH_SUPER_TABLE` | Get the name and type of table which table inherites attributes from.
`PDO::CUBRID_SCH_SUB_TABLE` | Get the name and type of table which inherites attributes from this table.
`PDO::CUBRID_SCH_CONSTRAINT` | Get the table constraints.
`PDO::CUBRID_SCH_TRIGGER` | Get the table triggers.
`PDO::CUBRID_SCH_TABLE_PRIVILEGE` | Get the privilege information of table.
`PDO::CUBRID_SCH_COL_PRIVILEGE` | Get the privilege information of column.
`PDO::CUBRID_SCH_DIRECT_SUPER_TABLE` | Get the direct super table of table.
`PDO::CUBRID_SCH_PRIMARY_KEY` | Get the table primary key.
`PDO::CUBRID_SCH_IMPORTED_KEYS` | Get imported keys of table.
`PDO::CUBRID_SCH_EXPORTED_KEYS` | Get exported keys of table.
`PDO::CUBRID_SCH_CROSS_REFERENCE` | Get reference relationship of two tables.

# PDO_CUBRID DSN

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO_CUBRID DSN — Connecting to CUBRID databases

### Beschreibung

The PDO_CUBRID Data Source Name (DSN) is composed of the following elements, delimited by semicolons:

DSN prefix

  The DSN prefix is `cubrid:`.

`host`
  The hostname on which the database server resides.
`port`
  The port on which the database server is running.
`dbname`
  The name of the database.

### Anmerkungen

> Hinweis: When you establish the connection to CUBRID, you should give username and password except DSN.

### Beispiele

Beispiel #1 PDO_CUBRID DSN examples

The following example shows a PDO_CUBRID DSN for connecting to a CUBRID database:

    cubrid:host=localhost;port=33000;dbname=demodb

# PDO::cubrid_schema

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO::cubrid_schema — Get the requested schema information

### Beschreibung

public function PDO::cubrid_schema(int `$schema_type`, string `$table_name` = ?, string `$col_name` = ?): array

This function is used to get the requested schema information from database. You have to designate `table_name`, if you want to get information on certain table, `col_name`, if you want to get information on certain column (can be used only with PDO::CUBRID_SCH_COL_PRIVILEGE).

The result of this function is returned as a two-dimensional array (column (associative array) * row (numeric array)). The following tables shows types of schema and the column structure of the result array to be returned based on the schema type.

Result Composition of Each Type
Schema | Column Number | Column Name | Value
--- | --- | --- | ---
PDO::CUBRID_SCH_TABLE | 1 | NAME |
| 2 | TYPE | 0:system table 1:view 2:table
PDO::CUBRID_SCH_VIEW | 1 | NAME |
| 2 | TYPE | 1:view
PDO::CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
PDO::CUBRID_SCH_ATTRIBUTE / PDO::CUBRID_SCH_TABLE_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexed
| 6 | NOT NULL | 1:not null
| 7 | SHARED | 1:shared
| 8 | UNIQUE | 1:unique
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:key
PDO::CUBRID_SCH_METHOD / PDO::CUBRID_SCH_TABLE_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
PDO::CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
PDO::CUBRID_SCH_SUPER_TABLE / PDO::CUBRID_SCH_DIRECT_SUPER_TABLE / PDO::CUBRID_SCH_SUB_TABLE | 1 | CLASS_NAME |
| 2 | TYPE | 0:system table 1:view 2:table
PDO::CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:primary key
| 7 | KEY_ORDER | base:1
PDO::CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
PDO::CUBRID_SCH_TABLE_PRIVILEGE / PDO::CUBRID_SCH_COL_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
PDO::CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
PDO::CUBRID_SCH_IMPORTED_KEYS / PDO::CUBRID_SCH_EXPORTED_KEYS / PDO::CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 8 | FK_NAME |
| 9 | PK_NAME |

### Parameter-Liste

`schema_type`
  Schema type that you want to know.
`table_name`
  Table you want to know the schema of.
`col_name`
  Column you want to know the schema of.

### Rückgabewerte

Array containing the schema information, when process is successful;

FALSE, when process is unsuccessful

### Beispiele

Beispiel #1 A PDO::cubrid_schema() example

This example shows how to get primary key and foreign keys of table game.

    <?php
    $pk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_PRIMARY_KEY, "game");
    print_r($pk_list);

    $fk_list = $dbh->cubrid_schema(PDO::CUBRID_SCH_IMPORTED_KEYS, "game");
    print_r($fk_list);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Result:
    Array
    (
        [0] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => athlete_code
                [KEY_SEQ] => 3
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [1] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => event_code
                [KEY_SEQ] => 2
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

        [2] => Array
            (
                [CLASS_NAME] => game
                [ATTR_NAME] => host_year
                [KEY_SEQ] => 1
                [KEY_NAME] => pk_game_host_year_event_code_athlete_code
            )

    )
    Array
    (
        [0] => Array
            (
                [PKTABLE_NAME] => athlete
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => athlete_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_athlete_code
                [PK_NAME] => pk_athlete_code
            )

        [1] => Array
            (
                [PKTABLE_NAME] => event
                [PKCOLUMN_NAME] => code
                [FKTABLE_NAME] => game
                [FKCOLUMN_NAME] => event_code
                [KEY_SEQ] => 1
                [UPDATE_RULE] => 1
                [DELETE_RULE] => 1
                [FK_NAME] => fk_game_event_code
                [PK_NAME] => pk_event_code
            )

    )

## Inhaltsverzeichnis

- PDO_CUBRID DSN — Connecting to CUBRID databases
- PDO::cubrid_schema — Get the requested schema information

# Microsoft SQL Server and Sybase PDO Driver (PDO_DBLIB)

## Einführung

PDO_DBLIB is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to Microsoft SQL Server and Sybase databases through the FreeTDS library.

This extension is not available anymore on Windows.

On Windows, you should use SqlSrv, an alternative driver for MS SQL is available from Microsoft: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx .

If it is not possible to use SqlSrv, you can use the PDO_ODBC driver to connect to Microsoft SQL Server and Sybase databases, as the native Windows DB-LIB is ancient, thread un-safe and no longer supported by Microsoft.

# PDO_DBLIB DSN

(PECL PDO_DBLIB >= 0.9.0)

PDO_DBLIB DSN — Connecting to Microsoft SQL Server and Sybase databases

### Beschreibung

The PDO_DBLIB Data Source Name (DSN) is composed of the following elements:

DSN prefix

  The DSN prefix is `sybase:` if PDO_DBLIB was linked against the Sybase ct-lib libraries, `mssql:` if PDO_DBLIB was linked against the Microsoft SQL Server libraries, or `dblib:` if PDO_DBLIB was linked against the FreeTDS libraries.

`host`

  The hostname on which the database server resides. Defaults to 127.0.0.1.

`dbname`

  The name of the database.

`charset`

  The client character set.

`appname`

  The application name (used in sysprocesses). Defaults to "PHP Generic DB-lib" or "PHP freetds".

`secure`

  Currently unused.

### Beispiele

Beispiel #1 PDO_DBLIB DSN examples

The following examples show a PDO_DBLIB DSN for connecting to Microsoft SQL Server and Sybase databases:

    mssql:host=localhost;dbname=testdb
    sybase:host=localhost;dbname=testdb
    dblib:host=localhost;dbname=testdb

## Inhaltsverzeichnis

- PDO_DBLIB DSN — Connecting to Microsoft SQL Server and Sybase databases

# The Pdo\Dblib class

(PHP 8 >= 8.4.0)

## Einführung

A PDO subclass representing a connection using the DBLib PDO driver.

## Klassenbeschreibung

namespace Pdo;
class Dblib extends PDO {
/* Geerbte Konstanten */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Konstanten */
public const int ATTR_CONNECTION_TIMEOUT;
public const int ATTR_QUERY_TIMEOUT;
public const bool ATTR_STRINGIFY_UNIQUEIDENTIFIER;
public const int ATTR_VERSION;
public const int ATTR_TDS_VERSION;
public const int ATTR_SKIP_EMPTY_ROWSETS;
public const bool ATTR_DATETIME_CONVERT;
/* Geerbte Methoden */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Vordefinierte Konstanten

`Pdo\Dblib::ATTR_CONNECTION_TIMEOUT`
`Pdo\Dblib::ATTR_QUERY_TIMEOUT`
`Pdo\Dblib::ATTR_STRINGIFY_UNIQUEIDENTIFIER`
  As of PHP 8.4.0 this constant is typed as bool; previously, it was typed as int.
`Pdo\Dblib::ATTR_VERSION`
`Pdo\Dblib::ATTR_TDS_VERSION`
`Pdo\Dblib::ATTR_SKIP_EMPTY_ROWSETS`
`Pdo\Dblib::ATTR_DATETIME_CONVERT`
  This connection attribute controls the format of strings for datetime types. When this is `false`, PDO_DBLIB will return a datetime type as a string in the format that SQL Server returns it in (i.e. `"2017-10-27 10:22:44"`). When `true`, PDO_DBLIB will convert the datetime type into a string using a user-defined or locale format, as specified in the FreeTDS locales.conf file. By default, this attribute is `false`. As of PHP 8.4.0 this constant is typed as bool; previously, it was typed as int.

# Firebird PDO Driver (PDO_FIREBIRD)

## Einführung

PDO_FIREBIRD is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to Firebird database.

## Installation

Use --with-pdo-firebird[=DIR] to install the PDO Firebird extension, where the optional `[=DIR]` is the Firebird base install directory.

    $ ./configure --with-pdo-firebird

## Vordefinierte Konstanten

Die folgenden Konstanten werden von diesem Treiber definiert und sind nur verfügbar, wenn die Erweiterung entweder in PHP einkompiliert oder dynamisch zur Laufzeit geladen wurde. Darüber hinaus sind diese Konstanten treiberspezifisch und sollten nur mit diesem Treiber benutzt werden. Treiberspezifische Attribute mit einem anderen Treiber zu nutzen, kann zu unerwarteten Ergebnissen führen. Wenn der Code mit verschiedenen Treibern funktioniert, kann PDO::getAttribute() verwendet werden, um mit `PDO::ATTR_DRIVER_NAME` den aktuellen Treiber zu ermitteln.

Warnung

The constants listed below have been DEPRECATED as of PHP 8.5.0. Use the corresponding Pdo\Firebird constants instead.

`PDO::FB_ATTR_DATE_FORMAT` (int)
  Alias von `Pdo\Firebird::ATTR_DATE_FORMAT`.
`PDO::FB_ATTR_TIME_FORMAT` (int)
  Alias von `Pdo\Firebird::ATTR_TIME_FORMAT`.
`PDO::FB_ATTR_TIMESTAMP_FORMAT` (int)
  Alias von `Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`.

# PDO_FIREBIRD DSN

(PECL PDO_FIREBIRD >= 0.1.0)

PDO_FIREBIRD DSN — Connecting to Firebird databases

### Beschreibung

The PDO_FIREBIRD Data Source Name (DSN) is composed of the following elements:

DSN prefix

  The DSN prefix is `firebird:`.

`dbname`

  The name of the database.

`charset`

  The character set.

`role`

  The SQL role name.

`dialect`

  The dialect of the database; either `1` or `3`. If not specified, the dialect defaults to `3`. Available as of PHP 7.4.0.

### Beispiele

Beispiel #1 PDO_FIREBIRD DSN example with path

The following example shows a PDO_FIREBIRD DSN for connecting to Firebird databases:

    firebird:dbname=/path/to/DATABASE.FDB

Beispiel #2 PDO_FIREBIRD DSN example with port and path

The following example shows a PDO_FIREBIRD DSN for connecting to a Firebird database using hostname port and path:

    firebird:dbname=hostname/port:/path/to/DATABASE.FDB

Beispiel #3 PDO_FIREBIRD DSN example with localhost and path to employee.fdb on Debian system

The following example shows a PDO_FIREBIRD DSN for connecting to a Firebird database employee.fdb using localhost:

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/employee.fdb

Beispiel #4 PDO_FIREBIRD DSN to connect to a dialect 1 database

The following example shows a PDO_FIREBIRD DSN for connecting to a Firebird database test.fdb which has been created using dialect 1. This is only supported as of PHP 7.4.0.

    firebird:dbname=localhost:/var/lib/firebird/2.5/data/test.fdb;charset=utf-8;dialect=1

## Inhaltsverzeichnis

- PDO_FIREBIRD DSN — Connecting to Firebird databases

# The Pdo\Firebird class

(PHP 8 >= 8.4.0)

## Einführung

A PDO subclass representing a connection using the Firebird PDO driver.

## Klassenbeschreibung

namespace Pdo;
class Firebird extends PDO {
/* Geerbte Konstanten */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Konstanten */
public const int ATTR_DATE_FORMAT;
public const int ATTR_TIME_FORMAT;
public const int ATTR_TIMESTAMP_FORMAT;
public const int TRANSACTION_ISOLATION_LEVEL;
public const int READ_COMMITTED;
public const int REPEATABLE_READ;
public const int SERIALIZABLE;
public const int WRITABLE_TRANSACTION;
/* Methoden */
public static function getApiVersion(): int
/* Geerbte Methoden */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Vordefinierte Konstanten

`Pdo\Firebird::ATTR_DATE_FORMAT`
  Sets the date format.
`Pdo\Firebird::ATTR_TIME_FORMAT`
  Sets the time format.
`Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`
  Sets the timestamp format.
`Pdo\Firebird::TRANSACTION_ISOLATION_LEVEL`
  Attribute to sets the transaction isolation level. This can be one of `Pdo\Firebird::READ_COMMITTED`, `Pdo\Firebird::REPEATABLE_READ`, or `Pdo\Firebird::SERIALIZABLE`.
`Pdo\Firebird::READ_COMMITTED`
  Flag denoting the ANSI transaction isolation level is read committed. This is the default behavior.
`Pdo\Firebird::REPEATABLE_READ`
  Flag denoting the ANSI transaction isolation level is repeatable read. This corresponds to Firebird's "snapshot" isolation level.
`Pdo\Firebird::SERIALIZABLE`
  Flag denoting the ANSI transaction isolation level is serializable. This corresponds to Firebird's "snapshot table stability" isolation level.
`Pdo\Firebird::WRITABLE_TRANSACTION`
  Boolean attribute used to toggle the transaction access mode between `READ ONLY` and `READ WRITE`. By default, it is `true` indicating `READ WRITE`.

# Pdo\Firebird::getApiVersion

(PHP 8 >= 8.4.0)

Pdo\Firebird::getApiVersion — Get the API version

### Beschreibung

public static function Pdo\Firebird::getApiVersion(): int

Returns the Firebird API version as defined by the C constant `FB_API_VER` in ibase.h.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the FireBird API as an int.

## Inhaltsverzeichnis

- Pdo\Firebird::getApiVersion — Get the API version

# IBM PDO Driver (PDO_IBM)

## Einführung

PDO_IBM is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to IBM databases.

## Installation

To build the PDO_IBM extension, the DB2 Client v9.1 or later must be installed on the same system as PHP. The DB2 Client can be downloaded from the IBM » Application Development Site.

> Hinweis: Note

> The DB2 Client v9.1 or later supports direct access to DB2 for Linux, UNIX, and Windows v8 and v9.1 servers.

> The DB2 Client v9.1 also supports access to DB2 UDB for i5 and DB2 UDB for z/OS servers using the separately purchased » DB2 Connect product.

PDO_IBM is a » PECL extension, so follow the instructions in Installation der PECL-Erweiterungen to install the PDO_IBM extension. Issue the configure command to point to the location of the DB2 Client header files and libraries as follows:

    bash$ ./configure --with-pdo-ibm=/path/to/sqllib[,shared]

The configure command defaults to the value of the DB2DIR environment variable.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

PDO_IBM Configuration Options
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
pdo_ibm.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Added in PDO_IBM 1.5.0
pdo_ibm.i5_override_ccsid | "0" | `INI_SYSTEM` | Added in PDO_IBM 1.5.0

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`pdo_ibm.i5_dbcs_alloc` int

  This options affects the internal buffer allocation strategy on IBM i. By default, this option is 0. When this option is set, buffers are allocated with a much larger size, in case the database is misleading about character size when converting between encodings. This option uses six times as much memory for buffers (to account for the largest possible UTF-8 sequences), but may be needed if truncated data is returned.

  - 0 - Minimum size buffers are allocated.

  - 1 - Larger size buffers are allocated.

`pdo_ibm.i5_override_ccsid` int

  The ASCII CCSID to use for conversion from EBCDIC on IBM i. Setting this to 1208 will use UTF-8. By default, this is 0, which will select the default ASCII job CCSID.

  To learn more about CCSIDs on IBM i, consult the » IBM documentation.

# PDO_IBM DSN

(PECL PDO_IBM >= 0.9.0)

PDO_IBM DSN — Connecting to IBM databases

### Beschreibung

The PDO_IBM Data Source Name (DSN) is based on the IBM CLI DSN. The major components of the PDO_IBM DSN are:

DSN prefix

  The DSN prefix is `ibm:`.

DSN

  The DSN can be any of the following:

  - a) Data source setup using db2cli.ini or odbc.ini

  - b) Catalogued database name i.e. database alias in the DB2 client catalog

  - c) Complete connection string in the following format: `DRIVER={IBM DB2 ODBC DRIVER};DATABASE=`database`;HOSTNAME=`hostname`;PORT=`port`;PROTOCOL=TCPIP;UID=`username`;PWD=`password`;` where the parameters represent the following values:

    `database`

      The name of the database.

    `hostname`

      The hostname or IP address of the database server.

    `port`

      The TCP/IP port on which the database is listening for requests.

    `username`

      The username with which you are connecting to the database.

    `password`

      The password with which you are connecting to the database.

### Beispiele

Beispiel #1 PDO_IBM DSN example using db2cli.ini

The following example shows a PDO_IBM DSN for connecting to an DB2 database cataloged as DB2_9 in db2cli.ini:

    $db = new PDO("ibm:DSN=DB2_9", "", "");

    [DB2_9]
    Database=testdb
    Protocol=tcpip
    Hostname=11.22.33.444
    Servicename=56789

Beispiel #2 PDO_IBM DSN example using a connection string

The following example shows a PDO_IBM DSN for connecting to an DB2 database named `testdb` using the DB2 CLI connection string syntax.

    $db = new PDO("ibm:DRIVER={IBM DB2 ODBC DRIVER};DATABASE=testdb;" .
      "HOSTNAME=11.22.33.444;PORT=56789;PROTOCOL=TCPIP;", "testuser", "tespass");

## Inhaltsverzeichnis

- PDO_IBM DSN — Connecting to IBM databases

# Informix PDO Driver (PDO_INFORMIX)

## Einführung

PDO_INFORMIX is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to Informix databases.

## Installation

To build the PDO_INFORMIX extension, the Informix Client SDK 2.81 UC1 or higher must be installed on the same system as PHP. The Informix Client SDK is available from the » IBM Informix Support Site.

PDO_INFORMIX is a » PECL extension, so follow the instructions in Installation der PECL-Erweiterungen to install the PDO_INFORMIX extension. Issue the configure command to point to the location of the Informix Client SDK header files and libraries as follows:

       bash$ ./configure --with-pdo-informix=/path/to/SDK[,shared]

The configure command defaults to the value of the INFORMIXDIR environment variable.

## Scrollable cursors

PDO_INFORMIX supports scrollable cursors; however, they are not enabled by default. To enable scrollable cursor support, you must either set `ENABLESCROLLABLECURSORS=1` in the corresponding ODBC connection settings in odbc.ini or pass the `EnableScrollableCursors=1` clause in the DSN connection string.

# PDO_INFORMIX DSN

(PECL PDO_INFORMIX >= 0.1.0)

PDO_INFORMIX DSN — Connecting to Informix databases

### Beschreibung

The PDO_INFORMIX Data Source Name (DSN) is based on the Informix ODBC DSN string. Details on configuring an Informix ODBC DSN are available from the » Informix Dynamic Server Information Center. The major components of the PDO_INFORMIX DSN are:

DSN prefix

  The DSN prefix is `informix:`.

DSN

  The DSN can be either a data source setup using odbc.ini or a complete » connection string.

### Beispiele

Beispiel #1 PDO_INFORMIX DSN example using odbc.ini

The following example shows a PDO_INFORMIX DSN for connecting to an Informix database cataloged as Infdrv33 in odbc.ini:

    $db = new PDO("informix:DSN=Infdrv33", "", "");

    [ODBC Data Sources]
    Infdrv33=INFORMIX 3.3 32-BIT

    [Infdrv33]
    Driver=/opt/informix/csdk_2.81.UC1G2/lib/cli/iclis09b.so
    Description=INFORMIX 3.3 32-BIT
    Database=common_db
    LogonID=testuser
    pwd=testpass
    Servername=ids_server
    DB_LOCALE=en_US.819
    OPTIMIZEAUTOCOMMIT=1
    ENABLESCROLLABLECURSORS=1

Beispiel #2 PDO_INFORMIX DSN example using a connection string

The following example shows a PDO_INFORMIX DSN for connecting to an Informix database named `common_db` using the Informix connection string syntax.

    $db = new PDO("informix:host=host.domain.com; service=9800;
        database=common_db; server=ids_server; protocol=onsoctcp;
        EnableScrollableCursors=1", "testuser", "tespass");

## Inhaltsverzeichnis

- PDO_INFORMIX DSN — Connecting to Informix databases

# MySQL PDO-Treiber (PDO_MYSQL)

## Einführung

PDO_MYSQL ist ein Treiber, der die PHP Data Objects (PDO)-Schnittstelle implementiert, um von PHP aus auf MySQL Datenbanken zugreifen zu können.

PDO_MYSQL verwendet standardmäßig emulierte vorbereitete Anweisungen.

MySQL 8

Bei PHP-Versionen vor PHP 7.1.16 oder der 7.2-Serie vor 7.2.4 muss das Standard-Passwort-Plugin des MySQL 8-Servers auf mysql_native_password gesetzt werden, da sonst Fehler angezeigt werden wie The server requested authentication method unknown to the client [caching_sha2_password], auch wenn caching_sha2_password nicht verwendet wird.

Das liegt daran, dass MySQL 8 standardmäßig caching_sha2_password verwendet und dieses Plugin von den älteren PHP- (mysqlnd) Versionen nicht erkannt wird. Stattdessen muss die Voreinstellung durch den Eintrag `default_authentication_plugin=mysql_native_password` in der Datei my.cnf geändert werden. Das Plugin caching_sha2_password wird seit PHP 7.4.4 vollständig unterstützt. In älteren Versionen wird es von der Erweiterung mysql_xdevapi unterstützt.

Warnung

Vorsicht ist geboten: Einige MySQL-Tabellentypen (Speicher-Engines) unterstützen keine Transaktionen. Wenn transaktionaler Datenbankcode für einen Tabellentyp geschrieben wird, der keine Transaktionen unterstützt, verhält sich MySQL so, als sei eine Transaktion erfolgreich initiiert worden. Darüber hinaus werden alle ausgelösten DDL-Abfragen implizit alle anstehenden Transaktionen festschreiben.

> Hinweis:

> Der MySQL-Treiber unterstützt die Konstante `PDO::PARAM_INPUT_OUTPUT` über die Methode PDOStatement::bindParam() nicht korrekt; solche Parameter können zwar verwendet werden, werden aber nicht aktualisiert (d. h. die eigentliche Ausgabe wird ignoriert).

## Installation

In allen gängigen Unix-Distributionen sind Binärversionen von PHP enthalten, die installiert werden können. Obwohl diese Binärversionen in der Regel mit Unterstützung für die MySQL-Erweiterungen gebaut werden, müssen die Erweiterungsbibliotheken selbst möglicherweise über ein zusätzliches Paket installiert werden. Ob dies der Fall ist, erfahren Sie in der Paketverwaltung Paketverwaltung der von Ihnen gewählten Distribution.

Unter Ubuntu zum Beispiel installiert das Paket `php5-mysql` die PHP-Erweiterungen ext/mysql, ext/mysqli und PDO_MYSQL. Auch unter CentOS installiert das Paket `php-mysql` diese drei PHP-Erweiterungen.

Alternativ können Sie diese Erweiterung auch selbst kompilieren. Wenn Sie PHP aus dem Quellcode kompilieren, können Sie die MySQL-Erweiterungen angeben, die Sie verwenden möchten, und auch die Client-Bibliothek für jede Erweiterung auswählen.

Um die Erweiterung PDO MySQL zu installieren, verwenden Sie beim Kompilieren --with-pdo-mysql[=DIR], wobei das optionale `[=DIR]` die MySQL-Basisbibliothek angibt. Die Standardbibliothek ist Mysqlnd. Für Details über die Auswahl einer Bibliothek, siehe Auswahl einer MySQL-Bibliothek.

Mit dem optionalen --with-mysql-sock[=DIR] kann der Speicherort des Unix-Sockets von MySQL für alle MySQL Erweiterungen, einschließlich PDO_MYSQL, festgelegt werden. Wenn nichts angegeben ist, werden die standardmäßigen Speicherorte durchsucht.

Optional kann --with-zlib-dir[=DIR] verwendet werden, um den Pfad zum libz-Installationspräfix festzulegen.

    $ ./configure --with-pdo-mysql --with-mysql-sock=/var/mysql/mysql.sock

Die SSL-Unterstützung wird mit den entsprechenden `Pdo\Mysql::ATTR_SSL_*`-Konstanten aktiviert, was dem Aufruf der » MySQL C API-Funktion mysql_ssl_set() entspricht. Darüber hinaus kann SSL nicht mittels PDO::setAttribute() aktiviert werden, da die Verbindung bereits existiert. Siehe auch die MySQL-Dokumentation über den » Aufbau einer Verbindung zu MySQL mit SSL.

## Vordefinierte Konstanten

Die folgenden Konstanten werden von diesem Treiber definiert und sind nur verfügbar, wenn die Erweiterung entweder in PHP einkompiliert oder dynamisch zur Laufzeit geladen wurde. Darüber hinaus sind diese Konstanten treiberspezifisch und sollten nur mit diesem Treiber benutzt werden. Treiberspezifische Attribute mit einem anderen Treiber zu nutzen, kann zu unerwarteten Ergebnissen führen. Wenn der Code mit verschiedenen Treibern funktioniert, kann PDO::getAttribute() verwendet werden, um mit `PDO::ATTR_DRIVER_NAME` den aktuellen Treiber zu ermitteln.

`PDO::MYSQL_ATTR_USE_BUFFERED_QUERY` (int)
  Alias von `Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
`PDO::MYSQL_ATTR_LOCAL_INFILE` (int)
  Alias von `Pdo\Mysql::ATTR_LOCAL_INFILE`
`PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY` (int)
  Alias von `Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`. Verfügbar seit PHP 8.1.0.
`PDO::MYSQL_ATTR_INIT_COMMAND` (int)
  Alias von `Pdo\Mysql::ATTR_INIT_COMMAND`
`PDO::MYSQL_ATTR_READ_DEFAULT_FILE` (int)
  Alias von `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
`PDO::MYSQL_ATTR_READ_DEFAULT_GROUP` (int)
  Alias von `Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
`PDO::MYSQL_ATTR_MAX_BUFFER_SIZE` (int)
  Alias von `Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
`PDO::MYSQL_ATTR_DIRECT_QUERY` (int)
  Alias von `PDO::ATTR_EMULATE_PREPARES`
`PDO::MYSQL_ATTR_FOUND_ROWS` (int)
  Alias von `Pdo\Mysql::ATTR_FOUND_ROWS`
`PDO::MYSQL_ATTR_IGNORE_SPACE` (int)
  Alias von `Pdo\Mysql::ATTR_IGNORE_SPACE`
`PDO::MYSQL_ATTR_COMPRESS` (int)
  Alias von `Pdo\Mysql::ATTR_COMPRESS`
`PDO::MYSQL_ATTR_SERVER_PUBLIC_KEY` (int)
  Alias von `Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
`PDO::MYSQL_ATTR_SSL_CA` (int)
  Alias von `Pdo\Mysql::ATTR_SSL_CA`
`PDO::MYSQL_ATTR_SSL_CAPATH` (int)
  Alias von `Pdo\Mysql::ATTR_SSL_CAPATH`
`PDO::MYSQL_ATTR_SSL_CERT` (int)
  Alias von `Pdo\Mysql::ATTR_SSL_CERT`
`PDO::MYSQL_ATTR_SSL_CIPHER` (int)
  Alias von `Pdo\Mysql::ATTR_SSL_CIPHER`
`PDO::MYSQL_ATTR_SSL_KEY` (int)
  Alias von `Pdo\Mysql::ATTR_SSL_KEY`
`PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT` (int)
  Alias von `Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT` Verfügbar seit PHP 7.0.18 und PHP 7.1.4.
`PDO::MYSQL_ATTR_MULTI_STATEMENTS` (int)
  Alias von `Pdo\Mysql::ATTR_MULTI_STATEMENTS`

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

PDO_MYSQL-Konfigurationsoptionen
Name | Standard | Veränderbar
--- | --- | ---
pdo_mysql.default_socket | "/tmp/mysql.sock" | `INI_SYSTEM`
pdo_mysql.debug | NULL | `INI_SYSTEM`

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`pdo_mysql.default_socket` string

  Setzt einen Unix-Domain-Socket. Wenn während der Ausführung von configure ein Domain-Socket gefunden wird, wird dieser Wert bereits beim Kompilieren gesetzt. Diese INI-Einstellung gilt nur unter Unix.

`pdo_mysql.debug` bool

  Aktiviert das Debugging für PDO_MYSQL. Diese Einstellung ist nur verfügbar, wenn PDO_MYSQL mit mysqlnd und im PDO-Debugmodus kompiliert wurde.

# PDO_MYSQL DSN

(PECL PDO_MYSQL >= 0.1.0)

PDO_MYSQL DSN — Verbinden mit MySQL-Datenbanken

### Beschreibung

Der Data Source Name (Name der Datenquelle, DSN) von PDO_MYSQL setzt sich aus den folgenden Elementen zusammen:

DSN-Präfix

  Das DSN-Präfix ist `mysql:`.

`host`

  Der Name des Rechners, auf dem sich der Datenbankserver befindet

`port`

  Die Nummer des Ports, an dem der Datenbankserver lauscht

`dbname`

  Der Name der Datenbank

`unix_socket`

  Der MySQL-Unix-Socket (sollte nicht mit `host` oder `port` verwendet werden).

`charset`

  Der Zeichensatz. Weitere Informationen enthält die Dokumentation zum Zeichensatz-Konzept.

### Beispiele

Beispiel #1 DSN-Beispiele für PDO_MYSQL

Das folgende Beispiel zeigt einen PDO_MYSQL-DSN für die Verbindung zu einer MySQL-Datenbank:

    mysql:host=localhost;dbname=testdb

Ein paar komplettere Beispiele:

    mysql:host=localhost;port=3307;dbname=testdb
    mysql:unix_socket=/tmp/mysql.sock;dbname=testdb

### Anmerkungen

> Hinweis: Nur Unix:

> Wenn der Hostname auf `"localhost"` gesetzt ist, wird die Verbindung zum Server über einen Domain-Socket hergestellt. Wenn PDO_MYSQL gegen libmysqlclient kompiliert wurde, ist der Speicherort der Socket-Datei der einkompilierte Speicherort von libmysqlclient. Wenn PDO_MYSQL gegen mysqlnd kompiliert wurde, kann der Standard-Socket mit der Einstellung pdo_mysql.default_socket festgelegt werden.

## Inhaltsverzeichnis

- PDO_MYSQL DSN — Verbinden mit MySQL-Datenbanken

# The Pdo\Mysql class

(PHP 8 >= 8.4.0)

## Einführung

A PDO subclass representing a connection using the MySQL PDO driver.

This driver supports a dedicated SQL query parser for the MySQL dialect. It can handle the following:

- Single and double-quoted literals with both doubling and backslash as escaping mechanisms
- Backtick literals with doubling as escaping mechanism
- Two-dashes, C-style comments, and Hash-comments.

## Klassenbeschreibung

class Pdo\Mysql extends PDO {
/* Geerbte Konstanten */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Konstanten */
public const int ATTR_USE_BUFFERED_QUERY;
public const int ATTR_LOCAL_INFILE;
public const int ATTR_LOCAL_INFILE_DIRECTORY;
public const int ATTR_INIT_COMMAND;
public const int ATTR_MAX_BUFFER_SIZE;
public const int ATTR_READ_DEFAULT_FILE;
public const int ATTR_READ_DEFAULT_GROUP;
public const int ATTR_COMPRESS;
public const int ATTR_DIRECT_QUERY;
public const int ATTR_FOUND_ROWS;
public const int ATTR_IGNORE_SPACE;
public const int ATTR_MULTI_STATEMENTS;
public const int ATTR_SERVER_PUBLIC_KEY;
public const int ATTR_SSL_KEY;
public const int ATTR_SSL_CERT;
public const int ATTR_SSL_CA;
public const int ATTR_SSL_CAPATH;
public const int ATTR_SSL_CIPHER;
public const int ATTR_SSL_VERIFY_SERVER_CERT;
/* Methoden */
public function getWarningCount(): int
/* Geerbte Methoden */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Vordefinierte Konstanten

`Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
  By default all statements are executed in buffered mode. If this attribute is set to `false` on a Pdo\Mysql object, the MySQL driver will use the unbuffered mode.

  Beispiel #1 Setting MySQL unbuffered mode

      <?php
      $pdo = new Pdo\Mysql("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
      $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

      $unbufferedResult = $pdo->query("SELECT Name FROM City");
      foreach ($unbufferedResult as $row) {
          echo $row['Name'] . PHP_EOL;
      }
      ?>

`Pdo\Mysql::ATTR_LOCAL_INFILE`
  Enable `LOAD LOCAL INFILE`.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`
  Allows restricting LOCAL DATA loading to files located in this designated directory.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_INIT_COMMAND`
  Command to execute when connecting to the MySQL server. Will automatically be re-executed when reconnecting.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
  Read options from the named option file instead of from my.cnf.

  > Hinweis: This option is not available if mysqlnd is used, because mysqlnd does not read the mysql configuration files.

`Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
  Read options from the named group from my.cnf or the file specified with `Pdo\Mysql::ATTR_READ_DEFAULT_FILE`.

  > Hinweis: This option is not available if mysqlnd is used, because mysqlnd does not read the mysql configuration files.

`Pdo\Mysql::ATTR_COMPRESS`
  Enable network communication compression.
`Pdo\Mysql::ATTR_DIRECT_QUERY`
  Alias von `PDO::ATTR_EMULATE_PREPARES`.
`Pdo\Mysql::ATTR_FOUND_ROWS`
  Return the number of found (matched) rows, not the number of changed rows.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_IGNORE_SPACE`
  Permit spaces after SQL function names. Makes all SQL functions names reserved words.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
  Maximum buffer size. Defaults to 1 MiB.

  > Hinweis: This constant is not supported when compiled against mysqlnd.

`Pdo\Mysql::ATTR_MULTI_STATEMENTS`
  Disables multi query execution in both PDO::prepare() and PDO::query() when set to `false`.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
  RSA public key file used with the SHA-256 based authentication.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_SSL_KEY`
  The file path to the SSL key.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_SSL_CERT`
  The file path to the SSL certificate.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_SSL_CA`
  The file path to the SSL certificate authority.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_SSL_CAPATH`
  The file path to the directory that contains the trusted SSL CA certificates, which are stored in PEM format.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_SSL_CIPHER`
  A list of one or more permissible ciphers to use for SSL encryption, in a format understood by OpenSSL. For example: `DHE-RSA-AES256-SHA:AES128-SHA`

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

`Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT`
  Provides a way to disable verification of the server SSL certificate.

  > Hinweis: This option is available only with mysqlnd.

  > Hinweis: Can only be used in the `driver_options` array when constructing a new database handle.

# Pdo\Mysql::getWarningCount

(PHP 8 >= 8.4.0)

Pdo\Mysql::getWarningCount — Returns the number of warnings from the last executed query

### Beschreibung

public function Pdo\Mysql::getWarningCount(): int

Returns the number of warnings from the last executed query.

> Hinweis: For retrieving warning messages the following SQL command can be used: `SHOW WARNINGS [limit row_count]`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an int representing the number of warnings generated by the last query.

### Beispiele

Beispiel #1 Pdo\Mysql::getWarningCount() example

    <?php

    $conn = PDO::connect("mysql:host=localhost;dbname=test;charset=utf8mb4", 'user', 'password');

    $conn->query('SELECT 42/0');
    if ($conn->getWarningCount() > 0) {
        $result = $conn->query("SHOW WARNINGS");
        $row = $result->fetch();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Warning (1365): Division by 0

## Inhaltsverzeichnis

- Pdo\Mysql::getWarningCount — Returns the number of warnings from the last executed query

# Microsoft SQL Server PDO Driver (PDO_SQLSRV)

## Einführung

PDO_SQLSRV is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to MS SQL Server (starting with SQL Server 2005) and SQL Azure databases.

## Installation

The most recent version of the driver is available for download here: » SQLSRV download. The driver sources are hosted in a » public repository.

For more information about system requirements, see » SQLSRV System Requirements.

On Windows the PDO_SQLSRV extension is enabled by downloading and adding appropriate DLL files to the PHP extension directory and the corresponding entry to the php.ini file.

On Linux and macOS, the PDO_SQLSRV extension can be installed using » PECL. See the » installation tutorial for details.

## Vordefinierte Konstanten

Die folgenden Konstanten werden von diesem Treiber definiert und sind nur verfügbar, wenn die Erweiterung entweder in PHP einkompiliert oder dynamisch zur Laufzeit geladen wurde. Darüber hinaus sind diese Konstanten treiberspezifisch und sollten nur mit diesem Treiber benutzt werden. Treiberspezifische Attribute mit einem anderen Treiber zu nutzen, kann zu unerwarteten Ergebnissen führen. Wenn der Code mit verschiedenen Treibern funktioniert, kann PDO::getAttribute() verwendet werden, um mit `PDO::ATTR_DRIVER_NAME` den aktuellen Treiber zu ermitteln.

`PDO::SQLSRV_TXN_READ_UNCOMMITTED` (int)
  This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Read Uncommitted.
`PDO::SQLSRV_TXN_READ_COMMITTED` (int)
  This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Read Committed.
`PDO::SQLSRV_TXN_REPEATABLE_READ` (int)
  This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Repeateable Read.
`PDO::SQLSRV_TXN_SNAPSHOT` (int)
  This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Snapshot.
`PDO::SQLSRV_TXN_SERIALIZABLE` (int)
  This constant is an acceptable value for the SQLSRV DSN key TransactionIsolation. This constant sets the transaction isolation level for the connection to Serializable.
`PDO::SQLSRV_ENCODING_BINARY` (int)
  Specifies that data is sent/retrieved as a raw byte stream to/from the server without performing encoding or translation. This constant can be passed to PDOStatement::setAttribute, PDO::prepare, PDOStatement::bindColumn, and PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_SYSTEM` (int)
  Specifies that data is sent/retrieved to/from the server as 8-bit characters as specified in the code page of the Windows locale that is set on the system. Any multi-byte characters or characters that do not map into this code page are substituted with a single byte question mark (?) character. This constant can be passed to PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, and PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_UTF8` (int)
  Specifies that data is sent/retrieved to/from the server in UTF-8 encoding. This is the default encoding. This constant can be passed to PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, and PDOStatement::bindParam.
`PDO::SQLSRV_ENCODING_DEFAULT` (int)
  Specifies that data is sent/retrieved to/from the server according to PDO::SQLSRV_ENCODING_SYSTEM if specified during connection. The connection's encoding is used if specified in a prepare statement. This constant can be passed to PDOStatement::setAttribute, PDO::setAttribute, PDO::prepare, PDOStatement::bindColumn, and PDOStatement::bindParam.
`PDO::SQLSRV_ATTR_QUERY_TIMEOUT` (int)
  A non-negative integer representing the timeout period, in seconds. Zero (0) is the default and means no timeout. This constant can be passed to PDOStatement::setAttribute, PDO::setAttribute, and PDO::prepare.
`PDO::SQLSRV_ATTR_DIRECT_QUERY` (int)
  Indicates that a query should be executed directly, without being prepared. This constant can be passed to PDO::setAttribute, and PDO::prepare. For more information, see » Direct and Prepared Statement Execution.

# PDO_SQLSRV DSN

(PECL pdo_sqlsrv >= 2.0.1)

PDO_SQLSRV DSN — Connecting to MS SQL Server and SQL Azure databases

### Beschreibung

The PDO_SQLSRV Data Source Name (DSN) is composed of the following elements:

DSN prefix

  The DSN prefix is `sqlsrv:`.

`APP`
  The application name used in tracing.
`ConnectionPooling`
  Specifies whether the connection is assigned from a connection pool (1 or `true`) or not (0 or `false`).
`Database`
  The name of the database.
`Encrypt`
  Specifies whether the communication with SQL Server is encrypted (1 or `true`) or unencrypted (0 or `false`).
`Failover_Partner`
  Specifies the server and instance of the database's mirror (if enabled and configured) to use when the primary server is unavailable.
`LoginTimeout`
  Specifies the number of seconds to wait before failing the connection attempt.
`MultipleActiveResultSets`
  Disables or explicitly enables support for multiple active Result sets (MARS).
`QuotedId`
  Specifies whether to use SQL-92 rules for quoted identifiers (1 or `true`) or to use legacy Transact-SQL rules (0 or `false`).
`Server`
  The name of the database server.
`TraceFile`
  Specifies the path for the file used for trace data.
`TraceOn`
  Specifies whether ODBC tracing is enabled (1 or `true`) or disabled (0 or `false`) for the connection being established.
`TransactionIsolation`
  Specifies the transaction isolation level. The accepted values for this option are PDO::SQLSRV_TXN_READ_UNCOMMITTED, PDO::SQLSRV_TXN_READ_COMMITTED, PDO::SQLSRV_TXN_REPEATABLE_READ, PDO::SQLSRV_TXN_SNAPSHOT, and PDO::SQLSRV_TXN_SERIALIZABLE.
`TrustServerCertificate`
  Specifies whether the client should trust (1 or `true`) or reject (0 or `false`) a self-signed server certificate.
`WSID`
  Specifies the name of the computer for tracing.

### Beispiele

Beispiel #1 PDO_SQLSRV DSN examples

The following example shows how to connect to a specified MS SQL Server database:

    $c = new PDO("sqlsrv:Server=localhost;Database=testdb", "UserName", "Password");

The following example shows how to connect to a MS SQL Server database on a specified port:

    $c = new PDO("sqlsrv:Server=localhost,1521;Database=testdb", "UserName", "Password");

The following example shows how to connect to a SQL Azure database with server ID 12345abcde. Note that when you connect to SQL Azure with PDO, your username will be UserName@12345abcde (UserName@ServerId).

    $c = new PDO("sqlsrv:Server=12345abcde.database.windows.net;Database=testdb", "UserName@12345abcde", "Password");

## Inhaltsverzeichnis

- PDO_SQLSRV DSN — Connecting to MS SQL Server and SQL Azure databases

# Oracle PDO Driver (PDO_OCI)

## Installation

If the Oracle Database is on the same machine as PHP, the database software already contains the necessary libraries. When PHP is on a different machine, use the free » Oracle Instant Client libraries. For details refer to the OCI8 Requirements section.

## PHP 8.4

Diese Erweiterung wurde ins » PECL-Repositorium verschoben und ist nicht mehr Teil von PHP ab PHP 8.4.0

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/PDO_OCI.

## PHP < 8.4

Use --with-pdo-oci[=DIR] to install the PDO Oracle OCI extension, where the optional `[=DIR]` is the Oracle Home directory. `[=DIR]` defaults to the $ORACLE_HOME environment variable.

Use --with-pdo-oci=instantclient,prefix,version for an Oracle Instant Client SDK, where prefix and version are configured.

    // Using $ORACLE_HOME
    $ ./configure --with-pdo-oci

    // Using OIC for Linux with 10.2.0.3 RPMs with a /usr prefix
    $ ./configure --with-pdo-oci=instantclient,/usr,10.2.0.3

## Vordefinierte Konstanten

Die folgenden Konstanten werden von diesem Treiber definiert und sind nur verfügbar, wenn die Erweiterung entweder in PHP einkompiliert oder dynamisch zur Laufzeit geladen wurde. Darüber hinaus sind diese Konstanten treiberspezifisch und sollten nur mit diesem Treiber benutzt werden. Treiberspezifische Attribute mit einem anderen Treiber zu nutzen, kann zu unerwarteten Ergebnissen führen. Wenn der Code mit verschiedenen Treibern funktioniert, kann PDO::getAttribute() verwendet werden, um mit `PDO::ATTR_DRIVER_NAME` den aktuellen Treiber zu ermitteln.

`PDO::OCI_ATTR_ACTION` (int)

  Provides a way to specify the action on the database session.

  Dies existiert seit PHP 7.2.16 and 7.3.3

`PDO::OCI_ATTR_CLIENT_INFO` (int)

  Provides a way to specify the client info on the database session.

  Dies existiert seit PHP 7.2.16 and 7.3.3

`PDO::OCI_ATTR_CLIENT_IDENTIFIER` (int)

  Provides a way to specify the client identifier on the database session.

  Dies existiert seit PHP 7.2.16 and 7.3.3

`PDO::OCI_ATTR_MODULE` (int)

  Provides a way to specify the module on the database session.

  Dies existiert seit PHP 7.2.16 and 7.3.3

# PDO_OCI DSN

(PECL PDO_OCI >= 0.1.0)

PDO_OCI DSN — Connecting to Oracle databases

### Beschreibung

The PDO_OCI Data Source Name (DSN) is composed of the following elements:

DSN prefix

  The DSN prefix is `oci:`.

`dbname` (Oracle Instant Client)

  The URI for the Oracle Instant Client connection takes the form of `dbname=//hostname:port-number/database`. If you are connecting to a database defined in tnsnames.ora, use only the name of the database: `dbname=database`.

`charset`

  The client-side character set for the current environment handle.

### Beispiele

Beispiel #1 PDO_OCI DSN examples

The following examples show a PDO_OCI DSN for connecting to Oracle databases:

    // Connect to a database defined in tnsnames.ora
    oci:dbname=mydb

    // Connect using the Oracle Instant Client
    oci:dbname=//localhost:1521/mydb

## Inhaltsverzeichnis

- PDO_OCI DSN — Connecting to Oracle databases

# ODBC and DB2 PDO Driver (PDO_ODBC)

## Einführung

PDO_ODBC is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to databases through ODBC drivers or through the IBM DB2 Call Level Interface (DB2 CLI) library. PDO_ODBC currently supports three different "flavours" of database drivers:

ibm-db2

  Supports access to IBM DB2 Universal Database, Cloudscape, and Apache Derby servers through the free DB2 express-C client.

unixODBC

  Supports access to database servers through the unixODBC driver manager and the database's own ODBC drivers.

generic

  Offers a compile option for ODBC driver managers that are not explicitly supported by PDO_ODBC.

On Windows, php_pdo_odbc.dll has to be enabled as extension in php.ini. It is linked against the Windows ODBC Driver Manager so that PHP can connect to any database cataloged as a System DSN.

## Installation

PDO_ODBC on UNIX systems

1. PDO_ODBC is included in the PHP source. You can compile the PDO_ODBC extension as either a static or shared module using the following configure commands.

   ibm_db2

         ./configure --with-pdo-odbc=ibm-db2,/opt/IBM/db2/V8.1/

     To build PDO_ODBC with the ibm-db2 flavour, you have to have previously installed the DB2 application development headers on the same machine on which you are compiling PDO_ODBC. The DB2 application development headers are an installable option in the DB2 servers, and are also available as part of the DB2 Application Development Client freely available for download from the IBM developerWorks » website.

     If you do not supply a location for the DB2 libraries and headers to the configure command, PDO_ODBC defaults to /home/db2inst1/sqllib.

   unixODBC

         ./configure --with-pdo-odbc=unixODBC,/usr/local

     If you do not supply a location for the unixODBC libraries and headers to the configure command, PDO_ODBC defaults to /usr/local.
   generic

         ./configure --with-pdo-odbc=generic,/usr/local,libname,ldflags,cflags

## Vordefinierte Konstanten

Die folgenden Konstanten werden von diesem Treiber definiert und sind nur verfügbar, wenn die Erweiterung entweder in PHP einkompiliert oder dynamisch zur Laufzeit geladen wurde. Darüber hinaus sind diese Konstanten treiberspezifisch und sollten nur mit diesem Treiber benutzt werden. Treiberspezifische Attribute mit einem anderen Treiber zu nutzen, kann zu unerwarteten Ergebnissen führen. Wenn der Code mit verschiedenen Treibern funktioniert, kann PDO::getAttribute() verwendet werden, um mit `PDO::ATTR_DRIVER_NAME` den aktuellen Treiber zu ermitteln.

`PDO_ODBC_TYPE` (string)
  Describes the ODBC library linked against the PDO_ODBC extension. Possible values include `unixODBC`, `iODBC`, or `generic`.

Warnung

The constants listed below have been DEPRECATED as of PHP 8.5.0. Use the corresponding Pdo\Odbc constants instead.

`PDO::ODBC_ATTR_USE_CURSOR_LIBRARY` (int)
  Alias von `Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`.
`PDO::ODBC_SQL_USE_IF_NEEDED` (int)
  Alias von `Pdo\Odbc::SQL_USE_IF_NEEDED`.
`PDO::ODBC_SQL_USE_DRIVER` (int)
  Alias von `Pdo\Odbc::SQL_USE_DRIVER`.
`PDO::ODBC_SQL_USE_ODBC` (int)
  Alias von `Pdo\Odbc::SQL_USE_ODBC`.
`PDO::ODBC_ATTR_ASSUME_UTF8` (bool)
  Alias von `Pdo\Odbc::ATTR_ASSUME_UTF8`.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

PDO_ODBC Configuration Options
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
pdo_odbc.connection_pooling | "strict" | `INI_ALL` |
pdo_odbc.db2_instance_name | NULL | `INI_SYSTEM` | Dieses veraltete Feature wird in der Zukunft sicherlich entfernt.

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`pdo_odbc.connection_pooling` string

  Whether to pool ODBC connections. Can be one of `"strict"`, `"relaxed"` or `"off"` (equals to `""`). The parameter describes how strict the connection manager should be when matching connection parameters to existing pooled connections. `strict` is the recommend default, and will result in the use of cached connections only when all the connection parameters match exactly. `relaxed` will result in the use of cached connections when similar connection parameters are used. This can result in increased use of the cache, at the risk of bleeding connection information between (for example) virtual hosts.

  This setting can only be changed from the php.ini file, and affects the entire process; any other modules loaded into the process that use the same ODBC libraries will be affected too, including the Unified ODBC extension.

  Warnung

  `relaxed` matching should not be used on a shared server, for security reasons.

  Tipp

  Leave this setting at the default `strict` setting unless you have good reason to change it.

`pdo_odbc.db2_instance_name` string

  If you compile PDO_ODBC using the `db2` flavour, this setting sets the value of the DB2INSTANCE environment variable on Linux and UNIX operating systems to the specified name of the DB2 instance. This enables PDO_ODBC to resolve the location of the DB2 libraries and make cataloged connections to DB2 databases.

  This setting can only be changed from the php.ini file, and affects the entire process; any other modules loaded into the process that use the same ODBC libraries will be affected too, including the Unified ODBC extension.

  This setting has no effect on Windows.

# PDO_ODBC DSN

(PECL PDO_ODBC >= 0.1.0)

PDO_ODBC DSN — Connecting to ODBC or DB2 databases

### Beschreibung

The PDO_ODBC Data Source Name (DSN) is composed of the following elements:

DSN prefix

  The DSN prefix is `odbc:`. If you are connecting to a database cataloged in the ODBC driver manager or the DB2 catalog, you can append the cataloged name of the database to the DSN.

DSN

  The name of the database as cataloged in the ODBC driver manager or the DB2 catalog. Alternately, you can provide a complete ODBC connection string to connect to a database as described at » http://www.connectionstrings.com/.

`UID`

  The name of the user for the connection. If you specify the user name in the DSN, PDO ignores the value of the user name argument in the PDO constructor.

`PWD`

  The password of the user for the connection. If you specify the password in the DSN, PDO ignores the value of the password argument in the PDO constructor.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | When passing an empty string to the password argument in the PDO constructor, `pwd` was not included in the connection string created until now, but the behavior has been changed to include it as an empty string. Passing `null` for the password argument in the PDO constructor results in the same behavior as before.
8.4.0 | Changed the behavior to ignore the user name argument and the password argument in the PDO constructor separately when the DSN contains `uid` or `pwd`. Previously, if included only either `uid` or `pwd` in the DSN, both the user name argument and the password argument in the PDO constructor were ignored.

### Beispiele

Beispiel #1 PDO_ODBC DSN example (ODBC driver manager)

The following example shows a PDO_ODBC DSN for connecting to an ODBC database cataloged as testdb in the ODBC driver manager:

    odbc:testdb

Beispiel #2 PDO_ODBC DSN example (IBM DB2 uncataloged connection)

The following example shows a PDO_ODBC DSN for connecting to an IBM DB2 database named `SAMPLE` using the full ODBC DSN syntax:

    odbc:DRIVER={IBM DB2 ODBC DRIVER};HOSTNAME=localhost;PORT=50000;DATABASE=SAMPLE;PROTOCOL=TCPIP;UID=db2inst1;PWD=ibmdb2;

Beispiel #3 PDO_ODBC DSN example (Microsoft Access uncataloged connection)

The following example shows a PDO_ODBC DSN for connecting to a Microsoft Access database stored at `C:\db.mdb` using the full ODBC DSN syntax:

    odbc:Driver={Microsoft Access Driver (*.mdb)};Dbq=C:\\db.mdb;Uid=Admin

## Inhaltsverzeichnis

- PDO_ODBC DSN — Connecting to ODBC or DB2 databases

# The Pdo\Odbc class

(PHP 8 >= 8.4.0)

## Einführung

A PDO subclass representing a connection using the ODBC PDO driver.

## Klassenbeschreibung

namespace Pdo;
class Odbc extends PDO {
/* Geerbte Konstanten */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Konstanten */
public const int ATTR_USE_CURSOR_LIBRARY;
public const int ATTR_ASSUME_UTF8;
public const int SQL_USE_IF_NEEDED;
public const int SQL_USE_DRIVER;
public const int SQL_USE_ODBC;
/* Geerbte Methoden */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Vordefinierte Konstanten

`Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`

  This option controls whether the ODBC cursor library is used. The ODBC cursor library supports some advanced ODBC features (e.g. block scrollable cursors), which may not be implemented by the driver. The following values are supported:

  `Pdo\Odbc::SQL_USE_IF_NEEDED`
    Use the ODBC cursor library when needed. This is the default.
  `Pdo\Odbc::SQL_USE_DRIVER`
    Never use the ODBC cursor library.
  `Pdo\Odbc::SQL_USE_ODBC`
    Always use the ODBC cursor library.
`Pdo\Odbc::ATTR_ASSUME_UTF8`
  Windows only. If `true`, UTF-16 encoded character data (`CHAR`, `VARCHAR` and `LONGVARCHAR`) is converted to UTF-8 when reading from or writing data to the database. If `false` (the default), character encoding conversion may be done by the driver.

# PostgreSQL PDO Driver (PDO_PGSQL)

## Einführung

PDO_PGSQL is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to PostgreSQL databases.

## Ressource-Typen

This extension defines a stream resource returned by Pdo\Pgsql::lobOpen().

## Installation

Use --with-pdo-pgsql[=DIR] to install the PDO PostgreSQL extension, where the optional `[=DIR]` is the PostgreSQL base install directory, or the path to pg_config.

    $ ./configure --with-pdo-pgsql

## Vordefinierte Konstanten

Die folgenden Konstanten werden von diesem Treiber definiert und sind nur verfügbar, wenn die Erweiterung entweder in PHP einkompiliert oder dynamisch zur Laufzeit geladen wurde. Darüber hinaus sind diese Konstanten treiberspezifisch und sollten nur mit diesem Treiber benutzt werden. Treiberspezifische Attribute mit einem anderen Treiber zu nutzen, kann zu unerwarteten Ergebnissen führen. Wenn der Code mit verschiedenen Treibern funktioniert, kann PDO::getAttribute() verwendet werden, um mit `PDO::ATTR_DRIVER_NAME` den aktuellen Treiber zu ermitteln.

`PDO::PGSQL_ATTR_DISABLE_PREPARES` (int)
  Alias von `Pdo\Pgsql::ATTR_DISABLE_PREPARES`. As of PHP 8.5.0, this constant is deprecated.
`PDO::PGSQL_TRANSACTION_IDLE` (int)
  Equivalent to `Pdo\Pgsql::TRANSACTION_IDLE`. As of PHP 8.5.0, this constant is deprecated, as it has no effect.
`PDO::PGSQL_TRANSACTION_ACTIVE` (int)
  Equivalent to `Pdo\Pgsql::TRANSACTION_ACTIVE`. As of PHP 8.5.0, this constant is deprecated, as it has no effect.
`PDO::PGSQL_TRANSACTION_INTRANS` (int)
  Equivalent to `Pdo\Pgsql::TRANSACTION_INTRANS`. As of PHP 8.5.0, this constant is deprecated, as it has no effect.
`PDO::PGSQL_TRANSACTION_INERROR` (int)
  Equivalent to `Pdo\Pgsql::TRANSACTION_INERROR`. As of PHP 8.5.0, this constant is deprecated, as it has no effect.
`PDO::PGSQL_TRANSACTION_UNKNOWN` (int)
  Equivalent to `Pdo\Pgsql::TRANSACTION_UNKNOWN`. As of PHP 8.5.0, this constant is deprecated, as it has no effect.

## General notes

> Hinweis: `bytea` columns are returned as stream resources. See Large Objects (LOBs) for how to read these values and how to bind data with `PDO::PARAM_LOB`.

# PDO_PGSQL DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_PGSQL >= 0.1.0)

PDO_PGSQL DSN — Connecting to PostgreSQL databases

### Beschreibung

The PDO_PGSQL Data Source Name (DSN) is composed of the following elements, delimited by spaces or semicolons:

DSN prefix

  The DSN prefix is `pgsql:`.

`host`

  The hostname on which the database server resides.

`port`

  The port on which the database server is running.

`dbname`

  The name of the database.

`user`

  The name of the user for the connection. If you specify the user name in the DSN, PDO ignores the value of the user name argument in the PDO constructor.

`password`

  The password of the user for the connection. If you specify the password in the DSN, PDO ignores the value of the password argument in the PDO constructor.

`sslmode`
  The SSL mode. Accepted values are `disable`, `allow`, `prefer`, `require`, `verify-ca`, and `verify-full`; their meaning is described in the » PostgreSQL Documentation. Many hosted PostgreSQL services require an encrypted connection, so `require` or stricter is needed to connect to them.

> Hinweis: All semicolons in the DSN string are replaced by spaces, because PostgreSQL expects this format. This implies that semicolons in any of the components (e.g. `password` or `dbname`) are not supported.

### Beispiele

Beispiel #1 PDO_PGSQL DSN examples

The following example shows a PDO_PGSQL DSN for connecting to a PostgreSQL database:

    pgsql:host=localhost;port=5432;dbname=testdb;user=bruce;password=mypass

The following example shows a PDO_PGSQL DSN for connecting to a PostgreSQL database via unix socket /tmp/.s.PGSQL.5432:

    pgsql:host=/tmp;port=5432;dbname=testdb;user=bruce;password=mypass

# PDO::pgsqlCopyFromArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromArray — Alias von Pdo\Pgsql::copyFromArray()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function PDO::pgsqlCopyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): bool

Diese Methode ist ein Alias für: Pdo\Pgsql::copyFromArray().

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The `rows` parameter now also accepts a Traversable; previously only an array was accepted.

# PDO::pgsqlCopyFromFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromFile — Alias von Pdo\Pgsql::copyFromFile()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function PDO::pgsqlCopyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): bool

Diese Methode ist ein Alias für: Pdo\Pgsql::copyFromFile().

# PDO::pgsqlCopyToArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToArray — Alias von Pdo\Pgsql::copyToArray()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function PDO::pgsqlCopyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): array|false

Diese Methode ist ein Alias für: Pdo\Pgsql::copyToArray().

# PDO::pgsqlCopyToFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToFile — Alias von Pdo\Pgsql::copyToFile()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function PDO::pgsqlCopyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = null
): bool

Diese Methode ist ein Alias für: Pdo\Pgsql::copyToFile().

# PDO::pgsqlGetNotify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetNotify — Alias von Pdo\Pgsql::getNotify()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function PDO::pgsqlGetNotify(int `$fetchMode` = PDO::FETCH_DEFAULT, int `$timeoutMilliseconds` = 0): array|false

Diese Methode ist ein Alias für: Pdo\Pgsql::getNotify().

# PDO::pgsqlGetPid

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetPid — Alias von Pdo\Pgsql::getPid()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function PDO::pgsqlGetPid(): int

Diese Methode ist ein Alias für: Pdo\Pgsql::getPid().

# PDO::pgsqlLOBCreate

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBCreate — Alias von Pdo\Pgsql::lobCreate()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function PDO::pgsqlLOBCreate(): string

Diese Methode ist ein Alias für: Pdo\Pgsql::lobCreate().

# PDO::pgsqlLOBOpen

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBOpen — Alias von Pdo\Pgsql::lobOpen()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function PDO::pgsqlLOBOpen(string `$oid`, string `$mode` = "rb"): resource|false

Diese Methode ist ein Alias für: Pdo\Pgsql::lobOpen().

# PDO::pgsqlLOBUnlink

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBUnlink — Alias von Pdo\Pgsql::lobUnlink()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function PDO::pgsqlLOBUnlink(string `$oid`): bool

Diese Methode ist ein Alias für: Pdo\Pgsql::lobUnlink().

## Inhaltsverzeichnis

- PDO_PGSQL DSN — Connecting to PostgreSQL databases
- PDO::pgsqlCopyFromArray — Alias von Pdo\Pgsql::copyFromArray
- PDO::pgsqlCopyFromFile — Alias von Pdo\Pgsql::copyFromFile
- PDO::pgsqlCopyToArray — Alias von Pdo\Pgsql::copyToArray
- PDO::pgsqlCopyToFile — Alias von Pdo\Pgsql::copyToFile
- PDO::pgsqlGetNotify — Alias von Pdo\Pgsql::getNotify
- PDO::pgsqlGetPid — Alias von Pdo\Pgsql::getPid
- PDO::pgsqlLOBCreate — Alias von Pdo\Pgsql::lobCreate
- PDO::pgsqlLOBOpen — Alias von Pdo\Pgsql::lobOpen
- PDO::pgsqlLOBUnlink — Alias von Pdo\Pgsql::lobUnlink

# The Pdo\Pgsql class

(PHP 8 >= 8.4.0)

## Einführung

A PDO subclass representing a connection using the PostgreSQL PDO driver.

This driver supports a dedicated SQL query parser for the PostgreSQL dialect. It can handle the following:

- Single and double-quoted literals, with doubling as escaping mechanism
- C-style “escape” string literals
- Dollar-quoted string literals
- Two-dashes and C-style comments (non-nested).
- Support for `??` as escape sequence for the `?` operator.

## Klassenbeschreibung

namespace Pdo;
class Pgsql extends PDO {
/* Geerbte Konstanten */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Konstanten */
public const int ATTR_DISABLE_PREPARES;
public const int ATTR_RESULT_MEMORY_SIZE;
public const int TRANSACTION_IDLE;
public const int TRANSACTION_ACTIVE;
public const int TRANSACTION_INTRANS;
public const int TRANSACTION_INERROR;
public const int TRANSACTION_UNKNOWN;
/* Methoden */
public function copyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false
public function copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function escapeIdentifier(string `$input`): string
public function getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false
public function getPid(): int
public function lobCreate(): string|false
public function lobOpen(string `$oid`, string `$mode` = "rb"): resource|false
public function lobUnlink(string `$oid`): bool
public function setNoticeCallback(?callable `$callback`): void
/* Geerbte Methoden */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Vordefinierte Konstanten

`Pdo\Pgsql::ATTR_DISABLE_PREPARES`
  Send the query and the parameters to the server together in a single call, avoiding the need to create a named prepared statement separately. If the query is only going to be executed once this can reduce latency by avoiding an unnecessary server round-trip.
`Pdo\Pgsql::ATTR_RESULT_MEMORY_SIZE`
  Returns the amount of memory, in bytes, allocated to the specified query result PDOStatement instance, or `null` if no results exist before the query is executed.
`PDO::ATTR_PREFETCH`
  As of PHP 8.5.0, setting this attribute to `0` enables lazy (single-row) fetching: rows are retrieved from the server one at a time as they are fetched, instead of buffering the whole result set in memory before the first PDOStatement::fetch() call. This reduces memory usage for large result sets. Any other value keeps the default buffered behavior. It can be set per connection with PDO::setAttribute(), or per statement via the PDO::prepare() or PDO::query() driver options.
  Achtung

  In lazy mode, a connection can have only one active statement at a time. Running another statement silently discards any unread rows of the previous one; no error is raised.

`Pdo\Pgsql::TRANSACTION_IDLE`
  Warnung

  This constant has no effect, and is deprecated as of PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_ACTIVE`
  Warnung

  This constant has no effect, and is deprecated as of PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_INTRANS`
  Warnung

  This constant has no effect, and is deprecated as of PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_INERROR`
  Warnung

  This constant has no effect, and is deprecated as of PHP 8.5.0.

`Pdo\Pgsql::TRANSACTION_UNKNOWN`
  Warnung

  This constant has no effect, and is deprecated as of PHP 8.5.0.

# Pdo\Pgsql::copyFromArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromArray — Copy data from a PHP array into a table

### Beschreibung

public function Pdo\Pgsql::copyFromArray(
string `$tableName`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copies data from `rows` array to table `tableName` using `separator` as fields delimiter and `fields` list.

### Parameter-Liste

`tableName`
  String containing table name.
`rows`
  An indexed array (or Traversable) of strings with fields separated by `separator`.
`separator`
  Delimiter used to separate fields in an entry of the `rows` array.
`nullAs`
  How to interpret SQL `NULL` values.
`fields`
  List of fields to insert.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | `rows` now also accepts a Traversable; previously only an array was accepted.

### Beispiele

Beispiel #1 Pdo\Pgsql::copyFromArray() example

Each element of `rows` is one record whose fields are joined by `separator` (a tab by default).

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');

    $rows = [
        "1\tapple\t10",
        "2\tbanana\t20",
        "3\tcherry\t30",
    ];
    $db->copyFromArray('fruits', $rows);

    foreach ($db->query('SELECT * FROM fruits ORDER BY id') as $row) {
        echo "{$row['id']} {$row['name']} {$row['qty']}\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1 apple 10
    2 banana 20
    3 cherry 30

### Siehe auch

- Pdo\Pgsql::copyToArray() - Copy data from database table into PHP array
- Pdo\Pgsql::copyFromFile() - Copy data from file into table
- Pdo\Pgsql::copyToFile() - Copy data from table into file

# Pdo\Pgsql::copyFromFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromFile — Copy data from file into table

### Beschreibung

public function Pdo\Pgsql::copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copies data from file specified by `filename` into table `tableName` using `separator` as fields delimiter and `fields` list

### Parameter-Liste

`tableName`
  String containing table name.
`filename`
  Filename containing the data to import.
`separator`
  Delimiter used to separate fields in an entry of the `rows` array.
`nullAs`
  How to interpret SQL `NULL` values.
`fields`
  List of fields to insert.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If `filename` cannot be opened for reading, the failure is reported through the connection's error handling (see `PDO::ATTR_ERRMODE`); with `PDO::ERRMODE_EXCEPTION` a PDOException is thrown.

### Beispiele

Beispiel #1 Pdo\Pgsql::copyFromFile() example

The file holds one record per line, with fields joined by `separator` (a tab by default).

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');

    file_put_contents('/tmp/fruits.tsv', "1\tapple\t10\n2\tbanana\t20\n");
    $db->copyFromFile('fruits', '/tmp/fruits.tsv');

    echo $db->query('SELECT count(*) FROM fruits')->fetchColumn(), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2

### Siehe auch

- Pdo\Pgsql::copyToFile() - Copy data from table into file
- Pdo\Pgsql::copyFromArray() - Copy data from a PHP array into a table
- Pdo\Pgsql::copyToArray() - Copy data from database table into PHP array

# Pdo\Pgsql::copyToArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToArray — Copy data from database table into PHP array

### Beschreibung

public function Pdo\Pgsql::copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

Copies data from `tableName` into array using `separator` as fields delimiter and `fields` list

### Parameter-Liste

`tableName`
  String containing table name.
`separator`
  Delimiter used to separate fields in an entry of the `rows` array.
`nullAs`
  How to interpret SQL `NULL` values.
`fields`
  List of fields to export.

### Rückgabewerte

Returns an array of rows,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Pdo\Pgsql::copyToArray() example

Each returned element is one record, with fields joined by `separator` and a trailing newline.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');
    $db->exec("INSERT INTO fruits VALUES (1, 'apple', 10), (2, 'banana', 20)");

    $rows = $db->copyToArray('fruits');
    var_export($rows);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array (
      0 => '1	apple	10
    ',
      1 => '2	banana	20
    ',
    )

### Siehe auch

- Pdo\Pgsql::copyFromArray() - Copy data from a PHP array into a table
- Pdo\Pgsql::copyFromFile() - Copy data from file into table
- Pdo\Pgsql::copyToFile() - Copy data from table into file

# Pdo\Pgsql::copyToFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToFile — Copy data from table into file

### Beschreibung

public function Pdo\Pgsql::copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

Copies data from table into file specified by `filename` using `separator` as fields delimiter and `fields` list.

### Parameter-Liste

`tableName`
  String containing table name.
`filename`
  Filename to export data.
`separator`
  Delimiter used to separate fields in an entry of the `rows` array.
`nullAs`
  How to interpret SQL `NULL` values.
`fields`
  List of fields to export.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If `filename` cannot be opened for writing, or cannot be written to, the failure is reported through the connection's error handling (see `PDO::ATTR_ERRMODE`); with `PDO::ERRMODE_EXCEPTION` a PDOException is thrown.

### Beispiele

Beispiel #1 Pdo\Pgsql::copyToFile() example

The table is written to `filename`, one record per line, with fields joined by `separator`.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->exec('CREATE TABLE fruits (id int, name text, qty int)');
    $db->exec("INSERT INTO fruits VALUES (1, 'apple', 10), (2, 'banana', 20)");

    $db->copyToFile('fruits', '/tmp/fruits.tsv');
    echo file_get_contents('/tmp/fruits.tsv');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1	apple	10
    2	banana	20

### Siehe auch

- Pdo\Pgsql::copyFromFile() - Copy data from file into table
- Pdo\Pgsql::copyFromArray() - Copy data from a PHP array into a table
- Pdo\Pgsql::copyToArray() - Copy data from database table into PHP array

# Pdo\Pgsql::escapeIdentifier

(PHP 8 >= 8.4.0)

Pdo\Pgsql::escapeIdentifier — Escapes a string for use as an SQL identifier

### Beschreibung

public function Pdo\Pgsql::escapeIdentifier(string `$input`): string

Escapes a string for use as an SQL identifier, such as a table, column, or function name. This is useful when a user-supplied identifier might contain special characters that would otherwise not be interpreted as part of the identifier by the SQL parser, or when the identifier might contain upper case characters whose case should be preserved.

### Parameter-Liste

`input`
  A string containing text to be escaped.

### Rückgabewerte

A string containing the escaped data.

### Beispiele

Beispiel #1 Pdo\Pgsql::escapeIdentifier() example

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $unescapedTableName = 'UnescapedTableName';
    $pdo->exec("CREATE TABLE $unescapedTableName ()");

    $escapedTableName = $pdo->escapeIdentifier('EscapedTableName');
    $pdo->exec("CREATE TABLE $escapedTableName ()");

    $statement = $pdo->query(
      "SELECT relname FROM pg_stat_user_tables WHERE relname ilike '%tablename'"
    );

    var_export($statement->fetchAll(PDO::FETCH_COLUMN, 0));

    $tableNameWithSymbols = 'Table-Name-With-Symbols';
    $pdo->exec("CREATE TABLE $tableNameWithSymbols ()");
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array (
      0 => 'unescapedtablename',
      1 => 'EscapedTableName',
    )
    Fatal error: Uncaught PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "Table"
    LINE 1: CREATE TABLE Table-Name-With-Symbols ()

### Siehe auch

- PDO::quote() - Setzt eine Zeichenkette für die Verwendung in einer Abfrage in Anführungszeichen

# Pdo\Pgsql::getNotify

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getNotify — Get asynchronous notification

### Beschreibung

public function Pdo\Pgsql::getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false

Returns a result set representing a pending asynchronous notification.

### Parameter-Liste

`fetchMode`

  The format the result set should be returned as, one of the following constants:

  - `PDO::FETCH_DEFAULT`
  - `PDO::FETCH_BOTH`
  - `PDO::FETCH_ASSOC`
  - `PDO::FETCH_NUM`
`timeoutMilliseconds`
  The length of time to wait for a response, in milliseconds.

### Rückgabewerte

If a notification is pending, returns a single row, otherwise returns `false`. The row has a `message` field (the channel name) and a `pid` field (the process ID of the notifying backend). If the notification carries a non-empty payload, the row also has a `payload` field. With `PDO::FETCH_NUM`, these fields are at indexes `0`, `1`, and `2`.

### Fehler/Exceptions

A ValueError is thrown if `fetchMode` is not one of the valid `PDO::FETCH_*` constants.

A ValueError is thrown if `timeoutMilliseconds` is less than `0`.

A `E_WARNING` is raised when `timeoutMilliseconds` is greater than the value that can be contained in a signed 32-bit integer, in which case it will be the maximum value of a signed 32-bit integer.

### Beispiele

Beispiel #1 Pdo\Pgsql::getNotify() example

Subscribe to a channel with `LISTEN`, then read the next pending notification with a one-second timeout.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    $db->exec('LISTEN messages');
    $db->exec("NOTIFY messages, 'hello'");

    $notification = $db->getNotify(PDO::FETCH_ASSOC, 1000);
    var_export($notification);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array (
      'message' => 'messages',
      'pid' => 1928,
      'payload' => 'hello',
    )

### Siehe auch

- PDO::query() - Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus
- PDOStatement::fetch() - Ruft die nächste Zeile aus einer Ergebnismenge ab
- PDOStatement::fetchAll() - Ruft die verbleibenden Zeilen aus einer Ergebnismenge ab

# Pdo\Pgsql::getPid

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getPid — Get the PID of the backend process handling this connection

### Beschreibung

public function Pdo\Pgsql::getPid(): int

Returns the PID of the backend process handling this connection. Note that the PID belongs to a process executing on the database server host, not the local host.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the PID as an int.

### Beispiele

Beispiel #1 Pdo\Pgsql::getPid() example

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    echo $db->getPid();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    12345

### Siehe auch

- pg_get_pid() - Prüft die Datenbankverbindung

# Pdo\Pgsql::lobCreate

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobCreate — Creates a new large object

### Beschreibung

public function Pdo\Pgsql::lobCreate(): string|false

Pdo\Pgsql::lobCreate() creates a large object and returns the OID which refers to it. It can be opened to read or write data with Pdo\Pgsql::lobOpen().

The OID can be stored in columns of type OID and be used to reference the large object, without causing the row to grow arbitrarily large. The large object will continue to live in the database until it is removed by calling Pdo\Pgsql::lobUnlink().

Large objects are cumbersome to use. Indeed, it is required that Pdo\Pgsql::lobUnlink() is called prior to deleting the last row referencing the OID in the entire database; otherwise, unreferenced large objects will remain on the server indefinitely. Moreover, large objects have no access controls. An alternative is the bytea column type, which can be up to 1GB in size, and this column type transparently manages the storage for optimal row size.

> Hinweis: This function, and all manipulations of the large object, must be called and carried out within a transaction.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the OID of the newly created large object on success, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Pdo\Pgsql::lobCreate() example

This example creates a new large object and copies the contents of a file into it. The OID is then stored into a table.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $oid = $db->lobCreate();
    $stream = $db->lobOpen($oid, 'w');
    $local = fopen($filename, 'rb');
    stream_copy_to_stream($local, $stream);
    $local = null;
    $stream = null;
    $stmt = $db->prepare("INSERT INTO BLOBS (ident, oid) VALUES (?, ?)");
    $stmt->execute([$some_id, $oid]);
    $db->commit();
    ?>

### Siehe auch

- Pdo\Pgsql::lobOpen() - Opens an existing large object stream
- Pdo\Pgsql::lobUnlink() - Deletes the large object
- pg_lo_create() - Erzeugt ein Large Object
- pg_lo_open() - Öffnet ein Large Object

# Pdo\Pgsql::lobOpen

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobOpen — Opens an existing large object stream

### Beschreibung

public function Pdo\Pgsql::lobOpen(string `$oid`, string `$mode` = "rb"): resource|false

Pdo\Pgsql::lobOpen() opens a stream to access the data referenced by `oid`. All usual filesystem functions, such as fread(), fwrite() or fgets() can be used to manipulate the contents of the stream.

> Hinweis: This function, and all manipulations of the large object, must be called and carried out within a transaction.

### Parameter-Liste

`oid`
  A large object identifier.
`mode`
  The access mode. If `mode` contains `w` or `+`, the stream is opened for reading and writing; otherwise it is opened for reading only. A `b` (binary) flag has no effect. The default `"rb"` opens the stream for reading.

### Rückgabewerte

Returns a stream resource on success,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Pdo\Pgsql::lobOpen() example

Following on from the Pdo\Pgsql::lobCreate() example, this code snippet retrieves the large object from the database and outputs it to the browser.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $stmt = $db->prepare("SELECT oid FROM BLOBS WHERE ident = ?");
    $stmt->execute([$some_id]);
    $stmt->bindColumn('oid', $oid, PDO::PARAM_STR);
    $stmt->fetch(PDO::FETCH_BOUND);
    $stream = $db->lobOpen($oid, 'r');
    header("Content-type: application/octet-stream");
    fpassthru($stream);
    ?>

### Siehe auch

- Pdo\Pgsql::lobCreate() - Creates a new large object
- Pdo\Pgsql::lobUnlink() - Deletes the large object
- pg_lo_create() - Erzeugt ein Large Object
- pg_lo_open() - Öffnet ein Large Object

# Pdo\Pgsql::lobUnlink

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobUnlink — Deletes the large object

### Beschreibung

public function Pdo\Pgsql::lobUnlink(string `$oid`): bool

Deletes a large object from the database identified by OID.

> Hinweis: This function, and all manipulations of the large object, must be called and carried out within a transaction.

### Parameter-Liste

`oid`
  A large object identifier.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Pdo\Pgsql::lobUnlink() example

This example unlinks a large object from the database before deleting the row that references it. It uses the blobs table from the Pdo\Pgsql::lobCreate() and Pdo\Pgsql::lobOpen() examples.

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $db->lobUnlink($oid);
    $stmt = $db->prepare("DELETE FROM BLOBS where ident = ?");
    $stmt->execute([$some_id]);
    $db->commit();
    ?>

### Siehe auch

- Pdo\Pgsql::lobCreate() - Creates a new large object
- Pdo\Pgsql::lobOpen() - Opens an existing large object stream
- pg_lo_create() - Erzeugt ein Large Object
- pg_lo_open() - Öffnet ein Large Object

# Pdo\Pgsql::setNoticeCallback

(PHP 8 >= 8.4.0)

Pdo\Pgsql::setNoticeCallback — Set a callback to handle notice and warning messages generated by the backend

### Beschreibung

public function Pdo\Pgsql::setNoticeCallback(?callable `$callback`): void

Set a callback to handle notice and warning messages generated by the backend. This includes messages emitted by PostgreSQL itself, as well as those raised by user-defined SQL functions using `RAISE`. Please note that the actual receipt of these messages depends on the backend setting `client_min_messages`.

### Parameter-Liste

`callback`
  If `null` is passed, the handler is reset to its default state.

  Otherwise, the handler is a callback with the following signature:

  function handler(string `$message`): void
  `message`
    A message generated by the backend.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 Pdo\Pgsql::setNoticeCallback() example

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $pdo->exec('CREATE TABLE parent(id int primary key)');
    $pdo->exec('CREATE TABLE child(id int references parent)');

    $pdo->setNoticeCallback(function ($message) {
        echo $message;
    });

    $pdo->exec('TRUNCATE parent CASCADE');
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    NOTICE:  truncate cascades to table "child"

## Inhaltsverzeichnis

- Pdo\Pgsql::copyFromArray — Copy data from a PHP array into a table
- Pdo\Pgsql::copyFromFile — Copy data from file into table
- Pdo\Pgsql::copyToArray — Copy data from database table into PHP array
- Pdo\Pgsql::copyToFile — Copy data from table into file
- Pdo\Pgsql::escapeIdentifier — Escapes a string for use as an SQL identifier
- Pdo\Pgsql::getNotify — Get asynchronous notification
- Pdo\Pgsql::getPid — Get the PID of the backend process handling this connection
- Pdo\Pgsql::lobCreate — Creates a new large object
- Pdo\Pgsql::lobOpen — Opens an existing large object stream
- Pdo\Pgsql::lobUnlink — Deletes the large object
- Pdo\Pgsql::setNoticeCallback — Set a callback to handle notice and warning messages generated by the backend

# SQLite PDO-Treiber (PDO_SQLITE)

## Einführung

Der PDO_SQLITE-Treiber implementiert das PHP Data Objects (PDO) Interface, um Zugriff auf SQLite3-Datenbanken zu ermöglichen.

> Hinweis:

> PDO_SQLITE erlaubt es Zeichenketten, abgesehen von Datenströmen, mit `PDO::PARAM_LOB` zu nutzen.

## Installation

The PDO_SQLITE PDO driver is enabled by default. To disable, --without-pdo-sqlite[=DIR] may be used, where the optional `[=DIR]` is the sqlite base install directory. As of PHP 7.4.0 » libsqlite ≥ 3.5.0 is required. Formerly, the bundled libsqlite could have been used instead, and was the default, if `[=DIR]` has been omitted.

> Hinweis: Additional setup on Windows as of PHP 7.4.0

> Diese Erweiterung benötigt DLL-Dateien. die für Windows verfügbar seien müssen. Der FAQ-Eintrag " Wie füge ich unter Windows PATH mein PHP-Verzeichnis hinzu?" gibt hierzu weitere Informationen. Obwohl ein einfaches Kopieren der DLL-Dateien vom PHP-Verzeichnis in den Windows-Systemordner auch funktioniert (weil der Systemordner immer im PATH enthalten ist), ist dieses Vorgehen nicht empfehlenswert. Diese Erweiterung benötigt die folgenden Dateien im PATH: libsqlite3.dll.

# PDO_SQLITE DSN

(PHP 5 >= 5.1.0, PHP 7, PECL PDO_SQLITE >= 0.2.0)

PDO_SQLITE DSN — Verbindungen zu SQLite-Datenbanken aufbauen

### Beschreibung

Der PDO_SQLITE-Data Source Name (DSN) setzt sich aus den folgenden Elementen zusammen:

DSN-Präfix (SQLite 3)

  Das DSN-Präfix ist `sqlite:`.

  - Um eine Datenbank auf dem Datenträger anzusprechen, wird ihr absoluter Pfad an das DSN-Präfix angehängt.

  - Um eine Datenbank im Speicher zu erzeugen, wird `:memory:` an das DSN-Präfix angefügt.

  - Besteht der DSN nur aus dem Präfix, wird eine temporäre Datenbank verwendet, die gelöscht wird, wenn die Verbindung geschlossen wird.

### Beispiele

Beispiel #1 PDO_SQLITE-DSN-Beispiele

Die folgenden Beispiele zeigen PDO_SQLITE DSN, die genutzt werden, um Verbindungen zu SQLite-Datenbanken aufzubauen:

    sqlite:/opt/databases/mydb.sq3
    sqlite::memory:
    sqlite:

# PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — Alias von Pdo\Sqlite::createAggregate()

### Beschreibung

public function PDO::sqliteCreateAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Diese Methode ist ein Alias für: Pdo\Sqlite::createAggregate().

# PDO::sqliteCreateCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

PDO::sqliteCreateCollation — Alias von Pdo\Sqlite::createCollation()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

public function PDO::sqliteCreateCollation(string `$name`, callable `$callback`): bool

Diese Methode ist ein Alias für: Pdo\Sqlite::createCollation().

# PDO::sqliteCreateFunction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateFunction — Alias von Pdo\Sqlite::createFunction()

### Beschreibung

public function PDO::sqliteCreateFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

Diese Methode ist ein Alias für: Pdo\Sqlite::createFunction().

### Changelog

Version | Beschreibung
--- | ---
7.1.4 | Der Parameter `flags` wurde hinzugefügt.

## Inhaltsverzeichnis

- PDO_SQLITE DSN — Verbindungen zu SQLite-Datenbanken aufbauen
- PDO::sqliteCreateAggregate — Alias von Pdo\Sqlite::createAggregate
- PDO::sqliteCreateCollation — Alias von Pdo\Sqlite::createCollation
- PDO::sqliteCreateFunction — Alias von Pdo\Sqlite::createFunction

# The Pdo\Sqlite class

(PHP 8 >= 8.4.0)

## Einführung

A PDO subclass representing a connection using the SQLite PDO driver.

This driver supports a dedicated SQL query parser for the SQLite dialect. It can handle the following:

- Single, double-quoted, and backtick literals, with doubling as escaping mechanism.
- Square brackets quoting for identifiers.
- Two-dashes and C-style comments (non-nested).

## Klassenbeschreibung

class Pdo\Sqlite extends PDO {
/* Geerbte Konstanten */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* Konstanten */
public const int DETERMINISTIC;
public const int OPEN_READONLY;
public const int OPEN_READWRITE;
public const int OPEN_CREATE;
public const int ATTR_OPEN_FLAGS;
public const int ATTR_READONLY_STATEMENT;
public const int ATTR_EXTENDED_RESULT_CODES;
/* Methoden */
public function createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool
public function loadExtension(string `$name`): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
/* Geerbte Methoden */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## Vordefinierte Konstanten

`Pdo\Sqlite::DETERMINISTIC`
`Pdo\Sqlite::OPEN_READONLY`
`Pdo\Sqlite::OPEN_READWRITE`
`Pdo\Sqlite::OPEN_CREATE`
`Pdo\Sqlite::ATTR_OPEN_FLAGS`
`Pdo\Sqlite::ATTR_READONLY_STATEMENT`
`Pdo\Sqlite::ATTR_EXTENDED_RESULT_CODES`

# Pdo\Sqlite::createAggregate

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createAggregate — Registriert eine benutzerdefinierte Aggregationsfunktion zur Verwendung in SQL-Anweisungen

### Beschreibung

public function Pdo\Sqlite::createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

Diese Methode entspricht Pdo\Sqlite::createFunction(), mit dem Unterschied, dass sie Funktionen registriert, die verwendet werden können, um ein über alle Zeilen einer Abfrage aggregiertes Ergebnis zu berechnen.

Der Hauptunterschied zwischen dieser Methode und Pdo\Sqlite::createFunction() ist, dass zwei Funktionen notwendig sind, um das Aggregat zu verwalten.

Tipp

Mit dieser Methode ist es möglich, native SQL-Funktionen zu überschreiben.

### Parameter-Liste

`name`
  Der Name der in SQL-Anweisungen genutzten Funktion.
`step`
  Die Callback-Funktion, welche für jede Zeile des Abfrageergebnisses ausgeführt wird. Der Callback sollte das Ergebnis akkumulieren und im Aggregationskontext speichern.

  Es ist notwendig, diese Funktion wie folgt zu definieren:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`
    Der Aggregationskontext. `null` für die erste Zeile; in den folgenden Zeilen hat er den Wert, der zuvor von der Schritt-Funktion zurückgegeben wurde. Sie sollten diesen nutzen, um den Aggregationszustand zu bewahren.
  `rownumber`
    Die Nummer der aktuellen Zeile.
  `value`
    Das erste Argument, das an das Aggregat übergeben wird.
  `values`
    Weitere Argumente, die an das Aggregat übergeben werden.
  Der Rückgabewert dieser Funktion wird im nächsten Aufruf der Schritt- oder End-Funktion als Argument für `context` verwendet.
`finalize`
  Die Callback-Funktion, die die Informationen aller Zeilen aggregiert. Sind alle Zeilen abgearbeitet, wird diese Funktion aufgerufen. Diese sollte dann die Daten des Aggregationskontexts auswerten und das Ergebnis zurückgeben. Diese Callback-Funktion sollte einen Variablentyp zurückgeben, der von SQLite verstanden wird, z. B. den Skalar-Typ.

  Diese Funktion ist wie folgt zu definieren:

  function fini(mixed `$context`, int `$rowcount`): mixed
  `context`

    Enthält den Rückgabewert des letzten Aufrufs der Schritt-Funktion.

  `rowcount`

    Enthält die Anzahl an Zeilen, die bereits aggregiert wurden.

  Der Rückgabewert dieser Funktion wird als Rückgabewert für die Aggregation genutzt.
`numArgs`
  Hinweis für den SQLite-Parser, ob die Callback-Funktion eine bestimmte Anzahl an Parametern erwartet.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Pdo\Sqlite::createAggregate()-Beispiel

In diesem Beispiel wird eine benutzerdefinierte Aggregationsfunktion mit dem Namen `max_length` erstellt, die in SQL-Abfragen verwendet werden kann.

In diesem Beispiel erzeugen wir eine Aggregationsfunktion mit dem Namen `max_length`, die die Länge der längsten Zeichenkette innerhalb einer der Tabellenspalten ermittelt. Für jede durchlaufene Zeile wird die Funktion `max_len_step` mit dem Parameter `$context` aufgerufen. Der Parameter "context" ist eine normale PHP-Variable, welche ein array oder sogar ein object beinhalten kann. In diesem Beispiel benötigen wir ihn als Speicher für die größte bisher gefundene Länge. Wenn die Zeichenkette in `$string` länger ist, als die aktuell längste, wird der Inhalt von "context" mit der neuen Länge überschrieben.

Nachdem alle Zeilen abgearbeitet wurden, ruft SQLite die `max_len_finalize`-Funktion auf, um das Endergebnis zu ermitteln. Auf Basis der in `$context` gesammelten Daten können beliebige Berechnungen durchgeführt werden. In diesem einfachen Beispiel wurde das Ergebnis bereits während der Abfrage berechnet, so dass der Wert von "context" direkt zurückgegeben werden kann.

    <?php
    $data = [
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
    ];
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->execute(array($str));
    }
    $insert = null;

    function max_len_step($context, $row_number, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $row_count)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

    ?>

Tipp

Es ist NICHT ratsam, eine Kopie der Werte in 'context' zu speichern, um diese dann am Ende auszuwerten. Das würde dazu führen, dass SQLite eine große Menge an Speicher benötigt, um die Abfrage abzuarbeiten - stellen Sie sich vor, wie viel Speicherplatz Sie benötigen würden, wenn eine Million Zeilen im Speicher abgelegt würden, von denen jede eine Zeichenkette von 32 Byte Länge enthält.

### Siehe auch

- Pdo\Sqlite::createFunction() - Registriert eine benutzerdefinierte Funktion zur Verwendung in SQL-Anweisungen
- Pdo\Sqlite::createCollation() - Registers a user-defined function for use as a collating function in SQL statements
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createCollation

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createCollation — Registers a user-defined function for use as a collating function in SQL statements

### Beschreibung

public function Pdo\Sqlite::createCollation(string `$name`, callable `$callback`): bool

This method is similar to Pdo\Sqlite::createFunction() except that it registers functions that are used to collate strings.

### Parameter-Liste

`name`
  Name of the SQL collating function to be created or redefined.
`callback`
  Callback function that defines the behaviour of a collation. It must accept two strings and return `-1`, `0`, or `1` if the first string sorts before, sorts identically, or sorts after the second string respectively. An internal function that behaves like this is strcmp().

  This function need to be defined as:

  function collation(string `$string1`, string `$string2`): int

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Pdo\Sqlite::createCollation() example

    <?php
    $db = new Pdo\Sqlite('sqlite::memory:');
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->sqliteCreateCollation('NATURAL_CMP', 'strnatcmp');
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1") as $row) {
      echo $row['col1'] . "\n";
    }
    echo "\n";
    foreach ($db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP") as $row) {
      echo $row['col1'] . "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    a1
    a10
    a2

    a1
    a2
    a10

### Siehe auch

- Pdo\Sqlite::createFunction() - Registriert eine benutzerdefinierte Funktion zur Verwendung in SQL-Anweisungen
- Pdo\Sqlite::createAggregate() - Registriert eine benutzerdefinierte Aggregationsfunktion zur Verwendung in SQL-Anweisungen
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createFunction

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createFunction — Registriert eine benutzerdefinierte Funktion zur Verwendung in SQL-Anweisungen

### Beschreibung

public function Pdo\Sqlite::createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

This method allows PHP function to be registered with SQLite as a user-defined function, so that it can be called within SQL queries. The defined function can be used in any SQL query that allows function calls, for example `SELECT`, `UPDATE`, or triggers.

Tipp

By using this method it is possible to override native SQL functions.

### Parameter-Liste

`function_name`
  Der Name der Funktion, der in SQL-Anweisungen genutzt wird.
`callback`
  Die Callback-Funktion, die die definierte SQL-Funktion verarbeitet.

  > Hinweis: Die Callback-Funktionen sollten einen Typ zurückgeben, der von SQLite verstanden wird, z. B. den Skalar-Typ.

  Diese Funktion muss wie folgt definiert werden:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    Das erste Argument, das an die SQL-Funktion übergeben wird.

  `values`

    Weitere Argumente, die an die SQL-Funktion übergeben werden.

`num_args`
  Die Anzahl von Argumenten, die die SQL-Funktion erwartet. Ist dieser Parameter `-1`, dann kann die SQL-Funktion eine beliebige Anzahl von Argumenten annehmen.
`flags`
  Eine Bitmaske von Flags. Zurzeit wird nur `Pdo\Sqlite::DETERMINISTIC` unterstützt, das angibt, dass die Funktion für dieselben Eingaben innerhalb einer einzelnen SQL-Anweisung immer dasselbe Ergebnis zurückgibt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Pdo\Sqlite::createFunction()-Beispiel

In diesem Beispiel wird eine Funktion verwendet, die die SHA256-Prüfsumme einer Zeichenkette berechnet und anschließend umgekehrt. Wenn die SQL-Anweisung ausgeführt wird, gibt sie den Wert des von unserer Funktion umgewandelten Dateinamens zurück. Die in $zeilen zurückgegebenen Daten enthalten das verarbeitete Ergebnis.

Das Schöne an dieser Technik ist, dass das Ergebnis der Abfrage nicht in einer `foreach`-Schleife nachbearbeitet werden muss.

    <?php
    function sha256_und_umkehren($string)
    {
        return strrev(hash('sha256', $string));
    }

    $db = new Pdo\Sqlite('sqlite::sqlitedb');
    $db->createFunction('sha256rev', 'sha256_und_umkehren', 1);
    $zeilen = $db->query('SELECT sha256rev(dateiname) FROM dateien')->fetchAll();
    ?>

### Siehe auch

- Pdo\Sqlite::createAggregate() - Registriert eine benutzerdefinierte Aggregationsfunktion zur Verwendung in SQL-Anweisungen
- Pdo\Sqlite::createCollation() - Registers a user-defined function for use as a collating function in SQL statements
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::loadExtension

(PHP 8 >= 8.4.0)

Pdo\Sqlite::loadExtension — Description

### Beschreibung

public function Pdo\Sqlite::loadExtension(string `$name`): void
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Description.

### Parameter-Liste

`name`
  Description.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

When does this function issue `E_*` level errors, and/or throw Exceptions.

### Beispiele

Beispiel #1 Pdo\Sqlite::loadExtension() example

Description.

    <?php
    echo "Code example";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Code example

### Anmerkungen

> Hinweis: Any notes that don't fit anywhere else should go here.

### Siehe auch

- ClassName::otherMethodName()
- some_function()

# Pdo\Sqlite::openBlob

(PHP 8 >= 8.4.0)

Pdo\Sqlite::openBlob — Description

### Beschreibung

public function Pdo\Sqlite::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Description.

### Parameter-Liste

`table`
  Description.
`column`
  Description.
`rowid`
  Description.
`dbname`
  Description.
`flags`
  One of the `Pdo\Sqlite::OPEN_*`

### Rückgabewerte

Description.

### Fehler/Exceptions

When does this function issue `E_*` level errors, and/or throw Exceptions.

### Beispiele

Beispiel #1 Pdo\Sqlite::openBlob() example

Description.

    <?php
    echo "Code example";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Code example

### Anmerkungen

> Hinweis: Any notes that don't fit anywhere else should go here.

### Siehe auch

- ClassName::otherMethodName()
- some_function()

## Inhaltsverzeichnis

- Pdo\Sqlite::createAggregate — Registriert eine benutzerdefinierte Aggregationsfunktion zur Verwendung in SQL-Anweisungen
- Pdo\Sqlite::createCollation — Registers a user-defined function for use as a collating function in SQL statements
- Pdo\Sqlite::createFunction — Registriert eine benutzerdefinierte Funktion zur Verwendung in SQL-Anweisungen
- Pdo\Sqlite::loadExtension — Description
- Pdo\Sqlite::openBlob — Description

- Installation/Konfiguration
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Verbindungen und Verbindungsmanagement
- Transaktionen und auto-commit
- Prepared Statements und Stored Procedures
- Fehler und Fehlerbehandlung
- Large Objects (LOBs)
- PDO — Die Klasse PDO
  - PDO::beginTransaction — Startet eine Transaktion
  - PDO::commit — Bestätigt eine Transaktion
  - PDO::connect — Connect to a database and return a PDO subclass for drivers that support it
  - PDO::__construct — Erzeugt eine PDO-Instanz, die eine Datenbankverbindung darstellt
  - PDO::errorCode — Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Datenbank-Handle verknüpft ist
  - PDO::errorInfo — Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Datenbank-Handle verknüpft sind
  - PDO::exec — Führt ein SQL-Statement aus und liefert die Anzahl der betroffenen Zeilen
  - PDO::getAttribute — Ruft ein Attribut einer Datenbankverbindung ab
  - PDO::getAvailableDrivers — Liefert ein Array mit den verfügbaren PDO-Treibern
  - PDO::inTransaction — Prüft, ob es eine offene Transaktion gibt
  - PDO::lastInsertId — Liefert die ID der zuletzt eingefügten Zeile oder den Wert der zuletzt eingefügten Sequenz
  - PDO::prepare — Bereitet eine Anweisung zur Ausführung vor und liefert ein Anweisungsobjekt
  - PDO::query — Bereitet eine SQL-Anweisung ohne Platzhalter vor und führt sie aus
  - PDO::quote — Setzt eine Zeichenkette für die Verwendung in einer Abfrage in Anführungszeichen
  - PDO::rollBack — Macht eine Transaktion rückgängig (Rollback)
  - PDO::setAttribute — Setzt ein Attribut
- PDOStatement — Die Klasse PDOStatement
  - PDOStatement::bindColumn — Bindet eine Spalte an eine PHP-Variable
  - PDOStatement::bindParam — Bindet einen Parameter an den angegebenen Variablennamen
  - PDOStatement::bindValue — Bindet einen Wert an einen Parameter
  - PDOStatement::closeCursor — Schließt den Cursor, damit die Anweisung erneut ausgeführt werden kann
  - PDOStatement::columnCount — Liefert die Anzahl der Spalten in der Ergebnismenge
  - PDOStatement::debugDumpParams — Gibt Informationen über einen vorbereiteten SQL-Befehl aus
  - PDOStatement::errorCode — Ruft den SQLSTATE-Code ab, der mit der letzten Operation über das Anweisungs-Handle verknüpft ist
  - PDOStatement::errorInfo — Ruft die erweiterten Fehlerinformationen ab, die mit der letzten Operation über das Anweisungs-Handle verknüpft sind
  - PDOStatement::execute — Führt ein Prepared Statement aus
  - PDOStatement::fetch — Ruft die nächste Zeile aus einer Ergebnismenge ab
  - PDOStatement::fetchAll — Ruft die verbleibenden Zeilen aus einer Ergebnismenge ab
  - PDOStatement::fetchColumn — Liefert eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge
  - PDOStatement::fetchObject — Ruft die nächste Zeile ab und liefert sie als Objekt
  - PDOStatement::getAttribute — Ruft ein Attribut einer Anweisung ab
  - PDOStatement::getColumnMeta — Liefert die Metadaten zu einer Spalte einer Ergebnismenge
  - PDOStatement::getIterator — Ermittelt den Iterator der Ergebnismenge
  - PDOStatement::nextRowset — Rückt in einem Anweisungshandle mit mehreren Sätzen von Zeilen (Rowsets) zum nächsten vor
  - PDOStatement::rowCount — Liefert die Anzahl der von der letzten SQL-Anweisung betroffenen Zeilen
  - PDOStatement::setAttribute — Setzt ein Anweisungsattribut
  - PDOStatement::setFetchMode — Legt den standardmäßigen Abrufmodus eine Anweisung fest
- PDORow — Die Klasse PDORow
- PDOException — Die Klasse PDOException
- PDO-Treiber
  - CUBRID PDO Driver — CUBRID PDO Driver (PDO_CUBRID)
  - MS SQL Server PDO Driver — Microsoft SQL Server and Sybase PDO Driver (PDO_DBLIB)
  - Pdo\Dblib — The Pdo\Dblib class
  - Firebird PDO Driver — Firebird PDO Driver (PDO_FIREBIRD)
  - Pdo\Firebird — The Pdo\Firebird class
  - IBM PDO Driver — IBM PDO Driver (PDO_IBM)
  - Informix PDO Driver — Informix PDO Driver (PDO_INFORMIX)
  - MySQL PDO-Treiber — MySQL PDO-Treiber (PDO_MYSQL)
  - Pdo\Mysql — The Pdo\Mysql class
  - MS SQL Server PDO Driver — Microsoft SQL Server PDO Driver (PDO_SQLSRV)
  - Oracle PDO Driver — Oracle PDO Driver (PDO_OCI)
  - ODBC and DB2 PDO Driver — ODBC and DB2 PDO Driver (PDO_ODBC)
  - Pdo\Odbc — The Pdo\Odbc class
  - PostgreSQL PDO Driver — PostgreSQL PDO Driver (PDO_PGSQL)
  - Pdo\Pgsql — The Pdo\Pgsql class
  - SQLite PDO-Treiber — SQLite PDO-Treiber (PDO_SQLITE)
  - Pdo\Sqlite — The Pdo\Sqlite class

- DBA — Abstraktionsschicht für dbm-style-Datenbanken
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Dba\Connection — The Dba\Connection class
  - DBA-Funktionen
- ODBC — ODBC (Unified)
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - ODBC Funktionen
- PDO — PHP Data Objects
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Verbindungen und Verbindungsmanagement
  - Transaktionen und auto-commit
  - Prepared Statements und Stored Procedures
  - Fehler und Fehlerbehandlung
  - Large Objects (LOBs)
  - PDO — Die Klasse PDO
  - PDOStatement — Die Klasse PDOStatement
  - PDORow — Die Klasse PDORow
  - PDOException — Die Klasse PDOException
  - PDO-Treiber

# Anbieterspezifische Datenbankerweiterungen

# CUBRID

# Einführung

These functions allow you to access CUBRID database servers. More information about CUBRID can be found at » CUBRID.

Documentation for CUBRID can be found at » CUBRID Documentation.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

In order to have these functions available, you must install CUBRID, and compile CUBRID PHP Library with CUBRID support.

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/cubrid.

Eine DLL-Datei für diese PECL-Erweiterung steht derzeit nicht zur Verfügung. Weitere Details finden Sie im Abschnitt zum Kompilieren für Windows.

For information about manual installation on Linux and Windows systems, please read the file build-guide.html included in the package.

## Laufzeit-Konfiguration

There is no runtime configuration now.

## Ressource-Typen

There are four resource types used in CUBRID. The first one is the link identifier for a database connection, the second is the resource which holds the result of a query, and the last two a resource which holds the query results of BLOB/CLOB data types.

## connection identifier

A connection identifier returned by cubrid_connect(), cubrid_connect_with_url(), cubrid_pconnect() and cubrid_pconnect_with_url().

## request identifier

A request identifier returned by cubrid_prepare() and cubrid_execute().

## LOB identifier

A LOB identifier returned by cubrid_lob_get().

## LOB2 identifier

A LOB identifier returned by cubrid_lob2_new() or get from the result set.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

The following constants can be used when executing SQL statement. They can be passed to cubrid_prepare() and cubrid_execute().

CUBRID SQL execution flags
Constant | Description
--- | ---
`CUBRID_INCLUDE_OID` | Determine whether to get OID during query execution.
`CUBRID_ASYNC` | Execute the query in asynchronous mode.
`CUBRID_EXEC_QUERY_ALL` | Execute the query in synchronous mode. This flag must be set when executing multiple SQL statements.

The following constants can be used when fetching the results to specify fetch behaviour. They can be passed to cubrid_fetch() and cubrid_fetch_array().

CUBRID fetch flags
Constant | Description
--- | ---
`CUBRID_NUM` | Get query result as a numeric array (0-default).
`CUBRID_ASSOC` | Get query result as an associative array.
`CUBRID_BOTH` | Get query result as both numeric and associative arrays (default value).
`CUBRID_OBJECT` | Get query result as an object.
`CUBRID_LOB` | The constant CUBRID_LOB can be used when you want to operate the lob object. It can be passed to cubrid_fetch(), cubrid_fetch_row(), cubrid_fetch_array(), cubrid_fetch_assoc() and cubrid_fetch_object().

The following constants can be used when positioning the cursor in query results. They can be passed to or returned by cubrid_move_cursor().

CUBRID cursor position flags
Constant | Description
--- | ---
`CUBRID_CURSOR_FIRST` | Move current cursor to the first position in the result.
`CUBRID_CURSOR_CURRENT` | Move current cursor as a default value if the origin is not specified.
`CUBRID_CURSOR_LAST` | Move current cursor to the last position in the result.
`CUBRID_CURSOR_SUCCESS` | Returned value of cubrid_move_cursor() function in case of success. This flag has been removed from 8.4.1.
`CUBRID_NO_MORE_DATA` | Returned value of cubrid_move_cursor() function in case of failure. This flag has been removed from 8.4.1.
`CUBRID_CURSOR_ERROR` | Returned value of cubrid_move_cursor() function in case of failure. This flag has been removed from 8.4.1.

The following constants can be used when setting the auto-commit mode for the database connection. They can be passed to cubrid_set_autocommit() or returned by cubrid_get_autocommit().

CUBRID auto-commit mode flags
Constant | Description
--- | ---
`CUBRID_AUTOCOMMIT_TRUE` | Enable the auto-commit mode.
`CUBRID_AUTOCOMMIT_FALSE` | Disable the auto-commit mode.

The following constants can be used when setting the database parameter. They can be passed to cubrid_set_db_parameter().

CUBRID parameter flags
Constant | Description
--- | ---
`CUBRID_PARAM_ISOLATION_LEVEL` | Transaction isolation level for the database connection.
`CUBRID_PARAM_LOCK_TIMEOUT` | Transaction timeout in seconds.

The following constants can be used when setting the transaction isolation level. They can be passed to cubrid_set_db_parameter() or returned by cubrid_get_db_parameter().

CUBRID isolation level flags
Constant | Description
--- | ---
`TRAN_COMMIT_CLASS_UNCOMMIT_INSTANCE` | The lowest isolation level (1). A dirty, non-repeatable or phantom read may occur for the tuple and a non-repeatable read may occur for the table as well.
`TRAN_COMMIT_CLASS_COMMIT_INSTANCE` | A relatively low isolation level (2). A dirty read does not occur, but non-repeatable or phantom read may occur.
`TRAN_REP_CLASS_UNCOMMIT_INSTANCE` | The default isolation of CUBRID (3). A dirty, non-repeatable or phantom read may occur for the tuple, but repeatable read is ensured for the table.
`TRAN_REP_CLASS_COMMIT_INSTANCE` | A relatively low isolation level (4). A dirty read does not occur, but non-repeatable or phantom read may.
`TRAN_REP_CLASS_REP_INSTANCE` | A relatively high isolation level (5). A dirty or non-repeatable read does not occur, but a phantom read may.
`TRAN_SERIALIZABLE` | The highest isolation level (6). Problems concerning concurrency (e.g. dirty read, non-repeatable read, phantom read, etc.) do not occur.

The following constants can be used when getting schema information. They can be passed to cubrid_schema().

CUBRID schema flags
Constant | Description
--- | ---
`CUBRID_SCH_CLASS` | Get name and type of table in CUBRID.
`CUBRID_SCH_VCLASS` | Get name and type of view in CUBRID.
`CUBRID_SCH_QUERY_SPEC` | Get the query definition of view.
`CUBRID_SCH_ATTRIBUTE` | Get the attributes of table column.
`CUBRID_SCH_CLASS_ATTRIBUTE` | Get the attributes of table.
`CUBRID_SCH_METHOD` | Get the instance method. The instance method is a method called by a class instance. It is used more often than the class method because most operations are executed in the instance.
`CUBRID_SCH_CLASS_METHOD` | Get the class method. The class method is a method called by a class object. It is usually used to create a new class instance or to initialize it. It is also used to access or update class attributes.
`CUBRID_SCH_METHOD_FILE` | Get the information of the file where the method of the table is defined.
`CUBRID_SCH_SUPERCLASS` | Get the name and type of table which table inherites attributes from.
`CUBRID_SCH_SUBCLASS` | Get the name and type of table which inherites attributes from this table.
`CUBRID_SCH_CONSTRAINT` | Get the table constraints.
`CUBRID_SCH_TRIGGER` | Get the table triggers.
`CUBRID_SCH_CLASS_PRIVILEGE` | Get the privilege information of table.
`CUBRID_SCH_ATTR_PRIVILEGE` | Get the privilege information of column.
`CUBRID_SCH_DIRECT_SUPER_CLASS` | Get the direct super table of table.
`CUBRID_SCH_PRIMARY_KEY` | Get the table primary key.
`CUBRID_SCH_IMPORTED_KEYS` | Get imported keys of table.
`CUBRID_SCH_EXPORTED_KEYS` | Get exported keys of table.
`CUBRID_SCH_CROSS_REFERENCE` | Get reference relationship of two tables.

The following constants can be used when reporting errors. They can be returned from cubrid_error_code_facility().

CUBRID error facility code
Constant | Description
--- | ---
`CUBRID_FACILITY_DBMS` | The error occurred in CUBRID dbms.
`CUBRID_FACILITY_CAS` | The error occurred in CUBRID broker cas.
`CUBRID_FACILITY_CCI` | The error occurred in CUBRID cci.
`CUBRID_FACILITY_CLIENT` | The error occurred in CUBRID PHP client.

# Beispiele

The following is a simple example that establishes a connection between PHP and CUBRID. This section will cover the most basic and notable features. The following code required to connect to CUBRID database, which means CUBRID Server and CUBRID Broker have to be running.

The example below uses the demodb database as an examples. By default it is created during the installation. Make sure it has been created.

Beispiel #1 Example of Data Retrieval

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc-kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * Set server information for CUBRID connection. host_ip is the IP
             * address where the CUBRID Broker is installed (localhost in this
             * example), and host_port is the port number of the CUBRID Broker.
             * The port number is the default given during the installation.
             * For details, see "Administrator's Guide."
             */
            $host_ip = "localhost";
            $host_port = 33000;
            $db_name = "demodb";
            /**
             * Connect to CUBRID Server. Do not make the actual connection, but
             * only retain the connection information. The reason for not making
             * the actual connection is to handle transaction more efficiently
             * in the 3-tier architecture.
             */
            $cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

            if (!$cubrid_con) {
                echo "Database Connection Error";
                exit;
            }
        ?>
        <?php
            $sql = "select sports, count(players) as players from event group by sports";
            /**
             * Request the CUBRID Server for the results of the SQL statement.
             * Now make the actual connection to the CUBRID Server.
             */
            $result = cubrid_execute($cubrid_con, $sql);

            if ($result) {
                /**
                 * Get the column names from the result set created by the SQL query.
                 */
                $columns = cubrid_column_names($result);
                /**
                 * Get the number of columns in the result set created by the SQL query.
                 */
                $num_fields = cubrid_num_cols($result);
                /**
                 * List the column names of the result set on the screen.
                 */
                echo "<tr>";

                while (list($key, $colname) = each($columns)) {
                    echo "<td align=center>$colname</td>";
                }

                echo "</tr>";

                /**
                 * Get the results from the result set.
                 */
                while ($row = cubrid_fetch($result)) {
                    echo "<tr>";

                    for ($i = 0; $i < $num_fields; $i++) {
                        echo "<td align=center>";
                        echo $row[$i];
                        echo "</td>";
                    }

                    echo "</tr>";
                }
            }
            /**
             * The PHP module in the CUBRID runs in a 3-tier architecture. Even when
             * calling SELECT for transaction processing, it is processed as a part
             * of the transaction. Therefore, the transaction needs to be rolled back
             * by calling commit or rollback even though SELECT was called for smooth
             * performance.
             */
            cubrid_commit($cubrid_con);
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

Beispiel #2 Example of Data Insertion

    <html>
        <head>
        <meta http-equiv="content-type" content="text/html; charset=euc- kr">
        </head>
        <body>
        <center>
        <table border=2>
        <?php
            /**
             * host_ip is the IP address where the CUBRID Broker is installed
             * host_port is the port number of the CUBRID Broker
             * db_name is the name of CUBRID Database
             */
            $host_ip = "localhost";
            $host_port = 33000;
            $db_name = "demodb";
            $cubrid_con = @cubrid_connect($host_ip, $host_port, $db_name);

            if (!$cubrid_con) {
                echo "Database Connection Error";
                exit;
            }
        ?>
        <?php
            $sql = "insert into olympic (host_year,host_nation,host_city,"
                . "opening_date,closing_date) values (2008, 'China', 'Beijing',"
                . "to_date('08-08-2008','mm-dd- yyyy'),to_date('08-24-2008','mm-dd-yyyy')) ;";
            $result = cubrid_execute($cubrid_con, $sql);
            if ($result) {
                /**
                 * Handled successfully, so commit.
                 */
                cubrid_commit($cubrid_con);
                echo "Inserted successfully ";
            } else {
                /**
                 * Error occurred, so the error message is output and rollback is called.
                 */
                echo cubrid_error_msg();
                cubrid_rollback($cubrid_con);
            }
            cubrid_disconnect($cubrid_con);
        ?>
        </body>
        </html>

# CUBRID Funktionen

# cubrid_bind

(PECL CUBRID >= 8.3.0)

cubrid_bind — Bind variables to a prepared statement as parameters

### Beschreibung

function cubrid_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

The cubrid_bind() function is used to bind values to a corresponding named or question mark placeholder in the SQL statement that was passed to cubrid_prepare(). If `bind_value_type` is not given, string will be the default.

> Hinweis: If the type of data to be bound is BLOB/CLOB, CUBRID will try to map the data as a PHP stream. If the actually bind value type is not stream, CUBRID will convert it to string, and use it as the full path and file name of a file on the client filesystem. If the type of data to be bound explicitly is ENUM, the `bind_value` argument should be the enum element which is in string format. In CUBRID shard environment, the `bind_value_type` must be included in the cubrid_bind() function.

The following table shows the types of substitute values.

CUBRID Bind Data Types
Support | Bind Type | Corresponding SQL Type
--- | --- | ---
Supported | STRING | CHAR, VARCHAR
| NCHAR | NCHAR, NVARCHAR
| BIT | BIT, VARBIT
| NUMERIC or NUMBER | SHORT, INT, NUMERIC
| FLOAT | FLOAT
| DOUBLE | DOUBLE
| TIME | TIME
| DATE | DATE
| TIMESTAMP | TIMESTAMP
| OBJECT | OBJECT
| ENUM | ENUM
| BLOB | BLOB
| CLOB | CLOB
| NULL | NULL
Not supported | SET | SET
| MULTISET | MULTISET
| SEQUENCE | SEQUENCE

### Parameter-Liste

`req_identifier`
  Request identifier as a result of cubrid_prepare().
`bind_index`
  Location of binding parameters. It starts with 1.
`bind_value`
  Actual value for binding.
`bind_value_type`
  A type of the value to bind. (It is omitted by default. Thus, the system internally uses string by default. However, you need to specify the exact type of the value as an argument when they are NCHAR, BIT, or BLOB/CLOB).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.3.1 | Added BLOB/CLOB data types support.

### Beispiele

Beispiel #1 cubrid_bind() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE sports='Basketball' and gender='M'");
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $game_req = cubrid_prepare($conn, "SELECT athlete_code FROM game WHERE host_year=1992 and event_code=? and nation_code='USA'");
    cubrid_bind($game_req, 1, $event_code, "number");
    cubrid_execute($game_req);

    printf("--- Dream Team (1992 United States men's Olympic basketball team) ---\n");
    while ($athlete_code = cubrid_fetch_array($game_req, CUBRID_NUM)) {
        $athlete_req = cubrid_prepare($conn, "SELECT name FROM athlete WHERE code=? AND nation_code='USA' AND event='Basketball' AND gender='M'");
        cubrid_bind($athlete_req, 1, $athlete_code[0], "number");
        cubrid_execute($athlete_req);
        $row = cubrid_fetch_assoc($athlete_req);
        printf("%s\n", $row["name"]);
    }

    cubrid_close_request($game_req);
    cubrid_close_request($athlete_req);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    --- Dream Team (1992 United States men's Olympic basketball team) ---
    Stockton John
    Robinson David
    Pippen Scottie
    Mullin C.
    Malone Karl
    Laettner C.
    Jordan Michael
    Johnson Earvin
    Ewing Patrick
    Drexler Clyde
    Bird Larry
    Barkley Charles

Beispiel #2 cubrid_bind() BLOB/CLOB example

    <?php
    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (doc_content CLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(doc_content) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        $fp = fopen("book.txt", "rb");

        cubrid_bind($req, 1, $fp, "clob");
        cubrid_execute($req);
    }
    ?>

Beispiel #3 cubrid_bind() BLOB/CLOB example

    <?php
    $con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
    if ($con) {
        cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
        cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (image BLOB)");
        $sql = "INSERT INTO php_cubrid_lob_test(image) VALUES(?)";
        $req = cubrid_prepare($con, $sql);

        cubrid_bind($req, 1, "cubrid_logo.png", "blob");
        cubrid_execute($req);
    }
    ?>

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement
- cubrid_prepare() - Prepare a SQL statement for execution

# cubrid_close_prepare

(PECL CUBRID >= 8.3.0)

cubrid_close_prepare — Close the request handle

### Beschreibung

function cubrid_close_prepare(resource `$req_identifier`): bool

The cubrid_close_prepare() function closes the request handle given by the `req_identifier` argument, and releases the memory region related to the handle. It is an alias of cubrid_close_request().

### Parameter-Liste

`req_identifier`
  Request identifier.

### Rückgabewerte

Return `true` on success.

### Beispiele

Beispiel #1 cubrid_close_prepare() example

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
    if ($con) {
       echo "connected successfully";
       $req = cubrid_execute ( $con, "select * from members",
                               CUBRID_INCLUDE_OID | CUBRID_ASYNC);
       if ($req) {
          while ( list ($id, $name) = cubrid_fetch ($req) ){
             echo $id;
             echo $name;
          }
          cubrid_close_prepare($req); // or you can use cubrid_close_request($req)
       }
       cubrid_disconnect($con);
    }
    ?>

### Siehe auch

- cubrid_close_request() - Close the request handle

# cubrid_close_request

(PECL CUBRID >= 8.3.0)

cubrid_close_request — Close the request handle

### Beschreibung

function cubrid_close_request(resource `$req_identifier`): bool

The cubrid_close_request() function closes the request handle given by the `req_identifier` argument, and releases the memory region related to the handle. It is an alias of cubrid_close_prepare().

### Parameter-Liste

`req_identifier`
  Request identifier.

### Rückgabewerte

Return `true` on success.

### Beispiele

Beispiel #1 cubrid_close_request() example

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb", "dba", "");
    if ($con) {
       echo "connected successfully";
       $req = cubrid_execute ( $con, "select * from members",
                               CUBRID_INCLUDE_OID | CUBRID_ASYNC);
       if ($req) {
          while ( list ($id, $name) = cubrid_fetch ($req) ){
             echo $id;
             echo $name;
          }
          cubrid_close_request($req); // or you can use cubrid_close_prepare($req)
       }
       cubrid_disconnect($con);
    }
    ?>

### Siehe auch

- cubrid_close_prepare() - Close the request handle

# cubrid_col_get

(PECL CUBRID >= 8.3.0)

cubrid_col_get — Get contents of collection type column using OID

### Beschreibung

function cubrid_col_get(resource `$conn_identifier`, string `$oid`, string `$attr_name`): array

The cubrid_col_get() function is used to get contents of the elements of the collection type (set, multiset, sequence) attribute you requested as an array.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to read.
`attr_name`
  Attribute name that you want to read from the instance.

### Rückgabewerte

Array (0-based numerical array) containing the elements you requested, when process is successful;

`false` (to distinguish the error from the situation of attribute having empty collection or NULL, in case of error, a warning message is shown; in such case you can check the error by using cubrid_error_code()), when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_col_get() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_col_size

(PECL CUBRID >= 8.3.0)

cubrid_col_size — Get the number of elements in collection type column using OID

### Beschreibung

function cubrid_col_size(resource `$conn_identifier`, string `$oid`, string `$attr_name`): int

The cubrid_col_size() function is used to get the number of elements in a collection type (set, multiset, sequence) attribute.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID the instance that you want to work with.
`attr_name`
  Name of the attribute that you want to work with.

### Rückgabewerte

Number of elements, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.3.1 | Change return value: when process is unsuccessful, return false, not -1.

### Beispiele

Beispiel #1 cubrid_col_size() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    $size = cubrid_col_size($conn, $oid, "b");
    var_dump($size);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    int(3)

# cubrid_column_names

(PECL CUBRID >= 8.3.0)

cubrid_column_names — Get the column names in result

### Beschreibung

function cubrid_column_names(resource `$req_identifier`): array

The cubrid_column_names() function is used to get the column names of the query result by using `req_identifier`.

### Parameter-Liste

`req_identifier`
  Request identifier.

### Rückgabewerte

Array of string values containing the column names, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_column_names() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Siehe auch

- cubrid_prepare() - Prepare a SQL statement for execution
- cubrid_execute() - Execute a prepared SQL statement
- cubrid_column_types() - Get column types in result

# cubrid_column_types

(PECL CUBRID >= 8.3.0)

cubrid_column_types — Get column types in result

### Beschreibung

function cubrid_column_types(resource `$req_identifier`): array

The cubrid_column_types() function gets column types of query results by using `req_identifier`.

### Parameter-Liste

`req_identifier`
  Request identifier.

### Rückgabewerte

Array of string values containing the column types, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_column_types() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

### Siehe auch

- cubrid_column_names() - Get the column names in result
- cubrid_prepare() - Prepare a SQL statement for execution
- cubrid_execute() - Execute a prepared SQL statement

# cubrid_commit

(PECL CUBRID >= 8.3.0)

cubrid_commit — Commit a transaction

### Beschreibung

function cubrid_commit(resource `$conn_identifier`): bool

The cubrid_commit() function is used to execute commit on the transaction pointed by `conn_identifier`, currently in progress. Connection to the server is closed after the cubrid_commit() function is called; However, the connection handle is still valid.

In CUBRID PHP, auto-commit mode is disabled by default for transaction management. You can set it by using cubrid_set_autocommit(). You can get its status by using cubrid_get_autocommit(). Before you start a transaction, remember to disable the auto-commit mode.

### Parameter-Liste

`conn_identifier`
  Connection identifier.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_commit() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;
    cubrid_set_autocommit($conn,false);
    if (!cubrid_execute($conn, $sql)) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Siehe auch

- cubrid_rollback() - Roll back a transaction
- cubrid_get_autocommit() - Get auto-commit mode of the connection
- cubrid_set_autocommit() - Set autocommit mode of the connection

# cubrid_connect

(PECL CUBRID >= 8.3.1)

cubrid_connect — Open a connection to a CUBRID Server

### Beschreibung

function cubrid_connect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

The cubrid_connect() function is used to establish the environment for connecting to your server by using your server address, port number, database name, user name, and password. If the user name and password is not given, then the "PUBLIC" connection will be made by default.

### Parameter-Liste

`host`
  Host name or IP address of CUBRID CAS server.
`port`
  Port number of CUBRID CAS server (BROKER_PORT configured in $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Name of database.
`userid`
  User name for the database. If not given, the default value is "public".
`passwd`
  User password. If not given, the default value is "".
`new_link`
  If a second call is made to cubrid_connect() with the same arguments, no new connection will be established, but instead, the connection identifier of the already opened connection will be returned. The `new_link` parameter modifies this behavior and makes cubrid_connect() always open a new connection, even if cubrid_connect() was called before with the same parameters.

### Rückgabewerte

Connection identifier, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_connect() example

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Siehe auch

- cubrid_pconnect() - Öffnet eine dauerhafte Verbindung zu einem CUBRID-Server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
- cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
- cubrid_disconnect() - Close a database connection
- cubrid_close() - Close CUBRID connection

# cubrid_connect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_connect_with_url — Establish the environment for connecting to CUBRID server

### Beschreibung

function cubrid_connect_with_url(
string `$conn_url`,
string `$userid` = ?,
string `$passwd` = ?,
bool `$new_link` = `false`
): resource

The cubrid_connect_with_url() function is used to establish the environment for connecting to your server by using connection information passed with an url string argument. If the HA feature is enabled in CUBRID, you must specify the connection information of the standby server, which is used for failover when failure occurs, in the url string argument of this function. If the user name and password is not given, then the "PUBLIC" connection will be made by default.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : A host name or IP address of the master database
- db_name : A name of the database
- db_user : A name of the database user
- db_password : A database user password
- alhosts : Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts
- rctime : An interval between the attempts to connect to the active broker in which failure occurred. After a failure occurs, the system connects to the broker specified by althosts (failover), terminates the transaction, and then attempts to connect to the active broker of the master database at every rctime. The default value is 600 seconds.
- login_timeout : Timeout value (unit: msec.) for database login. The default value is 0, which means infinite postponement.
- query_timeout : Timeout value (unit: msec.) for query request. Upon timeout, a message to cancel the requested query is sent to the server. The return value can depend on the disconnect_on_query_timeout configuration; even though the message to cancel a request is sent to server, that request may succeed.
- disconnect_on_query_timeout : Configures a value whether to immediately return an error of function being executed upon timeout. The default value is false.

> Hinweis: `?` and `:` that are used as identifiers in PHP connection URL can't be included in the password. The following is an example of a password that is invalid to use as connection URL because it contains "`?:`". $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Passwords that contain `?` or `:` may be passed as a separate parameter. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_connect_with_url($url, "dba", "12?"); If user or password is empty,you can't delete "`:`",the following is an example. $url = "CUBRID:localhost:33000:demodb:::";

### Parameter-Liste

`conn_url`
  A character string that contains server connection information.
`userid`
  User name for the database.
`passwd`
  User password.
`new_link`
  If a second call is made to cubrid_connect_with_url() with the same arguments, no new connection will be established, but instead, the connection identifier of the already opened connection will be returned. The `new_link` parameter modifies this behavior and makes cubrid_connect_with_url() always open a new connection, even if cubrid_connect_with_url() was called before with the same parameters.

### Rückgabewerte

Connection identifier, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_connect_with_url() url without properties example

    <?php
    $conn_url = "CUBRID:localhost:33000:demodb:dba::";
    $con = cubrid_connect_with_url($conn_url);

    if ($con) {
       echo "connected successfully";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

Beispiel #2 cubrid_connect_with_url() url with properties example

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?login_timeout=100";
    $con = cubrid_connect_with_url ($conn_url);

    if ($con) {
       echo "connected successfully";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

### Siehe auch

- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_pconnect() - Öffnet eine dauerhafte Verbindung zu einem CUBRID-Server
- cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
- cubrid_disconnect() - Close a database connection
- cubrid_close() - Close CUBRID connection

# cubrid_current_oid

(PECL CUBRID >= 8.3.0)

cubrid_current_oid — Get OID of the current cursor location

### Beschreibung

function cubrid_current_oid(resource `$req_identifier`): string

The cubrid_current_oid() function is used to get the oid of the current cursor location from the query result. To use cubrid_current_oid(), the query executed must be a updatable query, and the `CUBRID_INCLUDE_OID` option must be included during the query execution.

### Parameter-Liste

`req_identifier`
  Request identifier.

### Rückgabewerte

Oid of current cursor location, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_current_oid() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $res = cubrid_get($conn, $oid);

    print_r($res);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [s_name] => X
        [f_name] => Mixed
    )

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement

# cubrid_disconnect

(PECL CUBRID >= 8.3.0)

cubrid_disconnect — Close a database connection

### Beschreibung

function cubrid_disconnect(resource `$conn_identifier` = ?): bool

The cubrid_disconnect() function closes the connection handle and disconnects from server. If any request handle is not closed at this point, it will be closed. It is similar to the CUBRID MySQL compatible function cubrid_close().

### Parameter-Liste

`conn_identifier`
  Connection identifier.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_disconnect() example

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
       echo "connected successfully";

       $req = cubrid_execute( $con, "create table person(id int,name char(10))");
       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }

       $req = cubrid_execute( $con, "insert into person values(1,'James')");
       if ($req) {
          cubrid_close_request($req);
          cubrid_commit($con);
       } else {
          cubrid_rollback($con);
       }
       cubrid_disconnect($con);
    }
    ?>

### Siehe auch

- cubrid_close() - Close CUBRID connection
- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server

# cubrid_drop

(PECL CUBRID >= 8.3.0)

cubrid_drop — Delete an instance using OID

### Beschreibung

function cubrid_drop(resource `$conn_identifier`, string `$oid`): bool

The cubrid_drop() function is used to delete an instance from database by using the `oid` of the instance.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  Oid of the instance that you want to delete.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_drop() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("--- Before Drop: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    if (cubrid_drop($conn, $oid)) {
        cubrid_commit($conn);
    } else {
        cubrid_rollback($conn);
    }

    cubrid_close_request($req);

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    printf("\n--- After Drop: ---\n");
    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    --- Before Drop: ---
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

    --- After Drop: ---
    array(4) {
      ["a"]=>
      string(1) "2"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "4"
        [1]=>
        string(1) "5"
        [2]=>
        string(1) "7"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "44"
        [1]=>
        string(2) "55"
        [2]=>
        string(2) "66"
        [3]=>
        string(3) "666"
      }
      ["d"]=>
      string(10) "b         "
    }

### Siehe auch

- cubrid_is_instance() - Check whether the instance pointed by OID exists

# cubrid_error_code

(PECL CUBRID >= 8.3.0)

cubrid_error_code — Get error code for the most recent function call

### Beschreibung

function cubrid_error_code(): int

The cubrid_error_code() function is used to get the error code of the error that occurred during the API execution. Usually, it gets the error code when API returns false as its return value.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Error code of the error that occurred, or `0` (zero) if no error occurred.

### Beispiele

Beispiel #1 cubrid_error_code() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_prepare($conn , "SELECT * FROM code WHERE s_name=?");

    $req = @cubrid_execute($req);
    if (!$req) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Error facility: 4
    Error code: -30015
    Error msg: Some parameter not binded

### Siehe auch

- cubrid_error_code_facility() - Get the facility code of error
- cubrid_error_msg() - Get last error message for the most recent function call

# cubrid_error_code_facility

(PECL CUBRID >= 8.3.0)

cubrid_error_code_facility — Get the facility code of error

### Beschreibung

function cubrid_error_code_facility(): int

The cubrid_error_code_facility() function is used to get the facility code (level in which the error occurred) from the error code of the error that occurred during the API execution. Usually, you can get the error code when API returns false as its return value.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Facility code of the error code that occurred: `CUBRID_FACILITY_DBMS`, `CUBRID_FACILITY_CAS`, `CUBRID_FACILITY_CCI`, `CUBRID_FACILITY_CLIENT`.

### Beispiele

Beispiel #1 cubrid_error_code_facility() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = @cubrid_execute($conn, "SELECT * FROM unknown");
    if (!$req) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Error facility: 1
    Error code: -493
    Error msg: Syntax: In line 1, column 15 before END OF STATEMENT
    Syntax error: unexpected 'unknown'

### Siehe auch

- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_msg() - Get last error message for the most recent function call

# cubrid_error_msg

(PECL CUBRID >= 8.3.0)

cubrid_error_msg — Get last error message for the most recent function call

### Beschreibung

function cubrid_error_msg(): string

The cubrid_error_msg() function is used to get the error message that occurred during the use of CUBRID API. Usually, it gets error message when API returns false as its return value.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Error message that occurred.

### Beispiele

Beispiel #1 cubrid_error_msg() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    if (!@cubrid_schema($conn, 100000)) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n",
            cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Error facility: 2
    Error code: -10015
    Error msg: Invalid T_CCI_SCH_TYPE value

### Siehe auch

- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_code_facility() - Get the facility code of error

# cubrid_execute

(PECL CUBRID >= 8.3.0)

cubrid_execute — Execute a prepared SQL statement

### Beschreibung

function cubrid_execute(resource `$conn_identifier`, string `$sql`, int `$option` = 0): resource
function cubrid_execute(resource `$request_identifier`, int `$option` = 0): bool

The cubrid_execute() function is used to execute the given SQL statement. It executes the query by using `conn_identifier` and SQL, and then returns the request identifier created. It is used for simple execution of query, where the parameter binding is not needed. In addition, the cubrid_execute() function is used to execute the prepared statement by means of cubrid_prepare() and cubrid_bind(). At this time, you need to specify arguments of `request_identifier` and `option`.

The `option` is used to determine whether to get OID after query execution and whether to execute the query in synchronous or asynchronous mode. `CUBRID_INCLUDE_OID` and `CUBRID_ASYNC` (or `CUBRID_EXEC_QUERY_ALL` if you want to execute multiple SQL statements) can be specified by using a bitwise OR operator. If not specified, neither of them is selected. If the flag `CUBRID_EXEC_QUERY_ALL` is set, a synchronous mode (sync_mode) is used to retrieve query results, and in such cases the following rules are applied:

- The return value is the result of the first query.
- If an error occurs in any query, the execution is processed as a failure.
- In a query composed of q1 q2 q3, if an error occurs in q2 after q1 succeeds the execution, the result of q1 remains valid. That is, the previous successful query executions are not rolled back when an error occurs.
- If a query is executed successfully, the result of the second query can be obtained using cubrid_next_result().

If the first argument is `request_identifier` to execute the cubrid_prepare() function, you can specify an option, `CUBRID_ASYNC` only.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`sql`
  SQL to be executed.
`option`
  Query execution option `CUBRID_INCLUDE_OID`, `CUBRID_ASYNC`, `CUBRID_EXEC_QUERY_ALL`.
`request_identifier`
  cubrid_prepare() identifier.

### Rückgabewerte

Request identifier, when process is successful and first param is conn_identifier; `true`, when process is successful and first argument is request_identifier,Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Add new option `CUBRID_EXEC_QUERY_ALL`.

### Beispiele

Beispiel #1 cubrid_execute() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $result = cubrid_execute($conn, "SELECT code FROM event WHERE name='100m Butterfly' and gender='M'", CUBRID_ASYNC);
    $row = cubrid_fetch_array($result, CUBRID_ASSOC);
    $event_code = $row["code"];

    cubrid_close_request($result);

    $history_req = cubrid_prepare($conn, "SELECT * FROM history WHERE event_code=?");
    cubrid_bind($history_req, 1, $event_code, "number");
    cubrid_execute($history_req);

    printf("%-20s %-9s %-10s %-5s\n", "athlete", "host_year", "score", "unit");
    while ($row = cubrid_fetch_array($history_req, CUBRID_ASSOC)) {
        printf("%-20s %-9s %-10s %-5s\n",
            $row["athlete"], $row["host_year"], $row["score"], $row["unit"]);
    }

    cubrid_close_request($history_req);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    athlete              host_year score      unit
    Phelps Michael       2004      51.25      time

### Siehe auch

- cubrid_prepare() - Prepare a SQL statement for execution
- cubrid_bind() - Bind variables to a prepared statement as parameters
- cubrid_next_result() - Get result of next query when executing multiple SQL statements
- cubrid_close_request() - Close the request handle
- cubrid_commit() - Commit a transaction
- cubrid_rollback() - Roll back a transaction

# cubrid_fetch

(PECL CUBRID >= 8.3.0)

cubrid_fetch — Fetch the next row from a result set

### Beschreibung

function cubrid_fetch(resource `$result`, int `$type` = CUBRID_BOTH): mixed

The cubrid_fetch() function is used to get a single row from the query result. The cursor automatically moves to the next row after getting the result.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`type`
  Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH, CUBRID_OBJECT. If you want to operate the lob object, you can use CUBRID_LOB.

### Rückgabewerte

Result array or object, when process is successful.

`false`, when there are no more rows; NULL, when process is unsuccessful.

The result can be received either as an array or as an object, and you can decide which data type to use by setting the `type` argument. The `type` variable can be set to one of the following values:

- CUBRID_NUM : Numerical array (0-based)
- CUBRID_ASSOC : Associative array
- CUBRID_BOTH : Numerical & Associative array (default)
- CUBRID_OBJECT : object that has the attribute name as the column name of query result

When `type` argument is omitted, the result will be received using CUBRID_BOTH option as default. When you want to receive query result in object data type, the column name of the result must obey the naming rules for identifiers in PHP. For example, column name such as "count(*)" cannot be received in object type.

### Beispiele

Beispiel #1 cubrid_fetch() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT * FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch($req)) {
        printf("%-40s %-10s %-6s %-20s\n",
            $row["name"], $row["area"], $row["seats"], $row["address"]);
    }

    // if you want to operate lob object, you can use cubrid_fetch($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement
- cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- cubrid_fetch_row() - Return a numerical array with the values of the current row
- cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
- cubrid_fetch_object() - Fetch the next row and return it as an object

# cubrid_free_result

(PECL CUBRID >= 8.3.0)

cubrid_free_result — Free the memory occupied by the result data

### Beschreibung

function cubrid_free_result(resource `$req_identifier`): bool

This function frees the memory occupied by the result data. It returns `true` on success or `false` on failure. Note that it can only frees the client fetch buffer now, and if you want free all memory, use function cubrid_close_request().

### Parameter-Liste

`req_identifier`
  This is the request identifier.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_free_result() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM history WHERE host_year=2004 ORDER BY event_code");
    $row = cubrid_fetch_assoc($req);
    var_dump($row);

    cubrid_free_result($req);
    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(5) {
      ["event_code"]=>
      string(5) "20005"
      ["athlete"]=>
      string(12) "Hayes Joanna"
      ["host_year"]=>
      string(4) "2004"
      ["score"]=>
      string(5) "12.37"
      ["unit"]=>
      string(4) "time"
    }

# cubrid_get

(PECL CUBRID >= 8.3.0)

cubrid_get — Get a column using OID

### Beschreibung

function cubrid_get(resource `$conn_identifier`, string `$oid`, mixed `$attr` = ?): mixed

The cubrid_get() function is used to get the attribute of the instance of the given `oid`. You can get single attribute by using string data type for the `attr` argument, or many attributes by using array data type for the `attr` argument.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to read.
`attr`
  Name of the attribute that you want to read.

### Rückgabewerte

Content of the requested attribute, when process is successful; When `attr` is set with string data type, the result is returned as a string; when `attr` is set with array data type (0-based numerical array), then the result is returned in associative array. When `attr` is omitted, then all attributes are received in array form.

`false` when process is unsuccessful or result is NULL (If error occurs to distinguish empty string from NULL, then it prints the warning message. You can check the error by using cubrid_error_code())

### Beispiele

Beispiel #1 cubrid_get() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Siehe auch

- cubrid_put() - Update a column using OID

# cubrid_get_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_get_autocommit — Get auto-commit mode of the connection

### Beschreibung

function cubrid_get_autocommit(resource `$conn_identifier`): bool

The cubrid_get_autocommit() function is used to get the status of CUBRID database connection auto-commit mode.

For CUBRID 8.4.0, auto-commit mode is disabled by default for transaction management.

For CUBRID 8.4.1, auto-commit mode is enabled by default for transaction management.

### Parameter-Liste

`conn_identifier`
  Connection identifier.

### Rückgabewerte

`true`, when auto-commit is on.

`false`, when auto-commit is off.

`null` on error.

### Siehe auch

- cubrid_set_autocommit() - Set autocommit mode of the connection
- cubrid_commit() - Commit a transaction

# cubrid_get_charset

(PECL CUBRID >= 8.3.0)

cubrid_get_charset — Return the current CUBRID connection charset

### Beschreibung

function cubrid_get_charset(resource `$conn_identifier`): string

This function returns the current CUBRID connection charset and is similar to the CUBRID MySQL compatible function cubrid_client_encoding().

### Parameter-Liste

`conn_identifier`
  The CUBRID connection.

### Rückgabewerte

A string that represents the CUBRID connection charset on success,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_get_charset() example

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('Could not connect.');
    }

    printf("CUBRID current charset: %s\n", cubrid_get_charset($con));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CUBRID current charset: iso8859-1

### Siehe auch

- cubrid_client_encoding() - Return the current CUBRID connection charset

# cubrid_get_class_name

(PECL CUBRID >= 8.3.0)

cubrid_get_class_name — Get the class name using OID

### Beschreibung

function cubrid_get_class_name(resource `$conn_identifier`, string `$oid`): string

The cubrid_get_class_name() function is used to get the class name from `oid`. It doesn't work when selecting data from the system tables, for example db_class.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to check the existence.

### Rückgabewerte

Class name when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_get_class_name() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code", CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);
    $class_name = cubrid_get_class_name($conn, $oid);

    print_r($class_name);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    code

### Siehe auch

- cubrid_is_instance() - Check whether the instance pointed by OID exists
- cubrid_drop() - Delete an instance using OID

# cubrid_get_client_info

(PECL CUBRID >= 8.3.0)

cubrid_get_client_info — Return the client library version

### Beschreibung

function cubrid_get_client_info(): string

This function returns a string that represents the client library version.

### Parameter-Liste

### Rückgabewerte

A string that represents the client library version on success,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_get_client_info() example

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

# cubrid_get_db_parameter

(PECL CUBRID >= 8.3.0)

cubrid_get_db_parameter — Returns the CUBRID database parameters

### Beschreibung

function cubrid_get_db_parameter(resource `$conn_identifier`): array

This function returns the CUBRID database parameters,Bei einem Fehler wird `false` zurückgegeben.. It returns an associative array with the values for the following parameters:

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`
- `PARAM_MAX_STRING_LENGTH`
- `PARAM_AUTO_COMMIT`

Database parameters
Parameter | Description
--- | ---
PARAM_ISOLATION_LEVEL | The transaction isolation level.
LOCK_TIMEOUT | CUBRID provides the lock timeout feature, which sets the waiting time (in seconds) for the lock until the transaction lock setting is allowed. The default value of the lock_timeout_in_secs parameter is -1, which means the application client will wait indefinitely until the transaction lock is allowed.
PARAM_AUTO_COMMIT | In CUBRID PHP, auto-commit mode is disabled by default for transaction management. It can be set by using cubrid_set_autocommit().

The following table shows the isolation levels from 1 to 6. It consists of table schema (row) and isolation level:

Levels of Isolation Supported by CUBRID
Name | Description
--- | ---
SERIALIZABLE (6) | In this isolation level, problems concerning concurrency (e.g. dirty read, non-repeatable read, phantom read, etc.) do not occur.
REPEATABLE READ CLASS with REPEATABLE READ INSTANCES (5) | Another transaction T2 cannot update the schema of table A while transaction T1 is viewing table A. Transaction T1 may experience phantom read for the record R that was inserted by another transaction T2 when it is repeatedly retrieving a specific record.
REPEATABLE READ CLASS with READ COMMITTED INSTANCES (or CURSOR STABILITY) (4) | Another transaction T2 cannot update the schema of table A while transaction T1 is viewing table A. Transaction T1 may experience R read (non-repeatable read) that was updated and committed by another transaction T2 when it is repeatedly retrieving the record R.
REPEATABLE READ CLASS with READ UNCOMMITTED INSTANCES (3) | Default isolation level. Another transaction T2 cannot update the schema of table A while transaction T1 is viewing table A. Transaction T1 may experience R' read (dirty read) for the record that was updated but not committed by another transaction T2.
READ COMMITTED CLASS with READ COMMITTED INSTANCES (2) | Transaction T1 may experience A' read (non-repeatable read) for the table that was updated and committed by another transaction T2 while it is viewing table A repeatedly. Transaction T1 may experience R' read (non-repeatable read) for the record that was updated and committed by another transaction T2 while it is retrieving the record R repeatedly.
READ COMMITTED CLASS with READ UNCOMMITTED INSTANCES (1) | Transaction T1 may experience A' read (non-repeatable read) for the table that was updated and committed by another transaction T2 while it is repeatedly viewing table A. Transaction T1 may experience R' read (dirty read) for the record that was updated but not committed by another transaction T2.

### Parameter-Liste

`conn_identifier`
  The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.

### Rückgabewerte

An associative array with CUBRID database parameters; on success,Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Change LOCK_TIMEOUT to PARAM_LOCK_TIMEOUT, and MAX_STRING_LENGTH to PARAM_MAX_STRING_LENGTH in result.

### Beispiele

Beispiel #1 cubrid_get_db_parameter() example

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Siehe auch

- cubrid_set_db_parameter() - Sets the CUBRID database parameters
- cubrid_get_autocommit() - Get auto-commit mode of the connection

# cubrid_get_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_get_query_timeout — Get the query timeout value of the request

### Beschreibung

function cubrid_get_query_timeout(resource `$req_identifier`): int

The cubrid_get_query_timeout() function is used to get the query timeout of the request.

### Parameter-Liste

`req_identifier`
  Request identifier.

### Rückgabewerte

Returns the query timeout value in milliseconds of the current request on success,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_get_query_timeout() example

    <?php

    $host = "localhost";
    $port = 33000;
    $db = "demodb";

    $conn =
    cubrid_connect_with_url("CUBRID:$host:$port:$db:::?login_timeout=50000&query_timeout=5000&disconnect_on_query_timeout=yes");

    $req = cubrid_prepare($conn, "SELECT * FROM code");

    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_set_query_timeout($req, 1000);
    $timeout = cubrid_get_query_timeout($req);
    var_dump($timeout);

    cubrid_close($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(5000)
    int(1000)

### Siehe auch

- cubrid_set_query_timeout() - Set the timeout time of query execution

# cubrid_get_server_info

(PECL CUBRID >= 8.3.0)

cubrid_get_server_info — Return the CUBRID server version

### Beschreibung

function cubrid_get_server_info(resource `$conn_identifier`): string

This function returns a string that represents the CUBRID server version.

### Parameter-Liste

`conn_identifier`
  The CUBRID connection.

### Rückgabewerte

A string that represents the CUBRID server version on success,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_get_server_info() example

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

# cubrid_insert_id

(PECL CUBRID >= 8.3.0)

cubrid_insert_id — Return the ID generated for the last updated `AUTO_INCREMENT` column

### Beschreibung

function cubrid_insert_id(resource `$conn_identifier` = ?): string

The cubrid_insert_id() function retrieves the ID generated for the AUTO_INCREMENT column which is updated by the previous INSERT query. It returns 0 if the previous query does not generate new rows, or FALSE on failure.

> Hinweis: CUBRID supports AUTO_INCREMENT for more than one columns in a table. In most cases, there will be a single AUTO_INCREMENT column in a table. If there are multiple AUTO_INCREMENT columns, this function should not be used even if it will return a value.

### Parameter-Liste

`conn_identifier`
  The connection identifier previously obtained by a call to cubrid_connect().

### Rückgabewerte

A string representing the ID generated for an AUTO_INCREMENT column by the previous query, on success.

0, if the previous query does not generate new rows.

`false` on failure.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Change the return value from an array to string; Remove the first parameter class_name.

### Beispiele

Beispiel #1 cubrid_insert_id() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d int AUTO_INCREMENT(1, 2), t varchar)");

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($conn, "INSERT INTO cubrid_test(t) VALUES('cubrid_test')");
    }

    $id = cubrid_insert_id();
    var_dump($id);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(2) "19"

# cubrid_is_instance

(PECL CUBRID >= 8.3.0)

cubrid_is_instance — Check whether the instance pointed by OID exists

### Beschreibung

function cubrid_is_instance(resource `$conn_identifier`, string `$oid`): int

The cubrid_is_instance() function is used to check whether the instance pointed by the given `oid` exists or not.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to check the existence.

### Rückgabewerte

1, if such instance exists;

0, if such instance does not exist;

-1, in case of error

### Beispiele

Beispiel #1 cubrid_is_instance() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT host_year, medal, game_date
    FROM game
    WHERE athlete_code IN
        (SELECT code FROM athlete WHERE name='Thorpe Ian');
    EOD;

    $req = cubrid_execute($conn, $sql, CUBRID_INCLUDE_OID);
    $oid = cubrid_current_oid($req);

    $res = cubrid_is_instance ($conn, $oid);
    if ($res == 1) {
        echo "Instance pointed by $oid exists.\n";
    } else if ($res == 0){
        echo "Instance pointed by $oid doesn't exist.\n";
    } else {
        echo "error\n";
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Instance pointed by @0|0|0 doesn't exist.

### Siehe auch

- cubrid_drop() - Delete an instance using OID
- cubrid_get_class_name() - Get the class name using OID

# cubrid_lob_close

(PECL CUBRID >= 8.3.1)

cubrid_lob_close — Close BLOB/CLOB data

### Beschreibung

function cubrid_lob_close(array `$lob_identifier_array`): bool

cubrid_lob_close() is used to close all BLOB/CLOB returned from cubrid_lob_get().

### Parameter-Liste

`lob_identifier_array`
  LOB identifier array returned from cubrid_lob_get().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lob_close() example

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Doc size: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob_get() - Get BLOB/CLOB data
- cubrid_lob_size() - Get BLOB/CLOB data size
- cubrid_lob_export() - Export BLOB/CLOB data to file
- cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser

# cubrid_lob_export

(PECL CUBRID >= 8.3.1)

cubrid_lob_export — Export BLOB/CLOB data to file

### Beschreibung

function cubrid_lob_export(resource `$conn_identifier`, resource `$lob_identifier`, string `$path_name`): bool

cubrid_lob_export() is used to get BLOB/CLOB data from CUBRID database, and saves its contents to a file. To use this function, you must use cubrid_lob_get() first to get BLOB/CLOB info from CUBRID.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`lob_identifier`
  LOB identifier.
`path_name`
  Path name of the file.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lob_export() example

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Doc size: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob_get() - Get BLOB/CLOB data
- cubrid_lob_close() - Close BLOB/CLOB data
- cubrid_lob_size() - Get BLOB/CLOB data size
- cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser

# cubrid_lob_get

(PECL CUBRID >= 8.3.1)

cubrid_lob_get — Get BLOB/CLOB data

### Beschreibung

function cubrid_lob_get(resource `$conn_identifier`, string `$sql`): array

cubrid_lob_get() is used to get BLOB/CLOB meta info from CUBRID database, CUBRID gets BLOB/CLOB by executing the SQL statement, and returns all LOBs as a resource array. Be sure that the SQL retrieves only one column and its data type is BLOB or CLOB.

Remember to use cubrid_lob_close() to release the LOBs if you don't need it any more.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`sql`
  SQL statement to be executed.

### Rückgabewerte

Return an array of LOB resources, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_lob_get() example

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");
    echo "Doc size: ".cubrid_lob_size($lobs[0])." bytes";
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob_close() - Close BLOB/CLOB data
- cubrid_lob_size() - Get BLOB/CLOB data size
- cubrid_lob_export() - Export BLOB/CLOB data to file
- cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser

# cubrid_lob_send

(PECL CUBRID >= 8.3.1)

cubrid_lob_send — Read BLOB/CLOB data and send straight to browser

### Beschreibung

function cubrid_lob_send(resource `$conn_identifier`, resource `$lob_identifier`): bool

cubrid_lob_send() reads BLOB/CLOB data and passes it straight through to the browser. To use this function, you must use cubrid_lob_get() first to get BLOB/CLOB info from CUBRID.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`lob_identifier`
  LOB identifier.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lob_send() example

    <?php
    $conn = cubrid_connect ("localhost", 33000, "demodb", "dba");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $lobs = cubrid_lob_get($conn, "SELECT doc_content FROM doc WHERE id=5");

    cubrid_lob_send($conn, $lobs[0]);
    cubrid_lob_close($lobs);
    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob_get() - Get BLOB/CLOB data
- cubrid_lob_close() - Close BLOB/CLOB data
- cubrid_lob_size() - Get BLOB/CLOB data size
- cubrid_lob_export() - Export BLOB/CLOB data to file

# cubrid_lob_size

(PECL CUBRID >= 8.3.1)

cubrid_lob_size — Get BLOB/CLOB data size

### Beschreibung

function cubrid_lob_size(resource `$lob_identifier`): string

cubrid_lob_size() is used to get BLOB/CLOB data size.

### Parameter-Liste

`lob_identifier`
  LOB identifier.

### Rückgabewerte

A string representing LOB data size, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Change return value type from int to string.

### Beispiele

Beispiel #1 cubrid_lob_size() example

    <?php
    $lobs = cubrid_lob_get($con, "SELECT doc_content FROM doc WHERE doc_id=5");
    echo "Doc size:".cubrid_lob_size($lobs[0]);
    cubrid_lob_export($conn, $lobs[0], "doc_5.txt");
    cubrid_lob_close($lobs);
    ?>

### Siehe auch

- cubrid_lob_get() - Get BLOB/CLOB data
- cubrid_lob_close() - Close BLOB/CLOB data
- cubrid_lob_export() - Export BLOB/CLOB data to file
- cubrid_lob_send() - Read BLOB/CLOB data and send straight to browser

# cubrid_lob2_bind

(PECL CUBRID >= 8.4.1)

cubrid_lob2_bind — Bind a lob object or a string as a lob object to a prepared statement as parameters

### Beschreibung

function cubrid_lob2_bind(
resource `$req_identifier`,
int `$bind_index`,
mixed `$bind_value`,
string `$bind_value_type` = ?
): bool

The cubrid_lob2_bind() function is used to bind BLOB/CLOB datas to a corresponding question mark placeholder in the SQL statement that was passed to cubrid_prepare(). If `bind_value_type` is not given, string will be "BLOB" as the default. But if you use cubrid_lob2_new() before, `bind_value_type` will be consistent with `type` in cubrid_lob2_new() as the default.

### Parameter-Liste

`req_identifier`
  Request identifier as a result of cubrid_prepare().
`bind_index`
  Location of binding parameters. It starts with 1.
`bind_value`
  Actual value for binding.
`bind_value_type`
  It must be "BLOB" or "CLOB" and it won't be case-sensitive. If it not be given, the default value is "BLOB".

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lob2_bind() example

    <?php
    // Table: test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");

    cubrid_bind($req,1, 3);

    $lob = cubrid_lob2_new($conn, 'CLOB');
    cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_bind($req, 1, 4);

    cubrid_lob2_bind($req, 2, 'CUBRID LOB2 TEST', 'CLOB');

    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob2_new() - Create a lob object
- cubrid_lob2_close() - Close LOB object

# cubrid_lob2_close

(PECL CUBRID >= 8.4.1)

cubrid_lob2_close — Close LOB object

### Beschreibung

function cubrid_lob2_close(resource `$lob_identifier`): bool

The cubrid_lob2_close() function is used to close LOB object returned from cubrid_lob2_new() or got from the result set.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- cubrid_lob2_new() - Create a lob object

# cubrid_lob2_export

(PECL CUBRID >= 8.4.1)

cubrid_lob2_export — Export the lob object to a file

### Beschreibung

function cubrid_lob2_export(resource `$lob_identifier`, string `$file_name`): bool

The cubrid_lob2_export() function is used to save the contents of BLOB/CLOB data to a file. To use this function, you must use cubrid_lob2_new() or fetch a lob object from CUBRID database first. If the file already exists, the operation will fail. This function will not influence the cursor position of the lob object. It operates the entire lob object.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.
`filename`
  File name you want to store BLOB/CLOB data. It also supports the path of the file.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lob2_export() example

    <?php
    // Table: test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists doc");
    cubrid_execute($conn,"CREATE TABLE doc (id INT, doc_content CLOB)");
    cubrid_execute($conn,"INSERT INTO doc VALUES (5,'hello,cubrid')");

    $req = cubrid_prepare($conn, "select * from doc");

    cubrid_execute($req);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);

    $row = cubrid_fetch($req, CUBRID_NUM | CUBRID_LOB);

    cubrid_lob2_export($row[1], "doc_3.txt");

    cubrid_lob2_close($row[1]);
    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob2_new() - Create a lob object
- cubrid_lob2_close() - Close LOB object
- cubrid_lob2_import() - Importiert BLOB/CLOB-Daten aus einer Datei
- cubrid_lob2_bind() - Bind a lob object or a string as a lob object to a prepared statement as parameters

# cubrid_lob2_import

(PECL CUBRID >= 8.4.1)

cubrid_lob2_import — Importiert BLOB/CLOB-Daten aus einer Datei

### Beschreibung

function cubrid_lob2_import(resource `$lob_identifier`, string `$file_name`): bool

Die Funktion cubrid_lob2_import() wird verwendet, um den Inhalt von BLOB/CLOB-Daten aus einer Datei zu speichern. Um diese Funktion zu verwenden, muss zuerst cubrid_lob2_new() aufgerufen oder ein LOB-Objekt aus der CUBRID-Datenbank geholt werden. Wenn die Datei nicht existiert, schlägt die Operation fehl. Diese Funktion beeinflusst die Cursor-Position des LOB-Objekts nicht. Sie operiert auf dem gesamten LOB-Objekt.

### Parameter-Liste

`lob_identifier`
  LOB-Identifikator als Ergebnis von cubrid_lob2_new() oder aus dem Ergebnis-Set bezogen.
`filename`
  Name der Datei, aus der BLOB/CLOB-Daten importiert werden sollen. Der Pfad der Datei wird ebenfalls unterstützt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Beispiel für cubrid_lob2_export()

    <?php

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // oder cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);
    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob2_new() - Create a lob object
- cubrid_lob2_close() - Close LOB object
- cubrid_lob2_export() - Export the lob object to a file
- cubrid_lob2_bind() - Bind a lob object or a string as a lob object to a prepared statement as parameters

# cubrid_lob2_new

(PECL CUBRID >= 8.4.1)

cubrid_lob2_new — Create a lob object

### Beschreibung

function cubrid_lob2_new(resource `$conn_identifier` = ?, string `$type` = "BLOB"): resource

The cubrid_lob2_new() function is used to create a lob object (both BLOB and CLOB). This function should be used before you bind a lob object.

### Parameter-Liste

`conn_identifier`
  Connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() or cubrid_connect_with_url() is assumed.
`type`
  It may be "BLOB" or "CLOB", it won't be case-sensitive. The default value is "BLOB".

### Rückgabewerte

Lob identifier when it is successful,Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- cubrid_lob2_close() - Close LOB object

# cubrid_lob2_read

(PECL CUBRID >= 8.4.1)

cubrid_lob2_read — Read from BLOB/CLOB data

### Beschreibung

function cubrid_lob2_read(resource `$lob_identifier`, int `$len`): string

The cubrid_lob2_read() function reads `len` bytes from the LOB data and returns the bytes read.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.
`len`
  Length from buffer you want to read from the lob data.

### Rückgabewerte

Returns the contents as a string, `false` when there is no more data, or `null` on failure.

### Beispiele

Beispiel #1 cubrid_lob2_read() example 1

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "public", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    print "position now is " . cubrid_lob2_tell($row[1]) . "\n";

    cubrid_lob2_seek($row[1], 10, CUBRID_CURSOR_FIRST);

    print "\nposition after moving farword is " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 12);

    print "\nposition after reading is " . cubrid_lob2_tell($row[1]) . "\n";

    print $data . "\n";

    cubrid_lob2_seek($row[1], 5, CUBRID_CURSOR_CURRENT);

    print "\nposition after moving again is " . cubrid_lob2_tell($row[1]) . "\n";

    $data = cubrid_lob2_read($row[1], 20);
    print $data . "\n";

    cubrid_disconnect($conn);
    ?>

Beispiel #2 cubrid_lob2_read() example 2

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);

    while (true) {
        if ($data = cubrid_lob2_read($row[1], 1024)) {
            print $data . "\n";
        }
        elseif ($data === false) {
            print "There is no more data\n";
            break;
        }
        else {
            print "There must some errors\n";
            break;
        }
    }

    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob2_write() - Write to a lob object
- cubrid_lob2_seek() - Move the cursor of a lob object
- cubrid_lob2_seek64() - Move the cursor of a lob object
- cubrid_lob2_tell() - Tell the cursor position of the LOB object
- cubrid_lob2_tell64() - Tell the cursor position of the LOB object
- cubrid_lob2_size() - Get a lob object's size
- cubrid_lob2_size64() - Get a lob object's size

# cubrid_lob2_seek

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek — Move the cursor of a lob object

### Beschreibung

function cubrid_lob2_seek(resource `$lob_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

The cubrid_lob2_seek() function is used to move the cursor position of a lob object by the value set in the `offset` argument, to the direction set in the `origin` argument.

To set the `origin` argument, you can use `CUBRID_CURSOR_FIRST` to set the cursor position moving forward `offset` units from the first beginning. In this case, `offset` must be a positive value.

If you use `CUBRID_CURSOR_CURRENT` for `origin`, you can move forward or backward. and `offset` can be positive or negative.

If you use `CUBRID_CURSOR_LAST` for `origin`, you can move backward `offset` units from the end of LOB object and `offset` only can be positive.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.
`offset`
  Number of units you want to move the cursor.
`origin`
  This parameter can be the following values: CUBRID_CURSOR_FIRST: move forward from the first beginning. CUBRID_CURSOR_CURRENT: move forward or backward from the current position. CUBRID_CURSOR_LAST: move backward at the end of LOB object.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lob2_seek() example

    <?php
    // test_lob (id INT, contents CLOB)
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");
    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Hello world");

    cubrid_lob2_seek($lob, 0, CUBRID_CURSOR_LAST);
    cubrid_lob2_write($lob, "beautiful");

    cubrid_lob2_seek($lob, 15, CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 5);

    echo $data."\n";

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob2_read() - Read from BLOB/CLOB data
- cubrid_lob2_write() - Write to a lob object
- cubrid_lob2_seek64() - Move the cursor of a lob object
- cubrid_lob2_tell() - Tell the cursor position of the LOB object
- cubrid_lob2_tell64() - Tell the cursor position of the LOB object
- cubrid_lob2_size() - Get a lob object's size
- cubrid_lob2_size64() - Get a lob object's size

# cubrid_lob2_seek64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek64 — Move the cursor of a lob object

### Beschreibung

function cubrid_lob2_seek64(resource `$lob_identifier`, string `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

The cubrid_lob2_seek64() function is used to move the cursor position of a lob object by the value set in the `offset` argument, to the direction set in the `origin` argument. If the `offset` you want to move is larger than an integer data can be stored, you can use this function.

To set the `origin` argument, you can use `CUBRID_CURSOR_FIRST` to set the cursor position moving forward `offset` units from the first beginning. In this case, `offset` must be a positive value.

If you use `CUBRID_CURSOR_CURRENT` for `origin`, you can move forward or backward. and `offset` can be positive or negative.

If you use `CUBRID_CURSOR_LAST` for `origin`, you can move backward `offset` units from the end of LOB object and `offset` only can be positive.

> Hinweis: If you use this function to move the cursor position of the lob object, you should pass `offset` as a string.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.
`offset`
  Number of units you want to move the cursor.
`origin`
  This parameter can be the following values: CUBRID_CURSOR_FIRST: move forward from the first beginning. CUBRID_CURSOR_CURRENT: move forward or backward from the current position. CUBRID_CURSOR_LAST: move backward at the end of LOB object.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lob2_seek64() example

    <?php
    // test_lob (id INT, contents CLOB)
    // Data length of doc_1.txt should be greater than 20101029056306120215.

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES (?, ?)");
    cubrid_bind($req, 1, 1);

    $lob = cubrid_lob2_new($conn, "clob");
    cubrid_lob2_import($lob, "doc_1.txt");
    cubrid_lob2_bind($req, 2, $lob, 'CLOB'); // or cubrid_lob2_bind($req, 2, $lob);

    cubrid_execute($req);

    cubrid_lob2_close($lob);

    $req = cubrid_execute($conn, "select * from test_lob");
    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob = $row[1];

    cubrid_lob2_seek64($lob, "20101029056306120215", CUBRID_CURSOR_FIRST);
    $data = cubrid_lob2_read($lob, 20);
    echo $data."\n";
    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob2_read() - Read from BLOB/CLOB data
- cubrid_lob2_write() - Write to a lob object
- cubrid_lob2_seek() - Move the cursor of a lob object
- cubrid_lob2_tell() - Tell the cursor position of the LOB object
- cubrid_lob2_tell64() - Tell the cursor position of the LOB object
- cubrid_lob2_size() - Get a lob object's size
- cubrid_lob2_size64() - Get a lob object's size

# cubrid_lob2_size

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size — Get a lob object's size

### Beschreibung

function cubrid_lob2_size(resource `$lob_identifier`): int

The cubrid_lob2_size() function is used to get the size of a lob object.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### Rückgabewerte

It will return the size of the LOB object when it processes successfully,Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- cubrid_lob2_read() - Read from BLOB/CLOB data
- cubrid_lob2_write() - Write to a lob object
- cubrid_lob2_seek() - Move the cursor of a lob object
- cubrid_lob2_seek64() - Move the cursor of a lob object
- cubrid_lob2_tell() - Tell the cursor position of the LOB object
- cubrid_lob2_tell64() - Tell the cursor position of the LOB object
- cubrid_lob2_size64() - Get a lob object's size

# cubrid_lob2_size64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size64 — Get a lob object's size

### Beschreibung

function cubrid_lob2_size64(resource `$lob_identifier`): string

The cubrid_lob2_size64() function is used to get the size of a lob object. If the size of a lob object is larger than an integer data can be stored, you can use this function and it will return the size as a string.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### Rückgabewerte

It will return the size of the LOB object as a string when it processes successfully,Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- cubrid_lob2_read() - Read from BLOB/CLOB data
- cubrid_lob2_write() - Write to a lob object
- cubrid_lob2_seek() - Move the cursor of a lob object
- cubrid_lob2_seek64() - Move the cursor of a lob object
- cubrid_lob2_tell() - Tell the cursor position of the LOB object
- cubrid_lob2_tell64() - Tell the cursor position of the LOB object
- cubrid_lob2_size() - Get a lob object's size

# cubrid_lob2_tell

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell — Tell the cursor position of the LOB object

### Beschreibung

function cubrid_lob2_tell(resource `$lob_identifier`): int

The cubrid_lob2_tell() function is used to tell the cursor position of the LOB object.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### Rückgabewerte

It will return the cursor position on the LOB object when it processes successfully,Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- cubrid_lob2_read() - Read from BLOB/CLOB data
- cubrid_lob2_write() - Write to a lob object
- cubrid_lob2_seek() - Move the cursor of a lob object
- cubrid_lob2_seek64() - Move the cursor of a lob object
- cubrid_lob2_tell64() - Tell the cursor position of the LOB object
- cubrid_lob2_size() - Get a lob object's size
- cubrid_lob2_size64() - Get a lob object's size

# cubrid_lob2_tell64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell64 — Tell the cursor position of the LOB object

### Beschreibung

function cubrid_lob2_tell64(resource `$lob_identifier`): string

The cubrid_lob2_tell64() function is used to tell the cursor position of the LOB object. If the size of a lob object is larger than an integer data can be stored, you can use this function and it will return the position information as a string.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.

### Rückgabewerte

It will return the cursor position on the LOB object as a string when it processes successfully,Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- cubrid_lob2_read() - Read from BLOB/CLOB data
- cubrid_lob2_write() - Write to a lob object
- cubrid_lob2_seek() - Move the cursor of a lob object
- cubrid_lob2_seek64() - Move the cursor of a lob object
- cubrid_lob2_tell() - Tell the cursor position of the LOB object
- cubrid_lob2_size() - Get a lob object's size
- cubrid_lob2_size64() - Get a lob object's size

# cubrid_lob2_write

(PECL CUBRID >= 8.4.1)

cubrid_lob2_write — Write to a lob object

### Beschreibung

function cubrid_lob2_write(resource `$lob_identifier`, string `$buf`): bool

The cubrid_lob2_write() function reads as much as data from `buf` and stores it to the LOB object. Note that this function can only append characters now.

### Parameter-Liste

`lob_identifier`
  Lob identifier as a result of cubrid_lob2_new() or get from the result set.
`buf`
  Data that need to be written to the lob object.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lob2_write() example 1

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(2, ?)");

    $lob = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob, "Hello world");

    cubrid_lob2_bind($req, 1, $lob);
    cubrid_execute($req);

    cubrid_disconnect($conn);
    ?>

Beispiel #2 cubrid_lob2_write() example 2

    <?php
    // test_lob (id INT, contents CLOB)

    $conn = cubrid_connect("localhost", 33000, "demodb", "dba", "");

    cubrid_execute($conn,"DROP TABLE if exists test_lob");
    cubrid_execute($conn,"CREATE TABLE test_lob (id INT, contents CLOB)");

    $req = cubrid_prepare($conn, "INSERT INTO test_lob VALUES(1, ?)");
    $lob1 = cubrid_lob2_new($conn, 'CLOB');
    $len = cubrid_lob2_write($lob1, "cubrid php driver");
    cubrid_lob2_bind($req, 1, $lob1);
    cubrid_execute($req);

    $req = cubrid_execute($conn, "select * from test_lob");

    $row = cubrid_fetch_row($req, CUBRID_LOB);
    $lob2 = $row[1];
    cubrid_lob2_seek($lob2, 0, CUBRID_CURSOR_LAST);

    $pos = cubrid_lob2_tell($lob2);
    print "pos before write: $pos\n";

    cubrid_lob2_write($lob2, "Hello world");

    $pos = cubrid_lob2_tell($lob2);
    print "pos after write: $pos\n";

    cubrid_disconnect($conn);
    ?>

### Siehe auch

- cubrid_lob2_read() - Read from BLOB/CLOB data
- cubrid_lob2_seek() - Move the cursor of a lob object
- cubrid_lob2_seek64() - Move the cursor of a lob object
- cubrid_lob2_tell() - Tell the cursor position of the LOB object
- cubrid_lob2_tell64() - Tell the cursor position of the LOB object
- cubrid_lob2_size() - Get a lob object's size
- cubrid_lob2_size64() - Get a lob object's size

# cubrid_lock_read

(PECL CUBRID >= 8.3.0)

cubrid_lock_read — Set a read lock on the given OID

### Beschreibung

function cubrid_lock_read(resource `$conn_identifier`, string `$oid`): bool

The cubrid_lock_read() function is used to put read lock on the instance pointed by given `oid`.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to put read lock on.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lock_read() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_read($conn, $oid);

    $attr = cubrid_get($conn, $oid, "b");
    var_dump($attr);

    $attr = cubrid_get($conn, $oid);
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(9) "{1, 2, 3}"
    array(4) {
      ["a"]=>
      string(1) "1"
      ["b"]=>
      array(3) {
        [0]=>
        string(1) "1"
        [1]=>
        string(1) "2"
        [2]=>
        string(1) "3"
      }
      ["c"]=>
      array(4) {
        [0]=>
        string(2) "11"
        [1]=>
        string(2) "22"
        [2]=>
        string(2) "33"
        [3]=>
        string(3) "333"
      }
      ["d"]=>
      string(10) "a         "
    }

### Siehe auch

- cubrid_lock_write() - Set a write lock on the given OID

# cubrid_lock_write

(PECL CUBRID >= 8.3.0)

cubrid_lock_write — Set a write lock on the given OID

### Beschreibung

function cubrid_lock_write(resource `$conn_identifier`, string `$oid`): bool

The cubrid_lock_write() function is used to put write lock on the instance pointed by the given `oid`.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to put write lock on.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_lock_write() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    cubrid_lock_write($conn, $oid);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Siehe auch

- cubrid_lock_read() - Set a read lock on the given OID

# cubrid_move_cursor

(PECL CUBRID >= 8.3.0)

cubrid_move_cursor — Move the cursor in the result

### Beschreibung

function cubrid_move_cursor(resource `$req_identifier`, int `$offset`, int `$origin` = CUBRID_CURSOR_CURRENT): bool

The cubrid_move_cursor() function is used to move the current cursor location of `req_identifier` by the value set in the `offset` argument, to the direction set in the `origin` argument. To set the `origin` argument, you can use `CUBRID_CURSOR_FIRST` for the first part of the result, `CUBRID_CURSOR_CURRENT` for the current location of the result, or `CUBRID_CURSOR_LAST` for the last part of the result. If `origin` argument is not explicitly designated, then the function uses `CUBRID_CURSOR_CURRENT` as its default value.

If the value of cursor movement range goes over the valid limit, then the cursor moves to the next location after the valid range for the cursor. For example, if you move 20 units in the result with the size of 10, then the cursor will move to 11th place and return `CUBRID_NO_MORE_DATA`.

### Parameter-Liste

`req_identifier`
  Request identifier.
`offset`
  Number of units you want to move the cursor.
`origin`
  Location where you want to move the cursor from `CUBRID_CURSOR_FIRST`, `CUBRID_CURSOR_CURRENT`, `CUBRID_CURSOR_LAST`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_move_cursor() example

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_move_cursor($req, 1, CUBRID_CURSOR_LAST);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_CURRENT);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      [0]=>
      string(1) "G"
      [1]=>
      string(4) "Gold"
    }
    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement

# cubrid_next_result

(PECL CUBRID >= 8.4.0)

cubrid_next_result — Get result of next query when executing multiple SQL statements

### Beschreibung

function cubrid_next_result(resource `$result`): bool

The cubrid_next_result() function is used to get results of next query if multiple SQL statements are executed and `CUBRID_EXEC_QUERY_ALL` flag is set upon cubrid_execute().

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_next_result() example

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");

    $sql_stmt = "SELECT * FROM code; SELECT * FROM history WHERE host_year=2004 AND event_code=20281";
    $res = cubrid_execute($conn, $sql_stmt, CUBRID_EXEC_QUERY_ALL);

    get_result_info($res);
    cubrid_next_result($res);
    get_result_info($res);

    function get_result_info($req)
    {
        printf("\n------------ get_result_info --------------------\n");

        $row_num = cubrid_num_rows($req);
        $col_num = cubrid_num_cols($req);

        $column_name_list = cubrid_column_names($req);
        $column_type_list = cubrid_column_types($req);

        $column_last_name = cubrid_field_name($req, $col_num - 1);
        $column_last_table = cubrid_field_table($req, $col_num - 1);

        $column_last_type = cubrid_field_type($req, $col_num - 1);
        $column_last_len = cubrid_field_len($req, $col_num - 1);

        $column_1_flags = cubrid_field_flags($req, 1);

        printf("%-30s %d\n", "Row count:", $row_num);
        printf("%-30s %d\n", "Column count:", $col_num);
        printf("\n");

        printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Len");
        printf("------------------------------------------------------------------------------\n");

        $size = count($column_name_list);
        for($i = 0; $i < $size; $i++) {
            $column_len = cubrid_field_len($req, $i);
            printf("%-30s %-30s %-15s\n", $column_name_list[$i], $column_type_list[$i], $column_len);
        }
        printf("\n\n");

        printf("%-30s %s\n", "Last Column Name:", $column_last_name);
        printf("%-30s %s\n", "Last Column Table:", $column_last_table);
        printf("%-30s %s\n", "Last Column Type:", $column_last_type);
        printf("%-30s %d\n", "Last Column Len:", $column_last_len);
        printf("%-30s %s\n", "Second Column Flags:", $column_1_flags);

        printf("\n\n");
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ------------ get_result_info --------------------
    Row count:                     6
    Column count:                  2

    Column Names                   Column Types                   Column Len
    ------------------------------------------------------------------------------
    s_name                         char                           1
    f_name                         varchar                        6

    Last Column Name:              f_name
    Last Column Table:             code
    Last Column Type:              varchar
    Last Column Len:               6
    Second Column Flags:

    ------------ get_result_info --------------------
    Row count:                     4
    Column count:                  5

    Column Names                   Column Types                   Column Len
    ------------------------------------------------------------------------------
    event_code                     integer                        11
    athlete                        varchar                        40
    host_year                      integer                        11
    score                          varchar                        10
    unit                           varchar                        5

    Last Column Name:              unit
    Last Column Table:             history
    Last Column Type:              varchar
    Last Column Len:               5
    Second Column Flags:           not_null primary_key unique_key

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement

# cubrid_num_cols

(PECL CUBRID >= 8.3.0)

cubrid_num_cols — Return the number of columns in the result set

### Beschreibung

function cubrid_num_cols(resource `$result`): int

The cubrid_num_cols() function is used to get the number of columns from the query result. It can only be used when the query executed is a `SELECT` statement.

### Parameter-Liste

`result`
  Result.

### Rückgabewerte

Number of columns, when process is successful.

`false`, if SQL statement is not SELECT.

### Beispiele

Beispiel #1 cubrid_num_cols() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Row Num: 6
    Column Num: 2

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement
- cubrid_num_rows() - Get the number of rows in the result set

# cubrid_num_rows

(PECL CUBRID >= 8.3.0)

cubrid_num_rows — Get the number of rows in the result set

### Beschreibung

function cubrid_num_rows(resource `$result`): int

The cubrid_num_rows() function is used to get the number of rows from the query result. It can be used for `SELECT` statements. For `INSERT`, `UPDATE`, or `DELETE` queries, use the cubrid_affected_rows() function.

Note: The cubrid_num_rows() function can only be used for synchronous query; it returns 0 when it is used for asynchronous query.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute(), cubrid_query() and cubrid_prepare()

### Rückgabewerte

Number of rows, when process is successful.

0 when the query was done in async mode.

-1, if SQL statement is not SELECT.

`false` when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_num_rows() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_cols($req);

    printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Row Num: 6
    Column Num: 2

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement
- cubrid_num_cols() - Return the number of columns in the result set
- cubrid_affected_rows() - Return the number of rows affected by the last SQL statement

# cubrid_pconnect

(PECL CUBRID >= 8.3.1)

cubrid_pconnect — Öffnet eine dauerhafte Verbindung zu einem CUBRID-Server

### Beschreibung

function cubrid_pconnect(
string `$host`,
int `$port`,
string `$dbname`,
string `$userid` = ?,
string `$passwd` = ?
): resource

Stellt eine dauerhafte Verbindung zu einem CUBRID-Server her.

cubrid_pconnect() verhält sich sehr ähnlich wie cubrid_connect(), mit zwei wesentlichen Unterschieden.

Erstens versucht die Funktion beim Verbinden zunächst, eine (dauerhafte) Verbindung zu finden, die bereits mit demselben Host, Port, dbname und userid geöffnet ist. Wird eine gefunden, wird stattdessen ein Identifikator dafür zurückgegeben, anstatt eine neue Verbindung zu öffnen.

Zweitens wird die Verbindung zum SQL-Server nicht geschlossen, wenn die Ausführung des Skripts endet. Stattdessen bleibt die Verbindung für die spätere Verwendung offen (cubrid_close() oder cubrid_disconnect() schließen keine Verbindungen, die von cubrid_pconnect() hergestellt wurden).

Diese Art von Verbindung wird deshalb als „dauerhaft“ (persistent) bezeichnet.

### Parameter-Liste

`host`
  Hostname oder IP-Adresse des CUBRID-CAS-Servers.
`port`
  Portnummer des CUBRID-CAS-Servers (BROKER_PORT, konfiguriert in $CUBRID/conf/cubrid_broker.conf).
`dbname`
  Name der Datenbank.
`userid`
  Benutzername für die Datenbank.
`passwd`
  Benutzerpasswort.

### Rückgabewerte

Verbindungs-Identifikator im Erfolgsfall,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Beispiel für cubrid_pconnect()

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_pconnect("localhost", 33000, "demodb", "dba");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Siehe auch

- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
- cubrid_pconnect_with_url() - Open a persistent connection to CUBRID server
- cubrid_disconnect() - Close a database connection
- cubrid_close() - Close CUBRID connection

# cubrid_pconnect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_pconnect_with_url — Open a persistent connection to CUBRID server

### Beschreibung

function cubrid_pconnect_with_url(string `$conn_url`, string `$userid` = ?, string `$passwd` = ?): resource

Establishes a persistent connection to a CUBRID server.

cubrid_pconnect_with_url() acts very much like cubrid_connect_with_url() with two major differences.

First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, port, dbname and userid. If one is found, an identifier for it will be returned instead of opening a new connection.

Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (cubrid_close() or cubrid_disconnect() will not close links established by cubrid_pconnect_with_url()).

This type of link is therefore called 'persistent'.

<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]

<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]

<properties> ::= login_timeout=<milli_sec>

<properties> ::= query_timeout=<milli_sec>

<properties> ::= disconnect_on_query_timeout=true|false

<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]

<host> := HOSTNAME | IP_ADDR

<time> := SECOND

<milli_sec> := MILLI SECOND

- host : A host name or IP address of the master database
- db_name : A name of the database
- db_user : A name of the database user
- db_password : A database user password
- alhosts : Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts
- rctime : An interval between the attempts to connect to the active broker in which failure occurred. After a failure occurs, the system connects to the broker specified by althosts (failover), terminates the transaction, and then attempts to connect to the active broker of the master database at every rctime. The default value is 600 seconds.
- login_timeout : Timeout value (unit: msec.) for database login. The default value is 0, which means infinite postponement.
- query_timeout : Timeout value (unit: msec.) for query request. Upon timeout, a message to cancel requesting a query transferred to server is sent. The return value can depend on the disconnect_on_query_timeout configuration; even though the message to cancel a request is sent to server, that request may succeed.
- disconnect_on_query_timeout : Configures a value whether to immediately return an error of function being executed upon timeout. The default value is false.

> Hinweis: `?` and `:` that are used as identifiers in PHP connection URL can't be included in the password. The following is an example of a password that is invalid to use as connection URL because it contains "`?:`". $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100"; Passwords that contain `?` or `:` may be passed as a separate parameter. $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100"; $conn = cubrid_pconnect_with_url ($url, "dba", "12?"); If user or password is empty,you can't delete "`:`",the following is an example. $url = "CUBRID:localhost:33000:demodb:::";

### Parameter-Liste

`conn_url`
  A character string that contains server connection information.
`userid`
  User name for the database.
`passwd`
  User password.

### Rückgabewerte

Connection identifier, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_pconnect_with_url() url without properties example

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
       echo "connected successfully";
       cubrid_execute($con, "create table person(id int,name char(16))");
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_disconnect ($con);
    }
    ?>

Beispiel #2 cubrid_pconnect_with_url() url with properties example

    <?php
    $conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?althost=10.34.63.132:33088&rctime=100";
    $con = cubrid_pconnect_with_url ($conn_url);

    if ($con) {
       echo "connected successfully";
       $req =cubrid_execute($con, "insert into person values(1,'James')");

       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_disconnect ($con);
    }
    ?>

### Siehe auch

- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server
- cubrid_pconnect() - Öffnet eine dauerhafte Verbindung zu einem CUBRID-Server
- cubrid_disconnect() - Close a database connection
- cubrid_close() - Close CUBRID connection

# cubrid_prepare

(PECL CUBRID >= 8.3.0)

cubrid_prepare — Prepare a SQL statement for execution

### Beschreibung

function cubrid_prepare(resource `$conn_identifier`, string `$prepare_stmt`, int `$option` = 0): resource

The cubrid_prepare() function compiles a SQL statement for a given connection handle and returns a handle that represents the pre-compiled statement.

A prepared statement can be executed several times, which is efficient for repeated execution or for processing long data. Only a single statement can be used, and a parameter can be marked with a question mark (`?`) at the appropriate place in the SQL statement. Add a parameter when binding a value in the `VALUES` clause of an `INSERT` statement or in the `WHERE` clause. Note that a value can be bound to a parameter only by using the cubrid_bind() function.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`prepare_stmt`
  Prepare query.
`option`
  OID return option `CUBRID_INCLUDE_OID`.

### Rückgabewerte

Request identifier, if process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 cubrid_prepare() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $sql = <<<EOD
    SELECT g.event_code, e.name
    FROM game g
    JOIN event e ON g.event_code=e.code
    WHERE host_year = ? AND event_code NOT IN (SELECT event_code FROM game WHERE host_year=?) GROUP BY event_code;
    EOD;

    $req = cubrid_prepare($conn, $sql);

    cubrid_bind($req, 1, 2004);
    cubrid_bind($req, 2, 2000);
    cubrid_execute($req);

    $row_num = cubrid_num_rows($req);
    printf("There are %d event that exits in 2004 olympic but not in 2000. For example:\n\n", $row_num);

    printf("%-15s %s\n", "Event_code", "Event_name");
    printf("----------------------------\n");

    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);
    $row = cubrid_fetch_assoc($req);
    printf("%-15d %s\n", $row["event_code"], $row["name"]);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    There are 27 event that exits in 2004 olympic but not in 2000. For example:

    Event_code      Event_name
    ----------------------------
    20063           +91kg
    20070           64kg

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement
- cubrid_bind() - Bind variables to a prepared statement as parameters

# cubrid_put

(PECL CUBRID >= 8.3.0)

cubrid_put — Update a column using OID

### Beschreibung

function cubrid_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr` = ?,
mixed `$value`
): bool

The cubrid_put() function is used to update an attribute of the instance of the given `oid`.

You can update single attribute by using string data type to set `attr`. In such case, you can use integer, floating point or string type data for the `value` argument. To update multiple number of attributes, you can disregard the `attr` argument, and set `value` argument with associative array data type.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance that you want to update.
`attr`
  Name of the attribute that you want to update.
`value`
  New value that you want to assign to the attribute.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_put() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(2, {4,5,7}, {44,55,66,666}, 'b')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_put($conn, $oid, "b", array(2, 4, 8));

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(3) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "4"
      [2]=>
      string(1) "8"
    }

### Siehe auch

- cubrid_get() - Get a column using OID
- cubrid_set_add() - Insert a single element to set type column using OID
- cubrid_set_drop() - Delete an element from set type column using OID
- cubrid_seq_insert() - Fügt ein Element in eine Spalte vom Typ Sequenz anhand der OID ein
- cubrid_seq_drop() - Delete an element from sequence type column using OID
- cubrid_seq_put() - Update the element value of sequence type column using OID

# cubrid_rollback

(PECL CUBRID >= 8.3.0)

cubrid_rollback — Roll back a transaction

### Beschreibung

function cubrid_rollback(resource `$conn_identifier`): bool

The cubrid_rollback() function executes rollback on the transaction pointed by `conn_identifier`, currently in progress.

Connection to server is closed after calling cubrid_rollback(). Connection handle, however, is still valid.

### Parameter-Liste

`conn_identifier`
  Connection identifier.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_rollback() example

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb", "dba");
    cubrid_set_autocommit($conn,false);

    @cubrid_execute($conn, "DROP TABLE publishers");

    $sql = <<<EOD
    CREATE TABLE publishers(
    pub_id CHAR(3),
    pub_name VARCHAR(20),
    city VARCHAR(15),
    state CHAR(2),
    country VARCHAR(15)
    )
    EOD;

    if (!cubrid_execute($conn, $sql)) {
        printf("Error facility: %d\nError code: %d\nError msg: %s\n", cubrid_error_code_facility(), cubrid_error_code(), cubrid_error_msg());

        cubrid_disconnect($conn);
        exit;
    }

    $req = cubrid_prepare($conn, "INSERT INTO publishers VALUES(?, ?, ?, ?, ?)");

    $id_list = array("P01", "P02", "P03", "P04");
    $name_list = array("Abatis Publishers", "Core Dump Books", "Schadenfreude Press", "Tenterhooks Press");
    $city_list = array("New York", "San Francisco", "Hamburg", "Berkeley");
    $state_list = array("NY", "CA", NULL, "CA");
    $country_list = array("USA", "USA", "Germany", "USA");

    for ($i = 0, $size = count($id_list); $i < $size; $i++) {
        cubrid_bind($req, 1, $id_list[$i]);
        cubrid_bind($req, 2, $name_list[$i]);
        cubrid_bind($req, 3, $city_list[$i]);
        cubrid_bind($req, 4, $state_list[$i]);
        cubrid_bind($req, 5, $country_list[$i]);

        if (!($ret = cubrid_execute($req))) {
            break;
        }
    }

    if (!$ret) {
        cubrid_rollback($conn);
    } else {
        cubrid_commit($conn);

        $req = cubrid_execute($conn, "SELECT * FROM publishers");
        while ($result = cubrid_fetch_assoc($req)) {
            printf("%-3s %-20s %-15s %-3s %-15s\n",
                $result["pub_id"], $result["pub_name"], $result["city"], $result["state"], $result["country"]);
        }
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    P01 Abatis Publishers    New York        NY  USA
    P02 Core Dump Books      San Francisco   CA  USA
    P03 Schadenfreude Press  Hamburg             Germany
    P04 Tenterhooks Press    Berkeley        CA  USA

### Siehe auch

- cubrid_commit() - Commit a transaction
- cubrid_disconnect() - Close a database connection

# cubrid_schema

(PECL CUBRID >= 8.3.0)

cubrid_schema — Get the requested schema information

### Beschreibung

function cubrid_schema(
resource `$conn_identifier`,
int `$schema_type`,
string `$class_name` = ?,
string `$attr_name` = ?
): array

The cubrid_schema() function is used to get the requested schema information from database. To get information about specific class, set the `class_name`, to get information about specific attribute (can be used only with `CUBRID_SCH_ATTR_PRIVILEGE`), set the `attr_name`.

The result of the cubrid_schema() function is returned as a two-dimensional array (column (associative array) * row (numeric array)). The following tables shows types of schema and the column structure of the result array to be returned based on the schema type.

Result Composition of Each Type
Schema | Column Number | Column Name | Value
--- | --- | --- | ---
CUBRID_SCH_CLASS | 1 | NAME |
| 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_VCLASS | 1 | NAME |
| 2 | TYPE | 1:vclass
CUBRID_SCH_QUERY_SPEC | 1 | QUERY_SPEC |
CUBRID_SCH_ATTRIBUTE / CUBRID_SCH_CLASS_ATTRIBUTE | 1 | ATTR_NAME |
| 2 | DOMAIN |
| 3 | SCALE |
| 4 | PRECISION |
| 5 | INDEXED | 1:indexed
| 6 | NOT NULL | 1:not null
| 7 | SHARED | 1:shared
| 8 | UNIQUE | 1:unique
| 9 | DEFAULT |
| 10 | ATTR_ORDER | base:1
| 11 | CLASS_NAME |
| 12 | SOURCE_CLASS |
| 13 | IS_KEY | 1:key
CUBRID_SCH_METHOD / CUBRID_SCH_CLASS_METHOD | 1 | NAME |
| 2 | RET_DOMAIN |
| 3 | ARG_DOMAIN |
CUBRID_SCH_METHOD_FILE | 1 | METHOD_FILE |
CUBRID_SCH_SUPERCLASS / CUBRID_SCH_DIRECT_SUPER_CLASS / CUBRID_SCH_SUBCLASS | 1 | CLASS_NAME |
| 2 | TYPE | 0:system class 1:vclass 2:class
CUBRID_SCH_CONSTRAINT | 1 | TYPE | 0:unique 1:index 2:reverse unique 3:reverse index
| 2 | NAME |
| 3 | ATTR_NAME |
| 4 | NUM_PAGES |
| 5 | NUM_KEYS |
| 6 | PRIMARY_KEY | 1:primary key
| 7 | KEY_ORDER | base:1
CUBRID_SCH_TRIGGER | 1 | NAME |
| 2 | STATUS |
| 3 | EVENT |
| 4 | TARGET_CLASS |
| 5 | TARGET_ATTR |
| 6 | ACTION_TIME |
| 7 | ACTION |
| 8 | PRIORITY |
| 9 | CONDITION_TIME |
| 10 | CONDITION |
CUBRID_SCH_CLASS_PRIVILEGE / CUBRID_SCH_ATTR_PRIVILEGE | 1 | CLASS_NAME / ATTR_NAME |
| 2 | PRIVILEGE |
| 3 | GRANTABLE |
CUBRID_SCH_PRIMARY_KEY | 1 | CLASS_NAME |
| 2 | ATTR_NAME |
| 3 | KEY_SEQ | base:1
| 4 | KEY_NAME |
CUBRID_SCH_IMPORTED_KEYS / CUBRID_SCH_EXPORTED_KEYS / CUBRID_SCH_CROSS_REFERENCE | 1 | PKTABLE_NAME |
| 2 | PKCOLUMN_NAME |
| 3 | FKTABLE_NAME | base:1
| 4 | FKCOLUMN_NAME |
| 5 | KEY_SEQ | base:1
| 6 | UPDATE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 7 | DELETE_ACTION | 0:cascade 1:restrict 2:no action 3:set null
| 8 | FK_NAME |
| 9 | PK_NAME |

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`schema_type`
  Schema data that you want to know.
`class_name`
  Class you want to know the schema of.
`attr_name`
  Attribute you want to know the schema of.

### Rückgabewerte

Array containing the schema information, when process is successful,Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.3.1 | Change return value: when process is unsuccessful, return false, not -1.

### Beispiele

Beispiel #1 cubrid_schema() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    printf("\n--- Primary Key ---\n");
    $pk = cubrid_schema($conn, CUBRID_SCH_PRIMARY_KEY, "game");
    var_dump($pk);

    printf("\n--- Foreign Keys ---\n");
    $fk = cubrid_schema($conn, CUBRID_SCH_IMPORTED_KEYS, "game");
    var_dump($fk);

    printf("\n--- Column Attribute ---\n");
    $attr = cubrid_schema($conn, CUBRID_SCH_ATTRIBUTE, "stadium", "area");
    var_dump($attr);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    --- Primary Key ---
    array(3) {
      [0]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "3"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [1]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "2"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
      [2]=>
      array(4) {
        ["CLASS_NAME"]=>
        string(4) "game"
        ["ATTR_NAME"]=>
        string(9) "host_year"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["KEY_NAME"]=>
        string(41) "pk_game_host_year_event_code_athlete_code"
      }
    }

    --- Foreign Keys ---
    array(2) {
      [0]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(7) "athlete"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(12) "athlete_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(20) "fk_game_athlete_code"
        ["PK_NAME"]=>
        string(15) "pk_athlete_code"
      }
      [1]=>
      array(9) {
        ["PKTABLE_NAME"]=>
        string(5) "event"
        ["PKCOLUMN_NAME"]=>
        string(4) "code"
        ["FKTABLE_NAME"]=>
        string(4) "game"
        ["FKCOLUMN_NAME"]=>
        string(10) "event_code"
        ["KEY_SEQ"]=>
        string(1) "1"
        ["UPDATE_RULE"]=>
        string(1) "1"
        ["DELETE_RULE"]=>
        string(1) "1"
        ["FK_NAME"]=>
        string(18) "fk_game_event_code"
        ["PK_NAME"]=>
        string(13) "pk_event_code"
      }
    }

    --- Column Attribute ---
    array(1) {
      [0]=>
      array(13) {
        ["ATTR_NAME"]=>
        string(4) "area"
        ["DOMAIN"]=>
        string(1) "7"
        ["SCALE"]=>
        string(1) "2"
        ["PRECISION"]=>
        string(2) "10"
        ["INDEXED"]=>
        string(1) "0"
        ["NON_NULL"]=>
        string(1) "0"
        ["SHARED"]=>
        string(1) "0"
        ["UNIQUE"]=>
        string(1) "0"
        ["DEFAULT"]=>
        NULL
        ["ATTR_ORDER"]=>
        string(1) "4"
        ["CLASS_NAME"]=>
        string(7) "stadium"
        ["SOURCE_CLASS"]=>
        string(7) "stadium"
        ["IS_KEY"]=>
        string(1) "0"
      }
    }

# cubrid_seq_drop

(PECL CUBRID >= 8.3.0)

cubrid_seq_drop — Delete an element from sequence type column using OID

### Beschreibung

function cubrid_seq_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`
): bool

The cubrid_seq_drop() function is used to delete an element you request from the given sequence type attribute in the database.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance you want to work with.
`attr_name`
  Name of the attribute that you want to delete an element from.
`index`
  Index of the element that you want to delete (1-based).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_seq_drop() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_drop($conn, $oid, "c", 4);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(3) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
    }

### Siehe auch

- cubrid_seq_insert() - Fügt ein Element in eine Spalte vom Typ Sequenz anhand der OID ein
- cubrid_seq_put() - Update the element value of sequence type column using OID

# cubrid_seq_insert

(PECL CUBRID >= 8.3.0)

cubrid_seq_insert — Fügt ein Element in eine Spalte vom Typ Sequenz anhand der OID ein

### Beschreibung

function cubrid_seq_insert(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

Die Funktion cubrid_seq_insert() wird verwendet, um an einer gewünschten Position ein Element in ein Attribut vom Typ Sequenz einzufügen.

### Parameter-Liste

`conn_identifier`
  Verbindungs-Identifikator.
`oid`
  OID der Instanz, mit der gearbeitet werden soll.
`attr_name`
  Name des Attributs, in das eine Instanz eingefügt werden soll.
`index`
  Position des Elements, an der das Element eingefügt werden soll (1-basiert).
`seq_element`
  Inhalt des Elements, das eingefügt werden soll.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Beispiel für cubrid_seq_insert()

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_insert($conn, $oid, "c", 5, "44");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(5) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
      [4]=>
      string(2) "44"
    }

### Siehe auch

- cubrid_seq_drop() - Delete an element from sequence type column using OID
- cubrid_seq_put() - Update the element value of sequence type column using OID

# cubrid_seq_put

(PECL CUBRID >= 8.3.0)

cubrid_seq_put — Update the element value of sequence type column using OID

### Beschreibung

function cubrid_seq_put(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

The cubrid_seq_put() function is used to update the content of the requested element in a sequent type attribute using OID.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance you want to work with.
`attr_name`
  Name of the attribute that you want to update an element.
`index`
  Index (1-based) of the element that you want to update.
`seq_element`
  New content that you want to use for the update.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_seq_put() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c sequence(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_seq_put($conn, $oid, "c", 1, "111");

    $attr = cubrid_col_get($conn, $oid, "c");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      [0]=>
      string(2) "11"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }
    array(4) {
      [0]=>
      string(3) "111"
      [1]=>
      string(2) "22"
      [2]=>
      string(2) "33"
      [3]=>
      string(3) "333"
    }

### Siehe auch

- cubrid_seq_drop() - Delete an element from sequence type column using OID
- cubrid_seq_insert() - Fügt ein Element in eine Spalte vom Typ Sequenz anhand der OID ein

# cubrid_set_add

(PECL CUBRID >= 8.3.0)

cubrid_set_add — Insert a single element to set type column using OID

### Beschreibung

function cubrid_set_add(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

The cubrid_set_add() function is used to insert a single element to a set type attribute (set, multiset, sequence) you requested.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance you want to work with.
`attr_name`
  Name of the attribute you want to insert an element.
`set_element`
  Content of the element you want to insert.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_set_add() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_add($conn, $oid, "b", "4");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(4) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
      [3]=>
      string(1) "4"
    }

### Siehe auch

- cubrid_seq_drop() - Delete an element from sequence type column using OID

# cubrid_set_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_set_autocommit — Set autocommit mode of the connection

### Beschreibung

function cubrid_set_autocommit(resource `$conn_identifier`, bool `$mode`): bool

The cubrid_set_autocommit() function is used to set the CUBRID database auto-commit mode of the current database connection.

In CUBRID PHP, auto-commit mode is disabled by default for transaction management. When auto-commit mode is turned from off to on, any pending work is automatically committed.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`mode`
  Auto-commit mode. The following constants can be used:
  - `CUBRID_AUTOCOMMIT_FALSE`
  - `CUBRID_AUTOCOMMIT_TRUE`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- cubrid_get_autocommit() - Get auto-commit mode of the connection
- cubrid_commit() - Commit a transaction

# cubrid_set_db_parameter

(PECL CUBRID >= 8.4.0)

cubrid_set_db_parameter — Sets the CUBRID database parameters

### Beschreibung

function cubrid_set_db_parameter(resource `$conn_identifier`, int `$param_type`, int `$param_value`): bool

The cubrid_set_db_parameter() function is used to set the CUBRID database parameters. It can set the following CUBRID database parameters:

- `PARAM_ISOLATION_LEVEL`
- `PARAM_LOCK_TIMEOUT`

> Hinweis: The auto-commit mode can be set by using cubrid_set_autocommit().

### Parameter-Liste

`conn_identifier`
  The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.
`param_type`
  Database parameter type.
`param_value`
  Isolation level value (1-6) or lock timeout (in seconds) value.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_get_db_parameter() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    $params = cubrid_get_db_parameter($conn);
    var_dump($params);

    cubrid_set_autocommit($conn, CUBRID_AUTOCOMMIT_TRUE);
    cubrid_set_db_parameter($conn, CUBRID_PARAM_ISOLATION_LEVEL, 2);

    $params_new = cubrid_get_db_parameter($conn);
    var_dump($params_new);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(3)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(0)
    }
    array(4) {
      ["PARAM_ISOLATION_LEVEL"]=>
      int(2)
      ["PARAM_LOCK_TIMEOUT"]=>
      int(-1)
      ["PARAM_MAX_STRING_LENGTH"]=>
      int(1073741823)
      ["PARAM_AUTO_COMMIT"]=>
      int(1)
    }

### Siehe auch

- cubrid_get_db_parameter() - Returns the CUBRID database parameters
- cubrid_set_autocommit() - Set autocommit mode of the connection

# cubrid_set_drop

(PECL CUBRID >= 8.3.0)

cubrid_set_drop — Delete an element from set type column using OID

### Beschreibung

function cubrid_set_drop(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
string `$set_element`
): bool

The cubrid_set_drop() function is used to delete an element that you request from the given set type (set, multiset) attribute of the database.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  OID of the instance you want to work with.
`attr_name`
  Name of the attribute you want to delete an element from.
`set_element`
  Content of the element you want to delete.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 cubrid_set_drop() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb", "dba");

    @cubrid_execute($conn, "DROP TABLE foo");
    cubrid_execute($conn, "CREATE TABLE foo(a int AUTO_INCREMENT, b set(int), c list(int), d char(10))");
    cubrid_execute($conn, "INSERT INTO foo(a, b, c, d) VALUES(1, {1,2,3}, {11,22,33,333}, 'a')");

    $req = cubrid_execute($conn, "SELECT * FROM foo", CUBRID_INCLUDE_OID);

    cubrid_move_cursor($req, 1, CUBRID_CURSOR_FIRST);
    $oid = cubrid_current_oid($req);

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_set_drop($conn, $oid, "b", "1");

    $attr = cubrid_col_get($conn, $oid, "b");
    var_dump($attr);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      string(1) "1"
      [1]=>
      string(1) "2"
      [2]=>
      string(1) "3"
    }
    array(2) {
      [0]=>
      string(1) "2"
      [1]=>
      string(1) "3"
    }

### Siehe auch

- cubrid_set_add() - Insert a single element to set type column using OID

# cubrid_set_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_set_query_timeout — Set the timeout time of query execution

### Beschreibung

function cubrid_set_query_timeout(resource `$req_identifier`, int `$timeout`): bool

The cubrid_set_query_timeout() function is used to set the timeout time of query execution.

### Parameter-Liste

`req_identifier`
  Request identifier.
`timeout`
  Timeout time in milliseconds.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- cubrid_get_query_timeout() - Get the query timeout value of the request

# cubrid_version

(PECL CUBRID >= 8.3.0)

cubrid_version — Get the CUBRID PHP module's version

### Beschreibung

function cubrid_version(): string

The cubrid_version() function is used to get the CUBRID PHP module's version.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Version information (eg. "8.3.1.0001").

### Beispiele

Beispiel #1 cubrid_version() example

    <?php
    printf("%-30s %s\n", "CUBRID PHP Version:", cubrid_version());

    printf("\n");

    $conn = cubrid_connect("localhost", 33088, "demodb", "dba");

    if (!$conn) {
        die('Connect Error ('. cubrid_error_code() .')' . cubrid_error_msg());
    }

    $db_params = cubrid_get_db_parameter($conn);

    while (list($param_name, $param_value) = each($db_params)) {
        printf("%-30s %s\n", $param_name, $param_value);
    }

    printf("\n");

    $server_info = cubrid_get_server_info($conn);
    $client_info = cubrid_get_client_info();

    printf("%-30s %s\n", "Server Info:", $server_info);
    printf("%-30s %s\n", "Client Info:", $client_info);

    printf("\n");

    $charset = cubrid_get_charset($conn);

    printf("%-30s %s\n", "CUBRID Charset:", $charset);

    cubrid_disconnect($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CUBRID PHP Version:            9.1.0.0001

    PARAM_ISOLATION_LEVEL          3
    LOCK_TIMEOUT                   -1
    MAX_STRING_LENGTH              1073741823
    PARAM_AUTO_COMMIT              1

    Server Info:                   9.1.0.0212
    Client Info:                   9.1.0

    CUBRID Charset:                iso8859-1

### Siehe auch

- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_code_facility() - Get the facility code of error

## Inhaltsverzeichnis

- cubrid_bind — Bind variables to a prepared statement as parameters
- cubrid_close_prepare — Close the request handle
- cubrid_close_request — Close the request handle
- cubrid_col_get — Get contents of collection type column using OID
- cubrid_col_size — Get the number of elements in collection type column using OID
- cubrid_column_names — Get the column names in result
- cubrid_column_types — Get column types in result
- cubrid_commit — Commit a transaction
- cubrid_connect — Open a connection to a CUBRID Server
- cubrid_connect_with_url — Establish the environment for connecting to CUBRID server
- cubrid_current_oid — Get OID of the current cursor location
- cubrid_disconnect — Close a database connection
- cubrid_drop — Delete an instance using OID
- cubrid_error_code — Get error code for the most recent function call
- cubrid_error_code_facility — Get the facility code of error
- cubrid_error_msg — Get last error message for the most recent function call
- cubrid_execute — Execute a prepared SQL statement
- cubrid_fetch — Fetch the next row from a result set
- cubrid_free_result — Free the memory occupied by the result data
- cubrid_get — Get a column using OID
- cubrid_get_autocommit — Get auto-commit mode of the connection
- cubrid_get_charset — Return the current CUBRID connection charset
- cubrid_get_class_name — Get the class name using OID
- cubrid_get_client_info — Return the client library version
- cubrid_get_db_parameter — Returns the CUBRID database parameters
- cubrid_get_query_timeout — Get the query timeout value of the request
- cubrid_get_server_info — Return the CUBRID server version
- cubrid_insert_id — Return the ID generated for the last updated AUTO_INCREMENT column
- cubrid_is_instance — Check whether the instance pointed by OID exists
- cubrid_lob_close — Close BLOB/CLOB data
- cubrid_lob_export — Export BLOB/CLOB data to file
- cubrid_lob_get — Get BLOB/CLOB data
- cubrid_lob_send — Read BLOB/CLOB data and send straight to browser
- cubrid_lob_size — Get BLOB/CLOB data size
- cubrid_lob2_bind — Bind a lob object or a string as a lob object to a prepared statement as parameters
- cubrid_lob2_close — Close LOB object
- cubrid_lob2_export — Export the lob object to a file
- cubrid_lob2_import — Importiert BLOB/CLOB-Daten aus einer Datei
- cubrid_lob2_new — Create a lob object
- cubrid_lob2_read — Read from BLOB/CLOB data
- cubrid_lob2_seek — Move the cursor of a lob object
- cubrid_lob2_seek64 — Move the cursor of a lob object
- cubrid_lob2_size — Get a lob object's size
- cubrid_lob2_size64 — Get a lob object's size
- cubrid_lob2_tell — Tell the cursor position of the LOB object
- cubrid_lob2_tell64 — Tell the cursor position of the LOB object
- cubrid_lob2_write — Write to a lob object
- cubrid_lock_read — Set a read lock on the given OID
- cubrid_lock_write — Set a write lock on the given OID
- cubrid_move_cursor — Move the cursor in the result
- cubrid_next_result — Get result of next query when executing multiple SQL statements
- cubrid_num_cols — Return the number of columns in the result set
- cubrid_num_rows — Get the number of rows in the result set
- cubrid_pconnect — Öffnet eine dauerhafte Verbindung zu einem CUBRID-Server
- cubrid_pconnect_with_url — Open a persistent connection to CUBRID server
- cubrid_prepare — Prepare a SQL statement for execution
- cubrid_put — Update a column using OID
- cubrid_rollback — Roll back a transaction
- cubrid_schema — Get the requested schema information
- cubrid_seq_drop — Delete an element from sequence type column using OID
- cubrid_seq_insert — Fügt ein Element in eine Spalte vom Typ Sequenz anhand der OID ein
- cubrid_seq_put — Update the element value of sequence type column using OID
- cubrid_set_add — Insert a single element to set type column using OID
- cubrid_set_autocommit — Set autocommit mode of the connection
- cubrid_set_db_parameter — Sets the CUBRID database parameters
- cubrid_set_drop — Delete an element from set type column using OID
- cubrid_set_query_timeout — Set the timeout time of query execution
- cubrid_version — Get the CUBRID PHP module's version

# CUBRID MySQL Compatibility Functions

# cubrid_affected_rows

(PECL CUBRID >= 8.3.0)

cubrid_affected_rows — Return the number of rows affected by the last SQL statement

### Beschreibung

function cubrid_affected_rows(resource `$conn_identifier` = ?): int
function cubrid_affected_rows(resource `$req_identifier` = ?): int

The cubrid_affected_rows() function is used to get the number of rows affected by the SQL statement (INSERT, DELETE, UPDATE).

### Parameter-Liste

`conn_identifier`
  The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.
`req_identifier`
  Request Identifier, could be returned from either cubrid_prepare() or cubrid_execute(). If the request identifier is not specified, the last identifier requested by cubrid_prepare() or cubrid_execute() is assumed.

### Rückgabewerte

Number of rows affected by the SQL statement, when process is successful.

-1, when SQL statement is not INSERT, DELETE or UPDATE.

`false`, when the request identifier is not specified, and there is no last request.

### Beispiele

Beispiel #1 cubrid_affected_rows() example

    <?php
    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    cubrid_execute($conn, "DROP TABLE IF EXISTS cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (d varchar)");
    $sql_stmt = "INSERT INTO cubrid_test(d) VALUES('php-test')";
    $req = cubrid_prepare($conn, $sql_stmt);

    for ($i = 0; $i < 10; $i++) {
        cubrid_execute($req);
    }
    cubrid_commit($conn);

    $req = cubrid_execute($conn, "DELETE FROM cubrid_test WHERE d='php-test'", CUBRID_ASYNC);
    var_dump(cubrid_affected_rows());
    var_dump(cubrid_affected_rows($conn));
    var_dump(cubrid_affected_rows($req));

    cubrid_disconnect($conn);

    print "done!";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(10)
    int(10)
    int(10)
    done!

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement

# cubrid_client_encoding

(PECL CUBRID >= 8.3.1)

cubrid_client_encoding — Return the current CUBRID connection charset

### Beschreibung

function cubrid_client_encoding(resource `$conn_identifier` = ?): string

This function returns the current CUBRID connection charset and is similar to the CUBRID function cubrid_get_charset().

### Parameter-Liste

`conn_identifier`
  The CUBRID connection. If the connection identifier is not specified, the last link opened by cubrid_connect() is assumed.

### Rückgabewerte

A string that represents the CUBRID connection charset; on success.

`false` on failure.

### Beispiele

Beispiel #1 cubrid_client_encoding() example

    <?php

    $con = cubrid_connect("localhost", 33000, "demodb");
    if (!$con)
    {
        die('Could not connect.');
    }

    printf("CUBRID current charset: %s\n", cubrid_client_encoding($con));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CUBRID current charset: iso8859-1

### Siehe auch

- cubrid_get_charset() - Return the current CUBRID connection charset

# cubrid_close

(PECL CUBRID >= 8.3.1)

cubrid_close — Close CUBRID connection

### Beschreibung

function cubrid_close(resource `$conn_identifier` = ?): bool

The cubrid_close() function ends the transaction currently in process, closes the connection handle and disconnects from server. If there is any request handles not closed yet at this point, they will be closed. It is similar to the CUBRID function cubrid_disconnect().

### Parameter-Liste

`conn_identifier`
  The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

### Rückgabewerte

`true`, when process is successful.

`false`, when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_close() example

    <?php
    $con = cubrid_connect ("localhost", 33000, "demodb");
    if ($con) {
       echo "connected successfully";
       $req = cubrid_execute ( $con, "insert into person values(1,'James')");
       if ($req) {
          cubrid_close_request ($req);
          cubrid_commit ($con);
       } else {
          cubrid_rollback ($con);
       }
       cubrid_close ($con);
    }
    ?>

### Siehe auch

- cubrid_disconnect() - Close a database connection
- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_connect_with_url() - Establish the environment for connecting to CUBRID server

# cubrid_data_seek

(PECL CUBRID >= 8.3.0)

cubrid_data_seek — Move the internal row pointer of the CUBRID result

### Beschreibung

function cubrid_data_seek(resource `$result`, int `$row_number`): bool

This function performs the moving of the internal row pointer of the CUBRID result (associated with the specified result identifier) to point to a specific row number. There are functions, such as cubrid_fetch_assoc(), which use the currently stored value of row number.

### Parameter-Liste

`result`
  The result.
`row_number`
  This is the desired row number of the new result pointer.

### Rückgabewerte

Returns `true` on success or `false` on failure.

### Beispiele

Beispiel #1 cubrid_data_seek() example

    <?php
    $conn = cubrid_connect("127.0.0.1", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");
    cubrid_data_seek($req, 0);

    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 2);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_data_seek($req, 4);
    $result = cubrid_fetch_row($req);
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      [0]=>
      string(1) "X"
      [1]=>
      string(5) "Mixed"
    }
    array(2) {
      [0]=>
      string(1) "M"
      [1]=>
      string(3) "Man"
    }
    array(2) {
      [0]=>
      string(1) "S"
      [1]=>
      string(6) "Silver"
    }

# cubrid_db_name

(PECL CUBRID >= 8.3.1)

cubrid_db_name — Get db name from results of cubrid_list_dbs

### Beschreibung

function cubrid_db_name(array `$result`, int `$index`): string

Retrieve the database name from a call to cubrid_list_dbs().

### Parameter-Liste

`result`
  The result pointer from a call to cubrid_list_dbs().
`index`
  The index into the result set.

### Rückgabewerte

Returns the database name on success, and `false` on failure. If `false` is returned, use cubrid_error() to determine the nature of the error.

### Beispiele

Beispiel #1 cubrid_db_name() example

    <?php
    error_reporting(E_ALL);

    $conn = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $db_list = cubrid_list_dbs($conn);

    $i = 0;
    $cnt = count($db_list);
    while ($i < $cnt) {
        echo cubrid_db_name($db_list, $i) . "\n";
        $i++;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    demodb

### Siehe auch

- cubrid_list_dbs() - Return an array with the list of all existing CUBRID databases

# cubrid_errno

(PECL CUBRID >= 8.3.1)

cubrid_errno — Return the numerical value of the error message from previous CUBRID operation

### Beschreibung

function cubrid_errno(resource `$conn_identifier` = ?): int

Returns the error number from the last CUBRID function.

The cubrid_errno() function is used to get the error code of the error that occurred during the API execution. Usually, it gets the error code when API returns false as its return value.

### Parameter-Liste

`conn_identifier`
  The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

### Rückgabewerte

Returns the error number from the last CUBRID function, or `0` (zero) if no error occurred.

### Beispiele

Beispiel #1 cubrid_errno() example

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Error Code: ", cubrid_errno($con);
        echo "Error Message: ", cubrid_error($con);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Error Code: -493 Error Message: Syntax: Unknown class "person". select id, [name] from person

### Siehe auch

- cubrid_error() - Get the error message
- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_msg() - Get last error message for the most recent function call

# cubrid_error

(PECL CUBRID >= 8.3.1)

cubrid_error — Get the error message

### Beschreibung

function cubrid_error(resource `$connection` = ?): string

The cubrid_error() function is used to get the error message that occurred during the use of CUBRID API. Usually, it gets error message when API returns false as its return value.

### Parameter-Liste

`connection`
  The CUBRID connection.

### Rückgabewerte

Error message that occurred.

### Beispiele

Beispiel #1 cubrid_error() example

    <?php
    $con = cubrid_connect('localhost', 33000, 'demodb', 'dba', '');
    $req = cubrid_execute($con, "select id, name from person");
    if ($req) {
        while (list ($id, $name) = cubrid_fetch($req))
        echo $id, $name;
    } else {
        echo "Error Code: ", cubrid_errno($con);
        echo "Error Message: ", cubrid_error($con);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Error Code: -493 Error Message: Syntax: Unknown class "person". select id, [name] from person

### Siehe auch

- cubrid_errno() - Return the numerical value of the error message from previous CUBRID operation
- cubrid_error_code() - Get error code for the most recent function call
- cubrid_error_msg() - Get last error message for the most recent function call

# cubrid_fetch_array

(PECL CUBRID >=8.3.0)

cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both

### Beschreibung

function cubrid_fetch_array(resource `$result`, int `$type` = CUBRID_BOTH): array

The cubrid_fetch_array() function is used to get a single row from the query result and returns an array. The cursor automatically moves to the next row after getting the result.

### Parameter-Liste

`result`
  `Result` comes from a call to cubrid_execute()
`type`
  Array type of the fetched result CUBRID_NUM, CUBRID_ASSOC, CUBRID_BOTH. If you need to operate the lob object, you can use CUBRID_LOB.

### Rückgabewerte

Returns an array of strings that corresponds to the fetched row, when process is successful.

`false`, when there are no more rows; NULL, when process is unsuccessful.

The type of returned array depends on how type is defined. By using CUBRID_BOTH (default), you'll get an array with both associative and number indices, and you can decide which data type to use by setting the `type` argument. The `type` variable can be set to one of the following values:

- CUBRID_NUM : Numerical array (0-based)
- CUBRID_ASSOC : Associative array
- CUBRID_BOTH : Numerical & Associative array (default)

### Beispiele

Beispiel #1 cubrid_fetch_array() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_array($req, CUBRID_NUM)) {
        printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // if you want to operate LOB object, you can use cubrid_fetch_array($req, CUBRID_NUM | CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement
- cubrid_fetch() - Fetch the next row from a result set
- cubrid_fetch_row() - Return a numerical array with the values of the current row
- cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
- cubrid_fetch_object() - Fetch the next row and return it as an object

# cubrid_fetch_assoc

(PECL CUBRID >= 8.3.0)

cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row

### Beschreibung

function cubrid_fetch_assoc(resource `$result`, int `$type` = ?): array

This function returns the associative array, that corresponds to the fetched row, and then moves the internal data pointer ahead, or returns FALSE when the end is reached.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`type`
  Type can only be CUBRID_LOB, this parameter will be used only when you need to operate the lob object.

### Rückgabewerte

Associative array, when process is successful.

`false`, when there are no more rows; NULL, when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_fetch_assoc() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_assoc($req)) {
        printf("%-40s %-10s %-6s %-20s\n",
            $row["name"], $row["area"], $row["seats"], $row["address"]);
    }

    // if you want to operate LOB object, you can use cubrid_fetch_assoc($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement
- cubrid_fetch() - Fetch the next row from a result set
- cubrid_fetch_row() - Return a numerical array with the values of the current row
- cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- cubrid_fetch_object() - Fetch the next row and return it as an object

# cubrid_fetch_field

(PECL CUBRID >= 8.3.1)

cubrid_fetch_field — Get column information from a result and return as an object

### Beschreibung

function cubrid_fetch_field(resource `$result`, int `$field_offset` = 0): object

This function returns an object with certain properties of the specific column. The properties of the object are:

`name`
  column name
`table`
  name of the table that the column belongs to
`def`
  default value of the column
`max_length`
  maximum length of the column
`not_null`
  1 if the column cannot be NULL
`primary_key`
  1 if the column is a primary key
`unique_key`
  1 if the column is a unique key
`multiple_key`
  1 if the column is a non-unique key
`numeric`
  1 if the column is numeric
`blob`
  1 if the column is a BLOB
`type`
  the type of the column
`unsigned`
  1 if the column is unsigned
`zerofill`
  1 if the column is zero-filled

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`field_offset`
  The numerical field offset. If the field offset is not specified, the next field (that was not yet retrieved by this function) is retrieved. The `field_offset` starts at 0.

### Rückgabewerte

Object with certain properties of the specific column, when process is successful.

`false` on failure.

### Beispiele

Beispiel #1 cubrid_fetch_field() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Field Properties ---\n");
    printf("%-30s %s\n", "name:", $field->name);
    printf("%-30s %s\n", "table:", $field->table);
    printf("%-30s \"%s\"\n", "default value:", $field->def);
    printf("%-30s %d\n", "max length:", $field->max_length);
    printf("%-30s %d\n", "not null:", $field->not_null);
    printf("%-30s %d\n", "primary key:", $field->primary_key);
    printf("%-30s %d\n", "unique key:", $field->unique_key);
    printf("%-30s %d\n", "multiple key:", $field->multiple_key);
    printf("%-30s %d\n", "numeric:", $field->numeric);
    printf("%-30s %d\n", "blob:", $field->blob);
    printf("%-30s %s\n", "type:", $field->type);
    printf("%-30s %d\n", "unsigned:", $field->unsigned);
    printf("%-30s %d\n", "zerofill:", $field->zerofill);

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16681"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-9-30"
    }

    --- Field Properties ---
    name:                          athlete_code
    table:                         game
    default value:                 ""
    max length:                    0
    not null:                      1
    primary key:                   1
    unique key:                    1
    multiple key:                  0
    numeric:                       1
    blob:                          0
    type:                          integer
    unsigned:                      0
    zerofill:                      0

# cubrid_fetch_lengths

(PECL CUBRID >= 8.3.0)

cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row

### Beschreibung

function cubrid_fetch_lengths(resource `$result`): array

This function returns a numeric array with the lengths of the values of each field from the current row of the result set or it returns FALSE on failure.

> Hinweis: If field data type is BLOB/CLOB, you should get its length by using cubrid_lob_size().

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()

### Rückgabewerte

A numeric array, when process is successful.

`false` on failure.

### Beispiele

Beispiel #1 cubrid_fetch_lengths() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $row = cubrid_fetch_row($result);
    print_r($row);

    $lens = cubrid_fetch_lengths($result);
    print_r($lens);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => 2004
        [1] => 20085
        [2] => 15118
        [3] => 30134
        [4] => AUS
        [5] => G
        [6] => 2004-8-20
    )
    Array
    (
        [0] => 4
        [1] => 5
        [2] => 5
        [3] => 5
        [4] => 3
        [5] => 1
        [6] => 10
    )

# cubrid_fetch_object

(PECL CUBRID >= 8.3.0)

cubrid_fetch_object — Fetch the next row and return it as an object

### Beschreibung

function cubrid_fetch_object(
resource `$result`,
string `$class_name` = ?,
array `$params` = ?,
int `$type` = ?
): object

This function returns an object with the column names of the result set as properties. The values of these properties are extracted from the current row of the result.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`class_name`
  The name of the class to instantiate. If not specified, a stdClass (stdClass is PHP's generic empty class that's used when casting other types to objects) object is returned.
`params`
  An optional array of parameters to pass to the constructor for `class_name` objects.
`type`
  Type can only be CUBRID_LOB, this parameter will be used only when you need to operate the lob object.

### Rückgabewerte

An object, when process is successful.

`false`, when there are no more rows; NULL, when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_fetch_object() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $res = cubrid_execute($conn, "SELECT * FROM code");

    var_dump(cubrid_fetch_object($res));

    // if you want to operate LOB object, you can use cubrid_fetch_object($res, CUBRID_LOB)

    class demodb_code {
        public $s_name = null;
        public $f_name = null;

        public function toString() {
            var_dump($this);
        }
    }

    var_dump(cubrid_fetch_object($res, "demodb_code"));

    // if you want to operate LOB object, you can use cubrid_fetch_object($res, "demodb_code", CUBRID_LOB)

    class demodb_code_construct extends demodb_code {
        public function __construct($s, $f) {
            $this->s_name = $s;
            $this->f_name = $f;
        }
    }

    var_dump(cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name')));

    // if you want to operate LOB object, you can use cubrid_fetch_object($res, 'demodb_code_construct', array('s_name', 'f_name'), CUBRID_LOB)

    var_dump(cubrid_fetch_object($res));

    cubrid_close_request($res);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "X"
      ["f_name"]=>
      string(5) "Mixed"
    }
    object(demodb_code)#1 (2) {
      ["s_name"]=>
      string(1) "W"
      ["f_name"]=>
      string(5) "Woman"
    }
    object(demodb_code_construct)#1 (2) {
      ["s_name"]=>
      string(6) "s_name"
      ["f_name"]=>
      string(6) "f_name"
    }
    object(stdClass)#1 (2) {
      ["s_name"]=>
      string(1) "B"
      ["f_name"]=>
      string(6) "Bronze"
    }

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement
- cubrid_fetch() - Fetch the next row from a result set
- cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
- cubrid_fetch_row() - Return a numerical array with the values of the current row

# cubrid_fetch_row

(PECL CUBRID >= 8.3.0)

cubrid_fetch_row — Return a numerical array with the values of the current row

### Beschreibung

function cubrid_fetch_row(resource `$result`, int `$type` = ?): array

This function returns a numerical array with the values of the current row from the result set, starting from 0, and moves the internal data pointer ahead.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`type`
  Type can only be CUBRID_LOB, this parameter will be used only when you need to operate the lob object.

### Rückgabewerte

A numerical array, when process is successful.

`false`, when there are no more rows; NULL, when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_fetch_row() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT name,area,seats,address FROM stadium WHERE nation_code='GRE' AND seats > 10000");

    printf("%-40s %-10s %-6s %-20s\n", "name", "area", "seats", "address");
    while ($row = cubrid_fetch_row($req)) {
        printf("%-40s %-10s %-6s %-20s\n", $row[0], $row[1], $row[2], $row[3]);
    }

    // if you want to operate LOB object, you can use cubrid_fetch_row($req, CUBRID_LOB)

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    name                                     area       seats  address
    Panathinaiko Stadium                     86300.00   50000  Athens, Greece
    Olympic Stadium                          54700.00   13000  Athens, Greece
    Olympic Indoor Hall                      34100.00   18800  Athens, Greece
    Olympic Hall                             52400.00   21000  Athens, Greece
    Olympic Aquatic Centre                   42500.00   11500  Athens, Greece
    Markopoulo Olympic Equestrian Centre     64000.00   15000  Markopoulo, Athens, Greece
    Faliro Coastal Zone Olympic Complex      34650.00   12171  Faliro, Athens, Greece
    Athens Olympic Stadium                   120400.00  71030  Maroussi, Athens, Greece
    Ano Liossia                              34000.00   12000  Ano Liosia, Athens, Greece

### Siehe auch

- cubrid_execute() - Execute a prepared SQL statement
- cubrid_fetch() - Fetch the next row from a result set
- cubrid_fetch_array() - Fetch a result row as an associative array, a numeric array, or both
- cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
- cubrid_fetch_object() - Fetch the next row and return it as an object

# cubrid_field_flags

(PECL CUBRID >= 8.3.0)

cubrid_field_flags — Return a string with the flags of the given field offset

### Beschreibung

function cubrid_field_flags(resource `$result`, int `$field_offset`): string

This function returns a string with the flags of the given field offset separated by space. You can split the returned value using explode. The possible flags could be: `not_null`, `primary_key`, `unique_key`, `foreign_key`, `auto_increment`, `shared`, `reverse_index`, `reverse_unique` and `timestamp`.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`field_offset`
  The numerical field offset. The `field_offset` starts at 0. If `field_offset` does not exist, an error of level `E_WARNING` is also issued.

### Rückgabewerte

A string with flags, when process is successful.

`false` when invalid field_offset value.

-1 if SQL sentence is not SELECT.

### Beispiele

Beispiel #1 cubrid_field_flags() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Field Name", "Field Flags");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Field Name                     Field Flags
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_len

(PECL CUBRID >= 8.3.0)

cubrid_field_len — Get the maximum length of the specified field

### Beschreibung

function cubrid_field_len(resource `$result`, int `$field_offset`): int

This function returns the maximum length of the specified field on success, or it returns FALSE on failure.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`field_offset`
  The numerical field offset. The `field_offset` starts at 0. If `field_offset` does not exist, an error of level `E_WARNING` is also issued.

### Rückgabewerte

Maximum length, when process is successful.

`false` on failure.

### Beispiele

Beispiel #1 cubrid_field_len() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $column_names = cubrid_column_names($result);
    $column_types = cubrid_column_types($result);

    printf("%-30s %-30s %-15s\n", "Column Names", "Column Types", "Column Maxlen");
    for($i = 0, $size = count($column_names); $i < $size; $i++) {
        $column_len = cubrid_field_len($result, $i);
        printf("%-30s %-30s %-15s\n", $column_names[$i], $column_types[$i], $column_len);
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Column Names                   Column Types                   Column Maxlen
    host_year                      integer                        11
    event_code                     integer                        11
    athlete_code                   integer                        11
    stadium_code                   integer                        11
    nation_code                    char                           3
    medal                          char                           1
    game_date                      date                           10

# cubrid_field_name

(PECL CUBRID >= 8.3.0)

cubrid_field_name — Return the name of the specified field index

### Beschreibung

function cubrid_field_name(resource `$result`, int `$field_offset`): string

This function returns the name of the specified field index on success or it returns FALSE on failure.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`field_offset`
  The numerical field offset. The `field_offset` starts at 0. If `field_offset` does not exist, an error of level `E_WARNING` is also issued.

### Rückgabewerte

Name of specified field index, on success.

`false` on failure.

### Beispiele

Beispiel #1 cubrid_field_name() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM game WHERE host_year=2004 AND nation_code='AUS' AND medal='G'");

    $col_num = cubrid_num_cols($result);

    printf("%-30s %s\n", "Field Name", "Field Flags");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-30s %s\n", cubrid_field_name($result, $i), cubrid_field_flags($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Field Name                     Field Flags
    host_year                      not_null primary_key unique_key
    event_code                     not_null primary_key unique_key foreign_key
    athlete_code                   not_null primary_key unique_key foreign_key
    stadium_code                   not_null
    nation_code
    medal
    game_date

# cubrid_field_seek

(PECL CUBRID >= 8.3.0)

cubrid_field_seek — Move the result set cursor to the specified field offset

### Beschreibung

function cubrid_field_seek(resource `$result`, int `$field_offset` = 0): bool

This function moves the result set cursor to the specified field offset. This offset is used by cubrid_fetch_field() if it doesn't include a field offset. It returns TRUE on success or FALSE on failure.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`field_offset`
  The numerical field offset. The `field_offset` starts at 0. If `field_offset` does not exist, an error of level `E_WARNING` is also issued.

### Rückgabewerte

`true` on success.

`false` on failure.

### Beispiele

Beispiel #1 cubrid_field_seek() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $req = cubrid_execute($conn, "SELECT event_code,athlete_code,nation_code,game_date FROM game WHERE host_year=1988 and event_code=20001;");

    var_dump(cubrid_fetch_row($req));

    cubrid_field_seek($req, 1);
    $field = cubrid_fetch_field($req);

    printf("\n--- Field Properties ---\n");
    printf("%-30s %s\n", "name:", $field->name);
    printf("%-30s %s\n", "table:", $field->table);
    printf("%-30s \"%s\"\n", "default value:", $field->def);
    printf("%-30s %d\n", "max length:", $field->max_length);
    printf("%-30s %d\n", "not null:", $field->not_null);
    printf("%-30s %d\n", "unique key:", $field->unique_key);
    printf("%-30s %d\n", "multiple key:", $field->multiple_key);
    printf("%-30s %d\n", "numeric:", $field->numeric);
    printf("%-30s %s\n", "type:", $field->type);

    cubrid_close_request($req);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      [0]=>
      string(5) "20001"
      [1]=>
      string(5) "16132"
      [2]=>
      string(3) "KOR"
      [3]=>
      string(9) "1988-09-30"
    }

    --- Field Properties ---
    name:                          athlete_code
    table:                         game
    default value:                 ""
    max length:                    0
    not null:                      1
    unique key:                    1
    multiple key:                  0
    numeric:                       1
    type:                          integer

# cubrid_field_table

(PECL CUBRID >= 8.3.0)

cubrid_field_table — Return the name of the table of the specified field

### Beschreibung

function cubrid_field_table(resource `$result`, int `$field_offset`): string

This function returns the name of the table of the specified field. This is useful when using large select queries with JOINS.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`field_offset`
  The numerical field offset. The `field_offset` starts at 0. If `field_offset` does not exist, an error of level `E_WARNING` is also issued.

### Rückgabewerte

Name of the table of the specified field, on success.

`false` when invalid field_offset value.

-1 if SQL sentence is not SELECT.

### Beispiele

Beispiel #1 cubrid_field_table() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-15s %-15s %s\n",
            cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Field Table     Field Name      Field Type
    code            s_name          char
    code            f_name          varchar

# cubrid_field_type

(PECL CUBRID >= 8.3.0)

cubrid_field_type — Return the type of the column corresponding to the given field offset

### Beschreibung

function cubrid_field_type(resource `$result`, int `$field_offset`): string

This function returns the type of the column corresponding to the given field offset. The returned field type could be one of the following: "int", "real", "string", etc.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`field_offset`
  The numerical field offset. The `field_offset` starts at 0. If `field_offset` does not exist, an error of level `E_WARNING` is also issued.

### Rückgabewerte

Type of the column, on success.

`false` when invalid field_offset value.

-1 if SQL sentence is not SELECT.

### Beispiele

Beispiel #1 cubrid_field_type() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");
    $result = cubrid_execute($conn, "SELECT * FROM code");

    $col_num = cubrid_num_cols($result);

    printf("%-15s %-15s %s\n", "Field Table", "Field Name", "Field Type");
    for($i = 0; $i < $col_num; $i++) {
        printf("%-15s %-15s %s\n",
            cubrid_field_table($result, $i), cubrid_field_name($result, $i), cubrid_field_type($result, $i));
    }

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Field Table     Field Name      Field Type
    code            s_name          char
    code            f_name          varchar

# cubrid_list_dbs

(PECL CUBRID >= 8.3.0)

cubrid_list_dbs — Return an array with the list of all existing CUBRID databases

### Beschreibung

function cubrid_list_dbs(resource `$conn_identifier` = ?): array

This function returns an array with the list of all existing Cubrid databases.

### Parameter-Liste

`conn_identifier`
  The CUBRID connection.

### Rückgabewerte

An numeric array with all existing Cubrid databases; on success.

`false` on failure.

### Beispiele

Beispiel #1 cubrid_list_dbs() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $db_list = cubrid_list_dbs($conn);
    var_dump($db_list);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      [0]=>
      string(6) "demodb"
    }

# cubrid_num_fields

(PECL CUBRID >= 8.3.0)

cubrid_num_fields — Return the number of columns in the result set

### Beschreibung

function cubrid_num_fields(resource `$result`): int

This function returns the number of columns in the result set, on success, or it returns FALSE on failure.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute(), cubrid_query() and cubrid_prepare()

### Rückgabewerte

Number of columns, on success.

-1 if SQL sentence is not SELECT.

`false` when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_num_fields() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $row_num = cubrid_num_rows($req);
    $col_num = cubrid_num_fields($req);

    printf("Row Num: %d\nColumn Num: %d\n", $row_num, $col_num);

    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Row Num: 6
    Column Num: 2

# cubrid_ping

(PECL CUBRID >= 8.3.1)

cubrid_ping — Ping a server connection or reconnect if there is no connection

### Beschreibung

function cubrid_ping(resource `$conn_identifier` = ?): bool

Checks whether or not the connection to the server is working.

### Parameter-Liste

`conn_identifier`
  The CUBRID connection identifier. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

### Rückgabewerte

Returns `true` if the connection to the CUBRID server is working, otherwise `false`.

### Beispiele

Beispiel #1 cubrid_ping() example

    <?php
    set_time_limit(0);

    $conn = cubrid_connect('localhost', 33000, 'demodb');

    /* Assuming this query will take a long time */
    $sql = "select * from athlete";
    $result = cubrid_query($sql);
    if (!$result) {
        echo 'Query #1 failed, exiting.';
        exit;
    }

    /* Make sure the connection is still alive, if not, try to reconnect */
    if (!cubrid_ping($conn)) {
        echo 'Lost connection, exiting after query #1';
        exit;
    }
    cubrid_free_result($result);

    /* So the connection is still alive, let's run another query */
    $sql2 = "select * from code";
    $result2 = cubrid_query($sql2);
    ?>

# cubrid_query

(PECL CUBRID >= 8.3.1)

cubrid_query — Send a CUBRID query

### Beschreibung

function cubrid_query(string `$query`, resource `$conn_identifier` = ?): resource

cubrid_query() sends a unique query (multiple queries are not supported) to the currently active database on the server that's associated with the specified `conn_identifier`.

### Parameter-Liste

`query`
  An SQL query Data inside the query should be properly escaped.
`conn_identifier`
  The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

### Rückgabewerte

For SELECT, SHOW, DESCRIBE, EXPLAIN and other statements returning resultset, cubrid_query() returns a resource on success, or `false` on error.

For other type of SQL statements, INSERT, UPDATE, DELETE, DROP, etc, cubrid_query() returns `true` on success or `false` on error.

The returned result resource should be passed to cubrid_fetch_array(), and other functions for dealing with result tables, to access the returned data.

Use cubrid_num_rows() to find out how many rows were returned for a SELECT statement or cubrid_affected_rows() to find out how many rows were affected by a DELETE, INSERT, REPLACE, or UPDATE statement.

cubrid_query() will also fail and return `false` if the user does not have permission to access the table(s) referenced by the query.

### Beispiele

Beispiel #1 Invalid Query

The following query is syntactically invalid, so cubrid_query() fails and returns `false`.

    <?php
    $conn = cubrid_connect('localhost', 33000, 'demodb');

    $result = cubrid_query('SELECT * WHERE 1=1');
    if (!$result) {
        die('Invalid query: ' . cubrid_error());
    }

    ?>

Beispiel #2 Valid Query

The following query is valid, so cubrid_query() returns a resource.

    <?php
    // This could be supplied by a user, for example
    $firstname = 'fred';
    $lastname  = 'fox';

    $conn = cubrid_connect('localhost', 33000, 'demodb');

    cubrid_execute($conn,"DROP TABLE if exists friends");
    cubrid_execute($conn,"create table friends(firstname varchar,lastname varchar,address char(24),age int)");
    cubrid_execute($conn,"insert into friends values('fred','fox','home-1','20')");
    cubrid_execute($conn,"insert into friends values('blue','cat','home-2','21')");
    // Formulate Query
    // This is the best way to perform an SQL query
    // For more examples, see cubrid_real_escape_string()
    $query = sprintf("SELECT firstname, lastname, address, age FROM friends WHERE firstname='%s' AND lastname='%s'",
    cubrid_real_escape_string($firstname),
    cubrid_real_escape_string($lastname));

    // Perform Query
    $result = cubrid_query($query);

    // Check result
    // This shows the actual query sent to CUBRID, and the error. Useful for debugging.
    if (!$result) {
        $message  = 'Invalid query: ' . cubrid_error() . "\n";
        $message .= 'Whole query: ' . $query;
        die($message);
    }

    // Use result
    // Attempting to print $result won't allow access to information in the resource
    // One of the cubrid result functions must be used
    // See also cubrid_result(), cubrid_fetch_array(), cubrid_fetch_row(), etc.
    while ($row = cubrid_fetch_assoc($result)) {
        echo $row['firstname'];
        echo $row['lastname'];
        echo $row['address'];
        echo $row['age'];
    }

    // Free the resources associated with the result set
    // This is done automatically at the end of the script
    cubrid_free_result($result);
    ?>

### Siehe auch

- cubrid_connect() - Open a connection to a CUBRID Server
- cubrid_error() - Get the error message
- cubrid_real_escape_string() - Escape special characters in a string for use in an SQL statement
- cubrid_result() - Return the value of a specific field in a specific row
- cubrid_fetch_assoc() - Return the associative array that corresponds to the fetched row
- cubrid_unbuffered_query() - Perform a query without fetching the results into memory

# cubrid_real_escape_string

(PECL CUBRID >= 8.3.0)

cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement

### Beschreibung

function cubrid_real_escape_string(string `$unescaped_string`, resource `$conn_identifier` = ?): string

This function returns the escaped string version of the given string. It will escape the following characters: `'`. In general, single quotations are used to enclose character string. Double quotations may be used as well depending on the value of ansi_quotes, which is a parameter related to SQL statement. If the ansi_quotes value is set to no, character string enclosed by double quotations is handled as character string, not as an identifier. The default value is yes. If you want to include a single quote as part of a character string, enter two single quotes in a row.

### Parameter-Liste

`unescaped_string`
  The string that is to be escaped.
`conn_identifier`
  The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

### Rückgabewerte

Escaped string version of the given string, on success.

`false` on failure.

### Beispiele

Beispiel #1 cubrid_real_escape_string() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $unescaped_str = ' !"#$%&\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~';
    $escaped_str = cubrid_real_escape_string($unescaped_str);

    $len = strlen($unescaped_str);

    @cubrid_execute($conn, "DROP TABLE cubrid_test");
    cubrid_execute($conn, "CREATE TABLE cubrid_test (t char($len))");
    cubrid_execute($conn, "INSERT INTO cubrid_test (t) VALUES('$escaped_str')");

    $req = cubrid_execute($conn, "SELECT * FROM cubrid_test");
    $row = cubrid_fetch_assoc($req);

    var_dump($row);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["t"]=>
      string(95) " !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
    }

# cubrid_result

(PECL CUBRID >= 8.3.0)

cubrid_result — Return the value of a specific field in a specific row

### Beschreibung

function cubrid_result(resource `$result`, int `$row`, mixed `$field` = 0): string

This function returns the value of a specific field in a specific row from a result set.

### Parameter-Liste

`result`
  `result` comes from a call to cubrid_execute()
`row`
  The row number from the result that is being retrieved. Row numbers start at 0.
`field`
  The name or offset of the `field` being retrieved. It can be the field's offset, the field's name, or the field's table dot field name (tablename.fieldname). If the column name has been aliased ('select foo as bar from...'), use the alias instead of the column name. If undefined, the first field is retrieved.

### Rückgabewerte

Value of a specific field, on success (NULL if value if null).

`false` on failure.

### Beispiele

Beispiel #1 cubrid_result() example

    <?php
    $conn = cubrid_connect("localhost", 33000, "demodb");

    $req = cubrid_execute($conn, "SELECT * FROM code");

    $result = cubrid_result($req, 0);
    var_dump($result);

    $result = cubrid_result($req, 0, 1);
    var_dump($result);

    $result = cubrid_result($req, 5, "f_name");
    var_dump($result);

    cubrid_close_request($req);
    cubrid_disconnect($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "X"
    string(5) "Mixed"
    string(4) "Gold"

# cubrid_unbuffered_query

(PECL CUBRID >= 8.3.0)

cubrid_unbuffered_query — Perform a query without fetching the results into memory

### Beschreibung

function cubrid_unbuffered_query(string `$query`, resource `$conn_identifier` = ?): resource

This function performs a query without waiting for that all query results have been complete. It will return when the results are being generated.

### Parameter-Liste

`query`
  A SQL query.
`conn_identifier`
  The CUBRID connection. If the connection identifier is not specified, the last connection opened by cubrid_connect() is assumed.

### Rückgabewerte

For SELECT, SHOW, DESCRIBE or EXPLAIN statements returns a request identifier resource on success.

For other type of SQL statements, UPDATE, DELETE, DROP, etc, returns `true` on success.

`false` on failure.

### Beispiele

Beispiel #1 cubrid_unbuffered_query() example

    <?php
        $link = cubrid_connect("localhost", 30000, "demodb", "dba", "");
        if (!$link)
        {
            die('Could not connect.');
        }
        $query = "select * from code";
        $result = cubrid_unbuffered_query($query, $link);

        while ($row = cubrid_fetch($result))
        {
            var_dump($row);
        }

        cubrid_close_request($result);
        cubrid_disconnect($link);
    ?>

### Anmerkungen

> Hinweis: The benefits of cubrid_unbuffered_query() come at a cost: you cannot use cubrid_num_rows() and cubrid_data_seek() on a result set returned from cubrid_unbuffered_query().

## Inhaltsverzeichnis

- cubrid_affected_rows — Return the number of rows affected by the last SQL statement
- cubrid_client_encoding — Return the current CUBRID connection charset
- cubrid_close — Close CUBRID connection
- cubrid_data_seek — Move the internal row pointer of the CUBRID result
- cubrid_db_name — Get db name from results of cubrid_list_dbs
- cubrid_errno — Return the numerical value of the error message from previous CUBRID operation
- cubrid_error — Get the error message
- cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both
- cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row
- cubrid_fetch_field — Get column information from a result and return as an object
- cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row
- cubrid_fetch_object — Fetch the next row and return it as an object
- cubrid_fetch_row — Return a numerical array with the values of the current row
- cubrid_field_flags — Return a string with the flags of the given field offset
- cubrid_field_len — Get the maximum length of the specified field
- cubrid_field_name — Return the name of the specified field index
- cubrid_field_seek — Move the result set cursor to the specified field offset
- cubrid_field_table — Return the name of the table of the specified field
- cubrid_field_type — Return the type of the column corresponding to the given field offset
- cubrid_list_dbs — Return an array with the list of all existing CUBRID databases
- cubrid_num_fields — Return the number of columns in the result set
- cubrid_ping — Ping a server connection or reconnect if there is no connection
- cubrid_query — Send a CUBRID query
- cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement
- cubrid_result — Return the value of a specific field in a specific row
- cubrid_unbuffered_query — Perform a query without fetching the results into memory

# CUBRID Obsolete Aliases and Functions

# cubrid_load_from_glo

(PECL CUBRID >= 8.3.0)

cubrid_load_from_glo — Read data from a GLO instance and save it in a file

### Beschreibung

function cubrid_load_from_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

The cubrid_load_from_glo() function is used to read a data from a glo instance, and saves it in a designated file.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  Oid of the glo instance that you want to read the data from.
`file_name`
  Name of the file where you want to save the data in.

### Rückgabewerte

`true`, when process is successful.

`false`, when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_load_from_glo() example

    <?php
    $req = cubrid_execute ($con, "select image from person where id=1");
    if ($req) {
       list ($oid) = cubrid_fetch($req);
       cubrid_close_request($req);
       $res = cubrid_load_from_glo ($con, $oid, "output.jpg");
       if ($res) {
          echo "image changed successfully";
       }
    }
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: cubrid_load_from_glo()

> Hinweis: This function is removed from CUBRID 3.1.

### Siehe auch

- cubrid_new_glo() - Create a glo instance
- cubrid_save_to_glo() - Save requested file in a GLO instance
- cubrid_send_glo() - Read data from glo and send it to std output

# cubrid_new_glo

(PECL CUBRID >= 8.3.0)

cubrid_new_glo — Create a glo instance

### Beschreibung

function cubrid_new_glo(resource `$conn_identifier`, string `$class_name`, string `$file_name`): string

The cubrid_new_glo() function is used to create a glo instance in the requested class (glo class). The glo created is a LO type, and is stored in the `file_name` file.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`class_name`
  Name of the class that you want to create a glo in.
`file_name`
  The file name that you want to save in the newly created glo.

### Rückgabewerte

Oid of the instance created, when process is successful.

`false`, when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_new_glo() example

    <?php
    $oid = cubrid_new_glo ($con, "glo", "input.jpg");
    if ($oid){
       // the type of column "image" is "object"
       $req = cubrid_execute ($con, "insert into person(image) values($oid)");
       if ($req) {
          echo "image inserted successfully";
          cubrid_close_request ($req);
          cubrid_commit($con);
       }
    }
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: cubrid_new_glo()

> Hinweis: This function is removed from CUBRID 3.1.

### Siehe auch

- cubrid_save_to_glo() - Save requested file in a GLO instance
- cubrid_load_from_glo() - Read data from a GLO instance and save it in a file
- cubrid_send_glo() - Read data from glo and send it to std output

# cubrid_save_to_glo

(PECL CUBRID >= 8.3.0)

cubrid_save_to_glo — Save requested file in a GLO instance

### Beschreibung

function cubrid_save_to_glo(resource `$conn_identifier`, string `$oid`, string `$file_name`): int

The cubrid_save_to_glo() function is used to save requested file in a glo instance.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  Oid of the glo instance that you want to save a file in.
`file_name`
  The name of the file that you want to save.

### Rückgabewerte

`true`, when process is successful.

`false`, when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_save_to_glo() example

    <?php
    $req = cubrid_execute ($con, "select image from person where id=1");
    if ($req) {
       list ($oid) = cubrid_fetch($req);
       cubrid_close_request($req);
       $res = cubrid_save_to_glo ($con, $oid, "input.jpg");
       if ($res) {
          echo "image changed successfully";
       }
    }
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: cubrid_save_to_glo()

> Hinweis: This function is removed from CUBRID 3.1.

### Siehe auch

- cubrid_new_glo() - Create a glo instance
- cubrid_load_from_glo() - Read data from a GLO instance and save it in a file
- cubrid_send_glo() - Read data from glo and send it to std output

# cubrid_send_glo

(PECL CUBRID >= 8.3.0)

cubrid_send_glo — Read data from glo and send it to std output

### Beschreibung

function cubrid_send_glo(resource `$conn_identifier`, string `$oid`): int

The cubrid_send_glo() function is used to read data from glo instance and sends it to the PHP standard output.

### Parameter-Liste

`conn_identifier`
  Connection identifier.
`oid`
  Oid of the glo instance that you want to read data from.

### Rückgabewerte

`true`, when process is successful.

`false`, when process is unsuccessful.

### Beispiele

Beispiel #1 cubrid_send_glo() example

    <?php
    $req = cubrid_execute ($con, "select image from person where id =1");
    if ($req) {
      list ($oid) = cubrid_fetch($req);
      cubrid_close_request($req);
      Header ("Content-type: image/jpeg");
      cubrid_send_glo ($con, $oid);
    }
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: cubrid_send_glo()

> Hinweis: This function is removed from CUBRID 3.1.

### Siehe auch

- cubrid_new_glo() - Create a glo instance
- cubrid_save_to_glo() - Save requested file in a GLO instance
- cubrid_load_from_glo() - Read data from a GLO instance and save it in a file

## Inhaltsverzeichnis

- cubrid_load_from_glo — Read data from a GLO instance and save it in a file
- cubrid_new_glo — Create a glo instance
- cubrid_save_to_glo — Save requested file in a GLO instance
- cubrid_send_glo — Read data from glo and send it to std output

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Beispiele
- CUBRID Funktionen
  - cubrid_bind — Bind variables to a prepared statement as parameters
  - cubrid_close_prepare — Close the request handle
  - cubrid_close_request — Close the request handle
  - cubrid_col_get — Get contents of collection type column using OID
  - cubrid_col_size — Get the number of elements in collection type column using OID
  - cubrid_column_names — Get the column names in result
  - cubrid_column_types — Get column types in result
  - cubrid_commit — Commit a transaction
  - cubrid_connect — Open a connection to a CUBRID Server
  - cubrid_connect_with_url — Establish the environment for connecting to CUBRID server
  - cubrid_current_oid — Get OID of the current cursor location
  - cubrid_disconnect — Close a database connection
  - cubrid_drop — Delete an instance using OID
  - cubrid_error_code — Get error code for the most recent function call
  - cubrid_error_code_facility — Get the facility code of error
  - cubrid_error_msg — Get last error message for the most recent function call
  - cubrid_execute — Execute a prepared SQL statement
  - cubrid_fetch — Fetch the next row from a result set
  - cubrid_free_result — Free the memory occupied by the result data
  - cubrid_get — Get a column using OID
  - cubrid_get_autocommit — Get auto-commit mode of the connection
  - cubrid_get_charset — Return the current CUBRID connection charset
  - cubrid_get_class_name — Get the class name using OID
  - cubrid_get_client_info — Return the client library version
  - cubrid_get_db_parameter — Returns the CUBRID database parameters
  - cubrid_get_query_timeout — Get the query timeout value of the request
  - cubrid_get_server_info — Return the CUBRID server version
  - cubrid_insert_id — Return the ID generated for the last updated AUTO_INCREMENT column
  - cubrid_is_instance — Check whether the instance pointed by OID exists
  - cubrid_lob_close — Close BLOB/CLOB data
  - cubrid_lob_export — Export BLOB/CLOB data to file
  - cubrid_lob_get — Get BLOB/CLOB data
  - cubrid_lob_send — Read BLOB/CLOB data and send straight to browser
  - cubrid_lob_size — Get BLOB/CLOB data size
  - cubrid_lob2_bind — Bind a lob object or a string as a lob object to a prepared statement as parameters
  - cubrid_lob2_close — Close LOB object
  - cubrid_lob2_export — Export the lob object to a file
  - cubrid_lob2_import — Importiert BLOB/CLOB-Daten aus einer Datei
  - cubrid_lob2_new — Create a lob object
  - cubrid_lob2_read — Read from BLOB/CLOB data
  - cubrid_lob2_seek — Move the cursor of a lob object
  - cubrid_lob2_seek64 — Move the cursor of a lob object
  - cubrid_lob2_size — Get a lob object's size
  - cubrid_lob2_size64 — Get a lob object's size
  - cubrid_lob2_tell — Tell the cursor position of the LOB object
  - cubrid_lob2_tell64 — Tell the cursor position of the LOB object
  - cubrid_lob2_write — Write to a lob object
  - cubrid_lock_read — Set a read lock on the given OID
  - cubrid_lock_write — Set a write lock on the given OID
  - cubrid_move_cursor — Move the cursor in the result
  - cubrid_next_result — Get result of next query when executing multiple SQL statements
  - cubrid_num_cols — Return the number of columns in the result set
  - cubrid_num_rows — Get the number of rows in the result set
  - cubrid_pconnect — Öffnet eine dauerhafte Verbindung zu einem CUBRID-Server
  - cubrid_pconnect_with_url — Open a persistent connection to CUBRID server
  - cubrid_prepare — Prepare a SQL statement for execution
  - cubrid_put — Update a column using OID
  - cubrid_rollback — Roll back a transaction
  - cubrid_schema — Get the requested schema information
  - cubrid_seq_drop — Delete an element from sequence type column using OID
  - cubrid_seq_insert — Fügt ein Element in eine Spalte vom Typ Sequenz anhand der OID ein
  - cubrid_seq_put — Update the element value of sequence type column using OID
  - cubrid_set_add — Insert a single element to set type column using OID
  - cubrid_set_autocommit — Set autocommit mode of the connection
  - cubrid_set_db_parameter — Sets the CUBRID database parameters
  - cubrid_set_drop — Delete an element from set type column using OID
  - cubrid_set_query_timeout — Set the timeout time of query execution
  - cubrid_version — Get the CUBRID PHP module's version
- CUBRID MySQL Compatibility Functions
  - cubrid_affected_rows — Return the number of rows affected by the last SQL statement
  - cubrid_client_encoding — Return the current CUBRID connection charset
  - cubrid_close — Close CUBRID connection
  - cubrid_data_seek — Move the internal row pointer of the CUBRID result
  - cubrid_db_name — Get db name from results of cubrid_list_dbs
  - cubrid_errno — Return the numerical value of the error message from previous CUBRID operation
  - cubrid_error — Get the error message
  - cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both
  - cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row
  - cubrid_fetch_field — Get column information from a result and return as an object
  - cubrid_fetch_lengths — Return an array with the lengths of the values of each field from the current row
  - cubrid_fetch_object — Fetch the next row and return it as an object
  - cubrid_fetch_row — Return a numerical array with the values of the current row
  - cubrid_field_flags — Return a string with the flags of the given field offset
  - cubrid_field_len — Get the maximum length of the specified field
  - cubrid_field_name — Return the name of the specified field index
  - cubrid_field_seek — Move the result set cursor to the specified field offset
  - cubrid_field_table — Return the name of the table of the specified field
  - cubrid_field_type — Return the type of the column corresponding to the given field offset
  - cubrid_list_dbs — Return an array with the list of all existing CUBRID databases
  - cubrid_num_fields — Return the number of columns in the result set
  - cubrid_ping — Ping a server connection or reconnect if there is no connection
  - cubrid_query — Send a CUBRID query
  - cubrid_real_escape_string — Escape special characters in a string for use in an SQL statement
  - cubrid_result — Return the value of a specific field in a specific row
  - cubrid_unbuffered_query — Perform a query without fetching the results into memory
- CUBRID Obsolete Aliases and Functions
  - cubrid_load_from_glo — Read data from a GLO instance and save it in a file
  - cubrid_new_glo — Create a glo instance
  - cubrid_save_to_glo — Save requested file in a GLO instance
  - cubrid_send_glo — Read data from glo and send it to std output

# dBase

# Einführung

> Hinweis:

> Diese Erweiterung wurde ins » PECL-Repositorium verschoben und ist nicht mehr Teil von PHP ab PHP 5.3.0.

Diese Funktionen erlauben Ihnen den Zugriff auf Datensätze, die in Datenbanken im dBase-Format (dbf) vorliegen.

Warnung

Wir empfehlen, keine dBase-Dateien als Produktions-Datenbank zu verwenden. Wählen Sie dafür stattdessen » SQLite oder einen echten SQL-Server; » MySQL oder » Postgres sind bei PHP eine gute Wahl. Die dBase-Unterstützung durch PHP dient hauptsächlich dem Im- und Export von Daten zu oder aus ihrer Web-Datenbank, weil das DBF-Datei-Format allgemein von Windows-Tabellenkalulationen und -Zeitplanern verstanden wird.

Achtung

Von dbase 7.0.0 an werden Datenbanken automatisch per flock() gesperrt. Zuvor wurden Sperren nicht unterstützt, so dass zwei Webserver-Prozesse, die gleichzeitig dieselbe dBase-Datei änderten, mit hoher Wahrscheinlichkeit die Datenbank ruinierten. Dies kann auf Systemen, die die Sperren auf Prozessebene implementieren unter multithreaded SAPIS, auch noch mit dbase 7.0.0+ passieren.

dBase-Dateien sind einfache sequentielle Dateien mit fester Datensatzlänge. Neue Datensätze werden am Dateiende angehängt und gelöschte Datensätze werden beibehalten, bis Sie dbase_pack() aufrufen.

Nur dbf Datei-Level 3 (dBASE III+) - 5 (dBASE V) werden unterstützt. Folgende dBase-Feldtypen stehen stehen zur Verfügung:

Verfügbare Feldtypen
Feld | dBase-Typ | Format | Zusätzliche Informationen
--- | --- | --- | ---
`M` | Memo | n/a | Dieser Typ wird von PHP nicht unterstützt, ein solches Feld wird ignoriert
`D` | Date | `YYYYMMDD` | Die Feldlänge ist auf acht Zeichen begrenzt
`T` | DateTime | `YYYYMMDDhhmmss.uuu` | (FoxPro) Es wird keine Gültigkeitsprüfung vorgenommen. Verfügbar seit dbase 7.0.0.
`N` | Number | Eine Zahl | Sie müssen die Länge und die Genauigkeit (die Anzahl der Nachkommastellen) angeben.
`F` | Float | Eine Gleitkommazahl | Dasselbe wie `N`.
`C` | String | Eine Zeichenkette | Sie müssen die Länge angeben. Wenn Daten eingetragen werden, werden Leerzeichen ans Ende der Zeichenkette angehängt, bis die festgelegte Länge erreicht ist. Überlange Zeichenketten werden stillschweigend abgeschnitten, wenn die Daten gespeichert werden.
`L` | Boolean | `T` oder `Y` für `true`, `F` oder `N` für `false`, `?` für nicht initialisiert. | Wird seit dbase 7.0.0 als bool (`true` oder `false`), oder `null` für nicht initialisierte Felder zurückgeliefert. Wurde vorher als int (`1` oder `0`> zurückgegeben.

> Hinweis:

> Von dbase 7.0.0 an werden nullable Felder für `DBASE_TYPE_FOXPRO` Datenbanken unterstützt. Ist ein Feld nullable, wird die Übergabe von `null` das entsprechende Flag setzen, und beim späteren Abruf wird der Feldwert `null` sein.

> Hinweis:

> Indizes und Memo-Felder werden nicht unterstützt.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Ressource-Typen

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/dbase.

## Ressource-Typen

Von 7.0.0 an ist der Ressourcetyp `dbase` definiert, der von dbase_open() und dbase_create() zurückgegeben wird.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`DBASE_VERSION` (string)
  Die Version der Extension. (Verfügbar von dbase 7.0.0 an)
`DBASE_RDONLY` (int)
  Öffne die Datenbank nur zum Lesen. Verwendet mit dbase_open(). (Verfügbar von dbase 7.0.0 an)
`DBASE_RDWR` (int)
  Öffne die Datenbank zum Lesen und Schreiben. Verwendet mit dbase_open(). (Verfügbar von dbase 7.0.0 an)
`DBASE_TYPE_DBASE` (int)
  Erzeuge eine Datenbank im dBASE-Stil. Verwendet mit dbase_create(). (Verfügbar von dbase 7.0.0 an)
`DBASE_TYPE_FOXPRO` (int)
  Erzeuge eine Datenbank im FoxPro-Stil. Verwendet mit dbase_create(). (Verfügbar von dbase 7.0.0 an)

# dBase Funktionen

## Beispiele

Für viele Beispiele dieses Abschnitts wird eine dBase-Datenbank benötigt. Wir werden die Datenbank /tmp/test.dbf verwenden, die im Beispiel von dbase_create() erzeugt wird.

# dbase_add_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_add_record — Hängt einen Datensatz an eine Datenbank an

### Beschreibung

function dbase_add_record(resource `$database`, array `$data`): bool

Hängt die angegebenen Daten an die Datenbank an.

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

`data`

  Ein indiziertes Datenarray. Falls die Anzahl der Elemente nicht mit der Anzahl der Datenbankfelder übereinstimmt, schlägt dbase_add_record() fehl.

  > Hinweis:

  > Vergessen Sie nicht, den `deleted`-Schlüssel zu löschen, wenn Sie für diesen Parameter den Rückgabewert von dbase_get_record() verwenden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 Einen Datensatz in eine dBase-Datenbank einfügen

    <?php

    // im lesen/schreiben-Modus öffnen
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      dbase_add_record($db, array(
          date('Ymd'),
          'Maxim Topolov',
          '23',
          'max@example.com',
          'T'));
      dbase_close($db);
    }

    ?>

### Siehe auch

- dbase_delete_record() - Markiert einen Datensatz als gelöscht
- dbase_replace_record() - Ersetzt einen Datensatz in einer Datenbank

# dbase_close

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_close — Schließt eine Datenbank

### Beschreibung

function dbase_close(resource `$database`): bool

Schließt die angegebene Datenbank-Ressource.

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 Schließen einer dBase-Datenbankdatei

    <?php

    // im nur-lesen-Modus öffnen
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      // ein paar Daten auslesen ...

      dbase_close($db);
    }

    ?>

### Siehe auch

- dbase_open() - Öffnet eine Datenbank
- dbase_create() - Erzeugt eine Datenbank

# dbase_create

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_create — Erzeugt eine Datenbank

### Beschreibung

function dbase_create(string `$path`, array `$fields`, int `$type` = DBASE_TYPE_DBASE): resource

Erzeugt eine der angegebenen Definition entsprechende dBase-Datenbank. Existiert die Datei bereits, wird sie nicht gekürzt. dbase_pack() kann aufgerufen werden, um die Kürzung zu erzwingen.

> Hinweis:

> Diese Funktion wird von open_basedir beeinflusst.

### Parameter-Liste

`path`

  Der Pfad der Datenbank. Das kann ein relativer oder absoluter Pfad zu der Datei sein, in der dBase die Daten speichert.

`fields`

  Ein Array aus Arrays, von denen jedes das Format eines Datenbankfeldes beschreibt. Jedes Feld besteht aus einem Namen, einem Zeichen für den Feldtyp und gegebenenfalls einer Länge, einer Genauigkeit und einem nullable-Flag. Die unterstützten Feldtypen sind im Einführungsabschnitt aufgeführt.

  > Hinweis:

  > Die Feldnamen sind längenbeschränkt, und dürfen 10 Zeichen nicht überschreiten.

`type`

  Der zu erzeugende Datenbanktype. Entweder `DBASE_TYPE_DBASE` oder `DBASE_TYPE_FOXPRO`.

### Rückgabewerte

Gibt eine Datenbank-Ressource zurück, falls die Datenbank erfolgreich erzeugt werden konnte oder `false`, falls ein Fehler auftrat.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | Der Parameter `type` wurde hinzugefügt.
PECL dbase 7.0.0 | Der Rückgabewert ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 Erzeugen einer dBase-Datenbankdatei

    <?php

    // Datenbank-"Definition"
    $def = array(
      array("Datum",       "D"),
      array("Name",        "C",  50),
      array("Alter",       "N",   3, 0),
      array("Email",       "C", 128),
      array("IstMitglied", "L")
    );

    // Erzeugung
    if (!dbase_create('/tmp/test.dbf', $def)) {
      echo "Fehler, konnte die Datenbank nicht erzeugen\n";
    }

    ?>

### Siehe auch

- dbase_open() - Öffnet eine Datenbank
- dbase_close() - Schließt eine Datenbank

# dbase_delete_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_delete_record — Markiert einen Datensatz als gelöscht

### Beschreibung

function dbase_delete_record(resource `$database`, int `$number`): bool

Markiert den angegebenen Datensatz in der Datenbank als gelöscht.

> Hinweis:

> Um den Datensatz wirklich aus der Datenbank zu entfernen, müssen sie noch dbase_pack() aufrufen.

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

`number`

  Eine Ganzzahl, die von 1 bis zur Anzahl der Datensätze in der Datenbank (wie von dbase_numrecords() zurückgegeben) geht.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun eine resource statt eines int.

### Siehe auch

- dbase_add_record() - Hängt einen Datensatz an eine Datenbank an
- dbase_replace_record() - Ersetzt einen Datensatz in einer Datenbank

# dbase_get_header_info

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_header_info — Liefert Informationen des Dateikopfs einer Datenbank

### Beschreibung

function dbase_get_header_info(resource `$database`): array

Liefert für die angegebene Datenbank-Verbindungskennung Informationen über die Datenbankstruktur.

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

### Rückgabewerte

Ein indiziertes Array mit einem Eintrag für jedes Feld der Datenbank. Der Index des Arrays beginnt bei 0.

Jedes Element des Arrays enthält ein assoziatives Array mit folgenden Informationen über die Felder:

name
  Der Name des Feldes
type
  Der lesbare Name für den dBase-Typ des Feldes (d. h. date, boolean, etc.) Die unterstützten Feldtypen sind im Einführungsabschnitt aufgeführt.
length
  Die Anzahl der Bytes, die dieses Feld haben kann
precision
  Die Anzahl der Nachkommastellen des Feldes
format
  Ein für das Feld vorgeschlagenes printf()-Format-Spezifikationssymbol
offset
  Der Byte-Abstand des Feldes vom Anfang der Zeile

Falls die Dateikopf-Informationen der Datenbank nicht gelesen werden können, wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 Anzeigen der Informationen des Dateikopfs einer dBase-Datenbankdatei

    <?php
    // Der Pfad zur dBase-Datei
    $db_pfad = "/tmp/test.dbf";

    // Öffnen der dBase-Datei
    $dbh = dbase_open($db_pfad, 0)
      or die("Fehler! Konnte die dBase-Datenbankdatei '$db_pfad' nicht öffnen.");

    // Auslesen der Feldinformationen
    $feld_info = dbase_get_header_info($dbh);

    // Ausgeben der Informationen
    print_r($feld_info);
    ?>

# dbase_get_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record — Liefert einen Datensatz aus einer Datenbank als indiziertes Array

### Beschreibung

function dbase_get_record(resource `$database`, int `$number`): array

Gibt einen Datensatz aus einer Datenbank als indiziertes Array zurück.

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

`number`

  Der Index des Datensatzes zwischen `1` und `dbase_numrecords($dbase_identifier)`.

### Rückgabewerte

Ein indiziertes Array mit dem Datensatz. Dieses Array enthält zusätzlich einen assoziativen Schlüssel namens `deleted`, der auf 1 gesetzt ist, wenn der Datensatz zum Löschen markiert wurde (siehe dbase_delete_record()).

Jedes Feld wird in den entsprechenden PHP-Typ umgewandelt, ausgenommen:

- Datumsfelder werden als Zeichenkette zurückgegeben.
- Zeitstempelwerte werden in Zeichenketten umgewandelt.
- Ganzzahlen außerhalb des Bereiches `PHP_INT_MIN`..`PHP_INT_MAX` werden als Zeichenkette zurückgegeben.
- Boolesche Werte (`L`) werden zu `1` oder `0` umgewandelt.

Falls ein Fehler auftritt, gibt dbase_get_record() `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun vom Typ resource statt int.

### Siehe auch

- dbase_get_record_with_names() - Liefert einen Datensatz aus einer Datenbank als assoziatives Array

# dbase_get_record_with_names

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_record_with_names — Liefert einen Datensatz aus einer Datenbank als assoziatives Array

### Beschreibung

function dbase_get_record_with_names(resource `$database`, int `$number`): array

Gibt einen Datensatz aus einer dBase-Datenbank als assoziatives Array zurück.

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

`number`

  Der Index des Datensatzes zwischen `1` und `dbase_numrecords($dbase_identifier)`.

### Rückgabewerte

Ein assoziatives Array mit dem Datensatz. Dieses Array enthält einen zusätzlichen Schlüssel namens `deleted`, der auf 1 gesetzt ist, wenn der Datensatz zum Löschen markiert wurde (siehe dbase_delete_record()). Daher ist es nicht möglich den Wert eines Feldes mit dem Namen `deleted` mit dieser Funktion zu ermitteln.

Jedes Feld wird in den entsprechenden PHP-Typ umgewandelt, ausgenommen:

- Datumsfelder werden als Zeichenkette zurückgegeben.
- Zeitstempelwerte werden in Zeichenketten umgewandelt.
- Ganzzahlen außerhalb des Bereiches `PHP_INT_MIN`..`PHP_INT_MAX` werden als Zeichenkette zurückgegeben.
- Boolesche Werte (`L`) werden zu `1` oder `0` umgewandelt.

Falls ein Fehler auftritt, gibt dbase_get_record_with_names() `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 Liste aller in der Datenbank eingetragener Mitglieder

    <?php
    // im nur-lesen-Modus öffnen
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      $anzahl_datensaetze = dbase_numrecords($db);
      for ($i = 1; $i <= $anzahl_datensaetze; $i++) {
          $datensatz = dbase_get_record_with_names($db, $i);
          if ($datensatz['IstMitglied'] == 1) {
              echo "Mitglied #$i: " . trim($datensatz['Name']) . "\n";
          }
      }
    }
    ?>

### Siehe auch

- dbase_get_record() - Liefert einen Datensatz aus einer Datenbank als indiziertes Array

# dbase_numfields

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numfields — Liefert die Anzahl der Felder einer Datenbank

### Beschreibung

function dbase_numfields(resource `$database`): int

Gibt die Anzahl der Felder (Spalten) der angegebenen Datenbank zurück.

> Hinweis:

> Die Anzahl der Felder liegt zwischen 0 und `dbase_numfields($db)-1`, wogegen die Anzahl der Datensätze zwischen 1 und `dbase_numrecords($db)` liegt.

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

### Rückgabewerte

Die Anzahl der Felder in der Datenbank oder `false`, falls ein Fehler auftrat.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 dbase_numfields()-Beispiel

    <?php

    $rec = dbase_get_record($db, $recno);
    $nf  = dbase_numfields($db);
    for ($i = 0; $i < $nf; $i++) {
      echo $rec[$i], "\n";
    }

    ?>

### Siehe auch

- dbase_numrecords() - Liefert die Anzahl der Datensätze einer Datenbank

# dbase_numrecords

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numrecords — Liefert die Anzahl der Datensätze einer Datenbank

### Beschreibung

function dbase_numrecords(resource `$database`): int

Gibt die Anzahl der Datensätze (Zeilen) der angegebenen Datenbank zurück.

> Hinweis:

> Datensätze, die zur Löschung markiert sind, werden ebenfalls gezählt.

> Hinweis:

> Die Anzahl der Datensätze liegt zwischen 1 und `dbase_numrecords($db)`, wogegen die Anzahl der Felder zwischen 0 und `dbase_numfields($db)-1` liegt.

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

### Rückgabewerte

Die Anzahl der Datensätze in der Datenbank oder `false`, falls ein Fehler auftrat.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 Eine Schleife über alle Datensätze der Datenbank ausführen

    <?php

    // im nur-lesen-Modus öffnen
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      $anzahl_datensaetze = dbase_numrecords($db);
      for ($i = 1; $i <= $anzahl_datensaetze; $i++) {
          $record = dbase_get_record($db, $i);
          if (!$record['deleted']) {
              // mache etwas mit $record
          } else {
              // mache etwas mit dem gelöschten $record, oder ignoriere ihn
          }
      }
    }

    ?>

### Siehe auch

- dbase_numfields() - Liefert die Anzahl der Felder einer Datenbank

# dbase_open

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_open — Öffnet eine Datenbank

### Beschreibung

function dbase_open(string `$path`, int `$mode`): resource|false

dbase_open() öffnet eine dBase-Datenbank im angegebenen Zugriffsmodus.

> Hinweis:

> Diese Funktion wird von open_basedir beeinflusst.

### Parameter-Liste

`path`

  Der Pfad der Datenbank. Das kann ein relativer oder absoluter Pfad zu der Datei sein, in der dBase die Daten speichert.

`mode`

  Eine Ganzzahl, die denen des open()-Systemaufrufs entspricht (typischerweise bedeutet 0 nur lesen, 1 nur schreiben und 2 lesen und schreiben).

  > Hinweis:

  > Eine dBase-Datei kann nicht im nur-schreiben-Modus geöffnet werden, weil diese Funktion dann die Informationen des Dateikopfs nicht lesen könnte. Deshalb kann der `mode` 1 nicht verwendet werden.

  Von dbase 7.0.0 an kann `DBASE_RDONLY`, bzw. `DBASE_RDWR` verwendet werden, um den `mode` anzugeben.

### Rückgabewerte

Gibt im Erfolgsfall eine Datenbank-Ressource zurück. Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | Der Rückgabewert ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 Öffnen einer dBase-Datenbankdatei

    <?php

    // im nur-lesen-Modus öffnen
    $db = dbase_open('/tmp/test.dbf', 0);

    if ($db) {
      // ein paar Daten lesen ...

      dbase_close($db);
    }

    ?>

### Siehe auch

- dbase_create() - Erzeugt eine Datenbank
- dbase_close() - Schließt eine Datenbank

# dbase_pack

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_pack — Entfernt die als gelöscht markierten Datensätze aus einer Datenbank

### Beschreibung

function dbase_pack(resource `$database`): bool

Entfernt die mittels dbase_delete_record() als gelöscht markierten Datensätze endgültig aus der angegebenen Datenbank. Es ist zu beachten, dass die Datei nach erfolgreichem Packen gekürzt wird (anders als bei PACK-Kommando von dBASE III).

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 Leeren einer dBase-Datenbank

    <?php

    // im lesen-schreiben-Modus öffnen
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      $anzahl_datensaetze = dbase_numrecords($db);
      for ($i = 1; $i <= $anzahl_datensaetze; $i++) {
          dbase_delete_record($db, $i);
      }
      // Datensätze löschen
      dbase_pack($db);
    }

    ?>

### Siehe auch

- dbase_delete_record() - Markiert einen Datensatz als gelöscht

# dbase_replace_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_replace_record — Ersetzt einen Datensatz in einer Datenbank

### Beschreibung

function dbase_replace_record(resource `$database`, array `$data`, int `$number`): bool

Ersetzt in der Datenbank den angegebenen Datensatz `record_number` mit den Daten aus `record`.

### Parameter-Liste

`database`

  Die Datenbank-Ressource, die von dbase_open() oder dbase_create() zurückgegeben wurde.

`data`

  Ein indiziertes Datenarray. Falls die Anzahl der Elemente nicht mit der Anzahl der Datenbankfelder übereinstimmt, schlägt dbase_replace_record() fehl.

  > Hinweis:

  > Vergessen Sie nicht, den `deleted`-Schlüssel zu löschen, wenn Sie für diesen Parameter den Rückgabewert von dbase_get_record() verwenden.

`number`

  Eine Ganzzahl, die von 1 bis zur Anzahl der Datensätze in der Datenbank (wie von dbase_numrecords() zurückgegeben) geht.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL dbase 7.0.0 | `database` ist nun vom Typ resource statt int.

### Beispiele

Beispiel #1 Aktualisieren eines Datensatzes in der Datenbank

    <?php

    // im lesen-schreiben-Modus öffnen
    $db = dbase_open('/tmp/test.dbf', 2);

    if ($db) {
      // den alten Datensatz holen
      $datensatz = dbase_get_record_with_names($db, 1);

      // den Eintrag 'deleted' entfernen
      unset($datensatz['deleted']);

      // das Datumsfeld mit dem aktuellen Zeitstempel aktualisieren
      $datensatz['Datum'] = date('Ymd');

      // wandle den Datensatz in ein indexiertes Array um
      $datensatz = array_values($datensatz);

      // den Datensatz ersetzen
      dbase_replace_record($db, $datensatz, 1);
      dbase_close($db);
    }

    ?>

### Anmerkungen

> Hinweis:

> Boolesche Felder ergeben einen int-Elementwert (`0` oder `1`), wenn sie per dbase_get_record() oder dbase_get_record_with_names() gelesen werden. Werden sie zurückgeschrieben, wird der Wert zu `0`, so dass darauf geachtet werden muss, den Wert ordnungsgemäß anzupassen.

### Siehe auch

- dbase_add_record() - Hängt einen Datensatz an eine Datenbank an
- dbase_delete_record() - Markiert einen Datensatz als gelöscht

## Inhaltsverzeichnis

- dbase_add_record — Hängt einen Datensatz an eine Datenbank an
- dbase_close — Schließt eine Datenbank
- dbase_create — Erzeugt eine Datenbank
- dbase_delete_record — Markiert einen Datensatz als gelöscht
- dbase_get_header_info — Liefert Informationen des Dateikopfs einer Datenbank
- dbase_get_record — Liefert einen Datensatz aus einer Datenbank als indiziertes Array
- dbase_get_record_with_names — Liefert einen Datensatz aus einer Datenbank als assoziatives Array
- dbase_numfields — Liefert die Anzahl der Felder einer Datenbank
- dbase_numrecords — Liefert die Anzahl der Datensätze einer Datenbank
- dbase_open — Öffnet eine Datenbank
- dbase_pack — Entfernt die als gelöscht markierten Datensätze aus einer Datenbank
- dbase_replace_record — Ersetzt einen Datensatz in einer Datenbank

- Installation/Konfiguration
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- dBase Funktionen
  - dbase_add_record — Hängt einen Datensatz an eine Datenbank an
  - dbase_close — Schließt eine Datenbank
  - dbase_create — Erzeugt eine Datenbank
  - dbase_delete_record — Markiert einen Datensatz als gelöscht
  - dbase_get_header_info — Liefert Informationen des Dateikopfs einer Datenbank
  - dbase_get_record — Liefert einen Datensatz aus einer Datenbank als indiziertes Array
  - dbase_get_record_with_names — Liefert einen Datensatz aus einer Datenbank als assoziatives Array
  - dbase_numfields — Liefert die Anzahl der Felder einer Datenbank
  - dbase_numrecords — Liefert die Anzahl der Datensätze einer Datenbank
  - dbase_open — Öffnet eine Datenbank
  - dbase_pack — Entfernt die als gelöscht markierten Datensätze aus einer Datenbank
  - dbase_replace_record — Ersetzt einen Datensatz in einer Datenbank

# Firebird/InterBase

# Einführung

Warnung

Diese Erweiterung wird nicht mehr gepflegt und gilt als tot. Der Quellcode für diese Erweiterung ist jedoch weiterhin im PECL-GIT verfügbar: » https://github.com/php/pecl-database-interbase.

Firebird is a relational database offering many ISO SQL-2003 features that runs on Linux, Windows, and a variety of Unix platforms. Firebird offers excellent concurrency, high performance, and powerful language support for stored procedures and triggers. It has been used in production systems, under a variety of names since 1981.

InterBase is the name of the closed-source variant of this RDBMS that was developed by Embarcadero/Inprise. More information about InterBase is available at » http://www.embarcadero.com/products/interbase.

Firebird is a commercially independent project (fundation) of C++ programmers, technical advisors and supporters developing and enhancing a multi-platform relational database management system based on the source code released by Inprise Corp (now known as Embarcadero) under the InterBase Public License v.1.0 on 25 July, 2000. More information about Firebird is available at » http://www.firebirdsql.org/.

> Hinweis: Diese Erweiterung wurde ins » PECL-Repositorium verschoben und ist nicht mehr Teil von PHP ab PHP 7.4.0 This extension supports InterBase versions 6 and up and Firebird version 2.0 and up.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Laufzeit-Konfiguration

## Installation

Diese Erweiterung wurde ins » PECL-Repositorium verschoben und ist nicht mehr Teil von PHP ab PHP 7.4.0

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://github.com/FirebirdSQL/php-firebird.

To enable Firebird/InterBase support configure PHP --with-interbase[=DIR], where DIR is the Firebird/InterBase base install directory, which defaults to /usr.

> Hinweis: Note to Win32/Win64 Users
> Diese Erweiterung benötigt DLL-Dateien. die für Windows verfügbar seien müssen. Der FAQ-Eintrag " Wie füge ich unter Windows PATH mein PHP-Verzeichnis hinzu?" gibt hierzu weitere Informationen. Obwohl ein einfaches Kopieren der DLL-Dateien vom PHP-Verzeichnis in den Windows-Systemordner auch funktioniert (weil der Systemordner immer im PATH enthalten ist), ist dieses Vorgehen nicht empfehlenswert. Diese Erweiterung benötigt die folgenden Dateien im PATH: fbclient.dll,gds32.dll

> If you installed the Firebird/InterBase database server on the same machine PHP is running on, you will have this DLL already and fbclient.dll,gds32.dll (gds32.dll is generated from the installer for legacy applications) will already be in the PATH.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

InterBase configuration options
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
ibase.allow_persistent | "1" | `INI_SYSTEM` |
ibase.max_persistent | "-1" | `INI_SYSTEM` |
ibase.max_links | "-1" | `INI_SYSTEM` |
ibase.default_db | NULL | `INI_SYSTEM` |
ibase.default_user | NULL | `INI_ALL` |
ibase.default_password | NULL | `INI_ALL` |
ibase.default_charset | NULL | `INI_ALL` |
ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | `INI_ALL` |
ibase.dateformat | "%Y-%m-%d" | `INI_ALL` |
ibase.timeformat | "%H:%M:%S" | `INI_ALL` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`ibase.allow_persistent` bool
  Whether to allow persistent connections to Firebird/InterBase.
`ibase.max_persistent` int
  The maximum number of persistent Firebird/InterBase connections per process. New connections created with ibase_pconnect() will be non-persistent if this number would be exceeded.
`ibase.max_links` int
  The maximum number of Firebird/InterBase connections per process, including persistent connections.
`ibase.default_db` string
  The default database to connect to when ibase_[p]connect() is called without specifying a database name. If this value is set and SQL safe mode is enabled, no other connections than to this database will be allowed.
`ibase.default_user` string
  The user name to use when connecting to a database if no user name is specified.
`ibase.default_password` string
  The password to use when connecting to a database if no password is specified.
`ibase.default_charset` string
  The character set to use when connecting to a database if no character set is specified.
`ibase.timestampformat` string
`ibase.dateformat` string
`ibase.timeformat` string
  These directives are used to set the date and time formats that are used when returning dates and times from a result set, or when binding arguments to date and time parameters.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

The following constants can be passed to ibase_trans() to specify transaction behaviour.

Firebird/InterBase transaction flags
Constant | Description
--- | ---
IBASE_DEFAULT | The default transaction settings are to be used. This default is determined by the client library, which defines it as IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT in most cases.
IBASE_READ | Starts a read-only transaction.
IBASE_WRITE | Starts a read-write transaction.
IBASE_CONSISTENCY | Starts a transaction with the isolation level set to 'consistency', which means the transaction cannot read from tables that are being modified by other concurrent transactions.
IBASE_CONCURRENCY | Starts a transaction with the isolation level set to 'concurrency' (or 'snapshot'), which means the transaction has access to all tables, but cannot see changes that were committed by other transactions after the transaction was started.
IBASE_COMMITTED | Starts a transaction with the isolation level set to 'read committed'. This flag should be combined with either `IBASE_REC_VERSION` or `IBASE_REC_NO_VERSION`. This isolation level allows access to changes that were committed after the transaction was started. If `IBASE_REC_NO_VERSION` was specified, only the latest version of a row can be read. If `IBASE_REC_VERSION` was specified, a row can even be read when a modification to it is pending in a concurrent transaction.
IBASE_WAIT | Indicated that a transaction should wait and retry when a conflict occurs.
IBASE_NOWAIT | Indicated that a transaction should fail immediately when a conflict occurs.

The following constants can be passed to ibase_fetch_row(), ibase_fetch_assoc() or ibase_fetch_object() to specify fetch behaviour.

Firebird/InterBase fetch flags
Constant | Description
--- | ---
IBASE_FETCH_BLOBS | Also available as `IBASE_TEXT`for backward compatibility. Causes BLOB contents to be fetched inline, instead of being fetched as BLOB identifiers.
IBASE_FETCH_ARRAYS | Causes arrays to be fetched inline. Otherwise, array identifiers are returned. Array identifiers can only be used as arguments to INSERT operations, as no functions to handle array identifiers are currently available.
IBASE_UNIXTIME | Causes date and time fields not to be returned as strings, but as UNIX timestamps (the number of seconds since the epoch, which is 1-Jan-1970 0:00 UTC). Might be problematic if used with dates before 1970 on some systems.

The following constants are used to pass requests and options to the service API functions (ibase_server_info(), ibase_db_info(), ibase_backup(), ibase_restore() and ibase_maintain_db()). Please refer to the Firebird/InterBase manuals for the meaning of these options.

`IBASE_BKP_IGNORE_CHECKSUMS`
  Options to ibase_backup()
`IBASE_BKP_IGNORE_LIMBO`
  Options to ibase_backup()
`IBASE_BKP_METADATA_ONLY`
  Options to ibase_backup()
`IBASE_BKP_NO_GARBAGE_COLLECT`
  Options to ibase_backup()
`IBASE_BKP_OLD_DESCRIPTIONS`
  Options to ibase_backup()
`IBASE_BKP_NON_TRANSPORTABLE`
  Options to ibase_backup()
`IBASE_BKP_CONVERT`
  Options to ibase_backup()
`IBASE_RES_DEACTIVATE_IDX`
  Options to ibase_restore()
`IBASE_RES_NO_SHADOW`
  Options to ibase_restore()
`IBASE_RES_NO_VALIDITY`
  Options to ibase_restore()
`IBASE_RES_ONE_AT_A_TIME`
  Options to ibase_restore()
`IBASE_RES_REPLACE`
`IBASE_RES_CREATE`
  Options to ibase_restore()
`IBASE_RES_USE_ALL_SPACE`
  Options to ibase_restore()
`IBASE_PRP_PAGE_BUFFERS`
`IBASE_PRP_SWEEP_INTERVAL`
`IBASE_PRP_SHUTDOWN_DB`
`IBASE_PRP_DENY_NEW_TRANSACTIONS`
`IBASE_PRP_DENY_NEW_ATTACHMENTS`
`IBASE_PRP_RESERVE_SPACE`
`IBASE_PRP_RES_USE_FULL`
`IBASE_PRP_RES`
`IBASE_PRP_WRITE_MODE`
`IBASE_PRP_WM_ASYNC`
`IBASE_PRP_WM_SYNC`
`IBASE_PRP_ACCESS_MODE`
`IBASE_PRP_AM_READONLY`
`IBASE_PRP_AM_READWRITE`
`IBASE_PRP_SET_SQL_DIALECT`
`IBASE_PRP_ACTIVATE`
`IBASE_PRP_DB_ONLINE`
`IBASE_RPR_CHECK_DB`
`IBASE_RPR_IGNORE_CHECKSUM`
`IBASE_RPR_KILL_SHADOWS`
`IBASE_RPR_MEND_DB`
`IBASE_RPR_VALIDATE_DB`
`IBASE_RPR_FULL`
`IBASE_RPR_SWEEP_DB`
  Options to ibase_maintain_db()
`IBASE_STS_DATA_PAGES`
`IBASE_STS_DB_LOG`
`IBASE_STS_HDR_PAGES`
`IBASE_STS_IDX_PAGES`
`IBASE_STS_SYS_RELATIONS`
  Options to ibase_db_info()
`IBASE_SVC_SERVER_VERSION`
  Options to ibase_server_info()
`IBASE_SVC_IMPLEMENTATION`
  Options to ibase_server_info()
`IBASE_SVC_GET_ENV`
  Options to ibase_server_info()
`IBASE_SVC_GET_ENV_LOCK`
`IBASE_SVC_GET_ENV_MSG`
`IBASE_SVC_USER_DBPATH`
`IBASE_SVC_SVR_DB_INFO`
`IBASE_SVC_GET_USERS`
  Options to ibase_server_info()

# Firebird/InterBase Funktionen

# fbird_add_user

(PHP 5, PHP 7 < 7.4.0)

fbird_add_user — Alias von ibase_add_user()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_add_user().

### Siehe auch

- fbird_modify_user() - Alias von ibase_modify_user
- fbird_delete_user() - Alias von ibase_delete_user

# fbird_affected_rows

(PHP 5, PHP 7 < 7.4.0)

fbird_affected_rows — Alias von ibase_affected_rows()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_affected_rows().

### Siehe auch

- fbird_query() - Alias von ibase_query
- fbird_execute() - Alias von ibase_execute

# fbird_backup

(PHP 5, PHP 7 < 7.4.0)

fbird_backup — Alias von ibase_backup()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_backup().

# fbird_blob_add

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_add — Alias von ibase_blob_add()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_blob_add().

### Siehe auch

- fbird_blob_cancel() - Cancel creating blob
- fbird_blob_close() - Alias von ibase_blob_close
- fbird_blob_create() - Alias von ibase_blob_create
- fbird_blob_import() - Alias von ibase_blob_import

# fbird_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_cancel — Cancel creating blob

### Beschreibung

function fbird_blob_cancel(resource `$blob_handle`): bool

This function will discard a BLOB if it has not yet been closed by fbird_blob_close().

### Parameter-Liste

`blob_handle`
  A BLOB handle opened with fbird_blob_create().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fbird_blob_close() - Alias von ibase_blob_close
- fbird_blob_create() - Alias von ibase_blob_create
- fbird_blob_import() - Alias von ibase_blob_import

# fbird_blob_close

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_close — Alias von ibase_blob_close()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_blob_close().

### Siehe auch

- fbird_blob_create() - Alias von ibase_blob_create
- fbird_blob_cancel() - Cancel creating blob
- fbird_blob_open() - Alias von ibase_blob_open
- fbird_blob_import() - Alias von ibase_blob_import

# fbird_blob_create

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_create — Alias von ibase_blob_create()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_blob_create().

### Siehe auch

- fbird_blob_add() - Alias von ibase_blob_add
- fbird_blob_cancel() - Cancel creating blob
- fbird_blob_close() - Alias von ibase_blob_close
- fbird_blob_import() - Alias von ibase_blob_import

# fbird_blob_echo

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_echo — Alias von ibase_blob_echo()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_blob_echo().

### Siehe auch

- fbird_blob_open() - Alias von ibase_blob_open
- fbird_blob_close() - Alias von ibase_blob_close
- fbird_blob_get() - Alias von ibase_blob_get

# fbird_blob_get

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_get — Alias von ibase_blob_get()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_blob_get().

### Siehe auch

- fbird_blob_open() - Alias von ibase_blob_open
- fbird_blob_close() - Alias von ibase_blob_close
- fbird_blob_echo() - Alias von ibase_blob_echo

# fbird_blob_import

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_import — Alias von ibase_blob_import()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_blob_import().

### Siehe auch

- fbird_blob_add() - Alias von ibase_blob_add
- fbird_blob_cancel() - Cancel creating blob
- fbird_blob_close() - Alias von ibase_blob_close
- fbird_blob_create() - Alias von ibase_blob_create

# fbird_blob_info

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_info — Alias von ibase_blob_info()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_blob_info().

# fbird_blob_open

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_open — Alias von ibase_blob_open()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_blob_open().

### Siehe auch

- fbird_blob_close() - Alias von ibase_blob_close
- fbird_blob_echo() - Alias von ibase_blob_echo
- fbird_blob_get() - Alias von ibase_blob_get

# fbird_close

(PHP 5, PHP 7 < 7.4.0)

fbird_close — Alias von ibase_close()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_close().

### Siehe auch

- fbird_connect() - Alias von ibase_connect
- fbird_pconnect() - Alias von ibase_pconnect

# fbird_commit

(PHP 5, PHP 7 < 7.4.0)

fbird_commit — Alias von ibase_commit()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_commit().

# fbird_commit_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_commit_ret — Alias von ibase_commit_ret()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_commit_ret().

# fbird_connect

(PHP 5, PHP 7 < 7.4.0)

fbird_connect — Alias von ibase_connect()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_connect().

### Siehe auch

- fbird_pconnect() - Alias von ibase_pconnect
- fbird_close() - Alias von ibase_close

# fbird_db_info

(PHP 5, PHP 7 < 7.4.0)

fbird_db_info — Alias von ibase_db_info()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_db_info().

# fbird_delete_user

(PHP 5, PHP 7 < 7.4.0)

fbird_delete_user — Alias von ibase_delete_user()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_delete_user().

### Siehe auch

- fbird_add_user() - Alias von ibase_add_user
- fbird_modify_user() - Alias von ibase_modify_user

# fbird_drop_db

(PHP 5, PHP 7 < 7.4.0)

fbird_drop_db — Alias von ibase_drop_db()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_drop_db().

### Siehe auch

- fbird_connect() - Alias von ibase_connect
- fbird_pconnect() - Alias von ibase_pconnect

# fbird_errcode

(PHP 5, PHP 7 < 7.4.0)

fbird_errcode — Alias von ibase_errcode()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_errcode().

### Siehe auch

- fbird_errmsg() - Alias von ibase_errmsg

# fbird_errmsg

(PHP 5, PHP 7 < 7.4.0)

fbird_errmsg — Alias von ibase_errmsg()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_errmsg().

### Siehe auch

- fbird_errcode() - Alias von ibase_errcode

# fbird_execute

(PHP 5, PHP 7 < 7.4.0)

fbird_execute — Alias von ibase_execute()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_execute().

### Siehe auch

- fbird_query() - Alias von ibase_query

# fbird_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_assoc — Alias von ibase_fetch_assoc()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_fetch_assoc().

### Siehe auch

- fbird_fetch_row() - Alias von ibase_fetch_row
- fbird_fetch_object() - Alias von ibase_fetch_object

# fbird_fetch_object

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_object — Alias von ibase_fetch_object()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_fetch_object().

### Siehe auch

- fbird_fetch_row() - Alias von ibase_fetch_row
- fbird_fetch_assoc() - Alias von ibase_fetch_assoc

# fbird_fetch_row

(PHP 5, PHP 7 < 7.4.0)

fbird_fetch_row — Alias von ibase_fetch_row()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_fetch_row().

### Siehe auch

- fbird_fetch_assoc() - Alias von ibase_fetch_assoc
- fbird_fetch_object() - Alias von ibase_fetch_object

# fbird_field_info

(PHP 5, PHP 7 < 7.4.0)

fbird_field_info — Alias von ibase_field_info()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_field_info().

### Siehe auch

- fbird_num_fields() - Alias von ibase_num_fields

# fbird_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_free_event_handler — Alias von ibase_free_event_handler()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_free_event_handler().

### Siehe auch

- fbird_set_event_handler() - Alias von ibase_set_event_handler

# fbird_free_query

(PHP 5, PHP 7 < 7.4.0)

fbird_free_query — Alias von ibase_free_query()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_free_query().

# fbird_free_result

(PHP 5, PHP 7 < 7.4.0)

fbird_free_result — Alias von ibase_free_result()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_free_result().

# fbird_gen_id

(PHP 5, PHP 7 < 7.4.0)

fbird_gen_id — Alias von ibase_gen_id()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_gen_id().

# fbird_maintain_db

(PHP 5, PHP 7 < 7.4.0)

fbird_maintain_db — Alias von ibase_maintain_db()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_maintain_db().

# fbird_modify_user

(PHP 5, PHP 7 < 7.4.0)

fbird_modify_user — Alias von ibase_modify_user()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_modify_user().

### Siehe auch

- fbird_add_user() - Alias von ibase_add_user
- fbird_delete_user() - Alias von ibase_delete_user

# fbird_name_result

(PHP 5, PHP 7 < 7.4.0)

fbird_name_result — Alias von ibase_name_result()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_name_result().

### Siehe auch

- fbird_prepare() - Alias von ibase_prepare
- fbird_execute() - Alias von ibase_execute

# fbird_num_fields

(PHP 5, PHP 7 < 7.4.0)

fbird_num_fields — Alias von ibase_num_fields()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_num_fields().

### Siehe auch

- fbird_field_info() - Alias von ibase_field_info

# fbird_num_params

(PHP 5, PHP 7 < 7.4.0)

fbird_num_params — Alias von ibase_num_params()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_num_params().

### Siehe auch

- fbird_prepare() - Alias von ibase_prepare
- fbird_param_info() - Alias von ibase_param_info

# fbird_param_info

(PHP 5, PHP 7 < 7.4.0)

fbird_param_info — Alias von ibase_param_info()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_param_info().

### Siehe auch

- fbird_field_info() - Alias von ibase_field_info
- fbird_num_params() - Alias von ibase_num_params

# fbird_pconnect

(PHP 5, PHP 7 < 7.4.0)

fbird_pconnect — Alias von ibase_pconnect()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_pconnect().

### Siehe auch

- fbird_close() - Alias von ibase_close
- fbird_connect() - Alias von ibase_connect

# fbird_prepare

(PHP 5, PHP 7 < 7.4.0)

fbird_prepare — Alias von ibase_prepare()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_prepare().

# fbird_query

(PHP 5, PHP 7 < 7.4.0)

fbird_query — Alias von ibase_query()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_query().

### Siehe auch

- fbird_errmsg() - Alias von ibase_errmsg
- fbird_fetch_row() - Alias von ibase_fetch_row
- fbird_fetch_object() - Alias von ibase_fetch_object
- fbird_free_result() - Alias von ibase_free_result

# fbird_restore

(PHP 5, PHP 7 < 7.4.0)

fbird_restore — Alias von ibase_restore()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_restore().

# fbird_rollback

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback — Alias von ibase_rollback()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_rollback().

# fbird_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback_ret — Alias von ibase_rollback_ret()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_rollback_ret().

# fbird_server_info

(PHP 5, PHP 7 < 7.4.0)

fbird_server_info — Alias von ibase_server_info()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_server_info().

# fbird_service_attach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_attach — Alias von ibase_service_attach()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_service_attach().

# fbird_service_detach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_detach — Alias von ibase_service_detach()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_service_detach().

# fbird_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

fbird_set_event_handler — Alias von ibase_set_event_handler()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_set_event_handler().

### Siehe auch

- fbird_free_event_handler() - Alias von ibase_free_event_handler
- fbird_wait_event() - Alias von ibase_wait_event

# fbird_trans

(PHP 5, PHP 7 < 7.4.0)

fbird_trans — Alias von ibase_trans()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_trans().

# fbird_wait_event

(PHP 5, PHP 7 < 7.4.0)

fbird_wait_event — Alias von ibase_wait_event()

### Beschreibung

Diese Funktion ist ein Alias für: ibase_wait_event().

### Siehe auch

- fbird_set_event_handler() - Alias von ibase_set_event_handler
- fbird_free_event_handler() - Alias von ibase_free_event_handler

# ibase_add_user

(PHP 5, PHP 7 < 7.4.0)

ibase_add_user — Fügt einen Benutzer zu einer Security-Datenbank hinzu

### Beschreibung

function ibase_add_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Parameter-Liste

`service_handle`
  Das Handle für den Datenbankserverdienst.
`user_name`
  Der Anmeldename des neuen Datenbankbenutzers.
`password`
  Das Kennwort des neuen Benutzers.
`first_name`
  Der Vorname des neuen Benutzers.
`middle_name`
  Der zweite Vorname des neuen Datenbankbenutzers.
`last_name`
  Der Nachname des neuen Datenbankbenutzers.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_modify_user() - Ändert den Benutzer einer Security-Datenbank
- ibase_delete_user() - Löscht einen Benutzer aus einer Security-Datenbank

# ibase_affected_rows

(PHP 5, PHP 7 < 7.4.0)

ibase_affected_rows — Gibt die Anzahl der Zeilen zurück, die von der vorherigen Abfrage betroffen waren

### Beschreibung

function ibase_affected_rows(resource `$link_identifier` = ?): int

Diese Funktion gibt die Anzahl der Zeilen zurück, die von der vorherigen Abfrage (INSERT, UPDATE oder DELETE) betroffen waren, welche im angegebenen Transaktionskontext ausgeführt wurde.

### Parameter-Liste

`link_identifier`
  Ein Transaktionskontext. Wenn `link_identifier` eine Verbindungsressource ist, wird die Standardtransaktion verwendet.

### Rückgabewerte

Gibt die Anzahl der Zeilen als Ganzzahl zurück.

### Siehe auch

- ibase_query() - Führt eine Abfrage auf einer InterBase Datenbank aus
- ibase_execute() - Ausführen einer vorbereiteten Abfrage

# ibase_backup

(PHP 5, PHP 7 < 7.4.0)

ibase_backup — Initiiert eine Sicherungsaufgabe im Service Manager und springt sofort zurück

### Beschreibung

function ibase_backup(
resource `$service_handle`,
string `$source_db`,
string `$dest_file`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Diese Funktion übergibt die Argumente an den (entfernten) Datenbankserver. Dort startet sie einen neuen Sicherungsvorgang. Deshalb erhalten Sie keine Antwort.

### Parameter-Liste

`service_handle`
  Eine zuvor geöffnete Verbindung zum Datenbankserver.
`source_db`
  Der absolute Dateipfad zur Datenbank auf dem Datenbankserver. Sie können auch einen Datenbankalias verwenden.
`dest_file`
  Der Pfad zur Sicherungsdatei auf dem Datenbankserver.
`options`

  Zusätzliche Optionen, die zur Sicherung an den Datenbankserver übergeben werden. Der Parameter `options` darf eine Kombination folgender Konstanten sein: `IBASE_BKP_IGNORE_CHECKSUMS`, `IBASE_BKP_IGNORE_LIMBO`, `IBASE_BKP_METADATA_ONLY`, `IBASE_BKP_NO_GARBAGE_COLLECT`, `IBASE_BKP_OLD_DESCRIPTIONS`, `IBASE_BKP_NON_TRANSPORTABLE` or `IBASE_BKP_CONVERT`. Vgl. auch den Abschnitt Vordefinierte Konstanten.

`verbose`
  Da der Sicherungsvorgang auf dem Datenbankserver ausgeführt wird, haben Sie keine Chance, die Ausgabe abzurufen. Dieses Argument ist sinnlos.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Da der Sicherungsvorgang auf dem (Remote-) Server durchgeführt wird, übergibt diese Funktion nur die Argumente an diesen. Solange die Argumente gültig sind, werden Sie niemals `false` zurückbekommen.

### Beispiele

Beispiel #1 ibase_backup()-Beispiel

    <?php

    // Mit Datenbankserver mittels IP-Adresse und Port verbinden
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Sicherungsvorgang auf DB-Server starten
    // Sichern der Mitarbeiterdatenbank unter Verwendung des vollständigen Pfads nach /srv/backup/employees.fbk
    // Keine speziellen Paramter verwenden
    ibase_backup($service, '/srv/firebird/employees.fdb', '/srv/backup/employees.fbk');

    // Verbindung wieder freigeben
    ibase_service_detach ($service);
    ?>

Beispiel #2 ibase_backup()-Beispiel mit Argumenten

    <?php

    // Stelle eine Verbindung zum Datenbankserver mit Namen und Standardport her
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Sicherungsvorgang auf Datenbankserver starten
    // Sichern der Mitarbeiterdatenbank mittels Alias nach /srv/backup/employees.fbk.
    // Nur die Metadaten sichern. Kein transportables Backup erstellen.
    ibase_backup($service, 'employees.fdb', '/srv/backup/employees.fbk', IBASE_BKP_METADATA_ONLY | IBASE_BKP_NON_TRANSPORTABLE);

    // Verbindung wieder freigeben
    ibase_service_detach ($service);
    ?>

### Siehe auch

- ibase_restore() - Leitet eine Wiederherstellungsaufgabe im Service Manager ein und kehrt sofort zurück

# ibase_blob_add

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_add — Fügt Daten in ein neues BLOB ein

### Beschreibung

function ibase_blob_add(resource `$blob_handle`, string `$data`): void

ibase_blob_add() fügt Daten zu einem mittels ibase_blob_create() erstellten BLOB hinzu.

### Parameter-Liste

`blob_handle`
  Ein BLOB-Handle, das mit ibase_blob_create() geöffnet wurde.
`data`
  Die einzufügenden Daten

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- ibase_blob_cancel() - Bricht die Erstellung eines neuen BLOBs ab
- ibase_blob_close() - BLOB schließen
- ibase_blob_create() - Erstellt ein neues BLOB zum Hinzufügen von Daten
- ibase_blob_import() - Erstellt ein BLOB, kopiert die Dateidaten hinein und schließt es

# ibase_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_cancel — Bricht die Erstellung eines neuen BLOBs ab

### Beschreibung

function ibase_blob_cancel(resource `$blob_handle`): bool

Diese Funktion löscht ein BLOB, wenn es noch nicht mittels ibase_blob_close() geschlossen wurde.

### Parameter-Liste

`blob_handle`
  Ein BLOB-Handle, das mit ibase_blob_create() geöffnet wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_blob_close() - BLOB schließen
- ibase_blob_create() - Erstellt ein neues BLOB zum Hinzufügen von Daten
- ibase_blob_import() - Erstellt ein BLOB, kopiert die Dateidaten hinein und schließt es

# ibase_blob_close

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_close — BLOB schließen

### Beschreibung

function ibase_blob_close(resource `$blob_handle`): mixed

Diese Funktion schließt einen BLOB, das entweder mittels ibase_blob_open() zum Lesen geöffnet wurde oder mit ibase_blob_create() zum Schreiben.

### Parameter-Liste

`blob_handle`
  Ein BLOB-Handle, das mit ibase_blob_create() oder ibase_blob_open() geöffnet wurde.

### Rückgabewerte

Wenn das BLOB gelesen wurde, gibt diese Funktion `true` zurück. Wenn das BLOB erfolgreich geschrieben wurde, gibt diese Funktion eine Zeichenfolge zurück, die die BLOB-ID enthält, die ihr von der Datenbank zugewiesen wurde. Bei einem Fehler gibt diese Funktion `false` zurück.

### Siehe auch

- ibase_blob_cancel() - Bricht die Erstellung eines neuen BLOBs ab
- ibase_blob_open() - Öffnet BLOB zum Abrufen von Datenteilen

# ibase_blob_create

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_create — Erstellt ein neues BLOB zum Hinzufügen von Daten

### Beschreibung

function ibase_blob_create(resource `$link_identifier` = `null`): resource|false

ibase_blob_create() erstellt ein neues BLOB, um dies mit Daten zu füllen.

### Parameter-Liste

`link_identifier`
  Eine InterBase-Verbindungskennung. Falls nicht angegeben, wird die zuletzt geöffnete Verbindung angenommen.

### Rückgabewerte

Gibt ein BLOB-Handle zur späteren Verwendung mit ibase_blob_add() zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_blob_add() - Fügt Daten in ein neues BLOB ein
- ibase_blob_cancel() - Bricht die Erstellung eines neuen BLOBs ab
- ibase_blob_close() - BLOB schließen
- ibase_blob_import() - Erstellt ein BLOB, kopiert die Dateidaten hinein und schließt es

# ibase_blob_echo

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_echo — Ausgabe von BLOB-Inhalten an den Browser

### Beschreibung

function ibase_blob_echo(string `$blob_id`): bool
function ibase_blob_echo(resource `$link_identifier`, string `$blob_id`): bool

Diese Funktion öffnet ein BLOB zum Lesen und sendet seinen Inhalt direkt an die Standardausgabe (in den meisten Fällen den Browser).

### Parameter-Liste

`link_identifier`
  Eine InterBase/Firebird-Verbindungskennung. Wenn nicht angegeben, wird der zuletzt geöffnete Link angenommen.
`blob_id`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_blob_open() - Öffnet BLOB zum Abrufen von Datenteilen
- ibase_blob_close() - BLOB schließen
- ibase_blob_get() - Holt sich len Bytes Daten aus dem offenen BLOB

# ibase_blob_get

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_get — Holt sich len Bytes Daten aus dem offenen BLOB

### Beschreibung

function ibase_blob_get(resource `$blob_handle`, int `$len`): string

Diese Funktion gibt höchstens `len` Bytes von einem BLOB zurück, das zum Lesen mittels ibase_blob_open() geöffnet wurde.

> Hinweis: Aus einem BLOB, das zum Schreiben mittels ibase_blob_create() geöffnet wurde, kann nicht gelesen werden.

### Parameter-Liste

`blob_handle`
  Ein BLOB-Handle, das mit ibase_blob_open() geöffnet wurde.
`len`
  Größe der zurückgegebenen Daten.

### Rückgabewerte

Gibt maximal `len` Bytes aus dem BLOB zurück, oder `false` bei einem Fehler.

### Beispiele

Beispiel #1 ibase_blob_get()-Beispiel

    <?php
    $result    = ibase_query("SELECT blob_value FROM table");
    $data      = ibase_fetch_object($result);
    $blob_data = ibase_blob_info($data->BLOB_VALUE);
    $blob_hndl = ibase_blob_open($data->BLOB_VALUE);
    echo         ibase_blob_get($blob_hndl, $blob_data[0]);
    ?>

Während dieses Beispiel nicht viel mehr kann als ein 'ibase_blob_echo($data->BLOB_VALUE)', zeigt es Ihnen, wie Sie Informationen in eine $Variable bekommen, die Sie nach Belieben manipulieren können.

### Siehe auch

- ibase_blob_open() - Öffnet BLOB zum Abrufen von Datenteilen
- ibase_blob_close() - BLOB schließen
- ibase_blob_echo() - Ausgabe von BLOB-Inhalten an den Browser

# ibase_blob_import

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_import — Erstellt ein BLOB, kopiert die Dateidaten hinein und schließt es

### Beschreibung

function ibase_blob_import(resource `$link_identifier`, resource `$file_handle`): string
function ibase_blob_import(resource `$file_handle`): string

Diese Funktion erstellt ein BLOB, liest eine gesamte Datei ein, schließt sie und gibt die zugewiesene BLOB-ID zurück.

### Parameter-Liste

`link_identifier`
  Eine InterBase/Firebird-Verbindungskennung. Wenn nicht angegeben, wird der zuletzt geöffnete Link angenommen.
`file_handle`
  Das Datei-Handle ist ein Handle, das mittels fopen() erstellt wurde.

### Rückgabewerte

Gibt die BLOB-ID im Erfolgsfall zurück, oder `false` im Fehlerfall

### Beispiele

Beispiel #1 ibase_blob_import()-Beispiel

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $filename = '/tmp/bar';

    $fd = fopen($filename, 'r');
    if ($fd) {

        $blob = ibase_blob_import($dbh, $fd);
        fclose($fd);

        if (!is_string($blob)) {
            // Import fehlgeschlagen
        } else {
            $query = "INSERT INTO foo (name, data) VALUES ('$filename', ?)";
            $prepared = ibase_prepare($dbh, $query);
            if (!ibase_execute($prepared, $blob)) {
                // Einfügen der Daten fehlgeschlagen
            }
        }
    } else {
        // Öffnen der Datei nicht möglich
    }
    ?>

### Siehe auch

- ibase_blob_add() - Fügt Daten in ein neues BLOB ein
- ibase_blob_cancel() - Bricht die Erstellung eines neuen BLOBs ab
- ibase_blob_close() - BLOB schließen
- ibase_blob_create() - Erstellt ein neues BLOB zum Hinzufügen von Daten

# ibase_blob_info

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_info — Gibt die Blob-Länge und andere nützliche Informationen zurück

### Beschreibung

function ibase_blob_info(resource `$link_identifier`, string `$blob_id`): array
function ibase_blob_info(string `$blob_id`): array

Gibt die Blob-Länge und andere nützliche Informationen zurück.

### Parameter-Liste

`link_identifier`
  Eine InterBase/Firebird-Verbindungskennung. Wenn nicht angegeben, wird der zuletzt geöffnete Link angenommen.
`blob_id`
  Eine BLOB-ID.

### Rückgabewerte

Gibt ein Array mit Informationen zu einem BLOB zurück. Die zurückgegebenen Informationen bestehen aus der Länge des BLOBs, der Anzahl der darin enthaltenen Segmente, der Größe des größten Segments und, ob es sich um ein Stream-BLOB oder ein segmentiertes BLOB handelt.

# ibase_blob_open

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_open — Öffnet BLOB zum Abrufen von Datenteilen

### Beschreibung

function ibase_blob_open(resource `$link_identifier`, string `$blob_id`): resource|false
function ibase_blob_open(string `$blob_id`): resource|false

Öffnet ein existentes BLOB zum Lesen.

### Parameter-Liste

`link_identifier`
  Eine InterBase-Verbindungskennung. Falls nicht angegeben, wird die zuletzt geöffnete Verbindung angenommen.
`blob_id`
  Eine BLOB-ID.

### Rückgabewerte

Gibt ein BLOB-Handle zur späteren Verwendung mit ibase_blob_get() zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_blob_close() - BLOB schließen
- ibase_blob_echo() - Ausgabe von BLOB-Inhalten an den Browser
- ibase_blob_get() - Holt sich len Bytes Daten aus dem offenen BLOB

# ibase_close

(PHP 5, PHP 7 < 7.4.0)

ibase_close — Schließt eine Verbindung zu einer InterBase-Datenbank

### Beschreibung

function ibase_close(resource `$connection_id` = `null`): bool

Beendet die Verbindung zu einer InterBase-DB, deren Verbindungs-ID mit der von ibase_connect() zurück gegebenen ID überein stimmt. Vorgenommene Transaktionen der Verbindung werden übertragen, andere werden zurück genommen.

### Parameter-Liste

`connection_id`
  Eine Interbase Verbindungs-ID, die von ibase_connect() zurückgegeben wurde. Wenn ausgelassen, wird die zuletzt geöffnete Verbindung angenommen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_connect() - Öffnet eine Verbindung zu einer Datenbank
- ibase_pconnect() - Öffnet eine persistente Verbindung zu einer InterBase-Datenbank

# ibase_commit

(PHP 5, PHP 7 < 7.4.0)

ibase_commit — Schreibt eine Transaktion fest

### Beschreibung

function ibase_commit(resource `$link_or_trans_identifier` = `null`): bool

Schreibt eine Transaktion fest.

### Parameter-Liste

`link_or_trans_identifier`
  Wenn diese Funktion ohne Argument aufgerufen wird, wird die Standardtransaktion des Standardlinks festgeschrieben. Wenn das Argument eine Verbindungskennung ist, wird die Standardtransaktion der entsprechenden Verbindung festgeschrieben. Wenn das Argument eine Transaktionskennung ist, wird die entsprechende Transaktion festgeschrieben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ibase_commit_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_commit_ret — Schreibt eine Transaktion fest, ohne diese zu schließen

### Beschreibung

function ibase_commit_ret(resource `$link_or_trans_identifier` = `null`): bool

Commits a transaction without closing it.

### Parameter-Liste

`link_or_trans_identifier`
  Wenn diese Funktion ohne Argument aufgerufen wird, wird die Standardtransaktion des Standardlinks festgeschrieben. Wenn das Argument eine Verbindungskennung ist, wird die Standardtransaktion der entsprechenden Verbindung festgeschrieben. Wenn das Argument eine Transaktionskennung ist, wird die entsprechende Transaktion festgeschrieben. Der Kontext der Transaktion wird beibehalten, so dass Anweisungen, die innerhalb dieser Transaktion ausgeführt werden, nicht ungültig werden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ibase_connect

(PHP 5, PHP 7 < 7.4.0)

ibase_connect — Öffnet eine Verbindung zu einer Datenbank

### Beschreibung

function ibase_connect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Stellt eine Verbindung zu einem Firebird/InterBase-Server her.

Wenn ibase_connect() mit den selben Argumenten erneut aufgerufen wird, wird keine neue Verbindung hergestellt, sondern die ID der bereits geöffneten Verbindung zurück gegeben. Die Verbindung zum InterBase-Server wird am Ende des jeweiligen Skripts automatisch beendet, es sei denn, es wird vorher die Funktion ibase_close() aufgerufen.

### Parameter-Liste

`database`
  Das `database`-Argument muss ein gültiger Pfad zu einer bestehenden Datenbank des Servers sein. Ist der DB-Server nicht lokal, muss ihm - in Abhängigkeit vom benutzten Protokoll - ein 'hostname:' (bei TCP/IP), 'hostname/port:' (TCP/IP für Interbase Server auf benutzerdefiniertem TCP Port), oder '//hostname/' (bei NetBEUI) vorangestellt werden.
`username`
  Der Benutzername. Kann mit der `ibase.default_user` php.ini Direktive festgelegt werden.
`password`
  Das Passwort für `username`. Kann mit der `ibase.default_password` php.ini Direktive festegelegt werden.
`charset`
  `charset` ist der reguläre Zeichensatz der Datenbank.
`buffers`
  Mit `buffers` geben sie die Anzahl der Datenbank-Cache-Buffer (serverseitig) an. Ist der Wert 0 oder nicht angegeben, benutzt der Server seine Default-Werte.
`dialect`
  Mittels `dialect` bestimmen sie den Default-Wert des anzuwendenden SQL-Dialekts für alle Anweisungen während einer Datenbank-Verbindung (default ist der Client-seitig höchst verfügbare Dialekt).
`role`
  Wirkt nur unter InterBase 5 und höher.
`sync`

### Rückgabewerte

Gibt bei Erfolg eine Firebird/Interbase Verbindungs-ID zurück, oder `false` im Fehlerfall.

### Fehler/Exceptions

Erhalten Sie Fehlermeldungen wie "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (diese treten auf, wenn Sie Zeichen mit Akzent verwenden), wenn Sie diese Funktion und ibase_query() verwenden, müssen Sie den Zeichensatz (d.h. ISO8859_1 oder Ihren aktuellen Zeichensatz) einstellen.

### Beispiele

Beispiel #1 ibase_connect()-Beispiel:

    <?php
    $host = 'localhost:/pfad/zu/ihrer.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email, "\n";
    }
    ibase_free_result($sth);
    ibase_close($dbh);
    ?>

### Siehe auch

- ibase_pconnect() - Öffnet eine persistente Verbindung zu einer InterBase-Datenbank
- ibase_close() - Schließt eine Verbindung zu einer InterBase-Datenbank

# ibase_db_info

(PHP 5, PHP 7 < 7.4.0)

ibase_db_info — Fragt statistische Daten über eine Datenbank ab

### Beschreibung

function ibase_db_info(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): string
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# ibase_delete_user

(PHP 5, PHP 7 < 7.4.0)

ibase_delete_user — Löscht einen Benutzer aus einer Security-Datenbank

### Beschreibung

function ibase_delete_user(resource `$service_handle`, string `$user_name`): bool

### Parameter-Liste

`service_handle`
  Das Handle für den Datenbankserverdienst.
`user_name`
  Der Anmeldename des Benutzers, den Sie aus der Datenbank löschen möchten.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_add_user() - Fügt einen Benutzer zu einer Security-Datenbank hinzu
- ibase_modify_user() - Ändert den Benutzer einer Security-Datenbank

# ibase_drop_db

(PHP 5, PHP 7 < 7.4.0)

ibase_drop_db — Löscht eine Datenbank

### Beschreibung

function ibase_drop_db(resource `$connection` = `null`): bool

Diese Funktion löscht eine Datenbank, die entweder mit ibase_connect() oder ibase_pconnect() geöffnet wurde. Die Datenbank wird geschlossen und vom Server gelöscht.

### Parameter-Liste

`connection`
  Eine InterBase/Firebird-Verbindungskennung. Wenn nicht angegeben, wird der zuletzt geöffnete Link angenommen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_connect() - Öffnet eine Verbindung zu einer Datenbank
- ibase_pconnect() - Öffnet eine persistente Verbindung zu einer InterBase-Datenbank

# ibase_errcode

(PHP 5, PHP 7 < 7.4.0)

ibase_errcode — Gibt einen Fehlercode zurück

### Beschreibung

function ibase_errcode(): int

Gibt den Fehlercode zurück, der sich aus dem letzten InterBase/FireBird-Funktionsaufruf ergab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Fehlercode als ganze Zahl zurück oder `false` wenn kein Fehler aufgetreten ist.

### Siehe auch

- ibase_errmsg() - Gibt eine Fehlermeldung zurück

# ibase_errmsg

(PHP 5, PHP 7 < 7.4.0)

ibase_errmsg — Gibt eine Fehlermeldung zurück

### Beschreibung

function ibase_errmsg(): string

Gibt die Fehlermeldung zurück, die sich aus dem letzten InterBase/Firebird-Funktionsaufruf ergab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Fehlermeldung als String zurück oder `false`, wenn kein Fehler auftrat.

### Siehe auch

- ibase_errcode() - Gibt einen Fehlercode zurück

# ibase_execute

(PHP 5, PHP 7 < 7.4.0)

ibase_execute — Ausführen einer vorbereiteten Abfrage

### Beschreibung

function ibase_execute(resource `$query`, mixed `...$values`): resource

Führt eine zuvor per ibase_prepare() vorbereitete Abfrage aus.

Dies ist effizienter als der Gebrauch von ibase_query(), sofern sie mehrere ähnliche Abfragen durchführen wollen, bei denen sich immer nur einige Parameter ändern.

### Parameter-Liste

`query`
  Eine per ibase_prepare() vorbereite InterBase-Abfrage.
`values`

### Rückgabewerte

Erzeugt die Abfrage einen Fehler, wird `false` zurückgegeben. Ist sie erfolgreich und es gibt eine (möglicherweise leere) Ergebnismenge (so wie bei einer SELECT Abfrage), wird eine Ergebniskennung zurückgegeben. War die Abfrage erfolgreich und es gibt keine Ergebnisse, wird `true` zurückgegeben.

> Hinweis: Diese Funktion gibt die Anzahl der Zeilen zurück, die von der Abfrage betroffen waren (falls größer als 0 und für den Anweisungstyp zutreffend). Eine Abfrage, die erfolgreich war, aber keine Zeilen betraf (z. B. ein UPDATE eines nicht existierenden Datensatzes), gibt `true` zurück.

### Beispiele

Beispiel #1 ibase_execute()-Beispiel

    <?php

    $dbh = ibase_connect($host, $username, $password);

    $updates = array(
        1 => 'Erik',
        5 => 'Philipp',
        7 => 'Laurenz'
    );

    $query = ibase_prepare($dbh, "UPDATE FOO SET BAR = ? WHERE BAZ = ?");

    foreach ($updates as $baz => $bar) {
        ibase_execute($query, $bar, $baz);
    }

    ?>

### Siehe auch

- ibase_query() - Führt eine Abfrage auf einer InterBase Datenbank aus

# ibase_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_assoc — Ruft eine Ergebniszeile aus einer Abfrage als assoziatives Array ab

### Beschreibung

function ibase_fetch_assoc(resource `$result`, int `$fetch_flag` = 0): array

Ruft eine Ergebniszeile aus einer Abfrage als assoziatives Array ab.

ibase_fetch_assoc() holt eine Datenzeile aus `result`. Wenn zwei oder mehr Spalten des Ergebnisses den gleichen Feldnamen haben, hat die letzte Spalte Vorrang. Um auf die anderen Spalten mit demselben Namen zuzugreifen, müssen Sie entweder mit ibase_fetch_row() auf das Ergebnis mit numerischen Indizes zugreifen oder in Ihrer Abfrage Aliasnamen verwenden.

### Parameter-Liste

`result`
  Das Ergebnis-Handle.
`fetch_flag`
  `fetch_flag` ist eine Kombination der Konstanten `IBASE_TEXT` und `IBASE_UNIXTIME`. Diese wird mittel OR zusammengeführt. Die Übergabe von `IBASE_TEXT` hat zur Folge, dass diese Funktion BLOB-Inhalte, statt BLOB-IDs zurückgibt. function to return BLOB contents instead of BLOB ids. Die Angabe von `IBASE_UNIXTIME` hat zur Folge, dass diese Funktion Datums- und Zeitwerte als Unix-Zeitstempel zurückgibt, statt formatierter Zeichenfolgen.

### Rückgabewerte

Gibt ein assoziatives Array zurück, das der abgerufenen Zeile entspricht. Nachfolgende Aufrufe geben die nächste Zeile in der Ergebnismenge zurück oder `false` wenn es keine weiteren Zeilen mehr gibt.

### Siehe auch

- ibase_fetch_row() - Ruft eine Zeile aus einer InterBase-Datenbank ab
- ibase_fetch_object() - Liest einen Datensatz einer InterBase-Datenbank als Objekt ein

# ibase_fetch_object

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_object — Liest einen Datensatz einer InterBase-Datenbank als Objekt ein

### Beschreibung

function ibase_fetch_object(resource `$result_id`, int `$fetch_flag` = 0): object

Holt eine Zeile als Pseudo-Objekt von einer gegebenen Ergebniskennung.

Aufeinanderfolgende Aufrufe von ibase_fetch_object() liefern die nächste Zeile der Ergebnismenge.

### Parameter-Liste

`result_id`
  Eine InterBase Ergebniskennung, die durch ibase_query() oder ibase_execute() erhalten wurde.
`fetch_flag`
  `fetch_flag` ist eine Disjunktion der Konstanten `IBASE_TEXT` und `IBASE_UNIXTIME`. Die Angabe von `IBASE_TEXT` führt dazu, dass diese Funktion BLOB-Inhalte statt BLOB-IDs zurückliefert. Die Angabe von `IBASE_UNIXTIME` führt dazu, dass diese Funktion Date/Time-Werte als Unit-Zeitstempel anstelle von formatierten Zeichenketten zurückliefert.

### Rückgabewerte

Gibt ein Objekt mit der Information der nächsten Zeile, oder `false`, wenn es keine weiteren Zeilen gibt, zurück.

### Beispiele

Beispiel #1 ibase_fetch_object() example

    <?php
    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email . "\n";
    }
    ibase_close($dbh);
    ?>

### Siehe auch

- ibase_fetch_row() - Ruft eine Zeile aus einer InterBase-Datenbank ab
- ibase_fetch_assoc() - Ruft eine Ergebniszeile aus einer Abfrage als assoziatives Array ab

# ibase_fetch_row

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_row — Ruft eine Zeile aus einer InterBase-Datenbank ab

### Beschreibung

function ibase_fetch_row(resource `$result_identifier`, int `$fetch_flag` = 0): array

ibase_fetch_row() ruft eine Datenzeile aus der gegebenen Ergebnismenge ab.

Folgende Aufrufe von ibase_fetch_row() geben die nächste Zeile der Ergebnismenge zurück, oder `false`, wenn es keine weiteren Zeilen gibt.

### Parameter-Liste

`result_identifier`
  Eine InterBase Ergebniskennung.
`fetch_flag`
  `fetch_flag` ist eine Oder-Verknüpfung der Konstanten `IBASE_TEXT` und `IBASE_UNIXTIME`. Wird `IBASE_TEXT` angegeben, dann werden BLOB Inhalte anstelle von BLOB-IDs zurückgegeben. Wird `IBASE_UNIXTIME` angegeben, dann werden Datum/Zeit-Werte als Unix Zeitstempel anstelle von formatierten Zeichenketten zurückgegeben.

### Rückgabewerte

Gibt ein Array zurück, das der abgerufenen Zeile entspricht, oder `false`, wenn es keine weiteren Zeilen gibt. Jede Ergebnisspalte wird in einem Array-Offset gespeichert, beginnend mit Offset 0.

### Siehe auch

- ibase_fetch_assoc() - Ruft eine Ergebniszeile aus einer Abfrage als assoziatives Array ab
- ibase_fetch_object() - Liest einen Datensatz einer InterBase-Datenbank als Objekt ein

# ibase_field_info

(PHP 5, PHP 7 < 7.4.0)

ibase_field_info — Ruft Informationen zu einem Feld ab

### Beschreibung

function ibase_field_info(resource `$result`, int `$field_number`): array

Gibt ein Array mit Informationen zu einem Feld zurück, nachdem eine Auswahlabfrage ausgeführt wurde.

### Parameter-Liste

`result`
  Eine InterBase/Firebird-Ergebniskennung.
`field_number`
  Feld-Offset.

### Rückgabewerte

Gibt ein Array mit folgenden Schlüsseln zurück: `name`, `alias`, `relation`, `length` und `type`.

### Beispiele

Beispiel #1 ibase_field_info()-Beispiel

    <?php
    $rs = ibase_query("SELECT * FROM tablename");
    $coln = ibase_num_fields($rs);
    for ($i = 0; $i < $coln; $i++) {
        $col_info = ibase_field_info($rs, $i);
        echo "name: ". $col_info['name']. "\n";
        echo "alias: ". $col_info['alias']. "\n";
        echo "relation: ". $col_info['relation']. "\n";
        echo "length: ". $col_info['length']. "\n";
        echo "type: ". $col_info['type']. "\n";
    }
    ?>

### Siehe auch

- ibase_num_fields() - Ermittelt die Anzahl der Felder einer Ergebnismenge

# ibase_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_free_event_handler — Bricht einen registrierten Ereignishandler ab

### Beschreibung

function ibase_free_event_handler(resource `$event`): bool

Diese Funktion bewirkt, dass der durch `event` angegebene registrierte Ereignishandler abgebrochen wird. Die Rückruffunktion wird für die Ereignisse, für die sie registriert wurde, nicht mehr aufgerufen.

### Parameter-Liste

`event`
  Eine Ereignisressource, erstellt durch ibase_set_event_handler().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_set_event_handler() - Registriert eine Rückruffunktion, die aufgerufen werden soll, wenn Ereignisse auftreten

# ibase_free_query

(PHP 5, PHP 7 < 7.4.0)

ibase_free_query — Gibt den Speicher einer vorbereiteten Abfrage wieder frei

### Beschreibung

function ibase_free_query(resource `$query`): bool

Gibt eine vorbereitete Abfrage frei.

### Parameter-Liste

`query`
  Eine mit ibase_prepare() vorbereitete Abfrage.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ibase_free_result

(PHP 5, PHP 7 < 7.4.0)

ibase_free_result — Gibt eine Ergebnismenge frei

### Beschreibung

function ibase_free_result(resource `$result_identifier`): bool

Gibt eine Ergebnismenge frei.

### Parameter-Liste

`result_identifier`
  Eine Ergebnismenge, die durch ibase_query() oder ibase_execute() erzeugt wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ibase_gen_id

(PHP 5, PHP 7 < 7.4.0)

ibase_gen_id — Inkrementiert den benannten Generator und gibt dessen neuen Wert zurück

### Beschreibung

function ibase_gen_id(string `$generator`, int `$increment` = 1, resource `$link_identifier` = `null`): mixed
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Rückgabewerte

Gibt den neuen Generatorwert als Ganzzahl oder als Zeichenfolge zurück, wenn der Wert zu groß ist.

# ibase_maintain_db

(PHP 5, PHP 7 < 7.4.0)

ibase_maintain_db — Führt einen Wartungsbefehl auf dem Datenbankserver aus

### Beschreibung

function ibase_maintain_db(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ibase_modify_user

(PHP 5, PHP 7 < 7.4.0)

ibase_modify_user — Ändert den Benutzer einer Security-Datenbank

### Beschreibung

function ibase_modify_user(
resource `$service_handle`,
string `$user_name`,
string `$password`,
string `$first_name` = ?,
string `$middle_name` = ?,
string `$last_name` = ?
): bool

### Parameter-Liste

`service_handle`
  Das Handle für den Datenbankserverdienst.
`user_name`
  Der Anmeldename des zu ändernden Datenbankbenutzers.
`password`
  Das neue Passwort des Benutzers.
`first_name`
  Der neue Vorname des Benutzers.
`middle_name`
  Der neue zweite Vorname des Benutzers.
`last_name`
  Der neue Nachname des Benutzers.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ibase_add_user() - Fügt einen Benutzer zu einer Security-Datenbank hinzu
- ibase_delete_user() - Löscht einen Benutzer aus einer Security-Datenbank

# ibase_name_result

(PHP 5, PHP 7 < 7.4.0)

ibase_name_result — Weist einer Ergebnismenge einen Namen zu

### Beschreibung

function ibase_name_result(resource `$result`, string `$name`): bool

Diese Funktion weist einer Ergebnismenge einen Namen zu. Dieser Name kann später in UPDATE|DELETE ... WHERE CURRENT OF `name`-Anweisungen verwendet werden.

### Parameter-Liste

`result`
  Eine InterBase/Firebird-Ergebnismenge.
`name`
  Der zuzuweisende Name.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 ibase_name_result()-Beispiel

    <?php
    $result = ibase_query("SELECT field1,field2 FROM table FOR UPDATE");
    ibase_name_result($result, "my_cursor");

    $updateqry = ibase_prepare("UPDATE table SET field2 = ? WHERE CURRENT OF my_cursor");

    for ($i = 0; ibase_fetch_row($result); ++$i) {
        ibase_execute($updateqry, $i);
    }
    ?>

### Siehe auch

- ibase_prepare() - Bereitet eine Abfrage für späteres Binden der Parameter-Platzhalter und Ausführung vor
- ibase_execute() - Ausführen einer vorbereiteten Abfrage

# ibase_num_fields

(PHP 5, PHP 7 < 7.4.0)

ibase_num_fields — Ermittelt die Anzahl der Felder einer Ergebnismenge

### Beschreibung

function ibase_num_fields(resource `$result_id`): int

Ermittelt die Anzahl der Felder einer Ergebnismenge.

### Parameter-Liste

`result_id`
  Eine InterBase Ergebniskennung.

### Rückgabewerte

Gibt die Anzahl der Felder als Ganzzahl zurück.

### Beispiele

Beispiel #1 ibase_num_fields() Beispiel

    <?php
    $rs = ibase_query("SELECT * FROM tablename");
    $coln = ibase_num_fields($rs);
    for ($i = 0; $i < $coln; $i++) {
        $col_info = ibase_field_info($rs, $i);
        echo "Name: " . $col_info['name'] . "\n";
        echo "Alias: " . $col_info['alias'] . "\n";
        echo "Relation: " . $col_info['relation'] . "\n";
        echo "Länge: " . $col_info['length'] . "\n";
        echo "Typ: " . $col_info['type'] . "\n";
    }
    ?>

### Siehe auch

- ibase_field_info() - Ruft Informationen zu einem Feld ab

# ibase_num_params

(PHP 5, PHP 7 < 7.4.0)

ibase_num_params — Gibt die Anzahl der Parameter in einer vorbereiteten Abfrage zurück

### Beschreibung

function ibase_num_params(resource `$query`): int

Diese Funktion gibt die Anzahl der Parameter in der vorbereiteten Abfrage zurück, die mit `query` angegeben wurde. Dies ist die Anzahl der Bindungsargumente, die beim Aufrufen von ibase_execute() vorhanden sein müssen.

### Parameter-Liste

`query`
  Das vorbereitete Abfragehandle.

### Rückgabewerte

Gibt die Anzahl der Parameter als Ganzzahl zurück.

### Siehe auch

- ibase_prepare() - Bereitet eine Abfrage für späteres Binden der Parameter-Platzhalter und Ausführung vor
- ibase_param_info() - Gibt Informationen zu einem Parameter in einer vorbereiteten Abfrage zurück

# ibase_param_info

(PHP 5, PHP 7 < 7.4.0)

ibase_param_info — Gibt Informationen zu einem Parameter in einer vorbereiteten Abfrage zurück

### Beschreibung

function ibase_param_info(resource `$query`, int `$param_number`): array

Gibt ein Array mit Informationen zu einem Parameter zurück, nachdem eine Abfrage vorbereitet wurde.

### Parameter-Liste

`query`
  Ein von InterBase/Firebird vorbereitetes Abfragehandle.
`param_number`
  Parameteroffset.

### Rückgabewerte

Gibt ein Array mit den folgenden Schlüsseln zurück: `name`, `alias`, `relation`, `length` und `type`.

### Siehe auch

- ibase_field_info() - Ruft Informationen zu einem Feld ab
- ibase_num_params() - Gibt die Anzahl der Parameter in einer vorbereiteten Abfrage zurück

# ibase_pconnect

(PHP 5, PHP 7 < 7.4.0)

ibase_pconnect — Öffnet eine persistente Verbindung zu einer InterBase-Datenbank

### Beschreibung

function ibase_pconnect(
string `$database` = ?,
string `$username` = ?,
string `$password` = ?,
string `$charset` = ?,
int `$buffers` = ?,
int `$dialect` = ?,
string `$role` = ?,
int `$sync` = ?
): resource

Öffnet eine persistente Verbindung zu einer InterBase-Datenbank.

ibase_pconnect() agiert ähnlich der Funktion ibase_connect(), mit zwei Ausnahmen.

Erstens wird beim Verbindungs-Aufbau versucht, eine bereits bestehende (persistente) Verbindung zu finden, die mit den selben Parametern aufgebaut worden ist. Wird eine solche gefunden, wird statt eines neuen Verbindungs-Aufbaus die ID der bestehenden Verbindung zurückgegeben.

Zweitens wird beim Beenden des Skripts die Verbindung zum InterBase Server nicht beendet. Statt dessen wird die Verbindung für den weiteren Gebrauch beibehalten (ibase_close() beendet keine Verbindungen, die mittels ibase_pconnect() erzeugt wurden). Diese Art der Verbindung wird deshalb auch 'persistent' genannt.

### Parameter-Liste

`database`
  Das `database`-Argument muss ein gültiger Pfad zu einer bestehenden Datenbank des Servers sein. Ist der DB-Server nicht lokal, muss ihm - in Abhängigkeit vom benutzten Protokoll - ein 'hostname:' (bei TCP/IP), '//hostname/' (bei NetBEUI) oder 'hostname@' (IPX/SPX) vorangestellt werden.
`username`
  Der Benutzername. Kann mit der `ibase.default_user` php.ini Direktive festgelegt werden.
`password`
  Das Passwort für `username`. Kann mit der `ibase.default_password` php.ini Direktive festegelegt werden.
`charset`
  `charset` ist der reguläre Zeichensatz der Datenbank.
`buffers`
  Mit `buffers` geben sie die Anzahl der Datenbank-Cache-Buffer (serverseitig) an. Ist der Wert 0 oder nicht angegeben, benutzt der Server seine Default-Werte.
`dialect`
  Mittels `dialect` bestimmen sie den Default-Wert des anzuwendenden SQL-Dialekts für alle Anweisungen während einer Datenbank-Verbindung (default ist der Client-seitig höchst verfügbare Dialekt). Dies wirkt nur mit InterBase 6 und höher.
`role`
  Wirkt nur unter InterBase 5 und höher.
`sync`

### Rückgabewerte

Gibt bei Erfolg eine Firebird/Interbase Verbindungs-ID zurück, oder `false` im Fehlerfall.

### Siehe auch

- ibase_close() - Schließt eine Verbindung zu einer InterBase-Datenbank
- ibase_connect() - Öffnet eine Verbindung zu einer Datenbank

# ibase_prepare

(PHP 5, PHP 7 < 7.4.0)

ibase_prepare — Bereitet eine Abfrage für späteres Binden der Parameter-Platzhalter und Ausführung vor

### Beschreibung

function ibase_prepare(string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$trans`, string `$query`): resource

Bereitet eine Abfrage für späteres Binden der Parameter-Platzhalter und Ausführung vor (per ibase_execute()).

### Parameter-Liste

`query`
  Eine InterBase Abfrage.
`link_identifier`
  Ein InterBase-Verbindungs-Bezeichner, der von ibase_connect() zurückgegeben wurde. Falls ausgelassen, wird die zuletzt geöffnete Verbindung verwendet.
`trans`
  Ein InterBase-Transaktions-Handle mit der die Abfrage assoziiert werden soll. Falls ausgelassen, wird die Standard-Transaktion der Abfrage verwendet.

### Rückgabewerte

Gibt ein Handle der vorbereiteten Abfrage zurück, oder `false` im Fehlerfall.

# ibase_query

(PHP 5, PHP 7 < 7.4.0)

ibase_query — Führt eine Abfrage auf einer InterBase Datenbank aus

### Beschreibung

function ibase_query(resource `$link_identifier` = ?, string `$query`, int `$bind_args` = ?): resource

Führt eine Abfrage auf einer InterBase Datenbank aus.

### Parameter-Liste

`link_identifier`
  Eine InterBase Verbindungskennung. Wenn ausgelassen, wird die zuletzt geöffnete Verbindung angenommen.
`query`
  Eine InterBase Abfrage.
`bind_args`

### Rückgabewerte

Erzeugt die Abfrage einen Fehler, wird `false` zurückgegeben. Ist sie erfolgreich und es gibt eine (möglicherweise leere) Ergebnismenge (so wie bei einer SELECT Abfrage), wird eine Ergebniskennung zurückgegeben. War die Abfrage erfolgreich und es gibt keine Ergebnisse, wird `true` zurückgegeben.

> Hinweis: Unter PHP 5.0.0 und höher gibt diese Funktion die Anzahl der Zeilen zurück, die von der Abfrage für INSERT, UPDATE und DELETE Anweisungen betroffen waren. Um die Abwärtskompatibilität zu erhalten, wird `true` für diese Anweisungen zurückgegeben, wenn die Abfrage erfolgreich war, aber keine Zeilen betraf.

### Fehler/Exceptions

Erhalten Sie Fehlermeldungen wie "arithmetic exception, numeric overflow, or string truncation. Cannot transliterate character between character sets" (diese treten auf, wenn Sie Zeichen mit Akzent verwenden), wenn Sie diese Funktion und ibase_query() verwenden, müssen Sie den Zeichensatz (d.h. ISO8859_1 oder Ihren aktuellen Zeichensatz) einstellen.

### Beispiele

Beispiel #1 ibase_query() example

    <?php

    $host = 'localhost:/pfad/zu/ihrer.gdb';

    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';

    $sth = ibase_query($dbh, $stmt) or die(ibase_errmsg());

    ?>

### Siehe auch

- ibase_errmsg() - Gibt eine Fehlermeldung zurück
- ibase_fetch_row() - Ruft eine Zeile aus einer InterBase-Datenbank ab
- ibase_fetch_object() - Liest einen Datensatz einer InterBase-Datenbank als Objekt ein
- ibase_free_result() - Gibt eine Ergebnismenge frei

# ibase_restore

(PHP 5, PHP 7 < 7.4.0)

ibase_restore — Leitet eine Wiederherstellungsaufgabe im Service Manager ein und kehrt sofort zurück

### Beschreibung

function ibase_restore(
resource `$service_handle`,
string `$source_file`,
string `$dest_db`,
int `$options` = 0,
bool `$verbose` = `false`
): mixed

Diese Funktion übergibt die Argumente an den (entfernten) Datenbankserver. Dort startet sie einen neuen Sicherungsvorgang. Deshalb erhalten Sie keine Antwort.

### Parameter-Liste

`service_handle`
  Eine zuvor geöffnete Verbindung zum Datenbankserver.
`source_file`
  Der absolute Pfad auf dem Server, auf dem sich die Sicherungsdatei befindet.
`dest_db`
  Der Pfad zum Erstellen der neuen Datenbank auf dem Server. Sie können auch einen Datenbankalias verwenden.
`options`

  Zusätzliche Optionen, die zur Wiederherstellung an den Datenbankserver übergeben werden. Der Parameter `options` darf aus Kombinationen folgender Konstanten bestehen: `IBASE_RES_DEACTIVATE_IDX`, `IBASE_RES_NO_SHADOW`, `IBASE_RES_NO_VALIDITY`, `IBASE_RES_ONE_AT_A_TIME`, `IBASE_RES_REPLACE`, `IBASE_RES_CREATE`, `IBASE_RES_USE_ALL_SPACE`, `IBASE_PRP_PAGE_BUFFERS`, `IBASE_PRP_SWEEP_INTERVAL`, `IBASE_RES_CREATE`. Vgl. den Abschnitt Vordefinierte Konstanten für weitere informationen.

`verbose`
  Da der Wiederherstellungsvorgang auf dem Datenbankserver ausgeführt wird, haben Sie keine Chance, die Ausgabe abzurufen. Dieses Argument ist sinnlos.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Da der Sicherungsvorgang auf dem (Remote-) Server durchgeführt wird, übergibt diese Funktion nur die Argumente an diesen. Solange die Argumente gültig sind, werden Sie niemals `false` zurückbekommen.

### Beispiele

Beispiel #1 ibase_restore()-Beispiel

    <?php

    // Mit Datenbankserver mittels IP-Adresse und Port verbinden
    $service = ibase_service_attach ('10.1.11.200/3050', 'sysdba', 'masterkey');

    // Starte den Wiederherstellungsvorgang
    // Wiederherstellung der Mitarbeiter-DB in neue emps.fdb-Datenbank.
    // Keine Angabe weiterer Argumente.
    ibase_restore($service, '/srv/backup/employees.fbk', '/srv/firebird/emps.fdb');

    // Verbindung wieder freigeben
    ibase_service_detach ($service);
    ?>

Beispiel #2 ibase_restore()-Beispiel mit Argumenten

    <?php

    // Mit Datenbankserver mittels Namen und Standardport verbinden
    $service = ibase_service_attach ('fb-server.contoso.local', 'sysdba', 'masterkey');

    // Starte den Wiederherstellungsprozess
    // Employee-Datenbank mittels Alias wiederherstellen
    // Wiederherstellung ohne Indizes. Existierende DB ersetzen.
    ibase_restore($service, '/srv/backup/employees.fbk', 'employees.fdb', IBASE_RES_DEACTIVATE_IDX | IBASE_RES_REPLACE);

    // Verbindung wieder freigeben.
    ibase_service_detach ($service);
    ?>

### Siehe auch

- ibase_backup() - Initiiert eine Sicherungsaufgabe im Service Manager und springt sofort zurück

# ibase_rollback

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback — Macht eine Transaktion rückgängig

### Beschreibung

function ibase_rollback(resource `$link_or_trans_identifier` = `null`): bool

Macht eine Transaktion rückgängig.

### Parameter-Liste

`link_or_trans_identifier`
  Wenn diese Funktion ohne Argument aufgerufen wird, wird die Standardtransaktion des Standardlinks zurückgesetzt. Wenn das Argument eine Verbindungskennung ist, wird die Standardtransaktion der entsprechenden Verbindung zurückgesetzt. Wenn das Argument eine Transaktionskennung ist, wird die entsprechende Transaktion zurückgesetzt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ibase_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback_ret — Macht eine Transaktion rückgängig, ohne diese zu schließen

### Beschreibung

function ibase_rollback_ret(resource `$link_or_trans_identifier` = `null`): bool

Macht eine Transaktion rückgängig, ohne diese zu schließen

### Parameter-Liste

`link_or_trans_identifier`
  Wenn diese Funktion ohne Argument aufgerufen wird, wird die Standardtransaktion des Standardlinks zurückgesetzt. Wenn das Argument eine Verbindungskennung ist, wird die Standardtransaktion der entsprechenden Verbindung zurückgesetzt. Wenn das Argument eine Transaktionskennung ist, wird die entsprechende Transaktion zurückgesetzt. Der Transaktionskontext wird beibehalten, sodass Anweisungen, die innerhalb dieser Transaktion ausgeführt werden, nicht ungültig werden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ibase_server_info

(PHP 5, PHP 7 < 7.4.0)

ibase_server_info — Informationen zu einem Datenbankserver anfordern

### Beschreibung

function ibase_server_info(resource `$service_handle`, int `$action`): string

### Parameter-Liste

`service_handle`
  Eine zuvor erstellte Verbindung zum Datenbankserver.
`action`
  Eine gültige Konstante.

### Rückgabewerte

Gibt je nach Kontext gemischte Typen zurück.

### Beispiele

Beispiel #1 ibase_service_attach()-Beispiel

    <?php
        // Stelle eine Verbindung zum entfernten Firebird-Server her
        if (($service = ibase_service_attach('10.1.1.254/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Verbidung erfolgreich

            // Infos ausgeben
            echo "Server version: " . ibase_server_info($service, IBASE_SVC_SERVER_VERSION) . "\n";
            echo "Server implementation: " . ibase_server_info($service, IBASE_SVC_IMPLEMENTATION) . "\n";
            echo "Server users: " . print_r(ibase_server_info($service, IBASE_SVC_GET_USERS), true) . "\n";
            echo "Server directory: " . ibase_server_info($service, IBASE_SVC_GET_ENV) . "\n";
            echo "Server lock path: " . ibase_server_info($service, IBASE_SVC_GET_ENV_LOCK) . "\n";
            echo "Server lib path: " . ibase_server_info($service, IBASE_SVC_GET_ENV_MSG) . "\n";
            echo "Path of user db: " . ibase_server_info($service, IBASE_SVC_USER_DBPATH) . "\n";
            echo "Established connections: " . print_r(ibase_server_info($service, IBASE_SVC_SVR_DB_INFO),true) . "\n";

            // Serververbindung lösen (disconnect)
            ibase_service_detach($service);

        }
        else {
            // Fehler ausgeben
            $conn_error = ibase_errmsg();
            die($conn_error);
        }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Server version: LI-V3.0.4.33054 Firebird 3.0
    Server implementation: Firebird/Linux/AMD/Intel/x64
    Server users: Array
    (
        [0] => Array
            (
                [user_name] => SYSDBA
                [first_name] => Sql
                [middle_name] => Server
                [last_name] => Administrator
                [user_id] => 0
                [group_id] => 0
            )

    )

    Server directory: /etc/firebird/
    Server lock path: /tmp/firebird/
    Server lib path: /usr/lib64/firebird/lib/
    Path of user db: /var/lib/firebird/secdb/security3.fdb
    Established connections: Array
    (
        [attachments] => 3
        [databases] => 2
        [0] => /srv/firebird/poss.fdb
        [1] => /srv/firebird/employees.fdb
    )

# ibase_service_attach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_attach — Verbindet mit dem Service-Manager

### Beschreibung

function ibase_service_attach(string `$host`, string `$dba_username`, string `$dba_password`): resource|false

### Parameter-Liste

`host`
  Der Name oder die IP-Adresse des Datenbank-Hosts. Sie können den Port angeben durch Hinzufügen von '/' und der Portnummer. Sofern kein Port angegeben wurde, wird Port 3050 verwendet.
`dba_username`
  Der Name eines gültigen Benutzers.
`dba_password`
  Das Kennwort des Benutzers.

### Rückgabewerte

Gibt im Erfolgsfall eine Interbase/Firebird-Verbindungskennung zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 ibase_service_attach()-Beispiel

    <?php
        // Stellt über die IP-Adresse eine Verbindung zum Remote-Firebird-Server her
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Verbindung erfolgreich
            // Server-Version ermitteln (z. B. 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Serverimplementierung abrufen (z. B. 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Vom Server trennen (Verbindung trennen)
            ibase_service_detach($service);

            // Ausgabe
            echo "Server-Version: " . $server_version . "<br/>";
            echo "Server-Implementierung: " . $server_implementation;
        }
        else {
            // Fehler ausgeben
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

Beispiel #2 ibase_service_attach()-Beispiel mit `hostname/port`-Syntax

    <?php
        // Verbindung zum Remote-Firebird-Server über den Namen herstellen. Port 3050 verwenden.
        if (($service = ibase_service_attach('FB-SRV-01.contoso.local/3050', 'sysdba', 'masterkey')) != FALSE) {

            // Verbindung erfolgreich
            // Server-Version ermitteln (z. B. 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Serverimplementierung abrufen (z. B. 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Vom Server trennen (Verbindung trennen)
            ibase_service_detach($service);

            // Ausgabe
            echo "Server-Version: " . $server_version . "<br/>";
            echo "Server-Implementierung: " . $server_implementation;
        }
        else {
            // Fehler ausgeben
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

### Siehe auch

- ibase_service_detach() - Trennt die Verbindung zum Service-Manager

# ibase_service_detach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_detach — Trennt die Verbindung zum Service-Manager

### Beschreibung

function ibase_service_detach(resource `$service_handle`): bool

### Parameter-Liste

`service_handle`
  Eine zuvor erstellte Verbindung zum Datenbankserver.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 ibase_service_detach()-Beispiel

    <?php
        // Verbindung zum Remote-Firebird-Server mittels IP herstellen.
        if (($service = ibase_service_attach('10.1.1.199', 'sysdba', 'masterkey')) != FALSE) {

            // Verbindung erfolgreich
            // Server-Version ermitteln (z. B. 'LI-V3.0.4.33054 Firebird 3.0')
            $server_version  = ibase_server_info($service, IBASE_SVC_SERVER_VERSION);

            // Serverimplementierung abrufen (z. B. 'Firebird/Linux/AMD/Intel/x64')
            $server_implementation = ibase_server_info($service, IBASE_SVC_IMPLEMENTATION);

            // Verbindung trennen
            if(ibase_service_detach($service) == FALSE) {
                echo "Fehler beim Trennen vom Service.";
            }
            else {
                echo "Erfolgreich vom Service getrennt.";
            }

        }
        else {
            // Ausgabe bei Fehler
            $conn_error = ibase_errmsg();
            die($conn_error);
        }

    ?>

# ibase_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_set_event_handler — Registriert eine Rückruffunktion, die aufgerufen werden soll, wenn Ereignisse auftreten

### Beschreibung

function ibase_set_event_handler(callable `$event_handler`, string `$event_name`, string `...$even_names`): resource
function ibase_set_event_handler(
resource `$connection`,
callable `$event_handler`,
string `$event_name`,
string `...$event_names`
): resource

Diese Funktion registriert eine PHP-Benutzerfunktion als Ereignishandler für die angegebenen Ereignisse.

### Parameter-Liste

`event_handler`
  Der Rückruf wird mit dem Ereignisnamen und der Verknüpfungsressource als Argument aufgerufen, wenn eines der angegebenen Ereignisse von der Datenbank gesendet wird. Der Rückruf muss `false` zurückgeben, wenn der Eventhandler abgebrochen werden soll. Jeder andere Rückgabewert wird ignoriert. Diese Funktion akzeptiert bis zu 15 Ereignisargumente.
`event_name`
  Ein Ereignisname.
`event_names`
  Maximal 15 Ereignisse erlaubt.

### Rückgabewerte

Der Rückgabewert ist eine Ereignisressource. Diese Ressource kann verwendet werden, um den Ereignishandler mithilfe von ibase_free_event_handler() freizugeben.

### Beispiele

Beispiel #1 ibase_set_event_handler()-Beispiel

    <?php

    function event_handler($event_name, $link)
    {
        if ($event_name == "NEW ORDER") {
            // process new order
            ibase_query($link, "UPDATE orders SET status='handled'");
        } else if ($event_name == "DB_SHUTDOWN") {
            // free event handler
            return false;
        }
    }

    ibase_set_event_handler($link, "event_handler", "NEW_ORDER", "DB_SHUTDOWN");
    ?>

### Siehe auch

- ibase_free_event_handler() - Bricht einen registrierten Ereignishandler ab
- ibase_wait_event() - Wartet, bis ein Ereignis von der Datenbank veröffentlicht wurde

# ibase_trans

(PHP 5, PHP 7 < 7.4.0)

ibase_trans — Startet eine Transaktion

### Beschreibung

function ibase_trans(int `$trans_args` = ?, resource `$link_identifier` = ?): resource
function ibase_trans(resource `$link_identifier` = ?): resource

Startet eine Transaktion

> Hinweis: Der erste Aufruf von ibase_trans() gibt nicht die Standardtransaktion einer Verbindung zurück. Alle Transaktionen, die mittels ibase_trans() gestartet wurden, werden am Ende des Skripts rückgängig gemacht, sofern diese nicht mit ibase_commit() festgeschrieben oder mit ibase_rollback() rückgängig gemacht wurden.

> Hinweis: Diese Funktion akzeptiert mehrere `trans_args`- und `link_identifier`-Argumente. Dies erlaubt Transaktionen über mehrere Datenbankverbindungen, die mittels eines 2-Phasen-Commit-Algorithmus festgeschrieben werden. Dies bedeutet, dass Sie sich darauf verlassen können, dass die Aktualisierungen entweder in jeder Datenbank erfolgreich sind oder in jeder Datenbank fehlschlagen. Es bedeutet NICHT, dass Sie Tabellen aus verschiedenen Datenbanken in derselben Abfrage verwenden können! Wenn Sie Transaktionen über mehrere Datenbanken hinweg verwenden, müssen Sie die Parameter `link_id` und `transaction_id` in den Aufrufen von ibase_query() und ibase_prepare() verwenden.

### Parameter-Liste

`trans_args`
  `trans_args` darf eine Kombination aus `IBASE_READ`, `IBASE_WRITE`, `IBASE_COMMITTED`, `IBASE_CONSISTENCY`, `IBASE_CONCURRENCY`, `IBASE_REC_VERSION`, `IBASE_REC_NO_VERSION`, `IBASE_WAIT` und `IBASE_NOWAIT` sein.
`link_identifier`
  Eine InterBase/Firebird-Verbindungskennung. Wenn nicht angegeben, wird der zuletzt geöffnete Link angenommen.

### Rückgabewerte

Gibt ein Transaktions-Handle zurück oder `false` on bei einem Fehler.

# ibase_wait_event

(PHP 5, PHP 7 < 7.4.0)

ibase_wait_event — Wartet, bis ein Ereignis von der Datenbank veröffentlicht wurde

### Beschreibung

function ibase_wait_event(string `$event_name`, string `...$event_names`): string
function ibase_wait_event(resource `$connection`, string `$event_name`, string `...$event_names`): string

Diese Funktion unterbricht die Ausführung des Skripts, bis eines der angegebenen Ereignisse von der Datenbank gesendet wird. Der Name des Ereignisses, das gebucht wurde, wird zurückgegeben. Diese Funktion akzeptiert bis zu 15 Ereignisargumente.

### Parameter-Liste

`event_name`
  Der Ereignisname.
`event_names`

### Rückgabewerte

Gibt den Namen des Ereignisses zurück, das aufgetreten ist.

### Siehe auch

- ibase_set_event_handler() - Registriert eine Rückruffunktion, die aufgerufen werden soll, wenn Ereignisse auftreten
- ibase_free_event_handler() - Bricht einen registrierten Ereignishandler ab

## Inhaltsverzeichnis

- fbird_add_user — Alias von ibase_add_user
- fbird_affected_rows — Alias von ibase_affected_rows
- fbird_backup — Alias von ibase_backup
- fbird_blob_add — Alias von ibase_blob_add
- fbird_blob_cancel — Cancel creating blob
- fbird_blob_close — Alias von ibase_blob_close
- fbird_blob_create — Alias von ibase_blob_create
- fbird_blob_echo — Alias von ibase_blob_echo
- fbird_blob_get — Alias von ibase_blob_get
- fbird_blob_import — Alias von ibase_blob_import
- fbird_blob_info — Alias von ibase_blob_info
- fbird_blob_open — Alias von ibase_blob_open
- fbird_close — Alias von ibase_close
- fbird_commit — Alias von ibase_commit
- fbird_commit_ret — Alias von ibase_commit_ret
- fbird_connect — Alias von ibase_connect
- fbird_db_info — Alias von ibase_db_info
- fbird_delete_user — Alias von ibase_delete_user
- fbird_drop_db — Alias von ibase_drop_db
- fbird_errcode — Alias von ibase_errcode
- fbird_errmsg — Alias von ibase_errmsg
- fbird_execute — Alias von ibase_execute
- fbird_fetch_assoc — Alias von ibase_fetch_assoc
- fbird_fetch_object — Alias von ibase_fetch_object
- fbird_fetch_row — Alias von ibase_fetch_row
- fbird_field_info — Alias von ibase_field_info
- fbird_free_event_handler — Alias von ibase_free_event_handler
- fbird_free_query — Alias von ibase_free_query
- fbird_free_result — Alias von ibase_free_result
- fbird_gen_id — Alias von ibase_gen_id
- fbird_maintain_db — Alias von ibase_maintain_db
- fbird_modify_user — Alias von ibase_modify_user
- fbird_name_result — Alias von ibase_name_result
- fbird_num_fields — Alias von ibase_num_fields
- fbird_num_params — Alias von ibase_num_params
- fbird_param_info — Alias von ibase_param_info
- fbird_pconnect — Alias von ibase_pconnect
- fbird_prepare — Alias von ibase_prepare
- fbird_query — Alias von ibase_query
- fbird_restore — Alias von ibase_restore
- fbird_rollback — Alias von ibase_rollback
- fbird_rollback_ret — Alias von ibase_rollback_ret
- fbird_server_info — Alias von ibase_server_info
- fbird_service_attach — Alias von ibase_service_attach
- fbird_service_detach — Alias von ibase_service_detach
- fbird_set_event_handler — Alias von ibase_set_event_handler
- fbird_trans — Alias von ibase_trans
- fbird_wait_event — Alias von ibase_wait_event
- ibase_add_user — Fügt einen Benutzer zu einer Security-Datenbank hinzu
- ibase_affected_rows — Gibt die Anzahl der Zeilen zurück, die von der vorherigen Abfrage betroffen waren
- ibase_backup — Initiiert eine Sicherungsaufgabe im Service Manager und springt sofort zurück
- ibase_blob_add — Fügt Daten in ein neues BLOB ein
- ibase_blob_cancel — Bricht die Erstellung eines neuen BLOBs ab
- ibase_blob_close — BLOB schließen
- ibase_blob_create — Erstellt ein neues BLOB zum Hinzufügen von Daten
- ibase_blob_echo — Ausgabe von BLOB-Inhalten an den Browser
- ibase_blob_get — Holt sich len Bytes Daten aus dem offenen BLOB
- ibase_blob_import — Erstellt ein BLOB, kopiert die Dateidaten hinein und schließt es
- ibase_blob_info — Gibt die Blob-Länge und andere nützliche Informationen zurück
- ibase_blob_open — Öffnet BLOB zum Abrufen von Datenteilen
- ibase_close — Schließt eine Verbindung zu einer InterBase-Datenbank
- ibase_commit — Schreibt eine Transaktion fest
- ibase_commit_ret — Schreibt eine Transaktion fest, ohne diese zu schließen
- ibase_connect — Öffnet eine Verbindung zu einer Datenbank
- ibase_db_info — Fragt statistische Daten über eine Datenbank ab
- ibase_delete_user — Löscht einen Benutzer aus einer Security-Datenbank
- ibase_drop_db — Löscht eine Datenbank
- ibase_errcode — Gibt einen Fehlercode zurück
- ibase_errmsg — Gibt eine Fehlermeldung zurück
- ibase_execute — Ausführen einer vorbereiteten Abfrage
- ibase_fetch_assoc — Ruft eine Ergebniszeile aus einer Abfrage als assoziatives Array ab
- ibase_fetch_object — Liest einen Datensatz einer InterBase-Datenbank als Objekt ein
- ibase_fetch_row — Ruft eine Zeile aus einer InterBase-Datenbank ab
- ibase_field_info — Ruft Informationen zu einem Feld ab
- ibase_free_event_handler — Bricht einen registrierten Ereignishandler ab
- ibase_free_query — Gibt den Speicher einer vorbereiteten Abfrage wieder frei
- ibase_free_result — Gibt eine Ergebnismenge frei
- ibase_gen_id — Inkrementiert den benannten Generator und gibt dessen neuen Wert zurück
- ibase_maintain_db — Führt einen Wartungsbefehl auf dem Datenbankserver aus
- ibase_modify_user — Ändert den Benutzer einer Security-Datenbank
- ibase_name_result — Weist einer Ergebnismenge einen Namen zu
- ibase_num_fields — Ermittelt die Anzahl der Felder einer Ergebnismenge
- ibase_num_params — Gibt die Anzahl der Parameter in einer vorbereiteten Abfrage zurück
- ibase_param_info — Gibt Informationen zu einem Parameter in einer vorbereiteten Abfrage zurück
- ibase_pconnect — Öffnet eine persistente Verbindung zu einer InterBase-Datenbank
- ibase_prepare — Bereitet eine Abfrage für späteres Binden der Parameter-Platzhalter und Ausführung vor
- ibase_query — Führt eine Abfrage auf einer InterBase Datenbank aus
- ibase_restore — Leitet eine Wiederherstellungsaufgabe im Service Manager ein und kehrt sofort zurück
- ibase_rollback — Macht eine Transaktion rückgängig
- ibase_rollback_ret — Macht eine Transaktion rückgängig, ohne diese zu schließen
- ibase_server_info — Informationen zu einem Datenbankserver anfordern
- ibase_service_attach — Verbindet mit dem Service-Manager
- ibase_service_detach — Trennt die Verbindung zum Service-Manager
- ibase_set_event_handler — Registriert eine Rückruffunktion, die aufgerufen werden soll, wenn Ereignisse auftreten
- ibase_trans — Startet eine Transaktion
- ibase_wait_event — Wartet, bis ein Ereignis von der Datenbank veröffentlicht wurde

- Installation/Konfiguration
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Firebird/InterBase Funktionen
  - fbird_add_user — Alias von ibase_add_user
  - fbird_affected_rows — Alias von ibase_affected_rows
  - fbird_backup — Alias von ibase_backup
  - fbird_blob_add — Alias von ibase_blob_add
  - fbird_blob_cancel — Cancel creating blob
  - fbird_blob_close — Alias von ibase_blob_close
  - fbird_blob_create — Alias von ibase_blob_create
  - fbird_blob_echo — Alias von ibase_blob_echo
  - fbird_blob_get — Alias von ibase_blob_get
  - fbird_blob_import — Alias von ibase_blob_import
  - fbird_blob_info — Alias von ibase_blob_info
  - fbird_blob_open — Alias von ibase_blob_open
  - fbird_close — Alias von ibase_close
  - fbird_commit — Alias von ibase_commit
  - fbird_commit_ret — Alias von ibase_commit_ret
  - fbird_connect — Alias von ibase_connect
  - fbird_db_info — Alias von ibase_db_info
  - fbird_delete_user — Alias von ibase_delete_user
  - fbird_drop_db — Alias von ibase_drop_db
  - fbird_errcode — Alias von ibase_errcode
  - fbird_errmsg — Alias von ibase_errmsg
  - fbird_execute — Alias von ibase_execute
  - fbird_fetch_assoc — Alias von ibase_fetch_assoc
  - fbird_fetch_object — Alias von ibase_fetch_object
  - fbird_fetch_row — Alias von ibase_fetch_row
  - fbird_field_info — Alias von ibase_field_info
  - fbird_free_event_handler — Alias von ibase_free_event_handler
  - fbird_free_query — Alias von ibase_free_query
  - fbird_free_result — Alias von ibase_free_result
  - fbird_gen_id — Alias von ibase_gen_id
  - fbird_maintain_db — Alias von ibase_maintain_db
  - fbird_modify_user — Alias von ibase_modify_user
  - fbird_name_result — Alias von ibase_name_result
  - fbird_num_fields — Alias von ibase_num_fields
  - fbird_num_params — Alias von ibase_num_params
  - fbird_param_info — Alias von ibase_param_info
  - fbird_pconnect — Alias von ibase_pconnect
  - fbird_prepare — Alias von ibase_prepare
  - fbird_query — Alias von ibase_query
  - fbird_restore — Alias von ibase_restore
  - fbird_rollback — Alias von ibase_rollback
  - fbird_rollback_ret — Alias von ibase_rollback_ret
  - fbird_server_info — Alias von ibase_server_info
  - fbird_service_attach — Alias von ibase_service_attach
  - fbird_service_detach — Alias von ibase_service_detach
  - fbird_set_event_handler — Alias von ibase_set_event_handler
  - fbird_trans — Alias von ibase_trans
  - fbird_wait_event — Alias von ibase_wait_event
  - ibase_add_user — Fügt einen Benutzer zu einer Security-Datenbank hinzu
  - ibase_affected_rows — Gibt die Anzahl der Zeilen zurück, die von der vorherigen Abfrage betroffen waren
  - ibase_backup — Initiiert eine Sicherungsaufgabe im Service Manager und springt sofort zurück
  - ibase_blob_add — Fügt Daten in ein neues BLOB ein
  - ibase_blob_cancel — Bricht die Erstellung eines neuen BLOBs ab
  - ibase_blob_close — BLOB schließen
  - ibase_blob_create — Erstellt ein neues BLOB zum Hinzufügen von Daten
  - ibase_blob_echo — Ausgabe von BLOB-Inhalten an den Browser
  - ibase_blob_get — Holt sich len Bytes Daten aus dem offenen BLOB
  - ibase_blob_import — Erstellt ein BLOB, kopiert die Dateidaten hinein und schließt es
  - ibase_blob_info — Gibt die Blob-Länge und andere nützliche Informationen zurück
  - ibase_blob_open — Öffnet BLOB zum Abrufen von Datenteilen
  - ibase_close — Schließt eine Verbindung zu einer InterBase-Datenbank
  - ibase_commit — Schreibt eine Transaktion fest
  - ibase_commit_ret — Schreibt eine Transaktion fest, ohne diese zu schließen
  - ibase_connect — Öffnet eine Verbindung zu einer Datenbank
  - ibase_db_info — Fragt statistische Daten über eine Datenbank ab
  - ibase_delete_user — Löscht einen Benutzer aus einer Security-Datenbank
  - ibase_drop_db — Löscht eine Datenbank
  - ibase_errcode — Gibt einen Fehlercode zurück
  - ibase_errmsg — Gibt eine Fehlermeldung zurück
  - ibase_execute — Ausführen einer vorbereiteten Abfrage
  - ibase_fetch_assoc — Ruft eine Ergebniszeile aus einer Abfrage als assoziatives Array ab
  - ibase_fetch_object — Liest einen Datensatz einer InterBase-Datenbank als Objekt ein
  - ibase_fetch_row — Ruft eine Zeile aus einer InterBase-Datenbank ab
  - ibase_field_info — Ruft Informationen zu einem Feld ab
  - ibase_free_event_handler — Bricht einen registrierten Ereignishandler ab
  - ibase_free_query — Gibt den Speicher einer vorbereiteten Abfrage wieder frei
  - ibase_free_result — Gibt eine Ergebnismenge frei
  - ibase_gen_id — Inkrementiert den benannten Generator und gibt dessen neuen Wert zurück
  - ibase_maintain_db — Führt einen Wartungsbefehl auf dem Datenbankserver aus
  - ibase_modify_user — Ändert den Benutzer einer Security-Datenbank
  - ibase_name_result — Weist einer Ergebnismenge einen Namen zu
  - ibase_num_fields — Ermittelt die Anzahl der Felder einer Ergebnismenge
  - ibase_num_params — Gibt die Anzahl der Parameter in einer vorbereiteten Abfrage zurück
  - ibase_param_info — Gibt Informationen zu einem Parameter in einer vorbereiteten Abfrage zurück
  - ibase_pconnect — Öffnet eine persistente Verbindung zu einer InterBase-Datenbank
  - ibase_prepare — Bereitet eine Abfrage für späteres Binden der Parameter-Platzhalter und Ausführung vor
  - ibase_query — Führt eine Abfrage auf einer InterBase Datenbank aus
  - ibase_restore — Leitet eine Wiederherstellungsaufgabe im Service Manager ein und kehrt sofort zurück
  - ibase_rollback — Macht eine Transaktion rückgängig
  - ibase_rollback_ret — Macht eine Transaktion rückgängig, ohne diese zu schließen
  - ibase_server_info — Informationen zu einem Datenbankserver anfordern
  - ibase_service_attach — Verbindet mit dem Service-Manager
  - ibase_service_detach — Trennt die Verbindung zum Service-Manager
  - ibase_set_event_handler — Registriert eine Rückruffunktion, die aufgerufen werden soll, wenn Ereignisse auftreten
  - ibase_trans — Startet eine Transaktion
  - ibase_wait_event — Wartet, bis ein Ereignis von der Datenbank veröffentlicht wurde

# IBM DB2, Cloudscape and Apache Derby

# Einführung

These functions enable you to access IBM DB2 Universal Database, IBM Cloudscape, and Apache Derby databases using the DB2 Call Level Interface (DB2 CLI).

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

To connect to IBM DB2 Universal Database for Linux, UNIX, and Windows, or IBM Cloudscape, or Apache Derby, you must install an IBM DB2 Universal Database client on the same computer on which you are running PHP. The extension has been developed and tested with DB2 Version 8.2.

To connect to IBM DB2 Universal Database for z/OS or iSeries, you also require IBM DB2 Connect or the equivalent DRDA gateway software.

## Requirements on Linux or Unix

The user invoking the PHP executable or SAPI must specify the DB2 instance before accessing these functions. You can set the name of the DB2 instance in php.ini using the `ibm_db2.instance_name` configuration option, or you can source the DB2 instance profile before invoking the PHP executable.

If you created a DB2 instance named `db2inst1` in /home/db2inst1/, for example, you can add the following line to php.ini:

    ibm_db2.instance_name=db2inst1

If you do not set this option in php.ini, you must issue the following command to modify your environment variables to enable access to DB2:

    bash$ source /home/db2inst1/sqllib/db2profile

To enable your PHP-enabled Web server to access these functions, you must either set the `ibm_db2.instance_name` configuration option in php.ini, or source the DB2 instance environment in your Web server start script (typically /etc/init.d/httpd or /etc/init.d/apache).

## Installation

To build the ibm_db2 extension, the DB2 application development header files and libraries must be installed on the system. DB2 does not install these by default, so it may be necessary to return to the DB2 installer and add this option. The DB2 Application Development Client includes the header files and is freely available for download from the IBM DB2 Universal Database » support site.

If the DB2 application development header files and libraries are added to a Linux or Unix operating system on which DB2 was already installed, the command db2iupdt -e must be issued to update the symbolic links to the header files and libraries in the DB2 instances.

ibm_db2 is a » PECL extension, so follow the instructions in Installation der PECL-Erweiterungen to install the ibm_db2 extension for PHP. Issue the configure command to point to the location of the DB2 header files and libraries as follows:

    bash$ ./configure --with-IBM_DB2=/path/to/DB2

The configure command defaults to /opt/IBM/db2/V8.1.

> Hinweis: Note for IIS users
> If the ibm_db2 driver is being used with Microsoft Internet Information Server (IIS), it may be necessary to do the following:

> - Install DB2 with extended operating system security.
> - Add the PHP binary path to the PATH system environment variable (default C:\php\).
> - Create another system environment variable equal to the path where the PHP.INI file is located (eg: PHPRC = C:\php\).
> - Add the IUSR_COMPUTERNAME to the DB2USERS group.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

ibm_db2 Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
ibm_db2.binmode | "1" | `INI_ALL` |
ibm_db2.i5_all_pconnect | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.6.5.
ibm_db2.i5_allow_commit | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.4.9.
ibm_db2.i5_blank_userid | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.9.7.
ibm_db2.i5_char_trim | "0" | `INI_SYSTEM` | Available as of ibm_db2 2.1.0.
ibm_db2.i5_dbcs_alloc | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.5.0.
ibm_db2.i5_guard_profile | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.9.7.
ibm_db2.i5_ignore_userid | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.8.0.
ibm_db2.i5_job_sort | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.8.4.
ibm_db2.i5_log_verbose | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.9.7.
ibm_db2.i5_max_pconnect | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.9.7.
ibm_db2.i5_override_ccsid | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.9.7.
ibm_db2.i5_servermode_subsystem | NULL | `INI_SYSTEM` | Available as of ibm_db2 1.9.7.
ibm_db2.i5_sys_naming | "0" | `INI_SYSTEM` | Available as of ibm_db2 1.9.7.
ibm_db2.instance_name | NULL | `INI_SYSTEM` | Available as of ibm_db2 1.0.2.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`ibm_db2.binmode` int

  This option controls the mode used for converting to and from binary data in the PHP application.

  - 1 (DB2_BINARY)
  - 2 (DB2_CONVERT)
  - 3 (DB2_PASSTHRU)
`ibm_db2.i5_all_pconnect` int

  This option forces all connections to be persistent on IBM i. Basically, all db2_connect() calls transparently become db2_pconnect() calls. By default, this option is `0`. This option is provided as a convenience for cases where persistent connections are faster. It should not be used in new applications.

  - 0 - Persistent and non-persistent connections can be made.
  - 1 - All connections are persistent.
`ibm_db2.i5_allow_commit` int

  This option controls the transaction isolation mode used. By default, this option is `0`, so commitment control isn't used. This option can be overridden when connecting if the array key `i5_commit` is set in the connection options array passed to db2_connect() or db2_pconnect().

  - 0 - commitment control is not used
  - 1 - read uncommitted, dirty reads possible.
  - 2 - read committed, dirty reads are not possible.
  - 3 - repeatable read, dirty reads and non-repeatable reads are not possible
  - 4 - serializeable, dirty reads, non-repeatable reads, and phantoms are not possible
`ibm_db2.i5_blank_userid` int

  This controls if a blank user ID should be allowed on IBM i. By default, this option is `0`. Unlike `ibm_db2.i5_ignore_userid`, this option doesn't force all user IDs to be empty or change job behaviour, but simply allows an empty user ID to be passed, for connecting to Db2 as the current user.

  - 0 - Don't allow a blank user ID to be passed.
  - 1 - Allow a blank user ID to be passed.
`ibm_db2.i5_char_trim` int

  This option controls if the end of strings are trimmed on IBM i. Since many tables use fixed column sizes padded with spaces, this is provided as a convenience. By default, this option is `0`.

  - 0 - Columns are not trimmed.
  - 1 - Spaces at the end of returned character columns are removed.
`ibm_db2.i5_dbcs_alloc` int

  This options affects the internal buffer allocation strategy on IBM i. By default, this option is `0`. When this option is set, buffers are allocated with a much larger size, in case the database underestimates a string's size when converting between encodings. This option uses six times as much memory for buffers (to account for the largest possible UTF-8 sequences), but may be needed if truncated data is returned.

  - 0 - Minimum size buffers are allocated.
  - 1 - Larger size buffers are allocated.
`ibm_db2.i5_guard_profile` int

  This option checks if the database user profile was switched when connecting to a persistent database connection on IBM i, and if so, disconnects from the database. By default, this option is set to `0`.

  - 0 - Don't check for profile swaps.
  - 1 - Check for profile swaps and disconnect if so.
`ibm_db2.i5_log_verbose` int

  This option sets if SQL diagnostic messages like warnings and errors are always sent to the PHP error log on IBM i. Normally, only a brief message on failure is sent (such as "statement execute failed") to the PHP error log, as this option is set to `0` by default. Note that you can still and should call i.e. db2_stmt_errormsg() manually as part of checking if functions fail.

  - 0 - Only logs brief messages.
  - 1 - Logs the SQL diagnostic message in addition to the brief message.
`ibm_db2.i5_ignore_userid` int

  This option ignores the user ID when connecting to the database when running on IBM i, and runs SQL/CLI functionality inside of the PHP job, instead of a separate job. By default, this option is `0`. When enabled, it no longer uses a separate database server job, and always uses the current user profile for the database, ignoring the username and password passed to db2_connect() and db2_pconnect().

  - 0 - Uses the specified credentials, and use an SQL/CLI server job.
  - 1 - Always use blank credentials, and run SQL/CLI in the PHP job.
`ibm_db2.i5_job_sort` int

  Controls the job sort option on IBM i. By default, this option is `0`. This corresponds to the IBM i SQL/CLI `SQL_ATTR_CONN_SORT_SEQUENCE` attribute.

  - 0 - Uses the `*HEX` sort option, sorting by bytes.
  - 1 - Uses the job sort sequence set for the PHP job.
  - 2 - Uses the job sort sequence set for the database job.
`ibm_db2.i5_max_pconnect` int
  This will affect how many times a persistent connection can be reused when running on IBM i. By default, this is set to `0`, which means a persistent connection can always be reused. This option can help work around issues in a long-running database job (i.e. if a procedure is leaking memory), but is obviously not a long-term fix.
`ibm_db2.i5_override_ccsid` int
  The PASE CCSID to use for character conversions from EBCDIC on IBM i. By default, this is `0`, which will select the default PASE job CCSID, which comes from the PASE locale settings. For example, setting this to `1208` will use UTF-8. This should only be modified if the PASE job CCSID isn't the expected CCSID, and the locale cannot be modified. To learn more about CCSIDs on IBM i, consult the » IBM documentation. To learn how locales on IBM i PASE are mapped to CCSIDs, consult the » IBM documentation.
`ibm_db2.i5_sys_naming` int

  This option controls the naming mode when connecting to an IBM i system. By default, this option is `0`. The naming mode affects how names are resolved and the allowed syntax for names. When set to `0`, this uses periods to qualify names and uses the default library or user ID to resolve names. When set to `1`, this uses slashes to qualify names and uses the job library list to resolve names.

  - 0 - Uses the SQL naming mode ("SCHEMA.TABLE").
  - 1 - Uses the system naming mode ("LIBRARY/FILE").
  To learn more about naming modes on IBM i, consult the » IBM documentation.
`ibm_db2.i5_servermode-subsystem` string
  This option changes which subsystem database server jobs run under on IBM i. By default, this option is `null`, so jobs will run under the default subsystem for QSQSRVR jobs.
`ibm_db2.instance_name` string

  On Linux and UNIX operating systems, this option defines the name of the instance to use for cataloged database connections. By default, this option is `null`. If this option is set, its value overrides the DB2INSTANCE environment variable setting.

  This option is ignored on Windows operating systems.

## Ressource-Typen

The ibm_db2 extension returns connection resources, statement resources, and result set resources.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`DB2_BINARY` (int)
  Specifies that binary data shall be returned as is. This is the default mode.
`DB2_CONVERT` (int)
  Specifies that binary data shall be converted to a hexadecimal encoding and returned as an ASCII string.
`DB2_PASSTHRU` (int)
  Specifies that binary data shall be converted to a `null` value.
`DB2_SCROLLABLE` (int)
  Specifies a scrollable cursor for a statement resource. This mode enables random access to rows in a result set, but currently is supported only by IBM DB2 Universal Database.
`DB2_FORWARD_ONLY` (int)
  Specifies a forward-only cursor for a statement resource. This is the default cursor type and is supported on all database servers.
`DB2_PARAM_IN` (int)
  Specifies the PHP variable should be bound as an IN parameter for a stored procedure.
`DB2_PARAM_OUT` (int)
  Specifies the PHP variable should be bound as an OUT parameter for a stored procedure.
`DB2_PARAM_INOUT` (int)
  Specifies the PHP variable should be bound as an INOUT parameter for a stored procedure.
`DB2_PARAM_FILE` (int)
  Specifies that the column should be bound directly to a file for input.
`DB2_AUTOCOMMIT_ON` (int)
  Specifies that autocommit should be turned on.
`DB2_AUTOCOMMIT_OFF` (int)
  Specifies that autocommit should be turned off.
`DB2_DOUBLE` (int)
  Specifies that the variable should be bound as a DOUBLE, FLOAT, or REAL data type.
`DB2_LONG` (int)
  Specifies that the variable should be bound as a SMALLINT, INTEGER, or BIGINT data type.
`DB2_CHAR` (int)
  Specifies that the variable should be bound as a CHAR or VARCHAR data type.
`DB2_CASE_NATURAL` (int)
  Specifies that column names will be returned in their natural case.
`DB2_CASE_LOWER` (int)
  Specifies that column names will be returned in lower case.
`DB2_CASE_UPPER` (int)
  Specifies that column names will be returned in upper case.
`DB2_DEFERRED_PREPARE_ON` (int)
  Specifies that deferred prepare should be turned on for the specified statement resource.
`DB2_DEFERRED_PREPARE_OFF` (int)
  Specifies that deferred prepare should be turned off for the specified statement resource.

# IBM DB2 Funktionen

# db2_autocommit

(PECL ibm_db2 >= 1.0.0)

db2_autocommit — Returns or sets the AUTOCOMMIT state for a database connection

### Beschreibung

function db2_autocommit(resource `$connection`, int `$value` = ?): int|bool

Sets or gets the AUTOCOMMIT behavior of the specified connection resource.

### Parameter-Liste

`connection`
  A valid database connection resource variable as returned from db2_connect() or db2_pconnect().
`value`

  One of the following constants:

  `DB2_AUTOCOMMIT_OFF`
    Turns AUTOCOMMIT off.
  `DB2_AUTOCOMMIT_ON`
    Turns AUTOCOMMIT on.

### Rückgabewerte

When db2_autocommit() receives only the `connection` parameter, it returns the current state of AUTOCOMMIT for the requested connection as an integer value. A value of `DB2_AUTOCOMMIT_OFF` indicates that AUTOCOMMIT is off, while a value of `DB2_AUTOCOMMIT_ON` indicates that AUTOCOMMIT is on.

When db2_autocommit() receives both the `connection` parameter and `autocommit` parameter, it attempts to set the AUTOCOMMIT state of the requested connection to the corresponding state. Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Retrieving the AUTOCOMMIT value for a connection

In the following example, a connection which has been created with AUTOCOMMIT turned off is tested with the db2_autocommit() function.

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- AUTOCOMMIT is off.";
    } else {
        print "$ac -- AUTOCOMMIT is on.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0 -- AUTOCOMMIT is off.

Beispiel #2 Setting the AUTOCOMMIT value for a connection

In the following example, a connection which was initially created with AUTOCOMMIT turned off has its behavior changed to turn AUTOCOMMIT on.

    <?php
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);
    $conn = db2_connect($database, $user, $password, $options);

    // Turn AUTOCOMMIT on
    $rc = db2_autocommit($conn, DB2_AUTOCOMMIT_ON);
    if ($rc) {
        print "Turning AUTOCOMMIT on succeeded.\n";
    }

    // Check AUTOCOMMIT state
    $ac = db2_autocommit($conn);
    if ($ac == DB2_AUTOCOMMIT_OFF) {
        print "$ac -- AUTOCOMMIT is off.";
    } else {
        print "$ac -- AUTOCOMMIT is on.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Turning AUTOCOMMIT on succeeded.
    1 -- AUTOCOMMIT is on.

### Siehe auch

- db2_connect() - Returns a connection to a database
- db2_pconnect() - Returns a persistent connection to a database

# db2_bind_param

(PECL ibm_db2 >= 1.0.0)

db2_bind_param — Binds a PHP variable to an SQL statement parameter

### Beschreibung

function db2_bind_param(
resource `$stmt`,
int `$parameter_number`,
string `$variable_name`,
int `$parameter_type` = `DB2_PARAM_IN`,
int `$data_type` = 0,
int `$precision` = -1,
int `$scale` = 0
): bool

Binds a PHP variable to an SQL statement parameter in a statement resource returned by db2_prepare(). This function gives you more control over the parameter type, data type, precision, and scale for the parameter than simply passing the variable as part of the optional input array to db2_execute().

### Parameter-Liste

`stmt`
  A prepared statement returned from db2_prepare().
`parameter_number`
  Specifies the 1-indexed position of the parameter in the prepared statement.
`variable_name`
  A string specifying the name of the PHP variable to bind to the parameter specified by `parameter_number`.
`parameter_type`
  A constant specifying whether the PHP variable should be bound to the SQL parameter as an input parameter (`DB2_PARAM_IN`), an output parameter (`DB2_PARAM_OUT`), or as a parameter that accepts input and returns output (`DB2_PARAM_INOUT`). To avoid memory overhead, you can also specify `DB2_PARAM_FILE` to bind the PHP variable to the name of a file that contains large object (BLOB, CLOB, or DBCLOB) data.
`data_type`
  A constant specifying the SQL data type that the PHP variable should be bound as: one of `DB2_BINARY`, `DB2_CHAR`, `DB2_DOUBLE`, or `DB2_LONG` .
`precision`
  Specifies the precision with which the variable should be bound to the database. This parameter can also be used for retrieving XML output values from stored procedures. A non-negative value specifies the maximum size of the XML data that will be retrieved from the database. If this parameter is not used, a default of 1MB will be assumed for retrieving the XML output value from the stored procedure.
`scale`
  Specifies the scale with which the variable should be bound to the database.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Binding PHP variables to a prepared statement

The SQL statement in the following example uses two input parameters in the WHERE clause. We call db2_bind_param() to bind two PHP variables to the corresponding SQL parameters. Notice that the PHP variables do not have to be declared or assigned before the call to db2_bind_param(); in the example, `$lower_limit` is assigned a value before the call to db2_bind_param(), but `$upper_limit` is assigned a value after the call to db2_bind_param(). The variables must be bound and, for parameters that accept input, must have any value assigned, before calling db2_execute().

    <?php

    $sql = 'SELECT name, breed, weight FROM animals
        WHERE weight > ? AND weight < ?';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    // We can declare the variable before calling db2_bind_param()
    $lower_limit = 1;

    db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);

    // We can also declare the variable after calling db2_bind_param()
    $upper_limit = 15.0;

    if (db2_execute($stmt)) {
        while ($row = db2_fetch_array($stmt)) {
            print "{$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Pook, cat, 3.2
    Rickety Ride, goat, 9.7
    Peaches, dog, 12.3

Beispiel #2 Calling stored procedures with IN and OUT parameters

The stored procedure match_animal in the following example accepts three different parameters:

1. an input (IN) parameter that accepts the name of the first animal as input
2. an input-output (INOUT) parameter that accepts the name of the second animal as input and returns the string `TRUE` if an animal in the database matches that name
3. an output (OUT) parameter that returns the sum of the weight of the two identified animals

In addition, the stored procedure returns a result set consisting of the animals listed in alphabetic order starting at the animal corresponding to the input value of the first parameter and ending at the animal corresponding to the input value of the second parameter.

    <?php

    $sql = 'CALL match_animal(?, ?, ?)';
    $conn = db2_connect($database, $user, $password);
    $stmt = db2_prepare($conn, $sql);

    $name = "Peaches";
    $second_name = "Rickety Ride";
    $weight = 0;

    db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
    db2_bind_param($stmt, 2, "second_name", DB2_PARAM_INOUT);
    db2_bind_param($stmt, 3, "weight", DB2_PARAM_OUT);

    print "Values of bound parameters _before_ CALL:\n";
    print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

    if (db2_execute($stmt)) {
        print "Values of bound parameters _after_ CALL:\n";
        print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

        print "Results:\n";
        while ($row = db2_fetch_array($stmt)) {
            print "  {$row[0]}, {$row[1]}, {$row[2]}\n";
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Values of bound parameters _before_ CALL:
      1: Peaches 2: Rickety Ride 3: 0

    Values of bound parameters _after_ CALL:
      1: Peaches 2: TRUE 3: 22

    Results:
      Peaches, dog, 12.3
      Pook, cat, 3.2
      Rickety Ride, goat, 9.7

Beispiel #3 Inserting a binary large object (BLOB) directly from a file

The data for large objects are typically stored in files, such as XML documents or audio files. Rather than reading an entire file into a PHP variable, and then binding that PHP variable into an SQL statement, you can avoid some memory overhead by binding the file directly to the input parameter of your SQL statement. The following example demonstrates how to bind a file directly into a BLOB column.

    <?php
    $stmt = db2_prepare($conn, "INSERT INTO animal_pictures(picture) VALUES (?)");

    $picture = "/opt/albums/spook/grooming.jpg";
    $rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
    $rc = db2_execute($stmt);
    ?>

### Siehe auch

- db2_execute() - Executes a prepared SQL statement
- db2_prepare() - Prepares an SQL statement to be executed

# db2_client_info

(PECL ibm_db2 >= 1.1.1)

db2_client_info — Returns an object with properties that describe the DB2 database client

### Beschreibung

function db2_client_info(resource `$connection`): stdClass|false

This function returns an object with read-only properties that return information about the DB2 database client. The following table lists the DB2 client properties:

DB2 client properties
Property name | Return type | Description
--- | --- | ---
APPL_CODEPAGE | int | The application code page.
CONN_CODEPAGE | int | The code page for the current connection.
DATA_SOURCE_NAME | string | The data source name (DSN) used to create the current connection to the database.
DRIVER_NAME | string | The name of the library that implements the DB2 Call Level Interface (CLI) specification.
DRIVER_ODBC_VER | string | The version of ODBC that the DB2 client supports. This returns a string "MM.mm" where MM is the major version and mm is the minor version. The DB2 client always returns "03.51".
DRIVER_VER | string | The version of the client, in the form of a string "MM.mm.uuuu" where MM is the major version, mm is the minor version, and uuuu is the update. For example, "08.02.0001" represents major version 8, minor version 2, update 1.
ODBC_SQL_CONFORMANCE | string | The level of ODBC SQL grammar supported by the client: MINIMUM Supports the minimum ODBC SQL grammar. CORE Supports the core ODBC SQL grammar. EXTENDED Supports extended ODBC SQL grammar.
ODBC_VER | string | The version of ODBC that the ODBC driver manager supports. This returns a string "MM.mm.rrrr" where MM is the major version, mm is the minor version, and rrrr is the release. The DB2 client always returns "03.01.0000".

### Parameter-Liste

`connection`
  Specifies an active DB2 client connection.

### Rückgabewerte

Returns an object on a successful call,Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 A db2_client_info() example

To retrieve information about the client, you must pass a valid database connection resource to db2_client_info().

    <?php
    $conn = db2_connect( 'SAMPLE', 'db2inst1', 'ibmdb2' );
    $client = db2_client_info( $conn );

    if ($client) {
        echo "DRIVER_NAME: ";           var_dump( $client->DRIVER_NAME );
        echo "DRIVER_VER: ";            var_dump( $client->DRIVER_VER );
        echo "DATA_SOURCE_NAME: ";      var_dump( $client->DATA_SOURCE_NAME );
        echo "DRIVER_ODBC_VER: ";       var_dump( $client->DRIVER_ODBC_VER );
        echo "ODBC_VER: ";              var_dump( $client->ODBC_VER );
        echo "ODBC_SQL_CONFORMANCE: ";  var_dump( $client->ODBC_SQL_CONFORMANCE );
        echo "APPL_CODEPAGE: ";         var_dump( $client->APPL_CODEPAGE );
        echo "CONN_CODEPAGE: ";         var_dump( $client->CONN_CODEPAGE );
    }
    else {
        echo "Error retrieving client information.
         Perhaps your database connection was invalid.";
    }
    db2_close($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    DRIVER_NAME: string(8) "libdb2.a"
    DRIVER_VER: string(10) "08.02.0001"
    DATA_SOURCE_NAME: string(6) "SAMPLE"
    DRIVER_ODBC_VER: string(5) "03.51"
    ODBC_VER: string(10) "03.01.0000"
    ODBC_SQL_CONFORMANCE: string(8) "EXTENDED"
    APPL_CODEPAGE: int(819)
    CONN_CODEPAGE: int(819)

### Siehe auch

- db2_server_info() - Returns an object with properties that describe the DB2 database server

# db2_close

(PECL ibm_db2 >= 1.0.0)

db2_close — Closes a database connection

### Beschreibung

function db2_close(resource `$connection`): bool

This function closes a DB2 client connection created with db2_connect() and returns the corresponding resources to the database server.

If you attempt to close a persistent DB2 client connection created with db2_pconnect(), the close request is ignored and the persistent DB2 client connection remains available for the next caller.

### Parameter-Liste

`connection`
  Specifies an active DB2 client connection.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Closing a connection

The following example demonstrates a successful attempt to close a connection to an IBM DB2, Cloudscape, or Apache Derby database.

    <?php
    $conn = db2_connect('SAMPLE', 'db2inst1', 'ibmdb2');
    $rc = db2_close($conn);
    if ($rc) {
        echo "Connection was successfully closed.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Connection was successfully closed.

### Siehe auch

- db2_connect() - Returns a connection to a database
- db2_pclose() - Closes a persistent database connection
- db2_pconnect() - Returns a persistent connection to a database

# db2_column_privileges

(PECL ibm_db2 >= 1.0.0)

db2_column_privileges — Returns a result set listing the columns and associated privileges for a table

### Beschreibung

function db2_column_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Returns a result set listing the columns and associated privileges for a table.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema which contains the tables. To match all schemas, pass `null` or an empty string.
`table_name`
  The name of the table or view. To match all tables in the database, pass `null` or an empty string.
`column_name`
  The name of the column. To match all columns in the table, pass `null` or an empty string.

### Rückgabewerte

Returns a statement resource with a result set containing rows describing the column privileges for columns matching the specified parameters. The rows are composed of the following columns:

Column name | Description
--- | ---
TABLE_CAT | Name of the catalog. The value is NULL if this table does not have catalogs.
TABLE_SCHEM | Name of the schema.
TABLE_NAME | Name of the table or view.
COLUMN_NAME | Name of the column.
GRANTOR | Authorization ID of the user who granted the privilege.
GRANTEE | Authorization ID of the user to whom the privilege was granted.
PRIVILEGE | The privilege for the column.
IS_GRANTABLE | Whether the GRANTEE is permitted to grant this privilege to other users.

### Siehe auch

- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database

# db2_columns

(PECL ibm_db2 >= 1.0.0)

db2_columns — Returns a result set listing the columns and associated metadata for a table

### Beschreibung

function db2_columns(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$column_name` = `null`
): resource

Returns a result set listing the columns and associated metadata for a table.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema which contains the tables. To match all schemas, pass `'%'`.
`table_name`
  The name of the table or view. To match all tables in the database, pass `null` or an empty string.
`column_name`
  The name of the column. To match all columns in the table, pass `null` or an empty string.

### Rückgabewerte

Returns a statement resource with a result set containing rows describing the columns matching the specified parameters. The rows are composed of the following columns:

Column name | Description
--- | ---
TABLE_CAT | Name of the catalog. The value is NULL if this table does not have catalogs.
TABLE_SCHEM | Name of the schema.
TABLE_NAME | Name of the table or view.
COLUMN_NAME | Name of the column.
DATA_TYPE | The SQL data type for the column represented as an integer value.
TYPE_NAME | A string representing the data type for the column.
COLUMN_SIZE | An integer value representing the size of the column.
BUFFER_LENGTH | Maximum number of bytes necessary to store data from this column.
DECIMAL_DIGITS | The scale of the column, or `null` where scale is not applicable.
NUM_PREC_RADIX | An integer value of either `10` (representing an exact numeric data type), `2` (representing an approximate numeric data type), or `null` (representing a data type for which radix is not applicable).
NULLABLE | An integer value representing whether the column is nullable or not.
REMARKS | Description of the column.
COLUMN_DEF | Default value for the column.
SQL_DATA_TYPE | An integer value representing the size of the column.
SQL_DATETIME_SUB | Returns an integer value representing a datetime subtype code, or `null` for SQL data types to which this does not apply.
CHAR_OCTET_LENGTH | Maximum length in octets for a character data type column, which matches COLUMN_SIZE for single-byte character set data, or `null` for non-character data types.
ORDINAL_POSITION | The 1-indexed position of the column in the table.
IS_NULLABLE | A string value where 'YES' means that the column is nullable and 'NO' means that the column is not nullable.

### Siehe auch

- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database

# db2_commit

(PECL ibm_db2 >= 1.0.0)

db2_commit — Commits a transaction

### Beschreibung

function db2_commit(resource `$connection`): bool

Commits an in-progress transaction on the specified connection resource and begins a new transaction. PHP applications normally default to AUTOCOMMIT mode, so db2_commit() is not necessary unless AUTOCOMMIT has been turned off for the connection resource.

### Parameter-Liste

`connection`
  A valid database connection resource variable as returned from db2_connect() or db2_pconnect().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- db2_autocommit() - Returns or sets the AUTOCOMMIT state for a database connection
- db2_rollback() - Rolls back a transaction

# db2_conn_error

(PECL ibm_db2 >= 1.0.0)

db2_conn_error — Returns a string containing the SQLSTATE returned by the last connection attempt

### Beschreibung

function db2_conn_error(?resource `$connection` = `null`): string

db2_conn_error() returns an SQLSTATE value representing the reason the last attempt to connect to a database failed. As db2_connect() returns `false` in the event of a failed connection attempt, you do not pass any parameters to db2_conn_error() to retrieve the SQLSTATE value.

If, however, the connection was successful but becomes invalid over time, you can pass the `connection` parameter to retrieve the SQLSTATE value for a specific connection.

To learn what the SQLSTATE value means, you can issue the following command at a DB2 Command Line Processor prompt: `db2 '? `sqlstate-value`'`. You can also call db2_conn_errormsg() to retrieve an explicit error message and the associated SQLCODE value.

### Parameter-Liste

`connection`
  A connection resource associated with a connection that initially succeeded, but which over time became invalid.

### Rückgabewerte

Returns the SQLSTATE value resulting from a failed connection attempt. Returns an empty string if there is no error associated with the last connection attempt.

### Beispiele

Beispiel #1 Retrieving an SQLSTATE value for a failed connection attempt

The following example demonstrates how to return an SQLSTATE value after deliberately passing invalid parameters to db2_connect().

    <?php
    $conn = db2_connect('badname', 'baduser', 'badpassword');
    if (!$conn) {
        print "SQLSTATE value: " . db2_conn_error();
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    SQLSTATE value: 08001

### Siehe auch

- db2_conn_errormsg() - Returns the last connection error message and SQLCODE value
- db2_connect() - Returns a connection to a database
- db2_stmt_error() - Returns a string containing the SQLSTATE returned by an SQL statement
- db2_stmt_errormsg() - Returns a string containing the last SQL statement error message

# db2_conn_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_conn_errormsg — Returns the last connection error message and SQLCODE value

### Beschreibung

function db2_conn_errormsg(?resource `$connection` = `null`): string

db2_conn_errormsg() returns an error message and SQLCODE value representing the reason the last database connection attempt failed. As db2_connect() returns `false` in the event of a failed connection attempt, do not pass any parameters to db2_conn_errormsg() to retrieve the associated error message and SQLCODE value.

If, however, the connection was successful but becomes invalid over time, you can pass the `connection` parameter to retrieve the associated error message and SQLCODE value for a specific connection.

### Parameter-Liste

`connection`
  A connection resource associated with a connection that initially succeeded, but which over time became invalid.

### Rückgabewerte

Returns a string containing the error message and SQLCODE value resulting from a failed connection attempt. If there is no error associated with the last connection attempt, db2_conn_errormsg() returns an empty string.

### Beispiele

Beispiel #1 Retrieving the error message returned by a failed connection attempt

The following example demonstrates how to return an error message and SQLCODE value after deliberately passing invalid parameters to db2_connect().

    <?php
    $conn = db2_connect('badname', 'baduser', 'badpassword');
    if (!$conn) {
        print db2_conn_errormsg();
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    [IBM][CLI Driver] SQL1013N  The database alias name
    or database name "BADNAME" could not be found.  SQLSTATE=42705
     SQLCODE=-1013

### Siehe auch

- db2_conn_error() - Returns a string containing the SQLSTATE returned by the last connection attempt
- db2_connect() - Returns a connection to a database
- db2_stmt_error() - Returns a string containing the SQLSTATE returned by an SQL statement
- db2_stmt_errormsg() - Returns a string containing the last SQL statement error message

# db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — Returns a connection to a database

### Beschreibung

function db2_connect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Creates a new connection to an IBM DB2 Universal Database, IBM Cloudscape, or Apache Derby database.

### Parameter-Liste

`database`
  For a cataloged connection to a database, `database` represents the database alias in the DB2 client catalog.

  For an uncataloged connection to a database, `database` represents a complete connection string in the following format:

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Hinweis:

  > When connecting to Db2 on IBM i, the underlying system calls » SQLDriverConnect, which only accepts DSN, UID, and PWD for the » connection string. Like so:

  >     DSN=database;UID=username;PWD=password;

  where the parameters represent the following values:
  `database`
    The name of the database.
  `hostname`
    The hostname or IP address of the database server.
  `port`
    The TCP/IP port on which the database is listening for requests.
  `username`
    The username with which you are connecting to the database.
  `password`
    The password with which you are connecting to the database.
`username`
  The username with which you are connecting to the database. For uncataloged connections, you must pass a `null` value or empty string.
`password`
  The password with which you are connecting to the database. For uncataloged connections, you must pass a `null` value or empty string.
`options`

  An associative array of connection options that affect the behavior of the connection, where valid array keys include:

  `autocommit`
    Passing the `DB2_AUTOCOMMIT_ON` value turns autocommit on for this connection handle. Passing the `DB2_AUTOCOMMIT_OFF` value turns autocommit off for this connection handle.
  `DB2_ATTR_CASE`
    Passing the `DB2_CASE_NATURAL` value specifies that column names are returned in natural case. Passing the `DB2_CASE_LOWER` value specifies that column names are returned in lower case. Passing the `DB2_CASE_UPPER` value specifies that column names are returned in upper case.
  `CURSOR`
    Passing the `DB2_FORWARD_ONLY` value specifies a forward-only cursor for a statement resource. This is the default cursor type and is supported on all database servers. Passing the `DB2_SCROLLABLE` value specifies a scrollable cursor for a statement resource. This mode enables random access to rows in a result set, but currently is supported only by IBM DB2 Universal Database.

  The following new option is available in ibm_db2 version 1.7.0 and later.

  `trustedcontext`
    Passing the DB2_TRUSTED_CONTEXT_ENABLE value turns trusted context on for this connection handle. This parameter cannot be set using db2_set_option(). This key works only if the database is cataloged (even if the database is local), or if you specify the full DSN when you create the connection. To catalog the database, use following commands:

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
        db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
        db2 "update dbm cfg using svcename <SERVICENAME>"
        db2set DB2COMM=TCPIP

  The following new i5/OS options are available in ibm_db2 version 1.5.1 and later.

  `i5_lib`
    A character value that indicates the default library that will be used for resolving unqualified file references. This is not valid if the connection is using system naming mode.
  `i5_naming`
    `DB2_I5_NAMING_ON` value turns on DB2 UDB CLI iSeries system naming mode. Files are qualified using the slash (/) delimiter. Unqualified files are resolved using the library list for the job. `DB2_I5_NAMING_OFF` value turns off DB2 UDB CLI default naming mode, which is SQL naming. Files are qualified using the period (.) delimiter. Unqualified files are resolved using either the default library or the current user ID.
  `i5_commit`

    The `i5_commit` attribute should be set before the db2_connect(). If the value is changed after the connection has been established, and the connection is to a remote data source, the change does not take effect until the next successful db2_connect() for the connection handle.

    > Hinweis: The php.ini setting `ibm_db2.i5_allow_commit`==0 or `DB2_I5_TXN_NO_COMMIT` is the default, but may be overridden with the `i5_commit` option.

    `DB2_I5_TXN_NO_COMMIT` - Commitment control is not used. `DB2_I5_TXN_READ_UNCOMMITTED` - Dirty reads, nonrepeatable reads, and phantoms are possible. `DB2_I5_TXN_READ_COMMITTED` - Dirty reads are not possible. Nonrepeatable reads, and phantoms are possible. `DB2_I5_TXN_REPEATABLE_READ` - Dirty reads and nonrepeatable reads are not possible. Phantoms are possible. `DB2_I5_TXN_SERIALIZABLE` - Transactions are serializable. Dirty reads, non-repeatable reads, and phantoms are not possible
  `i5_query_optimize`
    `DB2_FIRST_IO` All queries are optimized with the goal of returning the first page of output as fast as possible. This goal works well when the output is controlled by a user who is most likely to cancel the query after viewing the first page of output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause. `DB2_ALL_IO` All queries are optimized with the goal of running the entire query to completion in the shortest amount of elapsed time. This is a good option when the output of a query is being written to a file or report, or the interface is queuing the output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause. This is the default.
  `i5_dbcs_alloc`
    `DB2_I5_DBCS_ALLOC_ON` value turns on DB2 6X allocation scheme for DBCS translation column size growth. `DB2_I5_DBCS_ALLOC_OFF` value turns off DB2 6X allocation scheme for DBCS translation column size growth. Note: php.ini setting `ibm_db2.i5_dbcs_alloc`==0 or `DB2_I5_DBCS_ALLOC_OFF` is the default, but may be overridden with the `i5_dbcs_alloc` option.
  `i5_date_fmt`
    `DB2_I5_FMT_ISO` - The International Organization for Standardization (ISO) date format yyyy-mm-dd is used. This is the default. `DB2_I5_FMT_USA` - The United States date format mm/dd/yyyy is used. `DB2_I5_FMT_EUR` - The European date format dd.mm.yyyy is used. `DB2_I5_FMT_JIS` - The Japanese Industrial Standard date format yyyy-mm-dd is used. `DB2_I5_FMT_MDY` - The date format mm/dd/yyyy is used. `DB2_I5_FMT_DMY` - The date format dd/mm/yyyy is used. `DB2_I5_FMT_YMD` - The date format yy/mm/dd is used. `DB2_I5_FMT_JUL` - The Julian date format yy/ddd is used. `DB2_I5_FMT_JOB` - The job default is used.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` - A slash ( / ) is used as the date separator. This is the default. `DB2_I5_SEP_DASH` - A dash ( - ) is used as the date separator. `DB2_I5_SEP_PERIOD` - A period ( . ) is used as the date separator. `DB2_I5_SEP_COMMA` - A comma ( , ) is used as the date separator. `DB2_I5_SEP_BLANK` - A blank is used as the date separator. `DB2_I5_SEP_JOB` - The job default is used
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` - The International Organization for Standardization (ISO) time format hh.mm.ss is used. This is the default. `DB2_I5_FMT_USA` - The United States time format hh:mmxx is used, where xx is AM or PM. `DB2_I5_FMT_EUR` - The European time format hh.mm.ss is used. `DB2_I5_FMT_JIS` - The Japanese Industrial Standard time format hh:mm:ss is used. `DB2_I5_FMT_HMS` - The hh:mm:ss format is used.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` - A colon ( : ) is used as the time separator. This is the default. `DB2_I5_SEP_PERIOD` - A period ( . ) is used as the time separator. `DB2_I5_SEP_COMMA` - A comma ( , ) is used as the time separator. `DB2_I5_SEP_BLANK` - A blank is used as the time separator. `DB2_I5_SEP_JOB` - The job default is used.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` - A period ( . ) is used as the decimal separator. This is the default. `DB2_I5_SEP_COMMA` - A comma ( , ) is used as the decimal separator. `DB2_I5_SEP_JOB` - The job default is used.

  The following new i5/OS option is available in ibm_db2 version 1.8.0 and later.

  `i5_libl`
    A character value that indicates the library list that will be used for resolving unqualified file references. Specify the library list elements separated by blanks 'i5_libl'=>"MYLIB YOURLIB ANYLIB".

    > Hinweis: `i5_libl` calls qsys2/qcmdexc('cmd',cmdlen), which is only available in i5/OS V5R4 and later.

### Rückgabewerte

Returns a connection handle resource if the connection attempt is successful. If the connection attempt fails, db2_connect() returns `false`.

### Beispiele

Beispiel #1 Creating a cataloged connection

Cataloged connections require you to have previously cataloged the target database through the DB2 Command Line Processor (CLP) or DB2 Configuration Assistant.

    <?php
    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        echo "Connection succeeded.";
        db2_close($conn);
    }
    else {
        echo "Connection failed.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Connection succeeded.

Beispiel #2 Creating an uncataloged connection

An uncataloged connection enables you to dynamically connect to a database.

    <?php
    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $hostname = 'localhost';
    $port = 50000;

    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
      "HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;";
    $conn = db2_connect($conn_string, '', '');

    if ($conn) {
        echo "Connection succeeded.";
        db2_close($conn);
    }
    else {
        echo "Connection failed.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Connection succeeded.

Beispiel #3 Creating a connection with autocommit off by default

Passing an array of options to db2_connect() enables you to modify the default behavior of the connection handle.

    <?php
    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

    $conn = db2_connect($database, $user, $password, $options);

    if ($conn) {
        echo "Connection succeeded.\n";
        if (db2_autocommit($conn)) {
             echo "Autocommit is on.\n";
        }
        else {
             echo "Autocommit is off.\n";
        }
        db2_close($conn);
    }
    else {
        echo "Connection failed.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Connection succeeded.
    Autocommit is off.

Beispiel #4 i5/OS best performance

To achieve best performance for your i5/OS ibm_db2 1.5.1 PHP application use the default host, userid, and password for your db2_connect().

    <?php
      $library = "ADC";
      $i5 = db2_connect("", "", "", array("i5_lib"=>"qsys2"));
      $result = db2_exec($i5,
           "select * from systables where table_schema = '$library'");
      while ($row = db2_fetch_both($result)) {
         echo $row['TABLE_NAME']."</br>";
      }
      db2_close($i5);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ANIMALS
    NAMES
    PICTURES

Beispiel #5 Using trusted context

The following example shows how to enable trusted context, switch users, and get the current user ID.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
      PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
    $options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_connect($dsn, "", "", $options);
    if($tc_conn) {
        echo "Explicit trusted connection succeeded.\n";

        if(db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            //Do some work as user 1.

            //Switching to trusted user.
            $parameters = array("trusted_user" => $tc_user,
              "trusted_password" => $tcuser_pass);
            $res = db2_set_option ($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            //Do more work as trusted user.

            if($userBefore != $userAfter) {
                echo "User has been switched." . "\n";
            }
        }

        db2_close($tc_conn);
    }
    else {
        echo "Explicit trusted connection failed.\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Explicit trusted connection succeeded.
    User has been switched.

### Siehe auch

- db2_close() - Closes a database connection
- db2_pconnect() - Returns a persistent connection to a database

# db2_cursor_type

(PECL ibm_db2 >= 1.0.0)

db2_cursor_type — Returns the cursor type used by a statement resource

### Beschreibung

function db2_cursor_type(resource `$stmt`): int

Returns the cursor type used by a statement resource. Use this to determine if you are working with a forward-only cursor or scrollable cursor.

### Parameter-Liste

`stmt`
  A valid statement resource.

### Rückgabewerte

Returns either `DB2_FORWARD_ONLY` if the statement resource uses a forward-only cursor or `DB2_SCROLLABLE` if the statement resource uses a scrollable cursor.

### Siehe auch

- db2_prepare() - Prepares an SQL statement to be executed

# db2_escape_string

(PECL ibm_db2 >= 1.6.0)

db2_escape_string — Used to escape certain characters

### Beschreibung

function db2_escape_string(string `$string_literal`): string

Prepends backslashes to special characters in the string argument.

### Parameter-Liste

`string_literal`
  The string that contains special characters that need to be modified. Characters that are prepended with a backslash are `\x00`, `\n`, `\r`, `\`, `'`, `"` and `\x1a`.

### Rückgabewerte

Returns `string_literal` with the special characters noted above prepended with backslashes.

### Beispiele

Beispiel #1 A db2_escape_string() example

Result of using the db2_escape_string() function

    <?php

    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $str[0] = "All characters: \x00 , \n , \r , \ , ' , \" , \x1a .";
        $str[1] = "Backslash (\). Single quote ('). Double quote (\")";
        $str[2] = "The NULL character \0 must be quoted as well";
        $str[3] = "Interesting characters: \x1a , \x00 .";
        $str[4] = "Nothing to quote";
        $str[5] = 200676;
        $str[6] = "";

        foreach( $str as $string ) {
            echo "db2_escape_string: " . db2_escape_string($string). "\n";
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    db2_escape_string: All characters: \0 , \n , \r , \\ , \' , \" , \Z .
    db2_escape_string: Backslash (\\). Single quote (\'). Double quote (\")
    db2_escape_string: The NULL character \0 must be quoted as well
    db2_escape_string: Interesting characters: \Z , \0 .
    db2_escape_string: Nothing to quote
    db2_escape_string: 200676
    db2_escape_string:

### Siehe auch

- db2_prepare() - Prepares an SQL statement to be executed

# db2_exec

(PECL ibm_db2 >= 1.0.0)

db2_exec — Executes an SQL statement directly

### Beschreibung

function db2_exec(resource `$connection`, string `$statement`, array `$options` = []): resource|false

Executes an SQL statement directly.

If you plan to interpolate PHP variables into the SQL statement, understand that this is one of the more common security exposures. Consider calling db2_prepare() to prepare an SQL statement with parameter markers for input values. Then you can call db2_execute() to pass in the input values and avoid SQL injection attacks.

If you plan to repeatedly issue the same SQL statement with different parameters, consider calling db2_prepare() and db2_execute() to enable the database server to reuse its access plan and increase the efficiency of your database access.

### Parameter-Liste

`connection`
  A valid database connection resource variable as returned from db2_connect() or db2_pconnect().
`statement`
  An SQL statement. The statement cannot contain any parameter markers.
`options`
  An associative array containing statement options. You can use this parameter to request a scrollable cursor on database servers that support this functionality. For a description of valid statement options, see db2_set_option().

### Rückgabewerte

Returns a statement resource if the SQL statement was issued successfully, or `false` if the database failed to execute the SQL statement.

### Beispiele

Beispiel #1 Creating a table with db2_exec()

The following example uses db2_exec() to issue a set of DDL statements in the process of creating a table.

    <?php
    $conn = db2_connect($database, $user, $password);

    // Create the test table
    $create = 'CREATE TABLE animals (id INTEGER, breed VARCHAR(32),
        name CHAR(16), weight DECIMAL(7,2))';
    $result = db2_exec($conn, $create);
    if ($result) {
        print "Successfully created the table.\n";
    }

    // Populate the test table
    $animals = array(
        array(0, 'cat', 'Pook', 3.2),
        array(1, 'dog', 'Peaches', 12.3),
        array(2, 'horse', 'Smarty', 350.0),
        array(3, 'gold fish', 'Bubbles', 0.1),
        array(4, 'budgerigar', 'Gizmo', 0.2),
        array(5, 'goat', 'Rickety Ride', 9.7),
        array(6, 'llama', 'Sweater', 150)
    );

    foreach ($animals as $animal) {
        $rc = db2_exec($conn, "INSERT INTO animals (id, breed, name, weight)
          VALUES ({$animal[0]}, '{$animal[1]}', '{$animal[2]}', {$animal[3]})");
        if ($rc) {
            print "Insert... ";
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Successfully created the table.
    Insert... Insert... Insert... Insert... Insert... Insert... Insert...

Beispiel #2 Executing a SELECT statement with a scrollable cursor

The following example demonstrates how to request a scrollable cursor for an SQL statement issued by db2_exec().

    <?php
    $conn = db2_connect($database, $user, $password);
    $sql = "SELECT name FROM animals
        WHERE weight < 10.0
        ORDER BY name";
    if ($conn) {
        require_once 'prepare.inc';
        $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
        while ($row = db2_fetch_array($stmt)) {
            print "$row[0]\n";
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Bubbles
    Gizmo
    Pook
    Rickety Ride

Beispiel #3 Returning XML data as an SQL ResultSet

The following example demonstrates how to work with documents stored in a XML column using the SAMPLE database. Using some pretty simple SQL/XML, this example returns some of the nodes in a XML document in an SQL ResultSet format that most users are familiar with.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = \'Kathy Smith\'
        ';
    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE\n");
    }
    db2_close($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Beispiel #4 Performing a "JOIN" with XML data

The following example works with documents stored in 2 different XML columns in the SAMPLE database. It creates 2 temporary tables from the XML documents from 2 different columns and returns an SQL ResultSet with information regarding shipping status for the customer.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
        SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
        FROM
        XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" BIGINT PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) as A,
        PURCHASEORDER AS B,
        XMLTABLE (
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
        COLUMNS
        "PONUM"  BIGINT PATH \'@PoNum\',
        "STATUS" VARCHAR (50) PATH \'@Status\'
        ) as C
        WHERE A.CID = B.CUSTID AND
        B.POID = C.PONUM AND
        A.NAME = \'Kathy Smith\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
    }

    db2_close($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1001     Kathy Smith     905-555-7258     5002     Shipped

Beispiel #5 Returning SQL data as part of a larger XML document

The following example works with a portion of the PRODUCT.DESCRIPTION documents in the SAMPLE database. It creates a XML document containing product description (XML data) and pricing info (SQL data).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
        for $prod in $doc/product
        where $prod/description/price < 10.00
        order by $prod/description/price ascending
        return(
            <promoitem> {
            $prod,
            <startdate> {$start} </startdate>,
            <enddate> {$end} </enddate>,
            <promoprice> {$promo} </promoprice>
            } </promoitem>
        )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = \'100-100-01\'
    ';

    $stmt = db2_exec($conn, $query);

    while($row = db2_fetch_array($stmt)){
        printf("$row[0]\n");
    }
    db2_close($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Siehe auch

- db2_execute() - Executes a prepared SQL statement
- db2_prepare() - Prepares an SQL statement to be executed

# db2_execute

(PECL ibm_db2 >= 1.0.0)

db2_execute — Executes a prepared SQL statement

### Beschreibung

function db2_execute(resource `$stmt`, array `$parameters` = []): bool

db2_execute() executes an SQL statement that was prepared by db2_prepare().

If the SQL statement returns a result set, for example, a SELECT statement or a CALL to a stored procedure that returns one or more result sets, you can retrieve a row as an array from the `stmt` resource using db2_fetch_assoc(), db2_fetch_both(), or db2_fetch_array(). Alternatively, you can use db2_fetch_row() to move the result set pointer to the next row and fetch a column at a time from that row with db2_result().

Refer to db2_prepare() for a brief discussion of the advantages of using db2_prepare() and db2_execute() rather than db2_exec().

### Parameter-Liste

`stmt`
  A prepared statement returned from db2_prepare().
`parameters`
  An array of input parameters matching any parameter markers contained in the prepared statement.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Preparing and executing an SQL statement with parameter markers

The following example prepares an INSERT statement that accepts four parameter markers, then iterates over an array of arrays containing the input values to be passed to db2_execute().

    <?php
    $pet = array(0, 'cat', 'Pook', 3.2);

    $insert = 'INSERT INTO animals (id, breed, name, weight)
        VALUES (?, ?, ?, ?)';

    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        $result = db2_execute($stmt, $pet);
        if ($result) {
            print "Successfully added new pet.";
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Successfully added new pet.

Beispiel #2 Calling a stored procedure with an OUT parameter

The following example prepares a CALL statement that accepts one parameter marker representing an OUT parameter, binds the PHP variable `$my_pets` to the parameter using db2_bind_param(), then issues db2_execute() to execute the CALL statement. After the CALL to the stored procedure has been made, the value of `$num_pets` changes to reflect the value returned by the stored procedure for that OUT parameter.

    <?php
    $num_pets = 0;
    $res = db2_prepare($conn, "CALL count_my_pets(?)");
    $rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT);
    $rc = db2_execute($res);
    print "I have $num_pets pets!";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    I have 7 pets!

Beispiel #3 Returning XML data as an SQL ResultSet

The following example demonstrates how to work with documents stored in a XML column using the SAMPLE database. Using some pretty simple SQL/XML, this example returns some of the nodes in a XML document in an SQL ResultSet format that most users are familiar with.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = 'SELECT * FROM XMLTABLE(
        XMLNAMESPACES (DEFAULT \'http://posample.org\'),
        \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
        COLUMNS
        "CID" VARCHAR (50) PATH \'@Cid\',
        "NAME" VARCHAR (50) PATH \'name\',
        "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
        ) AS T
        WHERE NAME = ?
        ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE\n");
        }
    }
    db2_close($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1000     Kathy Smith     416-555-1358
    1001     Kathy Smith     905-555-7258

Beispiel #4 Performing a "JOIN" with XML data

The following example works with documents stored in 2 different XML columns in the SAMPLE database. It creates 2 temporary tables from the XML documents from 2 different columns and returns an SQL ResultSet with information regarding shipping status for the customer.

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT A.CID, A.NAME, A.PHONE, C.PONUM, C.STATUS
    FROM
    XMLTABLE(
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("CUSTOMER.INFO")/customerinfo\'
    COLUMNS
    "CID" BIGINT PATH \'@Cid\',
    "NAME" VARCHAR (50) PATH \'name\',
    "PHONE" VARCHAR (50) PATH \'phone [ @type = "work"]\'
    ) as A,
    PURCHASEORDER AS B,
    XMLTABLE (
    XMLNAMESPACES (DEFAULT \'http://posample.org\'),
    \'db2-fn:xmlcolumn("PURCHASEORDER.PORDER")/PurchaseOrder\'
    COLUMNS
    "PONUM"  BIGINT PATH \'@PoNum\',
    "STATUS" VARCHAR (50) PATH \'@Status\'
    ) as C
    WHERE A.CID = B.CUSTID AND
        B.POID = C.PONUM AND
        A.NAME = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $name = 'Kathy Smith';

    if ($stmt) {
        db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_object($stmt)){
        printf("$row->CID     $row->NAME     $row->PHONE     $row->PONUM     $row->STATUS\n");
        }
    }

    db2_close($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1001     Kathy Smith     905-555-7258     5002     Shipped

Beispiel #5 Returning SQL data as part of a larger XML document

The following example works with a portion of the PRODUCT.DESCRIPTION documents in the SAMPLE database. It creates a XML document containing product description (XML data) and pricing info (SQL data).

    <?php

    $conn = db2_connect("SAMPLE", "db2inst1", "ibmdb2");

    $query = '
    SELECT
    XMLSERIALIZE(
    XMLQUERY(\'
        declare boundary-space strip;
        declare default element namespace "http://posample.org";
        <promoList> {
        for $prod in $doc/product
        where $prod/description/price < 10.00
        order by $prod/description/price ascending
        return(
            <promoitem> {
            $prod,
            <startdate> {$start} </startdate>,
            <enddate> {$end} </enddate>,
            <promoprice> {$promo} </promoprice>
                } </promoitem>
        )
        } </promoList>
    \' passing by ref DESCRIPTION AS "doc",
    PROMOSTART as "start",
    PROMOEND as "end",
    PROMOPRICE as "promo"
    RETURNING SEQUENCE)
    AS CLOB (32000))
    AS NEW_PRODUCT_INFO
    FROM PRODUCT
    WHERE PID = ?
    ';

    $stmt = db2_prepare($conn, $query);

    $pid = "100-100-01";

    if ($stmt) {
        db2_bind_param($stmt, 1, "pid", DB2_PARAM_IN);
        db2_execute($stmt);

        while($row = db2_fetch_array($stmt)){
        printf("$row[0]\n");
        }
    }

    db2_close($conn);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    <promoList xmlns="http://posample.org">
        <promoitem>
        <product pid="100-100-01">
            <description>
                <name>Snow Shovel, Basic 22 inch</name>
                <details>Basic Snow Shovel, 22 inches wide, straight handle with D-Grip</details>
                <price>9.99</price>
                <weight>1 kg</weight>
            </description>
        </product>
        <startdate>2004-11-19</startdate>
        <enddate>2004-12-19</enddate>
        <promoprice>7.25</promoprice>
        </promoitem>
    </promoList>

### Siehe auch

- db2_exec() - Executes an SQL statement directly
- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_prepare() - Prepares an SQL statement to be executed
- db2_result() - Returns a single column from a row in the result set

# db2_fetch_array

(PECL ibm_db2 >= 1.0.1)

db2_fetch_array — Returns an array, indexed by column position, representing a row in a result set

### Beschreibung

function db2_fetch_array(resource `$stmt`, int `$row_number` = -1): array|false

Returns an array, indexed by column position, representing a row in a result set. The columns are 0-indexed.

### Parameter-Liste

`stmt`
  A valid `stmt` resource containing a result set.
`row_number`
  Requests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.

### Rückgabewerte

Returns a 0-indexed array with column values indexed by the column position representing the next or requested row in the result set. Returns `false` if there are no rows left in the result set, or if the row requested by `row_number` does not exist in the result set.

### Beispiele

Beispiel #1 Iterating through a forward-only cursor

If you call db2_fetch_array() without a specific row number, it automatically retrieves the next row in the result set.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_array($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

Beispiel #2 Retrieving specific rows with db2_fetch_array() from a scrollable cursor

If your result set uses a scrollable cursor, you can call db2_fetch_array() with a specific row number. The following example retrieves every other row in the result set, starting with the second row.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_array($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row[1], $row[2], $row[3]);
        $i = $i + 2;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### Siehe auch

- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_result() - Returns a single column from a row in the result set

# db2_fetch_assoc

(PECL ibm_db2 >= 1.0.0)

db2_fetch_assoc — Returns an array, indexed by column name, representing a row in a result set

### Beschreibung

function db2_fetch_assoc(resource `$stmt`, int `$row_number` = -1): array|false

Returns an array, indexed by column name, representing a row in a result set.

### Parameter-Liste

`stmt`
  A valid `stmt` resource containing a result set.
`row_number`
  Requests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.

### Rückgabewerte

Returns an associative array with column values indexed by the column name representing the next or requested row in the result set. Returns `false` if there are no rows left in the result set, or if the row requested by `row_number` does not exist in the result set.

### Beispiele

Beispiel #1 Iterating through a forward-only cursor

If you call db2_fetch_assoc() without a specific row number, it automatically retrieves the next row in the result set.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_assoc($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

Beispiel #2 Retrieving specific rows with db2_fetch_assoc() from a scrollable cursor

If your result set uses a scrollable cursor, you can call db2_fetch_assoc() with a specific row number. The following example retrieves every other row in the result set, starting with the second row.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_assoc($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
        $i = $i + 2;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### Siehe auch

- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_result() - Returns a single column from a row in the result set

# db2_fetch_both

(PECL ibm_db2 >= 1.0.0)

db2_fetch_both — Returns an array, indexed by both column name and position, representing a row in a result set

### Beschreibung

function db2_fetch_both(resource `$stmt`, int `$row_number` = -1): array|false

Returns an array, indexed by both column name and position, representing a row in a result set. Note that the row returned by db2_fetch_both() requires more memory than the single-indexed arrays returned by db2_fetch_assoc() or db2_fetch_array().

### Parameter-Liste

`stmt`
  A valid `stmt` resource containing a result set.
`row_number`
  Requests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.

### Rückgabewerte

Returns an associative array with column values indexed by both the column name and 0-indexed column number. The array represents the next or requested row in the result set. Returns `false` if there are no rows left in the result set, or if the row requested by `row_number` does not exist in the result set.

### Beispiele

Beispiel #1 Iterating through a forward-only cursor

If you call db2_fetch_both() without a specific row number, it automatically retrieves the next row in the result set. The following example accesses columns in the returned array by both column name and by numeric index.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    $result = db2_execute($stmt);

    while ($row = db2_fetch_both($stmt)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row['ID'], $row[0], $row['BREED'], $row[3]);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

Beispiel #2 Retrieving specific rows with db2_fetch_both() from a scrollable cursor

If your result set uses a scrollable cursor, you can call db2_fetch_both() with a specific row number. The following example retrieves every other row in the result set, starting with the second row.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));

    $i=2;
    while ($row = db2_fetch_both($result, $i)) {
        printf ("%-5d %-16s %-32s %10s\n",
            $row[0], $row['NAME'], $row[2], $row['WEIGHT']);
        $i = $i + 2;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0     Pook             cat                                    3.20
    5     Rickety Ride     goat                                   9.70
    2     Smarty           horse                                350.00

### Siehe auch

- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_result() - Returns a single column from a row in the result set

# db2_fetch_object

(PECL ibm_db2 >= 1.0.0)

db2_fetch_object — Returns an object with properties representing columns in the fetched row

### Beschreibung

function db2_fetch_object(resource `$stmt`, int `$row_number` = -1): stdClass|false

Returns an object in which each property represents a column returned in the row fetched from a result set.

### Parameter-Liste

`stmt`
  A valid `stmt` resource containing a result set.
`row_number`
  Requests a specific 1-indexed row from the result set. Passing this parameter results in a PHP warning if the result set uses a forward-only cursor.

### Rückgabewerte

Returns an object representing a single row in the result set. The properties of the object map to the names of the columns in the result set.

The IBM DB2, Cloudscape, and Apache Derby database servers typically fold column names to upper-case, so the object properties will reflect that case.

If your SELECT statement calls a scalar function to modify the value of a column, the database servers return the column number as the name of the column in the result set. If you prefer a more descriptive column name and object property, you can use the AS clause to assign a name to the column in the result set.

Returns `false` if no row was retrieved.

### Beispiele

Beispiel #1 A db2_fetch_object() example

The following example issues a SELECT statement with a scalar function, RTRIM, that removes whitespace from the end of the column. Rather than creating an object with the properties "BREED" and "2", we use the AS clause in the SELECT statement to assign the name "name" to the modified column. The database server folds the column names to upper-case, resulting in an object with the properties "BREED" and "NAME".

    <?php
    $conn = db2_connect($database, $user, $password);

    $sql = "SELECT breed, RTRIM(name) AS name
        FROM animals
        WHERE id = ?";

    if ($conn) {
        $stmt = db2_prepare($conn, $sql);
        db2_execute($stmt, array(0));

        while ($pet = db2_fetch_object($stmt)) {
            echo "Come here, {$pet->NAME}, my little {$pet->BREED}!";
        }
        db2_close($conn);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Come here, Pook, my little cat!

### Siehe auch

- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_result() - Returns a single column from a row in the result set

# db2_fetch_row

(PECL ibm_db2 >= 1.0.0)

db2_fetch_row — Sets the result set pointer to the next row or requested row

### Beschreibung

function db2_fetch_row(resource `$stmt`, int `$row_number` = -1): bool

Use db2_fetch_row() to iterate through a result set, or to point to a specific row in a result set if you requested a scrollable cursor.

To retrieve individual fields from the result set, call the db2_result() function.

Rather than calling db2_fetch_row() and db2_result(), most applications will call one of db2_fetch_assoc(), db2_fetch_both(), or db2_fetch_array() to advance the result set pointer and return a complete row as an array.

### Parameter-Liste

`stmt`
  A valid `stmt` resource.
`row_number`
  With scrollable cursors, you can request a specific row number in the result set. Row numbering is 1-indexed.

### Rückgabewerte

Returns `true` if the requested row exists in the result set. Returns `false` if the requested row does not exist in the result set.

### Beispiele

Beispiel #1 Iterating through a result set

The following example demonstrates how to iterate through a result set with db2_fetch_row() and retrieve columns from the result set with db2_result().

    <?php
    $sql = 'SELECT name, breed FROM animals WHERE weight < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $name = db2_result($stmt, 0);
        $breed = db2_result($stmt, 1);
        print "$name $breed";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    cat Pook
    gold fish Bubbles
    budgerigar Gizmo
    goat Rickety Ride

Beispiel #2 i5/OS recommended alternatives to db2_fetch_row/db2_result

On i5/OS it is recommended that you use db2_fetch_both(), db2_fetch_array(), or db2_fetch_object() over db2_fetch_row()/db2_result(). In general db2_fetch_row()/db2_result() have more issues with various column types in `EBCDIC` to `ASCII` translation, including possible truncation in `DBCS` applications. You may also find the performance of db2_fetch_both(), db2_fetch_array(), and db2_fetch_object() to be superior to db2_fetch_row()/db2_result().

    <?php
      $conn = db2_connect("","","");
      $sql = 'SELECT SPECIFIC_SCHEMA, SPECIFIC_NAME, ROUTINE_SCHEMA, ROUTINE_NAME, ROUTINE_TYPE, ROUTINE_CREATED, ROUTINE_BODY, IN_PARMS, OUT_PARMS, INOUT_PARMS, PARAMETER_STYLE, EXTERNAL_NAME, EXTERNAL_LANGUAGE FROM QSYS2.SYSROUTINES FETCH FIRST 2 ROWS ONLY';
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_both($stmt)){
        echo "<br>db2_fetch_both {$row['SPECIFIC_NAME']} {$row['ROUTINE_CREATED']} {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_array($stmt)){
        echo "<br>db2_fetch_array {$row[1]}  {$row[5]}";
      }
      $stmt = db2_exec($conn, $sql, array('cursor' => DB2_SCROLLABLE));
      while ($row = db2_fetch_object($stmt)){
        echo "<br>db2_fetch_object {$row->SPECIFIC_NAME} {$row->ROUTINE_CREATED}";
      }
      db2_close($conn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    db2_fetch_both MATCH_ANIMAL 2006-08-25-17.10.23.775000 2006-08-25-17.10.23.775000
    db2_fetch_both MULTIRESULTS 2006-10-17-10.11.05.308000 2006-10-17-10.11.05.308000
    db2_fetch_array MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_array MULTIRESULTS 2006-10-17-10.11.05.308000
    db2_fetch_object MATCH_ANIMAL 2006-08-25-17.10.23.775000
    db2_fetch_object MULTIRESULTS 2006-10-17-10.11.05.308000

### Siehe auch

- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_result() - Returns a single column from a row in the result set

# db2_field_display_size

(PECL ibm_db2 >= 1.0.0)

db2_field_display_size — Returns the maximum number of bytes required to display a column

### Beschreibung

function db2_field_display_size(resource `$stmt`, int|string `$column`): int|false

Returns the maximum number of bytes required to display a column in a result set.

### Parameter-Liste

`stmt`
  Specifies a statement resource containing a result set.
`column`
  Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.

### Rückgabewerte

Returns an integer value with the maximum number of bytes required to display the specified column. If the column does not exist in the result set, db2_field_display_size() returns `false`.

### Siehe auch

- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set

# db2_field_name

(PECL ibm_db2 >= 1.0.0)

db2_field_name — Returns the name of the column in the result set

### Beschreibung

function db2_field_name(resource `$stmt`, int|string `$column`): string|false

Returns the name of the specified column in the result set.

### Parameter-Liste

`stmt`
  Specifies a statement resource containing a result set.
`column`
  Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.

### Rückgabewerte

Returns a string containing the name of the specified column. If the specified column does not exist in the result set, db2_field_name() returns `false`.

### Siehe auch

- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set

# db2_field_num

(PECL ibm_db2 >= 1.0.0)

db2_field_num — Returns the position of the named column in a result set

### Beschreibung

function db2_field_num(resource `$stmt`, int|string `$column`): int|false

Returns the position of the named column in a result set.

### Parameter-Liste

`stmt`
  Specifies a statement resource containing a result set.
`column`
  Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.

### Rückgabewerte

Returns an integer containing the 0-indexed position of the named column in the result set. If the specified column does not exist in the result set, db2_field_num() returns `false`.

### Siehe auch

- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set

# db2_field_precision

(PECL ibm_db2 >= 1.0.0)

db2_field_precision — Returns the precision of the indicated column in a result set

### Beschreibung

function db2_field_precision(resource `$stmt`, int|string `$column`): int|false

Returns the precision of the indicated column in a result set.

### Parameter-Liste

`stmt`
  Specifies a statement resource containing a result set.
`column`
  Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.

### Rückgabewerte

Returns an integer containing the precision of the specified column. If the specified column does not exist in the result set, db2_field_precision() returns `false`.

### Siehe auch

- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set

# db2_field_scale

(PECL ibm_db2 >= 1.0.0)

db2_field_scale — Returns the scale of the indicated column in a result set

### Beschreibung

function db2_field_scale(resource `$stmt`, int|string `$column`): int|false

Returns the scale of the indicated column in a result set.

### Parameter-Liste

`stmt`
  Specifies a statement resource containing a result set.
`column`
  Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.

### Rückgabewerte

Returns an integer containing the scale of the specified column. If the specified column does not exist in the result set, db2_field_scale() returns `false`.

### Siehe auch

- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set

# db2_field_type

(PECL ibm_db2 >= 1.0.0)

db2_field_type — Returns the data type of the indicated column in a result set

### Beschreibung

function db2_field_type(resource `$stmt`, int|string `$column`): string|false

Returns the data type of the indicated column in a result set.

### Parameter-Liste

`stmt`
  Specifies a statement resource containing a result set.
`column`
  Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.

### Rückgabewerte

Returns a string containing the defined data type of the specified column. If the specified column does not exist in the result set, db2_field_type() returns `false`.

### Siehe auch

- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set

# db2_field_width

(PECL ibm_db2 >= 1.0.0)

db2_field_width — Returns the width of the current value of the indicated column in a result set

### Beschreibung

function db2_field_width(resource `$stmt`, int|string `$column`): int|false

Returns the width of the current value of the indicated column in a result set. This is the maximum width of the column for a fixed-length data type, or the actual width of the column for a variable-length data type.

### Parameter-Liste

`stmt`
  Specifies a statement resource containing a result set.
`column`
  Specifies the column in the result set. This can either be an integer representing the 0-indexed position of the column, or a string containing the name of the column.

### Rückgabewerte

Returns an integer containing the width of the specified character or binary data type column in a result set. If the specified column does not exist in the result set, db2_field_width() returns `false`.

### Siehe auch

- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set

# db2_foreign_keys

(PECL ibm_db2 >= 1.0.0)

db2_foreign_keys — Returns a result set listing the foreign keys for a table

### Beschreibung

function db2_foreign_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

Returns a result set listing the foreign keys for a table.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema which contains the tables. If `schema` is `null`, db2_foreign_keys() matches the schema for the current connection.
`table_name`
  The name of the table.

### Rückgabewerte

Returns a statement resource with a result set containing rows describing the foreign keys for the specified table. The result set is composed of the following columns:

Column name | Description
--- | ---
PKTABLE_CAT | Name of the catalog for the table containing the primary key. The value is NULL if this table does not have catalogs.
PKTABLE_SCHEM | Name of the schema for the table containing the primary key.
PKTABLE_NAME | Name of the table containing the primary key.
PKCOLUMN_NAME | Name of the column containing the primary key.
FKTABLE_CAT | Name of the catalog for the table containing the foreign key. The value is NULL if this table does not have catalogs.
FKTABLE_SCHEM | Name of the schema for the table containing the foreign key.
FKTABLE_NAME | Name of the table containing the foreign key.
FKCOLUMN_NAME | Name of the column containing the foreign key.
KEY_SEQ | 1-indexed position of the column in the key.
UPDATE_RULE | Integer value representing the action applied to the foreign key when the SQL operation is UPDATE.
DELETE_RULE | Integer value representing the action applied to the foreign key when the SQL operation is DELETE.
FK_NAME | The name of the foreign key.
PK_NAME | The name of the primary key.
DEFERRABILITY | An integer value representing whether the foreign key deferrability is SQL_INITIALLY_DEFERRED, SQL_INITIALLY_IMMEDIATE, or SQL_NOT_DEFERRABLE.

### Siehe auch

- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database

# db2_free_result

(PECL ibm_db2 >= 1.0.0)

db2_free_result — Frees resources associated with a result set

### Beschreibung

function db2_free_result(resource `$stmt`): bool

Frees the system and database resources that are associated with a result set. These resources are freed implicitly when a script finishes, but you can call db2_free_result() to explicitly free the result set resources before the end of the script.

### Parameter-Liste

`stmt`
  A valid statement resource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- db2_free_stmt() - Frees resources associated with the indicated statement resource

# db2_free_stmt

(PECL ibm_db2 >= 1.0.0)

db2_free_stmt — Frees resources associated with the indicated statement resource

### Beschreibung

function db2_free_stmt(resource `$stmt`): bool

Frees the system and database resources that are associated with a statement resource. These resources are freed implicitly when a script finishes, but you can call db2_free_stmt() to explicitly free the statement resources before the end of the script.

### Parameter-Liste

`stmt`
  A valid statement resource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- db2_free_result() - Frees resources associated with a result set

# db2_get_option

(PECL ibm_db2 >= 1.6.0)

db2_get_option — Retrieves an option value for a statement resource or a connection resource

### Beschreibung

function db2_get_option(resource `$resource`, string `$option`): string|false

Retrieves the value of a specified option value for a statement resource or a connection resource.

### Parameter-Liste

`resource`
  A valid statement resource as returned from db2_prepare() or a valid connection resource as returned from db2_connect() or db2_pconnect().
`option`

  A valid statement or connection options. The following new options are available as of ibm_db2 version 1.6.0. They provide useful tracking information that can be set during execution with db2_get_option().

  > Hinweis: Prior versions of ibm_db2 do not support these new options. When the value in each option is being set, some servers might not handle the entire length provided and might truncate the value. To ensure that the data specified in each option is converted correctly when transmitted to a host system, use only the characters A through Z, 0 through 9, and the underscore (_) or period (.).

  `userid`

    `SQL_ATTR_INFO_USERID` - A pointer to a null-terminated character string used to identify the client user ID sent to the host database server when using DB2 Connect.

    > Hinweis: DB2 for z/OS and OS/390 servers support up to a length of 16 characters. This user-id is not to be confused with the authentication user-id, it is for identification purposes only and is not used for any authorization.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR` - A pointer to a null-terminated character string used to identify the client accounting string sent to the host database server when using DB2 Connect.

    > Hinweis: DB2 for z/OS and OS/390 servers support up to a length of 200 characters.

  `applname`

    `SQL_ATTR_INFO_APPLNAME` - A pointer to a null-terminated character string used to identify the client application name sent to the host database server when using DB2 Connect.

    > Hinweis: DB2 for z/OS and OS/390 servers support up to a length of 32 characters.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME` - A pointer to a null-terminated character string used to identify the client workstation name sent to the host database server when using DB2 Connect.

    > Hinweis: DB2 for z/OS and OS/390 servers support up to a length of 18 characters.

The following table specifies which options are compatible with the available resource types:

Resource-Parameter Matrix
Key | Value | Resource Type
--- | --- | ---
|  | Connection | Statement | Result Set
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Rückgabewerte

Returns the current setting of the connection attribute provided on success Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Setting and retrieving parameters through a connection resource

    <?php
    /* Database Connection Parameters */
    $database = 'SAMPLE';
    $user     = 'db2inst1';
    $password = 'ibmdb2';

    /* Obtain Connection Resource */
    $conn = db2_connect($database, $user, $password);

    echo "Client attributes passed through connection string:\n";

    /* Create the associative options array with valid key-value pairs */
    /* Assign the attributes through connection string */
    /* Access the options specified */
    $options1 = array('userid' => 'db2inst1');
    $conn1 = db2_connect($database, $user, $password, $options1);
    $val = db2_get_option($conn1, 'userid');
    echo $val . "\n";

    $options2 = array('acctstr' => 'account');
    $conn2 = db2_connect($database, $user, $password, $options2);
    $val = db2_get_option($conn2, 'acctstr');
    echo $val . "\n";

    $options3 = array('applname' => 'myapp');
    $conn3 = db2_connect($database, $user, $password, $options3);
    $val = db2_get_option($conn3, 'applname');
    echo $val . "\n";

    $options4 = array('wrkstnname' => 'workstation');
    $conn4 = db2_connect($database, $user, $password, $options4);
    $val = db2_get_option($conn4, 'wrkstnname');
    echo $val . "\n";

    echo "Client attributes passed post-connection:\n";

    /* Create the associative options array with valid key-value pairs */
    /* Assign the attributes after a connection is made */
    /* Access the options specified */
    $options5 = array('userid' => 'db2inst1');
    $conn5 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn5, $options5, 1);
    $val = db2_get_option($conn5, 'userid');
    echo $val . "\n";

    $options6 = array('acctstr' => 'account');
    $conn6 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn6, $options6, 1);
    $val = db2_get_option($conn6, 'acctstr');
    echo $val . "\n";

    $options7 = array('applname' => 'myapp');
    $conn7 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn7, $options7, 1);
    $val = db2_get_option($conn7, 'applname');
    echo $val . "\n";

    $options8 = array('wrkstnname' => 'workstation');
    $conn8 = db2_connect($database, $user, $password);
    $rc = db2_set_option($conn8, $options8, 1);
    $val = db2_get_option($conn8, 'wrkstnname');
    echo $val . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Client attributes passed through connection string:
    db2inst1
    account
    myapp
    workstation
    Client attributes passed post-connection:
    db2inst1
    account
    myapp
    workstation

### Siehe auch

- db2_connect() - Returns a connection to a database
- db2_cursor_type() - Returns the cursor type used by a statement resource
- db2_exec() - Executes an SQL statement directly
- db2_set_option() - Set options for connection or statement resources
- db2_pconnect() - Returns a persistent connection to a database
- db2_prepare() - Prepares an SQL statement to be executed

# db2_last_insert_id

(PECL ibm_db2 >= 1.7.1)

db2_last_insert_id — Returns the auto generated ID of the last insert query that successfully executed on this connection

### Beschreibung

function db2_last_insert_id(resource `$resource`): ?string

Returns the auto generated ID of the last insert query that successfully executed on this connection.

The result of this function is not affected by any of the following:

- A single row INSERT statement with a VALUES clause for a table without an identity column.
- A multiple row INSERT statement with a VALUES clause.
- An INSERT statement with a fullselect.
- A ROLLBACK TO SAVEPOINT statement.

### Parameter-Liste

`resource`
  A valid connection resource as returned from db2_connect() or db2_pconnect(). The value of this parameter cannot be a statement resource or result set resource.

### Rückgabewerte

Returns the auto generated ID of last insert query that successfully executed on this connection.

### Beispiele

Beispiel #1 A db2_last_insert_id() example

The following example shows how to return the auto generated ID of last insert query that successfully executed on this connection.

    <?php

    $database = "SAMPLE";
    $user = "db2inst1";
    $password = "ibmdb2";

    $conn = db2_connect($database, $user, $password);
    if($conn) {
        $createTable = "CREATE TABLE lastInsertID
          (id integer GENERATED BY DEFAULT AS IDENTITY, name varchar(20))";
        $insertTable = "INSERT INTO lastInsertID (name) VALUES ('Temp Name')";

        $stmt = @db2_exec($conn, $createTable);

        /* Checking for single row inserted. */
        $stmt = db2_exec($conn, $insertTable);
        $ret =  db2_last_insert_id($conn);
        if($ret) {
            echo "Last Insert ID is : " . $ret . "\n";
        } else {
            echo "No Last insert ID.\n";
        }

        db2_close($conn);
    }
    else {
        echo "Connection failed.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Last Insert ID is : 1

# db2_lob_read

(PECL ibm_db2 >= 1.6.0)

db2_lob_read — Gets a user defined size of LOB files with each invocation

### Beschreibung

function db2_lob_read(resource `$stmt`, int `$colnum`, int `$length`): string|false

Use db2_lob_read() to iterate through a specified column of a result set and retrieve a user defined size of LOB data.

### Parameter-Liste

`stmt`
  A valid `stmt` resource containing LOB data.
`colnum`
  A valid column number in the result set of the `stmt` resource.
`length`
  The size of the LOB data to be retrieved from the `stmt` resource.

### Rückgabewerte

Returns the amount of data the user specifies. Returns `false` if the data cannot be retrieved.

### Beispiele

Beispiel #1 Iterating through different types of data

    <?php

    /* Database Connection Parameters */
    $db = 'SAMPLE';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Obtain Connection Resource */
    $conn = db2_connect($db,$username,$password);

    if ($conn) {
        $drop = 'DROP TABLE clob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE clob_stream (id INTEGER, my_clob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO clob_stream (id,my_clob) VALUES (1, ?)");
        $variable = "THIS IS A CLOB TEST. THIS IS A CLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_clob FROM clob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Read LOB data */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Loop $i: $data\n";
            $i = $i + 1;
        }

        $drop = 'DROP TABLE blob_stream';
        $result = @db2_exec( $conn, $drop );

        $create = 'CREATE TABLE blob_stream (id INTEGER, my_blob CLOB)';
        $result = db2_exec( $conn, $create );

        $variable = "";
        $stmt = db2_prepare($conn, "INSERT INTO blob_stream (id,my_blob) VALUES (1, ?)");
        $variable = "THIS IS A BLOB TEST. THIS IS A BLOB TEST.";
        db2_bind_param($stmt, 1, "variable", DB2_PARAM_IN);
        db2_execute($stmt);

        $sql = "SELECT id,my_blob FROM blob_stream";
        $result = db2_prepare($conn, $sql);
        db2_execute($result);
        db2_fetch_row($result);
        $i = 0;
        /* Read LOB data */
        while ($data = db2_lob_read($result, 2, 6)) {
            echo "Loop $i: $data\n";
            $i = $i + 1;
        }
    } else {
        echo 'no connection: ' . db2_conn_errormsg();
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Loop 0: THIS I
    Loop 1: S A CL
    Loop 2: OB TES
    Loop 3: T. THI
    Loop 4: S IS A
    Loop 5:  CLOB
    Loop 6: TEST.
    Loop 0: THIS I
    Loop 1: S A BL
    Loop 2: OB TES
    Loop 3: T. THI
    Loop 4: S IS A
    Loop 5:  BLOB
    Loop 6: TEST.

### Siehe auch

- db2_bind_param() - Binds a PHP variable to an SQL statement parameter
- db2_exec() - Executes an SQL statement directly
- db2_execute() - Executes a prepared SQL statement
- db2_fetch_row() - Sets the result set pointer to the next row or requested row
- db2_prepare() - Prepares an SQL statement to be executed
- db2_result() - Returns a single column from a row in the result set

# db2_next_result

(PECL ibm_db2 >= 1.0.0)

db2_next_result — Requests the next result set from a stored procedure

### Beschreibung

function db2_next_result(resource `$stmt`): resource|false

A stored procedure can return zero or more result sets. While you handle the first result set in exactly the same way you would handle the results returned by a simple SELECT statement, to fetch the second and subsequent result sets from a stored procedure you must call the db2_next_result() function and return the result to a uniquely named PHP variable.

### Parameter-Liste

`stmt`
  A prepared statement returned from db2_exec() or db2_execute().

### Rückgabewerte

Returns a new statement resource containing the next result set if the stored procedure returned another result set. Returns `false` if the stored procedure did not return another result set.

### Beispiele

Beispiel #1 Calling a stored procedure that returns multiple result sets

In the following example, we call a stored procedure that returns three result sets. The first result set is fetched directly from the same statement resource on which we invoked the CALL statement, while the second and third result sets are fetched from statement resources returned from our calls to the db2_next_result() function.

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
      $stmt = db2_exec($conn, 'CALL multiResults()');

      print "Fetching first result set\n";
      while ($row = db2_fetch_array($stmt)) {
        var_dump($row);
      }

      print "\nFetching second result set\n";
      $res = db2_next_result($stmt);
      if ($res) {
        while ($row = db2_fetch_array($res)) {
          var_dump($row);
        }
      }

      print "\nFetching third result set\n";
      $res2 = db2_next_result($stmt);
      if ($res2) {
        while ($row = db2_fetch_array($res2)) {
          var_dump($row);
        }
      }

      db2_close($conn);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Fetching first result set
    array(2) {
      [0]=>
      string(16) "Bubbles         "
      [1]=>
      int(3)
    }
    array(2) {
      [0]=>
      string(16) "Gizmo           "
      [1]=>
      int(4)
    }

    Fetching second result set
    array(4) {
      [0]=>
      string(16) "Sweater         "
      [1]=>
      int(6)
      [2]=>
      string(5) "llama"
      [3]=>
      string(6) "150.00"
    }
    array(4) {
      [0]=>
      string(16) "Smarty          "
      [1]=>
      int(2)
      [2]=>
      string(5) "horse"
      [3]=>
      string(6) "350.00"
    }

    Fetching third result set
    array(1) {
      [0]=>
      string(16) "Bubbles         "
    }
    array(1) {
      [0]=>
      string(16) "Gizmo           "
    }

# db2_num_fields

(PECL ibm_db2 >= 1.0.0)

db2_num_fields — Returns the number of fields contained in a result set

### Beschreibung

function db2_num_fields(resource `$stmt`): int|false

Returns the number of fields contained in a result set. This is most useful for handling the result sets returned by dynamically generated queries, or for result sets returned by stored procedures, where your application cannot otherwise know how to retrieve and use the results.

### Parameter-Liste

`stmt`
  A valid statement resource containing a result set.

### Rückgabewerte

Returns an integer value representing the number of fields in the result set associated with the specified statement resource. Returns `false` if the statement resource is not a valid input value.

### Beispiele

Beispiel #1 Retrieving the number of fields in a result set

The following example demonstrates how to retrieve the number of fields returned in a result set.

    <?php

    $sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, $sql);
    $columns = db2_num_fields($stmt);

    echo "There are {$columns} columns in the result set.";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    There are 4 columns in the result set.

### Siehe auch

- db2_execute() - Executes a prepared SQL statement
- db2_field_display_size() - Returns the maximum number of bytes required to display a column
- db2_field_name() - Returns the name of the column in the result set
- db2_field_num() - Returns the position of the named column in a result set
- db2_field_precision() - Returns the precision of the indicated column in a result set
- db2_field_scale() - Returns the scale of the indicated column in a result set
- db2_field_type() - Returns the data type of the indicated column in a result set
- db2_field_width() - Returns the width of the current value of the indicated column in a result set

# db2_num_rows

(PECL ibm_db2 >= 1.0.0)

db2_num_rows — Returns the number of rows affected by an SQL statement

### Beschreibung

function db2_num_rows(resource `$stmt`): int|false

Returns the number of rows deleted, inserted, or updated by an SQL statement.

To determine the number of rows that will be returned by a SELECT statement, issue SELECT COUNT(*) with the same predicates as your intended SELECT statement and retrieve the value.

If your application logic checks the number of rows returned by a SELECT statement and branches if the number of rows is 0, consider modifying your application to attempt to return the first row with one of db2_fetch_assoc(), db2_fetch_both(), db2_fetch_array(), or db2_fetch_row(), and branch if the fetch function returns `false`.

> Hinweis: If you issue a SELECT statement using a scrollable cursor, db2_num_rows() returns the number of rows returned by the SELECT statement. However, the overhead associated with scrollable cursors significantly degrades the performance of your application, so if this is the only reason you are considering using scrollable cursors, you should use a forward-only cursor and either call SELECT COUNT(*) or rely on the bool return value of the fetch functions to achieve the equivalent functionality with much better performance.

### Parameter-Liste

`stmt`
  A valid `stmt` resource containing a result set.

### Rückgabewerte

Returns the number of rows affected by the last SQL statement issued by the specified statement handle,Bei einem Fehler wird `false` zurückgegeben.

# db2_pclose

(PECL ibm_db2 >= 1.8.0)

db2_pclose — Closes a persistent database connection

### Beschreibung

function db2_pclose(resource `$connection`): bool

This function closes a DB2 client connection created with db2_pconnect() and returns the corresponding resources to the database server.

> Hinweis: This function is only available on i5/OS in response to i5/OS system administration requests.

If you have a persistent DB2 client connection created with db2_pconnect(), you may use this function to close the connection. To avoid substantial connection performance penalties, this function should only be used in rare cases when the persistent connection has become unresponsive or the persistent connection will not be needed for a long period of time.

### Parameter-Liste

`connection`
  Specifies an active DB2 client connection.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Closing a persistent connection

The following example demonstrates a successful attempt to close a connection to an IBM DB2 i5/OS database.

    <?php
    $conn = db2_pconnect('', '', '');
    $rc = db2_pclose($conn);
    if ($rc) {
        echo "Connection was successfully closed.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Connection was successfully closed.

### Siehe auch

- db2_close() - Closes a database connection
- db2_pconnect() - Returns a persistent connection to a database

# db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — Returns a persistent connection to a database

### Beschreibung

function db2_pconnect(
string `$database`,
?string `$username`,
?string `$password`,
array `$options` = []
): resource|false

Returns a persistent connection to an IBM DB2 Universal Database, IBM Cloudscape, or Apache Derby database.

For more information on persistent connections, refer to Persistente Datenbankverbindungen.

Calling db2_close() on a persistent connection always returns `true`, but the underlying DB2 client connection remains open and waiting to serve the next matching db2_pconnect() request.

Users running version 1.9.0 or later of ibm_db2 should be aware that the extension will perform a transaction rollback on persistent connections at the end of a request, thus ending the transaction. This prevents the transaction block from carrying over to the next request which uses that connection if script execution ends before the transaction block does.

### Parameter-Liste

`database`
  For a cataloged connection to a database, `database` represents the database alias in the DB2 client catalog.

  For an uncataloged connection to a database, `database` represents a complete connection string in the following format:

      DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

  > Hinweis:

  > When connecting to Db2 on IBM i, the underlying system calls » SQLDriverConnect, which only accepts DSN, UID, and PWD for the » connection string. Like so:

  >     DSN=database;UID=username;PWD=password;

  where the parameters represent the following values:
  `database`
    The name of the database.
  `hostname`
    The hostname or IP address of the database server.
  `port`
    The TCP/IP port on which the database is listening for requests.
  `username`
    The username with which you are connecting to the database.
  `password`
    The password with which you are connecting to the database.
`username`
  The username with which you are connecting to the database.
`password`
  The password with which you are connecting to the database.
`options`

  An associative array of connection options that affect the behavior of the connection, where valid array keys include:

  `autocommit`
    Passing the `DB2_AUTOCOMMIT_ON` value turns autocommit on for this connection handle. Passing the `DB2_AUTOCOMMIT_OFF` value turns autocommit off for this connection handle.
  `DB2_ATTR_CASE`
    Passing the `DB2_CASE_NATURAL` value specifies that column names are returned in natural case. Passing the `DB2_CASE_LOWER` value specifies that column names are returned in lower case. Passing the `DB2_CASE_UPPER` value specifies that column names are returned in upper case.
  `CURSOR`
    Passing the `DB2_FORWARD_ONLY` value specifies a forward-only cursor for a statement resource. This is the default cursor type and is supported on all database servers. Passing the `DB2_SCROLLABLE` value specifies a scrollable cursor for a statement resource. This mode enables random access to rows in a result set, but currently is supported only by IBM DB2 Universal Database.

  The following new option is available in ibm_db2 version 1.7.0 and later.

  `trustedcontext`
    Passing the DB2_TRUSTED_CONTEXT_ENABLE value turns trusted context on for this connection handle. This parameter cannot be set using db2_set_option(). This key works only if the database is cataloged (even if the database is local), or if you specify the full DSN when you create the connection. To catalog the database, use following commands:

        db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
        db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
        db2 "update dbm cfg using svcename <SERVICENAME>"
        db2set DB2COMM=TCPIP

  The following new i5/OS options are available in ibm_db2 version 1.5.1 and later.

  Tipp

  Conflicting connection attributes used in conjunction with persistent connections can produce indeterminate results on i5/OS. Site policies should be establish for all applications using each persistent connection user profile. The default DB2_AUTOCOMMIT_ON is suggested when using persistent connections.

  `i5_lib`
    A character value that indicates the default library that will be used for resolving unqualified file references. This is not valid if the connection is using system naming mode.
  `i5_naming`
    `DB2_I5_NAMING_ON` value turns on DB2 UDB CLI iSeries system naming mode. Files are qualified using the slash (/) delimiter. Unqualified files are resolved using the library list for the job. `DB2_I5_NAMING_OFF` value turns off DB2 UDB CLI default naming mode, which is SQL naming. Files are qualified using the period (.) delimiter. Unqualified files are resolved using either the default library or the current user ID.
  `i5_commit`

    The `i5_commit` attribute should be set before the db2_pconnect(). If the value is changed after the connection has been established, and the connection is to a remote data source, the change does not take effect until the next successful db2_pconnect() for the connection handle.

    > Hinweis: The php.ini setting `ibm_db2.i5_allow_commit`==0 or `DB2_I5_TXN_NO_COMMIT` is the default, but may be overridden with the `i5_commit` option.

    `DB2_I5_TXN_NO_COMMIT` - Commitment control is not used. `DB2_I5_TXN_READ_UNCOMMITTED` - Dirty reads, nonrepeatable reads, and phantoms are possible. `DB2_I5_TXN_READ_COMMITTED` - Dirty reads are not possible. Nonrepeatable reads, and phantoms are possible. `DB2_I5_TXN_REPEATABLE_READ` - Dirty reads and nonrepeatable reads are not possible. Phantoms are possible. `DB2_I5_TXN_SERIALIZABLE` - Transactions are serializable. Dirty reads, non-repeatable reads, and phantoms are not possible
  `i5_query_optimize`
    `DB2_FIRST_IO` All queries are optimized with the goal of returning the first page of output as fast as possible. This goal works well when the output is controlled by a user who is most likely to cancel the query after viewing the first page of output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause. `DB2_ALL_IO` All queries are optimized with the goal of running the entire query to completion in the shortest amount of elapsed time. This is a good option when the output of a query is being written to a file or report, or the interface is queuing the output data. Queries coded with an OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause. This is the default.
  `i5_dbcs_alloc`
    `DB2_I5_DBCS_ALLOC_ON` value turns on DB2 6X allocation scheme for DBCS translation column size growth.

    `DB2_I5_DBCS_ALLOC_OFF` value turns off DB2 6X allocation scheme for DBCS translation column size growth.

    > Hinweis: The php.ini setting `ibm_db2.i5_dbcs_alloc`==0 or `DB2_I5_DBCS_ALLOC_OFF` is the default, but may be overridden with the `i5_dbcs_alloc` option.

  `i5_date_fmt`
    `DB2_I5_FMT_ISO` - The International Organization for Standardization (ISO) date format yyyy-mm-dd is used. This is the default. `DB2_I5_FMT_USA` - The United States date format mm/dd/yyyy is used. `DB2_I5_FMT_EUR` - The European date format dd.mm.yyyy is used. `DB2_I5_FMT_JIS` - The Japanese Industrial Standard date format yyyy-mm-dd is used. `DB2_I5_FMT_MDY` - The date format mm/dd/yyyy is used. `DB2_I5_FMT_DMY` - The date format dd/mm/yyyy is used. `DB2_I5_FMT_YMD` - The date format yy/mm/dd is used. `DB2_I5_FMT_JUL` - The Julian date format yy/ddd is used. `DB2_I5_FMT_JOB` - The job default is used.
  `i5_date_sep`
    `DB2_I5_SEP_SLASH` - A slash ( / ) is used as the date separator. This is the default. `DB2_I5_SEP_DASH` - A dash ( - ) is used as the date separator. `DB2_I5_SEP_PERIOD` - A period ( . ) is used as the date separator. `DB2_I5_SEP_COMMA` - A comma ( , ) is used as the date separator. `DB2_I5_SEP_BLANK` - A blank is used as the date separator. `DB2_I5_SEP_JOB` - The job default is used
  `i5_time_fmt`
    `DB2_I5_FMT_ISO` - The International Organization for Standardization (ISO) time format hh.mm.ss is used. This is the default. `DB2_I5_FMT_USA` - The United States time format hh:mmxx is used, where xx is AM or PM. `DB2_I5_FMT_EUR` - The European time format hh.mm.ss is used. `DB2_I5_FMT_JIS` - The Japanese Industrial Standard time format hh:mm:ss is used. `DB2_I5_FMT_HMS` - The hh:mm:ss format is used.
  `i5_time_sep`
    `DB2_I5_SEP_COLON` - A colon ( : ) is used as the time separator. This is the default. `DB2_I5_SEP_PERIOD` - A period ( . ) is used as the time separator. `DB2_I5_SEP_COMMA` - A comma ( , ) is used as the time separator. `DB2_I5_SEP_BLANK` - A blank is used as the time separator. `DB2_I5_SEP_JOB` - The job default is used.
  `i5_decimal_sep`
    `DB2_I5_SEP_PERIOD` - A period ( . ) is used as the decimal separator. This is the default. `DB2_I5_SEP_COMMA` - A comma ( , ) is used as the decimal separator. `DB2_I5_SEP_JOB` - The job default is used.

  The following new i5/OS option is available in ibm_db2 version 1.8.0 and later.

  `i5_libl`

    A character value that indicates the library list that will be used for resolving unqualified file references. Specify the library list elements separated by blanks 'i5_libl'=>"MYLIB YOURLIB ANYLIB".

    > Hinweis: i5_libl calls qsys2/qcmdexc('cmd',cmdlen), which is only available in i5/OS V5R4 and later.

### Rückgabewerte

Returns a connection handle resource if the connection attempt is successful. db2_pconnect() tries to reuse an existing connection resource that exactly matches the `database`, `username`, and `password` parameters. If the connection attempt fails, db2_pconnect() returns `false`.

### Changelog

Version | Beschreibung
--- | ---
PECL ibm_db2 1.9.0 | Active transactions within a persistent connection will be rolled back at the end of each request.
PECL ibm_db2 1.8.0 | The `i5_libl` option is available for i5/OS users.
PECL ibm_db2 1.7.0 | The `trustedcontext` option is available.
PECL ibm_db2 1.5.1 | The `i5_lib`, `i5_naming`, `i5_commit`, `i5_query_optimize`, `i5_dbcs_alloc`, `i5_date_fmt`, `i5_date_sep`, `i5_time_fmt`, `i5_time_sep` and `i5_decimal_sep` options are available for i5/OS users.

### Beispiele

Beispiel #1 A db2_pconnect() example

In the following example, the first call to db2_pconnect() returns a new persistent connection resource. The second call to db2_pconnect() returns a persistent connection resource that simply reuses the first persistent connection resource.

    <?php
    $database = 'SAMPLE';
    $user = 'db2inst1';
    $password = 'ibmdb2';

    $pconn = db2_pconnect($database, $user, $password);

    if ($pconn) {
        echo "Persistent connection succeeded.";
    }
    else {
        echo "Persistent connection failed.";
    }

    $pconn2 = db2_pconnect($database, $user, $password);
    if ($pconn) {
        echo "Second persistent connection succeeded.";
    }
    else {
        echo "Second persistent connection failed.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Persistent connection succeeded.
    Second persistent connection succeeded.

Beispiel #2 Using trusted context

The following example shows how to enable trusted context, switch users, and get the current user ID.

    <?php

    $database = "SAMPLE";
    $hostname = "localhost";
    $port = 50000;
    $authID = "db2inst1";
    $auth_pass = "ibmdb2";

    $tc_user = "tcuser";
    $tc_pass = "tcpassword";

    $dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;
      PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";
    $options = array ("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);

    $tc_conn = db2_pconnect($dsn, "", "", $options);
    if($tc_conn) {
        echo "Explicit trusted connection succeeded.\n";

        if(db2_get_option($tc_conn, "trustedcontext")) {
            $userBefore = db2_get_option($tc_conn, "trusted_user");

            //Do some work as user 1.

            //Switching to trusted user.
            $parameters = array("trusted_user" => $tc_user,
              "trusted_password" => $tcuser_pass);
            $res = db2_set_option ($tc_conn, $parameters, 1);

            $userAfter = db2_get_option($tc_conn, "trusted_user");
            //Do more work as trusted user.

            if($userBefore != $userAfter) {
                echo "User has been switched." . "\n";
            }
        }

        db2_close($tc_conn);
    }
    else {
        echo "Explicit trusted connection failed.\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Explicit trusted connection succeeded.
    User has been switched.

### Siehe auch

- db2_connect() - Returns a connection to a database

# db2_prepare

(PECL ibm_db2 >= 1.0.0)

db2_prepare — Prepares an SQL statement to be executed

### Beschreibung

function db2_prepare(resource `$connection`, string `$statement`, array `$options` = []): resource|false

db2_prepare() creates a prepared SQL statement which can include 0 or more parameter markers (`?` characters) representing parameters for input, output, or input/output. You can pass parameters to the prepared statement using db2_bind_param(), or for input values only, as an array passed to db2_execute().

There are three main advantages to using prepared statements in your application:

- Performance: when you prepare a statement, the database server creates an optimized access plan for retrieving data with that statement. Subsequently issuing the prepared statement with db2_execute() enables the statements to reuse that access plan and avoids the overhead of dynamically creating a new access plan for every statement you issue.
- Security: when you prepare a statement, you can include parameter markers for input values. When you execute a prepared statement with input values for placeholders, the database server checks each input value to ensure that the type matches the column definition or parameter definition.
- Advanced functionality: Parameter markers not only enable you to pass input values to prepared SQL statements, they also enable you to retrieve OUT and INOUT parameters from stored procedures using db2_bind_param().

### Parameter-Liste

`connection`
  A valid database connection resource variable as returned from db2_connect() or db2_pconnect().
`statement`
  An SQL statement, optionally containing one or more parameter markers..
`options`
  An associative array containing statement options. You can use this parameter to request a scrollable cursor on database servers that support this functionality. For a description of valid statement options, see db2_set_option().

### Rückgabewerte

Returns a statement resource if the SQL statement was successfully parsed and prepared by the database server. Returns `false` if the database server returned an error. You can determine which error was returned by calling db2_stmt_error() or db2_stmt_errormsg().

### Beispiele

Beispiel #1 Preparing and executing an SQL statement with parameter markers

The following example prepares an INSERT statement that accepts four parameter markers, then iterates over an array of arrays containing the input values to be passed to db2_execute().

    <?php
    $animals = array(
        array(0, 'cat', 'Pook', 3.2),
        array(1, 'dog', 'Peaches', 12.3),
        array(2, 'horse', 'Smarty', 350.0),
    );

    $insert = 'INSERT INTO animals (id, breed, name, weight)
        VALUES (?, ?, ?, ?)';
    $stmt = db2_prepare($conn, $insert);
    if ($stmt) {
        foreach ($animals as $animal) {
            $result = db2_execute($stmt, $animal);
        }
    }
    ?>

### Siehe auch

- db2_bind_param() - Binds a PHP variable to an SQL statement parameter
- db2_execute() - Executes a prepared SQL statement
- db2_stmt_error() - Returns a string containing the SQLSTATE returned by an SQL statement
- db2_stmt_errormsg() - Returns a string containing the last SQL statement error message

# db2_primary_keys

(PECL ibm_db2 >= 1.0.0)

db2_primary_keys — Returns a result set listing primary keys for a table

### Beschreibung

function db2_primary_keys(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`
): resource

Returns a result set listing the primary keys for a table.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema which contains the tables. If `schema` is `null`, db2_primary_keys() matches the schema for the current connection.
`table_name`
  The name of the table.

### Rückgabewerte

Returns a statement resource with a result set containing rows describing the primary keys for the specified table. The result set is composed of the following columns:

Column name | Description
--- | ---
TABLE_CAT | Name of the catalog for the table containing the primary key. The value is NULL if this table does not have catalogs.
TABLE_SCHEM | Name of the schema for the table containing the primary key.
TABLE_NAME | Name of the table containing the primary key.
COLUMN_NAME | Name of the column containing the primary key.
KEY_SEQ | 1-indexed position of the column in the key.
PK_NAME | The name of the primary key.

### Siehe auch

- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database

# db2_procedure_columns

(PECL ibm_db2 >= 1.0.0)

db2_procedure_columns — Returns a result set listing stored procedure parameters

### Beschreibung

function db2_procedure_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`,
?string `$parameter`
): resource

Returns a result set listing the parameters for one or more stored procedures.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema which contains the procedures. This parameter accepts a search pattern containing `_` and `%` as wildcards.
`procedure`
  The name of the procedure. This parameter accepts a search pattern containing `_` and `%` as wildcards.
`parameter`
  The name of the parameter. This parameter accepts a search pattern containing `_` and `%` as wildcards. If this parameter is `null`, all parameters for the specified stored procedures are returned.

### Rückgabewerte

Returns a statement resource with a result set containing rows describing the parameters for the stored procedures matching the specified parameters. The rows are composed of the following columns:

Column name | Description
--- | ---
PROCEDURE_CAT | The catalog that contains the procedure. The value is `null` if this table does not have catalogs.
PROCEDURE_SCHEM | Name of the schema that contains the stored procedure.
PROCEDURE_NAME | Name of the procedure.
COLUMN_NAME | Name of the parameter.
COLUMN_TYPE | An integer value representing the type of the parameter:
Return value | Parameter type
--- | ---
1 (SQL_PARAM_INPUT) | Input (IN) parameter.
2 (SQL_PARAM_INPUT_OUTPUT) | Input/output (INOUT) parameter.
3 (SQL_PARAM_OUTPUT) | Output (OUT) parameter.
DATA_TYPE | The SQL data type for the parameter represented as an integer value.
TYPE_NAME | A string representing the data type for the parameter.
COLUMN_SIZE | An integer value representing the size of the parameter.
BUFFER_LENGTH | Maximum number of bytes necessary to store data for this parameter.
DECIMAL_DIGITS | The scale of the parameter, or `null` where scale is not applicable.
NUM_PREC_RADIX | An integer value of either `10` (representing an exact numeric data type), `2` (representing an approximate numeric data type), or `null` (representing a data type for which radix is not applicable).
NULLABLE | An integer value representing whether the parameter is nullable or not.
REMARKS | Description of the parameter.
COLUMN_DEF | Default value for the parameter.
SQL_DATA_TYPE | An integer value representing the size of the parameter.
SQL_DATETIME_SUB | Returns an integer value representing a datetime subtype code, or `null` for SQL data types to which this does not apply.
CHAR_OCTET_LENGTH | Maximum length in octets for a character data type parameter, which matches COLUMN_SIZE for single-byte character set data, or `null` for non-character data types.
ORDINAL_POSITION | The 1-indexed position of the parameter in the CALL statement.
IS_NULLABLE | A string value where 'YES' means that the parameter accepts or returns `null` values and 'NO' means that the parameter does not accept or return `null` values.

### Siehe auch

- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database

# db2_procedures

(PECL ibm_db2 >= 1.0.0)

db2_procedures — Returns a result set listing the stored procedures registered in a database

### Beschreibung

function db2_procedures(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$procedure`
): resource

Returns a result set listing the stored procedures registered in a database.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema which contains the procedures. This parameter accepts a search pattern containing `_` and `%` as wildcards.
`procedure`
  The name of the procedure. This parameter accepts a search pattern containing `_` and `%` as wildcards.

### Rückgabewerte

Returns a statement resource with a result set containing rows describing the stored procedures matching the specified parameters. The rows are composed of the following columns:

Column name | Description
--- | ---
PROCEDURE_CAT | The catalog that contains the procedure. The value is `null` if this table does not have catalogs.
PROCEDURE_SCHEM | Name of the schema that contains the stored procedure.
PROCEDURE_NAME | Name of the procedure.
NUM_INPUT_PARAMS | Number of input (IN) parameters for the stored procedure.
NUM_OUTPUT_PARAMS | Number of output (OUT) parameters for the stored procedure.
NUM_RESULT_SETS | Number of result sets returned by the stored procedure.
REMARKS | Any comments about the stored procedure.
PROCEDURE_TYPE | Always returns `1`, indicating that the stored procedure does not return a return value.

### Siehe auch

- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database

# db2_result

(PECL ibm_db2 >= 1.0.0)

db2_result — Returns a single column from a row in the result set

### Beschreibung

function db2_result(resource `$stmt`, int|string `$column`): ?mixed

Use db2_result() to return the value of a specified column in the current row of a result set. You must call db2_fetch_row() before calling db2_result() to set the location of the result set pointer.

### Parameter-Liste

`stmt`
  A valid `stmt` resource.
`column`
  Either an integer mapping to the 0-indexed field in the result set, or a string matching the name of the column.

### Rückgabewerte

Returns the value of the requested field if the field exists in the result set. Returns `null` if the field does not exist, and issues a warning.

### Beispiele

Beispiel #1 A db2_result() example

The following example demonstrates how to iterate through a result set with db2_fetch_row() and retrieve columns from the result set with db2_result().

    <?php
    $sql = 'SELECT name, breed FROM animals WHERE weight < ?';
    $stmt = db2_prepare($conn, $sql);
    db2_execute($stmt, array(10));
    while (db2_fetch_row($stmt)) {
        $name = db2_result($stmt, 0);
        $breed = db2_result($stmt, 'BREED');
        print "$name $breed";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    cat Pook
    gold fish Bubbles
    budgerigar Gizmo
    goat Rickety Ride

### Siehe auch

- db2_fetch_array() - Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc() - Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both() - Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object() - Returns an object with properties representing columns in the fetched row
- db2_fetch_row() - Sets the result set pointer to the next row or requested row

# db2_rollback

(PECL ibm_db2 >= 1.0.0)

db2_rollback — Rolls back a transaction

### Beschreibung

function db2_rollback(resource `$connection`): bool

Rolls back an in-progress transaction on the specified connection resource and begins a new transaction. PHP applications normally default to AUTOCOMMIT mode, so db2_rollback() normally has no effect unless AUTOCOMMIT has been turned off for the connection resource.

### Parameter-Liste

`connection`
  A valid database connection resource variable as returned from db2_connect() or db2_pconnect().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Rolling back a DELETE statement

In the following example, we count the number of rows in a table, turn off AUTOCOMMIT mode on a database connection, delete all of the rows in the table and return the count of `0` to prove that the rows have been removed. We then issue db2_rollback() and return the updated count of rows in the table to show that the number is the same as before we issued the DELETE statement. The return to the original state of the table demonstrates that the roll back of the transaction succeeded.

    <?php
    $conn = db2_connect($database, $user, $password);

    if ($conn) {
        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Turn AUTOCOMMIT off
        db2_autocommit($conn, DB2_AUTOCOMMIT_OFF);

        // Delete all rows from ANIMALS
        db2_exec($conn, "DELETE FROM animals");

        $stmt = db2_exec($conn, "SELECT count(*) FROM animals");
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";

        // Roll back the DELETE statement
        db2_rollback( $conn );

        $stmt = db2_exec( $conn, "SELECT count(*) FROM animals" );
        $res = db2_fetch_array( $stmt );
        echo $res[0] . "\n";
        db2_close($conn);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    7
    0
    7

### Siehe auch

- db2_autocommit() - Returns or sets the AUTOCOMMIT state for a database connection
- db2_commit() - Commits a transaction

# db2_server_info

(PECL ibm_db2 >= 1.1.1)

db2_server_info — Returns an object with properties that describe the DB2 database server

### Beschreibung

function db2_server_info(resource `$connection`): stdClass|false

This function returns an object with read-only properties that return information about the IBM DB2, Cloudscape, or Apache Derby database server. The following table lists the database server properties:

Database server properties
Property name | Return type | Description
--- | --- | ---
DBMS_NAME | string | The name of the database server to which you are connected. For DB2 servers this is a combination of `DB2` followed by the operating system on which the database server is running.
DBMS_VER | string | The version of the database server, in the form of a string "MM.mm.uuuu" where MM is the major version, mm is the minor version, and uuuu is the update. For example, "08.02.0001" represents major version 8, minor version 2, update 1.
DB_CODEPAGE | int | The code page of the database to which you are connected.
DB_NAME | string | The name of the database to which you are connected.
DFT_ISOLATION | string | The default transaction isolation level supported by the server: UR Uncommitted read: changes are immediately visible by all concurrent transactions. CS Cursor stability: a row read by one transaction can be altered and committed by a second concurrent transaction. RS Read stability: a transaction can add or remove rows matching a search condition or a pending transaction. RR Repeatable read: data affected by pending transaction is not available to other transactions. NC No commit: any changes are visible at the end of a successful operation. Explicit commits and rollbacks are not allowed.
IDENTIFIER_QUOTE_CHAR | string | The character used to delimit an identifier.
INST_NAME | string | The instance on the database server that contains the database.
ISOLATION_OPTION | array | An array of the isolation options supported by the database server. The isolation options are described in the DFT_ISOLATION property.
KEYWORDS | array | An array of the keywords reserved by the database server.
LIKE_ESCAPE_CLAUSE | bool | `true` if the database server supports the use of `%` and `_` wildcard characters. `false` if the database server does not support these wildcard characters.
MAX_COL_NAME_LEN | int | Maximum length of a column name supported by the database server, expressed in bytes.
MAX_IDENTIFIER_LEN | int | Maximum length of an SQL identifier supported by the database server, expressed in characters.
MAX_INDEX_SIZE | int | Maximum size of columns combined in an index supported by the database server, expressed in bytes.
MAX_PROC_NAME_LEN | int | Maximum length of a procedure name supported by the database server, expressed in bytes.
MAX_ROW_SIZE | int | Maximum length of a row in a base table supported by the database server, expressed in bytes.
MAX_SCHEMA_NAME_LEN | int | Maximum length of a schema name supported by the database server, expressed in bytes.
MAX_STATEMENT_LEN | int | Maximum length of an SQL statement supported by the database server, expressed in bytes.
MAX_TABLE_NAME_LEN | int | Maximum length of a table name supported by the database server, expressed in bytes.
NON_NULLABLE_COLUMNS | bool | `true` if the database server supports columns that can be defined as NOT NULL, `false` if the database server does not support columns defined as NOT NULL.
PROCEDURES | bool | `true` if the database server supports the use of the CALL statement to call stored procedures, `false` if the database server does not support the CALL statement.
SPECIAL_CHARS | string | A string containing all of the characters other than a-Z, 0-9, and underscore that can be used in an identifier name.
SQL_CONFORMANCE | string | The level of conformance to the ANSI/ISO SQL-92 specification offered by the database server: ENTRY Entry-level SQL-92 compliance. FIPS127 FIPS-127-2 transitional compliance. FULL Full level SQL-92 compliance. INTERMEDIATE Intermediate level SQL-92 compliance.

### Parameter-Liste

`connection`
  Specifies an active DB2 client connection.

### Rückgabewerte

Returns an object on a successful call,Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 A db2_server_info() example

To retrieve information about the server, you must pass a valid database connection resource to db2_server_info().

    <?php

    $conn = db2_connect('sample', 'db2inst1', 'ibmdb2');

    $server = db2_server_info( $conn );

    if ($server) {
        echo "DBMS_NAME: ";                 var_dump( $server->DBMS_NAME );
        echo "DBMS_VER: ";                  var_dump( $server->DBMS_VER );
        echo "DB_CODEPAGE: ";               var_dump( $server->DB_CODEPAGE );
        echo "DB_NAME: ";                   var_dump( $server->DB_NAME );
        echo "INST_NAME: ";                 var_dump( $server->INST_NAME );
        echo "SPECIAL_CHARS: ";             var_dump( $server->SPECIAL_CHARS );
        echo "KEYWORDS: ";                  var_dump( sizeof($server->KEYWORDS) );
        echo "DFT_ISOLATION: ";             var_dump( $server->DFT_ISOLATION );
        echo "ISOLATION_OPTION: ";
        $il = '';
        foreach( $server->ISOLATION_OPTION as $opt )
        {
           $il .= $opt." ";
        }
        var_dump( $il );
        echo "SQL_CONFORMANCE: ";           var_dump( $server->SQL_CONFORMANCE );
        echo "PROCEDURES: ";                var_dump( $server->PROCEDURES );
        echo "IDENTIFIER_QUOTE_CHAR: ";     var_dump( $server->IDENTIFIER_QUOTE_CHAR );
        echo "LIKE_ESCAPE_CLAUSE: ";        var_dump( $server->LIKE_ESCAPE_CLAUSE );
        echo "MAX_COL_NAME_LEN: ";          var_dump( $server->MAX_COL_NAME_LEN );
        echo "MAX_ROW_SIZE: ";              var_dump( $server->MAX_ROW_SIZE );
        echo "MAX_IDENTIFIER_LEN: ";        var_dump( $server->MAX_IDENTIFIER_LEN );
        echo "MAX_INDEX_SIZE: ";            var_dump( $server->MAX_INDEX_SIZE );
        echo "MAX_PROC_NAME_LEN: ";         var_dump( $server->MAX_PROC_NAME_LEN );
        echo "MAX_SCHEMA_NAME_LEN: ";       var_dump( $server->MAX_SCHEMA_NAME_LEN );
        echo "MAX_STATEMENT_LEN: ";         var_dump( $server->MAX_STATEMENT_LEN );
        echo "MAX_TABLE_NAME_LEN: ";        var_dump( $server->MAX_TABLE_NAME_LEN );
        echo "NON_NULLABLE_COLUMNS: ";      var_dump( $server->NON_NULLABLE_COLUMNS );

        db2_close($conn);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    DBMS_NAME: string(9) "DB2/LINUX"
    DBMS_VER: string(10) "08.02.0000"
    DB_CODEPAGE: int(1208)
    DB_NAME: string(6) "SAMPLE"
    INST_NAME: string(8) "db2inst1"
    SPECIAL_CHARS: string(2) "@#"
    KEYWORDS: int(179)
    DFT_ISOLATION: string(2) "CS"
    ISOLATION_OPTION: string(12) "UR CS RS RR "
    SQL_CONFORMANCE: string(7) "FIPS127"
    PROCEDURES: bool(true)
    IDENTIFIER_QUOTE_CHAR: string(1) """
    LIKE_ESCAPE_CLAUSE: bool(true)
    MAX_COL_NAME_LEN: int(30)
    MAX_ROW_SIZE: int(32677)
    MAX_IDENTIFIER_LEN: int(18)
    MAX_INDEX_SIZE: int(1024)
    MAX_PROC_NAME_LEN: int(128)
    MAX_SCHEMA_NAME_LEN: int(30)
    MAX_STATEMENT_LEN: int(2097152)
    MAX_TABLE_NAME_LEN: int(128)
    NON_NULLABLE_COLUMNS: bool(true)

### Siehe auch

- db2_client_info() - Returns an object with properties that describe the DB2 database client

# db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — Set options for connection or statement resources

### Beschreibung

function db2_set_option(resource `$resource`, array `$options`, int `$type`): bool

Sets options for a statement resource or a connection resource. You cannot set options for result set resources.

### Parameter-Liste

`resource`
  A valid statement resource as returned from db2_prepare() or a valid connection resource as returned from db2_connect() or db2_pconnect().
`options`

  An associative array containing valid statement or connection options. This parameter can be used to change autocommit values, cursor types (scrollable or forward), and to specify the case of the column names (lower, upper, or natural) that will appear in a result set.

  `autocommit`
    Passing `DB2_AUTOCOMMIT_ON` turns autocommit on for the specified connection resource. Passing `DB2_AUTOCOMMIT_OFF` turns autocommit off for the specified connection resource.
  `cursor`
    Passing `DB2_FORWARD_ONLY` specifies a forward-only cursor for a statement resource. This is the default cursor type, and is supported by all database servers. Passing `DB2_SCROLLABLE` specifies a scrollable cursor for a statement resource. Scrollable cursors enable result set rows to be accessed in non-sequential order, but are only supported by IBM DB2 Universal Database databases.
  `binmode`
    Passing `DB2_BINARY` specifies that binary data will be returned as is. This is the default mode. This is the equivalent of setting `ibm_db2.binmode=1` in php.ini. Passing `DB2_CONVERT` specifies that binary data will be converted to hexadecimal encoding, and will be returned as such. This is the equivalent of setting `ibm_db2.binmode=2` in php.ini. Passing `DB2_PASSTHRU` specifies that binary data will be converted to `null`. This is the equivalent of setting `ibm_db2.binmode=3` in php.ini.
  `db2_attr_case`
    Passing `DB2_CASE_LOWER` specifies that column names of the result set are returned in lower case. Passing `DB2_CASE_UPPER` specifies that column names of the result set are returned in upper case. Passing `DB2_CASE_NATURAL` specifies that column names of the result set are returned in natural case.
  `deferred_prepare`
    Passing `DB2_DEFERRED_PREPARE_ON` turns deferred prepare on for the specified statement resource. Passing `DB2_DEFERRED_PREPARE_OFF` turns deferred prepare off for the specified statement resource.

  The following new i5/OS options are available in ibm_db2 version 1.5.1 and later. These options apply only when running PHP and ibm_db2 natively on i5 systems.

  `i5_fetch_only`
    `DB2_I5_FETCH_ON` - Cursors are read-only and cannot be used for positioned updates or deletes. This is the default unless `SQL_ATTR_FOR_FETCH_ONLY` environment has been set to `SQL_FALSE`. `DB2_I5_FETCH_OFF` - Cursors can be used for positioned updates and deletes.

  The following new option is available in ibm_db2 version 1.8.0 and later.

  `rowcount`
    `DB2_ROWCOUNT_PREFETCH_ON` - Client can request the full row count prior to fetching, which means that db2_num_rows() returns the number of rows selected even when a `ROLLFORWARD_ONLY` cursor is used. `DB2_ROWCOUNT_PREFETCH_OFF` - Client cannot request the full row count prior to fetching.

  The following new options are available in ibm_db2 version 1.7.0 and later.

  `trusted_user`
    To switch the user to a trusted user, pass the User ID (String) of the trusted user as the value of this key. This option can be set on a connection resource only. To use this option, trusted context must be enabled on the connection resource.
  `trusted_password`
    The password (String) that corresponds to the user specified by the trusted_user key.

  The following new options are available in ibm_db2 version 1.6.0 and later. These options provide useful tracking information that can be accessed during execution with db2_get_option().

  > Hinweis: When the value in each option is being set, some servers might not handle the entire length provided and might truncate the value. To ensure that the data specified in each option is converted correctly when transmitted to a host system, use only the characters A through Z, 0 through 9, and the underscore (_) or period (.).

  `userid`

    `SQL_ATTR_INFO_USERID` - A pointer to a null-terminated character string used to identify the client user ID sent to the host database server when using DB2 Connect.

    > Hinweis: DB2 for z/OS and OS/390 servers support up to a length of 16 characters. This user-id is not to be confused with the authentication user-id, it is for identification purposes only and is not used for any authorization.

  `acctstr`

    `SQL_ATTR_INFO_ACCTSTR` - A pointer to a null-terminated character string used to identify the client accounting string sent to the host database server when using DB2 Connect.

    > Hinweis: DB2 for z/OS and OS/390 servers support up to a length of 200 characters.

  `applname`

    `SQL_ATTR_INFO_APPLNAME` - A pointer to a null-terminated character string used to identify the client application name sent to the host database server when using DB2 Connect.

    > Hinweis: DB2 for z/OS and OS/390 servers support up to a length of 32 characters.

  `wrkstnname`

    `SQL_ATTR_INFO_WRKSTNNAME` - A pointer to a null-terminated character string used to identify the client workstation name sent to the host database server when using DB2 Connect.

    > Hinweis: DB2 for z/OS and OS/390 servers support up to a length of 18 characters.

`type`
  An integer value that specifies the type of resource that was passed into the function. The type of resource and this value must correspond. Passing `1` as the value specifies that a connection resource has been passed into the function. Passing any integer not equal to `1` as the value specifies that a statement resource has been passed into the function.

The following table specifies which options are compatible with the available resource types:

Resource-Parameter Matrix
Key | Value | Resource Type
--- | --- | ---
|  | Connection | Statement | Result Set
autocommit | `DB2_AUTOCOMMIT_ON` | X | - | -
autocommit | `DB2_AUTOCOMMIT_OFF` | X | - | -
cursor | `DB2_SCROLLABLE` | - | X | -
cursor | `DB2_FORWARD_ONLY` | - | X | -
binmode | `DB2_BINARY` | X | X | -
binmode | `DB2_CONVERT` | X | X | -
binmode | `DB2_PASSTHRU` | X | X | -
db2_attr_case | `DB2_CASE_LOWER` | X | X | -
db2_attr_case | `DB2_CASE_UPPER` | X | X | -
db2_attr_case | `DB2_CASE_NATURAL` | X | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_ON` | - | X | -
deferred_prepare | `DB2_DEFERRED_PREPARE_OFF` | - | X | -
i5_fetch_only | `DB2_I5_FETCH_ON` | - | X | -
i5_fetch_only | `DB2_I5_FETCH_OFF` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_ON` | - | X | -
rowcount | `DB2_ROWCOUNT_PREFETCH_OFF` | - | X | -
trusted_user | `<USER NAME> (String)` | X | - | -
trusted_password | `<PASSWORD> (String)` | X | - | -
userid | `SQL_ATTR_INFO_USERID` | X | X | -
acctstr | `SQL_ATTR_INFO_ACCTSTR` | X | X | -
applname | `SQL_ATTR_INFO_APPLNAME` | X | X | -
wrkstnname | `SQL_ATTR_INFO_WRKSTNNAME` | X | X | -

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Setting one parameter with a connection resource

    <?php
    /* Database Connection Parameters */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Connection String */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtain Connection Resource */
    $conn = db2_connect($conn_string, '', '');

    /* Create the associative options array with valid key-value pairs */
    $options = array('autocommit' => DB2_AUTOCOMMIT_ON);

    /* Call the function using the correct resource, options array, and type values */
    $result = db2_set_option($conn, $options, 1);

    /* Check if all options could be set correctly */
    if($result)
    {
      echo 'Options Set Successfully';
    }
    else
    {
      echo 'Could Not Set Options';
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Options Set Successfully

Beispiel #2 Setting multiple parameters with a connection resource

    <?php
    /* Database Connection Parameters */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Connection String */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtain Connection Resource */
    $conn = db2_connect($conn_string, '', '');

    /* Create the associative options array with valid key-value pairs */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                        'binmode' => DB2_PASSTHRU,
                  'db2_attr_case' => DB2_CASE_UPPER,
                         'cursor' => DB2_SCROLLABLE);

    /* Call the function using the correct resource, options array, and type values */
    $result = db2_set_option($conn, $options, 1);

    /* Check if all options could be set correctly */
    if($result)
    {
      echo 'Options Set Successfully';
    }
    else
    {
      echo 'Could Not Set Options';
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Options Set Successfully

Beispiel #3 Setting multiple parameters with an invalid key

    <?php
    /* Database Connection Parameters */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Connection String */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtain Connection Resource */
    $conn = db2_connect($conn_string, '', '');

    /* Create the associative options array with valid key-value pairs */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                 'MY_INVALID_KEY' => DB2_PASSTHRU,
                  'db2_attr_case' => DB2_CASE_UPPER,
                         'cursor' => DB2_SCROLLABLE);

    /* Call the function using the correct resource, options array, and type values */
    $result = db2_set_option($conn, $options, 1);

    /* Check if all options could be set correctly */
    if($result)
    {
      echo 'Options Set Successfully';
    }
    else
    {
      echo 'Could Not Set Options';
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Could Not Set Options

Beispiel #4 Setting multiple parameters with an invalid value

    <?php
    /* Database Connection Parameters */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Connection String */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtain Connection Resource */
    $conn = db2_connect($conn_string, '', '');

    /* Create the associative options array with valid key-value pairs */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                        'binmode' => 'INVALID_VALUE',
                  'db2_attr_case' => DB2_CASE_UPPER,
                         'cursor' => DB2_SCROLLABLE);

    /* Call the function using the correct resource, options array, and type values */
    $result = db2_set_option($conn, $options, 1);

    /* Check if all options could be set correctly */
    if($result)
    {
      echo 'Options Set Successfully';
    }
    else
    {
      echo 'Could Not Set Options';
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Could Not Set Options

Beispiel #5 Setting multiple parameters with a connection resource and the wrong type

    <?php
    /* Database Connection Parameters */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Connection String */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtain Connection Resource */
    $conn = db2_connect($conn_string, '', '');

    /* Create the associative options array with valid key-value pairs */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                        'binmode' => DB2_PASSTHRU,
                  'db2_attr_case' => DB2_CASE_UPPER,
                         'cursor' => DB2_SCROLLABLE);

    /* Call the function using the correct resource, options array, and the wrong type value */
    $result = db2_set_option($conn, $options, 2);

    /* Check if all options could be set correctly */
    if($result)
    {
      echo 'Options Set Successfully';
    }
    else
    {
      echo 'Could Not Set Options';
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Could Not Set Options

Beispiel #6 Setting multiple parameters with the wrong resource

    <?php
    /* Database Connection Parameters */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Connection String */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtain Connection Resource */
    $conn = db2_connect($conn_string, '', '');

    /* Create the associative options array with valid key-value pairs */
    $options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                        'binmode' => DB2_PASSTHRU,
                  'db2_attr_case' => DB2_CASE_UPPER,
                         'cursor' => DB2_SCROLLABLE);

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

    /* Call the function using the wrong resource, and the correct options array, and type values */
    $result = db2_set_option($stmt, $options, 1);

    /* Check if all options could be set correctly */
    if($result)
    {
      echo 'Options Set Successfully';
    }
    else
    {
      echo 'Could Not Set Options';
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Could Not Set Options

Beispiel #7 Putting it all together

    <?php
    /* Database Connection Parameters */
    $database = 'SAMPLE';
    $hostname = 'localhost';
    $port = 50000;
    $protocol = 'TCPIP';
    $username = 'db2inst1';
    $password = 'ibmdb2';

    /* Connection String */
    $conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
    $conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
    $conn_string .= "UID=$username;PWD=$password;";

    /* Obtain Connection Resource */
    $conn = db2_connect($conn_string, '', '');

    /* Create the associative options array with valid key-value pairs */
    $options = array('db2_attr_case' => DB2_CASE_LOWER,
                            'cursor' => DB2_SCROLLABLE);

    $stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

    /* Call the function using the correct resource, options array, and type values */
    $option_result = db2_set_option($stmt, $options, 2);
    $result = db2_execute($stmt, array('000130', '000140'));

    /* Get Row 2 before Row 1 since Scrollable Cursor */
    print_r(db2_fetch_assoc($stmt, 2));
    print '<br /><br />';
    print_r(db2_fetch_assoc($stmt, 1));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [empno] => 000140
        [firstnme] => HEATHER
        [midinit] => A
        [lastname] => NICHOLLS
        [workdept] => C01
        [phoneno] => 1793
        [hiredate] => 1976-12-15
        [job] => ANALYST
        [edlevel] => 18
        [sex] => F
        [birthdate] => 1946-01-19
        [salary] => 28420.00
        [bonus] => 600.00
        [comm] => 2274.00
    )

    Array
    (
        [empno] => 000130
        [firstnme] => DELORES
        [midinit] => M
        [lastname] => QUINTANA
        [workdept] => C01
        [phoneno] => 4578
        [hiredate] => 1971-07-28
        [job] => ANALYST
        [edlevel] => 16
        [sex] => F
        [birthdate] => 1925-09-15
        [salary] => 23800.00
        [bonus] => 500.00
        [comm] => 1904.00
    )

Beispiel #8 i5/OS cursors are read-only

    <?php
      $conn = db2_connect("", "", "", array("i5_lib"=>"nobody"));
      $stmt = db2_prepare($conn, 'select * from names where first = ?');
      $name = "first2";
      db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
      $options = array("i5_fetch_only"=>DB2_I5_FETCH_ON);
      db2_set_option($stmt,$options,0);
      if (db2_execute($stmt)) {
        while ($row = db2_fetch_array($stmt)) {
          echo "{$row[0]} {$row[1]}";
        }
      }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    first2 last2

### Siehe auch

- db2_connect() - Returns a connection to a database
- db2_pconnect() - Returns a persistent connection to a database
- db2_exec() - Executes an SQL statement directly
- db2_prepare() - Prepares an SQL statement to be executed
- db2_cursor_type() - Returns the cursor type used by a statement resource

# db2_special_columns

(PECL ibm_db2 >= 1.0.0)

db2_special_columns — Returns a result set listing the unique row identifier columns for a table

### Beschreibung

function db2_special_columns(
resource `$connection`,
?string `$qualifier`,
string `$schema`,
string `$table_name`,
int `$scope`
): resource

Returns a result set listing the unique row identifier columns for a table.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema which contains the tables.
`table_name`
  The name of the table.
`scope`

  Integer value representing the minimum duration for which the unique row identifier is valid. This can be one of the following values:

  Integer value | SQL constant | Description
  --- | --- | ---
  0 | SQL_SCOPE_CURROW | Row identifier is valid only while the cursor is positioned on the row.
  1 | SQL_SCOPE_TRANSACTION | Row identifier is valid for the duration of the transaction.
  2 | SQL_SCOPE_SESSION | Row identifier is valid for the duration of the connection.

### Rückgabewerte

Returns a statement resource with a result set containing rows with unique row identifier information for a table. The rows are composed of the following columns:

Column name | Description
--- | ---
SCOPE |
Integer value | SQL constant | Description
--- | --- | ---
0 | SQL_SCOPE_CURROW | Row identifier is valid only while the cursor is positioned on the row.
1 | SQL_SCOPE_TRANSACTION | Row identifier is valid for the duration of the transaction.
2 | SQL_SCOPE_SESSION | Row identifier is valid for the duration of the connection.
COLUMN_NAME | Name of the unique column.
DATA_TYPE | SQL data type for the column.
TYPE_NAME | Character string representation of the SQL data type for the column.
COLUMN_SIZE | An integer value representing the size of the column.
BUFFER_LENGTH | Maximum number of bytes necessary to store data from this column.
DECIMAL_DIGITS | The scale of the column, or `null` where scale is not applicable.
NUM_PREC_RADIX | An integer value of either `10` (representing an exact numeric data type), `2` (representing an approximate numeric data type), or `null` (representing a data type for which radix is not applicable).
PSEUDO_COLUMN | Always returns 1.

### Siehe auch

- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database

# db2_statistics

(PECL ibm_db2 >= 1.0.0)

db2_statistics — Returns a result set listing the index and statistics for a table

### Beschreibung

function db2_statistics(
resource `$connection`,
?string `$qualifier`,
?string `$schema`,
string `$table_name`,
bool `$unique`
): resource

Returns a result set listing the index and statistics for a table.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema that contains the targeted table. If this parameter is `null`, the statistics and indexes are returned for the schema of the current user.
`table_name`
  The name of the table.
`unique`
  When `unique` is `true`, the information for all indexes in the table are returned. Otherwise, only the information for unique indexes in the table are returned.

### Rückgabewerte

Returns a statement resource with a result set containing rows describing the statistics and indexes for the base tables matching the specified parameters. The rows are composed of the following columns:

Column name | Description
--- | ---
TABLE_CAT | The catalog that contains the table. The value is `null` if this table does not have catalogs.
TABLE_SCHEM | Name of the schema that contains the table.
TABLE_NAME | Name of the table.
NON_UNIQUE | An integer value representing whether the index prohibits unique values, or whether the row represents statistics on the table itself:
Return value | Parameter type
--- | ---
0 (SQL_FALSE) | The index allows duplicate values.
1 (SQL_TRUE) | The index values must be unique.
`null` | This row is statistics information for the table itself.
INDEX_QUALIFIER | A string value representing the qualifier that would have to be prepended to INDEX_NAME to fully qualify the index.
INDEX_NAME | A string representing the name of the index.
TYPE | An integer value representing the type of information contained in this row of the result set:
Return value | Parameter type
--- | ---
0 (SQL_TABLE_STAT) | The row contains statistics about the table itself.
1 (SQL_INDEX_CLUSTERED) | The row contains information about a clustered index.
2 (SQL_INDEX_HASH) | The row contains information about a hashed index.
3 (SQL_INDEX_OTHER) | The row contains information about a type of index that is neither clustered nor hashed.
ORDINAL_POSITION | The 1-indexed position of the column in the index. `null` if the row contains statistics information about the table itself.
COLUMN_NAME | The name of the column in the index. `null` if the row contains statistics information about the table itself.
ASC_OR_DESC | `A` if the column is sorted in ascending order, `D` if the column is sorted in descending order, `null` if the row contains statistics information about the table itself.
CARDINALITY | If the row contains information about an index, this column contains an integer value representing the number of unique values in the index. If the row contains information about the table itself, this column contains an integer value representing the number of rows in the table.
PAGES | If the row contains information about an index, this column contains an integer value representing the number of pages used to store the index. If the row contains information about the table itself, this column contains an integer value representing the number of pages used to store the table.
FILTER_CONDITION | Always returns `null`.

### Siehe auch

- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database
- db2_tables() - Returns a result set listing the tables and associated metadata in a database

# db2_stmt_error

(PECL ibm_db2 >= 1.0.0)

db2_stmt_error — Returns a string containing the SQLSTATE returned by an SQL statement

### Beschreibung

function db2_stmt_error(?resource `$stmt` = `null`): string

Returns a string containing the SQLSTATE value returned by an SQL statement.

If you do not pass a statement resource as an argument to db2_stmt_error(), the driver returns the SQLSTATE value associated with the last attempt to return a statement resource, for example, from db2_prepare() or db2_exec().

To learn what the SQLSTATE value means, you can issue the following command at a DB2 Command Line Processor prompt: `db2 '? `sqlstate-value`'`. You can also call db2_stmt_errormsg() to retrieve an explicit error message and the associated SQLCODE value.

### Parameter-Liste

`stmt`
  A valid statement resource.

### Rückgabewerte

Returns a string containing an SQLSTATE value.

### Siehe auch

- db2_conn_error() - Returns a string containing the SQLSTATE returned by the last connection attempt
- db2_conn_errormsg() - Returns the last connection error message and SQLCODE value
- db2_stmt_errormsg() - Returns a string containing the last SQL statement error message

# db2_stmt_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_stmt_errormsg — Returns a string containing the last SQL statement error message

### Beschreibung

function db2_stmt_errormsg(?resource `$stmt` = `null`): string

Returns a string containing the last SQL statement error message.

If you do not pass a statement resource as an argument to db2_stmt_errormsg(), the driver returns the error message associated with the last attempt to return a statement resource, for example, from db2_prepare() or db2_exec().

### Parameter-Liste

`stmt`
  A valid statement resource.

### Rückgabewerte

Returns a string containing the error message and SQLCODE value for the last error that occurred issuing an SQL statement.

### Siehe auch

- db2_conn_error() - Returns a string containing the SQLSTATE returned by the last connection attempt
- db2_conn_errormsg() - Returns the last connection error message and SQLCODE value
- db2_stmt_error() - Returns a string containing the SQLSTATE returned by an SQL statement

# db2_table_privileges

(PECL ibm_db2 >= 1.0.0)

db2_table_privileges — Returns a result set listing the tables and associated privileges in a database

### Beschreibung

function db2_table_privileges(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`
): resource

Returns a result set listing the tables and associated privileges in a database.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema which contains the tables. This parameter accepts a search pattern containing `_` and `%` as wildcards.
`table_name`
  The name of the table. This parameter accepts a search pattern containing `_` and `%` as wildcards.

### Rückgabewerte

Returns a statement resource with a result set containing rows describing the privileges for the tables that match the specified parameters. The rows are composed of the following columns:

Column name | Description
--- | ---
TABLE_CAT | The catalog that contains the table. The value is `null` if this table does not have catalogs.
TABLE_SCHEM | Name of the schema that contains the table.
TABLE_NAME | Name of the table.
GRANTOR | Authorization ID of the user who granted the privilege.
GRANTEE | Authorization ID of the user to whom the privilege was granted.
PRIVILEGE | The privilege that has been granted. This can be one of ALTER, CONTROL, DELETE, INDEX, INSERT, REFERENCES, SELECT, or UPDATE.
IS_GRANTABLE | A string value of "YES" or "NO" indicating whether the grantee can grant the privilege to other users.

### Siehe auch

- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_tables() - Returns a result set listing the tables and associated metadata in a database

# db2_tables

(PECL ibm_db2 >= 1.0.0)

db2_tables — Returns a result set listing the tables and associated metadata in a database

### Beschreibung

function db2_tables(
resource `$connection`,
?string `$qualifier` = `null`,
?string `$schema` = `null`,
?string `$table_name` = `null`,
?string `$table_type` = `null`
): resource

Returns a result set listing the tables and associated metadata in a database.

### Parameter-Liste

`connection`
  A valid connection to an IBM DB2, Cloudscape, or Apache Derby database.
`qualifier`
  A qualifier for DB2 databases running on OS/390 or z/OS servers. For other databases, pass `null` or an empty string.
`schema`
  The schema which contains the tables. This parameter accepts a search pattern containing `_` and `%` as wildcards.
`table_name`
  The name of the table. This parameter accepts a search pattern containing `_` and `%` as wildcards.
`table_type`
  A list of comma-delimited table type identifiers. To match all table types, pass `null` or an empty string. Valid table type identifiers include: ALIAS, HIERARCHY TABLE, INOPERATIVE VIEW, NICKNAME, MATERIALIZED QUERY TABLE, SYSTEM TABLE, TABLE, TYPED TABLE, TYPED VIEW, and VIEW.

### Rückgabewerte

Returns a statement resource with a result set containing rows describing the tables that match the specified parameters. The rows are composed of the following columns:

Column name | Description
--- | ---
TABLE_CAT | The catalog that contains the table. The value is `null` if this table does not have catalogs.
TABLE_SCHEM | Name of the schema that contains the table.
TABLE_NAME | Name of the table.
TABLE_TYPE | Table type identifier for the table.
REMARKS | Description of the table.

### Siehe auch

- db2_column_privileges() - Returns a result set listing the columns and associated privileges for a table
- db2_columns() - Returns a result set listing the columns and associated metadata for a table
- db2_foreign_keys() - Returns a result set listing the foreign keys for a table
- db2_primary_keys() - Returns a result set listing primary keys for a table
- db2_procedure_columns() - Returns a result set listing stored procedure parameters
- db2_procedures() - Returns a result set listing the stored procedures registered in a database
- db2_special_columns() - Returns a result set listing the unique row identifier columns for a table
- db2_statistics() - Returns a result set listing the index and statistics for a table
- db2_table_privileges() - Returns a result set listing the tables and associated privileges in a database

## Inhaltsverzeichnis

- db2_autocommit — Returns or sets the AUTOCOMMIT state for a database connection
- db2_bind_param — Binds a PHP variable to an SQL statement parameter
- db2_client_info — Returns an object with properties that describe the DB2 database client
- db2_close — Closes a database connection
- db2_column_privileges — Returns a result set listing the columns and associated privileges for a table
- db2_columns — Returns a result set listing the columns and associated metadata for a table
- db2_commit — Commits a transaction
- db2_conn_error — Returns a string containing the SQLSTATE returned by the last connection attempt
- db2_conn_errormsg — Returns the last connection error message and SQLCODE value
- db2_connect — Returns a connection to a database
- db2_cursor_type — Returns the cursor type used by a statement resource
- db2_escape_string — Used to escape certain characters
- db2_exec — Executes an SQL statement directly
- db2_execute — Executes a prepared SQL statement
- db2_fetch_array — Returns an array, indexed by column position, representing a row in a result set
- db2_fetch_assoc — Returns an array, indexed by column name, representing a row in a result set
- db2_fetch_both — Returns an array, indexed by both column name and position, representing a row in a result set
- db2_fetch_object — Returns an object with properties representing columns in the fetched row
- db2_fetch_row — Sets the result set pointer to the next row or requested row
- db2_field_display_size — Returns the maximum number of bytes required to display a column
- db2_field_name — Returns the name of the column in the result set
- db2_field_num — Returns the position of the named column in a result set
- db2_field_precision — Returns the precision of the indicated column in a result set
- db2_field_scale — Returns the scale of the indicated column in a result set
- db2_field_type — Returns the data type of the indicated column in a result set
- db2_field_width — Returns the width of the current value of the indicated column in a result set
- db2_foreign_keys — Returns a result set listing the foreign keys for a table
- db2_free_result — Frees resources associated with a result set
- db2_free_stmt — Frees resources associated with the indicated statement resource
- db2_get_option — Retrieves an option value for a statement resource or a connection resource
- db2_last_insert_id — Returns the auto generated ID of the last insert query that successfully executed on this connection
- db2_lob_read — Gets a user defined size of LOB files with each invocation
- db2_next_result — Requests the next result set from a stored procedure
- db2_num_fields — Returns the number of fields contained in a result set
- db2_num_rows — Returns the number of rows affected by an SQL statement
- db2_pclose — Closes a persistent database connection
- db2_pconnect — Returns a persistent connection to a database
- db2_prepare — Prepares an SQL statement to be executed
- db2_primary_keys — Returns a result set listing primary keys for a table
- db2_procedure_columns — Returns a result set listing stored procedure parameters
- db2_procedures — Returns a result set listing the stored procedures registered in a database
- db2_result — Returns a single column from a row in the result set
- db2_rollback — Rolls back a transaction
- db2_server_info — Returns an object with properties that describe the DB2 database server
- db2_set_option — Set options for connection or statement resources
- db2_special_columns — Returns a result set listing the unique row identifier columns for a table
- db2_statistics — Returns a result set listing the index and statistics for a table
- db2_stmt_error — Returns a string containing the SQLSTATE returned by an SQL statement
- db2_stmt_errormsg — Returns a string containing the last SQL statement error message
- db2_table_privileges — Returns a result set listing the tables and associated privileges in a database
- db2_tables — Returns a result set listing the tables and associated metadata in a database

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- IBM DB2 Funktionen
  - db2_autocommit — Returns or sets the AUTOCOMMIT state for a database connection
  - db2_bind_param — Binds a PHP variable to an SQL statement parameter
  - db2_client_info — Returns an object with properties that describe the DB2 database client
  - db2_close — Closes a database connection
  - db2_column_privileges — Returns a result set listing the columns and associated privileges for a table
  - db2_columns — Returns a result set listing the columns and associated metadata for a table
  - db2_commit — Commits a transaction
  - db2_conn_error — Returns a string containing the SQLSTATE returned by the last connection attempt
  - db2_conn_errormsg — Returns the last connection error message and SQLCODE value
  - db2_connect — Returns a connection to a database
  - db2_cursor_type — Returns the cursor type used by a statement resource
  - db2_escape_string — Used to escape certain characters
  - db2_exec — Executes an SQL statement directly
  - db2_execute — Executes a prepared SQL statement
  - db2_fetch_array — Returns an array, indexed by column position, representing a row in a result set
  - db2_fetch_assoc — Returns an array, indexed by column name, representing a row in a result set
  - db2_fetch_both — Returns an array, indexed by both column name and position, representing a row in a result set
  - db2_fetch_object — Returns an object with properties representing columns in the fetched row
  - db2_fetch_row — Sets the result set pointer to the next row or requested row
  - db2_field_display_size — Returns the maximum number of bytes required to display a column
  - db2_field_name — Returns the name of the column in the result set
  - db2_field_num — Returns the position of the named column in a result set
  - db2_field_precision — Returns the precision of the indicated column in a result set
  - db2_field_scale — Returns the scale of the indicated column in a result set
  - db2_field_type — Returns the data type of the indicated column in a result set
  - db2_field_width — Returns the width of the current value of the indicated column in a result set
  - db2_foreign_keys — Returns a result set listing the foreign keys for a table
  - db2_free_result — Frees resources associated with a result set
  - db2_free_stmt — Frees resources associated with the indicated statement resource
  - db2_get_option — Retrieves an option value for a statement resource or a connection resource
  - db2_last_insert_id — Returns the auto generated ID of the last insert query that successfully executed on this connection
  - db2_lob_read — Gets a user defined size of LOB files with each invocation
  - db2_next_result — Requests the next result set from a stored procedure
  - db2_num_fields — Returns the number of fields contained in a result set
  - db2_num_rows — Returns the number of rows affected by an SQL statement
  - db2_pclose — Closes a persistent database connection
  - db2_pconnect — Returns a persistent connection to a database
  - db2_prepare — Prepares an SQL statement to be executed
  - db2_primary_keys — Returns a result set listing primary keys for a table
  - db2_procedure_columns — Returns a result set listing stored procedure parameters
  - db2_procedures — Returns a result set listing the stored procedures registered in a database
  - db2_result — Returns a single column from a row in the result set
  - db2_rollback — Rolls back a transaction
  - db2_server_info — Returns an object with properties that describe the DB2 database server
  - db2_set_option — Set options for connection or statement resources
  - db2_special_columns — Returns a result set listing the unique row identifier columns for a table
  - db2_statistics — Returns a result set listing the index and statistics for a table
  - db2_stmt_error — Returns a string containing the SQLSTATE returned by an SQL statement
  - db2_stmt_errormsg — Returns a string containing the last SQL statement error message
  - db2_table_privileges — Returns a result set listing the tables and associated privileges in a database
  - db2_tables — Returns a result set listing the tables and associated metadata in a database

# MongoDB Extension

This extension is developed atop the » libmongoc and » libbson libraries. It provides a minimal API for core driver functionality: commands, queries, writes, connection management, and BSON serialization.

Userland PHP libraries that depend on this extension may provide higher level APIs, such as query builders, individual command helper methods, and GridFS. Application developers should consider using this extension in conjunction with the » MongoDB PHP library, which implements the same higher level APIs found in MongoDB drivers for other languages. This separation of concerns allows the extension to focus on essential features for which an extension implementation is paramount for performance.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

As of version 1.21.0, the extension requires PHP 8.1 or higher. Previous versions of the extension allow compatibility with older PHP versions.

The extension requires » libbson and » libmongoc, and will use bundled versions of both libraries by default. System libraries may also be used, as discussed in the manual installation documentation.

The extension, via libmongoc, optionally depends on a TLS library (e.g. OpenSSL) and will use it if available. If the build process fails to find a TLS library, users should check that the appropriate development package (e.g. `libssl-dev`) and » pkg-config are both installed. The process for detecting and configuring TLS libraries is discussed in more detail in the manual installation documentation.

» Cyrus SASL is an optional dependency to support Kerberos authentication and will be used if available.

> Hinweis: Due to potential problems representing 64-bit integers on 32-bit platforms, users are advised to use 64-bit environments. When using a 32-bit platform, be aware that any 64-bit integer read from the database will be returned as a MongoDB\BSON\Int64 instance instead of a PHP integer type.

## Installation

## Installing the MongoDB PHP Extension with PIE

> Hinweis: Der "PHP Installer for Extensions" (PIE) ist ein neues Tool, das PECL überflüssig machen wird. Wir empfehlen, für die Installation von Erweiterungen den PIE zu verwenden. Weitere Informationen sind unter » https://github.com/php/pie zu finden.

To install the MongoDB extension using PIE, run the following command:

    pie install mongodb/mongodb-extension

## Installing the MongoDB PHP Extension with PECL

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/mongodb

Linux, Unix, and macOS users may run the following command to install the extension:

    $ sudo pecl install mongodb

On systems with multiple version of PHP installed (e.g. macOS default, Homebrew, » XAMPP), each version of PHP will have its own pecl command and php.ini file(s). Additionally, each PHP environments (e.g. CLI, web) may use separate php.ini files.

As of extension version 1.17.0, PECL will prompt for various `configure` options. To install the extension with default options in a non-interactive script, empty string input may be piped to `pecl install` using the `yes` command:

    $ yes '' | sudo pecl install mongodb

A complete list of supported `configure` options can be found in the `package.xml` file included in the PECL package. To install the extension with specific `configure` options in a non-interactive script, the `--configureoptions` option for `pecl install` may be used:

    $ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb

By default, installing the extension via PECL will use bundled versions of » libbson, » libmongoc, and » libmongocrypt and attempt to automatically configure them.

> Hinweis: If the build process fails to find an SSL library, check that the development packages (e.g. `libssl-dev`) and » pkg-config are both installed. If that does not resolve the problem, consider using the manual installation process.

Finally, add the following line to the php.ini file for each environment that will need to use the extension:

    extension=mongodb.so

## Installing the MongoDB PHP Extension on macOS with Homebrew

» Homebrew 1.5.0 deprecated the » Homebrew/php tap and removed formulae for individual PHP extensions. Going forward, macOS users are advised to install the » php formula and follow the standard PECL installation instructions using the pecl command provided by the Homebrew PHP installation.

Alternatively, the » shivammathur/extensions tap provides formulae for individual PHP extensions. For example, to install the extension for PHP 8.4, run:

    $ brew install shivammathur/extensions/mongodb@8.4

Please note that only the latest extension version is available in brew.

> Hinweis: Install required dependencies
> To ensure that SSL support can be configured correctly, make sure that the `openssl` and `pkgconf` formulae are installed. If either of these packages are missing, the extension will be compiled with Secure Transport, which can lead to compatibility issues.

## Installing the MongoDB PHP Extension on Windows

Precompiled binaries are attached to the project's » Github releases. Archives are published for various combinations of PHP version, thread safety (TS or NTS), and architecture (x86 or x64). Determining the correct archive for the PHP environment and extract the php_mongodb.dll file to the extension directory ("ext" by default).

Add the following line to the php.ini file for each environment that will need to use the extension:

    extension=php_mongodb.dll

Failure to select the correct binary will result in an error when attempting to load the extension DLL at runtime:

    PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

Ensure that the downloaded DLL corresponds to the following PHP runtime properties:

- PHP version (`PHP_VERSION`)
- Thread safety (`PHP_ZTS`)
- Architecture (`PHP_INT_SIZE`)

In addition to the aforementioned constants, these properties can also be inferred from phpinfo(). If a system has multiple PHP runtimes installed, double-check that the phpinfo() output is for the correct environment.

> Hinweis: Additional DLL dependencies for Windows Users
> Diese Erweiterung benötigt DLL-Dateien. die für Windows verfügbar seien müssen. Der FAQ-Eintrag " Wie füge ich unter Windows PATH mein PHP-Verzeichnis hinzu?" gibt hierzu weitere Informationen. Obwohl ein einfaches Kopieren der DLL-Dateien vom PHP-Verzeichnis in den Windows-Systemordner auch funktioniert (weil der Systemordner immer im PATH enthalten ist), ist dieses Vorgehen nicht empfehlenswert. Diese Erweiterung benötigt die folgenden Dateien im PATH: libsasl.dll

## Building the MongoDB PHP Driver from source

For developers and users interested in the latest bugfixes, the extension may be compiled from the latest source code on » Github. Run the following commands to clone and build the project:

    $ git clone https://github.com/mongodb/mongo-php-driver.git
    $ cd mongo-php-driver
    $ git submodule update --init
    $ phpize
    $ ./configure
    $ make all
    $ sudo make install

On systems with multiple version of PHP installed (e.g. macOS default, Homebrew, » XAMPP), each version of PHP will have its own phpize command and php.ini file(s). Additionally, each PHP environments (e.g. CLI, web) may use separate php.ini files.

By default, the extension will use bundled versions of » libbson, » libmongoc, and » libmongocrypt and attempt to configure them automatically. If these libraries are already installed as system libraries, the extension can utilize them by specifying `--with-mongodb-system-libs=yes` as an option to `configure`.

For a complete list of `configure` options, run configure --help.

When using bundled versions of libmongoc and libmongocrypt, the extension will also attempt to select an SSL library according to the `--with-mongodb-ssl` `configure` option. As of extension version 1.17.0, OpenSSL is always preferred by default. Previously, Secure Transport was the default on macOS and OpenSSL was the default on all other platforms.

> Hinweis: If the build process fails to find an SSL library, check that the development packages (e.g. `libssl-dev`) and » pkg-config are both installed. When using Homebrew on macOS, it is common for a system to have multiple versions of OpenSSL installed. To ensure that the desired version of OpenSSL is selected, the `PKG_CONFIG_PATH` environment variable may be used to control the search path for `pkg-config`.

The final build step, make install, will report where mongodb.so has been installed, similar to:

    Installing shared extensions:     /usr/lib/php/extensions/debug-non-zts-20220829/

Ensure that the extension_dir option in php.ini points to the directory where mongodb.so was installed. The option may be queried by running:

    $ php -i | grep extension_dir
      extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
                       /usr/lib/php/extensions/debug-non-zts-20220829

If the directories differ, either change extension_dir in php.ini or manually move mongodb.so to the correct directory.

Finally, add the following line to the php.ini file for each environment that will need to use the extension:

    extension=mongodb.so

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

mongodb Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
mongodb.debug | "" | `INI_ALL` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`mongodb.debug` string
  This option can be used to enable or disable trace-level debug logging in the extension (and libmongoc). Specify an empty string, `"0"`, `"off"`, `"no"`, or `"false"` to disable logging. Specify `"stderr"` or `"stdout"` to log to `stderr` or `stdout`, respectively. Specify `"1"`, `"on"`, `"yes"`, or `"true"` to log to a new temporary file within the default system temp directory (i.e. sys_get_temp_dir()). Specify any other string to log to a new temporary file within that directory. If the directory cannot be used, the default system temp directory will be used instead.

  > Hinweis: Please note that the debug log can contain sensitive information, such as credentials to the MongoDB server and full documents written to or read from the server. Please review any debug logs before sharing them with other people.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`MONGODB_VERSION` (string)
  x.y.z style version number of the extension
`MONGODB_STABILITY` (string)
  Current stability (alpha/beta/stable)

# Tutorials

## Inhaltsverzeichnis

- Using the PHP Library for MongoDB (PHPLIB)
- Application Performance Monitoring (APM)

In this section you will find several tutorials on how to use the MongoDB driver for PHP.

## Using the PHP Library for MongoDB (PHPLIB)

After the initial extension set-up, we will continue explaining how to get started with the corresponding userland library to write our first project.

## Installing the PHP Library with Composer

The last thing we still need to install to get started on the application itself, is the PHP library.

The library needs to be installed with » Composer, a package manager for PHP. Instructions for installing Composer on various platforms may be found on its website.

Install the library by running:

    $ composer require mongodb/mongodb

It will output something akin to:

    ./composer.json has been created
    Loading composer repositories with package information
    Updating dependencies (including require-dev)
      - Installing mongodb/mongodb (1.0.0)
        Downloading: 100%

    Writing lock file
    Generating autoload files

Composer will create several files: `composer.json`, `composer.lock`, and a `vendor` directory that will contain the library and any other dependencies your project might require.

## Using the PHP Library

In addition to managing your dependencies, Composer will also provide you with an autoloader (for those dependencies' classes). Ensure that it is included at the start of your script or in your application's bootstrap code:

    <?php
    // This path should point to Composer's autoloader
    require 'vendor/autoload.php';

With this done, you can now use any of the functionality as described in the » library documentation.

If you have used MongoDB drivers in other languages, the library's API should look familiar. It contains a » Client class for connecting to MongoDB, a » Database class for database-level operations (e.g. commands, collection management), and a » Collection class for collection-level operations (e.g. » CRUD methods, index management).

As an example, this is how you insert a document into the beers collection of the demo database:

    <?php
    require 'vendor/autoload.php'; // include Composer's autoloader

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->insertOne( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

    echo "Inserted with Object ID '{$result->getInsertedId()}'";
    ?>

Since the inserted document did not contain an `_id` field, the extension will generate an MongoDB\BSON\ObjectId for the server to use as the `_id`. This value is also made available to the caller via the result object returned by the `insertOne` method.

After insertion, you can query for the data that you have just inserted. For that, you use the `find` method, which returns an iterable cursor:

    <?php
    require 'vendor/autoload.php'; // include Composer's autoloader

    $client = new MongoDB\Client("mongodb://localhost:27017");
    $collection = $client->demo->beers;

    $result = $collection->find( [ 'name' => 'Hinterland', 'brewery' => 'BrewDog' ] );

    foreach ($result as $entry) {
        echo $entry['_id'], ': ', $entry['name'], "\n";
    }
    ?>

While it may not be apparent in the examples, BSON documents and arrays are unserialized as special classes in the library by default. These classes extend ArrayObject for usability and implement the extension's MongoDB\BSON\Serializable and MongoDB\BSON\Unserializable interfaces to ensure that values preserve their type when serialized back into BSON. This avoids a caveat in the legacy `mongo` extension where arrays might turn into documents, and vice versa. See the Persisting Data specification for more information on how values are converted between PHP and BSON.

## Application Performance Monitoring (APM)

The extension contains an event subscriber API, which allows applications to monitor commands and internal activity pertaining to the » Server Discovery and Monitoring Specification. This tutorial will demonstrate command monitoring using the MongoDB\Driver\Monitoring\CommandSubscriber interface.

The MongoDB\Driver\Monitoring\CommandSubscriber interface defines three methods: `commandStarted`, `commandSucceeded`, and `commandFailed`. Each of these three methods accept a single `event` argument of a specific class for the respective event. For example, the `commandSucceeded`'s `$event` argument is a MongoDB\Driver\Monitoring\CommandSucceededEvent object.

In this tutorial we will implement a subscriber that creates a list of all the query profiles and the average time they took.

## Subscriber Class Scaffolding

We start with the framework for our subscriber:

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
        {
        }

        public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
        {
        }

        public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
        {
        }
    }

    ?>

## Registering the Subscriber

Once a subscriber object is instantiated, it needs to be registered with the extensions's monitoring system. This is done by calling MongoDB\Driver\Monitoring\addSubscriber() or MongoDB\Driver\Manager::addSubscriber() to register the subscriber globally or with a specific Manager, respectively.

    <?php

    \MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

    ?>

## Implementing the Logic

With the object registered, the only thing left is to implement the logic in the subscriber class. To correlate the two events that make up a successfully executed command (commandStarted and commandSucceeded), each event object exposes a `requestId` field.

To record the average time per query shape, we will start by checking for a `find` command in the commandStarted event. We will then add an item to the `pendingCommands` property indexed by its `requestId` and with its value representing the query shape.

If we receive a corresponding commandSucceeded event with the same `requestId`, we add the duration of the event (from `durationMicros`) to the total time and increment the operation count.

If a corresponding commandFailed event is encountered, we just remove the entry from the `pendingCommands` property.

    <?php

    class QueryTimeCollector implements \MongoDB\Driver\Monitoring\CommandSubscriber
    {
        private $pendingCommands = [];
        private $queryShapeStats = [];

        /* Creates a query shape out of the filter argument. Right now it only
         * takes the top level fields into account */
        private function createQueryShape( array $filter )
        {
            return json_encode( array_keys( $filter ) );
        }

        public function commandStarted( \MongoDB\Driver\Monitoring\CommandStartedEvent $event ): void
        {
            if ( 'find' === $event->getCommandName() )
            {
                $queryShape = $this->createQueryShape( (array) $event->getCommand()->filter );
                $this->pendingCommands[$event->getRequestId()] = $queryShape;
            }
        }

        public function commandSucceeded( \MongoDB\Driver\Monitoring\CommandSucceededEvent $event ): void
        {
            $requestId = $event->getRequestId();
            if ( array_key_exists( $requestId, $this->pendingCommands ) )
            {
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['count']++;
                $this->queryShapeStats[$this->pendingCommands[$requestId]]['duration'] += $event->getDurationMicros();
                unset( $this->pendingCommands[$requestId] );
            }
        }

        public function commandFailed( \MongoDB\Driver\Monitoring\CommandFailedEvent $event ): void
        {
            if ( array_key_exists( $event->getRequestId(), $this->pendingCommands ) )
            {
                unset( $this->pendingCommands[$event->getRequestId()] );
            }
        }

        public function __destruct()
        {
            foreach( $this->queryShapeStats as $shape => $stats )
            {
                echo "Shape: ", $shape, " (", $stats['count'], ")\n  ",
                    $stats['duration'] / $stats['count'], "µs\n\n";
            }
        }
    }

    $m = new \MongoDB\Driver\Manager( 'mongodb://localhost:27016' );

    /* Add the subscriber */
    \MongoDB\Driver\Monitoring\addSubscriber( new QueryTimeCollector() );

    /* Do a bunch of queries */
    $query = new \MongoDB\Driver\Query( [
        'region_slug' => 'scotland-highlands', 'age' => [ '$gte' => 20 ]
    ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    $query = new \MongoDB\Driver\Query( [
        'region_slug' => 'scotland-lowlands', 'age' => [ '$gte' => 15 ]
    ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    $query = new \MongoDB\Driver\Query( [ 'region_slug' => 'scotland-lowlands' ] );
    $cursor = $m->executeQuery( 'dramio.whisky', $query );

    ?>

# Explains the driver architecture, and special features

## Inhaltsverzeichnis

- Architecture
- Connections
- Persisting Data

## Architecture Overview

This article explains how all the different components of the PHP driver fit together, from base system libraries, through the extension, and to the PHP libraries on top.

At the top of this stack sits a » PHP library, which is distributed as a » Composer package. This library provides an API consistent with other MongoDB » drivers and implements various cross-driver » specifications. While the extension can be used directly, the library has minimal overhead and should be a common dependency for most applications built with MongoDB.

Sitting below that library is a PHP extension, which is distributed through » PECL. The extension forms the glue between PHP and our system libraries (» libmongoc, » libbson, and » libmongocrypt). Its public API provides only the most essential functionality:

- Connection management
- BSON encoding and decoding
- Object document serialization (to support ODM libraries)
- Executing commands, queries, and write operations
- Handling cursors for command and query results

Driver Source Code and JIRA Projects
Project | GitHub | JIRA
--- | --- | ---
PHP Library | » mongodb/mongo-php-library | » PHPLIB
PHP Extension | » mongodb/mongo-php-driver | » PHPC

## Connection handling and persistence

> Hinweis: Auf Unix-Plattformen reagiert die Erweiterung empfindlich auf Skripte, die den Systemaufruf fork() verwenden, ohne auch exec() aufzurufen. Es wird davon abgeraten, MongoDB\Driver\Manager-Instanzen in einem geforkten Kindprozess wiederzuverwenden.

## Connection and topology persistence (PHP version since 1.2.0)

All versions of the extension since 1.2.0 persist the » libmongoc client object in the PHP worker process, which allows it to re-use database connections, authentication states, and topology information across multiple requests.

When MongoDB\Driver\Manager::__construct() is invoked, a hash is created from its arguments (i.e. URI string and array options). The extension will attempt to find a previously persisted » libmongoc client object for that hash. If an existing client cannot be found for the hash, a new client will be created and persisted for future use. This behavior can be disabled via the `"disableClientPersistence"` driver option.

Each client contains its own database connections and a view of the server topology (e.g. standalone, replica set, shard cluster). By persisting the client between PHP requests, the extension is able to re-use established database connections and remove the need for » discovering the server topology on each request.

Consider the following example:

    <?php

    $managers = [
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1'),
        new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017'),
        new MongoDB\Driver\Manager('mongodb://rs1.example.com,rs2.example.com/', ['replicaSet' => 'myReplicaSet']),
    ];

    foreach ($managers as $manager) {
        $manager->executeCommand('test', new MongoDB\Driver\Command(['ping' => 1]));
    }

    ?>

The first two Manager objects will share the same » libmongoc client since their constructor arguments are identical. The third and fourth objects will each use their own client. In total, three clients will be created and the PHP worker executing this script will open two connections to `127.0.0.1` and one connection to each of `rs1.example.com` and `rs2.example.com`. If the extension discovers additional members of the replica set after issuing `hello` commands, it will open additional connections to those servers as well.

If the same worker executes the script again in a second request, the three clients will be re-used and no new connections will be made. Depending on how long ago the previous request was served, the extension may need to issue additional `hello` commands to update its view of the topologies.

## Socket persistence (PHP versions before 1.2.0)

Versions of the extension before 1.2.0 utilize PHP's Streams API for database connections, using an API within » libmongoc to designate custom handlers for socket communication; however, a new libmongoc client is created for each MongoDB\Driver\Manager. As a result, the extension persists individual database connections but not authentication state or topology information. This means that the extension needs to issue commands at the start of each request to authenticate and » discover the server topology.

Database connections are persisted by a hash derived from the server's host, port, and the URI string used to construct the MongoDB\Driver\Manager. The constructor's array options are not included in this hash.

> Hinweis: Versions of the extension >= 1.1.8 and < 1.2.0 do not persist sockets for SSL connections. See » PHPC-720 for additional information.

Despite its shortcomings with persisting SSL connections when and topology information, this version of the extension supports all SSL context options since it uses PHP's Streams API.

## Serialization and deserialization of PHP variables into MongoDB

This document discusses how compound structures (i.e. documents, arrays, and objects) are converted between BSON and PHP values.

## Serialization to BSON

## Arrays

If an array is a packed array — i.e. empty array or the keys start at 0 and are sequential without gaps: BSON array.

If the array is not packed — i.e. having associative (string) keys, the keys don't start at 0, or when there are gaps:: BSON object

A top-level (root) document, always serializes as a BSON document.

## Examples

These serialize as a BSON array:

    [ 8, 5, 2, 3 ] => [ 8, 5, 2, 3 ]
    [ 0 => 4, 1 => 9 ] => [ 4, 9 ]

These serialize as a BSON document:

    [ 0 => 1, 2 => 8, 3 => 12 ] => { "0" : 1, "2" : 8, "3" : 12 }
    [ "foo" => 42 ] => { "foo" : 42 }
    [ 1 => 9, 0 => 10 ] => { "1" : 9, "0" : 10 }

Note that the five examples are extracts of a full document, and represent only one value inside a document.

## Objects

If an object is of the stdClass class, serialize as a BSON document.

If an object is a supported class that implements MongoDB\BSON\Type, then use the BSON serialization logic for that specific type. MongoDB\BSON\Type instances (excluding MongoDB\BSON\Serializable may only be serialized as a document field value. Attempting to serialize such an object as a root document will throw a MongoDB\Driver\Exception\UnexpectedValueException

If an object is of an unknown class implementing the MongoDB\BSON\Type interface, then throw a MongoDB\Driver\Exception\UnexpectedValueException

If an object is of any other class, without implementing any special interface, serialize as a BSON document. Keep only public properties, and ignore protected and private properties.

If an object is of a class that implements the MongoDB\BSON\Serializable interface, call MongoDB\BSON\Serializable::bsonSerialize() and use the returned array or stdClass to serialize as a BSON document or array. The BSON type will be determined by the following:

1. Root documents must be serialized as a BSON document.
2. MongoDB\BSON\Persistable objects must be serialized as a BSON document.
3. If MongoDB\BSON\Serializable::bsonSerialize() returns a packed array, serialize as a BSON array.
4. If MongoDB\BSON\Serializable::bsonSerialize() returns a non-packed array or stdClass, serialize as a BSON document.
5. If MongoDB\BSON\Serializable::bsonSerialize() did not return an array or stdClass, throw an MongoDB\Driver\Exception\UnexpectedValueException exception.

If an object is of a class that implements the MongoDB\BSON\Persistable interface (which implies MongoDB\BSON\Serializable), obtain the properties in a similar way as in the previous paragraphs, but also add an additional property __pclass as a Binary value, with subtype `0x80` and data bearing the fully qualified class name of the object that is being serialized.

The __pclass property is added to the array or object returned by MongoDB\BSON\Serializable::bsonSerialize(), which means it will overwrite any __pclass key/property in the MongoDB\BSON\Serializable::bsonSerialize() return value. If you want to avoid this behaviour and set your own __pclass value, you must not implement MongoDB\BSON\Persistable and should instead implement MongoDB\BSON\Serializable directly.

## Examples

    <?php

    class stdClass
    {
        public $foo = 42;
    } // => {"foo": 42}

    class MyClass
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';
    } // => {"foo": 42}

    class AnotherClass1 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "wine"}

    class AnotherClass2 implements MongoDB\BSON\Serializable
    {
        public $foo = 42;

        public function bsonSerialize(): self
        {
            return $this;
        }
    } // => MongoDB\Driver\Exception\UnexpectedValueException("bsonSerialize() did not return an array or stdClass")

    class AnotherClass3 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    /**
     * Nesting Serializable classes
     */

    class AnotherClass4 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return $this->elements;
        }
    } // => {"0": "foo", "2": "bar"}

    class ContainerClass1 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass4();
        }

        function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "2": "bar"}}

    class AnotherClass5 implements MongoDB\BSON\Serializable
    {
        private $elements = [0 => 'foo', 2 => 'bar'];

        public function bsonSerialize(): array
        {
            return array_values($this->elements);
        }
    } // => {"0": "foo", "1": "bar"} as a root class
      //    ["foo", "bar"] as a nested value

    class ContainerClass2 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass5();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": ["foo", "bar"]}

    class AnotherClass6 implements MongoDB\BSON\Serializable
    {
        private $elements = ['foo', 'bar'];

        function bsonSerialize(): object
        {
            return (object) $this->elements;
        }
    } // => {"0": "foo", "1": "bar"}

    class ContainerClass3 implements MongoDB\BSON\Serializable
    {
        public $things;

        public function __construct()
        {
            $this->things = new AnotherClass6();
        }

        public function bsonSerialize(): array
        {
            return ['things' => $this->things];
        }
    } // => {"things": {"0": "foo", "1": "bar"}}

    class UpperClass implements MongoDB\BSON\Persistable
    {
        public $foo = 42;
        protected $prot = 'wine';
        private $fpr = 'cheese';

        private $data;

        public function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }

        public function bsonSerialize(): array
        {
            return ['foo' => $this->foo, 'prot' => $this->prot];
        }
    } // => {"foo": 42, "prot": "wine", "__pclass": {"$type": "80", "$binary": "VXBwZXJDbGFzcw=="}}

    ?>

## Deserialization from BSON

Warnung

Da Dokumente als Liste von Schlüssel-Wert-Paaren gespeichert werden, können BSON-Dokumente technisch gesehen doppelte Schlüssel enthalten; Anwendungen sollten allerdings davon absehen, Dokumente mit doppelten Schlüsseln zu erzeugen, da das Verhalten von Server und Treiber undefiniert sein kann. Der Grund dafür ist, dass PHP-Objekte und -Arrays keine doppelten Schlüssel haben können, weshalb bei der Dekodierung eines BSON-Dokuments mit doppelten Schlüsseln Daten verloren gehen können.

The legacy `mongo` extension deserialized both BSON documents and arrays as PHP arrays. While PHP arrays are convenient to work with, this behavior was problematic because different BSON types could deserialize to the same PHP value (e.g. `{"0": "foo"}` and `["foo"]`) and make it impossible to infer the original BSON type. By default, the `mongodb` extension addresses this concern by ensuring that BSON arrays and documents are converted to PHP arrays and objects, respectively.

For compound types, there are three data types:

root
  refers to the top-level BSON document only
document
  refers to embedded BSON documents only
array
  refers to a BSON array

Besides the three collective types, it is also possible to configure specific fields in your document to map to the data types mentioned below. As an example, the following type map allows you to map each embedded document within an `"addresses"` array to an Address class and each `"city"` field within those embedded address documents to a City class:

    [
        'fieldPaths' => [
            'addresses.$' => 'MyProject\Address',
            'addresses.$.city' => 'MyProject\City',
        ],
    ]

Each of those three data types, as well as the field specific mappings, can be mapped against different PHP types. The possible mapping values are:

not set or NULL (default)

  - A BSON array will be deserialized as a PHP array.
  - A BSON document (root or embedded) without a __pclass property [1]

    A __pclass property is only deemed to exist if there exists a property with that name, and it is a Binary value, and the sub-type of the Binary value is 0x80. If any of these three conditions is not met, the __pclass property does not exist and should be treated as any other normal property.

    becomes a PHP stdClass object, with each BSON document key set as a public stdClass property.
  - A BSON document (root or embedded) with a __pclass property [1] becomes a PHP object of the class name as defined by the __pclass property. If the named class implements the MongoDB\BSON\Persistable interface, then the properties of the BSON document, including the __pclass property, are sent as an associative array to the MongoDB\BSON\Unserializable::bsonUnserialize() function to initialise the object's properties. If the named class does not exist or does not implement the MongoDB\BSON\Persistable interface, stdClass will be used and each BSON document key (including __pclass) will be set as a public stdClass property. The __pclass functionality relies on the property being part of a retrieved MongoDB document. If you use a projection when querying for documents, you need to include the __pclass field in the projection for this functionality to work.
`"array"`
  Turns a BSON array or BSON document into a PHP array. There will be no special treatment of a __pclass property [1], but it may be set as an element in the returned array if it was present in the BSON document.
`"object"` or `"stdClass"`
  Turns a BSON array or BSON document into a stdClass object. There will be no special treatment of a __pclass property [1], but it may be set as a public property in the returned object if it was present in the BSON document.
`"bson"`
  Turns a BSON array into a MongoDB\BSON\PackedArray and a BSON document into a MongoDB\BSON\Document, regardless of whether the BSON document has a __pclass property [1].

  > Hinweis: The `bson` value is only available for the three root types, not in the field specific mappings.

any other string
  Defines the class name that the BSON array or BSON object should be deserialized as. For BSON objects that include __pclass properties, that class will take priority. If the named class does not exist, is not concrete (i.e. it is abstract or an interface), or does not implement MongoDB\BSON\Unserializable then an MongoDB\Driver\Exception\InvalidArgumentException exception is thrown. If the BSON object has a __pclass property and that class exists and implements MongoDB\BSON\Persistable it will supersede the class provided in the type map. The properties of the BSON document, including the __pclass property if it exists, will be sent as an associative array to the MongoDB\BSON\Unserializable::bsonUnserialize() function to initialise the object's properties.

## TypeMaps

TypeMaps can be set through the MongoDB\Driver\Cursor::setTypeMap() method on a MongoDB\Driver\Cursor object, or the `$typeMap` argument of MongoDB\BSON\toPHP(), MongoDB\BSON\Document::toPHP(), and MongoDB\BSON\PackedArray::toPHP(). Each of the three classes (root, document, and array) can be individually set, in addition to the field specific types.

If the value in the map is NULL, it means the same as the default value for that item.

## Examples

These examples use the following classes:

MyClass
  which does not implement any interface
YourClass
  which implements MongoDB\BSON\Unserializable
OurClass
  which implements MongoDB\BSON\Persistable
TheirClass
  which extends OurClass

The MongoDB\BSON\Unserializable::bsonUnserialize() method of YourClass, OurClass, TheirClass iterate over the array and set the properties without modifications. It also sets the `$unserialized` property to `true`:

    <?php

    function bsonUnserialize( array $map )
    {
        foreach ( $map as $k => $value )
        {
            $this->$k = $value;
        }
        $this->unserialized = true;
    }

    /* typemap: [] (all defaults) */
    { "foo": "yes", "bar" : false }
      -> stdClass { $foo => 'yes', $bar => false }

    { "foo": "no", "array" : [ 5, 6 ] }
      -> stdClass { $foo => 'no', $array => [ 5, 6 ] }

    { "foo": "no", "obj" : { "embedded" : 3.14 } }
      -> stdClass { $foo => 'no', $obj => stdClass { $embedded => 3.14 } }

    { "foo": "yes", "__pclass": "MyClass" }
      -> stdClass { $foo => 'yes', $__pclass => 'MyClass' }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "MyClass" } }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'MyClass') }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "YourClass") }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass') }

    { "foo": "yes", "__pclass": { "$type" : "80", "$binary" : "OurClass") }
      -> OurClass { $foo => 'yes', $__pclass => Binary(0x80, 'OurClass'), $unserialized => true }

    { "foo": "yes", "__pclass": { "$type" : "44", "$binary" : "YourClass") }
      -> stdClass { $foo => 'yes', $__pclass => Binary(0x44, 'YourClass') }

    /* typemap: [ "root" => "MissingClass" ] */
    { "foo": "yes" }
      -> MongoDB\Driver\Exception\InvalidArgumentException("MissingClass does not exist")

    /* typemap: [ "root" => "MyClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> MongoDB\Driver\Exception\InvalidArgumentException("MyClass does not implement Unserializable interface")

    /* typemap: [ "root" => "MongoDB\BSON\Unserializable" ] */
    { "foo": "yes" }
      -> MongoDB\Driver\Exception\InvalidArgumentException("Unserializable is not a concrete class")

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MongoDB\BSON\Unserializable" } }
      -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MongoDB\BSON\Unserializable"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> YourClass { $foo => "yes", $__pclass => Binary(0x80, "MyClass"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
      -> OurClass { $foo => "yes", $__pclass => Binary(0x80, "OurClass"), $unserialized => true }

    /* typemap: [ "root" => "YourClass" ] */
    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
      -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

    /* typemap: [ "root" => "OurClass" ] */
    { foo: "yes", "__pclass" : { "$type": "80", "$binary": "TheirClass" } }
      -> TheirClass { $foo => "yes", $__pclass => Binary(0x80, "TheirClass"), $unserialized => true }

    /* typemap: [ 'root' => 'YourClass' ] */
    { foo: "yes", "__pclass" : { "$type": "80", "$binary": "YourClass" } }
      -> YourClass { $foo => 'yes', $__pclass => Binary(0x80, 'YourClass'), $unserialized => true }

    /* typemap: [ 'root' => 'array', 'document' => 'array' ] */
    { "foo": "yes", "bar" : false }
      -> [ "foo" => "yes", "bar" => false ]

    { "foo": "no", "array" : [ 5, 6 ] }
      -> [ "foo" => "no", "array" => [ 5, 6 ] ]

    { "foo": "no", "obj" : { "embedded" : 3.14 } }
      -> [ "foo" => "no", "obj" => [ "embedded => 3.14 ] ]

    { "foo": "yes", "__pclass": "MyClass" }
      -> [ "foo" => "yes", "__pclass" => "MyClass" ]

    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "MyClass" } }
      -> [ "foo" => "yes", "__pclass" => Binary(0x80, "MyClass") ]

    { "foo": "yes", "__pclass" : { "$type": "80", "$binary": "OurClass" } }
      -> [ "foo" => "yes", "__pclass" => Binary(0x80, "OurClass") ]

    /* typemap: [ 'root' => 'object', 'document' => 'object' ] */
    { "foo": "yes", "__pclass": { "$type": "80", "$binary": "MyClass" } }
      -> stdClass { $foo => "yes", "__pclass" => Binary(0x80, "MyClass") }

# Security

## Inhaltsverzeichnis

- Request Injection Attacks
- Script Injection Attacks

## Request Injection Attacks

If you are passing `$_GET` (or `$_POST`) parameters to your queries, make sure that they are cast to strings first. Users can insert associative arrays in GET and POST requests, which could then become unwanted $-queries.

A fairly innocuous example: suppose you are looking up a user's information with the request http://www.example.com?username=bob. Your application creates the query `$q = new \MongoDB\Driver\Query( [ 'username' => $_GET['username'] ])`.

Someone could subvert this by getting http://www.example.com?username[$ne]=foo, which PHP will magically turn into an associative array, turning your query into `$q = new \MongoDB\Driver\Query( [ 'username' => [ '$ne' => 'foo' ] ] )`, which will return all users not named "foo" (all of your users, probably).

This is a fairly easy attack to defend against: make sure $_GET and $_POST parameters are the type you expect before you send them to the database. PHP has the filter_var() function to assist with this.

Note that this type of attack can be used with any database interaction that locates a document, including updates, upserts, deletes, and findAndModify commands.

See » the main documentation for more information about SQL-injection-like issues with MongoDB.

## Script Injection Attacks

If you are using JavaScript, make sure that any variables that cross the PHP- to-JavaScript boundary are passed in the `scope` field of MongoDB\BSON\Javascript, not interpolated into the JavaScript string. This can come up when using `$where` clauses in queries, mapReduce and group commands, and any other time you may pass JavaScript into the database.

For example, suppose we have some JavaScript to greet a user in the database logs. We could do:

    <?php
    $m = new MongoDB\Driver\Manager;

    // Don't do this!!!
    $username = $_GET['field'];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Hello, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

However, what if a malicious user passes in some JavaScript?

    <?php
    $m = new MongoDB\Driver\Manager;

    // Don't do this!!!
    $username = $_GET['field'];
    // $username is set to "'); db.users.drop(); print('"

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "print('Hello, $username!');"
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

Now MongoDB executes the JavaScript string `"print('Hello, '); db.users.drop(); print('!');"`. This attack is easy to avoid: use `args` to pass variables from PHP to JavaScript:

    <?php
    $m = new MongoDB\Driver\Manager;

    $_GET['field'] = 'derick';
    $args = [ $_GET['field'] ];

    $cmd = new \MongoDB\Driver\Command( [
        'eval' => "function greet(username) { print('Hello, ' + username + '!'); }",
        'args' => $args,
    ] );

    $r = $m->executeCommand( 'dramio', $cmd );
    ?>

This adds an argument to the JavaScript scope, which gets used as argument for the `greet` function. Now if someone tries to send malicious code, MongoDB will harmlessly print `Hello, '); db.dropDatabase(); print('!`.

Using arguments helps to prevent malicious input from being executed by the database. However, you must make sure that your code does not turn around and execute the input anyway! It is best to avoid executing any JavaScript on the server in the first place.

You are strongly recommended to stay clear of the » $where clause with queries, as it impacts performance significantly. Where possible, use either normal query operators, or the » Aggregation Framework.

As alternative to » MapReduce, which uses JavaScript, consider using the » Aggregation Framework. Unlike Map/Reduce, it uses an idiomatic language to construct queries, without having to write, and use, the slower JavaScript approach that Map/Reduce requires.

The » eval command has been deprecated since MongoDB 3.0, and should also be avoided.

# MongoDB Extension Classes

## Inhaltsverzeichnis

- MongoDB\Driver\Manager
- MongoDB\Driver\Command
- MongoDB\Driver\Query
- MongoDB\Driver\BulkWrite
- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\Session
- MongoDB\Driver\ClientEncryption
- MongoDB\Driver\ServerApi
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Cursor
- MongoDB\Driver\CursorId
- MongoDB\Driver\CursorInterface
- MongoDB\Driver\Server
- MongoDB\Driver\ServerDescription
- MongoDB\Driver\TopologyDescription
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError
- MongoDB\Driver\WriteResult
- MongoDB\Driver\BulkWriteCommandResult

# The MongoDB\Driver\Manager class

(mongodb >=1.0.0)

## Einführung

The MongoDB\Driver\Manager is the main entry point to the extension. It is responsible for maintaining connections to MongoDB (be it standalone server, replica set, or sharded cluster).

No connection to MongoDB is made upon instantiating the Manager. This means the MongoDB\Driver\Manager can always be constructed, even though one or more MongoDB servers are down.

Any write or query can throw connection exceptions as connections are created lazily. A MongoDB server may also become unavailable during the life time of the script. It is therefore important that all actions on the Manager to be wrapped in try/catch statements.

## Klassenbeschreibung

final class MongoDB\Driver\Manager {
/* Methoden */
final public function addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function __construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)
final public function createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getEncryptedFieldsMap(): array|object|null
final public function getReadConcern(): MongoDB\Driver\ReadConcern
final public function getReadPreference(): MongoDB\Driver\ReadPreference
final public function getServers(): array
final public function getWriteConcern(): MongoDB\Driver\WriteConcern
final public function removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server
final public function startSession(?array `$options` = `null`): MongoDB\Driver\Session
}

## Beispiele

Beispiel #1 MongoDB\Driver\Manager::__construct() basic example

var_dump()ing a MongoDB\Driver\Manager will print out various details about the manager that are otherwise not normally exposed. This can be useful to debug how the driver views your MongoDB setup, and which options are used.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\Driver\Manager)#1 (2) {
      ["uri"]=>
      string(26) "mongodb://127.0.0.1:27017/"
      ["cluster"]=>
      array(0) {
      }
    }

# MongoDB\Driver\Manager::addSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::addSubscriber — Registers a monitoring event subscriber with this Manager

### Beschreibung

final public function MongoDB\Driver\Manager::addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Registers a monitoring event subscriber with this Manager. The subscriber will be notified of all events for this Manager.

> Hinweis: If `subscriber` is already registered with this Manager, this function is a no-op. If `subscriber` is also registered globally, it will still only be notified once of each event for this Manager.

### Parameter-Liste

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  A monitoring event subscriber to register with this Manager.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `subscriber` is a MongoDB\Driver\Monitoring\LogSubscriber, since loggers can only be registered globally.

### Siehe auch

- MongoDB\Driver\Manager::removeSubscriber() - Unregisters a monitoring event subscriber with this Manager
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- Application Performance Monitoring (APM)

# MongoDB\Driver\Manager::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Manager::__construct — Create new MongoDB Manager

### Beschreibung

final public function MongoDB\Driver\Manager::__construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)

Constructs a new MongoDB\Driver\Manager object with the specified options.

> Hinweis: Per the » Server Discovery and Monitoring Specification, this constructor performs no I/O. Connections will be initialized on demand, when the first operation is executed.

> Hinweis: When specifying any SSL or TLS URI options via the connection string or `uriOptions` parameter, the extension will implicitly enable TLS for its connections. To avoid this, either explicitly disable the `tls` option or don't specify any TLS options.

> Hinweis: Auf Unix-Plattformen reagiert die Erweiterung empfindlich auf Skripte, die den Systemaufruf fork() verwenden, ohne auch exec() aufzurufen. Es wird davon abgeraten, MongoDB\Driver\Manager-Instanzen in einem geforkten Kindprozess wiederzuverwenden.

### Parameter-Liste

`uri`
  A » mongodb:// connection URI:

      mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[defaultAuthDb][?options]]

  Defaults to `"mongodb://127.0.0.1:27017"` if unspecified. For details on supported URI options, see » Connection String Options in the MongoDB manual. » Connection pool options are not supported, as the extension does not implement connection pools. The `uri` is a URL, hence any special characters in its components need to be URL encoded according to » RFC 3986. This is particularly relevant to the username and password, which can often include special characters such as `@`, `:`, or `%`. When connecting via a Unix domain socket, the socket path may contain special characters such as slashes and must be encoded. The rawurlencode() function may be used to encode constituent parts of the URI. The `defaultAuthDb` component may be used to specify the database name associated with the user's credentials; however the `authSource` URI option will take priority if specified. If neither `defaultAuthDb` nor `authSource` are specified, the `admin` database will be used by default. The `defaultAuthDb` component has no effect in the absence of user credentials.
`uriOptions`
  Additional » connection string options, which will overwrite any options with the same name in the `uri` parameter.

  uriOptions
  Option | Type | Description
  --- | --- | ---
  appname | string | MongoDB 3.4+ has the ability to annotate connections with metadata provided by the connecting client. This metadata is included in the server's logs upon establishing a connection and also recorded in slow query logs when database profiling is enabled. This option may be used to specify an application name, which will be included in the metadata. The value cannot exceed 128 characters in length.
  authMechanism | string | The authentication mechanism that MongoDB will use to authenticate the connection. For additional details and a list of supported values, see » Authentication Options in the MongoDB manual.
  authMechanismProperties | array | Properties for the selected authentication mechanism. For additional details and a list of supported properties, see the » Driver Authentication Specification. Hinweis: When not specified in the URI string, this option is expressed as an array of key/value pairs. The keys and values in this array should be strings.
  authSource | string | The database name associated with the user's credentials. Defaults to the database component of the connection URI, or the `admin` database if both are unspecified. For authentication mechanisms that delegate credential storage to other services (e.g. GSSAPI), this should be `"$external"`.
  compressors | string | A prioritized, comma-delimited list of compressors that the client wants to use. Messages are only compressed if the client and server share any compressors in common, and the compressor used in each direction will depend on the individual configuration of the server or driver. See the » Driver Compression Specification for more information.
  connectTimeoutMS | int | The time in milliseconds to attempt a connection before timing out. Defaults to 10,000 milliseconds.
  directConnection | bool | This option can be used to control replica set discovery behavior when only a single host is provided in the connection string. By default, providing a single member in the connection string will establish a direct connection or discover additional members depending on whether the `"replicaSet"` URI option is omitted or present, respectively. Specify `false` to force discovery to occur (if `"replicaSet"` is omitted) or specify `true` to force a direct connection (if `"replicaSet"` is present).
  enableOverloadRetargeting | bool | When set to `true` it forces server selection after a `SystemOverloadedError`. Defaults to `false`.
  heartbeatFrequencyMS | int | Specifies the interval in milliseconds between the driver's checks of the MongoDB topology, counted from the end of the previous check until the beginning of the next one. Defaults to 60,000 milliseconds. Per the » Server Discovery and Monitoring Specification, this value cannot be less than 500 milliseconds.
  journal | bool | Corresponds to the default write concern's `journal` parameter. If `true`, writes will require acknowledgement from MongoDB that the operation has been written to the journal. For details, see MongoDB\Driver\WriteConcern.
  loadBalanced | bool | Specifies whether the driver is connecting to a MongoDB cluster through a load balancer. If `true`, the driver may only connect to a single host (specified by either the connection string or SRV lookup), the `"directConnection"` URI option cannot be `true`, and the `"replicaSet"` URI option must be omitted. Defaults to `false`.
  localThresholdMS | int | The size in milliseconds of the latency window for selecting among multiple suitable MongoDB instances while resolving a read preference. Defaults to 15 milliseconds.
  maxAdaptiveRetries | int | This option can be used to change the maximum number of retries when a `SystemOverloadedError` occurs. Must be a positive integer; defaults to `2`.
  maxStalenessSeconds | int | Corresponds to the read preference's `"maxStalenessSeconds"`. Specifies, in seconds, how stale a secondary can be before the client stops using it for read operations. By default, there is no maximum staleness and clients will not consider a secondary’s lag when choosing where to direct a read operation. For details, see MongoDB\Driver\ReadPreference. If specified, the max staleness must be a signed 32-bit integer greater than or equal to `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS` (i.e. 90 seconds).
  password | string | The password for the user being authenticated. This option is useful if the password contains special characters, which would otherwise need to be URL encoded for the connection URI.
  readConcernLevel | string | Corresponds to the read concern's `level` parameter. Specifies the level of read isolation. For details, see MongoDB\Driver\ReadConcern.
  readPreference | string | Corresponds to the read preference's `mode` parameter. Defaults to `"primary"`. For details, see MongoDB\Driver\ReadPreference.
  readPreferenceTags | array | Corresponds to the read preference's `tagSets` parameter. Tag sets allow you to target read operations to specific members of a replica set. For details, see MongoDB\Driver\ReadPreference. Hinweis: When not specified in the URI string, this option is expressed as an array consistent with the format expected by MongoDB\Driver\ReadPreference::__construct().
  replicaSet | string | Specifies the name of the replica set.
  retryReads | bool | Specifies whether or not the driver should automatically retry certain read operations that fail due to transient network errors or replica set elections. This functionality requires MongoDB 3.6+. Defaults to `true`. See the » Retryable Reads Specification for more information.
  retryWrites | bool | Specifies whether or not the driver should automatically retry certain write operations that fail due to transient network errors or replica set elections. This functionality requires MongoDB 3.6+. Defaults to `true`. See » Retryable Writes in the MongoDB manual for more information.
  serverSelectionTimeoutMS | int | Specifies how long in milliseconds to block for server selection before throwing an exception. Defaults to 30,000 milliseconds.
  serverSelectionTryOnce | bool | When `true`, instructs the driver to scan the MongoDB deployment exactly once after server selection fails and then either select a server or raise an error. When `false`, the driver blocks and searches for a server up to the `"serverSelectionTimeoutMS"` value. Defaults to `true`.
  socketCheckIntervalMS | int | If a socket has not been used recently, the driver must check it via a `hello` command before using it for any operation. Defaults to 5,000 milliseconds.
  socketTimeoutMS | int | The time in milliseconds to attempt a send or receive on a socket before timing out. Defaults to 300,000 milliseconds (i.e. five minutes).
  srvMaxHosts | int | The maximum number of SRV results to randomly select when initially populating the seedlist or, during SRV polling, adding new hosts to the topology. Defaults to `0` (i.e. no maximum).
  srvServiceName | string | The service name to use for SRV lookup in initial DNS seedlist discovery and SRV polling. Defaults to `"mongodb"`.
  tls | bool | Initiates the connection with TLS/SSL if `true`. Defaults to `false`.
  tlsAllowInvalidCertificates | bool | Specifies whether or not the driver should error when the server's TLS certificate is invalid. Defaults to `false`. Warnung Disabling certificate validation creates a vulnerability.
  tlsAllowInvalidHostnames | bool | Specifies whether or not the driver should error when there is a mismatch between the server's hostname and the hostname specified by the TLS certificate. Defaults to `false`. Warnung Disabling certificate validation creates a vulnerability. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.
  tlsCAFile | string | Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection. The system certificate store will be used by default.
  tlsCertificateKeyFile | string | Path to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated.
  tlsCertificateKeyFilePassword | string | Password to decrypt the client private key (i.e. `"tlsCertificateKeyFile"` URI option) to be used for TLS connections.
  tlsDisableCertificateRevocationCheck | bool | If `true`, the driver will not attempt to check certificate revocation status (e.g. OCSP, CRL). Defaults to `false`.
  tlsDisableOCSPEndpointCheck | bool | If `true`, the driver will not attempt to contact an OCSP responder endpoint if needed (i.e. an OCSP response is not stapled). Defaults to `false`.
  tlsInsecure | bool | Relax TLS constraints as much as possible. Specifying `true` for this option has the same effect as specifying `true` for both the `"tlsAllowInvalidCertificates"` and `"tlsAllowInvalidHostnames"` URI options. Defaults to `false`. Warnung Disabling certificate validation creates a vulnerability. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.
  username | string | The username for the user being authenticated. This option is useful if the username contains special characters, which would otherwise need to be URL encoded for the connection URI.
  w | int|string | Corresponds to the default write concern's `w` parameter. For details, see MongoDB\Driver\WriteConcern.
  wTimeoutMS | int|string | Corresponds to the default write concern's `wtimeout` parameter. Specifies a time limit, in milliseconds, for the write concern. For details, see MongoDB\Driver\WriteConcern. If specified, `wTimeoutMS` must be a signed 32-bit integer greater than or equal to zero.
  zlibCompressionLevel | int | Specifies the compression level to use for the zlib compressor. This option has no effect if `zlib` is not included in the `"compressors"` URI option. See the » Driver Compression Specification for more information.

`driverOptions`

  driverOptions
  Option | Type | Description
  --- | --- | ---
  autoEncryption | array | Provides options to enable automatic client-side field level encryption. The list of options is described in the table below. Hinweis: Automatic encryption is an enterprise-only feature that only applies to operations on a collection. Automatic encryption is not supported for operations on a database or view, and operations that are not bypassed will result in error (see » libmongocrypt: Auto Encryption Allow-List). To bypass automatic encryption for all operations, set `bypassAutoEncryption` to `true`. Automatic encryption requires the authenticated user to have the » listCollections privilege action. Explicit encryption/decryption and automatic decryption is a community feature. The driver can still automatically decrypt when `bypassAutoEncryption` is `true`.
  ca_dir | string | Path to a correctly hashed certificate directory. The system certificate store will be used by default.
  crl_file | string | Path to a certificate revocation list file.
  disableClientPersistence | bool | If `true`, this Manager will use a new libmongoc client, which will not be persisted or shared with other Manager objects. When this Manager object is freed, its client will be destroyed and any connections will be closed. Defaults to `false`. Hinweis: Disabling client persistence is not generally recommended.
  driver | array | Allows a higher level library to append its own metadata to the server handshake. By default, the extension submits its own name, version, and platform (i.e. PHP version) in the handshake. Strings can be specified for the `"name"`, `"version"`, and `"platform"` keys of this array, and will be appended to the respective field(s) in the handshake document. Hinweis: Handshake information is limited to 512 bytes. The extension will truncate handshake data to fit within this 512-byte string. Higher level libraries are encouraged to keep their own metadata concise.
  serverApi | MongoDB\Driver\ServerApi | This option is used to declare a server API version for the manager. If omitted, no API version is declared.

  Options supported by automatic encryption through the `autoEncryption` driver option:

  autoEncryption
  Option | Type | Description
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | Der Manager, der verwendet wird, um Datenschlüssel-Abfragen auf einen anderen MongoDB-Cluster zu routen. Standardmäßig werden der aktuelle Manager und Cluster verwendet.
  keyVaultNamespace | string | Ein vollständig qualifizierter Namensraum (z. B. `"databaseName.collectionName"`), der die Kollektion bezeichnet, die alle Datenschlüssel enthält, die für Ver- und Entschlüsselung verwendet werden. Diese Option muss angegeben werden.
  kmsProviders | array | Ein Dokument, das die Konfiguration für einen oder mehrere KMS-Provider enthält, die verwendet werden, um Datenschlüssel zu verschlüsseln. Zu den unterstützten Providern gehören `"aws"`, `"azure"`, `"gcp"`, `"kmip"` und `"local"` und wenigstens einer muss angegeben werden. Wenn für `"aws"`, `"azure"` oder `"gcp"` ein leeres Dokument angegeben wird, versucht der Treiber, den Provider mit » Automatic Credentials (automatische Anmeldeinformationen) zu konfigurieren. Das Format für `"aws"` ist wie folgt:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  Das Format für `"azure"` ist wie folgt:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Der Standardwert ist "login.microsoftonline.com"
      }
  Das Format für `"gcp"` ist wie folgt:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Der Standardwert ist "oauth2.googleapis.com"
      }
  Das Format für `"kmip"` ist wie folgt:
      kmip: {
          endpoint: <string>
      }
  Das Format für `"local"` ist wie folgt:
      local: {
          // Der 96-Byte-Hauptschlüssel, der zur Ver- und Entschlüsselung von
          // Datenschlüsseln verwendet wird
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Ein Dokument, das die TLS-Konfiguration für einen oder mehrere KMS-Provider enthält. Zu den unterstützten Providern gehören `"aws"`, `"azure"`, `"gcp"` und `"kmip"`. Alle Provider unterstützen die folgenden Optionen:
      <provider>: {
          tlsCaFile: <optionale Zeichenkette>,
          tlsCertificateKeyFile: <optionale Zeichenkette>,
          tlsCertificateKeyFilePassword: <optionale Zeichenkette>,
          tlsDisableOCSPEndpointCheck: <optionaler Boolean>
      }
  schemaMap | array|object | Map of collection namespaces to a local JSON schema. This is used to configure automatic encryption. See » Automatic Encryption Rules in the MongoDB manual for more information. It is an error to specify a collection in both `schemaMap` and `encryptedFieldsMap`. Hinweis: Supplying a `schemaMap` provides more security than relying on JSON schemas obtained from the server. It protects against a malicious server advertising a false JSON schema, which could trick the client into sending unencrypted data that should be encrypted. Hinweis: Schemas supplied in the `schemaMap` only apply to configuring automatic encryption for client side encryption. Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.
  bypassAutoEncryption | bool | If `true`, `mongocryptd` will not be spawned automatically. This is used to disable automatic encryption. Defaults to `false`.
  bypassQueryAnalysis | bool | If `true`, automatic analysis of outgoing commands will be disabled and `mongocryptd` will not be spawned automatically. This enables the use case of explicit encryption for querying indexed fields without requiring the enterprise licensed `crypt_shared` library or `mongocryptd` process. Defaults to `false`.
  encryptedFieldsMap | array|object | Map of collection namespaces to an `encryptedFields` document. This is used to configure queryable encryption. See » Field Encryption and Queryability in the MongoDB manual for more information. It is an error to specify a collection in both `encryptedFieldsMap` and `schemaMap`. Hinweis: Supplying an `encryptedFieldsMap` provides more security than relying on an `encryptedFields` obtained from the server. It protects against a malicious server advertising a false `encryptedFields`.
  extraOptions | array | The `extraOptions` relate to the `mongocryptd` process. The following options are supported: `mongocryptdURI` (string): URI to connect to an existing `mongocryptd` process. Defaults to `"mongodb://localhost:27020"`. `mongocryptdBypassSpawn` (bool): If `true`, prevent the driver from spawning `mongocryptd`. Defaults to `false`. `mongocryptdSpawnPath` (string): Absolute path to search for `mongocryptd` binary. Defaults to empty string and consults system paths. `mongocryptdSpawnArgs` (array): Array of string arguments to pass to `mongocryptd` when spawning. Defaults to `["--idleShutdownTimeoutSecs=60"]`. `cryptSharedLibPath` (string): Absolute path to `crypt_shared` shared library. Defaults to empty string and consults system paths. `cryptSharedLibRequired` (bool): If `true`, require the driver to load `crypt_shared`. Defaults to `false`. See the » Client-Side Encryption Specification for more information.

  > Hinweis: Automatic encryption is an enterprise only feature that only applies to operations on a collection. Automatic encryption is not supported for operations on a database or view, and operations that are not bypassed will result in error. To bypass automatic encryption for all operations, set `bypassAutoEncryption=true` in `autoEncryption`. For more information on allowed operations, see the » Client-Side Encryption Specification.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\RuntimeException if the `uri` format is invalid

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The `"canonicalizeHostname"` URI option was removed. Use the `"CANONICALIZE_HOST_NAME"` property of the `"authMechanismProperties"` URI option instead. The `"gssapiServiceName"` URI option was removed. Use the `"SERVICE_NAME"` property of the `"authMechanismProperties"` URI option instead. The `"safe"` URI option was removed. Use the `"w"` and `"wTimeoutMS"` URI options instead. The `"ssl"` URI option was removed. Use the `"tls"` URI option instead. The `"allow_invalid_hostname"` driver option was removed. Use the `"tlsAllowInvalidHostnames"` URI option instead. The `"ca_file"` driver option was removed. Use the `"tlsCAFile"` URI option instead. The `"context"` driver option was removed. All context options were deprecated in favor of the various URI options related to TLS. The `"pem_file"` driver option was removed. Use the `"tlsCertificateKeyFile"` URI option instead. The `"pem_pwd"` driver option was removed. Use the `"tlsCertificateKeyFilePassword"` URI option instead. The `"weak_cert_validation"` driver option was removed. Use the `"tlsAllowInvalidCertificates"` URI option instead.
PECL mongodb 1.16.0 | The AWS KMS provider for client-side encryption now accepts a `"sessionToken"` option, which can be used to authenticate with temporary AWS credentials. Added `"tlsDisableOCSPEndpointCheck"` to the `"tlsOptions"` field of the `"autoEncryption"` driver option. If an empty document is specified for the `"azure"` or `"gcp"` KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.
PECL mongodb 1.15.0 | If an empty document is specified for the `"aws"` KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.
PECL mongodb 1.14.0 | Added the `"bypassQueryAnalysis"` and `"encryptedFieldsMap"` auto encryption options. Additional options pertaining to `crypt_shared` are now supported in the `"extraOptions"` auto encryption option.
PECL mongodb 1.13.0 | Added the `"srvMaxHosts"` and `"srvServiceName"` URI options.
PECL mongodb 1.12.0 | KMIP is now supported as a KMS provider for client-side encryption and may be configured in the `"kmsProviders"` field of the `"autoEncryption"` driver option. Additionally, TLS options for KMS providers may now be configured in the `"tlsOptions"` field of the `"autoEncryption"` driver option.
PECL mongodb 1.11.0 | Added the `"loadBalanced"` URI option.
PECL mongodb 1.10.0 | Added the `"disableClientPersistence"` driver option. Azure and GCP are now supported as KMS providers for client-side encryption and may be configured in the `"kmsProviders"` field of the `"autoEncryption"` driver option. Base64-encoded strings are now accepted as an alternative to MongoDB\BSON\Binary for options within `"kmsProviders"`.
PECL mongodb 1.8.0 | Added the `"directConnection"`, `"tlsDisableCertificateRevocationCheck"`, and `"tlsDisableOCSPEndpointCheck"` URI options. Added the `"driver"` driver option.
PECL mongodb 1.7.0 | Added the `"autoEncryption"` driver option. Specifying any SSL or TLS option via the `driverOptions` parameter will now implicitly enable TLS, as is done for the corresponding URI options.
PECL mongodb 1.6.0 | Added the `"retryReads"`, `"tls"`, `"tlsAllowInvalidCertificates"`, `"tlsAllowInvalidHostnames"`, `"tlsCAFile"`, `"tlsCertificateKeyFile"`, `"tlsCertificateKeyFilePassword"`, and `"tlsInsecure"` URI options. The `"retryWrites"` URI option defaults to `true`. Specifying any SSL or TLS URI option via the connection string or `uriOptions` parameter will now implicitly enable TLS unless `ssl` or `tls` is `false`. TLS is not implicitly enabled for any options in the `driverOptions` parameter, which is unchanged from previous versions.
PECL mongodb 1.5.0 | `"wtimeoutMS"` is now always validated and applied to the write concern. Previously, the option was ignored if `"w"` was <= 1, since the timeout only applies to replication.
PECL mongodb 1.4.0 | Added the `"compressors"`, `"retryWrites"`, and `"zlibCompressionLevel"` URI options.
PECL mongodb 1.3.0 | The `uriOptions` argument now accepts `"authMechanism"` and `"authMechanismProperties"` options. Previously, these options were only supported in the `uri` argument.
PECL mongodb 1.2.0 | The `uri` argument defaults to `"mongodb://127.0.0.1/"`. The default port remains `27017`. Added the `"appname"` URI option. Added the `"allow_invalid_hostname"`, `"ca_file"`, `"ca_dir"`, `"clr_file"`, `"pem_file"`, `"pem_pwd"`, and `"weak_cert_validation"` driver options. The PHP Streams API is no longer used for socket communication. The `"connectTimeoutMS"` URI option now defaults to 10 seconds instead of default_socket_timeout in previous versions. Additionally, the extension no longer supports all SSL context options via the `"context"` driver option.
PECL mongodb 1.1.0 | The `uri` argument is optional and defaults to `"mongodb://localhost:27017/"`.

### Beispiele

Beispiel #1 MongoDB\Driver\Manager::__construct() basic examples

Connecting to standalone MongoDB node:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");

    ?>

Connecting to standalone MongoDB node via a Unix domain socket. The socket path may include special characters such as slashes and should be encoded with rawurlencode().

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));

    ?>

Connecting to a replica set:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    ?>

Connecting to a sharded cluster (i.e. one or more mongos instances):

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");

    ?>

Connecting to MongoDB with authentication credentials for a particular user and database:

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://myusername:mypassword@example.com/?authSource=databaseName");

    ?>

Connecting to MongoDB with authentication credentials for a particular user and database, where the username or password includes special characters (e.g. `@`, `:`, `%`). In the following example, the password string `myp@ss:w%rd` has been manually escaped; however, rawurlencode() may also be used to escape URI components that may contain special characters.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://myusername:myp%40ss%3Aw%25rd@example.com/?authSource=databaseName");

    ?>

Connecting to MongoDB with X509 authentication:

    <?php

    $manager = new MongoDB\Driver\Manager(
        "mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",
        [],
        [
            "pem_file" => "/path/to/client.pem",
        ]
    );
    ?>

### Siehe auch

- Connection handling and persistence
- » MongoDB Connection String Format

# MongoDB\Driver\Manager::createClientEncryption

(mongodb >=1.7.0)

MongoDB\Driver\Manager::createClientEncryption — Create a new ClientEncryption object

### Beschreibung

final public function MongoDB\Driver\Manager::createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption

Constructs a new MongoDB\Driver\ClientEncryption object with the specified options.

### Parameter-Liste

`options`

  options
  Option | Type | Description
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | Der Manager, der verwendet wird, um Datenschlüssel-Abfragen auf einen anderen MongoDB-Cluster zu routen. Standardmäßig werden der aktuelle Manager und Cluster verwendet.
  keyVaultNamespace | string | Ein vollständig qualifizierter Namensraum (z. B. `"databaseName.collectionName"`), der die Kollektion bezeichnet, die alle Datenschlüssel enthält, die für Ver- und Entschlüsselung verwendet werden. Diese Option muss angegeben werden.
  kmsProviders | array | Ein Dokument, das die Konfiguration für einen oder mehrere KMS-Provider enthält, die verwendet werden, um Datenschlüssel zu verschlüsseln. Zu den unterstützten Providern gehören `"aws"`, `"azure"`, `"gcp"`, `"kmip"` und `"local"` und wenigstens einer muss angegeben werden. Wenn für `"aws"`, `"azure"` oder `"gcp"` ein leeres Dokument angegeben wird, versucht der Treiber, den Provider mit » Automatic Credentials (automatische Anmeldeinformationen) zu konfigurieren. Das Format für `"aws"` ist wie folgt:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  Das Format für `"azure"` ist wie folgt:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Der Standardwert ist "login.microsoftonline.com"
      }
  Das Format für `"gcp"` ist wie folgt:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Der Standardwert ist "oauth2.googleapis.com"
      }
  Das Format für `"kmip"` ist wie folgt:
      kmip: {
          endpoint: <string>
      }
  Das Format für `"local"` ist wie folgt:
      local: {
          // Der 96-Byte-Hauptschlüssel, der zur Ver- und Entschlüsselung von
          // Datenschlüsseln verwendet wird
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Ein Dokument, das die TLS-Konfiguration für einen oder mehrere KMS-Provider enthält. Zu den unterstützten Providern gehören `"aws"`, `"azure"`, `"gcp"` und `"kmip"`. Alle Provider unterstützen die folgenden Optionen:
      <provider>: {
          tlsCaFile: <optionale Zeichenkette>,
          tlsCertificateKeyFile: <optionale Zeichenkette>,
          tlsCertificateKeyFilePassword: <optionale Zeichenkette>,
          tlsDisableOCSPEndpointCheck: <optionaler Boolean>
      }

### Rückgabewerte

Returns a new MongoDB\Driver\ClientEncryption instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\RuntimeException if the extension was compiled without libmongocrypt support

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.16.0 | The AWS KMS provider for client-side encryption now accepts a `"sessionToken"` option, which can be used to authenticate with temporary AWS credentials. Added `"tlsDisableOCSPEndpointCheck"` to the `"tlsOptions"` option. If an empty document is specified for the `"azure"` or `"gcp"` KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.
PECL mongodb 1.15.0 | If an empty document is specified for the `"aws"` KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.
PECL mongodb 1.12.0 | KMIP is now supported as a KMS provider for client-side encryption and may be configured in the `"kmsProviders"` option. Added the `"tlsOptions"` option.
PECL mongodb 1.10.0 | Azure and GCP are now supported as KMS providers for client-side encryption and may be configured in the `"kmsProviders"` option. Base64-encoded strings are now accepted as an alternative to MongoDB\BSON\Binary for options within `"kmsProviders"`.

### Siehe auch

- MongoDB\Driver\ClientEncryption::__construct() - Create a new ClientEncryption object
- » Explicit (Manual) Client-Side Field Level Encryption in the MongoDB manual

# MongoDB\Driver\Manager::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeBulkWrite — Execute one or more write operations

### Beschreibung

final public function MongoDB\Driver\Manager::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Executes one or more write operations on the primary server.

A MongoDB\Driver\BulkWrite can be constructed with one or more write operations of varying types (e.g. updates, deletes, and inserts). The driver will attempt to send operations of the same type to the server in as few requests as possible to optimize round trips.

The default value for the `"writeConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`bulk` (MongoDB\Driver\BulkWrite)

  Die auszuführenden Schreibvorgänge.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

### Rückgabewerte

Gibt bei Erfolg ein MongoDB\Driver\WriteResult zurück.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if `bulk` does not contain any write operations.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `bulk` has already been executed. MongoDB\Driver\BulkWrite objects may not be executed multiple times.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Wirft eine MongoDB\Driver\Exception\BulkWriteException, wenn ein Schreibvorgang fehlschlägt (z. B. wegen eines Schreibfehlers oder eines Fehlers bei der Anwendung einer Schreibanweisung).
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\WriteConcern instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\WriteConcern object as `options` is deprecated and will be removed in 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the `"session"` option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an `options` array. For backwards compatibility, this parameter will still accept a MongoDB\Driver\WriteConcern object.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException is now thrown if `bulk` does not contain any write operations. Previously, a MongoDB\Driver\Exception\BulkWriteException was thrown.

### Beispiele

Beispiel #1 MongoDB\Driver\Manager::executeBulkWrite() example

    <?php

    $bulk = new MongoDB\Driver\BulkWrite();

    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);

    $bulk->update(['x' => 2], ['$set' => ['x' => 1]], ['multi' => false, 'upsert' => false]);
    $bulk->update(['x' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);
    $bulk->update(['_id' => 3], ['$set' => ['x' => 3]], ['multi' => false, 'upsert' => true]);

    $bulk->insert(['_id' => 4, 'x' => 2]);

    $bulk->delete(['x' => 1], ['limit' => 1]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 100);
    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Matched  %d document(s)\n", $result->getMatchedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());
    printf("Upserted %d document(s)\n", $result->getUpsertedCount());
    printf("Deleted  %d document(s)\n", $result->getDeletedCount());

    foreach ($result->getUpsertedIds() as $index => $id) {
        printf('upsertedId[%d]: ', $index);
        var_dump($id);
    }

    /* If the WriteConcern could not be fulfilled */
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf("%s (%d): %s\n", $writeConcernError->getMessage(), $writeConcernError->getCode(), var_export($writeConcernError->getInfo(), true));
    }

    /* If a write could not happen at all */
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Operation#%d: %s (%d)\n", $writeError->getIndex(), $writeError->getMessage(), $writeError->getCode());
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Inserted 3 document(s)
    Matched  1 document(s)
    Updated  1 document(s)
    Upserted 2 document(s)
    Deleted  1 document(s)
    upsertedId[3]: object(MongoDB\BSON\ObjectId)#5 (1) {
      ["oid"]=>
      string(24) "54d3adc3ce7a792f4d703756"
    }
    upsertedId[4]: int(3)

### Siehe auch

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWrite() - Execute one or more write operations on this server

# MongoDB\Driver\Manager::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Manager::executeBulkWriteCommand — Execute write operations using the bulkWrite command

### Beschreibung

final public function MongoDB\Driver\Manager::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Executes one or more write operations on the primary server using the » bulkWrite command introduced in MongoDB 8.0.

A MongoDB\Driver\BulkWriteCommand can be constructed with one or more write operations of varying types (e.g. inserts, updates, and deletes). Each write operation may target a different collection.

The default value for the `"writeConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### Parameter-Liste

`bulk` (MongoDB\Driver\BulkWriteCommand)

  Die auszuführenden Schreibvorgänge.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

### Rückgabewerte

Gibt bei Erfolg ein MongoDB\Driver\BulkWriteCommandResult zurück.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if `bulk` does not contain any write operations.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `bulk` has already been executed. MongoDB\Driver\BulkWriteCommand objects may not be executed multiple times.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Wirft eine MongoDB\Driver\Exception\BulkWriteCommandException, wenn ein Schreibvorgang fehlschlägt (z. B. fehlgeschlagener Befehl, Fehler beim Schreiben oder bei der Schreibanweisung)
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Beispiele

Beispiel #1 Mixed write operations

Mixed write operations (i.e. inserts, updates, and deletes) will be sent to the server using a single » bulkWrite command.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Delete documents from both collections
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insert documents into two collections
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Update a document in "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Inserted 3 document(s)
    Updated  1 document(s)

Beispiel #2 Ordered write operations causing an error

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Inserted %d document(s)\n", $result->getInsertedCount());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Inserted 2 document(s)

### Siehe auch

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWriteCommand() - Execute write operations on this server using the bulkWrite command

# MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommand — Execute a database command

### Beschreibung

final public function MongoDB\Driver\Manager::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Selects a server according to the `"readPreference"` option and executes the command on that server.

This method applies no special logic to the command. The Default values for the `"readPreference"`, `"readConcern"`, and `"writeConcern"` options will be inferred from an active transaction (indicated by the `"session"` option). If there is no active transaction, a primary read preference will be used for server selection.

Default values will not be inferred from the connection URI. Users are therefore encouraged to use specific read and/or write command methods if possible.

### Parameter-Liste

`db` (string)

  The name of the database on which to execute the command.

`command` (MongoDB\Driver\Command)

  Der auszuführende Befehl.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Ein Leseanliegen (Read Concern), das auf den Vorgang angewendet werden soll. Diese Option ist ab MongoDB 3.2 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  readPreference | MongoDB\Driver\ReadPreference | Eine Lesepräferenz, die verwendet wird, um einen Server für die Operation auszuwählen.
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

  Warnung

  If you are using a `"session"` which has a transaction in progress, you cannot specify a `"readConcern"` or `"writeConcern"` option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` mit einer zugehörigen Transaktion in Kombination mit einer der Optionen `"readConcern"` oder `"writeConcern"` verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command, issuing a write command to a secondary).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\ReadPreference instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\ReadPreference object as `options` is deprecated and will be removed in 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the `"session"` option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an `options` array. For backwards compatibility, this parameter will still accept a MongoDB\Driver\ReadPreference object.

### Beispiele

Beispiel #1 MongoDB\Driver\Manager::executeCommand() with a command returning a single result document

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $command = new MongoDB\Driver\Command(['ping' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* The ping command returns a single result document, so we need to access the
     * first result in the cursor. */
    $response = $cursor->toArray()[0];

    var_dump($response);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["ok"]=>
      float(1)
    }

Beispiel #2 MongoDB\Driver\Manager::executeCommand() with a command returning a cursor

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1, 'y' => 'foo']);
    $bulk->insert(['x' => 2, 'y' => 'bar']);
    $bulk->insert(['x' => 3, 'y' => 'bar']);
    $manager->executeBulkWrite('db.collection', $bulk);

    $command = new MongoDB\Driver\Command([
        'aggregate' => 'collection',
        'pipeline' => [
            ['$group' => ['_id' => '$y', 'sum' => ['$sum' => '$x']]],
        ],
        'cursor' => new stdClass,
    ]);
    $cursor = $manager->executeCommand('db', $command);

    /* The aggregate command can optionally return its results in a cursor instead
     * of a single result document. In this case, we can iterate on the cursor
     * directly to access those results. */
    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(stdClass)#6 (2) {
      ["_id"]=>
      string(3) "bar"
      ["sum"]=>
      int(10)
    }
    object(stdClass)#7 (2) {
      ["_id"]=>
      string(3) "foo"
      ["sum"]=>
      int(2)
    }

Beispiel #3 Limiting execution time for a command

The execution time of a command may be limited by specifying a value for `"maxTimeMS"` in the MongoDB\Driver\Command document. Note that this time limit is enforced on the server side and does not take network latency into account. See » Terminate Running Operations in the MongoDB manual for more information.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $command = new MongoDB\Driver\Command([
        'count' => 'collection',
        'query' => ['x' => ['$gt' => 1]],
        'maxTimeMS' => 1000,
    ]);

    $cursor = $manager->executeCommand('db', $command);

    var_dump($cursor->toArray()[0]);

    ?>

If the command fails to complete after one second of execution time on the server, a MongoDB\Driver\Exception\ExecutionTimeoutException will be thrown.

### Anmerkungen

> Hinweis: If a secondary `readPreference` is used, it is the caller's responsibility to ensure that the `command` can be executed on a secondary. No validation is done by the driver.

> Hinweis: This method does not default to using the read preference from the MongoDB Connection URI. Applications in need of that behavior should consider using MongoDB\Driver\Manager::executeReadCommand().

### Siehe auch

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeReadCommand() - Execute a database command that reads
- MongoDB\Driver\Manager::executeReadWriteCommand() - Execute a database command that reads and writes
- MongoDB\Driver\Manager::executeWriteCommand() - Execute a database command that writes
- MongoDB\Driver\Server::executeCommand() - Execute a database command on this server

# MongoDB\Driver\Manager::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeQuery — Execute a database query

### Beschreibung

final public function MongoDB\Driver\Manager::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Selects a server according to the `"readPreference"` option and executes the query on that server.

Default values for the `"readPreference"` option and Query's `"readConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`query` (MongoDB\Driver\Query)

  Die auszuführende Abfrage.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Eine Lesepräferenz, die verwendet wird, um einen Server für die Operation auszuwählen.
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid query operators).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\ReadPreference instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\ReadPreference object as `options` is deprecated and will be removed in 2.0.
PECL mongodb 1.4.0 | The third parameter is now an `options` array. For backwards compatibility, this parameter will still accept a MongoDB\Driver\ReadPreference object.

### Beispiele

Beispiel #1 MongoDB\Driver\Manager::executeQuery() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'projection' => ['_id' => 0],
        'sort' => ['x' => -1],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(stdClass)#6 (1) {
      ["x"]=>
      int(3)
    }
    object(stdClass)#7 (1) {
      ["x"]=>
      int(2)
    }

Beispiel #2 Limiting execution time for a query

The `"maxTimeMS"` MongoDB\Driver\Query option may be used to limit the execution time of a query. Note that this time limit is enforced on the server side and does not take network latency into account. See » Terminate Running Operations in the MongoDB manual for more information.

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');

    $filter = ['x' => ['$gt' => 1]];
    $options = [
        'maxTimeMS' => 1000,
    ];

    $query = new MongoDB\Driver\Query($filter, $options);
    $cursor = $manager->executeQuery('db.collection', $query);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

If the query fails to complete after one second of execution time on the server, a MongoDB\Driver\Exception\ExecutionTimeoutException will be thrown.

### Siehe auch

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Server::executeQuery() - Execute a database query on this server

# MongoDB\Driver\Manager::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadCommand — Execute a database command that reads

### Beschreibung

final public function MongoDB\Driver\Manager::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Selects a server according to the `"readPreference"` option and executes the command on that server.

This method will apply logic that is specific to commands that read (e.g. » distinct). Default values for the `"readPreference"` and `"readConcern"` options will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### Parameter-Liste

`db` (string)

  The name of the database on which to execute the command.

`command` (MongoDB\Driver\Command)

  Der auszuführende Befehl.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Ein Leseanliegen (Read Concern), das auf den Vorgang angewendet werden soll. Diese Option ist ab MongoDB 3.2 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  readPreference | MongoDB\Driver\ReadPreference | Eine Lesepräferenz, die verwendet wird, um einen Server für die Operation auszuwählen.
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.

  Warnung

  If you are using a `"session"` which has a transaction in progress, you cannot specify a `"readConcern"` or `"writeConcern"` option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` mit einer zugehörigen Transaktion in Kombination mit einer der Optionen `"readConcern"` oder `"writeConcern"` verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### Siehe auch

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Execute a database command
- MongoDB\Driver\Manager::executeReadWriteCommand() - Execute a database command that reads and writes
- MongoDB\Driver\Manager::executeWriteCommand() - Execute a database command that writes
- MongoDB\Driver\Server::executeReadCommand() - Execute a database command that reads on this server

# MongoDB\Driver\Manager::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadWriteCommand — Execute a database command that reads and writes

### Beschreibung

final public function MongoDB\Driver\Manager::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executes the command on the primary server.

This method will apply logic that is specific to commands that read and write (e.g. » aggregate). Default values for the `"readConcern"` and `"writeConcern"` options will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### Parameter-Liste

`db` (string)

  The name of the database on which to execute the command.

`command` (MongoDB\Driver\Command)

  Der auszuführende Befehl.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Ein Leseanliegen (Read Concern), das auf den Vorgang angewendet werden soll. Diese Option ist ab MongoDB 3.2 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

  Warnung

  If you are using a `"session"` which has a transaction in progress, you cannot specify a `"readConcern"` or `"writeConcern"` option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` mit einer zugehörigen Transaktion in Kombination mit einer der Optionen `"readConcern"` oder `"writeConcern"` verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the `"session"` option is used in combination with an unacknowledged write concern.

### Siehe auch

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Execute a database command
- MongoDB\Driver\Manager::executeReadCommand() - Execute a database command that reads
- MongoDB\Driver\Manager::executeWriteCommand() - Execute a database command that writes
- MongoDB\Driver\Server::executeReadWriteCommand() - Execute a database command that reads and writes on this server

# MongoDB\Driver\Manager::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeWriteCommand — Execute a database command that writes

### Beschreibung

final public function MongoDB\Driver\Manager::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executes the command on the primary server.

This method will apply logic that is specific to commands that write (e.g. » drop). The default value for the `"writeConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

> Hinweis: This method is not intended to be used to execute » insert, » update, or » delete commands. Users are encouraged to use MongoDB\Driver\Manager::executeBulkWrite() for those operations.

### Parameter-Liste

`db` (string)

  The name of the database on which to execute the command.

`command` (MongoDB\Driver\Command)

  Der auszuführende Befehl.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

  Warnung

  If you are using a `"session"` which has a transaction in progress, you cannot specify a `"readConcern"` or `"writeConcern"` option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` mit einer zugehörigen Transaktion in Kombination mit einer der Optionen `"readConcern"` oder `"writeConcern"` verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the `"session"` option is used in combination with an unacknowledged write concern.

### Siehe auch

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Manager::executeCommand() - Execute a database command
- MongoDB\Driver\Manager::executeReadCommand() - Execute a database command that reads
- MongoDB\Driver\Manager::executeReadWriteCommand() - Execute a database command that reads and writes
- MongoDB\Driver\Server::executeWriteCommand() - Execute a database command that writes on this server

# MongoDB\Driver\Manager::getEncryptedFieldsMap

(mongodb >=1.14.0)

MongoDB\Driver\Manager::getEncryptedFieldsMap — Return the encryptedFieldsMap auto encryption option for the Manager

### Beschreibung

final public function MongoDB\Driver\Manager::getEncryptedFieldsMap(): array|object|null

Returns the `encryptedFieldsMap` auto encryption option for the Manager, if specified.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The `encryptedFieldsMap` auto encryption option for the Manager, or `null` if it was not specified.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager

# MongoDB\Driver\Manager::getReadConcern

(mongodb >=1.1.0)

MongoDB\Driver\Manager::getReadConcern — Return the ReadConcern for the Manager

### Beschreibung

final public function MongoDB\Driver\Manager::getReadConcern(): MongoDB\Driver\ReadConcern

Returns the MongoDB\Driver\ReadConcern for the Manager, which is derived from its URI options. This is the default read concern for queries and commands executed on the Manager.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The MongoDB\Driver\ReadConcern for the Manager.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Manager::getReadConcern() example

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readConcernLevel=local');
    var_dump($manager->getReadConcern());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\Driver\ReadConcern)#2 (0) {
    }
    object(MongoDB\Driver\ReadConcern)#1 (1) {
      ["level"]=>
      string(5) "local"
    }

### Siehe auch

- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager

# MongoDB\Driver\Manager::getReadPreference

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getReadPreference — Return the ReadPreference for the Manager

### Beschreibung

final public function MongoDB\Driver\Manager::getReadPreference(): MongoDB\Driver\ReadPreference

Returns the MongoDB\Driver\ReadPreference for the Manager, which is derived from its URI options. This is the default read preference for queries and commands executed on the Manager.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The MongoDB\Driver\ReadPreference for the Manager.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Manager::getReadPreference() example

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getReadPreference());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=');
    var_dump($manager->getReadPreference());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\Driver\ReadPreference)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(18) "secondaryPreferred"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#3 (2) {
          ["dc"]=>
          string(2) "ny"
          ["rack"]=>
          string(1) "1"
        }
        [1]=>
        object(stdClass)#4 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [2]=>
        object(stdClass)#5 (0) {
        }
      }
    }

### Siehe auch

- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager

# MongoDB\Driver\Manager::getServers

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getServers — Return the servers to which this manager is connected

### Beschreibung

final public function MongoDB\Driver\Manager::getServers(): array

Returns an array of MongoDB\Driver\Server instances to which this manager is connected.

> Hinweis: Since the driver connects to the database lazily, this method may return an empty array if called before executing an operation on the MongoDB\Driver\Manager.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of MongoDB\Driver\Server instances to which this manager is connected.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Manager::getServers() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    /* The driver connects to the database server lazily, so Manager::getServers()
     * may initially return an empty array. */
    var_dump($manager->getServers());

    $command = new MongoDB\Driver\Command(['ping' => 1]);
    $manager->executeCommand('db', $command);

    var_dump($manager->getServers());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(0) {
    }
    array(1) {
      [0]=>
      object(MongoDB\Driver\Server)#3 (10) {
        ["host"]=>
        string(9) "localhost"
        ["port"]=>
        int(27017)
        ["type"]=>
        int(1)
        ["is_primary"]=>
        bool(false)
        ["is_secondary"]=>
        bool(false)
        ["is_arbiter"]=>
        bool(false)
        ["is_hidden"]=>
        bool(false)
        ["is_passive"]=>
        bool(false)
        ["last_hello_response"]=>
        array(8) {
          ["isWritablePrimary"]=>
          bool(true)
          ["maxBsonObjectSize"]=>
          int(16777216)
          ["maxMessageSizeBytes"]=>
          int(48000000)
          ["maxWriteBatchSize"]=>
          int(1000)
          ["localTime"]=>
          object(MongoDB\BSON\UTCDateTime)#4 (1) {
            ["milliseconds"]=>
            int(1447267964517)
          }
          ["maxWireVersion"]=>
          int(3)
          ["minWireVersion"]=>
          int(0)
          ["ok"]=>
          float(1)
        }
        ["round_trip_time"]=>
        int(554)
      }
    }

### Siehe auch

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::selectServer() - Select a server matching a read preference

# MongoDB\Driver\Manager::getWriteConcern

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getWriteConcern — Return the WriteConcern for the Manager

### Beschreibung

final public function MongoDB\Driver\Manager::getWriteConcern(): MongoDB\Driver\WriteConcern

Returns the MongoDB\Driver\WriteConcern for the Manager, which is derived from its URI options. This is the default write concern for writes and commands executed on the Manager.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The MongoDB\Driver\WriteConcern for the Manager.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Manager::getWriteConcern() example

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    var_dump($manager->getWriteConcern());

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/?w=majority&wtimeoutMS=2000');
    var_dump($manager->getWriteConcern());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\Driver\WriteConcern)#2 (0) {
    }
    object(MongoDB\Driver\WriteConcern)#1 (2) {
      ["w"]=>
      string(8) "majority"
      ["wtimeout"]=>
      int(2000)
    }

### Siehe auch

- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager

# MongoDB\Driver\Manager::removeSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::removeSubscriber — Unregisters a monitoring event subscriber with this Manager

### Beschreibung

final public function MongoDB\Driver\Manager::removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Unregisters a monitoring event subscriber with this Manager.

> Hinweis: If `subscriber` is not already registered with this Manager, this function is a no-op.

### Parameter-Liste

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  A monitoring event subscriber to unregister with this Manager.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\removeSubscriber() - Unregisters a monitoring event subscriber globally
- Application Performance Monitoring (APM)

# MongoDB\Driver\Manager::selectServer

(mongodb >=1.0.0)

MongoDB\Driver\Manager::selectServer — Select a server matching a read preference

### Beschreibung

final public function MongoDB\Driver\Manager::selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server

Selects a MongoDB\Driver\Server matching `readPreference`. If `readPreference` is `null` or omitted, the primary server will be selected by default. This may be used to preselect a server in order to perform version checking before executing an operation.

> Hinweis: Unlike MongoDB\Driver\Manager::getServers(), this method will initialize database connections and perform server discovery if necessary. See the » Server Selection Specification for additional information.

### Parameter-Liste

`readPreference` (MongoDB\Driver\ReadPreference)
  The read preference to use for selecting a server. If `null` or omitted, the primary server will be selected by default.

### Rückgabewerte

Returns a MongoDB\Driver\Server matching the read preference.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException if a server matching the read preference could not be found.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.11.0 | The `readPreference` is now optional. If `null` or omitted, the primary server will be selected by default.

### Siehe auch

- MongoDB\Driver\Server
- MongoDB\Driver\Manager::getServers() - Return the servers to which this manager is connected
- » Server Selection Specification

# MongoDB\Driver\Manager::startSession

(mongodb >=1.4.0)

MongoDB\Driver\Manager::startSession — Start a new client session for use with this client

### Beschreibung

final public function MongoDB\Driver\Manager::startSession(?array `$options` = `null`): MongoDB\Driver\Session

Creates a MongoDB\Driver\Session for the given options. The session may then be specified when executing commands, queries, and write operations.

> Hinweis: A MongoDB\Driver\Session can only be used with the MongoDB\Driver\Manager from which it was created.

### Parameter-Liste

`options`

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  causalConsistency | bool | Configure causal consistency in a session. If `true`, each operation in the session will be causally ordered after the previous read or write operation. Set to `false` to disable causal consistency. See » Causal Consistency in the MongoDB manual for more information. | `true`
  defaultTransactionOptions | array | Default options to apply to newly created transactions. These options are used unless they are overridden when a transaction is started with different value for each option.
  options
  Option | Type | Description
  --- | --- | ---
  maxCommitTimeMS | integer | Die maximale Dauer in Millisekunden, die ein einziger `commitTransaction`-Befehl beanspruchen darf. Wenn angegeben, muss `maxCommitTimeMS` eine vorzeichenbehaftete 32-bit Ganzzahl größer als oder gleich Null sein.
  readConcern | MongoDB\Driver\ReadConcern | Ein Leseanliegen (Read Concern), das auf den Vorgang angewendet werden soll. Diese Option ist ab MongoDB 3.2 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  readPreference | MongoDB\Driver\ReadPreference | Eine Lesepräferenz, die verwendet wird, um einen Server für die Operation auszuwählen.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.
  This option is available in MongoDB 4.0+. | `[]`
  snapshot | bool | Configure snapshot reads in a session. If `true`, a timestamp will be obtained from the first supported read operation in the session (i.e. `find`, `aggregate`, or unsharded `distinct`). Subsequent read operations within the session will then utilize a `"snapshot"` read concern level to read majority-committed data from that timestamp. Set to `false` to disable snapshot reads. Snapshot reads require MongoDB 5.0+ and cannot be used with causal consistency, transactions, or write operations. If `"snapshot"` is `true`, `"causalConsistency"` will default to `false`. See » Read Concern "snapshot" in the MongoDB manual for more information. | `false`

### Rückgabewerte

Returns a MongoDB\Driver\Session.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"causalConsistency"` and `"snapshot"` options are both `true`.
- Throws MongoDB\Driver\Exception\RuntimeException if the session could not be created (e.g. libmongoc does not support crypto).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.11.0 | The `"snapshot"` option was added.
PECL mongodb 1.6.0 | The `"maxCommitTimeMS"` option was added to `"defaultTransactionOptions"`.
PECL mongodb 1.5.0 | The `"defaultTransactionOptions"` option was added.

### Siehe auch

- MongoDB\Driver\Session
- » Causal Consistency in the MongoDB manual

## Inhaltsverzeichnis

- MongoDB\Driver\Manager::addSubscriber — Registers a monitoring event subscriber with this Manager
- MongoDB\Driver\Manager::__construct — Create new MongoDB Manager
- MongoDB\Driver\Manager::createClientEncryption — Create a new ClientEncryption object
- MongoDB\Driver\Manager::executeBulkWrite — Execute one or more write operations
- MongoDB\Driver\Manager::executeBulkWriteCommand — Execute write operations using the bulkWrite command
- MongoDB\Driver\Manager::executeCommand — Execute a database command
- MongoDB\Driver\Manager::executeQuery — Execute a database query
- MongoDB\Driver\Manager::executeReadCommand — Execute a database command that reads
- MongoDB\Driver\Manager::executeReadWriteCommand — Execute a database command that reads and writes
- MongoDB\Driver\Manager::executeWriteCommand — Execute a database command that writes
- MongoDB\Driver\Manager::getEncryptedFieldsMap — Return the encryptedFieldsMap auto encryption option for the Manager
- MongoDB\Driver\Manager::getReadConcern — Return the ReadConcern for the Manager
- MongoDB\Driver\Manager::getReadPreference — Return the ReadPreference for the Manager
- MongoDB\Driver\Manager::getServers — Return the servers to which this manager is connected
- MongoDB\Driver\Manager::getWriteConcern — Return the WriteConcern for the Manager
- MongoDB\Driver\Manager::removeSubscriber — Unregisters a monitoring event subscriber with this Manager
- MongoDB\Driver\Manager::selectServer — Select a server matching a read preference
- MongoDB\Driver\Manager::startSession — Start a new client session for use with this client

# The MongoDB\Driver\Command class

(mongodb >=1.0.0)

## Einführung

The MongoDB\Driver\Command class is a value object that represents a database command.

To provide Command Helpers the MongoDB\Driver\Command object should be composed.

## Klassenbeschreibung

final class MongoDB\Driver\Command {
/* Methoden */
final public function __construct(array|object `$document`, ?array `$commandOptions` = `null`)
}

## Beispiele

Beispiel #1 Composing MongoDB\Driver\Command to provide a helper to create collections

    <?php
    class CreateCollection {
        protected $cmd = array();

        function __construct($collectionName) {
            $this->cmd["create"] = (string) $collectionName;
        }
        function setCappedCollection($maxBytes, $maxDocuments = false) {
            $this->cmd["capped"] = true;
            $this->cmd["size"]   = (int) $maxBytes;

            if ($maxDocuments) {
                $this->cmd["max"] = (int) $maxDocuments;
            }
        }
        function usePowerOf2Sizes($bool) {
            if ($bool) {
                $this->cmd["flags"] = 1;
            } else {
                $this->cmd["flags"] = 0;
            }
        }
        function setFlags($flags) {
            $this->cmd["flags"] = (int) $flags;
        }
        function getCommand() {
            return new MongoDB\Driver\Command($this->cmd);
        }
        function getCollectionName() {
            return $this->cmd["create"];
        }
    }

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $createCollection = new CreateCollection("cappedCollection");
    $createCollection->setCappedCollection(64 * 1024);

    try {
        $command = $createCollection->getCommand();
        $cursor = $manager->executeCommand("databaseName", $command);
        $response = $cursor->toArray()[0];
        var_dump($response);

        $collstats = ["collstats" => $createCollection->getCollectionName()];
        $cursor = $manager->executeCommand("databaseName", new MongoDB\Driver\Command($collstats));
        $response = $cursor->toArray()[0];
        var_dump($response);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MongoDB\Driver\Command)#3 (1) {
      ["command"]=>
      array(3) {
        ["create"]=>
        string(16) "cappedCollection"
        ["capped"]=>
        bool(true)
        ["size"]=>
        int(65536)
      }
    }
    array(1) {
      ["ok"]=>
      float(1)
    }
    array(16) {
      ["ns"]=>
      string(29) "databaseName.cappedCollection"
      ["count"]=>
      int(0)
      ["size"]=>
      int(0)
      ["numExtents"]=>
      int(1)
      ["storageSize"]=>
      int(65536)
      ["nindexes"]=>
      int(1)
      ["lastExtentSize"]=>
      float(65536)
      ["paddingFactor"]=>
      float(1)
      ["paddingFactorNote"]=>
      string(101) "paddingFactor is unused and unmaintained in 2.8. It remains hard coded to 1.0 for compatibility only."
      ["userFlags"]=>
      int(0)
      ["capped"]=>
      bool(true)
      ["max"]=>
      int(9223372036854775807)
      ["maxSize"]=>
      int(65536)
      ["totalIndexSize"]=>
      int(8176)
      ["indexSizes"]=>
      object(stdClass)#4 (1) {
        ["_id_"]=>
        int(8176)
      }
      ["ok"]=>
      float(1)
    }

# MongoDB\Driver\Command::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Command::__construct — Create a new Command

### Beschreibung

final public function MongoDB\Driver\Command::__construct(array|object `$document`, ?array `$commandOptions` = `null`)

Constructs a new MongoDB\Driver\Command, which is an immutable value object that represents a database command. The command may then be executed with MongoDB\Driver\Manager::executeCommand().

The complete command document, which includes the command name and its options, should be expressed in the `document` parameter. The `commandOptions` parameter is only used to specify options related to the execution of the command and the resulting MongoDB\Driver\Cursor.

### Parameter-Liste

`document`
  The complete command document, which will be sent to the server.
`commandOptions`

  > Hinweis: Do not use this parameter to specify options described in the command's reference in the MongoDB manual. This parameter should only be used for the options explicitly listed below.

  commandOptions
  Option | Type | Description
  --- | --- | ---
  maxAwaitTimeMS | int | Positive integer denoting the time limit in milliseconds for the server to block a getMore operation if no data is available. This option should only be used in conjunction with commands that return a tailable cursor (e.g. » Change Streams).

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.4.0 | Added a second `commandOptions` argument, which supports the `"maxAwaitTimeMS"` option.

### Beispiele

Beispiel #1 MongoDB\Driver\Command::__construct() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(array("buildinfo" => 1));

    try {
        $cursor = $manager->executeCommand("admin", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(13) {
      ["version"]=>
      string(14) "2.8.0-rc2-pre-"
      ["gitVersion"]=>
      string(62) "b743d7158f7642f4da6b7eac8320374b3b88dc2e modules: subscription"
      ["OpenSSLVersion"]=>
      string(25) "OpenSSL 1.0.1f 6 Jan 2014"
      ["sysInfo"]=>
      string(104) "Linux infant 3.16.0-24-generic #32-Ubuntu SMP Tue Oct 28 13:07:32 UTC 2014 x86_64 BOOST_LIB_VERSION=1_49"
      ["loaderFlags"]=>
      string(91) "-fPIC -pthread -Wl,-z,now -rdynamic -Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -Wl,-E"
      ["compilerFlags"]=>
      string(301) "-Wnon-virtual-dtor -Woverloaded-virtual -std=c++11 -fPIC -fno-strict-aliasing -ggdb -pthread -Wall -Wsign-compare -Wno-unknown-pragmas -Winvalid-pch -pipe -Werror -O3 -Wno-unused-local-typedefs -Wno-unused-function -Wno-deprecated-declarations -Wno-unused-but-set-variable -fno-builtin-memcmp -std=c99"
      ["allocator"]=>
      string(8) "tcmalloc"
      ["versionArray"]=>
      array(4) {
        [0]=>
        int(2)
        [1]=>
        int(8)
        [2]=>
        int(0)
        [3]=>
        int(-8)
      }
      ["javascriptEngine"]=>
      string(2) "V8"
      ["bits"]=>
      int(64)
      ["debug"]=>
      bool(false)
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["ok"]=>
      float(1)
    }

Beispiel #2 MongoDB\Driver\Command::__construct() example

Commands can accept options as well, as part of the normal structure that you create to send to the server. For example, the `maxTimeMS` option can be passed with most commands to restrict the amount of time a specific command can run for on the server.

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $command = new MongoDB\Driver\Command(
        array(
            "distinct" => "beer",
            "key" => "beer_name",
            "maxTimeMS" => 10,
        )
    );

    try {
        $cursor = $manager->executeCommand("beerdb", $command);
        $response = $cursor->toArray()[0];
    } catch(MongoDB\Driver\Exception\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }
    var_dump($response);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

operation exceeded time limit

### Siehe auch

- MongoDB\Driver\Manager::executeCommand() - Execute a database command
- MongoDB\Driver\Cursor

## Inhaltsverzeichnis

- MongoDB\Driver\Command::__construct — Create a new Command

# The MongoDB\Driver\Query class

(mongodb >=1.0.0)

## Einführung

The MongoDB\Driver\Query class is a value object that represents a database query.

## Klassenbeschreibung

final class MongoDB\Driver\Query {
/* Methoden */
final public function __construct(array|object `$filter`, ?array `$queryOptions` = `null`)
}

# MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__construct — Create a new Query

### Beschreibung

final public function MongoDB\Driver\Query::__construct(array|object `$filter`, ?array `$queryOptions` = `null`)

Constructs a new MongoDB\Driver\Query, which is an immutable value object that represents a database query. The query may then be executed with MongoDB\Driver\Manager::executeQuery().

### Parameter-Liste

`filter` (array|object)

  Das » Abfrage-Prädikat. Ein leeres Prädikat passt auf alle Dokumente in der Sammlung.

  > Hinweis: Bei der Auswertung von Abfragekriterien vergleicht MongoDB Typen und Werte gemäß seiner eigenen » Vergleichsregeln für BSON-Typen, die sich von PHPs Regeln für Typenvergleich und Typen-Jonglage unterscheidet. Wenn es eine Übereinstimmung mit einem speziellen BSON-Typ gibt, sollten die Abfragekriterien die entsprechende BSON-Klasse verwenden (z. B. MongoDB\BSON\ObjectId, um auf eine » ObjectId zu passen).

`queryOptions`

  queryOptions
  Option | Type | Description
  --- | --- | ---
  allowDiskUse | bool | Allows MongoDB to use temporary disk files to store data exceeding the 100 megabyte system memory limit while processing a blocking sort operation.
  allowPartialResults | bool | For queries against a sharded collection, returns partial results from the mongos if some shards are unavailable instead of throwing an error. Falls back to the deprecated `"partial"` option if not specified.
  awaitData | bool | Use in conjunction with the `"tailable"` option to block a getMore operation on the cursor temporarily if at the end of data rather than returning no data. After a timeout period, the query returns as normal.
  batchSize | int | The number of documents to return in the first batch. Defaults to 101. A batch size of 0 means that the cursor will be established, but no documents will be returned in the first batch. In versions of MongoDB before 3.2, where queries use the legacy wire protocol OP_QUERY, a batch size of 1 will close the cursor irrespective of the number of matched documents.
  collation | array|object | Die » Collation (Vergleichs-/Sortierregel) ermöglicht es dem Benutzer, sprachspezifische Regeln für den Vergleich von Zeichenketten anzugeben, so z. B. Regeln für die Groß- und Kleinschreibung und Akzentzeichen. Bei der Angabe der Sortierung ist das Feld `"locale"` obligatorisch; alle anderen Sortierfelder sind optional. Die Beschreibungen der Felder sind unter » Collation Document zu finden. Wenn keine Kollation angegeben wurde, aber die Sammlung eine Standardkollation hat, verwendet die Operation die für die Sammlung angegebene Kollation. Wenn weder für die Sammlung noch für die Operation eine Kollation angegeben wurde, verwendet MongoDB den einfachen binären Vergleich, der in früheren Versionen für den Vergleich von Zeichenketten verwendet wurde. Diese Option ist ab MongoDB 3.4 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  comment | mixed | An arbitrary comment to help trace the operation through the database profiler, currentOp output, and logs. The comment can be any valid BSON type for MongoDB 4.4+. Earlier server versions only support string values. Falls back to the deprecated `"$comment"` modifier if not specified.
  exhaust | bool | Stream the data down full blast in multiple "more" packages, on the assumption that the client will fully read all data queried. Faster when you are pulling a lot of data and know you want to pull it all down. Note: the client is not allowed to not read all the data unless it closes the connection. This option is not supported by the find command in MongoDB 3.2+ and will force the driver to use the legacy wire protocol version (i.e. OP_QUERY).
  explain | bool | If `true`, the returned MongoDB\Driver\Cursor will contain a single document that describes the process and indexes used to return the query. Falls back to the deprecated `"$explain"` modifier if not specified. This option is not supported by the find command in MongoDB 3.2+ and will only be respected when using the legacy wire protocol version (i.e. OP_QUERY). The » explain command should be used on MongoDB 3.0+.
  hint | string|array|object | Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index. Falls back to the deprecated `"hint"` option if not specified.
  let | array|object | Die Zuordnung von Parameternamen und -werten. Die Werte müssen Konstanten oder geschlossene Ausdrücke sein, die nicht auf Dokumentfelder verweisen. Auf die Parameter kann dann als Variablen im Kontext eines aggregierten Ausdrucks zugegriffen werden (z. B. `$$var`). Diese Option ist ab MongoDB 5.0 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  limit | int | The maximum number of documents to return. If unspecified, then defaults to no limit. A limit of 0 is equivalent to setting no limit.
  max | array|object | The exclusive upper bound for a specific index. Falls back to the deprecated `"$max"` modifier if not specified.
  maxAwaitTimeMS | int | Positive integer denoting the time limit in milliseconds for the server to block a getMore operation if no data is available. This option should only be used in conjunction with the `"tailable"` and `"awaitData"` options.
  maxTimeMS | int | The cumulative time limit in milliseconds for processing operations on the cursor. MongoDB aborts the operation at the earliest following interrupt point. Falls back to the deprecated `"$maxTimeMS"` modifier if not specified.
  min | array|object | The inclusive lower bound for a specific index. Falls back to the deprecated `"$min"` modifier if not specified.
  noCursorTimeout | bool | Prevents the server from timing out idle cursors after an inactivity period (10 minutes).
  projection | array|object | The » projection specification to determine which fields to include in the returned documents. If you are using the ODM functionality to deserialise documents as their original PHP class, make sure that you include the __pclass field in the projection. This is required for the deserialization to work and without it, the extension will return (by default) a stdClass object instead.
  readConcern | MongoDB\Driver\ReadConcern | A read concern to apply to the operation. By default, the read concern from the MongoDB Connection URI will be used. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version.
  returnKey | bool | If `true`, returns only the index keys in the resulting documents. Default value is `false`. If `true` and the find command does not use an index, the returned documents will be empty. Falls back to the deprecated `"$returnKey"` modifier if not specified.
  showRecordId | bool | Determines whether to return the record identifier for each document. If `true`, adds a top-level `"$recordId"` field to the returned documents. Falls back to the deprecated `"$showDiskLoc"` modifier if not specified.
  singleBatch | bool | Determines whether to close the cursor after the first batch. Defaults to `false`.
  skip | int | Number of documents to skip. Defaults to 0.
  sort | array|object | The sort specification for the ordering of the results. Falls back to the deprecated `"$orderby"` modifier if not specified.
  tailable | bool | Returns a tailable cursor for a capped collection.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The `"partial"` option was removed. Use the `"allowPartialResults"` option instead. The `"maxScan"` option was removed. Support for this option was removed in MongoDB 4.2. The `"modifiers"` option was removed. This option was used for legacy query modifiers, which are all deprecated. The `"oplogReplay"` option was removed. It is ignored in MongoDB 4.4 and newer. The `"snapshot"` option was removed. Support for this option was removed in MongoDB 4.0. A negative value for the `"limit"` option no longer implies `true` for the `"singleBatch"` option. To only receive a single batch of results, combine a positive `"limit"` value with the `"singleBatch"` option.
PECL mongodb 1.14.0 | Added the `"let"` option. The `"comment"` option now accepts any type.
PECL mongodb 1.8.0 | Added the `"allowDiskUse"` option. The `"oplogReplay"` option is deprecated.
PECL mongodb 1.5.0 | The `"maxScan"` and `"snapshot"` options are deprecated.
PECL mongodb 1.3.0 | Added the `"maxAwaitTimeMS"` option.
PECL mongodb 1.2.0 | Added the `"allowPartialResults"`, `"collation"`, `"comment"`, `"hint"`, `"max"`, `"maxScan"`, `"maxTimeMS"`, `"min"`, `"returnKey"`, `"showRecordId"`, and `"snapshot"` options. Renamed the `"partial"` option to `"allowPartialResults"`. For backwards compatibility, `"partial"` will still be read if `"allowPartialResults"` is not specified. Removed the legacy `"secondaryOk"` option, which is obsolete. For queries using the legacy wire protocol OP_QUERY, the driver will set the `secondaryOk` bit as needed in accordance with the » Server Selection Specification.
PECL mongodb 1.1.0 | Added the `"readConcern"` option.

### Beispiele

Beispiel #1 MongoDB\Driver\Query::__construct() example

    <?php
    /* Select only documents authord by "bjori" with at least 100 views */
    $filter = [
        'author' => 'bjori',
        'views' => [
            '$gte' => 100,
        ],
    ];

    $options = [
        /* Only return the following fields in the matching documents */
        'projection' => [
            'title' => 1,
            'article' => 1,
        ],
        /* Return the documents in descending order of views */
        'sort' => [
            'views' => -1
        ],
    ];

    $query = new MongoDB\Driver\Query($filter, $options);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $readPreference = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    $cursor = $manager->executeQuery('databaseName.collectionName', $query, ['readPreference' => $readPreference]);

    foreach($cursor as $document) {
        var_dump($document);
    }

    ?>

### Siehe auch

- MongoDB\Driver\Manager::executeQuery() - Execute a database query
- MongoDB\Driver\Cursor

## Inhaltsverzeichnis

- MongoDB\Driver\Query::__construct — Create a new Query

# The MongoDB\Driver\BulkWrite class

(mongodb >=1.0.0)

## Einführung

The MongoDB\Driver\BulkWrite collects one or more write operations that should be sent to the server. After adding any number of insert, update, and delete operations, the collection may be executed via MongoDB\Driver\Manager::executeBulkWrite().

Write operations may either be ordered (default) or unordered. Ordered write operations are sent to the server, in the order provided, for serial execution. If a write fails, any remaining operations will be aborted. Unordered operations are sent to the server in an arbitrary order where they may be executed in parallel. Any errors that occur are reported after all operations have been attempted.

## Klassenbeschreibung

final class MongoDB\Driver\BulkWrite implements Countable {
/* Methoden */
public function __construct(?array `$options` = `null`)
public function count(): int
public function delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void
public function insert(array|object `$document`): mixed
public function update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void
}

## Beispiele

Beispiel #1 Mixed write operations are grouped by type

Mixed write operations (i.e. inserts, updates, and deletes) will be assembled into typed write commands to be sent sequentially to the server.

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->insert(['_id' => 3, 'x' => 3]);
    $bulk->delete(['x' => 1]);

    ?>

Will result in four write commands (i.e. roundtrips) being executed. Since the operations are ordered, the third insertion cannot be sent until the preceding update is executed.

Beispiel #2 Ordered write operations causing an error

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3, 'hello' => 'world']);
    $bulk->update(['_id' => 3], ['$set' => ['hello' => 'earth']]);
    $bulk->insert(['_id' => 4, 'hello' => 'pluto']);
    $bulk->update(['_id' => 4], ['$set' => ['hello' => 'moon']]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 5]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 1000);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Check if the write concern could not be fulfilled
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Check if any write operations did not complete at all
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operation#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Other error: %s\n", $e->getMessage());
        exit;
    }

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Inserted 4 document(s)
    Updated  2 document(s)

If the write concern could not be fulfilled, the example above would output something like:

    waiting for replication timed out (64): array (
      'wtimeout' => true,
    )
    Operation#7: E11000 duplicate key error index: databaseName.collectionName.$_id_ dup key: { : 3 } (11000)
    Inserted 4 document(s)
    Updated  2 document(s)

If we execute the example above, but allow for unordered writes:

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    /* ... */

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Operation#7: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 3 } (11000)
    Operation#8: E11000 duplicate key error index: db.collection.$_id_ dup key: { : 4 } (11000)
    Inserted 5 document(s)
    Updated  2 document(s)

## Siehe auch

- MongoDB\Driver\Manager::executeBulkWrite()
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWrite::__construct

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::__construct — Create a new BulkWrite

### Beschreibung

public function MongoDB\Driver\BulkWrite::__construct(?array `$options` = `null`)

Constructs a new MongoDB\Driver\BulkWrite, which is a mutable object to which one or more write operations may be added. The write(s) may then be executed with MongoDB\Driver\Manager::executeBulkWrite().

### Parameter-Liste

`options` (array)

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  bypassDocumentValidation | bool | If `true`, allows insert and update operations to circumvent document level validation. This option is available in MongoDB 3.2+ and is ignored for older server versions, which do not support document level validation. | `false`
  comment | mixed | An arbitrary comment to help trace the operation through the database profiler, currentOp output, and logs. This option is available in MongoDB 4.4+ and will result in an exception at execution time if specified for an older server version.
  let | array|object | Die Zuordnung von Parameternamen und -werten. Die Werte müssen Konstanten oder geschlossene Ausdrücke sein, die nicht auf Dokumentfelder verweisen. Auf die Parameter kann dann als Variablen im Kontext eines aggregierten Ausdrucks zugegriffen werden (z. B. `$$var`). Diese Option ist ab MongoDB 5.0 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  ordered | bool | Ordered operations (`true`) are executed serially on the MongoDB server, while unordered operations (`false`) are sent to the server in an arbitrary order and may be executed in parallel. | `true`

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.14.0 | Added the `"comment"` and `"let"` options.
PECL mongodb 1.1.0 | Added the `"bypassDocumentValidation"` option.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWrite::__construct() example

    <?php

    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);
    $bulk->delete([]);
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(
        ['x' => 2],
        ['$set' => ['x' => 1]],
        ['limit' => 1, 'upsert' => false]
    );
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->update(
        ['_id' => 3],
        ['$set' => ['x' => 3]],
        ['limit' => 1, 'upsert' => true]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $writeConcern = new MongoDB\Driver\WriteConcern(1);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $result = $e->getWriteResult();

        // Check if the write concern could not be fulfilled
        if ($writeConcernError = $result->getWriteConcernError()) {
            printf("%s (%d): %s\n",
                $writeConcernError->getMessage(),
                $writeConcernError->getCode(),
                var_export($writeConcernError->getInfo(), true)
            );
        }

        // Check if any write operations did not complete at all
        foreach ($result->getWriteErrors() as $writeError) {
            printf("Operation#%d: %s (%d)\n",
                $writeError->getIndex(),
                $writeError->getMessage(),
                $writeError->getCode()
            );
        }
    } catch (MongoDB\Driver\Exception\Exception $e) {
        printf("Other error: %s\n", $e->getMessage());
        exit;
    }

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());
    printf("Upserted %d document(s)\n", $result->getUpsertedCount());
    printf("Deleted  %d document(s)\n", $result->getDeletedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Inserted 2 document(s)
    Updated  1 document(s)
    Upserted 1 document(s)
    Deleted  1 document(s)

### Siehe auch

- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::count

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::count — Count number of write operations in the bulk

### Beschreibung

public function MongoDB\Driver\BulkWrite::count(): int

Returns the number of write operations added to the MongoDB\Driver\BulkWrite object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns number of write operations added to the MongoDB\Driver\BulkWrite object.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.2.0 | Returns the number of write operations added to the MongoDB\Driver\BulkWrite object. Earlier versions returned the expected number of client-to-server roundtrips required to execute all write operations.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWrite::count() example

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1, 'x' => 1]);
    $bulk->insert(['_id' => 2, 'x' => 2]);
    $bulk->update(['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->delete(['x' => 1]);

    var_dump(count($bulk));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(4)

# MongoDB\Driver\BulkWrite::delete

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk

### Beschreibung

public function MongoDB\Driver\BulkWrite::delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void

Adds a delete operation to the MongoDB\Driver\BulkWrite.

### Parameter-Liste

`filter` (array|object)

  Das » Abfrage-Prädikat. Ein leeres Prädikat passt auf alle Dokumente in der Sammlung.

  > Hinweis: Bei der Auswertung von Abfragekriterien vergleicht MongoDB Typen und Werte gemäß seiner eigenen » Vergleichsregeln für BSON-Typen, die sich von PHPs Regeln für Typenvergleich und Typen-Jonglage unterscheidet. Wenn es eine Übereinstimmung mit einem speziellen BSON-Typ gibt, sollten die Abfragekriterien die entsprechende BSON-Klasse verwenden (z. B. MongoDB\BSON\ObjectId, um auf eine » ObjectId zu passen).

`deleteOptions`

  deleteOptions
  Option | Type | Description | Default
  --- | --- | --- | ---
  collation | array|object | Die » Collation (Vergleichs-/Sortierregel) ermöglicht es dem Benutzer, sprachspezifische Regeln für den Vergleich von Zeichenketten anzugeben, so z. B. Regeln für die Groß- und Kleinschreibung und Akzentzeichen. Bei der Angabe der Sortierung ist das Feld `"locale"` obligatorisch; alle anderen Sortierfelder sind optional. Die Beschreibungen der Felder sind unter » Collation Document zu finden. Wenn keine Kollation angegeben wurde, aber die Sammlung eine Standardkollation hat, verwendet die Operation die für die Sammlung angegebene Kollation. Wenn weder für die Sammlung noch für die Operation eine Kollation angegeben wurde, verwendet MongoDB den einfachen binären Vergleich, der in früheren Versionen für den Vergleich von Zeichenketten verwendet wurde. Diese Option ist ab MongoDB 3.4 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  hint | string|array|object | Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index. This option is available in MongoDB 4.4+ and will result in an exception at execution time if specified for an older server version.
  limit | bool | Delete all matching documents (`false`), or only the first matching document (`true`) | `false`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.8.0 | Added the `"hint"` option.
PECL mongodb 1.2.0 | Added the `"collation"` option.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWrite::delete() example

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->delete(['x' => 1], ['limit' => 1]);
    $bulk->delete(['x' => 2], ['limit' => 0]);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Siehe auch

- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
- MongoDB\Driver\WriteResult

# MongoDB\Driver\BulkWrite::insert

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::insert — Add an insert operation to the bulk

### Beschreibung

public function MongoDB\Driver\BulkWrite::insert(array|object `$document`): mixed

Adds an insert operation to the MongoDB\Driver\BulkWrite.

### Parameter-Liste

`document` (array|object)
  A document to insert.

### Rückgabewerte

Returns the `_id` of the inserted document. If the `document` did not have an `_id`, the MongoDB\BSON\ObjectId generated for the insert will be returned.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.3.0 | The `_id` of the inserted document is always returned. Previously, the method only returned a value if a MongoDB\BSON\ObjectId was generated.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWrite::insert() example

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insert($doc1);
    $id2 = $bulk->insert($doc2);
    $id3 = $bulk->insert($doc3);

    var_dump($id1, $id2, $id3);

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Siehe auch

- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
- MongoDB\Driver\WriteResult
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Persistable

# MongoDB\Driver\BulkWrite::update

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::update — Add an update operation to the bulk

### Beschreibung

public function MongoDB\Driver\BulkWrite::update(array|object `$filter`, array|object `$newObj`, ?array `$updateOptions` = `null`): void

Adds an update operation to the MongoDB\Driver\BulkWrite.

### Parameter-Liste

`filter` (array|object)

  Das » Abfrage-Prädikat. Ein leeres Prädikat passt auf alle Dokumente in der Sammlung.

  > Hinweis: Bei der Auswertung von Abfragekriterien vergleicht MongoDB Typen und Werte gemäß seiner eigenen » Vergleichsregeln für BSON-Typen, die sich von PHPs Regeln für Typenvergleich und Typen-Jonglage unterscheidet. Wenn es eine Übereinstimmung mit einem speziellen BSON-Typ gibt, sollten die Abfragekriterien die entsprechende BSON-Klasse verwenden (z. B. MongoDB\BSON\ObjectId, um auf eine » ObjectId zu passen).

`newObj` (array|object)
  A document containing either update operators (e.g. `$set`), a replacement document (i.e. only `field:value` expressions), or an » aggregation pipeline.
`updateOptions`

  updateOptions
  Option | Type | Description | Default
  --- | --- | --- | ---
  arrayFilters | array | An array of filter documents that determines which array elements to modify for an update operation on an array field. See » Specify arrayFilters for Array Update Operations in the MongoDB manual for more information. This option is available in MongoDB 3.6+ and will result in an exception at execution time if specified for an older server version.
  collation | array|object | Die » Collation (Vergleichs-/Sortierregel) ermöglicht es dem Benutzer, sprachspezifische Regeln für den Vergleich von Zeichenketten anzugeben, so z. B. Regeln für die Groß- und Kleinschreibung und Akzentzeichen. Bei der Angabe der Sortierung ist das Feld `"locale"` obligatorisch; alle anderen Sortierfelder sind optional. Die Beschreibungen der Felder sind unter » Collation Document zu finden. Wenn keine Kollation angegeben wurde, aber die Sammlung eine Standardkollation hat, verwendet die Operation die für die Sammlung angegebene Kollation. Wenn weder für die Sammlung noch für die Operation eine Kollation angegeben wurde, verwendet MongoDB den einfachen binären Vergleich, der in früheren Versionen für den Vergleich von Zeichenketten verwendet wurde. Diese Option ist ab MongoDB 3.4 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  hint | string|array|object | Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index. This option is available in MongoDB 4.2+ and will result in an exception at execution time if specified for an older server version.
  multi | bool | Update only the first matching document if `false`, or all matching documents `true`. This option cannot be `true` if `newObj` is a replacement document. | `false`
  sort | array|object | Specify which document the operation updates if the query matches multiple documents. The first document matched by the sort order will be updated. This option cannot be used if `"multi"` is `true`. This option is available in MongoDB 8.0+ and will result in an exception at execution time if specified for an older server version.
  upsert | bool | If `filter` does not match an existing document, insert a single document. The document will be created from `newObj` if it is a replacement document (i.e. no update operators); otherwise, the operators in `newObj` will be applied to `filter` to create the new document. | `false`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.21.0 | Added the `"sort"` option.
PECL mongodb 1.7.0 | Added the `"hint"` option.
PECL mongodb 1.6.0 | The `newObj` parameter now accepts an aggregation pipeline. This feature requires MongoDB 4.2+ and will result in an exception at execution time if specified for an older server version.
PECL mongodb 1.5.0 | Using the `"arrayFilters"` option will result in an exception at execution time if unsupported by the server. Previously, no exception would be thrown and the option may have been ignored.
PECL mongodb 1.4.0 | Added the `"arrayFilters"` option.
PECL mongodb 1.2.0 | Added the `"collation"` option.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWrite::update() example

    <?php

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->update(
        ['x' => 2],
        ['$set' => ['y' => 3]],
        ['multi' => false, 'upsert' => false]
    );

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
    $result = $manager->executeBulkWrite('db.collection', $bulk);

    ?>

### Siehe auch

- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
- MongoDB\Driver\WriteResult

## Inhaltsverzeichnis

- MongoDB\Driver\BulkWrite::__construct — Create a new BulkWrite
- MongoDB\Driver\BulkWrite::count — Count number of write operations in the bulk
- MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk
- MongoDB\Driver\BulkWrite::insert — Add an insert operation to the bulk
- MongoDB\Driver\BulkWrite::update — Add an update operation to the bulk

# The MongoDB\Driver\BulkWriteCommand class

(mongodb >=2.1.0)

## Einführung

MongoDB\Driver\BulkWriteCommand collects one or more write operations that should be sent to the server using the » bulkWrite command introduced in MongoDB 8.0. After adding any number of insert, update, and delete operations, the command may be executed via MongoDB\Driver\Manager::executeBulkWriteCommand().

Unlike MongoDB\Driver\BulkWrite, where all write operations must target the same collection, each write operation within MongoDB\Driver\BulkWriteCommand may target a different collection.

Write operations may either be ordered (default) or unordered. Ordered write operations are sent to the server, in the order provided, for serial execution. If a write fails, any remaining operations will be aborted. Unordered operations are sent to the server in an arbitrary order where they may be executed in parallel. Any errors that occur are reported after all operations have been attempted.

## Klassenbeschreibung

final class MongoDB\Driver\BulkWriteCommand implements Countable {
/* Methoden */
public function __construct(?array `$options` = `null`)
public function count(): int
public function deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function insertOne(string `$namespace`, array|object `$document`): mixed
public function replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void
public function updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
public function updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
}

## Beispiele

Beispiel #1 Mixed write operations

Mixed write operations (i.e. inserts, updates, and deletes) will be sent to the server using a single » bulkWrite command.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Delete documents from both collections
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insert documents into two collections
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Update a document in "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Inserted 3 document(s)
    Updated  1 document(s)

Beispiel #2 Ordered write operations causing an error

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Inserted %d document(s)\n", $result->getInsertedCount());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Inserted 2 document(s)

## Siehe auch

- MongoDB\Driver\Manager::executeBulkWriteCommand()
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWriteCommand::__construct

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::__construct — Create a new BulkWriteCommand

### Beschreibung

public function MongoDB\Driver\BulkWriteCommand::__construct(?array `$options` = `null`)

Constructs a new MongoDB\Driver\BulkWriteCommand, which may be used to perform many insert, update, and delete operations on multiple collections in a single request using the » bulkWrite command introduced in MongoDB 8.0. This differs from MongoDB\Driver\BulkWrite, which is supported by all server versions but limited to a single collection.

After all write operations have been added, this object may be executed with MongoDB\Driver\Manager::executeBulkWriteCommand().

### Parameter-Liste

`options` (array)

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  bypassDocumentValidation | bool | If `true`, allows insert and update operations to circumvent document level validation. | `false`
  comment | mixed | An arbitrary comment to help trace the operation through the database profiler, currentOp output, and logs.
  let | array|object | Die Zuordnung von Parameternamen und -werten. Die Werte müssen Konstanten oder geschlossene Ausdrücke sein, die nicht auf Dokumentfelder verweisen. Auf die Parameter kann dann als Variablen im Kontext eines aggregierten Ausdrucks zugegriffen werden (z. B. `$$var`). Diese Option ist ab MongoDB 5.0 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  ordered | bool | Whether the operations in this bulk write should be executed in the order in which they were specified. If `false`, writes will continue to be executed if an individual write fails. If `true`, writes will stop executing if an individual write fails. | `true`
  verboseResults | bool | Whether detailed results for each successful operation should be included in the returned MongoDB\Driver\BulkWriteCommandResult. | `false`

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommand::__construct() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Delete documents from both collections
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insert documents into two collections
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Update a document in "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Inserted 3 document(s)
    Updated  1 document(s)

### Siehe auch

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::count

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::count — Count number of write operations in the BulkWriteCommand

### Beschreibung

public function MongoDB\Driver\BulkWriteCommand::count(): int

Returns the number of write operations added to the MongoDB\Driver\BulkWriteCommand object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns number of write operations added to the MongoDB\Driver\BulkWriteCommand object.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommand::count() example

    <?php

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1, 'x' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2, 'x' => 2]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->deleteMany('db.coll', ['x' => 1]);

    var_dump(count($bulk));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(4)

# MongoDB\Driver\BulkWriteCommand::deleteMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteMany — Add a deleteMany operation

### Beschreibung

public function MongoDB\Driver\BulkWriteCommand::deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Add a deleteMany operation to the MongoDB\Driver\BulkWriteCommand. All documents matching `filter` in the collection identified by `namespace` will be deleted.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`filter` (array|object)

  Das » Abfrage-Prädikat. Ein leeres Prädikat passt auf alle Dokumente in der Sammlung.

  > Hinweis: Bei der Auswertung von Abfragekriterien vergleicht MongoDB Typen und Werte gemäß seiner eigenen » Vergleichsregeln für BSON-Typen, die sich von PHPs Regeln für Typenvergleich und Typen-Jonglage unterscheidet. Wenn es eine Übereinstimmung mit einem speziellen BSON-Typ gibt, sollten die Abfragekriterien die entsprechende BSON-Klasse verwenden (z. B. MongoDB\BSON\ObjectId, um auf eine » ObjectId zu passen).

`options`

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  collation | array|object | Die » Collation (Vergleichs-/Sortierregel) ermöglicht es dem Benutzer, sprachspezifische Regeln für den Vergleich von Zeichenketten anzugeben, so z. B. Regeln für die Groß- und Kleinschreibung und Akzentzeichen. Bei der Angabe der Sortierung ist das Feld `"locale"` obligatorisch; alle anderen Sortierfelder sind optional. Die Beschreibungen der Felder sind unter » Collation Document zu finden. Wenn keine Kollation angegeben wurde, aber die Sammlung eine Standardkollation hat, verwendet die Operation die für die Sammlung angegebene Kollation. Wenn weder für die Sammlung noch für die Operation eine Kollation angegeben wurde, verwendet MongoDB den einfachen binären Vergleich, der in früheren Versionen für den Vergleich von Zeichenketten verwendet wurde. Diese Option ist ab MongoDB 3.4 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  hint | string|array|object | Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommand::deleteMany() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', ['x' => ['$gt' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Siehe auch

- MongoDB\Driver\BulkWriteCommand::deleteOne() - Add a deleteOne operation
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::deleteOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteOne — Add a deleteOne operation

### Beschreibung

public function MongoDB\Driver\BulkWriteCommand::deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Add a deleteOne operation to the MongoDB\Driver\BulkWriteCommand. The first document matching `filter` in the collection identified by `namespace` will be deleted.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`filter` (array|object)

  Das » Abfrage-Prädikat. Ein leeres Prädikat passt auf alle Dokumente in der Sammlung.

  > Hinweis: Bei der Auswertung von Abfragekriterien vergleicht MongoDB Typen und Werte gemäß seiner eigenen » Vergleichsregeln für BSON-Typen, die sich von PHPs Regeln für Typenvergleich und Typen-Jonglage unterscheidet. Wenn es eine Übereinstimmung mit einem speziellen BSON-Typ gibt, sollten die Abfragekriterien die entsprechende BSON-Klasse verwenden (z. B. MongoDB\BSON\ObjectId, um auf eine » ObjectId zu passen).

`options`

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  collation | array|object | Die » Collation (Vergleichs-/Sortierregel) ermöglicht es dem Benutzer, sprachspezifische Regeln für den Vergleich von Zeichenketten anzugeben, so z. B. Regeln für die Groß- und Kleinschreibung und Akzentzeichen. Bei der Angabe der Sortierung ist das Feld `"locale"` obligatorisch; alle anderen Sortierfelder sind optional. Die Beschreibungen der Felder sind unter » Collation Document zu finden. Wenn keine Kollation angegeben wurde, aber die Sammlung eine Standardkollation hat, verwendet die Operation die für die Sammlung angegebene Kollation. Wenn weder für die Sammlung noch für die Operation eine Kollation angegeben wurde, verwendet MongoDB den einfachen binären Vergleich, der in früheren Versionen für den Vergleich von Zeichenketten verwendet wurde. Diese Option ist ab MongoDB 3.4 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  hint | string|array|object | Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommand::deleteOne() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Siehe auch

- MongoDB\Driver\BulkWriteCommand::deleteMany() - Add a deleteMany operation
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::insertOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::insertOne — Add an insertOne operation

### Beschreibung

public function MongoDB\Driver\BulkWriteCommand::insertOne(string `$namespace`, array|object `$document`): mixed

Add an insertOne operation to the MongoDB\Driver\BulkWriteCommand. The document will be inserted into the collection identified by `namespace`.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`document` (array|object)
  A document to insert.

### Rückgabewerte

Returns the `_id` of the inserted document. If the `document` did not have an `_id`, the MongoDB\BSON\ObjectId generated for the insert will be returned.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommand::insertOne() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insertOne('db.coll', $doc1);
    $id2 = $bulk->insertOne('db.coll', $doc2);
    $id3 = $bulk->insertOne('db.coll', $doc3);

    var_dump($id1, $id2, $id3);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### Siehe auch

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON\ObjectId

# MongoDB\Driver\BulkWriteCommand::replaceOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::replaceOne — Add a replaceOne operation

### Beschreibung

public function MongoDB\Driver\BulkWriteCommand::replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void

Add a replaceOne operation to the MongoDB\Driver\BulkWriteCommand. The first document matching `filter` in the collection identified by `namespace` will be replaced.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`filter` (array|object)

  Das » Abfrage-Prädikat. Ein leeres Prädikat passt auf alle Dokumente in der Sammlung.

  > Hinweis: Bei der Auswertung von Abfragekriterien vergleicht MongoDB Typen und Werte gemäß seiner eigenen » Vergleichsregeln für BSON-Typen, die sich von PHPs Regeln für Typenvergleich und Typen-Jonglage unterscheidet. Wenn es eine Übereinstimmung mit einem speziellen BSON-Typ gibt, sollten die Abfragekriterien die entsprechende BSON-Klasse verwenden (z. B. MongoDB\BSON\ObjectId, um auf eine » ObjectId zu passen).

`replacement` (array|object)
  A replacement document.
`options`

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  collation | array|object | Die » Collation (Vergleichs-/Sortierregel) ermöglicht es dem Benutzer, sprachspezifische Regeln für den Vergleich von Zeichenketten anzugeben, so z. B. Regeln für die Groß- und Kleinschreibung und Akzentzeichen. Bei der Angabe der Sortierung ist das Feld `"locale"` obligatorisch; alle anderen Sortierfelder sind optional. Die Beschreibungen der Felder sind unter » Collation Document zu finden. Wenn keine Kollation angegeben wurde, aber die Sammlung eine Standardkollation hat, verwendet die Operation die für die Sammlung angegebene Kollation. Wenn weder für die Sammlung noch für die Operation eine Kollation angegeben wurde, verwendet MongoDB den einfachen binären Vergleich, der in früheren Versionen für den Vergleich von Zeichenketten verwendet wurde. Diese Option ist ab MongoDB 3.4 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  hint | string|array|object | Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.
  sort | array|object | Specify which document the operation replaces if the query matches multiple documents. The first document matched by the sort order will be replaced.
  upsert | bool | If `filter` does not match an existing document, insert a single document. The document will be created from `replacement`. | `false`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommand::replaceOne() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->replaceOne('db.coll', ['x' => 1], ['x' => 1, 'y' => 2]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Siehe auch

- MongoDB\Driver\BulkWriteCommand::updateOne() - Add an updateOne operation
- MongoDB\Driver\BulkWriteCommand::updateMany() - Add an updateMany operation
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateMany — Add an updateMany operation

### Beschreibung

public function MongoDB\Driver\BulkWriteCommand::updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Add an updateMany operation to the MongoDB\Driver\BulkWriteCommand. All documents matching `filter` in the collection identified by `namespace` will be updated.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`filter` (array|object)

  Das » Abfrage-Prädikat. Ein leeres Prädikat passt auf alle Dokumente in der Sammlung.

  > Hinweis: Bei der Auswertung von Abfragekriterien vergleicht MongoDB Typen und Werte gemäß seiner eigenen » Vergleichsregeln für BSON-Typen, die sich von PHPs Regeln für Typenvergleich und Typen-Jonglage unterscheidet. Wenn es eine Übereinstimmung mit einem speziellen BSON-Typ gibt, sollten die Abfragekriterien die entsprechende BSON-Klasse verwenden (z. B. MongoDB\BSON\ObjectId, um auf eine » ObjectId zu passen).

`update` (array|object)
  A document containing either update operators (e.g. `$set`) or an » aggregation pipeline.
`options`

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  arrayFilters | array | An array of filter documents that determines which array elements to modify for an update operation on an array field. See » Specify arrayFilters for Array Update Operations in the MongoDB manual for more information.
  collation | array|object | Die » Collation (Vergleichs-/Sortierregel) ermöglicht es dem Benutzer, sprachspezifische Regeln für den Vergleich von Zeichenketten anzugeben, so z. B. Regeln für die Groß- und Kleinschreibung und Akzentzeichen. Bei der Angabe der Sortierung ist das Feld `"locale"` obligatorisch; alle anderen Sortierfelder sind optional. Die Beschreibungen der Felder sind unter » Collation Document zu finden. Wenn keine Kollation angegeben wurde, aber die Sammlung eine Standardkollation hat, verwendet die Operation die für die Sammlung angegebene Kollation. Wenn weder für die Sammlung noch für die Operation eine Kollation angegeben wurde, verwendet MongoDB den einfachen binären Vergleich, der in früheren Versionen für den Vergleich von Zeichenketten verwendet wurde. Diese Option ist ab MongoDB 3.4 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  hint | string|array|object | Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.
  upsert | bool | If `filter` does not match an existing document, insert a single document. The document will be created by applying operators in `update` to any field values in `filter`. | `false`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommand::updateMany() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateMany('db.coll', ['x' => ['$gt' => 1]], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Siehe auch

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Add a replaceOne operation
- MongoDB\Driver\BulkWriteCommand::updateMany()
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateOne — Add an updateOne operation

### Beschreibung

public function MongoDB\Driver\BulkWriteCommand::updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Add an updateOne operation to the MongoDB\Driver\BulkWriteCommand. The first document matching `filter` in the collection identified by `namespace` will be updated.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`filter` (array|object)

  Das » Abfrage-Prädikat. Ein leeres Prädikat passt auf alle Dokumente in der Sammlung.

  > Hinweis: Bei der Auswertung von Abfragekriterien vergleicht MongoDB Typen und Werte gemäß seiner eigenen » Vergleichsregeln für BSON-Typen, die sich von PHPs Regeln für Typenvergleich und Typen-Jonglage unterscheidet. Wenn es eine Übereinstimmung mit einem speziellen BSON-Typ gibt, sollten die Abfragekriterien die entsprechende BSON-Klasse verwenden (z. B. MongoDB\BSON\ObjectId, um auf eine » ObjectId zu passen).

`update` (array|object)
  A document containing either update operators (e.g. `$set`) or an » aggregation pipeline.
`options`

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  arrayFilters | array | An array of filter documents that determines which array elements to modify for an update operation on an array field. See » Specify arrayFilters for Array Update Operations in the MongoDB manual for more information.
  collation | array|object | Die » Collation (Vergleichs-/Sortierregel) ermöglicht es dem Benutzer, sprachspezifische Regeln für den Vergleich von Zeichenketten anzugeben, so z. B. Regeln für die Groß- und Kleinschreibung und Akzentzeichen. Bei der Angabe der Sortierung ist das Feld `"locale"` obligatorisch; alle anderen Sortierfelder sind optional. Die Beschreibungen der Felder sind unter » Collation Document zu finden. Wenn keine Kollation angegeben wurde, aber die Sammlung eine Standardkollation hat, verwendet die Operation die für die Sammlung angegebene Kollation. Wenn weder für die Sammlung noch für die Operation eine Kollation angegeben wurde, verwendet MongoDB den einfachen binären Vergleich, der in früheren Versionen für den Vergleich von Zeichenketten verwendet wurde. Diese Option ist ab MongoDB 3.4 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  hint | string|array|object | Index specification. Specify either the index name as a string or the index key pattern. If specified, then the query system will only consider plans using the hinted index.
  sort | array|object | Specify which document the operation updates if the query matches multiple documents. The first document matched by the sort order will be updated.
  upsert | bool | If `filter` does not match an existing document, insert a single document. The document will be created by applying operators in `update` to any field values in `filter`. | `false`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommand::updateOne() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### Siehe auch

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Add a replaceOne operation
- MongoDB\Driver\BulkWriteCommand::updateMany() - Add an updateMany operation
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

## Inhaltsverzeichnis

- MongoDB\Driver\BulkWriteCommand::__construct — Create a new BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::count — Count number of write operations in the BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::deleteMany — Add a deleteMany operation
- MongoDB\Driver\BulkWriteCommand::deleteOne — Add a deleteOne operation
- MongoDB\Driver\BulkWriteCommand::insertOne — Add an insertOne operation
- MongoDB\Driver\BulkWriteCommand::replaceOne — Add a replaceOne operation
- MongoDB\Driver\BulkWriteCommand::updateMany — Add an updateMany operation
- MongoDB\Driver\BulkWriteCommand::updateOne — Add an updateOne operation

# The MongoDB\Driver\Session class

(mongodb >=1.4.0)

## Einführung

The MongoDB\Driver\Session class represents a client session and is returned by MongoDB\Driver\Manager::startSession(). Commands, queries, and write operations may then be associated with the session.

## Klassenbeschreibung

final class MongoDB\Driver\Session {
/* Konstanten */
const string TRANSACTION_NONE = none;
const string TRANSACTION_STARTING = starting;
const string TRANSACTION_IN_PROGRESS = in_progress;
const string TRANSACTION_COMMITTED = committed;
const string TRANSACTION_ABORTED = aborted;
/* Methoden */
final public function abortTransaction(): void
final public function advanceClusterTime(array|object `$clusterTime`): void
final public function advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void
final public function commitTransaction(): void
final private function __construct()
final public function endSession(): void
final public function getClusterTime(): ?object
final public function getLogicalSessionId(): object
final public function getOperationTime(): ?MongoDB\BSON\Timestamp
final public function getServer(): ?MongoDB\Driver\Server
final public function getTransactionOptions(): ?array
final public function getTransactionState(): string
final public function isDirty(): bool
final public function isInTransaction(): bool
final public function startTransaction(?array `$options` = `null`): void
}

## Vordefinierte Konstanten

`MongoDB\Driver\Session::TRANSACTION_NONE`
  There is no transaction in progress.
`MongoDB\Driver\Session::TRANSACTION_STARTING`
  A transaction has been started, but no operation has been sent to the server.
`MongoDB\Driver\Session::TRANSACTION_IN_PROGRESS`
  A transaction is in progress.
`MongoDB\Driver\Session::TRANSACTION_COMMITTED`
  The transaction was committed.
`MongoDB\Driver\Session::TRANSACTION_ABORTED`
  The transaction was aborted.

# MongoDB\Driver\Session::abortTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::abortTransaction — Aborts a transaction

### Beschreibung

final public function MongoDB\Driver\Session::abortTransaction(): void

Terminates the multi-document transaction and rolls back any data changes made by the operations within the transaction. That is, the transaction ends without saving any of the changes made by the operations in the transaction.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\RuntimeException if the transaction could not be aborted (e.g. a transaction was not started).

### Siehe auch

- MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client
- MongoDB\Driver\Session::commitTransaction() - Commits a transaction
- MongoDB\Driver\Session::startTransaction() - Starts a transaction

# MongoDB\Driver\Session::advanceClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceClusterTime — Advances the cluster time for this session

### Beschreibung

final public function MongoDB\Driver\Session::advanceClusterTime(array|object `$clusterTime`): void

Advances the cluster time for this session. If the cluster time is less than or equal to the session's current cluster time, this function is a no-op.

By using this method in conjunction with MongoDB\Driver\Session::advanceOperationTime() to copy the cluster and operation times from another session, you can ensure that operations in this session are causally consistent with the last operation in the other session.

### Parameter-Liste

`clusterTime`
  The cluster time is a document containing a logical timestamp and server signature. Typically, this value will be obtained by calling MongoDB\Driver\Session::getClusterTime() on another session object.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Session::advanceOperationTime() - Advances the operation time for this session
- MongoDB\Driver\Session::getClusterTime() - Returns the cluster time for this session

# MongoDB\Driver\Session::advanceOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceOperationTime — Advances the operation time for this session

### Beschreibung

final public function MongoDB\Driver\Session::advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void

Advances the operation time for this session. If the operation time is less than or equal to the session's current operation time, this function is a no-op.

By using this method in conjunction with MongoDB\Driver\Session::advanceClusterTime() to copy the operation and cluster times from another session, you can ensure that operations in this session are causally consistent with the last operation in the other session.

### Parameter-Liste

`operationTime`
  The operation time is a logical timestamp. Typically, this value will be obtained by calling MongoDB\Driver\Session::getOperationTime() on another session object.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Session::advanceClusterTime() - Advances the cluster time for this session
- MongoDB\Driver\Session::getClusterTime() - Returns the cluster time for this session

# MongoDB\Driver\Session::commitTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::commitTransaction — Commits a transaction

### Beschreibung

final public function MongoDB\Driver\Session::commitTransaction(): void

Saves the changes made by the operations in the multi-document transaction and ends the transaction. Until the commit, none of the data changes made from within the transaction are visible outside the transaction.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\CommandException if the server could not commit the transaction (e.g. due to conflicts, network issues). In case the exception's MongoDB\Driver\Exception\CommandException::getResultDocument() has a `"errorLabels"` element, and this array contains a `"TransientTransactionError"` or `"UnknownTransactionCommitResult"` value, it is safe to re-try the whole transaction. In newer versions of the extension, MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() should be used to test for this situation instead.
- Throws MongoDB\Driver\Exception\RuntimeException if the transaction could not be committed (e.g. a transaction was not started).

### Siehe auch

- MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client
- MongoDB\Driver\Session::abortTransaction() - Aborts a transaction
- MongoDB\Driver\Session::startTransaction() - Starts a transaction
- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() - Returns whether an error label is associated with an exception

# MongoDB\Driver\Session::__construct

(mongodb >=1.4.0)

MongoDB\Driver\Session::__construct — Create a new Session (not used)

### Beschreibung

final private function MongoDB\Driver\Session::__construct()

MongoDB\Driver\Session objects are returned by MongoDB\Driver\Manager::startSession() and cannot be constructed directly.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client

# MongoDB\Driver\Session::endSession

(mongodb >=1.5.0)

MongoDB\Driver\Session::endSession — Terminates a session

### Beschreibung

final public function MongoDB\Driver\Session::endSession(): void

This method closes an existing session. If a transaction was associated with this session, the transaction will be aborted. After calling this method, applications should not invoke other methods on the session.

> Hinweis: Sessions are also closed during garbage collection. It should not be necessary to call this method under normal circumstances.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client
- MongoDB\Driver\Session::abortTransaction() - Aborts a transaction
- MongoDB\Driver\Session::commitTransaction() - Commits a transaction
- MongoDB\Driver\Session::startTransaction() - Starts a transaction

# MongoDB\Driver\Session::getClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getClusterTime — Returns the cluster time for this session

### Beschreibung

final public function MongoDB\Driver\Session::getClusterTime(): ?object

Returns the cluster time for this session. If the session has not been used for any operation and MongoDB\Driver\Session::advanceClusterTime() has not been called, the cluster time will be `null`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the cluster time for this session, or `null` if the session has no cluster time.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Session::advanceClusterTime() - Advances the cluster time for this session

# MongoDB\Driver\Session::getLogicalSessionId

(mongodb >=1.4.0)

MongoDB\Driver\Session::getLogicalSessionId — Returns the logical session ID for this session

### Beschreibung

final public function MongoDB\Driver\Session::getLogicalSessionId(): object

Returns the logical session ID for this session, which may be used to identify this session's operations on the server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the logical session ID for this session.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Session::getOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session

### Beschreibung

final public function MongoDB\Driver\Session::getOperationTime(): ?MongoDB\BSON\Timestamp

Returns the operation time for this session. If the session has not been used for any operation and MongoDB\Driver\Session::advanceOperationTime() has not been called, the operation time will be `null`

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the operation time for this session, or `null` if the session has no operation time.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Session::advanceOperationTime() - Advances the operation time for this session

# MongoDB\Driver\Session::getServer

(mongodb >=1.6.0)

MongoDB\Driver\Session::getServer — Returns the server to which this session is pinned

### Beschreibung

final public function MongoDB\Driver\Session::getServer(): ?MongoDB\Driver\Server

Returns the MongoDB\Driver\Server to which this session is pinned. If the session is not pinned to a server, `null` will be returned.

Session pinning is primarily used for sharded transactions, as all commands within a sharded transaction must be sent to the same mongos instance. This method is intended to be used by libraries built atop the extension to allow use of a pinned server instead of invoking server selection.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the MongoDB\Driver\Server to which this session is pinned, or `null` if the session is not pinned to any server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Session::getTransactionOptions

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction

### Beschreibung

final public function MongoDB\Driver\Session::getTransactionOptions(): ?array

Returns options for the currently running transaction.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a array containing current transaction options, or `null` if no transaction is running.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Session::getTransactionState() - Returns the current transaction state for this session

# MongoDB\Driver\Session::getTransactionState

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionState — Returns the current transaction state for this session

### Beschreibung

final public function MongoDB\Driver\Session::getTransactionState(): string

Returns the transaction state for this session.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the current transaction state for this session.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Session::isInTransaction() - Returns whether a multi-document transaction is in progress
- MongoDB\Driver\Session::getTransactionOptions() - Returns options for the currently running transaction

# MongoDB\Driver\Session::isDirty

(mongodb >=1.13.0)

MongoDB\Driver\Session::isDirty — Returns whether the session has been marked as dirty

### Beschreibung

final public function MongoDB\Driver\Session::isDirty(): bool

Returns whether the session has been marked as dirty (i.e. it has been used with a command that encountered a network error).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns whether the session has been marked as dirty.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Session::isInTransaction

(mongodb >=1.6.0)

MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress

### Beschreibung

final public function MongoDB\Driver\Session::isInTransaction(): bool

Returns whether a multi-document transaction is currently in progress for this session. A transaction is considered "in progress" if it has been started but has not been committed or aborted.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if a transaction is currently in progress for this session, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Session::getTransactionState() - Returns the current transaction state for this session

# MongoDB\Driver\Session::startTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::startTransaction — Starts a transaction

### Beschreibung

final public function MongoDB\Driver\Session::startTransaction(?array `$options` = `null`): void

Starts a multi-document transaction associated with the session. At any given time, you can have at most one open transaction for a session. After starting a transaction, the session object must be passed to each operation via the `"session"` option (e.g. MongoDB\Driver\Manager::executeBulkWrite()) in order to associate that operation with the transaction.

Transactions can be committed through MongoDB\Driver\Session::commitTransaction(), and aborted with MongoDB\Driver\Session::abortTransaction(). Transactions are also automatically aborted when the session is closed from garbage collection or by explicitly calling MongoDB\Driver\Session::endSession().

### Parameter-Liste

`options`
  Options can be passed as argument to this method. Each element in this options array overrides the corresponding option from the `"defaultTransactionOptions"` option, if set when starting the session with MongoDB\Driver\Manager::startSession().

  options
  Option | Type | Description
  --- | --- | ---
  maxCommitTimeMS | integer | Die maximale Dauer in Millisekunden, die ein einziger `commitTransaction`-Befehl beanspruchen darf. Wenn angegeben, muss `maxCommitTimeMS` eine vorzeichenbehaftete 32-bit Ganzzahl größer als oder gleich Null sein.
  readConcern | MongoDB\Driver\ReadConcern | Ein Leseanliegen (Read Concern), das auf den Vorgang angewendet werden soll. Diese Option ist ab MongoDB 3.2 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  readPreference | MongoDB\Driver\ReadPreference | Eine Lesepräferenz, die verwendet wird, um einen Server für die Operation auszuwählen.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\CommandException if the transaction could not be started because of a server-side problem (e.g. a lock could not be obtained).
- Throws MongoDB\Driver\Exception\RuntimeException if the transaction could not be started (e.g. a transaction was already started).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.6.0 | The `"maxCommitTimeMS"` option was added.

### Siehe auch

- MongoDB\Driver\Manager::startSession() - Start a new client session for use with this client
- MongoDB\Driver\Session::commitTransaction() - Commits a transaction
- MongoDB\Driver\Session::abortTransaction() - Aborts a transaction

## Inhaltsverzeichnis

- MongoDB\Driver\Session::abortTransaction — Aborts a transaction
- MongoDB\Driver\Session::advanceClusterTime — Advances the cluster time for this session
- MongoDB\Driver\Session::advanceOperationTime — Advances the operation time for this session
- MongoDB\Driver\Session::commitTransaction — Commits a transaction
- MongoDB\Driver\Session::__construct — Create a new Session (not used)
- MongoDB\Driver\Session::endSession — Terminates a session
- MongoDB\Driver\Session::getClusterTime — Returns the cluster time for this session
- MongoDB\Driver\Session::getLogicalSessionId — Returns the logical session ID for this session
- MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session
- MongoDB\Driver\Session::getServer — Returns the server to which this session is pinned
- MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction
- MongoDB\Driver\Session::getTransactionState — Returns the current transaction state for this session
- MongoDB\Driver\Session::isDirty — Returns whether the session has been marked as dirty
- MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress
- MongoDB\Driver\Session::startTransaction — Starts a transaction

# The MongoDB\Driver\ClientEncryption class

(mongodb >=1.7.0)

## Einführung

The MongoDB\Driver\ClientEncryption class handles creation of data keys for client-side encryption, as well as manually encrypting and decrypting values.

## Klassenbeschreibung

final class MongoDB\Driver\ClientEncryption {
/* Konstanten */
const string AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC = AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic;
const string AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM = AEAD_AES_256_CBC_HMAC_SHA_512-Random;
const string ALGORITHM_INDEXED = Indexed;
const string ALGORITHM_UNINDEXED = Unindexed;
const string ALGORITHM_RANGE = Range;
const string QUERY_TYPE_EQUALITY = equality;
const string QUERY_TYPE_RANGE = range;
/* Methoden */
final public function addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function __construct(array `$options`)
final public function createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function decrypt(MongoDB\BSON\Binary `$value`): mixed
final public function deleteKey(MongoDB\BSON\Binary `$keyId`): object
final public function encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function encryptExpression(array|object `$expr`, ?array `$options` = `null`): object
final public function getKey(MongoDB\BSON\Binary `$keyId`): ?object
final public function getKeyByAltName(string `$keyAltName`): ?object
final public function getKeys(): MongoDB\Driver\Cursor
final public function removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object
}

## Vordefinierte Konstanten

`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC`
  Specifies an algorithm for » deterministic encryption, which is suitable for querying.
`MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM`
  Specifies an algorithm for » randomized encryption
`MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`
  Specifies an algorithm for an indexed, encrypted payload, which can be used with queryable encryption. To insert or query with an indexed, encrypted payload, the MongoDB\Driver\Manager must be configured with the `"autoEncryption"` driver option. The `"bypassQueryAnalysis"` auto encryption option may be `true`. The `"bypassAutoEncryption"` auto encryption option must be `false`.
`MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`
  Specifies an algorithm for an unindexed, encrypted payload.
`MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  Specifies an algorithm for a range encrypted payload, which can be used with queryable encryption. To query with a range encrypted payload, the MongoDB\Driver\Manager must be configured with the `"autoEncryption"` driver option. The `"bypassQueryAnalysis"` auto encryption option may be `true`. The `"bypassAutoEncryption"` auto encryption option must be `false`.

  > Hinweis: The extension does not yet support range queries for Decimal128 BSON field types.

`MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`
  Specifies an equality query type, which is used in conjunction with `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`.
`MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`
  Specifies a range query type, which is used in conjunction with `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Removed `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` and `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.20.0 | Added `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE` and `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE`. Deprecated `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` and `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.16.0 | Added `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` and `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
PECL mongodb 1.14.0 | Added `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED`, `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED`, and `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY`.

## Siehe auch

- MongoDB\Driver\Manager::createClientEncryption()

# MongoDB\Driver\ClientEncryption::addKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::addKeyAltName — Adds an alternate name to a key document

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Adds `keyAltName` to the set of alternate names for the key document with the given UUID `keyId`.

### Parameter-Liste

`keyId`
  A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.
`keyAltName`
  Alternate name to add to the key document.

### Rückgabewerte

Returns the previous version of the key document, or `null` if no document matched.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Siehe auch

- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Gets a key document by an alternate name
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Removes an alternate name from a key document

# MongoDB\Driver\ClientEncryption::__construct

(mongodb >=1.14.0)

MongoDB\Driver\ClientEncryption::__construct — Create a new ClientEncryption object

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::__construct(array `$options`)

Constructs a new MongoDB\Driver\ClientEncryption object with the specified options.

### Parameter-Liste

`options`

  options
  Option | Type | Description
  --- | --- | ---
  keyVaultClient | MongoDB\Driver\Manager | The Manager used to route data key queries. This option is required (unlike with MongoDB\Driver\Manager::createClientEncryption()).
  keyVaultNamespace | string | Ein vollständig qualifizierter Namensraum (z. B. `"databaseName.collectionName"`), der die Kollektion bezeichnet, die alle Datenschlüssel enthält, die für Ver- und Entschlüsselung verwendet werden. Diese Option muss angegeben werden.
  kmsProviders | array | Ein Dokument, das die Konfiguration für einen oder mehrere KMS-Provider enthält, die verwendet werden, um Datenschlüssel zu verschlüsseln. Zu den unterstützten Providern gehören `"aws"`, `"azure"`, `"gcp"`, `"kmip"` und `"local"` und wenigstens einer muss angegeben werden. Wenn für `"aws"`, `"azure"` oder `"gcp"` ein leeres Dokument angegeben wird, versucht der Treiber, den Provider mit » Automatic Credentials (automatische Anmeldeinformationen) zu konfigurieren. Das Format für `"aws"` ist wie folgt:
      aws: {
          accessKeyId: <string>,
          secretAccessKey: <string>,
          sessionToken: <optional string>
      }
  Das Format für `"azure"` ist wie folgt:
      azure: {
          tenantId: <string>,
          clientId: <string>,
          clientSecret: <string>,
          identityPlatformEndpoint: <optional string> // Der Standardwert ist "login.microsoftonline.com"
      }
  Das Format für `"gcp"` ist wie folgt:
      gcp: {
          email: <string>,
          privateKey: <base64 string>|<MongoDB\BSON\Binary>,
          endpoint: <optional string> // Der Standardwert ist "oauth2.googleapis.com"
      }
  Das Format für `"kmip"` ist wie folgt:
      kmip: {
          endpoint: <string>
      }
  Das Format für `"local"` ist wie folgt:
      local: {
          // Der 96-Byte-Hauptschlüssel, der zur Ver- und Entschlüsselung von
          // Datenschlüsseln verwendet wird
          key: <base64 string>|<MongoDB\BSON\Binary>
      }
  tlsOptions | array | Ein Dokument, das die TLS-Konfiguration für einen oder mehrere KMS-Provider enthält. Zu den unterstützten Providern gehören `"aws"`, `"azure"`, `"gcp"` und `"kmip"`. Alle Provider unterstützen die folgenden Optionen:
      <provider>: {
          tlsCaFile: <optionale Zeichenkette>,
          tlsCertificateKeyFile: <optionale Zeichenkette>,
          tlsCertificateKeyFilePassword: <optionale Zeichenkette>,
          tlsDisableOCSPEndpointCheck: <optionaler Boolean>
      }

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\RuntimeException if the extension was compiled without libmongocrypt support

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.16.0 | The AWS KMS provider for client-side encryption now accepts a `"sessionToken"` option, which can be used to authenticate with temporary AWS credentials. Added `"tlsDisableOCSPEndpointCheck"` to the `"tlsOptions"` option. If an empty document is specified for the `"azure"` or `"gcp"` KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.
PECL mongodb 1.15.0 | If an empty document is specified for the `"aws"` KMS provider, the driver will attempt to configure the provider using » Automatic Credentials.

### Siehe auch

- MongoDB\Driver\Manager::createClientEncryption() - Create a new ClientEncryption object
- » Explicit (Manual) Client-Side Field Level Encryption in the MongoDB manual

# MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::createDataKey — Creates a key document

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary

Creates a new key document and inserts it into the key vault collection.

### Parameter-Liste

`kmsProvider`
  The KMS provider (e.g. `"local"`, `"aws"`) that will be used to encrypt the new data key.
`options`

  Data key options
  Option | Type | Description
  --- | --- | ---
  masterKey | array | The masterKey document identifies a KMS-specific key used to encrypt the new data key. This option is required unless `kmsProvider` is `"local"`.
  `"aws"`-Provider-Optionen
  Option | Typ | Beschreibung
  --- | --- | ---
  region | string | Erforderlich
  key | string | Erforderlich; der Amazon-Ressourcenname (ARN) für den AWS-Kundenhauptschlüssel (CMK).
  endpoint | string | Optional; ein alternativer Host-Bezeichner, an den KMS-Anfragen gesendet werden; kann die Portnummer enthalten.
  `"azure"`-Provider-Optionen
  Option | Typ | Beschreibung
  --- | --- | ---
  keyVaultEndpoint | string | Erforderlich; der Host mit optionalem Port (z. B. "example.vault.azure.net").
  keyName | string | Erforderlich
  keyVersion | string | Optional; eine bestimmte Version des genannten Schlüssels. Standardmäßig wird die primäre Version des Schlüssels verwendet.
  `"gcp"`-Provider-Optionen
  Option | Typ | Beschreibung
  --- | --- | ---
  projectId | string | Erforderlich
  location | string | Erforderlich
  keyRing | string | Erforderlich
  keyName | string | Erforderlich
  keyVersion | string | Optional; eine bestimmte Version des genannten Schlüssels. Standardmäßig wird die primäre Version des Schlüssels verwendet.
  endpoint | string | Optional; der Host mit optionalem Port. Der Standardwert ist "cloudkms.googleapis.com".
  `"kmip"`-Provider-Optionen
  Option | Typ | Beschreibung
  --- | --- | ---
  keyId | string | Optional; der eindeutige Bezeichner für ein 96 Byte großes, verwaltetes geheimes KMIP-Datenobjekt. Wenn nicht angegeben, erstellt der Treiber ein zufälliges geheimes KMIP-Datenobjekt mit 96 Byte.
  endpoint | string | Optional; der Host mit optionalem Port.
  delegated | bool | Optional; wenn true, soll dieser Schlüssel vom KMIP-Server entschlüsselt werden.
  keyAltNames | array | An optional list of string alternate names used to reference a key. If a key is created with alternate names, then encryption may refer to the key by the unique alternate name instead of by `_id`.
  keyMaterial | MongoDB\BSON\Binary | An optional 96-byte value to use as custom key material for the data key being created. If keyMaterial is given, the custom key material is used for encrypting and decrypting data. Otherwise, the key material for the new data key is generated from a cryptographically secure random device.

### Rückgabewerte

Returns the identifier of the new key as a MongoDB\BSON\Binary object with subtype 4 (UUID).

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.20.0 | Added `"delegated"` to the KMIP provider masterKey options.
PECL mongodb 1.15.0 | Added the `"keyMaterial"` option.
PECL mongodb 1.10.0 | Azure and GCP are now supported as KMS providers for client-side encryption.

# MongoDB\Driver\ClientEncryption::decrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::decrypt — Decrypt a value

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::decrypt(MongoDB\BSON\Binary `$value`): mixed

Decrypts the value.

### Parameter-Liste

`value`
  A MongoDB\BSON\Binary instance with subtype 6 containing the encrypted value.

### Rückgabewerte

Returns the decrypted value as it was passed to MongoDB\Driver\ClientEncryption::encrypt().

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while decrypting the value

### Siehe auch

- MongoDB\Driver\ClientEncryption::encrypt() - Encrypt a value

# MongoDB\Driver\ClientEncryption::deleteKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::deleteKey — Deletes a key document

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::deleteKey(MongoDB\BSON\Binary `$keyId`): object

Removes the key document with the given UUID `keyId` from the key vault collection.

### Parameter-Liste

`keyId`
  A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

### Rückgabewerte

Returns the result of the internal `deleteOne` operation on the key vault collection.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

# MongoDB\Driver\ClientEncryption::encrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary

Encrypts the value.

### Parameter-Liste

`value`
  The value to be encrypted. Any value that can be inserted into MongoDB can be encrypted using this method.
`options`

  Verschlüsselungsoptionen
  Option | Typ | Beschreibung
  --- | --- | ---
  algorithm | string | Der zu verwendende Verschlüsselungsalgorithmus. Diese Option ist erforderlich und es muss eine der folgenden ClientEncryption-Konstanten angegeben werden: `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | The contention factor for evaluating queries with indexed, encrypted payloads. This option only applies and may only be specified when `algorithm` is `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` or `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Identifies a key vault collection document by `keyAltName`. This option is mutually exclusive with `keyId` and exactly one is required.
  keyId | MongoDB\BSON\Binary | Identifies a data key by `_id`. The value is a UUID (binary subtype 4). This option is mutually exclusive with `keyAltName` and exactly one is required.
  queryType | string | The query type for evaluating queries with indexed, encrypted payloads. Specify one of the following ClientEncryption constants: `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` This option only applies and may only be specified when `algorithm` is `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` or `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Index options for a queryable encryption field supporting "range" queries. The options below must match the values set in the `encryptedFields` of the target collection. For double and decimal128 BSON field types, `min`, `max`, and `precision` must all be set, or all be unset.
  Range index options
  Option | Type | Description
  --- | --- | ---
  min | mixed | Required if `precision` is set. The minimum BSON value of the range.
  max | mixed | Required if `precision` is set. The maximum BSON value of the range.
  sparsity | int | Optional; Positive 64-bit integer.
  precision | int | Optional. Positive 32-bit integer specifying precision to use for explicit encryption. May only be set for double or decimal128 BSON field types.
  trimFactor | int | Optional; Positive 32-bit integer.

### Rückgabewerte

Returns the encrypted value as MongoDB\BSON\Binary object with subtype 6.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while encrypting the value

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.20.0 | Added the `"trimFactor"` range option. The `"sparsity"` range option is now optional.
PECL mongodb 1.16.0 | Added the `"rangeOpts"` option.
PECL mongodb 1.14.0 | Added the `"contentionFactor"` and `"queryType"` options.

### Siehe auch

- MongoDB\Driver\ClientEncryption::decrypt() - Decrypt a value
- MongoDB\Driver\ClientEncryption::encryptExpression() - Encrypts a match or aggregate expression

# MongoDB\Driver\ClientEncryption::encryptExpression

(mongodb >=1.16.0)

MongoDB\Driver\ClientEncryption::encryptExpression — Encrypts a match or aggregate expression

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::encryptExpression(array|object `$expr`, ?array `$options` = `null`): object

Encrypts a match or aggregate expression to query a range index.

To query with a range encrypted payload, the MongoDB\Driver\Manager must be configured with the `"autoEncryption"` driver option. The `"bypassQueryAnalysis"` auto encryption option may be `true`. The `"bypassAutoEncryption"` auto encryption option must be `false`.

> Hinweis: The extension does not yet support range queries for Decimal128 BSON field types.

### Parameter-Liste

`expr`
  The match or aggregate expression to be encrypted. Expressions must use at least one of the `$gt`, `$gte`, `$lt`, or `$lte` operators. A top-level `$and` operator is required, even if only a single comparison operator is used. An example of a supported match expression (applies to queries and the `$match` aggregation stage) is as follows:

      [
          '$and' => [
              [ '<field>' => [ '$gt'  => '<value1>' ] ],
              [ '<field>' => [ '$lte' => '<value2>' ] ],
          ],
      ]

  An example of a supported aggregate expression is as follows:

      [
          '$and' => [
              [ '$gte' => [ '<fieldPath>', '<value1>' ] ],
              [ '$lt'  => [ '<fieldPath>', '<value2>' ] ],
          ],
      ]

`options`

  Verschlüsselungsoptionen
  Option | Typ | Beschreibung
  --- | --- | ---
  algorithm | string | Der zu verwendende Verschlüsselungsalgorithmus. Diese Option ist erforderlich und es muss eine der folgenden ClientEncryption-Konstanten angegeben werden: `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC` `MongoDB\Driver\ClientEncryption::AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM` `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_UNINDEXED` `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`
  contentionFactor | int | The contention factor for evaluating queries with indexed, encrypted payloads. This option only applies and may only be specified when `algorithm` is `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` or `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  keyAltName | string | Identifies a key vault collection document by `keyAltName`. This option is mutually exclusive with `keyId` and exactly one is required.
  keyId | MongoDB\BSON\Binary | Identifies a data key by `_id`. The value is a UUID (binary subtype 4). This option is mutually exclusive with `keyAltName` and exactly one is required.
  queryType | string | The query type for evaluating queries with indexed, encrypted payloads. Specify one of the following ClientEncryption constants: `MongoDB\Driver\ClientEncryption::QUERY_TYPE_EQUALITY` `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE` This option only applies and may only be specified when `algorithm` is `MongoDB\Driver\ClientEncryption::ALGORITHM_INDEXED` or `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE`.
  rangeOpts | array | Index options for a queryable encryption field supporting "range" queries. The options below must match the values set in the `encryptedFields` of the target collection. For double and decimal128 BSON field types, `min`, `max`, and `precision` must all be set, or all be unset.
  Range index options
  Option | Type | Description
  --- | --- | ---
  min | mixed | Required if `precision` is set. The minimum BSON value of the range.
  max | mixed | Required if `precision` is set. The maximum BSON value of the range.
  sparsity | int | Optional; Positive 64-bit integer.
  precision | int | Optional. Positive 32-bit integer specifying precision to use for explicit encryption. May only be set for double or decimal128 BSON field types.
  trimFactor | int | Optional; Positive 32-bit integer.

### Rückgabewerte

Returns the encrypted expression as an object.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while encrypting the expression

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.20.0 | Added the `"trimFactor"` range option. The `"sparsity"` range option is now optional.

### Siehe auch

- MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager
- MongoDB\Driver\ClientEncryption::encrypt() - Encrypt a value

# MongoDB\Driver\ClientEncryption::getKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKey — Gets a key document

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::getKey(MongoDB\BSON\Binary `$keyId`): ?object

Finds a single key document in the key vault collection with the given UUID `keyId`.

### Parameter-Liste

`keyId`
  A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.

### Rückgabewerte

Returns the key document, or `null` if no document matched.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

# MongoDB\Driver\ClientEncryption::getKeyByAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeyByAltName — Gets a key document by an alternate name

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::getKeyByAltName(string `$keyAltName`): ?object

Finds a single key document in the key vault collection with the given alternate name `keyAltName`.

### Parameter-Liste

`keyAltName`
  Alternate name for the key document.

### Rückgabewerte

Returns the key document, or `null` if no document matched.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Siehe auch

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Adds an alternate name to a key document
- MongoDB\Driver\ClientEncryption::removeKeyAltName() - Removes an alternate name from a key document

# MongoDB\Driver\ClientEncryption::getKeys

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeys — Gets all key documents

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::getKeys(): MongoDB\Driver\Cursor

Finds all key documents in the key vault collection.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

# MongoDB\Driver\ClientEncryption::removeKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::removeKeyAltName — Removes an alternate name from a key document

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object

Removes `keyAltName` from the set of alternate names for the key document with the given UUID `keyId`.

### Parameter-Liste

`keyId`
  A MongoDB\BSON\Binary instance with subtype 4 (UUID) identifying the key document.
`keyAltName`
  Alternate name to remove from the key document.

### Rückgabewerte

Returns the previous version of the key document, or `null` if no document matched.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Siehe auch

- MongoDB\Driver\ClientEncryption::addKeyAltName() - Adds an alternate name to a key document
- MongoDB\Driver\ClientEncryption::getKeyByAltName() - Gets a key document by an alternate name

# MongoDB\Driver\ClientEncryption::rewrapManyDataKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Rewraps data keys

### Beschreibung

final public function MongoDB\Driver\ClientEncryption::rewrapManyDataKey(array|object `$filter`, ?array `$options` = `null`): object

Rewraps (i.e. decrypts and re-encrypts) zero or more data keys in the key vault collection that match the given `filter`.

If the `"provider"` option is not specified, matching data keys will be rewrapped with their current KMS provider. Otherwise, matching data keys will be re-encrypted according to the specified `"provider"` and `"masterKey"` options.

### Parameter-Liste

`filter` (array|object)

  Das » Abfrage-Prädikat. Ein leeres Prädikat passt auf alle Dokumente in der Sammlung.

  > Hinweis: Bei der Auswertung von Abfragekriterien vergleicht MongoDB Typen und Werte gemäß seiner eigenen » Vergleichsregeln für BSON-Typen, die sich von PHPs Regeln für Typenvergleich und Typen-Jonglage unterscheidet. Wenn es eine Übereinstimmung mit einem speziellen BSON-Typ gibt, sollten die Abfragekriterien die entsprechende BSON-Klasse verwenden (z. B. MongoDB\BSON\ObjectId, um auf eine » ObjectId zu passen).

`options`

  RewrapManyDataKey options
  Option | Type | Description
  --- | --- | ---
  provider | string | The KMS provider (e.g. `"local"`, `"aws"`) that will be used to re-encrypt the matched data keys. If a KMS provider is not specified, matched data keys will be re-encrypted with their current KMS provider.
  masterKey | array | The masterKey identifies a KMS-specific key used to encrypt the new data key. This option should not be specified without the `"provider"` option. This option is required if `"provider"` is specified and not `"local"`.
  `"aws"`-Provider-Optionen
  Option | Typ | Beschreibung
  --- | --- | ---
  region | string | Erforderlich
  key | string | Erforderlich; der Amazon-Ressourcenname (ARN) für den AWS-Kundenhauptschlüssel (CMK).
  endpoint | string | Optional; ein alternativer Host-Bezeichner, an den KMS-Anfragen gesendet werden; kann die Portnummer enthalten.
  `"azure"`-Provider-Optionen
  Option | Typ | Beschreibung
  --- | --- | ---
  keyVaultEndpoint | string | Erforderlich; der Host mit optionalem Port (z. B. "example.vault.azure.net").
  keyName | string | Erforderlich
  keyVersion | string | Optional; eine bestimmte Version des genannten Schlüssels. Standardmäßig wird die primäre Version des Schlüssels verwendet.
  `"gcp"`-Provider-Optionen
  Option | Typ | Beschreibung
  --- | --- | ---
  projectId | string | Erforderlich
  location | string | Erforderlich
  keyRing | string | Erforderlich
  keyName | string | Erforderlich
  keyVersion | string | Optional; eine bestimmte Version des genannten Schlüssels. Standardmäßig wird die primäre Version des Schlüssels verwendet.
  endpoint | string | Optional; der Host mit optionalem Port. Der Standardwert ist "cloudkms.googleapis.com".
  `"kmip"`-Provider-Optionen
  Option | Typ | Beschreibung
  --- | --- | ---
  keyId | string | Optional; der eindeutige Bezeichner für ein 96 Byte großes, verwaltetes geheimes KMIP-Datenobjekt. Wenn nicht angegeben, erstellt der Treiber ein zufälliges geheimes KMIP-Datenobjekt mit 96 Byte.
  endpoint | string | Optional; der Host mit optionalem Port.
  delegated | bool | Optional; wenn true, soll dieser Schlüssel vom KMIP-Server entschlüsselt werden.

### Rückgabewerte

Returns an object, which will have an optional `bulkWriteResult` property containing the result of the internal `bulkWrite` operation as an object. If no data keys matched the filter or the write was unacknowledged, the `bulkWriteResult` property will be `null`.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\EncryptionException if an error occurs while decrypting or re-encrypting a data key.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.20.0 | Added `"delegated"` to the KMIP provider masterKey options.

## Inhaltsverzeichnis

- MongoDB\Driver\ClientEncryption::addKeyAltName — Adds an alternate name to a key document
- MongoDB\Driver\ClientEncryption::__construct — Create a new ClientEncryption object
- MongoDB\Driver\ClientEncryption::createDataKey — Creates a key document
- MongoDB\Driver\ClientEncryption::decrypt — Decrypt a value
- MongoDB\Driver\ClientEncryption::deleteKey — Deletes a key document
- MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value
- MongoDB\Driver\ClientEncryption::encryptExpression — Encrypts a match or aggregate expression
- MongoDB\Driver\ClientEncryption::getKey — Gets a key document
- MongoDB\Driver\ClientEncryption::getKeyByAltName — Gets a key document by an alternate name
- MongoDB\Driver\ClientEncryption::getKeys — Gets all key documents
- MongoDB\Driver\ClientEncryption::removeKeyAltName — Removes an alternate name from a key document
- MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Rewraps data keys

# The MongoDB\Driver\ServerApi class

(mongodb >=1.10.0)

## Einführung

## Klassenbeschreibung

final class MongoDB\Driver\ServerApi implements MongoDB\BSON\Serializable, Serializable {
/* Konstanten */
const string MongoDB\Driver\ServerAPI::V1 = "1";
/* Methoden */
final public function bsonSerialize(): stdClass
final public function __construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)
}

## Vordefinierte Konstanten

`MongoDB\Driver\ServerApi::V1`
  Server API version 1.

## Beispiele

Beispiel #1 Declare an API version on a manager

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* The buildInfo command returns a single result document, so we need to access
     * the first result in the cursor. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    4.9.0-alpha7-49-gb968ca0

Beispiel #2 Declare a strict API version on a manager

The following example sets the `strict` flag, which tells the server to reject any command that is not part of the declared API version. This results in an error when running the buildInfo command.

    <?php

    use MongoDB\Driver\Manager;
    use MongoDB\Driver\ServerApi;

    $v1 = new ServerApi(ServerApi::v1, true);
    $manager = new Manager('mongodb://localhost:27017', [], ['serverApi' => $v1]);

    $command = new MongoDB\Driver\Command(['buildInfo' => 1]);

    try {
        $cursor = $manager->executeCommand('admin', $command);
    } catch(MongoDB\Driver\Exception $e) {
        echo $e->getMessage(), "\n";
        exit;
    }

    /* The buildInfo command returns a single result document, so we need to access
     * the first result in the cursor. */
    $buildInfo = $cursor->toArray()[0];

    echo $buildInfo->version, "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Provided apiStrict:true, but the command buildInfo is not in API Version 1

# MongoDB\Driver\ServerApi::bsonSerialize

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::bsonSerialize — Returns an object for BSON serialization

### Beschreibung

final public function MongoDB\Driver\ServerApi::bsonSerialize(): stdClass

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an object for serializing the ServerApi as BSON.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON

# MongoDB\Driver\ServerApi::__construct

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::__construct — Create a new ServerApi instance

### Beschreibung

final public function MongoDB\Driver\ServerApi::__construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)

Creates a new MongoDB\Driver\ServerApi instance used to declare an API version when creating a MongoDB\Driver\Manager.

### Parameter-Liste

`version`
  A server API version. Supported API versions are provided as constants in MongoDB\Driver\ServerApi. The only supported API version is `MongoDB\Driver\ServerApi::V1`.
`strict`
  If the `strict` parameter is set to `true`, the server will yield an error for any command that is not part of the specified API version. If no value is provided, the server default value (`false`) is used.
`deprecationErrors`
  If the `deprecationErrors` parameter is set to `true`, the server will yield an error when using a command that is deprecated in the specified API version. If no value is provided, the server default value (`false`) is used.

## Inhaltsverzeichnis

- MongoDB\Driver\ServerApi::bsonSerialize — Returns an object for BSON serialization
- MongoDB\Driver\ServerApi::__construct — Create a new ServerApi instance

# The MongoDB\Driver\WriteConcern class

(mongodb >=1.0.0)

## Einführung

MongoDB\Driver\WriteConcern describes the level of acknowledgement requested from MongoDB for write operations to a standalone `mongod` or to replica sets or to sharded clusters. In sharded clusters, `mongos` instances will pass the write concern on to the shards.

## Klassenbeschreibung

final class MongoDB\Driver\WriteConcern implements MongoDB\BSON\Serializable, Serializable {
/* Konstanten */
const string MAJORITY = "majority";
/* Eigenschaften */
public readonly string|int|null $w;
public readonly ?bool $j;
public readonly int $wtimeout;
/* Methoden */
final public function bsonSerialize(): stdClass
final public function __construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)
final public function getJournal(): ?bool
final public function getW(): string|int|null
final public function getWtimeout(): int
final public function isDefault(): bool
}

## Eigenschaften

w
  The write concern value (integer number of nodes, the string `"majority"`, or a custom write concern tag name), or `null` if not set.
j
  Whether write operations must be committed to the journal before acknowledged, or `null` if not specified.
wtimeout
  The timeout in milliseconds to wait for write concern acknowledgement. A value of `0` means to wait indefinitely.

## Vordefinierte Konstanten

`MongoDB\Driver\WriteConcern::MAJORITY`
  Majority of all the members in the set; arbiters, non-voting members, passive members, hidden members and delayed members are all included in the definition of majority write concern.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.
PECL mongodb 1.7.0 | Implements Serializable.
PECL mongodb 1.2.0 | Implements MongoDB\BSON\Serializable.

# MongoDB\Driver\WriteConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\WriteConcern::bsonSerialize — Returns an object for BSON serialization

### Beschreibung

final public function MongoDB\Driver\WriteConcern::bsonSerialize(): stdClass

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an object for serializing the WriteConcern as BSON.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteConcern::bsonSerialize() with majority write concern

    <?php

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#2 (1) {
      ["w"]=>
      string(8) "majority"
    }

    { "w" : "majority" }

Beispiel #2 MongoDB\Driver\WriteConcern::bsonSerialize() with wtimeout and journal

    <?php

    $wc = new MongoDB\Driver\WriteConcern(2, 1000, true);
    var_dump($wc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#2 (3) {
      ["w"]=>
      int(2)
      ["j"]=>
      bool(true)
      ["wtimeout"]=>
      int(1000)
    }

    { "w" : 2, "j" : true, "wtimeout" : 1000 }

### Siehe auch

- MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
- » Write Concern reference

# MongoDB\Driver\WriteConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::__construct — Create a new WriteConcern

### Beschreibung

final public function MongoDB\Driver\WriteConcern::__construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)

Constructs a new MongoDB\Driver\WriteConcern, which is an immutable value object.

### Parameter-Liste

`w`

  Write concern
  Value | Description
  --- | ---
  1 | Requests acknowledgement that the write operation has propagated to the standalone `mongod` or the primary in a replica set. This is the default write concern for MongoDB.
  0 | Requests no acknowledgment of the write operation. However, this may return information about socket exceptions and networking errors to the application.
  <integer greater than 1> | Numbers greater than 1 are valid only for replica sets to request acknowledgement from specified number of members, including the primary.
  `MongoDB\Driver\WriteConcern::MAJORITY` | Requests acknowledgment that write operations have propagated to the majority of voting nodes, including the primary, and have been written to the on-disk journal for these nodes. Prior to MongoDB 3.0, this refers to the majority of replica set members (not just voting nodes).
  string | A string value is interpereted as a tag set. Requests acknowledgement that the write operations have propagated to a replica set member with the specified tag.

`wtimeout`
  How long to wait (in milliseconds) for secondaries before failing. `wtimeout` causes write operations to return with an error (WriteConcernError) after the specified limit, even if the required write concern will eventually succeed. When these write operations return, MongoDB does not undo successful data modifications performed before the write concern exceeded the `wtimeout` time limit. If specified, `wtimeout` must be a signed 64-bit integer greater than or equal to zero.

  Write concern timeout
  Value | Description
  --- | ---
  0 | Block indefinitely. This is the default.
  <integer greater than 0> | Milliseconds to wait until returning.

`journal`
  Wait until mongod has applied the write to the journal.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `w` is invalid or `wtimeout` is either negative or greater than the bounds of a signed 32-bit integer.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.7.0 | The `wTimeout` parameter now accepts 64-bit values.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteConcern::__construct() example

    <?php

    /* Request write acknowledgement from the majority of the replica set nodes */
    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 500);

    /* Request write acknowledgement from a node configured with the "MultipleDC" tag */
    $wc = new MongoDB\Driver\WriteConcern("MultipleDC", 500);

    ?>

### Siehe auch

- » Write Concern reference

# MongoDB\Driver\WriteConcern::getJournal

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option

### Beschreibung

final public function MongoDB\Driver\WriteConcern::getJournal(): ?bool

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the WriteConcern's "journal" option.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteConcern::getJournal() example

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, true);
    var_dump($wc->getJournal());

    $wc = new MongoDB\Driver\WriteConcern(1, 0, false);
    var_dump($wc->getJournal());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL
    bool(true)
    bool(false)

### Siehe auch

- » Write Concern reference

# MongoDB\Driver\WriteConcern::getW

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option

### Beschreibung

final public function MongoDB\Driver\WriteConcern::getW(): string|int|null

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the WriteConcern's "w" option.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteConcern::getW() example

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getW());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY);
    var_dump($wc->getW());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)
    string(8) "majority"

### Siehe auch

- » Write Concern reference

# MongoDB\Driver\WriteConcern::getWtimeout

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option

### Beschreibung

final public function MongoDB\Driver\WriteConcern::getWtimeout(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the WriteConcern's "wtimeout" option.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.7.0 | On 32-bit systems, this method will always truncate the `wTimeout` value if it exceeds the 32-bit range. In that case, a warning will be emitted.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteConcern::getWtimeout() example

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->getWtimeout());

    $wc = new MongoDB\Driver\WriteConcern(MongoDB\Driver\WriteConcern::MAJORITY, 3000);
    var_dump($wc->getWtimeout());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    int(3000)

### Siehe auch

- » Write Concern reference

# MongoDB\Driver\WriteConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern

### Beschreibung

final public function MongoDB\Driver\WriteConcern::isDefault(): bool

Returns whether this is the default write concern (i.e. no options are specified). This method is primarily intended to be used in conjunction with MongoDB\Driver\Manager::getWriteConcern() to determine whether the Manager has been constructed without any write concern options.

The driver will not include a default write concern in its write operations (e.g. MongoDB\Driver\Manager::executeBulkWrite()) in order to allow the server to apply its own default, which may have been » modified. Libraries that access the Manager's write concern to include it in their own write commands should use this method to ensure that default write concerns are left unset.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if this is the default write concern and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteConcern::isDefault() example

    <?php

    $wc = new MongoDB\Driver\WriteConcern(1);
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?w=majority');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $wc = $manager->getWriteConcern();
    var_dump($wc->isDefault());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(false)
    bool(true)

### Siehe auch

- MongoDB\Driver\Manager::getWriteConcern() - Return the WriteConcern for the Manager
- » Modify Default Write Concern in the MongoDB manual
- » Write Concern reference

## Inhaltsverzeichnis

- MongoDB\Driver\WriteConcern::bsonSerialize — Returns an object for BSON serialization
- MongoDB\Driver\WriteConcern::__construct — Create a new WriteConcern
- MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option
- MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option
- MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option
- MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern

# The MongoDB\Driver\ReadPreference class

(mongodb >=1.0.0)

## Einführung

## Klassenbeschreibung

final class MongoDB\Driver\ReadPreference implements MongoDB\BSON\Serializable, Serializable {
/* Eigenschaften */
public readonly string $mode;
public readonly ?array $tags;
public readonly int $maxStalenessSeconds;
public readonly ?object $hedge;
/* Konstanten */
const string PRIMARY = primary;
const string PRIMARY_PREFERRED = primaryPreferred;
const string SECONDARY = secondary;
const string SECONDARY_PREFERRED = secondaryPreferred;
const string NEAREST = nearest;
const int NO_MAX_STALENESS = -1;
const int SMALLEST_MAX_STALENESS_SECONDS = 90;
/* Methoden */
final public function bsonSerialize(): stdClass
final public function __construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)
final public function getHedge(): ?object
final public function getMaxStalenessSeconds(): int
final public function getMode(): int
final public function getModeString(): string
final public function getTagSets(): array
}

## Eigenschaften

mode
  The read preference mode as a string (e.g. `"primary"`, `"secondary"`).
tags
  The tag set list used by the read preference, or `null` if no tag sets were specified.
maxStalenessSeconds
  The maximum staleness in seconds for reads, or `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` if no maximum staleness was specified.
hedge
  A document specifying the hedge options for the read preference, or `null` if no hedge options were specified.
  Warnung

  This property is deprecated as hedged reads are deprecated in MongoDB 8.0.

## Vordefinierte Konstanten

`MongoDB\Driver\ReadPreference::PRIMARY`
  All operations read from the current replica set primary. This is the default read preference for MongoDB.
`MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`
  In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.
`MongoDB\Driver\ReadPreference::SECONDARY`
  All operations read from the secondary members of the replica set.
`MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED`
  In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.
`MongoDB\Driver\ReadPreference::NEAREST`
  Operations read from member of the replica set with the least network latency, irrespective of the member's type.
`MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`
  The default value for the `"maxStalenessSeconds"` option is to specify no limit on maximum staleness, which means that the driver will not consider a secondary's lag when choosing where to direct a read operation.
`MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`
  The minimum value for the `"maxStalenessSeconds"` option is 90 seconds. The driver estimates secondaries' staleness by periodically checking the latest write date of each replica set member. Since these checks are infrequent, the staleness estimate is coarse. Thus, the driver cannot enforce a max staleness value of less than 90 seconds.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.
PECL mongodb 2.0.0 | Removed the `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED`, and `MongoDB\Driver\ReadPreference::RP_NEAREST` constants. The getMode() method was also removed.
PECL mongodb 1.20.0 | Deprecated the `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED`, and `MongoDB\Driver\ReadPreference::RP_NEAREST` constants.
PECL mongodb 1.7.0 | Added the `MongoDB\Driver\ReadPreference::PRIMARY`, `MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::SECONDARY`, `MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED`, and `MongoDB\Driver\ReadPreference::NEAREST` constants. Implements Serializable.
PECL mongodb 1.2.0 | Added the `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` and `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS` constants. Implements MongoDB\BSON\Serializable.

# MongoDB\Driver\ReadPreference::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::bsonSerialize — Returns an object for BSON serialization

### Beschreibung

final public function MongoDB\Driver\ReadPreference::bsonSerialize(): stdClass

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an object for serializing the ReadPreference as BSON.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadPreference::bsonSerialize() with primary read preference

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#2 (1) {
      ["mode"]=>
      string(7) "primary"
    }

    { "mode" : "primary" }

Beispiel #2 MongoDB\Driver\ReadPreference::bsonSerialize() with secondary read preference and tag sets

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        [
            ['dc' => 'ny'],
            ['dc' => 'sf', 'use' => 'reporting'],
            []
        ]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["tags"]=>
      array(3) {
        [0]=>
        object(stdClass)#1 (1) {
          ["dc"]=>
          string(2) "ny"
        }
        [1]=>
        object(stdClass)#5 (2) {
          ["dc"]=>
          string(2) "sf"
          ["use"]=>
          string(9) "reporting"
        }
        [2]=>
        object(stdClass)#4 (0) {
        }
      }
    }

    { "mode" : "secondary", "tags" : [ { "dc" : "ny" }, { "dc" : "sf", "use" : "reporting" }, {  } ] }

Beispiel #3 MongoDB\Driver\ReadPreference::bsonSerialize() with secondary read preference and max staleness

    <?php

    $rp = new MongoDB\Driver\ReadPreference(
        MongoDB\Driver\ReadPreference::SECONDARY,
        null,
        ['maxStalenessSeconds' => 120]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#2 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }

    { "mode" : "secondary", "maxStalenessSeconds" : 120 }

### Siehe auch

- MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
- » Read Preference reference

# MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference

### Beschreibung

final public function MongoDB\Driver\ReadPreference::__construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)

Constructs a new MongoDB\Driver\ReadPreference, which is an immutable value object.

### Parameter-Liste

`mode`

  Read preference mode
  Value | Description
  --- | ---
  `"primary"` | All operations read from the current replica set primary. This is the default read preference for MongoDB.
  `"primaryPreferred"` | In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.
  `"secondary"` | All operations read from the secondary members of the replica set.
  `"secondaryPreferred"` | In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.
  `"nearest"` | Operations read from member of the replica set with the least network latency, irrespective of the member's type.

`tagSets`
  Tag sets allow you to target read operations to specific members of a replica set. This parameter should be an array of associative arrays, each of which contain zero or more key/value pairs. When selecting a server for a read operation, the driver attempt to select a node having all tags in a set (i.e. the associative array of key/value pairs). If selection fails, the driver will attempt subsequent sets. An empty tag set (`array()`) will match any node and may be used as a fallback. Tags are not compatible with the `"primary"` mode and, in general, only apply when selecting a secondary member of a set for a read operation. However, the `"nearest"` mode, when combined with a tag set, selects the matching member with the lowest network latency. This member may be a primary or secondary.
`options`

  options
  Option | Type | Description
  --- | --- | ---
  hedge | object|array | Specifies whether to use » hedged reads, which are supported by MongoDB 4.4+ for sharded queries. Server hedged reads are available for all non-primary read preferences and are enabled by default when using the `"nearest"` mode. This option allows explicitly enabling server hedged reads for non-primary read preferences by specifying `['enabled' => true]`, or explicitly disabling server hedged reads for the `"nearest"` read preference by specifying `['enabled' => false]`.
  maxStalenessSeconds | int | Specifies a maximum replication lag, or "staleness", for reads from secondaries. When a secondary's estimated staleness exceeds this value, the driver stops using it for read operations. If specified, the max staleness must be a signed 32-bit integer greater than or equal to `MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS`. Defaults to `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS`, which means that the driver will not consider a secondary's lag when choosing where to direct a read operation. This option is not compatible with the `"primary"` mode. Specifying a max staleness also requires all MongoDB instances in the deployment to be using MongoDB 3.4+. An exception will be thrown at execution time if any MongoDB instances in the deployment are of an older server version.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `mode` is invalid.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `tagSets` is provided for a primary read preference or is malformed (i.e. not an array of zero or more documents).
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the `"maxStalenessSeconds"` option is provided for a primary read preference or is out of range.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Passing an int for the `mode` argument is no longer supported.
PECL mongodb 1.20.0 | Passing an int for the `mode` argument is DEPRECATED.
PECL mongodb 1.8.0 | Added the `"hedge"` option.
PECL mongodb 1.3.0 | The `mode` argument now accepts a string value, which is consistent with the `"readPreference"` URI option for MongoDB\Driver\Manager::__construct().
PECL mongodb 1.2.0 | Added a third `options` argument, which supports the `"maxStalenessSeconds"` option.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadPreference::__construct() example

    <?php

    /* Prefer a secondary node but fall back to a primary. */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED));

    /* Prefer a node in the New York data center with lowest latency. */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST, [['dc' => 'ny']]));

    /* Require a secondary node whose replication lag is within two minutes of the primary */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['maxStalenessSeconds' => 120]));

    /* Explicitly enable server hedged reads */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, ['hedge' => ['enabled' => true]]));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MongoDB\Driver\ReadPreference)#1 (1) {
      ["mode"]=>
      string(18) "secondaryPreferred"
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(7) "nearest"
      ["tags"]=>
      array(1) {
        [0]=>
        object(stdClass)#2 (1) {
          ["dc"]=>
          string(2) "ny"
        }
      }
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["maxStalenessSeconds"]=>
      int(120)
    }
    object(MongoDB\Driver\ReadPreference)#1 (2) {
      ["mode"]=>
      string(9) "secondary"
      ["hedge"]=>
      object(stdClass)#1 (1) {
        ["enabled"]=>
        bool(true)
      }
    }

### Siehe auch

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getHedge

(mongodb >=1.8.0)

MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option

### Beschreibung

final public function MongoDB\Driver\ReadPreference::getHedge(): ?object

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ReadPreference's "hedge" option.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getMaxStalenessSeconds

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option

### Beschreibung

final public function MongoDB\Driver\ReadPreference::getMaxStalenessSeconds(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ReadPreference's "maxStalenessSeconds" option. If no max staleness has been specified, `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` will be returned.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadPreference::getMaxStalenessSeconds() example

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::NO_MAX_STALENESS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => 1000,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(-1)
    int(-1)
    int(90)
    int(1000)

### Siehe auch

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getMode

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option

Warnung

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\Driver\ReadPreference::getModeString() instead.

### Beschreibung

final public function MongoDB\Driver\ReadPreference::getMode(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ReadPreference's "mode" option.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Methode wurde entfernt.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadPreference::getMode() example

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getMode());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)
    int(5)
    int(2)
    int(6)
    int(10)

### Siehe auch

- MongoDB\Driver\ReadPreference::getModeString() - Returns the ReadPreference's "mode" option
- » Read Preference reference

# MongoDB\Driver\ReadPreference::getModeString

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::getModeString — Returns the ReadPreference's "mode" option

### Beschreibung

final public function MongoDB\Driver\ReadPreference::getModeString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ReadPreference's "mode" option as a string.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadPreference::getModeString() example

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getModeString());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::NEAREST);
    var_dump($rp->getModeString());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(7) "primary"
    string(16) "primaryPreferred"
    string(9) "secondary"
    string(18) "secondaryPreferred"
    string(7) "nearest"

### Siehe auch

- MongoDB\Driver\ReadPreference::getMode() - Returns the ReadPreference's "mode" option
- » Read Preference reference

# MongoDB\Driver\ReadPreference::getTagSets

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option

### Beschreibung

final public function MongoDB\Driver\ReadPreference::getTagSets(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ReadPreference's "tagSets" option.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadPreference::getTagSets() example

    <?php

    $mode = MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED;

    /* Null and an empty array both denote no tag set preference. */
    $rp = new MongoDB\Driver\ReadPreference($mode, null);
    var_dump($rp->getTagSets());

    $rp = new MongoDB\Driver\ReadPreference($mode, []);
    var_dump($rp->getTagSets());

    /* Prefer a node in New York, but fall back to any available node. */
    $rp = new MongoDB\Driver\ReadPreference($mode, [['dc' => 'ny']]);
    var_dump($rp->getTagSets());

    /* Prefer a node in the New York, followed by a node in San Francisco that is
       labeled for reporting usage, and finally fall back to any available node. */
    $rp = new MongoDB\Driver\ReadPreference($mode, [
      ['dc' => 'ny'],
      ['dc' => 'sf', 'use' => 'reporting'],
      [],
    ]);
    var_dump($rp->getTagSets());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(0) {
    }
    array(0) {
    }
    array(2) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(0) {
      }
    }
    array(3) {
      [0]=>
      array(1) {
        ["dc"]=>
        string(2) "ny"
      }
      [1]=>
      array(2) {
        ["dc"]=>
        string(2) "sf"
        ["use"]=>
        string(9) "reporting"
      }
      [2]=>
      array(0) {
      }
    }

### Siehe auch

- » Read Preference reference

## Inhaltsverzeichnis

- MongoDB\Driver\ReadPreference::bsonSerialize — Returns an object for BSON serialization
- MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference
- MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option
- MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option
- MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option
- MongoDB\Driver\ReadPreference::getModeString — Returns the ReadPreference's "mode" option
- MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option

# The MongoDB\Driver\ReadConcern class

(mongodb >=1.1.0)

## Einführung

MongoDB\Driver\ReadConcern controls the level of isolation for read operations for replica sets and replica set shards. This option requires MongoDB 3.2 or later.

## Klassenbeschreibung

final class MongoDB\Driver\ReadConcern implements MongoDB\BSON\Serializable, Serializable {
/* Eigenschaften */
public readonly ?string $level;
/* Konstanten */
const string AVAILABLE = "available";
const string LINEARIZABLE = "linearizable";
const string LOCAL = "local";
const string MAJORITY = "majority";
const string SNAPSHOT = "snapshot";
/* Methoden */
final public function bsonSerialize(): stdClass
final public function __construct(?string `$level` = `null`)
final public function getLevel(): ?string
final public function isDefault(): bool
}

## Eigenschaften

level
  The read concern level. `null` if no level was specified.

## Vordefinierte Konstanten

`MongoDB\Driver\ReadConcern::AVAILABLE`
  Default for reads against secondaries when `afterClusterTime`and `level` are unspecified. The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back). For unsharded collections (including collections in a standalone deployment or a replica set deployment), `"local"` and `"available"` read concerns behave identically. For a sharded cluster, `"available"` read concern provides greater tolerance for partitions since it does not wait to ensure consistency guarantees. However, a query with `"available"` read concern may return orphan documents if the shard is undergoing chunk migrations since the `"available"` read concern, unlike `"local"` read concern, does not contact the shard's primary nor the config servers for updated metadata.
`MongoDB\Driver\ReadConcern::LINEARIZABLE`
  The query returns data that reflects all successful writes issued with a write concern of `"majority"` and acknowledged prior to the start of the read operation. For replica sets that run with `writeConcernMajorityJournalDefault` set to `true`, linearizable read concern returns data that will never be rolled back. With `writeConcernMajorityJournalDefault` set to `false`, MongoDB will not wait for `w: "majority"` writes to be durable before acknowledging the writes. As such, `"majority"` write operations could possibly roll back in the event of a loss of a replica set member. You can specify linearizable read concern for read operations on the primary only. Linearizable read concern guarantees only apply if read operations specify a query filter that uniquely identifies a single document.
  Tipp

  Always use `maxTimeMS` with linearizable read concern in case a majority of data bearing members are unavailable. `maxTimeMS` ensures that the operation does not block indefinitely and instead ensures that the operation returns an error if the read concern cannot be fulfilled.

  Linearizable read concern requires MongoDB 3.4.
`MongoDB\Driver\ReadConcern::LOCAL`
  Default for reads against primary if `level` is unspecified and for reads against secondaries if `level` is unspecified but `afterClusterTime` is specified. The query returns the instance's most recent data. Provides no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
`MongoDB\Driver\ReadConcern::MAJORITY`
  The query returns the instance's most recent data acknowledged as having been written to a majority of members in the replica set. To use read concern level of `"majority"`, replica sets must use WiredTiger storage engine and election protocol version 1.
`MongoDB\Driver\ReadConcern::SNAPSHOT`
  Read concern `"snapshot"` is available for multi-document transactions, and starting in MongoDB 5.0, certain read operations outside of multi-document transactions. If the transaction is not part of a causally consistent session, upon transaction commit with write concern `"majority"`, the transaction operations are guaranteed to have read from a snapshot of majority-committed data. If the transaction is part of a causally consistent session, upon transaction commit with write concern `"majority"`, the transaction operations are guaranteed to have read from a snapshot of majority-committed data that provides causal consistency with the operation immediately preceding the transaction start. Outside of multi-document transactions, read concern `"snapshot"` is available on primaries and secondaries for the following read operations: `find`, `aggregate`, and `distinct` (on unsharded collections). All other read commands prohibit `"snapshot"`.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.
PECL mongodb 1.11.0 | Added the `MongoDB\Driver\ReadConcern::SNAPSHOT` constant.
PECL mongodb 1.7.0 | Implements Serializable.
PECL mongodb 1.4.0 | Added the `MongoDB\Driver\ReadConcern::AVAILABLE` constant.
PECL mongodb 1.2.0 | Added the `MongoDB\Driver\ReadConcern::LINEARIZABLE` constant. Implements MongoDB\BSON\Serializable.

## Siehe auch

- » Read Concern reference

# MongoDB\Driver\ReadConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization

### Beschreibung

final public function MongoDB\Driver\ReadConcern::bsonSerialize(): stdClass

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an object for serializing the ReadConcern as BSON.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadConcern::bsonSerialize() with empty read concern

    <?php

    $rc = new MongoDB\Driver\ReadConcern;
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#2 (0) {
    }

    { }

Beispiel #2 MongoDB\Driver\ReadConcern::bsonSerialize() with local read concern

    <?php

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#2 (1) {
      ["level"]=>
      string(5) "local"
    }

    { "level" : "local" }

### Siehe auch

- MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
- » Read Concern reference

# MongoDB\Driver\ReadConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::__construct — Create a new ReadConcern

### Beschreibung

final public function MongoDB\Driver\ReadConcern::__construct(?string `$level` = `null`)

Constructs a new MongoDB\Driver\ReadConcern, which is an immutable value object.

### Parameter-Liste

`level`
  The » read concern level. You may use, but are not limited to, one of the class constants.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadConcern::__construct() example

    <?php

    /* Unspecified read isolation level (uses the server's default behavior) */
    $rc = new MongoDB\Driver\ReadConcern();

    /* Request read isolation from a single replica set node */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);

    /* Request read isolation from a majority of the replica set nodes */
    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);

    ?>

### Siehe auch

- » Read Concern reference

# MongoDB\Driver\ReadConcern::getLevel

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option

### Beschreibung

final public function MongoDB\Driver\ReadConcern::getLevel(): ?string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ReadConcern's "level" option.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadConcern::getLevel() example

    <?php

    $rc = new MongoDB\Driver\ReadConcern();
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::LOCAL);
    var_dump($rc->getLevel());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->getLevel());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL
    string(5) "local"
    string(8) "majority"

### Siehe auch

- » Read Concern reference

# MongoDB\Driver\ReadConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern

### Beschreibung

final public function MongoDB\Driver\ReadConcern::isDefault(): bool

Returns whether this is the default read concern (i.e. no options are specified). This method is primarily intended to be used in conjunction with MongoDB\Driver\Manager::getReadConcern() to determine whether the Manager has been constructed without any read concern options.

The driver will not include a default read concern in its read operations (e.g. MongoDB\Driver\Manager::executeQuery()) in order to allow the server to apply its own default. Libraries that access the Manager's read concern to include it in their own read commands should use this method to ensure that default read concerns are left unset.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if this is the default read concern and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\ReadConcern::isDefault() example

    <?php

    $rc = new MongoDB\Driver\ReadConcern(null);
    var_dump($rc->isDefault());

    $rc = new MongoDB\Driver\ReadConcern(MongoDB\Driver\ReadConcern::MAJORITY);
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/?readConcernLevel=majority');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    $manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1/');
    $rc = $manager->getReadConcern();
    var_dump($rc->isDefault());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Siehe auch

- MongoDB\Driver\Manager::getReadConcern() - Return the ReadConcern for the Manager
- » Read Concern reference

## Inhaltsverzeichnis

- MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization
- MongoDB\Driver\ReadConcern::__construct — Create a new ReadConcern
- MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option
- MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern

# The MongoDB\Driver\Cursor class

(mongodb >=1.0.0)

## Einführung

The MongoDB\Driver\Cursor class encapsulates the results of a MongoDB command or query and may be returned by MongoDB\Driver\Manager::executeCommand() or MongoDB\Driver\Manager::executeQuery(), respectively.

## Klassenbeschreibung

final class MongoDB\Driver\Cursor implements MongoDB\Driver\CursorInterface {
/* Methoden */
final private function __construct()
public function current(): array|object|null
final public function getId(): MongoDB\BSON\Int64
final public function getServer(): MongoDB\Driver\Server
final public function isDead(): bool
public function key(): int
public function next(): void
public function rewind(): void
final public function setTypeMap(array `$typemap`): void
final public function toArray(): array
public function valid(): bool
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.9.0 | Implements Iterator.
PECL mongodb 1.6.0 | Implements MongoDB\Driver\CursorInterface, which extends Traversable.

## Beispiele

Beispiel #1 Reading a result set

MongoDB\Driver\Manager::executeCommand() and MongoDB\Driver\Manager::executeQuery() both return their result(s) as a MongoDB\Driver\Cursor object. This object can be used to iterate over the result set of the command or query.

Because MongoDB\Driver\Cursor implements the Traversable interface, you can simply iterate over the result set with `foreach`.

    <?php

    $manager = new MongoDB\Driver\Manager();

    /* Insert some documents so that our query returns information */
    $bulkWrite = new MongoDB\Driver\BulkWrite;
    $bulkWrite->insert(['name' => 'Ceres', 'size' => 946, 'distance' => 2.766]);
    $bulkWrite->insert(['name' => 'Vesta', 'size' => 525, 'distance' => 2.362]);
    $manager->executeBulkWrite("test.asteroids", $bulkWrite);

    /* Query for all the items in the collection */
    $query = new MongoDB\Driver\Query( [] );

    /* Query the "asteroids" collection of the "test" database */
    $cursor = $manager->executeQuery("test.asteroids", $query);

    /* $cursor now contains an object that wraps around the result set. Use
     * foreach() to iterate over all the result */
    foreach($cursor as $document) {
        print_r($document);
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc2
            )

        [name] => Ceres
        [size] => 946
        [distance] => 2.766
    )
    stdClass Object
    (
        [_id] => MongoDB\BSON\ObjectId Object
            (
                [oid] => 5a4cff2f122d3321565d8cc3
            )

        [name] => Vesta
        [size] => 525
        [distance] => 2.362
    )

Beispiel #2 Reading a result set for a tailable cursor

» Tailable cursors are a special type of MongoDB cursor that allows the client to read some results and then wait until more documents become available. These cursors are primarily used with » Capped Collections and » Change Streams.

While normal cursors can be iterated once with `foreach`, that approach will not work with tailable cursors. When `foreach` is used with a tailable cursor, the loop will stop upon reaching the end of the initial result set. Attempting to continue iteration on the cursor with a second `foreach` would throw an exception, since PHP attempts to rewind the cursor. Similar to result objects in other database drivers, cursors in MongoDB only support forward iteration, which means they cannot be rewound.

In order to continuously read from a tailable cursor, the Cursor object must be wrapped with an IteratorIterator. This allows the application to directly control the cursor's iteration, avoid inadvertently rewinding the cursor, and decide when to wait for new results or stop iteration entirely.

In order to demonstrate a tailable cursor in action, two scripts will be used: a "producer" and a "consumer". The producer script will create a new capped collection using the » create command and proceed to insert a new document into that collection each second.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $manager->executeCommand('test', new MongoDB\Driver\Command([
        'create' => 'asteroids',
        'capped' => true,
        'size' => 1048576,
    ]));

    while (true) {
        $bulkWrite = new MongoDB\Driver\BulkWrite;
        $bulkWrite->insert(['createdAt' => new MongoDB\BSON\UTCDateTime]);
        $manager->executeBulkWrite('test.asteroids', $bulkWrite);

        sleep(1);
    }

    ?>

With the producer script still running, a second consumer script may be executed to read the inserted documents using a tailable cursor, indicated by the `tailable` and `awaitData` options to MongoDB\Driver\Query::__construct().

    <?php

    $manager = new MongoDB\Driver\Manager;

    $query = new MongoDB\Driver\Query([], [
        'tailable' => true,
        'awaitData' => true,
    ]);

    $cursor = $manager->executeQuery('test.asteroids', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();

    while (true) {
        if ($iterator->valid()) {
            $document = $iterator->current();
            printf("Consumed document created at: %s\n", $document->createdAt);
        }

        $iterator->next();
    }

    ?>

The consumer script will start by quickly printing all available documents in the capped collection (as if `foreach` had been used); however, it will not terminate upon reaching the end of the initial result set. Since the cursor is tailable, calling IteratorIterator::next() will block and wait for additional results. IteratorIterator::valid() is also used to check if there is actually data available to read at each step.

> Hinweis: This example uses the `awaitData` query option to instruct the server to block for a short period (e.g. one second) at the end of the result set before returning a response to the driver. This is used to prevent the driver from aggressively polling the server when there are no results available. The `maxAwaitTimeMS` option may be used in conjunction with `tailable` and `awaitData` to specify the amount of time that the server should block when it reaches the end of the result set.

## Fehler/Exceptions

When iterating over the cursor object, BSON data is converted into PHP variables. This iteration can cause the following Exceptions:

- Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.
- Wirft eine MongoDB\Driver\Exception\UnexpectedValueException, wenn die Eingabe nicht genau ein BSON-Dokument enthält. Mögliche Gründe sind unter anderem ungültiges BSON, zusätzliche Daten (nach dem Lesen eines BSON-Dokuments) oder ein unerwarteter » libbson-Fehler.

# MongoDB\Driver\Cursor::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)

### Beschreibung

final private function MongoDB\Driver\Cursor::__construct()

MongoDB\Driver\Cursor objects are returned as the result of an executed command or query and cannot be constructed directly.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- MongoDB\Driver\Manager::executeCommand() - Execute a database command
- MongoDB\Driver\Manager::executeQuery() - Execute a database query
- MongoDB\Driver\Server::executeCommand() - Execute a database command on this server
- MongoDB\Driver\Server::executeQuery() - Execute a database query on this server

# MongoDB\Driver\Cursor::current

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::current — Returns the current element

### Beschreibung

public function MongoDB\Driver\Cursor::current(): array|object|null

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the current result document as an array or object, depending on the cursor's type map. If iteration has not started or the current position is not valid, `null` will be returned.

### Siehe auch

- Iterator::current() - Liefert das aktuelle Element

# MongoDB\Driver\Cursor::getId

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getId — Returns the ID for this cursor

### Beschreibung

final public function MongoDB\Driver\Cursor::getId(): MongoDB\BSON\Int64

Returns the ID for this cursor, which uniquely identifies the cursor on the server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ID for this cursor. The ID will be returned as a MongoDB\BSON\Int64 object.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The return type was changed to MongoDB\BSON\Int64. The `asInt64` parameter was removed.
PECL mongodb 1.20.0 | Deprecated returning a MongoDB\Driver\CursorId. Added the `asInt64` argument to ease migration for future versions. If `asInt64` is `true`, the ID will be returned as a MongoDB\BSON\Int64.

### Beispiele

Beispiel #1 MongoDB\Driver\Cursor::getId() example

    <?php

    /* In this example, we insert several documents into the collection and specify
     * a smaller batchSize to ensure that the first batch contains only a subset of
     * our results and the cursor remains open on the server. */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getId(true));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\BSON\Int64)#5 (1) {
      ["integer"]=>
      string(11) "94810124093"
    }

### Siehe auch

- MongoDB\BSON\Int64

# MongoDB\Driver\Cursor::getServer

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor

### Beschreibung

final public function MongoDB\Driver\Cursor::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server associated with this cursor. This is the server that executed the MongoDB\Driver\Query or MongoDB\Driver\Command.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the MongoDB\Driver\Server associated with this cursor.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Cursor::getServer() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump($cursor->getServer());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\Driver\Server)#5 (10) {
      ["host"]=>
      string(9) "localhost"
      ["port"]=>
      int(27017)
      ["type"]=>
      int(1)
      ["is_primary"]=>
      bool(false)
      ["is_secondary"]=>
      bool(false)
      ["is_arbiter"]=>
      bool(false)
      ["is_hidden"]=>
      bool(false)
      ["is_passive"]=>
      bool(false)
      ["last_hello_response"]=>
      array(8) {
        ["isWritablePrimary"]=>
        bool(true)
        ["maxBsonObjectSize"]=>
        int(16777216)
        ["maxMessageSizeBytes"]=>
        int(48000000)
        ["maxWriteBatchSize"]=>
        int(1000)
        ["localTime"]=>
        object(MongoDB\BSON\UTCDateTime)#6 (1) {
          ["milliseconds"]=>
          int(1446505367907)
        }
        ["maxWireVersion"]=>
        int(3)
        ["minWireVersion"]=>
        int(0)
        ["ok"]=>
        float(1)
      }
      ["round_trip_time"]=>
      int(584)
    }

### Siehe auch

- MongoDB\Driver\Server

# MongoDB\Driver\Cursor::isDead

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::isDead — Checks if the cursor is exhausted or may have additional results

### Beschreibung

final public function MongoDB\Driver\Cursor::isDead(): bool

Checks whether there are definitely no additional results available on the cursor. This method is similar to the » cursor.isExhausted() method in the MongoDB shell and is primarily useful when iterating » tailable cursors.

A cursor has no additional results and is considered "dead" when one of the following is true:

- The current batch has been fully iterated and the cursor ID is zero (i.e. a » getMore cannot be issued).
- An error was encountered while iterating the cursor.
- The cursor reached its configured limit.

By design, it is not possible to always determine whether a cursor has additional results. The cases where a cursor may have more data available is as follows:

- There are additional documents in the current batch, which are buffered on the client side. Iterating will fetch a document from the local buffer.
- There are no additional documents in the current batch (i.e. local buffer), but the cursor ID is non-zero. Iterating will request more documents from the server via a » getMore operation, which may or may not return additional results and/or indicate that the cursor has been closed on the server by returning zero for its ID.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if there are definitely no additional results available on the cursor, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Cursor::isDead() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);

    $iterator = new IteratorIterator($cursor);

    $iterator->rewind();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    $iterator->next();
    var_dump($cursor->isDead());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Siehe auch

- » Tailable Cursors in the MongoDB manual
- » cursor.isExhausted() in the MongoDB manual

# MongoDB\Driver\Cursor::key

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::key — Returns the current result's index within the cursor

### Beschreibung

public function MongoDB\Driver\Cursor::key(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The current result's numeric index within the cursor.

### Siehe auch

- Iterator::key() - Liefert den Schlüssel des aktuellen Elements

# MongoDB\Driver\Cursor::next

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::next — Advances the cursor to the next result

### Beschreibung

public function MongoDB\Driver\Cursor::next(): void

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Moves the current position to the next element in the cursor.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.

### Siehe auch

- Iterator::next() - Rückt den Zeiger auf das nächste Element vor

# MongoDB\Driver\Cursor::rewind

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result

### Beschreibung

public function MongoDB\Driver\Cursor::rewind(): void

If the cursor has advanced beyond its first position, it can no longer be rewound.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

`null`.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\LogicException if this method is called after the cursor has advanced beyond its first position.

### Siehe auch

- Iterator::rewind() - Setzt den Iterator auf das erste Element zurück

# MongoDB\Driver\Cursor::setTypeMap

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization

### Beschreibung

final public function MongoDB\Driver\Cursor::setTypeMap(array `$typemap`): void

Sets the type map configuration to use when unserializing the BSON results into PHP values.

### Parameter-Liste

`typeMap` (array)

  Konfiguration der Typzuordnung.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

When iterating over the cursor, the following exceptions can also be thrown due to an incorrect type map configuration:

- Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.

### Beispiele

Beispiel #1 MongoDB\Driver\Cursor::setTypeMap() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $id = $bulk->insert(['x' => 1]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query(['_id' => $id]);
    $cursor = $manager->executeQuery('db.collection', $query);
    $cursor->setTypeMap(['root' => 'array']);

    foreach ($cursor as $document) {
        var_dump($document);
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(2) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#6 (1) {
        ["oid"]=>
        string(24) "56424fb76118fd3267180741"
      }
      ["x"]=>
      int(1)
    }

### Siehe auch

- Persisting Data

# MongoDB\Driver\Cursor::toArray

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor

### Beschreibung

final public function MongoDB\Driver\Cursor::toArray(): array

Iterates the cursor and returns its results in an array. MongoDB\Driver\Cursor::setTypeMap() may be used to control how documents are unserialized into PHP values.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array containing all results for this cursor.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Cursor::toArray() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $query = new MongoDB\Driver\Query([]);
    $cursor = $manager->executeQuery('db.collection', $query);

    var_dump($cursor->toArray());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(3) {
      [0]=>
      object(stdClass)#6 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#5 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf61"
        }
        ["x"]=>
        int(1)
      }
      [1]=>
      object(stdClass)#8 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#7 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf62"
        }
        ["x"]=>
        int(2)
      }
      [2]=>
      object(stdClass)#10 (2) {
        ["_id"]=>
        object(MongoDB\BSON\ObjectId)#9 (1) {
          ["oid"]=>
          string(24) "564259a96118fd40b41bcf63"
        }
        ["x"]=>
        int(3)
      }
    }

### Siehe auch

- MongoDB\Driver\Cursor::setTypeMap() - Sets a type map to use for BSON unserialization

# MongoDB\Driver\Cursor::valid

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::valid — Checks if the current position in the cursor is valid

### Beschreibung

public function MongoDB\Driver\Cursor::valid(): bool

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

`true` if the current cursor position is valid, `false` otherwise.

### Siehe auch

- Iterator::valid() - Prüft, ob die aktuelle Position zulässig ist

## Inhaltsverzeichnis

- MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)
- MongoDB\Driver\Cursor::current — Returns the current element
- MongoDB\Driver\Cursor::getId — Returns the ID for this cursor
- MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor
- MongoDB\Driver\Cursor::isDead — Checks if the cursor is exhausted or may have additional results
- MongoDB\Driver\Cursor::key — Returns the current result's index within the cursor
- MongoDB\Driver\Cursor::next — Advances the cursor to the next result
- MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result
- MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization
- MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor
- MongoDB\Driver\Cursor::valid — Checks if the current position in the cursor is valid

# The MongoDB\Driver\CursorId class

(mongodb >=1.0.0)

## Einführung

The MongoDB\Driver\CursorID class is a value object that represents a cursor ID. Instances of this class are returned by MongoDB\Driver\Cursor::getId().

Warnung

This class has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications have to update their usage of MongoDB\Driver\Cursor::getId() to return MongoDB\BSON\Int64 instead.

## Klassenbeschreibung

final class MongoDB\Driver\CursorId implements Serializable, Stringable {
/* Methoden */
final private function __construct()
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse wurde entfernt.
PECL mongodb 1.20.0 | This class has been deprecated and will be removed in version 2.0.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.7.0 | Implements Serializable.

# MongoDB\Driver\CursorId::__construct

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)

### Beschreibung

final private function MongoDB\Driver\CursorId::__construct()

MongoDB\Driver\CursorId objects are returned from MongoDB\Driver\Cursor::getId() and cannot be constructed directly.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor

# MongoDB\Driver\CursorId::__toString

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__toString — String representation of the cursor ID

### Beschreibung

final public function MongoDB\Driver\CursorId::__toString(): string

Returns the string representation of the cursor ID.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of the cursor ID.

### Beispiele

Beispiel #1 MongoDB\Driver\CursorId::__toString() example

    <?php

    /* In this example, we insert several documents into the collection and specify
     * a smaller batchSize to ensure that the first batch contains only a subset of
     * our results and the cursor remains open on the server. */
    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
    $query = new MongoDB\Driver\Query([], ['batchSize' => 2]);

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->insert(['x' => 2]);
    $bulk->insert(['x' => 3]);
    $manager->executeBulkWrite('db.collection', $bulk);

    $cursor = $manager->executeQuery('db.collection', $query);
    var_dump((string) $cursor->getId());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(11) "98061641158"

### Siehe auch

- MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor

## Inhaltsverzeichnis

- MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)
- MongoDB\Driver\CursorId::__toString — String representation of the cursor ID

# The MongoDB\Driver\CursorInterface interface

(mongodb >=1.6.0)

## Einführung

This interface is implemented by MongoDB\Driver\Cursor to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\Driver\CursorInterface implements Iterator {
/* Methoden */
abstract public function getId(): MongoDB\BSON\Int64
abstract public function getServer(): MongoDB\Driver\Server
abstract public function isDead(): bool
abstract public function setTypeMap(array `$typemap`): void
abstract public function toArray(): array
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | This interface now extends Iterator. Return types previously declared as tentative are now enforced.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\Driver\CursorInterface::getId

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getId — Returns the ID for this cursor

### Beschreibung

abstract public function MongoDB\Driver\CursorInterface::getId(): MongoDB\BSON\Int64

Returns the ID for this cursor, which uniquely identifies the cursor on the server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ID for this cursor.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.20.0 | Added MongoDB\BSON\Int64 to the tentative return type for this method. MongoDB\Driver\CursorId will be removed from the return type in version 2.0.

### Siehe auch

- MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor
- MongoDB\Driver\CursorId
- MongoDB\BSON\Int64

# MongoDB\Driver\CursorInterface::getServer

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getServer — Returns the server associated with this cursor

### Beschreibung

abstract public function MongoDB\Driver\CursorInterface::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server associated with this cursor. This is the server that executed the MongoDB\Driver\Query or MongoDB\Driver\Command.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the MongoDB\Driver\Server associated with this cursor.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Cursor::getServer() - Returns the server associated with this cursor
- MongoDB\Driver\Server

# MongoDB\Driver\CursorInterface::isDead

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::isDead — Checks if the cursor may have additional results

### Beschreibung

abstract public function MongoDB\Driver\CursorInterface::isDead(): bool

Checks whether the cursor may have additional results available to read. A cursor is initially "alive" but may become "dead" for any of the following reasons:

- Advancing a non-tailable cursor did not return a document
- The cursor encountered an error
- The cursor read its last batch to completion
- The cursor reached its configured limit

This is primarily useful with tailable cursors.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if additional results are not available, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Cursor::isDead() - Checks if the cursor is exhausted or may have additional results

# MongoDB\Driver\CursorInterface::setTypeMap

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::setTypeMap — Sets a type map to use for BSON unserialization

### Beschreibung

abstract public function MongoDB\Driver\CursorInterface::setTypeMap(array `$typemap`): void

Sets the type map configuration to use when unserializing the BSON results into PHP values.

### Parameter-Liste

`typeMap` (array)

  Konfiguration der Typzuordnung.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Cursor::setTypeMap() - Sets a type map to use for BSON unserialization
- Persisting Data

# MongoDB\Driver\CursorInterface::toArray

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::toArray — Returns an array containing all results for this cursor

### Beschreibung

abstract public function MongoDB\Driver\CursorInterface::toArray(): array

Iterates the cursor and returns its results in an array. MongoDB\Driver\CursorInterface::setTypeMap() may be used to control how documents are unserialized into PHP values.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array containing all results for this cursor.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Cursor::toArray() - Returns an array containing all results for this cursor
- MongoDB\Driver\CursorInterface::setTypeMap() - Sets a type map to use for BSON unserialization

## Inhaltsverzeichnis

- MongoDB\Driver\CursorInterface::getId — Returns the ID for this cursor
- MongoDB\Driver\CursorInterface::getServer — Returns the server associated with this cursor
- MongoDB\Driver\CursorInterface::isDead — Checks if the cursor may have additional results
- MongoDB\Driver\CursorInterface::setTypeMap — Sets a type map to use for BSON unserialization
- MongoDB\Driver\CursorInterface::toArray — Returns an array containing all results for this cursor

# The MongoDB\Driver\Server class

(mongodb >=1.0.0)

## Einführung

## Klassenbeschreibung

final class MongoDB\Driver\Server {
/* Konstanten */
const int TYPE_UNKNOWN = 0;
const int TYPE_STANDALONE = 1;
const int TYPE_MONGOS = 2;
const int TYPE_POSSIBLE_PRIMARY = 3;
const int TYPE_RS_PRIMARY = 4;
const int TYPE_RS_SECONDARY = 5;
const int TYPE_RS_ARBITER = 6;
const int TYPE_RS_OTHER = 7;
const int TYPE_RS_GHOST = 8;
const int TYPE_LOAD_BALANCER = 9;
/* Methoden */
final private function __construct()
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getHost(): string
final public function getInfo(): array
final public function getLatency(): ?integer
final public function getPort(): int
final public function getServerDescription(): MongoDB\Driver\ServerDescription
final public function getTags(): array
final public function getType(): int
final public function isArbiter(): bool
final public function isHidden(): bool
final public function isPassive(): bool
final public function isPrimary(): bool
final public function isSecondary(): bool
}

## Vordefinierte Konstanten

`MongoDB\Driver\Server::TYPE_UNKNOWN`
  Unknown server type, returned by MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_STANDALONE`
  Standalone server type, returned by MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_MONGOS`
  Mongos server type, returned by MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_POSSIBLE_PRIMARY`
  Replica set possible primary server type, returned by MongoDB\Driver\Server::getType(). A server may be identified as a possible primary if it has not yet been checked but another member of the replica set thinks it is the primary.
`MongoDB\Driver\Server::TYPE_RS_PRIMARY`
  Replica set primary server type, returned by MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_SECONDARY`
  Replica set secondary server type, returned by MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_ARBITER`
  Replica set arbiter server type, returned by MongoDB\Driver\Server::getType().
`MongoDB\Driver\Server::TYPE_RS_OTHER`
  Replica set other server type, returned by MongoDB\Driver\Server::getType(). Such servers may be hidden, starting up, or recovering. They cannot be queried, but their hosts lists are useful for discovering the current replica set configuration.
`MongoDB\Driver\Server::TYPE_RS_GHOST`
  Replica set ghost server type, returned by MongoDB\Driver\Server::getType(). Servers may be identified as such in at least three situations: briefly during server startup; in an uninitialized replica set; or when the server is shunned (i.e. removed from the replica set config). They cannot be queried, nor can their host list be used to discover the current replica set configuration; however, the client may monitor this server in hope that it transitions to a more useful state.
`MongoDB\Driver\Server::TYPE_LOAD_BALANCER`
  Load balancer server type, returned by MongoDB\Driver\Server::getType().

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.11.0 | Added the `MongoDB\Driver\Server::TYPE_LOAD_BALANCER` constant.

# MongoDB\Driver\Server::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Server::__construct — Create a new Server (not used)

### Beschreibung

final private function MongoDB\Driver\Server::__construct()

MongoDB\Driver\Server objects are created internally by MongoDB\Driver\Manager when a database connection is established and may be returned by MongoDB\Driver\Manager::getServers() and MongoDB\Driver\Manager::selectServer().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- MongoDB\Driver\Manager::getServers() - Return the servers to which this manager is connected
- MongoDB\Driver\Manager::selectServer() - Select a server matching a read preference

# MongoDB\Driver\Server::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeBulkWrite — Execute one or more write operations on this server

### Beschreibung

final public function MongoDB\Driver\Server::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult

Executes one or more write operations on this server.

A MongoDB\Driver\BulkWrite can be constructed with one or more write operations of varying types (e.g. updates, deletes, and inserts). The driver will attempt to send operations of the same type to the server in as few requests as possible to optimize round trips.

The default value for the `"writeConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`bulk` (MongoDB\Driver\BulkWrite)

  Die auszuführenden Schreibvorgänge.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

### Rückgabewerte

Gibt bei Erfolg ein MongoDB\Driver\WriteResult zurück.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if `bulk` does not contain any write operations.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `bulk` has already been executed. MongoDB\Driver\BulkWrite objects may not be executed multiple times.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Wirft eine MongoDB\Driver\Exception\BulkWriteException, wenn ein Schreibvorgang fehlschlägt (z. B. wegen eines Schreibfehlers oder eines Fehlers bei der Anwendung einer Schreibanweisung).
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\WriteConcern instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\WriteConcern object as `options` is deprecated and will be removed in 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the `"session"` option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an `options` array. For backwards compatibility, this parameter will still accept a MongoDB\Driver\WriteConcern object.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException is now thrown if `bulk` does not contain any write operations. Previously, a MongoDB\Driver\Exception\BulkWriteException was thrown.

### Anmerkungen

> Hinweis: Es liegt in der Verantwortung des aufrufenden Codes, sicherzustellen, dass der Server in der Lage ist, den Schreibvorgang auszuführen. So schlägt beispielsweise die Ausführung eines Schreibvorgangs auf einem sekundären Server (mit Ausnahme seiner "lokalen" Datenbank) fehl.

### Siehe auch

- MongoDB\Driver\BulkWrite
- MongoDB\Driver\WriteResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations

# MongoDB\Driver\Server::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Server::executeBulkWriteCommand — Execute write operations on this server using the bulkWrite command

### Beschreibung

final public function MongoDB\Driver\Server::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Executes one or more write operations on this server using the » bulkWrite command introduced in MongoDB 8.0.

A MongoDB\Driver\BulkWriteCommand can be constructed with one or more write operations of varying types (e.g. inserts, updates, and deletes). Each write operation may target a different collection.

The default value for the `"writeConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### Parameter-Liste

`bulk` (MongoDB\Driver\BulkWriteCommand)

  Die auszuführenden Schreibvorgänge.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

### Rückgabewerte

Gibt bei Erfolg ein MongoDB\Driver\BulkWriteCommandResult zurück.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if `bulk` does not contain any write operations.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `bulk` has already been executed. MongoDB\Driver\BulkWriteCommand objects may not be executed multiple times.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Wirft eine MongoDB\Driver\Exception\BulkWriteCommandException, wenn ein Schreibvorgang fehlschlägt (z. B. fehlgeschlagener Befehl, Fehler beim Schreiben oder bei der Schreibanweisung)
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### Siehe auch

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command

# MongoDB\Driver\Server::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeCommand — Execute a database command on this server

### Beschreibung

final public function MongoDB\Driver\Server::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executes the command on this server.

This method applies no special logic to the command. The Default values for the `"readPreference"`, `"readConcern"`, and `"writeConcern"` options will be inferred from an active transaction (indicated by the `"session"` option). If there is no active transaction, a primary read preference will be used for server selection.

Default values will not be inferred from the connection URI. Users are therefore encouraged to use specific read and/or write command methods if possible.

> Hinweis: Die Option `"readPreference"` steuert nicht den Server, an den der Treiber die Operation ausgibt; sie wird immer auf diesem Serverobjekt ausgeführt. Stattdessen kann sie verwendet werden, wenn die Operation an einen sekundären Knoten (von einer Replikatsatzverbindung, keinen eigenständigen) oder einen Mongos-Knoten ausgegeben wird, um sicherzustellen, dass der Treiber das Übertragungsprotokoll entsprechend einstellt bzw. die Lesepräferenz zur Operation hinzufügt.

### Parameter-Liste

`db` (string)

  The name of the database on which to execute the command.

`command` (MongoDB\Driver\Command)

  Der auszuführende Befehl.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Ein Leseanliegen (Read Concern), das auf den Vorgang angewendet werden soll. Diese Option ist ab MongoDB 3.2 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  readPreference | MongoDB\Driver\ReadPreference | Eine Lesepräferenz, die verwendet wird, um einen Server für die Operation auszuwählen.
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

  Warnung

  If you are using a `"session"` which has a transaction in progress, you cannot specify a `"readConcern"` or `"writeConcern"` option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` mit einer zugehörigen Transaktion in Kombination mit einer der Optionen `"readConcern"` oder `"writeConcern"` verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command, issuing a write command to a secondary).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\ReadPreference instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\ReadPreference object as `options` is deprecated and will be removed in 2.0.
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the `"session"` option is used in combination with an unacknowledged write concern.
PECL mongodb 1.4.0 | The third parameter is now an `options` array. For backwards compatibility, this parameter will still accept a MongoDB\Driver\ReadPreference object.

### Anmerkungen

> Hinweis: Es liegt in der Verantwortung des aufrufenden Codes, sicherzustellen, dass der Server in der Lage ist, den Schreibvorgang auszuführen. So schlägt beispielsweise die Ausführung eines Schreibvorgangs auf einem sekundären Server (mit Ausnahme seiner "lokalen" Datenbank) fehl.

### Siehe auch

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeReadCommand() - Execute a database command that reads on this server
- MongoDB\Driver\Server::executeReadWriteCommand() - Execute a database command that reads and writes on this server
- MongoDB\Driver\Server::executeWriteCommand() - Execute a database command that writes on this server
- MongoDB\Driver\Manager::executeCommand() - Execute a database command

# MongoDB\Driver\Server::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeQuery — Execute a database query on this server

### Beschreibung

final public function MongoDB\Driver\Server::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executes the query on this server.

Default values for the `"readPreference"` option and Query's `"readConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

> Hinweis: Die Option `"readPreference"` steuert nicht den Server, an den der Treiber die Operation ausgibt; sie wird immer auf diesem Serverobjekt ausgeführt. Stattdessen kann sie verwendet werden, wenn die Operation an einen sekundären Knoten (von einer Replikatsatzverbindung, keinen eigenständigen) oder einen Mongos-Knoten ausgegeben wird, um sicherzustellen, dass der Treiber das Übertragungsprotokoll entsprechend einstellt bzw. die Lesepräferenz zur Operation hinzufügt.

### Parameter-Liste

`namespace` (string)

  A fully qualified namespace (e.g. `"databaseName.collectionName"`).

`query` (MongoDB\Driver\Query)

  Die auszuführende Abfrage.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  readPreference | MongoDB\Driver\ReadPreference | Eine Lesepräferenz, die verwendet wird, um einen Server für die Operation auszuwählen.
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid query operators).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\ReadPreference instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\ReadPreference object as `options` is deprecated and will be removed in 2.0.
PECL mongodb 1.4.0 | The third parameter is now an `options` array. For backwards compatibility, this parameter will still accept a MongoDB\Driver\ReadPreference object.

### Siehe auch

- MongoDB\Driver\Cursor
- MongoDB\Driver\Query
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\Manager::executeQuery() - Execute a database query

# MongoDB\Driver\Server::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadCommand — Execute a database command that reads on this server

### Beschreibung

final public function MongoDB\Driver\Server::executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executes the command on this server, irrespective of the `"readPreference"` option.

This method will apply logic that is specific to commands that read (e.g. » distinct). Default values for the `"readPreference"` and `"readConcern"` options will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

> Hinweis: Die Option `"readPreference"` steuert nicht den Server, an den der Treiber die Operation ausgibt; sie wird immer auf diesem Serverobjekt ausgeführt. Stattdessen kann sie verwendet werden, wenn die Operation an einen sekundären Knoten (von einer Replikatsatzverbindung, keinen eigenständigen) oder einen Mongos-Knoten ausgegeben wird, um sicherzustellen, dass der Treiber das Übertragungsprotokoll entsprechend einstellt bzw. die Lesepräferenz zur Operation hinzufügt.

### Parameter-Liste

`db` (string)

  The name of the database on which to execute the command.

`command` (MongoDB\Driver\Command)

  Der auszuführende Befehl.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Ein Leseanliegen (Read Concern), das auf den Vorgang angewendet werden soll. Diese Option ist ab MongoDB 3.2 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  readPreference | MongoDB\Driver\ReadPreference | Eine Lesepräferenz, die verwendet wird, um einen Server für die Operation auszuwählen.
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.

  Warnung

  If you are using a `"session"` which has a transaction in progress, you cannot specify a `"readConcern"` or `"writeConcern"` option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` mit einer zugehörigen Transaktion in Kombination mit einer der Optionen `"readConcern"` oder `"writeConcern"` verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### Siehe auch

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Execute a database command on this server
- MongoDB\Driver\Server::executeReadWriteCommand() - Execute a database command that reads and writes on this server
- MongoDB\Driver\Server::executeWriteCommand() - Execute a database command that writes on this server
- MongoDB\Driver\Manager::executeReadCommand() - Execute a database command that reads

# MongoDB\Driver\Server::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadWriteCommand — Execute a database command that reads and writes on this server

### Beschreibung

final public function MongoDB\Driver\Server::executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executes the command on this server.

This method will apply logic that is specific to commands that read and write (e.g. » aggregate). Default values for the `"readConcern"` and `"writeConcern"` options will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### Parameter-Liste

`db` (string)

  The name of the database on which to execute the command.

`command` (MongoDB\Driver\Command)

  Der auszuführende Befehl.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  readConcern | MongoDB\Driver\ReadConcern | Ein Leseanliegen (Read Concern), das auf den Vorgang angewendet werden soll. Diese Option ist ab MongoDB 3.2 verfügbar. Wenn sie für eine ältere Serverversion angegeben wird, kommt es bei der Ausführung zu einer Exception.
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

  Warnung

  If you are using a `"session"` which has a transaction in progress, you cannot specify a `"readConcern"` or `"writeConcern"` option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` mit einer zugehörigen Transaktion in Kombination mit einer der Optionen `"readConcern"` oder `"writeConcern"` verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the `"session"` option is used in combination with an unacknowledged write concern.

### Anmerkungen

> Hinweis: Es liegt in der Verantwortung des aufrufenden Codes, sicherzustellen, dass der Server in der Lage ist, den Schreibvorgang auszuführen. So schlägt beispielsweise die Ausführung eines Schreibvorgangs auf einem sekundären Server (mit Ausnahme seiner "lokalen" Datenbank) fehl.

### Siehe auch

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Execute a database command on this server
- MongoDB\Driver\Server::executeReadCommand() - Execute a database command that reads on this server
- MongoDB\Driver\Server::executeWriteCommand() - Execute a database command that writes on this server
- MongoDB\Driver\Manager::executeReadWriteCommand() - Execute a database command that reads and writes

# MongoDB\Driver\Server::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeWriteCommand — Execute a database command that writes on this server

### Beschreibung

final public function MongoDB\Driver\Server::executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor

Executes the command on this server.

This method will apply logic that is specific to commands that write (e.g. » drop). The default value for the `"writeConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

> Hinweis: This method is not intended to be used to execute » insert, » update, or » delete commands. Users are encouraged to use MongoDB\Driver\Server::executeBulkWrite() for those operations.

### Parameter-Liste

`db` (string)

  The name of the database on which to execute the command.

`command` (MongoDB\Driver\Command)

  Der auszuführende Befehl.

`options`

  options
  Option | Type | Description
  --- | --- | ---
  session | MongoDB\Driver\Session | Eine Session, die mit dem Vorgang verknüpft werden soll.
  writeConcern | MongoDB\Driver\WriteConcern | Eine Schreibanweisung (Write Concern), das auf den Vorgang angewendet werden soll.

  Warnung

  If you are using a `"session"` which has a transaction in progress, you cannot specify a `"readConcern"` or `"writeConcern"` option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction().

### Rückgabewerte

Gibt bei Erfolg einen MongoDB\Driver\Cursor zurück.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` mit einer zugehörigen Transaktion in Kombination mit einer der Optionen `"readConcern"` oder `"writeConcern"` verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn die Option `"session"` in Kombination mit einer unbestätigten Schreibanweisung verwendet wird.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Wirft eine MongoDB\Driver\Exception\ConnectionException, wenn der Aufbau einer Verbindung zum Server fehlschlägt (aus einem anderen Grund als der Authentifizierung).
- Wirft eine MongoDB\Driver\Exception\AuthenticationException, wenn eine Authentifizierung erforderlich ist und fehlschlägt.
- Throws MongoDB\Driver\Exception\RuntimeException on other errors (e.g. invalid command).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.4.4 | MongoDB\Driver\Exception\InvalidArgumentException will be thrown if the `"session"` option is used in combination with an unacknowledged write concern.

### Anmerkungen

> Hinweis: Es liegt in der Verantwortung des aufrufenden Codes, sicherzustellen, dass der Server in der Lage ist, den Schreibvorgang auszuführen. So schlägt beispielsweise die Ausführung eines Schreibvorgangs auf einem sekundären Server (mit Ausnahme seiner "lokalen" Datenbank) fehl.

### Siehe auch

- MongoDB\Driver\Command
- MongoDB\Driver\Cursor
- MongoDB\Driver\Server::executeCommand() - Execute a database command on this server
- MongoDB\Driver\Server::executeReadCommand() - Execute a database command that reads on this server
- MongoDB\Driver\Server::executeReadWriteCommand() - Execute a database command that reads and writes on this server
- MongoDB\Driver\Manager::executeWriteCommand() - Execute a database command that writes

# MongoDB\Driver\Server::getHost

(mongodb >=1.0.0)

MongoDB\Driver\Server::getHost — Returns the hostname of this server

### Beschreibung

final public function MongoDB\Driver\Server::getHost(): string

Returns the hostname of this server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of this server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Server::getHost() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getHost());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(9) "localhost"

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
- MongoDB\Driver\ServerDescription::getHost() - Returns the hostname of this server

# MongoDB\Driver\Server::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\Server::getInfo — Returns an array of information describing this server

### Beschreibung

final public function MongoDB\Driver\Server::getInfo(): array

Returns an array of information describing the server. This array is derived from the most recent » hello command response obtained through » server monitoring.

> Hinweis: When the driver is connected to a load balancer, this method will return the backing server's » hello command response from the initial connection handshake. This is in contrast to other methods (e.g. MongoDB\Driver\Server::getType()), which will return information about the load balancer itself.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of information describing this server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Server::getInfo() example

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost:27017/');

    $rp = new MongoDB\Driver\ReadPreference('primary');
    $server = $manager->selectServer($rp);

    var_dump($server->getInfo());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(23) {
      ["helloOk"]=>
      bool(true)
      ["topologyVersion"]=>
      array(2) {
        ["processId"]=>
        object(MongoDB\BSON\ObjectId)#4 (1) {
          ["oid"]=>
          string(24) "617b6d696a3a89d2f77e6df0"
        }
        ["counter"]=>
        int(6)
      }
      ["hosts"]=>
      array(1) {
        [0]=>
        string(15) "localhost:27017"
      }
      ["setName"]=>
      string(3) "rs0"
      ["setVersion"]=>
      int(1)
      ["ismaster"]=>
      bool(true)
      ["secondary"]=>
      bool(false)
      ["primary"]=>
      string(15) "localhost:27017"
      ["me"]=>
      string(15) "localhost:27017"
      ["electionId"]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "7fffffff0000000000000001"
      }
      ["lastWrite"]=>
      array(4) {
        ["opTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#6 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["lastWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#7 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
        ["majorityOpTime"]=>
        array(2) {
          ["ts"]=>
          object(MongoDB\BSON\Timestamp)#8 (2) {
            ["increment"]=>
            string(1) "1"
            ["timestamp"]=>
            string(10) "1635478989"
          }
          ["t"]=>
          int(1)
        }
        ["majorityWriteDate"]=>
        object(MongoDB\BSON\UTCDateTime)#9 (1) {
          ["milliseconds"]=>
          string(13) "1635478989000"
        }
      }
      ["maxBsonObjectSize"]=>
      int(16777216)
      ["maxMessageSizeBytes"]=>
      int(48000000)
      ["maxWriteBatchSize"]=>
      int(100000)
      ["localTime"]=>
      object(MongoDB\BSON\UTCDateTime)#10 (1) {
        ["milliseconds"]=>
        string(13) "1635478992136"
      }
      ["logicalSessionTimeoutMinutes"]=>
      int(30)
      ["connectionId"]=>
      int(3)
      ["minWireVersion"]=>
      int(0)
      ["maxWireVersion"]=>
      int(13)
      ["readOnly"]=>
      bool(false)
      ["ok"]=>
      float(1)
      ["$clusterTime"]=>
      array(2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#11 (2) {
          ["increment"]=>
          string(1) "1"
          ["timestamp"]=>
          string(10) "1635478989"
        }
        ["signature"]=>
        array(2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#12 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          int(0)
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#13 (2) {
        ["increment"]=>
        string(1) "1"
        ["timestamp"]=>
        string(10) "1635478989"
      }
    }

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.11.0 | When the driver is connected to a load balancer, this method returns the backing server's `hello` command response from the initial connection handshake.

### Siehe auch

- MongoDB\Driver\ServerDescription::getHelloResponse() - Returns the server's most recent "hello" response
- » hello command in the MongoDB manual
- » Server Discovery and Monitoring Specification

# MongoDB\Driver\Server::getLatency

(mongodb >=1.0.0)

MongoDB\Driver\Server::getLatency — Returns the latency of this server in milliseconds

### Beschreibung

final public function MongoDB\Driver\Server::getLatency(): ?integer

Returns the latency of this server in milliseconds. This is the client's measured » round trip time of a `hello` command.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the latency of this server in milliseconds, or `null` if no latency has been measured (e.g. client is connected to a load balancer).

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.11.0 | This method will return `null` if no latency has been measured. In earlier versions, an integer was always returned and an unset value might be reported as `-1`.

### Beispiele

Beispiel #1 MongoDB\Driver\Server::getLatency() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getLatency());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(592)

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
- MongoDB\Driver\ServerDescription::getRoundTripTime() - Returns the server's round trip time in milliseconds
- » Server Discovery and Monitoring Specification

# MongoDB\Driver\Server::getPort

(mongodb >=1.0.0)

MongoDB\Driver\Server::getPort — Returns the port on which this server is listening

### Beschreibung

final public function MongoDB\Driver\Server::getPort(): int

Returns the port on which this server is listening.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port on which this server is listening.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\Server::getPort() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://localhost:27017/");
    $server = $manager->selectServer();

    var_dump($server->getPort());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(27017)

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
- MongoDB\Driver\ServerDescription::getPort() - Returns the port on which this server is listening

# MongoDB\Driver\Server::getServerDescription

(mongodb >=1.13.0)

MongoDB\Driver\Server::getServerDescription — Returns a ServerDescription for this server

### Beschreibung

final public function MongoDB\Driver\Server::getServerDescription(): MongoDB\Driver\ServerDescription

Returns a MongoDB\Driver\ServerDescription for this server. This is an immutable value object that will describe the server at the time this method is called.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a MongoDB\Driver\ServerDescription for this server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Server::getTags

(mongodb >=1.0.0)

MongoDB\Driver\Server::getTags — Returns an array of tags describing this server in a replica set

### Beschreibung

final public function MongoDB\Driver\Server::getTags(): array

Returns an array of » tags used to describe this server in a replica set. The array will contain zero or more string key and value pairs.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of tags used to describe this server in a replica set.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server

# MongoDB\Driver\Server::getType

(mongodb >=1.0.0)

MongoDB\Driver\Server::getType — Returns an integer denoting the type of this server

### Beschreibung

final public function MongoDB\Driver\Server::getType(): int

Returns an int denoting the type of this server. The value will correlate with a MongoDB\Driver\Server constant.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an int denoting the type of this server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
- MongoDB\Driver\ServerDescription::getType() - Returns a string denoting the type of this server

# MongoDB\Driver\Server::isArbiter

(mongodb >=1.0.0)

MongoDB\Driver\Server::isArbiter — Checks if this server is an arbiter member of a replica set

### Beschreibung

final public function MongoDB\Driver\Server::isArbiter(): bool

Returns whether this server is an » arbiter member of a replica set.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if this server is an arbiter member of a replica set, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server

# MongoDB\Driver\Server::isHidden

(mongodb >=1.0.0)

MongoDB\Driver\Server::isHidden — Checks if this server is a hidden member of a replica set

### Beschreibung

final public function MongoDB\Driver\Server::isHidden(): bool

Returns whether this server is a » hidden member of a replica set.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if this server is a hidden member of a replica set, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server

# MongoDB\Driver\Server::isPassive

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPassive — Checks if this server is a passive member of a replica set

### Beschreibung

final public function MongoDB\Driver\Server::isPassive(): bool

Returns whether this server is a » passive member of a replica set (i.e. its priority is `0`).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if this server is a passive member of a replica set, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server

# MongoDB\Driver\Server::isPrimary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isPrimary — Checks if this server is a primary member of a replica set

### Beschreibung

final public function MongoDB\Driver\Server::isPrimary(): bool

Returns whether this server is a » primary member of a replica set.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if this server is a primary member of a replica set, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server

# MongoDB\Driver\Server::isSecondary

(mongodb >=1.0.0)

MongoDB\Driver\Server::isSecondary — Checks if this server is a secondary member of a replica set

### Beschreibung

final public function MongoDB\Driver\Server::isSecondary(): bool

Returns whether this server is a » secondary member of a replica set.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if this server is a secondary member of a replica set, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server

## Inhaltsverzeichnis

- MongoDB\Driver\Server::__construct — Create a new Server (not used)
- MongoDB\Driver\Server::executeBulkWrite — Execute one or more write operations on this server
- MongoDB\Driver\Server::executeBulkWriteCommand — Execute write operations on this server using the bulkWrite command
- MongoDB\Driver\Server::executeCommand — Execute a database command on this server
- MongoDB\Driver\Server::executeQuery — Execute a database query on this server
- MongoDB\Driver\Server::executeReadCommand — Execute a database command that reads on this server
- MongoDB\Driver\Server::executeReadWriteCommand — Execute a database command that reads and writes on this server
- MongoDB\Driver\Server::executeWriteCommand — Execute a database command that writes on this server
- MongoDB\Driver\Server::getHost — Returns the hostname of this server
- MongoDB\Driver\Server::getInfo — Returns an array of information describing this server
- MongoDB\Driver\Server::getLatency — Returns the latency of this server in milliseconds
- MongoDB\Driver\Server::getPort — Returns the port on which this server is listening
- MongoDB\Driver\Server::getServerDescription — Returns a ServerDescription for this server
- MongoDB\Driver\Server::getTags — Returns an array of tags describing this server in a replica set
- MongoDB\Driver\Server::getType — Returns an integer denoting the type of this server
- MongoDB\Driver\Server::isArbiter — Checks if this server is an arbiter member of a replica set
- MongoDB\Driver\Server::isHidden — Checks if this server is a hidden member of a replica set
- MongoDB\Driver\Server::isPassive — Checks if this server is a passive member of a replica set
- MongoDB\Driver\Server::isPrimary — Checks if this server is a primary member of a replica set
- MongoDB\Driver\Server::isSecondary — Checks if this server is a secondary member of a replica set

# The MongoDB\Driver\ServerDescription class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\ServerDescription class is a value object that represents a server to which the driver is connected. Instances of this class are returned by MongoDB\Driver\Server::getServerDescription() and MongoDB\Driver\Monitoring\ServerChangedEvent methods.

## Klassenbeschreibung

final class MongoDB\Driver\ServerDescription {
/* Konstanten */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_STANDALONE = "Standalone";
const string TYPE_MONGOS = "Mongos";
const string TYPE_POSSIBLE_PRIMARY = "PossiblePrimary";
const string TYPE_RS_PRIMARY = "RSPrimary";
const string TYPE_RS_SECONDARY = "RSSecondary";
const string TYPE_RS_ARBITER = "RSArbiter";
const string TYPE_RS_OTHER = "RSOther";
const string TYPE_RS_GHOST = "RSGhost";
const string TYPE_LOAD_BALANCER = "LoadBalancer";
/* Methoden */
final public function getHelloResponse(): array
final public function getHost(): string
final public function getLastUpdateTime(): int
final public function getPort(): int
final public function getRoundTripTime(): ?int
final public function getType(): string
}

## Vordefinierte Konstanten

`MongoDB\Driver\ServerDescription::TYPE_UNKNOWN`
  Unknown server type, returned by MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_STANDALONE`
  Standalone server type, returned by MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_MONGOS`
  Mongos server type, returned by MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_POSSIBLE_PRIMARY`
  Replica set possible primary server type, returned by MongoDB\Driver\ServerDescription::getType(). A server may be identified as a possible primary if it has not yet been checked but another memory of the replica set thinks it is the primary.
`MongoDB\Driver\ServerDescription::TYPE_RS_PRIMARY`
  Replica set primary server type, returned by MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_SECONDARY`
  Replica set secondary server type, returned by MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_ARBITER`
  Replica set arbiter server type, returned by MongoDB\Driver\ServerDescription::getType().
`MongoDB\Driver\ServerDescription::TYPE_RS_OTHER`
  Replica set other server type, returned by MongoDB\Driver\ServerDescription::getType(). Such servers may be hidden, starting up, or recovering. They cannot be queried, but their hosts lists are useful for discovering the current replica set configuration.
`MongoDB\Driver\ServerDescription::TYPE_RS_GHOST`
  Replica set ghost server type, returned by MongoDB\Driver\ServerDescription::getType(). Servers may be identified as such in at least three situations: briefly during server startup; in an uninitialized replica set; or when the server is shunned (i.e. removed from the replica set config). They cannot be queried, nor can their host list be used to discover the current replica set configuration; however, the client may monitor this server in hope that it transitions to a more useful state.
`MongoDB\Driver\ServerDescription::TYPE_LOAD_BALANCER`
  Load balancer server type, returned by MongoDB\Driver\ServerDescription::getType().

# MongoDB\Driver\ServerDescription::getHelloResponse

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHelloResponse — Returns the server's most recent "hello" response

### Beschreibung

final public function MongoDB\Driver\ServerDescription::getHelloResponse(): array

Returns an array of information describing the server. This array is derived from the most recent (at the time the MongoDB\Driver\ServerDescription was constructed) » hello command response obtained through » server monitoring.

> Hinweis: When the driver is connected to a load balancer, this method will return an empty array since load balancers are not monitored. This is in contrast to MongoDB\Driver\Server::getInfo(), which would return the backing server's » hello command response from the initial connection handshake.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of information describing this server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getInfo() - Returns an array of information describing this server
- » hello command in the MongoDB manual
- » Server Discovery and Monitoring Specification

# MongoDB\Driver\ServerDescription::getHost

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHost — Returns the hostname of this server

### Beschreibung

final public function MongoDB\Driver\ServerDescription::getHost(): string

Returns the hostname of this server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of this server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getHost() - Returns the hostname of this server

# MongoDB\Driver\ServerDescription::getLastUpdateTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getLastUpdateTime — Returns the server's last update time in microseconds

### Beschreibung

final public function MongoDB\Driver\ServerDescription::getLastUpdateTime(): int

Returns the server's last update time in microseconds.

> Hinweis: The returned value is a monotonic timestamp, which starts at an arbitrary point. As such, it is only suitable to compare with other return values from MongoDB\Driver\ServerDescription::getLastUpdateTime().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the server's last update time in microseconds.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\ServerDescription::getPort

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getPort — Returns the port on which this server is listening

### Beschreibung

final public function MongoDB\Driver\ServerDescription::getPort(): int

Returns the port on which this server is listening.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port on which this server is listening.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getPort() - Returns the port on which this server is listening

# MongoDB\Driver\ServerDescription::getRoundTripTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getRoundTripTime — Returns the server's round trip time in milliseconds

### Beschreibung

final public function MongoDB\Driver\ServerDescription::getRoundTripTime(): ?int

Returns the server's round trip time in milliseconds. This is the client's measurement of the duration of a » hello command.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the server's round trip time in milliseconds.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getLatency() - Returns the latency of this server in milliseconds

# MongoDB\Driver\ServerDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getType — Returns a string denoting the type of this server

### Beschreibung

final public function MongoDB\Driver\ServerDescription::getType(): string

Returns a string denoting the type of this server. The value will correlate with a MongoDB\Driver\ServerDescription constant.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string denoting the type of this server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Server::getType() - Returns an integer denoting the type of this server

## Inhaltsverzeichnis

- MongoDB\Driver\ServerDescription::getHelloResponse — Returns the server's most recent "hello" response
- MongoDB\Driver\ServerDescription::getHost — Returns the hostname of this server
- MongoDB\Driver\ServerDescription::getLastUpdateTime — Returns the server's last update time in microseconds
- MongoDB\Driver\ServerDescription::getPort — Returns the port on which this server is listening
- MongoDB\Driver\ServerDescription::getRoundTripTime — Returns the server's round trip time in milliseconds
- MongoDB\Driver\ServerDescription::getType — Returns a string denoting the type of this server

# The MongoDB\Driver\TopologyDescription class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\TopologyDescription class is a value object that represents a topology to which the driver is connected. Instances of this class are returned by MongoDB\Driver\Monitoring\TopologyChangedEvent methods.

## Klassenbeschreibung

final class MongoDB\Driver\TopologyDescription {
/* Konstanten */
const string TYPE_UNKNOWN = "Unknown";
const string TYPE_SINGLE = "Single";
const string TYPE_SHARDED = "Sharded";
const string TYPE_REPLICA_SET_NO_PRIMARY = "ReplicaSetNoPrimary";
const string TYPE_REPLICA_SET_WITH_PRIMARY = "ReplicaSetWithPrimary";
const string TYPE_LOAD_BALANCED = "LoadBalanced";
/* Methoden */
final public function getServers(): array
final public function getType(): string
final public function hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool
final public function hasWritableServer(): bool
}

## Vordefinierte Konstanten

`MongoDB\Driver\TopologyDescription::TYPE_UNKNOWN`
  Unknown topology type, returned by MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SINGLE`
  Single server (i.e. direct connection), returned by MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_SHARDED`
  Sharded cluster, returned by MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_NO_PRIMARY`
  Replica set with no primary server, returned by MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_REPLICA_SET_WITH_PRIMARY`
  Replica set with a primary server, returned by MongoDB\Driver\TopologyDescription::getType().
`MongoDB\Driver\TopologyDescription::TYPE_LOAD_BALANCED`
  Load balanced topology, returned by MongoDB\Driver\TopologyDescription::getType().

# MongoDB\Driver\TopologyDescription::getServers

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getServers — Returns the servers in the topology

### Beschreibung

final public function MongoDB\Driver\TopologyDescription::getServers(): array

Returns an array of MongoDB\Driver\ServerDescription objects corresponding to the known servers in the topology.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of MongoDB\Driver\ServerDescription objects corresponding to the known servers in the topology.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\TopologyDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getType — Returns a string denoting the type of this topology

### Beschreibung

final public function MongoDB\Driver\TopologyDescription::getType(): string

Returns a string denoting the type of this topology. The value will correlate with a MongoDB\Driver\TopologyDescription constant.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string denoting the type of this topology.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\TopologyDescription::hasReadableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasReadableServer — Returns whether the topology has a readable server

### Beschreibung

final public function MongoDB\Driver\TopologyDescription::hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool

Returns whether the topology has a readable server or, if `readPreference` is specified, a server matching the specified read preference.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns whether the topology has a readable server or, if `readPreference` is specified, a server matching the specified read preference.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\TopologyDescription::hasWritableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasWritableServer — Returns whether the topology has a writable server

### Beschreibung

final public function MongoDB\Driver\TopologyDescription::hasWritableServer(): bool

Returns whether the topology has a writable server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns whether the topology has a writable server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\TopologyDescription::getServers — Returns the servers in the topology
- MongoDB\Driver\TopologyDescription::getType — Returns a string denoting the type of this topology
- MongoDB\Driver\TopologyDescription::hasReadableServer — Returns whether the topology has a readable server
- MongoDB\Driver\TopologyDescription::hasWritableServer — Returns whether the topology has a writable server

# The MongoDB\Driver\WriteConcernError class

(mongodb >=1.0.0)

## Einführung

The MongoDB\Driver\WriteConcernError class encapsulates information about a write concern error and may be returned by MongoDB\Driver\WriteResult::getWriteConcernError().

## Klassenbeschreibung

final class MongoDB\Driver\WriteConcernError {
/* Eigenschaften */
public readonly string $message;
public readonly int $code;
public readonly ?object $info;
/* Methoden */
final public function getCode(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Eigenschaften

message
  The error message.
code
  The error code.
info
  Additional information for the error, or `null` if not available.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\WriteConcernError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getCode — Returns the WriteConcernError's error code

### Beschreibung

final public function MongoDB\Driver\WriteConcernError::getCode(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the WriteConcernError's error code.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteConcernError::getCode() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getCode());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(64)

### Siehe auch

- » Write Concern reference

# MongoDB\Driver\WriteConcernError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError

### Beschreibung

final public function MongoDB\Driver\WriteConcernError::getInfo(): ?object

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the metadata document for the WriteConcernError, or `null` if no metadata is available.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteConcernError::getInfo() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getInfo());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#1 (1) {
      ["wtimeout"]=>
      bool(true)
    }

### Siehe auch

- » Write Concern reference

# MongoDB\Driver\WriteConcernError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message

### Beschreibung

final public function MongoDB\Driver\WriteConcernError::getMessage(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the WriteConcernError's error message.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteConcernError::getMessage() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getMessage());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(33) "waiting for replication timed out"

### Siehe auch

- » Write Concern reference

## Inhaltsverzeichnis

- MongoDB\Driver\WriteConcernError::getCode — Returns the WriteConcernError's error code
- MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError
- MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message

# The MongoDB\Driver\WriteError class

(mongodb >=1.0.0)

## Einführung

The MongoDB\Driver\WriteError class encapsulates information about a write error and may be returned as an array element from MongoDB\Driver\WriteResult::getWriteErrors().

## Klassenbeschreibung

final class MongoDB\Driver\WriteError {
/* Eigenschaften */
public readonly string $message;
public readonly int $code;
public readonly int $index;
public readonly ?object $info;
/* Methoden */
final public function getCode(): int
final public function getIndex(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## Eigenschaften

message
  The error message.
code
  The error code.
index
  The index of the write operation within the MongoDB\Driver\BulkWrite that caused the error.
info
  Additional information for the error, or `null` if not available.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\WriteError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getCode — Returns the WriteError's error code

### Beschreibung

final public function MongoDB\Driver\WriteError::getCode(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the WriteError's error code.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteError::getCode() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getCode());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(11000)

# MongoDB\Driver\WriteError::getIndex

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getIndex — Returns the index of the write operation corresponding to this WriteError

### Beschreibung

final public function MongoDB\Driver\WriteError::getIndex(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the index of the write operation (from MongoDB\Driver\BulkWrite) corresponding to this WriteError.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteError::getIndex() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getIndex());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(1)

### Siehe auch

- MongoDB\Driver\BulkWrite

# MongoDB\Driver\WriteError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError

### Beschreibung

final public function MongoDB\Driver\WriteError::getInfo(): ?object

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the metadata document for the WriteError, or `null` if no metadata is available.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\WriteError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message

### Beschreibung

final public function MongoDB\Driver\WriteError::getMessage(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the WriteError's error message.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteError::getMessage() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors()[0]->getMessage());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"

## Inhaltsverzeichnis

- MongoDB\Driver\WriteError::getCode — Returns the WriteError's error code
- MongoDB\Driver\WriteError::getIndex — Returns the index of the write operation corresponding to this WriteError
- MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError
- MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message

# The MongoDB\Driver\WriteResult class

(mongodb >=1.0.0)

## Einführung

The MongoDB\Driver\WriteResult class encapsulates information about an executed MongoDB\Driver\BulkWrite and may be returned by MongoDB\Driver\Manager::executeBulkWrite().

## Klassenbeschreibung

final class MongoDB\Driver\WriteResult {
/* Eigenschaften */
public readonly ?int $insertedCount;
public readonly ?int $matchedCount;
public readonly ?int $modifiedCount;
public readonly ?int $deletedCount;
public readonly ?int $upsertedCount;
public readonly MongoDB\Driver\Server $server;
public readonly array $upsertedIds;
public readonly array $writeErrors;
public readonly ?MongoDB\Driver\WriteConcernError $writeConcernError;
public readonly ?MongoDB\Driver\WriteConcern $writeConcern;
public readonly array $errorReplies;
/* Methoden */
final public function getDeletedCount(): int
final public function getInsertedCount(): int
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getServer(): MongoDB\Driver\Server
final public function getUpsertedCount(): int
final public function getUpsertedIds(): array
final public function getWriteConcernError(): ?MongoDB\Driver\WriteConcernError
final public function getWriteErrors(): array
final public function isAcknowledged(): bool
}

## Eigenschaften

insertedCount
  The number of documents inserted (excluding upserts), or `null` if the write concern did not request acknowledgement.
matchedCount
  The number of documents matched by update and replace operations, or `null` if the write concern did not request acknowledgement.
modifiedCount
  The number of documents modified by update and replace operations, or `null` if the write concern did not request acknowledgement or if the server did not report this information.
deletedCount
  The number of documents deleted, or `null` if the write concern did not request acknowledgement.
upsertedCount
  The number of documents upserted, or `null` if the write concern did not request acknowledgement.
server
  The server that executed the bulk write.
upsertedIds
  An array of `_id` values for upserted documents. Array keys will correspond to the index of the write operation from MongoDB\Driver\BulkWrite.
writeErrors
  An array of MongoDB\Driver\WriteErrors for any write errors that occurred during execution.
writeConcernError
  The MongoDB\Driver\WriteConcernError that occurred, or `null` if no write concern error occurred.
writeConcern
  The MongoDB\Driver\WriteConcern used for the bulk write, or `null` if not available.
errorReplies
  An array of error reply documents from the server.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\WriteResult::getDeletedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getDeletedCount — Returns the number of documents deleted

### Beschreibung

final public function MongoDB\Driver\WriteResult::getDeletedCount(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of documents deleted.

### Fehler/Exceptions

- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Methode löst nun eine Ausnahme aus, wenn sie für ein unbestätigtes Schreiben aufgerufen wird, anstatt `null` zurückzugeben.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::getDeletedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getDeletedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)

### Siehe auch

- MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\WriteResult::getInsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getInsertedCount — Returns the number of documents inserted (excluding upserts)

### Beschreibung

final public function MongoDB\Driver\WriteResult::getInsertedCount(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of documents inserted (excluding upserts).

### Fehler/Exceptions

- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Methode löst nun eine Ausnahme aus, wenn sie für ein unbestätigtes Schreiben aufgerufen wird, anstatt `null` zurückzugeben.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::getInsertedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getInsertedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)

### Siehe auch

- MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\WriteResult::getMatchedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getMatchedCount — Returns the number of documents selected for update

### Beschreibung

final public function MongoDB\Driver\WriteResult::getMatchedCount(): int

If the update operation results in no change to the document (e.g. setting the value of a field to its current value), the matched count may be greater than the value returned by MongoDB\Driver\WriteResult::getModifiedCount().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of documents selected for update.

### Fehler/Exceptions

- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Methode löst nun eine Ausnahme aus, wenn sie für ein unbestätigtes Schreiben aufgerufen wird, anstatt `null` zurückzugeben.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::getMatchedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getMatchedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)

### Siehe auch

- MongoDB\Driver\WriteResult::getModifiedCount() - Returns the number of existing documents updated
- MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\WriteResult::getModifiedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getModifiedCount — Returns the number of existing documents updated

### Beschreibung

final public function MongoDB\Driver\WriteResult::getModifiedCount(): int

If the update operation results in no change to the document (e.g. setting the value of a field to its current value), the modified count may be less than the value returned by MongoDB\Driver\WriteResult::getMatchedCount().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of existing documents updated.

### Fehler/Exceptions

- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Methode löst nun eine Ausnahme aus, wenn sie für ein unbestätigtes Schreiben aufgerufen wird, anstatt `null` zurückzugeben.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::getModifiedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getModifiedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)

### Siehe auch

- MongoDB\Driver\WriteResult::getMatchedCount() - Returns the number of documents selected for update
- MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\WriteResult::getServer

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getServer — Returns the server associated with this write result

### Beschreibung

final public function MongoDB\Driver\WriteResult::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server associated with this write result. This is the server that executed the MongoDB\Driver\BulkWrite.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the MongoDB\Driver\Server associated with this write result.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::getServer() example

    <?php

    $manager = new MongoDB\Driver\Manager;
    $server = $manager->selectServer();

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $result = $server->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getServer() == $server);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

### Siehe auch

- MongoDB\Driver\Server

# MongoDB\Driver\WriteResult::getUpsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert

### Beschreibung

final public function MongoDB\Driver\WriteResult::getUpsertedCount(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of documents inserted by an upsert.

### Fehler/Exceptions

- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Methode löst nun eine Ausnahme aus, wenn sie für ein unbestätigtes Schreiben aufgerufen wird, anstatt `null` zurückzugeben.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::getUpsertedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(2)

### Siehe auch

- MongoDB\Driver\WriteResult::getUpsertedIds() - Returns an array of identifiers for upserted documents
- MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\WriteResult::getUpsertedIds

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedIds — Returns an array of identifiers for upserted documents

### Beschreibung

final public function MongoDB\Driver\WriteResult::getUpsertedIds(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of identifiers (i.e. `"_id"` field values) for upserted documents. The array keys will correspond to the index of the write operation (from MongoDB\Driver\BulkWrite) responsible for the upsert.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::getUpsertedIds() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);
    $bulk->update(['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->update(['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->update(['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->delete(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->getUpsertedIds());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(2) {
      [2]=>
      object(MongoDB\BSON\ObjectId)#4 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880b"
      }
      [3]=>
      object(MongoDB\BSON\ObjectId)#5 (1) {
        ["oid"]=>
        string(24) "580e62a224f2302f191b880c"
      }
    }

### Siehe auch

- MongoDB\Driver\WriteResult::getUpsertedCount() - Returns the number of documents inserted by an upsert
- MongoDB\Driver\WriteResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\WriteResult::getWriteConcernError

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteConcernError — Returns any write concern error that occurred

### Beschreibung

final public function MongoDB\Driver\WriteResult::getWriteConcernError(): ?MongoDB\Driver\WriteConcernError

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a MongoDB\Driver\WriteConcernError if a write concern error was encountered during the write operation, and `null` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::getWriteConcernError() example

    <?php

    $manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(2, 1);

    try {
        $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\Driver\WriteConcernError)#6 (3) {
      ["message"]=>
      string(33) "waiting for replication timed out"
      ["code"]=>
      int(64)
      ["info"]=>
      object(stdClass)#7 (1) {
        ["wtimeout"]=>
        bool(true)
      }
    }

### Siehe auch

- MongoDB\Driver\WriteConcern
- » Write Concern reference

# MongoDB\Driver\WriteResult::getWriteErrors

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred

### Beschreibung

final public function MongoDB\Driver\WriteResult::getWriteErrors(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of MongoDB\Driver\WriteError objects for any write errors encountered during the write operation. The array will be empty if no write errors occurred.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::getWriteErrors() with a single error

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* By default, bulk write operations are executed serially in order and
     * execution will stop after the first error.
     */
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
    }

Beispiel #2 MongoDB\Driver\WriteResult::getWriteErrors() with multiple errors

    <?php

    $manager = new MongoDB\Driver\Manager;

    /* The "ordered" option may be used to allow bulk write operations to continue
     * executing after the first error is encountered.
     */
    $bulk = new MongoDB\Driver\BulkWrite(['ordered' => false]);
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 2]);
    $bulk->insert(['_id' => 3]);
    $bulk->insert(['_id' => 4]);
    $bulk->insert(['_id' => 4]);

    try {
        $result = $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteErrors());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(2) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 2 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        NULL
      }
      [1]=>
      object(MongoDB\Driver\WriteError)#6 (4) {
        ["message"]=>
        string(81) "E11000 duplicate key error collection: db.collection index: _id_ dup key: { : 4 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(5)
        ["info"]=>
        NULL
      }
    }

### Siehe auch

- MongoDB\Driver\WriteError

# MongoDB\Driver\WriteResult::isAcknowledged

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged

### Beschreibung

final public function MongoDB\Driver\WriteResult::isAcknowledged(): bool

If the write is acknowledged, other count fields will be available on the MongoDB\Driver\WriteResult object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the write was acknowledged, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\WriteResult::isAcknowledged() with acknowledged write concern

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $result = $manager->executeBulkWrite('db.collection', $bulk);

    var_dump($result->isAcknowledged());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

Beispiel #2 MongoDB\Driver\WriteResult::isAcknowledged() with unacknowledged write concern

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)

### Siehe auch

- MongoDB\Driver\WriteConcern
- » Write Concern reference

## Inhaltsverzeichnis

- MongoDB\Driver\WriteResult::getDeletedCount — Returns the number of documents deleted
- MongoDB\Driver\WriteResult::getInsertedCount — Returns the number of documents inserted (excluding upserts)
- MongoDB\Driver\WriteResult::getMatchedCount — Returns the number of documents selected for update
- MongoDB\Driver\WriteResult::getModifiedCount — Returns the number of existing documents updated
- MongoDB\Driver\WriteResult::getServer — Returns the server associated with this write result
- MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert
- MongoDB\Driver\WriteResult::getUpsertedIds — Returns an array of identifiers for upserted documents
- MongoDB\Driver\WriteResult::getWriteConcernError — Returns any write concern error that occurred
- MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred
- MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged

# The MongoDB\Driver\BulkWriteCommandResult class

(mongodb >=2.1.0)

## Einführung

The MongoDB\Driver\BulkWriteCommandResult class encapsulates information about an executed MongoDB\Driver\BulkWriteCommand and is returned by MongoDB\Driver\Manager::executeBulkWriteCommand().

## Klassenbeschreibung

final class MongoDB\Driver\BulkWriteCommandResult {
/* Methoden */
final public function getDeletedCount(): int
final public function getDeleteResults(): ?MongoDB\BSON\Document
final public function getInsertedCount(): int
final public function getInsertResults(): ?MongoDB\BSON\Document
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getUpdateResults(): ?MongoDB\BSON\Document
final public function getUpsertedCount(): int
final public function isAcknowledged(): bool
}

# MongoDB\Driver\BulkWriteCommandResult::getDeletedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Returns the number of documents deleted

### Beschreibung

final public function MongoDB\Driver\BulkWriteCommandResult::getDeletedCount(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the total number of documents deleted by all operations.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommandResult::getDeletedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeletedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(3)

### Siehe auch

- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults() - Returns verbose results for successful deletes
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getDeleteResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Returns verbose results for successful deletes

### Beschreibung

final public function MongoDB\Driver\BulkWriteCommandResult::getDeleteResults(): ?MongoDB\BSON\Document

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a document containing the result of each successful delete operation, or `null` if verbose results were not requested. The document keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommandResult::getDeleteResults() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeleteResults()->toPHP());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#7 (1) {
      ["4"]=>
      object(stdClass)#6 (1) {
        ["deletedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "3"
        }
      }
    }

### Siehe auch

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount() - Returns the number of documents deleted
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getInsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Returns the number of documents inserted

### Beschreibung

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertedCount(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the total number of documents inserted (excluding upserts) by all operations.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommandResult::getInsertedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getInsertedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)

### Siehe auch

- MongoDB\Driver\BulkWriteCommandResult::getInsertResults() - Returns verbose results for successful inserts
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getInsertResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Returns verbose results for successful inserts

### Beschreibung

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertResults(): ?MongoDB\BSON\Document

Since `_id` fields for inserted documents are generated by the extension, the value of `insertedId` in each result will match the return value of MongoDB\Driver\BulkWriteCommand::insertOne() for the corresponding insert operation.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a document containing the result of each successful insert operation, or `null` if verbose results were not requested. The document keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommandResult::getInsertResults() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);

    $generatedId = $bulk->insertOne('db.coll', ['x' => 1]);

    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($generatedId);

    var_dump($result->getInsertResults()->toPHP());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f7ee69783dcce702097b41"
    }
    object(stdClass)#8 (1) {
      ["0"]=>
      object(stdClass)#7 (1) {
        ["insertedId"]=>
        object(MongoDB\BSON\ObjectId)#6 (1) {
          ["oid"]=>
          string(24) "67f7ee69783dcce702097b41"
        }
      }
    }

### Siehe auch

- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount() - Returns the number of documents inserted
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged
- MongoDB\Driver\BulkWriteCommand::insertOne() - Add an insertOne operation

# MongoDB\Driver\BulkWriteCommandResult::getMatchedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Returns the number of documents selected for update

### Beschreibung

final public function MongoDB\Driver\BulkWriteCommandResult::getMatchedCount(): int

If the update operation results in no change to the document (e.g. setting the value of a field to its current value), the matched count may be greater than the value returned by MongoDB\Driver\BulkWriteCommandResult::getModifiedCount().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the total number of documents selected for update by all operations.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getMatchedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)

### Siehe auch

- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Returns the number of existing documents updated
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Returns verbose results for successful updates
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getModifiedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Returns the number of existing documents updated

### Beschreibung

final public function MongoDB\Driver\BulkWriteCommandResult::getModifiedCount(): int

If the update operation results in no change to the document (e.g. setting the value of a field to its current value), the modified count may be less than the value returned by MongoDB\Driver\BulkWriteCommandResult::getMatchedCount().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the total number of existing documents updated by all operations.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getModifiedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)

### Siehe auch

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Returns the number of documents selected for update
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Returns verbose results for successful updates
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getUpdateResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Returns verbose results for successful updates

### Beschreibung

final public function MongoDB\Driver\BulkWriteCommandResult::getUpdateResults(): ?MongoDB\BSON\Document

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a document containing the result of each successful update operation, or `null` if verbose results were not requested. The document keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpdateResults()->toPHP());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#16 (3) {
      ["1"]=>
      object(stdClass)#7 (2) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#6 (1) {
          ["integer"]=>
          string(1) "1"
        }
      }
      ["2"]=>
      object(stdClass)#11 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#8 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#9 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#10 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d575"
        }
      }
      ["3"]=>
      object(stdClass)#15 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#12 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#13 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#14 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d576"
        }
      }
    }

### Siehe auch

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Returns the number of documents selected for update
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Returns the number of existing documents updated
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount() - Returns the number of documents upserted
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Returns the number of documents upserted

### Beschreibung

final public function MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the total number of documents upserted by all operations.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Löst eine MongoDB\Driver\Exception\LogicException aus, wenn der Schreibvorgang nicht bestätigt wurde.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpsertedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(2)

### Siehe auch

- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Returns verbose results for successful updates
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::isAcknowledged

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Returns whether the write was acknowledged

### Beschreibung

final public function MongoDB\Driver\BulkWriteCommandResult::isAcknowledged(): bool

If the write is acknowledged, other fields will be available on the MongoDB\Driver\BulkWriteCommandResult object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the write was acknowledged, and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() with acknowledged write concern

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->isAcknowledged());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)

Beispiel #2 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() with unacknowledged write concern

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)

### Siehe auch

- MongoDB\Driver\WriteConcern
- » Write Concern reference

## Inhaltsverzeichnis

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Returns the number of documents deleted
- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Returns verbose results for successful deletes
- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Returns the number of documents inserted
- MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Returns verbose results for successful inserts
- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Returns the number of documents selected for update
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Returns the number of existing documents updated
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Returns verbose results for successful updates
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Returns the number of documents upserted
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Returns whether the write was acknowledged

# MongoDB BSON Classes and Functions

## Inhaltsverzeichnis

- Funktionen
- MongoDB\BSON\Document
- MongoDB\BSON\PackedArray
- MongoDB\BSON\Iterator
- MongoDB\BSON\Binary
- MongoDB\BSON\VectorType
- MongoDB\BSON\Decimal128
- MongoDB\BSON\Javascript
- MongoDB\BSON\MaxKey
- MongoDB\BSON\MinKey
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Regex
- MongoDB\BSON\Timestamp
- MongoDB\BSON\UTCDateTime
- MongoDB\BSON\Type
- MongoDB\BSON\Persistable
- MongoDB\BSON\Serializable
- MongoDB\BSON\Unserializable
- MongoDB\BSON\BinaryInterface
- MongoDB\BSON\Decimal128Interface
- MongoDB\BSON\JavascriptInterface
- MongoDB\BSON\MaxKeyInterface
- MongoDB\BSON\MinKeyInterface
- MongoDB\BSON\ObjectIdInterface
- MongoDB\BSON\RegexInterface
- MongoDB\BSON\TimestampInterface
- MongoDB\BSON\UTCDateTimeInterface
- MongoDB\BSON\DBPointer
- MongoDB\BSON\Int64
- MongoDB\BSON\Symbol
- MongoDB\BSON\Undefined

# Funktionen

# MongoDB\BSON\fromJSON

(mongodb >=1.0.0)

MongoDB\BSON\fromJSON — Returns the BSON representation of a JSON value

Warnung

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::fromJSON() instead.

### Beschreibung

function MongoDB\BSON\fromJSON(string `$json`): string

Converts an » extended JSON string to its BSON representation.

### Parameter-Liste

`json` (string)
  JSON value to be converted.

### Rückgabewerte

The serialized BSON document as a binary string.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to BSON (e.g. due to a syntax error).

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Funktion wurde entfernt.

### Beispiele

Beispiel #1 MongoDB\BSON\fromJSON() example

    <?php

    $json = '{ "_id": { "$oid": "563143b280d2387c91807965" } }';
    $bson = MongoDB\BSON\fromJSON($json);
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(stdClass)#2 (1) {
      ["_id"]=>
      object(MongoDB\BSON\ObjectId)#1 (1) {
        ["oid"]=>
        string(24) "563143b280d2387c91807965"
      }
    }

### Siehe auch

- MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
- MongoDB\BSON\toJSON() - Returns the Legacy Extended JSON representation of a BSON value
- » MongoDB Extended JSON
- » MongoDB BSON

# MongoDB\BSON\fromPHP

(mongodb >=1.0.0)

MongoDB\BSON\fromPHP — Returns the BSON representation of a PHP value

Warnung

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::fromPHP() instead.

### Beschreibung

function MongoDB\BSON\fromPHP(array|object `$value`): string

Serializes a PHP array or object (e.g. document) to its » BSON representation. The returned binary string will describe a BSON document.

### Parameter-Liste

`value` (array|object)
  PHP value to be serialized.

### Rückgabewerte

The serialized BSON document as a binary string.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\UnexpectedValueException if the PHP value cannot be converted to BSON. Possible reasons include, but are not limited to, encountering an unexpected MongoDB\BSON\Type instance or MongoDB\BSON\Serializable::bsonSerialize() failing to return an array or stdClass.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Funktion wurde entfernt.

### Beispiele

Beispiel #1 MongoDB\BSON\fromPHP() example

    <?php

    $bson = MongoDB\BSON\fromPHP(['foo' => 1]);
    echo bin2hex($bson), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0e00000010666f6f000100000000

### Siehe auch

- MongoDB\BSON\Document::fromPHP() - Construct a new document instance from PHP data
- MongoDB\BSON\toPHP() - Returns the PHP representation of a BSON value
- » MongoDB BSON
- Persisting Data

# MongoDB\BSON\toCanonicalExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of a BSON value

Warnung

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::toCanonicalExtendedJSON() instead.

### Beschreibung

function MongoDB\BSON\toCanonicalExtendedJSON(string `$bson`): string

Converts a BSON string to its » Canonical Extended JSON representation. The canonical format prefers type fidelity at the expense of concise output and is most suited for producing output that can be converted back to BSON without any loss of type information (e.g. numeric types will remain differentiated).

### Parameter-Liste

`bson` (string)
  BSON value to be converted.

### Rückgabewerte

The converted JSON value.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\UnexpectedValueException, wenn die Eingabe nicht genau ein BSON-Dokument enthält. Mögliche Gründe sind unter anderem ungültiges BSON, zusätzliche Daten (nach dem Lesen eines BSON-Dokuments) oder ein unerwarteter » libbson-Fehler.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Funktion wurde entfernt.

### Beispiele

Beispiel #1 MongoDB\BSON\toCanonicalExtendedJSON() example

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toCanonicalExtendedJSON($bson), "\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Siehe auch

- MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of the BSON document
- MongoDB\BSON\fromJSON() - Returns the BSON representation of a JSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » Extended JSON Specification
- » MongoDB BSON

# MongoDB\BSON\toJSON

(mongodb >=1.0.0)

MongoDB\BSON\toJSON — Returns the Legacy Extended JSON representation of a BSON value

Warnung

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::toCanonicalExtendedJSON() or MongoDB\BSON\Document::toRelaxedExtendedJSON() instead.

### Beschreibung

function MongoDB\BSON\toJSON(string `$bson`): string

Converts a BSON string to its » Legacy Extended JSON representation.

> Hinweis: There exist several JSON formats for representing BSON. This function implements the "strict mode" defined in » MongoDB Extended JSON, which has been superseded by the canonical and relaxed formats defined in the » Extended JSON Specification and implemented by MongoDB\BSON\toCanonicalExtendedJSON() and MongoDB\BSON\toRelaxedExtendedJSON(), respectively.

Warnung

» JSON does not support `NAN` and `INF` and MongoDB's Legacy Extended JSON format does not define an alternative representation for these values (» libbson will output `nan` and `inf` literals, which may not be parsed as valid JSON). If you are working with BSON that may contain non-finite numbers, please use MongoDB\BSON\toCanonicalExtendedJSON() or MongoDB\BSON\toRelaxedExtendedJSON().

### Parameter-Liste

`bson` (string)
  BSON value to be converted.

### Rückgabewerte

The converted JSON value.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\UnexpectedValueException, wenn die Eingabe nicht genau ein BSON-Dokument enthält. Mögliche Gründe sind unter anderem ungültiges BSON, zusätzliche Daten (nach dem Lesen eines BSON-Dokuments) oder ein unerwarteter » libbson-Fehler.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Funktion wurde entfernt.

### Beispiele

Beispiel #1 MongoDB\BSON\toJSON() example

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toJSON($bson), "\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : nan }
    { "pos_inf" : inf }
    { "neg_inf" : -inf }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : "Zm9v", "$type" : "00" } }
    { "date" : { "$date" : 1445990400000 } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regex" : "pattern", "$options" : "i" } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Siehe auch

- MongoDB\BSON\fromJSON() - Returns the BSON representation of a JSON value
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON
- » MongoDB BSON

# MongoDB\BSON\toPHP

(mongodb >=1.0.0)

MongoDB\BSON\toPHP — Returns the PHP representation of a BSON value

Warnung

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::toPHP() instead.

### Beschreibung

function MongoDB\BSON\toPHP(string `$bson`, array `$typeMap` = array()): array|object

Unserializes a BSON document (i.e. binary string) to its PHP representation. The `typeMap` parameter may be used to control the PHP types used for converting BSON arrays and documents (both root and embedded).

Warnung

Da Dokumente als Liste von Schlüssel-Wert-Paaren gespeichert werden, können BSON-Dokumente technisch gesehen doppelte Schlüssel enthalten; Anwendungen sollten allerdings davon absehen, Dokumente mit doppelten Schlüsseln zu erzeugen, da das Verhalten von Server und Treiber undefiniert sein kann. Der Grund dafür ist, dass PHP-Objekte und -Arrays keine doppelten Schlüssel haben können, weshalb bei der Dekodierung eines BSON-Dokuments mit doppelten Schlüsseln Daten verloren gehen können.

### Parameter-Liste

`bson` (string)
  BSON value to be unserialized.
`typeMap` (array)

  Konfiguration der Typzuordnung.

### Rückgabewerte

The unserialized PHP value.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.
- Wirft eine MongoDB\Driver\Exception\UnexpectedValueException, wenn die Eingabe nicht genau ein BSON-Dokument enthält. Mögliche Gründe sind unter anderem ungültiges BSON, zusätzliche Daten (nach dem Lesen eines BSON-Dokuments) oder ein unerwarteter » libbson-Fehler.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Funktion wurde entfernt.
PECL mongodb 1.4.0 | If the input contains an unsupported, deprecated BSON type, the extension will now no longer log a warning to the debug log, but instead will create an object representing this type.
PECL mongodb 1.3.2 | MongoDB\Driver\Exception\UnexpectedValueException is no longer thrown if the input contains an unsupported, deprecated BSON type. Such types will be ignored (as they were in versions before 1.3.0), although the extension will now log a warning to the debug log (see: mongodb.debug).
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\UnexpectedValueException is thrown if the input contains an unsupported, deprecated BSON type. Previously, such types were ignored.

### Beispiele

Beispiel #1 MongoDB\BSON\toPHP() example

    <?php

    $bson = hex2bin('0e00000010666f6f000100000000');
    $value = MongoDB\BSON\toPHP($bson);
    var_dump($value);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(stdClass)#1 (1) {
      ["foo"]=>
      int(1)
    }

### Siehe auch

- MongoDB\BSON\Document::toPHP() - Returns the PHP representation of the BSON document
- MongoDB\BSON\fromPHP() - Returns the BSON representation of a PHP value
- » MongoDB BSON
- Persisting Data

# MongoDB\BSON\toRelaxedExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of a BSON value

Warnung

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::toRelaxedExtendedJSON() instead.

### Beschreibung

function MongoDB\BSON\toRelaxedExtendedJSON(string `$bson`): string

Converts a BSON string to its » Relaxed Extended JSON representation. The relaxed format prefers use of JSON type primitives at the expense of type fidelity and is most suited for producing output that can be easily consumed by web APIs and humans.

### Parameter-Liste

`bson` (string)
  BSON value to be converted.

### Rückgabewerte

The converted JSON value.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\UnexpectedValueException, wenn die Eingabe nicht genau ein BSON-Dokument enthält. Mögliche Gründe sind unter anderem ungültiges BSON, zusätzliche Daten (nach dem Lesen eines BSON-Dokuments) oder ein unerwarteter » libbson-Fehler.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Funktion wurde entfernt.

### Beispiele

Beispiel #1 MongoDB\BSON\toRelaxedExtendedJSON() example

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0, ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\fromPHP($document);
        echo MongoDB\BSON\toRelaxedExtendedJSON($bson), "\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : "2015-10-28T00:00:00Z" } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Siehe auch

- MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of the BSON document
- MongoDB\BSON\fromJSON() - Returns the BSON representation of a JSON value
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- » Extended JSON
- » MongoDB BSON

## Inhaltsverzeichnis

- MongoDB\BSON\fromJSON — Returns the BSON representation of a JSON value
- MongoDB\BSON\fromPHP — Returns the BSON representation of a PHP value
- MongoDB\BSON\toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toJSON — Returns the Legacy Extended JSON representation of a BSON value
- MongoDB\BSON\toPHP — Returns the PHP representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of a BSON value

# The MongoDB\BSON\Document class

(mongodb >=1.16.0)

## Einführung

Represents a BSON document. This class is used when reading data as raw BSON and cannot be modified.

## Klassenbeschreibung

final class MongoDB\BSON\Document implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Methoden */
final private function __construct()
final static public function fromBSON(string `$bson`): MongoDB\BSON\Document
final static public function fromJSON(string `$json`): MongoDB\BSON\Document
final static public function fromPHP(object|array `$value`): MongoDB\BSON\Document
final public function get(string `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(string `$key`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.17.0 | Implements MongoDB\BSON\Type.

# MongoDB\BSON\Document::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Document::__construct — Construct a new BSON document (unused)

### Beschreibung

final private function MongoDB\BSON\Document::__construct()

MongoDB\BSON\Document objects are created through static factory methods and cannot be instantiated directly.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- MongoDB\BSON\Document::fromPHP() - Construct a new document instance from PHP data
- MongoDB\BSON\Document::fromBSON() - Construct a new document instance from a BSON string
- MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
- » BSON Types

# MongoDB\BSON\Document::fromBSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromBSON — Construct a new document instance from a BSON string

### Beschreibung

final static public function MongoDB\BSON\Document::fromBSON(string `$bson`): MongoDB\BSON\Document

### Parameter-Liste

`bson` (string)
  A string containing a document in BSON format.

### Rückgabewerte

Returns a new MongoDB\BSON\Document instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if `bson` is an invalid BSON string or contains more than a single document.

### Siehe auch

- MongoDB\BSON\Document::fromPHP() - Construct a new document instance from PHP data
- MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
- » BSON Types

# MongoDB\BSON\Document::fromJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromJSON — Construct a new document instance from a JSON string

### Beschreibung

final static public function MongoDB\BSON\Document::fromJSON(string `$json`): MongoDB\BSON\Document

Converts an » extended JSON string to its BSON representation.

### Parameter-Liste

`json` (string)
  JSON value to be converted.

### Rückgabewerte

Returns a new MongoDB\BSON\Document instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to a BSON document (e.g. due to a syntax error).

### Siehe auch

- MongoDB\BSON\Document::fromPHP() - Construct a new document instance from PHP data
- MongoDB\BSON\Document::fromBSON() - Construct a new document instance from a BSON string
- » MongoDB Extended JSON
- » BSON Types

# MongoDB\BSON\Document::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromPHP — Construct a new document instance from PHP data

### Beschreibung

final static public function MongoDB\BSON\Document::fromPHP(object|array `$value`): MongoDB\BSON\Document

### Parameter-Liste

`value` (object|array)
  A PHP object or array containing the document. When passing an array with numeric keys, the numeric values are converted to strings and used as document keys.

### Rückgabewerte

Returns a new MongoDB\BSON\Document instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\BSON\Document::fromBSON() - Construct a new document instance from a BSON string
- MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
- » BSON Types

# MongoDB\BSON\Document::get

(mongodb >=1.16.0)

MongoDB\BSON\Document::get — Returns the value of a key in the document

### Beschreibung

final public function MongoDB\BSON\Document::get(string `$key`): mixed

### Parameter-Liste

`key` (string)
  The key to retrieve from the document.

### Rückgabewerte

Returns the value associated with the given key. If the key is not present in the document, an exception is thrown.

> Hinweis: When encountering a value encoded as 64-bit integer in the BSON document, the return value of this method will be a MongoDB\BSON\Int64 instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\RuntimeException if the key is not present in the document.

### Siehe auch

- MongoDB\BSON\Document::has() - Returns whether a key is present in the document
- » BSON Types

# MongoDB\BSON\Document::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\Document::getIterator — Returns an iterator for the BSON document

### Beschreibung

final public function MongoDB\BSON\Document::getIterator(): MongoDB\BSON\Iterator

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a MongoDB\BSON\Iterator instance that can be used to iterate over all keys in the document.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the BSON iterator could not be initialized.

### Siehe auch

- » BSON Types

# MongoDB\BSON\Document::has

(mongodb >=1.16.0)

MongoDB\BSON\Document::has — Returns whether a key is present in the document

### Beschreibung

final public function MongoDB\BSON\Document::has(string `$key`): bool

### Parameter-Liste

`key` (string)
  The key to look for in the document.

### Rückgabewerte

Returns `true` if the key is present in the document and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\BSON\Document::get() - Returns the value of a key in the document
- » BSON Types

# MongoDB\BSON\Document::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetExists — Returns whether a key is present in the document

### Beschreibung

final public function MongoDB\BSON\Document::offsetExists(mixed `$key`): bool

### Parameter-Liste

`key`
  The key to look for in the document.

### Rückgabewerte

Returns `true` if the key is present in the document and `false` otherwise.

### Siehe auch

- ArrayAccess::offsetExists() - Prüft, ob ein Offset-Punkt existiert
- MongoDB\BSON\Document::has() - Returns whether a key is present in the document

# MongoDB\BSON\Document::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetGet — Returns the value of a key in the document

### Beschreibung

final public function MongoDB\BSON\Document::offsetGet(mixed `$key`): mixed

### Parameter-Liste

`key`
  The key to retrieve from the document.

### Rückgabewerte

Returns the value associated with the given key. If the key is not present in the document, an exception is thrown.

> Hinweis: When encountering a value encoded as 64-bit integer in the BSON document, the return value of this method will be a MongoDB\BSON\Int64 instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\RuntimeException if the key is not present in the document.

### Siehe auch

- ArrayAccess::offsetGet() - Gibt den Wert eines Offset-Punkts zurück
- MongoDB\BSON\Document::get() - Returns the value of a key in the document

# MongoDB\BSON\Document::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetSet — Implementation of ArrayAccess

### Beschreibung

final public function MongoDB\BSON\Document::offsetSet(mixed `$key`, mixed `$value`): void

Sets the value at the specified `key` to `value`.

### Parameter-Liste

`key`
  The index being set.
`value`
  The new value for the `key`.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Always throws a MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetUnset — Implementation of ArrayAccess

### Beschreibung

final public function MongoDB\BSON\Document::offsetUnset(mixed `$key`): void

Unsets the value at the specified index.

### Parameter-Liste

`key`
  The index being unset.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Always throws a MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\Document::toCanonicalExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON document

### Beschreibung

final public function MongoDB\BSON\Document::toCanonicalExtendedJSON(): string

Converts the BSON document to its » Canonical Extended JSON representation. The canonical format prefers type fidelity at the expense of concise output and is most suited for producing output that can be converted back to BSON without any loss of type information (e.g. numeric types will remain differentiated).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the » Canonical Extended JSON representation of the BSON document.

### Beispiele

Beispiel #1 MongoDB\BSON\Document::toCanonicalExtendedJSON() example

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0 ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toCanonicalExtendedJSON(), "\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : { "$numberInt" : "123" } }
    { "int64" : { "$numberLong" : "4294967295"} }
    { "double" : { "$numberDouble" : "1.0" } }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : { "$numberLong" : "1445990400000" } } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : { "$numberInt" : "1" } } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Siehe auch

- MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
- MongoDB\BSON\Document::toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of the BSON document
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- » Extended JSON Specification
- » BSON Types

# MongoDB\BSON\Document::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::toPHP — Returns the PHP representation of the BSON document

### Beschreibung

final public function MongoDB\BSON\Document::toPHP(?array `$typeMap` = `null`): array|object

Unserializes the BSON document to its PHP representation. The `typeMap` parameter may be used to control the PHP types used for converting BSON arrays and documents (both root and embedded).

Warnung

Da Dokumente als Liste von Schlüssel-Wert-Paaren gespeichert werden, können BSON-Dokumente technisch gesehen doppelte Schlüssel enthalten; Anwendungen sollten allerdings davon absehen, Dokumente mit doppelten Schlüsseln zu erzeugen, da das Verhalten von Server und Treiber undefiniert sein kann. Der Grund dafür ist, dass PHP-Objekte und -Arrays keine doppelten Schlüssel haben können, weshalb bei der Dekodierung eines BSON-Dokuments mit doppelten Schlüsseln Daten verloren gehen können.

### Parameter-Liste

`typeMap` (array)

  Konfiguration der Typzuordnung.

### Rückgabewerte

The decoded PHP value.

> Hinweis: When encountering a value encoded as 64-bit integer in the BSON document, the return value of this method will be a MongoDB\BSON\Int64 instance.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.

### Siehe auch

- MongoDB\BSON\toPHP() - Returns the PHP representation of a BSON value
- » BSON Types

# MongoDB\BSON\Document::toRelaxedExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON document

### Beschreibung

final public function MongoDB\BSON\Document::toRelaxedExtendedJSON(): string

Converts the BSON document to its » Relaxed Extended JSON representation. The relaxed format prefers use of JSON type primitives at the expense of type fidelity and is most suited for producing output that can be easily consumed by web APIs and humans.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the » Relaxed Extended JSON representation of the BSON document.

### Beispiele

Beispiel #1 MongoDB\BSON\Document::toRelaxedExtendedJSON() example

    <?php

    $documents = [
        [ 'null' => null ],
        [ 'boolean' => true ],
        [ 'string' => 'foo' ],
        [ 'int32' => 123 ],
        [ 'int64' => 4294967295 ],
        [ 'double' => 1.0 ],
        [ 'nan' => NAN ],
        [ 'pos_inf' => INF ],
        [ 'neg_inf' => -INF ],
        [ 'array' => [ 'foo', 'bar' ]],
        [ 'document' => [ 'foo' => 'bar' ]],
        [ 'oid' => new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1') ],
        [ 'dec128' => new MongoDB\BSON\Decimal128('1234.5678') ],
        [ 'binary' => new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC) ],
        [ 'date' => new MongoDB\BSON\UTCDateTime(1445990400000) ],
        [ 'timestamp' => new MongoDB\BSON\Timestamp(1234, 5678) ],
        [ 'regex' => new MongoDB\BSON\Regex('pattern', 'i') ],
        [ 'code' => new MongoDB\BSON\Javascript('function() { return 1; }') ],
        [ 'code_ws' => new MongoDB\BSON\Javascript('function() { return a; }', ['a' => 1]) ],
        [ 'minkey' => new MongoDB\BSON\MinKey ],
        [ 'maxkey' => new MongoDB\BSON\MaxKey ],
    ];

    foreach ($documents as $document) {
        $bson = MongoDB\BSON\Document::fromPHP($document);
        echo $bson->toRelaxedExtendedJSON(), "\n";
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    { "null" : null }
    { "boolean" : true }
    { "string" : "foo" }
    { "int32" : 123 }
    { "int64" : 4294967295 }
    { "double" : 1.0 }
    { "nan" : { "$numberDouble" : "NaN" } }
    { "pos_inf" : { "$numberDouble" : "Infinity" } }
    { "neg_inf" : { "$numberDouble" : "-Infinity" } }
    { "array" : [ "foo", "bar" ] }
    { "document" : { "foo" : "bar" } }
    { "oid" : { "$oid" : "56315a7c6118fd1b920270b1" } }
    { "dec128" : { "$numberDecimal" : "1234.5678" } }
    { "binary" : { "$binary" : { "base64": "Zm9v", "subType" : "00" } } }
    { "date" : { "$date" : "2015-10-28T00:00:00Z" } }
    { "timestamp" : { "$timestamp" : { "t" : 5678, "i" : 1234 } } }
    { "regex" : { "$regularExpression" : { "pattern" : "pattern", "options" : "i" } } }
    { "code" : { "$code" : "function() { return 1; }" } }
    { "code_ws" : { "$code" : "function() { return a; }", "$scope" : { "a" : 1 } } }
    { "minkey" : { "$minKey" : 1 } }
    { "maxkey" : { "$maxKey" : 1 } }

### Siehe auch

- MongoDB\BSON\Document::fromJSON() - Construct a new document instance from a JSON string
- MongoDB\BSON\Document::toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of the BSON document
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » Extended JSON Specification
- » BSON Types

# MongoDB\BSON\Document::__toString

(mongodb >=1.16.0)

MongoDB\BSON\Document::__toString — Returns the string representation of this BSON Document

### Beschreibung

final public function MongoDB\BSON\Document::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this document as BSON.

### Siehe auch

- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\Document::__construct — Construct a new BSON document (unused)
- MongoDB\BSON\Document::fromBSON — Construct a new document instance from a BSON string
- MongoDB\BSON\Document::fromJSON — Construct a new document instance from a JSON string
- MongoDB\BSON\Document::fromPHP — Construct a new document instance from PHP data
- MongoDB\BSON\Document::get — Returns the value of a key in the document
- MongoDB\BSON\Document::getIterator — Returns an iterator for the BSON document
- MongoDB\BSON\Document::has — Returns whether a key is present in the document
- MongoDB\BSON\Document::offsetExists — Returns whether a key is present in the document
- MongoDB\BSON\Document::offsetGet — Returns the value of a key in the document
- MongoDB\BSON\Document::offsetSet — Implementation of ArrayAccess
- MongoDB\BSON\Document::offsetUnset — Implementation of ArrayAccess
- MongoDB\BSON\Document::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON document
- MongoDB\BSON\Document::toPHP — Returns the PHP representation of the BSON document
- MongoDB\BSON\Document::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON document
- MongoDB\BSON\Document::__toString — Returns the string representation of this BSON Document

# The MongoDB\BSON\PackedArray class

(mongodb >=1.16.0)

## Einführung

Represents a BSON array. This class is used when reading data as raw BSON and cannot be modified.

## Klassenbeschreibung

final class MongoDB\BSON\PackedArray implements MongoDB\BSON\Type, ArrayAccess, IteratorAggregate {
/* Methoden */
final private function __construct()
final static public function fromJSON(string `$json`): MongoDB\BSON\PackedArray
final static public function fromPHP(array `$value`): MongoDB\BSON\PackedArray
final public function get(int `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(int `$index`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.17.0 | Implements MongoDB\BSON\Type.
PECL mongodb 1.17.0 | MongoDB\BSON\PackedArray cannot be serialized in contexts where a BSON document is expected. In earlier versions, the BSON array would have been converted to a document.

# MongoDB\BSON\PackedArray::__construct

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__construct — Construct a new BSON array (unused)

### Beschreibung

final private function MongoDB\BSON\PackedArray::__construct()

MongoDB\BSON\PackedArray objects are created through static factory methods and cannot be instantiated directly.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- MongoDB\BSON\PackedArray::fromPHP() - Construct a new BSON array instance from PHP data
- » BSON Types

# MongoDB\BSON\PackedArray::fromJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::fromJSON — Construct a new BSON array instance from a JSON string

### Beschreibung

final static public function MongoDB\BSON\PackedArray::fromJSON(string `$json`): MongoDB\BSON\PackedArray

Converts an » extended JSON string to its BSON representation.

### Parameter-Liste

`json` (string)
  JSON value to be converted.

### Rückgabewerte

Returns a new MongoDB\BSON\PackedArray instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to a BSON array (e.g. due to a syntax error).

### Beispiele

Beispiel #1 MongoDB\BSON\PackedArray::fromJSON() example

    <?php

    $json = '[ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]';
    $packedArray = MongoDB\BSON\PackedArray::fromJSON($json);
    var_dump($packedArray);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MongoDB\BSON\PackedArray)#1 (2) {
      ["data"]=>
      string(68) "MQAAAAIwAAQAAABmb28AEDEAewAAABIyAP////8AAAAABzMAVjFafGEY/RuSAnCxAA=="
      ["value"]=>
      array(4) {
        [0]=>
        string(3) "foo"
        [1]=>
        int(123)
        [2]=>
        int(4294967295)
        [3]=>
        object(MongoDB\BSON\ObjectId)#2 (1) {
          ["oid"]=>
          string(24) "56315a7c6118fd1b920270b1"
        }
      }
    }

### Siehe auch

- MongoDB\BSON\PackedArray::fromPHP() - Construct a new BSON array instance from PHP data
- » MongoDB Extended JSON
- » BSON Types

# MongoDB\BSON\PackedArray::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::fromPHP — Construct a new BSON array instance from PHP data

### Beschreibung

final static public function MongoDB\BSON\PackedArray::fromPHP(array `$value`): MongoDB\BSON\PackedArray

### Parameter-Liste

`value` (array)
  The PHP array to convert to a BSON array. The array must be a list (i.e. have sequential numeric keys starting with `0`).

### Rückgabewerte

Returns a new MongoDB\BSON\PackedArray instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if the given array is not a list (i.e. has sequential numeric keys starting with `0`).

### Siehe auch

- » BSON Types

# MongoDB\BSON\PackedArray::get

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::get — Returns the value of an index in the array

### Beschreibung

final public function MongoDB\BSON\PackedArray::get(int `$key`): mixed

### Parameter-Liste

`key` (int)
  The index to retrieve from the array.

### Rückgabewerte

Returns the value associated with the given index. If the index is not present in the array, an exception is thrown.

> Hinweis: When encountering a value encoded as 64-bit integer in the BSON array, the return value of this method will be a MongoDB\BSON\Int64 instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\RuntimeException if the index is not present in the array.

### Siehe auch

- MongoDB\BSON\PackedArray::has() - Returns whether a index is present in the array
- » BSON Types

# MongoDB\BSON\PackedArray::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::getIterator — Returns an iterator for the BSON array

### Beschreibung

final public function MongoDB\BSON\PackedArray::getIterator(): MongoDB\BSON\Iterator

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a MongoDB\BSON\Iterator instance that can be used to iterate over all indexes in the array.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the BSON iterator could not be initialized.

### Siehe auch

- » BSON Types

# MongoDB\BSON\PackedArray::has

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::has — Returns whether a index is present in the array

### Beschreibung

final public function MongoDB\BSON\PackedArray::has(int `$index`): bool

### Parameter-Liste

`index` (int)
  The index to look for in the array.

### Rückgabewerte

Returns `true` if the index is present in the array and `false` otherwise.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\BSON\PackedArray::get() - Returns the value of an index in the array
- » BSON Types

# MongoDB\BSON\PackedArray::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetExists — Returns whether a index is present in the array

### Beschreibung

final public function MongoDB\BSON\PackedArray::offsetExists(mixed `$key`): bool

### Parameter-Liste

`key`
  The index to look for in the array.

### Rückgabewerte

Returns `true` if the index is present in the array and `false` otherwise.

### Siehe auch

- ArrayAccess::offsetExists() - Prüft, ob ein Offset-Punkt existiert
- MongoDB\BSON\PackedArray::has() - Returns whether a index is present in the array

# MongoDB\BSON\PackedArray::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetGet — Returns the value of an index in the array

### Beschreibung

final public function MongoDB\BSON\PackedArray::offsetGet(mixed `$key`): mixed

### Parameter-Liste

`key`
  The index to retrieve from the array. Only int is supported.

### Rückgabewerte

Returns the value associated with the given index. If the index is not present in the array, an exception is thrown.

> Hinweis: When encountering a value encoded as 64-bit integer in the BSON array, the return value of this method will be a MongoDB\BSON\Int64 instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\RuntimeException if the index is not present in the array.

### Siehe auch

- ArrayAccess::offsetGet() - Gibt den Wert eines Offset-Punkts zurück
- MongoDB\BSON\PackedArray::get() - Returns the value of an index in the array

# MongoDB\BSON\PackedArray::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetSet — Implementation of ArrayAccess

### Beschreibung

final public function MongoDB\BSON\PackedArray::offsetSet(mixed `$key`, mixed `$value`): void

Sets the value at the specified `key` to `value`.

### Parameter-Liste

`key`
  The index being set.
`value`
  The new value for the `key`.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Always throws a MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetUnset — Implementation of ArrayAccess

### Beschreibung

final public function MongoDB\BSON\PackedArray::offsetUnset(mixed `$key`): void

Unsets the value at the specified index.

### Parameter-Liste

`key`
  The index being unset.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Always throws a MongoDB\Driver\Exception\LogicException.

# MongoDB\BSON\PackedArray::toCanonicalExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON array

### Beschreibung

final public function MongoDB\BSON\PackedArray::toCanonicalExtendedJSON(): string

Converts the BSON array to its » Canonical Extended JSON representation. The canonical format prefers type fidelity at the expense of concise output and is most suited for producing output that can be converted back to BSON without any loss of type information (e.g. numeric types will remain differentiated).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the » Canonical Extended JSON representation of the BSON array.

### Beispiele

Beispiel #1 MongoDB\BSON\PackedArray::toCanonicalExtendedJSON() example

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toCanonicalExtendedJSON(), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    [ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### Siehe auch

- MongoDB\BSON\PackedArray::fromJSON() - Construct a new BSON array instance from a JSON string
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of the BSON array
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- » Extended JSON Specification
- » BSON Types

# MongoDB\BSON\PackedArray::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::toPHP — Returns the PHP representation of the BSON array

### Beschreibung

final public function MongoDB\BSON\PackedArray::toPHP(?array `$typeMap` = `null`): array|object

### Parameter-Liste

`typeMap` (array)

  Konfiguration der Typzuordnung.

### Rückgabewerte

The decoded PHP value.

> Hinweis: When encountering a value encoded as 64-bit integer in the BSON array, the return value of this method will be a MongoDB\BSON\Int64 instance.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\InvalidArgumentException if a class in the type map cannot be instantiated or does not implement MongoDB\BSON\Unserializable.

### Siehe auch

- MongoDB\BSON\toPHP() - Returns the PHP representation of a BSON value
- » BSON Types

# MongoDB\BSON\PackedArray::toRelaxedExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON array

### Beschreibung

final public function MongoDB\BSON\PackedArray::toRelaxedExtendedJSON(): string

Converts the BSON array to its » Relaxed Extended JSON representation. The relaxed format prefers use of JSON type primitives at the expense of type fidelity and is most suited for producing output that can be easily consumed by web APIs and humans.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the » Relaxed Extended JSON representation of the BSON array.

### Beispiele

Beispiel #1 MongoDB\BSON\PackedArray::toRelaxedExtendedJSON() example

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toRelaxedExtendedJSON(), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    [ "foo", 123, 4294967295, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### Siehe auch

- MongoDB\BSON\PackedArray::fromJSON() - Construct a new BSON array instance from a JSON string
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of the BSON array
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » Extended JSON Specification
- » BSON Types

# MongoDB\BSON\PackedArray::__toString

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__toString — Returns the string representation of this BSON array

### Beschreibung

final public function MongoDB\BSON\PackedArray::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this array as BSON.

### Siehe auch

- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\PackedArray::__construct — Construct a new BSON array (unused)
- MongoDB\BSON\PackedArray::fromJSON — Construct a new BSON array instance from a JSON string
- MongoDB\BSON\PackedArray::fromPHP — Construct a new BSON array instance from PHP data
- MongoDB\BSON\PackedArray::get — Returns the value of an index in the array
- MongoDB\BSON\PackedArray::getIterator — Returns an iterator for the BSON array
- MongoDB\BSON\PackedArray::has — Returns whether a index is present in the array
- MongoDB\BSON\PackedArray::offsetExists — Returns whether a index is present in the array
- MongoDB\BSON\PackedArray::offsetGet — Returns the value of an index in the array
- MongoDB\BSON\PackedArray::offsetSet — Implementation of ArrayAccess
- MongoDB\BSON\PackedArray::offsetUnset — Implementation of ArrayAccess
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON array
- MongoDB\BSON\PackedArray::toPHP — Returns the PHP representation of the BSON array
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON array
- MongoDB\BSON\PackedArray::__toString — Returns the string representation of this BSON array

# The MongoDB\BSON\Iterator class

(mongodb >=1.16.0)

## Einführung

Iterator used to iterate a BSON document or array.

## Klassenbeschreibung

final class MongoDB\BSON\Iterator implements Iterator {
/* Methoden */
final private function __construct()
public function current(): mixed
public function key(): string|int
public function next(): void
public function rewind(): void
public function valid(): bool
}

# MongoDB\BSON\Iterator::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::__construct — Construct a new BSON iterator (unused)

### Beschreibung

final private function MongoDB\BSON\Iterator::__construct()

MongoDB\BSON\Iterator objects are created by calling MongoDB\BSON\Document::getIterator() or MongoDB\BSON\PackedArray::getIterator() and cannot be instantiated directly.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- MongoDB\BSON\Document::getIterator() - Returns an iterator for the BSON document
- MongoDB\BSON\PackedArray::getIterator() - Returns an iterator for the BSON array
- » BSON Types

# MongoDB\BSON\Iterator::current

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::current — Returns the current element

### Beschreibung

public function MongoDB\BSON\Iterator::current(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the value of the current element.

> Hinweis: When encountering a value encoded as 64-bit integer in the BSON structure, the return value of this method will be a MongoDB\BSON\Int64 instance.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\LogicException if the iterator is not valid.

### Siehe auch

- Iterator::current() - Liefert das aktuelle Element

# MongoDB\BSON\Iterator::key

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::key — Returns the key of the current element

### Beschreibung

public function MongoDB\BSON\Iterator::key(): string|int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the key of the current element. When iterating a BSON document, the key will always be a string. When iterating a BSON array, the key will be an int.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\LogicException if the iterator is not valid.

### Siehe auch

- Iterator::key() - Liefert den Schlüssel des aktuellen Elements

# MongoDB\BSON\Iterator::next

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::next — Advances the iterator to next element

### Beschreibung

public function MongoDB\BSON\Iterator::next(): void

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- Iterator::next() - Rückt den Zeiger auf das nächste Element vor

# MongoDB\BSON\Iterator::rewind

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::rewind — Rewinds the Iterator to the first element

### Beschreibung

public function MongoDB\BSON\Iterator::rewind(): void

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- Iterator::rewind() - Setzt den Iterator auf das erste Element zurück

# MongoDB\BSON\Iterator::valid

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::valid — Checks if current position is valid

### Beschreibung

public function MongoDB\BSON\Iterator::valid(): bool

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the current iterator position is valid, `false` otherwise.

### Siehe auch

- Iterator::valid() - Prüft, ob die aktuelle Position zulässig ist

## Inhaltsverzeichnis

- MongoDB\BSON\Iterator::__construct — Construct a new BSON iterator (unused)
- MongoDB\BSON\Iterator::current — Returns the current element
- MongoDB\BSON\Iterator::key — Returns the key of the current element
- MongoDB\BSON\Iterator::next — Advances the iterator to next element
- MongoDB\BSON\Iterator::rewind — Rewinds the Iterator to the first element
- MongoDB\BSON\Iterator::valid — Checks if current position is valid

# The MongoDB\BSON\Binary class

(mongodb >=1.0.0)

## Einführung

BSON type for binary data (i.e. array of bytes). Binary values also have a subtype, which is used to indicate what kind of data is in the byte array. Subtypes from zero to 127 are predefined or reserved. Subtypes from 128-255 are user-defined.

## Klassenbeschreibung

final class MongoDB\BSON\Binary implements MongoDB\BSON\BinaryInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Konstanten */
const int TYPE_GENERIC = 0;
const int TYPE_FUNCTION = 1;
const int TYPE_OLD_BINARY = 2;
const int TYPE_OLD_UUID = 3;
const int TYPE_UUID = 4;
const int TYPE_MD5 = 5;
const int TYPE_ENCRYPTED = 6;
const int TYPE_COLUMN = 7;
const int TYPE_SENSITIVE = 8;
const int TYPE_VECTOR = 9;
const int TYPE_USER_DEFINED = 128;
/* Methoden */
final public function __construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)
final public static function fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary
final public function getData(): string
final public function getType(): int
final public function getVectorType(): MongoDB\BSON\VectorType
final public function jsonSerialize(): mixed
final public function toArray(): array
final public function __toString(): string
}

## Vordefinierte Konstanten

`MongoDB\BSON\Binary::TYPE_GENERIC`
  Generic binary data.
`MongoDB\BSON\Binary::TYPE_FUNCTION`
  Function.
`MongoDB\BSON\Binary::TYPE_OLD_BINARY`
  Generic binary data (deprecated in favor of `MongoDB\BSON\Binary::TYPE_GENERIC`).
`MongoDB\BSON\Binary::TYPE_OLD_UUID`
  Universally unique identifier (deprecated in favor of `MongoDB\BSON\Binary::TYPE_UUID`). When using this type, the Binary's data should be 16 bytes in length. Historically, other drivers encoded values with this type based on their language conventions (e.g. varying endianness), which makes it non-portable. The PHP extension applies no special handling for encoding or decoding data with this type.
`MongoDB\BSON\Binary::TYPE_UUID`
  Universally unique identifier. When using this type, the Binary's data should be 16 bytes in length and encoded according to » RFC 4122.
`MongoDB\BSON\Binary::TYPE_MD5`
  MD5 hash. When using this type, the Binary's data should be 16 bytes in length.
`MongoDB\BSON\Binary::TYPE_ENCRYPTED`
  Encrypted value. This subtype is used for client-side encryption.
`MongoDB\BSON\Binary::TYPE_COLUMN`
  Column data. This subtype is used for time-series collections.
`MongoDB\BSON\Binary::TYPE_SENSITIVE`
  Sensitive data. This subtype is used for sensitive data that should be excluded from server-side logging when possible.
`MongoDB\BSON\Binary::TYPE_VECTOR`
  Vector data. This subtype is used to efficiently store vector data for use with MongoDB's vector search.
`MongoDB\BSON\Binary::TYPE_USER_DEFINED`
  User-defined type. While types between 0 and 127 are predefined or reserved, types between 128 and 255 are user-defined and may be used for anything.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.2.0 | Added `MongoDB\BSON\Binary::TYPE_VECTOR`, as well as the MongoDB\BSON\Binary::fromVector(), MongoDB\BSON\Binary::getVectorType(), and MongoDB\BSON\Binary::toArray() functions.
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.17.0 | Added `MongoDB\BSON\Binary::TYPE_SENSITIVE`.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+. Added `MongoDB\BSON\Binary::TYPE_COLUMN`.
PECL mongodb 1.7.0 | Added `MongoDB\BSON\Binary::TYPE_ENCRYPTED`.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\BinaryInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\Binary::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Binary::__construct — Construct a new Binary

### Beschreibung

final public function MongoDB\BSON\Binary::__construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)

### Parameter-Liste

`data` (string)
  Binary data.
`type` (int)
  Unsigned 8-bit integer denoting the data's type. Defaults to `MongoDB\BSON\Binary::TYPE_GENERIC` if not specified.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `type` is not an unsigned 8-bit integer.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `type` is `MongoDB\BSON\Binary::TYPE_UUID` or `MongoDB\BSON\Binary::TYPE_OLD_UUID` and `data` is not exactly 16 bytes in length.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.15.0 | The `type` parameter defaults to `MongoDB\BSON\Binary::TYPE_GENERIC` if not specified.
PECL mongodb 1.3.0 | MongoDB\Driver\Exception\InvalidArgumentException is thrown if `type` is `MongoDB\BSON\Binary::TYPE_UUID` or `MongoDB\BSON\Binary::TYPE_OLD_UUID` and `data` is not exactly 16 bytes in length.
PECL mongodb 1.1.3 | MongoDB\Driver\Exception\InvalidArgumentException is thrown if `type` is not an unsigned 8-bit integer.

### Beispiele

Beispiel #1 MongoDB\BSON\Binary::__construct() example

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MongoDB\BSON\Binary)#1 (2) {
      ["data"]=>
      string(3) "foo"
      ["type"]=>
      int(0)
    }

### Siehe auch

- » BSON Types

# MongoDB\BSON\Binary::fromVector

(mongodb >=2.2.0)

MongoDB\BSON\Binary::fromVector — Creates a new binary with subtype `MongoDB\BSON\Binary::SUBTYPE_VECTOR` from the given array and vector type

### Beschreibung

final public static function MongoDB\BSON\Binary::fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary

### Parameter-Liste

`vector` (array)

  An array of values representing the vector data. The type of each value must match the type indicated by the `vectorType` parameter:

  - for `MongoDB\BSON\VectorType::Float32`, each value must be a float
  - for `MongoDB\BSON\VectorType::Int8`, each value must be an 8-bit int, i.e. from `-127` to `128`
  - for `MongoDB\BSON\VectorType::PackedBit`, each value must be a bool or 1-bit int, i.e. `0` or `1`
`vectorType` (MongoDB\BSON\VectorType)
  The vector data type.

### Rückgabewerte

Returns a new Binary with subtype `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\BSON\Binary::toArray() - Returns the vector as an array for a Binary with subtype MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::getVectorType() - Returns the data type for a Binary with the vector subtype
- MongoDB\BSON\VectorType
- » BSON Types

# MongoDB\BSON\Binary::getData

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getData — Returns the Binary's data

### Beschreibung

final public function MongoDB\BSON\Binary::getData(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Binary's data.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\Binary::getData() example

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getData());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "foo"

### Siehe auch

- » BSON Types

# MongoDB\BSON\Binary::getType

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getType — Returns the Binary's type

### Beschreibung

final public function MongoDB\BSON\Binary::getType(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Binary's type.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\Binary::getType() example

    <?php

    $binary = new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC);
    var_dump($binary->getType());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)

### Siehe auch

- » BSON Types

# MongoDB\BSON\Binary::getVectorType

(mongodb >=2.2.0)

MongoDB\BSON\Binary::getVectorType — Returns the data type for a Binary with the vector subtype

### Beschreibung

final public function MongoDB\BSON\Binary::getVectorType(): MongoDB\BSON\VectorType

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the data type of the Binary vector.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\LogicException if the subtype is not `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- » BSON Types
- MongoDB\BSON\VectorType

# MongoDB\BSON\Binary::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\Binary::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Binary.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\Binary::toArray

(mongodb >=2.2.0)

MongoDB\BSON\Binary::toArray — Returns the vector as an array for a Binary with subtype `MongoDB\BSON\Binary::SUBTYPE_VECTOR`

### Beschreibung

final public function MongoDB\BSON\Binary::toArray(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array containing the vector data.

### Fehler/Exceptions

- Throws MongoDB\Driver\Exception\LogicException if the subtype is not `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\BSON\Binary::fromVector() - Creates a new binary with subtype MongoDB\BSON\Binary::SUBTYPE_VECTOR from the given array and vector type
- » BSON Types

# MongoDB\BSON\Binary::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Binary::__toString — Returns the Binary's data

### Beschreibung

final public function MongoDB\BSON\Binary::__toString(): string

Diese Methode ist ein Alias für: MongoDB\BSON\Binary::getData().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Binary's data.

### Beispiele

Beispiel #1 MongoDB\BSON\Binary::__toString() example

    <?php

    var_dump((string) new MongoDB\BSON\Binary('foo', MongoDB\BSON\Binary::TYPE_GENERIC));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "foo"

### Siehe auch

- MongoDB\BSON\Binary::getData() - Returns the Binary's data
- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\Binary::__construct — Construct a new Binary
- MongoDB\BSON\Binary::fromVector — Creates a new binary with subtype MongoDB\BSON\Binary::SUBTYPE_VECTOR from the given array and vector type
- MongoDB\BSON\Binary::getData — Returns the Binary's data
- MongoDB\BSON\Binary::getType — Returns the Binary's type
- MongoDB\BSON\Binary::getVectorType — Returns the data type for a Binary with the vector subtype
- MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Binary::toArray — Returns the vector as an array for a Binary with subtype MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::__toString — Returns the Binary's data

# The MongoDB\BSON\VectorType enum

(mongodb >=2.2.0)

## Einführung

The MongoDB\BSON\VectorType enum is used to specify the type of vector data stored in a MongoDB\BSON\Binary with subtype `MongoDB\BSON\Binary::TYPE_VECTOR`.

## Übersicht über Aufzählungen

enum MongoDB\BSON\VectorType
{
case Float32 ; // Each element in the vector is a 32-bit floating point value.
case Int8 ; // Each element in the vector is an 8-bit integer value.
case PackedBit ; // Each element in the vector is a 1-bit value. When creating vectors of this type, you may pass either bool or 1-bit int values, i.e. `0` or `1`.
}

# The MongoDB\BSON\Decimal128 class

(mongodb >=1.2.0)

## Einführung

BSON type for the » Decimal128 floating-point format, which supports numbers with up to 34 decimal digits (i.e. significant digits) and an exponent range of −6143 to +6144.

Unlike the double BSON type (i.e. float in PHP), which only stores an approximation of the decimal values, the decimal data type stores the exact value. For example, `MongoDB\BSON\Decimal128('9.99')` has a precise value of 9.99 where as a double 9.99 would have an approximate value of 9.9900000000000002131628….

> Hinweis: MongoDB\BSON\Decimal128 ist nur mit MongoDB 3.4+ kompatibel. Der Versuch, den Typ BSON mit einer früheren Version von MongoDB zu verwenden, führt zu einem Fehler.

## Klassenbeschreibung

final class MongoDB\BSON\Decimal128 implements MongoDB\BSON\Decimal128Interface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final public function __construct(string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\Decimal128Interface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\Decimal128::__construct

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128

### Beschreibung

final public function MongoDB\BSON\Decimal128::__construct(string `$value`)

> Hinweis: MongoDB\BSON\Decimal128 ist nur mit MongoDB 3.4+ kompatibel. Der Versuch, den Typ BSON mit einer früheren Version von MongoDB zu verwenden, führt zu einem Fehler.

### Parameter-Liste

`value` (string)
  A decimal string.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `value` is not a valid decimal string.

### Beispiele

Beispiel #1 MongoDB\BSON\Decimal128::__construct() example

    <?php

    var_dump(new MongoDB\BSON\Decimal128(1234.5678));
    var_dump(new MongoDB\BSON\Decimal128(NAN));
    var_dump(new MongoDB\BSON\Decimal128(INF));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(9) "1234.5678"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(3) "NaN"
    }
    object(MongoDB\BSON\Decimal128)#1 (1) {
      ["dec"]=>
      string(8) "Infinity"
    }

### Siehe auch

- » Decimal128 floating-point format
- » BSON Types

# MongoDB\BSON\Decimal128::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\Decimal128::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Decimal128.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\Decimal128::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128

### Beschreibung

final public function MongoDB\BSON\Decimal128::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this Decimal128.

### Beispiele

Beispiel #1 MongoDB\BSON\Decimal128::__toString() example

    <?php

    var_dump((string) new MongoDB\BSON\Decimal128(1234.5678));
    var_dump((string) new MongoDB\BSON\Decimal128(NAN));
    var_dump((string) new MongoDB\BSON\Decimal128(INF));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(9) "1234.5678"
    string(3) "NaN"
    string(8) "Infinity"

### Siehe auch

- » Decimal128 floating-point format
- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128
- MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128

# The MongoDB\BSON\Javascript class

(mongodb >=1.0.0)

## Einführung

BSON type for Javascript code. An optional scope document may be specified that maps identifiers to values and defines the scope in which the code should be evaluated by the server.

> Hinweis: This BSON type is mainly used when executing database commands that take a Javascript function as a parameter, such as » mapReduce.

## Klassenbeschreibung

final class MongoDB\BSON\Javascript implements MongoDB\BSON\JavascriptInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final public function __construct(string `$code`, array|object|null `$scope` = `null`)
final public function getCode(): string
final public function getScope(): ?object
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\JavascriptInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\Javascript::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Javascript::__construct — Construct a new Javascript

### Beschreibung

final public function MongoDB\BSON\Javascript::__construct(string `$code`, array|object|null `$scope` = `null`)

### Parameter-Liste

`code` (string)
  Javascript code.
`scope` (array|object)
  Javascript scope.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `code` contains null bytes.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.2.0 | MongoDB\Driver\Exception\InvalidArgumentException is thrown if `code` contains null bytes. Previously, values would be truncated at the first null byte.

### Beispiele

Beispiel #1 MongoDB\BSON\Javascript::__construct() example

    <?php

    $code = new MongoDB\BSON\Javascript('function() { return 1; }');
    var_dump($code);

    $codews = new MongoDB\BSON\Javascript('function() { return foo; }', ['foo' => 'bar']);
    var_dump($codews);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MongoDB\BSON\Javascript)#1 (2) {
      ["javascript"]=>
      string(24) "function() { return 1; }"
      ["scope"]=>
      object(stdClass)#2 (0) {
      }
    }
    object(MongoDB\BSON\Javascript)#2 (2) {
      ["javascript"]=>
      string(26) "function() { return foo; }"
      ["scope"]=>
      object(stdClass)#1 (1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Siehe auch

- » BSON Types

# MongoDB\BSON\Javascript::getCode

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getCode — Returns the Javascript's code

### Beschreibung

final public function MongoDB\BSON\Javascript::getCode(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Javascript's code.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\Javascript::getCode() example

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getCode());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(33) "function foo(bar) { return bar; }"

### Siehe auch

- » BSON Types

# MongoDB\BSON\Javascript::getScope

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document

### Beschreibung

final public function MongoDB\BSON\Javascript::getScope(): ?object

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Javascript's scope document, or `null` if the is no scope.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\Javascript::getScope() example

    <?php

    $js = new MongoDB\BSON\Javascript('function foo(bar) { return bar; }');
    var_dump($js->getScope());

    $js = new MongoDB\BSON\Javascript('function foo() { return foo; }', ['foo' => 42]);
    var_dump($js->getScope());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL
    object(stdClass)#1 (1) {
      ["foo"]=>
      int(42)
    }

### Siehe auch

- » BSON Types

# MongoDB\BSON\Javascript::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\Javascript::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Javascript.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\Javascript::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::__toString — Returns the Javascript's code

### Beschreibung

final public function MongoDB\BSON\Javascript::__toString(): string

Diese Methode ist ein Alias für: MongoDB\BSON\Javascript::getCode().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Javascript's code.

### Beispiele

Beispiel #1 MongoDB\BSON\Javascript::__toString() example

    <?php

    var_dump((string) new MongoDB\BSON\Javascript('function foo(bar) { return bar; }'));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(33) "function foo(bar) { return bar; }"

### Siehe auch

- MongoDB\BSON\Javascript::getCode() - Returns the Javascript's code
- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\Javascript::__construct — Construct a new Javascript
- MongoDB\BSON\Javascript::getCode — Returns the Javascript's code
- MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document
- MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Javascript::__toString — Returns the Javascript's code

# The MongoDB\BSON\MaxKey class

(mongodb >=1.0.0)

## Einführung

Special BSON type which compares higher than all other possible BSON element values.

> Hinweis: This is an internal MongoDB type used for indexing and sharding.

## Klassenbeschreibung

final class MongoDB\BSON\MaxKey implements MongoDB\BSON\MaxKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Methoden */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\MaxKeyInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\MaxKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey

### Beschreibung

final public function MongoDB\BSON\MaxKey::__construct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\MaxKey::__construct() example

    <?php

    var_dump(new MongoDB\BSON\MaxKey());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MongoDB\BSON\MaxKey)#1 (0) {
    }

### Siehe auch

- » BSON Types

# MongoDB\BSON\MaxKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\MaxKey::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\MaxKey.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

## Inhaltsverzeichnis

- MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey
- MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON

# The MongoDB\BSON\MinKey class

(mongodb >=1.0.0)

## Einführung

Special BSON type which compares lower than all other possible BSON element values.

> Hinweis: This is an internal MongoDB type used for indexing and sharding.

## Klassenbeschreibung

final class MongoDB\BSON\MinKey implements MongoDB\BSON\MinKeyInterface, MongoDB\BSON\Type, JsonSerializable {
/* Methoden */
final public function __construct()
final public function jsonSerialize(): mixed
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\MinKeyInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\MinKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MinKey::__construct — Construct a new MinKey

### Beschreibung

final public function MongoDB\BSON\MinKey::__construct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\MinKey::__construct() example

    <?php

    var_dump(new MongoDB\BSON\MinKey());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MongoDB\BSON\MinKey)#1 (0) {
    }

### Siehe auch

- » BSON Types

# MongoDB\BSON\MinKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\MinKey::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\MinKey.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

## Inhaltsverzeichnis

- MongoDB\BSON\MinKey::__construct — Construct a new MinKey
- MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON

# The MongoDB\BSON\ObjectId class

(mongodb >=1.0.0)

## Einführung

BSON type for an » ObjectId. The value consists of 12 bytes, where the first four bytes are a timestamp that reflect the ObjectId's creation. Specifically, the value consists of:

- a 4-byte value representing the seconds since the Unix epoch,
- a 5-byte random number unique to a machine and process, and
- a 3-byte counter, starting with a random value.

In MongoDB, each document stored in a collection requires a unique `_id` field that acts as a primary key. If an inserted document omits the `_id` field, the extension automatically generates an ObjectId for the `_id` field.

Using ObjectIds for the `_id` field provides the following additional benefits:

- The creation time of the ObjectId may be accessed using the MongoDB\BSON\ObjectId::getTimestamp() method.
- Sorting on an `_id` field that stores ObjectId values is roughly equivalent to sorting by creation time.

## Klassenbeschreibung

final class MongoDB\BSON\ObjectId implements MongoDB\BSON\ObjectIdInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final public function __construct(?string `$id` = `null`)
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Renamed from `MongoDB\BSON\ObjectID` to `MongoDB\BSON\ObjectId`. Implements MongoDB\BSON\ObjectIdInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\ObjectId::__construct

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__construct — Construct a new ObjectId

### Beschreibung

final public function MongoDB\BSON\ObjectId::__construct(?string `$id` = `null`)

### Parameter-Liste

`id` (string)
  A 24-character hexadecimal string. If not provided, the extension will generate an ObjectId.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `id` is not a 24-character hexadecimal string.

### Beispiele

Beispiel #1 MongoDB\BSON\ObjectId::__construct() example

    <?php

    var_dump(new MongoDB\BSON\ObjectId());

    var_dump(new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "56732d3dda14d81214634921"
    }
    object(MongoDB\BSON\ObjectId)#1 (1) {
      ["oid"]=>
      string(24) "000000000000000000000001"
    }

### Siehe auch

- » ObjectId Reference
- » BSON Types: ObjectId

# MongoDB\BSON\ObjectId::getTimestamp

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId

### Beschreibung

final public function MongoDB\BSON\ObjectId::getTimestamp(): int

The timestamp component of an ObjectId is its most significant 32 bits, which denotes the number of seconds since the Unix epoch. This value is read as an unsigned 32-bit integer with big-endian byte order.

> Hinweis: Da der Integer-Typ bei PHP vorzeichenbehaftet ist, könnten einige Werte, die von dieser Methode zurückgegeben werden, auf 32-Bit-Plattformen als negative Ganzzahlen erscheinen. Um eine Zeichenketten-Darstellung des Dezimalwertes ohne Vorzeichen zu erhalten, kann das Formatierungszeichen `"%u"` von sprintf() verwendet werden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the timestamp component of this ObjectId.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\ObjectId::getTimestamp() example

    <?php

    var_dump((new MongoDB\BSON\ObjectId())->getTimestamp());

    var_dump((new MongoDB\BSON\ObjectId('0000002a0000000000000000'))->getTimestamp());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    integer(1484854719)
    integer(42)

### Siehe auch

- » ObjectId Reference
- » BSON Types: ObjectId

# MongoDB\BSON\ObjectId::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\ObjectId::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\ObjectId.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\ObjectId::__toString

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__toString — Returns the hexadecimal representation of this ObjectId

### Beschreibung

final public function MongoDB\BSON\ObjectId::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hexadecimal representation of this ObjectId.

### Beispiele

Beispiel #1 MongoDB\BSON\ObjectId::__toString() example

    <?php

    var_dump((string) new MongoDB\BSON\ObjectId());
    var_dump((string) new MongoDB\BSON\ObjectId('000000000000000000000001'));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(24) "56731b49da14d8747d701211"
    string(24) "000000000000000000000001"

### Siehe auch

- » ObjectId Reference
- » BSON Types: ObjectId

## Inhaltsverzeichnis

- MongoDB\BSON\ObjectId::__construct — Construct a new ObjectId
- MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId
- MongoDB\BSON\ObjectId::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\ObjectId::__toString — Returns the hexadecimal representation of this ObjectId

# The MongoDB\BSON\Regex class

(mongodb >=1.0.0)

## Einführung

BSON type for a regular expression pattern and optional » flags.

> Hinweis: This BSON type is mainly used when querying the database. Alternatively, the » $regex query operator may be used.

## Klassenbeschreibung

final class MongoDB\BSON\Regex implements MongoDB\BSON\RegexInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final public function __construct(string `$pattern`, string `$flags` = "")
final public function getFlags(): string
final public function getPattern(): string
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\RegexInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\Regex::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__construct — Construct a new Regex

### Beschreibung

final public function MongoDB\BSON\Regex::__construct(string `$pattern`, string `$flags` = "")

### Parameter-Liste

`pattern` (string)
  The regular expression pattern.

  > Hinweis: The pattern should not be wrapped with delimiter characters.

`flags` (string)
  The » regular expression flags. Characters in this argument will be sorted alphabetically.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if `pattern` or `flags` contain null bytes.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.2.0 | The `flags` argument is optional and defaults to an empty string. Characters in the `flags` argument will be sorted alphabetically when a Regex is constructed. Previously, the characters were stored in the order provided. MongoDB\Driver\Exception\InvalidArgumentException is thrown if `pattern` or `flags` contain null bytes. Previously, values would be truncated at the first null byte.

### Beispiele

Beispiel #1 MongoDB\BSON\Regex::__construct() example

    <?php

    $regex = new MongoDB\BSON\Regex('^foo', 'i');
    var_dump($regex);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MongoDB\BSON\Regex)#1 (2) {
      ["pattern"]=>
      string(4) "^foo"
      ["flags"]=>
      string(1) "i"
    }

### Siehe auch

- » BSON Types
- » Supported regular expression flags

# MongoDB\BSON\Regex::getFlags

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getFlags — Returns the Regex's flags

### Beschreibung

final public function MongoDB\BSON\Regex::getFlags(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Regex's flags.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\Regex::getFlags() example

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getFlags());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(1) "i"

### Siehe auch

- » BSON Types
- » Supported regular expression flags

# MongoDB\BSON\Regex::getPattern

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern

### Beschreibung

final public function MongoDB\BSON\Regex::getPattern(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Regex's pattern.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\Regex::getPattern() example

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump($regex->getPattern());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(5) "regex"

### Siehe auch

- » BSON Types

# MongoDB\BSON\Regex::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\Regex::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Regex.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\Regex::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__toString — Returns the string representation of this Regex

### Beschreibung

final public function MongoDB\BSON\Regex::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this Regex.

### Beispiele

Beispiel #1 MongoDB\BSON\Regex::__toString() example

    <?php

    $regex = new MongoDB\BSON\Regex('regex', 'i');
    var_dump((string) $regex);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(8) "/regex/i"

### Siehe auch

- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\Regex::__construct — Construct a new Regex
- MongoDB\BSON\Regex::getFlags — Returns the Regex's flags
- MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern
- MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Regex::__toString — Returns the string representation of this Regex

# The MongoDB\BSON\Timestamp class

(mongodb >=1.0.0)

## Einführung

Represents a » BSON timestamp, The value consists of a 4-byte timestamp (i.e. seconds since the epoch) and a 4-byte increment.

> Hinweis: This is an internal MongoDB type used for replication and sharding. It is not intended for general date storage (MongoDB\BSON\UTCDateTime should be used instead).

## Klassenbeschreibung

final class MongoDB\BSON\Timestamp implements MongoDB\BSON\TimestampInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final public function __construct(int `$increment`, int `$timestamp`)
final public function getIncrement(): int
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\TimestampInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\Timestamp::__construct

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__construct — Construct a new Timestamp

### Beschreibung

final public function MongoDB\BSON\Timestamp::__construct(int `$increment`, int `$timestamp`)

### Parameter-Liste

`increment` (int)
  32-bit integer denoting the incrementing ordinal for operations within a given second.
`timestamp` (int)
  32-bit integer denoting seconds since the Unix epoch.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\Timestamp::__construct() example

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MongoDB\BSON\Timestamp)#1 (2) {
      ["increment"]=>
      int(1234)
      ["timestamp"]=>
      int(5678)
    }

### Siehe auch

- » BSON Types: Timestamps

# MongoDB\BSON\Timestamp::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp

### Beschreibung

final public function MongoDB\BSON\Timestamp::getIncrement(): int

The increment component of a Timestamp is its least significant 32 bits, which denotes the incrementing ordinal for operations within a given second. This value is read as an unsigned 32-bit integer with big-endian byte order.

> Hinweis: Da der Integer-Typ bei PHP vorzeichenbehaftet ist, könnten einige Werte, die von dieser Methode zurückgegeben werden, auf 32-Bit-Plattformen als negative Ganzzahlen erscheinen. Um eine Zeichenketten-Darstellung des Dezimalwertes ohne Vorzeichen zu erhalten, kann das Formatierungszeichen `"%u"` von sprintf() verwendet werden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the increment component of this Timestamp.

Warnung

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- » BSON Types: Timestamps

# MongoDB\BSON\Timestamp::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp

### Beschreibung

final public function MongoDB\BSON\Timestamp::getTimestamp(): int

The timestamp component of a Timestamp is its most significant 32 bits, which denotes the number of seconds since the Unix epoch. This value is read as an unsigned 32-bit integer with big-endian byte order.

> Hinweis: Da der Integer-Typ bei PHP vorzeichenbehaftet ist, könnten einige Werte, die von dieser Methode zurückgegeben werden, auf 32-Bit-Plattformen als negative Ganzzahlen erscheinen. Um eine Zeichenketten-Darstellung des Dezimalwertes ohne Vorzeichen zu erhalten, kann das Formatierungszeichen `"%u"` von sprintf() verwendet werden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the timestamp component of this Timestamp.

Warnung

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- » BSON Types: Timestamps

# MongoDB\BSON\Timestamp::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\Timestamp::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Timestamp.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\Timestamp::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__toString — Returns the string representation of this Timestamp

### Beschreibung

final public function MongoDB\BSON\Timestamp::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this Timestamp.

### Beispiele

Beispiel #1 MongoDB\BSON\Timestamp::__toString() example

    <?php

    $timestamp = new MongoDB\BSON\Timestamp(1234, 5678);
    var_dump((string) $timestamp);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(11) "[1234:5678]"

### Siehe auch

- » BSON Types: Timestamps

## Inhaltsverzeichnis

- MongoDB\BSON\Timestamp::__construct — Construct a new Timestamp
- MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp
- MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp
- MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Timestamp::__toString — Returns the string representation of this Timestamp

# The MongoDB\BSON\UTCDateTime class

(mongodb >=1.0.0)

## Einführung

Represents a » BSON date. The value is a 64-bit integer that represents the number of milliseconds since the Unix epoch (Jan 1, 1970). Negative values represent dates before 1970.

## Klassenbeschreibung

final class MongoDB\BSON\UTCDateTime implements MongoDB\BSON\UTCDateTimeInterface, MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final public function __construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)
final public function jsonSerialize(): mixed
final public function toDateTime(): DateTime
final public function toDateTimeImmutable(): DateTimeImmutable
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\UTCDateTimeInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\UTCDateTime::__construct

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime

### Beschreibung

final public function MongoDB\BSON\UTCDateTime::__construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)

### Parameter-Liste

`milliseconds` (int|MongoDB\BSON\Int64|DateTimeInterface|null)
  Number of milliseconds since the Unix epoch (Jan 1, 1970). Negative values represent dates before 1970. This value may be provided as a 64-bit int. For compatibility on 32-bit systems, this parameter may also be provided as a MongoDB\BSON\Int64. If the argument is a DateTimeInterface, the number of milliseconds since the Unix epoch will be derived from that value. If this argument is `null`, the current time will be used by default.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | The `milliseconds` no longer accepts a string or float argument.
PECL mongodb 1.20.0 | The `milliseconds` argument now accepts a MongoDB\BSON\Int64 object (for compatibility on 32-bit platforms). Specifying a string or float is deprecated.
PECL mongodb 1.2.0 | The `milliseconds` argument is optional and defaults to `null` (i.e. current time). The argument also accepts a DateTimeInterface, which may be used to derive the number of milliseconds since the Unix epoch. Previously, only int, float, and string types were accepted.

### Beispiele

Beispiel #1 MongoDB\BSON\UTCDateTime::__construct() example

    <?php

    var_dump(new MongoDB\BSON\UTCDateTime);

    var_dump(new MongoDB\BSON\UTCDateTime(new DateTime));

    var_dump(new MongoDB\BSON\UTCDateTime(1416445411987));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1484852905560"
    }
    object(MongoDB\BSON\UTCDateTime)#1 (1) {
      ["milliseconds"]=>
      string(13) "1416445411987"
    }

### Siehe auch

- » BSON Types: Date

# MongoDB\BSON\UTCDateTime::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\UTCDateTime::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\UTCDateTime.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\UTCDateTime::toDateTime

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::toDateTime — Returns the DateTime representation of this UTCDateTime

### Beschreibung

final public function MongoDB\BSON\UTCDateTime::toDateTime(): DateTime

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the DateTime representation of this UTCDateTime. The returned DateTime will use the UTC time zone.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\UTCDatetime::toDateTime() example

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTime();
    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Siehe auch

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Returns the DateTimeImmutable representation of this UTCDateTime
- » BSON Types: Date

# MongoDB\BSON\UTCDateTime::toDateTimeImmutable

(mongodb >=1.20.0)

MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTime

### Beschreibung

final public function MongoDB\BSON\UTCDateTime::toDateTimeImmutable(): DateTimeImmutable

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the DateTimeImmutable representation of this UTCDateTime. The returned DateTimeImmutable will use the UTC time zone.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Beispiele

Beispiel #1 MongoDB\BSON\UTCDatetime::toDateTimeImmutable() example

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    $datetime = $utcdatetime->toDateTimeImmutable();
    var_dump($datetime->format('r'));
    var_dump($datetime->format('U.u'));
    var_dump($datetime->getTimezone());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(31) "Thu, 20 Nov 2014 01:03:31 +0000"
    string(17) "1416445411.987000"
    object(DateTimeZone)#3 (2) {
      ["timezone_type"]=>
      int(1)
      ["timezone"]=>
      string(6) "+00:00"
    }

### Siehe auch

- MongoDB\BSON\UTCDateTime::toDateTime() - Returns the DateTime representation of this UTCDateTime
- » BSON Types: Date

# MongoDB\BSON\UTCDateTime::__toString

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__toString — Returns the string representation of this UTCDateTime

### Beschreibung

final public function MongoDB\BSON\UTCDateTime::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this UTCDateTime.

### Beispiele

Beispiel #1 MongoDB\BSON\UTCDateTime::__toString() example

    <?php

    $utcdatetime = new MongoDB\BSON\UTCDateTime(1416445411987);
    var_dump((string) $utcdatetime);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(13) "1416445411987"

### Siehe auch

- » BSON Types: Date

## Inhaltsverzeichnis

- MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime
- MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\UTCDateTime::toDateTime — Returns the DateTime representation of this UTCDateTime
- MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTime
- MongoDB\BSON\UTCDateTime::__toString — Returns the string representation of this UTCDateTime

# The MongoDB\BSON\Type interface

(mongodb >=1.0.0)

## Einführung

Abstract base interface that should not be implemented directly.

## Interface-Übersicht

class MongoDB\BSON\Type {
}

This interface has no methods. Its only purpose is to be the base interface for all BSON type classes.

# The MongoDB\BSON\Persistable interface

(mongodb >=1.0.0)

## Einführung

Classes may implement this interface to take advantage of automatic ODM (object document mapping) behavior in the extension. During serialization, the extension will inject a __pclass property containing the PHP class name into the data returned by MongoDB\BSON\Serializable::bsonSerialize(). During unserialization, the same __pclass property will then be used to infer the PHP class (independent of any type map configuration) to be constructed before MongoDB\BSON\Unserializable::bsonUnserialize() is invoked. See Persisting Data for additional information.

> Hinweis: Even if MongoDB\BSON\Serializable::bsonSerialize() would return a sequential array, injection of the __pclass property will cause the object to be serialized as a BSON document.

## Interface-Übersicht

class MongoDB\BSON\Persistable implements MongoDB\BSON\Unserializable, MongoDB\BSON\Serializable {
/* Methoden */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document
/* Geerbte Methoden */
abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void
}

# MongoDB\BSON\Persistable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Persistable::bsonSerialize — Provides an array or document to serialize as BSON

### Beschreibung

abstract public function MongoDB\BSON\Persistable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document

Called during serialization of the object to BSON. The method must return an array, stdClass, or MongoDB\BSON\Document.

The return value will always be serialized as a BSON document. The serialized document will include a field containing the class name of the object. For this reason, it is not possible to return a MongoDB\BSON\PackedArray instance in this method.

Users are encouraged to include an _id property (e.g. a MongoDB\BSON\ObjectId initialized in the constructor) when returning data for a BSON root document. In the absence of an _id property, the extension or server will generate a MongoDB\BSON\ObjectId for insert or upsert operations, respectively.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array, stdClass, or MongoDB\BSON\Document to be serialized as a BSON document.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.17.0 | This method may now also return MongoDB\BSON\Document instances in addition to array and stdClass.

### Siehe auch

- MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
- MongoDB\BSON\Unserializable::bsonUnserialize() - Constructs the object from a BSON array or document
- MongoDB\BSON\Persistable
- Persisting Data

## Inhaltsverzeichnis

- MongoDB\BSON\Persistable::bsonSerialize — Provides an array or document to serialize as BSON

# The MongoDB\BSON\Serializable interface

(mongodb >=1.0.0)

## Einführung

Classes that implement this interface may return data to be serialized as a BSON array or document in lieu of the object's public properties.

## Interface-Übersicht

class MongoDB\BSON\Serializable implements MongoDB\BSON\Type {
/* Methoden */
abstract public function bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\BSON\Serializable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

### Beschreibung

abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray

Called during serialization of the object to BSON. The method must return an array, stdClass, MongoDB\BSON\Document, or MongoDB\BSON\PackedArray.

Root documents (e.g. a MongoDB\BSON\Serializable passed to MongoDB\BSON\Document::fromPHP()) will always be serialized as a BSON document. For field values, associative arrays and stdClass instances will be serialized as a BSON document and sequential arrays (i.e. sequential, numeric indexes starting at `0`) will be serialized as a BSON array.

Users are encouraged to include an _id property (e.g. a MongoDB\BSON\ObjectId initialized in the constructor) when returning data for a BSON root document. In the absence of an _id property, the extension or server will generate a MongoDB\BSON\ObjectId for insert or upsert operations, respectively.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array, stdClass, MongoDB\BSON\Document, or MongoDB\BSON\PackedArray to be serialized as a BSON array or document.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.17.0 | The return type was changed from array|object. Instead of object, the return type now specifies stdClass. Classes that implement this interface must be changed to no longer declare an object return type. As the return type is tentative, a deprecation warning is emitted on PHP 8.1 and newer. In addition to the changes above, the extension now also supports returning instances of MongoDB\BSON\Document and MongoDB\BSON\PackedArray. Please note that any MongoDB\BSON\PackedArray instances returned are silently converted to objects when stored as root documents. They are stored as arrays when used as an embedded field value.

### Beispiele

Beispiel #1 MongoDB\BSON\Serializable::bsonSerialize() returning an associative array for root document

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        private $id;

        function __construct()
        {
            $this->id = new MongoDB\BSON\ObjectId;
        }

        function bsonSerialize(): array
        {
            return ['_id' => $this->id, 'foo' => 'bar'];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyDocument)->toRelaxedExtendedJSON(), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    { "_id" : { "$oid" : "56cccdcada14d8755a58c591" }, "foo" : "bar" }

Beispiel #2 MongoDB\BSON\Serializable::bsonSerialize() returning a sequential array for root document

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyArray)->toRelaxedExtendedJSON(), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    { "0" : 1, "1" : 2, "2" : 3 }

Beispiel #3 MongoDB\BSON\Serializable::bsonSerialize() returning an associative array for document field

    <?php

    class MyDocument implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return ['foo' => 'bar'];
        }
    }

    $value = ['document' => new MyDocument];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    { "document" : { "foo" : "bar" } }

Beispiel #4 MongoDB\BSON\Serializable::bsonSerialize() returning a sequential array for document field

    <?php

    class MyArray implements MongoDB\BSON\Serializable
    {
        function bsonSerialize(): array
        {
            return [1, 2, 3];
        }
    }

    $value = ['array' => new MyArray];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    { "array" : [ 1, 2, 3 ] }

### Siehe auch

- MongoDB\BSON\Unserializable::bsonUnserialize() - Constructs the object from a BSON array or document
- MongoDB\BSON\Persistable
- Persisting Data

## Inhaltsverzeichnis

- MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

# The MongoDB\BSON\Unserializable interface

(mongodb >=1.0.0)

## Einführung

Classes that implement this interface may be specified in a type map for unserializing BSON arrays and documents (both root and embedded).

## Interface-Übersicht

class MongoDB\BSON\Unserializable {
/* Methoden */
abstract public function bsonUnserialize(array `$data`): void
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\BSON\Unserializable::bsonUnserialize

(mongodb >=1.0.0)

MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document

### Beschreibung

abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void

Called during unserialization of the object from BSON. The properties of the BSON array or document will be passed to the method as an array.

Remember to check for an _id property when handling data from a BSON document.

> Hinweis: This method acts as the constructor of the object. The __construct() method will not be called after this method.

### Parameter-Liste

`data` (array)
  Properties within the BSON array or document.

### Rückgabewerte

The return value from this method is ignored.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.

### Beispiele

Beispiel #1 MongoDB\BSON\Unserializable::bsonUnserialize() example

    <?php

    class MyDocument implements MongoDB\BSON\Unserializable
    {
        private $data = [];

        function bsonUnserialize(array $data): void
        {
            $this->data = $data;
        }
    }

    $bson = MongoDB\BSON\Document::fromJSON('{ "foo": "bar" }');

    var_dump($bson->toPHP(['root' => 'MyDocument']));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(MyDocument)#1 (1) {
      ["data":"MyDocument":private]=>
      array(1) {
        ["foo"]=>
        string(3) "bar"
      }
    }

### Siehe auch

- MongoDB\BSON\Serializable::bsonSerialize() - Provides an array or document to serialize as BSON
- MongoDB\BSON\Persistable
- Persisting Data

## Inhaltsverzeichnis

- MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document

# The MongoDB\BSON\BinaryInterface interface

(mongodb >=1.3.0)

## Einführung

This interface is implemented by MongoDB\BSON\Binary to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\BSON\BinaryInterface {
/* Methoden */
abstract public function getData(): string
abstract public function getType(): int
abstract public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\BSON\BinaryInterface::getData

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getData — Returns the BinaryInterface's data

### Beschreibung

abstract public function MongoDB\BSON\BinaryInterface::getData(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the BinaryInterface's data.

### Siehe auch

- MongoDB\BSON\Binary::getData() - Returns the Binary's data

# MongoDB\BSON\BinaryInterface::getType

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getType — Returns the BinaryInterface's type

### Beschreibung

abstract public function MongoDB\BSON\BinaryInterface::getType(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the BinaryInterface's type.

### Siehe auch

- MongoDB\BSON\Binary::getType() - Returns the Binary's type

# MongoDB\BSON\BinaryInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::__toString — Returns the BinaryInterface's data

### Beschreibung

abstract public function MongoDB\BSON\BinaryInterface::__toString(): string

Diese Methode ist ein Alias für: MongoDB\BSON\BinaryInterface::getData().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the BinaryInterface's data.

### Siehe auch

- MongoDB\BSON\BinaryInterface::getData() - Returns the BinaryInterface's data
- MongoDB\BSON\Binary::__toString() - Returns the Binary's data

## Inhaltsverzeichnis

- MongoDB\BSON\BinaryInterface::getData — Returns the BinaryInterface's data
- MongoDB\BSON\BinaryInterface::getType — Returns the BinaryInterface's type
- MongoDB\BSON\BinaryInterface::__toString — Returns the BinaryInterface's data

# The MongoDB\BSON\Decimal128Interface interface

(mongodb >=1.3.0)

## Einführung

This interface is implemented by MongoDB\BSON\Decimal128 to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\BSON\Decimal128Interface {
/* Methoden */
abstract public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\BSON\Decimal128Interface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface

### Beschreibung

abstract public function MongoDB\BSON\Decimal128Interface::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this Decimal128Interface.

### Siehe auch

- MongoDB\BSON\Decimal128::__toString() - Returns the string representation of this Decimal128

## Inhaltsverzeichnis

- MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface

# The MongoDB\BSON\JavascriptInterface interface

(mongodb >=1.3.0)

## Einführung

This interface is implemented by MongoDB\BSON\Javascript to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\BSON\JavascriptInterface {
/* Methoden */
abstract public function getCode(): string
abstract public function getScope(): ?object
abstract public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\BSON\JavascriptInterface::getCode

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getCode — Returns the JavascriptInterface's code

### Beschreibung

abstract public function MongoDB\BSON\JavascriptInterface::getCode(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the JavascriptInterface's code.

### Siehe auch

- MongoDB\BSON\Javascript::getCode() - Returns the Javascript's code

# MongoDB\BSON\JavascriptInterface::getScope

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getScope — Returns the JavascriptInterface's scope document

### Beschreibung

abstract public function MongoDB\BSON\JavascriptInterface::getScope(): ?object

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the JavascriptInterface's scope document.

### Siehe auch

- MongoDB\BSON\Javascript::getScope() - Returns the Javascript's scope document

# MongoDB\BSON\JavascriptInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::__toString — Returns the JavascriptInterface's code

### Beschreibung

abstract public function MongoDB\BSON\JavascriptInterface::__toString(): string

Diese Methode ist ein Alias für: MongoDB\BSON\JavascriptInterface::getCode().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the JavascriptInterface's code.

### Siehe auch

- MongoDB\BSON\JavascriptInterface::getCode() - Returns the JavascriptInterface's code
- MongoDB\BSON\Javascript::__toString() - Returns the Javascript's code

## Inhaltsverzeichnis

- MongoDB\BSON\JavascriptInterface::getCode — Returns the JavascriptInterface's code
- MongoDB\BSON\JavascriptInterface::getScope — Returns the JavascriptInterface's scope document
- MongoDB\BSON\JavascriptInterface::__toString — Returns the JavascriptInterface's code

# The MongoDB\BSON\MaxKeyInterface interface

(mongodb >=1.3.0)

## Einführung

This interface is implemented by MongoDB\BSON\MaxKey to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\BSON\MaxKeyInterface {
}

This interface has no methods.

# The MongoDB\BSON\MinKeyInterface interface

(mongodb >=1.3.0)

## Einführung

This interface is implemented by MongoDB\BSON\MinKey to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\BSON\MinKeyInterface {
}

This interface has no methods.

# The MongoDB\BSON\ObjectIdInterface interface

(mongodb >=1.3.0)

## Einführung

This interface is implemented by MongoDB\BSON\ObjectId to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\BSON\ObjectIdInterface {
/* Methoden */
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\BSON\ObjectIdInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface

### Beschreibung

abstract public function MongoDB\BSON\ObjectIdInterface::getTimestamp(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the timestamp component of this ObjectIdInterface.

### Siehe auch

- MongoDB\BSON\ObjectId::getTimestamp() - Returns the timestamp component of this ObjectId

# MongoDB\BSON\ObjectIdInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexadecimal representation of this ObjectIdInterface

### Beschreibung

abstract public function MongoDB\BSON\ObjectIdInterface::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hexadecimal representation of this ObjectIdInterface.

### Siehe auch

- MongoDB\BSON\ObjectId::__toString() - Returns the hexadecimal representation of this ObjectId

## Inhaltsverzeichnis

- MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface
- MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexadecimal representation of this ObjectIdInterface

# The MongoDB\BSON\RegexInterface interface

(mongodb >=1.3.0)

## Einführung

This interface is implemented by MongoDB\BSON\Regex to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\BSON\RegexInterface {
/* Methoden */
abstract public function getFlags(): string
abstract public function getPattern(): string
abstract public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\BSON\RegexInterface::getFlags

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getFlags — Returns the RegexInterface's flags

### Beschreibung

abstract public function MongoDB\BSON\RegexInterface::getFlags(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the RegexInterface's flags.

### Siehe auch

- MongoDB\BSON\Regex::getFlags() - Returns the Regex's flags

# MongoDB\BSON\RegexInterface::getPattern

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getPattern — Returns the RegexInterface's pattern

### Beschreibung

abstract public function MongoDB\BSON\RegexInterface::getPattern(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the RegexInterface's pattern.

### Siehe auch

- MongoDB\BSON\Regex::getPattern() - Returns the Regex's pattern

# MongoDB\BSON\RegexInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::__toString — Returns the string representation of this RegexInterface

### Beschreibung

abstract public function MongoDB\BSON\RegexInterface::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this RegexInterface.

### Siehe auch

- MongoDB\BSON\Regex::__toString() - Returns the string representation of this Regex

## Inhaltsverzeichnis

- MongoDB\BSON\RegexInterface::getFlags — Returns the RegexInterface's flags
- MongoDB\BSON\RegexInterface::getPattern — Returns the RegexInterface's pattern
- MongoDB\BSON\RegexInterface::__toString — Returns the string representation of this RegexInterface

# The MongoDB\BSON\TimestampInterface interface

(mongodb >=1.3.0)

## Einführung

This interface is implemented by MongoDB\BSON\Timestamp to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\BSON\TimestampInterface {
/* Methoden */
abstract public function getIncrement(): int
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\BSON\TimestampInterface::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getIncrement — Returns the increment component of this TimestampInterface

### Beschreibung

abstract public function MongoDB\BSON\TimestampInterface::getIncrement(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the increment component of this TimestampInterface.

Warnung

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

### Siehe auch

- MongoDB\BSON\Timestamp::getIncrement() - Returns the increment component of this Timestamp

# MongoDB\BSON\TimestampInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getTimestamp — Returns the timestamp component of this TimestampInterface

### Beschreibung

abstract public function MongoDB\BSON\TimestampInterface::getTimestamp(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the timestamp component of this TimestampInterface.

Warnung

On 32-bit systems this method may return a negative number. Although the increment and timestamp parts of the BSON timestamp type consists of two unsigned 32-bit values, PHP can not represent these on 32-bit platforms.

### Siehe auch

- MongoDB\BSON\Timestamp::getTimestamp() - Returns the timestamp component of this Timestamp

# MongoDB\BSON\TimestampInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::__toString — Returns the string representation of this TimestampInterface

### Beschreibung

abstract public function MongoDB\BSON\TimestampInterface::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this TimestampInterface.

### Siehe auch

- MongoDB\BSON\Timestamp::__toString() - Returns the string representation of this Timestamp

## Inhaltsverzeichnis

- MongoDB\BSON\TimestampInterface::getIncrement — Returns the increment component of this TimestampInterface
- MongoDB\BSON\TimestampInterface::getTimestamp — Returns the timestamp component of this TimestampInterface
- MongoDB\BSON\TimestampInterface::__toString — Returns the string representation of this TimestampInterface

# The MongoDB\BSON\UTCDateTimeInterface interface

(mongodb >=1.3.0)

## Einführung

This interface is implemented by MongoDB\BSON\UTCDateTime to be used as a parameter, return, or property type in userland classes.

## Klassenbeschreibung

class MongoDB\BSON\UTCDateTimeInterface {
/* Methoden */
abstract public function toDateTime(): DateTime
abstract public function toDateTimeImmutable(): DateTimeImmutable
abstract public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\BSON\UTCDateTimeInterface::toDateTime

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface

### Beschreibung

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTime(): DateTime

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the DateTime representation of this UTCDateTimeInterface. The returned DateTime should use the UTC time zone.

### Siehe auch

- MongoDB\BSON\UTCDateTime::toDateTime() - Returns the DateTime representation of this UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable

(mongodb >=2.0.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTimeInterface

### Beschreibung

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable(): DateTimeImmutable

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the DateTimeImmutable representation of this UTCDateTimeInterface. The returned DateTimeImmutable will use the UTC time zone.

### Siehe auch

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Returns the DateTimeImmutable representation of this UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface

### Beschreibung

abstract public function MongoDB\BSON\UTCDateTimeInterface::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this UTCDateTimeInterface.

### Siehe auch

- MongoDB\BSON\UTCDateTime::__toString() - Returns the string representation of this UTCDateTime

## Inhaltsverzeichnis

- MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface

# The MongoDB\BSON\DBPointer class

(mongodb >=1.4.0)

## Einführung

BSON type for the "DBPointer" type. This BSON type is deprecated, and this class can not be instantiated. It will be created from a BSON DBPointer type while converting BSON to PHP, and can also be converted back into BSON while storing documents in the database.

## Klassenbeschreibung

final class MongoDB\BSON\DBPointer implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

# MongoDB\BSON\DBPointer::__construct

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__construct — Construct a new DBPointer (unused)

### Beschreibung

final private function MongoDB\BSON\DBPointer::__construct()

MongoDB\BSON\DBPointer objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- » BSON Types

# MongoDB\BSON\DBPointer::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\DBPointer::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\DBPointer.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\DBPointer::__toString

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__toString — Returns an empty string

### Beschreibung

final public function MongoDB\BSON\DBPointer::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an empty string.

### Siehe auch

- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\DBPointer::__construct — Construct a new DBPointer (unused)
- MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\DBPointer::__toString — Returns an empty string

# The MongoDB\BSON\Int64 class

(mongodb >=1.5.0)

## Einführung

BSON type for a 64-bit integer. When decoding BSON to PHP data, this class is used when a 64-bit integer cannot be represented as a PHP integer on 32-bit platforms. These objects support overloaded arithmetic, bitwise, and comparison operators.

When working with raw BSON data through the MongoDB\BSON\Document, MongoDB\BSON\PackedArray, and MongoDB\BSON\Iterator classes, any 64-bit integer will be returned as an instance of this class, regardless of platform and whether the value can be represented as a PHP integer. This ensures that values can be roundtripped without changing the type.

During BSON encoding, objects of this class will convert back to a 64-bit integer type, even when the value would fit in a 32-bit integer. This allows explicitly storing values as 64-bit integers in BSON.

## Klassenbeschreibung

final class MongoDB\BSON\Int64 implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final public function __construct(int|string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.16.0 | The class can now be instantiated on all platforms. Added support for overloaded arithmetic, bitwise, and comparison operators.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

# MongoDB\BSON\Int64::__construct

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__construct — Construct a new Int64

### Beschreibung

final public function MongoDB\BSON\Int64::__construct(int|string `$value`)

Creates a new MongoDB\BSON\Int64 instance for the given integer value.

### Parameter-Liste

`value` (int|string)
  The value to assign to the Int64 instance. This value can be provided as an int or string, the latter being required on 32-bit platforms to represent 64-bit values.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.16.0 | This method was made public to support creating Int64 instances when working with raw BSON.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.
- Throws MongoDB\Driver\Exception\InvalidArgumentException if string `value` cannot be parsed as a 64-bit integer.

### Siehe auch

- » BSON Types

# MongoDB\BSON\Int64::jsonSerialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\Int64::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Int64.

> Hinweis: The output is consistent with the MongoDB\BSON\toCanonicalExtendedJSON() function, which uses the » canonical extended JSON format. This differs from other BSON classes, which use the driver-specific legacy extended JSON format (MongoDB\BSON\toJSON()), in order to ensure that the 64-bit integer value is correctly represented on 32-bit platforms.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\Int64::__toString

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64

### Beschreibung

final public function MongoDB\BSON\Int64::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this Int64.

### Beispiele

Beispiel #1 MongoDB\BSON\Int64::__toString() example

    <?php

    $int64 = new MongoDB\BSON\Int64('9223372036854775807');

    var_dump((string) $int64);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(19) "9223372036854775807"

### Siehe auch

- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\Int64::__construct — Construct a new Int64
- MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64

# The MongoDB\BSON\Symbol class

(mongodb >=1.4.0)

## Einführung

BSON type for the "Symbol" type. This BSON type is deprecated, and this class can not be instantiated. It will be created from a BSON symbol type while converting BSON to PHP, and can also be converted back into BSON while storing documents in the database.

## Klassenbeschreibung

final class MongoDB\BSON\Symbol implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

# MongoDB\BSON\Symbol::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__construct — Construct a new Symbol (unused)

### Beschreibung

final private function MongoDB\BSON\Symbol::__construct()

MongoDB\BSON\Symbol objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- » BSON Types

# MongoDB\BSON\Symbol::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\Symbol::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Symbol.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\Symbol::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__toString — Returns the Symbol as a string

### Beschreibung

final public function MongoDB\BSON\Symbol::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string representation of this Symbol.

### Siehe auch

- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\Symbol::__construct — Construct a new Symbol (unused)
- MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Symbol::__toString — Returns the Symbol as a string

# The MongoDB\BSON\Undefined class

(mongodb >=1.4.0)

## Einführung

BSON type for the "Undefined" type. This BSON type is deprecated, and this class can not be instantiated. It will be created from a BSON undefined type while converting BSON to PHP, and can also be converted back into BSON while storing documents in the database.

## Klassenbeschreibung

final class MongoDB\BSON\Undefined implements MongoDB\BSON\Type, JsonSerializable, Stringable {
/* Methoden */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse implementiert nicht mehr die Serializable-Schnittstelle.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

# MongoDB\BSON\Undefined::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__construct — Construct a new Undefined (unused)

### Beschreibung

final private function MongoDB\BSON\Undefined::__construct()

MongoDB\BSON\Undefined objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- » BSON Types

# MongoDB\BSON\Undefined::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON

### Beschreibung

final public function MongoDB\BSON\Undefined::jsonSerialize(): mixed

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns data which can be serialized by json_encode() to produce an extended JSON representation of the MongoDB\BSON\Undefined.

> Hinweis: Die Ausgabe entspricht der Funktion MongoDB\BSON\toJSON(), die das alte, treiberspezifische erweiterte JSON-Format verwendet. Dies entspricht nicht unbedingt den erweiterten JSON-Formaten » relaxed oder » canonical, die von MongoDB\BSON\toRelaxedExtendedJSON() bzw. MongoDB\BSON\toCanonicalExtendedJSON() verwendet werden.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- JsonSerializable::jsonSerialize() - Gibt die Daten an, die in JSON serialisiert werden sollen
- json_encode() - Liefert die JSON-Darstellung eines Wertes
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » MongoDB Extended JSON

# MongoDB\BSON\Undefined::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__toString — Returns an empty string

### Beschreibung

final public function MongoDB\BSON\Undefined::__toString(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an empty string.

### Siehe auch

- » BSON Types

## Inhaltsverzeichnis

- MongoDB\BSON\Undefined::__construct — Construct a new Undefined (unused)
- MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Undefined::__toString — Returns an empty string

# Monitoring classes and subscriber functions

## Inhaltsverzeichnis

- Funktionen
- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\LogSubscriber
- MongoDB\Driver\Monitoring\SDAMSubscriber
- MongoDB\Driver\Monitoring\Subscriber

# Funktionen

# MongoDB\Driver\Monitoring\addSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\addSubscriber — Registers a monitoring event subscriber globally

### Beschreibung

function MongoDB\Driver\Monitoring\addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Registers a monitoring event subscriber globally. The subscriber will be notified of all events in the extension for any Manager.

> Hinweis: If `subscriber` is already registered globally, this function is a no-op. If `subscriber` is also registered with one or more Managers, it will still only be notified once of each event for each Manager.

### Parameter-Liste

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  A monitoring event subscriber to register globally.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\removeSubscriber() - Unregisters a monitoring event subscriber globally
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\removeSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\removeSubscriber — Unregisters a monitoring event subscriber globally

### Beschreibung

function MongoDB\Driver\Monitoring\removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void

Unregisters a monitoring event subscriber globally.

> Hinweis: If `subscriber` is not already registered globally, this function is a no-op.

### Parameter-Liste

`subscriber` (MongoDB\Driver\Monitoring\Subscriber)
  A monitoring event subscriber to unregister globally.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Monitoring\Subscriber
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Manager::removeSubscriber() - Unregisters a monitoring event subscriber with this Manager
- Application Performance Monitoring (APM)

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\addSubscriber — Registers a monitoring event subscriber globally
- MongoDB\Driver\Monitoring\removeSubscriber — Unregisters a monitoring event subscriber globally

# The MongoDB\Driver\Monitoring\CommandFailedEvent class

(mongodb >=1.3.0)

## Einführung

The MongoDB\Driver\Monitoring\CommandFailedEvent class encapsulates information about a failed command.

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\CommandFailedEvent {
/* Eigenschaften */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly Exception $error;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Methoden */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Eigenschaften

host
  The hostname of the server that executed the command.
port
  The port of the server that executed the command.
commandName
  The command name.
databaseName
  The database name.
duration
  The duration of the command in microseconds. The duration is a calculated value that includes the time to send the message and receive the response from the server.
error
  The exception that was thrown when the command failed.
reply
  The failure reply document returned by the server.
operationId
  The operation ID. This may be used to link events together such as bulk writes, which may dispatch multiple commands.
requestId
  The request ID. This may be used to associate this MongoDB\Driver\Monitoring\CommandFailedEvent with a corresponding MongoDB\Driver\Monitoring\CommandStartedEvent.
serviceId
  The service ID, or `null` if the server does not support it (i.e. not using load-balanced mode).
serverConnectionId
  The server connection ID, or `null` if not available.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties. The duration property replaces the getDurationMicros() method.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Returns the command name

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName(): string

Returns the command name (e.g. `"find"`, `"aggregate"`).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command name.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Returns the database on which the command was executed

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the database on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Returns the command's duration in microseconds

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros(): int

The command's duration is a calculated value that includes the time to send the message and receive the reply from the server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command's duration in microseconds.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getError

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Returns the Exception associated with the failed command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getError(): Exception

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Exception associated with the failed command.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Returns the server hostname for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getHost(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of the server on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId(): string

The operation ID is generated by the extension and may be used to link events together such as bulk write operations, which may have been split across several commands at the protocol level.

> Hinweis: Since multiple commands may share the same operation ID, it is not reliable to use this value to associate event objects with each other. The request ID returned by MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() should be used instead.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command's operation ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Returns the command's request ID
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Returns the server port for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getPort(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port of the server on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getReply

(mongodb >=1.5.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getReply(): object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command reply document as a stdClass object.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)
- Persisting Data

# MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Returns the command's request ID

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId(): string

The request ID is generated by the extension and may be used to associate this MongoDB\Driver\Monitoring\CommandFailedEvent with a previous MongoDB\Driver\Monitoring\CommandStartedEvent.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command's request ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Returns the command's request ID
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Returns the Server on which the command was executed

Warnung

This method has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\Driver\Monitoring\CommandFailedEvent::getHost() and MongoDB\Driver\Monitoring\CommandFailedEvent::getPort() instead.

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the MongoDB\Driver\Server on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Methode wurde entfernt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Returns the Server on which the command was executed
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Returns the server connection ID for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId(): ?int

Returns the server connection ID for the command. The server connection ID is distinct from server (i.e. MongoDB\Driver\Monitoring\CommandFailedEvent::getServer()) and is returned in the "connectionId" field of a `hello` command response MongoDB 4.2+.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the server connection ID, or `null` if it is not available.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Returns the load balancer service ID for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

When the driver is connected to a MongoDB cluster through a load balancer, the service ID corresponds to the `serviceId` field in the `hello` command response.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the load balancer service ID, or `null` if the driver is not connected to a load balancer.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Returns the command name
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDatabaseName — Returns the database on which the command was executed
- MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Returns the command's duration in microseconds
- MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Returns the Exception associated with the failed command
- MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Returns the server hostname for the command
- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Returns the server port for the command
- MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document
- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Returns the command's request ID
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Returns the Server on which the command was executed
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Returns the server connection ID for the command
- MongoDB\Driver\Monitoring\CommandFailedEvent::getServiceId — Returns the load balancer service ID for the command

# The MongoDB\Driver\Monitoring\CommandStartedEvent class

(mongodb >=1.3.0)

## Einführung

The MongoDB\Driver\Monitoring\CommandStartedEvent class encapsulates information about a started command.

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\CommandStartedEvent {
/* Eigenschaften */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly object $command;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Methoden */
final public function getCommand(): object
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Eigenschaften

host
  The hostname of the server that executed the command.
port
  The port of the server that executed the command.
commandName
  The command name.
databaseName
  The database name.
command
  The command document.
operationId
  The operation ID. This may be used to link events together such as bulk writes, which may dispatch multiple commands.
requestId
  The request ID. This may be used to associate this MongoDB\Driver\Monitoring\CommandStartedEvent with a corresponding MongoDB\Driver\Monitoring\CommandSucceededEvent or MongoDB\Driver\Monitoring\CommandFailedEvent.
serviceId
  The service ID, or `null` if the server does not support it (i.e. not using load-balanced mode).
serverConnectionId
  The server connection ID, or `null` if not available.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Returns the command document

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand(): object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command document as a stdClass object.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)
- Persisting Data

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName(): string

Returns the command name (e.g. `"find"`, `"aggregate"`).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command name.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Returns the database on which the command was executed

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the database on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Returns the server hostname for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getHost(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of the server on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId(): string

The operation ID is generated by the extension and may be used to link events together such as bulk write operations, which may have been split across several commands at the protocol level.

> Hinweis: Since multiple commands may share the same operation ID, it is not reliable to use this value to associate event objects with each other. The request ID returned by MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() should be used instead.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command's operation ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId() - Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId() - Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Returns the command's request ID
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Returns the server port for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getPort(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port of the server on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId(): string

The request ID is generated by the extension and may be used to associate this MongoDB\Driver\Monitoring\CommandStartedEvent with a later MongoDB\Driver\Monitoring\CommandFailedEvent or MongoDB\Driver\Monitoring\CommandSucceededEvent.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command's request ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId() - Returns the command's request ID
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Returns the command's request ID
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Returns the Server on which the command was executed

Warnung

This method has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\Driver\Monitoring\CommandStartedEvent::getHost() and MongoDB\Driver\Monitoring\CommandStartedEvent::getPort() instead.

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the MongoDB\Driver\Server on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Methode wurde entfernt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandFailedEvent::getServer() - Returns the Server on which the command was executed
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer() - Returns the Server on which the command was executed
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Returns the server connection ID for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId(): ?int

Returns the server connection ID for the command. The server connection ID is distinct from server (i.e. MongoDB\Driver\Monitoring\CommandStartedEvent::getServer()) and is returned in the "connectionId" field of a `hello` command response MongoDB 4.2+.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the server connection ID, or `null` if it is not available.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Returns the load balancer service ID for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId(): ?MongoDB\BSON\ObjectId

When the driver is connected to a MongoDB cluster through a load balancer, the service ID corresponds to the `serviceId` field in the `hello` command response.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the load balancer service ID, or `null` if the driver is not connected to a load balancer.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Returns the command document
- MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name
- MongoDB\Driver\Monitoring\CommandStartedEvent::getDatabaseName — Returns the database on which the command was executed
- MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Returns the server hostname for the command
- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Returns the server port for the command
- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Returns the Server on which the command was executed
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Returns the server connection ID for the command
- MongoDB\Driver\Monitoring\CommandStartedEvent::getServiceId — Returns the load balancer service ID for the command

# The MongoDB\Driver\Monitoring\CommandSucceededEvent class

(mongodb >=1.3.0)

## Einführung

The MongoDB\Driver\Monitoring\CommandSucceededEvent class encapsulates information about a successful command.

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\CommandSucceededEvent {
/* Eigenschaften */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* Methoden */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## Eigenschaften

host
  The hostname of the server that executed the command.
port
  The port of the server that executed the command.
commandName
  The command name.
databaseName
  The database name.
duration
  The duration of the command in microseconds. The duration is a calculated value that includes the time to send the message and receive the response from the server.
reply
  The reply document returned by the server.
operationId
  The operation ID. This may be used to link events together such as bulk writes, which may dispatch multiple commands.
requestId
  The request ID. This may be used to associate this MongoDB\Driver\Monitoring\CommandSucceededEvent with a corresponding MongoDB\Driver\Monitoring\CommandStartedEvent.
serviceId
  The service ID, or `null` if the server does not support it (i.e. not using load-balanced mode).
serverConnectionId
  The server connection ID, or `null` if not available.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties. The duration property replaces the getDurationMicros() method.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Returns the command name

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName(): string

Returns the command name (e.g. `"find"`, `"aggregate"`).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command name.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName

(mongodb >=1.19.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Returns the database on which the command was executed

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the database on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Returns the command's duration in microseconds

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros(): int

The command's duration is a calculated value that includes the time to send the message and receive the reply from the server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command's duration in microseconds.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Returns the server hostname for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of the server on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId(): string

The operation ID is generated by the extension and may be used to link events together such as bulk write operations, which may have been split across several commands at the protocol level.

> Hinweis: Since multiple commands may share the same operation ID, it is not reliable to use this value to associate event objects with each other. The request ID returned by MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() should be used instead.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command's operation ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId() - Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId() - Returns the command's request ID
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Returns the server port for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port of the server on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply(): object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command reply document as a stdClass object.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)
- Persisting Data

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Returns the command's request ID

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId(): string

The request ID is generated by the extension and may be used to associate this MongoDB\Driver\Monitoring\CommandSucceededEvent with a previous MongoDB\Driver\Monitoring\CommandStartedEvent.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the command's request ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId() - Returns the command's request ID
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Returns the Server on which the command was executed

Warnung

This method has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost() and MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort() instead.

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer(): MongoDB\Driver\Server

Returns the MongoDB\Driver\Server on which the command was executed.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the MongoDB\Driver\Server on which the command was executed.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Methode wurde entfernt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Returns the Server on which the command was executed
- MongoDB\Driver\Cursor::getServer() - Returns the server associated with this cursor
- MongoDB\Driver\WriteResult::getServer() - Returns the server associated with this write result
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Returns the server connection ID for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId(): ?int

Returns the server connection ID for the command. The server connection ID is distinct from server (i.e. MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer()) and is returned in the "connectionId" field of a `hello` command response MongoDB 4.2+.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the server connection ID, or `null` if it is not available.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId

(mongodb >=1.11.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Returns the load balancer service ID for the command

### Beschreibung

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId(): ?MongoDB\BSON\ObjectId

When the driver is connected to a MongoDB cluster through a load balancer, the service ID corresponds to the `serviceId` field in the `hello` command response.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the load balancer service ID, or `null` if the driver is not connected to a load balancer.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Returns the command name
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDatabaseName — Returns the database on which the command was executed
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Returns the command's duration in microseconds
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Returns the server hostname for the command
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Returns the server port for the command
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Returns the command's request ID
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Returns the Server on which the command was executed
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Returns the server connection ID for the command
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getServiceId — Returns the load balancer service ID for the command

# The MongoDB\Driver\Monitoring\ServerChangedEvent class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\Monitoring\ServerChangedEvent class encapsulates information about a changed server description. For example, a server's type changing from secondary to primary would cause its server description to change.

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\ServerChangedEvent {
/* Eigenschaften */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\ServerDescription $newDescription;
public readonly MongoDB\Driver\ServerDescription $previousDescription;
/* Methoden */
final public function getHost(): string
final public function getNewDescription(): MongoDB\Driver\ServerDescription
final public function getPort(): int
final public function getPreviousDescription(): MongoDB\Driver\ServerDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Eigenschaften

host
  The hostname of the server.
port
  The port of the server.
topologyId
  The topology ID.
newDescription
  The new server description.
previousDescription
  The previous server description.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Returns the hostname of the server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getHost(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of the server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Returns the new description for the server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription(): MongoDB\Driver\ServerDescription

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the new MongoDB\Driver\ServerDescription for the server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Returns the port on which this server is listening

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPort(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port on which this server is listening.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Returns the previous description for the server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription(): MongoDB\Driver\ServerDescription

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the previous MongoDB\Driver\ServerDescription for the server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Returns the topology ID associated with this server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the topology ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Returns the hostname of the server
- MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Returns the new description for the server
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPort — Returns the port on which this server is listening
- MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Returns the previous description for the server
- MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Returns the topology ID associated with this server

# The MongoDB\Driver\Monitoring\ServerClosedEvent class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\Monitoring\ServerClosedEvent class encapsulates information about a closed server. This corresponds to an existing server being removed from the topology.

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\ServerClosedEvent {
/* Eigenschaften */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Methoden */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Eigenschaften

host
  The hostname of the server.
port
  The port of the server.
topologyId
  The topology ID.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Returns the hostname of the server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getHost(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of the server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Returns the port on which this server is listening

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getPort(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port on which this server is listening.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Returns the topology ID associated with this server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the topology ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Returns the hostname of the server
- MongoDB\Driver\Monitoring\ServerClosedEvent::getPort — Returns the port on which this server is listening
- MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Returns the topology ID associated with this server

# The MongoDB\Driver\Monitoring\ServerOpeningEvent class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\Monitoring\ServerOpeningEvent class encapsulates information about an opened server. This corresponds to a new server being added to the topology.

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\ServerOpeningEvent {
/* Eigenschaften */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Methoden */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Eigenschaften

host
  The hostname of the server.
port
  The port of the server.
topologyId
  The topology ID.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Returns the hostname of the server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of the server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Returns the port on which this server is listening

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port on which this server is listening.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Returns the topology ID associated with this server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the topology ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Returns the hostname of the server
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort — Returns the port on which this server is listening
- MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Returns the topology ID associated with this server

# The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class encapsulates information about a failed server heartbeat (i.e. » hello command issued through » server monitoring).

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent {
/* Eigenschaften */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly Exception $error;
/* Methoden */
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Eigenschaften

host
  The hostname of the server.
port
  The port of the server.
awaited
  Whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return `false`.
duration
  The duration of the heartbeat in microseconds. The duration is a calculated value that includes the time to send the message and receive the response from the server.
error
  The exception that was thrown when the heartbeat failed.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties. The duration property replaces the getDurationMicros() method.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Returns the heartbeat's duration in microseconds

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros(): int

The heartbeat's duration is a calculated value that includes the time to send the message and receive the reply from the server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the heartbeat's duration in microseconds.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Returns the Exception associated with the failed heartbeat

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError(): Exception

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Exception associated with the failed heartbeat.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Returns the hostname of the server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of the server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Returns the port on which this server is listening

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port on which this server is listening.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited(): bool

Returns whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return `false`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `false`.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Returns the heartbeat's duration in microseconds
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Returns the Exception associated with the failed heartbeat
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Returns the hostname of the server
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort — Returns the port on which this server is listening
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

# The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class encapsulates information about a started server heartbeat (i.e. » hello command issued through » server monitoring).

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent {
/* Eigenschaften */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
/* Methoden */
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## Eigenschaften

host
  The hostname of the server.
port
  The port of the server.
awaited
  Whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return `false`.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Returns the hostname of the server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of the server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Returns the port on which this server is listening

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port on which this server is listening.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited(): bool

Returns whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return `false`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `false`.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Returns the hostname of the server
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort — Returns the port on which this server is listening
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

# The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class encapsulates information about a successful server heartbeat (i.e. » hello command issued through » server monitoring).

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent {
/* Eigenschaften */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly object $reply;
/* Methoden */
final public function getDurationMicros(): int
final public function getHost(): string
final public function getPort(): int
final public function getReply(): object
final public function isAwaited(): bool
}

## Eigenschaften

host
  The hostname of the server.
port
  The port of the server.
awaited
  Whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return `false`.
duration
  The duration of the heartbeat in microseconds. The duration is a calculated value that includes the time to send the message and receive the response from the server.
reply
  The reply document returned by the server.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties. The duration property replaces the getDurationMicros() method.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Returns the heartbeat's duration in microseconds

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros(): int

The heartbeat's duration is a calculated value that includes the time to send the message and receive the reply from the server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the heartbeat's duration in microseconds.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Returns the hostname of the server

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost(): string

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the hostname of the server.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Returns the port on which this server is listening

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort(): int

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the port on which this server is listening.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Returns the heartbeat reply document

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply(): object

The reply document will be converted from BSON to PHP using the default deserialization rules (e.g. BSON documents will be converted to stdClass).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the heartbeat reply document as a stdClass object.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- Application Performance Monitoring (APM)
- Persisting Data

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

### Beschreibung

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited(): bool

Returns whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return `false`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `false`.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Returns the heartbeat's duration in microseconds
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Returns the hostname of the server
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort — Returns the port on which this server is listening
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Returns the heartbeat reply document
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

# The MongoDB\Driver\Monitoring\TopologyChangedEvent class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\Monitoring\TopologyChangedEvent class encapsulates information about a changed topology description. For example, a topology discovering a new replica set primary would cause its topology description to change.

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\TopologyChangedEvent {
/* Eigenschaften */
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\TopologyDescription $newDescription;
public readonly MongoDB\Driver\TopologyDescription $previousDescription;
/* Methoden */
final public function getNewDescription(): MongoDB\Driver\TopologyDescription
final public function getPreviousDescription(): MongoDB\Driver\TopologyDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Eigenschaften

topologyId
  The topology ID.
newDescription
  The new topology description.
previousDescription
  The previous topology description.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Returns the new description for the topology

### Beschreibung

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription(): MongoDB\Driver\TopologyDescription

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the new MongoDB\Driver\TopologyDescription for the topology.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Returns the previous description for the topology

### Beschreibung

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription(): MongoDB\Driver\TopologyDescription

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the previous MongoDB\Driver\TopologyDescription for the topology.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Returns the topology ID

### Beschreibung

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the topology ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Returns the new description for the topology
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Returns the previous description for the topology
- MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Returns the topology ID

# The MongoDB\Driver\Monitoring\TopologyClosedEvent class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\Monitoring\TopologyClosedEvent class encapsulates information about a closed topology.

> Hinweis: Due to the driver's connection handling and persistence behavior, this event can only be observed when a MongoDB\Driver\Manager is created with the `"disableClientPersistence"` driver option and freed before request shutdown (RSHUTDOWN).

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\TopologyClosedEvent {
/* Eigenschaften */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Methoden */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Eigenschaften

topologyId
  The topology ID.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Returns the topology ID

### Beschreibung

final public function MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the topology ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Returns the topology ID

# The MongoDB\Driver\Monitoring\TopologyOpeningEvent class

(mongodb >=1.13.0)

## Einführung

The MongoDB\Driver\Monitoring\TopologyOpeningEvent class encapsulates information about an opened topology.

> Hinweis: Due to the driver's connection handling and persistence behavior, this event may not be observed if a MongoDB\Driver\Manager uses a previously persisted » libmongoc client.

## Klassenbeschreibung

final class MongoDB\Driver\Monitoring\TopologyOpeningEvent {
/* Eigenschaften */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* Methoden */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## Eigenschaften

topologyId
  The topology ID.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Returns the topology ID

### Beschreibung

final public function MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the topology ID.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Returns the topology ID

# The MongoDB\Driver\Monitoring\CommandSubscriber interface

(mongodb >=1.3.0)

## Einführung

Classes may implement this interface to register an event subscriber that is notified for each started, successful, and failed command event. See Application Performance Monitoring (APM) for additional information.

## Interface-Übersicht

class MongoDB\Driver\Monitoring\CommandSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Methoden */
abstract public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void
abstract public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void
abstract public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Notification method for a failed command

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void

If the subscriber is registered, this method is called when a command fails.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\CommandFailedEvent)
  An event object encapsulating information about the failed command.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Notification method for a started command

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void

If the subscriber is registered, this method is called when a command is sent to the server.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\CommandStartedEvent)
  An event object encapsulating information about the started command.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Notification method for a successful command

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void

If the subscriber is registered, this method is called when a command succeeds.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\CommandSucceededEvent)
  An event object encapsulating information about the successful command.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager
- Application Performance Monitoring (APM)

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Notification method for a failed command
- MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Notification method for a started command
- MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Notification method for a successful command

# The MongoDB\Driver\Monitoring\LogSubscriber interface

(mongodb >=1.17.0)

## Einführung

Classes implementing this interface may be registered as a subscriber and receive log messages from the extension. This is similar to stream-based debug logging (i.e. mongodb.debug) except that trace-level log messages are not received.

As with stream-based logging, it is only possible to register a logger globally using MongoDB\Driver\Monitoring\addSubscriber(). The extension is not able to distinguish log messages for individual MongoDB\Driver\Manager objects.

## Interface-Übersicht

class MongoDB\Driver\Monitoring\LogSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Konstanten */
const int LEVEL_ERROR = 0;
const int LEVEL_CRITICAL = 1;
const int LEVEL_WARNING = 2;
const int LEVEL_MESSAGE = 3;
const int LEVEL_INFO = 4;
const int LEVEL_DEBUG = 5;
/* Methoden */
abstract public function log(int `$level`, string `$domain`, string `$message`): void
}

## Vordefinierte Konstanten

`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_ERROR`
  Error log level. An error condition that the extension is unable to report through its API. This is the most severe log level in the extension.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_CRITICAL`
  Critical log level. An error condition with slightly less severity. This constant exists for consistency with libmongoc; however, the extension is unlikely to use it in practice.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_WARNING`
  Warning log level. Indicates a situation where undesirable application behavior may occur.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_MESSAGE`
  Message or notice log level. Indicates an event that is unusual but not problematic.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_INFO`
  Info log level. High-level information about normal driver behavior.
`MongoDB\Driver\Monitoring\LogSubscriber::LEVEL_DEBUG`
  Debug log level. Detailed information that may be helpful when debugging an application.

# MongoDB\Driver\Monitoring\LogSubscriber::log

(mongodb >=1.17.0)

MongoDB\Driver\Monitoring\LogSubscriber::log — Notification method for a log message

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\LogSubscriber::log(int `$level`, string `$domain`, string `$message`): void

If the subscriber is registered, this method is called for each logged message.

### Parameter-Liste

`level`
  The severity level. This will be one of the interface constants.
`domain`
  The name of the driver component that emitted the log message.
`message`
  The log message.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\LogSubscriber::log — Notification method for a log message

# The MongoDB\Driver\Monitoring\SDAMSubscriber interface

(mongodb >=1.13.0)

## Einführung

Classes may implement this interface to register an event subscriber that is notified for various SDAM events. See the » Server Discovery and Monitoring and » SDAM Monitoring specifications for additional information.

## Interface-Übersicht

class MongoDB\Driver\Monitoring\SDAMSubscriber implements MongoDB\Driver\Monitoring\Subscriber {
/* Methoden */
abstract public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void
abstract public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void
abstract public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void
abstract public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void
abstract public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void
abstract public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void
abstract public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void
abstract public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void
abstract public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Rückgabetypen, die zuvor als vorläufig deklariert waren, werden nun erzwungen.
PECL mongodb 1.15.0 | Rückgabetypen für Methoden werden in PHP 8.0 und neuer als vorläufig deklariert, was in Code, der diese Schnittstelle implementiert, ohne die entsprechenden Rückgabetypen zu deklarieren, einen Hinweis auf eine veraltete Verwendung auslöst. Um diesen Hinweis zu unterdrücken, kann das Attribut `#[ReturnTypeWillChange]` hinzugefügt werden.

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Notification method for a server description change

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void

If the subscriber is registered, this method is called when a server's description changes. For example, a server's type changing from secondary to primary would cause its server description to change.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\ServerChangedEvent)
  An event object encapsulating information about the changed server description.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Notification method for closing a server

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void

If the subscriber is registered, this method is called when an existing server is removed from the topology.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\ServerClosedEvent)
  An event object encapsulating information about the closed server.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Notification method for a failed server heartbeat

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void

If the subscriber is registered, this method is called when a server heartbeat (i.e. » hello command issued through » server monitoring) fails.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent)
  An event object encapsulating information about the failed server heartbeat.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Notification method for a started server heartbeat

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void

If the subscriber is registered, this method is called when a server heartbeat (i.e. » hello command issued through » server monitoring) is sent to the server.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent)
  An event object encapsulating information about the started server heartbeat.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Notification method for a successful server heartbeat

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void

If the subscriber is registered, this method is called when a server heartbeat (i.e. » hello command issued through » server monitoring) succeeds.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent)
  An event object encapsulating information about the successful server heartbeat.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Notification method for opening a server

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void

If the subscriber is registered, this method is called when a new server is added to the topology.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\ServerOpeningEvent)
  An event object encapsulating information about the opened server.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Notification method for a topology description change

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void

If the subscriber is registered, this method is called when the topology's description changes. For example, a topology discovering a new replica set primary would cause its topology description to change.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\TopologyChangedEvent)
  An event object encapsulating information about the changed topology description.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Notification method for closing the topology

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void

If the subscriber is registered, this method is called when the topology is closed.

> Hinweis: Due to the driver's connection handling and persistence behavior, this event can only be observed when a MongoDB\Driver\Manager is created with the `"disableClientPersistence"` driver option and freed before request shutdown (RSHUTDOWN).

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\TopologyClosedEvent)
  An event object encapsulating information about the closed topology.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Notification method for opening the topology

### Beschreibung

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void

If the subscriber is registered, this method is called when the topology is opened.

> Hinweis: Due to the driver's connection handling and persistence behavior, this event may not be observed if a MongoDB\Driver\Manager uses a previously persisted » libmongoc client.

### Parameter-Liste

`event` (MongoDB\Driver\Monitoring\TopologyOpeningEvent)
  An event object encapsulating information about the opened topology.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

- Wirft eine MongoDB\Driver\Exception\InvalidArgumentException, wenn beim Analysieren von Argumenten ein Fehler auftritt.

### Siehe auch

- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\addSubscriber() - Registers a monitoring event subscriber globally
- MongoDB\Driver\Manager::addSubscriber() - Registers a monitoring event subscriber with this Manager

## Inhaltsverzeichnis

- MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Notification method for a server description change
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Notification method for closing a server
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Notification method for a failed server heartbeat
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Notification method for a started server heartbeat
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Notification method for a successful server heartbeat
- MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Notification method for opening a server
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Notification method for a topology description change
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Notification method for closing the topology
- MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Notification method for opening the topology

# The MongoDB\Driver\Monitoring\Subscriber interface

(mongodb >=1.3.0)

## Einführung

Base interface for event subscribers. This is used as a parameter type in the functions MongoDB\Driver\Monitoring\addSubscriber() and MongoDB\Driver\Monitoring\removeSubscriber() and should not be implemented directly.

## Interface-Übersicht

class MongoDB\Driver\Monitoring\Subscriber {
}

This interface has no methods. Its only purpose is to be the base interface for all event subscribers.

# Exception classes

## Inhaltsverzeichnis

- MongoDB\Driver\Exception\AuthenticationException
- MongoDB\Driver\Exception\BulkWriteException
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\Exception\CommandException
- MongoDB\Driver\Exception\ConnectionException
- MongoDB\Driver\Exception\ConnectionTimeoutException
- MongoDB\Driver\Exception\EncryptionException
- MongoDB\Driver\Exception\Exception
- MongoDB\Driver\Exception\ExecutionTimeoutException
- MongoDB\Driver\Exception\InvalidArgumentException
- MongoDB\Driver\Exception\LogicException
- MongoDB\Driver\Exception\RuntimeException
- MongoDB\Driver\Exception\ServerException
- MongoDB\Driver\Exception\SSLConnectionException
- MongoDB\Driver\Exception\UnexpectedValueException
- MongoDB\Driver\Exception\WriteException
- Class Tree

# The MongoDB\Driver\Exception\AuthenticationException class

(mongodb >= 1.0.0)

## Einführung

Thrown when the driver fails to authenticate with the server.

## Klassenbeschreibung

class MongoDB\Driver\Exception\AuthenticationException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\BulkWriteException class

(mongodb >= 1.0.0)

## Einführung

Thrown when a bulk write operation fails.

## Klassenbeschreibung

class MongoDB\Driver\Exception\BulkWriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Eigenschaften */
public readonly MongoDB\Driver\WriteResult $writeResult;
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Eigenschaften

writeResult
  The MongoDB\Driver\WriteResult associated with the failed write operation.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | The writeResult property is now public readonly.
PECL mongodb 2.0.0 | This class now extends MongoDB\Driver\Exception\ServerException instead of MongoDB\Driver\Exception\WriteException.

# MongoDB\Driver\Exception\BulkWriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Returns the WriteResult for the failed write operation

### Beschreibung

final public function MongoDB\Driver\Exception\BulkWriteException::getWriteResult(): MongoDB\Driver\WriteResult

Returns the MongoDB\Driver\WriteResult for the failed write operation. The MongoDB\Driver\WriteResult::getWriteErrors() and MongoDB\Driver\WriteResult::getWriteConcernError() methods may be used to get more details about the failure.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The MongoDB\Driver\WriteResult for the failed write operation.

### Beispiele

Beispiel #1 MongoDB\Driver\Exception\BulkWriteException::getWriteResult() example

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Siehe auch

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations

## Inhaltsverzeichnis

- MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Returns the WriteResult for the failed write operation

# The MongoDB\Driver\Exception\BulkWriteCommandException class

(mongodb >=2.1.0)

## Einführung

Exception thrown due to failed execution of a MongoDB\Driver\BulkWriteCommand. The methods of this class provide more details of the error that occurred, including the error reply and partial results from the bulk write.

## Klassenbeschreibung

class MongoDB\Driver\Exception\BulkWriteCommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Eigenschaften */
private ?MongoDB\BSON\Document $errorReply;
private ?MongoDB\Driver\BulkWriteCommandResult $partialResult;
private array $writeConcernErrors;
private array $writeErrors;
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
final public function getErrorReply(): ?MongoDB\BSON\Document
final public function getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult
final public function getWriteConcernErrors(): array
final public function getWriteErrors(): array
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Eigenschaften

errorReply
  Any top-level error that occurred when attempting to communicate with the server or execute the bulk write. This value may be `null` if the exception was thrown due to errors occurring on individual writes.
partialResult
  A MongoDB\Driver\BulkWriteCommandResult reporting the result of any successful operations that were performed before the error was encountered. This value may be `null` if it cannot be determined that at least one write was successfully performed (and acknowledged).
writeConcernErrors
  An array of any MongoDB\Driver\WriteConcernErrors that occurred while executing the bulk write. This list may have multiple items if more than one server command was required to execute the bulk write.
writeErrors
  An array of any MongoDB\Driver\WriteErrors that occurred during the execution of individual write operations. Array keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand. This map will contain at most one entry if the bulk write was ordered.

# MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Returns any top-level command error

### Beschreibung

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply(): ?MongoDB\BSON\Document

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns any top-level error that occurred when attempting to communicate with the server or execute the bulk write. This value may be `null` if the exception was thrown due to errors occurring on individual writes.

### Beispiele

Beispiel #1 MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    // This example uses configureFailPoint to simulate a top-level command error
    $manager->executeCommand('admin', new MongoDB\Driver\Command([
        'configureFailPoint' => 'failCommand',
        'mode' => ['times' => 1],
        'data' => [
            'failCommands' => ['bulkWrite'],
            'errorCode' => 8, /* UnknownError */
        ],
    ]));

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getErrorReply()?->toPHP());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)#12 (6) {
      ["ok"]=>
      float(0)
      ["errmsg"]=>
      string(43) "Failing command via 'failCommand' failpoint"
      ["code"]=>
      int(8)
      ["codeName"]=>
      string(12) "UnknownError"
      ["$clusterTime"]=>
      object(stdClass)#10 (2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#6 (2) {
          ["increment"]=>
          string(1) "7"
          ["timestamp"]=>
          string(10) "1744319389"
        }
        ["signature"]=>
        object(stdClass)#9 (2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#7 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          object(MongoDB\BSON\Int64)#8 (1) {
            ["integer"]=>
            string(1) "0"
          }
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#11 (2) {
        ["increment"]=>
        string(1) "7"
        ["timestamp"]=>
        string(10) "1744319389"
      }
    }

### Siehe auch

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command

# MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Returns the result of any successful write operations

### Beschreibung

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a MongoDB\Driver\BulkWriteCommandResult reporting the result of any successful operations that were performed before the error was encountered. The return value will be `null` if it cannot be determined that at least one write was successfully performed (and acknowledged).

### Beispiele

Beispiel #1 Partial result if at least one write is successful

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)

Beispiel #2 No partial result if no writes are successful

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $manager->executeBulkWriteCommand($bulk);

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL

### Siehe auch

- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Returns any write concern errors

### Beschreibung

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array of any MongoDB\Driver\WriteConcernErrors that occurred while executing the bulk write. This list may have multiple items if more than one server command was required to execute the bulk write.

### Beispiele

Beispiel #1 MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(50);

    try {
        $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteConcernErrors());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteConcernError)#6 (3) {
        ["message"]=>
        string(29) "Not enough data-bearing nodes"
        ["code"]=>
        int(100)
        ["info"]=>
        object(stdClass)#8 (1) {
          ["writeConcern"]=>
          object(stdClass)#7 (3) {
            ["w"]=>
            int(50)
            ["wtimeout"]=>
            int(0)
            ["provenance"]=>
            string(14) "clientSupplied"
          }
        }
      }
    }

### Siehe auch

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Returns any write errors

### Beschreibung

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors(): array

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array of any MongoDB\Driver\WriteErrors that occurred during the execution of individual write operations. Array keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand. This map will contain at most one entry if the bulk write was ordered.

### Beispiele

Beispiel #1 MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteErrors());
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(2) {
      [2]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
      [3]=>
      object(MongoDB\Driver\WriteError)#7 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#8 (0) {
        }
      }
    }

### Siehe auch

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\WriteError

## Inhaltsverzeichnis

- MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Returns any top-level command error
- MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Returns the result of any successful write operations
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Returns any write concern errors
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Returns any write errors

# The MongoDB\Driver\Exception\CommandException class

(mongodb >= 1.5.0)

## Einführung

Thrown when a command fails.

## Klassenbeschreibung

class MongoDB\Driver\Exception\CommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Eigenschaften */
public readonly object $resultDocument;
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
final public function getResultDocument(): object
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Eigenschaften

resultDocument
  The result document associated with the failed command.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.3.0 | The resultDocument property is now public readonly.

# MongoDB\Driver\Exception\CommandException::getResultDocument

(mongodb >= 1.5.0)

MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command

### Beschreibung

final public function MongoDB\Driver\Exception\CommandException::getResultDocument(): object

Returns the result document for the failed command.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The result document for the failed command.

### Siehe auch

- MongoDB\Driver\Manager::executeCommand() - Execute a database command

## Inhaltsverzeichnis

- MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command

# The MongoDB\Driver\Exception\ConnectionException class

(mongodb >= 1.0.0)

## Einführung

Base class for exceptions thrown when the driver fails to establish a database connection.

## Klassenbeschreibung

class MongoDB\Driver\Exception\ConnectionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\ConnectionTimeoutException class

(mongodb >= 1.0.0)

## Einführung

Thrown when the driver fails to establish a database connection within a specified time limit (connectTimeoutMS) or server selection fails (serverSelectionTimeoutMS).

## Klassenbeschreibung

final class MongoDB\Driver\Exception\ConnectionTimeoutException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\EncryptionException class

(mongodb >= 1.7.0)

## Einführung

Base class for exceptions thrown during client-side encryption.

## Klassenbeschreibung

class MongoDB\Driver\Exception\EncryptionException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\Exception interface

(mongodb >= 1.0.0)

## Einführung

Common interface for all extension exceptions. This interface is also used by the library, and may be used to identify any exceptions originating from the MongoDB PHP driver (i.e. extension and library).

## Klassenbeschreibung

class MongoDB\Driver\Exception\Exception {
}

# The MongoDB\Driver\Exception\ExecutionTimeoutException class

(mongodb >= 1.0.0)

## Einführung

Thrown when a query or command fails to complete within a specified time limit (e.g. » maxTimeMS).

## Klassenbeschreibung

final class MongoDB\Driver\Exception\ExecutionTimeoutException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.5.0 | This class now extends MongoDB\Driver\Exception\ServerException instead of MongoDB\Driver\Exception\RuntimeException.

# The MongoDB\Driver\Exception\InvalidArgumentException class

(mongodb >= 1.0.0)

## Einführung

Thrown when a driver method is given invalid arguments (e.g. invalid option types).

## Klassenbeschreibung

class MongoDB\Driver\Exception\InvalidArgumentException extends InvalidArgumentException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\LogicException class

(mongodb >= 1.0.0)

## Einführung

Thrown when the driver is incorrectly used (e.g. rewinding a cursor).

## Klassenbeschreibung

class MongoDB\Driver\Exception\LogicException extends LogicException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\RuntimeException class

(mongodb >= 1.0.0)

## Einführung

Thrown when the driver encounters a runtime error (e.g. internal error from » libmongoc).

## Klassenbeschreibung

class MongoDB\Driver\Exception\RuntimeException extends RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Eigenschaften */
protected ?array $errorLabels;
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
final public function hasErrorLabel(string `$errorLabel`): bool
/* Geerbte Methoden */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Eigenschaften

errorLabels
  Contains an array of error labels to go with an exception. For example, error labels can be used to detect whether a transaction can be retried safely if the `TransientTransactionError` label is present. The existence of a specific error label should be tested for with the MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(), instead of interpreting this `errorLabels` property manually.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 1.6.0 | The MongoDB\Driver\Exception\RuntimeException::hasErrorLabel() method and MongoDB\Driver\Exception\RuntimeException::errorLabels property have been added.

# MongoDB\Driver\Exception\RuntimeException::hasErrorLabel

(mongodb >= 1.6.0)

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception

### Beschreibung

final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool

Returns whether the `errorLabel` has been set for this exception. Error labels are set by either the server or the extension to indicate specific situations that may be handled by an application. A common situation might be determining whether to safely retry a transaction that failed due to a transient error (e.g. network error, transaction conflict). Examples of error labels are `TransientTransactionError` and `UnknownTransactionCommitResult`.

### Parameter-Liste

`errorLabel`
  The name of the `errorLabel` to test for.

### Rückgabewerte

Whether the given `errorLabel` is associated with this exception.

### Siehe auch

- MongoDB\Driver\Session::commitTransaction() - Commits a transaction
- » MongoDB documentation on transactions

## Inhaltsverzeichnis

- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception

# The MongoDB\Driver\Exception\ServerException class

(mongodb >= 1.5.0)

## Einführung

Base class for exceptions thrown by the server. The code of this exception and its subclasses will correspond to the original error code from the server.

## Klassenbeschreibung

class MongoDB\Driver\Exception\ServerException extends MongoDB\Driver\Exception\RuntimeException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\SSLConnectionException class

(mongodb >= 1.0.0)

Warnung

This exception class is DEPRECATED as of extension version 1.5.0 and was removed in 2.0. This exception was never thrown by the extension. Applications should use MongoDB\Driver\Exception\ConnectionException instead.

## Einführung

Thrown when the driver fails to establish an SSL connection with the server.

## Klassenbeschreibung

final class MongoDB\Driver\Exception\SSLConnectionException extends MongoDB\Driver\Exception\ConnectionException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\UnexpectedValueException class

(mongodb >= 1.0.0)

## Einführung

Thrown when the driver encounters an unexpected value (e.g. during BSON serialization or deserialization).

## Klassenbeschreibung

class MongoDB\Driver\Exception\UnexpectedValueException extends UnexpectedValueException implements MongoDB\Driver\Exception\Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\WriteException class

(mongodb >= 1.0.0)

Warnung

This exception class is DEPRECATED as of extension version 1.20.0 and was removed in 2.0. This exception was never directly thrown by the extension. Applications should use MongoDB\Driver\Exception\BulkWriteException instead.

## Einführung

Base class for exceptions thrown by a failed write operation. The exception encapsulates a MongoDB\Driver\WriteResult object.

## Klassenbeschreibung

abstract class MongoDB\Driver\Exception\WriteException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* Eigenschaften */
protected MongoDB\Driver\WriteResult $writeResult;
/* Geerbte Eigenschaften */
protected ?array $errorLabels;
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
final public function getWriteResult(): MongoDB\Driver\WriteResult
/* Geerbte Methoden */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Eigenschaften

writeResult
  The MongoDB\Driver\WriteResult associated with the failed write operation.

## Changelog

Version | Beschreibung
--- | ---
PECL mongodb 2.0.0 | Diese Klasse wurde entfernt.
PECL mongodb 1.20.0 | This class has been deprecated and will be removed in version 2.0.
PECL mongodb 1.5.0 | This class now extends MongoDB\Driver\Exception\ServerException instead of MongoDB\Driver\Exception\RuntimeException.

# MongoDB\Driver\Exception\WriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation

### Beschreibung

final public function MongoDB\Driver\Exception\WriteException::getWriteResult(): MongoDB\Driver\WriteResult

Returns the MongoDB\Driver\WriteResult for the failed write operation. The MongoDB\Driver\WriteResult::getWriteErrors() and MongoDB\Driver\WriteResult::getWriteConcernError() methods may be used to get more details about the failure.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The MongoDB\Driver\WriteResult for the failed write operation.

### Beispiele

Beispiel #1 MongoDB\Driver\Exception\WriteException::getWriteResult() example

    <?php

    $manager = new MongoDB\Driver\Manager('mongodb://localhost');
    $bulk = new MongoDB\Driver\BulkWrite;
    $bulk->insert(['_id' => 1]);
    $bulk->insert(['_id' => 1]);

    try {
        $manager->executeBulkWrite('db.collection', $bulk);
    } catch (MongoDB\Driver\Exception\WriteException $e) {
        $writeResult = $e->getWriteResult();

        if ($writeConcernError = $writeResult->getWriteConcernError()) {
            var_dump($writeConcernError);
        }

        if ($writeErrors = $writeResult->getWriteErrors()) {
            var_dump($writeErrors);
        }
    }

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(70) "E11000 duplicate key error index: db.collection.$_id_ dup key: { : 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(1)
        ["info"]=>
        NULL
      }
    }

### Siehe auch

- MongoDB\Driver\WriteResult
- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations

## Inhaltsverzeichnis

- MongoDB\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation

# MongoDB Exception Class Tree

The class hierarchy for MongoDB exceptions is modeled after that of the SPL Exceptions. Base classes extend their SPL counterpart and all exception classes in the extension implement the MongoDB\Driver\Exception\Exception interface.

- MongoDB\Driver\Exception\LogicException (extends LogicException)
- MongoDB\Driver\Exception\InvalidArgumentException (extends InvalidArgumentException)
- MongoDB\Driver\Exception\UnexpectedValueException (extends UnexpectedValueException)
- MongoDB\Driver\Exception\RuntimeException (extends RuntimeException)
  - MongoDB\Driver\Exception\ConnectionException
    - MongoDB\Driver\Exception\AuthenticationException
    - MongoDB\Driver\Exception\ConnectionTimeoutException
    - MongoDB\Driver\Exception\SSLConnectionException (deprecated)
  - MongoDB\Driver\Exception\EncryptionException
  - MongoDB\Driver\Exception\ServerException
    - MongoDB\Driver\Exception\BulkWriteCommandException
    - MongoDB\Driver\Exception\CommandException
    - MongoDB\Driver\Exception\ExecutionTimeoutException
    - MongoDB\Driver\Exception\WriteException (deprecated)
      - MongoDB\Driver\Exception\BulkWriteException

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Tutorials
  - Using the PHP Library for MongoDB (PHPLIB)
  - Application Performance Monitoring (APM)
- Driver Architecture and Internals — Explains the driver architecture, and special features
  - Architecture — Architecture Overview
  - Connections — Connection handling and persistence
  - Persisting Data — Serialization and deserialization of PHP variables into MongoDB
- Security
  - Request Injection Attacks
  - Script Injection Attacks
- MongoDB\Driver — MongoDB Extension Classes
  - MongoDB\Driver\Manager — The MongoDB\Driver\Manager class
  - MongoDB\Driver\Command — The MongoDB\Driver\Command class
  - MongoDB\Driver\Query — The MongoDB\Driver\Query class
  - MongoDB\Driver\BulkWrite — The MongoDB\Driver\BulkWrite class
  - MongoDB\Driver\BulkWriteCommand — The MongoDB\Driver\BulkWriteCommand class
  - MongoDB\Driver\Session — The MongoDB\Driver\Session class
  - MongoDB\Driver\ClientEncryption — The MongoDB\Driver\ClientEncryption class
  - MongoDB\Driver\ServerApi — The MongoDB\Driver\ServerApi class
  - MongoDB\Driver\WriteConcern — The MongoDB\Driver\WriteConcern class
  - MongoDB\Driver\ReadPreference — The MongoDB\Driver\ReadPreference class
  - MongoDB\Driver\ReadConcern — The MongoDB\Driver\ReadConcern class
  - MongoDB\Driver\Cursor — The MongoDB\Driver\Cursor class
  - MongoDB\Driver\CursorId — The MongoDB\Driver\CursorId class
  - MongoDB\Driver\CursorInterface — The MongoDB\Driver\CursorInterface interface
  - MongoDB\Driver\Server — The MongoDB\Driver\Server class
  - MongoDB\Driver\ServerDescription — The MongoDB\Driver\ServerDescription class
  - MongoDB\Driver\TopologyDescription — The MongoDB\Driver\TopologyDescription class
  - MongoDB\Driver\WriteConcernError — The MongoDB\Driver\WriteConcernError class
  - MongoDB\Driver\WriteError — The MongoDB\Driver\WriteError class
  - MongoDB\Driver\WriteResult — The MongoDB\Driver\WriteResult class
  - MongoDB\Driver\BulkWriteCommandResult — The MongoDB\Driver\BulkWriteCommandResult class
- MongoDB\BSON — MongoDB BSON Classes and Functions
  - Funktionen
  - MongoDB\BSON\Document — The MongoDB\BSON\Document class
  - MongoDB\BSON\PackedArray — The MongoDB\BSON\PackedArray class
  - MongoDB\BSON\Iterator — The MongoDB\BSON\Iterator class
  - MongoDB\BSON\Binary — The MongoDB\BSON\Binary class
  - MongoDB\BSON\VectorType — The MongoDB\BSON\VectorType enum
  - MongoDB\BSON\Decimal128 — The MongoDB\BSON\Decimal128 class
  - MongoDB\BSON\Javascript — The MongoDB\BSON\Javascript class
  - MongoDB\BSON\MaxKey — The MongoDB\BSON\MaxKey class
  - MongoDB\BSON\MinKey — The MongoDB\BSON\MinKey class
  - MongoDB\BSON\ObjectId — The MongoDB\BSON\ObjectId class
  - MongoDB\BSON\Regex — The MongoDB\BSON\Regex class
  - MongoDB\BSON\Timestamp — The MongoDB\BSON\Timestamp class
  - MongoDB\BSON\UTCDateTime — The MongoDB\BSON\UTCDateTime class
  - MongoDB\BSON\Type — The MongoDB\BSON\Type interface
  - MongoDB\BSON\Persistable — The MongoDB\BSON\Persistable interface
  - MongoDB\BSON\Serializable — The MongoDB\BSON\Serializable interface
  - MongoDB\BSON\Unserializable — The MongoDB\BSON\Unserializable interface
  - MongoDB\BSON\BinaryInterface — The MongoDB\BSON\BinaryInterface interface
  - MongoDB\BSON\Decimal128Interface — The MongoDB\BSON\Decimal128Interface interface
  - MongoDB\BSON\JavascriptInterface — The MongoDB\BSON\JavascriptInterface interface
  - MongoDB\BSON\MaxKeyInterface — The MongoDB\BSON\MaxKeyInterface interface
  - MongoDB\BSON\MinKeyInterface — The MongoDB\BSON\MinKeyInterface interface
  - MongoDB\BSON\ObjectIdInterface — The MongoDB\BSON\ObjectIdInterface interface
  - MongoDB\BSON\RegexInterface — The MongoDB\BSON\RegexInterface interface
  - MongoDB\BSON\TimestampInterface — The MongoDB\BSON\TimestampInterface interface
  - MongoDB\BSON\UTCDateTimeInterface — The MongoDB\BSON\UTCDateTimeInterface interface
  - MongoDB\BSON\DBPointer — The MongoDB\BSON\DBPointer class
  - MongoDB\BSON\Int64 — The MongoDB\BSON\Int64 class
  - MongoDB\BSON\Symbol — The MongoDB\BSON\Symbol class
  - MongoDB\BSON\Undefined — The MongoDB\BSON\Undefined class
- MongoDB\Driver\Monitoring — Monitoring classes and subscriber functions
  - Funktionen
  - MongoDB\Driver\Monitoring\CommandFailedEvent — The MongoDB\Driver\Monitoring\CommandFailedEvent class
  - MongoDB\Driver\Monitoring\CommandStartedEvent — The MongoDB\Driver\Monitoring\CommandStartedEvent class
  - MongoDB\Driver\Monitoring\CommandSucceededEvent — The MongoDB\Driver\Monitoring\CommandSucceededEvent class
  - MongoDB\Driver\Monitoring\ServerChangedEvent — The MongoDB\Driver\Monitoring\ServerChangedEvent class
  - MongoDB\Driver\Monitoring\ServerClosedEvent — The MongoDB\Driver\Monitoring\ServerClosedEvent class
  - MongoDB\Driver\Monitoring\ServerOpeningEvent — The MongoDB\Driver\Monitoring\ServerOpeningEvent class
  - MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent — The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class
  - MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent — The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class
  - MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent — The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class
  - MongoDB\Driver\Monitoring\TopologyChangedEvent — The MongoDB\Driver\Monitoring\TopologyChangedEvent class
  - MongoDB\Driver\Monitoring\TopologyClosedEvent — The MongoDB\Driver\Monitoring\TopologyClosedEvent class
  - MongoDB\Driver\Monitoring\TopologyOpeningEvent — The MongoDB\Driver\Monitoring\TopologyOpeningEvent class
  - MongoDB\Driver\Monitoring\CommandSubscriber — The MongoDB\Driver\Monitoring\CommandSubscriber interface
  - MongoDB\Driver\Monitoring\LogSubscriber — The MongoDB\Driver\Monitoring\LogSubscriber interface
  - MongoDB\Driver\Monitoring\SDAMSubscriber — The MongoDB\Driver\Monitoring\SDAMSubscriber interface
  - MongoDB\Driver\Monitoring\Subscriber — The MongoDB\Driver\Monitoring\Subscriber interface
- MongoDB\Driver\Exception — Exception classes
  - MongoDB\Driver\Exception\AuthenticationException — The MongoDB\Driver\Exception\AuthenticationException class
  - MongoDB\Driver\Exception\BulkWriteException — The MongoDB\Driver\Exception\BulkWriteException class
  - MongoDB\Driver\Exception\BulkWriteCommandException — The MongoDB\Driver\Exception\BulkWriteCommandException class
  - MongoDB\Driver\Exception\CommandException — The MongoDB\Driver\Exception\CommandException class
  - MongoDB\Driver\Exception\ConnectionException — The MongoDB\Driver\Exception\ConnectionException class
  - MongoDB\Driver\Exception\ConnectionTimeoutException — The MongoDB\Driver\Exception\ConnectionTimeoutException class
  - MongoDB\Driver\Exception\EncryptionException — The MongoDB\Driver\Exception\EncryptionException class
  - MongoDB\Driver\Exception\Exception — The MongoDB\Driver\Exception\Exception interface
  - MongoDB\Driver\Exception\ExecutionTimeoutException — The MongoDB\Driver\Exception\ExecutionTimeoutException class
  - MongoDB\Driver\Exception\InvalidArgumentException — The MongoDB\Driver\Exception\InvalidArgumentException class
  - MongoDB\Driver\Exception\LogicException — The MongoDB\Driver\Exception\LogicException class
  - MongoDB\Driver\Exception\RuntimeException — The MongoDB\Driver\Exception\RuntimeException class
  - MongoDB\Driver\Exception\ServerException — The MongoDB\Driver\Exception\ServerException class
  - MongoDB\Driver\Exception\SSLConnectionException — The MongoDB\Driver\Exception\SSLConnectionException class
  - MongoDB\Driver\Exception\UnexpectedValueException — The MongoDB\Driver\Exception\UnexpectedValueException class
  - MongoDB\Driver\Exception\WriteException — The MongoDB\Driver\Exception\WriteException class
  - Class Tree — MongoDB Exception Class Tree

# Treiber und Plugins für MySQL

PHP stellt mehrere Treiber und Plugins für den Zugriff auf MySQL und dessen Handhabung zur Verfügung.

In der Übersicht dieses Abschnitts werden die Unterschiede und die Funktionalitäten der MySQL-Erweiterungen beschrieben.

Die hier genannten Erweiterungen unterstützen das MySQL-Protokoll. Beispiele für kompatible Datenbankserver sind » MariaDB Server, » MySQL Server, » Percona Server for MySQL und » TiDB.

# Übersicht über die PHP-Treiber für MySQL

# Einleitung

Es gibt mehrere PHP-APIs für den Zugriff auf die MySQL-Datenbank. Zur Auswahl stehen die Erweiterungen mysqli und PDO_MySQL.

Dieser Leitfaden erklärt die Terminologie, die zur Beschreibung der einzelnen APIs verwendet wird, gibt Informationen über die Auswahl der zu verwendenden API sowie Informationen zur Auswahl der MySQL-Bibliothek, die mit der API verwendet werden soll.

# Übersicht über die Terminologie

Dieser Abschnitt bietet eine Einführung in die Möglichkeiten, die bei der Entwicklung einer PHP-Anwendung, die mit einer MySQL-Datenbank interagieren muss, zur Verfügung stehen.

Was ist eine API?

Eine API (Application Programming Interface, Schnittstelle für die Anwendungsprogrammierung) definiert die Klassen, Methoden, Funktionen und Variablen, die eine Anwendung aufrufen muss, um die gewünschte Aufgabe zu erfüllen. Im Falle von PHP-Anwendungen, die mit Datenbanken kommunizieren müssen, werden die erforderlichen APIs in der Regel über PHP-Erweiterungen bereitgestellt.

APIs können entweder prozedural oder objektorientiert sein. Bei einer prozeduralen API werden Funktionen aufgerufen, um Aufgaben auszuführen, während bei einer objektorientierten API Klassen instanziiert und dann die Methoden der resultierenden Objekte aufgerufen werden. Von den beiden ist die letztere in der Regel die bevorzugte Schnittstelle, da sie moderner ist und zu besser strukturiertem Code führt.

Wenn eine PHP-Anwendung geschrieben wird, die sich mit dem MySQL-Server verbinden muss, stehen mehrere APIs zur Verfügung. In diesem Dokument wird beschrieben, welche Möglichkeiten es gibt und welche die beste Wahl für die jeweilige Anwendung ist.

Was ist ein Konnektor?

Der Begriff Konnektor, wie er in der MySQL-Dokumentation verwendet wird, bezieht sich auf Software, die es ermöglicht, von einer Anwendung aus eine Verbindung zum MySQL-Datenbankserver herzustellen. MySQL bietet Konnektoren für verschiedene Sprachen, darunter PHP.

Wenn eine PHP-Anwendung mit einem Datenbankserver kommunizieren soll, muss PHP-Code geschrieben werden, der die Verbindung zum Datenbankserver, die Abfrage der Datenbank und andere datenbankbezogene Funktionen ermöglicht. Es wird eine Software benötigt, die die API für die Kommunikation zwischen der Anwendung und dem Datenbankserver zur Verfügung stellt und gegebenenfalls andere zwischengeschaltete Bibliotheken verwendet. Diese Software wird allgemein als Konnektor bezeichnet, weil sie es der Anwendung ermöglicht, sich mit einem Datenbankserver zu verbinden.

Was ist ein Treiber?

Ein Treiber ist ein Stück Software, das für die Kommunikation mit einem bestimmten Typ von Datenbankserver entwickelt wurde. Der Treiber kann auch eine Bibliothek aufrufen, z. B. die MySQL Client Library oder den MySQL Native Driver. Diese Bibliotheken implementieren das Low-Level-Protokoll, das für die Kommunikation mit dem MySQL-Datenbankserver verwendet wird.

So verwendet beispielsweise die Datenbank-Abstraktionsschicht PHP Data Objects (PDO) einen von mehreren datenbankspezifischen Treibern. Einer der verfügbaren Treiber ist der PDO-MYSQL-Treiber, der eine Schnittstelle zum MySQL-Server bietet.

Manchmal werden die Begriffe Konnektor und Treiber synonym verwendet, was verwirrend sein kann. In der MySQL-Dokumentation ist der Begriff "Treiber" für Software reserviert, die den datenbankspezifischen Teil eines Konnektor-Pakets bereitstellt.

Was ist eine Erweiterung?

In der PHP-Dokumentation wird häufig der Begriff Erweiterung verwendet. Der PHP-Code besteht aus einem Kern und optionalen Erweiterungen der Kernfunktionalität. Die PHP-Erweiterung für MySQL, `mysqli`, wird mit Hilfe des PHP-Frameworks für Erweiterungen implementiert.

Damit die Funktionen einer Erweiterung von PHP-Programmierern programmtechnisch genutzt werden können, stellt diese in der Regel eine API zur Verfügung. Allerdings stellen nicht alle Erweiterungen, die das Framework für PHP-Erweiterungen verwenden, dem PHP-Programmierer eine API zur Verfügung.

Der PDO-Treiber für MySQL beispielsweise stellt dem PHP-Programmierer keine API zur Verfügung, sondern eine Schnittstelle zur darüber liegenden PDO-Schicht.

Die Begriffe API und Erweiterung sollten nicht als gleichbedeutend angesehen werden, da eine Erweiterung dem Programmierer nicht unbedingt eine API zur Verfügung stellt.

# Auswahl einer API

PHP bietet verschiedene APIs für die Verbindung zu MySQL. Im Folgenden werden die APIs beschrieben, die von den Erweiterungen mysqli und PDO bereitgestellt werden. In jedem Codeschnipsel wird eine Verbindung zu einem MySQL-Server auf "example.com" mit dem Benutzernamen "user" und dem Passwort "password" hergestellt und es wird eine Abfrage zur Begrüßung des Benutzers ausgeführt.

Beispiel #1 Vergleich der MySQL-APIs

    <?php
    // mysqli
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
    $row = $result->fetch_assoc();
    echo htmlentities($row['_message']);

    // PDO
    $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
    $statement = $pdo->query("SELECT 'Hello, dear MySQL user!' AS _message FROM DUAL");
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['_message']);

Beispiel #2 Vergleich mit vorbereiteten Anweisungen

    <?php
    // mysqli
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $statement = $mysqli->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $result = $statement->get_result();
    $row = $result->fetch_assoc();
    echo htmlentities($row['District']);

    // PDO
    $pdo = new PDO('mysql:host=example.com;dbname=database', 'user', 'password');
    $statement = $pdo->prepare("SELECT District FROM City WHERE Name=?");
    $statement->execute(["Amersfoort"]);
    $row = $statement->fetch(PDO::FETCH_ASSOC);
    echo htmlentities($row['District']);

Vergleich der Merkmale

Die Leistung der beiden Erweiterungen ist insgesamt gesehen in etwa gleich. Allerdings macht die Leistung der Erweiterungen nur einen Bruchteil der Gesamtlaufzeit einer PHP-Webanforderung aus. Oft liegt der Einfluss bei nur 0,1%.

| ext/mysqli | PDO_MySQL
--- | --- | ---
PHP-Version der Einführung | 5.0 | 5.1
Enthalten in PHP 7.x und 8.x | Ja | Ja
Entwicklungsstatus | Aktiv | Aktiv
Lebenszyklus | Aktiv | Aktiv
Für neue Projekte empfohlen | Ja | Ja
OOP-Schnittstelle | Ja | Ja
Prozedurale Schnittstelle | Ja | Nein
API unterstützt nicht-blockierende, asynchrone Abfragen mit mysqlnd | Ja | Nein
Persistente (dauerhafte) Verbindungen | Ja | Ja
API unterstützt Zeichensätze | Ja | Ja
API unterstützt serverseitige vorbereitete Anweisungen | Ja | Ja
API unterstützt clientseitige vorbereitete Anweisungen | Nein | Ja
API unterstützt gespeicherte Prozeduren | Ja | Ja
API unterstützt Mehrfachanweisungen | Ja | Weitestgehend
API unterstützt Transaktionen | Ja | Ja
Transaktionen können mit SQL gesteuert werden | Ja | Ja
Unterstützt die gesamte Funktionalität von MySQL 5.1+ | Ja | Weitestgehend

# Auswahl einer Bibliothek

Die PHP-Erweiterungen mysqli und PDO_MySQL sind schlanke Wrapper, die auf einer C-Clientbibliothek aufbauen. Es kann eine der beiden Bibliotheken mysqlnd und `libmysqlclient` verwendet werden. Die Bibliothek muss beim Kompilieren ausgewählt werden.

Die Bibliothek mysqlnd ist Teil der PHP-Distribution. Sie bietet Funktionen wie Lazy Connections und Abfrage-Caching, Funktionen, die mit libmysqlclient nicht verfügbar sind, weshalb dringend empfohlen wird, die eingebaute Bibliothek mysqlnd zu verwenden. Die mysqlnd-Dokumentation enthält zusätzliche Details und eine Auflistung der Funktionen, die sie bietet.

Beispiel #1 Konfigurationsoptionen für die Verwendung von mysqlnd oder libmysqlclient

    // Empfohlen, kompiliert mit mysqlnd
    $ ./configure --with-mysqli=mysqlnd --with-pdo-mysql=mysqlnd

    // Alternativ empfohlen, kompiliert mit mysqlnd
    $ ./configure --with-mysqli --with-pdo-mysql

    // Nicht empfohlen, kompiliert mit libmysqlclient
    $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysql_config

Vergleich der Merkmale der Bibliotheken

Es wird empfohlen, die Bibliothek mysqlnd anstelle der Client-Server-Bibliothek von MySQL (libmysqlclient) zu verwenden. Beide Bibliotheken werden unterstützt und ständig verbessert.

| MySQL native driver (mysqlnd) | Client-Server-Bibliothek von MySQL (`libmysqlclient`)
--- | --- | ---
Teil der PHP-Distribution | Ja | Nein
PHP-Version der Einführung | 5.3.0 | N/A
Lizenz | PHP-Lizenz 3.01 | Duale Lizenz
Entwicklungsstatus | Aktiv | Aktiv
Lebenszyklus | Kein Ende angekündigt | Kein Ende angekündigt
Voreinstellung beim Kompilieren (bei allen MySQL-Erweiterungen) | Ja | Nein
Unterstützung des Komprimierungsprotokolls | Ja | Ja
SSL-Unterstützung | Ja | Ja
Unterstützung von benannten Pipes | Ja | Ja
Nicht-blockierende, asynchrone Abfragen | Ja | Nein
Statistiken zur Leistung | Ja | Nein
LOAD LOCAL INFILE berücksichtigt die Direktive open_basedir | Ja | Nein
Verwendet das PHP-eigene Speicherverwaltungssystem (hält sich z. B. an die PHP-Speichergrenzen) | Ja | Nein
Rückgabe numerischer Spalten als Doubles (COM_QUERY) | Ja | Nein
Rückgabe numerischer Spalten als Zeichenketten (COM_QUERY) | Ja | Ja
Plugin-API | Ja | Eingeschränkt
Automatische Wiederherstellung der Verbindung | Nein | Optional

# Konzepte

## Inhaltsverzeichnis

- Gepufferte und ungepufferte Abfragen
- Zeichensätze

Diese Konzepte gelten speziell für die MySQL-Treiber für PHP.

## Gepufferte und ungepufferte Abfragen

Abfragen werden standardmäßig im gepufferten Modus ausgeführt. Das bedeutet, dass die Abfrageergebnisse sofort vom MySQL-Server an PHP übertragen werden und dann im Speicher des PHP-Prozesses gehalten werden. Dies ermöglicht weitere Aktionen wie die Anzahl der Zeilen zu zählen und den aktuellen Ergebniszeiger zu verschieben (zu suchen). Außerdem ist es möglich, weitere Abfragen über dieselbe Verbindung durchzuführen, während die Ergebnismenge verarbeitet wird. Der Nachteil des gepufferten Modus ist, dass größere Ergebnismengen viel Speicherplatz benötigen können. Der Speicher bleibt so lange belegt, bis alle Verweise auf die Ergebnismenge aufgehoben sind oder die Ergebnismenge explizit freigegeben wurde, was spätestens beim Beenden der Abfrage automatisch geschieht. Weil beim gepufferten Modus die gesamte Ergebnismenge auf einmal gespeichert wird, wird auch der Ausdruck "store result" (Ergebnis speichern) verwendet.

> Hinweis: Wenn die Bibliothek libmysqlclient verwendet wird, wird der für eine Ergebnismenge verwendete Speicher nicht zum PHP-Speicherlimit gezählt, es sei denn, die Daten werden in PHP-Variablen abgerufen. Mit mysqlnd wird die gesamte Ergebnismenge in den Speicher mit eingerechnet.

Ungepufferte MySQL-Abfragen führen die Abfrage aus und warten dann darauf, dass die Daten vom MySQL-Server abgerufen werden. Dadurch wird zwar weniger Speicher von PHP verwendet, aber die Last auf dem Server kann steigen. Solange nicht die gesamte Ergebnismenge vom Server abgerufen wurde, können keine weiteren Abfragen über dieselbe Verbindung gesendet werden. Ungepufferte Abfragen können auch als "use result" (Ergebnis verwenden) bezeichnet werden. Nachdem alle Zeilen der Ergebnismenge abgerufen wurden, ist die Ergebnismenge weg, und kann nicht mehr durchlaufen werden.

Aufgrund dieser Merkmale sollten ungepufferte Abfragen nur verwendet werden, wenn eine große Ergebnismenge erwartet wird, die sequentiell verarbeitet werden soll. Ungepufferte Abfragen weisen eine Reihe von Fallstricken auf, die ihre Verwendung erschweren, z. B. ist die Anzahl der Zeilen in der Ergebnismenge erst bekannt, nachdem die letzte Zeile abgerufen wurde. Gepufferte Abfragen sind die einfachere und flexiblere Lösung, um Ergebnismengen zu verarbeiten.

Da standardmäßig gepufferte Abfragen verwendet werden, zeigen die folgenden Beispiele, wie ungepufferte Abfragen mit der jeweiligen API ausgeführt werden.

Beispiel #1 Beispiel für ungepufferte Abfragen: mysqli

    <?php
    $mysqli  = new mysqli("localhost", "my_user", "my_password", "world");
    $unbufferedResult = $mysqli->query("SELECT Name FROM City", MYSQLI_USE_RESULT);

    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

Beispiel #2 Beispiel für ungepufferte Abfragen: pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world", 'my_user', 'my_password');
    $pdo->setAttribute(PDO::MYSQL_ATTR_USE_BUFFERED_QUERY, false);

    $unbufferedResult = $pdo->query("SELECT Name FROM City");
    foreach ($unbufferedResult as $row) {
        echo $row['Name'] . PHP_EOL;
    }
    ?>

## Zeichensätze

Idealerweise sollte der richtige Zeichensatz auf Serverebene eingestellt werden. Dies wird im Abschnitt » Character Set Configuration des Handbuchs zum MySQL-Server beschrieben. Alternativ dazu bietet jede MySQL-API eine Methode, um den Zeichensatz zur Laufzeit zu setzen.

Achtung

# Der Zeichensatz und die Maskierung von Zeichen

Da sich der Zeichensatz auf jede Aktion auswirkt und auch Auswirkungen auf die Sicherheit hat, sollte er bekannt und definiert sein. Zum Beispiel orientiert sich der Mechanismus für das Maskieren (z. B. mysqli_real_escape_string() bei mysqli und PDO::quote() bei PDO_MySQL) an dieser Einstellung. Es ist wichtig zu wissen, dass diese Funktionen nicht den Zeichensatz verwenden, der für eine Abfrage definiert ist, sodass z. B. Folgendes keinen Einfluss auf sie hat:

Beispiel #1 Probleme beim Einstellen des Zeichensatzes mit SQL

    <?php

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    // Wirkt sich NICHT auf $mysqli->real_escape_string(); aus
    $mysqli->query("SET NAMES utf8mb4");

    // Wirkt sich NICHT auf $mysqli->real_escape_string(); aus
    $mysqli->query("SET CHARACTER SET utf8mb4");

    // Allerdings wirkt sich das auf $mysqli->real_escape_string(); aus
    $mysqli->set_charset('utf8mb4');

    // Aber das wirkt sich NICHT aus (UTF-8 vs. utf8mb4) - hier keine Bindestriche verwenden
    $mysqli->set_charset('UTF-8');
    ?>

Die folgenden Beispiele zeigen, wie der Zeichensatz mit der jeweiligen API korrekt zur Laufzeit geändert werden kann.

> Hinweis: Möglicher Fehler mit UTF-8
> Da die Namen von Zeichensätzen in MySQL keine Bindestriche enthalten, muss in MySQL die Zeichenkette "utf8" verwendet werden, um den Zeichensatz auf UTF-8 zu setzen (bis zu 3 Byte UTF-8 Unicode Encoding). Die Zeichenkette "UTF-8" ist dagegen ungültig, weshalb der Zeichensatz mit "UTF-8" nicht geändert werden kann und ein Fehler ausgegeben wird.

Beispiel #2 Beispiel für das Einstellen des Zeichensatzes: mysqli

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    echo 'Der ursprüngliche Zeichensatz: ' . $mysqli->character_set_name() . "\n";

    if (!$mysqli->set_charset('utf8mb4')) {
        printf("Fehler beim Laden des Zeichensatzes utf8mb4: %s\n", $mysqli->error);
        exit;
    }

    echo 'Der aktuelle Zeichensatz: ' . $mysqli->character_set_name() . "\n";
    ?>

Beispiel #3 Beispiel für das Einstellen des Zeichensatzes: pdo_mysql

    <?php
    $pdo = new PDO("mysql:host=localhost;dbname=world;charset=utf8mb4", 'my_user', 'my_pass');
    ?>

- Übersicht über die Terminologie
- Auswahl einer API
- Auswahl einer Bibliothek
- Konzepte
  - Gepufferte und ungepufferte Abfragen
  - Zeichensätze

# MySQL Improved Extension

# Einführung

Die `mysqli`-Erweiterung ermöglicht es, die ab MySQL 4.1 gegebene Funktionalität anzusprechen. Weitere Informationen über den MySQL-Datenbank-Server sind unter » http://www.mysql.com/ zu finden.

Ein Überblick über Software, die MySQL unter PHP nutzt, ist unter Übersicht zu finden.

Dokumentation über MySQL befindet sich unter » http://dev.mysql.com/doc/.

Teile dieser Dokumentation sind mit Erlaubnis der Oracle Corporation dem MySQL-Handbuch entnommen.

Beispiele verwenden entweder die » world oder » sakila Datenbank, die frei verfügbar sind.

# Übersicht

Dieser Abschnitt bietet eine Einführung in die Möglichkeiten, die bei der Entwicklung einer PHP-Anwendung, die mit einer MySQL-Datenbank interagieren soll, zur Verfügung stehen.

Was ist eine API?

Eine Schnittstelle zur Programmierung von Anwendungen (Application Programming Interface, API) definiert die Klassen, Methoden, Funktionen und Variablen, die eine Anwendung aufrufen muss, um die gewünschte Aufgabe zu erfüllen. Im Falle von PHP-Anwendungen, die mit Datenbanken kommunizieren müssen, werden die erforderlichen APIs in der Regel über PHP-Erweiterungen bereitgestellt.

APIs können entweder prozedural oder objektorientiert sein. Bei einer prozeduralen API werden Funktionen aufgerufen, um Aufgaben auszuführen, während bei einer objektorientierten API Klassen instanziiert und dann die Methoden der resultierenden Objekte aufgerufen werden. Von den beiden ist die letztere in der Regel die bevorzugte Schnittstelle, da sie moderner ist und zu besser strukturiertem Code führt.

Wenn eine PHP-Anwendung geschrieben wird, die sich mit dem MySQL-Server verbinden muss, stehen mehrere APIs zur Verfügung. In diesem Dokument wird beschrieben, welche Möglichkeiten es gibt und welche die beste Wahl für die jeweilige Anwendung ist.

Was ist ein Konnektor?

Der Begriff Konnektor, wie er in der MySQL-Dokumentation verwendet wird, bezieht sich auf Software, die es ermöglicht, von einer Anwendung aus eine Verbindung zum MySQL-Datenbankserver herzustellen. MySQL bietet Konnektoren für verschiedene Sprachen, darunter PHP.

Wenn eine PHP-Anwendung mit einem Datenbankserver kommunizieren soll, muss PHP-Code geschrieben werden, der die Verbindung zum Datenbankserver, die Abfrage der Datenbank und andere datenbankbezogene Funktionen ermöglicht. Es wird eine Software benötigt, die die API für die Kommunikation zwischen der Anwendung und dem Datenbankserver zur Verfügung stellt und gegebenenfalls andere zwischengeschaltete Bibliotheken verwendet. Diese Software wird allgemein als Konnektor bezeichnet, weil sie es der Anwendung ermöglicht, sich mit einem Datenbankserver zu verbinden.

Was ist ein Treiber?

Ein Treiber ist ein Stück Software, das für die Kommunikation mit einem bestimmten Typ von Datenbankserver entwickelt wurde. Der Treiber kann auch eine Bibliothek aufrufen, z. B. die MySQL Client Library oder den MySQL Native Driver. Diese Bibliotheken implementieren das Low-Level-Protokoll, das für die Kommunikation mit dem MySQL-Datenbankserver verwendet wird.

So verwendet beispielsweise die Datenbankabstraktionsschicht PHP Data Objects (PDO) einen von mehreren datenbankspezifischen Treibern. Einer der verfügbaren Treiber ist der PDO-MYSQL-Treiber, der eine Schnittstelle zum MySQL-Server bietet.

Manchmal werden die Begriffe Konnektor und Treiber synonym verwendet, was verwirrend sein kann. In der MySQL-Dokumentation ist der Begriff "Treiber" für Software reserviert, die den datenbankspezifischen Teil eines Konnektor-Pakets bereitstellt.

Was ist eine Erweiterung?

In der PHP-Dokumentation wird häufig der Begriff Erweiterung verwendet. Der PHP-Code besteht aus einem Kern und optionalen Erweiterungen der Kernfunktionalität. Zu den PHP-Erweiterungen für MySQL gehören mysqli und der PDO-Treiber für MySQL, die mit Hilfe des PHP-Frameworks für Erweiterungen implementiert werden.

Damit die Funktionen einer Erweiterung von PHP-Programmierern programmtechnisch genutzt werden können, stellt diese in der Regel eine API zur Verfügung. Allerdings stellen nicht alle Erweiterungen, die das Framework für PHP-Erweiterungen verwenden, dem PHP-Programmierer eine API zur Verfügung.

Der PDO-Treiber für MySQL beispielsweise stellt dem PHP-Programmierer keine API zur Verfügung, sondern eine Schnittstelle zur darüber liegenden PDO-Schicht.

Die Begriffe API und Erweiterung sollten nicht als gleichbedeutend angesehen werden, da eine Erweiterung dem Programmierer nicht unbedingt eine API zur Verfügung stellt.

Was sind die wichtigsten PHP-APIs, die für die Verwendung von MySQL zur Verfügung stehen?

Wenn eine Verbindung zu einem MySQL-Datenbankserver hergestellt werden soll, gibt es im Wesentlichen zwei Optionen für die API:

- Die PHP-Erweiterung mysqli

- PHP Data Objects (PDO)

Jede hat ihre eigenen Vor- und Nachteile. Die folgende Diskussion soll eine kurze Einführung in die wichtigsten Aspekte der einzelnen APIs geben.

Was ist die PHP-Erweiterung mysqli?

Die Erweiterung `mysqli`, auch bekannt als MySQL improved, wurde entwickelt, um die Vorteile der neuen Funktionen, die in MySQL-Systemen ab Version 4.1.3 zur Verfügung stehen, nutzen zu können. `mysqli` ist in PHP ab Version 5 enthalten.

`mysqli` bietet viele Vorteile, aber die wichtigsten Verbesserungen gegenüber `mysql` sind:

- Objektorientierte Schnittstelle

- Unterstützung für vorbereitete Anweisungen

- Unterstützung für Mehrfachanweisungen

- Unterstützung für Transaktionen

- Verbesserte Debugging-Funktionen

Zusätzlich zur objektorientierten Schnittstelle bietet die Erweiterung auch eine prozedurale Schnittstelle.

Die Erweiterung `mysqli` wird mit Hilfe des PHP-Frameworks für Erweiterungen erstellt; der Quellcode befindet sich im Verzeichnis ext/mysqli.

Weitere Informationen über die Erweiterung `mysqli` sind unter Mysqli zu finden.

Was ist PDO?

PHP Data Objects, oder PDO, ist eine Abstraktionsschicht für Datenbanken speziell für PHP-Anwendungen. PDO bietet eine einheitliche API, die unabhängig von der Art des Datenbankservers ist, mit dem sich die Anwendung verbindet. Wenn die PDO-API verwendet wird, könnte man theoretisch den verwendeten Datenbankserver wechseln, beispielsweise von Firebird zu MySQL, und müsste nur geringfügige Änderungen am PHP-Code vornehmen.

Andere Beispiele für Datenbankabstraktionsschichten sind JDBC für Java-Anwendungen und DBI für Perl.

PDO hat zwar seine Vorteile, z. B. eine klare, einfache und portierbare API, aber sein Hauptnachteil ist, dass es nicht möglich ist, alle verbesserten Features zu nutzen, die in den neuesten Versionen des MySQL-Servers verfügbar sind. Beispielsweise können mit PDO nicht die Mehrfachanweisungen von MySQL genutzt werden.

PDO wird mit Hilfe des PHP-Frameworks für Erweiterungen erstellt; der Quellcode befindet sich im Verzeichnis ext/pdo.

Weitere Informationen über PDO sind unter PDO zu finden.

Was ist der PDO-MYSQL-Treiber?

Der PDO-MYSQL-Treiber ist zumindest aus der Sicht eines PHP-Programmiers keine API im eigentlichen Sinne. Genau genommen befindet sich der PDO-MYSQL-Treiber in der Schicht unter PDO selbst und bietet eine MySQL-spezifische Funktionalität. Der Programmierer ruft zwar die PDO-API auf, aber PDO verwendet den PDO-MYSQL-Treiber, um mit dem MySQL-Server zu kommunizieren.

Der PDO-MYSQL-Treiber ist einer von mehreren verfügbaren PDO-Treibern. Daneben gibt es unter anderem PDO-Treiber für die Datenbankserver Firebird und PostgreSQL.

Der PDO-MYSQL-Treiber wird mit Hilfe des PHP-Frameworks für Erweiterungen erstellt; er stellt dem PHP-Programmierer keine API zur Verfügung. Der Quellcode befindet sich im Verzeichnis ext/pdo_mysql.

Weitere Informationen über den PDO-MYSQL-Treiber sind unter MySQL PDO-Treiber zu finden.

Was ist PHPs MySQL Native Driver?

Um mit dem MySQL-Datenbankserver zu kommunizieren, verwenden `mysqli` und der PDO-MYSQL-Treiber jeweils eine Low-Level-Bibliothek, die das erforderliche Protokoll implementiert. In der Vergangenheit war die einzige verfügbare Bibliothek die MySQL Client Library, auch bekannt als `libmysqlclient`.

Die Schnittstelle von `libmysqlclient` wurde jedoch ursprünglich für C-Anwendungen entwickelt und ist daher nicht für die Kommunikation mit PHP-Anwendungen optimiert. Aus diesem Grund wurde für PHP-Anwendungen der MySQL Native Driver, `mysqlnd`, als Alternative zu `libmysqlclient` entwickelt.

Sowohl die Erweiterung `mysqli` als auch der PDO-Treiber für MySQL können jeweils so konfiguriert werden, dass sie entweder `libmysqlclient` oder `mysqlnd` verwenden. Da `mysqlnd` speziell für die Verwendung im PHP-System entwickelt wurde, verfügt es über zahlreiche Speicher- und Geschwindigkeitsverbesserungen gegenüber `libmysqlclient`. Es wird dringend empfohlen, diese Verbesserungen zu nutzen.

Der MySQL Native Driver wird mit Hilfe des PHP-Frameworks für Erweiterungen erstellt; er stellt dem PHP-Programmierer keine API zur Verfügung. Der Quellcode befindet sich im Verzeichnis ext/mysqlnd.

Vergleich der Merkmale

Die folgende Tabelle vergleicht die Funktionalität der wichtigsten Methoden für den Aufbau einer Verbindung zu MySQL mittels PHP:

Vergleich der MySQL-API-Optionen in PHP
| PHP-Erweiterung mysqli | PDO (mit PDO-Treiber für MySQL und MySQL Native Driver)
--- | --- | ---
PHP-Version der Einführung | 5.0 | 5.0
MySQL-Entwicklungsstatus | In aktiver Entwicklung | In aktiver Entwicklung
API unterstützt Zeichensätze | Ja | Ja
API unterstützt serverseitige vorbereitete Anweisungen | Ja | Ja
API unterstützt clientseitige vorbereitete Anweisungen | Nein | Ja
API unterstützt gespeicherte Prozeduren | Ja | Ja
API unterstützt Mehrfachanweisungen | Ja | Weitestgehend
Unterstützt die gesamte Funktionalität von MySQL 4.1+ | Ja | Weitestgehend

# Kurzanleitung für den schnellen Einstieg

## Inhaltsverzeichnis

- Prozedurale und objektorientierte Schnittstelle
- Datenbankverbindungen
- Ausführen von Anweisungen
- Vorbereitete Anweisungen (Prepared Statements)
- Gespeicherte Prozeduren (Stored Procedures)
- Mehrfach-Anweisungen
- API-Unterstützung für Transaktionen
- Metadaten

Diese Kurzanleitung hilft dabei, sich mit der PHP-MySQL-API vertraut zu machen.

Diese Kurzanleitung gibt einen Überblick über die mysqli-Erweiterung. Es werden Beispiele für alle wichtigen Aspekte der API beschrieben. Datenbankkonzepte werden in dem Maße erklärt, wie es für die Darstellung von MySQL-spezifischen Konzepten erforderlich ist.

Voraussetzungen: Vertrautheit mit der Programmiersprache PHP, der Sprache SQL und Grundkenntnisse über den MySQL-Server.

## Prozedurale und objektorientierte Schnittstelle

Die mysqli-Erweiterung verfügt über eine doppelte Schnittstelle. Sie unterstützt das prozedurale und das objektorientierte Programmier-Paradigma.

Benutzer, die von der alten mysql-Erweiterung umsteigen, werden vielleicht die prozedurale Schnittstelle bevorzugen. Die prozedurale Schnittstelle ist ähnlich wie die der alten mysql Erweiterung. In vielen Fällen unterscheiden sich die Funktionsnamen nur durch das Präfix. Einige mysqli-Funktionen benötigen ein Verbindungs-Handle als ersten Parameter, während entsprechende Funktionen der alten mysql-Schnittstelle es als optionalen letzten Parameter nehmen.

Beispiel #1 Einfacher Umstieg von der alten mysql-Erweiterung

    <?php
    $mysqli = mysqli_connect("example.com", "user", "password", "database");
    $result = mysqli_query($mysqli, "SELECT 'Bitte verwenden Sie nicht die veraltete mysql-Erweiterung für neue Projekte. ' AS _msg FROM DUAL");
    $row = mysqli_fetch_assoc($result);
    echo $row['_msg'];

    $mysql = mysql_connect("example.com", "user", "password");
    mysql_select_db("test");
    $result = mysql_query("SELECT 'Verwenden Sie stattdessen die mysqli-Erweiterung.' AS _msg FROM DUAL", $mysql);
    $row = mysql_fetch_assoc($result);
    echo $row['_msg'];

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Bitte verwenden Sie nicht die veraltete mysql-Erweiterung für neue Projekte. Verwenden Sie stattdessen die mysqli-Erweiterung.

Die objektorientierte Schnittstelle

Neben der klassischen prozeduralen Schnittstelle kann der Benutzer auch die objektorientierte Schnittstelle verwenden. Die Dokumentation ist anhand der objektorientierten Schnittstelle gegliedert. Um den Einstieg zu erleichtern, sind die Funktionen der objektorientierten Schnittstelle nach ihrem Zweck gruppiert. Der Referenzteil enthält Beispiele für beide Syntaxvarianten.

Es gibt keine signifikanten Leistungsunterschiede zwischen den beiden Schnittstellen. Der Benutzer kann seine Wahl nach persönlichen Vorlieben treffen.

Beispiel #2 Objektorientierte und prozedurale Schnittstelle

    <?php

    $mysqli = mysqli_connect("example.com", "user", "password", "database");

    $result = mysqli_query($mysqli, "SELECT 'A world full of ' AS _msg FROM DUAL");
    $row = mysqli_fetch_assoc($result);
    echo $row['_msg'];

    $mysqli = new mysqli("example.com", "user", "password", "database");

    $result = $mysqli->query("SELECT 'choices to please everybody.' AS _msg FROM DUAL");
    $row = $result->fetch_assoc();
    echo $row['_msg'];

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    A world full of choices to please everybody.

Für die Kurzanleitung wird die objektorientierte Schnittstelle verwendet, weil der Referenzabschnitt entsprechend aufgebaut ist.

Stile miteinander kombinieren

Es ist jederzeit möglich, zwischen den Stilen zu wechseln. Das Kombinieren beider Stile wird aus Gründen des Programmierstils und der Verständlichkeit des Codes nicht empfohlen.

Beispiel #3 Schlechter Programmierstil

    <?php

    $mysqli = new mysqli("example.com", "user", "password", "database");

    $result = mysqli_query($mysqli, "SELECT 'Möglich, aber schlechter Stil.' AS _msg FROM DUAL");

    if ($row = $result->fetch_assoc()) {
        echo $row['_msg'];
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Möglich, aber schlechter Stil.

Siehe auch

- mysqli::__construct()
- mysqli::query()
- mysqli_result::fetch_assoc()
- $mysqli::connect_errno
- $mysqli::connect_error
- $mysqli::errno
- $mysqli::error
- Übersicht über die Funktionen der MySQLi-Erweiterung

## Datenbankverbindungen

Der MySQL-Server unterstützt die Verwendung verschiedener Transportschichten für Verbindungen. Verbindungen verwenden TCP/IP, Unix-Domain-Sockets oder Windows Named Pipes.

Der Hostname `localhost` hat eine besondere Bedeutung. Er ist an die Verwendung von Unix-Domain-Sockets gebunden. Um eine TCP/IP-Verbindung zum Localhost zu öffnen, muss `127.0.0.1` anstelle des Hostnamens `localhost` verwendet werden.

Beispiel #1 Die besondere Bedeutung von localhost

    <?php

    $mysqli = new mysqli("localhost", "user", "password", "database");

    echo $mysqli->host_info . "\n";

    $mysqli = new mysqli("127.0.0.1", "user", "password", "database", 3306);

    echo $mysqli->host_info . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Localhost via UNIX socket
    127.0.0.1 via TCP/IP

Standardwerte für Verbindungsparameter

Je nach verwendeter Verbindungsfunktion können verschiedene Parameter weggelassen werden. Wenn ein Parameter nicht angegeben wird, versucht die Erweiterung, die Standardwerte zu verwenden, die in der PHP-Konfigurationsdatei festgelegt sind.

Beispiel #2 Standardwerte festlegen

    mysqli.default_host=192.168.2.27
    mysqli.default_user=root
    mysqli.default_pw=""
    mysqli.default_port=3306
    mysqli.default_socket=/tmp/mysql.sock

Die entsprechenden Parameterwerte werden dann an die Client-Bibliothek übergeben, die von der Erweiterung verwendet wird. Wenn die Client-Bibliothek leere oder nicht gesetzte Parameter findet, kann sie die Standardwerte der Bibliothek verwenden.

Standardwerte der integrierten Verbindungsbibliothek

Wenn der Wert von host nicht definiert oder leer ist, verwendet die Client-Bibliothek standardmäßig eine Unix-Socket-Verbindung zu `localhost`. Wenn der Socket undefiniert oder leer ist und eine Unix-Socket-Verbindung angefordert wird, dann wird versucht, eine Verbindung zum Standardsocket `/tmp/mysql.sock` aufzubauen.

Auf Windows-Systemen wird der Hostname `.` von der Client-Bibliothek als Versuch interpretiert, eine auf einer Windows Namend Pipe basierende Verbindung zu öffnen. In diesem Fall wird der Socket-Parameter als Name der Pipe interpretiert. Wird er nicht angegeben oder ist er leer, dann wird der Socket (Name der Pipe) standardmäßig auf `\\.\pipe\MySQL` gesetzt.

Wenn eine Verbindung weder basierend auf einen Unix-Domänen-Socket noch auf eine Windows Named Pipe aufgebaut werden soll und der Parameterwert für den Port nicht gesetzt ist, verwendet die Bibliothek standardmäßig den Port `3306`.

Die mysqlnd-Bibliothek und die MySQL-Client-Bibliothek (libmysqlclient) implementieren dieselbe Logik zur Bestimmung der Standardwerte.

Optionen für die Verbindung

Die Verbindungsoptionen sind verfügbar, um z. B. Initialisierungsbefehle zu setzen, die beim Aufbau der Verbindung ausgeführt werden, oder um die Verwendung eines bestimmten Zeichensatzes anzugeben. Die Verbindungsoptionen müssen gesetzt werden, bevor eine Netzwerkverbindung aufgebaut wird.

Um eine Verbindungsoption zu setzen, muss der Verbindungsvorgang in drei Schritten durchgeführt werden: erstellen eines Verbindungs-Handles mit mysqli_init() oder mysqli::__construct(), setzen der gewünschten Optionen mit mysqli::options() und Aufbau der Netzwerkverbindung mit mysqli::real_connect().

Pooling von Verbindungen

Die mysqli-Erweiterung unterstützt persistente Datenbankverbindungen, die eine spezielle Art von gepoolten Verbindungen sind. Standardmäßig wird jede Datenbankverbindung, die von einem Skript geöffnet wird, entweder explizit durch den Benutzer während der Laufzeit geschlossen oder am Ende des Skripts automatisch freigegeben. Eine persistente Verbindung wird nicht geschlossen. Stattdessen wird sie in einen Pool gelegt, um später wiederverwendet zu werden, wenn eine Verbindung zum selben Server mit denselben Benutzernamen, Passwort, Socket, Port und Standarddatenbank geöffnet wird. Die Wiederverwendung spart Verbindungs-Overhead.

Jeder PHP-Prozess verwendet seinen eigenen mysqli-Verbindungspool. Abhängig vom Einsatzmodell des Webservers kann ein PHP-Prozess eine oder mehrere Anfragen bedienen. Daher kann eine in einem Pool gehaltene Verbindung von einem oder mehreren Skripten nacheinander verwendet werden.

Persistente Verbindung

Wenn im Verbindungspool für eine bestimmte Kombination von Host, Benutzername, Passwort, Socket, Port und Standarddatenbank keine unbenutzte persistente Verbindung gefunden wird, öffnet mysqli eine neue Verbindung. Die Verwendung persistenter Verbindungen kann mit der PHP-Direktive mysqli.allow_persistent aktiviert und deaktiviert werden. Die Gesamtzahl der von einem Skript geöffneten Verbindungen kann mit mysqli.max_links begrenzt werden. Die maximale Anzahl von persistenten Verbindungen pro PHP-Prozess kann mit mysqli.max_persistent begrenzt werden. Bitte beachten Sie, dass der Webserver viele PHP-Prozesse erzeugen kann.

Eine häufige Kritik an persistenten Verbindungen ist, dass ihr Zustand vor der Wiederverwendung nicht zurückgesetzt wird. Zum Beispiel werden offene und nicht abgeschlossene Transaktionen nicht nicht automatisch zurückgesetzt. Aber auch Berechtigungsänderungen, die in der Zeit zwischen der Aufnahme der Verbindung in den Pool und ihrer Wiederverwendung vorgenommen wurden, werden nicht berücksichtigt. Dies kann als unerwünschter Nebeneffekt angesehen werden. Andererseits kann der Name `persistent` als Zusage verstanden werden, dass der Zustand erhalten bleibt.

Die mysqli-Erweiterung unterstützt beide Arten einer persistenten Verbindung: den persistenten Zustand und den vor der Wiederverwendung zurückgesetzten Zustand. Die Voreinstellung ist Zurücksetzen. Bevor eine persistente Verbindung wiederverwendet wird, ruft die mysqli-Erweiterung implizit mysqli::change_user() auf, um den Zustand zurückzusetzen. Die persistente Verbindung erscheint dem Benutzer so, als ob sie gerade geöffnet worden wäre. Es sind keine Spuren von früheren Verwendungen sichtbar.

Der Aufruf von mysqli::change_user() ist eine aufwändige Operation. Um die beste Leistung zu erzielen, sollten Benutzer die Erweiterung mit dem Kompilierungsflag `MYSQLI_NO_CHANGE_USER_ON_PCONNECT` neu kompilieren.

Es ist dem Benutzer überlassen, zwischen sicherem Verhalten und bester Leistung zu wählen. Beides sind berechtigte Optimierungsziele. Um die Benutzung zu erleichtern, wurde das sichere Verhalten auf Kosten der maximalen Leistung als Standard festgelegt.

Siehe auch

- mysqli::__construct()
- mysqli_init()
- mysqli::options()
- mysqli::real_connect()
- mysqli::change_user()
- $mysqli::host_info
- MySQLi-Konfigurationsoptionen
- Persistente Datenbankverbindungen

## Ausführen von Anweisungen

Anweisungen können mit mysqli::query(), mysqli::real_query() und mysqli::multi_query() ausgeführt werden. Die Funktion mysqli::query() wird am häufigsten verwendet und kombiniert in einem Aufruf die auszuführende Anweisung mit einem gepufferten Abruf der Ergebnismenge, falls vorhanden. Der Aufruf von mysqli::query() ist gleichbedeutend mit dem Aufruf von mysqli::real_query() gefolgt von mysqli::store_result().

Beispiel #1 Ausführen von Anfragen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

Gepufferte Ergebnisse

Nach der Ausführung der Anweisung können die Ergebnisse entweder alle auf einmal vom Server abgerufen werden oder Zeile für Zeile. Die clientseitige Pufferung der Ergebnismenge ermöglicht es dem Server, die mit den Ergebnissen der Anweisung verbundenen Ressourcen so früh wie möglich freizugeben. Im Allgemeinen verarbeiten Clients die Ergebnismengen langsam. Es wird daher empfohlen, gepufferte Ergebnismengen zu verwenden. mysqli::query() kombiniert die Ausführung einer Anweisung mit der Pufferung der Ergebnismenge.

PHP-Anwendungen können frei durch gepufferte Ergebnismengen navigieren. Da die Ergebnismengen im Speicher des Clients gehalten werden, ist die Navigation sehr schnell. Bitte bedenken Sie, dass es oft einfacher ist, einen Client zu skalieren als den Server.

Beispiel #2 Navigation durch gepufferte Ergebnisse

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $result = $mysqli->query("SELECT id FROM test ORDER BY id ASC");

    echo "Umgekehrte Reihenfolge...\n";
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);
        $row = $result->fetch_assoc();
        echo " id = " . $row['id'] . "\n";
    }

    echo "Reihenfolge der Ergebnisse...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Umgekehrte Reihenfolge...
     id = 3
     id = 2
     id = 1
    Reihenfolge der Ergebnisse...
     id = 1
     id = 2
     id = 3

Ungepufferte Ergebnismengen

Wenn der Client-Speicher knapp ist und es nicht notwendig ist, Server-Ressourcen so früh wie möglich freizugeben, um die Serverlast gering zu halten, können ungepufferte Ergebnisse verwendet werden. Das Blättern durch ungepufferte Ergebnisse ist erst möglich, nachdem alle Zeilen gelesen wurden.

Beispiel #3 Navigation durch ungepufferte Ergebnisse

    <?php

    $mysqli->real_query("SELECT id FROM test ORDER BY id ASC");
    $result = $mysqli->use_result();

    echo "Reihenfolge der Ergebnisse...\n";
    foreach ($result as $row) {
        echo " id = " . $row['id'] . "\n";
    }

Datentypen der Werte in der Ergebnismenge

Die Funktionen mysqli::query(), mysqli::real_query() und mysqli::multi_query() werden verwendet, um nicht vorbereitete Anweisungen auszuführen. Auf der Ebene des Client-Server-Protokolls von MySQL werden der Befehl `COM_QUERY` und das Textprotokoll für die Ausführung von Anweisungen verwendet. Mit dem Textprotokoll wandelt der MySQL-Server alle Daten einer Ergebnismenge vor dem Senden in Zeichenketten um. Diese Umwandlung wird unabhängig vom Datentyp der Spalten der SQL-Ergebnismenge durchgeführt. Die mysql-Client-Bibliotheken empfangen alle Spaltenwerte als Zeichenketten. Es wird keine weitere clientseitige Umwandlung durchgeführt, um Spalten zurück in ihre nativen Typen umzuwandeln. Stattdessen werden alle Werte als PHP-Zeichenketten bereitgestellt.

Beispiel #4 Das Textprotokoll gibt standardmäßig Zeichenketten zurück

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

    $result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    id = 1 (string)
    label = a (string)

Wenn die mysqlnd-Bibliothek verwendet wird, können Integer- und Float-Spalten durch Setzen der Verbindungsoption `MYSQLI_OPT_INT_AND_FLOAT_NATIVE` in PHP-Zahlen umgewandelt werden. Wenn sie gesetzt ist, überprüft die mysqlnd-Bibliothek die Metadaten der Spaltentypen in der Ergebnismenge und wandelt numerische SQL-Spalten in PHP-Zahlen um, wenn der Wertebereich des PHP-Datentyps dies zulässt. Auf diese Weise werden z. B. SQL-INT-Spalten als Integer zurückgegeben.

Beispiel #5 Native Datentypen bei mysqlnd und Verbindungsoption

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli();
    $mysqli->options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1);
    $mysqli->real_connect("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

    $result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    id = 1 (integer)
    label = a (string)

Siehe auch

- mysqli::__construct()
- mysqli::options()
- mysqli::real_connect()
- mysqli::query()
- mysqli::multi_query()
- mysqli::use_result()
- mysqli::store_result()

## Vorbereitete Anweisungen (Prepared Statements)

Die MySQL-Datenbank unterstützt vorbereitete Anweisungen. Vorbereitete Anweisungen oder parametrisierte Anweisungen ermöglichen die wiederholte und effiziente Ausführung derselben Anweisung und schützen gleichzeitig vor SQL-Injections.

Grundlegender Ablauf

Die Ausführung einer vorbereiteten Anweisung besteht aus zwei Phasen: der Vorbereitung und der Ausführung. In der Vorbereitungsphase wird eine Anweisungsvorlage an den Datenbankserver gesendet. Der Server führt eine Syntaxprüfung durch und initialisiert Server-interne Ressourcen für die spätere Verwendung.

Der MySQL-Server unterstützt die Verwendung des anonymen, positionsbezogenen Platzhalters `?`.

Auf das Vorbereiten folgt das Ausführen. Während der Ausführung bindet der Client die Parameterwerte und sendet sie an den Server. Der Server führt die Anweisung mit den gebundenen Werten unter Verwendung der zuvor erstellten internen Ressourcen aus.

Beispiel #1 Vorbereitete Anweisung

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Nicht-vorbereitete Anweisung */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    /* Vorbereitete Anweisung, Stufe 1: vorbereiten */
    $stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

    /* Vorbereitete Anweisung, Stufe 2: binden und ausführen */
    $id = 1;
    $label = 'PHP';
    $stmt->bind_param("is", $id, $label); // "is" bedeutet, dass $id als Integer und
                                          // $label als Zeichenkette gebunden ist

    $stmt->execute();

Mehrmalige Ausführung

Eine vorbereitete Anweisung kann mehrmals ausgeführt werden. Bei jeder Ausführung wird der aktuelle Wert der gebundenen Variablen ausgewertet und an den Server gesendet. Die Anweisung wird nicht erneut analysiert und die Anweisungsvorlage wird nicht erneut an den Server übertragen.

Beispiel #2 INSERT einmal vorbereitet, mehrfach ausgeführt

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Nicht-vorbereitete Anweisung */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");

    /* Vorbereitete Anweisung, Stufe 1: vorbereiten */
    $stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

    /* Vorbereitete Anweisung, Stufe 2: binden und ausführen */
    $stmt->bind_param("is", $id, $label); // "is" bedeutet, dass $id als Integer und
                                          // $label als Zeichenkette gebunden ist

    $data = [
        1 => 'PHP',
        2 => 'Java',
        3 => 'C++'
    ];
    foreach ($data as $id => $label) {
        $stmt->execute();
    }

    $result = $mysqli->query('SELECT id, label FROM test');
    var_dump($result->fetch_all(MYSQLI_ASSOC));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      [0]=>
      array(2) {
        ["id"]=>
        string(1) "1"
        ["label"]=>
        string(3) "PHP"
      }
      [1]=>
      array(2) {
        ["id"]=>
        string(1) "2"
        ["label"]=>
        string(4) "Java"
      }
      [2]=>
      array(2) {
        ["id"]=>
        string(1) "3"
        ["label"]=>
        string(3) "C++"
      }
    }

Jede vorbereitete Anweisung beansprucht Ressourcen auf dem Server, weshalb sie sofort nach ihrer Verwendung explizit geschlossen werden sollte. Falls dies nicht explizit geschieht, wird die Anweisung geschlossen, wenn das Anweisungs-Handle von PHP freigegeben wird.

Die Verwendung einer vorbereiteten Anweisung ist nicht immer die effizienteste Art, eine Anweisung auszuführen. Eine vorbereitete Anweisung, die nur einmal ausgeführt wird, verursacht mehr Client-Server-Umläufe (Roundtrips) als eine nicht-vorbereitete Anweisung. Aus diesem Grund wird die `SELECT`-Anweisung nicht als vorbereitete Anweisung ausgeführt.

Außerdem sollte für INSERTs die Verwendung der multi-INSERT-Syntax von MySQL in Betracht gezogen werden. Für das Beispiel erfordert multi-INSERT weniger Umläufe zwischen Server und Client als die oben gezeigte vorbereitete Anweisung.

Beispiel #3 Weniger Umläufe durch multi-INSERT-SQL

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $values = [1, 2, 3, 4];

    $stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?), (?), (?), (?)");
    $stmt->bind_param('iiii', ...$values);
    $stmt->execute();

Datentypen der Werte in der Ergebnismenge

Das MySQL-Client-Server-Protokoll definiert unterschiedliche Datenübertragungsprotokolle für vorbereitete Anweisungen und nicht-vorbereitete Anweisungen. Vorbereitete Anweisungen verwenden das sogenannte Binärprotokoll. Der MySQL-Server sendet die Ergebnisdaten "as is" (wie sie sind) im Binärformat. Die Ergebnisse werden vor dem Senden nicht zu Zeichenketten serialisiert. Die Client-Bibliotheken empfangen die binären Daten und versuchen, die Werte in geeignete PHP-Datentypen umzuwandeln. Zum Beispiel werden Ergebnisse aus einer SQL-`INT`-Spalte als PHP-Integer-Variablen bereitgestellt.

Beispiel #4 Native Datentypen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Nicht-vorbereitete Anweisung */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();
    $result = $stmt->get_result();
    $row = $result->fetch_assoc();

    printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
    printf("label = %s (%s)\n", $row['label'], gettype($row['label']));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    id = 1 (integer)
    label = PHP (string)

Dieses Verhalten unterscheidet sich von nicht-vorbereiteten Anweisungen. Standardmäßig geben nicht-vorbereitete Anweisungen alle Ergebnisse als Zeichenketten zurück. Diese Vorgabe kann mit einer Verbindungsoption geändert werden. Wenn diese Verbindungsoption verwendet wird, gibt es keine Unterschiede.

Ergebnisse über gebundene Variablen abrufen

Ergebnisse von vorbereiteten Anweisungen können entweder durch Binden der Ausgabevariablen oder durch Anfordern eines mysqli_result-Objekts abgerufen werden.

Die Ausgabevariablen müssen nach der Ausführung der Anweisung gebunden werden. Für jede Spalte der Ergebnismenge der Anweisung muss eine Variable gebunden werden.

Beispiel #5 Binden der Ausgabevariablen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Nicht-vorbereitete Anweisung */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();

    $stmt->bind_result($out_id, $out_label);

    while ($stmt->fetch()) {
        printf("id = %s (%s), label = %s (%s)\n", $out_id, gettype($out_id), $out_label, gettype($out_label));
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    id = 1 (integer), label = PHP (string)

Vorbereitete Anweisungen geben standardmäßig ungepufferte Ergebnismengen zurück. Die Ergebnisse der Anweisung werden nicht implizit vom Server abgerufen und zur clientseitigen Pufferung zum Client übertragen. Die Ergebnismenge nimmt solange Serverressourcen in Anspruch, bis alle Ergebnisse vom Client abgerufen wurden. Es wird daher empfohlen, die Ergebnisse frühzeitig abzurufen. Wenn ein Client nicht alle Ergebnisse abrufen kann oder der Client die Anweisung schließt, bevor er alle Daten geholt hat, müssen die Daten implizit mit `mysqli` abgerufen werden.

Mit mysqli_stmt::store_result() ist es auch möglich, die Ergebnisse einer vorbereiteten Anweisung zu puffern.

Abrufen der Ergebnisse über die mysqli_result-Schnittstelle.

Anstatt gebundene Ergebnisse zu verwenden, können die Ergebnisse auch über die mysqli_result-Schnittstelle abgerufen werden. mysqli_stmt::get_result() gibt eine gepufferte Ergebnismenge zurück.

Beispiel #6 Verwendung von mysqli_result zum Abrufen von Ergebnissen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Nicht-vorbereitete Anweisung */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
    $stmt->execute();

    $result = $stmt->get_result();

    var_dump($result->fetch_all(MYSQLI_ASSOC));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      [0]=>
      array(2) {
        ["id"]=>
        int(1)
        ["label"]=>
        string(3) "PHP"
      }
    }

Die Verwendung der mysqli_result-Schnittstelle bietet den zusätzlichen Vorteil einer flexiblen clientseitigen Navigation in der Ergebnismenge.

Beispiel #7 Gepufferte Ergebnismenge für flexibles Auslesen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Nicht-vorbereitete Anweisung */
    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT, label TEXT)");
    $mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP'), (2, 'Java'), (3, 'C++')");

    $stmt = $mysqli->prepare("SELECT id, label FROM test");
    $stmt->execute();

    $result = $stmt->get_result();

    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);
        var_dump($result->fetch_assoc());
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      ["id"]=>
      int(3)
      ["label"]=>
      string(3) "C++"
    }
    array(2) {
      ["id"]=>
      int(2)
      ["label"]=>
      string(4) "Java"
    }
    array(2) {
      ["id"]=>
      int(1)
      ["label"]=>
      string(3) "PHP"
    }

Maskierung und SQL-Injection

Die gebundenen Variablen werden getrennt von der Abfrage an den Server gesendet und können diese daher nicht beeinflussen. Der Server verwendet diese Werte erst zum Zeitpunkt der der Ausführung, nachdem die Anweisungsvorlage geparst wurde. Die gebundenen Parameter müssen nicht müssen nicht maskiert werden, da sie nie direkt in die Abfragezeichenkette eingefügt werden. Dem Server muss der Typ der gebundenen Variablen mitgeteilt werden, um eine geeignete Umwandlung zu ermöglichen. Siehe mysqli_stmt::bind_param() für weitere Informationen.

Diese Trennung wird oft als die einzige Möglichkeit angesehen, sich gegen SQL-Injection zu schützen, aber tatsächlich kann das gleiche Maß an Sicherheit auch mit nicht-vorbereiteten Anweisungen erreicht werden, wenn alle Werte korrekt formatiert sind. Es ist wichtig, zu beachten, dass eine korrekte Formatierung nicht dasselbe ist wie die Maskierung, und mehr Logik beinhaltet. Daher sind vorbereitete Anweisungen einfach ein bequemerer und weniger fehleranfälliger Ansatz, um dieses Niveau an Datenbanksicherheit zu erreichen.

Clientseitige Emulation vorbereiteter Anweisungen

Die API enthält keine Emulation für die clientseitige Emulation von vorbereiteten Anweisungen.

Siehe auch

- mysqli::__construct()
- mysqli::query()
- mysqli::prepare()
- mysqli_stmt::prepare()
- mysqli_stmt::execute()
- mysqli_stmt::bind_param()
- mysqli_stmt::bind_result()

## Gespeicherte Prozeduren (Stored Procedures)

Die MySQL-Datenbank unterstützt gespeicherte Prozeduren. Eine gespeicherte Prozedur ist ein Unterprogramm, das im Datenbankkatalog gespeichert ist. Anwendungen können die gespeicherte Prozedur aufrufen und ausführen. Um eine gespeicherte Prozedur auszuführen, wird die SQL-Anweisung `CALL` verwendet.

Parameter

In Abhängigkeit von der MySQL-Version können gespeicherte Prozeduren die Parameter `IN`, `INOUT` und `OUT` haben. Die mysqli-Schnittstelle selbst hat keine speziellen Bezeichnungen für die verschiedenen Arten von Parametern.

Der Parameter IN

Die Eingabeparameter werden mit der Anweisung `CALL` bereitgestellt. Bitte stellen Sie sicher, dass die Werte korrekt maskiert sind.

Beispiel #1 Aufrufen einer gespeicherten Prozedur

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query("CREATE PROCEDURE p(IN id_val INT) BEGIN INSERT INTO test(id) VALUES(id_val); END;");

    $mysqli->query("CALL p(1)");

    $result = $mysqli->query("SELECT id FROM test");

    var_dump($result->fetch_assoc());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["id"]=>
      string(1) "1"
    }

Die Parameter INOUT/OUT

Auf die Werte der Parameter `INOUT`/`OUT` wird über Session-Variablen zugegriffen.

Beispiel #2 Verwendung von Session-Variablen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p(OUT msg VARCHAR(50)) BEGIN SELECT "Hi!" INTO msg; END;');

    $mysqli->query("SET @msg = ''");
    $mysqli->query("CALL p(@msg)");

    $result = $mysqli->query("SELECT @msg as _p_out");

    $row = $result->fetch_assoc();
    echo $row['_p_out'];

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hi!

Anwendungs- und Framework-Entwickler können gegebenenfalls eine komfortablere API bereitstellen, die neben Session-Variablen auch das direkte Durchsuchen von Datenbankkatalogen verwendet. Dabei sind jedoch die Leistungseinbußen zu beachten, die eine benutzerdefinierte Lösung auf Basis der Kataloginspektion haben kann.

Umgang mit Ergebnismengen

Gespeicherte Prozeduren können Ergebnismengen zurückgeben. Ergebnismengen, die von einer gespeicherten Prozedur zurückgegeben werden, können mit mysqli::query() nicht korrekt abgerufen werden. Die Funktion mysqli::query() führt die Anweisung aus und ruft, falls vorhanden, die erste Ergebnismenge in einen Puffer ab. Gespeicherte Prozeduren können jedoch weitere Ergebnismengen zurückgeben, die dem Benutzer verborgen sind, was dazu führt, dass mysqli::query() nicht die vom Benutzer erwarteten Ergebnismengen zurückgibt.

Ergebnismengen, die von einer gespeicherten Prozedur zurückgegeben werden, werden mit mysqli::real_query() oder mysqli::multi_query() abgerufen. Beide Funktionen ermöglichen das Abrufen einer beliebigen Anzahl von Ergebnismengen, die von einer Anweisung wie `CALL` zurückgegeben werden. Gelingt es nicht, alle Ergebnismengen abzurufen, die von einer gespeicherten Prozedur zurückgegeben wurden, löst das einen Fehler aus.

Beispiel #3 Ergebnisse von gespeicherten Prozeduren abrufen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $mysqli->multi_query("CALL p()");

    do {
        if ($result = $mysqli->store_result()) {
            printf("---\n");
            var_dump($result->fetch_all());
            $result->free();
        }
    } while ($mysqli->next_result());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        string(1) "1"
      }
      [1]=>
      array(1) {
        [0]=>
        string(1) "2"
      }
      [2]=>
      array(1) {
        [0]=>
        string(1) "3"
      }
    }
    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        string(1) "2"
      }
      [1]=>
      array(1) {
        [0]=>
        string(1) "3"
      }
      [2]=>
      array(1) {
        [0]=>
        string(1) "4"
      }
    }

Verwendung von vorbereiteten Anweisungen

Es ist keine besondere Vorgehensweise erforderlich, wenn die Schnittstelle für vorbereitete Anweisungen zum Abrufen von Ergebnissen aus der gleichen gespeicherten Prozedur wie oben verwendet wird. Die Schnittstellen für vorbereitete und nicht-vorbereitete Anweisungen sind ähnlich. Es ist zu beachten, dass nicht jede Version des MYSQL-Servers die Vorbereitung der SQL-Anweisung `CALL` unterstützt.

Beispiel #4 Gespeicherte Prozeduren und vorbereitete Anweisungen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $stmt = $mysqli->prepare("CALL p()");

    $stmt->execute();

    do {
        if ($result = $stmt->get_result()) {
            printf("---\n");
            var_dump($result->fetch_all());
            $result->free();
        }
    } while ($stmt->next_result());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        int(1)
      }
      [1]=>
      array(1) {
        [0]=>
        int(2)
      }
      [2]=>
      array(1) {
        [0]=>
        int(3)
      }
    }
    ---
    array(3) {
      [0]=>
      array(1) {
        [0]=>
        int(2)
      }
      [1]=>
      array(1) {
        [0]=>
        int(3)
      }
      [2]=>
      array(1) {
        [0]=>
        int(4)
      }
    }

Natürlich wird auch die Verwendung der bind-API für das Abrufen von Daten unterstützt.

Beispiel #5 Gespeicherte Prozeduren und vorbereitete Anweisungen mit der bind-API

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");
    $mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

    $mysqli->query("DROP PROCEDURE IF EXISTS p");
    $mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

    $stmt = $mysqli->prepare("CALL p()");

    $stmt->execute();

    do {
        if ($stmt->store_result()) {
            $stmt->bind_result($id_out);
            while ($stmt->fetch()) {
                echo "id = $id_out\n";
            }
        }
    } while ($stmt->next_result());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    id = 1
    id = 2
    id = 3
    id = 2
    id = 3
    id = 4

Siehe auch

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## Mehrfach-Anweisungen

Bei MySQL ist es optional möglich, mehrere Anweisungen in einer Anweisungszeile zu haben, was aber eine besondere Vorgehensweise erfordert.

Mehrfach-Anweisungen oder Mehrfach-Abfragen müssen mit mysqli::multi_query() ausgeführt werden. Die einzelnen Anweisungen der Anweisungszeile werden durch Semikolon getrennt. Anschließend müssen alle Ergebnismengen, die von den ausgeführten Anweisungen zurückgegeben werden, abgerufen werden.

Der MySQL-Server erlaubt es, Anweisungen, die Ergebnismengen zurückgeben, und Anweisungen, die keine Ergebnismengen zurückgeben, in einer Mehrfach-Anweisung zu verwenden.

Beispiel #1 Mehrere Anweisungen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $mysqli->query("DROP TABLE IF EXISTS test");
    $mysqli->query("CREATE TABLE test(id INT)");

    $sql = "SELECT COUNT(*) AS _num FROM test;
            INSERT INTO test(id) VALUES (1);
            SELECT COUNT(*) AS _num FROM test; ";

    $mysqli->multi_query($sql);

    do {
        if ($result = $mysqli->store_result()) {
            var_dump($result->fetch_all(MYSQLI_ASSOC));
            $result->free();
        }
    } while ($mysqli->next_result());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "0"
      }
    }
    array(1) {
      [0]=>
      array(1) {
        ["_num"]=>
        string(1) "1"
      }
    }

Sicherheitstechnische Überlegungen

Die API-Funktionen mysqli::query() und mysqli::real_query() setzen kein Verbindungsflag auf dem Server, das für die Aktivierung von Mehrfach-Abfragen benötigt wird. Für Mehrfach-Anweisungen wird ein zusätzlicher API-Aufruf verwendet, um den Schaden von Angriffen mit SQL-Injections zu verringern. Ein Angreifer könnte versuchen, Anweisungen wie `; DROP DATABASE mysql` oder `; SELECT SLEEP(999)` an das Ende einer Anweisung anzuhängen. Wenn es dem Angreifer gelingt, SQL zur Anweisung hinzuzufügen, aber mysqli::multi_query() nicht verwendet wird, führt der Server die eingeschleuste bösartige SQL-Anweisung nicht aus.

Beispiel #2 SQL-Injection

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $result = $mysqli->query("SELECT 1; DROP TABLE mysql.user");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    PHP Fatal error:  Uncaught mysqli_sql_exception: You have an error in your SQL syntax;
    check the manual that corresponds to your MySQL server version for the right syntax to
    use near 'DROP TABLE mysql.user' at line 1

Vorbereitete Anweisungen

Die Verwendung der Mehrfach-Anweisung wird bei vorbereiteten Anweisungen nicht unterstützt.

Siehe auch

- mysqli::query()
- mysqli::multi_query()
- mysqli::next_result()
- mysqli::more_results()

## API-Unterstützung für Transaktionen

Je nach verwendeter Speicher-Engine unterstützt der MySQL-Server Transaktionen. Seit MySQL 5.5 ist InnoDB die Standard-Speicher-Engine. InnoDB bietet volle Unterstützung für ACID-Transaktionen.

Transaktionen können entweder mit SQL oder über API-Aufrufe gesteuert werden. Es wird empfohlen, API-Aufrufe zu verwenden, um den `autocommit`-Modus zu aktivieren oder zu deaktivieren und um Transaktionen zu übertragen (Commit) und rückgängig zu machen (Rollback).

Beispiel #1 Einstellen des `autocommit`-Modus mit SQL und über die API

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    /* Empfohlen: Verwendung der API zur Steuerung von Transaktionseinstellungen */
    $mysqli->autocommit(false);

    /* Wird von Replikations- und Load-Balancing-Plugins nicht erkannt und überwacht */
    $mysqli->query('SET AUTOCOMMIT = 0');

Optionale Zusatzpakete, z. B. das Replikations- und Load-Balancing-Plugin, können API-Aufrufe problemlos überwachen. Wenn Transaktionen über API-Aufrufe gesteuert werden, bietet das Replikations-Plugin transaktionsbezogenes Load-Balancing. Transaktionsbezogenes Load-Balancing ist nicht verfügbar, wenn SQL-Anweisungen verwendet werden, um den `autocommit`-Modus zu setzen oder Transaktionen zu übertragen oder rückgängig zu machen.

Beispiel #2 Übertragen und Zurücksetzen (Commit und Rollback)

    <?php
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");
    $mysqli->autocommit(false);

    $mysqli->query("INSERT INTO test(id) VALUES (1)");
    $mysqli->rollback();

    $mysqli->query("INSERT INTO test(id) VALUES (2)");
    $mysqli->commit();

Es ist zu beachten, dass der MySQL-Server nicht alle Anweisungen zurücknehmen kann. Einige Anweisungen führen zu einem impliziten Commit.

Siehe auch

- mysqli::autocommit()
- mysqli::begin_transaction()
- mysqli::commit()
- mysqli::rollback()

## Metadaten

Eine MySQL-Ergebnismenge enthält Metadaten. Die Metadaten beschreiben die Spalten, die in der Ergebnismenge gefunden werden. Alle von MySQL gesendeten Metadaten sind über die `mysqli`-Schnittstelle verfügbar. Die Erweiterung führt keine oder vernachlässigbare Änderungen an den Informationen durch, die sie empfängt. Die Unterschiede zwischen den MySQL-Server-Versionen werden nicht angeglichen.

Auf die Metadaten wird über die mysqli_result-Schnittstelle zugegriffen.

Beispiel #1 Zugriff auf die Metadaten der Ergebnismenge

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $result = $mysqli->query("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
    var_dump($result->fetch_fields());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      [0]=>
      object(stdClass)#3 (13) {
        ["name"]=>
        string(4) "_one"
        ["orgname"]=>
        string(0) ""
        ["table"]=>
        string(0) ""
        ["orgtable"]=>
        string(0) ""
        ["def"]=>
        string(0) ""
        ["db"]=>
        string(0) ""
        ["catalog"]=>
        string(3) "def"
        ["max_length"]=>
        int(1)
        ["length"]=>
        int(1)
        ["charsetnr"]=>
        int(63)
        ["flags"]=>
        int(32897)
        ["type"]=>
        int(8)
        ["decimals"]=>
        int(0)
      }
      [1]=>
      object(stdClass)#4 (13) {
        ["name"]=>
        string(4) "_two"
        ["orgname"]=>
        string(0) ""
        ["table"]=>
        string(0) ""
        ["orgtable"]=>
        string(0) ""
        ["def"]=>
        string(0) ""
        ["db"]=>
        string(0) ""
        ["catalog"]=>
        string(3) "def"
        ["max_length"]=>
        int(5)
        ["length"]=>
        int(5)
        ["charsetnr"]=>
        int(8)
        ["flags"]=>
        int(1)
        ["type"]=>
        int(253)
        ["decimals"]=>
        int(31)
      }
    }

Vorbereitete Anweisungen

Auf die Metadaten von Ergebnismengen, die mit vorbereiteten Anweisungen erstellt wurden, wird auf die gleiche Weise zugegriffen. Ein geeignetes mysqli_result-Handle wird von mysqli_stmt::result_metadata() zurückgegeben.

Beispiel #2 Metadaten der vorbereiteten Anweisungen

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("example.com", "user", "password", "database");

    $stmt = $mysqli->prepare("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
    $stmt->execute();
    $result = $stmt->result_metadata();
    var_dump($result->fetch_fields());

Siehe auch

- mysqli::query()
- mysqli_result::fetch_fields()

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

Um diese Erweitertung zu benutzen muss PHP mit Support für die mysqli Erweiterung compiliert werden.

MySQL 8

Bei der Verwendung von PHP vor 7.1.16 oder PHP 7.2 vor 7.2.4, ist als Standard Passwort-Plugin des MySQL 8 Servers mysql_native_password zu konfigurieren; andernfalls werden Fehlermeldungen in der Art The server requested authentication method unknown to the client [caching_sha2_password] auftreten, selbst wenn caching_sha2_password nicht verwendet wird.

Das liegt daran, dass MySQL 8 standardmäßig caching_sha2_password verwendet und dieses Plugin von den älteren PHP- (mysqlnd) Versionen nicht erkannt wird. Stattdessen muss die Voreinstellung durch den Eintrag `default_authentication_plugin=mysql_native_password` in der Datei my.cnf geändert werden. Das Plugin caching_sha2_password wird seit PHP 7.4.4 vollständig unterstützt. In älteren Versionen wird es von der Erweiterung mysql_xdevapi unterstützt.

## Installation

Die `mysqli`-Erweiterung wurde in PHP 5.0.0 eingeführt; der MySQL Native Driver mit PHP 5.3.0.

## Installation unter Linux

Die gängigen Unix-Distributionen enthalten Binärversionen von PHP, die installiert werden können. Obwohl diese Binärversionen typischerweise mit Unterstützung für die MySQL-Erweiterungen erstellt wurden, müssen möglicherweise die Erweiterungs-Bibliotheken selbst unter Verwendung eines zusätzlichen Pakets installiert werden. Die Paketverwaltung der gewählten Distribution ist auf dessen Verfügbarkeit zu prüfen.

Beispielsweise installiert unter Ubuntu das Paket `php5-mysql` die PHP-Erweiterungen ext/mysql, ext/mysqli und pdo_mysql. Unter CentOS installiert das Paket `php-mysql` diese drei Erweiterungen ebenfalls.

Alternativ kann diese Erweiterung auch selbst kompiliert werden. Das Kompilieren von PHP aus den Quellen erlaubt die Auswahl der MySQL-Erweiterungen, die verwendet werden sollen, sowie die Wahl der Client-Bibliothek für jede Erweiterung.

Der MySQL Native Driver wird empfohlen, da er zu einer verbesserten Performance führt und Zugriff auf Funktionen gewährt, die bei der Verwendung der MySQL-Client-Bibliothek nicht zur Verfügung stehen. Lesen Sie Was versteht man unter dem MySQL Native Driver von PHP?, um einen kurzen Überblick über die Vorteile des MySQL Native Drivers zu erhalten.

`/path/to/mysql_config` stellt den Pfad des `mysql_config`-Programms dar, das mit MySQL-Server ausgeliefert wird.

Unterstützungsmatrix für die MySQLi-Kompilierung
PHP-Version | Standard | Konfigurationsoptionen: mysqlnd | Konfigurationsoptionen: `libmysqlclient` | Changelog
--- | --- | --- | --- | ---
5.4.x und höher | mysqlnd | --with-mysqli | --with-mysqli=/path/to/mysql_config | mysqlnd ist nun standardmäßig aktiviert
5.3.x | libmysqlclient | --with-mysqli=mysqlnd | --with-mysqli=/path/to/mysql_config | mysqlnd wird unterstützt
5.0.x, 5.1.x, 5.2.x | libmysqlclient | Nicht verfügbar | --with-mysqli=/path/to/mysql_config | mysqlnd wird nicht unterstützt

Es ist möglich, MySQL-Erweiterungen und Client-Bibliotheken frei zu mischen. Zum Beispiel ist es denkbar, dass die MySQL-Erweiterung die MySQL-Client-Bibliothek (libmysqlclient) verwendet, während die `mysqli`-Erweiterung so konfiguriert ist, dass sie den MySQL Native Driver verwendet. Alle Kombinationen von Erweiterungen und Client-Bibliotheken sind möglich.

## Installation auf Windows-Systemen

Unter Windows muss die DLL php_mysqli.dll in der php.ini aktiviert werden.

Wie bei der Aktivierung jeder anderen PHP-Erweiterung (wie z. B. php_mysqli.dll) sollte auch hier die PHP-Anweisung extension_dir auf das Verzeichnis zeigen, in dem die vorhandenen PHP-Erweiterungen liegen. Siehe dazu auch den Abschnitt Manuelle PHP-Installation auf Windows. Ein entsprechender `extension_dir`-Wert ist zum Beispiel c:\php\ext.

> Hinweis:

> Wenn beim Starten des Webservers ein Fehler ähnlich dem folgenden auftritt: `"Unable to load dynamic library './php_mysqli.dll'"`, liegt das daran, dass php_mysqli.dll vom System nicht gefunden wird.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

MySQLi-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
mysqli.allow_local_infile | "0" | `INI_SYSTEM` | Vor PHP 7.2.16 und 7.3.3 war der Standardwert "1".
mysqli.local_infile_directory |  | `INI_SYSTEM` | Verfügbar seit PHP 8.1.0.
mysqli.allow_persistent | "1" | `INI_SYSTEM` |
mysqli.max_persistent | "-1" | `INI_SYSTEM` |
mysqli.max_links | "-1" | `INI_SYSTEM` |
mysqli.default_port | "3306" | `INI_ALL` |
mysqli.default_socket | NULL | `INI_ALL` |
mysqli.default_host | NULL | `INI_ALL` |
mysqli.default_user | NULL | `INI_ALL` |
mysqli.default_pw | NULL | `INI_ALL` |
mysqli.reconnect | "0" | `INI_SYSTEM` | Entfernt in PHP 8.2.0
mysqli.rollback_on_cached_plink | "0" | `INI_SYSTEM` |

Für weitere Details und Definitionen über die oben genannten INI_*-Konstanten siehe das Kapitel über Konfigurations-Änderungen.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`mysqli.allow_local_infile` bool

  Erlaubt den Zugriff auf, aus der Persepektive von PHP, lokale Dateien mit LOAD DATA-Anweisungen.

`mysqli.local_infile_directory` string

  Erlaubt es, das Laden von LOCAL DATA auf Dateien zu beschränken, die sich in diesem bestimmten Verzeichnis befinden.

`mysqli.allow_persistent` bool

  Aktiviert die Möglichkeit, persistente Verbindungen mittels mysqli_connect() zu erstellen.

`mysqli.max_persistent` int

  Die maximale Anzahl persistenter Verbindungen. Ist der Wert auf 0 gesetzt, ist die Anzahl unbegrenzt.

`mysqli.max_links` int

  Die maximale Anzahl von MySQL-Verbindungen pro Prozess.

`mysqli.default_port` int

  Die Standard-TCP-Portnummer, die benutzt werden soll, wenn eine Verbindung zum Datenbankserver aufgebaut werden soll und kein anderer Port explizit angegeben wurde. Wenn hier kein Standardport angegeben wird, wird der Port aus der `MYSQL_TCP_PORT` Umgebungs-Variable, dem `mysql-tcp`-Eintrag in der /etc/services oder der compile-time `MYSQL_PORT`-Konstante (in dieser Reihenfolge) verwendet. Win32 benutzt nur die `MYSQL_PORT`-Konstante.

`mysqli.default_socket` string

  Der Standard-Socketname, der beim Verbindungsaufbau zu einem lokalen Datenbankserver verwendet wird, sofern kein anderer Socketname angegeben wurde.

`mysqli.default_host` string

  Der Standard-Server-Host, der beim Verbindungsaufbau zu einem lokalen Datenbankserver verwendet wird, sofern kein anderer Host angegeben wurde.

`mysqli.default_user` string

  Der Standard-Benutzername, der beim Verbindungsaufbau zu einem lokalen Datenbankserver verwendet wird, sofern kein anderer Name angegeben wurde.

`mysqli.default_pw` string

  Das Standard-Passwort, das beim Verbindungsaufbau zu einem lokalen Datenbankserver verwendet wird, sofern kein anderes Passwort angegeben wurde.

`mysqli.reconnect` int

  Automatischer Neuaufbau der Verbindung, falls die Verbindung getrennt wird.

  > Hinweis: Diese php.ini-Einstellung wurde vom mysqlnd-Treiber ignoriert und in PHP 8.2.0 entfernt.

`mysqli.rollback_on_cached_plink` bool

  Ist diese Option aktiviert, dann werden beim Schließen einer persistenten Verbindung alle ausstehenden Transaktionen dieser Verbindung zurückgesetzt, bevor sie in den Pool der persistenten Verbindungen zurückgestellt wird. Andernfalls werden ausstehende Transaktionen erst zurückgesetzt, wenn die Verbindung wiederverwendet oder wenn sie tatsächlich geschlossen wird.

Benutzer können `MYSQL_OPT_READ_TIMEOUT` nicht durch einen API-Aufruf oder Laufzeit-Konfigurationseinstellungen ändern. Es ist zu beachten, dass es, wenn das möglich wäre, Unterschiede gäbe, wie `libmysqlclient` und Streams den Wert von `MYSQL_OPT_READ_TIMEOUT` interpretieren.

# Die Erweiterung mysqli und persistente (beständige) Verbindungen

Die Idee hinter persistenten Verbindungen ist, dass eine Verbindung zwischen einem Client-Prozess und einer Datenbank von einem Client-Prozess mehrfach verwendet werden kann, anstatt jedes Mal neu erstellt und zerstört zu werden. Da ungenutzte Verbindungen zwischengespeichert werden und zur Wiederverwendung bereitstehen, reduziert sich der Mehraufwand, der entsteht, wenn jedes Mal eine neue Verbindung erstellt werden muss.

Im Gegensatz zur Erweiterung mysql bietet mysqli keine eigene Funktion zum Öffnen von persistenten Verbindungen. Um eine persistente Verbindung zu öffnen, muss dem Hostnamen beim Aufbau der Verbindung das Präfix `p:` vorangestellt werden.

Das Problem bei persistenten Verbindungen ist, dass sie von Clients in unvorhersehbaren Zuständen hinterlassen werden können. Zum Beispiel könnte eine Tabellensperre aktiviert werden, bevor ein Client unerwartet beendet wird. Ein neuer Client-Prozess, der diese persistente Verbindung wiederverwendet, erhält die Verbindung as is (so wie sie ist). Der neue Client-Prozess müsste alle notwendigen Aufräumarbeiten durchführen, bevor er die persistente Verbindung sinnvoll nutzen kann, was den Aufwand für den Programmierer erhöht.

Für diese Aufräumarbeiten ist in der persistenten Verbindung der Erweiterung `mysqli` jedoch ein entsprechender Code enthalten. Die Aufräumarbeiten, die von `mysqli` durchgeführt werden, umfassen:

- das Rollback aktiver Transaktionen

- das Schließen und Löschen temporärer Tabellen

- das Entsperren von Tabellen

- das Zurücksetzen von Sessionvariablen

- das Schließen vorbereiteter Anweisungen (geschieht bei PHP immer)

- das Schließen von Handlern

- die Freigabe von Sperren, die mit GET_LOCK() gesetzt wurden

Dadurch wird sichergestellt, dass sich eine persistente Verbindungen in einem bereinigten Zustand befindet, wenn sie aus dem Verbindungs-Pool abgerufen wird, bevor der Client-Prozess sie verwendet.

Die Erweiterung `mysqli` erledigt diese Bereinigung durch den automatischen Aufruf der C-API-Funktion `mysql_change_user()`.

Die automatisierte Bereinigung hat jedoch Vor- und Nachteile. Der Vorteil ist, dass der Programmierer sich nicht mehr darum kümmern muss, den Bereinigungscode hinzuzufügen, da er automatisch aufgerufen wird. Der Nachteil ist jedoch, dass der Code eventuell etwas langsamer sein könnte, da er zur Durchführung der Bereinigung jedes Mal ausgeführt werden muss, wenn eine Verbindung aus dem Verbindungs-Pool abgerufen wird.

Der Code für die automatische Bereinigung kann abgeschaltet werden, indem PHP mit der Option `MYSQLI_NO_CHANGE_USER_ON_PCONNECT` kompiliert wird.

> Hinweis:

> Die Erweiterung `mysqli` unterstützt persistente Verbindungen, wenn sie entweder den MySQL Native Driver oder die MySQL Client Library verwendet.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`MYSQLI_READ_DEFAULT_GROUP` (int)

  Liest Optionen der angegebenen Gruppe aus my.cnf oder der mit `MYSQLI_READ_DEFAULT_FILE` angegebenen Datei.

`MYSQLI_READ_DEFAULT_FILE` (int)

  Liest Optionen aus der angegebenen Datei anstelle von my.cnf.

`MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Teilt dem Server mit, dass der Client mit dem Sandbox-Modus für abgelaufene Passwörter umgehen kann. Kann in Verbindung mit mysqli_options() verwendet werden.
`MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` (int)
  Wenn diese Option aktiviert ist, gibt sie das Verzeichnis an, aus dem bei `LOAD DATA LOCAL`-Anweisungen das clientseitige Laden von `LOCAL`-Daten erlaubt ist.
`MYSQLI_OPT_CONNECT_TIMEOUT` (int)

  Der Verbindungs-Timeout in Sekunden.

`MYSQLI_OPT_READ_TIMEOUT` (int)

  Der Timeout für das Ergebnis der Befehlsausführung in Sekunden. Verfügbar ab PHP 7.2.0.

`MYSQLI_OPT_LOCAL_INFILE` (int)

  Ermöglicht den Befehl `LOAD LOCAL INFILE`.

`MYSQLI_OPT_INT_AND_FLOAT_NATIVE` (int)

  Konvertiert Integer- und Float-Spalten zurück in PHP-Zahlen. Nur gültig für mysqlnd.

`MYSQLI_OPT_NET_CMD_BUFFER_SIZE` (int)

  Die Größe des internen Kommando-/Netzwerkpuffers. Nur gültig für mysqlnd.

`MYSQLI_OPT_NET_READ_BUFFER_SIZE` (int)

  Die Maximalgröße der Datenblöcke in Bytes, wenn der Textkörper eines MySQL-Befehlspakets gelesen wird. Nur gültig für mysqlnd.

`MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` (int)

`MYSQLI_INIT_COMMAND` (int)

  Das Kommando, das beim Aufbau der Verbindung zum MySQL-Server ausgeführt werden soll. Dieses Kommando wird auch bei der automatischen Wiederaufnahme der Verbindung nach Unterbrechungen ausgeführt.

`MYSQLI_CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  Teilt dem Server mit, dass der Client mit dem Sandbox-Modus für abgelaufene Passwörter umgehen kann. Kann in Verbindung mit mysqli_real_connect() verwendet werden.
`MYSQLI_CLIENT_FOUND_ROWS` (int)
  Gibt die Anzahl der übereinstimmenden Zeilen zurück, nicht die Anzahl der betroffenen Zeilen.
`MYSQLI_CLIENT_SSL_VERIFY_SERVER_CERT` (int)
  Überprüft das Zertifikat des Servers.
`MYSQLI_CLIENT_SSL` (int)

  Verwendet SSL-Verschlüsselung. Diese Option sollte nicht von Anwendungen gesetzt werden, sie wird stattdessen von der MySQL-Client-Bibliothek intern gesetzt.

`MYSQLI_CLIENT_COMPRESS` (int)

  Verwendet komprimierte Übertragung.

`MYSQLI_CLIENT_INTERACTIVE` (int)

  Unterbricht die Verbindung nach `interactive_timeout` Sekunden Inaktivität (an Stelle von `wait_timeout`). Die `wait_timeout`-Variable der Verbindungs-Session wird auf den Wert der `interactive_timeout`-Variablen der Session gesetzt.

`MYSQLI_CLIENT_IGNORE_SPACE` (int)

  Ermöglicht Leerzeichen nach Funktionsnamen, dadurch werden alle Funktionsnamen automatisch zu reservierten Worten.

`MYSQLI_CLIENT_NO_SCHEMA` (int)

  Deaktiviert die `datenbank.tabelle.spalte`-Syntax.

`MYSQLI_CLIENT_MULTI_QUERIES`

  Ermöglicht mehrere durch Semikolon getrennte Abfragen innerhalb eines einzelnen mysqli_query()-Aufrufs.

`MYSQLI_STORE_RESULT` (int)

  Die Abfrageergebnisse werden clientseitig gepuffert. Diese Konstante hat den Wert `0`.

`MYSQLI_STORE_RESULT_COPY_DATA` (int)
  Seit PHP 8.1 hat diese Konstante keine Wirkung mehr. Vor PHP 8.1 wurde diese Konstante verwendet, um Ergebnisse aus dem internen `mysqlnd`-Puffer in die abgerufenen PHP-Variablen zu kopieren. Standardmäßig verwendet `mysqlnd` eine Referenzlogik, um zu vermeiden, dass im Speicher befindliche Ergebnisse kopiert und dupliziert werden. Für bestimmte Ergebnismengen, z. B. Ergebnismengen mit vielen kleinen Zeilen, kann der Kopieransatz den Gesamtspeicherverbrauch reduzieren, weil die PHP-Variablen mit den Ergebnissen früher freigegeben werden können. Nur in Verbindung mit `mysqlnd` verfügbar. Veraltet seit PHP 8.4.0.
`MYSQLI_USE_RESULT` (int)

  Die Abfrageergebnisse werden nicht clientseitig gepuffert. Diese Konstante hat den Wert `1`.

`MYSQLI_ASSOC` (int)

  Die Spaltenwerte werden als Array mit dem Spaltennamen als Schlüssel zurückgegeben.

`MYSQLI_NUM` (int)

  Die Spaltenwerte werden als Array mit der Spaltennummer als Schlüssel zurückgegeben.

`MYSQLI_BOTH` (int)

  Die Spaltenwerte werden als Array mit sowohl der Spaltennummer als auch dem Spaltennamen als Schlüssel zurückgegeben.

`MYSQLI_NOT_NULL_FLAG` (int)

  Gibt an, dass eine Spalte als `NOT NULL` definiert ist.

`MYSQLI_PRI_KEY_FLAG` (int)

  Die Spalte ist Teil eines Primärschlüssels.

`MYSQLI_UNIQUE_KEY_FLAG` (int)

  Die Spalte ist Teil eines Unique-Index.

`MYSQLI_MULTIPLE_KEY_FLAG` (int)

  Die Spalte ist Teil eines Index.

`MYSQLI_BLOB_FLAG` (int)

  Die Spalte ist als `BLOB` definiert.

`MYSQLI_UNSIGNED_FLAG` (int)

  Die Spalte ist als `UNSIGNED` definiert.

`MYSQLI_ZEROFILL_FLAG` (int)

  Die Spalte ist als `ZEROFILL` definiert.

`MYSQLI_AUTO_INCREMENT_FLAG` (int)

  Die Spalte ist als `AUTO_INCREMENT` definiert.

`MYSQLI_TIMESTAMP_FLAG` (int)

  Die Spalte ist als `TIMESTAMP` definiert.

`MYSQLI_SET_FLAG` (int)

  Die Spalte ist als `SET` definiert.

`MYSQLI_NUM_FLAG` (int)

  Die Spalte ist als `NUMERIC` definiert.

`MYSQLI_PART_KEY_FLAG` (int)

  Die Spalte ist Teil eines mehrspaltigen Index.

`MYSQLI_GROUP_FLAG` (int)

  Die Spalte ist Teil der `GROUP BY`-Bedingung.

`MYSQLI_NO_DEFAULT_VALUE_FLAG` (int)
  In der Definition einer Spalte gibt es keine `DEFAULT`-Klausel. Dies gilt nicht für `NULL`- oder `AUTO_INCREMENT`-Spalten, weil solche Spalten einen Standardwert von `NULL` bzw. einen impliziten Standardwert haben.
`MYSQLI_TYPE_DECIMAL` (int)

  Die Spalte ist als `DECIMAL` definiert.

`MYSQLI_TYPE_NEWDECIMAL` (int)

  Die Spalte ist als `DECIMAL` oder `NUMERIC` definiert.

`MYSQLI_TYPE_BIT` (int)

  Die Spalte ist als `BIT` definiert.

`MYSQLI_TYPE_TINY` (int)

  Die Spalte ist als `TINYINT` definiert.

`MYSQLI_TYPE_SHORT` (int)

  Die Spalte ist als `SMALLINT` definiert.

`MYSQLI_TYPE_LONG` (int)

  Die Spalte ist als `INT` definiert.

`MYSQLI_TYPE_FLOAT` (int)

  Die Spalte ist als `FLOAT` definiert.

`MYSQLI_TYPE_DOUBLE` (int)

  Die Spalte ist als `DOUBLE` definiert.

`MYSQLI_TYPE_NULL` (int)

  Die Spalte ist als `DEFAULT NULL` definiert.

`MYSQLI_TYPE_TIMESTAMP` (int)

  Die Spalte ist als `TIMESTAMP` definiert.

`MYSQLI_TYPE_LONGLONG` (int)

  Die Spalte ist als `BIGINT` definiert.

`MYSQLI_TYPE_INT24` (int)

  Die Spalte ist als `MEDIUMINT` definiert.

`MYSQLI_TYPE_DATE` (int)

  Die Spalte ist als `DATE` definiert.

`MYSQLI_TYPE_TIME` (int)

  Die Spalte ist als `TIME` definiert.

`MYSQLI_TYPE_DATETIME` (int)

  Die Spalte ist als `DATETIME` definiert.

`MYSQLI_TYPE_YEAR` (int)

  Die Spalte ist als `YEAR` definiert.

`MYSQLI_TYPE_NEWDATE` (int)

  Die Spalte ist als `DATE` definiert.

`MYSQLI_TYPE_INTERVAL` (int)

  Alias von `MYSQLI_TYPE_ENUM`. Entfernt in PHP 8.4.0.

`MYSQLI_TYPE_ENUM` (int)

  Die Spalte ist als `ENUM` definiert.

`MYSQLI_TYPE_SET` (int)

  Die Spalte ist als `SET` definiert.

`MYSQLI_TYPE_TINY_BLOB` (int)

  Die Spalte ist als `TINYBLOB` definiert.

`MYSQLI_TYPE_MEDIUM_BLOB` (int)

  Die Spalte ist als `MEDIUMBLOB` definiert.

`MYSQLI_TYPE_LONG_BLOB` (int)

  Die Spalte ist als `LONGBLOB` definiert.

`MYSQLI_TYPE_BLOB` (int)

  Die Spalte ist als `BLOB` definiert.

`MYSQLI_TYPE_VAR_STRING` (int)

  Die Spalte ist als `VARCHAR` definiert.

`MYSQLI_TYPE_STRING` (int)

  Die Spalte ist als `CHAR` oder `BINARY` definiert.

`MYSQLI_TYPE_CHAR` (int)

  Die Spalte ist als `TINYINT` definiert. Für `CHAR`, siehe `MYSQLI_TYPE_STRING`.

`MYSQLI_TYPE_GEOMETRY` (int)

  Die Spalte ist als `GEOMETRY` definiert.

`MYSQLI_TYPE_JSON` (int)

  Die Spalte ist als `JSON` definiert. Nur gültig für mysqlnd und MySQL 5.7.8 und höher.

`MYSQLI_TYPE_VECTOR` (int)

  Die Spalte ist als `VECTOR` definiert.

`MYSQLI_NEED_DATA`

  Weitere Daten für eine gebundene Variable verfügbar.

`MYSQLI_ENUM_FLAG` (int)

  Die Spalte ist als `ENUM` definiert.

`MYSQLI_BINARY_FLAG` (int)

  Die Spalte ist als `BINARY` definiert.

`MYSQLI_CURSOR_TYPE_FOR_UPDATE` (int)

  Entfernt in PHP 8.4.0.

`MYSQLI_CURSOR_TYPE_NO_CURSOR` (int)

`MYSQLI_CURSOR_TYPE_READ_ONLY` (int)

`MYSQLI_CURSOR_TYPE_SCROLLABLE` (int)

  Entfernt in PHP 8.4.0.

`MYSQLI_STMT_ATTR_CURSOR_TYPE` (int)

`MYSQLI_STMT_ATTR_PREFETCH_ROWS` (int)

  Entfernt in PHP 8.4.0.

`MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH` (int)

`MYSQLI_SET_CHARSET_NAME` (int)

`MYSQLI_REPORT_INDEX` (int)

  Meldet, wenn kein Index oder ein ungültiger Index in einer Abfrage verwendet wurde.

`MYSQLI_REPORT_ERROR` (int)

  Meldet Fehler von mysqli-Funktionsaufrufen.

`MYSQLI_REPORT_STRICT` (int)

  Löst bei Fehlern eine `mysqli_sql_exception` aus, anstatt eine Warnung zu erzeugen.

`MYSQLI_REPORT_ALL` (int)

  Aktiviert alle Meldungs-Optionen.

`MYSQLI_REPORT_OFF` (int)

  Schaltet die Meldungen aus.

`MYSQLI_DEBUG_TRACE_ENABLED` (int)

  Wenn dies gleich 1 ist, dann steht die mysqli_debug()-Funktionalität zur Verfügung.

`MYSQLI_SERVER_PUBLIC_KEY` (int)

`MYSQLI_REFRESH_GRANT` (int)

  Aktualisiert die Berechtigungstabellen. Veraltet seit PHP 8.4.0.

`MYSQLI_REFRESH_LOG` (int)

  Leert die Logs so, wie die Ausführung der SQL-Anweisung `FLUSH LOGS`. Veraltet seit PHP 8.4.0.

`MYSQLI_REFRESH_TABLES` (int)

  Leert den Tabellen-Zwischenspeicher so, wie die Ausführung der SQL-Anweisung `FLUSH TABLES`. Veraltet seit PHP 8.4.0.

`MYSQLI_REFRESH_HOSTS` (int)

  Leert den Host-Zwischenspeicher so, wie die Ausführung der SQL-Anweisung `FLUSH HOSTS`. Veraltet seit PHP 8.4.0.

`MYSQLI_REFRESH_REPLICA` (int)

  Alias der `MYSQLI_REFRESH_SLAVE`-Konstante. Verfügbar seit PHP 8.1.0. Veraltet seit PHP 8.4.0.

`MYSQLI_REFRESH_STATUS` (int)

  Setzt die Statusvariablen so zurück, wie die Ausführung der SQL-Anweisung `FLUSH STATUS`. Veraltet seit PHP 8.4.0.

`MYSQLI_REFRESH_THREADS` (int)

  Leert den Thread-Zwischenspeicher. Veraltet seit PHP 8.4.0.

`MYSQLI_REFRESH_SLAVE` (int)

  Auf einem Slave-Replikationsserver: Setzt die Master-Server-Informationen zurück und führt einen Neustart des Slave durch. Dies ist wie die Ausführung der SQL-Anweisung `RESET SLAVE`. Veraltet seit PHP 8.4.0.

`MYSQLI_REFRESH_MASTER` (int)

  Auf einem Master-Replikationsserver: Entfernt die binären Protokolldateien, die im binären Protokollindex aufgeführt werden, und schneidet die Indexdatei ab. Dies ist wie die Ausführung der SQL-Anweisung `RESET MASTER`. Veraltet seit PHP 8.4.0.

`MYSQLI_REFRESH_BACKUP_LOG` (int)
  Schließt die Backup-Logdateien und öffnet sie wieder. Veraltet seit PHP 8.4.0.
`MYSQLI_TRANS_COR_AND_CHAIN` (int)

  Fügt "AND CHAIN" an mysqli_commit() oder mysqli_rollback() an.

`MYSQLI_TRANS_COR_AND_NO_CHAIN` (int)

  Fügt "AND NO CHAIN" an mysqli_commit() oder mysqli_rollback() an.

`MYSQLI_TRANS_COR_RELEASE` (int)

  Fügt "RELEASE" an mysqli_commit() oder mysqli_rollback() an.

`MYSQLI_TRANS_COR_NO_RELEASE` (int)

  Fügt "NO RELEASE" an mysqli_commit() oder mysqli_rollback() an.

`MYSQLI_TRANS_START_READ_ONLY` (int)

  Beginnt die Transaktion als "START TRANSACTION READ ONLY" mit mysqli_begin_transaction().

`MYSQLI_TRANS_START_READ_WRITE` (int)

  Beginnt die Transaktion als "START TRANSACTION READ WRITE" mit mysqli_begin_transaction().

`MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT` (int)

  Beginnt die Transaktion als "START TRANSACTION WITH CONSISTENT SNAPSHOT".

`MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` (int)

  Benötigt MySQL 5.6.5 und höher.

`MYSQLI_IS_MARIADB` (bool)

  Gibt an, ob die mysqli-Erweiterung gegen eine MariaDB-Client-Bibliothek erstellt wurde. Verfügbar seit PHP 8.1.2.

`MYSQLI_ASYNC` (int)
  Die Abfrage wird asynchron durchgeführt und es wird nicht sofort eine Ergebnismenge zurückgegeben. Nur mit `mysqlnd` verfügbar.
`MYSQLI_ON_UPDATE_NOW_FLAG` (int)
  Wenn ein Feld aktualisiert wird, erhält es die aktuelle Zeit.

# Hinweise

Hinweise zur Implementierung:

1. Die Unterstützung für `MYSQL_TYPE_GEOMETRY` zu der MySQLi-Erweiterung in PHP 5.3 hinzugefügt.

2. Beachten Sie, dass es verschiedene interne Implementierungen von `libmysqlclient` und `mysqlnd` zum Handling von Spalten des Typs `MYSQL_TYPE_GEOMETRY` gibt. Allgemein nimmt `mysqlnd` viel weniger Speicher ein. Zum Beispiel, wenn eine Spalte `POINT` in einem Ergebnis-Set vorkommt, reserviert `libmysqlclient` bis zu 4GB RAM, obwohl weniger als 50 bytes benötigt würden. Die Speicherzuweisung ist viel geringer, weniger als 50 bytes, wenn man `mysqlnd` nutzt.

# Die Funktionen der Erweiterung MySQLi im Überblick

Zusammenfassung der mysqli-Methoden
Die Klasse mysqli
OOP-Schnittstelle | Prozedurale Schnittstelle | Alias (nicht verwenden) | Beschreibung
--- | --- | --- | ---
Eigenschaften
$mysqli::affected_rows | mysqli_affected_rows() | N/A | Liefert die Anzahl der Zeilen, die von einer vorherigen MySQL-Operation betroffen sind
$mysqli::client_info | mysqli_get_client_info() | N/A | Liefert die Version des MySQL-Clients als Zeichenkette
$mysqli::client_version | mysqli_get_client_version() | N/A | Liefert die Version des MySQL-Clients als Integer
$mysqli::connect_errno | mysqli_connect_errno() | N/A | Liefert den Fehlercode des letzten Verbindungsversuchs
$mysqli::connect_error | mysqli_connect_error() | N/A | Liefert eine Zeichenkette, die den letzten Verbindungsfehler beschreibt
$mysqli::errno | mysqli_errno() | N/A | Liefert den Fehlercode des letzten Funktionsaufrufs
$mysqli::error | mysqli_error() | N/A | Liefert eine Zeichenkette, die den letzten Fehler beschreibt
$mysqli::field_count | mysqli_field_count() | N/A | Liefert die Anzahl der Spalten der letzten Abfrage
$mysqli::host_info | mysqli_get_host_info() | N/A | Liefert eine Zeichenkette, die den Typ der verwendeten Verbindung angibt
$mysqli::protocol_version | mysqli_get_proto_info() | N/A | Liefert die Version des verwendeten MySQL-Protokolls
$mysqli::server_info | mysqli_get_server_info() | N/A | Liefert die Version des MySQL-Servers
$mysqli::server_version | mysqli_get_server_version() | N/A | Liefert die Version des MySQL-Servers als Integer
$mysqli::info | mysqli_info() | N/A | Ruft Informationen über die zuletzt ausgeführte Abfrage ab
$mysqli::insert_id | mysqli_insert_id() | N/A | Liefert die automatisch erzeugte ID, die in der letzten Anweisung verwendet wurde
$mysqli::sqlstate | mysqli_sqlstate() | N/A | Liefert den SQLSTATE-Fehler der letzten MySQL-Operation
$mysqli::warning_count | mysqli_warning_count() | N/A | Liefert die Anzahl der Warnungen der letzten Abfrage für die angegebene Verbindung
Methoden
mysqli::autocommit() | mysqli_autocommit() | N/A | Aktiviert oder deaktiviert die automatische Bestätigung von Datenbankänderungen
mysqli::change_user() | mysqli_change_user() | N/A | Ändert den Benutzer der angegebenen Datenbankverbindung
mysqli::character_set_name() | mysqli_character_set_name() | N/A | Liefert den Standardzeichensatz für die Datenbankverbindung
mysqli::close() | mysqli_close() | N/A | Schließt eine zuvor geöffnete Datenbankverbindung
mysqli::commit() | mysqli_commit() | N/A | Bestätigt die aktuelle Transaktion
mysqli::__construct() | mysqli_connect() | N/A | Baut eine neue Verbindung zum MySQL-Server auf [Hinweis: statische (d.h. Klassen-) Methode]
mysqli::debug() | mysqli_debug() | N/A | Führt Debugging-Operationen durch
mysqli::dump_debug_info() | mysqli_dump_debug_info() | N/A | Schreibt die Debugging-Informationen in die Logdatei
mysqli::get_charset() | mysqli_get_charset() | N/A | Liefert ein Zeichensatz-Objekt
mysqli::get_connection_stats() | mysqli_get_connection_stats() | N/A | Liefert Verbindungsstatistiken des Clients. Nur in mysqlnd verfügbar.
mysqli::get_client_info() | mysqli_get_client_info() | N/A | Liefert die Version des MySQL-Clients als Zeichenkette
N/A | mysqli_get_client_stats() | N/A | Liefert prozessbezogene Client-Statistiken. Nur in mysqlnd verfügbar.
mysqli::get_server_info() | mysqli_get_server_info() | N/A | Liefert eine Zeichenkette, die die Version des MySQL-Servers angibt, mit dem die Erweiterung mysqli verbunden ist
mysqli::get_warnings() | mysqli_get_warnings() | N/A | NICHT DOKUMENTIERT
mysqli::init() | mysqli_init() | N/A | Initialisiert MySQLi und liefert ein Objekt zur Verwendung mit mysqli_real_connect
mysqli::kill() | mysqli_kill() | N/A | Weist den Server an, einen MySQL-Thread zu beenden
mysqli::more_results() | mysqli_more_results() | N/A | Prüft, ob es von einer Mehrfachabfrage noch weitere Abfrageergebnisse gibt
mysqli::multi_query() | mysqli_multi_query() | N/A | Führt eine oder mehrere Abfragen in einer Datenbank durch
mysqli::next_result() | mysqli_next_result() | N/A | Bereitet das nächste Ergebnis von multi_query vor
mysqli::options() | mysqli_options() | mysqli_set_opt() | Setzt Optionen
mysqli::ping() | mysqli_ping() | N/A | Pingt eine Serververbindung an oder versucht eine neue Verbindung aufzubauen, wenn die Verbindung unterbrochen wurde
mysqli::prepare() | mysqli_prepare() | N/A | Bereitet eine SQL-Anweisung zur Ausführung vor
mysqli::query() | mysqli_query() | N/A | Führt eine Abfrage in einer Datenbank durch
mysqli::real_connect() | mysqli_real_connect() | N/A | Baut eine Verbindung zu einem Mysql-Server auf
mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | Maskiert Sonderzeichen in einer Zeichenkette zur Verwendung in einer SQL-Anweisung, wobei der aktuelle Zeichensatz der Verbindung berücksichtigt wird
mysqli::real_query() | mysqli_real_query() | N/A | Führt eine SQL-Abfrage aus
mysqli::refresh() | mysqli_refresh() | N/A | Aktualisiert Tabellen oder leert Caches oder setzt die Informationen des Replikationsservers zurück
mysqli::rollback() | mysqli_rollback() | N/A | Nimmt die aktuelle Transaktion zurück
mysqli::select_db() | mysqli_select_db() | N/A | Wählt die standardmäßige Datenbank für Datenbankabfragen aus
mysqli::set_charset() | mysqli_set_charset() | N/A | Legt den Standard-Zeichensatz des Clients fest
mysqli::ssl_set() | mysqli_ssl_set() | N/A | Wird beim Aufbau sicherer Verbindungen mit SSL verwendet
mysqli::stat() | mysqli_stat() | N/A | Ermittelt den aktuellen Systemstatus
mysqli::stmt_init() | mysqli_stmt_init() | N/A | Initialisiert eine Anweisung und liefert ein Objekt für die Verwendung mit mysqli_stmt_prepare
mysqli::store_result() | mysqli_store_result() | N/A | Überträgt die Ergebnismenge der letzten Abfrage
mysqli::thread_id() | mysqli_thread_id() | N/A | Liefert die Thread-ID der aktuellen Verbindung
mysqli::thread_safe() | mysqli_thread_safe() | N/A | Gibt an, ob Thread-Sicherheit gegeben ist oder nicht
mysqli::use_result() | mysqli_use_result() | N/A | Initiiert den Abruf einer Ergebnismenge

Zusammenfassung der mysqli_stmt-Methoden
MySQL_STMT
OOP-Schnittstelle | Prozedurale Schnittstelle | Alias (nicht verwenden) | Beschreibung
--- | --- | --- | ---
Eigenschaften
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | N/A | Liefert die Gesamtzahl der Zeilen, die durch die zuletzt ausgeführte Anweisung geändert, gelöscht oder eingefügt wurden
$mysqli_stmt::errno | mysqli_stmt_errno() | N/A | Liefert den Fehlercode der zuletzt aufgerufenen Anweisungsfunktion
$mysqli_stmt::error | mysqli_stmt_error() | N/A | Liefert die Beschreibung des letzten Fehlers einer Anweisung als Zeichenkette
$mysqli_stmt::field_count | mysqli_stmt_field_count() | N/A | Liefert die Anzahl der Spalten in der angegebenen Anweisung
$mysqli_stmt::insert_id | mysqli_stmt_insert_id() | N/A | Ermittelt die ID, die beim letzten INSERT-Vorgang erzeugt wurde
$mysqli_stmt::num_rows | mysqli_stmt_num_rows() | N/A | Liefert die Anzahl der Zeilen in der Ergebnismenge einer Anweisung
$mysqli_stmt::param_count | mysqli_stmt_param_count() | N/A | Liefert die Anzahl der Parameter der angegebenen Anweisung
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | N/A | Liefert den SQLSTATE-Fehler der Ausführung der letzten Anweisung
Methods
mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | N/A | Wird verwendet, um den aktuellen Wert eines Anweisungsattributs abzurufen
mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | N/A | Wird verwendet, um das Verhalten einer vorbereiteten Anweisung zu ändern
mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | N/A | Bindet Variablen als Parameter an eine vorbereitete Anweisung
mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | N/A | Bindet Variablen für die Speicherung der Ergebnisse an eine vorbereitete Anweisung
mysqli_stmt::close() | mysqli_stmt_close() | N/A | Schließt eine vorbereitete Anweisung
mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | N/A | Springt zu einer beliebige Zeile in der Ergebnismenge einer Abfrage
mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | Führt eine vorbereitete Anweisung aus
mysqli_stmt::fetch() | mysqli_stmt_fetch() | N/A | Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab
mysqli_stmt::free_result() | mysqli_stmt_free_result() | N/A | Gibt den mit der angegebenen Anweisung verbundenen Ergebnisspeicher frei
mysqli_stmt::get_result() | mysqli_stmt_get_result() | N/A | Ruft die Ergebnismenge aus einer vorbereiteten Anweisung ab. Nur in mysqlnd verfügbar.
mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | N/A | NICHT DOKUMENTIERT
mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | Überprüft, ob es weitere Abfrageergebnisse aus einer Mehrfachabfrage gibt
mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | Liest das nächste Ergebnis aus einer Mehrfachanfrage aus
mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | N/A | Siehe auch die Eigenschaft $mysqli_stmt::num_rows
mysqli_stmt::prepare() | mysqli_stmt_prepare() | N/A | Bereitet eine SQL-Anweisung zur Ausführung vor
mysqli_stmt::reset() | mysqli_stmt_reset() | N/A | Setzt eine vorbereitete Anweisung zurück
mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | N/A | Liefert die Metadaten der Ergebnismenge aus einer vorbereiteten Anweisung
mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | N/A | Sendet Daten blockweise
mysqli_stmt::store_result() | mysqli_stmt_store_result() | N/A | Überträgt eine Ergebnismenge aus einer vorbereiteten Anweisung

Zusammenfassung der mysqli_result-Methoden
mysqli_result
OOP-Schnittstelle | Prozedurale Schnittstelle | Alias (nicht verwenden) | Beschreibung
--- | --- | --- | ---
Eigenschaften
$mysqli_result::current_field | mysqli_field_tell() | N/A | Ermittelt den aktuellen Spalten-Offset eines Ergebniszeigers
$mysqli_result::field_count | mysqli_num_fields() | N/A | Ermittelt die Anzahl der Spalten eines Ergebnisses
$mysqli_result::lengths | mysqli_fetch_lengths() | N/A | Liefert die Längen der Spalten der aktuellen Zeile einer Ergebnismenge
$mysqli_result::num_rows | mysqli_num_rows() | N/A | Ermittelt die Anzahl der Zeilen eines Ergebnisses
Methoden
mysqli_result::data_seek() | mysqli_data_seek() | N/A | Setzt den Ergebniszeiger auf eine beliebige Zeile im Ergebnis
mysqli_result::fetch_all() | mysqli_fetch_all() | N/A | Ruft alle Ergebniszeilen ab und liefert die Ergebnismenge als assoziatives und/oder numerisches Array. Nur in mysqlnd verfügbar.
mysqli_result::fetch_array() | mysqli_fetch_array() | N/A | Ruft eine Ergebniszeile als assoziatives und/oder numerisches Array ab
mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | N/A | Ruft eine Ergebniszeile als assoziatives Array ab
mysqli_result::fetch_column() | mysqli_fetch_column() | N/A | Ruft eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge ab
mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | N/A | Ruft die Metadaten für eine einzelne Spalte ab
mysqli_result::fetch_field() | mysqli_fetch_field() | N/A | Liefert die nächste Spalte einer Ergebnismenge
mysqli_result::fetch_fields() | mysqli_fetch_fields() | N/A | Liefert ein Array von Objekten, die die Spalten einer Ergebnismenge darstellen
mysqli_result::fetch_object() | mysqli_fetch_object() | N/A | Liefert die aktuelle Zeile einer Ergebnismenge als Objekt
mysqli_result::fetch_row() | mysqli_fetch_row() | N/A | Ruft eine Ergebniszeile als numerisches Array ab
mysqli_result::field_seek() | mysqli_field_seek() | N/A | Setzt den Ergebniszeiger auf die angegebene Spalte
mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | N/A | Gibt den mit einem Ergebnis verbundenen Speicher frei

Summary of mysqli_driver-Methoden
MySQL_Driver
OOP-Schnittstelle | Prozedurale Schnittstelle | Alias (nicht verwenden) | Beschreibung
--- | --- | --- | ---
Eigenschaften
$mysqli_driver::mysqli_report | mysqli_report() | N/A | Legt den Modus für mysqli-Fehlermeldungen fest
Methoden
mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | N/A | NICHT DOKUMENTIERT
mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | N/A | NICHT DOKUMENTIERT

> Hinweis:

> Alias-Funktionen stehen nur aus Gründen der Abwärtskompatibilität zur Verfügung. Sie sollten nicht in neuen Projekten verwendet werden.

# Die Klasse mysqli

(PHP 5, PHP 7, PHP 8)

## Einführung

Repräsentiert eine Verbindung zwischen PHP und einer MySQL-Datenbank.

## Klassenbeschreibung

class mysqli {
/* Eigenschaften */
public readonly int|string $affected_rows;
public readonly string $client_info;
public readonly int $client_version;
public readonly int $connect_errno;
public readonly ?string $connect_error;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly int $field_count;
public readonly string $host_info;
public readonly ?string $info;
public readonly int|string $insert_id;
public readonly string $server_info;
public readonly int $server_version;
public readonly string $sqlstate;
public readonly int $protocol_version;
public readonly int $thread_id;
public readonly int $warning_count;
/* Methoden */
public function __construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function autocommit(bool `$enable`): bool
public function begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool
public function change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool
public function character_set_name(): string
public function close(): true
public function commit(int `$flags` = 0, ?string `$name` = `null`): bool
public function connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool
public function debug(string `$options`): true
public function dump_debug_info(): bool
public function execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool
public function get_charset(): ?object
#[\Deprecated]
public function get_client_info(): string
public function get_connection_stats(): array
public function get_server_info(): string
public function get_warnings(): mysqli_warning|false
#[\Deprecated]
public function init(): ?bool
#[\Deprecated]
public function kill(int `$process_id`): bool
public function more_results(): bool
public function multi_query(string `$query`): bool
public function next_result(): bool
public function options(int `$option`, string|int `$value`): bool
#[\Deprecated]
public function ping(): bool
public static function poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false
public function prepare(string `$query`): mysqli_stmt|false
public function query(string `$query`, int `$result_mode` = MYSQLI_STORE_RESULT): mysqli_result|bool
public function real_connect(
?string `$hostname` = null,
?string `$username` = null,
#[\SensitiveParameter]?string `$password` = null,
?string `$database` = null,
?int `$port` = null,
?string `$socket` = null,
int `$flags` = 0
): bool
public function real_escape_string(string `$string`): string
public function real_query(string `$query`): bool
public function reap_async_query(): mysqli_result|bool
#[\Deprecated]
public function refresh(int `$flags`): bool
public function release_savepoint(string `$name`): bool
public function rollback(int `$flags` = 0, ?string `$name` = null): bool
public function savepoint(string `$name`): bool
public function select_db(string `$database`): bool
public function set_charset(string `$charset`): bool
public function ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true
public function stat(): string|false
public function stmt_init(): mysqli_stmt|false
public function store_result(int `$mode` = 0): mysqli_result|false
public function thread_safe(): bool
public function use_result(): mysqli_result|false
}

# mysqli::$affected_rows

# mysqli_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli::$affected_rows -- mysqli_affected_rows — Liefert die Anzahl der Datensätze, die vom letzten MySQL-Vorgang betroffen waren

### Beschreibung

Objektorientierter Stil

int|string $mysqli->affected_rows;

Prozeduraler Stil

function mysqli_affected_rows(mysqli `$mysql`): int|string

Gibt die Anzahl der von der letzten `INSERT`-, `UPDATE`-,`REPLACE`- oder `DELETE`-Abfrage betroffenen Datensätze zurück. Entspricht bei `SELECT`-Anweisungen mysqli_num_rows().

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Eine Ganzzahl größer als Null zeigt die Anzahl der betroffenen oder abgerufenen Datensätze an. Null gibt an, dass bei einer `UPDATE`-Anweisung keine Datensätze aktualisiert wurden, keine Datensätze mit der `WHERE`-Klausel übereinstimmen oder dass die Datenbankabfrage noch nicht aufgeführt wurde. `-1` gibt an, dass die Datenbankabfrage einen Fehler zurückgegeben hat oder dass mysqli_affected_rows() für eine ungepufferte `SELECT`-Abfrage aufgerufen wurde.

> Hinweis:

> Ist die Anzahl der betroffenen Datensätze größer als der maximale Integer-Wert (`PHP_INT_MAX`), wird die Anzahl der betroffenen Datensätze als Zeichenkette zurückgegeben.

### Beispiele

Beispiel #1 $mysqli->affected_rows-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Datensätze einfügen */
    $mysqli->query("CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Betroffene Datensätze (INSERT): %d\n", $mysqli->affected_rows);

    $mysqli->query("ALTER TABLE Language ADD Status int default 0");

    /* Datensätze ändern */
    $mysqli->query("UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Betroffene Datensätze (UPDATE): %d\n", $mysqli->affected_rows);

    /* Datensätze löschen */
    $mysqli->query("DELETE FROM Language WHERE Percentage < 50");
    printf("Betroffene Datensätze (DELETE): %d\n", $mysqli->affected_rows);

    /* Alle Datensätze auswählen */
    $result = $mysqli->query("SELECT CountryCode FROM Language");
    printf("Betroffene Datensätze (SELECT): %d\n", $mysqli->affected_rows);

    /* Tabelle Language löschen */
    $mysqli->query("DROP TABLE Language");

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Datensätze einfügen */
    mysqli_query($link, "CREATE TABLE Language SELECT * from CountryLanguage");
    printf("Betroffene Datensätze (INSERT): %d\n", mysqli_affected_rows($link));

    mysqli_query($link, "ALTER TABLE Language ADD Status int default 0");

    /* Datensätze ändern */
    mysqli_query($link, "UPDATE Language SET Status=1 WHERE Percentage > 50");
    printf("Betroffene Datensätze (UPDATE): %d\n", mysqli_affected_rows($link));

    /* Datensätze löschen */
    mysqli_query($link, "DELETE FROM Language WHERE Percentage < 50");
    printf("Betroffene Datensätze (DELETE): %d\n", mysqli_affected_rows($link));

    /* Alle Datensätze auswählen */
    $result = mysqli_query($link, "SELECT CountryCode FROM Language");
    printf("Betroffene Datensätze (SELECT): %d\n", mysqli_affected_rows($link));

    /* Tabelle Language löschen */
    mysqli_query($link, "DROP TABLE Language");

Die obigen Bespiele erzeugen folgende Ausgabe:

    Betroffene Datensätze (INSERT): 984
    Betroffene Datensätze (UPDATE): 168
    Betroffene Datensätze (DELETE): 815
    Betroffene Datensätze (SELECT): 169

### Siehe auch

- mysqli_num_rows() - Ermittelt die Anzahl der Zeilen einer Ergebnismenge
- mysqli_info() - Ruft Informationen über die zuletzt ausgeführte Abfrage ab

# mysqli::autocommit

# mysqli_autocommit

(PHP 5, PHP 7, PHP 8)

mysqli::autocommit -- mysqli_autocommit — Aktiviert oder deaktiviert das automatische Bestätigen von Datenbankänderungen

### Beschreibung

Objektorientierter Stil

public function mysqli::autocommit(bool `$enable`): bool

Prozeduraler Stil

function mysqli_autocommit(mysqli `$mysql`, bool `$enable`): bool

Aktiviert oder deaktiviert den Autocommit-Modus für Abfragen an die Datenbankverbindung.

Um den aktuellen Status von Autocommit festzustellen, ist die SQL-Anweisung `SELECT @@autocommit` zu verwenden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`enable`

  Legt fest, ob Autocommit aktiviert werden soll oder nicht.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 mysqli::autocommit()-Beispiel

Objektorientierter Stil

    <?php

    /* mysqli anweisen, eine Ausnahme auszulösen, wenn ein Fehler auftritt */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Die Tabellen-Engine muss Transaktionen unterstützen */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* autocommit ausschalten */
    $mysqli->autocommit(false);

    $result = $mysqli->query("SELECT @@autocommit");
    $row = $result->fetch_row();
    printf("Autocommit ist %s\n", $row[0]);

    try {
        /* Insert-Anweisung vorbereiten */
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);

        /* Ein paar Werte einfügen */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        $stmt->execute();
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        $stmt->execute();

        /* Bestätigen der Daten in der Datenbank. Dies setzt nicht autocommit=true */
        $mysqli->commit();
        print "2 Datensätze in der Datenbank bestätigt\n";

        $result = $mysqli->query("SELECT @@autocommit");
        $row = $result->fetch_row();
        printf("Autocommit ist %s\n", $row[0]);

        /* Versuchen, weitere Werte einzufügen */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        $stmt->execute();
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        $stmt->execute();

        /* Das Setzen von autocommit=true löst eine Bestätigung aus */
        $mysqli->autocommit(true);

        print "2 weitere Datensätze in der Datenbank bestätigt\n";
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Prozeduraler Stil

    <?php

    /* mysqli anweisen, eine Ausnahme auszulösen, wenn ein Fehler auftritt */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Die Tabellen-Engine muss Transaktionen unterstützen */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* autocommit ausschalten */
    mysqli_autocommit($mysqli, false);

    $result = mysqli_query($mysqli, "SELECT @@autocommit");
    $row = mysqli_fetch_row($result);
    printf("Autocommit ist %s\n", $row[0]);

    try {
        /* Insert-Anweisung vorbereiten */
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);

        /* Ein paar Werte einfügen */
        $language_code = 'DE';
        $native_speakers = 50_123_456;
        mysqli_stmt_execute($stmt);
        $language_code = 'FR';
        $native_speakers = 40_546_321;
        mysqli_stmt_execute($stmt);

        /* Bestätigen der Daten in der Datenbank. Dies setzt nicht autocommit=true */
        mysqli_commit($mysqli);
        print "2 Datensätze in der Datenbank bestätigt\n";

        $result = mysqli_query($mysqli, "SELECT @@autocommit");
        $row = mysqli_fetch_row($result);
        printf("Autocommit ist %s\n", $row[0]);

        /* Versuchen, weitere Werte einzufügen */
        $language_code = 'PL';
        $native_speakers = 30_555_444;
        mysqli_stmt_execute($stmt);
        $language_code = 'DK';
        $native_speakers = 5_222_444;
        mysqli_stmt_execute($stmt);

        /* Das Setzen von autocommit=true löst eine Bestätigung aus */
        mysqli_autocommit($mysqli, true);

        print "2 weitere Datensätze in der Datenbank bestätigt\n";
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

Die obigen Bespiele erzeugen folgende Ausgabe:

    Autocommit ist 0
    2 Datensätze in der Datenbank bestätigt
    Autocommit ist 0
    2 weitere Datensätze in der Datenbank bestätigt
    Autocommit ist 0
    2 Datensätze in der Datenbank bestätigt
    Autocommit ist 0
    2 weitere Datensätze in der Datenbank bestätigt

### Anmerkungen

> Hinweis:

> Die Funktion kann nicht mit Tabellentypen verwendet werden, die keine Transaktionen unterstützen (wie MyISAM oder ISAM).

### Siehe auch

- mysqli_begin_transaction() - Startet eine Transaktion
- mysqli_commit() - Bestätigt die aktuelle Transaktion
- mysqli_rollback() - Macht die aktuelle Transaktion rückgängig

# mysqli::begin_transaction

# mysqli_begin_transaction

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::begin_transaction -- mysqli_begin_transaction — Startet eine Transaktion

### Beschreibung

Objektorientierter Stil

public function mysqli::begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool

Prozeduraler Stil:

function mysqli_begin_transaction(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Beginnt eine Transaktion; benötigt die InnoDB-Engine (sie ist standardmäßig aktiviert). Für weitere Details über die Funktionsweise von MySQL-Transaktionen siehe » http://dev.mysql.com/doc/mysql/en/commit.html.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`flags`

  Gültige Flags sind:

  - `MYSQLI_TRANS_START_READ_ONLY`: Startet die Transaktion als "START TRANSACTION READ ONLY" (nur lesend). Benötigt MySQL 5.6 oder höher.

  - `MYSQLI_TRANS_START_READ_WRITE`: Startet die Transaktion als "START TRANSACTION READ WRITE" (lesend und schreibend). Benötigt MySQL 5.6 oder höher.

  - `MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT`: Startet die Transaktion als "START TRANSACTION WITH CONSISTENT SNAPSHOT".

`name`

  Name des Sicherungspunkts für die Transaktion

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `name` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 mysqli::begin_transaction()-Beispiel

Objektorientierter Stil

    <?php

    /* mysqli anweisen, eine Ausnahme auszulösen, wenn ein Fehler auftritt */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Die Tabellen-Engine muss Transaktionen unterstützen */
    $mysqli->query("CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Transaktion starten */
    $mysqli->begin_transaction();

    try {
        /* Ein paar Werte einfügen */
        $mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Versuchen, ungültige Werte einzufügen */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
        $stmt->bind_param('ss', $language_code, $native_speakers);
        $stmt->execute();

        /* Wenn der Code bis hierher fehlerfrei ist, die Daten in der Datenbank bestätigen */
        $mysqli->commit();
    } catch (mysqli_sql_exception $exception) {
        $mysqli->rollback();

        throw $exception;
    }

Prozeduraler Stil

    <?php

    /* mysqli anweisen, eine Ausnahme auszulösen, wenn ein Fehler auftritt */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Die Tabellen-Engine muss Transaktionen unterstützen */
    mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
        Code text NOT NULL,
        Speakers int(11) NOT NULL
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");

    /* Transaktion starten */
    mysqli_begin_transaction($mysqli);

    try {
        /* Ein paar Werte einfügen */
        mysqli_query($mysqli, "INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");

        /* Versuchen, ungültige Werte einzufügen */
        $language_code = 'FR';
        $native_speakers = 'Unknown';
        $stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
        mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);
        mysqli_stmt_execute($stmt);

        /* Wenn der Code bis hierher fehlerfrei ist, die Daten in der Datenbank bestätigen */
        mysqli_commit($mysqli);
    } catch (mysqli_sql_exception $exception) {
        mysqli_rollback($mysqli);

        throw $exception;
    }

### Anmerkungen

> Hinweis:

> Diese Funktion funktioniert nicht mit Tabellentypen, die keine Transaktionen unterstützen (wie MyISAM oder ISAM).

### Siehe auch

- mysqli_autocommit() - Aktiviert oder deaktiviert das automatische Bestätigen von Datenbankänderungen
- mysqli_commit() - Bestätigt die aktuelle Transaktion
- mysqli_rollback() - Macht die aktuelle Transaktion rückgängig

# mysqli::change_user

# mysqli_change_user

(PHP 5, PHP 7, PHP 8)

mysqli::change_user -- mysqli_change_user — Ändert den Benutzer der Datenbankverbindung

### Beschreibung

Objektorientierter Stil

public function mysqli::change_user(string `$username`, #[\SensitiveParameter]string `$password`, ?string `$database`): bool

Prozeduraler Stil

function mysqli_change_user(
mysqli `$mysql`,
string `$username`,
#[\SensitiveParameter]string `$password`,
?string `$database`
): bool

Versucht, mit den angegebenen Anmeldeinformationen eine Verbindung zur angegebenen Datenbank herzustellen.

Im Gegensatz zu mysqli::connect() trennt diese Methode die aktuelle Verbindung nicht, wenn die neue Verbindung nicht geöffnet werden kann.

Für einen erfolgreichen Benutzerwechsel müssen gültige Werte für die Parameter `username` und `password` angegeben werden und der Benutzer muss über ausreichende Berechtigungen für den Zugriff auf die gewünschte Datenbank verfügen. Wenn die Autorisierung aus irgendeinem Grund fehlschlägt, bleibt die aktuelle Benutzerauthentifizierung unverändert.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`username`

  Der MySQL-Benutzername

`password`

  Das MySQL-Passwort

`database`

  Der Name der Datenbank. Wenn `null` oder eine leere Zeichenkette übergeben wird, wird die Verbindung zum Server ohne Standard-Datenbank geöffnet.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 Zurücksetzen der Verbindungs-Session

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("SET @a:=1");

    $mysqli->change_user("my_user", "my_password", "world");

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Standard-Datenbank: %s\n", $row[0]);

    $result = $mysqli->query("SELECT @a");
    $row = $result->fetch_row();
    if ($row[0] === null) {
        printf("Der Wert der Variable a ist NULL\n");
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "SET @a:=1");

    mysqli_change_user($link, "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("Standard-Datenbank: %s\n", $row[0]);

    $result = mysqli_query($link, "SELECT @a");
    $row = mysqli_fetch_row($result);
    if ($row[0] === null) {
        printf("Der Wert der Variable a ist NULL\n");
    }

Die obigen Bespiele erzeugen folgende Ausgabe:

    Standard-Datenbank: world
    Der Wert der Variable a ist NULL

Beispiel #2 Wenn `database` `null` ist, wird die Verbindung ohne Auswahl einer Standard-Datenbank geöffnet

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->change_user("my_user", "my_password", null);

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Standard-Datenbank: %s\n", $row[0]);

Die obigen Bespiele erzeugen folgende Ausgabe:

    Standard-Datenbank:

### Anmerkungen

> Hinweis:

> Wenn dieser Befehl verwendet wird, verhält sich die aktuelle Datenbankverbindung immer so, als ob es sich um eine völlig neue Datenbankverbindung handelt, unabhängig davon, ob der Vorgang erfolgreich abgeschlossen wurde. Mit diesem Zurücksetzen werden auch alle aktiven Transaktionen zurückgesetzt, alle temporären Tabellen geschlossen und alle gesperrten Tabellen entsperrt.

### Siehe auch

- mysqli_connect() - Alias von mysqli::__construct
- mysqli_select_db() - Legt die standardmäßige Datenbank für Datenbankabfragen fest

# mysqli::character_set_name

# mysqli_character_set_name

(PHP 5, PHP 7, PHP 8)

mysqli::character_set_name -- mysqli_character_set_name — Liefert den aktuellen Zeichensatz der Datenbankverbindung

### Beschreibung

Objektorientierter Stil

public function mysqli::character_set_name(): string

Prozeduraler Stil

function mysqli_character_set_name(mysqli `$mysql`): string

Gibt den aktuellen Zeichensatz der Datenbankverbindung zurück.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt den aktuellen Zeichensatz der Datenbankverbindung zurück.

### Beispiele

Beispiel #1 mysqli::character_set_name()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Standardzeichensatz festlegen */
    $mysqli->set_charset('utf8mb4');

    /* Aktuellen Zeichensatz ausgeben */
    $charset = $mysqli->character_set_name();
    printf("Der aktuelle Zeichensatz ist %s\n", $charset);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Standardzeichensatz festlegen */
    mysqli_set_charset($mysqli, 'utf8mb4');

    /* Aktuellen Zeichensatz ausgeben */
    $charset = mysqli_character_set_name($mysqli);
    printf("Der aktuelle Zeichensatz ist %s\n", $charset);

Die obigen Bespiele erzeugen folgende Ausgabe:

    Der aktuelle Zeichensatz ist utf8mb4

### Siehe auch

- mysqli_set_charset() - Legt den Standard-Zeichensatz des Clients fest
- mysqli_real_escape_string() - Maskiert Sonderzeichen in einer Zeichenkette zur Verwendung in einer SQL-Anweisung, wobei der aktuelle Zeichensatz der Verbindung berücksichtigt wird

# mysqli::close

# mysqli_close

(PHP 5, PHP 7, PHP 8)

mysqli::close -- mysqli_close — Schließt die zuvor geöffnete Datenbankverbindung

### Beschreibung

Objektorientierter Stil

public function mysqli::close(): true

Prozeduraler Stil

function mysqli_close(mysqli `$mysql`): true

Schließt die zuvor geöffnete Datenbankverbindung.

Offene nicht-persistente MySQL-Verbindungen und Ergebnismengen werden automatisch geschlossen, wenn ihre Objekte entfernt werden. Das explizite Schließen offener Verbindungen und das Freigeben von Ergebnismengen ist optional. Es ist jedoch empfehlenswert, die Verbindung zu schließen, sobald das Skript alle seine Datenbankoperationen beendet hat, wenn nach dem Abrufen der Ergebnisse noch umfangreiche Verarbeitungsschritte erforderlich sind.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion gibt nun immer `true` zurück; vorher gab sie bei einem Fehler `false` zurück.

### Beispiele

Beispiel #1 mysqli::close()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    /* Schließen der Verbindung, sobald sie nicht mehr benötigt wird */
    $mysqli->close();

    foreach ($result as $row) {
        /* Verarbeitung der aus der Datenbank abgerufenen Daten */
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    /* Schließen der Verbindung, sobald sie nicht mehr benötigt wird */
    mysqli_close($mysqli);

    foreach ($result as $row) {
        /* Verarbeitung der aus der Datenbank abgerufenen Daten */
    }

### Anmerkungen

> Hinweis:

> mysqli_close() schließt keine persistenten Verbindungen. Weitere Details sind der Handbuchseite zu persistenten Datenbankverbindungen zu entnehmen.

### Siehe auch

- mysqli::__construct() - Baut eine neue Verbindung zum MySQL-Server auf
- mysqli_init() - Initialisiert MySQLi und liefert ein Objekt zur Verwendung mit mysqli_real_connect()
- mysqli_real_connect() - Baut eine Verbindung zu einem MySQL-Server auf
- mysqli_free_result() - Gibt den mit einem Ergebnis verbundenen Speicher frei

# mysqli::commit

# mysqli_commit

(PHP 5, PHP 7, PHP 8)

mysqli::commit -- mysqli_commit — Bestätigt die aktuelle Transaktion

### Beschreibung

Objektorientierter Stil

public function mysqli::commit(int `$flags` = 0, ?string `$name` = `null`): bool

Prozeduraler Stil

function mysqli_commit(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Bestätigt die aktuelle Transaktion für die Datenbankverbindung.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`flags`

  Eine Bitmaske von `MYSQLI_TRANS_COR_*`-Konstanten

`name`

  Falls angegeben, wird `COMMIT/*name*/` ausgeführt

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `name` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Siehe das mysqli::begin_transaction()-Beispiel.

### Anmerkungen

> Hinweis:

> Diese Funktion funktioniert nicht mit Tabellentypen, die keine Transaktionen unterstützen (wie MyISAM oder ISAM).

### Siehe auch

- mysqli_autocommit() - Aktiviert oder deaktiviert das automatische Bestätigen von Datenbankänderungen
- mysqli_begin_transaction() - Startet eine Transaktion
- mysqli_rollback() - Macht die aktuelle Transaktion rückgängig
- mysqli_savepoint() - Sezt einen benannten Sicherungspunkt für eine Transaktion

# mysqli::$connect_errno

# mysqli_connect_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_errno -- mysqli_connect_errno — Liefert den Fehlercode des letzten Verbindungsversuchs

### Beschreibung

Objektorientierter Stil

int $mysqli->connect_errno;

Prozeduraler Stil

function mysqli_connect_errno(): int

Gibt den Fehlercode des letzten Verbindungsversuchs zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Der Fehlercode für den letzten Verbindungsversuch, falls dieser fehlgeschlagen ist. Null bedeutet, dass kein Fehler aufgetreten ist.

Gibt den letzten Fehlercode der Verbindung zurück, unabhängig davon, auf welcher Instanz er aufgerufen wurde.

### Beispiele

Beispiel #1 $mysqli->connect_errno-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ wird verwendet, um Warnungen zu unterdrücken */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
    if ($mysqli->connect_errno) {
        /* Hier kann die bevorzugte Methode zur Fehlerprotokollierung verwendet werden */
        error_log('Fehler beim Aufbau der Verbindung: ' . $mysqli->connect_errno);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ wird verwendet, um Warnungen zu unterdrücken */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
    if (!$link) {
        /* Hier kann die bevorzugte Methode zur Fehlerprotokollierung verwendet werden */
        error_log('Fehler beim Aufbau der Verbindung: ' . mysqli_connect_errno());
    }

### Siehe auch

- mysqli_connect() - Alias von mysqli::__construct
- mysqli_connect_error() - Liefert eine Beschreibung des letzten Verbindungsfehlers
- mysqli_errno() - Liefert den Fehlercode des letzten Funktionsaufrufs
- mysqli_error() - Liefert eine Zeichenkette, die den letzten Fehler beschreibt
- mysqli_sqlstate() - Liefert den SQLSTATE-Fehler der letzten MySQL-Operation

# mysqli::$connect_error

# mysqli_connect_error

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_error -- mysqli_connect_error — Liefert eine Beschreibung des letzten Verbindungsfehlers

### Beschreibung

Objektorientierter Stil

?string $mysqli->connect_error;

Prozeduraler Stil

function mysqli_connect_error(): ?string

Gibt die Fehlermeldung des letzten Verbindungsversuchs zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Die Zeichenkette, die den Fehler beschreibt. Wenn kein Fehler aufgetreten ist, wird `null` zurückgegeben.

Gibt den letzten Fehler der Verbindung zurück, unabhängig davon, auf welcher Instanz er aufgerufen wurde.

### Beispiele

Beispiel #1 $mysqli->connect_error-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ wird verwendet, um Warnungen zu unterdrücken */
    $mysqli = @new mysqli('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
    if ($mysqli->connect_error) {
        /* Hier kann die bevorzugte Methode zur Fehlerprotokollierung verwendet werden */
        error_log('Fehler beim Aufbau der Verbindung: ' . $mysqli->connect_error);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_OFF);
    /* @ wird verwendet, um Warnungen zu unterdrücken */
    $link = @mysqli_connect('localhost', 'fake_user', 'wrong_password', 'does_not_exist');
    if (!$link) {
        /* Hier kann die bevorzugte Methode zur Fehlerprotokollierung verwendet werden */
        error_log('Fehler beim Aufbau der Verbindung: ' . mysqli_connect_error());
    }

### Siehe auch

- mysqli_connect() - Alias von mysqli::__construct
- mysqli_connect_errno() - Liefert den Fehlercode des letzten Verbindungsversuchs
- mysqli_errno() - Liefert den Fehlercode des letzten Funktionsaufrufs
- mysqli_error() - Liefert eine Zeichenkette, die den letzten Fehler beschreibt
- mysqli_sqlstate() - Liefert den SQLSTATE-Fehler der letzten MySQL-Operation

# mysqli::__construct

# mysqli::connect

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli::__construct -- mysqli::connect -- mysqli_connect — Baut eine neue Verbindung zum MySQL-Server auf

### Beschreibung

Objektorientierter Stil

public function mysqli::__construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function mysqli::connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool

Prozeduraler Stil

function mysqli_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): mysqli|false

Baut eine Verbindung zum MySQL-Server auf.

### Parameter-Liste

`hostname`

  Kann entweder ein Hostname oder eine IP-Adresse sein. Wenn diesem Parameter der Wert `null` übergeben wird, wird der Wert von mysqli.default_host ü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, z. B. `localhost:3308`.

  Wenn dem Host ein `p:` vorangestellt wird, wird eine persistente (dauerhafte) Verbindung geöffnet. Bei Verbindungen, die aus dem Verbindungs-Pool geöffnet werden, wird automatisch die Funktion mysqli_change_user() aufgerufen.

`username`

  Der MySQL-Benutzername oder `null`, um den Benutzernamen aus der INI-Option mysqli.default_user zu übernehmen.

`password`

  Das MySQL-Passwort oder `null`, um den Benutzernamen aus der INI-Option mysqli.default_pw zu übernehmen.

`database`

  Die Datenbank, die standardmäßig bei Abfragen verwendet werden soll, oder `null`.

`port`

  Die Portnummer, über die versucht wird, eine Verbindung mit dem MySQL-Server herzustellen, oder `null`, um den Port aus der INI-Option mysqli.default_port zu übernehmen.

`socket`

  Der Socket oder die benannte Pipe an, der/die verwendet werden soll, oder `null`, um den Socket aus der INI-Option mysqli.default_socket zu übernehmen.

  > Hinweis:

  > Mit dem Parameter `socket` 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 `hostname` bestimmt.

### Rückgabewerte

mysqli::__construct() gibt immer ein Objekt zurück, das die Verbindung zu einem MySQL-Server repräsentiert, unabhängig davon, ob sie erfolgreich ist oder nicht.

mysqli_connect() gibt ein Objekt zurück, das die Verbindung zu einem MySQL-Server repräsentiert. Bei einem Fehler wird `false` zurückgegeben.

mysqli::connect() gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. Vor PHP 8.1.0 wird bei Erfolg `null` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | mysqli::connect() gibt bei Erfolg nun `true` anstelle von `null` zurück.
7.4.0 | Alle Parameter sind nun nullable (akzeptieren den `null`-Wert).

### Beispiele

Beispiel #1 mysqli::__construct()-Beispiel

Objektorientierter Stil

    <?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);

Prozeduraler Stil

    <?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));

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Erfolg... localhost via TCP/IP

Beispiel #2 Erweitern der Klasse mysqli

    <?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');

Beispiel #3 Manuelle Fehlerbehandlung

Falls die Meldung von Fehlern deaktiviert ist, ist der Entwickler dafür verantwortlich, Fehler zu überprüfen und zu behandeln

Objektorientierter Stil

    <?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);
    }

Prozeduraler Stil

    <?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));
    }

### Anmerkungen

> Hinweis:

> MySQLnd nimmt immer den Standardzeichensatz des Servers an. Dieser Zeichensatz wird während des Aufbaus der Verbindung bzw. der Authentifizierung übermittelt und danach von MySQLnd verwendet.

> Libmysqlclient verwendet als Standardzeichensatz den, der in der Datei my.cnf angegeben oder durch einen Aufruf von mysqli_options() vor dem Aufruf von mysqli_real_connect() aber nach mysqli_init() gesetzt wurde.

> Hinweis:

> Objektorientierter Stil: 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 mysqli_connect_error() oder die Eigenschaft mysqli->connect_error verwendet werden.

> Hinweis:

> Wenn es nötig ist, Optionen zu setzen, z. B. das Zeitlimit für die Verbindung, muss stattdessen die Funktion mysqli_real_connect() verwendet werden.

> Hinweis:

> Der Aufruf des Konstruktors ohne Parameter entspricht dem Aufruf von mysqli_init().

> Hinweis:

> Der Fehler "Can't create TCP/IP socket (10106)" bedeutet in der Regel, dass in der Konfigurationsanweisung variables_order das Zeichen `E` fehlt. Wenn unter Windows die Systemumgebung nicht kopiert wird, ist die Umgebungsvariable `SYSTEMROOT` nicht verfügbar und PHP hat dann ein Problem beim Laden von Winsock.

### Siehe auch

- mysqli_real_connect() - Baut eine Verbindung zu einem MySQL-Server auf
- mysqli_options() - Setzt Optionen
- mysqli_connect_errno() - Liefert den Fehlercode des letzten Verbindungsversuchs
- mysqli_connect_error() - Liefert eine Beschreibung des letzten Verbindungsfehlers
- mysqli_close() - Schließt die zuvor geöffnete Datenbankverbindung

# mysqli::debug

# mysqli_debug

(PHP 5, PHP 7, PHP 8)

mysqli::debug -- mysqli_debug — Führt Debugging-Operationen durch

### Beschreibung

Objektorientierter Stil

public function mysqli::debug(string `$options`): true

Prozeduraler Stil

function mysqli_debug(string `$options`): true

Führt Debugging-Operationen mit Hilfe der Debugging-Bibliothek von Fred Fish durch.

### Parameter-Liste

`options`

  Eine Zeichenkette, die die auszuführende Debugging-Operation angibt

  Die Zeichenkette für die Fehlersuche ist eine Folge von Feldern, die wie nachstehend beschrieben durch Doppelpunkte getrennt sind: ``

      <feld_1>:<feld_2>:<feld_N>

  . Jedes Feld besteht aus einem obligatorischen Flag-Zeichen, gefolgt von einem optionalen `,` und einer durch Komma getrennten Liste von Modifikatoren: `flag[,modifier,modifier,...,modifier]`

  Zulässige Flag-Zeichen
  `options`-Zeichen | Beschreibung
  --- | ---
  O | `MYSQLND_DEBUG_FLUSH`
  A/a | `MYSQLND_DEBUG_APPEND`
  F | `MYSQLND_DEBUG_DUMP_FILE`
  i | `MYSQLND_DEBUG_DUMP_PID`
  L | `MYSQLND_DEBUG_DUMP_LINE`
  m | `MYSQLND_DEBUG_TRACE_MEMORY_CALLS`
  n | `MYSQLND_DEBUG_DUMP_LEVEL`
  o | Ausgabe in Datei
  T | `MYSQLND_DEBUG_DUMP_TIME`
  t | `MYSQLND_DEBUG_DUMP_TRACE`
  x | `MYSQLND_DEBUG_PROFILE_CALLS`

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion gibt nun immer `true` zurück; vorher gab sie bei einem Fehler `false` zurück.

### Beispiele

Beispiel #1 Erzeugen einer Trace-Datei

    <?php

    /* Erstellen einer Trace-Datei in '/tmp/client.trace' auf dem lokalen (Client-)Rechner: */
    mysqli_debug("d:t:o,/tmp/client.trace");

    ?>

### Anmerkungen

> Hinweis:

> Um die Funktion mysqli_debug() nutzen zu können, muss die MySQL-Client-Bibliothek mit Debugging-Unterstützung kompiliert werden.

### Siehe auch

- mysqli_dump_debug_info() - Schreibt Debugging-Informationen in die Logdatei
- mysqli_report() - Alias von mysqli_driver->report_mode

# mysqli::dump_debug_info

# mysqli_dump_debug_info

(PHP 5, PHP 7, PHP 8)

mysqli::dump_debug_info -- mysqli_dump_debug_info — Schreibt Debugging-Informationen in die Logdatei

### Beschreibung

Objektorientierter Stil

public function mysqli::dump_debug_info(): bool

Prozeduraler Stil

function mysqli_dump_debug_info(mysqli `$mysql`): bool

Diese Funktion ist dafür vorgesehen, von einem Benutzer mit SUPER-Berechtigung ausgeführt zu werden, und dient dazu, Debugging-Informationen über die Verbindung in die Logdatei des MySQL-Servers zu schreiben.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- mysqli_debug() - Führt Debugging-Operationen durch

# mysqli::$errno

# mysqli_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$errno -- mysqli_errno — Liefert den Fehlercode des letzten Funktionsaufrufs

### Beschreibung

Objektorientierter Stil

int $mysqli->errno;

Prozeduraler Stil

function mysqli_errno(mysqli `$mysql`): int

Gibt den letzten Fehlercode des letzten MySQLi-Funktionsaufrufs zurück, der entweder erfolgreich war oder fehlschlug.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt den Fehlercode des letzten Aufrufs zurück, wenn er fehlgeschlagen ist. Null bedeutet, dass kein Fehler aufgetreten ist.

### Beispiele

Beispiel #1 $mysqli->errno-Beispiel

Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if ($mysqli->connect_errno) {
        printf("Verbindung fehlgeschlagen: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Fehlercode: %d\n", $mysqli->errno);
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Fehlercode: %d\n", mysqli_errno($link));
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehlercode: 1193

### Siehe auch

- mysqli_connect_errno() - Liefert den Fehlercode des letzten Verbindungsversuchs
- mysqli_connect_error() - Liefert eine Beschreibung des letzten Verbindungsfehlers
- mysqli_error() - Liefert eine Zeichenkette, die den letzten Fehler beschreibt
- mysqli_sqlstate() - Liefert den SQLSTATE-Fehler der letzten MySQL-Operation

# mysqli::$error

# mysqli_error

(PHP 5, PHP 7, PHP 8)

mysqli::$error -- mysqli_error — Liefert eine Zeichenkette, die den letzten Fehler beschreibt

### Beschreibung

Objektorientierter Stil

string $mysqli->error;

Prozeduraler Stil

function mysqli_error(mysqli `$mysql`): string

Gibt die letzte Fehlermeldung des letzten MySQLi-Funktionsaufrufs zurück, der entweder erfolgreich war oder fehlschlug.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die den Fehler beschreibt, oder eine leere Zeichenkette, wenn kein Fehler aufgetreten ist.

### Beispiele

Beispiel #1 $mysqli->error-Beispiel

Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if ($mysqli->connect_errno) {
        printf("Verbindung fehlgeschlagen: %s\n", $mysqli->connect_error);
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        printf("Fehlermeldung: %s\n", $mysqli->error);
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        printf("Fehlermeldung: %s\n", mysqli_error($link));
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehlermeldung: Unknown system variable 'a'

### Siehe auch

- mysqli_connect_errno() - Liefert den Fehlercode des letzten Verbindungsversuchs
- mysqli_connect_error() - Liefert eine Beschreibung des letzten Verbindungsfehlers
- mysqli_errno() - Liefert den Fehlercode des letzten Funktionsaufrufs
- mysqli_sqlstate() - Liefert den SQLSTATE-Fehler der letzten MySQL-Operation

# mysqli::$error_list

# mysqli_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli::$error_list -- mysqli_error_list — Liefert eine Liste der Fehler des zuletzt ausgeführten Befehls

### Beschreibung

Objektorientierter Stil

array $mysqli->error_list;

Prozeduraler Stil

function mysqli_error_list(mysqli `$mysql`): array

Gibt ein Array von Fehlern des letzten MySQLi-Funktionsaufrufs zurück, der entweder erfolgreich war oder fehlschlug.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt eine Liste von Fehlern zurück. Die einzelnen Fehler liegen als assoziative Arrays mit den Schlüsseln errno, error und sqlstate vor.

### Beispiele

Beispiel #1 $mysqli->error_list-Beispiel

Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "nobody", "");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    if (!$mysqli->query("SET a=1")) {
        print_r($mysqli->error_list);
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    if (!mysqli_query($link, "SET a=1")) {
        print_r(mysqli_error_list($link));
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Array
    (
        [0] => Array
            (
                [errno] => 1193
                [sqlstate] => HY000
                [error] => Unknown system variable 'a'
            )

    )

### Siehe auch

- mysqli_connect_errno() - Liefert den Fehlercode des letzten Verbindungsversuchs
- mysqli_connect_error() - Liefert eine Beschreibung des letzten Verbindungsfehlers
- mysqli_error() - Liefert eine Zeichenkette, die den letzten Fehler beschreibt
- mysqli_sqlstate() - Liefert den SQLSTATE-Fehler der letzten MySQL-Operation

# mysqli::execute_query

# mysqli_execute_query

(PHP 8 >= 8.2.0)

mysqli::execute_query -- mysqli_execute_query — Bereitet eine SQL-Anweisung vor, bindet die Parameter und führt die Anweisung aus

### Beschreibung

Objektorientierter Stil

public function mysqli::execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool

Prozeduraler Stil

function mysqli_execute_query(mysqli `$mysql`, string `$query`, ?array `$params` = `null`): mysqli_result|bool

Bereitet eine SQL-Anweisung vor, bindet die Parameter und führt die Anweisung aus. Die Methode mysqli::execute_query() ist eine Zusammenfassung von mysqli::prepare(), mysqli_stmt::bind_param(), mysqli_stmt::execute() und mysqli_stmt::get_result().

Die Anweisungsvorlage darf null oder mehr Fragezeichen-Parametermarker (`?`) - auch Platzhalter genannt - enthalten. Die Parameterwerte müssen mit dem Parameter `params` als Array angegeben werden.

Eine vorbereitete Anweisung wird im Hintergrund erstellt und ist nie außerhalb der Funktion sichtbar. Es ist unmöglich, auf die Eigenschaften der Anweisung zuzugreifen, wie es mit einem mysqli_stmt-Objekt möglich wäre. Aufgrund dieser Einschränkung werden die Statusinformationen in das mysqli-Objekt kopiert und stehen über dessen Methoden, z. B. mysqli_affected_rows() oder mysqli_error(), zur Verfügung.

> Hinweis:

> Wenn eine Anweisung an mysqli_execute_query() übergeben wird, die größer ist als die vom Server maximal erlaubte Paketgröße (`max_allowed_packet`), hängen die zurückgegebenen Fehlercodes vom Betriebssystem ab. Die Funktion verhält sich wie folgt:

> - Unter Linux gibt sie den Fehlercode 1153 zurück. Diese Fehlermeldung bedeutet got a packet bigger than `max_allowed_packet` bytes.

> - Unter Windows gibt sie den Fehlercode 2006 zurück. Diese Fehlermeldung bedeutet server has gone away.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`query`

  Die Zeichenkette mit der Abfrage. Sie darf nur eine SQL-Anweisung enthalten.

  Die SQL-Anweisung darf null oder mehr Platzhalter für Parameter enthalten, die an den entsprechenden Stellen durch Fragezeichen (`?`) dargestellt werden.

  > Hinweis:

  > Die Platzhalter sind nur an bestimmten Stellen einer SQL-Anweisung zulässig. Zum Beispiel sind sie bei einer `INSERT`-Anweisung in der `VALUES()`-Liste erlaubt, um die Werte für die Spalten einer Zeile anzugeben, oder bei einer `WHERE`-Klausel im Vergleich mit einer Spalte, um einen Vergleichswert anzugeben. Nicht zulässig sind sie hingegen für Bezeichner (wie Tabellen- oder Spaltennamen).

`params`

  Eine optionale Array-Liste mit so vielen Elementen, wie es gebundene Parameter in der auszuführenden SQL-Anweisung gibt. Jeder Wert wird wie eine Zeichenkette behandelt.

### Rückgabewerte

Gibt bei einem Fehler `false` zurück. Bei erfolgreichen Abfragen, die eine Ergebnismenge erzeugen, also z. B. `SELECT, SHOW, DESCRIBE` oder `EXPLAIN`, wird ein mysqli_result-Objekt zurückgegeben. Bei anderen erfolgreichen Abfragen wird `true` zurückgegeben.

### Beispiele

Beispiel #1 mysqli::execute_query()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = $mysqli->execute_query($query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
    $result = mysqli_execute_query($link, $query, ['DEU']);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["District"]);
    }

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Aachen (Nordrhein-Westfalen)
    Augsburg (Baijeri)
    Bergisch Gladbach (Nordrhein-Westfalen)
    Berlin (Berliini)
    Bielefeld (Nordrhein-Westfalen)

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_execute() - Führt eine vorbereitete Anweisung aus
- mysqli_stmt_bind_param() - Bindet Variablen als Parameter an eine vorbereitete Anweisung (prepared statement)
- mysqli_stmt_get_result() - Ruft die Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab

# mysqli::$field_count

# mysqli_field_count

(PHP 5, PHP 7, PHP 8)

mysqli::$field_count -- mysqli_field_count — Liefert die Anzahl der Spalten der letzten Abfrage

### Beschreibung

Objektorientierter Stil

int $mysqli->field_count;

Prozeduraler Stil

function mysqli_field_count(mysqli `$mysql`): int

Gibt die Anzahl der Spalten der letzten Abfrage für die Verbindung zurück, die durch den Parameter `mysql` angegeben wird. Diese Funktion kann nützlich sein, wenn die Funktion mysqli_store_result() verwendet wird, um festzustellen, ob die Abfrage eine nicht leere Ergebnismenge erzeugt haben sollte oder nicht, ohne die Art der Abfrage zu kennen.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt einen Integerwert zurück, der die Anzahl der Spalten in einer Ergebnismenge angibt.

### Beispiele

Beispiel #1 $mysqli->field_count-Beispiel

Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query( "DROP TABLE IF EXISTS friends");
    $mysqli->query( "CREATE TABLE friends (id int, name varchar(20))");

    $mysqli->query( "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $mysqli->real_query("SELECT * FROM friends");

    if ($mysqli->field_count) {
        /* es war eine select/show- oder describe-Abfrage */
        $result = $mysqli->store_result();

        /* Ergebnismenge verarbeiten */
        $row = $result->fetch_row();

        /* Ergebnismenge löschen */
        $result->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "DROP TABLE IF EXISTS friends");
    mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

    mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    mysqli_real_query($link, "SELECT * FROM friends");

    if (mysqli_field_count($link)) {
        /* es war eine select/show- oder describe-Abfrage */
        $result = mysqli_store_result($link);

        /* Ergebnismenge verarbeiten */
        $row = mysqli_fetch_row($result);

        /* Ergebnismenge löschen */
        mysqli_free_result($result);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

# mysqli::get_charset

# mysqli_get_charset

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_charset -- mysqli_get_charset — Liefert ein Zeichensatz-Objekt

### Beschreibung

Objektorientierter Stil

public function mysqli::get_charset(): ?object

Prozeduraler Stil

function mysqli_get_charset(mysqli `$mysql`): ?object

Gibt ein Zeichensatz-Objekt zurück, das mehrere Eigenschaften des aktuell verwendeten Zeichensatzes enthält.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Die Funktion gibt ein Zeichensatz-Objekt mit den folgenden Eigenschaften zurück:

`charset`

  Name des Zeichensatzes

`collation`

  Name der Kollation (Sortierregel)

`dir`

  Verzeichnis, aus dem die Beschreibung des Zeichensatzes geholt wurde (?) oder "" für interne Zeichensätze

`min_length`

  Minimale Zeichenlänge (in Bytes)

`max_length`

  Maximale Zeichenlänge (in Bytes)

`number`

  Interne Nummer des Zeichensatzes

`state`

  Status des Zeichensatzes (?)

### Beispiele

Beispiel #1 mysqli::get_charset()-Beispiel

Objektorientierter Stil

    <?php
      $db = mysqli_init();
      $db->real_connect("localhost","root","","test");
      var_dump($db->get_charset());
    ?>

Prozeduraler Stil

    <?php
      $db = mysqli_init();
      mysqli_real_connect($db, "localhost","root","","test");
      var_dump(mysqli_get_charset($db));
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    object(stdClass)#2 (7) {
      ["charset"]=>
      string(6) "latin1"
      ["collation"]=>
      string(17) "latin1_swedish_ci"
      ["dir"]=>
      string(0) ""
      ["min_length"]=>
      int(1)
      ["max_length"]=>
      int(1)
      ["number"]=>
      int(8)
      ["state"]=>
      int(801)
    }

### Siehe auch

- mysqli_character_set_name() - Liefert den aktuellen Zeichensatz der Datenbankverbindung
- mysqli_set_charset() - Legt den Standard-Zeichensatz des Clients fest

# mysqli::$client_info

# mysqli::get_client_info

# mysqli_get_client_info

(PHP 5, PHP 7, PHP 8)

mysqli::$client_info -- mysqli::get_client_info -- mysqli_get_client_info — Liefert die Version des MySQL-Clients als Zeichenkette

### Beschreibung

Objektorientierter Stil

string $mysqli->client_info;
#[\Deprecated]
public function mysqli::get_client_info(): string

Prozeduraler Stil

function mysqli_get_client_info(?mysqli `$mysql` = null): string

Gibt eine Zeichenkette zurück, die die Version der MySQL-Client-Bibliothek angibt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die die Version der MySQL-Client-Bibliothek darstellt.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Aufruf von mysqli_get_client_info() mit dem Parameter `mysql` ist veraltet. Diese Funktion benötigte nie einen Parameter, sondern ließ ihn fälschlicherweise als optionalen Parameter zu.
8.1.0 | Der objektorientierte Stil mysqli::get_client_info() ist veraltet.

### Beispiele

Beispiel #1 mysqli_get_client_info

    <?php

    /* Es wird keine Verbindung benötigt, um die
       Version der MySQL-Client-Bibliothek zu ermitteln */

    printf("Version der Client-Bibliothek: %s\n", mysqli_get_client_info());
    ?>

### Siehe auch

- mysqli_get_client_version() - Liefert die Version des MySQL-Clients als Integer
- mysqli_get_server_info() - Liefert die Version des MySQL-Servers
- mysqli_get_server_version() - Liefert die Version des MySQL-Servers als Integer

# mysqli::$client_version

# mysqli_get_client_version

(PHP 5, PHP 7, PHP 8)

mysqli::$client_version -- mysqli_get_client_version — Liefert die Version des MySQL-Clients als Integer

### Beschreibung

Objektorientierter Stil

int $mysqli->client_version;

Prozeduraler Stil

function mysqli_get_client_version(): int

Gibt die Versionsnummer des MySQL-Clients als Integer zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt eine Zahl zurück, die die Version der MySQL-Client-Bibliothek im folgenden Format darstellt: `Haupt_Version * 10000 + Neben_Version * 100 + Unter_Version`. So wird zum Beispiel Version 4.1.0 als 40100 zurückgegeben.

Dies ist nützlich, um schnell die Version der Client-Bibliothek zu ermitteln, um zu wissen, ob eine Fähigkeit vorhanden ist.

### Beispiele

Beispiel #1 mysqli_get_client_version

    <?php

    /* Es wird keine Verbindung benötigt, um die
       Version der MySQL-Client-Bibliothek zu ermitteln */

    printf("Version der Client-Bibliothek: %d\n", mysqli_get_client_version());
    ?>

### Siehe auch

- mysqli_get_client_info() - Liefert die Version des MySQL-Clients als Zeichenkette
- mysqli_get_server_info() - Liefert die Version des MySQL-Servers
- mysqli_get_server_version() - Liefert die Version des MySQL-Servers als Integer

# mysqli::get_connection_stats

# mysqli_get_connection_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::get_connection_stats -- mysqli_get_connection_stats — Liefert Verbindungsstatistiken des Clients

### Beschreibung

Objektorientierter Stil

public function mysqli::get_connection_stats(): array

Prozeduraler Stil

function mysqli_get_connection_stats(mysqli `$mysql`): array

Gibt Statistiken über die Client-Verbindung zurück.

> Hinweis:

> Nur in mysqlnd verfügbar.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt ein Array mit Verbindungsstatistiken zurück.

### Beispiele

Beispiel #1 mysqli_get_connection_stats()-Beispiel

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_connection_stats($link));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Siehe auch

- Beschreibung der Statistiken

# mysqli::$host_info

# mysqli_get_host_info

(PHP 5, PHP 7, PHP 8)

mysqli::$host_info -- mysqli_get_host_info — Liefert eine Zeichenkette, die den Typ der verwendeten Verbindung angibt

### Beschreibung

Objektorientierter Stil

string $mysqli->host_info;

Prozeduraler Stil

function mysqli_get_host_info(mysqli `$mysql`): string

Gibt eine Zeichenkette zurück, die die durch den Parameter `mysql` angegebene Verbindung beschreibt (einschließlich des Hostnamens des Servers).

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die den Hostnamen des Servers und den Verbindungstyp darstellt.

### Beispiele

Beispiel #1 $mysqli->host_info-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Host-Informationen ausgeben */
    printf("Host-Info: %s\n", $mysqli->host_info);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Host-Informationen ausgeben */
    printf("Host-Info: %s\n", mysqli_get_host_info($link));

Die obigen Bespiele erzeugen folgende Ausgabe:

    Host-Info: Localhost via UNIX socket

### Siehe auch

- mysqli_get_proto_info() - Liefert die Version des verwendeten MySQL-Protokolls

# mysqli::$protocol_version

# mysqli_get_proto_info

(PHP 5, PHP 7, PHP 8)

mysqli::$protocol_version -- mysqli_get_proto_info — Liefert die Version des verwendeten MySQL-Protokolls

### Beschreibung

Objektorientierter Stil

int $mysqli->protocol_version;

Prozeduraler Stil

function mysqli_get_proto_info(mysqli `$mysql`): int

Gibt einen Integerwert zurück, der die Version des MySQL-Protokolls angibt, das von der durch den Parameter `mysql` angegebenen Verbindung verwendet wird.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt einen Integerwert zurück, der die Protokoll-Version angibt.

### Beispiele

Beispiel #1 $mysqli->protocol_version-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Protokoll-Version ausgeben */
    printf("Protokoll-Version: %d\n", $mysqli->protocol_version);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Protokoll-Version ausgeben */
    printf("Protokoll-Version: %d\n", mysqli_get_proto_info($link));

Die obigen Bespiele erzeugen folgende Ausgabe:

    Protokoll-Version: 10

### Siehe auch

- mysqli_get_host_info() - Liefert eine Zeichenkette, die den Typ der verwendeten Verbindung angibt

# mysqli::$server_info

# mysqli::get_server_info

# mysqli_get_server_info

(PHP 5, PHP 7, PHP 8)

mysqli::$server_info -- mysqli::get_server_info -- mysqli_get_server_info — Liefert die Version des MySQL-Servers

### Beschreibung

Objektorientierter Stil

string $mysqli->server_info;
public function mysqli::get_server_info(): string

Prozeduraler Stil

function mysqli_get_server_info(mysqli `$mysql`): string

Gibt eine Zeichenkette mit der Version des MySQL-Servers zurück, mit dem die Erweiterung mysqli verbunden ist.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die die Server-Version angibt.

### Beispiele

Beispiel #1 $mysqli->server_info-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Server-Version ausgeben */
    printf("Server-Version: %s\n", $mysqli->server_info);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Server-Version ausgeben */
    printf("Server-Version: %s\n", mysqli_get_server_info($link));

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Server-Version: 8.0.21

### Siehe auch

- mysqli_get_client_info() - Liefert die Version des MySQL-Clients als Zeichenkette
- mysqli_get_client_version() - Liefert die Version des MySQL-Clients als Integer
- mysqli_get_server_version() - Liefert die Version des MySQL-Servers als Integer

# mysqli::$server_version

# mysqli_get_server_version

(PHP 5, PHP 7, PHP 8)

mysqli::$server_version -- mysqli_get_server_version — Liefert die Version des MySQL-Servers als Integer

### Beschreibung

Objektorientierter Stil

int $mysqli->server_version;

Prozeduraler Stil

function mysqli_get_server_version(mysqli `$mysql`): int

mysqli_get_server_version() gibt die Version des verbundenen Servers (angegeben durch `mysql`) als Ganzzahl zurück.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt die Server-Version als Ganzzahl zurück.

Diese Versionsnummer hat die Form `Haupt_Version * 10000 + Neben_Version * 100 + Unter_Version` (d. h. Version 4.1.0 ist 40100).

### Beispiele

Beispiel #1 $mysqli->server_version-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password");

    /* Server-Version ausgeben */
    printf("Server-Version: %d\n", $mysqli->server_version);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password");

    /* Server-Version ausgeben */
    printf("Server-Version: %d\n", mysqli_get_server_version($link));

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Server-Version: 80021

### Siehe auch

- mysqli_get_client_info() - Liefert die Version des MySQL-Clients als Zeichenkette
- mysqli_get_client_version() - Liefert die Version des MySQL-Clients als Integer
- mysqli_get_server_info() - Liefert die Version des MySQL-Servers

# mysqli::get_warnings

# mysqli_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_warnings -- mysqli_get_warnings — Ermittelt das Ergebnis von SHOW WARNINGS

### Beschreibung

Objektorientierter Stil

public function mysqli::get_warnings(): mysqli_warning|false

Prozeduraler Stil

function mysqli_get_warnings(mysqli `$mysql`): mysqli_warning|false

Gibt eine einfach verknüpfte Liste bestehend aus mysqli_warning oder `false` zurück, wenn keine Warnungen vorhanden sind. Jedes Objekt in der Liste entspricht einer einzelnen Zeile des Ergebnisses von `SHOW WARNINGS`. Durch den Aufruf von mysqli_warning::next() wird das Objekt mit den Werten der nächsten Zeile neu gefüllt.

> Hinweis: Um Warnmeldungen abzurufen, wird empfohlen, statt dieser Funktion den SQL-Befehl `SHOW WARNINGS [limit row_count]` zu verwenden.

Warnung

Die verknüpfte Liste kann nicht zurückgespult oder erneut aufgerufen werden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt eine einfach verknüpfte Liste bestehend aus mysqli_warning oder `false` zurück, wenn keine Warnungen vorhanden sind.

### Beispiele

Beispiel #1 Die verknüpfte Liste durchlaufen, um alle Warnungen zu erhalten

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if ($mysqli->warning_count > 0) {
        $warning = $mysqli->get_warnings();
        if ($warning !== false) {
            do {
                printf("Fehlernummer: %s\n", $warning->errno);
                printf("Meldung: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "user", "password", "test");

    mysqli_query($link, "SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if (mysqli_warning_count($link) > 0) {
        $warning = mysqli_get_warnings($link);
        if ($warning !== false) {
            do {
                printf("Fehlernummer: %s\n", $warning->errno);
                printf("Meldung: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehlernummer: 1365
    Meldung: Division by 0
    Fehlernummer: 1292
    Meldung: Truncated incorrect INTEGER value: 'NULL'

# mysqli::$info

# mysqli_info

(PHP 5, PHP 7, PHP 8)

mysqli::$info -- mysqli_info — Ruft Informationen über die zuletzt ausgeführte Abfrage ab

### Beschreibung

Objektorientierter Stil

?string $mysqli->info;

Prozeduraler Stil

function mysqli_info(mysqli `$mysql`): ?string

Die Funktion mysqli_info() gibt eine Zeichenkette mit Informationen über die zuletzt ausgeführte Abfrage zurück. Die Form dieser Zeichenkette wird im Folgenden beschrieben:

Mögliche Rückgabewerte von mysqli_info
Typ der Abfrage | Beispiel für die Ergebnis-Zeichenkette
--- | ---
INSERT INTO...SELECT... | Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO...VALUES (...),(...),(...) | Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ... | Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE ... | Records: 3 Duplicates: 0 Warnings: 0
UPDATE ... | Rows matched: 40 Changed: 40 Warnings: 0

> Hinweis:

> Abfragen, die nicht in eines der oben genannten Formate fallen, werden nicht unterstützt. In diesen Fällen gibt mysqli_info() eine leere Zeichenkette zurück.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die zusätzliche Informationen über die zuletzt ausgeführte Abfrage enthält.

### Beispiele

Beispiel #1 $mysqli->info-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    $mysqli->query("INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", $mysqli->info);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE t1 LIKE City");

    /* INSERT INTO ... SELECT */
    mysqli_query($link, "INSERT INTO t1 SELECT * FROM City ORDER BY ID LIMIT 150");
    printf("%s\n", mysqli_info($link));

Die obigen Bespiele erzeugen folgende Ausgabe:

    Records: 150  Duplicates: 0  Warnings: 0

### Siehe auch

- mysqli_affected_rows() - Liefert die Anzahl der Datensätze, die vom letzten MySQL-Vorgang betroffen waren
- mysqli_warning_count() - Liefert die Anzahl der Warnungen, die durch die letzte Abfrage erzeugt wurden
- mysqli_num_rows() - Ermittelt die Anzahl der Zeilen einer Ergebnismenge

# mysqli::init

# mysqli_init

(PHP 5, PHP 7, PHP 8)

mysqli::init -- mysqli_init — Initialisiert MySQLi und liefert ein Objekt zur Verwendung mit mysqli_real_connect()

### Beschreibung

Objektorientierter Stil

#[\Deprecated]
public function mysqli::init(): ?bool

Prozeduraler Stil

function mysqli_init(): mysqli|false

Erstellt oder initialisiert ein MySQL-Objekt, das für mysqli_options() und mysqli_real_connect() geeignet ist.

> Hinweis:

> Abgesehen von den Funktionen mysqli_options() und mysqli_ssl_set() schlagen alle nachfolgenden Aufrufe einer mysqli-Funktion solange fehl, bis mysqli_real_connect() aufgerufen wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

mysqli::init() gibt bei Erfolg `null` zurück. Bei einem Fehler wird `false` zurückgegeben. mysqli_init() gibt bei Erfolg ein Objekt zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Die objektorientierte Methode mysqli::init() ist veraltet. Anstelle von parent::init() sollte parent::__construct() verwendet werden.

### Beispiele

Siehe mysqli_real_connect().

### Siehe auch

- mysqli_options() - Setzt Optionen
- mysqli_close() - Schließt die zuvor geöffnete Datenbankverbindung
- mysqli_real_connect() - Baut eine Verbindung zu einem MySQL-Server auf
- mysqli_connect() - Alias von mysqli::__construct

# mysqli::$insert_id

# mysqli_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli::$insert_id -- mysqli_insert_id — Liefert den Wert, der bei der letzten Anweisung für die AUTO_INCREMENT-Spalte erzeugt wurde

### Beschreibung

Objektorientierter Stil

int|string $mysqli->insert_id;

Prozeduraler Stil

function mysqli_insert_id(mysqli `$mysql`): int|string

Gibt die ID zurück, die durch eine `INSERT`- oder `UPDATE`-Anweisung für eine Tabelle mit einer Spalte mit dem Attribut `AUTO_INCREMENT` erzeugt wurde. Im Fall einer `INSERT`-Anweisung für mehrere Zeilen, wird der erste automatisch erzeugte Wert zurückgegeben, der erfolgreich eingefügt wurde.

Wenn eine `INSERT`- oder `UPDATE`-Anweisung mit der MySQL-Funktion `LAST_INSERT_ID()` ausgeführt wird, wird auch der von mysqli_insert_id() zurückgegebene Wert geändert. Wenn `LAST_INSERT_ID(expr)` verwendet wurde, um den Wert von `AUTO_INCREMENT` zu erzeugen, wird der Wert des letzten Ausdrucks `expr` anstelle des erzeugten `AUTO_INCREMENT`-Werts zurückgegeben.

Gibt `0` zurück, wenn die vorherige Anweisung einen `AUTO_INCREMENT`-Wert nicht verändert hat. mysqli_insert_id() muss unmittelbar nach der Anweisung aufgerufen werden, die den Wert erzeugt hat.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt den Wert der `AUTO_INCREMENT`-Spalte zurück, die durch die vorherige Anweisung aktualisiert wurde. Gibt Null zurück, wenn es keine vorherige Anweisung für die Verbindung gab oder wenn die Anweisung keinen `AUTO_INCREMENT`-Wert aktualisiert hat.

Nur Anweisungen, die über die aktuelle Verbindung gesendet werden, beeinflussen den Rückgabewert. Der Wert wird nicht von Anweisungen beeinflusst, die über andere Verbindungen oder Clients ausgegeben werden.

> Hinweis:

> Wenn die Zahl größer ist als der maximale int-Wert, wird sie als Zeichenkette zurückgegeben.

### Beispiele

Beispiel #1 $mysqli->insert_id-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    $mysqli->query($query);

    printf("Der neue Datensatz hat die ID %d.\n", $mysqli->insert_id);

    /* Tabelle löschen */
    $mysqli->query("DROP TABLE myCity");

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TABLE myCity LIKE City");

    $query = "INSERT INTO myCity VALUES (NULL, 'Stuttgart', 'DEU', 'Stuttgart', 617000)";
    mysqli_query($link, $query);

    printf("Der neue Datensatz hat die ID %d.\n", mysqli_insert_id($link));

    /* Tabelle löschen */
    mysqli_query($link, "DROP TABLE myCity");

Die obigen Bespiele erzeugen folgende Ausgabe:

    Der neue Datensatz hat die ID 1.

# mysqli::kill

# mysqli_kill

(PHP 5, PHP 7, PHP 8)

mysqli::kill -- mysqli_kill — Weist den Server an, einen MySQL-Thread zu beenden

Warnung

Diese Funktion ist seit PHP 8.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

Objektorientierter Stil

#[\Deprecated]
public function mysqli::kill(int `$process_id`): bool

Prozeduraler Stil

#[\Deprecated]
function mysqli_kill(mysqli `$mysql`, int `$process_id`): bool

Diese Funktion wird verwendet, um den Server aufzufordern, den durch den Parameter `process_id` angegebenen MySQL-Thread zu beenden. Dieser Wert muss mit der Funktion mysqli_thread_id() abgefragt werden.

Um eine laufende Abfrage zu beenden, sollte der SQL-Befehl `KILL QUERY processid` verwendet werden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Sowohl mysqli::kill() als auch mysqli_kill() sind nun veraltet. Stattdessen sollte der SQL-Befehl `KILL` verwendet werden.

### Beispiele

Beispiel #1 mysqli::kill()-Beispiel

Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    /* Ermitteln der Thread-ID */
    $thread_id = $mysqli->thread_id;

    /* Verbindung beenden */
    $mysqli->kill($thread_id);

    /* Dies sollte einen Fehler erzeugen */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Fehler: %s\n", $mysqli->error);
        exit;
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    /* Ermitteln der Thread-ID */
    $thread_id = mysqli_thread_id($link);

    /* Verbindung beenden */
    mysqli_kill($link, $thread_id);

    /* Dies sollte einen Fehler erzeugen */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Fehler: %s\n", mysqli_error($link));
        exit;
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehler: MySQL server has gone away

### Siehe auch

- mysqli_thread_id() - Liefert die Thread-ID der aktuellen Verbindung

# mysqli::more_results

# mysqli_more_results

(PHP 5, PHP 7, PHP 8)

mysqli::more_results -- mysqli_more_results — Prüft, ob es von einer Mehrfachabfrage noch weitere Abfrageergebnisse gibt

### Beschreibung

Objektorientierter Stil

public function mysqli::more_results(): bool

Prozeduraler Stil

function mysqli_more_results(mysqli `$mysql`): bool

Zeigt an, ob von einem vorherigen Aufruf von mysqli_multi_query() eine oder mehrere Ergebnismengen verfügbar sind.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt `true` zurück, wenn von einem vorherigen Aufruf von mysqli_multi_query() eine oder mehrere Ergebnismengen (einschließlich Fehler) verfügbar sind, andernfalls `false`.

### Beispiele

Siehe mysqli_multi_query().

### Siehe auch

- mysqli_multi_query() - Führt eine oder mehrere Abfragen in einer Datenbank durch
- mysqli_next_result() - Bereitet das nächste Ergebnis von multi_query vor
- mysqli_store_result() - Überträgt die Ergebnismenge der letzten Abfrage
- mysqli_use_result() - Initiiert den Abruf einer Ergebnismenge

# mysqli::multi_query

# mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — Führt eine oder mehrere Abfragen in einer Datenbank durch

### Beschreibung

Objektorientierter Stil

public function mysqli::multi_query(string `$query`): bool

Prozeduraler Stil

function mysqli_multi_query(mysqli `$mysql`, string `$query`): bool

Führt eine oder mehrere Abfragen aus, die durch Semikolons getrennt sind.

Warnung

# Sicherheitswarnung: SQL-Injection

Wenn die Abfrage irgendwelche Eingabevariablen enthält, sollten stattdessen parametrisierte Prepared Statements verwendet werden. Alternativ dazu müssen die Daten korrekt formatiert sein und alle Strings müssen mit der Funktion mysqli_real_escape_string() maskiert werden.

Die Abfragen werden dabei asynchron in einem einzigen Aufruf an die Datenbank gesendet, aber die Datenbank verarbeitet sie sequentiell. mysqli_multi_query() wartet, bis die erste Abfrage abgeschlossen ist, bevor es die Kontrolle an PHP zurückgibt. Der MySQL-Server verarbeitet dann der Reihe nach die nächsten Abfragen. Sobald das nächste Ergebnis vorliegt, wartet MySQL darauf, dass die Funktion mysqli_next_result() von PHP erneut ausgeführt wird.

Es wird empfohlen, eine do-while-Schleife zu verwenden, um mehrere Abfragen zu verarbeiten. Die Verbindung ist so lange belegt, bis alle Abfragen abgeschlossen sind und ihre Ergebnisse an PHP übermittelt wurden. Solange nicht alle Abfragen abgearbeitet sind, kann keine andere Anweisung auf derselben Verbindung ausgeführt werden. Um mit der nächsten Abfrage in der Reihenfolge fortzufahren, muss mysqli_next_result() verwendet werden. Wenn das nächste Ergebnis noch nicht bereit ist, wartet mysqli auf die Antwort des MySQL-Servers. Um zu prüfen, ob es weitere Ergebnisse gibt, kann mysqli_more_results() verwendet werden.

Bei Abfragen, die eine Ergebnismenge zurückgeben, also zum Beispiel `SELECT, SHOW, DESCRIBE` oder `EXPLAIN`, können die Funktionen mysqli_use_result() oder mysqli_store_result() verwendet werden, um die Ergebnismenge abzurufen. Bei Abfragen, die keine Ergebnismenge zurückgeben, können die gleichen Funktionen verwendet werden, um Informationen wie die Anzahl der betroffenen Zeilen abzurufen.

Tipp

Wenn `CALL`-Anweisungen für gespeicherte Prozeduren ausgeführt werden, können mehrere Ergebnismengen erzeugt werden. Wenn die gespeicherte Prozedur `SELECT`-Anweisungen enthält, werden die Ergebnismengen in der Reihenfolge zurückgegeben, in der sie bei der Ausführung der Prozedur erzeugt werden. Im Allgemeinen kann der Aufrufende nicht wissen, wie viele Ergebnismengen eine Prozedur zurückgeben wird, und muss damit rechnen, mehrere Ergebnisse abrufen zu müssen. Das letzte Ergebnis der Prozedur ist ein Statusergebnis, das keine Ergebnismenge enthält. Der Status gibt an, ob die Prozedur erfolgreich war oder ein Fehler aufgetreten ist.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`query`

  Eine Zeichenkette mit den Abfragen, die ausgeführt werden sollen. Mehrere Abfragen müssen durch ein Semikolon getrennt werden.

### Rückgabewerte

Wenn die erste Anweisung fehlgeschlagen ist, wird `false` zurückgegeben. Um nachfolgende Fehler von anderen Anweisungen zu erhalten, muss zuerst die Funktion mysqli_next_result() aufgerufen werden.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 mysqli::multi_query()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Mehrfachabfrage ausführen */
    $mysqli->multi_query($query);
    do {
        /* Ergebnismenge in PHP speichern */
        if ($result = $mysqli->store_result()) {
            while ($row = $result->fetch_row()) {
                printf("%s\n", $row[0]);
            }
        }
        /* Trennlinie ausgeben */
        if ($mysqli->more_results()) {
            printf("-----------------\n");
        }
    } while ($mysqli->next_result());

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Mehrfachabfrage ausführen */
    mysqli_multi_query($link, $query);
    do {
        /* Ergebnismenge in PHP speichern */
        if ($result = mysqli_store_result($link)) {
            while ($row = mysqli_fetch_row($result)) {
                printf("%s\n", $row[0]);
            }
        }
        /* Trennlinie ausgeben */
        if (mysqli_more_results($link)) {
            printf("-----------------\n");
        }
    } while (mysqli_next_result($link));

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Siehe auch

- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_use_result() - Initiiert den Abruf einer Ergebnismenge
- mysqli_store_result() - Überträgt die Ergebnismenge der letzten Abfrage
- mysqli_next_result() - Bereitet das nächste Ergebnis von multi_query vor
- mysqli_more_results() - Prüft, ob es von einer Mehrfachabfrage noch weitere Abfrageergebnisse gibt

# mysqli::next_result

# mysqli_next_result

(PHP 5, PHP 7, PHP 8)

mysqli::next_result -- mysqli_next_result — Bereitet das nächste Ergebnis von multi_query vor

### Beschreibung

Objektorientierter Stil

public function mysqli::next_result(): bool

Prozeduraler Stil

function mysqli_next_result(mysqli `$mysql`): bool

Bereitet die nächste Ergebnismenge aus einem vorherigen Aufruf von mysqli_multi_query() vor, die dann durch die Funktionen mysqli_store_result() oder mysqli_use_result() abgerufen werden kann.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. Gibt im Gegensatz zu mysqli_more_results() auch `false` zurück, wenn die nächste Anweisung zu einem Fehler führte.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Siehe mysqli_multi_query().

### Siehe auch

- mysqli_multi_query() - Führt eine oder mehrere Abfragen in einer Datenbank durch
- mysqli_more_results() - Prüft, ob es von einer Mehrfachabfrage noch weitere Abfrageergebnisse gibt
- mysqli_store_result() - Überträgt die Ergebnismenge der letzten Abfrage
- mysqli_use_result() - Initiiert den Abruf einer Ergebnismenge

# mysqli::options

# mysqli_options

(PHP 5, PHP 7, PHP 8)

mysqli::options -- mysqli_options — Setzt Optionen

### Beschreibung

Objektorientierter Stil

public function mysqli::options(int `$option`, string|int `$value`): bool

Prozeduraler Stil

function mysqli_options(mysqli `$mysql`, int `$option`, string|int `$value`): bool

Wird verwendet, um zusätzliche Verbindungsoptionen festzulegen und das Verhalten einer Verbindung zu beeinflussen.

Diese Funktion kann mehrfach aufgerufen werden, um mehrere Optionen zu setzen.

mysqli_options() muss nach mysqli_init() und vor mysqli_real_connect() aufgerufen werden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`option`

  Die Option, die gesetzt werden soll. Es kann einer der folgenden Werte sein:

  Gültige Optionen
  Name | Beschreibung
  --- | ---
  `MYSQLI_OPT_CONNECT_TIMEOUT` | Zeitlimit für den Verbindungsaufbau (in Sekunden)
  `MYSQLI_OPT_READ_TIMEOUT` | Zeitlimit für die Ausführung eines Befehls (in Sekunden). Verfügbar seit PHP 7.2.0.
  `MYSQLI_OPT_LOCAL_INFILE` | Aktivieren/Deaktivieren von `LOAD LOCAL INFILE`
  `MYSQLI_INIT_COMMAND` | Der Befehl, der nach dem Aufbau einer Verbindung zum MySQL-Server ausgeführt wird
  `MYSQLI_SET_CHARSET_NAME` | Der Zeichensatz, der als Standard gesetzt werden soll
  `MYSQLI_READ_DEFAULT_FILE` | Optionen aus der benannten Optionsdatei lesen statt aus my.cnf; wird von mysqlnd nicht unterstützt.
  `MYSQLI_READ_DEFAULT_GROUP` | Liest die Optionen der benannten Gruppe aus der Datei my.cnf oder der Datei, die mit `MYSQL_READ_DEFAULT_FILE` angegeben wurde; wird von mysqlnd nicht unterstützt.
  `MYSQLI_SERVER_PUBLIC_KEY` | Die öffentliche RSA-Schlüsseldatei, die für die SHA-256-basierte Authentifizierung verwendet wird.
  `MYSQLI_OPT_NET_CMD_BUFFER_SIZE` | Die Größe des internen Befehls-/Netzwerkpuffers; gilt nur für mysqlnd.
  `MYSQLI_OPT_NET_READ_BUFFER_SIZE` | Maximale zu lesende Blockgröße (in Bytes), wenn der Textkörper eines MySQL-Befehlspakets gelesen wird; gilt nur für mysqlnd.
  `MYSQLI_OPT_INT_AND_FLOAT_NATIVE` | Wenn nicht-vorbereitete Anweisungen verwendet werden, werden Spalten mit Integer- und Float-Werten wieder in PHP-Zahlen umgewandelt; gilt nur für mysqlnd.
  `MYSQLI_OPT_SSL_VERIFY_SERVER_CERT` | Gibt an, ob das Serverzertifikat verifiziert werden soll oder nicht.

`value`

  Der Wert für die Option

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Siehe mysqli_real_connect().

### Anmerkungen

> Hinweis:

> MySQLnd nimmt immer den Standardzeichensatz des Servers an. Dieser Zeichensatz wird während des Aufbaus der Verbindung bzw. der Authentifizierung übermittelt und danach von MySQLnd verwendet.

> Libmysqlclient verwendet als Standardzeichensatz den, der in der Datei my.cnf angegeben oder durch einen Aufruf von mysqli_options() vor dem Aufruf von mysqli_real_connect() aber nach mysqli_init() gesetzt wurde.

### Siehe auch

- mysqli_init() - Initialisiert MySQLi und liefert ein Objekt zur Verwendung mit mysqli_real_connect()
- mysqli_real_connect() - Baut eine Verbindung zu einem MySQL-Server auf

# mysqli::ping

# mysqli_ping

(PHP 5, PHP 7, PHP 8)

mysqli::ping -- mysqli_ping — Pingt eine Serververbindung an oder versucht eine neue Verbindung aufzubauen, wenn die Verbindung unterbrochen wurde

Warnung

Diese Funktion ist seit PHP 8.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

Objektorientierter Stil

#[\Deprecated]
public function mysqli::ping(): bool

Prozeduraler Stil

#[\Deprecated]
function mysqli_ping(mysqli `$mysql`): bool

Überprüft, ob die Verbindung zum Server funktioniert. Wenn sie unterbrochen wurde und die globale Option mysqli.reconnect aktiviert ist, wird automatisch versucht, eine neue Verbindung herzustellen.

> Hinweis: Die php.ini-Einstellung mysqli.reconnect wird vom mysqlnd-Treiber ignoriert, so dass nie automatisch versucht wird, eine neue Verbindung herzustellen.

Diese Funktion kann von Clients verwendet werden, die längere Zeit untätig sind, um zu überprüfen, ob der Server die Verbindung getrennt hat, und sich gegebenenfalls neu zu verbinden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Sowohl mysqli::ping() als auch mysqli_ping() sind nun veraltet. Die Funktionalität `reconnect` ist seit PHP 8.2.0 nicht mehr verfügbar, wodurch diese Funktion überflüssig wurde.

### Beispiele

Beispiel #1 mysqli::ping()-Beispiel

Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if ($mysqli->connect_errno) {
        printf("Verbindung fehlgeschlagen: %s\n", $mysqli->connect_error);
        exit();
    }

    /* Überprüfen, ob der Server läuft */
    if ($mysqli->ping()) {
        printf ("Unsere Verbindung ist OK!\n");
    } else {
        printf ("Fehler: %s\n", $mysqli->error);
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    /* Überprüfen, ob der Server läuft */
    if (mysqli_ping($link)) {
        printf ("Unsere Verbindung ist OK!\n");
    } else {
        printf ("Fehler: %s\n", mysqli_error($link));
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Unsere Verbindung ist OK!

# mysqli::poll

# mysqli_poll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::poll -- mysqli_poll — Überprüft den Status von Verbindungen

### Beschreibung

Objektorientierter Stil

public static function mysqli::poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Prozeduraler Stil

function mysqli_poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

Überprüft den Status von Verbindungen. Diese Methode kann als statische Methode verwendet werden.

> Hinweis:

> Nur in mysqlnd verfügbar.

### Parameter-Liste

`read`

  Eine Liste der Verbindungen, die auf ausstehende Ergebnisse geprüft werden sollen, die gelesen werden können.

`error`

  Eine Liste der Verbindungen, bei denen ein Fehler aufgetreten ist, z. B. ein Abfragefehler oder eine unterbrochene Verbindung.

`reject`

  Eine Liste der Verbindungen, die abgelehnt wurden, weil keine asynchrone Abfrage durchgeführt wurde, für die die Funktion Ergebnisse abfragen könnte.

`seconds`

  Die Maximale Anzahl von Sekunden, die gewartet werden soll; muss nicht-negativ sein.

`microseconds`

  Die Maximale Anzahl von Mikrosekunden, die gewartet werden soll; muss nicht-negativ sein.

### Rückgabewerte

Gibt bei Erfolg die Anzahl der verfügbaren Verbindungen zurück, andernfalls `false`.

### Fehler/Exceptions

Wenn weder `read` noch `error` übergeben wird, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wenn weder `read` noch `error` übergeben wird, wird nun eine ValueError-Exception geworfen.

### Beispiele

Beispiel #1 mysqli_poll()-Beispiel

    <?php
    $link1 = mysqli_connect();
    $link1->query("SELECT 'test'", MYSQLI_ASYNC);
    $all_links = array($link1);
    $processed = 0;
    do {
        $links = $errors = $reject = array();
        foreach ($all_links as $link) {
            $links[] = $errors[] = $reject[] = $link;
        }
        if (!mysqli_poll($links, $errors, $reject, 1)) {
            continue;
        }
        foreach ($links as $link) {
            if ($result = $link->reap_async_query()) {
                print_r($result->fetch_row());
                if (is_object($result))
                    mysqli_free_result($result);
            } else die(sprintf("MySQLi-Fehler: %s", mysqli_error($link)));
            $processed++;
        }
    } while ($processed < count($all_links));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => test
    )

### Siehe auch

- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_reap_async_query() - Ruft das Ergebnis einer asynchronen Abfrage ab

# mysqli::prepare

# mysqli_prepare

(PHP 5, PHP 7, PHP 8)

mysqli::prepare -- mysqli_prepare — Bereitet eine SQL-Anweisung zur Ausführung vor

### Beschreibung

Objektorientierter Stil

public function mysqli::prepare(string `$query`): mysqli_stmt|false

Prozeduraler Stil

function mysqli_prepare(mysqli `$mysql`, string `$query`): mysqli_stmt|false

Bereitet eine SQL-Abfrage vor und gibt einen Zeiger auf die Anweisung zurück, der für weitere Operationen mit der Anweisung verwendet werden kann. Die Abfrage muss aus einer einzigen SQL-Anweisung bestehen.

Die Anweisungsvorlage darf null oder mehr Fragezeichen-Parametermarker (`?`) - auch Platzhalter genannt - enthalten. Diese Parametermarker müssen vor der Ausführung der Anweisung mittels mysqli_stmt_bind_param() an Anwendungsvariablen gebunden werden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`query`

  Die Zeichenkette mit der Abfrage. Sie darf nur eine SQL-Anweisung enthalten.

  Die SQL-Anweisung darf null oder mehr Platzhalter für Parameter enthalten, die an den entsprechenden Stellen durch Fragezeichen (`?`) dargestellt werden.

  > Hinweis:

  > Die Platzhalter sind nur an bestimmten Stellen einer SQL-Anweisung zulässig. Zum Beispiel sind sie bei einer `INSERT`-Anweisung in der `VALUES()`-Liste erlaubt, um die Werte für die Spalten einer Zeile anzugeben, oder bei einer `WHERE`-Klausel im Vergleich mit einer Spalte, um einen Vergleichswert anzugeben. Nicht zulässig sind sie hingegen für Bezeichner (wie Tabellen- oder Spaltennamen).

### Rückgabewerte

mysqli_prepare() gibt ein Anweisungs-Objekt zurück oder `false`, wenn ein Fehler aufgetreten ist.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 mysqli::prepare()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* vorbereitete Anweisung erstellen */
    $stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?");

    /* Parameter für die Platzhalter binden */
    $stmt->bind_param("s", $city);

    /* Anfrage ausführen */
    $stmt->execute();

    /* Ergebnisvariablen binden */
    $stmt->bind_result($district);

    /* Wert abrufen */
    $stmt->fetch();

    printf("%s liegt im Bezirk %s\n", $city, $district);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* vorbereitete Anweisung erstellen */
    $stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?");

    /* Parameter für die Platzhalter binden */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* Anfrage ausführen */
    mysqli_stmt_execute($stmt);

    /* Ergebnisvariablen binden */
    mysqli_stmt_bind_result($stmt, $district);

    /* Wert abrufen */
    mysqli_stmt_fetch($stmt);

    printf("%s liegt im Bezirk %s\n", $city, $district);

Die obigen Bespiele erzeugen folgende Ausgabe:

    Amersfoort liegt im Bezirk Utrecht

### Siehe auch

- mysqli_stmt_execute() - Führt eine vorbereitete Anweisung aus
- mysqli_stmt_fetch() - Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab
- mysqli_stmt_bind_param() - Bindet Variablen als Parameter an eine vorbereitete Anweisung (prepared statement)
- mysqli_stmt_bind_result() - Bindet Variablen an eine vorbereitete Anweisung (prepared statement), um das Ergebnis einer Abfrage abzulegen
- mysqli_stmt_get_result() - Ruft die Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab
- mysqli_stmt_close() - Schließt eine vorbereitete Anweisung (prepared statement)

# mysqli::query

# mysqli_query

(PHP 5, PHP 7, PHP 8)

mysqli::query -- mysqli_query — Führt eine Abfrage in einer Datenbank durch

### Beschreibung

Objektorientierter Stil

public function mysqli::query(string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Prozeduraler Stil

function mysqli_query(mysqli `$mysql`, string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

Führt in einer Datenbank die Abfrage `query` durch.

Warnung

# Sicherheitswarnung: SQL-Injection

Wenn die Abfrage irgendwelche Eingabevariablen enthält, sollten stattdessen parametrisierte Prepared Statements verwendet werden. Alternativ dazu müssen die Daten korrekt formatiert sein und alle Strings müssen mit der Funktion mysqli_real_escape_string() maskiert werden.

Bei Nicht-DML-Abfragen (nicht INSERT, UPDATE oder DELETE) ist diese Funktion vergleichbar mit dem Aufruf von mysqli_real_query(), gefolgt entweder von mysqli_use_result() oder mysqli_store_result().

> Hinweis:

> Wenn eine Anweisung an mysqli_query() übergeben wird, die größer ist als die vom Server maximal erlaubte Paketgröße (`max_allowed_packet`), hängen die zurückgegebenen Fehlercodes davon ab, ob der MySQL Native Driver (`mysqlnd`) oder die MySQL Client Library (`libmysqlclient`) verwendet wird. Die Funktion verhält sich wie folgt:

> - `mysqlnd` gibt unter Linux den Fehlercode 1153 zurück. Diese Fehlermeldung bedeutet got a packet bigger than `max_allowed_packet` bytes.

> - `mysqlnd` gibt unter Windows den Fehlercode 2006 zurück. Diese Fehlermeldung bedeutet server has gone away.

> - `libmysqlclient` gibt auf allen Plattformen den Fehlercode 2006 zurück. Diese Fehlermeldung bedeutet server has gone away.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`query`

  Die Zeichenkette für die Abfrage

`result_mode`

  Der Ergebnismodus kann eine von 3 Konstanten sein, die bestimmen, wie das Ergebnis vom MySQL-Server zurückgegeben werden soll.

  `MYSQLI_STORE_RESULT` (Standard) - gibt ein mysqli_result-Objekt mit gepufferter Ergebnismenge zurück.

  `MYSQLI_USE_RESULT` - gibt ein mysqli_result-Objekt mit ungepufferter Ergebnismenge zurück. Solange es noch Datensätze gibt, die darauf warten, abgerufen zu werden, ist die Verbindung belegt und alle nachfolgenden Aufrufe geben den Fehler `Commands out of sync` zurück. Um den Fehler zu vermeiden, müssen alle Datensätze vom Server abgeholt werden oder die Ergebnismenge muss durch den Aufruf von mysqli_free_result() verworfen werden.

  `MYSQLI_ASYNC` (verfügbar mit mysqlnd) - die Abfrage wird asynchron ausgeführt und die Ergebnismenge wird nicht sofort zurückgegeben. Um die Ergebnisse solcher Abfragen zu erhalten, wird dann die Funktion mysqli_poll() benutzt. Dies wird in Kombination mit einer der Konstanten `MYSQLI_STORE_RESULT` oder `MYSQLI_USE_RESULT` verwendet.

### Rückgabewerte

Gibt bei einem Fehler `false` zurück. Bei erfolgreichen Abfragen, die eine Ergebnismenge erzeugen, also z. B. `SELECT, SHOW, DESCRIBE` oder `EXPLAIN`, gibt mysqli_query() ein mysqli_result-Objekt zurück. Bei anderen erfolgreichen Abfragen gibt mysqli_query() `true` zurück.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 mysqli::query()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Erstellen einer Tabelle gibt keine Ergebnismenge zurück */
    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Tabelle myCity erfolgreich erstellt.\n");

    /* Select-Abfragen geben eine Ergebnismenge zurück */
    $result = $mysqli->query("SELECT Name FROM City LIMIT 10");
    printf("Select gab %d Zeilen zurück.\n", $result->num_rows);

    /* Um große Datenmengen abzurufen, verwenden wir MYSQLI_USE_RESULT */
    $result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Hinweis: Solange nicht alle Datensätze vollständig abgerufen wurden oder
      die Ergebnismenge geschlossen wurde, können keine Funktionen ausgeführt
      werden, die mit dem Server interagieren. Alle Aufrufe werden einen
      'out of sync'-Fehler zurückgeben */
    $mysqli->query("SET @a:='this will not work'");

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Erstellen einer Tabelle gibt keine Ergebnismenge zurück */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
    printf("Tabelle myCity erfolgreich erstellt.\n");

    /* Select-Abfragen geben eine Ergebnismenge zurück */
    $result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
    printf("Select gab %d Zeilen zurück.\n", mysqli_num_rows($result));

    /* Um große Datenmengen abzurufen, verwenden wir MYSQLI_USE_RESULT */
    $result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);

    /* Hinweis: Solange nicht alle Datensätze vollständig abgerufen wurden oder
      die Ergebnismenge geschlossen wurde, können keine Funktionen ausgeführt
      werden, die mit dem Server interagieren. Alle Aufrufe werden einen
      'out of sync'-Fehler zurückgeben */
    mysqli_query($link, "SET @a:='this will not work'");

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Tabelle myCity erfolgreich erstellt.
    Select gab 10 Zeilen zurück.

    Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in...

### Siehe auch

- mysqli_execute_query() - Bereitet eine SQL-Anweisung vor, bindet die Parameter und führt die Anweisung aus
- mysqli_real_query() - Führt eine SQL-Abfrage aus
- mysqli_multi_query() - Führt eine oder mehrere Abfragen in einer Datenbank durch
- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_free_result() - Gibt den mit einem Ergebnis verbundenen Speicher frei

# mysqli::real_connect

# mysqli_real_connect

(PHP 5, PHP 7, PHP 8)

mysqli::real_connect -- mysqli_real_connect — Baut eine Verbindung zu einem MySQL-Server auf

### Beschreibung

Objektorientierter Stil

public function mysqli::real_connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

Prozeduraler Stil

function mysqli_real_connect(
mysqli `$mysql`,
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter]?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`,
int `$flags` = 0
): bool

Baut eine Verbindung zu einer MySQL-Datenbank auf.

Diese Funktion unterscheidet sich von der Funktion mysqli_connect():

- mysqli_real_connect() benötigt ein gültiges Objekt, das mit der Funktion mysqli_init() erstellt werden muss.

- Mit der Funktion mysqli_options() können verschiedene Optionen für die Verbindung eingestellt werden.

- Es gibt den Parameter `flags`.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`hostname`

  Kann entweder ein Hostname oder eine IP-Adresse sein. Wenn diesem Parameter der Wert `null` übergeben wird, wird der Wert von mysqli.default_host ü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, z. B. `localhost:3308`.

`username`

  Der MySQL-Benutzername oder `null`, um den Benutzernamen aus der INI-Option mysqli.default_user zu übernehmen.

`password`

  Das MySQL-Passwort oder `null`, um den Benutzernamen aus der INI-Option mysqli.default_pw zu übernehmen.

`database`

  Die Datenbank, die standardmäßig bei Abfragen verwendet werden soll, oder `null`.

`port`

  Die Portnummer, über die versucht wird, eine Verbindung mit dem MySQL-Server herzustellen, oder `null`, um den Port aus der INI-Option mysqli.default_port zu übernehmen.

`socket`

  Der Socket oder die benannte Pipe an, der/die verwendet werden soll, oder `null`, um den Socket aus der INI-Option mysqli.default_socket zu übernehmen.

  > Hinweis:

  > Mit dem Parameter `socket` 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 `hostname` bestimmt.

`flags`

  Mit dem Parameter `flags` können verschiedene Verbindungsoptionen eingestellt werden:

  Unterstützte Flags
  Name | Beschreibung
  --- | ---
  `MYSQLI_CLIENT_COMPRESS` | Das Komprimierungsprotokoll verwenden
  `MYSQLI_CLIENT_FOUND_ROWS` | Die Anzahl der übereinstimmenden Zeilen zurückgeben, nicht die Anzahl der betroffenen Zeilen
  `MYSQLI_CLIENT_IGNORE_SPACE` | Leerzeichen nach Funktionsnamen zulassen; macht alle Funktionsnamen zu reservierten Wörtern
  `MYSQLI_CLIENT_INTERACTIVE` | `interactive_timeout` Sekunden der Inaktivität zulassen, bevor die Verbindung getrennt wird (anstelle von `wait_timeout` Sekunden)
  `MYSQLI_CLIENT_SSL` | SSL verwenden (Verschlüsselung)
  `MYSQLI_CLIENT_SSL_DONT_VERIFY_SERVER_CERT` | Wie `MYSQLI_CLIENT_SSL`, deaktiviert aber die Überprüfung des übergebenen SSL-Zertifikats; gilt nur für Installationen, die den MySQL Native Driver und MySQL 5.6 oder höher verwenden.

  > Hinweis:

  > Aus Sicherheitsgründen wird das Flag `MULTI_STATEMENT` von PHP nicht unterstützt. Wenn mehrere Abfragen ausgeführt werden sollen, muss die Funktion mysqli_multi_query() verwendet werden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Alle Parameter sind nun nullable (akzeptieren den `null`-Wert).

### Beispiele

Beispiel #1 mysqli::real_connect()-Beispiel

Objektorientierter Stil

    <?php

    $mysqli = mysqli_init();
    if (!$mysqli) {
        die('mysqli_init ist fehlgeschlagen');
    }

    if (!$mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
        die('Setzen von MYSQLI_INIT_COMMAND ist fehlgeschlagen');
    }

    if (!$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
        die('Setzen von MYSQLI_OPT_CONNECT_TIMEOUT ist fehlgeschlagen');
    }

    if (!$mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db')) {
        die('Verbindungsfehler (' . mysqli_connect_errno() . ') '
                . mysqli_connect_error());
    }

    echo 'Erfolg... ' . $mysqli->host_info . "\n";

    $mysqli->close();
    ?>

Objektorientierter Stil, wenn die Klasse mysqli erweitert wird

    <?php

    class foo_mysqli extends mysqli {
        public function __construct($host, $user, $pass, $db) {
            parent::__construct();

            if (!parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
                die('Setzen von MYSQLI_INIT_COMMAND ist fehlgeschlagen');
            }

            if (!parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
                die('Setzen von MYSQLI_OPT_CONNECT_TIMEOUT ist fehlgeschlagen');
            }

            if (!parent::real_connect($host, $user, $pass, $db)) {
                die('Verbindungsfehler (' . mysqli_connect_errno() . ') '
                        . mysqli_connect_error());
            }
        }
    }

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

    echo 'Erfolg... ' . $db->host_info . "\n";

    $db->close();
    ?>

Prozeduraler Stil

    <?php

    $link = mysqli_init();
    if (!$link) {
        die('mysqli_init ist fehlgeschlagen');
    }

    if (!mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0')) {
        die('Setzen von MYSQLI_INIT_COMMAND ist fehlgeschlagen');
    }

    if (!mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5)) {
        die('Setzen von MYSQLI_OPT_CONNECT_TIMEOUT ist fehlgeschlagen');
    }

    if (!mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db')) {
        die('Verbindungsfehler (' . mysqli_connect_errno() . ') '
                . mysqli_connect_error());
    }

    echo 'Erfolg... ' . mysqli_get_host_info($link) . "\n";

    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Erfolg... MySQL host info: localhost via TCP/IP

### Anmerkungen

> Hinweis:

> MySQLnd nimmt immer den Standardzeichensatz des Servers an. Dieser Zeichensatz wird während des Aufbaus der Verbindung bzw. der Authentifizierung übermittelt und danach von MySQLnd verwendet.

> Libmysqlclient verwendet als Standardzeichensatz den, der in der Datei my.cnf angegeben oder durch einen Aufruf von mysqli_options() vor dem Aufruf von mysqli_real_connect() aber nach mysqli_init() gesetzt wurde.

### Siehe auch

- mysqli_connect() - Alias von mysqli::__construct
- mysqli_init() - Initialisiert MySQLi und liefert ein Objekt zur Verwendung mit mysqli_real_connect()
- mysqli_options() - Setzt Optionen
- mysqli_ssl_set() - Wird beim Aufbau sicherer Verbindungen mit SSL verwendet
- mysqli_close() - Schließt die zuvor geöffnete Datenbankverbindung

# mysqli::real_escape_string

# mysqli_real_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::real_escape_string -- mysqli_real_escape_string — Maskiert Sonderzeichen in einer Zeichenkette zur Verwendung in einer SQL-Anweisung, wobei der aktuelle Zeichensatz der Verbindung berücksichtigt wird

### Beschreibung

Objektorientierter Stil

public function mysqli::real_escape_string(string `$string`): string

Prozeduraler Stil

function mysqli_real_escape_string(mysqli `$mysql`, string `$string`): string

Diese Funktion wird verwendet, um eine zulässige SQL-Zeichenkette zu erstellen, die in einer SQL-Anweisung verwendet werden kann. Die angegebene Zeichenkette wird kodiert, um eine maskierte SQL-Zeichenkette zu erzeugen, wobei der aktuelle Zeichensatz der Verbindung zugrunde gelegt wird.

Achtung

# Sicherheit: Der Standardzeichensatz

Damit sich der Zeichensatz auf mysqli_real_escape_string() auswirkt, muss er entweder auf der Server-Ebene oder mit der API-Funktion mysqli_set_charset() gesetzt werden. Weitere Informationen zu Zeichensätzen sind im Abschnitt Konzepte zu finden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`string`

  Die Zeichenkette, die maskiert werden soll

  Folgende Zeichen werden kodiert: `NUL` (ASCII 0), `\n`, `\r`, `\`, `'`, `"` und ``CTRL`+`Z``.

### Rückgabewerte

Gibt eine maskierte Zeichenkette zurück.

### Beispiele

Beispiel #1 mysqli::real_escape_string()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* diese Abfrage mit maskiertem $city funktioniert */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        $mysqli->real_escape_string($city));
    $result = $mysqli->query($query);
    printf("Select gab %d Zeilen zurück.\n", $result->num_rows);

    /* diese Abfrage schlägt fehl, weil wir $city nicht maskiert haben */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = $mysqli->query($query);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "'s-Hertogenbosch";

    /* diese Abfrage mit maskiertem $city funktioniert */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'",
        mysqli_real_escape_string($mysqli, $city));
    $result = mysqli_query($mysqli, $query);
    printf("Select gab %d Zeilen zurück.\n", mysqli_num_rows($result));

    /* diese Abfrage schlägt fehl, weil wir $city nicht maskiert haben */
    $query = sprintf("SELECT CountryCode FROM City WHERE name='%s'", $city);
    $result = mysqli_query($mysqli, $query);

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Select gab 1 Zeilen zurück.

    Fatal error: Uncaught mysqli_sql_exception: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 's-Hertogenbosch'' at line 1 in...

### Siehe auch

- mysqli_set_charset() - Legt den Standard-Zeichensatz des Clients fest

# mysqli::real_query

# mysqli_real_query

(PHP 5, PHP 7, PHP 8)

mysqli::real_query -- mysqli_real_query — Führt eine SQL-Abfrage aus

### Beschreibung

Objektorientierter Stil

public function mysqli::real_query(string `$query`): bool

Prozeduraler Stil

function mysqli_real_query(mysqli `$mysql`, string `$query`): bool

Führt eine einzelne Abfrage in der Datenbank aus, deren Ergebnis dann mit den Funktionen mysqli_store_result() oder mysqli_use_result() abgerufen oder gespeichert werden kann.

Warnung

# Sicherheitswarnung: SQL-Injection

Wenn die Abfrage irgendwelche Eingabevariablen enthält, sollten stattdessen parametrisierte Prepared Statements verwendet werden. Alternativ dazu müssen die Daten korrekt formatiert sein und alle Strings müssen mit der Funktion mysqli_real_escape_string() maskiert werden.

Um festzustellen, ob von einer bestimmten Abfrage eine Ergebnismenge zu erwarten ist oder nicht, siehe mysqli_field_count().

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`query`

  Die Zeichenkette für die Abfrage

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Siehe auch

- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_store_result() - Überträgt die Ergebnismenge der letzten Abfrage
- mysqli_use_result() - Initiiert den Abruf einer Ergebnismenge

# mysqli::reap_async_query

# mysqli_reap_async_query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::reap_async_query -- mysqli_reap_async_query — Ruft das Ergebnis einer asynchronen Abfrage ab

### Beschreibung

Objektorientierter Stil

public function mysqli::reap_async_query(): mysqli_result|bool

Prozeduraler Stil

function mysqli_reap_async_query(mysqli `$mysql`): mysqli_result|bool

Ruft das Ergebnis einer asynchronen Abfrage ab.

> Hinweis:

> Nur in mysqlnd verfügbar.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt bei einem Fehler `false` zurück. Bei erfolgreichen Abfragen, die eine Ergebnismenge erzeugen, also z. B. `SELECT, SHOW, DESCRIBE` oder `EXPLAIN`, gibt mysqli_reap_async_query() ein mysqli_result-Objekt zurück. Bei anderen erfolgreichen Abfragen gibt mysqli_reap_async_query() `true` zurück.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Siehe auch

- mysqli_poll() - Überprüft den Status von Verbindungen

# mysqli::refresh

# mysqli_refresh

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::refresh -- mysqli_refresh — Führt ein Refresh durch

Warnung

Diese Funktion ist seit PHP 8.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

Objektorientierter Stil

#[\Deprecated]
public function mysqli::refresh(int `$flags`): bool

Prozeduraler Stil

#[\Deprecated]
function mysqli_refresh(mysqli `$mysql`, int `$flags`): bool

Aktualisiert Tabellen oder leert Caches oder setzt die Informationen des Replikationsservers zurück.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`flags`

  Die Optionen für das Refresh werden durch die MYSQLI_REFRESH_*-Konstanten festgelegt, die in der Dokumentation zu den MySQLi-Konstanten beschrieben sind.

  Siehe auch die offizielle Dokumentation zu » MySQL Refresh.

### Rückgabewerte

Gibt `true` zurück, wenn das Refresh erfolgreich war, ansonsten `false`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Sowohl mysqli::refresh() als auch mysqli_refresh() sind nun veraltet. Stattdessen sollte der SQL-Befehl `FLUSH` verwendet werden.

### Siehe auch

- mysqli_poll() - Überprüft den Status von Verbindungen

# mysqli::release_savepoint

# mysqli_release_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::release_savepoint -- mysqli_release_savepoint — Entfernt einen benannten Sicherungspunkt aus der Menge der Sicherungspunkte der aktuellen Transaktion

### Beschreibung

Objektorientierter Stil

public function mysqli::release_savepoint(string `$name`): bool

Prozeduraler Stil:

function mysqli_release_savepoint(mysqli `$mysql`, string `$name`): bool

Diese Funktion entspricht der Ausführung von `$mysqli->query("RELEASE SAVEPOINT `$name`");`. Durch diese Funktion wird kein Commit oder Rollback ausgelöst.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`name`

  Der Bezeichner des Sicherungspunkts

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- mysqli_savepoint() - Sezt einen benannten Sicherungspunkt für eine Transaktion

# mysqli::rollback

# mysqli_rollback

(PHP 5, PHP 7, PHP 8)

mysqli::rollback -- mysqli_rollback — Macht die aktuelle Transaktion rückgängig

### Beschreibung

Objektorientierter Stil

public function mysqli::rollback(int `$flags` = 0, ?string `$name` = `null`): bool

Prozeduraler Stil

function mysqli_rollback(mysqli `$mysql`, int `$flags` = 0, ?string `$name` = `null`): bool

Macht die aktuelle Transaktion für die Datenbank rückgängig.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`flags`

  Eine Bitmaske von `MYSQLI_TRANS_COR_*`-Konstanten

`name`

  Falls angegeben, wird `ROLLBACK/*name*/` ausgeführt

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `name` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Siehe das mysqli::begin_transaction()-Beispiel.

### Anmerkungen

> Hinweis:

> Diese Funktion funktioniert nicht mit Tabellentypen, die keine Transaktionen unterstützen (wie MyISAM oder ISAM).

### Siehe auch

- mysqli_begin_transaction() - Startet eine Transaktion
- mysqli_commit() - Bestätigt die aktuelle Transaktion
- mysqli_autocommit() - Aktiviert oder deaktiviert das automatische Bestätigen von Datenbankänderungen
- mysqli_release_savepoint() - Entfernt einen benannten Sicherungspunkt aus der Menge der Sicherungspunkte der aktuellen Transaktion

# mysqli::savepoint

# mysqli_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::savepoint -- mysqli_savepoint — Sezt einen benannten Sicherungspunkt für eine Transaktion

### Beschreibung

Objektorientierter Stil

public function mysqli::savepoint(string `$name`): bool

Prozeduraler Stil:

function mysqli_savepoint(mysqli `$mysql`, string `$name`): bool

Diese Funktion entspricht der Ausführung von `$mysqli->query("SAVEPOINT `$name`");`

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`name`

  Der Bezeichner des Sicherungspunkts

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- mysqli_release_savepoint() - Entfernt einen benannten Sicherungspunkt aus der Menge der Sicherungspunkte der aktuellen Transaktion

# mysqli::select_db

# mysqli_select_db

(PHP 5, PHP 7, PHP 8)

mysqli::select_db -- mysqli_select_db — Legt die standardmäßige Datenbank für Datenbankabfragen fest

### Beschreibung

Objektorientierter Stil

public function mysqli::select_db(string `$database`): bool

Prozeduraler Stil

function mysqli_select_db(mysqli `$mysql`, string `$database`): bool

Wählt die Datenbank aus, die standardmäßig bei Abfragen über die Datenbankverbindung verwendet werden soll.

> Hinweis:

> Diese Funktion sollte nur verwendet werden, um die Standard-Datenbank für die Verbindung zu ändern. Die Standard-Datenbank kann mit dem 4. Parameter in mysqli_connect() ausgewählt werden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`database`

  Der Name der Datenbank

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 mysqli::select_db()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    /* Ermitteln des Namens der aktuellen Standard-Datenbank */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Die Standard-Datenbank ist %s.\n", $row[0]);

    /* Standard-Datenbank auf "world" ändern */
    $mysqli->select_db("world");

    /* Ermitteln des Namens der aktuellen Standard-Datenbank */
    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Die Standard-Datenbank ist %s.\n", $row[0]);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    /* Ermitteln des Namens der aktuellen Standard-Datenbank */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("Die Standard-Datenbank ist %s.\n", $row[0]);

    /* Standard-Datenbank auf "world" ändern */
    mysqli_select_db($link, "world");

    /* Ermitteln des Namens der aktuellen Standard-Datenbank */
    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("Die Standard-Datenbank ist %s.\n", $row[0]);

Die obigen Bespiele erzeugen folgende Ausgabe:

    Die Standard-Datenbank ist test.
    Die Standard-Datenbank ist world.

### Siehe auch

- mysqli_connect() - Alias von mysqli::__construct
- mysqli_real_connect() - Baut eine Verbindung zu einem MySQL-Server auf

# mysqli::set_charset

# mysqli_set_charset

(PHP 5 >= 5.0.5, PHP 7, PHP 8)

mysqli::set_charset -- mysqli_set_charset — Legt den Standard-Zeichensatz des Clients fest

### Beschreibung

Objektorientierter Stil

public function mysqli::set_charset(string `$charset`): bool

Prozeduraler Stil

function mysqli_set_charset(mysqli `$mysql`, string `$charset`): bool

Legt den Zeichensatz fest, der verwendet werden soll, wenn Daten vom und zum Datenbankserver gesendet werden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`charset`

  Der gewünschte Zeichensatz

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 mysqli::set_charset()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    printf("Ursprünglicher Zeichensatz: %s\n", $mysqli->character_set_name());

    /* Zeichensatz auf utf8mb4 ändern */
    $mysqli->set_charset("utf8mb4");

    printf("Aktueller Zeichensatz: %s\n", $mysqli->character_set_name());

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'test');

    printf("Ursprünglicher Zeichensatz: %s\n", mysqli_character_set_name($link));

    /* Zeichensatz auf utf8mb4 ändern */
    mysqli_set_charset($link, "utf8mb4");

    printf("Aktueller Zeichensatz: %s\n", mysqli_character_set_name($link));

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Ursprünglicher Zeichensatz: latin1
    Aktueller Zeichensatz: utf8mb4

### Anmerkungen

> Hinweis:

> Dies ist die bevorzugte Methode, um den Zeichensatz zu ändern. Es ist nicht empfehlenswert, mysqli_query() zu verwenden, um ihn zu setzen (z. B. mit `SET NAMES utf8`). Siehe den Abschnitt Konzepte für MySQL-Zeichensätze für weitere Informationen.

### Siehe auch

- mysqli_character_set_name() - Liefert den aktuellen Zeichensatz der Datenbankverbindung
- mysqli_real_escape_string() - Maskiert Sonderzeichen in einer Zeichenkette zur Verwendung in einer SQL-Anweisung, wobei der aktuelle Zeichensatz der Verbindung berücksichtigt wird
- Konzepte für MySQL-Zeichensätze
- » Liste der Zeichensätze, die MySQL unterstützt

# mysqli::$sqlstate

# mysqli_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli::$sqlstate -- mysqli_sqlstate — Liefert den SQLSTATE-Fehler der letzten MySQL-Operation

### Beschreibung

Objektorientierter Stil

string $mysqli->sqlstate;

Prozeduraler Stil

function mysqli_sqlstate(mysqli `$mysql`): string

Gibt eine Zeichenkette zurück, die den SQLSTATE-Fehlercode für den letzten Fehler enthält. Der Fehlercode besteht aus fünf Zeichen. `'00000'` bedeutet, dass kein Fehler aufgetreten ist. Die Werte werden durch ANSI-SQL und ODBC festgelegt. Eine Liste der möglichen Werte ist unter » http://dev.mysql.com/doc/mysql/en/error-handling.html zu finden.

> Hinweis:

> Es ist zu beachten, dass noch nicht alle MySQL-Fehler zu SQLSTATEs zugeordnet sind. Für Fehler, die noch nicht zugeordnet sind, wird der Wert `HY000` (allgemeiner Fehler) verwendet.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die den SQLSTATE-Fehlercode für den letzten Fehler enthält. Der Fehlercode besteht aus fünf Zeichen. `'00000'` bedeutet, dass kein Fehler aufgetreten ist.

### Beispiele

Beispiel #1 $mysqli->sqlstate-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Da die Tabelle City bereits existiert, sollte ein Fehler auftreten */
    try {
        $mysqli->query("CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Fehler - SQLSTATE %s.\n", $mysqli->sqlstate);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Da die Tabelle City bereits existiert, sollte ein Fehler auftreten */
    try {
        mysqli_query($link, "CREATE TABLE City (ID INT, Name VARCHAR(30))");
    } catch (mysqli_sql_exception) {
        printf("Fehler - SQLSTATE %s.\n", mysqli_sqlstate($link));
    }

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehler - SQLSTATE 42S01.

### Siehe auch

- mysqli_errno() - Liefert den Fehlercode des letzten Funktionsaufrufs
- mysqli_error() - Liefert eine Zeichenkette, die den letzten Fehler beschreibt

# mysqli::ssl_set

# mysqli_ssl_set

(PHP 5, PHP 7, PHP 8)

mysqli::ssl_set -- mysqli_ssl_set — Wird beim Aufbau sicherer Verbindungen mit SSL verwendet

### Beschreibung

Objektorientierter Stil

public function mysqli::ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Prozeduraler Stil

function mysqli_ssl_set(
mysqli `$mysql`,
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

Wird beim Aufbau sicherer Verbindungen mit SSL verwendet. Diese Funktion muss vor mysqli_real_connect() aufgerufen werden. Wenn die Unterstützung von OpenSSL nicht aktiviert ist, bewirkt diese Funktion nichts.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`key`

  Pfad und Name der Schlüsseldatei

`certificate`

  Pfad und Name der Zertifikatsdatei

`ca_certificate`

  Pfad und Name der Datei der Zertifizierungsstelle

`ca_path`

  Der Pfad zum Verzeichnis, das vertrauenswürdige SSL-CA-Zertifikate im PEM-Format enthält

`cipher_algos`

  Eine Liste der zulässigen Verschlüsselungsmethoden, die für die SSL-Verschlüsselung verwendet werden können

### Rückgabewerte

Gibt immer `true` zurück. Wenn die SSL-Einstellungen nicht korrekt sind, gibt mysqli_real_connect() beim Versuch, eine Verbindung aufzubauen, einen Fehler zurück.

### Siehe auch

- mysqli_options() - Setzt Optionen
- mysqli_real_connect() - Baut eine Verbindung zu einem MySQL-Server auf

# mysqli::stat

# mysqli_stat

(PHP 5, PHP 7, PHP 8)

mysqli::stat -- mysqli_stat — Liefert den aktuellen Systemstatus

### Beschreibung

Objektorientierter Stil

public function mysqli::stat(): string|false

Prozeduraler Stil

function mysqli_stat(mysqli `$mysql`): string|false

mysqli_stat() gibt eine Zeichenkette zurück, welche ähnliche Informationen enthält, wie sie der Befehl 'mysqladmin status' liefert. Das beinhaltet die Uptime in Sekunden, die Anzahl der laufenden Prozesse, Anfragen, Reloads und geöffnete Tabellen.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Eine Zeichenkette, die den Status des Servers enthält. Im Fehlerfall `false`.

### Beispiele

Beispiel #1 mysqli::stat()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    printf("Systemstatus: %s\n", $mysqli->stat());

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    printf("Systemstatus: %s\n", mysqli_stat($link));

Die obigen Bespiele erzeugen folgende Ausgabe:

    Systemstatus: Uptime: 272  Threads: 1  Questions: 5340  Slow queries: 0
    Opens: 13  Flush tables: 1  Open tables: 0  Queries per second avg: 19.632
    Memory in use: 8496K  Max memory used: 8560K

### Siehe auch

- mysqli_get_server_info() - Liefert die Version des MySQL-Servers

# mysqli::stmt_init

# mysqli_stmt_init

(PHP 5, PHP 7, PHP 8)

mysqli::stmt_init -- mysqli_stmt_init — Initialisiert eine Anweisung und liefert ein Objekt für die Verwendung mit mysqli_stmt_prepare

### Beschreibung

Objektorientierter Stil

public function mysqli::stmt_init(): mysqli_stmt|false

Prozeduraler Stil

function mysqli_stmt_init(mysqli `$mysql`): mysqli_stmt|false

Erstellt und initialisiert ein Anweisungs-Objekt, das für die Funktion mysqli_stmt_prepare() geeignet ist.

> Hinweis:

> Alle nachfolgenden Aufrufe einer mysqli_stmt-Funktion schlagen solange fehl, bis mysqli_stmt_prepare() aufgerufen wurde.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt ein Objekt zurück.

### Siehe auch

- mysqli_stmt_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor

# mysqli::store_result

# mysqli_store_result

(PHP 5, PHP 7, PHP 8)

mysqli::store_result -- mysqli_store_result — Überträgt die Ergebnismenge der letzten Abfrage

### Beschreibung

Objektorientierter Stil

public function mysqli::store_result(int `$mode` = 0): mysqli_result|false

Prozeduraler Stil

function mysqli_store_result(mysqli `$mysql`, int `$mode` = 0): mysqli_result|false

Überträgt die Ergebnismenge der letzten Abfrage über die durch `mysql` angegebene Datenbankverbindung, um sie mit der Funktion mysqli_data_seek() zu verwenden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`mode`

  Die Option, die gesetzt werden soll. Ab PHP 8.1 hat dieser Parameter keine Auswirkung mehr. Es kann einer der folgenden Werte sein:

  Gültige Optionen
  Name | Beschreibung
  --- | ---
  `MYSQLI_STORE_RESULT_COPY_DATA` | Kopiert die Ergebnisse aus dem internen mysqlnd-Puffer in die abgerufenen PHP-Variablen. Um zu vermeiden, dass im Speicher gehaltene Ergebnisse kopiert und dupliziert werden, verwendet mysqlnd standardmäßig Referenzen. In bestimmten Fällen, z. B. bei Ergebnismengen mit vielen kleinen Zeilen, kann das Kopieren den Gesamtspeicherverbrauch verringern, weil die PHP-Variablen, die Ergebnisse enthalten, früher freigegeben werden können (nur mit mysqlnd verfügbar).

### Rückgabewerte

Gibt ein gepuffertes Ergebnisobjekt zurück oder `false`, wenn ein Fehler aufgetreten ist.

> Hinweis:

> Wenn die Abfrage keine Ergebnismenge zurückgegeben hat (z. B. wenn die Abfrage eine INSERT-Anweisung war), gibt die Funktion `false` zurück. Diese Funktion gibt auch `false` zurück, wenn die Ergebnismenge nicht gelesen werden konnte. Ob ein Fehler aufgetreten ist, kann überprüft werden, indem kontrolliert wird, ob mysqli_error() eine nicht-leere Zeichenkette zurückgibt, ob mysqli_errno() einen Wert ungleich Null zurückgibt oder ob mysqli_field_count() einen Wert ungleich Null zurückgibt. Ein weiterer möglicher Grund dafür, dass diese Funktion nach einem erfolgreichen Aufruf von mysqli_query() `false` zurückgibt, kann eine zu große Ergebnismenge sein (der dafür benötigte Speicher kann nicht zugewiesen werden). Wenn mysqli_field_count() einen Wert ungleich Null zurückgibt, sollte die Anweisung eine nicht-leere Ergebnismenge erzeugt haben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Übergabe des Parameters `mode` ist nun veraltet. Der Parameter hat seit PHP 8.1.0 keine Wirkung mehr.

### Beispiele

Siehe mysqli_multi_query().

### Anmerkungen

> Hinweis:

> Obwohl es immer sinnvoll ist, den vom Ergebnis einer Abfrage belegten Speicher mit der Funktion mysqli_free_result() freizugeben, ist dies besonders wichtig, wenn große Ergebnismengen mit der Funktion mysqli_store_result() übertragen werden.

### Siehe auch

- mysqli_real_query() - Führt eine SQL-Abfrage aus
- mysqli_use_result() - Initiiert den Abruf einer Ergebnismenge

# mysqli::$thread_id

# mysqli_thread_id

(PHP 5, PHP 7, PHP 8)

mysqli::$thread_id -- mysqli_thread_id — Liefert die Thread-ID der aktuellen Verbindung

### Beschreibung

Objektorientierter Stil

int $mysqli->thread_id;

Prozeduraler Stil

function mysqli_thread_id(mysqli `$mysql`): int

Die Funktion mysqli_thread_id() gibt die Thread-ID der aktuellen Verbindung zurück, die dann mit der Funktion mysqli_kill() beendet werden kann. Wenn die Verbindung unterbrochen wird und mit mysqli_ping() wieder aufgebaut wird, ändert sich die Thread-ID. Daher sollte die Thread-ID nur abgefragt werden, wenn sie benötigt wird.

> Hinweis:

> Jede Verbindung bekommt eine eigene Thread-ID zugewiesen. Wenn also die Verbindung unterbrochen und dann wiederhergestellt wird, wird eine neue Thread-ID zugewiesen.

> Um eine laufende Abfrage zu beenden, kann der SQL-Befehl `KILL QUERY processid` verwendet werden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Gibt die Thread-ID der aktuellen Verbindung zurück.

### Beispiele

Beispiel #1 $mysqli->thread_id-Beispiel

Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    /* Thread-ID ermitteln */
    $thread_id = $mysqli->thread_id;

    /* Verbindung beenden */
    $mysqli->kill($thread_id);

    /* Dies sollte einen Fehler erzeugen */
    if (!$mysqli->query("CREATE TABLE myCity LIKE City")) {
        printf("Fehler: %s\n", $mysqli->error);
        exit;
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    /* Thread-ID ermitteln */
    $thread_id = mysqli_thread_id($link);

    /* Verbindung beenden */
    mysqli_kill($link, $thread_id);

    /* Dies sollte einen Fehler erzeugen */
    if (!mysqli_query($link, "CREATE TABLE myCity LIKE City")) {
        printf("Fehler: %s\n", mysqli_error($link));
        exit;
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehler: MySQL server has gone away

### Siehe auch

- mysqli_kill() - Weist den Server an, einen MySQL-Thread zu beenden

# mysqli::thread_safe

# mysqli_thread_safe

(PHP 5, PHP 7, PHP 8)

mysqli::thread_safe -- mysqli_thread_safe — Gibt an, ob Thread-Sicherheit gegeben ist oder nicht

### Beschreibung

Objektorientierter Stil

public function mysqli::thread_safe(): bool

Prozeduraler Stil

function mysqli_thread_safe(): bool

Gibt an, ob die Client-Bibliothek als threadsicher kompiliert ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn die Client-Bibliothek threadsicher ist, ansonsten `false`.

# mysqli::use_result

# mysqli_use_result

(PHP 5, PHP 7, PHP 8)

mysqli::use_result -- mysqli_use_result — Initiiert den Abruf einer Ergebnismenge

### Beschreibung

Objektorientierter Stil

public function mysqli::use_result(): mysqli_result|false

Prozeduraler Stil

function mysqli_use_result(mysqli `$mysql`): mysqli_result|false

Wird verwendet, um die Ergebnismenge der letzten mit der Funktion mysqli_real_query() über die Datenbankverbindung ausgeführten Abfrage zur Verarbeitung vorzubereiten.

Bevor die Ergebnisse einer Abfrage abgerufen werden können, muss entweder diese Funktion oder die Funktion mysqli_store_result() aufgerufen werden. Wenn keine der beiden Funktionen aufgerufen wird, schlägt die nächste Abfrage über die Datenbankverbindung fehl.

> Hinweis:

> Die Funktion mysqli_use_result() überträgt nicht die gesamte Ergebnismenge von der Datenbank und kann daher nicht mit Funktionen wie mysqli_data_seek() verwendet werden, um zu einer bestimmten Zeile innerhalb der Menge zu gelangen. Um diese Funktionalität zu nutzen, muss die Ergebnismenge mit mysqli_store_result() gespeichert werden. mysqli_use_result() sollte nicht verwendet werden, wenn auf der Client-Seite eine umfangreiche Verarbeitung durchgeführt wird, da dies den Server blockiert und andere Threads daran hindert, die Tabellen zu aktualisieren, aus denen die Daten geholt werden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein ungepuffertes Ergebnisobjekt zurück oder `false`, wenn ein Fehler aufgetreten ist.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 mysqli::use_result()-Beispiel

Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Mehrfachabfrage ausführen */
    if ($mysqli->multi_query($query)) {
        do {
            /* erste Ergebnismenge speichern */
            if ($result = $mysqli->use_result()) {
                while ($row = $result->fetch_row()) {
                    printf("%s\n", $row[0]);
                }
                $result->close();
            }
            /* Trennlinie ausgeben */
            if ($mysqli->more_results()) {
                printf("-----------------\n");
            }
        } while ($mysqli->next_result());
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query  = "SELECT CURRENT_USER();";
    $query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

    /* Mehrfachabfrage ausführen */
    if (mysqli_multi_query($link, $query)) {
        do {
            /* erste Ergebnismenge speichern */
            if ($result = mysqli_use_result($link)) {
                while ($row = mysqli_fetch_row($result)) {
                    printf("%s\n", $row[0]);
                }
                mysqli_free_result($result);
            }
            /* Trennlinie ausgeben */
            if (mysqli_more_results($link)) {
                printf("-----------------\n");
            }
        } while (mysqli_next_result($link));
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    my_user@localhost
    -----------------
    Amersfoort
    Maastricht
    Dordrecht
    Leiden
    Haarlemmermeer

### Siehe auch

- mysqli_real_query() - Führt eine SQL-Abfrage aus
- mysqli_store_result() - Überträgt die Ergebnismenge der letzten Abfrage

# mysqli::$warning_count

# mysqli_warning_count

(PHP 5, PHP 7, PHP 8)

mysqli::$warning_count -- mysqli_warning_count — Liefert die Anzahl der Warnungen, die durch die letzte Abfrage erzeugt wurden

### Beschreibung

Objektorientierter Stil

int $mysqli->warning_count;

Prozeduraler Stil

function mysqli_warning_count(mysqli `$mysql`): int

Gibt die Anzahl der Warnungen zurück, die durch die letzte Abfrage über die angebene Verbindung erzeugt wurden.

> Hinweis: Für das Ermitteln der Warnungen kann der SQL-Befehl `SHOW WARNINGS [limit row_count]` verwendet werden.

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

### Rückgabewerte

Die Anzahl der Warnungen oder 0, falls es keine Warnungen gibt.

### Beispiele

Beispiel #1 $mysqli->warning_count-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 42/0");

    if ($mysqli->warning_count > 0) {
        $result = $mysqli->query("SHOW WARNINGS");
        $row = $result->fetch_row();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "SELECT 42/0");

    if (mysqli_warning_count($link) > 0) {
        $result = mysqli_query($link, "SHOW WARNINGS");
        $row = mysqli_fetch_row($result);
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

Die obigen Bespiele erzeugen folgende Ausgabe:

    Warning (1365): Division by 0

### Siehe auch

- mysqli_errno() - Liefert den Fehlercode des letzten Funktionsaufrufs
- mysqli_error() - Liefert eine Zeichenkette, die den letzten Fehler beschreibt
- mysqli_sqlstate() - Liefert den SQLSTATE-Fehler der letzten MySQL-Operation

## Inhaltsverzeichnis

- mysqli::$affected_rows — Liefert die Anzahl der Datensätze, die vom letzten MySQL-Vorgang betroffen waren
- mysqli::autocommit — Aktiviert oder deaktiviert das automatische Bestätigen von Datenbankänderungen
- mysqli::begin_transaction — Startet eine Transaktion
- mysqli::change_user — Ändert den Benutzer der Datenbankverbindung
- mysqli::character_set_name — Liefert den aktuellen Zeichensatz der Datenbankverbindung
- mysqli::close — Schließt die zuvor geöffnete Datenbankverbindung
- mysqli::commit — Bestätigt die aktuelle Transaktion
- mysqli::$connect_errno — Liefert den Fehlercode des letzten Verbindungsversuchs
- mysqli::$connect_error — Liefert eine Beschreibung des letzten Verbindungsfehlers
- mysqli::__construct — Baut eine neue Verbindung zum MySQL-Server auf
- mysqli::debug — Führt Debugging-Operationen durch
- mysqli::dump_debug_info — Schreibt Debugging-Informationen in die Logdatei
- mysqli::$errno — Liefert den Fehlercode des letzten Funktionsaufrufs
- mysqli::$error — Liefert eine Zeichenkette, die den letzten Fehler beschreibt
- mysqli::$error_list — Liefert eine Liste der Fehler des zuletzt ausgeführten Befehls
- mysqli::execute_query — Bereitet eine SQL-Anweisung vor, bindet die Parameter und führt die Anweisung aus
- mysqli::$field_count — Liefert die Anzahl der Spalten der letzten Abfrage
- mysqli::get_charset — Liefert ein Zeichensatz-Objekt
- mysqli::$client_info — Liefert die Version des MySQL-Clients als Zeichenkette
- mysqli::$client_version — Liefert die Version des MySQL-Clients als Integer
- mysqli::get_connection_stats — Liefert Verbindungsstatistiken des Clients
- mysqli::$host_info — Liefert eine Zeichenkette, die den Typ der verwendeten Verbindung angibt
- mysqli::$protocol_version — Liefert die Version des verwendeten MySQL-Protokolls
- mysqli::$server_info — Liefert die Version des MySQL-Servers
- mysqli::$server_version — Liefert die Version des MySQL-Servers als Integer
- mysqli::get_warnings — Ermittelt das Ergebnis von SHOW WARNINGS
- mysqli::$info — Ruft Informationen über die zuletzt ausgeführte Abfrage ab
- mysqli::init — Initialisiert MySQLi und liefert ein Objekt zur Verwendung mit mysqli_real_connect()
- mysqli::$insert_id — Liefert den Wert, der bei der letzten Anweisung für die AUTO_INCREMENT-Spalte erzeugt wurde
- mysqli::kill — Weist den Server an, einen MySQL-Thread zu beenden
- mysqli::more_results — Prüft, ob es von einer Mehrfachabfrage noch weitere Abfrageergebnisse gibt
- mysqli::multi_query — Führt eine oder mehrere Abfragen in einer Datenbank durch
- mysqli::next_result — Bereitet das nächste Ergebnis von multi_query vor
- mysqli::options — Setzt Optionen
- mysqli::ping — Pingt eine Serververbindung an oder versucht eine neue Verbindung aufzubauen, wenn die Verbindung unterbrochen wurde
- mysqli::poll — Überprüft den Status von Verbindungen
- mysqli::prepare — Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli::query — Führt eine Abfrage in einer Datenbank durch
- mysqli::real_connect — Baut eine Verbindung zu einem MySQL-Server auf
- mysqli::real_escape_string — Maskiert Sonderzeichen in einer Zeichenkette zur Verwendung in einer SQL-Anweisung, wobei der aktuelle Zeichensatz der Verbindung berücksichtigt wird
- mysqli::real_query — Führt eine SQL-Abfrage aus
- mysqli::reap_async_query — Ruft das Ergebnis einer asynchronen Abfrage ab
- mysqli::refresh — Führt ein Refresh durch
- mysqli::release_savepoint — Entfernt einen benannten Sicherungspunkt aus der Menge der Sicherungspunkte der aktuellen Transaktion
- mysqli::rollback — Macht die aktuelle Transaktion rückgängig
- mysqli::savepoint — Sezt einen benannten Sicherungspunkt für eine Transaktion
- mysqli::select_db — Legt die standardmäßige Datenbank für Datenbankabfragen fest
- mysqli::set_charset — Legt den Standard-Zeichensatz des Clients fest
- mysqli::$sqlstate — Liefert den SQLSTATE-Fehler der letzten MySQL-Operation
- mysqli::ssl_set — Wird beim Aufbau sicherer Verbindungen mit SSL verwendet
- mysqli::stat — Liefert den aktuellen Systemstatus
- mysqli::stmt_init — Initialisiert eine Anweisung und liefert ein Objekt für die Verwendung mit mysqli_stmt_prepare
- mysqli::store_result — Überträgt die Ergebnismenge der letzten Abfrage
- mysqli::$thread_id — Liefert die Thread-ID der aktuellen Verbindung
- mysqli::thread_safe — Gibt an, ob Thread-Sicherheit gegeben ist oder nicht
- mysqli::use_result — Initiiert den Abruf einer Ergebnismenge
- mysqli::$warning_count — Liefert die Anzahl der Warnungen, die durch die letzte Abfrage erzeugt wurden

# Die Klasse mysqli_stmt

(PHP 5, PHP 7, PHP 8)

## Einführung

Repräsentiert ein Prepared Statement.

## Klassenbeschreibung

class mysqli_stmt {
/* Eigenschaften */
public readonly int|string $affected_rows;
public readonly int|string $insert_id;
public readonly int|string $num_rows;
public readonly int $param_count;
public readonly int $field_count;
public readonly int $errno;
public readonly string $error;
public readonly array $error_list;
public readonly string $sqlstate;
public int $id;
/* Methoden */
public function __construct(mysqli `$mysql`, ?string `$query` = `null`)
public function attr_get(int `$attribute`): int
public function attr_set(int `$attribute`, int `$value`): bool
public function bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool
public function bind_result(mixed `&$var`, mixed `&...$vars`): bool
public function close(): true
public function data_seek(int `$offset`): void
public function execute(?array `$params` = `null`): bool
public function fetch(): ?bool
public function free_result(): void
public function get_result(): mysqli_result|false
public function get_warnings(): mysqli_warning|false
public function more_results(): bool
public function next_result(): bool
public function num_rows(): int|string
public function prepare(string `$query`): bool
public function reset(): bool
public function result_metadata(): mysqli_result|false
public function send_long_data(int `$param_num`, string `$data`): bool
public function store_result(): bool
}

## Eigenschaften

id

  Enthält die ID der Anweisung.

# mysqli_stmt::$affected_rows

# mysqli_stmt_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$affected_rows -- mysqli_stmt_affected_rows — Liefert die gesamte Anzahl der Datensätze, die bei der letzten ausgeführten Anweisung geändert, gelöscht, eingefügt oder abgeglichen wurden

### Beschreibung

Objektorientierter Stil

int|string $mysqli_stmt->affected_rows;

Prozeduraler Stil

function mysqli_stmt_affected_rows(mysqli_stmt `$statement`): int|string

Gibt die Anzahl der Datensätze zurück, die von einer `INSERT`-, `UPDATE`- oder `DELETE`-Abfrage betroffen waren. Funktioniert wie mysqli_stmt_num_rows() bei `SELECT`-Anweisungen.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Ein Integer größer als Null zeigt die Anzahl der betroffenen Datensätze an. Null zeigt an, dass von einer `UPDATE`-Anweisung keine Datensätze betroffen waren, dass keine Datensätze die `WHERE`-Bedingung der Anweisung erfüllt haben oder dass keine Anweisung ausgeführt wurde. `-1` zeigt an, dass die Abfrage einen Fehler zurückgegeben hat oder dass bei einer `SELECT`-Abfrage mysqli_stmt_affected_rows() vor mysqli_stmt_store_result() aufgerufen wurde.

> Hinweis:

> Ist die Anzahl der betroffenen Datensätze größer als der maximal erlaubte Wert eines PHP-Integers, wird die Anzahl der betroffenen Datensätze als Zeichenkette zurückgegeben.

### Beispiele

Beispiel #1 mysqli_stmt_affected_rows()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* temporäre Tabelle erzeugen */
    $mysqli->query("CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* Anweisung vorbereiten */
    $stmt = $mysqli->prepare($query);

    /* Variable an Platzhalter binden */
    $code = 'A%';
    $stmt->bind_param("s", $code);

    /* Anweisung ausführen */
    $stmt->execute();

    printf("eingefügte Datensätze: %d\n", $stmt->affected_rows);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* temporäre Tabelle erzeugen */
    mysqli_query($link, "CREATE TEMPORARY TABLE myCountry LIKE Country");

    $query = "INSERT INTO myCountry SELECT * FROM Country WHERE Code LIKE ?";

    /* Anweisung vorbereiten */
    $stmt = mysqli_prepare($link, $query);

    /* Variable an Platzhalter binden */
    $code = 'A%';
    mysqli_stmt_bind_param($stmt, "s", $code);

    /* Anweisung ausführen */
    mysqli_stmt_execute($stmt);

    printf("Eingefügte Datensätze: %d\n", mysqli_stmt_affected_rows($stmt));

Die obigen Bespiele erzeugen folgende Ausgabe:

    Eingefügte Datensätze: 17

### Siehe auch

- mysqli_stmt_num_rows() - Liefert die Anzahl der vom Server abgerufenen Datensätze
- mysqli_stmt_store_result() - Speichert eine Ergebnismenge in einem internen Puffer

# mysqli_stmt::attr_get

# mysqli_stmt_attr_get

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_get -- mysqli_stmt_attr_get — Liefert den aktuellen Wert des Attributs einer Anweisung

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::attr_get(int `$attribute`): int

Prozeduraler Stil

function mysqli_stmt_attr_get(mysqli_stmt `$statement`, int `$attribute`): int

Gibt den aktuellen Wert des Attributs einer Anweisung zurück.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

`attribute`

  Das Attribut, dessen Wert abgefragt werden soll.

### Rückgabewerte

Gibt den Wert des Attributs zurück.

# mysqli_stmt::attr_set

# mysqli_stmt_attr_set

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_set -- mysqli_stmt_attr_set — Verändert das Verhalten einer vorbereiteten Anweisung (prepared statement)

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::attr_set(int `$attribute`, int `$value`): bool

Prozeduraler Stil

function mysqli_stmt_attr_set(mysqli_stmt `$statement`, int `$attribute`, int `$value`): bool

Wird verwendet, um das Verhalten einer vorbereiteten Anweisung (prepared statement) zu verändern. Die Funktion kann mehrmals aufgerufen werden, um verschiedene Attribute zu setzen.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

`attribute`

  Das Attribut, das gesetzt werden soll. Es kann einen der folgenden Werte haben:

  Attribut-Werte
  Konstante | Beschreibung
  --- | ---
  MYSQLI_STMT_ATTR_UPDATE_MAX_LENGTH | Der Wert `true` veranlasst mysqli_stmt_store_result(), die Meta-Information `MYSQL_FIELD->max_length` zu aktualisieren.
  MYSQLI_STMT_ATTR_CURSOR_TYPE | Der Typ des Cursors, der für die Anweisung geöffnet wird, wenn mysqli_stmt_execute() aufgerufen wird. `value` kann `MYSQLI_CURSOR_TYPE_NO_CURSOR` (Voreinstellung) oder `MYSQLI_CURSOR_TYPE_READ_ONLY` sein.
  MYSQLI_STMT_ATTR_PREFETCH_ROWS | Die Anzahl der Datensätze, die auf einmal vom Server abgerufen werden, wenn ein Cursor verwendet wird. `value` kann zwischen 1 und dem Maximalwert von unsigned long (einschließlich) liegen. Die Voreinstellung ist 1. Entfernt in PHP 8.4.0.

  Wenn die Option `MYSQLI_STMT_ATTR_CURSOR_TYPE` mit `MYSQLI_CURSOR_TYPE_READ_ONLY` verwendet wird, dann wird ein Cursor für die Anweisung geöffnet, sobald mysqli_stmt_execute() aufgerufen wird. Wenn es schon einen offenen Cursor von einem vorherigen Aufruf von mysqli_stmt_execute() gibt, dann wird der Cursor geschlossen, bevor der neue geöffnet wird. mysqli_stmt_reset() schließt ebenfalls alle offenen Cursor, bevor die Anweisung für die Wiederausführung vorbereitet wird. mysqli_stmt_free_result() schließt alle offenen Cursor.

  Wenn ein Cursor für eine Anweisung geöffnet wird, dann ist mysqli_stmt_store_result() unnötig.

`value`

  Der Wert, der dem Attribut zugewiesen werden soll.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Siehe auch

- » Connector/MySQL mysql_stmt_attr_set()

# mysqli_stmt::bind_param

# mysqli_stmt_bind_param

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_param -- mysqli_stmt_bind_param — Bindet Variablen als Parameter an eine vorbereitete Anweisung (prepared statement)

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool

Prozeduraler Stil

function mysqli_stmt_bind_param(
mysqli_stmt `$statement`,
string `$types`,
mixed `&$var`,
mixed `&...$vars`
): bool

Bindet Variablen an die Parameter-Platzhalter einer SQL-Anweisung, die mit mysqli_prepare() oder mysqli_stmt_prepare() vorbereitet wurde.

> Hinweis:

> Wenn die Größe des Inhalts einer Variablen die maximal erlaubte Paketgröße (max_allowed_packet) überschreitet, dann muss `b` in `types` angegeben werden und mysqli_stmt_send_long_data() verwendet werden, um die Daten paketweise zu verschicken.

> Hinweis:

> Vorsicht, wenn mysqli_stmt_bind_param() zusammen mit call_user_func_array() verwendet werden soll. mysqli_stmt_bind_param() erfordert, dass die Parameter als Referenzvariablen übergeben werden, wohingegen call_user_func_array() als Parameter eine Liste von Variablen akzeptiert, die sowohl Referenzen als auch Werte sein können.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

`types`

  Eine Zeichenkette, die ein oder mehrere Zeichen enthält, die die Typen der zu bindenden Variablen spezifizieren.

  Zeichen für die Typangabe
  Zeichen | Beschreibung
  --- | ---
  i | die entsprechende Variable hat den Typ int
  d | die entsprechende Variable hat den Typ float
  s | die entsprechende Variable hat den Typ string
  b | die entsprechende Variable ist ein BLOB und wird paketweise geschickt

`var`
`vars`

  Die Anzahl der Variablen und die Länge der Zeichenkette `types` müssen zu den Parametern in der Anweisung passen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 mysqli_stmt::bind_param()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    $stmt->bind_param('sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    $stmt->execute();

    printf("Datenätze eingefügt: %d.\n", $stmt->affected_rows);

    /* bereinige die Tabelle CountryLanguage */
    $mysqli->query("DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("Datensätze gelöscht: %d.\n", $mysqli->affected_rows);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    $stmt = mysqli_prepare($link, "INSERT INTO CountryLanguage VALUES (?, ?, ?, ?)");
    mysqli_stmt_bind_param($stmt, 'sssd', $code, $language, $official, $percent);

    $code = 'DEU';
    $language = 'Bavarian';
    $official = "F";
    $percent = 11.2;

    mysqli_stmt_execute($stmt);

    printf("Datenätze eingefügt: %d.\n", mysqli_stmt_affected_rows($stmt));

    /* bereinige die Tabelle CountryLanguage */
    mysqli_query($link, "DELETE FROM CountryLanguage WHERE Language='Bavarian'");
    printf("Datensätze gelöscht: %d.\n", mysqli_affected_rows($link));

Die obigen Bespiele erzeugen folgende Ausgabe:

    Datensätze eingefügt: 1.
    Datensätze gelöscht: 1.

Beispiel #2 Argumente mittels `...` übergeben

Der Operator `...` kann verwendet werden, um eine Liste von Argumenten mit variabler Länge zu übergeben, z. B. in einer `WHERE IN`-Bedingung.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $stmt = $mysqli->prepare("SELECT Language FROM CountryLanguage WHERE CountryCode IN (?, ?)");
    /* Argumente mittels ... übergeben */
    $stmt->bind_param('ss', ...['DEU', 'POL']);
    $stmt->execute();
    $stmt->store_result();

    printf("%d Datensätze gefunden.\n", $stmt->num_rows());

Die obigen Bespiele erzeugen folgende Ausgabe:

    10 Datensätze gefunden.

### Siehe auch

- mysqli_stmt_bind_result() - Bindet Variablen an eine vorbereitete Anweisung (prepared statement), um das Ergebnis einer Abfrage abzulegen
- mysqli_stmt_execute() - Führt eine vorbereitete Anweisung aus
- mysqli_stmt_fetch() - Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab
- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_send_long_data() - Sendet Daten blockweise
- mysqli_stmt_errno() - Liefert den Fehlercode der zuletzt aufgerufenen Anweisung
- mysqli_stmt_error() - Liefert die Beschreibung des letzten Fehlers einer Anweisung als Zeichenkette

# mysqli_stmt::bind_result

# mysqli_stmt_bind_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_result -- mysqli_stmt_bind_result — Bindet Variablen an eine vorbereitete Anweisung (prepared statement), um das Ergebnis einer Abfrage abzulegen

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::bind_result(mixed `&$var`, mixed `&...$vars`): bool

Prozeduraler Stil

function mysqli_stmt_bind_result(mysqli_stmt `$statement`, mixed `&$var`, mixed `&...$vars`): bool

Bindet Spalten der Ergebnismenge an Variablen.

Wenn mysqli_stmt_fetch() aufgerufen wird, um Daten abzurufen, dann legt das MySQL-Client-/Serverprotokoll die Daten der gebundenen Spalten in den spezifizierten Variablen `var`/`vars` ab.

Eine Spalte kann jederzeit gebunden oder neu gebunden werden, auch nachdem eine Ergebnismenge teilweise abgerufen wurde. Die neue Bindung wird beim nächsten Mal wirksam, wenn mysqli_stmt_fetch() aufgerufen wird.

> Hinweis:

> Alle Spalten müssen nach dem Aufruf von mysqli_stmt_execute() und vor dem Aufruf von mysqli_stmt_fetch() gebunden werden.

> Hinweis:

> Abhängig vom Typ der Spalte können Variablen automatisch den entsprechenden PHP-Typ annehmen.

Tipp

Diese Funktion ist nützlich für einfache Ergebnisse. Verwenden Sie mysqli_stmt_get_result(), um iterierbare Ergebnismengen abzurufen oder um jeden Datensatz als Array oder Objekt abzurufen.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

`var`

  Die erste Variable, die gebunden werden soll.

`vars`

  Weitere zu bindende Variablen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* bereite Abfrage vor */
    $stmt = $mysqli->prepare("SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    $stmt->execute();

    /* binde Variablen an die Ergebnismenge */
    $stmt->bind_result($col1, $col2);

    /* rufe die Ergebnisse ab */
    while ($stmt->fetch()) {
        printf("%s %s\n", $col1, $col2);
    }

Beispiel #2 Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* bereite Abfrage vor */
    $stmt = mysqli_prepare($link, "SELECT Code, Name FROM Country ORDER BY Name LIMIT 5");
    mysqli_stmt_execute($stmt);

    /* binde Variablen an die Ergebnismenge */
    mysqli_stmt_bind_result($stmt, $col1, $col2);

    /* rufe die Ergebnisse ab */
    while (mysqli_stmt_fetch($stmt)) {
        printf("%s %s\n", $col1, $col2);
    }

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    AFG Afghanistan
    ALB Albania
    DZA Algeria
    ASM American Samoa
    AND Andorra

### Siehe auch

- mysqli_stmt_get_result() - Ruft die Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab
- mysqli_stmt_bind_param() - Bindet Variablen als Parameter an eine vorbereitete Anweisung (prepared statement)
- mysqli_stmt_execute() - Führt eine vorbereitete Anweisung aus
- mysqli_stmt_fetch() - Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab
- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor

# mysqli_stmt::close

# mysqli_stmt_close

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::close -- mysqli_stmt_close — Schließt eine vorbereitete Anweisung (prepared statement)

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::close(): true

Prozeduraler Stil

function mysqli_stmt_close(mysqli_stmt `$statement`): true

Schließt eine vorbereitete Anweisung (prepared statement). mysqli_stmt_close() gibt ebenfalls das Handle der Anweisung frei. Wenn die gegebene Anweisung noch anhängige oder ungelesene Ergebnismengen hat, dann verwirft die Funktion diese, sodass die nächste Abfrage ausgeführt werden kann.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion gibt nun immer `true` zurück; vorher gab sie bei einem Fehler `false` zurück.

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor

# mysqli_stmt::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::__construct — Erzeugt ein neues mysqli_stmt-Objekt

### Beschreibung

public function mysqli_stmt::__construct(mysqli `$mysql`, ?string `$query` = `null`)

Diese Methode erzeugt ein neues mysqli_stmt-Objekt.

### Parameter-Liste

`link`

  Ein gültiges mysqli-Objekt.

`query`

  Die Abfrage als Zeichenkette. Wenn der Parameter `null` ist, dann verhält sich der Konstruktor genau wie mysqli_stmt_init(), andernfalls verhält er sich wie bei mysqli_prepare().

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `query` ist nun ein Nullable-Typ.

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_init() - Initialisiert eine Anweisung und liefert ein Objekt für die Verwendung mit mysqli_stmt_prepare

# mysqli_stmt::data_seek

# mysqli_stmt_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::data_seek -- mysqli_stmt_data_seek — Verschiebt den Ergebniszeiger auf eine beliebige Zeile im gepufferten Ergebnis

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::data_seek(int `$offset`): void

Prozeduraler Stil

function mysqli_stmt_data_seek(mysqli_stmt `$statement`, int `$offset`): void

Diese Funktion verschiebt den Ergebnismengenzeiger der gepufferten Ergebnismenge in die mit dem Parameter `offset` angegebene beliebige Zeile.

Diese Funktion funktioniert nur bei einer gepufferten internen Ergebnismenge. mysqli_stmt_store_result() muss vor mysqli_stmt_data_seek() aufgerufen werden.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

`offset`

  Muss zwischen Null und der Anzahl der Zeilen - 1 liegen (0.. mysqli_stmt_num_rows() - 1)

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    $stmt->bind_result($name, $code);

    $stmt->store_result();

    /* zu Zeile Nr. 400 springen */
    $stmt->data_seek(399);

    $stmt->fetch();

    printf ("Stadt: %s  Ländercode: %s\n", $name, $code);

Beispiel #2 Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $stmt = mysqli_prepare($link, $query);

    mysqli_stmt_execute($stmt);

    mysqli_stmt_bind_result($stmt, $name, $code);

    mysqli_stmt_store_result($stmt);

    /* zu Zeile Nr. 400 springen */
    mysqli_stmt_data_seek($stmt, 399);

    mysqli_stmt_fetch($stmt);

    printf ("Stadt: %s  Ländercode: %s\n", $name, $code);

Die obigen Bespiele erzeugen folgende Ausgabe:

    Stadt: Benin City  Ländercode: NGA

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_store_result() - Speichert eine Ergebnismenge in einem internen Puffer
- mysqli_stmt_num_rows() - Liefert die Anzahl der vom Server abgerufenen Datensätze
- mysqli_data_seek() - Verschiebt den Ergebniszeiger auf die angegebene Zeile

# mysqli_stmt::$errno

# mysqli_stmt_errno

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$errno -- mysqli_stmt_errno — Liefert den Fehlercode der zuletzt aufgerufenen Anweisung

### Beschreibung

Objektorientierter Stil

int $mysqli_stmt->errno;

Prozeduraler Stil

function mysqli_stmt_errno(mysqli_stmt `$statement`): int

Gibt den Fehlercode der zuletzt aufgerufenen Anweisungsfunktion zurück, die entweder erfolgreich war oder fehlschlug.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt einen Fehlercode zurück. Null bedeutet, dass kein Fehler aufgetreten ist.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    /* Verbindung aufbauen */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Tabelle löschen */
        $mysqli->query("DROP TABLE myCountry");

        /* Abfrage ausführen */
        $stmt->execute();

        printf("Fehler: %d.\n", $stmt->errno);

        /* Anweisung schließen */
        $stmt->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    /* Verbindung aufbauen */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Tabelle löschen */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Abfrage ausführen */
        mysqli_stmt_execute($stmt);

        printf("Fehler: %d.\n", mysqli_stmt_errno($stmt));

        /* Anweisung schließen */
        mysqli_stmt_close($stmt);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehler: 1146.

### Siehe auch

- mysqli_stmt_error() - Liefert die Beschreibung des letzten Fehlers einer Anweisung als Zeichenkette
- mysqli_stmt_sqlstate() - Liefert den SQLSTATE-Fehlercode der letzten Anweisung

# mysqli_stmt::$error

# mysqli_stmt_error

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$error -- mysqli_stmt_error — Liefert die Beschreibung des letzten Fehlers einer Anweisung als Zeichenkette

### Beschreibung

Objektorientierter Stil

string $mysqli_stmt->error;

Prozeduraler Stil

function mysqli_stmt_error(mysqli_stmt `$statement`): string

Gibt eine Zeichenkette zurück, die die Fehlermeldung der zuletzt aufgerufenen Anweisungsfunktion enthält, die entweder erfolgreich war oder fehlschlug.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die den Fehler beschreibt, oder eine leere Zeichenkette, wenn kein Fehler aufgetreten ist.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    /* Verbindung aufbauen */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Tabelle löschen */
        $mysqli->query("DROP TABLE myCountry");

        /* Abfrage ausführen */
        $stmt->execute();

        printf("Fehler: %s.\n", $stmt->error);

        /* Anweisung schließen */
        $stmt->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    /* Verbindung aufbauen */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Tabelle löschen */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Abfrage ausführen */
        mysqli_stmt_execute($stmt);

        printf("Fehler: %s.\n", mysqli_stmt_error($stmt));

        /* Anweisung schließen */
        mysqli_stmt_close($stmt);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehler: Table 'world.myCountry' doesn't exist.

### Siehe auch

- mysqli_stmt_errno() - Liefert den Fehlercode der zuletzt aufgerufenen Anweisung
- mysqli_stmt_sqlstate() - Liefert den SQLSTATE-Fehlercode der letzten Anweisung

# mysqli_stmt::$error_list

# mysqli_stmt_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli_stmt::$error_list -- mysqli_stmt_error_list — Liefert eine Liste der Fehler der zuletzt ausgeführten Anweisung

### Beschreibung

Objektorientierter Stil

array $mysqli_stmt->error_list;

Prozeduraler Stil

function mysqli_stmt_error_list(mysqli_stmt `$statement`): array

Gibt ein Array von Fehlern der zuletzt aufgerufenen Anweisungsfunktion zurück, die entweder erfolgreich war oder fehlschlug.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt eine Liste von Fehlern zurück, die jeweils als assoziatives Array mit den Schlüsseln errno, error und sqlstate vorliegen.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    /* Verbindung aufbauen */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Tabelle löschen */
        $mysqli->query("DROP TABLE myCountry");

        /* Abfrage ausführen */
        $stmt->execute();

        echo "Fehler:\n";
        print_r($stmt->error_list);

        /* Anweisung schließen */
        $stmt->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    /* Verbindung aufbauen */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Tabelle löschen */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Abfrage ausführen */
        mysqli_stmt_execute($stmt);

        echo "Fehler:\n";
        print_r(mysqli_stmt_error_list($stmt));

        /* Anweisung schließen */
        mysqli_stmt_close($stmt);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehler:
    Array
    (
        [0] => Array
            (
                [errno] => 1146
                [sqlstate] => 42S02
                [error] => Table 'world.myCountry' doesn't exist
            )

    )

### Siehe auch

- mysqli_stmt_error() - Liefert die Beschreibung des letzten Fehlers einer Anweisung als Zeichenkette
- mysqli_stmt_errno() - Liefert den Fehlercode der zuletzt aufgerufenen Anweisung
- mysqli_stmt_sqlstate() - Liefert den SQLSTATE-Fehlercode der letzten Anweisung

# mysqli_stmt::execute

# mysqli_stmt_execute

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::execute -- mysqli_stmt_execute — Führt eine vorbereitete Anweisung aus

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::execute(?array `$params` = `null`): bool

Prozeduraler Stil

function mysqli_stmt_execute(mysqli_stmt `$statement`, ?array `$params` = `null`): bool

Führt eine zuvor vorbereitete Anweisung aus. Die Anweisung muss vorher erfolgreich vorbereitet werden, entweder mit einer der Funktionen mysqli_prepare() oder mysqli_stmt_prepare() oder durch Übergabe des zweiten Parameters an mysqli_stmt::__construct().

Wenn es sich um eine `UPDATE`-, `DELETE`- oder `INSERT`-Anweisung handelt, kann die Gesamtzahl der betroffenen Zeilen mit Hilfe der Funktion mysqli_stmt_affected_rows() ermittelt werden. Wenn die Abfrage eine Ergebnismenge liefert, kann diese mit der Funktion mysqli_stmt_get_result() abgerufen werden oder indem sie mit der Funktion mysqli_stmt_fetch() Zeile für Zeile direkt aus der Anweisung abgerufen wird.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

`params`

  Ein optionales Listen-Array mit so vielen Elementen, wie es gebundene Parameter in der auszuführenden SQL-Anweisung gibt. Jeder Wert wird wie eine Zeichenkette behandelt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der optionale Parameter `params` wurde hinzugefügt.

### Beispiele

Beispiel #1 Ausführen einer vorbereiteten Anweisung mit gebundenen Variablen

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");

    /* insert-Anweisung vorbereiten */
    $stmt = $mysqli->prepare("INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Variablen an Parameter binden */
    $stmt->bind_param("sss", $val1, $val2, $val3);

    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Anweisung ausführen */
    $stmt->execute();

    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Anweisung ausführen */
    $stmt->execute();

    /* Alle Zeilen von myCity abrufen */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");

    /* insert-Anweisung vorbereiten */
    $stmt = mysqli_prepare($link, "INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)");

    /* Variablen an Parameter binden */
    mysqli_stmt_bind_param($stmt, "sss", $val1, $val2, $val3);

    $val1 = 'Stuttgart';
    $val2 = 'DEU';
    $val3 = 'Baden-Wuerttemberg';

    /* Anweisung ausführen */
    mysqli_stmt_execute($stmt);

    $val1 = 'Bordeaux';
    $val2 = 'FRA';
    $val3 = 'Aquitaine';

    /* Anweisung ausführen */
    mysqli_stmt_execute($stmt);

    /* Alle Zeilen von myCity abrufen */
    $query = "SELECT Name, CountryCode, District FROM myCity";
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Die obigen Bespiele erzeugen folgende Ausgabe:

    Stuttgart (DEU,Baden-Wuerttemberg)
    Bordeaux (FRA,Aquitaine)

Beispiel #2 Ausführen einer vorbereiteten Anweisung mit einem Array von Werten

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

    $mysqli->query('CREATE TEMPORARY TABLE myCity LIKE City');

    /* insert-Anweisung vorbereiten */
    $stmt = $mysqli->prepare('INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Anweisung ausführen */
    $stmt->execute(['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Alle Zeilen von myCity abrufen */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = $mysqli->query($query);
    while ($row = $result->fetch_row()) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect('localhost', 'my_user', 'my_password', 'world');

    mysqli_query($link, 'CREATE TEMPORARY TABLE myCity LIKE City');

    /* insert-Anweisung vorbereiten */
    $stmt = mysqli_prepare($link, 'INSERT INTO myCity (Name, CountryCode, District) VALUES (?,?,?)');

    /* Anweisung ausführen */
    mysqli_stmt_execute($stmt, ['Stuttgart', 'DEU', 'Baden-Wuerttemberg']);

    /* Alle Zeilen von myCity abrufen */
    $query = 'SELECT Name, CountryCode, District FROM myCity';
    $result = mysqli_query($link, $query);
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s,%s)\n", $row[0], $row[1], $row[2]);
    }

Die obigen Bespiele erzeugen folgende Ausgabe:

    Stuttgart (DEU,Baden-Wuerttemberg)

### Siehe auch

- mysqli_execute_query() - Bereitet eine SQL-Anweisung vor, bindet die Parameter und führt die Anweisung aus
- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_bind_param() - Bindet Variablen als Parameter an eine vorbereitete Anweisung (prepared statement)
- mysqli_stmt_get_result() - Ruft die Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab

# mysqli_stmt::fetch

# mysqli_stmt_fetch

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::fetch -- mysqli_stmt_fetch — Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::fetch(): ?bool

Prozeduraler Stil

function mysqli_stmt_fetch(mysqli_stmt `$statement`): ?bool

Ruft das Ergebnis einer vorbereiteten Anweisung in die Variablen ab, die durch mysqli_stmt_bind_result() gebunden wurden.

> Hinweis:

> Es ist zu beachten, dass alle Spalten durch die Anwendung gebunden werden müssen, bevor mysqli_stmt_fetch() aufgerufen wird.

> Hinweis:

> Die Daten werden ungepuffert übertragen, ohne die Funktion mysqli_stmt_store_result() aufzurufen, was die Leistung verringern kann (aber den Speicherbedarf reduziert).

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Rückgabewerte
Wert | Beschreibung
--- | ---
`true` | Erfolg. Die Daten wurden abgerufen
`false` | Es ist ein Fehler aufgetreten
`null` | Es gibt keine weiteren Zeilen/Daten oder die Daten wurden abgeschnitten

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = $mysqli->prepare($query)) {

        /* Anweisung ausführen */
        $stmt->execute();

        /* Ergebnisvariablen binden */
        $stmt->bind_result($name, $code);

        /* Werte abrufen */
        while ($stmt->fetch()) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* Anweisung schließen */
        $stmt->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, CountryCode FROM City ORDER by ID DESC LIMIT 150,5";

    if ($stmt = mysqli_prepare($link, $query)) {

        /* Anweisung ausführen */
        mysqli_stmt_execute($stmt);

        /* Ergebnisvariablen binden */
        mysqli_stmt_bind_result($stmt, $name, $code);

        /* Werte abrufen */
        while (mysqli_stmt_fetch($stmt)) {
            printf ("%s (%s)\n", $name, $code);
        }

        /* Anweisung schließen */
        mysqli_stmt_close($stmt);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Rockford (USA)
    Tallahassee (USA)
    Salinas (USA)
    Santa Clarita (USA)
    Springfield (USA)

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_errno() - Liefert den Fehlercode der zuletzt aufgerufenen Anweisung
- mysqli_stmt_error() - Liefert die Beschreibung des letzten Fehlers einer Anweisung als Zeichenkette
- mysqli_stmt_bind_result() - Bindet Variablen an eine vorbereitete Anweisung (prepared statement), um das Ergebnis einer Abfrage abzulegen

# mysqli_stmt::$field_count

# mysqli_stmt_field_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$field_count -- mysqli_stmt_field_count — Liefert die Anzahl der Spalten in der angegebenen Anweisung

### Beschreibung

Objektorientierter Stil

int $mysqli_stmt->field_count;

Prozeduraler Stil

function mysqli_stmt_field_count(mysqli_stmt `$statement`): int

Gibt die Anzahl der Spalten in der vorbereiteten Anweisung zurück.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt eine ganze Zahl zurück, die die Anzahl der Spalten angibt.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Code=?");
    $stmt->bind_param('s', $code);
    $stmt->execute();
    $row = $stmt->get_result()->fetch_row();
    for ($i = 0; $i < $stmt->field_count; $i++) {
        printf("Der Wert der Spalte Nummer %d ist %s", $i, $row[$i]);
    }

Beispiel #2 Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $code = 'FR';

    $stmt = mysqli_prepare($mysqli, "SELECT Name FROM Country WHERE Code=?");
    mysqli_stmt_bind_param($stmt, 's', $code);
    mysqli_stmt_execute($stmt);
    $result = mysqli_stmt_get_result($stmt);
    $row = mysqli_fetch_row($result);
    for ($i = 0; $i < mysqli_stmt_field_count($stmt); $i++) {
        printf("Der Wert der Spalte Nummer %d ist %s", $i, $row[$i]);
    }

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Der Wert der Spalte Nummer 0 ist France

### Siehe auch

- mysqli_stmt_num_rows() - Liefert die Anzahl der vom Server abgerufenen Datensätze

# mysqli_stmt::free_result

# mysqli_stmt_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::free_result -- mysqli_stmt_free_result — Gibt den mit der angegebenen Anweisung verbundenen Ergebnisspeicher frei

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::free_result(): void

Prozeduraler Stil

function mysqli_stmt_free_result(mysqli_stmt `$statement`): void

Gibt den mit der Anweisung verbundenen Ergebnisspeicher frei, der von der Funktion mysqli_stmt_store_result() zugewiesen wurde.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- mysqli_stmt_store_result() - Speichert eine Ergebnismenge in einem internen Puffer

# mysqli_stmt::get_result

# mysqli_stmt_get_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::get_result -- mysqli_stmt_get_result — Ruft die Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::get_result(): mysqli_result|false

Prozeduraler Stil

function mysqli_stmt_get_result(mysqli_stmt `$statement`): mysqli_result|false

Ruft eine Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab. Die Daten werden vom MySQL-Server an PHP übertragen. Diese Methode sollte nur bei Abfragen aufgerufen werden, die eine Ergebnismenge erzeugen.

> Hinweis:

> Nur in mysqlnd verfügbar.

> Hinweis:

> Diese Funktion kann nicht zusammen mit mysqli_stmt_store_result() verwendet werden. Beide Funktionen rufen die komplette Ergebnismenge vom MySQL-Server ab.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt bei einem Fehler `false` zurück. Bei erfolgreichen Abfragen, die eine Ergebnismenge erzeugen, also z. B. `SELECT, SHOW, DESCRIBE` oder `EXPLAIN`, gibt mysqli_stmt_get_result() ein mysqli_result-Objekt zurück. Bei anderen erfolgreichen Abfragen gibt mysqli_stmt_get_result() `false` zurück. Mit der Funktion mysqli_stmt_errno() kann zwischen den beiden Gründen für `false` unterschieden werden; aufgrund eines Fehlers musste dafür vor PHP 7.4.13 die Funktion mysqli_errno() verwendet werden.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = $mysqli->prepare($query);
    $stmt->bind_param("s", $continent);

    $continentList = array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        $stmt->execute();
        $result = $stmt->get_result();
        while ($row = $result->fetch_array(MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }

Beispiel #2 Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, Population, Continent FROM Country WHERE Continent=? ORDER BY Name LIMIT 1";

    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_bind_param($stmt, "s", $continent);

    $continentList= array('Europe', 'Africa', 'Asia', 'North America');

    foreach ($continentList as $continent) {
        mysqli_stmt_execute($stmt);
        $result = mysqli_stmt_get_result($stmt);
        while ($row = mysqli_fetch_array($result, MYSQLI_NUM)) {
            foreach ($row as $r) {
                print "$r ";
            }
            print "\n";
        }
    }

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Albania 3401200 Europe
    Algeria 31471000 Africa
    Afghanistan 22720000 Asia
    Anguilla 8000 North America

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_result_metadata() - Liefert die Metadaten der Ergebnismenge aus einer vorbereiteten Anweisung
- mysqli_stmt_fetch() - Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab
- mysqli_fetch_array() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab
- mysqli_stmt_store_result() - Speichert eine Ergebnismenge in einem internen Puffer

# mysqli_stmt::get_warnings

# mysqli_stmt_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli_stmt::get_warnings -- mysqli_stmt_get_warnings — Ermittelt das Ergebnis von SHOW WARNINGS

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::get_warnings(): mysqli_warning|false

Prozeduraler Stil

function mysqli_stmt_get_warnings(mysqli_stmt `$statement`): mysqli_warning|false
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# mysqli_stmt::$insert_id

# mysqli_stmt_insert_id

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$insert_id -- mysqli_stmt_insert_id — Ermittelt die ID, die beim letzten INSERT-Vorgang erzeugt wurde

### Beschreibung

Objektorientierter Stil

int|string $mysqli_stmt->insert_id;

Prozeduraler Stil

function mysqli_stmt_insert_id(mysqli_stmt `$statement`): int|string
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# mysqli_stmt::more_results

# mysqli_stmt_more_results

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::more_results -- mysqli_stmt_more_results — Prüft, ob es weitere Ergebnisse aus einer Mehrfachabfrage gibt

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::more_results(): bool

Prozeduraler Stil:

function mysqli_stmt_more_results(mysqli_stmt `$statement`): bool

Prüft, ob es weitere Ergebnisse aus einer Mehrfachabfrage gibt.

> Hinweis:

> Nur in mysqlnd verfügbar.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt `true` zurück, wenn es weitere Ergebnisse gibt, andernfalls `false`.

### Siehe auch

- mysqli_stmt::next_result() - Liest das nächste Ergebnis einer Mehrfachabfrage aus
- mysqli::multi_query() - Führt eine oder mehrere Abfragen in einer Datenbank durch

# mysqli_stmt::next_result

# mysqli_stmt_next_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::next_result -- mysqli_stmt_next_result — Liest das nächste Ergebnis einer Mehrfachabfrage aus

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::next_result(): bool

Prozeduraler Stil:

function mysqli_stmt_next_result(mysqli_stmt `$statement`): bool

Liest das nächste Ergebnis einer Mehrfachabfrage aus.

> Hinweis:

> Vor PHP 8.1.0 nur mit mysqlnd verfügbar.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Nun auch verfügbar, wenn gegen libmysqlclient gelinkt wird.

### Siehe auch

- mysqli_stmt::more_results() - Prüft, ob es weitere Ergebnisse aus einer Mehrfachabfrage gibt
- mysqli::multi_query() - Führt eine oder mehrere Abfragen in einer Datenbank durch

# mysqli_stmt::$num_rows

# mysqli_stmt::num_rows

# mysqli_stmt_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$num_rows -- mysqli_stmt::num_rows -- mysqli_stmt_num_rows — Liefert die Anzahl der vom Server abgerufenen Datensätze

### Beschreibung

Objektorientierter Stil

int|string $mysqli_stmt->num_rows;
public function mysqli_stmt::num_rows(): int|string

Prozeduraler Stil

function mysqli_stmt_num_rows(mysqli_stmt `$statement`): int|string

Gibt die Anzahl der Datensätze zurück, die im Anweisungshandle gepuffert sind. Diese Funktion funktioniert erst, wenn die gesamte Ergebnismenge mit mysqli_stmt_store_result() in einem Anweisungshandle gepuffert wurde.

Diese Funktion gibt `0` zurück, solange nicht alle Datensätze vom Server abgerufen wurden.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt die Anzahl der gepufferten Zeilen als Integer zurück. Gibt im ungepufferten Modus `0` zurück, solange nicht alle Datensätze vom Server abgerufen wurden.

> Hinweis:

> Wenn die Anzahl der Zeilen größer ist als `PHP_INT_MAX`, wird die Anzahl als String zurückgegeben.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* Das Ergebnis im internen Puffer speichern */
    $stmt->store_result();

    printf("Die Anzahl der Datensätze: %d.\n", $stmt->num_rows);

Beispiel #2 Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* Das Ergebnis im internen Puffer speichern */
    mysqli_stmt_store_result($stmt);

    printf("Die Anzahl der Datensätze: %d.\n", mysqli_stmt_num_rows($stmt));

Die obigen Bespiele erzeugen folgende Ausgabe:

    Die Anzahl der Datensätze: 20.

### Siehe auch

- mysqli_stmt_store_result() - Speichert eine Ergebnismenge in einem internen Puffer
- mysqli_stmt_affected_rows() - Liefert die gesamte Anzahl der Datensätze, die bei der letzten ausgeführten Anweisung geändert, gelöscht, eingefügt oder abgeglichen wurden
- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor

# mysqli_stmt::$param_count

# mysqli_stmt_param_count

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$param_count -- mysqli_stmt_param_count — Liefert die Anzahl der Parameter einer Anweisung

### Beschreibung

Objektorientierter Stil

int $mysqli_stmt->param_count;

Prozeduraler Stil

function mysqli_stmt_param_count(mysqli_stmt `$statement`): int

Gibt die Anzahl der Parameter-Platzhalter zurück, die in der vorbereiteten Anweisung (Prepared Statement) vorhanden sind.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt einen Integer zurück, der die Anzahl der Parameter angibt.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Datenbankverbindung prüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = $mysqli->prepare("SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = $stmt->param_count;
        printf("Die Anweisung hat %d Parameter.\n", $marker);

        /* Abfrage-Objekt schließen */
        $stmt->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Datenbankverbindung prüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    if ($stmt = mysqli_prepare($link, "SELECT Name FROM Country WHERE Name=? OR Code=?")) {

        $marker = mysqli_stmt_param_count($stmt);
        printf("Die Anweisung hat %d Parameter.\n", $marker);

        /* Abfrage-Objekt schließen */
        mysqli_stmt_close($stmt);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Die Anweisung hat 2 Parameter.

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor

# mysqli_stmt::prepare

# mysqli_stmt_prepare

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::prepare -- mysqli_stmt_prepare — Bereitet eine SQL-Anweisung zur Ausführung vor

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::prepare(string `$query`): bool

Prozeduraler Stil

function mysqli_stmt_prepare(mysqli_stmt `$statement`, string `$query`): bool

Bereitet eine Anweisung zur Ausführung vor. Die Abfrage muss aus einer einzigen SQL-Anweisung bestehen.

Die Anweisungsvorlage darf null oder mehr Fragezeichen-Parametermarker (`?`) - auch Platzhalter genannt - enthalten. Diese Parametermarker müssen vor der Ausführung der Anweisung mittels mysqli_stmt_bind_param() an Anwendungsvariablen gebunden werden.

> Hinweis:

> Wenn eine Anweisung an mysqli_stmt_prepare() übergeben wird, die größer ist als die vom Server maximal erlaubte Paketgröße (`max_allowed_packet`), hängen die zurückgegebenen Fehlercodes davon ab, ob der MySQL Native Driver (`mysqlnd`) oder die MySQL Client Library (`libmysqlclient`) verwendet wird. Die Funktion verhält sich wie folgt:

> - `mysqlnd` gibt unter Linux den Fehlercode 1153 zurück. Diese Fehlermeldung bedeutet got a packet bigger than `max_allowed_packet` bytes.

> - `mysqlnd` gibt unter Windows den Fehlercode 2006 zurück. Diese Fehlermeldung bedeutet server has gone away.

> - `libmysqlclient` gibt auf allen Plattformen den Fehlercode 2006 zurück. Diese Fehlermeldung bedeutet server has gone away.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

`query`

  Die Zeichenkette mit der Abfrage. Sie darf nur eine SQL-Anweisung enthalten.

  Die SQL-Anweisung darf null oder mehr Platzhalter für Parameter enthalten, die an den entsprechenden Stellen durch Fragezeichen (`?`) dargestellt werden.

  > Hinweis:

  > Die Platzhalter sind nur an bestimmten Stellen einer SQL-Anweisung zulässig. Zum Beispiel sind sie bei einer `INSERT`-Anweisung in der `VALUES()`-Liste erlaubt, um die Werte für die Spalten einer Zeile anzugeben, oder bei einer `WHERE`-Klausel im Vergleich mit einer Spalte, um einen Vergleichswert anzugeben. Nicht zulässig sind sie hingegen für Bezeichner (wie Tabellen- oder Spaltennamen).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 mysqli_stmt::prepare()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* Vorbereitete Anweisung erstellen */
    $stmt = $mysqli->stmt_init();
    $stmt->prepare("SELECT District FROM City WHERE Name=?");

    /* Parameter für die Platzhalter binden */
    $stmt->bind_param("s", $city);

    /* Anfrage ausführen */
    $stmt->execute();

    /* Ergebnisvariablen binden */
    $stmt->bind_result($district);

    /* Wert abrufen */
    $stmt->fetch();

    printf("%s liegt im Bezirk %s\n", $city, $district);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $city = "Amersfoort";

    /* Vorbereitete Anweisung erstellen */
    $stmt = mysqli_stmt_init($link);
    mysqli_stmt_prepare($stmt, "SELECT District FROM City WHERE Name=?");

    /* Parameter an Platzhalter binden */
    mysqli_stmt_bind_param($stmt, "s", $city);

    /* Anfrage ausführen */
    mysqli_stmt_execute($stmt);

    /* Ergebnisvariablen binden */
    mysqli_stmt_bind_result($stmt, $district);

    /* Wert abrufen */
    mysqli_stmt_fetch($stmt);

    printf("%s liegt im Bezirk %s\n", $city, $district);

Die obigen Bespiele erzeugen folgende Ausgabe:

    Amersfoort liegt im Bezirk Utrecht

### Siehe auch

- mysqli_stmt_init() - Initialisiert eine Anweisung und liefert ein Objekt für die Verwendung mit mysqli_stmt_prepare
- mysqli_stmt_execute() - Führt eine vorbereitete Anweisung aus
- mysqli_stmt_fetch() - Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab
- mysqli_stmt_bind_param() - Bindet Variablen als Parameter an eine vorbereitete Anweisung (prepared statement)
- mysqli_stmt_bind_result() - Bindet Variablen an eine vorbereitete Anweisung (prepared statement), um das Ergebnis einer Abfrage abzulegen
- mysqli_stmt_get_result() - Ruft die Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab
- mysqli_stmt_close() - Schließt eine vorbereitete Anweisung (prepared statement)

# mysqli_stmt::reset

# mysqli_stmt_reset

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::reset -- mysqli_stmt_reset — Setzt eine vorbereitete Anweisung zurück

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::reset(): bool

Prozeduraler Stil

function mysqli_stmt_reset(mysqli_stmt `$statement`): bool

Diese Funktion setzt die vorbereitete Anweisung auf dem Client und dem Server auf den Zustand zurück, in dem sie sich befand, nachdem sie vorbereitet wurde.

Sie setzt die Anweisung auf dem Server, die mit mysqli_stmt_send_long_data() gesendeten Daten, ungepufferte Ergebnismengen und aktuelle Fehler zurück. Es werden keine Bindungen oder gespeicherten Ergebnismengen gelöscht. Gespeicherte Ergebnismengen werden gelöscht, wenn die vorbereitete Anweisung ausgeführt (oder geschlossen) wird.

Um eine Anweisung mit einer anderen Abfrage vorzubereiten, kann die Funktion mysqli_stmt_prepare() verwendet werden.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor

# mysqli_stmt::result_metadata

# mysqli_stmt_result_metadata

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — Liefert die Metadaten der Ergebnismenge aus einer vorbereiteten Anweisung

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::result_metadata(): mysqli_result|false

Prozeduraler Stil

function mysqli_stmt_result_metadata(mysqli_stmt `$statement`): mysqli_result|false

Wenn eine an mysqli_prepare() übergebene Anweisung eine Ergebnismenge erzeugt, gibt mysqli_stmt_result_metadata() ein Ergebnisobjekt zurück, das zur Verarbeitung der Metainformationen, z. B. die Gesamtzahl der Spalten und der einzelnen Informationen über die Spalten, verwendet werden kann.

> Hinweis:

> Dieser Ergebnismengenzeiger kann als Argument an Funktionen übergeben werden, die spaltenbasierte Ergebnismengen-Metadaten verarbeiten, z. B.:

> - mysqli_num_fields()

> - mysqli_fetch_field()

> - mysqli_fetch_field_direct()

> - mysqli_fetch_fields()

> - mysqli_field_count()

> - mysqli_field_seek()

> - mysqli_field_tell()

> - mysqli_free_result()

Wenn die Ergebnismenge nicht mehr benötigt wird, sollte sie freigegeben werden. Dazu kann sie an die Funktion mysqli_free_result() übergeben werden.

> Hinweis:

> Die von mysqli_stmt_result_metadata() zurückgegebene Ergebnismenge enthält nur Metadaten, keine Zeilendaten. Die Zeilen können mit der Funktion mysqli_stmt_fetch() über das Anweisungshandle abgerufen werden.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt ein Ergebnisobjekt zurück oder `false`, wenn ein Fehler aufgetreten ist.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->query("DROP TABLE IF EXISTS friends");
    $mysqli->query("CREATE TABLE friends (id int, name varchar(20))");

    $mysqli->query("INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $stmt = $mysqli->prepare("SELECT id, name FROM friends");
    $stmt->execute();

    /* Ergebnismenge der Metadaten abrufen */
    $result = $stmt->result_metadata();

    /* Informationen über die Spalten aus der Metadaten-Ergebnismenge abrufen */
    $field = $result->fetch_field();

    printf("Name der Spalte: %s\n", $field->name);

    /* Ergebnismenge schließen */
    $result->close();

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "DROP TABLE IF EXISTS friends");
    mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))");

    mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");

    $stmt = mysqli_prepare($link, "SELECT id, name FROM friends");
    mysqli_stmt_execute($stmt);

    /* Ergebnismenge der Metadaten abrufen */
    $result = mysqli_stmt_result_metadata($stmt);

    /* Informationen über die Spalten aus der Metadaten-Ergebnismenge abrufen */
    $field = mysqli_fetch_field($result);

    printf("Name der Spalte: %s\n", $field->name);

    /* Ergebnismenge schließen */
    mysqli_free_result($result);

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_free_result() - Gibt den mit einem Ergebnis verbundenen Speicher frei

# mysqli_stmt::send_long_data

# mysqli_stmt_send_long_data

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::send_long_data -- mysqli_stmt_send_long_data — Sendet Daten blockweise

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::send_long_data(int `$param_num`, string `$data`): bool

Prozeduraler Stil

function mysqli_stmt_send_long_data(mysqli_stmt `$statement`, int `$param_num`, string `$data`): bool

Damit werden Parameter blockweise zum Datenbank-Server geschickt, z. B. wenn die Größe eines BLOBs die Größe `max_allowed_packet` überschreitet. Die Funktion kann mehrmals aufgerufen werden, um Teile von Textdaten oder Binärdaten für eine Tabellenspalte zu verschicken. Die Tabellenspalte muss dabei den Typ TEXT oder BLOB haben.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

`param_num`

  Zeigt an, für welchen Parameter Daten geschickt werden. Die Parameter sind von Null an durchnummeriert.

`data`

  Eine Zeichenkette, die die Daten enthält, die gesendet werden sollen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $stmt = $mysqli->prepare("INSERT INTO messages (message) VALUES (?)");
    $null = NULL;
    $stmt->bind_param("b", $null);
    $fp = fopen("messages.txt", "r");
    while (!feof($fp)) {
        $stmt->send_long_data(0, fread($fp, 8192));
    }
    fclose($fp);
    $stmt->execute();
    ?>

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_bind_param() - Bindet Variablen als Parameter an eine vorbereitete Anweisung (prepared statement)

# mysqli_stmt::$sqlstate

# mysqli_stmt_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — Liefert den SQLSTATE-Fehlercode der letzten Anweisung

### Beschreibung

Objektorientierter Stil

string $mysqli_stmt->sqlstate;

Prozeduraler Stil

function mysqli_stmt_sqlstate(mysqli_stmt `$statement`): string

Gibt eine Zeichenkette mit dem SQLSTATE-Fehlercode der zuletzt aufgerufenen Funktion (des Prepared Statements) zurück, die entweder erfolgreich oder fehlerhaft beendet werden konnte. Der Fehlercode besteht aus fünf Zeichen. `'00000'` bedeutet kein Fehler. Die möglichen Werte sind durch ANSI SQL oder ODBC spezifiziert. Für eine Liste möglicher Werte siehe » http://dev.mysql.com/doc/mysql/en/error-handling.html.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt eine Zeichenkette mit dem SQLSTATE-Fehlercode des letzten Fehlers zurück. Der Fehlercode besteht aus fünf Zeichen. `'00000'` bedeutet kein Fehler.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    /* Datenbankverbindung öffnen */
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Datenbankverbindung prüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $mysqli->query("CREATE TABLE myCountry LIKE Country");
    $mysqli->query("INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = $mysqli->prepare($query)) {

        /* Tabelle löschen */
        $mysqli->query("DROP TABLE myCountry");

        /* Abfrage ausführen */
        $stmt->execute();

        printf("Fehler: %s.\n", $stmt->sqlstate);

        /* Abfrage-Objekt schließen */
        $stmt->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    /* Datenbankverbindung öffnen */
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Datenbankverbindung prüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    mysqli_query($link, "CREATE TABLE myCountry LIKE Country");
    mysqli_query($link, "INSERT INTO myCountry SELECT * FROM Country");

    $query = "SELECT Name, Code FROM myCountry ORDER BY Name";
    if ($stmt = mysqli_prepare($link, $query)) {

        /* Tabelle löschen */
        mysqli_query($link, "DROP TABLE myCountry");

        /* Abfrage ausführen */
        mysqli_stmt_execute($stmt);

        printf("Fehler: %s.\n", mysqli_stmt_sqlstate($stmt));

        /* Abfrage-Objekt schließen */
        mysqli_stmt_close($stmt);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Fehler: 42S02.

### Anmerkungen

> Hinweis:

> Anchtung! Nicht alle MySQL-Fehler können auf SQLSTATE-Codes abgebildet werden. Der Wert `HY000` (Allgemeiner Fehler) wird für nicht abgebildete MySQL-Fehler verwendet.

### Siehe auch

- mysqli_stmt_errno() - Liefert den Fehlercode der zuletzt aufgerufenen Anweisung
- mysqli_stmt_error() - Liefert die Beschreibung des letzten Fehlers einer Anweisung als Zeichenkette

# mysqli_stmt::store_result

# mysqli_stmt_store_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::store_result -- mysqli_stmt_store_result — Speichert eine Ergebnismenge in einem internen Puffer

### Beschreibung

Objektorientierter Stil

public function mysqli_stmt::store_result(): bool

Prozeduraler Stil

function mysqli_stmt_store_result(mysqli_stmt `$statement`): bool

Diese Funktion sollte nur aufgerufen werden, wenn die Abfrage eine gültige Ergebnismenge zurückgibt (z. B. `SELECT, SHOW, DESCRIBE, EXPLAIN`) und die komplette Ergebnismenge gepuffert werden muss. Jeder nachfolgende Aufruf von mysqli_stmt_fetch() liefert dann Daten aus dem Puffer.

> Hinweis:

> Es ist unnötig, mysqli_stmt_store_result() für andere Abfragen aufzurufen. Aber in keinem Fall schadet es oder benötigt merklich Laufzeit. Ob eine Abfrage eine Ergebnismenge zurückgibt, kann festgestellt werden, indem das Ergebnis von mysqli_stmt_result_metadata() auf `false` geprüft wird.

### Parameter-Liste

`statement`

  Nur bei prozeduralem Aufruf: ein von mysqli_stmt_init() zurückgegebenes mysqli_stmt-Objekt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = $mysqli->prepare($query);
    $stmt->execute();

    /* Das Ergebnis im internen Puffer speichern */
    $stmt->store_result();

    printf("Die Anzahl der Datensätze: %d.\n", $stmt->num_rows);

Beispiel #2 Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 20";
    $stmt = mysqli_prepare($link, $query);
    mysqli_stmt_execute($stmt);

    /* Das Ergebnis im internen Puffer speichern */
    mysqli_stmt_store_result($stmt);

    printf("Die Anzahl der Datensätze: %d.\n", mysqli_stmt_num_rows($stmt));

Die obigen Bespiele erzeugen folgende Ausgabe:

    Die Anzahl der Datensätze: 20.

### Siehe auch

- mysqli_prepare() - Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt_result_metadata() - Liefert die Metadaten der Ergebnismenge aus einer vorbereiteten Anweisung
- mysqli_stmt_fetch() - Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab

## Inhaltsverzeichnis

- mysqli_stmt::$affected_rows — Liefert die gesamte Anzahl der Datensätze, die bei der letzten ausgeführten Anweisung geändert, gelöscht, eingefügt oder abgeglichen wurden
- mysqli_stmt::attr_get — Liefert den aktuellen Wert des Attributs einer Anweisung
- mysqli_stmt::attr_set — Verändert das Verhalten einer vorbereiteten Anweisung (prepared statement)
- mysqli_stmt::bind_param — Bindet Variablen als Parameter an eine vorbereitete Anweisung (prepared statement)
- mysqli_stmt::bind_result — Bindet Variablen an eine vorbereitete Anweisung (prepared statement), um das Ergebnis einer Abfrage abzulegen
- mysqli_stmt::close — Schließt eine vorbereitete Anweisung (prepared statement)
- mysqli_stmt::__construct — Erzeugt ein neues mysqli_stmt-Objekt
- mysqli_stmt::data_seek — Verschiebt den Ergebniszeiger auf eine beliebige Zeile im gepufferten Ergebnis
- mysqli_stmt::$errno — Liefert den Fehlercode der zuletzt aufgerufenen Anweisung
- mysqli_stmt::$error — Liefert die Beschreibung des letzten Fehlers einer Anweisung als Zeichenkette
- mysqli_stmt::$error_list — Liefert eine Liste der Fehler der zuletzt ausgeführten Anweisung
- mysqli_stmt::execute — Führt eine vorbereitete Anweisung aus
- mysqli_stmt::fetch — Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab
- mysqli_stmt::$field_count — Liefert die Anzahl der Spalten in der angegebenen Anweisung
- mysqli_stmt::free_result — Gibt den mit der angegebenen Anweisung verbundenen Ergebnisspeicher frei
- mysqli_stmt::get_result — Ruft die Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab
- mysqli_stmt::get_warnings — Ermittelt das Ergebnis von SHOW WARNINGS
- mysqli_stmt::$insert_id — Ermittelt die ID, die beim letzten INSERT-Vorgang erzeugt wurde
- mysqli_stmt::more_results — Prüft, ob es weitere Ergebnisse aus einer Mehrfachabfrage gibt
- mysqli_stmt::next_result — Liest das nächste Ergebnis einer Mehrfachabfrage aus
- mysqli_stmt::$num_rows — Liefert die Anzahl der vom Server abgerufenen Datensätze
- mysqli_stmt::$param_count — Liefert die Anzahl der Parameter einer Anweisung
- mysqli_stmt::prepare — Bereitet eine SQL-Anweisung zur Ausführung vor
- mysqli_stmt::reset — Setzt eine vorbereitete Anweisung zurück
- mysqli_stmt::result_metadata — Liefert die Metadaten der Ergebnismenge aus einer vorbereiteten Anweisung
- mysqli_stmt::send_long_data — Sendet Daten blockweise
- mysqli_stmt::$sqlstate — Liefert den SQLSTATE-Fehlercode der letzten Anweisung
- mysqli_stmt::store_result — Speichert eine Ergebnismenge in einem internen Puffer

# Die Klasse mysqli_result

(PHP 5, PHP 7, PHP 8)

## Einführung

Stellt das Ergebnis einer Datenbankabfrage dar.

## Klassenbeschreibung

class mysqli_result implements IteratorAggregate {
/* Eigenschaften */
public readonly int $current_field;
public readonly int $field_count;
public readonly ?array $lengths;
public readonly int|string $num_rows;
public int $type;
/* Methoden */
public function __construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)
public function data_seek(int `$offset`): bool
public function fetch_all(int `$mode` = `MYSQLI_NUM`): array
public function fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false
public function fetch_assoc(): array|null|false
public function fetch_column(int `$column` = 0): null|int|float|string|false
public function fetch_field(): object|false
public function fetch_field_direct(int `$index`): object|false
public function fetch_fields(): array
public function fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false
public function fetch_row(): array|null|false
public function field_seek(int `$index`): true
public function free(): void
public function close(): void
public function free_result(): void
public function getIterator(): Iterator
}

## Eigenschaften

type

  Legt als Integer fest, ob das Ergebnis gepuffert werden soll (`MYSQLI_STORE_RESULT`) oder nicht (`MYSQLI_USE_RESULT`).

## Changelog

Version | Beschreibung
--- | ---
8.0.0 | mysqli_result implementiert nun IteratorAggregate. Zuvor wurde stattdessen Traversable implementiert.

# mysqli_result::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_result::__construct — Erstellt ein mysqli_result-Objekt

### Beschreibung

public function mysqli_result::__construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)

Diese Methode erstellt ein neues mysqli_result-Objekt.

Sie kann nach dem Aufruf einer der Funktionen mysqli_real_query() oder mysqli_multi_query() verwendet werden, um ein mysqli_result-Objekt zu erstellen. Das Objekt manuell zu konstruieren entspricht dem Aufruf der Funktionen mysqli_store_result() oder mysqli_use_result().

### Parameter-Liste

`mysql`

  Nur bei prozeduralem Aufruf: ein von mysqli_connect() oder mysqli_init() zurückgegebenes mysqli-Objekt.

`result_mode`

  Der Ergebnismodus kann eine von 2 Konstanten sein, die angeben, wie das Ergebnis vom MySQL-Server zurückgegeben wird.

  `MYSQLI_STORE_RESULT` (Standard) - erstellt ein mysqli_result-Objekt mit einer gepufferten Ergebnismenge.

  `MYSQLI_USE_RESULT` - erstellt ein mysqli_result-Objekt mit einer ungepufferten Ergebnismenge. Solange es noch Datensätze gibt, die darauf warten, abgerufen zu werden, ist die Verbindung belegt und alle nachfolgenden Aufrufe geben den Fehler `Commands out of sync` zurück. Um den Fehler zu vermeiden, müssen alle Datensätze vom Server abgerufen werden oder die Ergebnismenge muss durch den Aufruf der Funktion mysqli_free_result() verworfen werden. Die Verbindung muss offen bleiben, damit die Zeilen abgerufen werden können.

### Fehler/Exceptions

If mysqli error reporting is enabled (`MYSQLI_REPORT_ERROR`) and the requested operation fails, a warning is generated. If, in addition, the mode is set to `MYSQLI_REPORT_STRICT`, a mysqli_sql_exception is thrown instead.

### Beispiele

Beispiel #1 Erstellen eines mysqli_result-Objekts

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Select-Abfragen geben eine Ergebnismenge zurück */
    $mysqli->real_query("SELECT Name FROM City LIMIT 10");

    $result = new mysqli_result($mysqli);
    printf("Select gab %d Zeilen zurück.\n", $result->num_rows);

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Select gab 10 Zeilen zurück.

### Siehe auch

- mysqli_multi_query() - Führt eine oder mehrere Abfragen in einer Datenbank durch
- mysqli_real_query() - Führt eine SQL-Abfrage aus
- mysqli_store_result() - Überträgt die Ergebnismenge der letzten Abfrage
- mysqli_use_result() - Initiiert den Abruf einer Ergebnismenge

# mysqli_result::$current_field

# mysqli_field_tell

(PHP 5, PHP 7, PHP 8)

mysqli_result::$current_field -- mysqli_field_tell — Ermittelt den aktuellen Spalten-Offset eines Ergebniszeigers

### Beschreibung

Objektorientierter Stil

int $mysqli_result->current_field;

Prozeduraler Stil

function mysqli_field_tell(mysqli_result `$result`): int

Gibt die Position des Spaltenzeigers zurück, der beim letzten Aufruf der Funktion mysqli_fetch_field() verwendet wurde. Dieser Wert kann als Argument für mysqli_field_seek() verwendet werden.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

### Rückgabewerte

Gibt die aktuelle Position des Spaltenzeigers zurück.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Informationen über alle Spalten abrufen */
        while ($finfo = $result->fetch_field()) {

            /* Position des Spaltenzeigers ermitteln */
            $currentfield = $result->current_field;

            printf("Spalte %d:\n", $currentfield);
            printf("Name:       %s\n", $finfo->name);
            printf("Tabelle:    %s\n", $finfo->table);
            printf("max. Länge: %d\n", $finfo->max_length);
            printf("Flags:      %d\n", $finfo->flags);
            printf("Typ:        %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Informationen über alle Spalten abrufen */
        while ($finfo = mysqli_fetch_field($result)) {

            /* Position des Spaltenzeigers ermitteln */
            $currentfield = mysqli_field_tell($result);

            printf("Spalte %d:\n", $currentfield);
            printf("Name:       %s\n", $finfo->name);
            printf("Tabelle:    %s\n", $finfo->table);
            printf("max. Länge: %d\n", $finfo->max_length);
            printf("Flags:      %d\n", $finfo->flags);
            printf("Typ:        %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Spalte 1:
    Name:       Name
    Tabelle:    Country
    max. Länge: 11
    Flags:      1
    Typ:        254

    Spalte 2:
    Name:       SurfaceArea
    Tabelle:    Country
    max. Länge: 10
    Flags:      32769
    Typ:        4

### Siehe auch

- mysqli_fetch_field() - Liefert die Metadaten der nächsten Spalte einer Ergebnismenge
- mysqli_field_seek() - Setzt den Ergebniszeiger auf die angegebene Spalte

# mysqli_result::data_seek

# mysqli_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::data_seek -- mysqli_data_seek — Verschiebt den Ergebniszeiger auf die angegebene Zeile

### Beschreibung

Objektorientierter Stil

public function mysqli_result::data_seek(int `$offset`): bool

Prozeduraler Stil

function mysqli_data_seek(mysqli_result `$result`, int `$offset`): bool

Die Funktion mysqli_data_seek() verschiebt den Ergebniszeiger auf eine beliebige durch `offset` angegebene Zeile der Ergebnismenge.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

`offset`

  Der Zeilenversatz. Muss zwischen null und der Gesamtzahl der Zeilen minus eins liegen (0..mysqli_num_rows() - 1).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysqli::data_seek()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";
    $result = $mysqli->query($query);

    /* Zu Zeile 401 springen */
    $result->data_seek(400);

    /* Eine einzelne Zeile abrufen */
    $row = $result->fetch_row();

    printf("Stadt: %s  Ländercode: %s\n", $row[0], $row[1]);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name";

    $result = mysqli_query($link, $query);

    /* Zu Zeile 401 springen */
    mysqli_data_seek($result, 400);

    /* Eine einzelne Zeile abrufen */
    $row = mysqli_fetch_row($result);

    printf ("Stadt: %s  Ländercode: %s\n", $row[0], $row[1]);

Die obigen Bespiele erzeugen folgende Ausgabe:

    Stadt: Benin City  Ländercode: NGA

Beispiel #2 Anpassen des Ergebniszeigers beim Iterieren

Wenn über eine Ergebnismenge iteriert wird, ist diese Funktion nützlich, um eine benutzerdefinierte Reihenfolge festzulegen oder um den Ergebniszeiger bei mehrfacher Iteration zurückzusetzen.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY Name LIMIT 15,4";
    $result = $mysqli->query($query);

    /* Die Ergebnismenge in umgekehrter Reihenfolge durchlaufen */
    for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
        $result->data_seek($row_no);

        /* Eine einzelne Zeile abrufen */
        $row = $result->fetch_row();

        printf("Stadt: %s  Ländercode: %s\n", $row[0], $row[1]);
    }

    /* Den Zeiger auf den Anfang der Ergebnismenge zurücksetzen */
    $result->data_seek(0);

    print "\n";

    /* Die gleiche Ergebnismenge erneut durchlaufen */
    while ($row = $result->fetch_row()) {
        printf("Stadt: %s  Ländercode: %s\n", $row[0], $row[1]);
    }

Die obigen Bespiele erzeugen folgende Ausgabe:

    Stadt: Acmbaro  Ländercode: MEX
    Stadt: Abuja  Ländercode: NGA
    Stadt: Abu Dhabi  Ländercode: ARE
    Stadt: Abottabad  Ländercode: PAK

    Stadt: Abottabad  Ländercode: PAK
    Stadt: Abu Dhabi  Ländercode: ARE
    Stadt: Abuja  Ländercode: NGA
    Stadt: Acmbaro  Ländercode: MEX

### Anmerkungen

> Hinweis:

> Diese Funktion kann nur bei gepufferten Ergebnissen verwendet werden, die mit einer der Funktionen mysqli_store_result(), mysqli_query() oder mysqli_stmt_get_result() gewonnen wurden.

### Siehe auch

- mysqli_store_result() - Überträgt die Ergebnismenge der letzten Abfrage
- mysqli_fetch_row() - Liefert die nächste Zeile einer Ergebnismenge als numerisches Array
- mysqli_fetch_array() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab
- mysqli_fetch_assoc() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives Array ab
- mysqli_fetch_object() - Liefert die nächste Zeile einer Ergebnismenge als Objekt
- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_num_rows() - Ermittelt die Anzahl der Zeilen einer Ergebnismenge

# mysqli_result::fetch_all

# mysqli_fetch_all

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_result::fetch_all -- mysqli_fetch_all — Ruft alle Ergebniszeilen als assoziatives und/oder numerisches Array ab

### Beschreibung

Objektorientierter Stil

public function mysqli_result::fetch_all(int `$mode` = `MYSQLI_NUM`): array

Prozeduraler Stil

function mysqli_fetch_all(mysqli_result `$result`, int `$mode` = `MYSQLI_NUM`): array

Gibt ein zweidimensionales Array mit allen Ergebniszeilen als assoziative Arrays, numerische Arrays oder beides zurück.

> Hinweis:

> Vor PHP 8.1.0 war diese Funktion nur mit mysqlnd verfügbar.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

`mode`

  Dieser optionale Parameter gibt an, welcher Typ von Array aus den aktuellen Zeilendaten erzeugt werden soll. Die möglichen Werte für diesen Parameter sind die Konstanten `MYSQLI_ASSOC`, `MYSQLI_NUM` und `MYSQLI_BOTH`.

### Rückgabewerte

Gibt ein Array von assoziativen und/oder numerischen Arrays zurück, die die Ergebniszeilen enthalten.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Steht nun auch in Verbindung mit libmysqlclient zur Verfügung.

### Beispiele

Beispiel #1 mysqli_result::fetch_all()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    $rows = $result->fetch_all(MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($mysqli, "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3");

    $rows = mysqli_fetch_all($result, MYSQLI_ASSOC);
    foreach ($rows as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Die obigen Bespiele erzeugen folgende Ausgabe:

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Siehe auch

- mysqli_fetch_array() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab
- mysqli_fetch_column() - Ruft eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge ab
- mysqli_query() - Führt eine Abfrage in einer Datenbank durch

# mysqli_result::fetch_array

# mysqli_fetch_array

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_array -- mysqli_fetch_array — Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab

### Beschreibung

Objektorientierter Stil

public function mysqli_result::fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false

Prozeduraler Stil

function mysqli_fetch_array(mysqli_result `$result`, int `$mode` = `MYSQLI_BOTH`): array|null|false

Ruft eine Zeile der Daten aus der Ergebnismenge ab und gibt sie als Array zurück. Bei jedem weiteren Aufruf dieser Funktion wird die jeweils nächste Zeile der Ergebnismenge zurückgegeben oder `null`, wenn es keine weitere Zeile gibt.

Neben der Speicherung der Daten in einem Array mit numerischen Indizes kann diese Funktion die Daten auch in einem assoziativen Array speichern, indem sie die Feldnamen der Ergebnismenge als Schlüssel verwendet.

Wenn zwei oder mehr Spalten des Ergebnisses den gleichen Namen haben, hat die letzte Spalte Vorrang und überschreibt alle vorherigen Daten. Um auf mehrere Spalten mit demselben Namen zuzugreifen, muss die numerisch indizierte Version der Zeile verwendet werden.

> Hinweis: Bei den Spaltennamen, die von dieser Funktion zurückgegeben werden, wird zwischen Groß- und Kleinschreibung unterschieden.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

`mode`

  Dieser optionale Parameter gibt an, welcher Typ von Array aus den aktuellen Zeilendaten erzeugt werden soll. Die möglichen Werte für diesen Parameter sind die Konstanten `MYSQLI_ASSOC`, `MYSQLI_NUM` und `MYSQLI_BOTH`.

  Mit der Konstante `MYSQLI_ASSOC` verhält sich diese Funktion genauso wie die Funktion mysqli_fetch_assoc(), während sie sich mit `MYSQLI_NUM` genauso verhält wie die Funktion mysqli_fetch_row(). Die letzte Option, `MYSQLI_BOTH`, erzeugt ein einziges Array mit den Eigenschaften beider Funktionen.

### Rückgabewerte

Gibt ein Array zurück, das die abgerufene Zeile enthält oder `null`, wenn es in der Ergebnismenge keine weitere Zeile gibt. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysqli_result::fetch_array()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID LIMIT 3";
    $result = $mysqli->query($query);

    /* numerisches Array */
    $row = $result->fetch_array(MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* assoziatives Array */
    $row = $result->fetch_array(MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* assoziatives und numerisches Array */
    $row = $result->fetch_array(MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER by ID LIMIT 3";
    $result = mysqli_query($mysqli, $query);

    /* numerisches Array */
    $row = mysqli_fetch_array($result, MYSQLI_NUM);
    printf("%s (%s)\n", $row[0], $row[1]);

    /* assoziatives Array */
    $row = mysqli_fetch_array($result, MYSQLI_ASSOC);
    printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);

    /* assoziatives und numerisches Array */
    $row = mysqli_fetch_array($result, MYSQLI_BOTH);
    printf("%s (%s)\n", $row[0], $row["CountryCode"]);

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Kabul (AFG)
    Qandahar (AFG)
    Herat (AFG)

### Siehe auch

- mysqli_fetch_assoc() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives Array ab
- mysqli_fetch_column() - Ruft eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge ab
- mysqli_fetch_row() - Liefert die nächste Zeile einer Ergebnismenge als numerisches Array
- mysqli_fetch_object() - Liefert die nächste Zeile einer Ergebnismenge als Objekt
- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_data_seek() - Verschiebt den Ergebniszeiger auf die angegebene Zeile

# mysqli_result::fetch_assoc

# mysqli_fetch_assoc

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_assoc -- mysqli_fetch_assoc — Ruft die nächste Zeile einer Ergebnismenge als assoziatives Array ab

### Beschreibung

Objektorientierter Stil

public function mysqli_result::fetch_assoc(): array|null|false

Prozeduraler Stil

function mysqli_fetch_assoc(mysqli_result `$result`): array|null|false

Ruft eine Zeile der Daten aus der Ergebnismenge ab und gibt sie als assoziatives Array zurück. Bei jedem weiteren Aufruf dieser Funktion wird die jeweils nächste Zeile der Ergebnismenge zurückgegeben oder `null`, wenn es keine weitere Zeile gibt.

Wenn zwei oder mehr Spalten des Ergebnisses den gleichen Namen haben, hat die letzte Spalte Vorrang und überschreibt alle vorherigen Daten. Um auf mehrere Spalten mit demselben Namen zuzugreifen, kann die Funktion mysqli_fetch_row() verwendet werden, mit der ein numerisch indiziertes Array abgerufen wird, oder es können Aliase in der Select-Liste der SQL-Abfrage verwendet werden, um den Spalten unterschiedliche Namen zu geben.

> Hinweis: Bei den Spaltennamen, die von dieser Funktion zurückgegeben werden, wird zwischen Groß- und Kleinschreibung unterschieden.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

### Rückgabewerte

Gibt ein assoziatives Array zurück, das die abgerufene Zeile enthält, wobei jeder Schlüssel des Arrays den Namen einer der Spalten der Ergebnismenge darstellt, oder `null`, wenn es in der Ergebnismenge keine weitere Zeile gibt. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysqli_result::fetch_assoc()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* Abrufen eines assoziativen Arrays */
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* Abrufen eines assoziativen Arrays */
    while ($row = mysqli_fetch_assoc($result)) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

Beispiel #2 Vergleich der Verwendung von mysqli_result iterator und mysqli_result::fetch_assoc()

mysqli_result kann mit `foreach` iteriert werden. Die Ergebnismenge wird immer ab der ersten Zeile durchlaufen, unabhängig von der aktuellen Position.

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = 'SELECT Name, CountryCode FROM City ORDER BY ID DESC';

    // Mit Iterator
    $result = $mysqli->query($query);
    foreach ($result as $row) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

    echo "\n==================\n";

    // Ohne Iterator
    $result = $mysqli->query($query);
    while ($row = $result->fetch_assoc()) {
        printf("%s (%s)\n", $row["Name"], $row["CountryCode"]);
    }

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

    ==================
    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Siehe auch

- mysqli_fetch_array() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab
- mysqli_fetch_column() - Ruft eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge ab
- mysqli_fetch_row() - Liefert die nächste Zeile einer Ergebnismenge als numerisches Array
- mysqli_fetch_object() - Liefert die nächste Zeile einer Ergebnismenge als Objekt
- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_data_seek() - Verschiebt den Ergebniszeiger auf die angegebene Zeile

# mysqli_result::fetch_column

# mysqli_fetch_column

(PHP 8 >= 8.1.0)

mysqli_result::fetch_column -- mysqli_fetch_column — Ruft eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge ab

### Beschreibung

Objektorientierter Stil

public function mysqli_result::fetch_column(int `$column` = 0): null|int|float|string|false

Prozeduraler Stil

function mysqli_fetch_column(mysqli_result `$result`, int `$column` = 0): null|int|float|string|false

Ruft eine Zeile aus der Ergebnismenge ab und gibt den Wert der durch den nullbasierten Index angegebenen Spalte zurück. Jeder nachfolgende Aufruf dieser Funktion gibt den Wert aus der nächsten Zeile der Ergebnismenge zurück oder `false`, wenn es keine weitere Zeile gibt.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

`column`

  Die Nummer der nullbasierten Spalte, die aus der Zeile abgerufen werden soll. Wenn kein Wert angegeben wird, wird der Wert der ersten Spalte zurückgegeben.

### Rückgabewerte

Gibt den Wert einer einzelnen Spalte aus der nächsten Zeile einer Ergebnismenge zurück oder `false`, wenn es keine weitere Zeile gibt.

Warnung

Mit dieser Funktion ist es nicht möglich, eine weitere Spalte aus derselben Zeile zurückzugeben.

### Beispiele

Beispiel #1 mysqli_result::fetch_column()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

    $result = $mysqli->query($query);

    /* einen einzelnen Wert aus der zweiten Spalte abrufen */
    while ($Name = $result->fetch_column(1)) {
        printf("%s\n", $Name);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT CountryCode, Name FROM City ORDER BY ID DESC LIMIT 5";

    $result = mysqli_query($mysqli, $query);

    /* einen einzelnen Wert aus der zweiten Spalte abrufen */
    while ($Name = mysqli_fetch_column($result, 1)) {
        printf("%s\n", $Name);
    }

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Rafah
    Nablus
    Jabaliya
    Hebron
    Khan Yunis

### Siehe auch

- mysqli_fetch_all() - Ruft alle Ergebniszeilen als assoziatives und/oder numerisches Array ab
- mysqli_fetch_array() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab
- mysqli_fetch_assoc() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives Array ab
- mysqli_fetch_object() - Liefert die nächste Zeile einer Ergebnismenge als Objekt
- mysqli_fetch_row() - Liefert die nächste Zeile einer Ergebnismenge als numerisches Array
- mysqli_data_seek() - Verschiebt den Ergebniszeiger auf die angegebene Zeile

# mysqli_result::fetch_field

# mysqli_fetch_field

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field -- mysqli_fetch_field — Liefert die Metadaten der nächsten Spalte einer Ergebnismenge

### Beschreibung

Objektorientierter Stil

public function mysqli_result::fetch_field(): object|false

Prozeduraler Stil

function mysqli_fetch_field(mysqli_result `$result`): object|false

Gibt die Definition einer Spalte aus einer Ergebnismenge als Objekt zurück. Um Informationen über alle Spalten in der Ergebnismenge abzurufen, muss diese Funktion mehrmals aufgerufen werden.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

### Rückgabewerte

Gibt ein Objekt zurück, das die Informationen über die Definition einer Spalte enthält, oder `false`, wenn keine Spalteninformationen verfügbar sind.

Eigenschaften des Objekts
Eigenschaft | Beschreibung
--- | ---
name | Der Name der Spalte
orgname | Der ursprüngliche Name der Spalte, falls ein Alias angegeben wurde
table | Der Name der Tabelle, zu der diese Spalte gehört (falls nicht berechnet)
orgtable | Der ursprüngliche Name der Tabelle, falls ein Alias angegeben wurde
def | Nicht verwendet; immer eine leere Zeichenkette
db | Der Name der Datenbank
catalog | Nicht verwendet; immer `"def"`
max_length | Die maximale Breite der Spalte für die Ergebnismenge. Seit PHP 8.1 ist dieser Wert immer `0`.
length | Die Breite der Spalte in Bytes. Bei Zeichenkettenspalten hängt der Längenwert vom Zeichensatz der Verbindung ab. Ist der Zeichensatz z. B. ein Ein-Byte-Zeichensatz wie `latin1`, beträgt der Längenwert für eine `SELECT 'abc'`-Abfrage 3. Ist der Zeichensatz ein Multibyte-Zeichensatz wie `utf8mb4`, bei dem die Zeichen bis zu 4 Bytes umfassen, beträgt der Längenwert 12.
charsetnr | Die Nummer des Zeichensatzes der Spalte
flags | Ein Integer, der die Bit-Flags der Spalte darstellt
type | Der für diese Spalte verwendete Datentyp
decimals | Bei numerischen Spalten die Anzahl der Dezimalstellen, bei Zeitspalten die Genauigkeit der Sekundenbruchteile.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Informationen über alle Spalten abrufen */
        while ($finfo = $result->fetch_field()) {

            printf("Name:       %s\n", $finfo->name);
            printf("Tabelle:    %s\n", $finfo->table);
            printf("max. Länge: %d\n", $finfo->max_length);
            printf("Flags:      %d\n", $finfo->flags);
            printf("Typ:        %d\n\n", $finfo->type);
        }
        $result->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Informationen über alle Spalten abrufen */
        while ($finfo = mysqli_fetch_field($result)) {

            printf("Name:       %s\n", $finfo->name);
            printf("Tabelle:    %s\n", $finfo->table);
            printf("max. Länge: %d\n", $finfo->max_length);
            printf("Flags:      %d\n", $finfo->flags);
            printf("Typ:        %d\n\n", $finfo->type);
        }
        mysqli_free_result($result);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Name:       Name
    Tabelle:    Country
    max. Länge: 11
    Flags:      1
    Typ:        254

    Name:       SurfaceArea
    Tabelle:    Country
    max. Länge: 10
    Flags:      32769
    Typ:        4

### Siehe auch

- mysqli_num_fields() - Ermittelt die Anzahl der Spalten in der Ergebnismenge
- mysqli_fetch_field_direct() - Ruft die Metadaten für eine einzelne Spalte ab
- mysqli_fetch_fields() - Liefert ein Array von Objekten, die die Spalten einer Ergebnismenge darstellen
- mysqli_field_seek() - Setzt den Ergebniszeiger auf die angegebene Spalte

# mysqli_result::fetch_field_direct

# mysqli_fetch_field_direct

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — Ruft die Metadaten für eine einzelne Spalte ab

### Beschreibung

Objektorientierter Stil

public function mysqli_result::fetch_field_direct(int `$index`): object|false

Prozeduraler Stil

function mysqli_fetch_field_direct(mysqli_result `$result`, int `$index`): object|false

Gibt ein Objekt zurück, das die Informationen über die Definition einer Spalte aus der angegebenen Ergebnismenge enthält.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

`index`

  Die Nummer der Spalte. Dieser Wert muss im Bereich von `0` bis `Anzahl der Spalten - 1` liegen.

### Rückgabewerte

Gibt ein Objekt zurück, das die Informationen über die Definition einer Spalte enthält, oder `false`, wenn für die angegebene `index` keine Feldinformationen verfügbar sind.

Eigenschaften des Objekts
Eigenschaft | Beschreibung
--- | ---
name | Der Name der Spalte
orgname | Der ursprüngliche Name der Spalte, falls ein Alias angegeben wurde
table | Der Name der Tabelle, zu der diese Spalte gehört (falls nicht berechnet)
orgtable | Der ursprüngliche Name der Tabelle, falls ein Alias angegeben wurde
def | Nicht verwendet; immer eine leere Zeichenkette
db | Der Name der Datenbank
catalog | Nicht verwendet; immer `"def"`
max_length | Die maximale Breite der Spalte für die Ergebnismenge. Seit PHP 8.1 ist dieser Wert immer `0`.
length | Die Breite der Spalte in Bytes. Bei Zeichenkettenspalten hängt der Längenwert vom Zeichensatz der Verbindung ab. Ist der Zeichensatz z. B. ein Ein-Byte-Zeichensatz wie `latin1`, beträgt der Längenwert für eine `SELECT 'abc'`-Abfrage 3. Ist der Zeichensatz ein Multibyte-Zeichensatz wie `utf8mb4`, bei dem die Zeichen bis zu 4 Bytes umfassen, beträgt der Längenwert 12.
charsetnr | Die Nummer des Zeichensatzes der Spalte
flags | Ein Integer, der die Bit-Flags der Spalte darstellt
type | Der für diese Spalte verwendete Datentyp
decimals | Bei numerischen Spalten die Anzahl der Dezimalstellen, bei Zeitspalten die Genauigkeit der Sekundenbruchteile.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Informationen über die Spalte 'SurfaceArea' abrufen */
        $finfo = $result->fetch_field_direct(1);

        printf("Name:       %s\n", $finfo->name);
        printf("Tabelle:    %s\n", $finfo->table);
        printf("max. Länge: %d\n", $finfo->max_length);
        printf("Flags:      %d\n", $finfo->flags);
        printf("Typ:        %d\n", $finfo->type);

        $result->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Name LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Informationen über die Spalte 'SurfaceArea' abrufen */
        $finfo = mysqli_fetch_field_direct($result, 1);

        printf("Name:       %s\n", $finfo->name);
        printf("Tabelle:    %s\n", $finfo->table);
        printf("max. Länge: %d\n", $finfo->max_length);
        printf("Flags:      %d\n", $finfo->flags);
        printf("Typ:        %d\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Name:       SurfaceArea
    Tabelle:    Country
    max. Länge: 10
    Flags:      32769
    Typ:        4

### Siehe auch

- mysqli_num_fields() - Ermittelt die Anzahl der Spalten in der Ergebnismenge
- mysqli_fetch_field() - Liefert die Metadaten der nächsten Spalte einer Ergebnismenge
- mysqli_fetch_fields() - Liefert ein Array von Objekten, die die Spalten einer Ergebnismenge darstellen

# mysqli_result::fetch_fields

# mysqli_fetch_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_fields -- mysqli_fetch_fields — Liefert ein Array von Objekten, die die Spalten einer Ergebnismenge darstellen

### Beschreibung

Objektorientierter Stil

public function mysqli_result::fetch_fields(): array

Prozeduraler Stil

function mysqli_fetch_fields(mysqli_result `$result`): array

Diese Funktion erfüllt den gleichen Zweck wie die Funktion mysqli_fetch_field(), mit dem einzigen Unterschied, dass die Spalten als Array von Objekten zurückgegeben werden, anstatt für jede Spalte ein einzelnes Objekt zurückzugeben.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

### Rückgabewerte

Gibt ein Array von Objekten zurück, die die Informationen über die Definition der Spalten enthalten.

Eigenschaften des Objekts
Eigenschaft | Beschreibung
--- | ---
name | Der Name der Spalte
orgname | Der ursprüngliche Name der Spalte, falls ein Alias angegeben wurde
table | Der Name der Tabelle, zu der diese Spalte gehört (falls nicht berechnet)
orgtable | Der ursprüngliche Name der Tabelle, falls ein Alias angegeben wurde
def | Nicht verwendet; immer eine leere Zeichenkette
db | Der Name der Datenbank
catalog | Nicht verwendet; immer `"def"`
max_length | Die maximale Breite der Spalte für die Ergebnismenge. Seit PHP 8.1 ist dieser Wert immer `0`.
length | Die Breite der Spalte in Bytes. Bei Zeichenkettenspalten hängt der Längenwert vom Zeichensatz der Verbindung ab. Ist der Zeichensatz z. B. ein Ein-Byte-Zeichensatz wie `latin1`, beträgt der Längenwert für eine `SELECT 'abc'`-Abfrage 3. Ist der Zeichensatz ein Multibyte-Zeichensatz wie `utf8mb4`, bei dem die Zeichen bis zu 4 Bytes umfassen, beträgt der Längenwert 12.
charsetnr | Die Nummer des Zeichensatzes der Spalte
flags | Ein Integer, der die Bit-Flags der Spalte darstellt
type | Der für diese Spalte verwendete Datentyp
decimals | Bei numerischen Spalten die Anzahl der Dezimalstellen, bei Zeitspalten die Genauigkeit der Sekundenbruchteile.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $mysqli = new mysqli("127.0.0.1", "root", "foofoo", "sakila");

    /* Verbindung überprüfen */
    if ($mysqli->connect_errno) {
        printf("Verbindung fehlgeschlagen: %s\n", $mysqli->connect_error);
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Zeichensatz ändern, um dessen Auswirkung auf einige Werte
        // (z. B. die Länge in Bytes) zu zeigen
        $mysqli->set_charset($charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "======================\n";
        echo "Zeichensatz: $charset\n";
        echo "======================\n";

        if ($result = $mysqli->query($query)) {

            /* Informationen über alle Spalten abrufen */
            $finfo = $result->fetch_fields();

            foreach ($finfo as $val) {
                printf("Name:            %s\n",   $val->name);
                printf("Tabelle:         %s\n",   $val->table);
                printf("max. Länge:      %d\n",   $val->max_length);
                printf("Länge:           %d\n",   $val->length);
                printf("Zeichensatz-Nr.: %d\n",   $val->charsetnr);
                printf("Flags:           %d\n",   $val->flags);
                printf("Typ:             %d\n\n", $val->type);
            }
            $result->free();
        }
    }
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    foreach (array('latin1', 'utf8') as $charset) {

        // Zeichensatz ändern, um dessen Auswirkung auf einige Werte
        // (z. B. die Länge in Bytes) zu zeigen
        mysqli_set_charset($link, $charset);

        $query = "SELECT actor_id, last_name from actor ORDER BY actor_id";

        echo "======================\n";
        echo "Zeichensatz: $charset\n";
        echo "======================\n";

        if ($result = mysqli_query($link, $query)) {

            /* Informationen über alle Spalten abrufen */
            $finfo = mysqli_fetch_fields($result);

            foreach ($finfo as $val) {
                printf("Name:            %s\n",   $val->name);
                printf("Tabelle:         %s\n",   $val->table);
                printf("max. Länge:      %d\n",   $val->max_length);
                printf("Länge:           %d\n",   $val->length);
                printf("Zeichensatz-Nr.: %d\n",   $val->charsetnr);
                printf("Flags:           %d\n",   $val->flags);
                printf("Typ:             %d\n\n", $val->type);
            }
            mysqli_free_result($result);
        }
    }

    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    ======================
    Zeichensatz: latin1
    ======================
    Name:            actor_id
    Tabelle:         actor
    max. Länge:      3
    Länge:           5
    Zeichensatz-Nr.: 63
    Flags:           49699
    Typ:             2

    Name:            last_name
    Tabelle:         actor
    max. Länge:      12
    Länge:           45
    Zeichensatz-Nr.: 8
    Flags:           20489
    Typ:             253

    ======================
    Zeichensatz: utf8
    ======================
    Name:            actor_id
    Tabelle:         actor
    max. Länge:      3
    Länge:           5
    Zeichensatz-Nr.: 63
    Flags:           49699
    Typ:             2

    Name:            last_name
    Tabelle:         actor
    max. Länge:      12
    Länge:           135
    Zeichensatz-Nr.: 33
    Flags:           20489

### Siehe auch

- mysqli_num_fields() - Ermittelt die Anzahl der Spalten in der Ergebnismenge
- mysqli_fetch_field_direct() - Ruft die Metadaten für eine einzelne Spalte ab
- mysqli_fetch_field() - Liefert die Metadaten der nächsten Spalte einer Ergebnismenge

# mysqli_result::fetch_object

# mysqli_fetch_object

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_object -- mysqli_fetch_object — Liefert die nächste Zeile einer Ergebnismenge als Objekt

### Beschreibung

Objektorientierter Stil

public function mysqli_result::fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Prozeduraler Stil

function mysqli_fetch_object(mysqli_result `$result`, string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

Ruft eine Zeile aus der Ergebnismenge ab und gibt sie als Objekt zurück, wobei die Eigenschaften die Namen der Spalten der Ergebnismenge darstellen. Jeder nachfolgende Aufruf dieser Funktion gibt die nächste Zeile der Ergebnismenge zurück oder `null`, wenn es keine weitere Zeile gibt.

Wenn zwei oder mehr Spalten des Ergebnisses den gleichen Namen haben, hat die letzte Spalte Vorrang und überschreibt alle vorherigen Daten. Um auf mehrere Spalten mit demselben Namen zuzugreifen, kann die Funktion mysqli_fetch_row() verwendet werden, um ein numerisch indiziertes Array abzurufen, oder es können Aliase in der Select-Liste der SQL-Abfrage verwendet werden, um den Spalten unterschiedliche Namen zu geben.

> Hinweis: Diese Funktion legt die Eigenschaften des Objekts fest, bevor sie den Konstruktor des Objekts aufruft.

> Hinweis: Bei den Spaltennamen, die von dieser Funktion zurückgegeben werden, wird zwischen Groß- und Kleinschreibung unterschieden.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

`class`

  Der Name der Klasse, die instanziiert, mit ihren Eigenschaften versehen und zurückgegeben werden soll. Wenn nicht angegeben, wird ein stdClass-Objekt zurückgegeben.

`constructor_args`

  Ein optionales Array von Parametern, das an den Konstruktor des Objekts `class` übergeben werden soll.

### Rückgabewerte

Gibt ein Objekt zurück, das die abgerufene Zeile enthält, wobei die Eigenschaften die Namen der Spalten der Ergebnismenge angeben, oder `null`, wenn es keine weitere Zeile in der Ergebnismenge gibt. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn `constructor_args` nicht leer ist, die Klasse aber keinen Konstruktor hat, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wenn `constructor_args` nicht leer ist, die Klasse aber keinen Konstruktor hat, wird nun ein ValueError geworfen; zuvor wurde eine Exception geworfen.
8.0.0 | Der Parameter `constructor_args` akzeptiert bei Konstruktoren mit 0 Parametern nun `[]`; zuvor wurde eine Exception geworfen.

### Beispiele

Beispiel #1 mysqli_result::fetch_object()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    while ($obj = $result->fetch_object()) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($link, $query);

    while ($obj = mysqli_fetch_object($result)) {
        printf("%s (%s)\n", $obj->Name, $obj->CountryCode);
    }

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Siehe auch

- mysqli_fetch_array() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab
- mysqli_fetch_assoc() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives Array ab
- mysqli_fetch_column() - Ruft eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge ab
- mysqli_fetch_row() - Liefert die nächste Zeile einer Ergebnismenge als numerisches Array
- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_data_seek() - Verschiebt den Ergebniszeiger auf die angegebene Zeile

# mysqli_result::fetch_row

# mysqli_fetch_row

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_row -- mysqli_fetch_row — Liefert die nächste Zeile einer Ergebnismenge als numerisches Array

### Beschreibung

Objektorientierter Stil

public function mysqli_result::fetch_row(): array|null|false

Prozeduraler Stil

function mysqli_fetch_row(mysqli_result `$result`): array|null|false

Ruft eine Zeile aus der Ergebnismenge ab und gibt sie als numerisches Array zurück, wobei die Indizes den Spaltennummern (bei 0 beginnend) entsprechen. Jeder nachfolgende Aufruf dieser Funktion gibt die nächste Zeile innerhalb der Ergebnismenge zurück oder `null`, wenn es keine weitere Zeile gibt.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

### Rückgabewerte

Gibt ein numerisches Array zurück, das die abgerufene Zeile enthält oder `null`, wenn es keine weitere Zeile in der Ergebnismenge gibt. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysqli_result::fetch_row()-Beispiel

Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = $mysqli->query($query);

    /* Assoziatives Array abrufen */
    while ($row = $result->fetch_row()) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");

    $query = "SELECT Name, CountryCode FROM City ORDER BY ID DESC";

    $result = mysqli_query($mysqli, $query);

    /* Assoziatives Array abrufen */
    while ($row = mysqli_fetch_row($result)) {
        printf("%s (%s)\n", $row[0], $row[1]);
    }

Oben gezeigte Beispiele erzeugen eine ähnliche Ausgabe wie:

    Pueblo (USA)
    Arvada (USA)
    Cape Coral (USA)
    Green Bay (USA)
    Santa Clara (USA)

### Siehe auch

- mysqli_fetch_array() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab
- mysqli_fetch_assoc() - Ruft die nächste Zeile einer Ergebnismenge als assoziatives Array ab
- mysqli_fetch_column() - Ruft eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge ab
- mysqli_fetch_object() - Liefert die nächste Zeile einer Ergebnismenge als Objekt
- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_data_seek() - Verschiebt den Ergebniszeiger auf die angegebene Zeile

# mysqli_result::$field_count

# mysqli_num_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::$field_count -- mysqli_num_fields — Ermittelt die Anzahl der Spalten in der Ergebnismenge

### Beschreibung

Objektorientierter Stil

int $mysqli_result->field_count;

Prozeduraler Stil

function mysqli_num_fields(mysqli_result `$result`): int

Gib die Anzahl der Spalten in der Ergebnismenge zurück.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

### Rückgabewerte

Gibt die Anzahl der Spalten als int zurück.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Anzahl der Spalten in der Ergebnismenge ermitteln */
    $field_cnt = $result->field_count;

    printf("Die Ergebnismenge enthält %d Spalten.\n", $field_cnt);

Beispiel #2 Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Name, CountryCode, District, Population FROM City ORDER BY ID LIMIT 1");

    /* Anzahl der Spalten in der Ergebnismenge ermitteln */
    $field_cnt = mysqli_num_fields($result);

    printf("Die Ergebnismenge enthält %d Spalten.\n", $field_cnt);

Die obigen Bespiele erzeugen folgende Ausgabe:

    Die Ergebnismenge enthält 4 Spalten.

### Siehe auch

- mysqli_fetch_field() - Liefert die Metadaten der nächsten Spalte einer Ergebnismenge

# mysqli_result::field_seek

# mysqli_field_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::field_seek -- mysqli_field_seek — Setzt den Ergebniszeiger auf die angegebene Spalte

### Beschreibung

Objektorientierter Stil

public function mysqli_result::field_seek(int `$index`): true

Prozeduraler Stil

function mysqli_field_seek(mysqli_result `$result`, int `$index`): true

Setzt den Spaltenzeiger auf den angegebenen Offset. Der nächste Aufruf von mysqli_fetch_field() ruft die Definition der mit diesem Offset verbundenen Spalte ab.

> Hinweis:

> Um an den Anfang einer Zeile zu springen, muss ein Offset-Wert von Null übergeben werden.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

`index`

  Die Nummer der Spalte. Dieser Wert muss im Bereich von `0` bis `Anzahl der Spalten - 1` liegen.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion gibt nun immer `true` zurück; vorher gab sie bei einem Fehler `false` zurück.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = $mysqli->query($query)) {

        /* Informationen über die zweite Spalte abrufen */
        $result->field_seek(1);
        $finfo = $result->fetch_field();

        printf("Name:       %s\n", $finfo->name);
        printf("Tabelle:    %s\n", $finfo->table);
        printf("max. Länge: %d\n", $finfo->max_length);
        printf("Flags:      %d\n", $finfo->flags);
        printf("Typ:        %d\n\n", $finfo->type);

        $result->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT Name, SurfaceArea from Country ORDER BY Code LIMIT 5";

    if ($result = mysqli_query($link, $query)) {

        /* Informationen über die zweite Spalte abrufen */
        mysqli_field_seek($result, 1);
        $finfo = mysqli_fetch_field($result);

        printf("Name:       %s\n", $finfo->name);
        printf("Tabelle:    %s\n", $finfo->table);
        printf("max. Länge: %d\n", $finfo->max_length);
        printf("Flags:      %d\n", $finfo->flags);
        printf("Typ:        %d\n\n", $finfo->type);

        mysqli_free_result($result);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Name:       SurfaceArea
    Tabelle:    Country
    max. Länge: 10
    Flags:      32769
    Typ:        4

### Siehe auch

- mysqli_fetch_field() - Liefert die Metadaten der nächsten Spalte einer Ergebnismenge

# mysqli_result::free

# mysqli_result::close

# mysqli_result::free_result

# mysqli_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_result::free -- mysqli_result::close -- mysqli_result::free_result -- mysqli_free_result — Gibt den mit einem Ergebnis verbundenen Speicher frei

### Beschreibung

Objektorientierter Stil

public function mysqli_result::free(): void
public function mysqli_result::close(): void
public function mysqli_result::free_result(): void

Prozeduraler Stil

function mysqli_free_result(mysqli_result `$result`): void

Gibt den mit dem Ergebnis `result` verbundenen Speicher frei.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_stmt_get_result() - Ruft die Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab
- mysqli_store_result() - Überträgt die Ergebnismenge der letzten Abfrage
- mysqli_use_result() - Initiiert den Abruf einer Ergebnismenge

# mysqli_result::getIterator

(PHP 8)

mysqli_result::getIterator — Ruft einen externen Iterator ab

### Beschreibung

public function mysqli_result::getIterator(): Iterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# mysqli_result::$lengths

# mysqli_fetch_lengths

(PHP 5, PHP 7, PHP 8)

mysqli_result::$lengths -- mysqli_fetch_lengths — Liefert die Breiten der Spalten der aktuellen Zeile einer Ergebnismenge

### Beschreibung

Objektorientierter Stil

?array $mysqli_result->lengths;

Prozeduraler Stil

function mysqli_fetch_lengths(mysqli_result `$result`): array|false

Die Funktion mysqli_fetch_lengths() gibt ein Array zurück, das die Breiten aller Spalten der aktuellen Zeile aus der Ergebnismenge enthält.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

### Rückgabewerte

Gibt ein Array von ganzen Zahlen zurück, die die Breite jeder Spalte angeben (ohne abschließende Nullzeichen), oder `false`, wenn ein Fehler aufgetreten ist.

Die Funktion mysqli_fetch_lengths() gilt nur für die aktuelle Zeile der Ergebnismenge. Sie gibt `false` zurück, wenn sie vor mysqli_fetch_row/array/object aufgerufen wird oder nachdem alle Zeilen des Ergebnisses abgerufen wurden.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = $mysqli->query($query)) {

        $row = $result->fetch_row();

        /* Spaltenbreiten anzeigen */
        foreach ($result->lengths as $i => $val) {
            printf("Die Spalte %2d hat eine Breite von %2d\n", $i+1, $val);
        }
        $result->close();
    }

    /* Verbindung schließen */
    $mysqli->close();
    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    /* Verbindung überprüfen */
    if (mysqli_connect_errno()) {
        printf("Verbindung fehlgeschlagen: %s\n", mysqli_connect_error());
        exit();
    }

    $query = "SELECT * from Country ORDER BY Code LIMIT 1";

    if ($result = mysqli_query($link, $query)) {

        $row = mysqli_fetch_row($result);

        /* Spaltenbreiten anzeigen */
        foreach (mysqli_fetch_lengths($result) as $i => $val) {
            printf("Die Spalte %2d hat eine Breite von %2d\n", $i+1, $val);
        }
        mysqli_free_result($result);
    }

    /* Verbindung schließen */
    mysqli_close($link);
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Die Spalte  1 hat eine Breite von  3
    Die Spalte  2 hat eine Breite von  5
    Die Spalte  3 hat eine Breite von 13
    Die Spalte  4 hat eine Breite von  9
    Die Spalte  5 hat eine Breite von  6
    Die Spalte  6 hat eine Breite von  1
    Die Spalte  7 hat eine Breite von  6
    Die Spalte  8 hat eine Breite von  4
    Die Spalte  9 hat eine Breite von  6
    Die Spalte 10 hat eine Breite von  6
    Die Spalte 11 hat eine Breite von  5
    Die Spalte 12 hat eine Breite von 44
    Die Spalte 13 hat eine Breite von  7
    Die Spalte 14 hat eine Breite von  3
    Die Spalte 15 hat eine Breite von  2

# mysqli_result::$num_rows

# mysqli_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_result::$num_rows -- mysqli_num_rows — Ermittelt die Anzahl der Zeilen einer Ergebnismenge

### Beschreibung

Objektorientierter Stil

int|string $mysqli_result->num_rows;

Prozeduraler Stil

function mysqli_num_rows(mysqli_result `$result`): int|string

Gibt die Anzahl der Zeilen in der Ergebnismenge zurück.

Das Verhalten von mysqli_num_rows() hängt davon ab, ob eine gepufferte oder eine ungepufferte Ergebnismenge verwendet wird. Wenn bei einer ungepufferten Ergebnismenge nicht alle Zeilen vom Server abgerufen wurden, gibt diese Funktion `0` zurück.

### Parameter-Liste

`result`

  Nur bei prozeduralem Aufruf: Ein von mysqli_query(), mysqli_store_result(), mysqli_use_result() oder mysqli_stmt_get_result() zurückgegebenes mysqli_result-Objekt.

### Rückgabewerte

Gibt einen Integer zurück, der die Anzahl der abgerufenen Zeilen angibt. Gibt im ungepufferten Modus `0` zurück, wenn nicht alle Zeilen vom Server abgerufen wurden.

> Hinweis:

> Wenn die Anzahl der Zeilen größer ist als `PHP_INT_MAX`, wird die Anzahl als String zurückgegeben.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $result = $mysqli->query("SELECT Code, Name FROM Country ORDER BY Name");

    /* Anzahl der Zeilen in der Ergebnismenge ermitteln */
    $row_cnt = $result->num_rows;

    printf("Die Ergebnismenge enthält %d Zeilen.\n", $row_cnt);

Beispiel #2 Prozeduraler Stil

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT Code, Name FROM Country ORDER BY Name");

    /* Anzahl der Zeilen in der Ergebnismenge ermitteln */
    $row_cnt = mysqli_num_rows($result);

    printf("Die Ergebnismenge enthält %d Zeilen.\n", $row_cnt);

Die obigen Bespiele erzeugen folgende Ausgabe:

    Die Ergebnismenge enthält 239 Zeilen.

### Anmerkungen

> Hinweis:

> Im Gegensatz zur Funktion mysqli_stmt_num_rows() hat diese Funktion keine objektorientierte Methodenvariante. Im objektorientierten Stil muss die "Getter"-Eigenschaft verwendet werden.

### Siehe auch

- mysqli_affected_rows() - Liefert die Anzahl der Datensätze, die vom letzten MySQL-Vorgang betroffen waren
- mysqli_store_result() - Überträgt die Ergebnismenge der letzten Abfrage
- mysqli_use_result() - Initiiert den Abruf einer Ergebnismenge
- mysqli_query() - Führt eine Abfrage in einer Datenbank durch
- mysqli_stmt_num_rows() - Liefert die Anzahl der vom Server abgerufenen Datensätze

## Inhaltsverzeichnis

- mysqli_result::__construct — Erstellt ein mysqli_result-Objekt
- mysqli_result::$current_field — Ermittelt den aktuellen Spalten-Offset eines Ergebniszeigers
- mysqli_result::data_seek — Verschiebt den Ergebniszeiger auf die angegebene Zeile
- mysqli_result::fetch_all — Ruft alle Ergebniszeilen als assoziatives und/oder numerisches Array ab
- mysqli_result::fetch_array — Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab
- mysqli_result::fetch_assoc — Ruft die nächste Zeile einer Ergebnismenge als assoziatives Array ab
- mysqli_result::fetch_column — Ruft eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge ab
- mysqli_result::fetch_field — Liefert die Metadaten der nächsten Spalte einer Ergebnismenge
- mysqli_result::fetch_field_direct — Ruft die Metadaten für eine einzelne Spalte ab
- mysqli_result::fetch_fields — Liefert ein Array von Objekten, die die Spalten einer Ergebnismenge darstellen
- mysqli_result::fetch_object — Liefert die nächste Zeile einer Ergebnismenge als Objekt
- mysqli_result::fetch_row — Liefert die nächste Zeile einer Ergebnismenge als numerisches Array
- mysqli_result::$field_count — Ermittelt die Anzahl der Spalten in der Ergebnismenge
- mysqli_result::field_seek — Setzt den Ergebniszeiger auf die angegebene Spalte
- mysqli_result::free — Gibt den mit einem Ergebnis verbundenen Speicher frei
- mysqli_result::getIterator — Ruft einen externen Iterator ab
- mysqli_result::$lengths — Liefert die Breiten der Spalten der aktuellen Zeile einer Ergebnismenge
- mysqli_result::$num_rows — Ermittelt die Anzahl der Zeilen einer Ergebnismenge

# Die Klasse mysqli_driver

(PHP 5, PHP 7, PHP 8)

## Einführung

Die Klasse mysqli_driver ist eine Instanz des Monostate-Entwurfsmusters, d. h. es gibt nur einen Treiber, auf den durch eine beliebige Menge von mysqli_driver-Instanzen zugegriffen werden kann.

## Klassenbeschreibung

final class mysqli_driver {
/* Eigenschaften */
public readonly string $client_info;
public readonly int $client_version;
public readonly int $driver_version;
public int $report_mode;
}

## Eigenschaften

client_info

  Die Header-Version der Client-API

client_version

  Die Client-Version

driver_version

  Die Version des MySQLi-Treibers

  Warnung

  Diese Eigenschaft ist seit PHP 8.1.0 veraltet. Es wird dringend davon abgeraten, sich auf diese Eigenschaft zu verlassen.

embedded

  Ist der MySQLi-Embedded-Support aktiviert?

  Warnung

  Diese Eigenschaft wurde in PHP 8.0.0 entfernt.

reconnect

  Erlaubt oder verbietet das Wiederverbinden (INI-Anweiung mysqli.reconnect).

  Warnung

  Diese Eigenschaft wurde in PHP 8.2.0 zusammen mit der INI-Anweiung mysqli.reconnect entfernt.

report_mode

  Wird auf `MYSQLI_REPORT_OFF`, `MYSQLI_REPORT_ALL` oder eine beliebige Kombination von `MYSQLI_REPORT_STRICT` (löst bei Fehlern Exceptions aus), `MYSQLI_REPORT_ERROR` (meldet Fehler) und `MYSQLI_REPORT_INDEX` (meldet Fehler bezüglich Indizes) gesetzt. Siehe auch mysqli_report().

## Changelog

Version | Beschreibung
--- | ---
8.2.0 | mysqli_driver::$reconnect wurde entfernt.
8.1.0 | mysqli_driver::$driver_version wurde als veraltet markiert.
8.0.0 | mysqli_driver::$embedded wurde entfernt.
7.4.0 | mysqli_driver::embedded_server_start() und mysqli_driver:embedded_server_end() wurden entfernt.

# mysqli_driver::embedded_server_end

# mysqli_embedded_server_end

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_end -- mysqli_embedded_server_end — Stoppt den eingebauten Server

Warnung

Diese Funktion wurde in PHP 7.4.0 ENTFERNT.

### Beschreibung

Objektorientierter Stil

public function mysqli_driver::embedded_server_end(): void

Prozeduraler Stil

function mysqli_embedded_server_end(): void
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# mysqli_driver::embedded_server_start

# mysqli_embedded_server_start

(PHP 5 >= 5.1.0, PHP 7 < 7.4.0)

mysqli_driver::embedded_server_start -- mysqli_embedded_server_start — Initialisiert und startet den eingebauten Server

Warnung

Diese Funktion wurde in PHP 7.4.0 ENTFERNT.

### Beschreibung

Objektorientierter Stil

public function mysqli_driver::embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool

Prozeduraler Stil

function mysqli_embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# mysqli_driver::$report_mode

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_driver::$report_mode -- mysqli_report — Legt den Modus für die mysqli-Fehlermeldungen fest

### Beschreibung

Objektorientierter Stil

int $mysqli_driver->report_mode;

Prozeduraler Stil

function mysqli_report(int `$flags`): true

In Abhängigkeit von den Flags wird der Modus für mysqli-Fehlermeldungen auf Exception, Warning oder None gesetzt. Wenn der Parameter auf `MYSQLI_REPORT_ALL` oder `MYSQLI_REPORT_INDEX` gesetzt ist, informiert er auch über Abfragen, die keinen (oder einen fehlerhaften) Index verwenden.

Seit PHP 8.1.0 ist der Standardwert `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`; vorher war es `MYSQLI_REPORT_OFF`.

### Parameter-Liste

`flags`

  Unterstützte Flags
  Name | Beschreibung
  --- | ---
  `MYSQLI_REPORT_OFF` | Deaktiviert die Meldung von Fehlern
  `MYSQLI_REPORT_ERROR` | Fehler von mysqli-Funktionsaufrufen melden
  `MYSQLI_REPORT_STRICT` | Bei einem Fehler eine mysqli_sql_exception statt einer Warnung auslösen
  `MYSQLI_REPORT_INDEX` | Fehlende oder fehlerhafte Indizes in einer Abfrage melden
  `MYSQLI_REPORT_ALL` | Alle Optionen aktivieren (alles melden)

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Standardwert ist nun `MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT`; vorher war es `MYSQLI_REPORT_OFF`.

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php

    /* Fehlermeldungen aktivieren */
    $driver = new mysqli_driver();
    $driver->report_mode = MYSQLI_REPORT_ALL;

    try {
        /* wenn die Verbindung fehlschlägt, wird eine mysqli_sql_exception ausgelöst */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* diese Abfrage sollte einen Fehler melden */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* Wenn die Spalte population keinen Index hat, sollte diese Abfrage einen fehlerhaften Index melden */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

Beispiel #2 Prozeduraler Stil

    <?php

    /* Fehlermeldungen aktivieren */
    mysqli_report(MYSQLI_REPORT_ALL);

    try {
        /* wenn die Verbindung fehlschlägt, wird eine mysqli_sql_exception ausgelöst */
        $link = mysqli_connect("localhost", "my_user", "my_password", "my_db");

        /* diese Abfrage sollte einen Fehler melden */
        $result = mysqli_query($link, "SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* Wenn die Spalte population keinen Index hat, sollte diese Abfrage einen fehlerhaften Index melden */
        $result = mysqli_query($link, "SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

Beispiel #3 Nur Fehler melden, die sich nicht auf den Index beziehen

    <?php

    /* Fehlermeldungen aktivieren */
    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

    try {
        /* wenn die Verbindung fehlschlägt, wird eine mysqli_sql_exception ausgelöst */
        $mysqli = new mysqli("localhost", "my_user", "my_password", "my_db");

        /* diese Abfrage sollte einen Fehler melden */
        $result = $mysqli->query("SELECT Name FROM Nonexistingtable WHERE population > 50000");

        /* diese Abfrage meldet KEINEN Fehler, auch wenn kein Index vorhanden ist */
        $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000");
    } catch (mysqli_sql_exception $e) {
        error_log($e->__toString());
    }

### Siehe auch

- mysqli_sql_exception
- set_exception_handler() - Installiert einen benutzerdefinierten Exceptionhandler
- error_reporting() - Gibt an, welche PHP-Fehlermeldungen gemeldet werden

## Inhaltsverzeichnis

- mysqli_driver::embedded_server_end — Stoppt den eingebauten Server
- mysqli_driver::embedded_server_start — Initialisiert und startet den eingebauten Server
- mysqli_driver::$report_mode — Legt den Modus für die mysqli-Fehlermeldungen fest

# Die Klasse mysqli_warning

(PHP 5, PHP 7, PHP 8)

## Einführung

Stellt eine MySQL-Warnung dar.

## Klassenbeschreibung

final class mysqli_warning {
/* Eigenschaften */
public string $message;
public string $sqlstate;
public int $errno;
/* Methoden */
private function __construct()
public function next(): bool
}

## Eigenschaften

message

  Die Nachrichten-Zeichenkette

sqlstate

  Der SQL-Status

errno

  Die Fehlernummer

# mysqli_warning::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_warning::__construct — Privater Konstruktor, um eine direkte Instanziierung zu verhindern

### Beschreibung

private function mysqli_warning::__construct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# mysqli_warning::next

(PHP 5, PHP 7, PHP 8)

mysqli_warning::next — Ruft die nächste Warnung ab

### Beschreibung

public function mysqli_warning::next(): bool

Rückt, falls möglich, auf die nächsten Warnung vor.

Nachdem die Warnmeldung auf die nächste Warnung gesetzt wurde, stehen die neuen Werte der Eigenschaften `message`, `sqlstate` und `errno` von mysqli_warning zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn die nächste Warnung erfolgreich abgerufen werden konnte. Wenn es keine weitere Warnung gibt, wird `false` zurückgegeben.

## Inhaltsverzeichnis

- mysqli_warning::__construct — Privater Konstruktor, um eine direkte Instanziierung zu verhindern
- mysqli_warning::next — Ruft die nächste Warnung ab

# Die Klasse mysqli_sql_exception

(PHP 5, PHP 7, PHP 8)

## Einführung

Die MySQLi-Fehlerbehandlungs-Klasse

## Klassenbeschreibung

final class mysqli_sql_exception extends RuntimeException {
/* Eigenschaften */
protected string $sqlstate = "00000";
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
public function getSqlState(): string
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## Eigenschaften

sqlstate

  Der SQL-Status mit dem Fehler.

# mysqli_sql_exception::getSqlState

(PHP 8 >= 8.1.2)

mysqli_sql_exception::getSqlState — Liefert den SQLSTATE-Fehlercode

### Beschreibung

public function mysqli_sql_exception::getSqlState(): string

Gibt eine Zeichenkette zurück, die den SQLSTATE-Fehlercode für den letzten Fehler enthält. Der Fehlercode besteht aus fünf Zeichen. Die Werte werden durch ANSI-SQL und ODBC festgelegt. Eine Liste der möglichen Werte ist unter » http://dev.mysql.com/doc/mysql/en/error-handling.html zu finden.

> Hinweis:

> Es ist zu beachten, dass noch nicht alle MySQL-Fehler zu SQLSTATEs zugeordnet sind. Für Fehler, die noch nicht zugeordnet sind, wird der Wert `HY000` (allgemeiner Fehler) verwendet.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die den SQLSTATE-Fehlercode für den letzten Fehler enthält. Der Fehlercode besteht aus fünf Zeichen.

## Inhaltsverzeichnis

- mysqli_sql_exception::getSqlState — Liefert den SQLSTATE-Fehlercode

# Aliase und veraltete MySQLi Funktionen

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli_connect — Alias von mysqli::__construct()

### Beschreibung

Diese Funktion ist ein Alias für: mysqli::__construct()

> Hinweis:

> Wenn der Exception-Modus von mysqli nicht aktiviert ist und eine Verbindung fehlschlägt, dann gibt mysqli_connect() `false` anstelle eines Objekts zurück. Die Funktion mysqli_connect_error() kann verwendet werden, um den Verbindungsfehler zu liefern.

# mysqli::escape_string

# mysqli_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::escape_string -- mysqli_escape_string — Alias von mysqli_real_escape_string()

### Beschreibung

Diese Funktion ist ein Alias für: mysqli_real_escape_string().

# mysqli_execute

(PHP 5, PHP 7, PHP 8)

mysqli_execute — Alias von mysqli_stmt_execute()

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

Diese Funktion ist ein Alias für: mysqli_stmt_execute().

### Siehe auch

- mysqli_stmt_execute() - Führt eine vorbereitete Anweisung aus

# mysqli_get_client_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_get_client_stats — Liefert prozessbezogene Client-Statistiken

### Beschreibung

function mysqli_get_client_stats(): array

Gibt Statistiken über die einzelnen Client-Prozesse zurück.

> Hinweis:

> Nur in mysqlnd verfügbar.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array mit Client-Statistiken zurück.

### Beispiele

Beispiel #1 mysqli_get_client_stats()-Beispiel

    <?php
    $link = mysqli_connect();
    print_r(mysqli_get_client_stats());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [bytes_sent] => 43
        [bytes_received] => 80
        [packets_sent] => 1
        [packets_received] => 2
        [protocol_overhead_in] => 8
        [protocol_overhead_out] => 4
        [bytes_received_ok_packet] => 11
        [bytes_received_eof_packet] => 0
        [bytes_received_rset_header_packet] => 0
        [bytes_received_rset_field_meta_packet] => 0
        [bytes_received_rset_row_packet] => 0
        [bytes_received_prepare_response_packet] => 0
        [bytes_received_change_user_packet] => 0
        [packets_sent_command] => 0
        [packets_received_ok] => 1
        [packets_received_eof] => 0
        [packets_received_rset_header] => 0
        [packets_received_rset_field_meta] => 0
        [packets_received_rset_row] => 0
        [packets_received_prepare_response] => 0
        [packets_received_change_user] => 0
        [result_set_queries] => 0
        [non_result_set_queries] => 0
        [no_index_used] => 0
        [bad_index_used] => 0
        [slow_queries] => 0
        [buffered_sets] => 0
        [unbuffered_sets] => 0
        [ps_buffered_sets] => 0
        [ps_unbuffered_sets] => 0
        [flushed_normal_sets] => 0
        [flushed_ps_sets] => 0
        [ps_prepared_never_executed] => 0
        [ps_prepared_once_executed] => 0
        [rows_fetched_from_server_normal] => 0
        [rows_fetched_from_server_ps] => 0
        [rows_buffered_from_client_normal] => 0
        [rows_buffered_from_client_ps] => 0
        [rows_fetched_from_client_normal_buffered] => 0
        [rows_fetched_from_client_normal_unbuffered] => 0
        [rows_fetched_from_client_ps_buffered] => 0
        [rows_fetched_from_client_ps_unbuffered] => 0
        [rows_fetched_from_client_ps_cursor] => 0
        [rows_skipped_normal] => 0
        [rows_skipped_ps] => 0
        [copy_on_write_saved] => 0
        [copy_on_write_performed] => 0
        [command_buffer_too_small] => 0
        [connect_success] => 1
        [connect_failure] => 0
        [connection_reused] => 0
        [reconnect] => 0
        [pconnect_success] => 0
        [active_connections] => 1
        [active_persistent_connections] => 0
        [explicit_close] => 0
        [implicit_close] => 0
        [disconnect_close] => 0
        [in_middle_of_command_close] => 0
        [explicit_free_result] => 0
        [implicit_free_result] => 0
        [explicit_stmt_close] => 0
        [implicit_stmt_close] => 0
        [mem_emalloc_count] => 0
        [mem_emalloc_ammount] => 0
        [mem_ecalloc_count] => 0
        [mem_ecalloc_ammount] => 0
        [mem_erealloc_count] => 0
        [mem_erealloc_ammount] => 0
        [mem_efree_count] => 0
        [mem_malloc_count] => 0
        [mem_malloc_ammount] => 0
        [mem_calloc_count] => 0
        [mem_calloc_ammount] => 0
        [mem_realloc_count] => 0
        [mem_realloc_ammount] => 0
        [mem_free_count] => 0
        [proto_text_fetched_null] => 0
        [proto_text_fetched_bit] => 0
        [proto_text_fetched_tinyint] => 0
        [proto_text_fetched_short] => 0
        [proto_text_fetched_int24] => 0
        [proto_text_fetched_int] => 0
        [proto_text_fetched_bigint] => 0
        [proto_text_fetched_decimal] => 0
        [proto_text_fetched_float] => 0
        [proto_text_fetched_double] => 0
        [proto_text_fetched_date] => 0
        [proto_text_fetched_year] => 0
        [proto_text_fetched_time] => 0
        [proto_text_fetched_datetime] => 0
        [proto_text_fetched_timestamp] => 0
        [proto_text_fetched_string] => 0
        [proto_text_fetched_blob] => 0
        [proto_text_fetched_enum] => 0
        [proto_text_fetched_set] => 0
        [proto_text_fetched_geometry] => 0
        [proto_text_fetched_other] => 0
        [proto_binary_fetched_null] => 0
        [proto_binary_fetched_bit] => 0
        [proto_binary_fetched_tinyint] => 0
        [proto_binary_fetched_short] => 0
        [proto_binary_fetched_int24] => 0
        [proto_binary_fetched_int] => 0
        [proto_binary_fetched_bigint] => 0
        [proto_binary_fetched_decimal] => 0
        [proto_binary_fetched_float] => 0
        [proto_binary_fetched_double] => 0
        [proto_binary_fetched_date] => 0
        [proto_binary_fetched_year] => 0
        [proto_binary_fetched_time] => 0
        [proto_binary_fetched_datetime] => 0
        [proto_binary_fetched_timestamp] => 0
        [proto_binary_fetched_string] => 0
        [proto_binary_fetched_blob] => 0
        [proto_binary_fetched_enum] => 0
        [proto_binary_fetched_set] => 0
        [proto_binary_fetched_geometry] => 0
        [proto_binary_fetched_other] => 0
    )

### Siehe auch

- Beschreibung der Statistiken

# mysqli_get_links_stats

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

mysqli_get_links_stats — Liefert Informationen über offene und zwischengespeicherte Verbindungen

### Beschreibung

function mysqli_get_links_stats(): array

mysqli_get_links_stats() gibt Informationen über offene und zwischengespeicherte MySQL-Verbindungen zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

mysqli_get_links_stats() gibt ein assoziatives Array mit drei Elementen zurück, die folgende Schlüssel haben:

`total`

  Ein Wert vom Typ int, der die Gesamtzahl der offenen Verbindungen unabhängig vom jeweiligen Zustand angibt.

`active_plinks`

  Ein Wert vom Typ int, der die Anzahl der aktiven persistenten (dauerhaften) Verbindungen angibt.

`cached_plinks`

  Ein Wert vom Typ int, der die Anzahl der inaktiven persistenten Verbindungen angibt.

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_report — Alias von mysqli_driver->report_mode

### Beschreibung

Diese Funktion ist ein Alias für: mysqli_driver->report_mode

# mysqli::set_opt

# mysqli_set_opt

(PHP 5, PHP 7, PHP 8)

mysqli::set_opt -- mysqli_set_opt — Alias von mysqli_options()

### Beschreibung

Diese Funktion ist ein Alias für: mysqli_options().

## Inhaltsverzeichnis

- mysqli_connect — Alias von mysqli::__construct
- mysqli::escape_string — Alias von mysqli_real_escape_string
- mysqli_execute — Alias von mysqli_stmt_execute
- mysqli_get_client_stats — Liefert prozessbezogene Client-Statistiken
- mysqli_get_links_stats — Liefert Informationen über offene und zwischengespeicherte Verbindungen
- mysqli_report — Alias von mysqli_driver->report_mode
- mysqli::set_opt — Alias von mysqli_options

# Changelog

Folgende Änderungen wurden an den Klassen/Funktionen/Methoden dieser Extension vorgenommen.

Version | Function | Description
--- | --- | ---
8.4.0 | mysqli::kill | Sowohl mysqli::kill als auch mysqli_kill sind nun veraltet. Stattdessen sollte der SQL-Befehl KILL verwendet werden.
| mysqli::ping | Sowohl mysqli::ping als auch mysqli_ping sind nun veraltet. Die Funktionalität reconnect ist seit PHP 8.2.0 nicht mehr verfügbar, wodurch diese Funktion überflüssig wurde.
| mysqli::refresh | Sowohl mysqli::refresh als auch mysqli_refresh sind nun veraltet. Stattdessen sollte der SQL-Befehl FLUSH verwendet werden.
| mysqli::store_result | Die Übergabe des Parameters mode ist nun veraltet. Der Parameter hat seit PHP 8.1.0 keine Wirkung mehr.
8.3.0 | mysqli_result::fetch_object | Wenn constructor_args nicht leer ist, die Klasse aber keinen Konstruktor hat, wird nun ein ValueError geworfen; zuvor wurde eine Exception geworfen.
| mysqli::poll | Wenn weder read noch error übergeben wird, wird nun eine ValueError-Exception geworfen.
8.1.0 | mysqli_driver::$report_mode | Der Standardwert ist nun MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT; vorher war es MYSQLI_REPORT_OFF.
| mysqli_result::fetch_all | Steht nun auch in Verbindung mit libmysqlclient zur Verfügung.
| mysqli_stmt::execute | Der optionale Parameter params wurde hinzugefügt.
| mysqli_stmt::next_result | Nun auch verfügbar, wenn gegen libmysqlclient gelinkt wird.
| mysqli::__construct | mysqli::connect gibt bei Erfolg nun true anstelle von null zurück.
| mysqli::$client_info | Der Aufruf von mysqli_get_client_info mit dem Parameter mysql ist veraltet. Diese Funktion benötigte nie einen Parameter, sondern ließ ihn fälschlicherweise als optionalen Parameter zu.
| mysqli::$client_info | Der objektorientierte Stil mysqli::get_client_info ist veraltet.
| mysqli::init | Die objektorientierte Methode mysqli::init ist veraltet. Anstelle von parent::init sollte parent::__construct verwendet werden.
8.0.0 | mysqli_result::fetch_object | Der Parameter constructor_args akzeptiert bei Konstruktoren mit 0 Parametern nun []; zuvor wurde eine Exception geworfen.
| mysqli_result::field_seek | Diese Funktion gibt nun immer true zurück; vorher gab sie bei einem Fehler false zurück.
| mysqli_stmt::close | Diese Funktion gibt nun immer true zurück; vorher gab sie bei einem Fehler false zurück.
| mysqli_stmt::__construct | query ist nun ein Nullable-Typ.
| mysqli::begin_transaction | name ist nun nullable (akzeptiert den null-Wert).
| mysqli::close | Diese Funktion gibt nun immer true zurück; vorher gab sie bei einem Fehler false zurück.
| mysqli::commit | name ist nun nullable (akzeptiert den null-Wert).
| mysqli::debug | Diese Funktion gibt nun immer true zurück; vorher gab sie bei einem Fehler false zurück.
| mysqli::rollback | name ist nun nullable (akzeptiert den null-Wert).
7.4.0 | mysqli::__construct | Alle Parameter sind nun nullable (akzeptieren den null-Wert).
| mysqli::real_connect | Alle Parameter sind nun nullable (akzeptieren den null-Wert).

- Übersicht
- Kurzanleitung für den schnellen Einstieg
  - Prozedurale und objektorientierte Schnittstelle
  - Datenbankverbindungen
  - Ausführen von Anweisungen
  - Vorbereitete Anweisungen (Prepared Statements)
  - Gespeicherte Prozeduren (Stored Procedures)
  - Mehrfach-Anweisungen
  - API-Unterstützung für Transaktionen
  - Metadaten
- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Die Erweiterung mysqli und persistente (beständige) Verbindungen
- Vordefinierte Konstanten
- Hinweise
- Die Funktionen der Erweiterung MySQLi im Überblick
- mysqli — Die Klasse mysqli
  - mysqli::$affected_rows — Liefert die Anzahl der Datensätze, die vom letzten MySQL-Vorgang betroffen waren
  - mysqli::autocommit — Aktiviert oder deaktiviert das automatische Bestätigen von Datenbankänderungen
  - mysqli::begin_transaction — Startet eine Transaktion
  - mysqli::change_user — Ändert den Benutzer der Datenbankverbindung
  - mysqli::character_set_name — Liefert den aktuellen Zeichensatz der Datenbankverbindung
  - mysqli::close — Schließt die zuvor geöffnete Datenbankverbindung
  - mysqli::commit — Bestätigt die aktuelle Transaktion
  - mysqli::$connect_errno — Liefert den Fehlercode des letzten Verbindungsversuchs
  - mysqli::$connect_error — Liefert eine Beschreibung des letzten Verbindungsfehlers
  - mysqli::__construct — Baut eine neue Verbindung zum MySQL-Server auf
  - mysqli::debug — Führt Debugging-Operationen durch
  - mysqli::dump_debug_info — Schreibt Debugging-Informationen in die Logdatei
  - mysqli::$errno — Liefert den Fehlercode des letzten Funktionsaufrufs
  - mysqli::$error — Liefert eine Zeichenkette, die den letzten Fehler beschreibt
  - mysqli::$error_list — Liefert eine Liste der Fehler des zuletzt ausgeführten Befehls
  - mysqli::execute_query — Bereitet eine SQL-Anweisung vor, bindet die Parameter und führt die Anweisung aus
  - mysqli::$field_count — Liefert die Anzahl der Spalten der letzten Abfrage
  - mysqli::get_charset — Liefert ein Zeichensatz-Objekt
  - mysqli::$client_info — Liefert die Version des MySQL-Clients als Zeichenkette
  - mysqli::$client_version — Liefert die Version des MySQL-Clients als Integer
  - mysqli::get_connection_stats — Liefert Verbindungsstatistiken des Clients
  - mysqli::$host_info — Liefert eine Zeichenkette, die den Typ der verwendeten Verbindung angibt
  - mysqli::$protocol_version — Liefert die Version des verwendeten MySQL-Protokolls
  - mysqli::$server_info — Liefert die Version des MySQL-Servers
  - mysqli::$server_version — Liefert die Version des MySQL-Servers als Integer
  - mysqli::get_warnings — Ermittelt das Ergebnis von SHOW WARNINGS
  - mysqli::$info — Ruft Informationen über die zuletzt ausgeführte Abfrage ab
  - mysqli::init — Initialisiert MySQLi und liefert ein Objekt zur Verwendung mit mysqli_real_connect()
  - mysqli::$insert_id — Liefert den Wert, der bei der letzten Anweisung für die AUTO_INCREMENT-Spalte erzeugt wurde
  - mysqli::kill — Weist den Server an, einen MySQL-Thread zu beenden
  - mysqli::more_results — Prüft, ob es von einer Mehrfachabfrage noch weitere Abfrageergebnisse gibt
  - mysqli::multi_query — Führt eine oder mehrere Abfragen in einer Datenbank durch
  - mysqli::next_result — Bereitet das nächste Ergebnis von multi_query vor
  - mysqli::options — Setzt Optionen
  - mysqli::ping — Pingt eine Serververbindung an oder versucht eine neue Verbindung aufzubauen, wenn die Verbindung unterbrochen wurde
  - mysqli::poll — Überprüft den Status von Verbindungen
  - mysqli::prepare — Bereitet eine SQL-Anweisung zur Ausführung vor
  - mysqli::query — Führt eine Abfrage in einer Datenbank durch
  - mysqli::real_connect — Baut eine Verbindung zu einem MySQL-Server auf
  - mysqli::real_escape_string — Maskiert Sonderzeichen in einer Zeichenkette zur Verwendung in einer SQL-Anweisung, wobei der aktuelle Zeichensatz der Verbindung berücksichtigt wird
  - mysqli::real_query — Führt eine SQL-Abfrage aus
  - mysqli::reap_async_query — Ruft das Ergebnis einer asynchronen Abfrage ab
  - mysqli::refresh — Führt ein Refresh durch
  - mysqli::release_savepoint — Entfernt einen benannten Sicherungspunkt aus der Menge der Sicherungspunkte der aktuellen Transaktion
  - mysqli::rollback — Macht die aktuelle Transaktion rückgängig
  - mysqli::savepoint — Sezt einen benannten Sicherungspunkt für eine Transaktion
  - mysqli::select_db — Legt die standardmäßige Datenbank für Datenbankabfragen fest
  - mysqli::set_charset — Legt den Standard-Zeichensatz des Clients fest
  - mysqli::$sqlstate — Liefert den SQLSTATE-Fehler der letzten MySQL-Operation
  - mysqli::ssl_set — Wird beim Aufbau sicherer Verbindungen mit SSL verwendet
  - mysqli::stat — Liefert den aktuellen Systemstatus
  - mysqli::stmt_init — Initialisiert eine Anweisung und liefert ein Objekt für die Verwendung mit mysqli_stmt_prepare
  - mysqli::store_result — Überträgt die Ergebnismenge der letzten Abfrage
  - mysqli::$thread_id — Liefert die Thread-ID der aktuellen Verbindung
  - mysqli::thread_safe — Gibt an, ob Thread-Sicherheit gegeben ist oder nicht
  - mysqli::use_result — Initiiert den Abruf einer Ergebnismenge
  - mysqli::$warning_count — Liefert die Anzahl der Warnungen, die durch die letzte Abfrage erzeugt wurden
- mysqli_stmt — Die Klasse mysqli_stmt
  - mysqli_stmt::$affected_rows — Liefert die gesamte Anzahl der Datensätze, die bei der letzten ausgeführten Anweisung geändert, gelöscht, eingefügt oder abgeglichen wurden
  - mysqli_stmt::attr_get — Liefert den aktuellen Wert des Attributs einer Anweisung
  - mysqli_stmt::attr_set — Verändert das Verhalten einer vorbereiteten Anweisung (prepared statement)
  - mysqli_stmt::bind_param — Bindet Variablen als Parameter an eine vorbereitete Anweisung (prepared statement)
  - mysqli_stmt::bind_result — Bindet Variablen an eine vorbereitete Anweisung (prepared statement), um das Ergebnis einer Abfrage abzulegen
  - mysqli_stmt::close — Schließt eine vorbereitete Anweisung (prepared statement)
  - mysqli_stmt::__construct — Erzeugt ein neues mysqli_stmt-Objekt
  - mysqli_stmt::data_seek — Verschiebt den Ergebniszeiger auf eine beliebige Zeile im gepufferten Ergebnis
  - mysqli_stmt::$errno — Liefert den Fehlercode der zuletzt aufgerufenen Anweisung
  - mysqli_stmt::$error — Liefert die Beschreibung des letzten Fehlers einer Anweisung als Zeichenkette
  - mysqli_stmt::$error_list — Liefert eine Liste der Fehler der zuletzt ausgeführten Anweisung
  - mysqli_stmt::execute — Führt eine vorbereitete Anweisung aus
  - mysqli_stmt::fetch — Ruft Ergebnisse aus einer vorbereiteten Anweisung in gebundene Variablen ab
  - mysqli_stmt::$field_count — Liefert die Anzahl der Spalten in der angegebenen Anweisung
  - mysqli_stmt::free_result — Gibt den mit der angegebenen Anweisung verbundenen Ergebnisspeicher frei
  - mysqli_stmt::get_result — Ruft die Ergebnismenge aus einer vorbereiteten Anweisung als mysqli_result-Objekt ab
  - mysqli_stmt::get_warnings — Ermittelt das Ergebnis von SHOW WARNINGS
  - mysqli_stmt::$insert_id — Ermittelt die ID, die beim letzten INSERT-Vorgang erzeugt wurde
  - mysqli_stmt::more_results — Prüft, ob es weitere Ergebnisse aus einer Mehrfachabfrage gibt
  - mysqli_stmt::next_result — Liest das nächste Ergebnis einer Mehrfachabfrage aus
  - mysqli_stmt::$num_rows — Liefert die Anzahl der vom Server abgerufenen Datensätze
  - mysqli_stmt::$param_count — Liefert die Anzahl der Parameter einer Anweisung
  - mysqli_stmt::prepare — Bereitet eine SQL-Anweisung zur Ausführung vor
  - mysqli_stmt::reset — Setzt eine vorbereitete Anweisung zurück
  - mysqli_stmt::result_metadata — Liefert die Metadaten der Ergebnismenge aus einer vorbereiteten Anweisung
  - mysqli_stmt::send_long_data — Sendet Daten blockweise
  - mysqli_stmt::$sqlstate — Liefert den SQLSTATE-Fehlercode der letzten Anweisung
  - mysqli_stmt::store_result — Speichert eine Ergebnismenge in einem internen Puffer
- mysqli_result — Die Klasse mysqli_result
  - mysqli_result::__construct — Erstellt ein mysqli_result-Objekt
  - mysqli_result::$current_field — Ermittelt den aktuellen Spalten-Offset eines Ergebniszeigers
  - mysqli_result::data_seek — Verschiebt den Ergebniszeiger auf die angegebene Zeile
  - mysqli_result::fetch_all — Ruft alle Ergebniszeilen als assoziatives und/oder numerisches Array ab
  - mysqli_result::fetch_array — Ruft die nächste Zeile einer Ergebnismenge als assoziatives und/oder numerisches Array ab
  - mysqli_result::fetch_assoc — Ruft die nächste Zeile einer Ergebnismenge als assoziatives Array ab
  - mysqli_result::fetch_column — Ruft eine einzelne Spalte aus der nächsten Zeile einer Ergebnismenge ab
  - mysqli_result::fetch_field — Liefert die Metadaten der nächsten Spalte einer Ergebnismenge
  - mysqli_result::fetch_field_direct — Ruft die Metadaten für eine einzelne Spalte ab
  - mysqli_result::fetch_fields — Liefert ein Array von Objekten, die die Spalten einer Ergebnismenge darstellen
  - mysqli_result::fetch_object — Liefert die nächste Zeile einer Ergebnismenge als Objekt
  - mysqli_result::fetch_row — Liefert die nächste Zeile einer Ergebnismenge als numerisches Array
  - mysqli_result::$field_count — Ermittelt die Anzahl der Spalten in der Ergebnismenge
  - mysqli_result::field_seek — Setzt den Ergebniszeiger auf die angegebene Spalte
  - mysqli_result::free — Gibt den mit einem Ergebnis verbundenen Speicher frei
  - mysqli_result::getIterator — Ruft einen externen Iterator ab
  - mysqli_result::$lengths — Liefert die Breiten der Spalten der aktuellen Zeile einer Ergebnismenge
  - mysqli_result::$num_rows — Ermittelt die Anzahl der Zeilen einer Ergebnismenge
- mysqli_driver — Die Klasse mysqli_driver
  - mysqli_driver::embedded_server_end — Stoppt den eingebauten Server
  - mysqli_driver::embedded_server_start — Initialisiert und startet den eingebauten Server
  - mysqli_driver::$report_mode — Legt den Modus für die mysqli-Fehlermeldungen fest
- mysqli_warning — Die Klasse mysqli_warning
  - mysqli_warning::__construct — Privater Konstruktor, um eine direkte Instanziierung zu verhindern
  - mysqli_warning::next — Ruft die nächste Warnung ab
- mysqli_sql_exception — Die Klasse mysqli_sql_exception
  - mysqli_sql_exception::getSqlState — Liefert den SQLSTATE-Fehlercode
- Aliase und veraltete MySQLi Funktionen
  - mysqli_connect — Alias von mysqli::__construct
  - mysqli::escape_string — Alias von mysqli_real_escape_string
  - mysqli_execute — Alias von mysqli_stmt_execute
  - mysqli_get_client_stats — Liefert prozessbezogene Client-Statistiken
  - mysqli_get_links_stats — Liefert Informationen über offene und zwischengespeicherte Verbindungen
  - mysqli_report — Alias von mysqli_driver->report_mode
  - mysqli::set_opt — Alias von mysqli_options
- Changelog

# Mysql_xdevapi

# Einführung

Diese Erweiterung ermöglicht den Zugriff auf den MySQL Document Store (Dokumentenspeicher) über die X DevAPI. Die X DevAPI ist eine generische API, die von mehreren MySQL-Konnektoren bereitgestellt wird. Sie ermöglicht einen einfachen Zugriff auf relationale Tabellen sowie auf Sammlungen von Dokumenten, die über eine API mit CRUD-ähnlichen Operationen in JSON dargestellt werden.

Die X DevAPI verwendet das X-Protokoll, das Client-Server-Protokoll der neuen Generation des MySQL 8.0-Servers.

Allgemeine Informationen über den MySQL-Dokumentenspeicher sind im Kapitel » MySQL Document Store im MySQL-Handbuch zu finden.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Erstellen/Kompilieren aus dem Quellcode

## Anforderungen

Für diese Erweiterung wird ein MySQL 8+-Server benötigt, auf dem das X-Plugin aktiviert ist (Standard).

Folgende Bibliotheken werden benötigt, um diese Erweiterung zu kompilieren: Boost (1.53.0 oder höher), OpenSSL und Protobuf.

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Ein Beispiel für die Installation auf Ubuntu 18.04 mit PHP 7.2:

    // Abhängigkeiten
    $ apt install build-essential libprotobuf-dev libboost-dev openssl protobuf-compiler liblz4-tool zstd

    // PHP mit den gewünschten Erweiterungen; php7.2-dev wird zum Kompilieren benötigt
    $ apt install php7.2-cli php7.2-dev php7.2-mysql php7.2-pdo php7.2-xml

    // Kompilieren der Erweiterung
    $ pecl install mysql_xdevapi

Der Befehl `pecl install` aktiviert keine PHP-Erweiterungen (standardmäßig). Die Aktivierung kann auf verschiedene Arten erfolgen. Hier ein weiteres Beispiel für PHP 7.2 auf Ubuntu 18.04:

    // Eine eigene ini-Datei erstellen
    $ echo "extension=mysql_xdevapi.so" > /etc/php/7.2/mods-available/mysql_xdevapi.ini

    // Den Befehl 'phpenmod' verwenden (Achtung: ist Debian/Ubuntu-spezifisch)
    $ phpenmod -v 7.2 -s ALL mysql_xdevapi

    // Alternativ zu 'phpenmod' kann der Symlink auch manuell gesetzt werden
    // $ ln -s /etc/php/7.2/mods-available/mysql_xdevapi.ini /etc/php/7.2/cli/conf.d/20-mysql_xdevapi.ini

    // Schauen wir uns an, welche MySQL-Erweiterungen nun aktiviert sind
    $ php -m |grep mysql

    mysql_xdevapi
    mysqli
    mysqlnd
    pdo_mysql

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/mysql_xdevapi.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Mysql_xdevapi-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
xmysqlnd.collect_memory_statistics | 0 | `INI_SYSTEM` |
xmysqlnd.collect_statistics | 1 | `INI_ALL` |
xmysqlnd.debug |  | `INI_SYSTEM` |
xmysqlnd.mempool_default_size | 16000 | `INI_ALL` |
xmysqlnd.net_read_timeout | 31536000 | `INI_SYSTEM` |
xmysqlnd.trace_alloc |  | `INI_SYSTEM` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`xmysqlnd.collect_memory_statistics` int

`xmysqlnd.collect_statistics` int

`xmysqlnd.debug` string

`xmysqlnd.mempool_default_size` int

`xmysqlnd.net_read_timeout` int

`xmysqlnd.trace_alloc` string

## Erstellen/Kompilieren aus dem Quellcode

Hinweise zum Kompilieren dieser Erweiterung aus dem Quellcode:

- Der Name der Erweiterung ist 'mysql_xdevapi', also muss `--enable-mysql-xdevapi` verwendet werden.

- Boost: erforderlich; verwenden Sie wahlweise die Konfigurationsoption --with-boost=DIR oder setzen Sie die Umgebungsvariable MYSQL_XDEVAPI_BOOST_ROOT. Benötigt werden nur die Boost-Header-Dateien, nicht die Binärdateien.

- Google Protocol Buffers (protobuf): erforderlich; verwenden Sie die Konfigurationsoption --with-protobuf=DIR oder setzen Sie die Umgebungsvariable MYSQL_XDEVAPI_PROTOBUF_ROOT.

  Verwenden Sie optional `make protobufs`, um die Protobuf-Dateien (*.pb.cc/.h) zu erstellen, und `make clean-protobufs`, um die erstellten Protobuf-Dateien zu löschen.

  Windows-spezifischer protobuf-Hinweis: Je nach Umgebung kann die statische Bibliothek mit einer Multi-Threaded-DLL-Laufzeit erforderlich sein. Zur Vorbereitung verwenden Sie die folgenden Optionen: -Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF

- Google Protocol Buffers / Protocol-Compiler (protoc): erforderlich; stellen Sie sicher, dass während des Erstellens das korrekte 'protoc' in PATH vorhanden ist. Dies ist besonders wichtig, weil Windows PHP SDK Batch-Skripte die Umgebung überschreiben können.

- Bison: erforderlich und im PATH vorhanden.

  Windows-spezifischer Bison Hinweis: Wir empfehlen dringend, dass das mit dem verwendeten PHP SDK gelieferte Bison verwendet wird, da andernfalls ein Fehler ähnlich wie "zend_globals_macros.h(39): error C2375: 'zendparse': redefinition; different linkage Zend/zend_language_parser.h(214): note: see declaration of 'zendparse'" die Folge sein kann. Außerdem können Windows PHP SDK Batch-Skripte die Umgebung überschreiben.

- Windows-spezifische Hinweise: Um die Umgebung vorzubereiten, siehe die offizielle Windows-Build-Dokumentation für » das aktuelle SDK.

  Wir empfehlen, bei allen Pfaden den Backslash '\\' anstelle eines Schrägstrichs '/' zu verwenden.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`MYSQLX_CLIENT_SSL` (int)
`MYSQLX_TYPE_DECIMAL` (int)
`MYSQLX_TYPE_TINY` (int)
`MYSQLX_TYPE_SHORT` (int)
`MYSQLX_TYPE_SMALLINT` (int)
`MYSQLX_TYPE_MEDIUMINT` (int)
`MYSQLX_TYPE_INT` (int)
`MYSQLX_TYPE_BIGINT` (int)
`MYSQLX_TYPE_LONG` (int)
`MYSQLX_TYPE_FLOAT` (int)
`MYSQLX_TYPE_DOUBLE` (int)
`MYSQLX_TYPE_NULL` (int)
`MYSQLX_TYPE_TIMESTAMP` (int)
`MYSQLX_TYPE_LONGLONG` (int)
`MYSQLX_TYPE_INT24` (int)
`MYSQLX_TYPE_DATE` (int)
`MYSQLX_TYPE_TIME` (int)
`MYSQLX_TYPE_DATETIME` (int)
`MYSQLX_TYPE_YEAR` (int)
`MYSQLX_TYPE_NEWDATE` (int)
`MYSQLX_TYPE_ENUM` (int)
`MYSQLX_TYPE_SET` (int)
`MYSQLX_TYPE_TINY_BLOB` (int)
`MYSQLX_TYPE_MEDIUM_BLOB` (int)
`MYSQLX_TYPE_LONG_BLOB` (int)
`MYSQLX_TYPE_BLOB` (int)
`MYSQLX_TYPE_VAR_STRING` (int)
`MYSQLX_TYPE_STRING` (int)
`MYSQLX_TYPE_CHAR` (int)
`MYSQLX_TYPE_BYTES` (int)
`MYSQLX_TYPE_INTERVAL` (int)
`MYSQLX_TYPE_GEOMETRY` (int)
`MYSQLX_TYPE_JSON` (int)
`MYSQLX_TYPE_NEWDECIMAL` (int)
`MYSQLX_TYPE_BIT` (int)
`MYSQLX_LOCK_DEFAULT` (int)
`MYSQLX_LOCK_NOWAIT` (int)
`MYSQLX_LOCK_SKIP_LOCKED` (int)

# Changelog

Folgende Änderungen wurden an den Klassen/Funktionen/Methoden dieser Extension vorgenommen.

### Allgemeine Changelog für die Erweiterung ext/mysql_xdevapi

Dieses Changelog bezieht sich auf die Erweiterung ext/mysql_xdevapi.

### Allgemeine Änderungen an ext/mysql_xdevapi

Version | Beschreibung
--- | ---
8.0.28 | Die Unterstützung von TLSv1 und TLSv1.1 wurde entfernt. Die Werte "TLSv1", "TLSv1.0" und "TLSv1.1" werden für das Verbindungsattribut "tls-versions" nun als ungültig betrachtet.
8.0.26 | Die Unterstützung von TLSv1 und TLSv1.1 ist veraltet.

# Beispiele

Der zentrale Einstiegspunkt in die X DevAPI ist die Funktion mysql_xdevapi\getSession(), die einen URI zu einem MySQL 8.0 Server benötigt und ein mysql_xdevapi\Session-Objekt zurückgibt.

Beispiel #1 Verbindung zu einem MySQL-Server aufbauen

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("Die Verbindung konnte nicht hergestellt werden: " . $e->getMessage());
    }

    // ... $session verwenden
    ?>

Die Session bietet einen vollständigen Zugriff auf die API. Bei einer neuen MySQL-Installation muss zunächst ein Datenbankschema mit einer Sammlung zum Speichern der Daten erstellt werden:

Beispiel #2 Erstellen eines Schemas und einer Sammlung auf dem MySQL-Server

    <?php
    $schema = $session->createSchema("test");
    $collection = $schema->createCollection("example");
    ?>

Beim Speichern von Daten wird üblicherweise die Funktion json_encode() verwendet, um die Daten in JSON zu kodieren, die dann in einer Sammlung gespeichert werden können.

Im folgenden Beispiel werden Daten in der zuvor erstellten Sammlung gespeichert und Teile davon wieder abgerufen.

Beispiel #3 Speichern und Abrufen von Daten

    <?php
    $marco = [
      "name" => "Marco",
      "age"  => 19,
      "job"  => "Programmer"
    ];
    $mike = [
      "name" => "Mike",
      "age"  => 39,
      "job"  => "Manager"
    ];

    $schema = $session->getSchema("test");
    $collection = $schema->getCollection("example");

    $collection->add($marco, $mike)->execute();

    var_dump($collection->find("name = 'Mike'")->execute()->fetchOne());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(4) {
      ["_id"]=>
      string(28) "00005ad66aaf0000000000000003"
      ["age"]=>
      int(39)
      ["job"]=>
      string(7) "Manager"
      ["name"]=>
      string(4) "Mike"
    }

Das folgende Beispiel zeigt, dass der MySQL-Server ein zusätzliches Feld namens `_id` hinzufügt, das als Primärschlüssel für das Dokument dient.

Das Beispiel zeigt auch, dass die abgerufenen Daten alphabetisch sortiert sind. Diese spezifische Reihenfolge ergibt sich aus der effizienten Binärspeicherung im MySQL-Server, aber man sollte sich nicht darauf verlassen. Einzelheiten dazu sind in der MySQL-Dokumentation zum Datentyp JSON zu finden.

Optional können die PHP-Iteratoren verwendet werden, um mehrere Dokumente abzurufen:

Beispiel #4 Abrufen und Durchlaufen mehrerer Dokumente

    <?php
    $result = $collection->find()->execute();
    foreach ($result as $doc) {
      echo "{$doc["name"]} is a {$doc["job"]}.\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Marco is a Programmer.
    Mike is a Manager.

# Mysql_xdevapi-Funktionen

# expression

(No version information available, might only be in Git)

expression — Bindet die Variablen der vorbereiteten Anweisung als Parameter

### Beschreibung

function mysql_xdevapi\expression(string `$expression`): object

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`expression`

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\Expression()-Beispiel

    <?php
    $expression = mysql_xdevapi\Expression("[age,job]");

    $res  = $coll->find("age > 30")->fields($expression)->limit(3)->execute();
    $data = $res->fetchAll();

    print_r($data);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    <?php

# getSession

(No version information available, might only be in Git)

getSession — Baut eine Verbindung zu einem MySQL-Server auf

### Beschreibung

function mysql_xdevapi\getSession(string `$uri`): mysql_xdevapi\Session

Baut eine Verbindung zum MySQL-Server auf.

### Parameter-Liste

`uri`

  Der URI des MySQL-Servers, z. B. `mysqlx://user:password@host`.

  URI-Format:

  `scheme://[user[:[password]]@]target[:port][?attribute1=value1&attribute2=value2...`

  - `scheme`: erforderlich; das Verbindungsprotokoll

    In mysql_xdevapi ist es immer 'mysqlx' (für das X-Protokoll)

  - `user`: optional; das MySQL-Benutzerkonto für die Authentifizierung

  - `password`: optional; das Passwort des MySQL-Benutzers für die Authentifizierung

  - `target`: erforderlich; die Serverinstanz, auf die sich die Verbindung bezieht:

    * TCP-Verbindung (Hostname, IPv4-Adresse oder IPv6-Adresse)

    * Pfad des Unix-Sockets (lokaler Dateipfad)

    * Windows Named-Pipe (lokaler Dateipfad)

  - `port`: optional; der Netzwerk-Port des MySQL-Servers

    der Standard-Port für das X-Protokoll ist 33060

  - `?attribute=value`: Dieses Element ist optional und gibt ein Datenwörterbuch an, das verschiedene Optionen enthält, unter anderem:

    - Das Attribut `auth` (Authentifizierungsmechanismus), das für verschlüsselte Verbindungen benötigt wird. Für weitere Informationen siehe » Command Options for Encrypted Connections. Die folgenden 'auth'-Werte werden unterstützt: `plain`, `mysql41`, `external` und `sha256_mem`.

    - Das Attribut `connect-timeout` betrifft die Verbindung selbst, aber nicht die nachfolgenden Operationen. Es wird pro Verbindung gesetzt, unabhängig davon, ob die Verbindung zu einem oder mehreren Hosts besteht.

      Das Zeitlimit für die Verbindung wird mit einer positiven Ganzzahl in Sekunden angegeben. Wenn 0 (Null) angegeben wird, ist das Zeitlimit deaktiviert (unendlich). Wird kein Zeitlimit angegeben, wird der Standardwert 10 verwendet.

      In diesem Zusammenhang können die Umgebungsvariablen MYSQLX_CONNECTION_TIMEOUT (Zeitlimit in Sekunden) und MYSQLX_TEST_CONNECTION_TIMEOUT (wird bei Tests verwendet) gesetzt und im URI anstelle von connect-timeout verwendet werden. Die URI-Option connect-timeout hat gegenüber diesen Umgebungsvariablen Vorrang.

    - Das optionale Attribut `compression` akzeptiert diese Werte: `preferred` (der Client verhandelt mit dem Server, um einen unterstützten Algorithmus zu finden; wenn kein von beiden Seiten unterstützter Algorithmus gefunden wird, bleibt die Verbindung unkomprimiert), `required` (wie "preferred", aber die Verbindung wird abgebrochen, wenn kein von beiden Seiten unterstützter Algorithmus gefunden wird) oder `disabled` (die Verbindung bleibt unkomprimiert). Der Standardwert ist `preferred`.

      Diese Option wurde in Version 8.0.20 hinzugefügt.

    - Das optionale Attribut `compression-algorithms` definiert die gewünschten Kompressionsalgorithmen (und die bevorzugte Reihenfolge ihrer Verwendung): `zstd_stream` (alias: zstd), `lz4_message` (alias: lz4) oder `deflate_stream` (alias: deflate oder zlib). Standardmäßig wird (je nach Verfügbarkeit des Systems) die Reihenfolge lz4_message, zstd_stream und dann deflate_stream verwendet. Wenn zum Beispiel compression-algorithms=[lz4,zstd_stream] übergeben wird, wird lz4 verwendet, wenn es verfügbar ist, andernfalls wird zstd_stream verwendet. Wenn beide nicht verfügbar sind, hängt das Verhalten vom compression-Wert ab, so wird z. B. bei compression=required eine Fehlermeldung ausgegeben.

      Diese Option wurde in Version 8.0.22 hinzugefügt.

  Beispiel #1 Beispiele für URIs

      mysqlx://foobar
      mysqlx://root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F
      mysqlx://foo:bar@localhost:33060
      mysqlx://foo:bar@localhost:33160?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33260?ssl-mode=required
      mysqlx://foo:bar@localhost:33360?ssl-mode=required&auth=mysql41
      mysqlx://foo:bar@(/path/to/socket)
      mysqlx://foo:bar@(/path/to/socket)?auth=sha256_mem
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]
      mysqlx://foobar?ssl-ca=(/path/to/ca.pem)&ssl-crl=(/path/to/crl.pem)
      mysqlx://foo:bar@[localhost:33060, 127.0.0.1:33061]?ssl-mode=disabled
      mysqlx://foo:bar@localhost:33160/?connect-timeout=0
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required
      mysqlx://foo:bar@localhost:33160/?connect-timeout=10&compression=required&compression-algorithms=[lz4,zstd_stream]

  Für weitere Informationen siehe den Abschnitt » Connecting using a URI String zur MySQL Shell.

### Rückgabewerte

Gibt ein Session-Objekt zurück.

### Fehler/Exceptions

Ein Verbindungsfehler löst eine Exception aus.

### Beispiele

Beispiel #2 mysql_xdevapi\getSession()-Beispiel

    <?php
    try {
        $session = mysql_xdevapi\getSession("mysqlx://user:password@host");
    } catch(Exception $e) {
        die("Die Verbindung konnte nicht aufgebaut werden: " . $e->getMessage());
    }

    $schemas = $session->getSchemas();
    print_r($schemas);

    $mysql_version = $session->getServerVersion();
    print_r($mysql_version);

    var_dump($collection->find("name = 'Alfred'")->execute()->fetchOne());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => helloworld
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        [2] => mysql_xdevapi\Schema Object
            (
                [name] => mysql
            )
        [3] => mysql_xdevapi\Schema Object
            (
                [name] => performance_schema
            )
        [4] => mysql_xdevapi\Schema Object
            (
                [name] => sys
            )
    )

    80012

    array(4) {
      ["_id"]=>
      string(28) "00005ad66abf0001000400000003"
      ["age"]=>
      int(42)
      ["job"]=>
      string(7) "Butler"
      ["name"]=>
      string(4) "Alfred"
    }

## Inhaltsverzeichnis

- expression — Bindet die Variablen der vorbereiteten Anweisung als Parameter
- getSession — Baut eine Verbindung zu einem MySQL-Server auf

# Die BaseResult-Schnittstelle

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\BaseResult {
/* Methoden */
abstract public function getWarnings(): array
abstract public function getWarningsCount(): int
}

# BaseResult::getWarnings

(No version information available, might only be in Git)

BaseResult::getWarnings — Ruft Warnungen der letzten Operation ab

### Beschreibung

abstract public function mysql_xdevapi\BaseResult::getWarnings(): array

Ruft die Warnungen ab, die bei der letzten Operation des MySQL-Servers erzeugt wurden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array von Objekten mit Warnungen aus der letzten Operation zurück. Jedes Objekt enthält eine Fehlermeldung ('message'), ein Fehlerlevel ('level') und einen Fehlercode ('code'). Wenn es keinen Fehler gab, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::getWarnings()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# BaseResult::getWarningsCount

(No version information available, might only be in Git)

BaseResult::getWarningsCount — Ruft die Anzahl der Warnungen der letzten Operation ab

### Beschreibung

abstract public function mysql_xdevapi\BaseResult::getWarningsCount(): int

Gibt die Anzahl der Warnungen zurück, die bei der letzten Operation erzeugt wurden. Diese Warnungen werden insbesondere vom MySQL-Server ausgelöst.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Warnungen der letzten Operation zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::getWarningsCount()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2

## Inhaltsverzeichnis

- BaseResult::getWarnings — Ruft Warnungen der letzten Operation ab
- BaseResult::getWarningsCount — Ruft die Anzahl der Warnungen der letzten Operation ab

# Die Klasse Client

(No version information available, might only be in Git)

## Einführung

Ermöglicht den Zugriff auf den Verbindungspool.

## Klassenbeschreibung

class mysql_xdevapi\Client {
/* Methoden */
public function close(): bool
public function getSession(): mysql_xdevapi\Session
}

# mysql_xdevapi\Client::close

(No version information available, might only be in Git)

mysql_xdevapi\Client::close — Schließt die Client-Verbindung

### Beschreibung

public function mysql_xdevapi\Client::close(): bool

Schließt alle Client-Verbindungen mit dem Server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn die Verbindungen geschlossen sind.

# Client::__construct

(No version information available, might only be in Git)

Client::__construct — Der Konstruktor der Klasse Client

### Beschreibung

private function mysql_xdevapi\Client::__construct()

Erstellt ein Client-Objekt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\Client::__construct()-Beispiel

    <?php
    $pooling_options = '{
      "enabled": true,
        "maxSize": 10,
        "maxIdleTime": 3600,
        "queueTimeOut": 1000
    }';
    $client = mysql_xdevapi\getClient($connection_uri, $pooling_options);
    $session = $client->getSession();

# Client::getClient

(No version information available, might only be in Git)

Client::getClient — Ruft eine Client-Session ab

### Beschreibung

public function mysql_xdevapi\Client::getSession(): mysql_xdevapi\Session

Ruft die mit dem Client verknüpfte Session ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Session-Objekt zurück.

## Inhaltsverzeichnis

- mysql_xdevapi\Client::close — Schließt die Client-Verbindung
- Client::__construct — Der Konstruktor der Klasse Client
- Client::getClient — Ruft eine Client-Session ab

# Die Klasse Collection

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\Collection implements mysql_xdevapi\SchemaObject {
/* Eigenschaften */
public $name;
/* Methoden */
public function add(mixed `$document`): mysql_xdevapi\CollectionAdd
public function addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
public function count(): int
public function createIndex(string `$index_name`, string `$index_desc_json`): void
public function dropIndex(string `$index_name`): bool
public function existsInDatabase(): bool
public function find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind
public function getName(): string
public function getOne(string `$id`): Document
public function getSchema(): Schema Object
public function getSession(): Session
public function modify(string `$search_condition`): mysql_xdevapi\CollectionModify
public function remove(string `$search_condition`): mysql_xdevapi\CollectionRemove
public function removeOne(string `$id`): mysql_xdevapi\Result
public function replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
}

## Eigenschaften

name

# Collection::add

(No version information available, might only be in Git)

Collection::add — Fügt einer Sammlung Dokumente hinzu

### Beschreibung

public function mysql_xdevapi\Collection::add(mixed `$document`): mysql_xdevapi\CollectionAdd

Fügt die angegebenen Dokumente zu einer Sammlung hinzu, wobei diese Methode mehrere Varianten unterstützt. Zu den Möglichkeiten gehören:

1. Hinzufügen eines einzelnen Dokuments als JSON-Zeichenkette.

2. Hinzufügen eines einzelnen Dokuments als Array: `[ 'field' => 'value', 'field2' => 'value2' ... ]`

3. Eine Mischung aus beidem, wobei in einer Operation auch mehrere Dokumente hinzugefügt werden können.

### Parameter-Liste

`document`

  Ein oder mehrere Dokumente, wobei es sich entweder um JSON oder ein Array von Feldern mit den zugehörigen Werten handeln kann. Das Array darf nicht leer sein.

  Der MySQL-Server erzeugt für jedes Dokument automatisch einen eindeutigen `_id`-Wert (empfohlen), der jedoch auch manuell hinzugefügt werden kann. Dieser Wert darf noch nicht vorhanden sein, weil der Vorgang sonst fehlschlägt.

### Rückgabewerte

Gibt ein CollectionAdd-Objekt zurück. Mittels execute() wird ein Ergebnis zurückgegeben, das verwendet werden kann, um die Anzahl der betroffenen Elemente abzufragen, die Anzahl der durch den Vorgang erzeugten Warnungen zu ermitteln oder eine Liste der erzeugten IDs für die eingefügten Dokumente zu erhalten.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::add()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Hinzufügen zweier Dokumente
    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Hinzufügen zweier Dokumente mit einem einzigen JSON-Objekt
    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    // Abrufen einer Liste der beim letzten add() erzeugten IDs
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Anmerkungen

> Hinweis:

> Wie im Beispiel gezeigt, wird ab MySQL-Server 8.0 eine eindeutige _id erzeugt. Wenn MySQL 5.7 verwendet wird, muss das Feld _id manuell definiert werden.

# Collection::addOrReplaceOne

(No version information available, might only be in Git)

Collection::addOrReplaceOne — Fügt einer Sammlung ein Dokument hinzu oder ersetzt es

### Beschreibung

public function mysql_xdevapi\Collection::addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Fügt ein neues Dokument hinzu oder ersetzt ein bereits vorhandenes Dokument.

Für diese Methode gibt es mehrere Szenarien:

- Wenn weder die ID noch ein eindeutiger Wert des Schlüssels mit einem Dokument in der Sammlung übereinstimmen, wird das Dokument hinzugefügt.

- Wenn die ID mit keinem Dokument übereinstimmt, aber ein oder mehrere eindeutige Schlüsselwerte mit einem Dokument in der Sammlung übereinstimmen, wird ein Fehler ausgegeben.

- Wenn die ID mit einem vorhandenen Dokument übereinstimmt und für die Sammlung keine eindeutigen Schlüssel definiert sind, wird das Dokument ersetzt.

- Wenn die ID mit einem vorhandenen Dokument übereinstimmt und entweder alle eindeutigen Schlüssel des Ersatzdokuments mit demselben Dokument übereinstimmen oder mit keinem anderen Dokument der Sammlung in Konflikt stehen, wird das Dokument ersetzt.

- Wenn die ID mit einem vorhandenen Dokument übereinstimmt und ein oder mehrere eindeutige Schlüssel mit einem anderen Dokument aus der Sammlung übereinstimmen, wird ein Fehler ausgegeben.

### Parameter-Liste

`id`

  Die Filter-ID. Wenn diese ID oder ein anderes Feld, das einen eindeutigen Index hat, bereits in der Sammlung vorhanden ist, wird stattdessen das zugehörige Dokument aktualisiert.

  Standardmäßig wird diese ID automatisch vom MySQL-Server erzeugt, wenn der Datensatz hinzugefügt wird, und wird durch das Feld "_id" referenziert.

`doc`

  Das hinzuzufügende oder zu ersetzende Dokument; eine JSON-Zeichenkette.

### Rückgabewerte

Gibt ein Result-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::addOrReplaceOne()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Verwenden von add()
    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    // Verwenden von addOrReplaceOne()
    // Hinweis: Wir übergeben hier einen bekannten _id-Wert
    $result = $collection->addOrReplaceOne('00005b6b53610000000000000056', '{"name": "Fred",  "age": 21, "job": "Construction"}');

    ?>

# Collection::__construct

(No version information available, might only be in Git)

Collection::__construct — Der Konstruktor der Klasse Collection

### Beschreibung

private function mysql_xdevapi\Collection::__construct()

Erstellt ein Collection-Objekt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::getOne()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Eine eindeutige _id wird (standardmäßig und empfohlen) vom MySQL-Server erzeugt.
    // Dies ruft die erzeugten _id's ab; in diesem Beispiel nur eine, also $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::count

(No version information available, might only be in Git)

Collection::count — Ermittelt die Anzahl der Dokumente

### Beschreibung

public function mysql_xdevapi\Collection::count(): int

Diese Funktion ähnelt der SQL-Operation `SELECT COUNT(*)` auf dem MySQL-Server für das aktuelle Schema und die Sammlung. Anders ausgedrückt: Sie zählt die Anzahl der Dokumente in der Sammlung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Dokumente in der Sammlung zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::count()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection
      ->add(
      '{"name": "Bernie",
        "jobs": [
          {"title":"Cat Herder","Salary":42000},
          {"title":"Father","Salary":0}
        ],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [
          {"title":"Scientist","Salary":18000},
          {"title":"Mother","Salary":0}
        ],
        "hobbies": ["Walking","Making pies"]}')
      ->execute();

    var_dump($collection->count());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(2)

# Collection::createIndex

(No version information available, might only be in Git)

Collection::createIndex — Erzeugt einen Index für die Sammlung

### Beschreibung

public function mysql_xdevapi\Collection::createIndex(string `$index_name`, string `$index_desc_json`): void

Erzeugt einen Index für die Sammlung.

Wenn bereits ein Index mit dem angegebenen Namen existiert oder wenn der Index falsch definiert ist, wird eine Exception ausgelöst.

### Parameter-Liste

`index_name`

  Der Name des Indexes, der erstellt werden soll. Dieser Name muss ein gültiger Indexname sein, der von der SQL-Anweisung `CREATE INDEX` akzeptiert wird.

`index_desc_json`

  Die Definition des zu erstellenden Indexes. Er enthält ein Array von IndexField-Objekten, wobei jedes Objekt ein einzelnes Dokument beschreibt, das in den Index aufgenommen werden soll, sowie eine optionale Zeichenkette für den Typ des Index, der INDEX (Standard) oder SPATIAL sein kann.

  Eine einzelne IndexField-Beschreibung besteht aus den folgenden Feldern:

  - `field`: Zeichenkette; der vollständige Pfad zum zu indizierenden Dokument oder Feld.

  - `type`: Zeichenkette; einer der unterstützten SQL-Spaltentypen, dem das Feld zugeordnet werden soll. Bei numerischen Typen kann das optionale Schlüsselwort UNSIGNED folgen. Beim Typ TEXT kann die bei der Indizierung zu berücksichtigende Länge hinzugefügt werden.

  - `required`: Boolean; (optional) `true`, wenn das Feld im Dokument vorhanden sein muss. Der Standardwert ist `false`, außer bei `GEOJSON`, wo standardmäßig `true` verwendet wird.

  - `options`: Integer; (optional) spezielle Optionsflags, die beim Dekodieren von `GEOJSON`-Daten verwendet werden sollen.

  - `srid`: Integer; (optional) der srid-Wert, der beim Dekodieren von `GEOJSON`-Daten verwendet werden soll.

  Es ist nicht zulässig, andere, oben nicht beschriebene Felder in IndexDefinition- oder IndexField-Dokumente aufzunehmen.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::createIndex()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // Erstellen eines Textindexes
    $collection->createIndex(
      'myindex1',
      '{"fields": [{
        "field": "$.name",
        "type": "TEXT(25)",
        "required": true}],
        "unique": false}'
    );

    // Ein räumlicher Index
    $collection->createIndex(
      'myindex2',
      '{"fields": [{
        "field": "$.home",
        "type": "GEOJSON",
        "required": true}],
        "type": "SPATIAL"}'
    );

    // Ein Index mit mehreren Feldern
    $collection->createIndex(
      'myindex3',
      '{"fields": [
        {
          "field": "$.name",
          "type": "TEXT(20)",
          "required": true
        },
        {
          "field": "$.age",
          "type": "INTEGER"
        },
        {
          "field": "$.job",
          "type": "TEXT(30)",
          "required": false
        }
      ],
      "unique": true
      }'
    );

# Collection::dropIndex

(No version information available, might only be in Git)

Collection::dropIndex — Löscht den Index einer Sammlung

### Beschreibung

public function mysql_xdevapi\Collection::dropIndex(string `$index_name`): bool

Löscht den Index einer Sammlung.

Diese Operation führt nicht zu einem Fehler, wenn es den Index nicht gibt, aber in diesem Fall wird `false` zurückgegeben.

### Parameter-Liste

`index_name`

  Der Name des zu löschenden Sammlungsindexes

### Rückgabewerte

Gibt `true` zurück, wenn die Operation DROP INDEX erfolgreich war, andernfalls `false`.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::dropIndex()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    $collection->createIndex(
      'myindex',
      '{"fields": [{"field": "$.name", "type": "TEXT(25)", "required": true}], "unique": false}'
    );

    // ...

    if ($collection->dropIndex('myindex')) {
        echo "Ein Index namens 'myindex' wurde gefunden und gelöscht.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ein Index namens 'myindex' wurde gefunden und gelöscht.

# Collection::existsInDatabase

(No version information available, might only be in Git)

Collection::existsInDatabase — Prüft, ob es die Sammlung in der Datenbank gibt

### Beschreibung

public function mysql_xdevapi\Collection::existsInDatabase(): bool

Prüft, ob das Collection-Objekt auf eine Sammlung in der Datenbank (Schema) verweist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn es die Sammlung in der Datenbank gibt, und `false` wenn nicht.

Eine Tabelle, die durch zwei Spalten (doc und _id) definiert ist, wird als eine Sammlung betrachtet. Ab MySQL 8.0.21 wird eine Tabelle mit drei Spalten (doc, _id und _json_schema) als Sammlung betrachtet. Wenn weitere Spalten hinzugefügt werden, wird sie von existsInDatabase() nicht mehr als Sammlung betrachtet.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::existsInDatabase()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    // ...

    $collection = $schema->getCollection("people");

    // ...

    if (!$collection->existsInDatabase()) {
    echo "Die Sammlung gibt es in der Datenbank namens addressbook nicht mehr. Was ist passiert?";
    }
    ?>

# Collection::find

(No version information available, might only be in Git)

Collection::find — Sucht nach Dokumenten

### Beschreibung

public function mysql_xdevapi\Collection::find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind

Durchsucht eine Sammlung in einer Datenbank nach einem Dokument oder einer Gruppe von Dokumenten. Die gefundenen Dokumente werden als CollectionFind-Objekt zurückgegeben, das weiter bearbeitet werden kann oder aus dem Ergebnisse abgerufen werden können.

### Parameter-Liste

`search_condition`

  Obwohl optional, wird normalerweise eine Bedingung definiert, um die Ergebnisse auf eine Teilmenge von Dokumenten zu beschränken.

  Die Bedingung kann aus mehreren Elementen zusammengesetzt sein, und die Syntax unterstützt die Parameterbindung. Der als Suchbedingung verwendete Ausdruck muss ein gültiger SQL-Ausdruck sein. Wird keine Suchbedingung angegeben (leeres Feld), wird find('true') angenommen.

### Rückgabewerte

Ein CollectionFind-Objekt, um die Operation zu überprüfen, oder um die gefundenen Dokumente abzurufen.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::find()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred",     "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",        "age": 19, "job": "Swimmer"}')->execute();
    $collection->add('{"name": "Fred",       "age": 20, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma",      "age": 21, "job": "Teacher"}')->execute();
    $collection->add('{"name": "Suki",       "age": 22, "job": "Teacher"}')->execute();

    $find   = $collection->find('job LIKE :job AND age > :age');
    $result = $find
      ->bind(['job' => 'Teacher', 'age' => 20])
      ->sort('age DESC')
      ->limit(2)
      ->execute();

    print_r($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b536100000000000000a8
                [age] => 22
                [job] => Teacher
                [name] => Suki
            )
        [1] => Array
            (
                [_id] => 00005b6b536100000000000000a7
                [age] => 21
                [job] => Teacher
                [name] => Wilma
            )
    )

# Collection::getName

(No version information available, might only be in Git)

Collection::getName — Ruft den Namen einer Sammlung ab

### Beschreibung

public function mysql_xdevapi\Collection::getName(): string

Ruft den Namen einer Sammlung ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Namen der Sammlung als Zeichenkette zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::getName()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    var_dump($collection->getName());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(6) "people"

# Collection::getOne

(No version information available, might only be in Git)

Collection::getOne — Ruft ein Dokument ab

### Beschreibung

public function mysql_xdevapi\Collection::getOne(string `$id`): Document

Ruft ein Dokument aus einer Sammlung ab.

Dies ist eine Kurzform für: `Collection.find("_id = :id").bind("id", id).execute().fetchOne();`

### Parameter-Liste

`id`

  Die _id des Dokuments in der Sammlung

### Rückgabewerte

Gibt das Sammlungsobjekt zurück oder `null` wenn es kein Dokument mit _id gibt.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::getOne()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 42, "job": "Butler"}')->execute();

    // Eine eindeutige _id wird (standardmäßig und empfohlen) vom MySQL-Server erzeugt.
    // Dies ruft die erzeugten _id's ab; in diesem Beispiel nur eine, also $ids[0]
    $ids        = $result->getGeneratedIds();
    $alfreds_id = $ids[0];

    // ...

    print_r($alfreds_id);
    print_r($collection->getOne($alfreds_id));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    00005b6b536100000000000000b1

    Array
    (
        [_id] => 00005b6b536100000000000000b1
        [age] => 42
        [job] => Butler
        [name] => Alfred
    )

# Collection::getSchema

(No version information available, might only be in Git)

Collection::getSchema — Ruft ein Schema-Objekt ab

### Beschreibung

public function mysql_xdevapi\Collection::getSchema(): Schema Object

Ruft das Schema-Objekt ab, das die Sammlung enthält.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg das Schema-Objekt zurück oder `null`, wenn das Objekt für die angegebene Sammlung nicht abgerufen werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::getSchema()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    var_dump($collection->getSchema());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Collection::getSession

(No version information available, might only be in Git)

Collection::getSession — Ruft ein Session-Objekt ab

### Beschreibung

public function mysql_xdevapi\Collection::getSession(): Session

Ruft ein neues Session-Objekt aus einer Sammlung ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Session-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::getSession()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    // ...

    $newsession = $collection->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(mysql_xdevapi\Session)#1 (0) {
    }
    object(mysql_xdevapi\Session)#4 (0) {
    }

# Collection::modify

(No version information available, might only be in Git)

Collection::modify — Ändert Dokumente einer Sammlung

### Beschreibung

public function mysql_xdevapi\Collection::modify(string `$search_condition`): mysql_xdevapi\CollectionModify

Ändert die Dokumente einer Sammlung, die bestimmte Suchbedingungen erfüllen. Es sind mehrere Operationen möglich und die Bindung von Parametern wird unterstützt.

### Parameter-Liste

`search_condition`

  Muss ein gültiger SQL-Ausdruck sein, der zum Abgleich der zu ändernden Dokumente verwendet wird. Ein solcher Ausdruck kann ein einfaches `true` sein, das auf alle Dokumente zutrifft, oder er kann Funktionen und Operatoren verwenden wie `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'` oder `'_id IN ["2","5","7","10"]'`.

### Rückgabewerte

Wenn die Operation nicht ausgeführt wird, gibt die Funktion ein Modify-Objekt zurück, dem weitere Änderungsoperationen hinzugefügt werden können.

Wird die Operation ausgeführt, dann enthält das zurückgegebene Objekt das Ergebnis der Operation.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::modify()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Hinzufügen von zwei neuen Jobs für alle Painter: Artist und Crafter
    $collection
      ->modify("job in ('Butler', 'Painter')")
      ->arrayAppend('job', 'Artist')
      ->arrayAppend('job', 'Crafter')
      ->execute();

    // Entfernen des Feldes 'beer' aus allen Dokumenten mit 'age < 21'
    $collection
      ->modify('age < 21')
      ->unset(['beer'])
      ->execute();
    ?>

# Collection::remove

(No version information available, might only be in Git)

Collection::remove — Löscht Dokumente einer Sammlung

### Beschreibung

public function mysql_xdevapi\Collection::remove(string `$search_condition`): mysql_xdevapi\CollectionRemove

Löscht die Dokumente einer Sammlung, die bestimmte Suchbedingungen erfüllen. Es sind mehrere Operationen möglich und die Bindung von Parametern wird unterstützt.

### Parameter-Liste

`search_condition`

  Muss ein gültiger SQL-Ausdruck sein, der zum Abgleich der zu löschenden Dokumente verwendet wird. Ein solcher Ausdruck kann ein einfaches `true` sein, das auf alle Dokumente zutrifft, oder er kann Funktionen und Operatoren verwenden wie `'CAST(_id AS SIGNED) >= 10'`, `'age MOD 2 = 0 OR age MOD 3 = 0'` oder `'_id IN ["2","5","7","10"]'`.

### Rückgabewerte

Wenn die Operation nicht ausgeführt wird, gibt die Funktion ein Remove-Objekt zurück, dem weitere Löschvorgänge hinzugefügt werden können.

Wird die Operation ausgeführt, dann enthält das zurückgegebene Objekt das Ergebnis der Operation.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::remove()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Entfernen aller Painter
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Entfernen des ältesten Butlers
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Entfernen des Datensatzes mit dem höchsten Alter (age)
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# Collection::removeOne

(No version information available, might only be in Git)

Collection::removeOne — Löscht ein Dokument einer Sammlung

### Beschreibung

public function mysql_xdevapi\Collection::removeOne(string `$id`): mysql_xdevapi\Result

Löscht das Dokument mit der zugehörigen ID aus der Sammlung. Dies ist eine Kurzform für `Collection.remove("_id = :id").bind("id", id).execute()`.

### Parameter-Liste

`id`

  Die ID des zu entfernenden Dokuments. Normalerweise ist dies die _id, die vom MySQL-Server beim Hinzufügen des Datensatzes erzeugt wurde.

### Rückgabewerte

Gibt ein Result-Objekt zurück, das verwendet werden kann, um die Anzahl der betroffenen Elemente und die Anzahl der durch die Operation erzeugten Warnungen abzufragen.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::removeOne()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Normalerweise ist die _id aus anderen Quellen bekannt, aber für
    // dieses Beispiel rufen wir die generierte ID ab und verwenden sie
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    $result = $collection->removeOne($alfred_id);

    if(!$result->getAffectedItemsCount()) {
        echo "Alfred mit der ID $alfred_id wurde nicht entfernt.";
    } else {
        echo "Auf Wiedersehen, Alfred, du kannst _id $alfred_id mitnehmen.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Auf Wiedersehen, Alfred, du kannst _id 00005b6b536100000000000000cb mitnehmen.

# Collection::replaceOne

(No version information available, might only be in Git)

Collection::replaceOne — Ersetzt ein Dokument einer Sammlung

### Beschreibung

public function mysql_xdevapi\Collection::replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result

Aktualisiert (oder ersetzt) das durch die ID angegebene Dokument, sofern es vorhanden ist.

### Parameter-Liste

`id`

  Die ID des Dokuments, das ersetzt oder aktualisiert werden soll. Normalerweise ist dies die _id, die vom MySQL-Server beim Hinzufügen des Datensatzes erzeugt wurde.

`doc`

  Das Dokument, mit dem das zum Parameter `id` gehörende Dokument aktualisiert oder ersetzt werden soll.

  Dieses Dokument kann entweder ein Dokument-Objekt sein oder eine gültige JSON-Zeichenkette, die das neue Dokument beschreibt.

### Rückgabewerte

Gibt ein Result-Objekt zurück, das verwendet werden kann, um die Anzahl der betroffenen Elemente und die Anzahl der durch die Operation erzeugten Warnungen abzufragen.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::replaceOne()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();

    // Normalerweise ist die _id aus anderen Quellen bekannt, aber für
    // dieses Beispiel rufen wir die generierte ID ab und verwenden sie
    $ids       = $result->getGeneratedIds();
    $alfred_id = $ids[0];

    // ...

    $alfred = $collection->getOne($alfred_id);
    $alfred['age'] = 81;
    $alfred['job'] = 'Guru';

    $collection->replaceOne($alfred_id, $alfred);

    ?>

## Inhaltsverzeichnis

- Collection::add — Fügt einer Sammlung Dokumente hinzu
- Collection::addOrReplaceOne — Fügt einer Sammlung ein Dokument hinzu oder ersetzt es
- Collection::__construct — Der Konstruktor der Klasse Collection
- Collection::count — Ermittelt die Anzahl der Dokumente
- Collection::createIndex — Erzeugt einen Index für die Sammlung
- Collection::dropIndex — Löscht den Index einer Sammlung
- Collection::existsInDatabase — Prüft, ob es die Sammlung in der Datenbank gibt
- Collection::find — Sucht nach Dokumenten
- Collection::getName — Ruft den Namen einer Sammlung ab
- Collection::getOne — Ruft ein Dokument ab
- Collection::getSchema — Ruft ein Schema-Objekt ab
- Collection::getSession — Ruft ein Session-Objekt ab
- Collection::modify — Ändert Dokumente einer Sammlung
- Collection::remove — Löscht Dokumente einer Sammlung
- Collection::removeOne — Löscht ein Dokument einer Sammlung
- Collection::replaceOne — Ersetzt ein Dokument einer Sammlung

# Die Klasse CollectionAdd

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\CollectionAdd implements mysql_xdevapi\Executable {
/* Methoden */
public function execute(): mysql_xdevapi\Result
}

# CollectionAdd::__construct

(No version information available, might only be in Git)

CollectionAdd::__construct — Der Konstruktor der Klasse CollectionAdd

### Beschreibung

private function mysql_xdevapi\CollectionAdd::__construct()

Wird verwendet, um ein Dokument zu einer Sammlung hinzuzufügen; wird von einem Collection-Objekt aufgerufen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionAdd::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Hinzufügen zweier Dokumente
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Hinzufügen zweier Dokumente mit einem einzigen JSON-Objekt
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Abrufen einer Liste der beim letzten add() erzeugten IDs
    $ids = $result->getGeneratedIds();
    print_r($ids);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

### Anmerkungen

> Hinweis:

> Wie im Beispiel gezeigt, wird ab MySQL-Server 8.0 eine eindeutige _id erzeugt. Wenn MySQL 5.7 verwendet wird, muss das Feld _id manuell definiert werden.

# CollectionAdd::execute

(No version information available, might only be in Git)

CollectionAdd::execute — Führt eine Anweisung aus

### Beschreibung

public function mysql_xdevapi\CollectionAdd::execute(): mysql_xdevapi\Result

Die Methode execute wird benötigt, um eine Anforderung für eine CRUD-Operation an den MySQL-Server zu senden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Result-Objekt zurück, das verwendet werden kann, um den Status der Operation zu überprüfen, z. B. die Anzahl der betroffenen Zeilen.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionAdd::execute()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    // Hinzufügen zweier Dokumente
    $collection
      ->add('{"name": "Fred",  "age": 21, "job": "Construction"}')
      ->execute();

    $collection
      ->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')
      ->execute();

    // Hinzufügen zweier Dokumente mit einem einzigen JSON-Objekt
    $result = $collection
      ->add(
        '{"name": "Bernie",
          "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
          "hobbies": ["Sports","Making cupcakes"]}',
        '{"name": "Jane",
          "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
          "hobbies": ["Walking","Making pies"]}')
      ->execute();

    // Abrufen einer Liste der beim letzten add() erzeugten IDs
    $ids = $result->getGeneratedIds();
    print_r($ids);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 00005b6b53610000000000000056
        [1] => 00005b6b53610000000000000057
    )

## Inhaltsverzeichnis

- CollectionAdd::__construct — Der Konstruktor der Klasse CollectionAdd
- CollectionAdd::execute — Führt eine Anweisung aus

# Die Klasse CollectionFind

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\CollectionFind implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Methoden */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind
public function execute(): mysql_xdevapi\DocResult
public function fields(string `$projection`): mysql_xdevapi\CollectionFind
public function groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function having(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function limit(int `$rows`): mysql_xdevapi\CollectionFind
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function offset(int `$position`): mysql_xdevapi\CollectionFind
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionFind
}

# CollectionFind::bind

(No version information available, might only be in Git)

CollectionFind::bind — Bindet einen Wert an den Platzhalter einer Abfrage

### Beschreibung

public function mysql_xdevapi\CollectionFind::bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind

Mit dieser Funktion kann ein Parameter an den Platzhalter in der Suchbedingung einer Suchanfrage gebunden werden. Der Platzhalter hat die Form :NAME, wobei ':' ein gewöhnliches Präfix ist, das vor jedem NAME stehen muss; NAME ist der eigentliche Name des Platzhalters. Um mehrere Elemente in der Suchbedingung ersetzen zu können, akzeptiert diese Funktion eine Liste von Platzhaltern.

### Parameter-Liste

`placeholder_values`

  Die Werte, die in der Suchbedingung ersetzt werden sollen; mehrere Werte sind zulässig und werden als Array mit "PLATZHALTER_NAME => PLATZHALTER_WERT" übergeben.

### Rückgabewerte

Gibt ein CollectionFind-Objekt zurück. Alternativ kann es mit execute() verkettet werden, um ein Result-Objekt zu erhalten.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionFind::bind()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::__construct

(No version information available, might only be in Git)

CollectionFind::__construct — Der Konstruktor der Klasse CollectionFind

### Beschreibung

private function mysql_xdevapi\CollectionFind::__construct()

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 CollectionFind-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $result = $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::execute

(No version information available, might only be in Git)

CollectionFind::execute — Führt eine Anweisung aus

### Beschreibung

public function mysql_xdevapi\CollectionFind::execute(): mysql_xdevapi\DocResult

Führt eine Suchoperation aus; diese Funktion bietet die Möglichkeit, Methoden zu verketten.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein mysql_xdevapi\DocResult-Objekt zurück, aus dem Ergebnisse abgerufen werden können oder der Status des Vorgangs abgefragt werden kann.

### Beispiele

Beispiel #1 CollectionFind-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->execute();

    var_dump($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000cf"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::fields

(No version information available, might only be in Git)

CollectionFind::fields — Setzt den Filter für die Felder eines Dokuments

### Beschreibung

public function mysql_xdevapi\CollectionFind::fields(string `$projection`): mysql_xdevapi\CollectionFind

Definiert die Spalten, die die Abfrage zurückgeben soll. Falls nicht angegeben, werden alle Spalten zurückgegeben.

### Parameter-Liste

`projection`

  Kann entweder eine einzelne Zeichenkette sein oder ein Array von Zeichenketten, die die Spalten bestimmen, die von jedem Dokument, das die Suchbedingung erfüllt, zurückgegeben werden sollen.

### Rückgabewerte

Gibt ein CollectionFind-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionFind::fields()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->fields('name')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(1) {
        ["name"]=>
        string(6) "Alfred"
      }
    }

# CollectionFind::groupBy

(No version information available, might only be in Git)

CollectionFind::groupBy — Setzt die Kriterien für die Gruppierung

### Beschreibung

public function mysql_xdevapi\CollectionFind::groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind

Diese Funktion kann verwendet werden, um die Ergebnismenge nach einer oder mehreren Spalten zu gruppieren. Sie wird häufig mit Aggregatfunktionen wie `COUNT`, `MAX`, `MIN`, `SUM` usw. verwendet.

### Parameter-Liste

`sort_expr`

  Die Spalte(n), die für die Gruppierungsoperation verwendet werden soll(en). Dies kann entweder eine einzelne Zeichenkette sein oder ein Array von Zeichenketten, die jeweils eine Spalte bezeichnen.

### Rückgabewerte

Gibt ein CollectionFind-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionFind::groupBy()-Beispiel

    <?php

    // Unter der Annahme, dass $coll ein gültiges Collection-Objekt ist

    // Abrufen aller Dokumente aus der Sammlung und Gruppieren der Ergebnisse nach der Spalte 'name'.
    $res = $coll->find()->groupBy('name')->execute();

    ?>

# CollectionFind::having

(No version information available, might only be in Git)

CollectionFind::having — Setzt Bedingungen für Aggregatfunktionen

### Beschreibung

public function mysql_xdevapi\CollectionFind::having(string `$sort_expr`): mysql_xdevapi\CollectionFind

Diese Funktion kann nach der "field"-Operation verwendet werden, um die abzurufenden Dokumente auszuwählen.

### Parameter-Liste

`sort_expr`

  Dies muss ein gültiger SQL-Ausdruck sein; es können auch Aggregatfunktionen verwendet werden.

### Rückgabewerte

Gibt ein CollectionFind-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionFind::having()-Beispiel

    <?php

    // Unter der Annahme, dass $coll ein gültiges Collection-Objekt ist

    // Finde alle Dokumente, bei denen 'age' größer als 40 ist.
    // Nur die Spalten 'name' und 'age' werden im Ergebnisobjekt zurückgegeben
    $res = $coll->find()->fields(['name','age'])->having('age > 40')->execute();

    ?>

# CollectionFind::limit

(No version information available, might only be in Git)

CollectionFind::limit — Begrenzt die Anzahl der zurückgegebenen Dokumente

### Beschreibung

public function mysql_xdevapi\CollectionFind::limit(int `$rows`): mysql_xdevapi\CollectionFind

Legt die maximale Anzahl der zurückzugebenden Dokumente fest.

### Parameter-Liste

`rows`

  Die maximale Anzahl von Dokumenten

### Rückgabewerte

Gibt ein CollectionFind-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann; kann mit der Methode execute() verkettet werden, die dann ein DocResult-Objekt zurückgibt.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionFind::limit()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::lockExclusive

(No version information available, might only be in Git)

CollectionFind::lockExclusive — Führt eine Operation mit EXCLUSIVE LOCK aus

### Beschreibung

public function mysql_xdevapi\CollectionFind::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Sperrt das Dokument exklusiv. Solange das Dokument gesperrt ist, können andere Transaktionen das Dokument nicht aktualisieren, `SELECT ... LOCK IN SHARE MODE` verwenden oder die Daten in bestimmten Isolationsstufen der Transaktion lesen. Zusammenhängende Lesevorgänge ignorieren alle Sperren, die auf die in der Leseansicht vorhandenen Datensätze gesetzt sind.

Um Gleichzeitigkeitsprobleme zu vermeiden, ist es sinnvoll, diese Funktion zusammen mit der Methode mysql_xdevapi\Collection::modify() zu verwenden. Im Wesentlichen verwendet diese Funktion Zeilensperren, um den Zugriff auf Zeilen zu serialisieren.

### Parameter-Liste

`lock_waiting_option`

  Die optionale Warteoption. Voreingestellt ist `MYSQLX_LOCK_DEFAULT`. Folgende Konstanten sind zulässig:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Rückgabewerte

Gibt ein CollectionFind-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionFind::lockExclusive()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockExclusive()
      ->execute();

    // ... durchführen einer Operation am Objekt

    // Abschließen der Transaktion und entsperren des Dokuments
    $session->commit();
    ?>

# CollectionFind::lockShared

(No version information available, might only be in Git)

CollectionFind::lockShared — Führt eine Operation mit SHARED LOCK aus

### Beschreibung

public function mysql_xdevapi\CollectionFind::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind

Ermöglicht die gemeinsame Nutzung der Dokumente durch mehrere Transaktionen, die im Shared Mode (geteilter Modus) gesperrt sind.

Solange die Transaktion nicht bestätigt ist, können andere Sessions die Zeilen lesen, aber nicht ändern.

Wenn eine dieser Zeilen durch eine andere noch nicht bestätigte Transaktion geändert wurde, wartet die Abfrage, bis diese Transaktion beendet ist, um die neuesten Werte verwenden zu können.

### Parameter-Liste

`lock_waiting_option`

  Die optionale Warteoption. Voreingestellt ist `MYSQLX_LOCK_DEFAULT`. Folgende Konstanten sind zulässig:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Rückgabewerte

Gibt ein CollectionFind-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionFind::lockShared()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $session->startTransaction();

    $result = $collection
      ->find("age > 50")
      ->lockShared()
      ->execute();

    // ... lesen des Objekts im Shared Mode

    // Abschließen der Transaktion und entsperren des Dokuments
    $session->commit();
    ?>

# CollectionFind::offset

(No version information available, might only be in Git)

CollectionFind::offset — Überspringt die angegebene Anzahl von Elementen, die zurückgegeben werden sollen

### Beschreibung

public function mysql_xdevapi\CollectionFind::offset(int `$position`): mysql_xdevapi\CollectionFind

Überspringt die angegebene Anzahl von Elementen, die sonst von der Suchoperation zurückgegeben werden würden; wird zusammen mit der Methode limit() verwendet.

Wenn ein Offset angegeben wird, der größer als die Größe der Ergebnismenge ist, führt dies zu einer leeren Menge.

### Parameter-Liste

`position`

  Die Anzahl der für die limit()-Operation zu überspringenden Elemente

### Rückgabewerte

Gibt ein CollectionFind-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionFind::offset()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('age asc')
      ->offset(1)
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# CollectionFind::sort

(No version information available, might only be in Git)

CollectionFind::sort — Setzt die Kriterien für die Sortierung

### Beschreibung

public function mysql_xdevapi\CollectionFind::sort(string `$sort_expr`): mysql_xdevapi\CollectionFind

Sortiert die Ergebnismenge nach der im Argument sort_expr ausgewählten Spalte. Möglich sind die Reihenfolgen ASC (aufsteigend) und DESC (absteigend). Diese Operation entspricht der SQL-Operation 'ORDER BY' und folgt denselben Regeln.

### Parameter-Liste

`sort_expr`

  Es können ein oder mehrere durch Komma getrennte Sortierausdrücke angegeben werden. Die Auswertung erfolgt von links nach rechts.

### Rückgabewerte

Gibt ein CollectionFind-Objekt zurück, das verwendet werden kann, um den Befehl auszuführen oder um weitere Operationen hinzuzufügen.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionFind::sort()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");
    $create
      ->add('{"name": "Alfred", "age": 18, "job": "Butler"}')
      ->execute();
    $create
      ->add('{"name": "Reginald", "age": 42, "job": "Butler"}')
      ->execute();

    // ...

    $collection = $schema->getCollection("people");

    $result = $collection
      ->find()
      ->sort('job desc', 'age asc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(2) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000106"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }
      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000107"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

## Inhaltsverzeichnis

- CollectionFind::bind — Bindet einen Wert an den Platzhalter einer Abfrage
- CollectionFind::__construct — Der Konstruktor der Klasse CollectionFind
- CollectionFind::execute — Führt eine Anweisung aus
- CollectionFind::fields — Setzt den Filter für die Felder eines Dokuments
- CollectionFind::groupBy — Setzt die Kriterien für die Gruppierung
- CollectionFind::having — Setzt Bedingungen für Aggregatfunktionen
- CollectionFind::limit — Begrenzt die Anzahl der zurückgegebenen Dokumente
- CollectionFind::lockExclusive — Führt eine Operation mit EXCLUSIVE LOCK aus
- CollectionFind::lockShared — Führt eine Operation mit SHARED LOCK aus
- CollectionFind::offset — Überspringt die angegebene Anzahl von Elementen, die zurückgegeben werden sollen
- CollectionFind::sort — Setzt die Kriterien für die Sortierung

# Die Klasse CollectionModify

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\CollectionModify implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSkippable, mysql_xdevapi\CrudOperationSortable {
/* Methoden */
public function arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionModify
public function patch(string `$document`): mysql_xdevapi\CollectionModify
public function replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function skip(int `$position`): mysql_xdevapi\CollectionModify
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionModify
public function unset(array `$fields`): mysql_xdevapi\CollectionModify
}

# CollectionModify::arrayAppend

(No version information available, might only be in Git)

CollectionModify::arrayAppend — Hängt ein Element an das Array eines Feldes an

### Beschreibung

public function mysql_xdevapi\CollectionModify::arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Fügt dem Feld eines Dokuments ein Element hinzu. Mehrere Elemente eines Feldes werden als Array dargestellt. Im Gegensatz zu arrayInsert(), wo die Position für ein neues Element angegeben werden kann, wird es bei arrayAppend() immer am Ende des Arrays angehängt.

### Parameter-Liste

`collection_field`

  Der Bezeichner des Feldes, in das das neue Element eingefügt wird

`expression_or_literal`

  Das neue Element, das am Ende des Dokumentfeld-Arrays eingefügt wird

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück, das verwendet werden kann, um den Befehl auszuführen oder um weitere Operationen hinzuzufügen.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::arrayAppend()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::arrayInsert

(No version information available, might only be in Git)

CollectionModify::arrayInsert — Fügt ein Element in das Array eines Feldes ein

### Beschreibung

public function mysql_xdevapi\CollectionModify::arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Fügt dem Feld eines Dokuments ein Element hinzu. Mehrere Elemente eines Feldes werden als Array dargestellt. Im Gegensatz zu CollectionModify::arrayAppend(), wo das neue Element immer am Ende des Arrays angehängt wird, kann bei dieser Methode die Position für ein neues Element angegeben werden.

### Parameter-Liste

`collection_field`

  Bezeichnet das Element im Array, nach dem das neue Element eingefügt wird. Das Format dieses Parameters ist `FIELD_NAME[ INDEX ]`, wobei FIELD_NAME der Name des Dokumentfeldes ist, dem das Element hinzugefügt werden soll, und INDEX der Index des Elements innerhalb des Feldes ist.

  Das Feld INDEX ist nullbasiert, d. h. das erste Element des Arrays hat einen Index von 0.

`expression_or_literal`

  Das neue Element, das nach FIELD_NAME[ INDEX ] eingefügt wird

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück, das verwendet werden kann, um den Befehl auszuführen oder um weitere Operationen hinzuzufügen.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::arrayInsert()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayInsert('traits[1]', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010d
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Happy
                        [2] => Brother
                        [3] => Human
                    )
            )
    )

# CollectionModify::bind

(No version information available, might only be in Git)

CollectionModify::bind — Bindet einen Wert an einen Platzhalter einer Abfrage

### Beschreibung

public function mysql_xdevapi\CollectionModify::bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify

Bindet einen Parameter an einen Platzhalter in der Suchbedingung einer Änderungsoperation.

Der Platzhalter hat die Form :NAME, wobei ":" ein gewöhnliches Präfix ist, das immer vor NAME, dem Namen des Platzhalters, stehen muss. Für den Fall, dass mehrere Entitäten in der Suchbedingung der Änderungsoperation ersetzt werden müssen, akzeptiert die bind-Methode auch eine Liste von Platzhaltern.

### Parameter-Liste

`placeholder_values`

  Die Werte der Platzhalter, die in der Suchbedingung ersetzt werden sollen. Es sind mehrere Werte erlaubt, die als Array von Zuordnungen der Form PLATZHALTER_NAME->PLATZHALTER_WERT übergeben werden müssen.

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück, das verwendet werden kann, um den Befehl auszuführen oder um weitere Operationen hinzuzufügen.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::bind()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000110
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::__construct

(No version information available, might only be in Git)

CollectionModify::__construct — Der Konstruktor der Klasse CollectionModify

### Beschreibung

private function mysql_xdevapi\CollectionModify::__construct()

Ändert (aktualisiert) eine Sammlung und wird durch die Methode mysql_xdevapi\Collection::modify() instanziiert.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name in ('Bernie', 'Jane')")
      ->arrayAppend('traits', 'Happy')
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000010c
                [name] => Bernie
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                        [3] => Happy
                    )
            )
    )

# CollectionModify::execute

(No version information available, might only be in Git)

CollectionModify::execute — Führt eine Änderungsoperation aus

### Beschreibung

public function mysql_xdevapi\CollectionModify::execute(): mysql_xdevapi\Result

Die Methode execute wird benötigt, um eine Anforderung für eine CRUD-Operation an den MySQL-Server zu senden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Result-Objekt zurück, das verwendet werden kann, um den Status der Operation zu überprüfen, z. B. die Anzahl der betroffenen Zeilen.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::execute()-Beispiel

    <?php

    /* ... */

    ?>

# CollectionModify::limit

(No version information available, might only be in Git)

CollectionModify::limit — Begrenzt die Anzahl der zu ändernden Dokumente

### Beschreibung

public function mysql_xdevapi\CollectionModify::limit(int `$rows`): mysql_xdevapi\CollectionModify

Begrenzt die Anzahl der Dokumente, die durch diesen Vorgang verändert werden; kann mit skip() kombiniert werden, um die Anzahl der zu überspringenden Dokumente anzugeben.

### Parameter-Liste

`rows`

  Die maximale Anzahl der zu ändernden Dokumente

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::limit()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();
    $collection->add('{"name": "Betty", "age": 24, "job": "Teacher"}')->execute();

    $collection
      ->modify("job = :job")
      ->bind(['job' => 'Teacher'])
      ->set('job', 'Principal')
      ->limit(1)
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000118
                [age] => 21
                [job] => Construction
                [name] => Fred
            )
        [1] => Array
            (
                [_id] => 00005b6b53610000000000000119
                [age] => 23
                [job] => Principal
                [name] => Wilma
            )
        [2] => Array
            (
                [_id] => 00005b6b5361000000000000011a
                [age] => 24
                [job] => Teacher
                [name] => Betty
            )
    )

# CollectionModify::patch

(No version information available, might only be in Git)

CollectionModify::patch — Patcht ein Dokument

### Beschreibung

public function mysql_xdevapi\CollectionModify::patch(string `$document`): mysql_xdevapi\CollectionModify

Übernimmt ein Patch-Objekt und wendet es auf ein oder mehrere Dokumente an und kann mehrere Dokumenteigenschaften aktualisieren.

### Parameter-Liste

`document`

  Ein Dokument mit den Eigenschaften, die auf die übereinstimmenden Dokumente anzuwenden sind.

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::patch()-Beispiel

    <?php

    $res = $coll->modify('"Programmatore" IN job')->patch('{"Hobby" : "Programmare"}')->execute();

    ?>

# CollectionModify::replace

(No version information available, might only be in Git)

CollectionModify::replace — Ersetzt ein Feld eines Dokuments

### Beschreibung

public function mysql_xdevapi\CollectionModify::replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Ersetzt (aktualisiert) den Wert des angegebenen Feldes durch einen neuen Wert.

### Parameter-Liste

`collection_field`

  Der Dokumentpfad (Name) des zu setzenden Elements

`expression_or_literal`

  Der Wert, auf den das angegebene Attribut gesetzt werden soll

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::replace()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->replace("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b5361000000000000011b
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::set

(No version information available, might only be in Git)

CollectionModify::set — Setzt ein Attribut eines Dokuments

### Beschreibung

public function mysql_xdevapi\CollectionModify::set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify

Setzt oder aktualisiert Attribute der Dokumente in einer Sammlung.

### Parameter-Liste

`collection_field`

  Der Dokumentpfad (Name) des zu setzenden Elements

`expression_or_literal`

  Der Wert, auf den das angegebene Attribut gesetzt werden soll

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::set()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $result = $collection
      ->add(
      '{"name":   "Bernie",
        "traits": ["Friend", "Brother", "Human"]}')
      ->execute();

    $collection
      ->modify("name = :name")
      ->bind(['name' => 'Bernie'])
      ->set("name", "Bern")
      ->execute();

    $result = $collection
      ->find()
      ->execute();

    print_r($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [_id] => 00005b6b53610000000000000111
                [name] => Bern
                [traits] => Array
                    (
                        [0] => Friend
                        [1] => Brother
                        [2] => Human
                    )
            )
    )

# CollectionModify::skip

(No version information available, might only be in Git)

CollectionModify::skip — Überspringt Elemente

### Beschreibung

public function mysql_xdevapi\CollectionModify::skip(int `$position`): mysql_xdevapi\CollectionModify

Überspringt die ersten N Elemente, die andernfalls durch eine Suchoperation zurückgegeben werden würden. Wenn die Anzahl der übersprungenen Elemente größer ist als die Größe der Ergebnismenge, dann gibt die Suchoperation eine leere Menge zurück.

### Parameter-Liste

`position`

  Die Anzahl der zu überspringenden Elemente

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::skip()-Beispiel

    <?php

    $coll->modify('age > :age')->sort('age desc')->unset(['age'])->bind(['age' => 20])->limit(4)->skip(1)->execute();

    ?>

# CollectionModify::sort

(No version information available, might only be in Git)

CollectionModify::sort — Setzt die Kriterien für die Sortierung

### Beschreibung

public function mysql_xdevapi\CollectionModify::sort(string `$sort_expr`): mysql_xdevapi\CollectionModify

Sortiert die Ergebnismenge nach der im Argument sort_expr ausgewählten Spalte. Möglich sind die Reihenfolgen ASC (aufsteigend) und DESC (absteigend). Diese Operation entspricht der SQL-Operation 'ORDER BY' und folgt denselben Regeln.

### Parameter-Liste

`sort_expr`

  Es können ein oder mehrere durch Komma getrennte Sortierausdrücke angegeben werden. Die Auswertung erfolgt von links nach rechts.

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::sort()-Beispiel

    <?php

    $res = $coll->modify('true')->sort('name desc', 'age asc')->limit(4)->set('Married', 'NO')->execute();

    ?>

# CollectionModify::unset

(No version information available, might only be in Git)

CollectionModify::unset — Löscht den Wert eines Feldes in einem Dokument

### Beschreibung

public function mysql_xdevapi\CollectionModify::unset(array `$fields`): mysql_xdevapi\CollectionModify

Entfernt Attribute aus den Dokumenten einer Sammlung.

### Parameter-Liste

`fields`

  Die Attribute, die aus den Dokumenten einer Sammlung entfernt werden sollen

### Rückgabewerte

Gibt ein CollectionModify-Objekt zurück, das für die weitere Verarbeitung verwendet werden kann.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionModify::unset()-Beispiel

    <?php

    $res = $coll->modify('job like :job_name')->unset(["age", "name"])->bind(['job_name' => 'Plumber'])->execute();

    ?>

## Inhaltsverzeichnis

- CollectionModify::arrayAppend — Hängt ein Element an das Array eines Feldes an
- CollectionModify::arrayInsert — Fügt ein Element in das Array eines Feldes ein
- CollectionModify::bind — Bindet einen Wert an einen Platzhalter einer Abfrage
- CollectionModify::__construct — Der Konstruktor der Klasse CollectionModify
- CollectionModify::execute — Führt eine Änderungsoperation aus
- CollectionModify::limit — Begrenzt die Anzahl der zu ändernden Dokumente
- CollectionModify::patch — Patcht ein Dokument
- CollectionModify::replace — Ersetzt ein Feld eines Dokuments
- CollectionModify::set — Setzt ein Attribut eines Dokuments
- CollectionModify::skip — Überspringt Elemente
- CollectionModify::sort — Setzt die Kriterien für die Sortierung
- CollectionModify::unset — Löscht den Wert eines Feldes in einem Dokument

# Die Klasse CollectionRemove

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\CollectionRemove implements mysql_xdevapi\Executable, mysql_xdevapi\CrudOperationBindable, mysql_xdevapi\CrudOperationLimitable, mysql_xdevapi\CrudOperationSortable {
/* Methoden */
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionRemove
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove
}

# CollectionRemove::bind

(No version information available, might only be in Git)

CollectionRemove::bind — Bindet einen Wert an einen Platzhalter

### Beschreibung

public function mysql_xdevapi\CollectionRemove::bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove

Bindet einen Parameter an einen Platzhalter in der Suchbedingung einer Löschoperation.

Der Platzhalter hat die Form :NAME, wobei ":" ein gewöhnliches Präfix ist, das immer vor NAME, dem Namen des Platzhalters, stehen muss. Für den Fall, dass mehrere Entitäten in der Suchbedingung der Löschoperation ersetzt werden müssen, akzeptiert die bind-Methode auch eine Liste von Platzhaltern.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`placeholder_values`

  Die Werte der Platzhalter, die in der Suchbedingung ersetzt werden sollen. Es sind mehrere Werte erlaubt, die als Array von Zuordnungen der Form PLATZHALTER_NAME->PLATZHALTER_WERT übergeben werden müssen.

### Rückgabewerte

Gibt ein CollectionRemove-Objekt zurück, das verwendet werden kann, um den Befehl auszuführen oder um weitere Operationen hinzuzufügen.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionRemove::bind()-Beispiel

    <?php

    $res = $coll->remove('age > :age_from and age < :age_to')->bind(['age_from' => 20, 'age_to' => 50])->limit(7)->execute();

    ?>

# CollectionRemove::__construct

(No version information available, might only be in Git)

CollectionRemove::__construct — Der Konstruktor der Klasse CollectionRemove

### Beschreibung

private function mysql_xdevapi\CollectionRemove::__construct()

Entfernt Dokumente aus einer Sammlung und wird durch die Methode mysql_xdevapi\Collection::remove() instanziiert.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\Collection::remove()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("people");

    $collection->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $collection->add('{"name": "Bob",    "age": 19, "job": "Painter"}')->execute();

    // Entfernen aller Painter
    $collection
      ->remove("job in ('Painter')")
      ->execute();

    // Entfernen des ältesten Butlers
    $collection
      ->remove("job in ('Butler')")
      ->sort('age desc')
      ->limit(1)
      ->execute();

    // Entfernen des Datensatzes mit dem niedrigsten age
    $collection
      ->remove('true')
      ->sort('age desc')
      ->limit(1)
      ->execute();
    ?>

# CollectionRemove::execute

(No version information available, might only be in Git)

CollectionRemove::execute — Führt eine Löschoperation aus

### Beschreibung

public function mysql_xdevapi\CollectionRemove::execute(): mysql_xdevapi\Result

Die Funktion execute muss aufgerufen werden, damit der Client eine Anforderung für eine CRUD-Operation an den Server sendet.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Result-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionRemove::execute()-Beispiel

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

# CollectionRemove::limit

(No version information available, might only be in Git)

CollectionRemove::limit — Begrenzt die Anzahl der zu löschenden Dokumente

### Beschreibung

public function mysql_xdevapi\CollectionRemove::limit(int `$rows`): mysql_xdevapi\CollectionRemove

Legt die maximale Anzahl der zu löschenden Dokumente fest.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`rows`

  Die maximale Anzahl der zu löschenden Dokumente

### Rückgabewerte

Gibt ein CollectionRemove-Objekt zurück, das verwendet werden kann, um den Befehl auszuführen oder um weitere Operationen hinzuzufügen.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionRemove::limit()-Beispiel

    <?php

    $res = $coll->remove('job in (\'Barista\', \'Programmatore\', \'Ballerino\', \'Programmatrice\')')->limit(5)->sort(['age desc', 'name asc'])->execute();

    ?>

# CollectionRemove::sort

(No version information available, might only be in Git)

CollectionRemove::sort — Setzt die Kriterien für die Sortierung

### Beschreibung

public function mysql_xdevapi\CollectionRemove::sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove

Sortiert die Ergebnismenge nach der im Argument sort_expr ausgewählten Spalte. Möglich sind die Reihenfolgen ASC (aufsteigend) und DESC (absteigend). Diese Operation entspricht der SQL-Operation 'ORDER BY' und folgt denselben Regeln.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`sort_expr`

  Es können ein oder mehrere durch Komma getrennte Sortierausdrücke angegeben werden. Die Auswertung erfolgt von links nach rechts.

### Rückgabewerte

Gibt ein CollectionRemove-Objekt zurück, das verwendet werden kann, um den Befehl auszuführen oder um weitere Operationen hinzuzufügen.

### Beispiele

Beispiel #1 mysql_xdevapi\CollectionRemove::sort()-Beispiel

    <?php

    $res = $coll->remove('true')->sort('age desc')->limit(2)->execute();

    ?>

## Inhaltsverzeichnis

- CollectionRemove::bind — Bindet einen Wert an einen Platzhalter
- CollectionRemove::__construct — Der Konstruktor der Klasse CollectionRemove
- CollectionRemove::execute — Führt eine Löschoperation aus
- CollectionRemove::limit — Begrenzt die Anzahl der zu löschenden Dokumente
- CollectionRemove::sort — Setzt die Kriterien für die Sortierung

# Die Klasse ColumnResult

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\ColumnResult {
/* Methoden */
public function getCharacterSetName(): string
public function getCollationName(): string
public function getColumnLabel(): string
public function getColumnName(): string
public function getFractionalDigits(): int
public function getLength(): int
public function getSchemaName(): string
public function getTableLabel(): string
public function getTableName(): string
public function getType(): int
public function isNumberSigned(): int
public function isPadded(): int
}

# ColumnResult::__construct

(No version information available, might only be in Git)

ColumnResult::__construct — Der Konstruktor der Klasse ColumnResult

### Beschreibung

private function mysql_xdevapi\ColumnResult::__construct()

Ruft die Metadaten von Spalten ab, z. B. den Zeichensatz, und wird durch die Methode mysql_xdevapi\RowResult::getColumns() instanziiert.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS nonsense")->execute();
    $session->sql("CREATE DATABASE nonsense")->execute();
    $session->sql("CREATE TABLE nonsense.numbers (hello int, world float unsigned)")->execute();
    $session->sql("INSERT INTO  nonsense.numbers values (42, 42)")->execute();

    $schema = $session->getSchema("nonsense");
    $table  = $schema->getTable("numbers");

    $result1 = $table->select('hello','world')->execute();

    // Gibt ein Array von ColumnResult-Objekten zurück
    $columns = $result1->getColumns();

    foreach ($columns as $column) {
        echo "\nDer Bezeichner der Spalte " , $column->getColumnLabel();
        echo " ist vom Typ "       , $column->getType();
        echo " und ist ", ($column->isNumberSigned() === 0) ? "vorzeichenlos." : "vorzeichenbehaftet.";
    }

    // Alternativ
    $result2 = $session->sql("SELECT * FROM nonsense.numbers")->execute();

    // Gibt ein Array von FieldMetadata-Objekten zurück
    print_r($result2->getColumns());

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Der Bezeichner der Spalte hallo ist vom Typ 19 und ist vorzeichenbehaftet.
    Die Bezeichner der Spalte world ist vom Typ 4 und ist vorzeichenlos.

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => hello
                [original_name] => hello
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 6
                [type_name] => FLOAT
                [name] => world
                [original_name] => world
                [table] => numbers
                [original_table] => numbers
                [schema] => nonsense
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 31
                [length] => 12
                [flags] => 1
                [content_type] => 0
            )
    )

# ColumnResult::getCharacterSetName

(No version information available, might only be in Git)

ColumnResult::getCharacterSetName — Ruft den Zeichensatz einer Spalte ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getCharacterSetName(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getCharacterSetName()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::getCollationName

(No version information available, might only be in Git)

ColumnResult::getCollationName — Ruft den Namen der Sortierreihenfolge einer Spalte ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getCollationName(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getCollationName()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnLabel

(No version information available, might only be in Git)

ColumnResult::getColumnLabel — Ruft den Bezeichner (Label) einer Spalte ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getColumnLabel(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getColumnLabel()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnName

(No version information available, might only be in Git)

ColumnResult::getColumnName — Ruft den Namen einer Spalte ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getColumnName(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getColumnName()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::getFractionalDigits

(No version information available, might only be in Git)

ColumnResult::getFractionalDigits — Ruft die Anzahl der Nachkommastellen einer Spalte ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getFractionalDigits(): int

Ermittelt die Anzahl der Nachkommastellen einer Spalte.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getFractionalDigits()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::getLength

(No version information available, might only be in Git)

ColumnResult::getLength — Ruft die Länge eines Spaltenfeldes ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getLength(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getLength()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::getSchemaName

(No version information available, might only be in Git)

ColumnResult::getSchemaName — Ruft den Namen des Schemas einer Spalte ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getSchemaName(): string

Ruft den Namen des Schemas ab, zu dem die betreffende Spalte gehört.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getSchemaName()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::getTableLabel

(No version information available, might only be in Git)

ColumnResult::getTableLabel — Ruft den Bezeichner (Label) der Tabelle einer Spalte ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getTableLabel(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getTableLabel()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::getTableName

(No version information available, might only be in Git)

ColumnResult::getTableName — Ruft den Namen der Tabelle einer Spalte ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getTableName(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Namen der Tabelle zurück, in der sich die Spalte befindet.

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getTableName()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::getType

(No version information available, might only be in Git)

ColumnResult::getType — Ruft den Typ einer Spalte ab

### Beschreibung

public function mysql_xdevapi\ColumnResult::getType(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::getType()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::isNumberSigned

(No version information available, might only be in Git)

ColumnResult::isNumberSigned — Prüft, ob der Typ einer Spalte vorzeichenbehaftet ist

### Beschreibung

public function mysql_xdevapi\ColumnResult::isNumberSigned(): int

Ruft die Spalteninformationen einer Tabelle ab; wird durch die Methode mysql_xdevapi\RowResult::getColumns() instanziiert.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn der Typ der angegebenen Spalte vorzeichenbehaftet ist.

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::isNumberSigned()-Beispiel

    <?php

    /* ... */

    ?>

# ColumnResult::isPadded

(No version information available, might only be in Git)

ColumnResult::isPadded — Prüft, ob eine Spalte aufgefüllt wird

### Beschreibung

public function mysql_xdevapi\ColumnResult::isPadded(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn die angegebene Spalte aufgefüllt wird.

### Beispiele

Beispiel #1 mysql_xdevapi\ColumnResult::isPadded()-Beispiel

    <?php

    /* ... */

    ?>

## Inhaltsverzeichnis

- ColumnResult::__construct — Der Konstruktor der Klasse ColumnResult
- ColumnResult::getCharacterSetName — Ruft den Zeichensatz einer Spalte ab
- ColumnResult::getCollationName — Ruft den Namen der Sortierreihenfolge einer Spalte ab
- ColumnResult::getColumnLabel — Ruft den Bezeichner (Label) einer Spalte ab
- ColumnResult::getColumnName — Ruft den Namen einer Spalte ab
- ColumnResult::getFractionalDigits — Ruft die Anzahl der Nachkommastellen einer Spalte ab
- ColumnResult::getLength — Ruft die Länge eines Spaltenfeldes ab
- ColumnResult::getSchemaName — Ruft den Namen des Schemas einer Spalte ab
- ColumnResult::getTableLabel — Ruft den Bezeichner (Label) der Tabelle einer Spalte ab
- ColumnResult::getTableName — Ruft den Namen der Tabelle einer Spalte ab
- ColumnResult::getType — Ruft den Typ einer Spalte ab
- ColumnResult::isNumberSigned — Prüft, ob der Typ einer Spalte vorzeichenbehaftet ist
- ColumnResult::isPadded — Prüft, ob eine Spalte aufgefüllt wird

# Die CrudOperationBindable-Schnittstelle

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\CrudOperationBindable {
/* Methoden */
abstract public function bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable
}

# CrudOperationBindable::bind

(No version information available, might only be in Git)

CrudOperationBindable::bind — Bindet einen Wert an einen Platzhalter

### Beschreibung

abstract public function mysql_xdevapi\CrudOperationBindable::bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable

Bindet einen Parameter an einen bestimmten Platzhalter.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`placeholder_values`

  Die Namen der Platzhalter und die zu bindenden Werte

### Rückgabewerte

Gibt ein CrudOperationBindable-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\CrudOperationBindable::bind()-Beispiel

    <?php

    $res = $coll->modify('name like :name')->arrayInsert('job[0]', 'Calciatore')->bind(['name' => 'ENTITY'])->execute();
    $res = $table->delete()->orderby('age desc')->where('age < 20 and age > 12 and name != :name')->bind(['name' => 'Tierney'])->limit(2)->execute();

    ?>

## Inhaltsverzeichnis

- CrudOperationBindable::bind — Bindet einen Wert an einen Platzhalter

# Die CrudOperationLimitable-Schnittstelle

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\CrudOperationLimitable {
/* Methoden */
abstract public function limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable
}

# CrudOperationLimitable::limit

(No version information available, might only be in Git)

CrudOperationLimitable::limit — Begrenzt die Anzahl der Ergebnisse

### Beschreibung

abstract public function mysql_xdevapi\CrudOperationLimitable::limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable

Legt die maximale Anzahl von Datensätzen oder Dokumenten fest, die zurückgegeben werden sollen.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`rows`

  Die maximale Anzahl der Datensätze oder Dokumente

### Rückgabewerte

Gibt ein CrudOperationLimitable-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\CrudOperationLimitable::limit()-Beispiel

    <?php

    $res = $coll->find()->fields(['name as n','age as a','job as j'])->groupBy('j')->limit(11)->execute();
    $res = $table->update()->set('age',69)->where('age > 15 and age < 22')->limit(4)->orderby(['age asc','name desc'])->execute();

    ?>

## Inhaltsverzeichnis

- CrudOperationLimitable::limit — Begrenzt die Anzahl der Ergebnisse

# Die CrudOperationSkippable-Schnittstelle

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\CrudOperationSkippable {
/* Methoden */
abstract public function skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable
}

# CrudOperationSkippable::skip

(No version information available, might only be in Git)

CrudOperationSkippable::skip — Überspringt die angegebene Anzahl von Datensätzen

### Beschreibung

abstract public function mysql_xdevapi\CrudOperationSkippable::skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable

Überspringt die angegebene Anzahl von Datensätzen in der zurückgegebenen Operation.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`skip`

  Die Anzahl der zu überspringenden Elemente

### Rückgabewerte

Gibt ein CrudOperationSkippable-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\CrudOperationSkippable::skip()-Beispiel

    <?php

    $res = $coll->find('job like \'Programmatore\'')->limit(1)->skip(3)->sort('age asc')->execute();

    ?>

## Inhaltsverzeichnis

- CrudOperationSkippable::skip — Überspringt die angegebene Anzahl von Datensätzen

# Die CrudOperationSortable-Schnittstelle

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\CrudOperationSortable {
/* Methoden */
abstract public function sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable
}

# CrudOperationSortable::sort

(No version information available, might only be in Git)

CrudOperationSortable::sort — Sortiert die Ergebnisse

### Beschreibung

abstract public function mysql_xdevapi\CrudOperationSortable::sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable

Sortiert die Ergebnismenge nach der im Argument sort_expr ausgewählten Spalte. Möglich sind die Reihenfolgen ASC (aufsteigend) und DESC (absteigend). Diese Operation entspricht der SQL-Operation 'ORDER BY' und folgt denselben Regeln.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`sort_expr`

  Es können ein oder mehrere durch Komma getrennte Sortierausdrücke angegeben werden. Die Auswertung erfolgt von links nach rechts.

### Rückgabewerte

Gibt ein CrudOperationSortable-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\CrudOperationSortable::sort()-Beispiel

    <?php

    $res = $coll->find('job like \'Cavia\'')->sort('age desc', '_id desc')->execute();

    ?>

## Inhaltsverzeichnis

- CrudOperationSortable::sort — Sortiert die Ergebnisse

# Die DatabaseObject-Schnittstelle

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\DatabaseObject {
/* Methoden */
abstract public function existsInDatabase(): bool
abstract public function getName(): string
abstract public function getSession(): mysql_xdevapi\Session
}

# DatabaseObject::existsInDatabase

(No version information available, might only be in Git)

DatabaseObject::existsInDatabase — Prüft, ob es das Objekt in der Datenbank gibt

### Beschreibung

abstract public function mysql_xdevapi\DatabaseObject::existsInDatabase(): bool

Überprüft, ob ein Datenbankobjekt auf ein Objekt verweist, das in der Datenbank existiert.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn das Objekt in der Datenbank existiert, und `false`, wenn es nicht existiert.

### Beispiele

Beispiel #1 mysql_xdevapi\DatabaseObject::existsInDatabase()-Beispiel

    <?php

    $existInDb = $dbObj->existsInDatabase();

    ?>

# DatabaseObject::getName

(No version information available, might only be in Git)

DatabaseObject::getName — Ruft den Namen eines Objekts ab

### Beschreibung

abstract public function mysql_xdevapi\DatabaseObject::getName(): string

Ruft den Namen eines Datenbankobjekts ab.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Namen des betreffenden Datenbankobjekts zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\DatabaseObject::getName()-Beispiel

    <?php

    $dbObjName = $dbObj->getName();

    ?>

# DatabaseObject::getSession

(No version information available, might only be in Git)

DatabaseObject::getSession — Ruft den Namen einer Session ab

### Beschreibung

abstract public function mysql_xdevapi\DatabaseObject::getSession(): mysql_xdevapi\Session

Ruft die mit dem Datenbankobjekt verknüpfte Session ab.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Session-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\DatabaseObject::getSession()-Beispiel

    <?php

    $session = $dbObj->getSession();

    ?>

## Inhaltsverzeichnis

- DatabaseObject::existsInDatabase — Prüft, ob es das Objekt in der Datenbank gibt
- DatabaseObject::getName — Ruft den Namen eines Objekts ab
- DatabaseObject::getSession — Ruft den Namen einer Session ab

# Die Klasse DocResult

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\DocResult implements mysql_xdevapi\BaseResult, Traversable {
/* Methoden */
public function fetchAll(): array
public function fetchOne(): array
public function getWarnings(): Array
public function getWarningsCount(): int
}

# DocResult::__construct

(No version information available, might only be in Git)

DocResult::__construct — Der Konstruktor der Klasse DocResult

### Beschreibung

private function mysql_xdevapi\DocResult::__construct()

Ruft Dokument-Ergebnisse und Warnungen ab und wird von CollectionFind instanziiert.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 DocResult-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gibt ein DocResult-Objekt zurück
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->limit(1)
      ->execute();

    var_dump($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b536100000000000000f3"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }
    }

# DocResult::fetchAll

(No version information available, might only be in Git)

DocResult::fetchAll — Ruft alle Zeilen aus einer Ergebnismenge ab

### Beschreibung

public function mysql_xdevapi\DocResult::fetchAll(): array

Ruft alle Ergebnisse aus einer Ergebnismenge ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein numerisches Array mit allen Ergebnissen einer Abfrage zurück, wobei jedes Ergebnis ein assoziatives Array ist. Wenn es kein Ergebnis gibt, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\DocResult::fetchAll()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gibt ein DocResult-Objekt zurück
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchAll());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(2) {

      [0]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000123"
        ["age"]=>
        int(42)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(8) "Reginald"
      }

      [1]=>
      array(4) {
        ["_id"]=>
        string(28) "00005b6b53610000000000000122"
        ["age"]=>
        int(18)
        ["job"]=>
        string(6) "Butler"
        ["name"]=>
        string(6) "Alfred"
      }

    }

# DocResult::fetchOne

(No version information available, might only be in Git)

DocResult::fetchOne — Ruft eine Zeile aus einer Ergebnismenge ab

### Beschreibung

public function mysql_xdevapi\DocResult::fetchOne(): array

Ruft ein Ergebnis aus einer Ergebnismenge ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das Ergebnis als assoziatives Array zurück oder `null`, wenn es kein Ergebnis gibt.

### Beispiele

Beispiel #1 mysql_xdevapi\DocResult::fetchOne()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gibt ein DocResult-Objekt zurück
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    var_dump($result->fetchOne());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000125"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

# DocResult::getWarnings

(No version information available, might only be in Git)

DocResult::getWarnings — Ruft die Warnungen der letzten Operation ab

### Beschreibung

public function mysql_xdevapi\DocResult::getWarnings(): Array

Ruft die Warnungen ab, die von der letzten Operation des MySQL-Servers erzeugt wurden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array von Warning-Objekten der letzten Operation zurück. Jedes Objekt enthält eine Fehlermeldung ("message"), eine Fehlerstufe ("level") und einen Fehlercode ("code"). Wenn kein Fehler aufgetreten ist, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\DocResult::getWarnings()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gibt ein DocResult-Objekt zurück
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "Es sind Fehler aufgetreten:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Es sind Fehler aufgetreten:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Something bad and so on
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Something bad and so on
                [level] => 2
                [code] => 1365
            )
    )

# DocResult::getWarningsCount

(No version information available, might only be in Git)

DocResult::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation

### Beschreibung

public function mysql_xdevapi\DocResult::getWarningsCount(): int

Gibt die Anzahl der Warnungen zurück, die durch die letzte Operation ausgelöst wurden. Es handelt sich hierbei speziell um die vom MySQL-Server ausgelösten Warnungen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Warnungen zurück, die bei der letzten Operation aufgetreten sind.

### Beispiele

Beispiel #1 mysql_xdevapi\DocResult::getWarningsCount()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $create->add('{"name": "Alfred", "age": 18, "job": "Butler"}')->execute();
    $create->add('{"name": "Reginald", "age": 42, "job": "Butler"}')->execute();

    // ...

    $collection = $schema->getCollection("people");

    // Gibt ein DocResult-Objekt zurück
    $result = $collection
      ->find('job like :job and age > :age')
      ->bind(['job' => 'Butler', 'age' => 16])
      ->sort('age desc')
      ->execute();

    if (!$result->getWarningsCount()) {
        echo "Es ist ein Fehler aufgetreten:\n";
        print_r($result->getWarnings());
        exit;
    }

    var_dump($result->fetchOne());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Es ist ein Fehler aufgetreten:

    array(4) {
      ["_id"]=>
      string(28) "00005b6b53610000000000000135"
      ["age"]=>
      int(42)
      ["job"]=>
      string(6) "Butler"
      ["name"]=>
      string(8) "Reginald"
    }

## Inhaltsverzeichnis

- DocResult::__construct — Der Konstruktor der Klasse DocResult
- DocResult::fetchAll — Ruft alle Zeilen aus einer Ergebnismenge ab
- DocResult::fetchOne — Ruft eine Zeile aus einer Ergebnismenge ab
- DocResult::getWarnings — Ruft die Warnungen der letzten Operation ab
- DocResult::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation

# Die Klasse Exception

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\Exception extends RuntimeException implements Throwable {
}

# Die Executable-Schnittstelle

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\Executable {
/* Methoden */
abstract public function execute(): mysql_xdevapi\Result
}

# Executable::execute

(No version information available, might only be in Git)

Executable::execute — Führt eine Anweisung aus

### Beschreibung

abstract public function mysql_xdevapi\Executable::execute(): mysql_xdevapi\Result

Führt eine Anweisung aus einer Sammlungs-Operation oder einer Tabellenabfrage aus. Diese Funktion bietet die Möglichkeit, Methoden zu verketten.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt eines der Result-Objekte zurück, z. B. ein Result- oder ein SqlStatementResult-Objekt.

### Beispiele

Beispiel #1 execute()-Beispiele

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $result_sql = $session->sql("CREATE DATABASE addressbook")->execute();

    var_dump($result_sql);

    $schema     = $session->getSchema("addressbook");
    $collection = $schema->createCollection("humans");

    $result_collection = $collection->add(
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}');

    $result_collection_executed = $result_collection->execute();

    var_dump($result_collection);
    var_dump($result_collection_executed);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(mysql_xdevapi\SqlStatementResult)#3 (0) {
    }

    object(mysql_xdevapi\CollectionAdd)#5 (0) {
    }

    object(mysql_xdevapi\Result)#7 (0) {
    }

## Inhaltsverzeichnis

- Executable::execute — Führt eine Anweisung aus

# Die Klasse ExecutionStatus

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\ExecutionStatus {
/* Eigenschaften */
public $affectedItems;
public $matchedItems;
public $foundItems;
public $lastInsertId;
public $lastDocumentId;
/* Konstruktor */
private function __construct()
}

## Eigenschaften

affectedItems

matchedItems

foundItems

lastInsertId

lastDocumentId

# ExecutionStatus::__construct

(No version information available, might only be in Git)

ExecutionStatus::__construct — Der Konstruktor der Klasse ExecutionStatus

### Beschreibung

private function mysql_xdevapi\ExecutionStatus::__construct()

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\ExecutionStatus::__construct()-Beispiel

    <?php

    /* ... */

    ?>

## Inhaltsverzeichnis

- ExecutionStatus::__construct — Der Konstruktor der Klasse ExecutionStatus

# Die Klasse Expression

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\Expression {
/* Eigenschaften */
public $name;
/* Konstruktor */
public function __construct(string `$expression`)
}

## Eigenschaften

name

# Expression::__construct

(No version information available, might only be in Git)

Expression::__construct — Der Konstruktor der Klasse Expression

### Beschreibung

public function mysql_xdevapi\Expression::__construct(string `$expression`)

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`expression`

### Beispiele

Beispiel #1 mysql_xdevapi\Expression::__construct()-Beispiel

    <?php

    /* ... */

    ?>

## Inhaltsverzeichnis

- Expression::__construct — Der Konstruktor der Klasse Expression

# Die Klasse Result

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\Result implements mysql_xdevapi\BaseResult, Traversable {
/* Methoden */
public function getAffectedItemsCount(): int
public function getAutoIncrementValue(): int
public function getGeneratedIds(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# Result::__construct

(No version information available, might only be in Git)

Result::__construct — Der Konstruktor der Klasse Result

### Beschreibung

private function mysql_xdevapi\Result::__construct()

Ein Objekt, das generierte IDs, AUTO_INCREMENT-Werte und Warnungen für eine Ergebnismenge abruft.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\Result::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(3)

# Result::getAffectedItemsCount

(No version information available, might only be in Git)

Result::getAffectedItemsCount — Ermittelt die Anzahl der betroffenen Zeilen

### Beschreibung

public function mysql_xdevapi\Result::getAffectedItemsCount(): int

Ermittelt die Anzahl der von der vorherigen Operation betroffenen Zeilen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der betroffenen Zeilen als Ganzzahl zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Result::getAffectedItemsCount()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    var_dump( $res->getAffectedItemsCount() );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)

# Result::getAutoIncrementValue

(No version information available, might only be in Git)

Result::getAutoIncrementValue — Ruft einen automatisch erhöhten Wert ab

### Beschreibung

public function mysql_xdevapi\Result::getAutoIncrementValue(): int

Ermittelt den letzten AUTO_INCREMENT-Wert (ID der letzten Einfügung).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den letzten AUTO_INCREMENT-Wert zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Result::getAutoIncrementValue()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("
      CREATE TABLE addressbook.names
        (id INT NOT NULL AUTO_INCREMENT, name VARCHAR(30), age INT, PRIMARY KEY (id))
      ")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->insert("name", "age")->values(["Suzanne", 31],["Julie", 43])->execute();
    $result = $table->insert("name", "age")->values(["Suki", 34])->execute();

    $ai = $result->getAutoIncrementValue();
    var_dump($ai);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(3)

# Result::getGeneratedIds

(No version information available, might only be in Git)

Result::getGeneratedIds — Ruft die zuletzt erzeugten IDs ab

### Beschreibung

public function mysql_xdevapi\Result::getGeneratedIds(): array

Ruft die bei der letzten Operation erzeugten _id-Werte ab. Das unique-Feld _id wird vom MySQL-Server erzeugt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array der _id-Werte zurück, die bei der letzten Operation erzeugt wurden, oder ein leeres Array, wenn es keine _id-Werte gibt.

### Beispiele

Beispiel #1 mysql_xdevapi\Result::getGeneratedIds()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema = $session->getSchema("addressbook");
    $create = $schema->createCollection("people");

    $collection = $schema->getCollection("people");

    $result = $collection->add(
      '{"name": "Bernie",
        "jobs": [{"title":"Cat Herder","Salary":42000}, {"title":"Father","Salary":0}],
        "hobbies": ["Sports","Making cupcakes"]}',
      '{"name": "Jane",
        "jobs": [{"title":"Scientist","Salary":18000}, {"title":"Mother","Salary":0}],
        "hobbies": ["Walking","Making pies"]}')->execute();

    $ids = $result->getGeneratedIds();
    var_dump($ids);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(2) {
      [0]=>
      string(28) "00005b6b53610000000000000064"
      [1]=>
      string(28) "00005b6b53610000000000000065"
    }

# Result::getWarnings

(No version information available, might only be in Git)

Result::getWarnings — Ruft die Warnungen der letzten Operation ab

### Beschreibung

public function mysql_xdevapi\Result::getWarnings(): array

Ruft die Warnungen der letzten Result-Operation ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array von Warning-Objekten der letzten Operation zurück. Jedes Objekt enthält eine Fehlermeldung ("message"), eine Fehlerstufe ("level") und einen Fehlercode ("code"). Wenn kein Fehler aufgetreten ist, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::getWarnings()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# Result::getWarningsCount

(No version information available, might only be in Git)

Result::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation

### Beschreibung

public function mysql_xdevapi\Result::getWarningsCount(): int

Ermittelt die Anzahl der Warnungen der letzten Result-Operation.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Warnungen zurück, die bei der letzten Operation aufgetreten sind.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::getWarningsCount()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2

## Inhaltsverzeichnis

- Result::__construct — Der Konstruktor der Klasse Result
- Result::getAffectedItemsCount — Ermittelt die Anzahl der betroffenen Zeilen
- Result::getAutoIncrementValue — Ruft einen automatisch erhöhten Wert ab
- Result::getGeneratedIds — Ruft die zuletzt erzeugten IDs ab
- Result::getWarnings — Ruft die Warnungen der letzten Operation ab
- Result::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation

# Die Klasse RowResult

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\RowResult implements mysql_xdevapi\BaseResult, Traversable {
/* Methoden */
public function fetchAll(): array
public function fetchOne(): array
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# RowResult::__construct

(No version information available, might only be in Git)

RowResult::__construct — Der Konstruktor der Klasse RowResult

### Beschreibung

private function mysql_xdevapi\RowResult::__construct()

Stellt die Ergebnismenge dar, die durch die Abfrage der Datenbank erhalten wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age > 18')->execute()->fetchAll();

    print_r($row);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchAll

(No version information available, might only be in Git)

RowResult::fetchAll — Ruft alle Zeilen aus einer Ergebnismenge ab

### Beschreibung

public function mysql_xdevapi\RowResult::fetchAll(): array

Ruft alle Zeilen aus einer Ergebnismenge ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein numerisches Array mit allen Ergebnissen einer Abfrage zurück, wobei jedes Ergebnis ein assoziatives Array ist. Wenn es kein Ergebnis gibt, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::fetchAll()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# RowResult::fetchOne

(No version information available, might only be in Git)

RowResult::fetchOne — Ruft eine Zeile aus einer Ergebnismenge ab

### Beschreibung

public function mysql_xdevapi\RowResult::fetchOne(): array

Ruft ein Ergebnis aus einer Ergebnismenge ab.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das Ergebnis als assoziatives Array zurück oder `null` wenn es kein Ergebnis gibt.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::fetchOne()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->where('age < 40')->execute()->fetchOne();

    print_r($row);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [name] => Sam
        [age] => 33
    )

# RowResult::getColumnsCount

(No version information available, might only be in Git)

RowResult::getColumnsCount — Ermittelt die Anzahl der Spalten einer Ergebnismenge

### Beschreibung

public function mysql_xdevapi\RowResult::getColumnsCount(): int

Ermittelt die Anzahl der in einer Ergebnismenge vorhandenen Spalten.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Spalten zurück; 0, wenn keine vorhanden sind.

### Changelog

Version | Beschreibung
--- | ---
8.0.14 | Die Methode wurde umbenannt von getColumnCount() in getColumnsCount().

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::getColumnsCount()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    echo $sql->getColumnsCount();

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2

# RowResult::getColumnNames

(No version information available, might only be in Git)

RowResult::getColumnNames — Ruft alle Spaltennamen aus einer Ergebnismenge ab

### Beschreibung

public function mysql_xdevapi\RowResult::getColumnNames(): array

Ruft die Spaltennamen der in einer Ergebnismenge vorhandenen Spalten ab.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein numerisches Array mit den Spaltennamen der Tabelle zurück oder ein leeres Array, wenn die Ergebnismenge leer ist.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::getColumnNames()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $colnames = $sql->getColumnNames();

    print_r($colnames);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => name
        [1] => age
    )

# RowResult::getColumns

(No version information available, might only be in Git)

RowResult::getColumns — Ruft die Metadaten der Spalten aus einer Ergebnismenge ab

### Beschreibung

public function mysql_xdevapi\RowResult::getColumns(): array

Ruft die Metadaten der Spalten ab, die in der Ergebnismenge vorhanden sind.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array von FieldMetadata-Objekten zurück, die die Spalten in der Ergebnismenge darstellen. Wenn die Ergebnismenge leer ist, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::getColumns()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE addressbook")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $sql = $session->sql("SELECT * from addressbook.names")->execute();

    $cols = $sql->getColumns();

    print_r($cols);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 7
                [type_name] => BYTES
                [name] => name
                [original_name] => name
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 255
                [fractional_digits] => 0
                [length] => 65535
                [flags] => 0
                [content_type] => 0
            )
        [1] => mysql_xdevapi\FieldMetadata Object
            (
                [type] => 1
                [type_name] => SINT
                [name] => age
                [original_name] => age
                [table] => names
                [original_table] => names
                [schema] => addressbook
                [catalog] => def
                [collation] => 0
                [fractional_digits] => 0
                [length] => 11
                [flags] => 0
                [content_type] => 0
            )
    )

# RowResult::getWarnings

(No version information available, might only be in Git)

RowResult::getWarnings — Ruft die Warnungen der letzten Operation ab

### Beschreibung

public function mysql_xdevapi\RowResult::getWarnings(): array

Ruft die Warnungen der letzten RowResult-Operation ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array von Warning-Objekten der letzten Operation zurück. Jedes Objekt enthält eine Fehlermeldung ("message"), eine Fehlerstufe ("level") und einen Fehlercode ("code"). Wenn kein Fehler aufgetreten ist, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::getWarnings()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();
    $warnings = $res->getWarnings();

    print_r($warnings);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
        [1] => mysql_xdevapi\Warning Object
            (
                [message] => Division by 0
                [level] => 2
                [code] => 1365
            )
    )

# RowResult::getWarningsCount

(No version information available, might only be in Git)

RowResult::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation

### Beschreibung

public function mysql_xdevapi\RowResult::getWarningsCount(): int

Ermittelt die Anzahl der Warnungen der letzten RowResult-Operation.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Warnungen zurück, die bei der letzten Operation aufgetreten sind.

### Beispiele

Beispiel #1 mysql_xdevapi\RowResult::getWarningsCount()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS foo")->execute();
    $session->sql("CREATE DATABASE foo")->execute();
    $session->sql("CREATE TABLE foo.test_table(x int)")->execute();

    $schema = $session->getSchema("foo");
    $table  = $schema->getTable("test_table");

    $table->insert(['x'])->values([1])->values([2])->execute();

    $res = $table->select(['x/0 as bad_x'])->execute();

    echo $res->getWarningsCount();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2

## Inhaltsverzeichnis

- RowResult::__construct — Der Konstruktor der Klasse RowResult
- RowResult::fetchAll — Ruft alle Zeilen aus einer Ergebnismenge ab
- RowResult::fetchOne — Ruft eine Zeile aus einer Ergebnismenge ab
- RowResult::getColumnsCount — Ermittelt die Anzahl der Spalten einer Ergebnismenge
- RowResult::getColumnNames — Ruft alle Spaltennamen aus einer Ergebnismenge ab
- RowResult::getColumns — Ruft die Metadaten der Spalten aus einer Ergebnismenge ab
- RowResult::getWarnings — Ruft die Warnungen der letzten Operation ab
- RowResult::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation

# Die Klasse Schema

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\Schema implements mysql_xdevapi\DatabaseObject {
/* Eigenschaften */
public $name;
/* Methoden */
public function createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection
public function dropCollection(string `$collection_name`): bool
public function existsInDatabase(): bool
public function getCollection(string `$name`): mysql_xdevapi\Collection
public function getCollectionAsTable(string `$name`): mysql_xdevapi\Table
public function getCollections(): array
public function getName(): string
public function getSession(): mysql_xdevapi\Session
public function getTable(string `$name`): mysql_xdevapi\Table
public function getTables(): array
}

## Eigenschaften

name

# Schema::__construct

(No version information available, might only be in Git)

Schema::__construct — Der Konstruktor der Klasse Schema

### Beschreibung

private function mysql_xdevapi\Schema::__construct()

Das Schema-Objekt bietet vollen Zugriff auf das Schema (Datenbank).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

# Schema::createCollection

(No version information available, might only be in Git)

Schema::createCollection — Fügt einem Schema eine Sammlung hinzu

### Beschreibung

public function mysql_xdevapi\Schema::createCollection(string `$name`, string `$validate` = ?): mysql_xdevapi\Collection

Erzeugt eine Sammlung innerhalb des Schemas.

### Parameter-Liste

`name`

  Der Name der Sammlung

`validate`

  Die Definition der Validierung in Form eines JSON-Objekts

### Rückgabewerte

Gibt ein Collection-Objekt zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.20 | Der optionale Parameter validate wurde hinzugefügt.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::createCollection()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [trees] => mysql_xdevapi\Collection Object
            (
                [name] => trees
            )
    )

Beispiel #2 Beispiel für die Verwendung von mysql_xdevapi\Schema::createCollection() mit Validierungsparameter

    <?php
     $collection = $schema->createCollection("mycollection", '{
        "validation": {
            "level": "strict",
            "schema": {
                "id": "http://json-schema.org/geo",
                "description": "A geographical coordinate",
                "type": "object",
                "properties": {
                    "latitude": {
                        "type": "number"
                    },
                    "longitude": {
                        "type": "number"
                    }
                },
                "required": ["latitude", "longitude"]
            }
        }
    }');
    // Wird erfolgreich ausgeführt
    $collection->add('{"latitude": 10, "longitude": 20}')->execute();

    // Schlägt fehl, ungültige Typen (keine Zahlen)
    $collection->add('{"latitude": "lat", "longitude": "long"}')->execute();

# Schema::dropCollection

(No version information available, might only be in Git)

Schema::dropCollection — Entfernt eine Sammlung aus einem Schema

### Beschreibung

public function mysql_xdevapi\Schema::dropCollection(string `$collection_name`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`collection_name`

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::dropCollection()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");

    $schema->createCollection("trees");
    $schema->dropCollection("trees");
    $schema->createCollection("buildings");

    print_r($schema->gettables());
    print_r($schema->getcollections());

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [fruit] => mysql_xdevapi\Table Object
            (
                [name] => fruit
            )
    )
    Array
    (
        [buildings] => mysql_xdevapi\Collection Object
            (
                [name] => buildings
            )
    )

# Schema::existsInDatabase

(No version information available, might only be in Git)

Schema::existsInDatabase — Prüft, ob es das angegebene Objekt in der Datenbank gibt

### Beschreibung

public function mysql_xdevapi\Schema::existsInDatabase(): bool

Prüft, ob das betreffende Objekt (Schema, Tabelle, Sammlung oder View) im Schema-Objekt vorhanden ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn das Schema, die Tabelle, die Sammlung oder der View noch im Schema vorhanden ist, andernfalls wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::existsInDatabase()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();
    $session->sql("CREATE TABLE food.fruit(name text, rating text)")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    // ...

    // Ist diese Sammlung noch in der Datenbank (Schema)?
    if ($trees->existsInDatabase()) {
        echo "Ja, die Sammlung 'trees' ist noch in der Datenbank.";
    }

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Ja, die Sammlung 'trees' ist noch in der Datenbank.

# Schema::getCollection

(No version information available, might only be in Git)

Schema::getCollection — Ruft eine Sammlung aus einem Schema ab

### Beschreibung

public function mysql_xdevapi\Schema::getCollection(string `$name`): mysql_xdevapi\Collection

Ruft eine Sammlung aus dem angegebenen Schema ab.

### Parameter-Liste

`name`

  Der Name der abzurufenden Sammlung

### Rückgabewerte

Gibt das Collection-Objekt für die ausgewählte Sammlung zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::getCollection()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS food")->execute();
    $session->sql("CREATE DATABASE food")->execute();

    $schema = $session->getSchema("food");
    $schema->createCollection("trees");

    // ...

    $trees = $schema->getCollection("trees");

    var_dump($trees);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(mysql_xdevapi\Collection)#3 (1) {
      ["name"]=>
      string(5) "trees"
    }

# Schema::getCollectionAsTable

(No version information available, might only be in Git)

Schema::getCollectionAsTable — Ruft eine Sammlung als Table-Objekt ab

### Beschreibung

public function mysql_xdevapi\Schema::getCollectionAsTable(string `$name`): mysql_xdevapi\Table

Ruft eine Sammlung als Table-Objekt statt als Collection-Objekt ab.

### Parameter-Liste

`name`

  Der Name der Sammlung, aus der ein Table-Objekt instanziiert werden soll.

### Rückgabewerte

Gibt ein mysql_xdevapi\Table-Objekt für die Sammlung zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::getCollectionAsTable()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $table      = $schema->getCollectionAsTable("people");
    $collection = $schema->getCollection("people");

    var_dump($table);
    var_dump($collection);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(mysql_xdevapi\Table)#4 (1) {
      ["name"]=>
      string(6) "people"
    }

    object(mysql_xdevapi\Collection)#5 (1) {
      ["name"]=>
      string(6) "people"
    }

# Schema::getCollections

(No version information available, might only be in Git)

Schema::getCollections — Ruft alle Sammlungen eines Schemas ab

### Beschreibung

public function mysql_xdevapi\Schema::getCollections(): array

Ruft eine Liste der Sammlungen des Schemas ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array mit allen Sammlungen des Schemas zurück, wobei jedes Element des Arrays aus dem Namen der Sammlung als Schlüssel und einem Collection-Objekt als Wert besteht.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::getCollections()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");
    $collect = $schema->createCollection("people");
    $collect->add('{"name": "Fred",  "age": 21, "job": "Construction"}')->execute();
    $collect->add('{"name": "Wilma", "age": 23, "job": "Teacher"}')->execute();

    $collections = $schema->getCollections();
    var_dump($collections);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      ["people"]=>
      object(mysql_xdevapi\Collection)#4 (1) {
        ["name"]=>
        string(6) "people"
      }
    }

# Schema::getName

(No version information available, might only be in Git)

Schema::getName — Ruft den Namen eines Schemas ab

### Beschreibung

public function mysql_xdevapi\Schema::getName(): string

Ruft den Namen des Schemas ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Namen des mit dem Schema-Objekt verknüpften Schemas als Zeichenkette zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::getName()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    var_dump($schema->getName());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(11) "addressbook"

# Schema::getSession

(No version information available, might only be in Git)

Schema::getSession — Ruft eine Schema-Session ab

### Beschreibung

public function mysql_xdevapi\Schema::getSession(): mysql_xdevapi\Session

Ruft ein neues Session-Objekt aus dem Schema-Objekt ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Session-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::getSession()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $schema  = $session->getSchema("addressbook");

    // ...

    $newsession = $schema->getSession();

    var_dump($session);
    var_dump($newsession);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(mysql_xdevapi\Session)#1 (0) {
    }

    object(mysql_xdevapi\Session)#3 (0) {
    }

# Schema::getTable

(No version information available, might only be in Git)

Schema::getTable — Ruft eine Tabelle eines Schemas ab

### Beschreibung

public function mysql_xdevapi\Schema::getTable(string `$name`): mysql_xdevapi\Table

Ruft ein Table-Objekt für die angegebene Tabelle aus dem Schema ab.

### Parameter-Liste

`name`

  Der Name der Tabelle

### Rückgabewerte

Gibt ein Table-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::getTable()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Schema::getTables

(No version information available, might only be in Git)

Schema::getTables — Ruft alle Tabellen eines Schemas ab

### Beschreibung

public function mysql_xdevapi\Schema::getTables(): array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array mit allen Tabellen des Schemas zurück, wobei jedes Element des Arrays aus dem Namen der Tabelle als Schlüssel und einem Table-Objekt als Wert besteht.

### Beispiele

Beispiel #1 mysql_xdevapi\Schema::getTables()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();

    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $session->sql("CREATE TABLE addressbook.cities(name text, population int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Portland', 639863), ('Seattle', 704352)")->execute();

    $schema = $session->getSchema("addressbook");
    $tables = $schema->getTables();

    var_dump($tables);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(2) {
      ["cities"]=>
      object(mysql_xdevapi\Table)#3 (1) {
        ["name"]=>
        string(6) "cities"
      }

      ["names"]=>
      object(mysql_xdevapi\Table)#4 (1) {
        ["name"]=>
        string(5) "names"
      }
    }

## Inhaltsverzeichnis

- Schema::__construct — Der Konstruktor der Klasse Schema
- Schema::createCollection — Fügt einem Schema eine Sammlung hinzu
- Schema::dropCollection — Entfernt eine Sammlung aus einem Schema
- Schema::existsInDatabase — Prüft, ob es das angegebene Objekt in der Datenbank gibt
- Schema::getCollection — Ruft eine Sammlung aus einem Schema ab
- Schema::getCollectionAsTable — Ruft eine Sammlung als Table-Objekt ab
- Schema::getCollections — Ruft alle Sammlungen eines Schemas ab
- Schema::getName — Ruft den Namen eines Schemas ab
- Schema::getSession — Ruft eine Schema-Session ab
- Schema::getTable — Ruft eine Tabelle eines Schemas ab
- Schema::getTables — Ruft alle Tabellen eines Schemas ab

# Die SchemaObject-Schnittstelle

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\SchemaObject implements mysql_xdevapi\DatabaseObject {
/* Methoden */
abstract function getSchema(): mysql_xdevapi\Schema
}

# SchemaObject::getSchema

(No version information available, might only be in Git)

SchemaObject::getSchema — Ruft ein Schema-Objekt ab

### Beschreibung

abstract function mysql_xdevapi\SchemaObject::getSchema(): mysql_xdevapi\Schema

Wird von anderen Objekten verwendet, um ein Schema-Objekt abzurufen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das aktuelle Schema-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::getSchema()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

## Inhaltsverzeichnis

- SchemaObject::getSchema — Ruft ein Schema-Objekt ab

# Die Klasse Session

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\Session {
/* Methoden */
public function close(): bool
public function commit(): Object
public function createSchema(string `$schema_name`): mysql_xdevapi\Schema
public function dropSchema(string `$schema_name`): bool
public function generateUUID(): string
public function getDefaultSchema(): ?mysql_xdevapi\Schema
public function getSchema(string `$schema_name`): mysql_xdevapi\Schema
public function getSchemas(): array
public function getServerVersion(): int
public function listClients(): array
public function quoteName(string `$name`): string
public function releaseSavepoint(string `$name`): void
public function rollback(): void
public function rollbackTo(string `$name`): void
public function setSavepoint(string `$name` = ?): string
public function sql(string `$query`): mysql_xdevapi\SqlStatement
public function startTransaction(): void
}

# Session::close

(No version information available, might only be in Git)

Session::close — Schließt eine Session

### Beschreibung

public function mysql_xdevapi\Session::close(): bool

Schließt die Session mit dem Server.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn die Session geschlossen wurde.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::close()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->close();

# Session::commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

Session::commit — Bestätigt eine Transaktion

### Beschreibung

public function mysql_xdevapi\Session::commit(): Object

Bestätigt die Transaktion.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein SqlStatementResult-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::commit()-Beispiel

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();

    $collection->add('{"John":42, "Sam":33}')->execute();
    $savepoint = $session->setSavepoint();

    $session->commit();
    $session->close();

# Session::__construct

(No version information available, might only be in Git)

Session::__construct — Der Konstruktor der Klasse Session

### Beschreibung

private function mysql_xdevapi\Session::__construct()

Ein Session-Objekt; wird von getSession() instanziiert.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->close();
    ?>

# Session::createSchema

(No version information available, might only be in Git)

Session::createSchema — Erstellt ein neues Schema

### Beschreibung

public function mysql_xdevapi\Session::createSchema(string `$schema_name`): mysql_xdevapi\Schema

Erstellt ein neues Schema.

### Parameter-Liste

`schema_name`

  Der Name des zu erstellenden Schemas

### Rückgabewerte

Gibt bei Erfolg ein Schema-Objekt zurück und löst bei einem Fehler eine Exception aus.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::createSchema()-Beispiel

    <?php
    $uri  = 'mysqlx://happyuser:password@127.0.0.1:33060/';
    $sess = mysql_xdevapi\getSession($uri);

    try {

        if ($schema = $sess->createSchema('fruit')) {
            echo "Info: Ich habe ein Schema mit dem Namen 'fruit' erstellt\n";
        }

    } catch (Exception $e) {

       echo $e->getMessage();

    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Info: Ich habe ein Schema mit dem Namen 'fruit' erstellt

# Session::dropSchema

(No version information available, might only be in Git)

Session::dropSchema — Löscht ein Schema

### Beschreibung

public function mysql_xdevapi\Session::dropSchema(string `$schema_name`): bool

Löscht ein Schema (Datenbank).

### Parameter-Liste

`schema_name`

  Der Name des zu löschenden Schemas

### Rückgabewerte

Gibt `true` zurück, wenn das Schema gelöscht wurde, oder `false`, wenn es nicht existiert oder nicht gelöscht werden kann.

Wenn das Schema nicht existiert, wird ein Fehler der Stufe `E_WARNING` erzeugt.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::dropSchema()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->dropSchema("addressbook");

    $session->close();
    ?>

# Session::generateUUID

(No version information available, might only be in Git)

Session::generateUUID — Erzeugt eine neue UUID

### Beschreibung

public function mysql_xdevapi\Session::generateUUID(): string

Erzeugt einen Universal Unique IDentifier (UUID) gemäß » RFC 4122.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt eine UUID zurück; eine Zeichenkette mit 32 Zeichen.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::generateUuid()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $uuid = $session->generateUuid();

    var_dump($uuid);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(32) "484B18AC7980F8D4FE84613CDA5EE84B"

# Session::getDefaultSchema

(No version information available, might only be in Git)

Session::getDefaultSchema — Ruft den Namen des Standardschemas ab

### Beschreibung

public function mysql_xdevapi\Session::getDefaultSchema(): ?mysql_xdevapi\Schema

Ruft das Standardschema ab, das normalerweise im Verbindungs-URI definiert wird.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das über die Verbindung definierte Standardschema zurück, oder `null`, wenn keines definiert wurde.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::getSchema()-Beispiel

    <?php
    $uri = "mysqlx://testuser:testpasswd@localhost:33160/testx?ssl-mode=disabled";
    $session = mysql_xdevapi\getSession($uri);

    $schema = $session->getDefaultSchema();
    echo $schema->getName();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    testx

# Session::getSchema

(No version information available, might only be in Git)

Session::getSchema — Ruft ein neues Schema-Objekt ab

### Beschreibung

public function mysql_xdevapi\Session::getSchema(string `$schema_name`): mysql_xdevapi\Schema

Ruft ein neues Schema-Objekt für das angegebene Schema ab.

### Parameter-Liste

`schema_name`

  Der Name des Schemas (Datenbank), für das ein Schema-Objekt abgerufen werden soll.

### Rückgabewerte

Gibt ein Schema-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::getSchema()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schema  = $session->getSchema("addressbook");

    print_r($schema);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    mysql_xdevapi\Schema Object
    (
        [name] => addressbook
    )

# Session::getSchemas

(No version information available, might only be in Git)

Session::getSchemas — Ruft Schema-Objekte ab

### Beschreibung

public function mysql_xdevapi\Session::getSchemas(): array

Ruft Schema-Objekte für alle Schemata ab, die für die Session verfügbar sind.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array mit Objekten zurück, die alle für die Session verfügbaren Schemata darstellen.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::getSchemas()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $schemas  = $session->getSchemas();

    print_r($schemas);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => mysql_xdevapi\Schema Object
            (
                [name] => addressbook
            )
        [1] => mysql_xdevapi\Schema Object
            (
                [name] => information_schema
            )
        ...

# Session::getServerVersion

(No version information available, might only be in Git)

Session::getServerVersion — Ruft die Serverversion ab

### Beschreibung

public function mysql_xdevapi\Session::getServerVersion(): int

Ermittelt die Version des MySQL-Servers, der für die Session verwendet wird.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Version des für die Session verwendeten MySQL-Servers in Form einer ganzen Zahl zurück, z. B. "80012".

### Beispiele

Beispiel #1 mysql_xdevapi\Session::getServerVersion()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $version = $session->getServerVersion();

    var_dump($version);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(80012)

# Session::listClients

(No version information available, might only be in Git)

Session::listClients — Ruft eine Liste der Clients ab

### Beschreibung

public function mysql_xdevapi\Session::listClients(): array

Ruft eine Liste der Clients ab, die mit dem MySQL-Server der Session verbunden sind.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array mit den aktuell angemeldeten Clients zurück. Die Array-Elemente sind "client_id", "user", "host", und "sql_session".

### Beispiele

Beispiel #1 mysql_xdevapi\Session::listClients()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $ids = $session->listClients();

    var_dump($ids);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(1) {
      [0]=>
      array(4) {
        ["client_id"]=>
        int(61)
        ["user"]=>
        string(4) "root"
        ["host"]=>
        string(9) "localhost"
        ["sql_session"]=>
        int(72)
      }
    }

# Session::quoteName

(No version information available, might only be in Git)

Session::quoteName — Fügt Anführungszeichen hinzu

### Beschreibung

public function mysql_xdevapi\Session::quoteName(string `$name`): string

Mit dieser Funktion können SQL-Namen und Bezeichner maskiert werden. Sie maskiert den angegebenen Bezeichner gemäß den Einstellungen der aktuellen Verbindung. Diese Funktion sollte nicht verwendet werden, um Werte zu maskieren.

### Parameter-Liste

`name`

  Die Zeichenkette, die in Anführungszeichen gesetzt werden soll

### Rückgabewerte

Gibt die in Anführungszeichen gesetzte Zeichenkette zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::quoteName()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $first = "MySQL's test";
    var_dump($first);
    var_dump($session->quoteName($first));

    $second = 'Another `test` "like" `this`';
    var_dump($second);
    var_dump($session->quoteName($second));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(12) "MySQL's test"
    string(14) "`MySQL's test`"

    string(28) "Another `test` "like" `this`"
    string(34) "`Another ``test`` "like" ``this```"

# Session::releaseSavepoint

(No version information available, might only be in Git)

Session::releaseSavepoint — Entfernt einen gesetzten Sicherungspunkt

### Beschreibung

public function mysql_xdevapi\Session::releaseSavepoint(string `$name`): void

Entfernt einen zuvor gesetzten Sicherungspunkt.

### Parameter-Liste

`name`

  Der Name des zu entfernenden Sicherungspunkts

### Rückgabewerte

Gibt ein SqlStatementResult-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::releaseSavepoint()-Beispiel

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollback

(No version information available, might only be in Git)

Session::rollback — Macht eine Transaktion rückgängig (Rollback)

### Beschreibung

public function mysql_xdevapi\Session::rollback(): void

Macht eine Transaktion rückgängig.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein SqlStatementResult-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::rollback()-Beispiel

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::rollbackTo

(No version information available, might only be in Git)

Session::rollbackTo — Macht eine Transaktion bis zu einem Sicherungspunkt rückgängig

### Beschreibung

public function mysql_xdevapi\Session::rollbackTo(string `$name`): void

Macht eine Transaktion bis zum Sicherungspunkt rückgängig.

### Parameter-Liste

`name`

  zu eine Der Name des Sicherungspunktes, bis zu dem zurückgesprungen werden soll; die Groß- und Kleinschreibung wird nicht berücksichtigt.

### Rückgabewerte

Gibt ein SqlStatementResult-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::rollbackTo()-Beispiel

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint1 = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $savepoint2 = $session->setSavepoint();

    $session->rollbackTo($savepoint1);
    ?>

# Session::setSavepoint

(No version information available, might only be in Git)

Session::setSavepoint — Erzeugt einen Sicherungspunkt

### Beschreibung

public function mysql_xdevapi\Session::setSavepoint(string `$name` = ?): string

Erzeugt einen neuen Sicherungspunkt für die Transaktion.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`name`

  Der Name des Sicherungspunkts. Wenn der optionale Parameter `name` nicht als 'SICHERUNGSPUNKT1', 'SICHERUNGSPUNKT2' usw. definiert ist, wird der Name automatisch generiert.

### Rückgabewerte

Gibt den Namen des Sicherungspunkts zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::setSavepoint()-Beispiel

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("names");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

# Session::sql

(No version information available, might only be in Git)

Session::sql — Erzeugt eine SQL-Anweisung

### Beschreibung

public function mysql_xdevapi\Session::sql(string `$query`): mysql_xdevapi\SqlStatement

Erzeugt eine native SQL-Anweisung. Platzhalter werden mit der nativen "?"-Syntax unterstützt. Mit der Methode `execute` kann die SQL-Anweisung ausgeführt werden.

### Parameter-Liste

`query`

  Die auszuführende SQL-Anweisung

### Rückgabewerte

Gibt ein SqlStatement-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::sql()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("CREATE DATABASE addressbook")->execute();
    ?>

# Session::startTransaction

(No version information available, might only be in Git)

Session::startTransaction — Startet eine Transaktion

### Beschreibung

public function mysql_xdevapi\Session::startTransaction(): void

Startet eine neue Transaktion.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein SqlStatementResult-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Session::startTransaction()-Beispiel

    <?php
    $session    = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $collection = $session->getSchema("addressbook")->getCollection("friends");

    $session->startTransaction();
    $collection->add( '{"test1":1, "test2":2}' )->execute();

    $savepoint = $session->setSavepoint();

    $collection->add( '{"test3":3, "test4":4}' )->execute();

    $session->releaseSavepoint($savepoint);
    $session->rollback();
    ?>

## Inhaltsverzeichnis

- Session::close — Schließt eine Session
- Session::commit — Bestätigt eine Transaktion
- Session::__construct — Der Konstruktor der Klasse Session
- Session::createSchema — Erstellt ein neues Schema
- Session::dropSchema — Löscht ein Schema
- Session::generateUUID — Erzeugt eine neue UUID
- Session::getDefaultSchema — Ruft den Namen des Standardschemas ab
- Session::getSchema — Ruft ein neues Schema-Objekt ab
- Session::getSchemas — Ruft Schema-Objekte ab
- Session::getServerVersion — Ruft die Serverversion ab
- Session::listClients — Ruft eine Liste der Clients ab
- Session::quoteName — Fügt Anführungszeichen hinzu
- Session::releaseSavepoint — Entfernt einen gesetzten Sicherungspunkt
- Session::rollback — Macht eine Transaktion rückgängig (Rollback)
- Session::rollbackTo — Macht eine Transaktion bis zu einem Sicherungspunkt rückgängig
- Session::setSavepoint — Erzeugt einen Sicherungspunkt
- Session::sql — Erzeugt eine SQL-Anweisung
- Session::startTransaction — Startet eine Transaktion

# Die Klasse SqlStatement

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\SqlStatement {
/* Konstanten */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Eigenschaften */
public $statement;
/* Methoden */
public function bind(string `$param`): mysql_xdevapi\SqlStatement
public function execute(): mysql_xdevapi\Result
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Eigenschaften

statement

## Vordefinierte Konstanten

`mysql_xdevapi\SqlStatement::EXECUTE_ASYNC`

`mysql_xdevapi\SqlStatement::BUFFERED`

# SqlStatement::bind

(No version information available, might only be in Git)

SqlStatement::bind — Bindet die Parameter einer Anweisung

### Beschreibung

public function mysql_xdevapi\SqlStatement::bind(string `$param`): mysql_xdevapi\SqlStatement

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`param`

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatement::bind()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatement::__construct

(No version information available, might only be in Git)

SqlStatement::__construct — Der Konstruktor der Klasse SqlStatement

### Beschreibung

private function mysql_xdevapi\SqlStatement::__construct()

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatement::__construct()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatement::execute

(No version information available, might only be in Git)

SqlStatement::execute — Führt eine Operation aus

### Beschreibung

public function mysql_xdevapi\SqlStatement::execute(): mysql_xdevapi\Result

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatement::execute()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatement::getNextResult

(No version information available, might only be in Git)

SqlStatement::getNextResult — Ruft das nächste Ergebnis ab

### Beschreibung

public function mysql_xdevapi\SqlStatement::getNextResult(): mysql_xdevapi\Result

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatement::getNextResult()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatement::getResult

(No version information available, might only be in Git)

SqlStatement::getResult — Ruft ein Ergebnis ab

### Beschreibung

public function mysql_xdevapi\SqlStatement::getResult(): mysql_xdevapi\Result

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatement::getResult()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatement::hasMoreResults

(No version information available, might only be in Git)

SqlStatement::hasMoreResults — Prüft, ob es weitere Ergebnisse gibt

### Beschreibung

public function mysql_xdevapi\SqlStatement::hasMoreResults(): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn die Ergebnismenge weitere Objekte enthält, die abgerufen werden können.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatement::hasMoreResults()-Beispiel

    <?php

    /* ... */

    ?>

## Inhaltsverzeichnis

- SqlStatement::bind — Bindet die Parameter einer Anweisung
- SqlStatement::__construct — Der Konstruktor der Klasse SqlStatement
- SqlStatement::execute — Führt eine Operation aus
- SqlStatement::getNextResult — Ruft das nächste Ergebnis ab
- SqlStatement::getResult — Ruft ein Ergebnis ab
- SqlStatement::hasMoreResults — Prüft, ob es weitere Ergebnisse gibt

# Die Klasse SqlStatementResult

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\SqlStatementResult implements mysql_xdevapi\BaseResult, Traversable {
/* Methoden */
public function fetchAll(): array
public function fetchOne(): array
public function getAffectedItemsCount(): int
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): Array
public function getGeneratedIds(): array
public function getLastInsertId(): String
public function getWarnings(): array
public function getWarningCounts(): int
public function hasData(): bool
public function nextResult(): mysql_xdevapi\Result
}

# SqlStatementResult::__construct

(No version information available, might only be in Git)

SqlStatementResult::__construct — Der Konstruktor der Klasse SqlStatementResult

### Beschreibung

private function mysql_xdevapi\SqlStatementResult::__construct()

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::__construct()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::fetchAll

(No version information available, might only be in Git)

SqlStatementResult::fetchAll — Ruft alle Zeilen aus dem Ergebnis ab

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::fetchAll(): array

Ruft alle Zeilen aus der Ergebnismenge ab.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein numerisches Array mit allen Ergebnissen der Abfrage zurück; jedes Ergebnis ist ein assoziatives Array. Wenn keine Zeilen vorliegen, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::fetchAll()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchAll();

    print_r($rows);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# SqlStatementResult::fetchOne

(No version information available, might only be in Git)

SqlStatementResult::fetchOne — Ruft eine Zeile aus dem Ergebnis ab

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::fetchOne(): array

Ruft eine Zeile aus der Ergebnismenge ab.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das Ergebnis als assoziatives Arrays zurück. Falls es kein Ergebnis gibt, wird `null` zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::fetchOne()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->sql("DROP DATABASE IF EXISTS dbtest")->execute();
    $session->sql("CREATE DATABASE dbtest")->execute();
    $session->sql("CREATE TABLE dbtest.workers(name text, age int, job text)")->execute();
    $session->sql("INSERT INTO dbtest.workers values ('John', 42, 'bricklayer'), ('Sam', 33, 'carpenter')")->execute();

    $schema = $session->getSchema("dbtest");
    $table  = $schema->getTable("workers");

    $rows = $session->sql("SELECT * FROM dbtest.workers")->execute()->fetchOne();

    print_r($rows);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [name] => John
        [age] => 42
        [job] => bricklayer
    )

# SqlStatementResult::getAffectedItemsCount

(No version information available, might only be in Git)

SqlStatementResult::getAffectedItemsCount — Ermittelt die Anzahl der betroffenen Zeilen

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::getAffectedItemsCount(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::getAffectedItemsCount()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnsCount

(No version information available, might only be in Git)

SqlStatementResult::getColumnsCount — Ermittelt die Anzahl der Spalten

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::getColumnsCount(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Spalten zurück; 0, wenn es keine gibt.

### Changelog

Version | Beschreibung
--- | ---
8.0.14 | Die Methode wurde umbenannt von getColumnCount() in getColumnsCount().

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::getColumnsCount()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnNames

(No version information available, might only be in Git)

SqlStatementResult::getColumnNames — Ruft die Namen der Spalten ab

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::getColumnNames(): array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::getColumnNames()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumns

(No version information available, might only be in Git)

SqlStatementResult::getColumns — Ruft Spalten ab

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::getColumns(): Array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::getColumns()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::getGeneratedIds

(No version information available, might only be in Git)

SqlStatementResult::getGeneratedIds — Ruft die zuletzt erzeugten IDs ab

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::getGeneratedIds(): array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array der _id-Werte zurück, die bei der letzten Operation erzeugt wurden, oder ein leeres Array, wenn es keine _id-Werte gibt.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::getGeneratedIds()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::getLastInsertId

(No version information available, might only be in Git)

SqlStatementResult::getLastInsertId — Ruft die ID der letzten Einfügung ab

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::getLastInsertId(): String

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die ID für die letzte Einfügeoperation zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::getLastInsertId()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarnings

(No version information available, might only be in Git)

SqlStatementResult::getWarnings — Ruft die Warnungen der letzten Operation ab

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::getWarnings(): array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array von Warning-Objekten der letzten Operation zurück. Jedes Objekt enthält eine Fehlermeldung ("message"), eine Fehlerstufe ("level") und einen Fehlercode ("code"). Wenn kein Fehler aufgetreten ist, wird ein leeres Array zurückgegeben.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::getWarnings()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarningsCount

(No version information available, might only be in Git)

SqlStatementResult::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::getWarningCounts(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Warnungen zurück, die bei der letzten CRUD-Operation ausgelöst wurden.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::getWarningsCount()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::hasData

(No version information available, might only be in Git)

SqlStatementResult::hasData — Prüft, ob die Ergebnismenge Daten enthält

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::hasData(): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn die Ergebnismenge Daten enthält.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::hasData()-Beispiel

    <?php

    /* ... */

    ?>

# SqlStatementResult::nextResult

(No version information available, might only be in Git)

SqlStatementResult::nextResult — Ruft das nächste Ergebnis ab

### Beschreibung

public function mysql_xdevapi\SqlStatementResult::nextResult(): mysql_xdevapi\Result

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt das nächste Result-Objekt aus der Ergebnismenge zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\SqlStatementResult::nextResult()-Beispiel

    <?php

    /* ... */

    ?>

## Inhaltsverzeichnis

- SqlStatementResult::__construct — Der Konstruktor der Klasse SqlStatementResult
- SqlStatementResult::fetchAll — Ruft alle Zeilen aus dem Ergebnis ab
- SqlStatementResult::fetchOne — Ruft eine Zeile aus dem Ergebnis ab
- SqlStatementResult::getAffectedItemsCount — Ermittelt die Anzahl der betroffenen Zeilen
- SqlStatementResult::getColumnsCount — Ermittelt die Anzahl der Spalten
- SqlStatementResult::getColumnNames — Ruft die Namen der Spalten ab
- SqlStatementResult::getColumns — Ruft Spalten ab
- SqlStatementResult::getGeneratedIds — Ruft die zuletzt erzeugten IDs ab
- SqlStatementResult::getLastInsertId — Ruft die ID der letzten Einfügung ab
- SqlStatementResult::getWarnings — Ruft die Warnungen der letzten Operation ab
- SqlStatementResult::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation
- SqlStatementResult::hasData — Prüft, ob die Ergebnismenge Daten enthält
- SqlStatementResult::nextResult — Ruft das nächste Ergebnis ab

# Die Klasse Statement

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\Statement {
/* Konstanten */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* Methoden */
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## Vordefinierte Konstanten

`mysql_xdevapi\Statement::EXECUTE_ASYNC`

`mysql_xdevapi\Statement::BUFFERED`

# Statement::__construct

(No version information available, might only be in Git)

Statement::__construct — Der Konstruktor der Klasse Statement

### Beschreibung

private function mysql_xdevapi\Statement::__construct()

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\Statement::__construct()-Beispiel

    <?php

    /* ... */

    ?>

# Statement::getNextResult

(No version information available, might only be in Git)

Statement::getNextResult — Ruft das nächste Ergebnis ab

### Beschreibung

public function mysql_xdevapi\Statement::getNextResult(): mysql_xdevapi\Result

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\Statement::getNextResult()-Beispiel

    <?php

    /* ... */

    ?>

# Statement::getResult

(No version information available, might only be in Git)

Statement::getResult — Ruft ein Ergebnis ab

### Beschreibung

public function mysql_xdevapi\Statement::getResult(): mysql_xdevapi\Result

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\Statement::getResult()-Beispiel

    <?php

    /* ... */

    ?>

# Statement::hasMoreResults

(No version information available, might only be in Git)

Statement::hasMoreResults — Prüft, ob es weitere Ergebnisse gibt

### Beschreibung

public function mysql_xdevapi\Statement::hasMoreResults(): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 mysql_xdevapi\Statement::hasMoreResults()-Beispiel

    <?php

    /* ... */

    ?>

## Inhaltsverzeichnis

- Statement::__construct — Der Konstruktor der Klasse Statement
- Statement::getNextResult — Ruft das nächste Ergebnis ab
- Statement::getResult — Ruft ein Ergebnis ab
- Statement::hasMoreResults — Prüft, ob es weitere Ergebnisse gibt

# Die Klasse Table

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

Ermöglicht den Zugriff auf eine Tabelle durch INSERT/SELECT/UPDATE/DELETE-Anweisungen.

## Klassenbeschreibung

class mysql_xdevapi\Table implements mysql_xdevapi\SchemaObject {
/* Eigenschaften */
public $name;
/* Methoden */
public function count(): int
public function delete(): mysql_xdevapi\TableDelete
public function existsInDatabase(): bool
public function getName(): string
public function getSchema(): mysql_xdevapi\Schema
public function getSession(): mysql_xdevapi\Session
public function insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert
public function isView(): bool
public function select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect
public function update(): mysql_xdevapi\TableUpdate
}

## Eigenschaften

name

# Table::__construct

(No version information available, might only be in Git)

Table::__construct — Der Konstruktor der Klasse Table

### Beschreibung

private function mysql_xdevapi\Table::__construct()

Erstellt ein Table-Objekt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");
    ?>

# Table::count

(No version information available, might only be in Git)

Table::count — Ermittelt die Anzahl der Zeilen

### Beschreibung

public function mysql_xdevapi\Table::count(): int

Ermittelt die Anzahl der Zeilen in einer Tabelle.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Zeilen einer Tabelle zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::count()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->count());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(2)

# Table::delete

(No version information available, might only be in Git)

Table::delete — Löscht Zeilen aus einer Tabelle

### Beschreibung

public function mysql_xdevapi\Table::delete(): mysql_xdevapi\TableDelete

Löscht Zeilen aus einer Tabelle.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein TableDelete-Objekt zurück. Mit der Methode execute() kann die DELETE-Anweisung ausgeführt werden.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::delete()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()->where("name = :name")->orderby("age DESC")->limit(1)->bind(['name' => 'John'])->execute();
    ?>

# Table::existsInDatabase

(No version information available, might only be in Git)

Table::existsInDatabase — Prüft, ob es die angegebene Tabelle in der Datenbank gibt

### Beschreibung

public function mysql_xdevapi\Table::existsInDatabase(): bool

Überprüft, ob es die angegebene Tabelle in der Datenbank gibt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn es die Tabelle in der Datenbank gibt, und `false`, wenn nicht.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::existsInDatabase()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->existsInDatabase()) {
      echo "Ja, diese Tabelle gibt es noch im Schema der Session.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Ja, diese Tabelle gibt es noch im Schema der Session.

# Table::getName

(No version information available, might only be in Git)

Table::getName — Ruft den Namen einer Tabelle ab

### Beschreibung

public function mysql_xdevapi\Table::getName(): string

Gibt den Namen des angegebenen Datenbankobjekts zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Namen des angegebenen Datenbankobjekts zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::getName()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getName());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(5) "names"

# Table::getSchema

(No version information available, might only be in Git)

Table::getSchema — Ruft das Schema einer Tabelle ab

### Beschreibung

public function mysql_xdevapi\Table::getSchema(): mysql_xdevapi\Schema

Ruft das mit der Tabelle verknüpfte Schema ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Schema-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::getSchema()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSchema());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(mysql_xdevapi\Schema)#9 (1) {
      ["name"]=>
      string(11) "addressbook"
    }

# Table::getSession

(No version information available, might only be in Git)

Table::getSession — Ruft die Session zu einer Tabelle ab

### Beschreibung

public function mysql_xdevapi\Table::getSession(): mysql_xdevapi\Session

Ruft die mit der Tabelle verknüpfte Session ab.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Session-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::getSession()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    var_dump($table->getSession());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(mysql_xdevapi\Session)#9 (0) {
    }

# Table::insert

(No version information available, might only be in Git)

Table::insert — Fügt Zeilen in eine Tabelle ein

### Beschreibung

public function mysql_xdevapi\Table::insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert

Fügt Zeilen in eine Tabelle ein.

### Parameter-Liste

`columns`

  Die Spalten, in die Daten eingefügt werden sollen; das kann ein Array mit einem oder mehreren Werten oder eine Zeichenkette sein.

`more_columns`

  Die Definitionen weiterer Spalten

### Rückgabewerte

Gibt ein TableInsert-Objekt zurück. Mit der Methode execute() kann die INSERT-Anweisung ausgeführt werden.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::insert()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# Table::isView

(No version information available, might only be in Git)

Table::isView — Prüft, ob eine Tabelle ein View ist

### Beschreibung

public function mysql_xdevapi\Table::isView(): bool

Prüft, ob das zugrundeliegende Objekt ein View ist oder nicht.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `true` zurück, wenn das zugrundeliegende Objekt eine Ansicht ist, und andernfalls `false`.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::isView()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    if ($table->isView()) {
        echo "Dies ist ein View.";
    } else {
        echo "Dies ist kein View.";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Dies ist kein View.

# Table::select

(No version information available, might only be in Git)

Table::select — Wählt Zeilen aus einer Tabelle aus

### Beschreibung

public function mysql_xdevapi\Table::select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect

Ruft Daten aus einer Tabelle ab.

### Parameter-Liste

`columns`

  Die Spalten, aus denen Daten ausgewählt werden sollen; das kann ein Array mit einem oder mehreren Werten oder eine Zeichenkette sein.

`more_columns`

  Die Definitionen weiterer Spalten

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück. Mit der Methode execute() kann die SELECT-Anweisung ausgeführt und ein RowResult-Objekt zurückgegeben werden.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::count()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $row = $table->select('name', 'age')->execute()->fetchAll();

    print_r($row);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 33
            )
    )

# Table::update

(No version information available, might only be in Git)

Table::update — Aktualisiert Zeilen in einer Tabelle

### Beschreibung

public function mysql_xdevapi\Table::update(): mysql_xdevapi\TableUpdate

Aktualisiert Zeilen in einer Tabelle.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein TableUpdate-Objekt zurück. Mit der Methode execute() kann die UPDATE-Anweisung ausgeführt werden.

### Beispiele

Beispiel #1 mysql_xdevapi\Table::update()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()->set('age',34)->where('name = "Sam"')->limit(1)->execute();
    ?>

## Inhaltsverzeichnis

- Table::__construct — Der Konstruktor der Klasse Table
- Table::count — Ermittelt die Anzahl der Zeilen
- Table::delete — Löscht Zeilen aus einer Tabelle
- Table::existsInDatabase — Prüft, ob es die angegebene Tabelle in der Datenbank gibt
- Table::getName — Ruft den Namen einer Tabelle ab
- Table::getSchema — Ruft das Schema einer Tabelle ab
- Table::getSession — Ruft die Session zu einer Tabelle ab
- Table::insert — Fügt Zeilen in eine Tabelle ein
- Table::isView — Prüft, ob eine Tabelle ein View ist
- Table::select — Wählt Zeilen aus einer Tabelle aus
- Table::update — Aktualisiert Zeilen in einer Tabelle

# Die Klasse TableDelete

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

Eine Anweisung, um etwas in einer Tabelle zu löschen.

## Klassenbeschreibung

class mysql_xdevapi\TableDelete implements mysql_xdevapi\Executable {
/* Methoden */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableDelete
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\TableDelete
public function orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete
public function where(string `$where_expr`): mysql_xdevapi\TableDelete
}

# TableDelete::bind

(No version information available, might only be in Git)

TableDelete::bind — Bindet die Parameter für eine DELETE-Anweisung

### Beschreibung

public function mysql_xdevapi\TableDelete::bind(array `$placeholder_values`): mysql_xdevapi\TableDelete

Bindet einen Wert an einen bestimmten Platzhalter.

### Parameter-Liste

`placeholder_values`

  Der Name des Platzhalters und der zu bindende Wert

### Rückgabewerte

Gibt ein TableDelete-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableDelete::bind()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::__construct

(No version information available, might only be in Git)

TableDelete::__construct — Der Konstruktor der Klasse TableDelete

### Beschreibung

private function mysql_xdevapi\TableDelete::__construct()

Wird von der Methode delete() aufgerufen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\TableDelete::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::execute

(No version information available, might only be in Git)

TableDelete::execute — Führt eine DELETE-Anweisung aus

### Beschreibung

public function mysql_xdevapi\TableDelete::execute(): mysql_xdevapi\Result

Führt die DELETE-Anweisung aus.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Result-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableDelete::execute()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::limit

(No version information available, might only be in Git)

TableDelete::limit — Begrenzt die Anzahl der zu löschenden Zeilen

### Beschreibung

public function mysql_xdevapi\TableDelete::limit(int `$rows`): mysql_xdevapi\TableDelete

Legt die maximale Anzahl der zu löschenden Datensätze oder Dokumente fest.

### Parameter-Liste

`rows`

  Die maximale Anzahl der zu löschenden Datensätze oder Dokumente

### Rückgabewerte

Gibt ein TableDelete-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableDelete::limit()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("name = :name")
      ->bind(['name' => 'John'])
      ->orderby("age DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::orderby

(No version information available, might only be in Git)

TableDelete::orderby — Setzt die Sortierkriterien für eine DELETE-Anweisung

### Beschreibung

public function mysql_xdevapi\TableDelete::orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete

Legt die Sortierkriterien für die Ergebnismenge fest.

### Parameter-Liste

`orderby_expr`

  Die Definition der Sortierung

### Rückgabewerte

Gibt ein TableDelete-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableDelete::orderBy()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("age = :age")
      ->bind(['age' => 42])
      ->orderby("name DESC")
      ->limit(1)
      ->execute();

    ?>

# TableDelete::where

(No version information available, might only be in Git)

TableDelete::where — Setzt die Suchbedingung für eine DELETE-Anweisung

### Beschreibung

public function mysql_xdevapi\TableDelete::where(string `$where_expr`): mysql_xdevapi\TableDelete

Legt die Bedingung fest, nach der bei der Suche gefiltert werden soll.

### Parameter-Liste

`where_expr`

  Die Suchbedingung zum Filtern von Dokumenten oder Datensätzen

### Rückgabewerte

Gibt ein TableDelete-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableDelete::where()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->delete()
      ->where("id = :id")
      ->bind(['id' => 42])
      ->limit(1)
      ->execute();

    ?>

## Inhaltsverzeichnis

- TableDelete::bind — Bindet die Parameter für eine DELETE-Anweisung
- TableDelete::__construct — Der Konstruktor der Klasse TableDelete
- TableDelete::execute — Führt eine DELETE-Anweisung aus
- TableDelete::limit — Begrenzt die Anzahl der zu löschenden Zeilen
- TableDelete::orderby — Setzt die Sortierkriterien für eine DELETE-Anweisung
- TableDelete::where — Setzt die Suchbedingung für eine DELETE-Anweisung

# Die Klasse TableInsert

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

Eine Anweisung, um etwas in eine Tabelle einzufügen.

## Klassenbeschreibung

class mysql_xdevapi\TableInsert implements mysql_xdevapi\Executable {
/* Methoden */
public function execute(): mysql_xdevapi\Result
public function values(array `$row_values`): mysql_xdevapi\TableInsert
}

# TableInsert::__construct

(No version information available, might only be in Git)

TableInsert::__construct — Der Konstruktor der Klasse TableInsert

### Beschreibung

private function mysql_xdevapi\TableInsert::__construct()

Wird von der Methode insert() aufgerufen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\TableInsert::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::execute

(No version information available, might only be in Git)

TableInsert::execute — Führt eine INSERT-Anweisung aus

### Beschreibung

public function mysql_xdevapi\TableInsert::execute(): mysql_xdevapi\Result

Führt die INSERT-Anweisung aus.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Result-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableInsert::execute()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

# TableInsert::values

(No version information available, might only be in Git)

TableInsert::values — Fügt Werte für eine einzufügende Zeile hinzu

### Beschreibung

public function mysql_xdevapi\TableInsert::values(array `$row_values`): mysql_xdevapi\TableInsert

Legt die Werte fest, die eingefügt werden sollen.

### Parameter-Liste

`row_values`

  Die einzufügenden Spaltenwerte (ein Array)

### Rückgabewerte

Gibt ein TableInsert-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableInsert::values()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table
      ->insert("name", "age")
      ->values(["Suzanne", 31],["Julie", 43])
      ->execute();
    ?>

## Inhaltsverzeichnis

- TableInsert::__construct — Der Konstruktor der Klasse TableInsert
- TableInsert::execute — Führt eine INSERT-Anweisung aus
- TableInsert::values — Fügt Werte für eine einzufügende Zeile hinzu

# Die Klasse TableSelect

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

Eine Anweisung, um Datensätze aus einer Tabelle abzurufen.

## Klassenbeschreibung

class mysql_xdevapi\TableSelect implements mysql_xdevapi\Executable {
/* Methoden */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableSelect
public function execute(): mysql_xdevapi\RowResult
public function groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect
public function having(string `$sort_expr`): mysql_xdevapi\TableSelect
public function limit(int `$rows`): mysql_xdevapi\TableSelect
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function offset(int `$position`): mysql_xdevapi\TableSelect
public function orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect
public function where(string `$where_expr`): mysql_xdevapi\TableSelect
}

# TableSelect::bind

(No version information available, might only be in Git)

TableSelect::bind — Bindet die Parameter für eine SELECT-Anweisung

### Beschreibung

public function mysql_xdevapi\TableSelect::bind(array `$placeholder_values`): mysql_xdevapi\TableSelect

Bindet einen Wert an einen bestimmten Platzhalter.

### Parameter-Liste

`placeholder_values`

  Der Name des Platzhalters und der zu bindende Wert

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::bind()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::__construct

(No version information available, might only be in Git)

TableSelect::__construct — Der Konstruktor der Klasse TableSelect

### Beschreibung

private function mysql_xdevapi\TableSelect::__construct()

Ein von der Methode select() zurückgegebenes Objekt. Mit der Methode execute() kann die Abfrage ausgeführt werden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 33)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::execute

(No version information available, might only be in Git)

TableSelect::execute — Führt eine SELECT-Anweisung aus

### Beschreibung

public function mysql_xdevapi\TableSelect::execute(): mysql_xdevapi\RowResult

Führt die SELECT-Anweisung aus, indem sie mit der Methode execute() verkettet wird.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein RowResult-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::execute()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->orderBy('age desc')
      ->execute();

    $row = $result->fetchAll();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::groupBy

(No version information available, might only be in Git)

TableSelect::groupBy — Setzt die Gruppierungskriterien für eine SELECT-Anweisung

### Beschreibung

public function mysql_xdevapi\TableSelect::groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect

Legt die Kriterien für die Gruppierung der Ergebnismenge fest.

### Parameter-Liste

`sort_expr`

  Die Kriterien für die Gruppierung

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::groupBy()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [count] => 1
                [age] => 31
            )
        [1] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::having

(No version information available, might only be in Git)

TableSelect::having — Setzt die HAVING-Bedingung für eine SELECT-Anweisung

### Beschreibung

public function mysql_xdevapi\TableSelect::having(string `$sort_expr`): mysql_xdevapi\TableSelect

Legt eine Bedingung für Datensätze fest, die bei Operationen der Aggregatfunktion berücksichtigt werden sollen.

### Parameter-Liste

`sort_expr`

  Eine Bedingung für die Aggregatfunktionen, die auf die Gruppierungskriterien angewendet werden

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::having()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('Suki', 31)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('count(*) as count', 'age')
      ->groupBy('age')->orderBy('age asc')
      ->having('count > 1')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [count] => 2
                [age] => 42
            )
    )

# TableSelect::limit

(No version information available, might only be in Git)

TableSelect::limit — Begrenzt die Anzahl der zurückgegebenen Dokumente

### Beschreibung

public function mysql_xdevapi\TableSelect::limit(int `$rows`): mysql_xdevapi\TableSelect

Legt die maximale Anzahl der zurückzugebenden Datensätze oder Dokumente fest.

### Parameter-Liste

`rows`

  Die maximale Anzahl der Datensätze oder Dokumente

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::limit()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::lockExclusive

(No version information available, might only be in Git)

TableSelect::lockExclusive — Führt eine Operation mit EXCLUSIVE LOCK aus

### Beschreibung

public function mysql_xdevapi\TableSelect::lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Führt eine Leseoperation mit EXCLUSIVE LOCK (exklusive Sperre) aus. Es kann jeweils nur eine Sperre aktiv sein.

### Parameter-Liste

`lock_waiting_option`

  Die optionale Warteoption; Voreingestellt ist `MYSQLX_LOCK_DEFAULT`. Folgende Werte sind zulässig:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::lockExclusive()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockExclusive(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::lockShared

(No version information available, might only be in Git)

TableSelect::lockShared — Führt eine Operation mit SHARED LOCK aus

### Beschreibung

public function mysql_xdevapi\TableSelect::lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect

Führt eine Leseoperation mit SHARED LOCK (geteilte Sperre) aus. Es kann jeweils nur eine Sperre aktiv sein.

### Parameter-Liste

`lock_waiting_option`

  Die optionale Warteoption; Voreingestellt ist `MYSQLX_LOCK_DEFAULT`. Folgende Werte sind zulässig:

  - `MYSQLX_LOCK_DEFAULT`

  - `MYSQLX_LOCK_NOWAIT`

  - `MYSQLX_LOCK_SKIP_LOCKED`

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::lockShared()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $session->startTransaction();

    $result = $table->select('name', 'age')
      ->lockShared(MYSQLX_LOCK_NOWAIT)
      ->execute();

    $session->commit();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
        [1] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::offset

(No version information available, might only be in Git)

TableSelect::offset — Setzt die Anzahl der zu überspringenden Zeilen

### Beschreibung

public function mysql_xdevapi\TableSelect::offset(int `$position`): mysql_xdevapi\TableSelect

Überspringt die angegebene Anzahl von Zeilen in einem Ergebnis.

### Parameter-Liste

`position`

  Die Anzahl der zu überspringenden Zeilen

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::offset()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $session->sql("DROP DATABASE IF EXISTS addressbook")->execute();
    $session->sql("CREATE DATABASE addressbook")->execute();
    $session->sql("CREATE TABLE addressbook.names(name text, age int)")->execute();
    $session->sql("INSERT INTO addressbook.names values ('John', 42), ('Sam', 42)")->execute();

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->limit(1)
      ->offset(1)
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
    )

# TableSelect::orderby

(No version information available, might only be in Git)

TableSelect::orderby — Setzt die Sortierkriterien für eine SELECT-Anweisung

### Beschreibung

public function mysql_xdevapi\TableSelect::orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect

Legt die Kriterien für die Reihenfolge fest.

### Parameter-Liste

`sort_expr`

  Die Ausdrücke, die die Kriterien für die Reihenfolge definieren; das kann ein Array mit einem oder mehreren Ausdrücken oder eine Zeichenkette sein.

`sort_exprs`

  Weitere sort_expr-Parameter

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::orderBy()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name', 'age')
      ->orderBy('name desc')
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => Sam
                [age] => 42
            )
        [1] => Array
            (
                [name] => John
                [age] => 42
            )
    )

# TableSelect::where

(No version information available, might only be in Git)

TableSelect::where — Setzt die Suchbedingung für eine SELECT-Anweisung

### Beschreibung

public function mysql_xdevapi\TableSelect::where(string `$where_expr`): mysql_xdevapi\TableSelect

Legt die Bedingung fest, nach der bei der Suche gefiltert werden soll.

### Parameter-Liste

`where_expr`

  Die Suchbedingung zum Filtern von Dokumenten oder Datensätzen

### Rückgabewerte

Gibt ein TableSelect-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableSelect::where()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $result = $table->select('name','age')
      ->where('name like :name and age > :age')
      ->bind(['name' => 'John', 'age' => 42])
      ->execute();

    $row = $result->fetchAll();
    print_r($row);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [name] => John
                [age] => 42
            )
    )

## Inhaltsverzeichnis

- TableSelect::bind — Bindet die Parameter für eine SELECT-Anweisung
- TableSelect::__construct — Der Konstruktor der Klasse TableSelect
- TableSelect::execute — Führt eine SELECT-Anweisung aus
- TableSelect::groupBy — Setzt die Gruppierungskriterien für eine SELECT-Anweisung
- TableSelect::having — Setzt die HAVING-Bedingung für eine SELECT-Anweisung
- TableSelect::limit — Begrenzt die Anzahl der zurückgegebenen Dokumente
- TableSelect::lockExclusive — Führt eine Operation mit EXCLUSIVE LOCK aus
- TableSelect::lockShared — Führt eine Operation mit SHARED LOCK aus
- TableSelect::offset — Setzt die Anzahl der zu überspringenden Zeilen
- TableSelect::orderby — Setzt die Sortierkriterien für eine SELECT-Anweisung
- TableSelect::where — Setzt die Suchbedingung für eine SELECT-Anweisung

# Die Klasse TableUpdate

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

Eine Anweisung, um Datensätze in einer Tabelle zu aktualisieren.

## Klassenbeschreibung

class mysql_xdevapi\TableUpdate implements mysql_xdevapi\Executable {
/* Methoden */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate
public function execute(): mysql_xdevapi\TableUpdate
public function limit(int `$rows`): mysql_xdevapi\TableUpdate
public function orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate
public function set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate
public function where(string `$where_expr`): mysql_xdevapi\TableUpdate
}

# TableUpdate::bind

(No version information available, might only be in Git)

TableUpdate::bind — Bindet die Parameter für eine UPDATE-Anweisung

### Beschreibung

public function mysql_xdevapi\TableUpdate::bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate

Bindet einen Wert an einen bestimmten Platzhalter.

### Parameter-Liste

`placeholder_values`

  Der Name des Platzhalters und der zu bindende Wert, definiert als JSON-Array.

### Rückgabewerte

Gibt ein TableUpdate-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableUpdate::bind()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $table->update()
      ->set('status', 'admin')
      ->where('name = :name and age > :age')
      ->bind(['name' => 'Bernie', 'age' => 2000])
      ->execute();

    ?>

# TableUpdate::__construct

(No version information available, might only be in Git)

TableUpdate::__construct — Der Konstruktor der Klasse TableUpdate

### Beschreibung

private function mysql_xdevapi\TableUpdate::__construct()

Wird von der Methode update() aufgerufen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\TableUpdate::__construct()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::execute

(No version information available, might only be in Git)

TableUpdate::execute — Führt eine UPDATE-Anweisung aus

### Beschreibung

public function mysql_xdevapi\TableUpdate::execute(): mysql_xdevapi\TableUpdate

Führt die UPDATE-Anweisung aus.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein TableUpdate-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableUpdate::execute()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::limit

(No version information available, might only be in Git)

TableUpdate::limit — Begrenzt die Anzahl der zu aktualisierenden Zeilen

### Beschreibung

public function mysql_xdevapi\TableUpdate::limit(int `$rows`): mysql_xdevapi\TableUpdate

Legt die maximale Anzahl der zu aktualisierenden Datensätze oder Dokumente fest.

### Parameter-Liste

`rows`

  Die maximale Anzahl der zu aktualisierenden Datensätze oder Dokumente

### Rückgabewerte

Gibt ein TableUpdate-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableUpdate::limit()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::orderby

(No version information available, might only be in Git)

TableUpdate::orderby — Setzt die Sortierkriterien für eine UPDATE-Anweisung

### Beschreibung

public function mysql_xdevapi\TableUpdate::orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate

Legt die Kriterien für die Sortierung fest.

### Parameter-Liste

`orderby_expr`

  Die Ausdrücke, die die Kriterien für die Reihenfolge definieren; das kann ein Array mit einem oder mehreren Ausdrücken oder eine Zeichenkette sein.

`orderby_exprs`

  Weitere sort_expr-Parameter

### Rückgabewerte

Gibt ein TableUpdate-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableUpdate::orderby()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();
    ?>

# TableUpdate::set

(No version information available, might only be in Git)

TableUpdate::set — Fügt eine zu aktualisierende Spalte hinzu

### Beschreibung

public function mysql_xdevapi\TableUpdate::set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate

Aktualisiert in den Datensätzen einer Tabelle die Werte einer Spalte.

### Parameter-Liste

`table_field`

  Der Name der zu aktualisierenden Spalte

`expression_or_literal`

  Der Wert, auf den die angegebene Spalte gesetzt werden soll

### Rückgabewerte

Gibt ein TableUpdate-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableUpdate::set()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

# TableUpdate::where

(No version information available, might only be in Git)

TableUpdate::where — Setzt den Suchfilter

### Beschreibung

public function mysql_xdevapi\TableUpdate::where(string `$where_expr`): mysql_xdevapi\TableUpdate

Legt die Bedingung fest, nach der bei der Suche gefiltert werden soll.

### Parameter-Liste

`where_expr`

  Die Suchbedingung zum Filtern von Dokumenten oder Datensätzen

### Rückgabewerte

Gibt ein TableUpdate-Objekt zurück.

### Beispiele

Beispiel #1 mysql_xdevapi\TableUpdate::where()-Beispiel

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");

    $schema = $session->getSchema("addressbook");
    $table  = $schema->getTable("names");

    $res = $table->update()
      ->set('level', 3)
      ->where('age > 15 and age < 22')
      ->limit(4)
      ->orderby(['age asc','name desc'])
      ->execute();

    ?>

## Inhaltsverzeichnis

- TableUpdate::bind — Bindet die Parameter für eine UPDATE-Anweisung
- TableUpdate::__construct — Der Konstruktor der Klasse TableUpdate
- TableUpdate::execute — Führt eine UPDATE-Anweisung aus
- TableUpdate::limit — Begrenzt die Anzahl der zu aktualisierenden Zeilen
- TableUpdate::orderby — Setzt die Sortierkriterien für eine UPDATE-Anweisung
- TableUpdate::set — Fügt eine zu aktualisierende Spalte hinzu
- TableUpdate::where — Setzt den Suchfilter

# Die Klasse Warning

(PECL mysql-xdevapi >= 8.0.11)

## Einführung

## Klassenbeschreibung

class mysql_xdevapi\Warning {
/* Eigenschaften */
public $message;
public $level;
public $code;
/* Konstruktor */
private function __construct()
}

## Eigenschaften

message

level

code

# Warning::__construct

(No version information available, might only be in Git)

Warning::__construct — Der Konstruktor der Klasse Warning

### Beschreibung

private function mysql_xdevapi\Warning::__construct()

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Beispiele

Beispiel #1 mysql_xdevapi\Warning::__construct()-Beispiel

    <?php

    /* ... */

    ?>

## Inhaltsverzeichnis

- Warning::__construct — Der Konstruktor der Klasse Warning

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Erstellen/Kompilieren aus dem Quellcode
- Vordefinierte Konstanten
- Changelog
- Beispiele
- Mysql_xdevapi-Funktionen
  - expression — Bindet die Variablen der vorbereiteten Anweisung als Parameter
  - getSession — Baut eine Verbindung zu einem MySQL-Server auf
- mysql_xdevapi\BaseResult — Die BaseResult-Schnittstelle
  - BaseResult::getWarnings — Ruft Warnungen der letzten Operation ab
  - BaseResult::getWarningsCount — Ruft die Anzahl der Warnungen der letzten Operation ab
- mysql_xdevapi\Client — Die Klasse Client
  - mysql_xdevapi\Client::close — Schließt die Client-Verbindung
  - Client::__construct — Der Konstruktor der Klasse Client
  - Client::getClient — Ruft eine Client-Session ab
- mysql_xdevapi\Collection — Die Klasse Collection
  - Collection::add — Fügt einer Sammlung Dokumente hinzu
  - Collection::addOrReplaceOne — Fügt einer Sammlung ein Dokument hinzu oder ersetzt es
  - Collection::__construct — Der Konstruktor der Klasse Collection
  - Collection::count — Ermittelt die Anzahl der Dokumente
  - Collection::createIndex — Erzeugt einen Index für die Sammlung
  - Collection::dropIndex — Löscht den Index einer Sammlung
  - Collection::existsInDatabase — Prüft, ob es die Sammlung in der Datenbank gibt
  - Collection::find — Sucht nach Dokumenten
  - Collection::getName — Ruft den Namen einer Sammlung ab
  - Collection::getOne — Ruft ein Dokument ab
  - Collection::getSchema — Ruft ein Schema-Objekt ab
  - Collection::getSession — Ruft ein Session-Objekt ab
  - Collection::modify — Ändert Dokumente einer Sammlung
  - Collection::remove — Löscht Dokumente einer Sammlung
  - Collection::removeOne — Löscht ein Dokument einer Sammlung
  - Collection::replaceOne — Ersetzt ein Dokument einer Sammlung
- mysql_xdevapi\CollectionAdd — Die Klasse CollectionAdd
  - CollectionAdd::__construct — Der Konstruktor der Klasse CollectionAdd
  - CollectionAdd::execute — Führt eine Anweisung aus
- mysql_xdevapi\CollectionFind — Die Klasse CollectionFind
  - CollectionFind::bind — Bindet einen Wert an den Platzhalter einer Abfrage
  - CollectionFind::__construct — Der Konstruktor der Klasse CollectionFind
  - CollectionFind::execute — Führt eine Anweisung aus
  - CollectionFind::fields — Setzt den Filter für die Felder eines Dokuments
  - CollectionFind::groupBy — Setzt die Kriterien für die Gruppierung
  - CollectionFind::having — Setzt Bedingungen für Aggregatfunktionen
  - CollectionFind::limit — Begrenzt die Anzahl der zurückgegebenen Dokumente
  - CollectionFind::lockExclusive — Führt eine Operation mit EXCLUSIVE LOCK aus
  - CollectionFind::lockShared — Führt eine Operation mit SHARED LOCK aus
  - CollectionFind::offset — Überspringt die angegebene Anzahl von Elementen, die zurückgegeben werden sollen
  - CollectionFind::sort — Setzt die Kriterien für die Sortierung
- mysql_xdevapi\CollectionModify — Die Klasse CollectionModify
  - CollectionModify::arrayAppend — Hängt ein Element an das Array eines Feldes an
  - CollectionModify::arrayInsert — Fügt ein Element in das Array eines Feldes ein
  - CollectionModify::bind — Bindet einen Wert an einen Platzhalter einer Abfrage
  - CollectionModify::__construct — Der Konstruktor der Klasse CollectionModify
  - CollectionModify::execute — Führt eine Änderungsoperation aus
  - CollectionModify::limit — Begrenzt die Anzahl der zu ändernden Dokumente
  - CollectionModify::patch — Patcht ein Dokument
  - CollectionModify::replace — Ersetzt ein Feld eines Dokuments
  - CollectionModify::set — Setzt ein Attribut eines Dokuments
  - CollectionModify::skip — Überspringt Elemente
  - CollectionModify::sort — Setzt die Kriterien für die Sortierung
  - CollectionModify::unset — Löscht den Wert eines Feldes in einem Dokument
- mysql_xdevapi\CollectionRemove — Die Klasse CollectionRemove
  - CollectionRemove::bind — Bindet einen Wert an einen Platzhalter
  - CollectionRemove::__construct — Der Konstruktor der Klasse CollectionRemove
  - CollectionRemove::execute — Führt eine Löschoperation aus
  - CollectionRemove::limit — Begrenzt die Anzahl der zu löschenden Dokumente
  - CollectionRemove::sort — Setzt die Kriterien für die Sortierung
- mysql_xdevapi\ColumnResult — Die Klasse ColumnResult
  - ColumnResult::__construct — Der Konstruktor der Klasse ColumnResult
  - ColumnResult::getCharacterSetName — Ruft den Zeichensatz einer Spalte ab
  - ColumnResult::getCollationName — Ruft den Namen der Sortierreihenfolge einer Spalte ab
  - ColumnResult::getColumnLabel — Ruft den Bezeichner (Label) einer Spalte ab
  - ColumnResult::getColumnName — Ruft den Namen einer Spalte ab
  - ColumnResult::getFractionalDigits — Ruft die Anzahl der Nachkommastellen einer Spalte ab
  - ColumnResult::getLength — Ruft die Länge eines Spaltenfeldes ab
  - ColumnResult::getSchemaName — Ruft den Namen des Schemas einer Spalte ab
  - ColumnResult::getTableLabel — Ruft den Bezeichner (Label) der Tabelle einer Spalte ab
  - ColumnResult::getTableName — Ruft den Namen der Tabelle einer Spalte ab
  - ColumnResult::getType — Ruft den Typ einer Spalte ab
  - ColumnResult::isNumberSigned — Prüft, ob der Typ einer Spalte vorzeichenbehaftet ist
  - ColumnResult::isPadded — Prüft, ob eine Spalte aufgefüllt wird
- mysql_xdevapi\CrudOperationBindable — Die CrudOperationBindable-Schnittstelle
  - CrudOperationBindable::bind — Bindet einen Wert an einen Platzhalter
- mysql_xdevapi\CrudOperationLimitable — Die CrudOperationLimitable-Schnittstelle
  - CrudOperationLimitable::limit — Begrenzt die Anzahl der Ergebnisse
- mysql_xdevapi\CrudOperationSkippable — Die CrudOperationSkippable-Schnittstelle
  - CrudOperationSkippable::skip — Überspringt die angegebene Anzahl von Datensätzen
- mysql_xdevapi\CrudOperationSortable — Die CrudOperationSortable-Schnittstelle
  - CrudOperationSortable::sort — Sortiert die Ergebnisse
- mysql_xdevapi\DatabaseObject — Die DatabaseObject-Schnittstelle
  - DatabaseObject::existsInDatabase — Prüft, ob es das Objekt in der Datenbank gibt
  - DatabaseObject::getName — Ruft den Namen eines Objekts ab
  - DatabaseObject::getSession — Ruft den Namen einer Session ab
- mysql_xdevapi\DocResult — Die Klasse DocResult
  - DocResult::__construct — Der Konstruktor der Klasse DocResult
  - DocResult::fetchAll — Ruft alle Zeilen aus einer Ergebnismenge ab
  - DocResult::fetchOne — Ruft eine Zeile aus einer Ergebnismenge ab
  - DocResult::getWarnings — Ruft die Warnungen der letzten Operation ab
  - DocResult::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation
- mysql_xdevapi\Exception — Die Klasse Exception
- mysql_xdevapi\Executable — Die Executable-Schnittstelle
  - Executable::execute — Führt eine Anweisung aus
- mysql_xdevapi\ExecutionStatus — Die Klasse ExecutionStatus
  - ExecutionStatus::__construct — Der Konstruktor der Klasse ExecutionStatus
- mysql_xdevapi\Expression — Die Klasse Expression
  - Expression::__construct — Der Konstruktor der Klasse Expression
- mysql_xdevapi\Result — Die Klasse Result
  - Result::__construct — Der Konstruktor der Klasse Result
  - Result::getAffectedItemsCount — Ermittelt die Anzahl der betroffenen Zeilen
  - Result::getAutoIncrementValue — Ruft einen automatisch erhöhten Wert ab
  - Result::getGeneratedIds — Ruft die zuletzt erzeugten IDs ab
  - Result::getWarnings — Ruft die Warnungen der letzten Operation ab
  - Result::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation
- mysql_xdevapi\RowResult — Die Klasse RowResult
  - RowResult::__construct — Der Konstruktor der Klasse RowResult
  - RowResult::fetchAll — Ruft alle Zeilen aus einer Ergebnismenge ab
  - RowResult::fetchOne — Ruft eine Zeile aus einer Ergebnismenge ab
  - RowResult::getColumnsCount — Ermittelt die Anzahl der Spalten einer Ergebnismenge
  - RowResult::getColumnNames — Ruft alle Spaltennamen aus einer Ergebnismenge ab
  - RowResult::getColumns — Ruft die Metadaten der Spalten aus einer Ergebnismenge ab
  - RowResult::getWarnings — Ruft die Warnungen der letzten Operation ab
  - RowResult::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation
- mysql_xdevapi\Schema — Die Klasse Schema
  - Schema::__construct — Der Konstruktor der Klasse Schema
  - Schema::createCollection — Fügt einem Schema eine Sammlung hinzu
  - Schema::dropCollection — Entfernt eine Sammlung aus einem Schema
  - Schema::existsInDatabase — Prüft, ob es das angegebene Objekt in der Datenbank gibt
  - Schema::getCollection — Ruft eine Sammlung aus einem Schema ab
  - Schema::getCollectionAsTable — Ruft eine Sammlung als Table-Objekt ab
  - Schema::getCollections — Ruft alle Sammlungen eines Schemas ab
  - Schema::getName — Ruft den Namen eines Schemas ab
  - Schema::getSession — Ruft eine Schema-Session ab
  - Schema::getTable — Ruft eine Tabelle eines Schemas ab
  - Schema::getTables — Ruft alle Tabellen eines Schemas ab
- mysql_xdevapi\SchemaObject — Die SchemaObject-Schnittstelle
  - SchemaObject::getSchema — Ruft ein Schema-Objekt ab
- mysql_xdevapi\Session — Die Klasse Session
  - Session::close — Schließt eine Session
  - Session::commit — Bestätigt eine Transaktion
  - Session::__construct — Der Konstruktor der Klasse Session
  - Session::createSchema — Erstellt ein neues Schema
  - Session::dropSchema — Löscht ein Schema
  - Session::generateUUID — Erzeugt eine neue UUID
  - Session::getDefaultSchema — Ruft den Namen des Standardschemas ab
  - Session::getSchema — Ruft ein neues Schema-Objekt ab
  - Session::getSchemas — Ruft Schema-Objekte ab
  - Session::getServerVersion — Ruft die Serverversion ab
  - Session::listClients — Ruft eine Liste der Clients ab
  - Session::quoteName — Fügt Anführungszeichen hinzu
  - Session::releaseSavepoint — Entfernt einen gesetzten Sicherungspunkt
  - Session::rollback — Macht eine Transaktion rückgängig (Rollback)
  - Session::rollbackTo — Macht eine Transaktion bis zu einem Sicherungspunkt rückgängig
  - Session::setSavepoint — Erzeugt einen Sicherungspunkt
  - Session::sql — Erzeugt eine SQL-Anweisung
  - Session::startTransaction — Startet eine Transaktion
- mysql_xdevapi\SqlStatement — Die Klasse SqlStatement
  - SqlStatement::bind — Bindet die Parameter einer Anweisung
  - SqlStatement::__construct — Der Konstruktor der Klasse SqlStatement
  - SqlStatement::execute — Führt eine Operation aus
  - SqlStatement::getNextResult — Ruft das nächste Ergebnis ab
  - SqlStatement::getResult — Ruft ein Ergebnis ab
  - SqlStatement::hasMoreResults — Prüft, ob es weitere Ergebnisse gibt
- mysql_xdevapi\SqlStatementResult — Die Klasse SqlStatementResult
  - SqlStatementResult::__construct — Der Konstruktor der Klasse SqlStatementResult
  - SqlStatementResult::fetchAll — Ruft alle Zeilen aus dem Ergebnis ab
  - SqlStatementResult::fetchOne — Ruft eine Zeile aus dem Ergebnis ab
  - SqlStatementResult::getAffectedItemsCount — Ermittelt die Anzahl der betroffenen Zeilen
  - SqlStatementResult::getColumnsCount — Ermittelt die Anzahl der Spalten
  - SqlStatementResult::getColumnNames — Ruft die Namen der Spalten ab
  - SqlStatementResult::getColumns — Ruft Spalten ab
  - SqlStatementResult::getGeneratedIds — Ruft die zuletzt erzeugten IDs ab
  - SqlStatementResult::getLastInsertId — Ruft die ID der letzten Einfügung ab
  - SqlStatementResult::getWarnings — Ruft die Warnungen der letzten Operation ab
  - SqlStatementResult::getWarningsCount — Ermittelt die Anzahl der Warnungen der letzten Operation
  - SqlStatementResult::hasData — Prüft, ob die Ergebnismenge Daten enthält
  - SqlStatementResult::nextResult — Ruft das nächste Ergebnis ab
- mysql_xdevapi\Statement — Die Klasse Statement
  - Statement::__construct — Der Konstruktor der Klasse Statement
  - Statement::getNextResult — Ruft das nächste Ergebnis ab
  - Statement::getResult — Ruft ein Ergebnis ab
  - Statement::hasMoreResults — Prüft, ob es weitere Ergebnisse gibt
- mysql_xdevapi\Table — Die Klasse Table
  - Table::__construct — Der Konstruktor der Klasse Table
  - Table::count — Ermittelt die Anzahl der Zeilen
  - Table::delete — Löscht Zeilen aus einer Tabelle
  - Table::existsInDatabase — Prüft, ob es die angegebene Tabelle in der Datenbank gibt
  - Table::getName — Ruft den Namen einer Tabelle ab
  - Table::getSchema — Ruft das Schema einer Tabelle ab
  - Table::getSession — Ruft die Session zu einer Tabelle ab
  - Table::insert — Fügt Zeilen in eine Tabelle ein
  - Table::isView — Prüft, ob eine Tabelle ein View ist
  - Table::select — Wählt Zeilen aus einer Tabelle aus
  - Table::update — Aktualisiert Zeilen in einer Tabelle
- mysql_xdevapi\TableDelete — Die Klasse TableDelete
  - TableDelete::bind — Bindet die Parameter für eine DELETE-Anweisung
  - TableDelete::__construct — Der Konstruktor der Klasse TableDelete
  - TableDelete::execute — Führt eine DELETE-Anweisung aus
  - TableDelete::limit — Begrenzt die Anzahl der zu löschenden Zeilen
  - TableDelete::orderby — Setzt die Sortierkriterien für eine DELETE-Anweisung
  - TableDelete::where — Setzt die Suchbedingung für eine DELETE-Anweisung
- mysql_xdevapi\TableInsert — Die Klasse TableInsert
  - TableInsert::__construct — Der Konstruktor der Klasse TableInsert
  - TableInsert::execute — Führt eine INSERT-Anweisung aus
  - TableInsert::values — Fügt Werte für eine einzufügende Zeile hinzu
- mysql_xdevapi\TableSelect — Die Klasse TableSelect
  - TableSelect::bind — Bindet die Parameter für eine SELECT-Anweisung
  - TableSelect::__construct — Der Konstruktor der Klasse TableSelect
  - TableSelect::execute — Führt eine SELECT-Anweisung aus
  - TableSelect::groupBy — Setzt die Gruppierungskriterien für eine SELECT-Anweisung
  - TableSelect::having — Setzt die HAVING-Bedingung für eine SELECT-Anweisung
  - TableSelect::limit — Begrenzt die Anzahl der zurückgegebenen Dokumente
  - TableSelect::lockExclusive — Führt eine Operation mit EXCLUSIVE LOCK aus
  - TableSelect::lockShared — Führt eine Operation mit SHARED LOCK aus
  - TableSelect::offset — Setzt die Anzahl der zu überspringenden Zeilen
  - TableSelect::orderby — Setzt die Sortierkriterien für eine SELECT-Anweisung
  - TableSelect::where — Setzt die Suchbedingung für eine SELECT-Anweisung
- mysql_xdevapi\TableUpdate — Die Klasse TableUpdate
  - TableUpdate::bind — Bindet die Parameter für eine UPDATE-Anweisung
  - TableUpdate::__construct — Der Konstruktor der Klasse TableUpdate
  - TableUpdate::execute — Führt eine UPDATE-Anweisung aus
  - TableUpdate::limit — Begrenzt die Anzahl der zu aktualisierenden Zeilen
  - TableUpdate::orderby — Setzt die Sortierkriterien für eine UPDATE-Anweisung
  - TableUpdate::set — Fügt eine zu aktualisierende Spalte hinzu
  - TableUpdate::where — Setzt den Suchfilter
- mysql_xdevapi\Warning — Die Klasse Warning
  - Warning::__construct — Der Konstruktor der Klasse Warning

# Ursprüngliche MySQL API

# Einführung

Diese Erweiterung ist seit PHP 5.5.0 veraltet und wurde in PHP 7.0.0 entfernt. Stattdessen sollten entweder die mysqli oder PDO_MySQL Erweiterungen genutzt werden. Siehe auch die Übersicht der MySQL APIs , um weitere Hilfe bei der Auswahl der MySQL API zu erhalten.

Diese Funktionen erlauben den Zugriff auf einen MySQL Datenbank-Server. Weitere Information zu MySQL sind unter » http://www.mysql.com/ erhältlich.

Die Dokumentation zu MySQL ist unter » http://dev.mysql.com/doc/ zu finden.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

Um diese Funktionen nutzen zu können, müssen Sie PHP mit MySQL-Unterstützung übersetzen.

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

## Installation

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

Verwenden Sie die Konfigurationsoption --with-mysql[=DIR], um diese Erweiterung zu kompilieren. Der optionale Parameter `[DIR]` sollte dabei das Verzeichnis angeben, in dem Sie MySQL installiert haben.

Die MySQL-Erweiterung ist zwar kompatibel mit aktuellen MySQL-Versionen, sie unterstützt aber nicht mehr alle zusätzlichen Funktionalitäten die seit MySQL 4.1.0 hinzugekommen sind. Wenn Sie diese benötigen, so verwenden Sie stattdessen die neuere MySQLi-Erweiterung.

Wenn Sie beide MySQL-Erweiterungen gleichzeitig verwenden wollen, so sollten Sie diese mit der gleichen MySQL-Client-Bibliotheksversion erstellen, um mögliche Versionskonflikte zu vermeiden.

## Installation auf Linux-Systemen

Beachten sie: `[DIR]` ist der Pfad zu den MySQL-Client-Bibliotheksdateien (Header-Dateien und Bibliotheken), die von » MySQL heruntergeladen werden können.

Matrix der ext/mysql-Kompilierungsoptionen
PHP Version | Standard | Konfigurationsoptionen: mysqlnd | Konfigurationsoptionen: `libmysqlclient` | Changelog
--- | --- | --- | --- | ---
4.x.x | libmysqlclient | Nicht verfügbar | --without-mysql zum Deaktivieren | MySQL ist standardmäßig aktiviert und die MySQL-Client-Bibliotheken sind gebündelt.
5.0.x, 5.1.x, 5.2.x | libmysqlclient | Nicht verfügbar | --with-mysql=[DIR] | MySQL ist nicht mehr standardmäßig aktiviert und die MySQL-Client-Bibliotheken sind nicht mehr gebündelt.
5.3.x | libmysqlclient | --with-mysql=mysqlnd | --with-mysql=[DIR] | mysqlnd ist nun verügbar
5.4.x | mysqlnd | --with-mysql | --with-mysql=[DIR] | mysqlnd ist nun der Standard

## Installation auf Windows-Systemen

## PHP 5.0.x, 5.1.x, 5.2.x

MySQL ist nicht mehr automatisch aktiviert, Sie müssen die DLL php_mysql.dll in Ihrer php.ini selbst einbinden. PHP benötigt darüber hinaus Zugriff auf die MySQL-Client-Bibliothek. Eine Datei mit Namen libmysql.dll ist in der PHP-Distribution für Windows enthalten. Diese muss für Ihr Windows-System über PATH zu finden sein, damit Sie MySQL-Datenbanken aus PHP heraus verwenden können. Der FAQ-Eintrag "Wie füge ich unter Windows mein PHP-Verzeichnis zu PATH hinzu?" bietet nähere Informationen zu diesem Thema. Sie können libmysql.dll zwar auch direkt in Ihr Windows-Systemverzeichnis kopieren (da dieses immer im PATH-Suchpfad enthalten ist), von diesem Vorgehen wird aber abgeraten.

Die PHP-Direktive extension_dir sollte, wie bei jeder anderen Erweiterung auch, auf das Verzeichnis zeigen, in dem die PHP-Erweiterungen (wie php_mysql.dll) zu finden sind. Siehe hierzu auch Manuelle PHP-Installation auf Windows. Ein Beispiel für einen Wert von extension_dir für PHP 5 ist `c:\php\ext`.

> Hinweis: Erscheint beim Start des Webservers eine Fehlermeldung in der Art von `"Unable to load dynamic library './php_mysql.dll'"`, so liegt das daran, dass php_mysql.dll und/oder libmysql.dll vom System nicht gefunden werden konnten.

## PHP 5.3.0+

Der MySQL Native Treiber ist standardmäßig aktiviert. Binden sie php_mysql.dll ein, libmysql.dll wird jedoch nicht mehr benötigt oder verwendet.

## MySQL-Installationshinweise

Warnung

Initialisierungsprobleme und Abstürze können vorkommen, wenn Sie diese Erweiterung zusammen mit der Erweiterung recode verwenden. Nähere Informationen hierzu finden Sie im Handbuch-Abschnitt zu recode.

> Hinweis: Wenn Sie andere Zeichensätze als den Standardzeichensatz latin verwenden sollen, so müssen Sie zum Erstellen der Erweiterung eine externe libmysqlclient verwenden die mit voller Zeichensatzunterstützung erstellt wurde. Die mit PHP 4 mitgelieferte libmysql bietet dies nicht.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

MySQL-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
mysql.allow_local_infile | "1" | `INI_SYSTEM` |
mysql.allow_persistent | "1" | `INI_SYSTEM` |
mysql.max_persistent | "-1" | `INI_SYSTEM` |
mysql.max_links | "-1" | `INI_SYSTEM` |
mysql.trace_mode | "0" | `INI_ALL` |
mysql.default_port | NULL | `INI_ALL` |
mysql.default_socket | NULL | `INI_ALL` |
mysql.default_host | NULL | `INI_ALL` |
mysql.default_user | NULL | `INI_ALL` |
mysql.default_password | NULL | `INI_ALL` |
mysql.connect_timeout | "60" | `INI_ALL` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`mysql.allow_local_infile` int
  Erlaubt den Zugriff auf (aus PHPs Sicht) lokale Dateien mit LOAD DATA Anweisungen
`mysql.allow_persistent` bool
  Gibt an, ob persistente Verbindungen zu MySQL gestattet werden sollen.
`mysql.max_persistent` int
  Die maximale Anzahl von persistenten MySQL-Verbindungen pro Prozess.
`mysql.max_links` int
  Die maximale Anzahl von MySQL-Verbindungen einschließlich persistenter, pro Prozess.
`mysql.trace_mode` bool
  Falls `mysql.trace_mode` aktiviert ist, werden Warnungen für Tabellen/Index-Scans, nicht freigegebene Ergebnismengen und SQL-Fehler angezeigt. (Eingeführt in PHP 4.3.0)
`mysql.default_port` string
  Gibt die Portnummer an, über den die Verbindung zum MySQL-Server aufgebaut werden soll, wenn kein Port als Verbindungsparameter übergeben wurde. Wird die Portnummer nicht angegeben, wird der Port über die Umgebungsvariable MYSQL_TCP_PORT, dem Eintrag `mysql-tcp` aus der Datei /etc/services oder der compile-time-Konstanten `MYSQL_PORT` in genau dieser Reihenfolge festgelegt. Win32-Systeme verwenden nur die Konstante. `MYSQL_PORT`.
`mysql.default_socket` string
  Legt den Socketnamen fest, der bei der Verbindung zu einem lokalen Datenbankserver verwendet werden soll, wenn kein anderer Name angegeben wurde.
`mysql.default_host` string
  Legt den Datenbankserver fest, zu dem eine Verbindung aufgebaut werden soll, wenn kein Server angegeben wurde. Diese Option hat im SQL safe mode keine Auswirkungen.
`mysql.default_user` string
  Legt den Benutzernamen fest, der bei einer Verbindung zu einer Datenbank verwendet werden soll, wenn kein Benutzer angegeben wurde. Diese Option hat im SQL safe mode keine Auswirkungen.
`mysql.default_password` string
  Legt das Passwort fest, das bei einer Verbindung zu einer Datenbank verwendet werden soll, wenn kein Passwort angegeben wurde. Diese Option hat im SQL safe mode keine Auswirkungen.
`mysql.connect_timeout` int
  Verbindungstimeout in Sekunden. Auf Linux-Systemen wird dieser Timeout auch für die erste Antwort des Servers verwendet.

## Ressource-Typen

Innerhalb des MySQL-Moduls werden zwei Resourcetypen benutzt. Der erste ist die Verbindungskennung für eine Verbindung zum Datenbankserver, der zweite Typ ist eine Resource die auf das Ergebnis einer Anfrage/Abfrage verweist.

# Changelog

Folgende Änderungen wurden an den Klassen/Funktionen/Methoden dieser Extension vorgenommen.

### General Changelog for the ext/mysql extension

This changelog references the ext/mysql extension.

### Global ext/mysql changes

The following is a list of changes to the entire ext/mysql extension.

Version | Beschreibung
--- | ---
7.0.0 | This extension was removed from PHP. For details, see Auswahl einer API.

### Changes to existing functions

The following list is a compilation of changelog entries from the ext/mysql functions.

Version | Function | Description
--- | --- | ---

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

Es ist möglich, zusätzliche Client-Flags bei den Funktionen mysql_connect() und mysql_pconnect() anzugeben. Die folgenden Konstanten sind definiert:

MySQL-Client-Konstanten
Konstante | Beschreibung
--- | ---
`MYSQL_CLIENT_COMPRESS` | Verwende das Kompressionsprotokoll
`MYSQL_CLIENT_IGNORE_SPACE` | Erlaubt Leerzeichen nach Funktionsnamen
`MYSQL_CLIENT_INTERACTIVE` | Erlaubt Inaktivität von interactive_timeout Sekunden (anstatt wait_timeout), bevor die Verbindung geschlossen wird.
`MYSQL_CLIENT_SSL` | Verwende SSL-Verschlüsselung. Dieses Flag kann nur mit Version 4.x der MySQL-Client-Bibliothek oder neuer verwendet werden. Mit PHP 4 und den Windows Binaries für PHP 5 wird nur Version 3.23.x mitgeliefert.

Die Funktion mysql_fetch_array() verwendet eine Konstante für die verschiedenen Arten der Ergebnisarrays. Die folgenden Konstanten sind definiert:

MySQL-fetch-Konstanten
Konstante | Beschreibung
--- | ---
`MYSQL_ASSOC` | Spalten werden in einem assoziativen Array zurückgegeben.
`MYSQL_BOTH` | Spalten werden sowohl als assoziatives als auch als numerisches Array zurückgegeben.
`MYSQL_NUM` | Spalten werden als numerisches Array zurückgegeben. Der Index beginnt bei 0, dieser entspricht dem ersten Feld des Ergebnisses.

# Beispiele

## Inhaltsverzeichnis

- MySQL Extension Übersichtsbeispiel

## MySQL Extension Übersichtsbeispiel

Folgendes einfache Beispiel zeigt Ihnen, wie Sie sich mit einer MySQL-Datenbank verbinden, eine Anfrage ausführen, die Ergebnisse ausgeben und die Verbindung wieder trennen.

Beispiel #1 MySQL-Erweiterung: ein Überblicks-Beispiel

    <?php
    // Verbindung aufbauen, auswählen einer Datenbank
    $link = mysql_connect("mysql_host", "mysql_user", "mysql_password")
        or die("Keine Verbindung möglich: " . mysql_error());
    echo "Verbindung zum Datenbankserver erfolgreich";
    mysql_select_db("Meine_Datenbank") or die("Auswahl der Datenbank fehlgeschlagen");

    // Ausführen einer SQL-Anfrage
    $query = "SELECT * FROM Meine_Tabelle";
    $result = mysql_query($query) or die("Anfrage fehlgeschlagen: " . mysql_error());

    // Ausgabe der Ergebnisse in HTML
    echo "<table>\n";
    while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Freigeben des Resultsets
    mysql_free_result($result);

    // Schließen der Verbinung
    mysql_close($link);
    ?>

# MySQL Funktionen

## Anmerkungen

> Hinweis: Der Großeil der MySQL Funktionen unterstützen einen `link_identifier` als optionalen letzten Parameter. Wird keiner übergeben so wird die zuletzt geöffnete Verbindung benutzt. Existiert auch diese nicht so wird versucht eine Verbindung mit den Defaultparametern aus php.ini zu öffnen. Schlägt auch dies fehl so wird `false` zurückgegeben.

# mysql_affected_rows

(PHP 4, PHP 5)

mysql_affected_rows — Liefert die Anzahl betroffener Datensätze einer vorhergehenden MySQL-Operation

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_affected_rows()
- PDOStatement::rowCount()

### Beschreibung

function mysql_affected_rows(resource `$link_identifier` = NULL): int

Gibt die Anzahl der Datensätze zurück, die von der letzten INSERT- UPDATE-, REPLACE- oder DELETE-Abfrage in Verbindung mit `link_identifier` betroffen waren.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg die Anzahl betroffener Datensätze und zurück -1 falls die letzte Abfrage fehlschlug.

War die letzte Abfrage ein DELETE-Anweisung ohne WHERE-Bedingung, wurden alle Datensätze aus der Tabelle gelöscht. Für MySQL-Versionen vor 4.1.2 wird diese Funktion hier aber Null (0) zurückgeben.

Verwenden Sie UPDATE, wird MySQL keine Spalten aktualisieren, bei denen der neue Wert dem alten entspricht. Das kann dazu führen, dass mysql_affected_rows() nicht die tatsächliche Anzahl der betroffenen Zeilen zurückgibt, sondern nur die, die tatsächlich von der Abfrage betroffen sind.

REPLACE-Anfragen löschen zunächst den Eintrag mit dem gleichen Primärschlüssel und fügen dann den neuen Eintrag ein. Diese Funktion gibt in diesem Fall die Summe aus gelöschten und eingefügten Einträgen zurück.

Im Falle von "INSERT ... ON DUPLICATE KEY UPDATE"-Anweisungen ist der Rückgabewert `1`, wenn eine Einfügung vorgenommen wurde oder `2`, wenn eine bestehende Zeile aktualisiert wurde.

### Beispiele

Beispiel #1 mysql_affected_rows()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Keine Verbindung möglich: ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* dies sollte die korrekte Anzahl gelöschter Datensätze zurückgeben */
    mysql_query('DELETE FROM mytable WHERE id < 10');
    printf("Gelöschte Datensätze: %d\n", mysql_affected_rows());

    /* mit einer WHERE Bedingung, die niemals wahr ist, sollte 0 zurückgegeben
       werden */
    mysql_query('DELETE FROM mytable WHERE 0');
    printf("Gelöschte Datensätze: %d\n", mysql_affected_rows());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Gelöschte Datensätze: 10
    Gelöschte Datensätze: 0

Beispiel #2 mysql_affected_rows()-Beispiel mit Transaktionen

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('keine Verbindung möglich: ' . mysql_error());
    }
    mysql_select_db('mydb');

    /* Update der Datensätze */
    mysql_query("UPDATE mytable SET used=1 WHERE id < 10");
    printf ("Aktualisierte Datensätze: %d\n", mysql_affected_rows());
    mysql_query("COMMIT");
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Aktualisierte Datensätze: 10

### Anmerkungen

> Hinweis: Transaktionen
> Falls Sie Transaktionen verwenden, müssen Sie mysql_affected_rows() unmittelbar nach Ihrer INSERT-, UPDATE-, oder DELETE-Abfrage aufrufen, nicht nach dem Commit.

> Hinweis: SELECT Anweisungen
> Um die Anzahl der gelieferten Datensätze einer SELECT-Abfrage zu erhalten, verwenden Sie stattdessen die Funktion mysql_num_rows().

> Hinweis: Kaskadierende Fremdschlüssel-Beziehungen
> mysql_affected_rows() zählt keine Zeilen, die implizit durch die Verwendung von ON DELETE CASCADE und/oder ON UPDATE CASCADE in Fremdschlüssel-Bedingungen betroffen sind.

### Siehe auch

- mysql_num_rows() - Liefert die Anzahl der Zeilen in einem Ergebnis
- mysql_info() - Liefert Informationen über die zuletzt ausgeführte Anfrage

# mysql_client_encoding

(PHP 4 >= 4.3.0, PHP 5)

mysql_client_encoding — Liefert den Namen des Zeichensatzes

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_character_set_name()

### Beschreibung

function mysql_client_encoding(resource `$link_identifier` = NULL): string

Gibt die Variable `character_set` von MySQL zurück.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt den Standard-Zeichensatz (character set) für die aktuelle Verbindung zurück.

### Beispiele

Beispiel #1 mysql_client_encoding()-Beispiel

    <?php
    $link    = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $charset = mysql_client_encoding($link);

    echo "Der aktuelle Zeichensatz ist: $charset\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Der aktuelle Zeichensatz ist: latin1

### Siehe auch

- mysql_set_charset() - Setzt den Verbindungszeichensatz
- mysql_real_escape_string() - Maskiert spezielle Zeichen innerhalb einer Zeichenkette für die Verwendung in einer SQL-Anweisung

# mysql_close

(PHP 4, PHP 5)

mysql_close — Schließt eine Verbindung zu MySQL

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_close()
- PDO: Zuweisung des Wertes `null` zum PDO-Objekt

### Beschreibung

function mysql_close(resource `$link_identifier` = NULL): bool

mysql_close() schließt die nicht persistente Verbindung zum MySQL-Server, die mit der angegebenen Verbindungskennung verknüpft ist. Wird `link_identifier` nicht angegeben, wird die zuletzt geöffnete Verbindung geschlossen.

Offene nicht-persistente MySQL Verbindungen und Ergebnismengen werden automatisch zerstört, wenn ein PHP-Skript seine Ausführung beendet. Obwohl also das explizite Schließen von offenen Verbindungen und das Freigeben von Ergebnismengen optional ist, wird es dennoch empfohlen. Dadurch werden Ressourcen unmittelbar an PHP und MySQL zurückgeben, was die Performance verbessern kann. Weitere Informationen sind unter Freigeben von Ressourcen zu finden.

### Parameter-Liste

`link_identifier`

  Die MySQL Verbindung. Wenn nicht angegeben, wird die letzte mit mysql_connect() geöffnete Verbindung verwendet. Wenn noch keine Verbindung hergestellt wurde wird ein `E_WARNING` Fehler geworfen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_close()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Keine Verbindung möglich: ' . mysql_error());
    }
    echo 'Erfolgreich verbunden';
    mysql_close($link);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Erfolgreich verbunden

### Anmerkungen

> Hinweis: mysql_close() schließt keine persistenten Verbindungen, die mit mysql_pconnect() geöffnet wurden. Weitere Details sind der Manpage über Persistente Verbindungen zu entnehmen.

### Siehe auch

- mysql_connect() - Öffnet eine Verbindung zu einem MySQL-Server
- mysql_free_result() - Gibt belegten Speicher wieder frei

# mysql_connect

(PHP 4, PHP 5)

mysql_connect — Öffnet eine Verbindung zu einem MySQL-Server

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_connect()
- PDO::__construct()

### Beschreibung

function mysql_connect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
bool `$new_link` = `false`,
int `$client_flags` = 0
): resource|false

Öffnet eine neue Verbindung zu einem MySQL-Server oder verwendet eine bestehende.

### Parameter-Liste

`server`
  Der MySQL-Server. Er kann zudem eine Portnummer enthalten, z. B. "hostname:port" oder den Pfad zu einem lokalen Socket, z. B. ":/pfad/zum/socket" für Zugriffe auf dem lokalen Rechner (localhost). Wenn die PHP-Direktive mysql.default_host nicht definiert ist (Standard), ist der Vorgabewert 'localhost:3306'. Bei SQL safe mode wird dieser Paramter ignoriert und immer der Wert 'localhost:3306' verwendet.
`username`
  Der Benutzername. Der Standardwert ist durch mysql.default_user definiert. Bei SQL safe mode wird dieser Parameter ignoriert und der Name des Benutzers verwendet, dem der Prozess gehört.
`password`
  Das Passwort. Der Standardwert ist durch mysql.default_password definiert. Bei SQL safe mode wird dieser Parameter ignoriert und ein leeres Passwort verwendet.
`new_link`
  Für den Fall, dass ein zweiter Aufruf von mysql_connect() mit den gleichen Argumenten erfolgt, wird keine neue Verbindung aufgebaut, sondern die Verbindungskennung der schon bestehenden Verbindung zurückgegeben. Der Parameter `new_link` beeinflusst dieses Verhalten und mysql_connect() öffnet immer eine neue Verbindung, sogar dann, wenn mysql_connect() zu einem früheren Zeitpunkt mit den gleichen Parametern aufgerufen wurde. Bei SQL safe mode wird dieser Parameter ignoriert.
`client_flags`
  Der Parameter `client_flags` kann eine Kombination der folgenden Konstanten sein: 128 (aktiviert die Verwendung von `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` und `MYSQL_CLIENT_INTERACTIVE`. Lesen sie den Abschnitt über MySQL-Client-Konstanten für weitergehende Informationen. Bei SQL safe mode wird dieser Parameter ignoriert.

### Rückgabewerte

Gibt im Erfolgsfall eine MySQL-Verbindungskennung zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_connect()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Verbindung schlug fehl: ' . mysql_error());
    }
    echo 'Erfolgreich verbunden';
    mysql_close($link);
    ?>

Beispiel #2 mysql_connect()-Beispiel unter Verwendung der `hostname:port`-Syntax

    <?php
    // Verbindung zu example.com auf Port 3307
    $link = mysql_connect('example.com:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Verbindung schlug fehl: ' . mysql_error());
    }
    echo 'Erfolgreich verbunden';
    mysql_close($link);

    // Verbindung zu localhost auf Port 3307
    $link = mysql_connect('127.0.0.1:3307', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Verbindung schlug fehl: ' . mysql_error());
    }
    echo 'Erfolgreich verbunden';
    mysql_close($link);
    ?>

Beispiel #3 mysql_connect()-Beispiel unter Verwendung der ":/path/to/socket"-Syntax

    <?php
    // Verbing zu localhost und Socket z. B. /tmp/mysql.sock

    // Variante 1: localhost weglassen
    $link = mysql_connect(':/tmp/mysql', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Verbindung schlug fehl: ' . mysql_error());
    }
    echo 'Erfolgreich verbunden';
    mysql_close($link);

    // Variante 2: mit localhost
    $link = mysql_connect('localhost:/tmp/mysql.sock', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Verbindung schlug fehl: ' . mysql_error());
    }
    echo 'Erfolgreich verbunden';
    mysql_close($link);
    ?>

### Anmerkungen

> Hinweis: Immer wenn Sie "localhost" oder "localhost:port" als Server angeben, wird die MySQL-Client-Bibliothek dies überschreiben und versuchen, sich mit einem lokalen Socket (named pipe unter Windows) zu verbinden. Wenn Sie TCP/IP verwenden möchten, verwenden sie "127.0.0.1" statt "localhost". Wenn die MySQL-Client-Bibliothek versucht, sich mit dem falschen lokalen Socket zu verbinden, sollte der korrekte Pfad in der php.ini als mysql.default_host geetzt werden und das Server-Feld leergelassen werden.

> Hinweis: Die Verbindung zum Server wird geschlossen, sobald die Ausführung des Skripts endet, außer sie wurde zuvor explizit durch den Aufruf von mysql_close() geschlossen.

> Hinweis: Error "Can't create TCP/IP socket (10106)" deutet meist darauf hin, dass die Konfigurationsanweisung variables_order das Zeichen `E` nicht enthält. Wird unter Windows die Umgebung nicht kopiert, ist die Umgebungsvariable `SYSTEMROOT` nicht verfügbar und PHP wird Schwierigkeiten haben, Winsock zu laden.

### Siehe auch

- mysql_pconnect() - Öffnet eine persistente Verbindung zum MySQL-Server
- mysql_close() - Schließt eine Verbindung zu MySQL

# mysql_create_db

(PHP 4, PHP 5)

mysql_create_db — Legt eine MySQL-Datenbank an

Warnung

Diese Funktion wurde in PHP 4.3.0 als veraltet gekennzeichnet und wurde in PHP 7.0.0 zusammen mit der gesamten ursprünglichen MySQL-Erweiterung entfernt. Stattdessen sollten die aktiv entwickelten Erweiterungen MySQLi oder PDO_MySQL verwendet werden. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_query()
- PDO::query()

### Beschreibung

function mysql_create_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_create_db() versucht, eine neue Datenbank auf dem Server anzulegen, der mit der angegebenen Verbindungskennung verknüpft ist.

### Parameter-Liste

`database_name`
  Der Name der zu erstellenden Datenbank.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_create_db()-Alternativbeispiel

Die Funktion mysql_create_db() ist veraltet. Es ist besser, stattdessen mysql_query() zu verwenden, um eine `CREATE DATABASE`-SQL-Anweisung auszuführen.

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Verbindung fehlgeschlagen: ' . mysql_error());
    }

    $sql = 'CREATE DATABASE my_db';
    if (mysql_query($sql, $link)) {
        echo "Datenbank my_db erfolgreich erzeugt\n";
    } else {
        echo 'Erzeugung der Datenbank fehlgeschlagen:: ' . mysql_error() . "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Datenbank my_db erfolgreich erzeugt

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_createdb()

> Hinweis: Diese Funktion steht nicht zur Verfügung, wenn das MySQL-Modul gegen eine MySQL 4.x Client-Bibliothek gelinkt wurde.

### Siehe auch

- mysql_query() - Sendet eine Abfrage an MySQL
- mysql_select_db() - Wählt eine MySQL-Datenbank aus

# mysql_data_seek

(PHP 4, PHP 5)

mysql_data_seek — Bewegt den internen Ergebnis-Zeiger

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_data_seek()
- `PDO::FETCH_ORI_ABS`

### Beschreibung

function mysql_data_seek(resource `$result`, int `$row_number`): bool

mysql_data_seek() bewegt den internen Datensatz-Zeiger eines Abfrageergebnisses, das mit der übergebenen Resultkennung verknüpft ist, zu dem Datensatz mit der übergebenen Zeilennummer. Der nächste Aufruf einer MySQL-fetch-Funktion, wie etwa mysql_fetch_row() gibt die entsprechende Zeile zurück.

Die Zeilennummer `row_number` beginnt bei 0. `row_number` sollte ein Wert im Bereich zwischen 0 und mysql_num_rows() - 1 sein. Falls die Ergebnismenge jedoch leer sein sollte (mysql_num_rows() == 0), wird eine Suche nach der Zeilennummer 0 mit einem `E_WARNING` fehlschlagen und mysql_data_seek() gibt `false` zurück.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`row_number`
  Die gewünschte Zeilennummer des neuen Ergebnis-Zeigers.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_data_seek()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Keine Verbindung möglich: ' . mysql_error());
    }
    $db_selected = mysql_select_db('sample_db');
    if (!$db_selected) {
        die('Konnte Datenbank nicht auswählen: ' . mysql_error());
    }
    $query = 'SELECT last_name, first_name FROM friends';
    $result = mysql_query($query);
    if (!$result) {
        die('Anfrage fehlgeschlagen: ' . mysql_error());
    }
    /* Hole Zeilen in umgekehrter Reihenfolge */
    for ($i = mysql_num_rows($result) - 1; $i >= 0; $i--) {
        if (!mysql_data_seek($result, $i)) {
            echo "Kann nicht zu Zeile $i gehen (seek): " . mysql_error() . "\n";
            continue;
        }

        if (!($row = mysql_fetch_assoc($result))) {
            continue;
        }

        echo $row['last_name'] . ' ' . $row['first_name'] . "<br />\n";
    }

    mysql_free_result($result);
    ?>

### Anmerkungen

> Hinweis: Die Funktion mysql_data_seek() kann nur zusammen mit mysql_query() verwendet werden und nicht mit mysql_unbuffered_query().

### Siehe auch

- mysql_query() - Sendet eine Abfrage an MySQL
- mysql_num_rows() - Liefert die Anzahl der Zeilen in einem Ergebnis
- mysql_fetch_row() - Liefert einen Datensatz als indiziertes Array
- mysql_fetch_assoc() - Liefert einen Datensatz als assoziatives Array
- mysql_fetch_array() - Liefert einen Datensatz als assoziatives Array, als numerisches Array oder beides
- mysql_fetch_object() - Liefert eine Ergebniszeile als Objekt

# mysql_db_name

(PHP 4, PHP 5)

mysql_db_name — Liefert den Namen einer Datenbank vom mysql_list_dbs()-Aufruf

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- SQL-Abfrage: `SELECT DATABASE()`

### Beschreibung

function mysql_db_name(resource `$result`, int `$row`, mixed `$field` = NULL): string

Gibt den Namen einer Datenbank vom Aufruf von mysql_list_dbs() zurück.

### Parameter-Liste

`result`
  Der Ergebniszeiger von einem Aufruf von mysql_list_dbs().
`row`
  Der Index in der Ergebnismenge.
`field`
  Der Feldname (Spaltenname).

### Rückgabewerte

Gibt bei Erfolg den Namen einer Datenbank zurück und `false` bei Fehlern. Falls `false` zurückgegeben wird, verwenden sie mysql_error(), um die Art des Fehlers zu ermitteln.

### Beispiele

Beispiel #1 mysql_db_name()-Beispiel

    <?php
    error_reporting(E_ALL);

    $link = mysql_connect('dbhost', 'username', 'password');
    $db_list = mysql_list_dbs($link);

    $i = 0;
    $cnt = mysql_num_rows($db_list);
    while ($i < $cnt) {
        echo mysql_db_name($db_list, $i) . "\n";
        $i++;
    }
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_dbname()

### Siehe auch

- mysql_list_dbs() - Listet die verfügbaren Datenbanken (Schemata) auf einem MySQL-Server auf
- mysql_tablename() - Liefert den Namen einer Tabelle

# mysql_db_query

(PHP 4, PHP 5)

mysql_db_query — Wählt eine Datenbank aus und führt darauf eine Abfrage aus

Warnung

Diese Funktion wurde in PHP 5.3.0 als veraltet gekennzeichnet und wurde in PHP 7.0.0 zusammen mit der gesamten ursprünglichen MySQL-Erweiterung entfernt. Stattdessen sollten die aktiv entwickelten Erweiterungen MySQLi oder PDO_MySQL verwendet werden. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_select_db() then the query
- PDO::__construct()

### Beschreibung

function mysql_db_query(string `$database`, string `$query`, resource `$link_identifier` = NULL): resource|bool

mysql_db_query() wählt eine Datenbank aus und führt eine Abfrage darauf aus.

### Parameter-Liste

`database`
  Der Name der auszuwählenden Datenbank.
`query`
  Die MySQL-Abfrage. Die Daten innerhalb der Abfrage sollten korrekt maskiert sein.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt eine positive MySQL-Ergebnisressource für das Abfrageergebnis zurück oder `false` im Fehlerfall. Diese Funktion gibt für `INSERT`-, `UPDATE`- und `DELETE`-Abfragen ebenfalls `true`/`false` zurück, um Erfolg/Misserfolg anzuzeigen.

### Beispiele

Beispiel #1 mysql_db_query()-Alternativbeispiel

    <?php

    if (!$link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
        echo 'Keine Verbindung zu mysql';
        exit;
    }

    if (!mysql_select_db('mysql_dbname', $link)) {
        echo 'Konnte die Datenbank nicht auswählen';
        exit;
    }

    $sql    = 'SELECT foo FROM bar WHERE id = 42';
    $result = mysql_query($sql, $link);

    if (!$result) {
        echo "DB-Fehler, konnte die Datenbank nicht abfragen\n";
        echo 'MySQL Error: ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_assoc($result)) {
        echo $row['foo'];
    }

    mysql_free_result($result);

    ?>

### Anmerkungen

> Hinweis: Beachten Sie, dass diese Funktion NICHT zu der Datenbank zurückwechselt, mit der Sie sich zuvor verbunden hatten. Mit anderen Worten ausgedrückt: Sie können diese Funktion nicht verwenden, um temporär eine SQL-Abfrage auf einer anderen Datenbank auszuführen. Sie müssen selbst (manuell) sicherstellen, dass Sie wieder Ihre vorherige Datenbank verwenden. Sie sollten sich angewöhnen, statt dieser Funktion in Ihren SQL-Abfragen die Schreibweise `datenbank.tabelle` oder die Funktion mysql_select_db() zu verwenden.

### Siehe auch

- mysql_query() - Sendet eine Abfrage an MySQL
- mysql_select_db() - Wählt eine MySQL-Datenbank aus

# mysql_drop_db

(PHP 4, PHP 5)

mysql_drop_db — Löscht eine Datenbank

Warnung

Diese Funktion wurde in PHP 4.3.0 als veraltet gekennzeichnet und wurde in PHP 7.0.0 zusammen mit der gesamten ursprünglichen MySQL-Erweiterung entfernt. Stattdessen sollten die aktiv entwickelten Erweiterungen MySQLi oder PDO_MySQL verwendet werden. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- Eine `DROP DATABASE`-Anweisung ausführen

### Beschreibung

function mysql_drop_db(string `$database_name`, resource `$link_identifier` = NULL): bool

mysql_drop_db() versucht eine komplette Datenbank vom Server, der mit der übergebenen Verbindungskennung `link_identifier` verknüpft ist, zu löschen. Diese Funktion ist veraltet. Stattdessen sollte mit der Funktion mysql_query() der SQL-Befehl `DROP DATABASE` ausgeführt werden.

### Parameter-Liste

`database_name`
  Der Name der zu löschenden Datenbank.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_drop_db()-Alternativbeispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Verbindung nicht möglich: ' . mysql_error());
    }

    $sql = 'DROP DATABASE my_db';
    if (mysql_query($sql, $link)) {
        echo "Datenbank my_db wurde erfolgreich gelöscht\n";
    } else {
        echo 'Fehler beim Löschen der Datenbank: ' . mysql_error() . "\n";
    }
    ?>

### Anmerkungen

Warnung

Diese Funktion steht nicht zur Verfügung, wenn das MySQL-Modul gegen eine MySQL 4.x Client-Bibliothek gelinkt wurde.

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_dropdb()

### Siehe auch

- mysql_query() - Sendet eine Abfrage an MySQL

# mysql_errno

(PHP 4, PHP 5)

mysql_errno — Liefert die Nummer einer Fehlermeldung einer zuvor ausgeführten MySQL-Operation

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_errno()
- PDO::errorCode()

### Beschreibung

function mysql_errno(resource `$link_identifier` = NULL): int

Gibt die Fehlernummer der letzten MySQL-Funktion zurück.

Fehler, die vom MySQL-Server kommen, geben keine Warnungen mehr aus. Verwenden Sie stattdessen die Funktion mysql_errno(), um die Fehlernummer zu erhalten. Beachten Sie, dass diese Funktion nur die Fehlernummer der zuletzt ausgeführten MySQL-Funktion (ohne die Funktionen mysql_error() und mysql_errno()) zurückgibt. Wenn Sie diese Funktion also verwenden wollen, stellen Sie sicher, dass Sie den Wert überprüfen, bevor Sie eine andere MySQL-Funktion aufrufen.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt die Fehlernummer der letzten MySQL-Funktion zurück oder `0` (Null), wenn kein Fehler auftrat.

### Beispiele

Beispiel #1 mysql_errno()-Beispiel

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!mysql_select_db("nicht_vorhandene_datenbank", $link)) {
        echo mysql_errno($link) . ": " . mysql_error($link). "\n";
    }

    mysql_select_db("kossu", $link);
    if (!mysql_query("SELECT * FROM nicht_vorhandene_tabelle", $link)) {
        echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1049: Unknown database 'nicht_vorhandene_datenbank'
    1146: Table 'kossu.nicht_vorhandene_tabelle' doesn't exist

### Siehe auch

- mysql_error() - Liefert den Fehlertext der zuvor ausgeführten MySQL-Operation
- » MySQL error codes

# mysql_error

(PHP 4, PHP 5)

mysql_error — Liefert den Fehlertext der zuvor ausgeführten MySQL-Operation

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_error()
- PDO::errorInfo()

### Beschreibung

function mysql_error(resource `$link_identifier` = NULL): string

Gibt den Fehlertext der letzten MySQL-Funktion zurück. Fehler, die vom MySQL-Server kommen, geben keine Warnungen mehr aus. Verwenden Sie stattdessen die Funktion mysql_error(), um den Fehlertext zu erhalten. Beachten Sie, dass diese Funktion nur den Fehlertext der zuletzt ausgeführten MySQL-Funktion (ohne die Funktionen mysql_error() und mysql_errno()) zurückgibt. Wenn Sie diese Funktion also verwenden wollen, stellen Sie sicher, dass Sie den Wert überprüfen, bevor Sie eine andere MySQL-Funktion aufrufen.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt den Fehlertext der letzten MySQL-Funktion zurück oder `''` (eine leere Zeichenkette), falls kein Fehler aufgetreten ist.

### Beispiele

Beispiel #1 mysql_error()-Beispiel

    <?php
    $link = mysql_connect("localhost", "mysql_user", "mysql_password");

    mysql_select_db("nicht_vorhandene_datenbank", $link);
    echo mysql_errno($link) . ": " . mysql_error($link). "\n";

    mysql_select_db("kossu", $link);
    mysql_query("SELECT * FROM nicht_vorhandene_tabelle", $link);
    echo mysql_errno($link) . ": " . mysql_error($link) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1049: Unknown database 'nicht_vorhandene_datenbank'
    1146: Table 'kossu.nicht_vorhandene_tabelle' doesn't exist

### Siehe auch

- mysql_errno() - Liefert die Nummer einer Fehlermeldung einer zuvor ausgeführten MySQL-Operation
- » MySQL error codes

# mysql_escape_string

(PHP 4 >= 4.0.3, PHP 5)

mysql_escape_string — Maskiert eine Zeichenkette zur Verwendung in einer MySQL-Abfrage

Warnung

Diese Funktion wurde in PHP 4.3.0 als veraltet gekennzeichnet und wurde in PHP 7.0.0 zusammen mit der gesamten ursprünglichen MySQL-Erweiterung entfernt. Stattdessen sollten die aktiv entwickelten Erweiterungen MySQLi oder PDO_MySQL verwendet werden. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_escape_string()
- PDO::quote()

### Beschreibung

function mysql_escape_string(string `$unescaped_string`): string

Diese Funktion maskiert `unescaped_string` zur sicheren Verwendung in mysql_query().

Diese Funktion ist identisch mit der Funktion mysql_real_escape_string(), davon abgesehen, dass mysql_real_escape_string() eine Verbindungskennung benötigt und die Zeichenkette entsprechend zum aktuellen Zeichensatz maskiert. Der Funktion mysql_escape_string() kann keine Verbindungskennung übergeben werden und der aktuelle Zeichensatz wird nicht berücksichtigt.

### Parameter-Liste

`unescaped_string`
  Die zu maskierende Zeichenkette.

### Rückgabewerte

Gibt die maskierte Zeichenkette zurück.

### Beispiele

Beispiel #1 mysql_escape_string()-Beispiel

    <?php
    $item = "Zak's Laptop";
    $escaped_item = mysql_escape_string($item);
    printf("Die maskierte Zeichenkette: %s\n", $escaped_item);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Die maskierte Zeichenkette: Zak\'s Laptop

### Anmerkungen

> Hinweis: mysql_escape_string() maskiert nicht `%` und `_`.

### Siehe auch

- mysql_real_escape_string() - Maskiert spezielle Zeichen innerhalb einer Zeichenkette für die Verwendung in einer SQL-Anweisung

# mysql_fetch_array

(PHP 4, PHP 5)

mysql_fetch_array — Liefert einen Datensatz als assoziatives Array, als numerisches Array oder beides

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_array()
- PDOStatement::fetch()

### Beschreibung

function mysql_fetch_array(resource `$result`, int `$result_type` = MYSQL_BOTH): array

Gibt ein Array zurück, das dem gelesenen Datensatz entspricht und bewegt den internen Datenzeiger um einen Schritt vorwärts.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`result_type`
  Der Typ des Arrays, das gelesen werden soll. Er ist eine Konstante, die folgende Werte haben kann: `MYSQL_ASSOC`, `MYSQL_NUM` und `MYSQL_BOTH`.

### Rückgabewerte

Gibt ein Array von Zeichenketten zurück, das dem gelesenen Datensatz entspricht oder `false` falls keine weiteren Datensätze vorhanden sind. Der Typ des zurückgegebenen Arrays hängt davon ab, wie `result_type` definiert ist. Verwenden sie `MYSQL_BOTH` (Standard), erhalten sie ein Array mit sowohl assoziativen als auch numerischen Indizes. Verwenden sie `MYSQL_ASSOC` erhalten sie nur assoziative Indizes (wie bei der Funktion mysql_fetch_assoc()), mit `MYSQL_NUM` erhalten sie nur numerische Indizes (wie bei der Funktion mysql_fetch_row()).

Falls zwei oder mehrere Spalten des Ergebnisses den gleichen Feldnamen haben, dann wird nur der Wert der letzten Spalte im Array unter diesem Feldnamen abgelegt. Um auch auf die anderen gleichnamigen Spalten zugreifen zu können, müssen Sie den numerischen Index der Spalte verwenden oder einen Alias für die Spalte vergeben. Falls Sie Aliase für Spalten verwenden, können Sie auf die Inhalte dieser Spalten nicht über ihren ursprünglichen Namen zugreifen.

### Beispiele

Beispiel #1 Abfrage mit alias für identische Feldnamen

    SELECT table1.field AS foo, table2.field AS bar FROM table1, table2

Beispiel #2 mysql_fetch_array() mit `MYSQL_NUM`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
        die("Keine Verbindung möglich: " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_NUM)) {
        printf("ID: %s  Name: %s", $row[0], $row[1]);
    }

    mysql_free_result($result);
    ?>

Beispiel #3 mysql_fetch_array() mit `MYSQL_ASSOC`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
        die("Keine Verbindung möglich: " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) {
        printf("ID: %s  Name: %s", $row["id"], $row["name"]);
    }

    mysql_free_result($result);
    ?>

Beispiel #4 mysql_fetch_array() mit `MYSQL_BOTH`

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password") or
        die("Keine Verbindung möglich: " . mysql_error());
    mysql_select_db("mydb");

    $result = mysql_query("SELECT id, name FROM mytable");

    while ($row = mysql_fetch_array($result, MYSQL_BOTH)) {
        printf ("ID: %s  Name: %s", $row[0], $row["name"]);
    }

    mysql_free_result($result);
    ?>

### Anmerkungen

> Hinweis: Performance
> Zu betonen ist, dass die Verwendung von mysql_fetch_array() nicht signifikant langsamer ist als mysql_fetch_row(), obwohl die Funktion einen sichtlichen Mehrwert bietet.

> Hinweis: Bei den Spaltennamen, die von dieser Funktion zurückgegeben werden, wird zwischen Groß- und Kleinschreibung unterschieden.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Siehe auch

- mysql_fetch_row() - Liefert einen Datensatz als indiziertes Array
- mysql_fetch_assoc() - Liefert einen Datensatz als assoziatives Array
- mysql_data_seek() - Bewegt den internen Ergebnis-Zeiger
- mysql_query() - Sendet eine Abfrage an MySQL

# mysql_fetch_assoc

(PHP 4 >= 4.0.3, PHP 5)

mysql_fetch_assoc — Liefert einen Datensatz als assoziatives Array

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_assoc()
- PDOStatement::fetch() mit `PDO::FETCH_ASSOC` als `mode`

### Beschreibung

function mysql_fetch_assoc(resource `$result`): array

Gibt ein assoziatives Array zurück, das dem geholten Datensatz entspricht und bewegt den internen Datenzeiger vorwärts. mysql_fetch_assoc() entspricht in der Funktionsweise exakt dem Aufruf von mysql_fetch_array() mit Angabe von MYSQL_ASSOC als optionalen zweiten Parameter. Sie gibt nur ein assoziatives Array zurück.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

### Rückgabewerte

Gibt ein Array von Zeichenketten zurück, das dem gelesenen Datensatz entspricht oder `false` falls keine weiteren Datensätze vorhanden sind.

Falls zwei oder mehrere Felder des Ergebnisses den gleichen Feldnamen haben, dann wird nur der Wert des letzten Felds im Array unter diesem Feldnamen abgelegt. Um auch auf die anderen, gleichnamigen, Felder zugreifen zu können, müssen Sie entweder numerische Indizes und damit mysql_fetch_row() verwenden, oder Aliase für Ihre Felder anlegen. Zur Verwendung von Aliasen schauen Sie sich das Beispiel unter der Beschreibung von mysql_fetch_array() an.

### Beispiele

Beispiel #1 Ein ausführliches mysql_fetch_assoc()-Beispiel

    <?php

    $conn = mysql_connect("localhost", "mysql_user", "mysql_password");

    if (!$conn) {
        echo "Keine Verbindung zu DB möglich: " . mysql_error();
        exit;
    }

    if (!mysql_select_db("mydbname")) {
        echo "Konnte mydbname nicht auswählen: " . mysql_error();
        exit;
    }

    $sql = "SELECT id as userid, fullname, userstatus
            FROM   sometable
            WHERE  userstatus = 1";

    $result = mysql_query($sql);

    if (!$result) {
        echo "Konnte Abfrage ($sql) aus DB nicht erfolgreich ausführen: " . mysql_error();
        exit;
    }

    if (mysql_num_rows($result) == 0) {
        echo "Keine Zeilen gefunden, nichts auszugeben, also Ende";
        exit;
    }

    // Solange eine Zeile mit Daten vorhanden ist, schreibe diese Zeile in $row
    // als assoziatives Array
    // Hinweis: Wenn Sie nur eine Ergebniszeile erwarten, benötigen Sie keine Schleife
    // Hinweis: Wenn Sie extract($row) innerhalb dieser Schleife schreiben,
    //          erzeugen Sie $userid, $fullname und $userstatus
    while ($row = mysql_fetch_assoc($result)) {
        echo $row["userid"];
        echo $row["fullname"];
        echo $row["userstatus"];
    }

    mysql_free_result($result);

    ?>

### Anmerkungen

> Hinweis: Performance
> Zu betonen ist, dass die Verwendung von mysql_fetch_array() nicht signifikant langsamer ist als mysql_fetch_row(), obwohl die Funktion einen sichtlichen Mehrwert bietet.

> Hinweis: Bei den Spaltennamen, die von dieser Funktion zurückgegeben werden, wird zwischen Groß- und Kleinschreibung unterschieden.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Siehe auch

- mysql_fetch_row() - Liefert einen Datensatz als indiziertes Array
- mysql_fetch_array() - Liefert einen Datensatz als assoziatives Array, als numerisches Array oder beides
- mysql_data_seek() - Bewegt den internen Ergebnis-Zeiger
- mysql_query() - Sendet eine Abfrage an MySQL
- mysql_error() - Liefert den Fehlertext der zuvor ausgeführten MySQL-Operation

# mysql_fetch_field

(PHP 4, PHP 5)

mysql_fetch_field — Liefert ein Objekt mit Spalteninformationen aus einem Abfrageergebnis

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_field()
- PDOStatement::getColumnMeta()

### Beschreibung

function mysql_fetch_field(resource `$result`, int `$field_offset` = 0): object

Gibt ein Objekt zurück, das Feldinformationen enthält. Diese Funktion kann verwendet werden, um Informationen über Felder im übergebenen Abfrageergebnis zu erhalten.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`field_offset`
  Der numerische Feldoffset. Wird dieser nicht angegeben, so werden die Informationen über das nächste bisher noch nicht von dieser Funktion gelesene Feld zurückgegeben. Der Feldoffset startet bei `0`.

### Rückgabewerte

Gibt ein Objekt mit Feldinformationen zurück. Die Eigenschaften des Objekts sind:

- name - Spaltenname
- table - der Name der Tabelle, zu der die Spalte gehört, wobei dies der Aliasname ist falls, einer definiert wurde
- max_length - die maximale Länge der Spalte
- not_null - 1, wenn die Spalte nicht `null` sein kann
- primary_key - 1, wenn die Spalte ein Primärschlüssel ist
- unique_key - 1, wenn die Spalte ein eindeutiger Schlüssel ist
- multiple_key - 1, wenn die Spalte ein nicht eindeutiger Schlüssel ist
- numeric - 1, wenn die Spalte vom Typ 'numeric' ist
- blob - 1, wenn die Saplte vom Typ 'BLOB' ist
- type - der Typ der Spalte
- unsigned - 1, wenn die Spalte vorzeichenlos ist
- zerofill - 1, wenn die Spalte mit Nullen aufgefüllt wird (zero-filled)

### Beispiele

Beispiel #1 mysql_fetch_field()-Beispiel

    <?php
    $conn = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$conn) {
        die('Keine Verbindung möglich: ' . mysql_error());
    }
    mysql_select_db('database');
    $result = mysql_query('select * from table');
    if (!$result) {
        die('Anfrage fehlgeschlagen: ' . mysql_error());
    }
    /* Metadaten der Spalten holen */
    $i = 0;
    while ($i < mysql_num_fields($result)) {
        echo "Informationen für Spalte $i:<br />\n";
        $meta = mysql_fetch_field($result, $i);
        if (!$meta) {
            echo "Keine Informationen vorhanden<br />\n";
        }
        echo "<pre>
    blob:         $meta->blob
    max_length:   $meta->max_length
    multiple_key: $meta->multiple_key
    name:         $meta->name
    not_null:     $meta->not_null
    numeric:      $meta->numeric
    primary_key:  $meta->primary_key
    table:        $meta->table
    type:         $meta->type
    unique_key:   $meta->unique_key
    unsigned:     $meta->unsigned
    zerofill:     $meta->zerofill
    </pre>";
        $i++;
    }
    mysql_free_result($result);
    ?>

### Anmerkungen

> Hinweis: Bei den Spaltennamen, die von dieser Funktion zurückgegeben werden, wird zwischen Groß- und Kleinschreibung unterschieden.

> Hinweis: Falls Feld- oder Tabellennamen in der SQL-Abfrage mit einem Alias versehen wurden, so wird dieser zurückgegeben. Der ursprüngliche Name kann beispielsweise durch die Verwendung von mysqli_result::fetch_field() in Erfahrung gebracht werden.

### Siehe auch

- mysql_field_seek() - Setzt den Ergebniszeiger auf einen bestimmten Feldoffset

# mysql_fetch_lengths

(PHP 4, PHP 5)

mysql_fetch_lengths — Liefert die Längen aller Felder aus einem Ergebnis

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_lengths()
- PDOStatement::getColumnMeta()

### Beschreibung

function mysql_fetch_lengths(resource `$result`): array|false

Gibt ein Array zurück, das die Länge eines jeden Feldes in dem zuletzt von MySQL geholten Datensatz enthält.

mysql_fetch_lengths() speichert die Länge jeder Ergebnisspalte in der letzten Ergebniszeile, erhalten von mysql_fetch_row(), mysql_fetch_assoc(), mysql_fetch_array() und mysql_fetch_object() in einem Array, dessen Offset bei 0 beginnt.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

### Rückgabewerte

Gibt bei Erfolg ein array mit Längenwerten zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Ein mysql_fetch_lengths()-Beispiel

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Konnte die Abfrage nicht ausführen: ' . mysql_error();
        exit;
    }
    $row     = mysql_fetch_assoc($result);
    $lengths = mysql_fetch_lengths($result);

    print_r($row);
    print_r($lengths);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [id] => 42
        [email] => user@example.com
    )
    Array
    (
        [0] => 2
        [1] => 16
    )

### Siehe auch

- mysql_field_len() - Liefert die Länge des angegebenen Feldes
- mysql_fetch_row() - Liefert einen Datensatz als indiziertes Array
- strlen() - Ermitteln der String-Länge

# mysql_fetch_object

(PHP 4, PHP 5)

mysql_fetch_object — Liefert eine Ergebniszeile als Objekt

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_object()
- PDOStatement::fetch() mit `PDO::FETCH_OBJ` als `mode`

### Beschreibung

function mysql_fetch_object(resource `$result`, string `$class_name` = ?, array `$params` = ?): object

Gibt ein Objekt mit Eigenschaften zurück, die mit der angeforderten Zeile korrespondieren, und bewegt den internen Datenzeiger vorwärts.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`class_name`
  Der Name der Klasse, die instanziiert, mit Eigenschaften versehen und zurückgegeben werden soll. Wenn nicht angegeben, wird ein stdClass-Objekt zurückgegeben.
`params`
  Ein optionales Array von Parametern, die dem Konstruktor von `class_name`-Objekten übergeben werden sollen.

### Rückgabewerte

Gibt ein Objekt mit Eigenschaften zurück, die mit der angeforderten Zeile korrespondieren, oder `false` wenn es keine weiteren Zeilen mehr gibt.

### Beispiele

Beispiel #1 mysql_fetch_object()-Beispiel

    <?php
    mysql_connect("hostname", "benutzer", "passwort");
    mysql_select_db("meinedatenbank");
    $result = mysql_query("select * from meinetabelle");
    while ($row = mysql_fetch_object($result)) {
        echo $row->user_id;
        echo $row->vollername;
    }
    mysql_free_result($result);
    ?>

Beispiel #2 mysql_fetch_object()-Beispiel

    <?php
    class foo {
        public $name;
    }

    mysql_connect("hostname", "benutzer", "passwort");
    mysql_select_db("meinedatenbank");

    $result = mysql_query("select name from meinetabelle limit 1");
    $obj = mysql_fetch_object($result, 'foo');
    var_dump($obj);
    ?>

### Anmerkungen

> Hinweis: Performanz
> Unter Berücksichtigung der Ausführungsgeschwindigkeit ist diese Funktion identisch zu mysql_fetch_array() und fast so schnell wie mysql_fetch_row() (der Unterschied ist unwesentlich).

> Hinweis: mysql_fetch_object() ist vergleichbar mit mysql_fetch_array(), mit dem Unterschied, dass ein Objekt statt eines Arrays zurückgegeben wird. Indirekt bedeutet das, dass Sie auf die Daten nur über die Feldnamen zugreifen können und nicht über die Offsets (da Zahlen keine erlaubten Namen für Eigenschaften sind).

> Hinweis: Bei den Spaltennamen, die von dieser Funktion zurückgegeben werden, wird zwischen Groß- und Kleinschreibung unterschieden.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Siehe auch

- mysql_fetch_array() - Liefert einen Datensatz als assoziatives Array, als numerisches Array oder beides
- mysql_fetch_assoc() - Liefert einen Datensatz als assoziatives Array
- mysql_fetch_row() - Liefert einen Datensatz als indiziertes Array
- mysql_data_seek() - Bewegt den internen Ergebnis-Zeiger
- mysql_query() - Sendet eine Abfrage an MySQL

# mysql_fetch_row

(PHP 4, PHP 5)

mysql_fetch_row — Liefert einen Datensatz als indiziertes Array

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_row()
- PDOStatement::fetch() mit `PDO::FETCH_NUM` als `mode`

### Beschreibung

function mysql_fetch_row(resource `$result`): array

Gibt ein numerisch indizertes Array zurück, das dem geholten Datensatz entspricht, und bewegt den internen Datensatzzeiger vorwärts.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

### Rückgabewerte

Gibt ein numerisches Array von Zeichenketten zurück, das dem gelesenen Datensatz entspricht, oder `false`, falls keine weiteren Zeilen vorhanden sind.

mysql_fetch_row() gibt einen Datensatz aus dem Abfrageergebnis mit der übergebenen Kennung zurück. Der Datensatz wird als Array zurückgegeben. Jedes Feld wird in einem Array-Offset abgelegt, der bei Offset 0 beginnt.

### Beispiele

Beispiel #1 Einen Datensatz mit mysql_fetch_row() holen

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Konnte Abfrage nicht ausführen: ' . mysql_error();
        exit;
    }
    $row = mysql_fetch_row($result);

    echo $row[0]; // 42
    echo $row[1]; // der email-Wert
    ?>

### Anmerkungen

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Siehe auch

- mysql_fetch_array() - Liefert einen Datensatz als assoziatives Array, als numerisches Array oder beides
- mysql_fetch_assoc() - Liefert einen Datensatz als assoziatives Array
- mysql_fetch_object() - Liefert eine Ergebniszeile als Objekt
- mysql_data_seek() - Bewegt den internen Ergebnis-Zeiger
- mysql_fetch_lengths() - Liefert die Längen aller Felder aus einem Ergebnis
- mysql_result() - Liefert eine Spalte aus einem MySQL-Ergebnis

# mysql_field_flags

(PHP 4, PHP 5)

mysql_field_flags — Liefert die Flags des angegebenen Feldes aus einem Abfrageergebnis

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_field_direct() [flags]
- PDOStatement::getColumnMeta() [flags]

### Beschreibung

function mysql_field_flags(resource `$result`, int `$field_offset`): string|false

mysql_field_flags() gibt die Flags des Feldes am übergebenen Offset zurück. Die Flags werden als einzelne Worte pro Flag und durch ein einziges Leerzeichen getrennt zurückgegeben, sodass sie einfach mit explode() getrennt werden können.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`field_offset`

  Der numerische Offset des Feldes. Der `field_offset` beginnt bei `0`. Falls `field_offset` nicht existiert, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt eine Zeichenkette aus Flags zurück, die mit dem Ergebnis assoziiert sind. Bei einem Fehler wird `false` zurückgegeben.

Die folgenden Flags werden zurückgegeben, wenn Ihre Version von MySQL aktuell genug ist, diese zu unterstützen: `"not_null"`, `"primary_key"`, `"unique_key"`, `"multiple_key"`, `"blob"`, `"unsigned"`, `"zerofill"`, `"binary"`, `"enum"`, `"auto_increment"` und `"timestamp"`.

### Beispiele

Beispiel #1 Ein mysql_field_flags()-Beispiel

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Konnte die Abfrage nicht ausführen: ' . mysql_error();
        exit;
    }
    $flags = mysql_field_flags($result, 0);

    echo $flags;
    print_r(explode(' ', $flags));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    not_null primary_key auto_increment
    Array
    (
        [0] => not_null
        [1] => primary_key
        [2] => auto_increment
    )

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_fieldflags()

### Siehe auch

- mysql_field_type() - Liefert den Typ des spezifizierten Feldes aus einem Ergebnis
- mysql_field_len() - Liefert die Länge des angegebenen Feldes

# mysql_field_len

(PHP 4, PHP 5)

mysql_field_len — Liefert die Länge des angegebenen Feldes

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_field_direct() [length]
- PDOStatement::getColumnMeta() [len]

### Beschreibung

function mysql_field_len(resource `$result`, int `$field_offset`): int|false

mysql_field_len() gibt die Länge des angegebenen Feldes zurück.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`field_offset`

  Der numerische Offset des Feldes. Der `field_offset` beginnt bei `0`. Falls `field_offset` nicht existiert, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt die Länge des Feldes zurück, das dem übergebenen Index entspricht. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_field_len()-Beispiel

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Konnte die Abfrage nicht ausführen: ' . mysql_error();
        exit;
    }

    // Gibt die Länge der Spalte id zurück, wie im Datenbankschema definiert
    $length = mysql_field_len($result, 0);
    echo $length;
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_fieldlen()

### Siehe auch

- mysql_fetch_lengths() - Liefert die Längen aller Felder aus einem Ergebnis
- strlen() - Ermitteln der String-Länge

# mysql_field_name

(PHP 4, PHP 5)

mysql_field_name — Liefert den Namen des angegebenen Feldes aus einem Ergebnis

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_field_direct() [name] oder [orgname]
- PDOStatement::getColumnMeta() [name]

### Beschreibung

function mysql_field_name(resource `$result`, int `$field_offset`): string|false

mysql_field_name() gibt den Namen des Feldes zurück, das dem angegeben Feldindex entspricht.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`field_offset`

  Der numerische Offset des Feldes. Der `field_offset` beginnt bei `0`. Falls `field_offset` nicht existiert, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt den Namen des Feldes zurück, das dem übergebenen Index entspricht. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_field_name()-Beispiel

    <?php
    /* Die Benutzertabelle besteht aus 3 Feldern
     *   user_id
     *   username
     *   password.
     */
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Keine Verbindung zum MySQL-Server: ' . mysql_error());
    }
    $dbname = 'mydb';
    $db_selected = mysql_select_db($dbname, $link);
    if (!$db_selected) {
        die("Konnte $dbname nicht auswählen: " . mysql_error());
    }
    $res = mysql_query('select * from users', $link);

    echo mysql_field_name($res, 0) . "\n";
    echo mysql_field_name($res, 2);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    user_id
    password

### Anmerkungen

> Hinweis: Bei den Spaltennamen, die von dieser Funktion zurückgegeben werden, wird zwischen Groß- und Kleinschreibung unterschieden.

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_fieldname()

### Siehe auch

- mysql_field_type() - Liefert den Typ des spezifizierten Feldes aus einem Ergebnis
- mysql_field_len() - Liefert die Länge des angegebenen Feldes

# mysql_field_seek

(PHP 4, PHP 5)

mysql_field_seek — Setzt den Ergebniszeiger auf einen bestimmten Feldoffset

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_field_seek()
- PDOStatement::fetch() unter Verwendung der Parameter `cursor_orientation` und `offset`

### Beschreibung

function mysql_field_seek(resource `$result`, int `$field_offset`): bool

Setzt den Feldzeiger auf den angegeben Feldoffset. Wird beim nächsten Aufruf von mysql_fetch_field() kein Feldoffset übergeben, wird der Feldoffset zurückgegeben, der bei mysql_field_seek() angegeben wurde.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`field_offset`

  Der numerische Offset des Feldes. Der `field_offset` beginnt bei `0`. Falls `field_offset` nicht existiert, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- mysql_fetch_field() - Liefert ein Objekt mit Spalteninformationen aus einem Abfrageergebnis

# mysql_field_table

(PHP 4, PHP 5)

mysql_field_table — Liefert den Namen der Tabelle, die das genannte Feld enthält

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_field_direct() [table] oder [orgtable]
- PDOStatement::getColumnMeta() [table]

### Beschreibung

function mysql_field_table(resource `$result`, int `$field_offset`): string

Gibt den Namen der Tabelle zurück, die das genannte Feld enthält.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`field_offset`

  Der numerische Offset des Feldes. Der `field_offset` beginnt bei `0`. Falls `field_offset` nicht existiert, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg den Namen der Tabelle zurück.

### Beispiele

Beispiel #1 Ein mysql_field_table()-Beispiel

    <?php

    $query = "SELECT account.*, country.* FROM account, country WHERE country.name = 'Portugal' AND account.country_id = country.id";

    // Erhalte Resultat von der DB
    $result = mysql_query($query);

    // Listet den Tabellennamen und danach den Spaltennamen auf
    for ($i = 0; $i < mysql_num_fields($result); ++$i) {
        $table = mysql_field_table($result, $i);
        $field = mysql_field_name($result, $i);

        echo  "$table: $field\n";
    }

    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_fieldtable()

### Siehe auch

- mysql_list_tables() - Listet Tabellen einer MySQL-Datenbank auf

# mysql_field_type

(PHP 4, PHP 5)

mysql_field_type — Liefert den Typ des spezifizierten Feldes aus einem Ergebnis

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_fetch_field_direct() [type]
- PDOStatement::getColumnMeta() [driver:decl_type] or [pdo_type]

### Beschreibung

function mysql_field_type(resource `$result`, int `$field_offset`): string

mysql_field_type() ist ähnlich wie die Funktion mysql_field_name(). Die Argumente sind identisch, aber stattdessen wird der Typ des Feldes zurückgegeben.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`field_offset`

  Der numerische Offset des Feldes. Der `field_offset` beginnt bei `0`. Falls `field_offset` nicht existiert, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Der zurückgegebene Feldtyp ist einer von `"int"`, `"real"`, `"string"`, `"blob"` und anderen, wie in der » MySQL-Dokumentation weiter ausgeführt.

### Beispiele

Beispiel #1 mysql_field_type()-Beispiel

    <?php
    mysql_connect("localhost", "mysql_username", "mysql_password");
    mysql_select_db("mysql");
    $result = mysql_query("SELECT * FROM func");
    $fields = mysql_num_fields($result);
    $rows   = mysql_num_rows($result);
    $table  = mysql_field_table($result, 0);
    echo "Die '" . $table . "' Tabelle hat " . $fields . " Felder und " . $rows . " Datensätze\n";
    echo "Die Tabelle hat folgende Felder:\n";
    for ($i=0; $i < $fields; $i++) {
        $type  = mysql_field_type($result, $i);
        $name  = mysql_field_name($result, $i);
        $len   = mysql_field_len($result, $i);
        $flags = mysql_field_flags($result, $i);
        echo $type . " " . $name . " " . $len . " " . $flags . "\n";
    }
    mysql_free_result($result);
    mysql_close();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Die Tabelle 'func' hat 4 Felder und 1 Datensätze
    Die Tabelle hat folgende Felder:
    string name 64 not_null primary_key binary
    int ret 1 not_null
    string dl 128 not_null
    string type 9 not_null enum

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_fieldtype()

### Siehe auch

- mysql_field_name() - Liefert den Namen des angegebenen Feldes aus einem Ergebnis
- mysql_field_len() - Liefert die Länge des angegebenen Feldes

# mysql_free_result

(PHP 4, PHP 5)

mysql_free_result — Gibt belegten Speicher wieder frei

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_free_result()
- Den Wert `null` dem PDO-Objekt zuweisen oder PDOStatement::closeCursor()

### Beschreibung

function mysql_free_result(resource `$result`): bool

mysql_free_result() gibt den Speicher frei, der mit `result` (Ergebniskennung) verknüpft ist.

Die Funktion muss nur dann aufgerufen werden, wenn Sie sich bei Anfragen, die große Ergebnismengen liefern, Sorgen über den Speicherverbrauch zur Laufzeit des PHP-Skripts machen. Nach Ablauf des Skripts wird der Speicher ohnehin freigegeben.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Wird für den Parameter `result` ein Wert angegeben, der nicht vom Typ resource ist, wird ein Fehler der Stufe E_WARNING ausgegeben. Beachten Sie, dass mysql_query() nur eine Ressource für SELECT-, SHOW-, EXPLAIN- und DESCRIBE-Abfragen zurückgibt.

### Beispiele

Beispiel #1 Ein mysql_free_result()-Beispiel

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Abfrage konnte nicht ausgeführt werden: ' . mysql_error();
        exit;
    }
    /* Verwende result, unter der Annahme wir sind hinterher damit fertig */
    $row = mysql_fetch_assoc($result);

    /* Nun geben wir den Speicher für result frei und fahren in unserem Skript fort */
    mysql_free_result($result);

    echo $row['id'];
    echo $row['email'];
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_freeresult()

### Siehe auch

- mysql_query() - Sendet eine Abfrage an MySQL
- is_resource() - Prüft, ob eine Variable vom Typ resource ist

# mysql_get_client_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_client_info — Liefert MySQL-Clientinformationen

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_get_client_info()
- PDOStatement::getAttribute() mit `PDO::ATTR_CLIENT_VERSION` als `attribute`

### Beschreibung

function mysql_get_client_info(): string

mysql_get_client_info() gibt eine Zeichenkette mit der Version der Client-Bibliothek zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Version der MySQL-Client-Bibliothek zurück.

### Beispiele

Beispiel #1 mysql_get_client_info()-Beispiel

    <?php
    printf("MySQL-Client-Info: %s\n", mysql_get_client_info());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    MySQL-Client-Info: 3.23.39

### Siehe auch

- mysql_get_host_info() - Liefert Informationen zum MySQL-Host
- mysql_get_proto_info() - Liefert MySQL-Protokollinformationen
- mysql_get_server_info() - Liefert Informationen zum MySQL-Server

# mysql_get_host_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_host_info — Liefert Informationen zum MySQL-Host

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_get_host_info()
- PDOStatement::getAttribute() mit `PDO::ATTR_CONNECTION_STATUS` als `attribute`

### Beschreibung

function mysql_get_host_info(resource `$link_identifier` = NULL): string|false

Beschreibt den Typ der aktuell verwendeten Verbindung inklusive dem Hostnamen des Servers.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt eine Zeichenkette zurück, die den Typ der aktuell verwendeten MySQL-Verbindung beschreibt. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_get_host_info()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Keine Verbindung möglich: ' . mysql_error());
    }
    printf("MySQL-Host-Info: %s\n", mysql_get_host_info());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    MySQL-Host-Info: Localhost via UNIX socket

### Siehe auch

- mysql_get_client_info() - Liefert MySQL-Clientinformationen
- mysql_get_proto_info() - Liefert MySQL-Protokollinformationen
- mysql_get_server_info() - Liefert Informationen zum MySQL-Server

# mysql_get_proto_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_proto_info — Liefert MySQL-Protokollinformationen

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_get_proto_info()

### Beschreibung

function mysql_get_proto_info(resource `$link_identifier` = NULL): int|false

Liefert die MySQL-Protokollversion.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg die Version des MySQL-Protokolls zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_get_proto_info()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Keine Verbindung möglich: ' . mysql_error());
    }
    printf("Die MySQL-Protokollversion: %s\n", mysql_get_proto_info());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Die MySQL-Protokollversion: 10

### Siehe auch

- mysql_get_client_info() - Liefert MySQL-Clientinformationen
- mysql_get_host_info() - Liefert Informationen zum MySQL-Host
- mysql_get_server_info() - Liefert Informationen zum MySQL-Server

# mysql_get_server_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_server_info — Liefert Informationen zum MySQL-Server

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_get_server_info()
- PDOStatement::getAttribute() mit `PDO::ATTR_SERVER_VERSION` als `attribute`

### Beschreibung

function mysql_get_server_info(resource `$link_identifier` = NULL): string|false

Gibt die Version des MySQL-Servers zurück.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg die Version des MySQL-Servers zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_get_server_info()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Keine Verbindung möglich: ' . mysql_error());
    }
    printf("Die MySQL-Server-Version: %s\n", mysql_get_server_info());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Die MySQL-Server Version: 4.0.1-alpha

### Siehe auch

- mysql_get_client_info() - Liefert MySQL-Clientinformationen
- mysql_get_host_info() - Liefert Informationen zum MySQL-Host
- mysql_get_proto_info() - Liefert MySQL-Protokollinformationen
- phpversion() - Liefert die aktuelle PHP-Version

# mysql_info

(PHP 4 >= 4.3.0, PHP 5)

mysql_info — Liefert Informationen über die zuletzt ausgeführte Anfrage

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_info()

### Beschreibung

function mysql_info(resource `$link_identifier` = NULL): string

Gibt ausführliche Informationen zur letzten Abfrage zurück.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg Informationen über die Anweisung zurück oder `false` bei einem Fehler. Im Beispiel unten sehen Sie, welche Anweisungen Informationen liefern, und wie der zurückgegebene Wert aussehen kann. Anweisungen, die nicht aufgeführt sind, geben `false` zurück.

### Beispiele

Beispiel #1 Relevante MySQL-Anweisungen

Anweisungen, die Zeichenketten zurückgeben. Die Nummern dienen nur zur Illustration; die tatsächlichen Werte entsprechen der jeweiligen Abfrage.

    INSERT INTO ... SELECT ...
    String format: Records: 23 Duplicates: 0 Warnings: 0
    INSERT INTO ... VALUES (...),(...),(...)...
    String format: Records: 37 Duplicates: 0 Warnings: 0
    LOAD DATA INFILE ...
    String format: Records: 42 Deleted: 0 Skipped: 0 Warnings: 0
    ALTER TABLE
    String format: Records: 60 Duplicates: 0 Warnings: 0
    UPDATE
    String format: Rows matched: 65 Changed: 65 Warnings: 0

### Anmerkungen

> Hinweis: mysql_info() liefert bei INSERT...VALUES-Befehlen nur dann einen gültigen (nicht-`false`) Wert, wenn mehrfache Werte angegeben wurden.

### Siehe auch

- mysql_affected_rows() - Liefert die Anzahl betroffener Datensätze einer vorhergehenden MySQL-Operation
- mysql_insert_id() - Liefert die ID, die in der vorherigen Abfrage erzeugt wurde
- mysql_stat() - Zeigt den momentanen Serverstatus an

# mysql_insert_id

(PHP 4, PHP 5)

mysql_insert_id — Liefert die ID, die in der vorherigen Abfrage erzeugt wurde

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_insert_id()
- PDO::lastInsertId()

### Beschreibung

function mysql_insert_id(resource `$link_identifier` = NULL): int

Gibt die ID zurück, die für eine AUTO_INCREMENT-Spalte durch die vorherige Abfrage (meist INSERT) erzeugt wurde.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg die ID zurück, die durch die vorherige Abfrage für eine AUTO_INCREMENT-Spalte erzeugt wurde, `0`, falls die vorherige Abfrage keinen AUTO_INCREMENT Wert erzeugt hatte, oder `false`, falls keine MySQL-Verbindung existierte.

### Beispiele

Beispiel #1 mysql_insert_id()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Keine Verbindung möglich: ' . mysql_error());
    }
    mysql_select_db('mydb');

    mysql_query("INSERT INTO mytable (product) values ('kossu')");
    printf("Der letze eingefügte Datensatz hat die ID %d\n", mysql_insert_id());
    ?>

### Anmerkungen

Achtung

mysql_insert_id() konvertiert den Typ der Rückgabe der nativen MySQL C API-Funktion `mysql_insert_id()` in den Typ `long` (in PHP als int bezeichnet). Falls Ihre AUTO_INCREMENT-Spalte vom Typ BIGINT (64 Bit) ist, ist der Wert, den mysql_insert_id() zurückgibt, nicht korrekt. Verwenden Sie in einer SQL-Abfrage in diesem Fall stattdessen die MySQL-interne SQL-Funktion `LAST_INSERT_ID()`. Für weitergehende Informationen bezüglich PHPs maximaler Integer-Werte, lesen Sie bitte die Integer-Dokumenation.

> Hinweis: Da mysql_insert_id() mit der zuletzt durchgeführten Abfrage arbeitet, sollten Sie mysql_insert_id() unmittelbar nach der Abfrage aufrufen, die den Wert erzeugt.

> Hinweis: Der Wert der MySQL-SQL-Funktion `LAST_INSERT_ID()` gibt immer den zuletzt erzeugten AUTO_INCREMENT-Wert zurück. Dieser wird zwischen Abfragen nicht zurückgesetzt.

### Siehe auch

- mysql_query() - Sendet eine Abfrage an MySQL
- mysql_info() - Liefert Informationen über die zuletzt ausgeführte Anfrage

# mysql_list_dbs

(PHP 4, PHP 5)

mysql_list_dbs — Listet die verfügbaren Datenbanken (Schemata) auf einem MySQL-Server auf

Warnung

Diese Funktion wurde in PHP 5.4.0 als veraltet gekennzeichnet und wurde in PHP 7.0.0 zusammen mit der gesamten ursprünglichen MySQL-Erweiterung entfernt. Stattdessen sollten die aktiv entwickelten Erweiterungen MySQLi oder PDO_MySQL verwendet werden. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- SQL Query: `SHOW DATABASES`

### Beschreibung

function mysql_list_dbs(resource `$link_identifier` = NULL): resource

Gibt eine Ergebniskennung zurück, die alle Datenbanken auf dem Datenbank-Server enthält.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg eine Ergebniszeiger-Ressource zurück oder `false` bei einem Fehler. Verwenden sie die Funktion mysql_tablename(), um dieses Ergebnis zu durchlaufen oder irgendeine der Funktionen, die mit Ergebnistabellen umgehen können, wie etwa mysql_fetch_array().

### Beispiele

Beispiel #1 mysql_list_dbs()-Beispiel

    <?php
    // Verwendung ohne mysql_list_dbs()
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $res = mysql_query("SHOW DATABASES");

    while ($row = mysql_fetch_assoc($res)) {
        echo $row['Database'] . "\n";
    }

    // Veraltet seit PHP 5.4.0
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $db_list = mysql_list_dbs($link);

    while ($row = mysql_fetch_object($db_list)) {
         echo $row->Database . "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    database1
    database2
    database3

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_listdbs()

### Siehe auch

- mysql_db_name() - Liefert den Namen einer Datenbank vom mysql_list_dbs-Aufruf
- mysql_select_db() - Wählt eine MySQL-Datenbank aus

# mysql_list_fields

(PHP 4, PHP 5)

mysql_list_fields — Listet MySQL-Tabellenfelder auf

Warnung

Diese Funktion wurde in PHP 5.4.0 als veraltet gekennzeichnet und wurde in PHP 7.0.0 zusammen mit der gesamten ursprünglichen MySQL-Erweiterung entfernt. Stattdessen sollten die aktiv entwickelten Erweiterungen MySQLi oder PDO_MySQL verwendet werden. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- SQL Query: `SHOW COLUMNS FROM tabelle`

### Beschreibung

function mysql_list_fields(string `$database_name`, string `$table_name`, resource `$link_identifier` = NULL): resource

Gibt Informationen über den übergebenen Tabellennamen zurück.

Diese Funktion ist veraltet. Stattdessen ist es vorzuziehen, den SQL-Befehl `SHOW COLUMNS FROM table [LIKE 'name']` mit der Funktion mysql_query() auszuführen.

### Parameter-Liste

`database_name`
  Der Name der abgefragten Datenbank.
`table_name`
  Der Name der abgefragten Tabelle.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg eine Ergebniszeiger-Ressource zurück oder `false` bei einem Fehler.

Das zurückgegebene Resultat kann mit mysql_field_flags(), mysql_field_len(), mysql_field_name() und mysql_field_type() verwendet werden,

### Beispiele

Beispiel #1 Alternative zum veraltetenmysql_list_fields()

    <?php
    $result = mysql_query("SHOW COLUMNS FROM sometable");
    if (!$result) {
        echo 'Konnte Abfrage nicht ausführen: ' . mysql_error();
        exit;
    }
    if (mysql_num_rows($result) > 0) {
        while ($row = mysql_fetch_assoc($result)) {
            print_r($row);
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [Field] => id
        [Type] => int(7)
        [Null] =>
        [Key] => PRI
        [Default] =>
        [Extra] => auto_increment
    )
    Array
    (
        [Field] => email
        [Type] => varchar(100)
        [Null] =>
        [Key] =>
        [Default] =>
        [Extra] =>
    )

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_listfields()

### Siehe auch

- mysql_field_flags() - Liefert die Flags des angegebenen Feldes aus einem Abfrageergebnis
- mysql_info() - Liefert Informationen über die zuletzt ausgeführte Anfrage

# mysql_list_processes

(PHP 4 >= 4.3.0, PHP 5)

mysql_list_processes — Zeigt die MySQL-Prozesse an

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_thread_id()

### Beschreibung

function mysql_list_processes(resource `$link_identifier` = NULL): resource|false

Gibt die aktuellen Prozesse des MySQL-Servers zurück.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg einen Ergebniszeiger vom Typ resource zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_list_processes()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');

    $result = mysql_list_processes($link);
    while ($row = mysql_fetch_assoc($result)){
        printf("%s %s %s %s %s\n", $row["Id"], $row["Host"], $row["db"],
            $row["Command"], $row["Time"]);
    }
    mysql_free_result($result);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1 localhost test Processlist 0
    4 localhost mysql sleep 5

### Siehe auch

- mysql_thread_id() - Zeigt die aktuelle Thread-ID an
- mysql_stat() - Zeigt den momentanen Serverstatus an

# mysql_list_tables

(PHP 4, PHP 5)

mysql_list_tables — Listet Tabellen einer MySQL-Datenbank auf

Warnung

Diese Funktion wurde in PHP 4.3.0 als veraltet gekennzeichnet und wurde in PHP 7.0.0 zusammen mit der gesamten ursprünglichen MySQL-Erweiterung entfernt. Stattdessen sollten die aktiv entwickelten Erweiterungen MySQLi oder PDO_MySQL verwendet werden. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- SQL-Abfrage: `SHOW TABLES FROM dbname`

### Beschreibung

function mysql_list_tables(string `$database`, resource `$link_identifier` = NULL): resource|false

Gibt eine Liste der Tabellennamen einer MySQL-Datenbank zurück.

Diese Funktion ist veraltet. Stattdessen ist es vorzuziehen, mysql_query() mit dem SQL-Befehl `SHOW TABLES [FROM db_name] [LIKE 'pattern']` zu verwenden.

### Parameter-Liste

`database`
  Der Name der Datenbank.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg einen Ergebniszeiger vom Typ resource zurück. Bei einem Fehler wird `false` zurückgegeben.

Verwenden sie die Funktion mysql_tablename(), um dieses Resultat zu durchlaufen oder irgendeine andere Funktion, die mit Ergebnistabellen umgehen kann, wie zum Beispiel mysql_fetch_array().

### Beispiele

Beispiel #1 mysql_list_tables()-Alternativbeispiel

    <?php
    $dbname = 'mysql_dbname';

    if (!mysql_connect('mysql_host', 'mysql_user', 'mysql_password')) {
        echo 'Konnte nicht mit mysql verbinden';
        exit;
    }

    $sql = "SHOW TABLES FROM $dbname";
    $result = mysql_query($sql);

    if (!$result) {
        echo "DB-Fehler, konnte die Tabellen nicht auflisten\n";
        echo 'MySQL-Fehler: ' . mysql_error();
        exit;
    }

    while ($row = mysql_fetch_row($result)) {
        echo "Tabelle: {$row[0]}\n";
    }

    mysql_free_result($result);
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_listtables()

### Siehe auch

- mysql_list_dbs() - Listet die verfügbaren Datenbanken (Schemata) auf einem MySQL-Server auf
- mysql_tablename() - Liefert den Namen einer Tabelle

# mysql_num_fields

(PHP 4, PHP 5)

mysql_num_fields — Liefert die Anzahl der Felder in einem Ergebnis

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_num_fields()
- PDOStatement::columnCount()

### Beschreibung

function mysql_num_fields(resource `$result`): int|false

Gibt die Anzahl der Felder in einem Abfrageergebnis zurück.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

### Rückgabewerte

Gibt bei Erfolg die Anzahl der Felder in der Ergebnisressource zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Ein mysql_num_fields()-Beispiel

    <?php
    $result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
    if (!$result) {
        echo 'Konnte die Abfrage nicht ausführen: ' . mysql_error();
        exit;
    }

    /* Gibt 2 zurück, da id,email === zwei Felder */
    echo mysql_num_fields($result);
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_numfields()

### Siehe auch

- mysql_select_db() - Wählt eine MySQL-Datenbank aus
- mysql_query() - Sendet eine Abfrage an MySQL
- mysql_fetch_field() - Liefert ein Objekt mit Spalteninformationen aus einem Abfrageergebnis
- mysql_num_rows() - Liefert die Anzahl der Zeilen in einem Ergebnis

# mysql_num_rows

(PHP 4, PHP 5)

mysql_num_rows — Liefert die Anzahl der Zeilen in einem Ergebnis

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_num_rows()
- mysqli_stmt_num_rows()
- PDOStatement::rowCount()

### Beschreibung

function mysql_num_rows(resource `$result`): int|false

Gibt die Anzahl der Zeilen einer Ergebnismenge zurück. Diese Funktion ist nur gültig für Befehle wie SELECT oder SHOW, die eine tatsächliche Ergebnismenge zurückgeben. Haben Sie eine INSERT-, UPDATE- oder DELETE-Abfrage ausgeführt und möchten die Anzahl der betroffenen Datensätze ermitteln, verwenden Sie die Funktion mysql_affected_rows().

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

### Rückgabewerte

Gibt bei Erfolg die Anzahl der Zeilen in einer Ergebnismenge zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_num_rows()-Beispiel

    <?php

    $link = mysql_connect("localhost", "mysql_user", "mysql_password");
    mysql_select_db("database", $link);

    $result = mysql_query("SELECT * FROM table1", $link);
    $num_rows = mysql_num_rows($result);

    echo "$num_rows Zeilen\n";

    ?>

### Anmerkungen

> Hinweis: Wenn Sie mysql_unbuffered_query() verwenden, gibt mysql_num_rows() solange nicht den korrekten Wert zurück, bis Sie alle Zeilen der Ergebnismenge erhalten haben.

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_numrows()

### Siehe auch

- mysql_affected_rows() - Liefert die Anzahl betroffener Datensätze einer vorhergehenden MySQL-Operation
- mysql_connect() - Öffnet eine Verbindung zu einem MySQL-Server
- mysql_data_seek() - Bewegt den internen Ergebnis-Zeiger
- mysql_select_db() - Wählt eine MySQL-Datenbank aus
- mysql_query() - Sendet eine Abfrage an MySQL

# mysql_pconnect

(PHP 4, PHP 5)

mysql_pconnect — Öffnet eine persistente Verbindung zum MySQL-Server

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_connect() mit `p:` Host-Präfix
- PDO::__construct() mit `PDO::ATTR_PERSISTENT` als Treiberoption

### Beschreibung

function mysql_pconnect(
string `$server` = ini_get("mysql.default_host"),
string `$username` = ini_get("mysql.default_user"),
string `$password` = ini_get("mysql.default_password"),
int `$client_flags` = 0
): resource

Baut eine persistente Verbindung zu einem MySQL-Server auf.

mysql_pconnect() verhält sich weitgehend wie mysql_connect() mit zwei großen Unterschieden.

Erstens: Vor dem Verbindungsaufbau wird zunächst versucht eine offene (persistente) Verbindung zum gleichen Host, mit dem gleichen Benutzernamen und Benutzerkennwort zu finden. Wenn das gelingt, wird die Verbindungskennung dieser Verbindung zurückgegeben statt eine neue Verbindung aufzubauen.

Zweitens: Die Verbindung zum SQL-Server wird beim Beenden des PHP-Skripts nicht geschlossen. Sie bleibt zur zukünftigen Verwendung bestehen. (mysql_close() schließt keine von mysql_pconnect() geöffneten Verbindungen).

Deshalb wird dieser Verbindungstyp "persistent" genannt.

### Parameter-Liste

`server`
  Der MySQL-Server. Er kann zudem eine Portnummer enthalten, z. B. "hostname:port" oder den Pfad zu einem lokalen Socket z. B. ":/pfad/zum/socket" für Zugriffe auf dem lokalen Rechner (localhost). Wenn die PHP-Direktive mysql.default_host nicht definiert ist (Standard), ist der Vorgabewert "localhost:3306".
`username`
  Der Benutzername. Der Standardwert ist der Name des Benutzers, dem der Prozess gehört.
`password`
  Das Passwort. Der Standardwert ist ein leeres Passwort.
`client_flags`
  Der Parameter `client_flags` kann eine Kombination der folgenden Konstanten sein: 128 (aktiviert die Verwendung von `LOAD DATA LOCAL`), `MYSQL_CLIENT_SSL`, `MYSQL_CLIENT_COMPRESS`, `MYSQL_CLIENT_IGNORE_SPACE` und `MYSQL_CLIENT_INTERACTIVE`.

### Rückgabewerte

Gibt im Erfolgsfall eine persitente MySQL-Verbindungskennung zurück. Bei einem Fehler wird `false` zurückgegeben.

### Anmerkungen

> Hinweis: Beachten Sie, dass diese Art der Verbindung nur funktioniert. wenn Sie PHP als Modul-Version verwenden. Für mehr Informationen schauen Sie unter Persistente Datenbankverbindungen nach.

Warnung

Die Verwendung von persistenten Verbindungen verlangt unter Umständen eine feinere Abstimmung der Konfiguration von Apache und MySQL. Dadurch sollten Sie sicherstellen, dass Sie die Anzahl der Verbindungen, die MySQL maximal erlaubt, nicht überschreiten.

### Siehe auch

- mysql_connect() - Öffnet eine Verbindung zu einem MySQL-Server
- Persistente Datenbankverbindungen

# mysql_ping

(PHP 4 >= 4.3.0, PHP 5)

mysql_ping — Pingt eine Serververbindung an und verbindet erneut, wenn keine Verbindung besteht

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_ping()

### Beschreibung

function mysql_ping(resource `$link_identifier` = NULL): bool

Überprüft, ob die Verbindung zum Server funktioniert oder nicht. Ist die Verbindung abgebrochen, wird ein automatischer Reconnect versucht. Diese Funktion können Sie in PHP-Skripts verwenden, die längere Zeit untätig bleiben, um zu prüfen, ob der Server die Verbindung abgebaut hat oder nicht, und im Bedarfsfall wird versucht, die Verbindung wieder herzustellen. Rückgabewert: mysql_ping() gibt `true` zurück, wenn die Verbindung zum Server funktioniert, ansonsten `false`.

> Hinweis: Die automatische Wiederherstellung der Verbindung ist standardmäßig in MySQL >= 5.0.3 deaktiviert.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt `true` zurück, wenn die Verbindung zum MySQL-Server noch besteht, ansonsten `false`.

### Beispiele

Beispiel #1 mysql_ping()-Beispiel

    <?php
    set_time_limit(0);

    $conn = mysql_connect('localhost', 'mysqluser', 'mypass');
    $db   = mysql_select_db('mydb');

    /* Annahme: diese Abfrage dauert sehr lange */
    $result = mysql_query($sql);
    if (!$result) {
        echo 'Abfrage #1 fehlgeschlagen, aussteigen.';
        exit;
    }

    /*
    Sicherstellen, dass die Verbindung immer noch besteht, falls nicht,
    versuchen diese wieder aufzubauen
    */
    if (!mysql_ping($conn)) {
        echo 'Verbindung verloren, Ausstieg nach Abfrage #1';
        exit;
    }
    mysql_free_result($result);

    /* Verbindung besteht noch, absetzen eine einer weiteren Abfrage */
    $result2 = mysql_query($sql2);
    ?>

### Siehe auch

- mysql_thread_id() - Zeigt die aktuelle Thread-ID an
- mysql_list_processes() - Zeigt die MySQL-Prozesse an

# mysql_query

(PHP 4, PHP 5)

mysql_query — Sendet eine Abfrage an MySQL

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_query()
- PDO::query()

### Beschreibung

function mysql_query(string `$query`, resource `$link_identifier` = NULL): mixed

mysql_query() sendet eine einzelne Abfrage (mehrere Abfragen werden nicht unterstützt) zur momentan aktiven Datenbank auf dem Server, die mit der übergebenen Verbindungskennung `link_identifier` verknüpft ist.

### Parameter-Liste

`query`
  Eine SQL-Anweisung. Die Anweisung sollte nicht mit einem Semikolon abgeschlossen werden. Werte innerhalb der Abfrage sollten korrekt maskiert werden.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Für SELECT, SHOW, DESCRIBE, EXPLAIN und andere Anweisungen, die eine Ergebnismenge zurückgeben, gibt mysql_query() bei Erfolg eine Ressource zurück, oder `false` bei einem Fehler.

Für alle anderen von SQL-Anweisungen wie INSERT, UPDATE, DELETE, DROP, etc, gibt mysql_query() bei Erfolg `true` zurück oder `false` bei einem Fehler.

Die zurückgegebene Ergebnisressource sollte an mysql_fetch_array() oder andere Funktionen, die mit Ergebnis Tabellen umgehen, übergeben werden, um auf die erhaltenen Daten zuzugreifen.

Verwenden sie mysql_num_rows() um zu erfahren, wieviele Datensätze für eine SELECT-Anweisung zurückgegeben wurden, oder mysql_affected_rows() um zu erfahren, wieviele Datensätze von einer DELETE-, INSERT-, REPLACE- oder UPDATE-Anweisung betroffen waren.

mysql_query() wird ebenfalls fehlschlagen und `false` zurückgeben, wenn der Benutzer nicht die Rechte hat, auf die Tabellen, die in der Anweisung referenziert wurden, zuzugreifen.

### Beispiele

Beispiel #1 Ungültige Anfrage

Die folgende Abfrage ist syntaktisch falsch, deshalb gibt mysql_query() `false` zurück:

    <?php
    $result = mysql_query('SELECT * WHERE 1=1');
    if (!$result) {
        die('Ungültige Abfrage: ' . mysql_error());
    }

    ?>

Beispiel #2 Gültige Anfrage

Die folgende Abfrage ist gültig, daher gibt mysql_query() eine Ressource zurück.

    <?php
    // Dies könnte z. B. durch einen Benutzer angegeben werden
    $firstname = 'fred';
    $lastname  = 'fox';

    // Formuliere Abfrage
    // Dies ist die beste Art, eine SQL-Abfrage durchzuführen
    // Für weitere Beispiele siehe: mysql_real_escape_string()
    $query = sprintf("SELECT firstname, lastname, address, age FROM friends
        WHERE firstname='%s' AND lastname='%s'",
        mysql_real_escape_string($firstname),
        mysql_real_escape_string($lastname));

    // Führe Abfrage aus
    $result = mysql_query($query);

    // Prüfe Ergebnis
    // Dies zeigt die tatsächliche Abfrage, die an MySQL gesandt wurde und den
    // Fehler. Nützlich bei der Fehlersuche
    if (!$result) {
        $message  = 'Ungültige Abfrage: ' . mysql_error() . "\n";
        $message .= 'Gesamte Abfrage: ' . $query;
        die($message);
    }

    // Verwende Ergebnis
    // Der Versuch $result auszugeben, erlaubt keine Zugriff auf die Informationen
    // der Ressource.
    // Eine der MySQL-result-Funktionen muss verwendet werden
    // Siehe auch: mysql_result(), mysql_fetch_array(), mysql_fetch_row(), etc.
    while ($row = mysql_fetch_assoc($result)) {
        echo $row['firstname'];
        echo $row['lastname'];
        echo $row['address'];
        echo $row['age'];
    }

    // Gebe Ressourcen, die mit der Ergebnismenge assoziiert sind, frei
    // Dies geschieht am Ende eines Skripts automatisch
    mysql_free_result($result);
    ?>

### Siehe auch

- mysql_connect() - Öffnet eine Verbindung zu einem MySQL-Server
- mysql_error() - Liefert den Fehlertext der zuvor ausgeführten MySQL-Operation
- mysql_real_escape_string() - Maskiert spezielle Zeichen innerhalb einer Zeichenkette für die Verwendung in einer SQL-Anweisung
- mysql_result() - Liefert eine Spalte aus einem MySQL-Ergebnis
- mysql_fetch_assoc() - Liefert einen Datensatz als assoziatives Array
- mysql_unbuffered_query() - Sendet eine SQL-Anfrage an MySQL, ohne Ergebniszeilen abzuholen und zu puffern

# mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string — Maskiert spezielle Zeichen innerhalb einer Zeichenkette für die Verwendung in einer SQL-Anweisung

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_real_escape_string()
- PDO::quote()

### Beschreibung

function mysql_real_escape_string(string `$unescaped_string`, resource `$link_identifier` = NULL): string

Maskiert spezielle Zeichen in `unescaped_string` unter Berücksichtigung des aktuellen Zeichensatzes der Verbindung, so dass das Ergebnis ohne Probleme in mysql_query() verwendet werden kann. Wenn Sie Binärdaten einfügen wollen, müssen Sie die Funktion auf jeden Fall verwenden.

mysql_real_escape_string() ruft die Funktion mysql_real_escape_string der MySQL-Bibliothek auf, die folgende Zeichen mit einem Backslash ('\') versieht: `\x00`, `\n`, `\r`, `\`, `'`, `"` und `\x1a`.

Die Funktion muss (mit wenigen Ausnahmen) immer verwendet werden, um Daten abzusichern, bevor sie per Abrage an MySQL übermittelt werden.

Achtung

# Sicherheit: Der Standardzeichensatz

Der Zeichensatz muss entweder auf Ebene des Servers oder mittels der API-Funktion mysql_set_charset() gesetzt werden, damit dieser mysql_real_escape_string() beeinflusst. Siehe das Grundlagenkapitel zum Thema Zeichensätze für mehr Informationen.

### Parameter-Liste

`unescaped_string`
  Die zu maskierende Zeichenkette.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt eine maskierte Zeichenkette zurück oder im Fehlerfall `false`.

### Fehler/Exceptions

Wird diese Funktion ohne MySQL-Verbindung ausgeführt, werden ebenfalls PHP-Fehler der Stufe `E_WARNUNG` ausgelöst. Diese Funktion sollte nur mit einer gültigen MySQL-Verbindung verwendet werden.

### Beispiele

Beispiel #1 Einfaches mysql_real_escape_string()-Beispiel

    <?php
    // Verbindung herstellen
    $link = mysql_connect('mysql_host', 'mysql_user', 'mysql_password')
        OR die(mysql_error());

    // Abfrage erstellen
    $query = sprintf("SELECT * FROM users WHERE user='%s' AND password='%s'",
                mysql_real_escape_string($user),
                mysql_real_escape_string($password));
    ?>

Beispiel #2 mysql_real_escape_string() benötigt eine Verbindung

Diese Beispiel verdeutlicht, was geschieht, wenn beim Aufruf dieser Funktion keine MySQL-Verbindung vorhanden ist.

    <?php
    // Wir sind nicht mit MySQL verbunden

    $lastname  = "O'Reilly";
    $_lastname = mysql_real_escape_string($lastname);

    $query = "SELECT * FROM actors WHERE last_name = '$_lastname'";

    var_dump($_lastname);
    var_dump($query);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Warning: mysql_real_escape_string(): No such file or directory in /this/test/script.php on line 5
    Warning: mysql_real_escape_string(): A link to the server could not be established in /this/test/script.php on line 5

    bool(false)
    string(41) "SELECT * FROM actors WHERE last_name = ''"

Beispiel #3 Ein beispielhafter SQL-Injection-Angriff

    <?php
    // Wir haben $_POST['password'] nicht überprüft, es könnte
    // jeder beliebiger Wert sein, den der Benutzer will!
    $_POST['username'] = 'aidan';
    $_POST['password'] = "' OR ''='";

    // Datenbankabfrage zur Ueberpruefung der Logindaten
    $query = "SELECT * FROM users WHERE user='{$_POST['username']}' AND password='{$_POST['password']}'";
    mysql_query($query);

    // Das bedeutet, der an MySQL gesendete Query wuerde sein:
    echo $query;
    ?>

Die Abfrage, die an MySQL übermittelt wird:

    SELECT * FROM users WHERE user='aidan' AND password='' OR ''=''

Dies würde jedem erlauben, sich ohne valides Passwort einzuloggen.

### Anmerkungen

> Hinweis: Sie müssen eine Verbindung zu MySQL geöffnet haben, bevor Sie mysql_real_escape_string() verwenden, ansonsten erhalten Sie einen Fehler vom Typ `E_WARNING` und der Rückgabewert wird zu `false`. Ist `link_identifier` nicht angegeben, wird die letzte MySQL-Verbindung verwendet.

> Hinweis: Wenn die Funktion nicht verwendet wird, um die Daten zu maskieren, ist die Abfrage anfällig für SQL-Injection-Angriffe.

> Hinweis: mysql_real_escape_string() maskiert weder `%` noch `_`. Diese Zeichen werden in MySQL als Platzhalter interpretiert, wenn sie mit `LIKE`, `GRANT` oder `REVOKE` kombiniert werden.

### Siehe auch

- mysql_set_charset() - Setzt den Verbindungszeichensatz
- mysql_client_encoding() - Liefert den Namen des Zeichensatzes

# mysql_result

(PHP 4, PHP 5)

mysql_result — Liefert eine Spalte aus einem MySQL-Ergebnis

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_data_seek() zusammen mit mysqli_field_seek() und mysqli_fetch_field()
- PDOStatement::fetchColumn()

### Beschreibung

function mysql_result(resource `$result`, int `$row`, mixed `$field` = 0): string

Gibt den Inhalt einer Spalte aus einer MySQL-Ergebnismenge zurück.

Wenn auf Abfrageergebnisse mit vielen Datensätzen zugegriffen werden soll, sollten Sie Funktionen in Betracht ziehen, die auf ganze Datensätze zugreifen (siehe unten). Diese Funktionen liefern bei einem einzigen Aufruf den Inhalt mehrerer Spalten und sind aus diesem Grund SEHR viel schneller als mysql_result(). Beachten Sie auch, dass die Angabe eines numerischen Offsets für eine Spalte sehr viel schneller ist als die Angabe eines Spaltennamens oder tabellenname.spaltenname.

### Parameter-Liste

`result`

  Das Ergebnis Ressource, das ausgewertet wird. Dieses Ergebnis kommt von einem Aufruf von mysql_query().

`row`
  Die Zeilennummer des erhaltenen Ergebnisses. Zeilennummern beginnen mit `0`.
`field`
  Der Name oder der Offset der abzurufenden Spalte (Feld). Dies kann der Offset der Spalte sein, der Name der Spalte oder ein Bezeichner in der Form Tabellenname.Spaltenname. Wurde ein Alias für den Spaltennamen verwendet ('select foo as bar from...'), verwenden Sie stattdessen den Alias. Ist der Wert nicht definiert, wird die erste Spalte zurückgegeben.

### Rückgabewerte

Gibt bei Erfolg die Inhalte einer Spalte einer MySQL-Ergebnismenge zurück oder `false` bei Fehlern.

### Beispiele

Beispiel #1 mysql_result()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Keine Verbindung möglich: ' . mysql_error());
    }
    if (!mysql_select_db('database_name')) {
        die('Konnte Datenbank nicht auswählen: ' . mysql_error());
    }
    $result = mysql_query('SELECT name FROM work.employee');
    if (!$result) {
        die('Konnte Abfrage nicht ausführen:' . mysql_error());
    }
    echo mysql_result($result, 2); // gibt den Namen des dritten Angestellten aus

    mysql_close($link);
    ?>

### Anmerkungen

> Hinweis: Aufrufe von mysql_result() sollten nicht mit Aufrufen anderer Funktionen verschachtelt werden, die auch auf das Ergebnis zugreifen.

### Siehe auch

- mysql_fetch_row() - Liefert einen Datensatz als indiziertes Array
- mysql_fetch_array() - Liefert einen Datensatz als assoziatives Array, als numerisches Array oder beides
- mysql_fetch_assoc() - Liefert einen Datensatz als assoziatives Array
- mysql_fetch_object() - Liefert eine Ergebniszeile als Objekt

# mysql_select_db

(PHP 4, PHP 5)

mysql_select_db — Wählt eine MySQL-Datenbank aus

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_select_db()
- PDO::__construct() (Teil des DSN)

### Beschreibung

function mysql_select_db(string `$database_name`, resource `$link_identifier` = NULL): bool

Setzt die aktive Datenbank auf dem Server, die mit der angegebenen Verbindung verknüpft ist. Jeder nachfolgende Aufruf von mysql_query() operiert auf dieser aktiven Datenbank.

### Parameter-Liste

`database_name`
  Der Name der auszuwählenden Datenbank.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_select_db()-Beispiel

    <?php

    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    if (!$link) {
        die('Verbindung nicht möglich : ' . mysql_error());
    }

    // Verwende Datenbank foo
    $db_selected = mysql_select_db('foo', $link);
    if (!$db_selected) {
        die ('Kann foo nicht verwenden : ' . mysql_error());
    }
    ?>

### Anmerkungen

> Hinweis: Für die Abwärtskompatibiliät kann der folgende veraltete Alias verwendet werden: mysql_selectdb()

### Siehe auch

- mysql_connect() - Öffnet eine Verbindung zu einem MySQL-Server
- mysql_pconnect() - Öffnet eine persistente Verbindung zum MySQL-Server
- mysql_query() - Sendet eine Abfrage an MySQL

# mysql_set_charset

(PHP 5 >= 5.2.3)

mysql_set_charset — Setzt den Verbindungszeichensatz

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_set_charset()
- PDO: `charset` zur Verbindungszeichenkette hinzufügen, beispielsweise`charset=utf8`

### Beschreibung

function mysql_set_charset(string `$charset`, resource `$link_identifier` = NULL): bool

Setzt den Standardzeichensatz für die angegebene Verbindung.

### Parameter-Liste

`charset`
  Ein gültiger Zeichensatzname.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Anmerkungen

> Hinweis: Diese Funktion benötigt MySQL 5.0.7 oder später.

> Hinweis: Dies ist die bevorzugte Methode zur Änderung des Zeichensatzes. Dafür mysql_query() (z. B. `SET NAMES utf8`) zu verwenden, wird nicht empfohlen. Siehe den Abschnitt MySQL-Zeichensatzkonzepte für nähere Informationen.

### Siehe auch

- Setzen des Zeichensatzes in MySQL
- » Liste der von MySQL unterstützten Zeichensätze
- mysql_client_encoding() - Liefert den Namen des Zeichensatzes

# mysql_stat

(PHP 4 >= 4.3.0, PHP 5)

mysql_stat — Zeigt den momentanen Serverstatus an

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_stat()
- PDOStatement::getAttribute() mit `PDO::ATTR_SERVER_INFO` als `attribute`

### Beschreibung

function mysql_stat(resource `$link_identifier` = NULL): string

mysql_stat() gibt den momentanen Server-Status zurück.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt eine Zeichenkette mit dem Status für uptime, threads, queries, open tables, flush tables und queries per second zurück. Für eine komplette Liste der anderen Status-Variablen müssen sie die SQL-Anweisung `SHOW STATUS` verwenden. Wenn die Verbindungskennung `Verbindungskennung` ungültig ist, wird `null` zurückgegeben.

### Beispiele

Beispiel #1 mysql_stat()-Beispiel

    <?php
    $link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $status = explode('  ', mysql_stat($link));
    print_r($status);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Uptime: 5380
        [1] => Threads: 2
        [2] => Questions: 1321299
        [3] => Slow queries: 0
        [4] => Opens: 26
        [5] => Flush tables: 1
        [6] => Open tables: 17
        [7] => Queries per second avg: 245.595
    )

Beispiel #2 Alternatives mysql_stat()-Beispiel

    <?php
    $link   = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $result = mysql_query('SHOW STATUS', $link);
    while ($row = mysql_fetch_assoc($result)) {
        echo $row['Variable_name'] . ' = ' . $row['Value'] . "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    back_log = 50
    basedir = /usr/local/
    bdb_cache_size = 8388600
    bdb_log_buffer_size = 32768
    bdb_home = /var/db/mysql/
    bdb_max_lock = 10000
    bdb_logdir =
    bdb_shared_data = OFF
    bdb_tmpdir = /var/tmp/
    ...

### Siehe auch

- mysql_get_server_info() - Liefert Informationen zum MySQL-Server
- mysql_list_processes() - Zeigt die MySQL-Prozesse an

# mysql_tablename

(PHP 4, PHP 5)

mysql_tablename — Liefert den Namen einer Tabelle

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- SQL-Abfrage: `SHOW TABLES`

### Beschreibung

function mysql_tablename(resource `$result`, int `$i`): string|false

Liest den Tabellennamen aus einem Ergebnis (`result`).

Diese Funktion ist veraltet. Es wird empfohlen, stattdessen eine SQL-Abfrage wie `SHOW TABLES [FROM db_name] [LIKE 'pattern']` zu verwenden.

### Parameter-Liste

`result`
  Ein Ergebniszeiger vom Typ resource, der von mysql_list_tables() zurückgegeben wird.
`i`
  Der Integer-Index (Zeilen-/Tabellennummer).

### Rückgabewerte

Gibt bei Erfolg den Tabellennamen zurück. Bei einem Fehler wird `false` zurückgegeben.

Verwenden Sie die Funktion mysql_tablename(), um den Ergebniszeiger zu durchlaufen, oder verwenden Sie eine andere Ergebnisfunktion wie mysql_fetch_array().

### Beispiele

Beispiel #1 mysql_tablename()-Beispiel

    <?php
    mysql_connect("localhost", "mysql_user", "mysql_password");
    $result = mysql_list_tables("mydb");
    $num_rows = mysql_num_rows($result);
    for ($i = 0; $i < $num_rows; $i++) {
        echo "Tabelle: ", mysql_tablename($result, $i), "\n";
    }

    mysql_free_result($result);
    ?>

### Anmerkungen

> Hinweis: Die Funktion mysql_num_rows() kann verwendet werden, um die Anzahl der Tabellen im Ergebniszeiger zu bestimmen.

### Siehe auch

- mysql_list_tables() - Listet Tabellen einer MySQL-Datenbank auf
- mysql_field_table() - Liefert den Namen der Tabelle, die das genannte Feld enthält
- mysql_db_name() - Liefert den Namen einer Datenbank vom mysql_list_dbs-Aufruf

# mysql_thread_id

(PHP 4 >= 4.3.0, PHP 5)

mysql_thread_id — Zeigt die aktuelle Thread-ID an

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- mysqli_thread_id()

### Beschreibung

function mysql_thread_id(resource `$link_identifier` = NULL): int|false

Gibt die aktuelle Thread-ID zurück. Ist die Verbindung abgerissen und Sie bauen diese mit mysql_ping() wieder auf, wechselt die Thread-ID. Das bedeutet, dass sie die Thread-ID nur abfragen, wenn sie sie benötigen.

### Parameter-Liste

`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Gibt bei Erfolg die Thread-ID zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mysql_thread_id()-Beispiel

    <?php
    $link = mysql_connect('localhost', 'mysql_user', 'mysql_password');
    $thread_id = mysql_thread_id($link);
    if ($thread_id){
        printf("Die aktuelle Thread-ID ist %d\n", $thread_id);
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Die aktuelle Thread-ID ist 73

### Siehe auch

- mysql_ping() - Pingt eine Serververbindung an und verbindet erneut, wenn keine Verbindung besteht
- mysql_list_processes() - Zeigt die MySQL-Prozesse an

# mysql_unbuffered_query

(PHP 4 >= 4.0.6, PHP 5)

mysql_unbuffered_query — Sendet eine SQL-Anfrage an MySQL, ohne Ergebniszeilen abzuholen und zu puffern

Warnung

Diese Erweiterung ist seit PHP 5.5.0 als veraltet markiert und wurde in PHP 7.0.0 entfernt. Verwenden Sie stattdessen die Erweiterungen MySQLi oder PDO_MySQL. Weitere Informationen bietet der Ratgeber MySQL: Auswahl einer API. Alternativen zu dieser Funktion umfassen:

- Siehe: Gepufferte und ungepufferte Queries

### Beschreibung

function mysql_unbuffered_query(string `$query`, resource `$link_identifier` = NULL): resource

mysql_unbuffered_query() sendet die SQL-Abfrage `query` an MySQL, ohne dass die Datensätze des Ergebnisses automatisch geholt und gepuffert werden, wie es bei der Verwendung von mysql_query() der Fall ist. Dies spart eine erhebliche Menge an Speicher bei SQL-Abfragen ein, die große Ergebnismengen zurückgeben und Sie können unmittelbar mit dem Abfrageergebnis arbeiten, sobald der erste Datensatz gefunden wurde: Sie müssen nicht darauf warten, bis die gesamte SQL-Abfrage abgeschlossen ist. Um mysql_unbuffered_query() verwenden zu können während mehrere Datenbankverbindungen geöffnet sind, müssen Sie den optionalen Parameter `link_identifier` angeben, um zu identifizieren, welche Verbindung Sie verwenden möchten.

### Parameter-Liste

`query`
  Die auszuführende SQL-Abfrage. Werte innerhalb der Abfrage sollten mit korrekt maskiert sein.
`link_identifier`

  Die MySQL-Verbindung. Wird die Verbindungskennung nicht angegeben, wird die letzte durch mysql_connect() geöffnete Verbindung angenommen. Falls keine solche Verbindung gefunden wird, wird versucht, eine Verbindung aufzubauen, wie es beim Aufruf von mysql_connect() ohne Angabe von Argumenten der Fall wäre. Falls zufällig keine Verbindung gefunden oder aufgebaut werden kann, wird eine Warnung der Stufe `E_WARNING` erzeugt.

### Rückgabewerte

Für SELECT-, SHOW-, DESCRIBE- oder EXPLAIN-Anweisungen gibt mysql_unbuffered_query() bei Erfolg eine Ressource zurück oder `false` bei einem Fehler.

Für alle anderen von SQL-Anweisungen wie INSERT, UPDATE, DELETE, DROP, etc, gibt mysql_unbuffered_query() bei Erfolg `true` zurück oder `false` bei Fehlern.

### Anmerkungen

> Hinweis: Die Vorteile von mysql_unbuffered_query() haben ihren Preis: Auf ein Ergebnis von mysql_unbuffered_query() können die Funktionen mysql_num_rows() und mysql_data_seek() nicht angewendet werden. Ausserdem müssen Sie sicherstellen, dass Sie alle Datensätze des Ergebnisses einer ungepufferten SQL-Abfrage abgeholt haben. Erst dann können Sie eine neue SQL-Abfrage bei Verwendung derselben Verbindung `link_identifier` an MySQL absetzen.

### Siehe auch

- mysql_query() - Sendet eine Abfrage an MySQL

## Inhaltsverzeichnis

- mysql_affected_rows — Liefert die Anzahl betroffener Datensätze einer vorhergehenden MySQL-Operation
- mysql_client_encoding — Liefert den Namen des Zeichensatzes
- mysql_close — Schließt eine Verbindung zu MySQL
- mysql_connect — Öffnet eine Verbindung zu einem MySQL-Server
- mysql_create_db — Legt eine MySQL-Datenbank an
- mysql_data_seek — Bewegt den internen Ergebnis-Zeiger
- mysql_db_name — Liefert den Namen einer Datenbank vom mysql_list_dbs-Aufruf
- mysql_db_query — Wählt eine Datenbank aus und führt darauf eine Abfrage aus
- mysql_drop_db — Löscht eine Datenbank
- mysql_errno — Liefert die Nummer einer Fehlermeldung einer zuvor ausgeführten MySQL-Operation
- mysql_error — Liefert den Fehlertext der zuvor ausgeführten MySQL-Operation
- mysql_escape_string — Maskiert eine Zeichenkette zur Verwendung in einer MySQL-Abfrage
- mysql_fetch_array — Liefert einen Datensatz als assoziatives Array, als numerisches Array oder beides
- mysql_fetch_assoc — Liefert einen Datensatz als assoziatives Array
- mysql_fetch_field — Liefert ein Objekt mit Spalteninformationen aus einem Abfrageergebnis
- mysql_fetch_lengths — Liefert die Längen aller Felder aus einem Ergebnis
- mysql_fetch_object — Liefert eine Ergebniszeile als Objekt
- mysql_fetch_row — Liefert einen Datensatz als indiziertes Array
- mysql_field_flags — Liefert die Flags des angegebenen Feldes aus einem Abfrageergebnis
- mysql_field_len — Liefert die Länge des angegebenen Feldes
- mysql_field_name — Liefert den Namen des angegebenen Feldes aus einem Ergebnis
- mysql_field_seek — Setzt den Ergebniszeiger auf einen bestimmten Feldoffset
- mysql_field_table — Liefert den Namen der Tabelle, die das genannte Feld enthält
- mysql_field_type — Liefert den Typ des spezifizierten Feldes aus einem Ergebnis
- mysql_free_result — Gibt belegten Speicher wieder frei
- mysql_get_client_info — Liefert MySQL-Clientinformationen
- mysql_get_host_info — Liefert Informationen zum MySQL-Host
- mysql_get_proto_info — Liefert MySQL-Protokollinformationen
- mysql_get_server_info — Liefert Informationen zum MySQL-Server
- mysql_info — Liefert Informationen über die zuletzt ausgeführte Anfrage
- mysql_insert_id — Liefert die ID, die in der vorherigen Abfrage erzeugt wurde
- mysql_list_dbs — Listet die verfügbaren Datenbanken (Schemata) auf einem MySQL-Server auf
- mysql_list_fields — Listet MySQL-Tabellenfelder auf
- mysql_list_processes — Zeigt die MySQL-Prozesse an
- mysql_list_tables — Listet Tabellen einer MySQL-Datenbank auf
- mysql_num_fields — Liefert die Anzahl der Felder in einem Ergebnis
- mysql_num_rows — Liefert die Anzahl der Zeilen in einem Ergebnis
- mysql_pconnect — Öffnet eine persistente Verbindung zum MySQL-Server
- mysql_ping — Pingt eine Serververbindung an und verbindet erneut, wenn keine Verbindung besteht
- mysql_query — Sendet eine Abfrage an MySQL
- mysql_real_escape_string — Maskiert spezielle Zeichen innerhalb einer Zeichenkette für die Verwendung in einer SQL-Anweisung
- mysql_result — Liefert eine Spalte aus einem MySQL-Ergebnis
- mysql_select_db — Wählt eine MySQL-Datenbank aus
- mysql_set_charset — Setzt den Verbindungszeichensatz
- mysql_stat — Zeigt den momentanen Serverstatus an
- mysql_tablename — Liefert den Namen einer Tabelle
- mysql_thread_id — Zeigt die aktuelle Thread-ID an
- mysql_unbuffered_query — Sendet eine SQL-Anfrage an MySQL, ohne Ergebniszeilen abzuholen und zu puffern

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Changelog
- Vordefinierte Konstanten
- Beispiele
  - MySQL Extension Übersichtsbeispiel
- MySQL Funktionen
  - mysql_affected_rows — Liefert die Anzahl betroffener Datensätze einer vorhergehenden MySQL-Operation
  - mysql_client_encoding — Liefert den Namen des Zeichensatzes
  - mysql_close — Schließt eine Verbindung zu MySQL
  - mysql_connect — Öffnet eine Verbindung zu einem MySQL-Server
  - mysql_create_db — Legt eine MySQL-Datenbank an
  - mysql_data_seek — Bewegt den internen Ergebnis-Zeiger
  - mysql_db_name — Liefert den Namen einer Datenbank vom mysql_list_dbs-Aufruf
  - mysql_db_query — Wählt eine Datenbank aus und führt darauf eine Abfrage aus
  - mysql_drop_db — Löscht eine Datenbank
  - mysql_errno — Liefert die Nummer einer Fehlermeldung einer zuvor ausgeführten MySQL-Operation
  - mysql_error — Liefert den Fehlertext der zuvor ausgeführten MySQL-Operation
  - mysql_escape_string — Maskiert eine Zeichenkette zur Verwendung in einer MySQL-Abfrage
  - mysql_fetch_array — Liefert einen Datensatz als assoziatives Array, als numerisches Array oder beides
  - mysql_fetch_assoc — Liefert einen Datensatz als assoziatives Array
  - mysql_fetch_field — Liefert ein Objekt mit Spalteninformationen aus einem Abfrageergebnis
  - mysql_fetch_lengths — Liefert die Längen aller Felder aus einem Ergebnis
  - mysql_fetch_object — Liefert eine Ergebniszeile als Objekt
  - mysql_fetch_row — Liefert einen Datensatz als indiziertes Array
  - mysql_field_flags — Liefert die Flags des angegebenen Feldes aus einem Abfrageergebnis
  - mysql_field_len — Liefert die Länge des angegebenen Feldes
  - mysql_field_name — Liefert den Namen des angegebenen Feldes aus einem Ergebnis
  - mysql_field_seek — Setzt den Ergebniszeiger auf einen bestimmten Feldoffset
  - mysql_field_table — Liefert den Namen der Tabelle, die das genannte Feld enthält
  - mysql_field_type — Liefert den Typ des spezifizierten Feldes aus einem Ergebnis
  - mysql_free_result — Gibt belegten Speicher wieder frei
  - mysql_get_client_info — Liefert MySQL-Clientinformationen
  - mysql_get_host_info — Liefert Informationen zum MySQL-Host
  - mysql_get_proto_info — Liefert MySQL-Protokollinformationen
  - mysql_get_server_info — Liefert Informationen zum MySQL-Server
  - mysql_info — Liefert Informationen über die zuletzt ausgeführte Anfrage
  - mysql_insert_id — Liefert die ID, die in der vorherigen Abfrage erzeugt wurde
  - mysql_list_dbs — Listet die verfügbaren Datenbanken (Schemata) auf einem MySQL-Server auf
  - mysql_list_fields — Listet MySQL-Tabellenfelder auf
  - mysql_list_processes — Zeigt die MySQL-Prozesse an
  - mysql_list_tables — Listet Tabellen einer MySQL-Datenbank auf
  - mysql_num_fields — Liefert die Anzahl der Felder in einem Ergebnis
  - mysql_num_rows — Liefert die Anzahl der Zeilen in einem Ergebnis
  - mysql_pconnect — Öffnet eine persistente Verbindung zum MySQL-Server
  - mysql_ping — Pingt eine Serververbindung an und verbindet erneut, wenn keine Verbindung besteht
  - mysql_query — Sendet eine Abfrage an MySQL
  - mysql_real_escape_string — Maskiert spezielle Zeichen innerhalb einer Zeichenkette für die Verwendung in einer SQL-Anweisung
  - mysql_result — Liefert eine Spalte aus einem MySQL-Ergebnis
  - mysql_select_db — Wählt eine MySQL-Datenbank aus
  - mysql_set_charset — Setzt den Verbindungszeichensatz
  - mysql_stat — Zeigt den momentanen Serverstatus an
  - mysql_tablename — Liefert den Namen einer Tabelle
  - mysql_thread_id — Zeigt die aktuelle Thread-ID an
  - mysql_unbuffered_query — Sendet eine SQL-Anfrage an MySQL, ohne Ergebniszeilen abzuholen und zu puffern

# MySQL Native Driver

# Einführung

Der MySQL Native Driver ist ein Ersatz für die MySQL Client Library (libmysqlclient). Der MySQL Native Driver ist seit PHP 5.3.0 Teil der offiziellen PHP-Quellen.

Die MySQL-Datenbankerweiterungen `mysqli` und PDO MYSQL kommunizieren beide mit dem MySQL-Server. In der Vergangenheit nutzten diese Erweiterungen die von der MySQL Client Library bereitgestellten Dienste. Die Erweiterungen wurden dafür gegen die MySQL-Client-Bibliothek kompiliert, um deren Client-Server-Protokoll zu verwenden.

Mit dem MySQL Native Driver gibt es nun eine Alternative, weil die MySQL-Datenbankerweiterungen nun so kompiliert werden können, dass sie den MySQL Native Driver anstelle der MySQL Client Library verwenden.

Der MySQL Native Driver ist eine in C geschriebene PHP-Erweiterung.

# Übersicht

Was er nicht ist

Der MySQL Native Driver wurde zwar als PHP-Erweiterung geschrieben, stellt dem PHP-Programmierer aber keine neue API zur Verfügung. Die Programmierer-APIs für die Verbindung zu MySQL-Datenbanken werden von den MySQL-Erweiterungen `mysqli` und PDO MYSQL bereitgestellt. Diese Erweiterungen können nun die Dienste des MySQL Native Drivers nutzen, um mit dem MySQL-Server zu kommunizieren. Daher sollte der MySQL Native Driver nicht als API betrachtet werden.

Warum sollte er verwendet werden?

Der MySQL Native Driver bietet gegenüber der MySQL Client Library eine Reihe von Vorteilen.

Die ältere MySQL Client Library wurde von MySQL AB (jetzt Oracle Corporation) geschrieben und daher unter der MySQL-Lizenz veröffentlicht. Dies führte letztendlich dazu, dass die MySQL-Unterstützung in PHP standardmäßig deaktiviert war. Der MySQL Native Driver hingegen wurde als Teil des PHP-Projekts entwickelt und wird daher unter der PHP-Lizenz veröffentlicht. Damit sind die Lizenzierungsprobleme, die es in der Vergangenheit gab, beseitigt.

Außerdem mussten die MySQL-Datenbankerweiterungen in der Vergangenheit mit einer Kopie der MySQL Client Library erstellt werden. Das bedeutete in der Regel, dass MySQL auf dem Rechner, auf dem der PHP-Quellcode erstellt wurde, installiert sein musste. Darüber hinaus riefen die MySQL-Datenbankerweiterungen die Datei der MySQL Client Library zur Laufzeit der PHP-Anwendungen auf, so dass die Datei auf dem System installiert sein musste. Mit dem MySQL Native Driver ist das nicht mehr der Fall, weil er in der Standarddistribution enthalten ist. Es ist also nicht erforderlich, MySQL zu installieren, um PHP zu entwickeln oder PHP-Datenbankanwendungen auszuführen.

Da der MySQL Native Driver als PHP-Erweiterung geschrieben wurde, ist er eng an die Funktionsweise von PHP gekoppelt. Dies führt insbesondere bei der Speichernutzung zu einer höheren Effizienz, weil der Treiber das Speicherverwaltungssystem von PHP nutzt. Außerdem unterstützt er das PHP-Speicherlimit. Mit dem MySQL Native Driver wird eine vergleichbare oder sogar bessere Leistung erzielt als mit der MySQL Client Library, da er stets die effizienteste Nutzung des Speichers gewährleistet. Ein Beispiel für die Speichereffizienz ist die Tatsache, dass bei Verwendung der MySQL Client Library jede Zeile zweimal im Speicher abgelegt wird, während beim MySQL Native Driver jede Zeile nur einmal im Speicher abgelegt wird.

> Hinweis: Überwachen der Speichernutzung
> Aufgrund der Tatsache, dass der MySQL Native Driver die Speicherverwaltung von PHP verwendet, kann seine Speichernutzung mit memory_get_usage() verfolgt werden. Dies ist mit libmysqlclient nicht möglich, weil es stattdessen die C-Funktion malloc() verwendet.

Besondere Fähigkeiten

Der native MySQL-Treiber bietet auch einige besondere Funktionalitäten, die nicht verfügbar sind, wenn die MySQL-Datenbankerweiterungen die MySQL Client Library verwenden. Diese besonderen Funktionalitäten sind unten aufgeführt:

- Verbesserte persistente (dauerhafte) Verbindungen
- Die spezielle Funktion mysqli_fetch_all()
- Aufrufe für Leistungsstatistiken: mysqli_get_client_stats(), mysqli_get_connection_stats()

Mit Hilfe der Leistungsstatistiken können Leistungsengpässe sehr gut erkannt werden.

In Verbindung mit der Erweiterung `mysqli` ermöglicht der MySQL Native Driver auch persistente Verbindungen.

SSL-Unterstützung

Der MySQL Native Driver unterstützt SSL.

Unterstützung komprimierter Protokolle

Der MySQL Native Driver unterstützt das komprimierte Client-Server-Protokoll. Wenn die Erweiterung `ext/mysqli` so konfiguriert ist, dass sie den MySQL Native Driver verwendet, kann sie dieses Feature ebenfalls nutzen. Es ist zu beachten, dass `PDO_MYSQL` die Komprimierung in Verbindung mit mysqlnd NICHT unterstützt.

Unterstützung für benannte Pipes

In Windows-Umgebungen können benannte Pipes für Verbindungen verwendet werden.

# Installation

Installation unter Unix

Um den MySQL Native Driver nutzen zu können, muss PHP so kompiliert werden, dass die MySQL-Datenbankerweiterungen den MySQL Native Driver unterstützen. Dies geschieht über die Konfigurationsoptionen mit denen der PHP-Quellcode kompiliert wird.

Um zum Beispiel die Erweiterung MySQL, `mysqli` und PDO MYSQL unter Verwendung des MySQL Native Driver zu erstellen, müsste der folgende Befehl eingegeben werden:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    [weitere Optionen]

Installation unter Windows

In den offiziellen PHP-Distributionen für Windows ist der MySQL Native Driver standardmäßig aktiviert, so dass keine zusätzliche Konfiguration erforderlich ist, um ihn zu verwenden. Alle MySQL-Datenbankerweiterungen verwenden in diesem Fall den MySQL Native Driver.

Unterstützung des SHA-256 Authentifizierungs-Plugins

Damit sich der MySQL Native Driver über über Konten mit MySQL verbinden kann, die das MySQL SHA-256 Authentifizierungs-Plugin verwenden, muss die OpenSSL-Funktionalität in PHP integriert und aktiviert sein. PHP kann dazu zum Beispiel wie folgt konfiguriert werden:

    ./configure --with-mysql=mysqlnd \
    --with-mysqli=mysqlnd \
    --with-pdo-mysql=mysqlnd \
    --with-openssl
    [weitere Optionen]

In Autotools wird die erweiterte SSL-Unterstützung in `mysqlnd` implizit aktiviert, wenn es durch Verwendung der Konfigurationsoption --with-openssl zusammen mit der Erweiterung `openssl` kompiliert wird. Wenn ohne die Erweiterung `openssl` kompiliert wird, kann die Konfigurationsoption --with-mysqlnd-ssl verwendet werden, um die erweiterte SSL-Unterstützung explizit zu aktivieren.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Autotools-Konfigurationsoption --with-mysqlnd-ssl wurde hinzugefügt, um die erweiterte SSL-Unterstützung explizit zu aktivieren, wenn ohne die Erweiterung `openssl` kompiliert wird.

# Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Konfigurationsoptionen für den MySQL Native Driver
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
mysqlnd.collect_statistics | "1" | `INI_SYSTEM` |
mysqlnd.collect_memory_statistics | "0" | `INI_SYSTEM` |
mysqlnd.debug | "" | `INI_SYSTEM` |
mysqlnd.log_mask | 0 | `INI_ALL` |
mysqlnd.mempool_default_size | 16000 | `INI_ALL` |
mysqlnd.net_read_timeout | "86400" | `INI_ALL` | Vor PHP 7.2.0 war der Standardwert "31536000" und die Veränderbarkeit war `INI_SYSTEM`
mysqlnd.net_cmd_buffer_size | "4096" | `INI_SYSTEM` |
mysqlnd.net_read_buffer_size | "32768" | `INI_SYSTEM` |
mysqlnd.sha256_server_public_key | "" | `INI_PERDIR` |
mysqlnd.trace_alloc | "" | `INI_SYSTEM` |
mysqlnd.fetch_data_copy | 0 | `INI_ALL` | Entfernt seit PHP 8.1.0

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`mysqlnd.collect_statistics` bool
  Aktiviert das Sammeln verschiedener Client-Statistiken, auf die über mysqli_get_client_stats() und mysqli_get_connection_stats() zugegriffen werden kann, und die auch von der Funktion phpinfo() im Abschnitt `mysqlnd` ausgegeben werden. Diese Konfigurationseinstellung aktiviert alle Statistiken des MySQL Native Drivers mit Ausnahme derjenigen, die sich auf die Speicherverwaltung beziehen.
`mysqlnd.collect_memory_statistics` bool
  Aktiviert das Sammeln verschiedener Speicherstatistiken, auf die über mysqli_get_client_stats() und mysqli_get_connection_stats() zugegriffen werden kann, und die auch von der Funktion phpinfo() im Abschnitt `mysqlnd` ausgegeben werden. Diese Konfigurationseinstellung aktiviert die Statistiken zur Speicherverwaltung innerhalb der gesamten Statistiken des MySQL Native Drivers.
`mysqlnd.debug` string
  Zeichnet die Kommunikation aller Erweiterungen, die `mysqlnd` verwenden, in der angegebenen Protokolldatei auf. Das Format der Direktive ist `mysqlnd.debug = "option1[,parameter_option1][:option2[,parameter_option2]]"`. Folgende Optionen stehen für die Formatzeichenkette zur Verfügung:
  - A[,file] - Hängt die Trace-Ausgabe an die angegebene Datei an. Stellt außerdem sicher, dass die Daten nach jedem Schreibvorgang geschrieben werden. Zu diesem Zweck wird die Trace-Datei geschlossen und erneut geöffnet (was recht langsam ist). Dies trägt dazu bei, dass auch bei einem Absturz der Anwendung eine vollständige Protokolldatei vorhanden ist.
  - a[,file] - Hängt die Trace-Ausgabe an die angegebene Datei an.
  - d - Aktiviert die Ausgabe des Makros DBUG_<N> für den aktuellen Zustand. Es kann eine Liste mit Schlüsselwörtern angehängt werden, um nur die Ausgaben des DBUG-Makros auszuwählen, die diese Schlüsselwörter enthalten. Wenn eine leere Liste angegeben wird, werden alle Makros ausgegeben.
  - f[,functions] - Beschränkt die Aktivitäten des Debuggers auf die angegebene Liste von Funktionen. Eine leere Liste impliziert, dass alle Funktionen ausgewählt werden.
  - F - Versieht jede Zeile der Debugger-Ausgabe mit dem Namen der Quelldatei, die das Makro enthält, das die Ausgabe verursacht.
  - i - Versieht jede Zeile der Debugger-Ausgabe mit der PID des aktuellen Prozesses.
  - L - Versieht jede Zeile der Debugger-Ausgabe mit dem Namen der Quelldatei, die das Makro enthält, sowie der Zeile des Makros, das diese Ausgabe verursacht.
  - n - Versieht jede Zeile der Debugger-Ausgabe mit der aktuellen Tiefe der Funktionsverschachtelung
  - o[,file] - Ähnlich wie a[,file], überschreibt aber die alte Datei und hängt nicht an sie an.
  - O[,file] - Ähnlich wie A[,file], überschreibt aber die alte Datei und hängt nicht an sie an.
  - t[,N] - Aktiviert die Verfolgung des Kontrollflusses einer Funktion. Die maximale Verschachtelungstiefe wird durch N angegeben. Die Voreinstellung für N ist 200.
  - x - Aktiviert die Erstellung von Profilen.
  - m - Verfolgt die mit der Speicherzuweisung und -freigabe verbundenen Aufrufe.
  Beispiel:

      d:t:x:O,/tmp/mysqlnd.trace

  > Hinweis: Dieses Funktionalität steht nur mit einem sogenannten Debug-Build von PHP zur Verfügung.

`mysqlnd.log_mask` int
  Legt fest, welche Abfragen protokolliert werden sollen. Der Standardwert ist 0, was die Protokollierung deaktiviert. Die Definition erfolgt mit einer Ganzzahl und nicht mit PHP-Konstanten. Ein Wert von 48 (16 + 32) protokolliert zum Beispiel langsame Abfragen, die entweder einen fehlerhaften Index ("no good index") (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) oder überhaupt keinen Index (SERVER_QUERY_NO_INDEX_USED = 32) verwenden. Ein Wert von 2043 (1 + 2 + 8 + ... + 1024) protokolliert alle langsamen Abfragetypen. Folgende Typen stehen zur Verfügung: SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2, SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32, SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256, SERVER_STATUS_NO_BACKSLASH_ESCAPES=512 und SERVER_QUERY_WAS_SLOW=1024.
`mysqlnd.mempool_default_size` int
  Die voreingestellte Größe des mysqlnd-Speicherbereichs, der von den Ergebnismengen verwendet wird.
`mysqlnd.net_read_timeout` int
  `mysqlnd` und die MySQL Client Library `libmysqlclient` verwenden unterschiedliche Netzwerk-APIs. So verwendet `mysqlnd` PHP-Streams, während `libmysqlclient` den eigenen Wrapper für die Netzwerkaufrufe der Betriebssystemebene verwendet. PHP setzt für das Lesen von Streams standardmäßig ein Zeitlimit von 60s. Dies wird in der php.ini über `default_socket_timeout` eingestellt. Diese Vorgabe gilt für alle Streams, die keinen anderen Wert für das Zeitlimit setzen. `mysqlnd` setzt keinen anderen Wert, weshalb Verbindungen von lang laufenden Abfragen nach `default_socket_timeout` Sekunden getrennt werden können, was die Fehlermeldung 2006 - MySQL Server has gone away zur Folge hat. Die MySQL Client Library setzt standardmäßig ein Zeitlimit von 24 * 3600 Sekunden (1 Tag) und wartet auf andere Zeitlimits, z. B. TCP/IP-Zeitlimits. `mysqlnd` benutzt nun das gleiche sehr lange Zeitlimit. Der Wert ist über eine neue Einstellung in der php.ini konfigurierbar: `mysqlnd.net_read_timeout`. `mysqlnd.net_read_timeout` wird von jeder Erweiterung verwendet, die `mysqlnd` verwendet (`ext/mysql`, `ext/mysqli` und `PDO_MySQL`). `mysqlnd` weist PHP-Streams an, `mysqlnd.net_read_timeout` zu verwenden. Zu beachten ist, dass es subtile Unterschiede zwischen `MYSQL_OPT_READ_TIMEOUT` aus der MySQL Client Library und PHP-Streams geben kann. Zum Beispiel gilt `MYSQL_OPT_READ_TIMEOUT` laut Dokumentation nur für TCP/IP-Verbindungen und, vor MySQL 5.1.2, nur unter Windows. PHP-Streams haben diese Einschränkung möglicherweise nicht. Im Zweifelsfall sollte die Dokumentation von Streams zu Rate gezogen werden.
`mysqlnd.net_cmd_buffer_size` int
  `mysqlnd` weist jeder Verbindung einen internen Befehls-/Netzwerkpuffer von `mysqlnd.net_cmd_buffer_size` Bytes zu (in der php.ini). Wenn ein Befehl des MySQL-Client-Server-Protokolls, zum Beispiel `COM_QUERY` (normale Abfrage), nicht in den Puffer passt, vergrößert `mysqlnd` den Puffer auf die für das Senden des Befehls erforderliche Größe. Jedes Mal, wenn der Puffer für eine Verbindung erweitert wird, wird `command_buffer_too_small` um eins erhöht. Wenn `mysqlnd` den Puffer bei fast jeder Verbindung über seine anfängliche Größe von `mysqlnd.net_cmd_buffer_size` Bytes hinaus vergrößern muss, sollten in Betracht gezogen werden, die Standardgröße zu erhöhen, um Neuzuweisungen zu vermeiden. Die voreingestellte Puffergröße beträgt 4096 Bytes, was der kleinstmögliche Wert ist. Der Wert kann auch mittels `mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)` gesetzt werden.
`mysqlnd.net_read_buffer_size` int
  Die maximale Größe des gelesenen Teilstücks in Bytes, wenn der Inhalt eines MySQL-Befehlspakets gelesen wird. Das MySQL-Client-Server-Protokoll kapselt alle seine Befehle in Paketen. Die Pakete bestehen aus einem kleinen Kopf und einem Textkörper mit dem eigentlichen Inhalt. Die Größe des Körpers ist im Kopfteil kodiert. `mysqlnd` liest den Körper in Stücken von `MIN(header.size, mysqlnd.net_read_buffer_size)` Bytes. Wenn ein Paketkörper größer als `mysqlnd.net_read_buffer_size` Bytes ist, muss `mysqlnd` den Befehl `read()` mehrfach aufrufen. Der Wert kann auch mittels `mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)` gesetzt werden.
`mysqlnd.sha256_server_public_key` string
  Diese Option bezieht sich auf das SHA-256-Authentifizierungs-Plugin und enthält den Pfad zur Datei mit dem öffentlichen RSA-Schlüssel des MySQL-Servers. Der Client kann entweder auf die Angabe eines öffentlichen RSA-Schlüssels verzichten, den Schlüssel über diese PHP-Konfigurationseinstellung angeben oder zur Laufzeit mittels mysqli_options(). Wird vom Client kein öffentlicher RSA-Schlüssel angegeben, wird der Schlüssel im Rahmen des Standard-Authentifizierungsverfahrens des SHA-256-Authentifizierungs-Plugins ausgetauscht.
`mysqlnd.trace_alloc` string
`mysqlnd.fetch_data_copy` int
  Erzwingt das Kopieren von Ergebnismengen aus den internen Ergebnismengenpuffern in PHP-Variablen, anstatt die standardmäßige Referenz- und Copy-on-Write-Logik zu verwenden. Weitere Details sind in den Hinweisen zur Implementierung der Speicherverwaltung zu finden. Wenn Ergebnismengen kopiert werden, anstatt sie von PHP-Variablen referenzieren zu lassen, kann der für die PHP-Variablen belegte Speicher früher freigegeben werden. Je nach API-Code des Benutzers, den tatsächlichen Datenbankabfragen und der Größe ihrer Ergebnismengen kann dies den Speicherbedarf von mysqlnd verringern. Dies darf nicht gesetzt werden, wenn PDO_MySQL verwendet wird. PDO_MySQL unterstützt diesen neuen Abrufmodus noch nicht.

  > Hinweis: Diese Einstellung wurde in PHP 8.1.0 entfernt.

# Inkompatibilitäten

Der MySQL Native Driver ist größtenteils mit der MySQL Client Library (`libmysql`) kompatibel. Dieser Abschnitt beschreibt die Inkompatibilitäten zwischen diesen Bibliotheken.

- Werte vom Datentyp `bit` werden bei `libmysql` als binäre Zeichenketten (z. B. "\0" oder "\x1F") und bei `mysqlnd` als dezimale Zeichenketten (z. B. "0" oder "31") zurückgegeben. Wenn der Code mit beiden Bibliotheken kompatibel sein soll, müssen Bit-Felder von MySQL immer mit einer Abfrage wie der folgenden als Zahlen zurückgegeben werden: `SELECT bit + 0 FROM table`.

# Persistente (dauerhafte) Verbindungen

Verwendung persistenter Verbindungen

Wenn `mysqli` zusammen mit `mysqlnd` verwendet wird, erzeugt es beim Aufbau einer persistenten Verbindung auf dem Server einen `COM_CHANGE_USER`- (`mysql_change_user()`) Aufruf. Dadurch wird sichergestellt, dass sich die Verbindung erneut authentifiziert.

Da mit dem `COM_CHANGE_USER`-Aufruf ein gewisser Mehraufwand verbunden ist, ist es möglich, diesen bei der Kompilierung zu deaktivieren. Wenn dann eine persistente Verbindung wiederverwendet wird, wird ein `COM_PING`- (`mysql_ping`) Aufruf erzeugt, um einfach zu testen, ob die Verbindung erneut verwendet werden kann.

Die Erzeugung von `COM_CHANGE_USER` kann mit dem Kompilierungs-Flag `MYSQLI_NO_CHANGE_USER_ON_PCONNECT` deaktiviert werden. Nur als Beispiel:

    shell# CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" ./configure --with-mysql=/usr/local/mysql/ --with-mysqli=/usr/local/mysql/bin/mysql_config --with-pdo-mysql=/usr/local/mysql/bin/mysql_config --enable-debug && make clean && make -j6

Oder alternativ:

    shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT"
    shell# configure --whatever-option
    shell# make clean
    shell# make

Es ist zu beachten, dass `COM_CHANGE_USER` nur von `mysqli` in Verbindung mit `mysqlnd` verwendet wird. Andere Erweiterungs-Treiber-Kombinationen verwenden bei der ersten Nutzung einer persistenten Verbindung `COM_PING`.

# Statistiken

Der MySQL Native Driver bietet die Möglichkeit, Statistiken über die Kommunikation zwischen Client und Server zu sammeln. Es gibt zwei Arten von Statistiken:

- Client-Statistiken
- Verbindungsstatistiken

Wenn die Erweiterung mysqli verwendet wird, können diese Statistiken über zwei API-Aufrufe abgerufen werden:

- mysqli_get_client_stats()
- mysqli_get_connection_stats()

> Hinweis: Die Statistiken werden für alle Erweiterungen zusammengefasst, die den MySQL Native Driver verwenden. Wenn zum Beispiel sowohl die Erweiterung mysqli als auch der PDO-MySQL-Treiber so konfiguriert sind, dass sie MySQLnd verwenden, dann wirken sich die Funktionsaufrufe von mysqli und die Methodenaufrufe von PDO auf die Statistik aus. Es gibt keine Möglichkeit, herauszufinden, wie sehr ein bestimmter API-Aufruf einer Erweiterung, die gegen den MySQL Native Driver kompiliert wurde, eine bestimmte Statistik beeinflusst hat.

## Statistiken abrufen

Auf die Client-Statistiken kann mit der Funktion mysqli_get_client_stats() zugegriffen werden.

Auf die Verbindungstatistiken kann mit der Funktion mysqli_get_connection_stats() zugegriffen werden.

Beide Funktionen geben ein assoziatives Array zurück, wobei der Name einer Statistik der Schlüssel für die zugehörigen statistischen Daten ist.

## Statistiken vom MySQL Native Driver

Die meisten Statistiken beziehen sich auf eine Verbindung, aber manche beziehen sich auf den Prozess; in diesem Fall wird darauf hingewiesen.

Die folgenden Statistiken werden vom MySQL Native Driver erstellt:

Netzwerkbezogene Statistiken
`bytes_sent`
  Die Anzahl der von PHP an den MySQL-Server gesendeten Bytes.
`bytes_received`
  Die Anzahl der vom MySQL-Server empfangenen Bytes.
`packets_sent`
  Die Anzahl der vom MySQL-Client-Server-Protokoll gesendeten Pakete.
`packets_received`
  Die Anzahl der vom MySQL-Client-Server-Protokoll empfangenen Pakete.
`protocol_overhead_in`
  Der Overhead des MySQL-Client-Server-Protokolls für eingehenden Datenverkehr in Bytes. Derzeit wird nur der Paket-Header (4 Bytes) als Overhead betrachtet. `protocol_overhead_in = packets_received * 4`
`protocol_overhead_out`
  Der Overhead des MySQL-Client-Server-Protokolls für ausgehenden Datenverkehr in Bytes. Derzeit wird nur der Paket-Header (4 Bytes) als Overhead betrachtet. `protocol_overhead_out = packets_received * 4`
`bytes_received_ok_packet`
  Die Gesamtgröße der mit dem MySQL-Client-Server-Protokoll empfangenen OK-Pakete in Bytes. Die OK-Pakete können eine Statusmeldung enthalten, deren Länge variieren kann, weshalb die Größe eines OK-Pakets nicht festgelegt ist.

  > Hinweis: Die Gesamtgröße in Bytes enthält die Größe des Header-Pakets (4 Bytes, siehe Protokoll-Overhead).

`packets_received_ok`
  Die Anzahl der mit dem MySQL-Client-Server-Protokoll empfangenen OK-Pakete.
`bytes_received_eof_packet`
  Die Gesamtgröße der mit dem MySQL-Client-Server-Protokoll empfangenen EOF-Pakete in Bytes. Die Größe von EOF kann je nach Serverversion variieren. Außerdem kann EOF eine Fehlermeldung enthalten.

  > Hinweis: Die Gesamtgröße in Bytes enthält die Größe des Header-Pakets (4 Bytes, siehe Protokoll-Overhead).

`packets_received_eof`
  Die Anzahl der mit dem MySQL-Client-Server-Protokoll empfangenen EOF-Pakete. Wie bei anderen Paketstatistiken erhöht sich die Anzahl der Pakete auch dann, wenn PHP nicht das erwartete Paket, sondern z. B. eine Fehlermeldung empfängt.
`bytes_received_rset_header_packet`
  Die Gesamtgröße der mit dem MySQL-Client-Server-Protokoll empfangenen Header-Pakete der Ergebnismenge in Bytes. Die Größe der Pakete variiert in Abhängigkeit von der Nutzlast (`LOAD LOCAL INFILE`, `INSERT`, `UPDATE`, `SELECT`, Fehlermeldung).

  > Hinweis: Die Gesamtgröße in Bytes enthält die Größe des Header-Pakets (4 Bytes, siehe Protokoll-Overhead).

`packets_received_rset_header`
  Die Anzahl der mit dem MySQL-Client-Server-Protokoll empfangenen Header-Pakete der Ergebnismenge.
`bytes_received_rset_field_meta_packet`
  Die Gesamtgröße der mit dem MySQL-Client-Server-Protokoll empfangenen Metadaten-Pakete (Spalteninformationen) der Ergebnismenge in Bytes. Die Größe hängt natürlich von den Feldern in der Ergebnismenge ab. Im Fall von COM_LIST_FIELDS kann das Paket auch eine Fehlermeldung oder ein EOF-Paket enthalten.

  > Hinweis: Die Gesamtgröße in Bytes enthält die Größe des Header-Pakets (4 Bytes, siehe Protokoll-Overhead).

`packets_received_rset_field_meta`
  Die Anzahl der mit dem MySQL-Client-Server-Protokoll empfangenen Metadaten-Pakete (Spalteninformationen) der Ergebnismenge.
`bytes_received_rset_row_packet`
  Die Gesamtgröße der mit dem MySQL-Client-Server-Protokoll empfangenen Pakete mit den Zeilendaten der Ergebnismenge in Bytes. Das Paket kann auch eine Fehlermeldung oder ein EOF-Paket enthalten. Die Anzahl der Fehlermeldungen und EOF-Pakete können ermittelt werden, indem `rows_fetched_from_server_normal` und `rows_fetched_from_server_ps` von `bytes_received_rset_row_packet` abgezogen werden.

  > Hinweis: Die Gesamtgröße in Bytes enthält die Größe des Header-Pakets (4 Bytes, siehe Protokoll-Overhead).

`packets_received_rset_row`
  Die Anzahl der mit dem MySQL-Client-Server-Protokoll empfangenen Pakete mit den Zeilendaten der Ergebnismenge.
`bytes_received_prepare_response_packet`
  Die Gesamtgröße der Pakete für die Initialisierung vorbereiteter Anweisungen (prepared statement init packets), die vom MySQL-Client-Server-Protokoll als OK zurückgegeben werden, in Bytes. Diese Pakete können auch Fehlermeldungen enthalten. Die Größe der Pakete hängt von der MySQL-Version ab.

  > Hinweis: Die Gesamtgröße in Bytes enthält die Größe des Header-Pakets (4 Bytes, siehe Protokoll-Overhead).

`packets_received_prepare_response`
  Die Anzahl der Pakete für die Initialisierung vorbereiteter Anweisungen (prepared statement init packets), die vom MySQL-Client-Server-Protokoll als OK zurückgegeben werden.
`bytes_received_change_user_packet`
  Die Gesamtgröße der mit dem MySQL-Client-Server-Protokoll empfangenen COM_CHANGE_USER-Pakete in Bytes. Ein Paket kann auch eine Fehlermeldung oder ein EOF enthalten.

  > Hinweis: Die Gesamtgröße in Bytes enthält die Größe des Header-Pakets (4 Bytes, siehe Protokoll-Overhead).

`packets_received_change_user`
  Die Anzahl der mit dem MySQL-Client-Server-Protokoll empfangenen COM_CHANGE_USER-Pakete.
`packets_sent_command`
  Die Anzahl der Befehle des MySQL-Client-Server-Protokolls, die von PHP an MySQL gesendet wurden. Es gibt keine Möglichkeit herauszufinden, welche spezifischen Befehle gesendet wurden und wie viele davon.
`bytes_received_real_data_normal`
  Die Anzahl der Bytes an Nutzdaten, die der PHP-Client über das Textprotokoll von `mysqlnd` abgerufen hat. Dies ist die Größe der tatsächlichen Daten, die in den Ergebnismengen enthalten sind, die vom PHP-Client abgerufen wurden und nicht aus vorbereiteten Anweisungen stammen. Zu beachten ist, dass, obwohl eine vollständige Ergebnismenge von `mysqlnd` aus MySQL abgerufen wurde, diese Statistik nur die tatsächlichen Daten zählt, die vom PHP-Client aus `mysqlnd` abgerufen wurden.

  Das folgende Beispiel zeigt eine Codesequenz, die den Wert erhöht:

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->fetch_assoc();
      $res->close();

  Jeder Abrufvorgang erhöht den Wert.

  Die Statistik wird jedoch nicht erhöht, wenn die Ergebnismenge auf dem Client nur gepuffert, aber nicht abgerufen wird, wie im folgenden Beispiel:

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->close();

`bytes_received_real_data_ps`
  Die Anzahl der Bytes an Nutzdaten, die der PHP-Client über das Protokoll für vorbereitete Anweisungen von `mysqlnd` abgerufen hat. Dies ist die Größe der tatsächlichen Daten, die in den Ergebnismengen enthalten sind, die vom PHP-Client abgerufen wurden und aus vorbereiteten Anweisungen stammen. Der Wert erhöht sich nur dann, wenn die Ergebnismenge anschließend vom PHP-Client gelesen wird. Zu beachten ist, dass, obwohl eine vollständige Ergebnismenge von `mysqlnd` aus MySQL abgerufen wurde, diese Statistik nur die tatsächlichen Daten zählt, die vom PHP-Client aus `mysqlnd` abgerufen wurden. Siehe auch `bytes_received_real_data_normal`.

Statistiken zu Ergebnismengen
`result_set_queries`
  Die Anzahl der Abfragen, die eine Ergebnismenge erzeugt haben. Beispiele für Abfragen, die eine Ergebnismenge erzeugen: `SELECT`, `SHOW`. Die Statistik wird nicht erhöht, wenn beim Lesen des Header-Pakets einer Zeile der Ergebnismenge ein Fehler aufgetreten ist.

  > Hinweis: Diese Statistik kann als indirektes Maß für die Anzahl der von PHP an MySQL gesendeten Anfragen verwendet werden. Dies kann helfen, einen Client zu identifizieren, der eine hohe Datenbanklast verursacht.

`non_result_set_queries`
  Die Anzahl der Abfragen, die keine Ergebnismenge erzeugt haben. Beispiele für Abfragen, die keine Ergebnismenge erzeugen: `INSERT`, `UPDATE`, `LOAD DATA`. Die Statistik wird nicht erhöht, wenn beim Lesen des Header-Pakets einer Zeile der Ergebnismenge ein Fehler aufgetreten ist.

  > Hinweis: Diese Statistik kann als indirektes Maß für die Anzahl der von PHP an MySQL gesendeten Anfragen verwendet werden. Dies kann helfen, einen Client zu identifizieren, der eine hohe Datenbanklast verursacht.

`no_index_used`
  Die Anzahl der Abfragen, die eine Ergebnismenge erzeugt, aber keinen Index verwendet haben (siehe auch die mysqld-Startoption `--log-queries-not-using-indexes`).

  > Hinweis: Solche Anfragen können als Exception gemeldet werden, indem `mysqli_report(MYSQLI_REPORT_INDEX);` aufgerufen wird. Es ist möglich, sie stattdessen als Warnung zu melden, indem `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);` aufgerufen wird.

`bad_index_used`
  Die Anzahl der Abfragen, die eine Ergebnismenge erzeugt, aber keinen guten Index verwendet haben (siehe auch die mysqld-Startoption `--log-slow-queries`).

  > Hinweis: Solche Anfragen können als Exception gemeldet werden, indem `mysqli_report(MYSQLI_REPORT_INDEX);` aufgerufen wird. Es ist möglich, sie stattdessen als Warnung zu melden, indem `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);` aufgerufen wird.

`slow_queries`
  SQL-Anweisungen, deren Ausführung länger als `long_query_time` Sekunden dauerte und bei denen mindestens `min_examined_row_limit` Zeilen untersucht werden mussten.
  Achtung

  Wird von mysqli_report() nicht gemeldet.

`buffered_sets`
  Die Anzahl der gepufferten Ergebnismengen, die von normalen Abfragen (d. h. nicht über eine vorbereitete Anweisung) zurückgegeben wurden.

  Beispiele für API-Aufrufe, die Ergebnismengen auf dem Client puffern: mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result()

`unbuffered_sets`
  Die Anzahl der ungepufferten Ergebnismengen, die von normalen Abfragen (d. h. nicht über eine vorbereitete Anweisung) zurückgegeben wurden.

  Ein Beispiel für API-Aufrufe, die keine Ergebnismengen auf dem Client puffern: mysqli_use_result()

`ps_buffered_sets`
  Die Anzahl der gepufferten Ergebnismengen, die von vorbereiteten Anweisungen zurückgegeben wurden.

  Ein Beispiel für API-Aufrufe, die Ergebnismengen auf dem Client puffern: mysqli_stmt_store_result()

`ps_unbuffered_sets`
  Die Anzahl der ungepufferten Ergebnismengen, die von vorbereiteten Anweisungen zurückgegeben wurden. In der Standardeinstellung werden vorbereitete Anweisungen nicht gepuffert, sodass die meisten vorbereiteten Anweisungen in dieser Statistik enthalten sind.
`flushed_normal_sets`
  Die Anzahl der Ergebnismengen, die von normalen Abfragen (d. h. nicht über eine vorbereitete Anweisung) zurückgegeben wurden, mit ungelesenen Daten, die stillschweigend geleert wurden..

  > Hinweis: Die Bereinigung (Flushing) erfolgt nur bei ungepufferten Ergebnismengen. Ungepufferte Ergebnismengen müssen vollständig abgerufen werden, bevor eine neue Abfrage über die Verbindung ausgeführt werden kann, sonst gibt MySQL einen Fehler aus. Wenn eine Anwendung nicht alle Zeilen aus einer ungepufferten Ergebnismenge abruft, ruft mysqlnd die Ergebnismenge implizit ab, um die Verbindung freizugeben. Siehe auch `rows_skipped_normal`, `rows_skipped_ps`.

  > Ein paar mögliche Ursachen für einen impliziten Flush:

  > - Eine fehlerhafte Client-Anwendung
  > - Der Client hat aufgehört, Zeilen abzurufen, weil er gefunden hat, wonach er gesucht hat, aber die Ergebnismenge wurde noch nicht vollständig abgerufen
  > - Die Client-Anwendung wurde unerwartet beendet

`flushed_ps_sets`
  Die Anzahl der Ergebnismengen vorbereiteter Anweisungen mit ungelesenen Daten, die stillschweigend geleert wurden.

  > Hinweis: Die Bereinigung (Flushing) erfolgt nur bei ungepufferten Ergebnismengen. Ungepufferte Ergebnismengen müssen vollständig abgerufen werden, bevor eine neue Abfrage über die Verbindung ausgeführt werden kann, sonst gibt MySQL einen Fehler aus. Wenn eine Anwendung nicht alle Zeilen aus einer ungepufferten Ergebnismenge abruft, ruft mysqlnd die Ergebnismenge implizit ab, um die Verbindung freizugeben. Siehe auch `rows_skipped_normal`, `rows_skipped_ps`.

  > Ein paar mögliche Ursachen für einen impliziten Flush:

  > - Eine fehlerhafte Client-Anwendung
  > - Der Client hat aufgehört, Zeilen abzurufen, weil er gefunden hat, wonach er gesucht hat, aber die Ergebnismenge wurde noch nicht vollständig abgerufen
  > - Die Client-Anwendung wurde unerwartet beendet

`ps_prepared_never_executed`
  Die Anzahl der vorbereiteten, aber nie ausgeführten Anweisungen.
`ps_prepared_once_executed`
  Die Anzahl der vorbereiteten Anweisungen, die nur einmal ausgeführt wurden.
`rows_fetched_from_server_normal`
`rows_fetched_from_server_ps`
  Die Anzahl der Zeilen der Ergebnismenge, die vom Server abgerufen wurden. Dazu gehören auch die Zeilen, die nicht vom Client gelesen wurden, sondern implizit aus geleerten ungepufferten Ergebnismengen abgerufen wurden. Siehe auch `packets_received_rset_row`.
`rows_buffered_from_client_normal`
  Die Anzahl der gepufferten Zeilen, die von einer normalen Abfrage stammen. Dies ist die Anzahl der Zeilen, die von MySQL abgerufen und auf dem Client gepuffert wurden.

  Beispiele für Abfragen, die Ergebnisse puffern:

  - mysqli_query()
  - mysqli_store_result()
`rows_buffered_from_client_ps`
  Wie `rows_buffered_from_client_normal`, aber für vorbereitete Anweisungen.
`rows_fetched_from_client_normal_buffered`
  Die Anzahl der Zeilen, die der Client aus einer gepufferten Ergebnismenge abgerufen hat, die durch eine normale Abfrage erstellt wurde.
`rows_fetched_from_client_ps_buffered`
  Die Anzahl der Zeilen, die der Client aus einer gepufferten Ergebnismenge abgerufen hat, die durch eine vorbereitete Anweisung erstellt wurde.
`rows_fetched_from_client_normal_unbuffered`
  Die Anzahl der Zeilen, die der Client aus einer ungepufferten Ergebnismenge abgerufen hat, die durch eine normale Abfrage erstellt wurde.
`rows_fetched_from_client_ps_unbuffered`
  Die Anzahl der Zeilen, die der Client aus einer ungepufferten Ergebnismenge abgerufen hat, die durch eine vorbereitete Anweisung erstellt wurde.
`rows_fetched_from_client_ps_cursor`
  Die Anzahl der Zeilen, die der Client von einem durch eine vorbereitete Anweisung erstellten Zeiger (Cursor) abgerufen hat.
`rows_skipped_normal`
`rows_skipped_ps`
  Für zukünftige Verwendung reserviert (wird derzeit nicht unterstützt).
`copy_on_write_saved`
`copy_on_write_performed`
  Diese Statistik bezieht sich auf die Prozessebene. Bei mysqlnd zeigen die von den Erweiterungen zurückgegebenen Variablen auf die internen Netzwerk-Ergebnispuffer von mysqlnd. Wenn die Daten nicht verändert werden, werden die abgerufenen Daten nur einmal im Speicher gehalten. Werden die Daten jedoch verändert, muss mysqlnd ein Copy-on-Write (Kopieren beim Schreiben) durchführen.
`explicit_free_result`
`implicit_free_result`
  Diese Statistik bezieht sich auf die Verbindungs- und die Prozessebene. Die Anzahl der freigegebenen Ergebnismengen.
`proto_text_fetched_null`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_NULL`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_null`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_NULL`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_bit`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_BIT`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_bit`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_BIT`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_tinyint`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_TINY`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_tinyint`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_TINY`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_short`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_SHORT`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_short`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_SHORT`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_int24`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_INT24`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_int24`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_INT24`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_int`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_LONG`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_int`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_LONG`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_bigint`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_LONGLONG`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_bigint`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_LONGLONG`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_decimal`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_DECIMAL` oder `MYSQL_TYPE_NEWDECIMAL`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_decimal`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_DECIMAL` oder `MYSQL_TYPE_NEWDECIMAL`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_float`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_FLOAT`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_float`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_FLOAT`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_double`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_DOUBLE`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_double`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_DOUBLE`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_date`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_DATE` oder `MYSQL_TYPE_NEWDATE`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_date`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_DATE` oder `MYSQL_TYPE_NEWDATE`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_year`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_YEAR`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_year`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_YEAR`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_time`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_TIME`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_time`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_TIME`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_datetime`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_DATETIME`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_datetime`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_DATETIME`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_timestamp`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_TIMESTAMP`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_timestamp`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_TIMESTAMP`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_string`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING` oder `MYSQL_TYPE_VARCHAR` fetched from a normal query (MySQL text protocol).
`proto_binary_fetched_string`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_STRING`, `MYSQL_TYPE_VARSTRING` oder `MYSQL_TYPE_VARCHAR` fetched from a prepared statement (MySQL binary protocol).
`proto_text_fetched_blob`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB` oder `MYSQL_TYPE_BLOB`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_blob`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_TINY_BLOB`, `MYSQL_TYPE_MEDIUM_BLOB`, `MYSQL_TYPE_LONG_BLOB` oder `MYSQL_TYPE_BLOB` die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_enum`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_ENUM`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_enum`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_ENUM`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_set`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_SET`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_set`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_SET`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_geometry`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_GEOMETRY`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).
`proto_binary_fetched_geometry`
  Die Anzahl der Spalten des Typs `MYSQL_TYPE_GEOMETRY`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).
`proto_text_fetched_other`
  Die Anzahl der Spalten eines zuvor nicht aufgelisteten Typs `MYSQL_TYPE_*`, die aus einer normalen Abfrage abgerufen wurden (MySQL-Textprotokoll).

  > Hinweis: Theoretisch sollte dies immer `0` sein.

`proto_binary_fetched_other`
  Die Anzahl der Spalten eines zuvor nicht aufgelisteten Typs `MYSQL_TYPE_*`, die aus einer vorbereiteten Anweisung abgerufen wurden (MySQL-Binärprotokoll).

  > Hinweis: Theoretisch sollte dies immer `0` sein.

Verbindungsbezogene Statistiken
`connect_success`
  Die Anzahl der erfolgreichen Verbindungsversuche.

  > Hinweis: `connect_success` enthält die Summe der erfolgreichen Versuche, persistente und nicht-persistente Verbindungen herzustellen. Die Anzahl der erfolgreichen Versuche, eine nicht-persistente Verbindung herzustellen, ist also `connect_success - pconnect_success`.

`pconnect_success`
  Die Anzahl der erfolgreichen Versuche, eine persistente (dauerhafte) Verbindung herzustellen.
`connect_failure`
  Die Anzahl der fehlgeschlagenen Verbindungsversuche.
`reconnect`
  Diese Statistik bezieht sich auf die Prozessebene.
`active_connections`
  Diese Statistik bezieht sich auf die Prozessebene. Die Anzahl der aktiven Verbindungen (persistent und nicht-persistent).

  > Hinweis: Die Anzahl der aktiven nicht-persistenten Verbindungen ist `active_connections - active_persistent_connections`.

`active_persistent_connections`
  Diese Statistik bezieht sich auf die Prozessebene. Die Anzahl der aktiven persistenten Verbindungen.
`explicit_close`
  Die Anzahl der explizit geschlossenen Verbindungen.

  Beispiel #1 Beispiele für Codeschnipsel, die zu einem expliziten Schließen führen

  -     $link = new mysqli(/* ... */);
        $link->close(/* ... */);

  -     $link = new mysqli(/* ... */);
        $link->connect(/* ... */);

`implicit_close`
  Die Anzahl der implizit geschlossenen Verbindungen.

  Beispiel #2 Beispiele für Codeschnipsel, die zu einem impliziten Schließen führen

  -     $link = new mysqli(/* ... */);
        $link->real_connect(/* ... */);

  - `unset($link)`
  - Persistente Verbindung: eine gepoolte Verbindung wurde mit real_connect erstellt und es können unbekannte Optionen gesetzt sein - implizites Schließen, um die Rückgabe einer Verbindung mit unbekannten Optionen zu vermeiden
  - Persistente Verbindung: ping/change_user schlägt fehl und ext/mysqli schließt die Verbindung
  - Am Ende der Skriptausführung: Schließen der Verbindungen, die noch nicht vom Benutzer geschlossen wurden
`disconnect_close`
  Die Anzahl der fehlgeschlagenen Verbindungen, die der C-API-Aufruf `mysql_real_connect` beim Versuch, eine Verbindung aufzubauen, meldet.
`in_middle_of_command_close`
  Diese Statistik bezieht sich auf die Prozessebene. Eine Verbindung wurde mitten in der Ausführung eines Befehls geschlossen (noch nicht abgerufene Ergebnismengen, nachdem eine Abfrage gesendet und bevor eine Antwort abgerufen wurde, während Daten abgerufen wurden, während Daten mit LOAD DATA übertragen wurden).
  Warnung

  Sofern keine asynchronen Abfragen verwendet werden, sollte dies nur passieren, wenn ein Skript unerwartet gestoppt wird und PHP die Verbindungen automatisch schließt.

`init_command_executed_count`
  Die Anzahl der ausgeführten init-Befehle, zum Beispiel `mysqli_options(MYSQLI_INIT_COMMAND , $value)`. Die Anzahl der erfolgreichen Ausführungen ist `init_command_executed_count - init_command_failed_count`.
`init_command_failed_count`
  Die Anzahl der fehlgeschlagenen init-Befehle.

Statistiken im Zusammenhang mit dem `COM_*`-Befehl
`com_quit`
`com_init_db`
`com_query`
`com_field_list`
`com_create_db`
`com_drop_db`
`com_refresh`
`com_shutdown`
`com_statistics`
`com_process_info`
`com_connect`
`com_process_kill`
`com_debug`
`com_ping`
`com_time`
`com_delayed_insert`
`com_change_user`
`com_binlog_dump`
`com_table_dump`
`com_connect_out`
`com_register_slave`
`com_stmt_prepare`
`com_stmt_execute`
`com_stmt_send_long_data`
`com_stmt_close`
`com_stmt_reset`
`com_stmt_set_option`
`com_stmt_fetch`
`com_daemon`
  Die Anzahl der Versuche, einen bestimmten `COM_*`-Befehl von PHP an MySQL zu senden. Die Statistik wird erhöht, nachdem die Zeile geprüft wurde und unmittelbar bevor das entsprechende MySQL-Client-Server-Protokoll-Paket gesendet wird.
  Achtung

  Die Statistik wird nicht nach unten korrigiert, wenn MySQLnd das Paket nicht über die Leitung senden kann. Im Falle eines Fehlers gibt MySQLnd die PHP-Warnung Error while sending %s packet. PID=%d. aus.

  Beispiel #3 Beispiele für die Verwendung

  - Überprüfen, ob PHP bestimmte Befehle an MySQL sendet, zum Beispiel, ob ein Client `COM_PROCESS_KILL` sendet
  - Berechnen der durchschnittlichen Anzahl der ausgeführten vorbereiteten Anweisungen durch Vergleich von `COM_EXECUTE` und `COM_PREPARE`
  - Überprüfen, ob PHP nicht-vorbereitete SQL-Anweisungen ausgeführt hat, indem kontrolliert wird, ob `COM_QUERY` Null ist
  - Erkennen von PHP-Skripten, die eine zu große Anzahl von SQL-Anweisungen ausführen, indem `COM_QUERY` und `COM_EXECUTE` überprüft werden

Sonstige Statistiken
`explicit_stmt_close`
`implicit_stmt_close`
  Diese Statistik bezieht sich auf die Prozessebene. Die Anzahl der abgeschlossenen vorbereiteten Anweisungen.

  > Hinweis: Eine vorbereitete Anweisung wird immer explizit abgeschlossen. Sie wird nur dann implizit abgeschlossen, wenn ihre Vorbereitung fehlschlägt.

`mem_emalloc_count`
`mem_emalloc_ammount`
`mem_ecalloc_count`
`mem_ecalloc_ammount`
`mem_realloc_count`
`mem_realloc_ammount`
`mem_efree_count`
`mem_malloc_count`
`mem_malloc_ammount`
`mem_calloc_count`
`mem_calloc_ammount`
`mem_ealloc_count`
`mem_ealloc_ammount`
`mem_free_count`
  Diese Statistik bezieht sich auf die Prozessebene. Die Anzahl der Aufrufe bezüglich der Speicherverwaltung.
`command_buffer_too_small`
  Die Anzahl der Erweiterungen des Netzwerk-Befehlspuffers, wenn PHP einen Befehl an MySQL sendet. MySQLnd weist jeder Verbindung einen internen Befehls-/Netzwerkpuffer von mysqlnd.net_cmd_buffer_size Bytes zu. Wenn ein Befehl des MySQL-Client-Server-Protokolls, z. B. `COM_QUERY` (normale Abfrage), nicht in den Puffer passt, vergrößert MySQLnd den Puffer auf die Größe, die zum Senden des Befehls erforderlich ist. Jedes Mal, wenn der Puffer für eine Verbindung vergrößert wird, wird `command_buffer_too_small` um eins erhöht. Wenn MySQLnd den Puffer bei fast jeder Verbindung über seine anfängliche Größe von mysqlnd.net_cmd_buffer_size Bytes hinaus vergrößern muss, sollte in Erwägung gezogen werden, die Standardgröße zu erhöhen, um Neuzuweisungen zu vermeiden.
`connection_reused`
  Die Anzahl, wie oft eine persistente Verbindung insgesamt wiederverwendet wurde.

# Hinweise

Dieser Abschnitt enthält eine Reihe von Hinweisen zur Verwendung des MySQL Native Driver.

- Wenn `mysqlnd` verwendet wird, bedeutet dies, dass die PHP-Streams für die zugrundeliegende Verbindung verwendet werden. Für weitere Informationen zu `mysqlnd`, z. B. Timeout-Einstellungen, sollte die Dokumentation für PHP-Streams (Streams) herangezogen werden, nicht die Dokumentation für die MySQL Client Library.

# Speicherverwaltung

Einführung

Der MySQL Native Driver verwaltet den Speicher anders als die MySQL Client Library. Die Bibliotheken unterscheiden sich in der Art und Weise, wie Speicher zugewiesen und freigegeben wird, wie Speicher beim Lesen von MySQL-Ergebnissen in Teilstücken zugewiesen wird, welche Debug- und Entwicklungsoptionen existieren und wie von MySQL gelesene Ergebnisse mit PHP-Benutzervariablen verknüpft werden.

Die folgenden Hinweise sind als Einführung und Zusammenfassung für Benutzer gedacht, die daran interessiert sind, den MySQL Native Driver auf C-Code-Ebene zu verstehen.

Für die Speicherverwaltung verwendete Funktionen

Alle Zuweisungen und Freigaben von Speicher erfolgen über die Funktionen der PHP-Speicherverwaltung, weshalb der Speicherverbrauch von mysqlnd mit Hilfe von PHP-API-Aufrufen wie memory_get_usage() verfolgt werden kann. Da der Speicher über die PHP-Speicherverwaltung zugewiesen und freigegeben wird, werden die Änderungen möglicherweise nicht sofort auf der Ebene des Betriebssystems sichtbar. Die PHP-Speicherverwaltung fungiert als Proxy, der die Freigabe von Speicher an das System eventuell verzögert. Aus diesem Grund ist ein Vergleich des Speicherverbrauchs des MySQL Native Drivers und der MySQL Client Library schwierig. Die MySQL Client Library verwendet direkt die Aufrufe der Speicherverwaltung des Betriebssystems, sodass die Auswirkungen sofort auf der Betriebssystemebene beobachtet werden können.

Jede von PHP erzwungene Speicherbegrenzung wirkt sich auch auf den MySQL Native Driver aus. Dies kann zu "Out-of-Memory"-Fehlern führen, wenn große Ergebnismengen abgerufen werden, die die Größe des von PHP zur Verfügung gestellten Speichers überschreiten. Da die MySQL Client Library nicht die Funktionen der PHP-Speicherverwaltung verwendet, unterliegt sie nicht den von PHP gesetzten Speichergrenzen. Wenn die MySQL Client Library verwendet wird, kann der Speicherbedarf eines PHP-Prozesses je nach Einsatzmodell über das PHP-Speicherlimit hinaus anwachsen. Gleichzeitig sind PHP-Skripte in der Lage, größere Ergebnismengen zu verarbeiten, da der für die Speicherung der Ergebnismengen vorgesehene Speicher nicht unter der Kontrolle von PHP steht.

Die Funktionen der PHP-Speicherverwaltung werden vom MySQL Native Driver über einen schlanken Wrapper aufgerufen. Der Wrapper erleichtert unter anderem das Debugging.

Handhabung von Ergebnismengen

Die verschiedenen MySQL-Server- und Client-APIs unterscheiden zwischen gepufferten und ungepufferten Ergebnismengen. Ungepufferte Ergebnismengen werden Zeile für Zeile von MySQL zum Client übertragen, während der Client die Ergebnisse durchläuft. Gepufferte Ergebnisse werden in ihrer Gesamtheit von der Client-Bibliothek abgerufen, bevor sie an den Client weitergegeben werden.

Der MySQL Native Driver verwendet PHP-Streams für die Kommunikation mit dem MySQL-Server. Die von MySQL gesendeten Ergebnisse werden aus den Netzwerkpuffern der PHP-Streams in den Ergebnispuffer von mysqlnd abgerufen. Der Ergebnispuffer besteht aus Zvals. In einem zweiten Schritt werden die Ergebnisse dem PHP-Skript zur Verfügung gestellt. Diese abschließende Übertragung vom Ergebnispuffer in PHP-Variablen wirkt sich auf den Speicherverbrauch aus und macht sich vor allem dann bemerkbar, wenn gepufferte Ergebnismengen verwendet werden.

Standardmäßig versucht der MySQL Native Driver zu vermeiden, dass gepufferte Ergebnisse doppelt im Speicher gehalten werden. Die Ergebnisse werden nur einmal im internen Ergebnispuffer und ihren Zvals gespeichert. Wenn die Ergebnisse vom PHP-Skript in PHP-Variablen abgerufen werden, verweisen die Variablen auf den internen Ergebnispuffer. Ergebnisse von Datenbankabfragen werden nicht kopiert und nur einmal im Speicher gehalten. Wenn ein Benutzer den Inhalt einer Variable ändert, die Ergebnisse einer Datenbankabfrage enthält, muss ein Copy-on-Write (Kopieren beim Schreiben) durchgeführt werden, um zu vermeiden, dass der referenzierte interne Ergebnispuffer geändert wird. Der Inhalt des Puffers darf nicht verändert werden, weil der Benutzer die Ergebnismenge möglicherweise ein zweites Mal lesen möchte. Der Copy-on-Write-Mechanismus wird durch eine zusätzliche Liste zur Verwaltung der Referenzen und die Verwendung von Standard-Zval-Referenzzählern realisiert. Copy-on-Write muss auch dann durchgeführt werden, wenn der Benutzer eine Ergebnismenge in PHP-Variablen einliest und eine Ergebnismenge wieder freigibt, bevor die Variablen zurückgesetzt werden.

Im Allgemeinen funktioniert diese Vorgehensweise gut bei Skripten, die eine Ergebnismenge einmal lesen und die Variablen mit den Ergebnissen nicht verändern. Ihr größter Nachteil ist der durch die zusätzliche Referenzverwaltung verursachte zusätzliche Speicherbedarf. Dieser rührt in erster Linie daher, dass Benutzervariablen, die Ergebnisse enthalten, erst dann vollständig freigegeben werden können, wenn sie nicht mehr von der mysqlnd-Referenzverwaltung referenziert werden. Der MySQL Native Driver entfernt die Referenz auf die Benutzervariablen, wenn die Ergebnismenge freigegeben wird oder wenn ein Copy-on-Write durchgeführt wird. Ein Beobachter sieht, wie der Gesamtspeicherbedarf solange ansteigt, bis die Ergebnismenge freigegeben wird. Mit Hilfe der Statistiken kann überprüft werden, ob ein Skript die Ergebnismenge explizit freigibt oder ob sie vom Treiber implizit freigegeben wird und somit der Speicher länger als nötig verwendet wird. Anhand der Statistiken lässt sich auch feststellen, wie viele Copy-on-Write-Operationen durchgeführt wurden.

Ein PHP-Skript, das viele kleine Zeilen aus einer gepufferten Ergebnismenge ausliest und dazu einen Codeschnipsel verwendet, der `while ($row = $res->fetch_assoc()) { ... }` entspricht, kann den Speicherbedarf optimieren, indem es Kopien anstelle von Referenzen anfordert. Kopien anzufordern bedeutet zwar, dass die Ergebnisse doppelt im Speicher gehalten werden, aber es erlaubt PHP, die in `$row` enthaltene Kopie schon freizugeben, während die Ergebnismenge durchlaufen wird, statt erst, wenn die Ergebnismenge selbst freigegeben wird. Auf einem stark ausgelasteten Server kann die Optimierung der Spitzenspeichernutzung dazu beitragen, die Gesamtleistung des Systems zu verbessern, obwohl der Weg über Kopien für ein einzelnes Skript aufgrund zusätzlicher Zuweisungen und Speicherkopiervorgänge langsamer sein kann.

Überwachung und Fehlersuche

Es gibt mehrere Möglichkeiten, die Speichernutzung des MySQL Native Drivers zu verfolgen. Um einen schnellen Überblick zu erhalten oder die Speichereffizienz von PHP-Skripten zu überprüfen, empfiehlt sich ein Blick auf die Statistiken, die von der Bibliothek gesammelt werden. Anhand der Statistiken können z. B. SQL-Anweisungen erkannt werden, die mehr Ergebnisse erzeugen als von einem PHP-Skript verarbeitet werden.

Das Debug-Trace-Protokoll kann so konfiguriert werden, dass es Aufrufe der Speicherverwaltung aufzeichnet. Das ist hilfreich, um zu sehen, wann Speicher zugewiesen oder freigegeben wird. Die Größe der angeforderten Speicherabschnitte wird jedoch möglicherweise nicht aufgeführt.

Einige neuere Versionen des MySQL Native Drivers bieten die Emulation von zufälligen "Out-of-Memory"-Situationen. Diese Funktion ist nur für die C-Entwickler der Bibliothek oder die Autoren des mysqlnd-Plugins gedacht. Die entsprechenden PHP-Konfigurationseinstellungen und weitere Details sind im Quellcode zu finden. Die Funktion wird als nicht für die Allgemeinheit bestimmt betrachtet und kann jederzeit ohne vorherige Ankündigung geändert werden.

# Plugin-API des MySQL Native Drivers

## Inhaltsverzeichnis

- Vergleich der mysqlnd-Plugins mit dem MySQL-Proxy
- Bezugsquellen für die mysqlnd-Plugin-API
- Plugin-Architektur des MySQL Native Drivers
- Die Plugin-API von mysqlnd
- Einführung in die Erstellung eines mysqlnd-Plugins

Die Plugin-API des MySQL Native Drivers ist eine Komponente des MySQL Native Drivers, oder kurz `mysqlnd`. Die `mysqlnd`-Plugins arbeiten in der Schicht zwischen der PHP-Anwendung und dem MySQL-Server. Dies ist vergleichbar mit dem MySQL-Proxy. Der MySQL-Proxy arbeitet in einer Schicht zwischen einer beliebigen MySQL-Client-Anwendung, zum Beispiel einer PHP-Anwendung, und dem MySQL-Server. `Mysqlnd`-Plugins können typische MySQL-Proxy-Aufgaben wie Lastausgleich, Überwachung und Leistungsoptimierung übernehmen. Aufgrund der unterschiedlichen Architektur und des Standorts haben `mysqlnd`-Plugins einige der Nachteile von MySQL-Proxy nicht. So gibt es bei Plugins beispielsweise keinen Single Point of Failure (einzelnen Ausfallpunkt), keinen dedizierten Proxy-Server, der eingesetzt werden muss, und keine neue Programmiersprache, die erlernt werden muss (Lua).

Ein `mysqlnd`-Plugin kann als eine Erweiterung von `mysqlnd` betrachtet werden. Die Plugins können die meisten der `mysqlnd`-Funktionen abfangen. Diese Funktionen werden von den PHP-MySQL-Erweiterungen wie `ext/mysql`, `ext/mysqli` und `PDO_MYSQL` aufgerufen. Daher ist es für ein `mysqlnd`-Plugin möglich, alle von einer Client-Anwendung an diese Erweiterungen gerichteten Aufrufe abzufangen.

Auch Aufrufe von internen `mysqlnd`-Funktionen können abgefangen oder ersetzt werden. Es gibt keine Einschränkungen für die Bearbeitung von `mysqlnd`-internen Funktionstabellen. Es ist also möglich, das Ganze so zu konfigurieren, dass der Aufruf bestimmter `mysqlnd`-Funktionen durch eine Erweiterung, die `mysqlnd` verwendet, an die entsprechende Funktion im `mysqlnd`-Plugin geleitet wird. Die Möglichkeit, die internen Funktionstabellen von `mysqlnd` auf diese Weise zu manipulieren, bietet maximale Flexibilität für Plugins.

Ein `mysqlnd`-Plugin ist im Grunde eine PHP-Erweiterung, die in C geschrieben ist und die Plugin-API von `mysqlnd` verwendet (die in den MySQL Native Driver `mysqlnd` integriert ist). Plugins können für PHP-Anwendungen 100% transparent gemacht werden. Es sind keine Änderungen an den Anwendungen erforderlich, da Plugins in einer anderen Schicht arbeiten. Das `mysqlnd`-Plugin kann man sich als eine Schicht unterhalb von `mysqlnd` vorstellen.

Die folgende Liste enthält ein paar mögliche Anwendungen für `mysqlnd`-Plugins.

- Load Balancing (Lastverteilung)
  - Trennung von Lese- und Schreibvorgängen. Ein Beispiel hierfür ist die Erweiterung PECL/mysqlnd_ms (Master Slave). Diese Erweiterung trennt Lese- und Schreibanfragen für eine Replikationskonfiguration.
  - Ausfallsicherung
  - Round-Robin, Übertragung auf den am wenigsten belasteten Server
- Server-Überwachung
  - Abfrage-Protokollierung
  - Abfrage-Analyse
  - Abfrage-Überprüfung. Ein Beispiel hierfür ist die Erweiterung PECL/mysqlnd_sip (SQL Injection Protection). Diese Erweiterung prüft Abfragen und führt nur solche aus, die einem bestimmten Regelwerk entsprechen.
- Leistung
  - Zwischenspeicherung. Ein Beispiel hierfür ist die Erweiterung PECL/mysqlnd_qc (Query Cache).
  - Drosselung
  - Sharding (Aufteilung). Ein Beispiel hierfür ist die Erweiterung PECL/mysqlnd_mc (Multi Connect). Diese Erweiterung versucht, eine SELECT-Anweisung in n Teile aufzuteilen, indem sie SELECT ... LIMIT part_1, SELECT LIMIT part_n verwendet. Sie sendet die Abfragen an verschiedene MySQL-Server und führt das Ergebnis auf dem Client zusammen.

Verfügbare Plugins für den MySQL Native Driver

Es gibt bereits eine Reihe von mysqlnd-Plugins. Dazu gehören:

- PECL/mysqlnd_mc - Plugin für Mehrfachverbindungen (Multi Connect). plugin.
- PECL/mysqlnd_ms - Plugin für die Master-Slave-Konfiguration.
- PECL/mysqlnd_qc - Plugin für die Zwischenspeicherung von Abfragen (Query Cache). plugin.
- PECL/mysqlnd_pscache - Plugin für die Zwischenspeicherung von Handles für vorbereitete Anweisungen (Prepared Statement Handle Cache).
- PECL/mysqlnd_sip - Plug-in zum Schutz vor SQL-Injections.
- PECL/mysqlnd_uh - Plugin für die Benutzerverwaltung (User Handler).

## Vergleich der mysqlnd-Plugins mit dem MySQL-Proxy

Bei den `mysqlnd`-Plugins und dem MySQL-Proxy handelt es sich um verschiedene Technologien, die unterschiedliche Ansätze verwenden. Beide eignen sich für eine Vielzahl von Standardaufgaben wie Lastausgleich, Überwachung und Leistungsverbesserung. Ein wichtiger Unterschied besteht darin, dass der MySQL-Proxy mit allen MySQL-Clients funktioniert, während `mysqlnd`-Plugins spezifisch für PHP-Anwendungen sind.

Als PHP-Erweiterung wird ein `mysqlnd`-Plugin zusammen mit dem Rest von PHP auf dem PHP-Anwendungsserver installiert. Der MySQL-Proxy kann entweder auf dem PHP-Anwendungsserver laufen oder auf einem dedizierten Rechner installiert werden, um mehrere PHP-Anwendungsserver zu verwalten.

Der Einsatz des MySQL-Proxys auf dem Anwendungsserver hat zwei Vorteile:

1. Kein einzelner Ausfallpunkt
2. Einfach zu skalieren (horizontale Skalierung, Skalierung durch den Client)

Mit dem MySQL-Proxy (und den `mysqlnd`-Plugins) lassen sich auf einfache Weise Probleme lösen, die andernfalls Änderungen an bestehenden Anwendungen erfordert hätten.

Allerdings hat der MySQL-Proxy auch ein paar Nachteile:

- Es handelt sich um eine neue Komponente und Technologie, die beherrscht und implementiert werden muss.
- Er erfordert Kenntnisse in der Skriptsprache Lua.

Der MySQL-Proxy kann mit C- und Lua-Programmierung angepasst werden, wobei Lua für diesen Zweck bevorzugt wird. Für die meisten PHP-Experten ist Lua eine neu zu erlernende Sprache. Ein `mysqlnd`-Plugin kann in C geschrieben werden und mit » PECL/mysqlnd_uh ist es auch möglich, Plugins in PHP zu schreiben.

Der MySQL-Proxy läuft als Daemon - ein Hintergrundprozess. Da alle Zustände gespeichert werden können, kann der MySQL-Proxy frühere Entscheidungen abrufen. Ein `mysqlnd`-Plugin ist im Gegensatz dazu an den Lebenszyklus einer PHP-Abfrage gebunden. Der MySQL-Proxy kann auch einmalig berechnete Ergebnisse auf mehrere Anwendungsserver verteilen. Ein `mysqlnd`-Plugin müsste dazu Daten in einem persistenten Medium speichern. Zu diesem Zweck müsste ein anderer Daemon verwendet werden, z. B. Memcache. Dies verschafft dem MySQL-Proxy in diesem Fall einen Vorteil.

Der MySQL-Proxy nutzt das Wire-Protokoll. Mit dem MySQL-Proxy muss das MySQL-Client-Server-Protokoll analysiert und rekonstruiert werden (Reverse Engineering). Die Aktionen sind auf diejenigen beschränkt, die durch die Änderung des Kommunikationsprotokolls erreicht werden können. Wenn sich das Wire-Protokoll ändert (was sehr selten vorkommt), müssen auch die MySQL-Proxy-Skripte geändert werden.

`Mysqlnd`-Plugins nutzen die C-API, die den `libmysqlclient`-Client nachbildet. Diese C-API ist im Wesentlichen ein Wrapper um das MySQL-Client-Server-Protokoll, das manchmal auch als Wire-Protokoll bezeichnet wird. Sämtliche C-API-Aufrufe können abgefangen werden. Da PHP die C-API nutzt, können somit alle PHP-Aufrufe eingehängt werden, ohne dass eine Programmierung auf der Ebene des Wire-Protokolls erforderlich ist.

`Mysqlnd` implementiert das Wire-Protokoll. Plugins können daher das Kommunikationsprotokoll analysieren, rekonstruieren, ändern und sogar ersetzen. In der Regel ist dies jedoch nicht nötig.

Mit Plugins können Implementierungen erstellt werden, die zwei Ebenen verwenden (C-API und Wire-Protokoll), weshalb sie flexibler sind als der MySQL-Proxy. Wenn ein `mysqlnd`-Plugin unter Verwendung der C-API implementiert wird, sind bei späteren Änderungen am Wire-Protokoll keine Änderungen am Plugin selbst erforderlich.

## Bezugsquellen für die mysqlnd-Plugin-API

Die `mysqlnd`-Plugin-API ist Teil der PHP-Erweiterung MySQL Native Driver `ext/mysqlnd`. Die Entwicklung der `mysqlnd`-Plugin-API begann im Dezember 2009. Sie wird als Teil des PHP-Quellcode-Repositoriums entwickelt ist entweder über Git oder durch den Download eines Snapshots des Quellcodes verfügbar.

Plugin-Entwickler können die `mysqlnd`-Version ermitteln, indem sie auf `MYSQLND_VERSION` zugreifen, eine Zeichenkette im Format mysqlnd 8.3.17, oder über `MYSQLND_VERSION_ID`, eine ganze Zahl, z. B. 50007. Die Versionsnummer kann wie folgt berechnet werden:

Tabelle für die Berechnung der MYSQLND_VERSION_ID
Version (Teil) | Beispiel
--- | ---
Major*10000 | 5*10000 = 50000
Minor*100 | 0*100 = 0
Patch | 7 = 7
MYSQLND_VERSION_ID | 50007

Während der Entwicklung sollten sich Entwickler für Kompatibilitäts- und Versionstests auf die `mysqlnd`-Versionsnummer beziehen, da während des Lebenszyklus eines PHP-Entwicklungszweigs mit einer einzigen PHP-Versionsnummer mehrere Versionen von `mysqlnd` auftreten können.

## Plugin-Architektur des MySQL Native Drivers

Dieser Abschnitt bietet einen Überblick über die Plugin-Architektur von `mysqlnd`.

Überblick über den MySQL Native Driver

Vor der Entwicklung eines `mysqlnd`-Plugins ist es nützlich, ein wenig über den Aufbau von `mysqlnd` selbst zu wissen. `Mysqlnd` besteht aus den folgenden Modulen:

Das Organisationsdiagramm von mysqlnd, pro Modul
Modul-Statistiken | mysqlnd_statistics.c
--- | ---
Datenbankverbindung | mysqlnd.c
Ergebnismenge | mysqlnd_result.c
Metadaten der Ergebnismenge | mysqlnd_result_meta.c
Anweisung | mysqlnd_ps.c
Netzwerk | mysqlnd_net.c
Wire-Protokoll | mysqlnd_wireprotocol.c

Objektorientiertes Paradigma in C

Auf der Code-Ebene verwendet `mysqlnd` ein C-Pattern, um die Objektorientierung zu implementieren.

In C wird ein Objekt mittels `struct` beschrieben. Die Mitglieder dieser Struktur sind die Eigenschaften des Objekts. Die Strukturmitglieder, die auf Funktionen verweisen, stellen die Methoden dar.

Im Gegensatz zu anderen Sprachen wie C++ oder Java gibt es im objektorientierten Paradigma von C keine festen Regeln für die Vererbung. Es gibt jedoch einige Konventionen, die befolgt werden müssen und auf die später eingegangen wird.

Der PHP-Lebenszyklus

Der Lebenszyklus von PHP besteht aus 2 grundlegenden Zyklen:

- Der Start- und Shutdown-Zyklus der PHP-Engine
- Der Zyklus einer Anfrage

Wenn die PHP-Engine startet, ruft sie für jede registrierte Erweiterung die Funktion für die Modulinitialisierung (MINIT) auf. Dies ermöglicht es jedem Modul, Variablen zu definieren und Ressourcen zuzuweisen, die während der gesamten Lebensdauer des Prozesses der PHP-Engine vorhanden sind. Wenn die PHP-Engine herunterfährt, ruft sie für jede Erweiterung die Funktion für das Herunterfahren des Moduls (MSHUTDOWN) auf.

Während der Lebensdauer der PHP-Engine erhält sie eine Reihe von Anfragen. Jede Anfrage löst einen neuen Lebenszyklus aus. Bei jeder Anfrage ruft die PHP-Engine die Anfrage-Initialisierungsfunktion der jeweiligen Erweiterung auf. Die Erweiterung kann alle für die Bearbeitung der Anfrage erforderlichen Variablen definieren und Ressourcen zuweisen. Am Ende des Anfragezyklus ruft die Engine für jede Erweiterung die Funktion zum Herunterfahren der Anfrage (RSHUTDOWN) auf, damit die Erweiterung alle erforderlichen Aufräumarbeiten durchführen kann.

Wie ein Plugin funktioniert

Ein `mysqlnd`-Plugin funktioniert, indem es die Aufrufe an `mysqlnd` abfängt, die von Erweiterungen stammen, die `mysqlnd` verwenden. Dies wird dadurch erreicht, dass die Funktionstabelle von `mysqlnd` abgerufen, gesichert und durch eine eigene Funktionstabelle ersetzt wird, die die Funktionen des Plugins nach Bedarf aufruft.

Der folgende Code zeigt, wie die Funktionstabelle von `mysqlnd` ersetzt wird:

    /* ein Ort zum Speichern der ursprünglichen Funktionstabelle */
    struct st_mysqlnd_conn_methods org_methods;

    void minit_register_hooks(TSRMLS_D) {
      /* die aktive Funktionstabelle */
      struct st_mysqlnd_conn_methods * current_methods
        = mysqlnd_conn_get_methods();

      /* Sicherung der ursprünglichen Funktionstabelle */
      memcpy(&org_methods, current_methods,
        sizeof(struct st_mysqlnd_conn_methods);

      /* Installation der neuen Methoden */
      current_methods->query = MYSQLND_METHOD(my_conn_class, query);
    }

Die Bearbeitung der Tabelle der Verbindungsfunktionen muss während der Modulinitialisierung (MINIT) erfolgen. Die Funktionstabelle ist eine gemeinsam genutzte globale Ressource. In einer Multi-Thread-Umgebung mit einem TSRM-Build führt die Bearbeitung einer gemeinsam genutzten globalen Ressource während der Verarbeitung einer Anfrage mit ziemlicher Sicherheit zu Konflikten.

> Hinweis: Bei der Bearbeitung der Funktionstabelle von `mysqlnd` sollte keine Logik mit fester Größe verwendet werden: Neue Methoden könnten am Ende der Funktionstabelle hinzugefügt werden. Die Funktionstabelle kann sich in der Zukunft jederzeit ändern.

Aufrufen von Elternmethoden

Wenn die ursprüngliche Funktionstabelle gesichert wird, können die ursprünglichen Einträge - die Elternmethoden - weiterhin aufgerufen werden.

In einigen Fällen, z. B. bei `Connection::stmt_init()`, ist es unerlässlich, die Elternmethode aufzurufen, bevor weitere Aktionen in der abgeleiteten Methode erfolgen.

    MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn,
      const char *query, unsigned int query_len TSRMLS_DC) {

      php_printf("my_conn_class::query(query = %s)\n", query);

      query = "SELECT 'query rewritten' FROM DUAL";
      query_len = strlen(query);

      return org_methods.query(conn, query, query_len); /* return with call to parent */
    }

Erweitern von Eigenschaften

Ein `mysqlnd`-Objekt wird durch eine C-Struktur (struct) dargestellt. Es ist nicht möglich, einer C-Struktur zur Laufzeit ein Mitglied hinzuzufügen. Benutzer von `mysqlnd`-Objekten können nicht einfach Eigenschaften zu den Objekten hinzufügen.

Beliebige Daten (Eigenschaften) können zu einem `mysqlnd`-Objekt hinzugefügt werden, indem eine geeignete Funktion der `mysqlnd_plugin_get_plugin_<object>_data()`-Familie verwendet wird. Wenn ein Objekt zugewiesen wird, reserviert `mysqlnd` am Ende des Objekts Speicherplatz für einen `void *`-Zeiger auf beliebige Daten. `mysqlnd` reserviert den Platz für einen `void *`-Zeiger pro Plugin.

Die folgende Tabelle zeigt, wie die Position des Zeigers für ein bestimmtes Plugin berechnet werden kann:

Berechnen eines Zeigers für mysqlnd
Speicheradresse | Inhalt
--- | ---
0 | Beginn der C-Struktur des mysqlnd-Objekts
n | Ende der C-Struktur des mysqlnd-Objekts
n + (m x sizeof(void*)) | void* zu den Objektdaten des m-ten Plugins

Wenn geplant ist, Unterklassen für einen der Konstruktoren des `mysqlnd`-Objekts zu erstellen, was erlaubt ist, muss dies unbedingt bedacht werden!

Der folgende Code zeigt, wie Eigenschaften erweitert werden:

    /* alle Daten, die zugeordnet werden sollen */
    typedef struct my_conn_properties {
      unsigned long query_counter;
    } MY_CONN_PROPERTIES;

    /* die Plugin-ID */
    unsigned int my_plugin_id;

    void minit_register_hooks(TSRMLS_D) {
      /* erhalten einer eindeutigen Plugin-ID */
      my_plugin_id = mysqlnd_plugin_register();
      /* snip - siehe Extending Connection: methods */
    }

    static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) {
      MY_CONN_PROPERTIES** props;
      props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data(
        conn, my_plugin_id);
      if (!props || !(*props)) {
        *props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent);
        (*props)->query_counter = 0;
      }
      return props;
    }

Der Plugin-Entwickler ist für die Verwaltung des Speichers verantwortlich, der für die Plugin-Daten verwendet wird.

Es wird empfohlen, für die Daten von Plugins den Speicherallokator von `mysqlnd` zu verwenden. Diese Funktionen werden nach dem Schema `mnd_*loc()` benannt. Der `mysqlnd`-Allokator hat einige nützliche Eigenschaften, zum Beispiel die Möglichkeit, einen Debug-Allokator in einem Nicht-Debug-Build zu benutzen.

Wann und wie eine Unterklasse erstellt wird
| Wann soll die Unterklasse erstellt werden? | Hat jede Instanz ihre eine eigene Funktionstabelle? | Wie wird die Unterklasse erstellt?
--- | --- | --- | ---
Verbindung (MYSQLND) | MINIT | Nein | mysqlnd_conn_get_methods()
Ergebnismenge (MYSQLND_RES) | MINIT oder später | Ja | mysqlnd_result_get_methods() oder Manipulation der Funktionstabelle der Objektmethoden
Metadaten der Ergebnismenge (MYSQLND_RES_METADATA) | MINIT | Nein | mysqlnd_result_metadata_get_methods()
Anweisung (MYSQLND_STMT) | MINIT | Nein | mysqlnd_stmt_get_methods()
Netzwerk (MYSQLND_NET) | MINIT oder später | Ja | mysqlnd_net_get_methods() oder Manipulation der Funktionstabelle der Objektmethoden
Wire-Protokoll (MYSQLND_PROTOCOL) | MINIT oder später | Ja | mysqlnd_protocol_get_methods() oder Manipulation der Funktionstabelle der Objektmethoden

Nach MINIT darf die Funktionstabelle nicht mehr manipuliert werden, wenn es nach der obigen Tabelle nicht erlaubt ist.

Einige Klassen enthalten einen Zeiger auf die Funktionstabelle der Methoden. Alle Instanzen einer solchen Klasse teilen sich dieselbe Funktionstabelle. Um Chaos zu vermeiden, insbesondere in Umgebungen mit Threads, dürfen solche Funktionstabellen nur während MINIT manipuliert werden.

Andere Klassen verwenden Kopien einer gemeinsam genutzten globalen Funktionstabelle. Die Kopie der Funktionstabelle der Klasse wird zusammen mit dem Objekt erstellt. Jedes Objekt verwendet seine eigene Funktionstabelle. Dadurch ergeben sich zwei Möglichkeiten: Zum einen kann die Standard-Funktionstabelle eines Objekts während MINIT manipuliert werden, zum anderen können die Methoden eines Objekts zusätzlich angepasst werden, ohne dass sich dies auf andere Instanzen derselben Klasse auswirkt.

Der Vorteil der gemeinsam genutzten Funktionstabellen ist die verbesserte Leistung. Das liegt daran, dass es nicht nötig ist, eine Funktionstabelle für jedes einzelne Objekt zu kopieren.

Status des Konstruktors
Typ | Zuweisung, Konstruktion, Zurücksetzen | Kann geändert werden? | Aufgerufen von
--- | --- | --- | ---
Verbindung (MYSQLND) | mysqlnd_init() | Nein | mysqlnd_connect()
Ergebnismenge (MYSQLND_RES) | Zuweisung: Connection::result_init() Zurücksetzen und Neuinitialisierung während: Result::use_result() Result::store_result | Ja, aber die Elternmethode aufrufen! | Connection::list_fields() Statement::get_result() Statement::prepare() (nur Metadaten) Statement::resultMetaData()
Metadaten der Ergebnismenge (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Ja, aber die Elternmethode aufrufen! | Result::read_result_metadata()
Anweisung (MYSQLND_STMT) | Connection::stmt_init() | Ja, aber die Elternmethode aufrufen! | Connection::stmt_init()
Netzwerk (MYSQLND_NET) | mysqlnd_net_init() | Nein | Connection::init()
Wire-Protokoll (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | Nein | Connection::init()

Es wird dringend empfohlen, einen Konstruktor nicht vollständig zu ersetzen. Die Konstruktoren führen Speicherzuweisungen durch, die für die API des `mysqlnd`-Plugins und die Objektlogik von `mysqlnd` unerlässlich sind. Wenn ein Entwickler die Warnungen ignoriert und darauf besteht, die Konstruktoren einzuhängen, sollte er zumindest den übergeordneten Konstruktor aufrufen, bevor er etwas mit dem Konstruktor tut.

Ungeachtet aller Warnungen kann es nützlich sein, Konstruktoren zu vererben. Konstruktoren sind der perfekte Ort, um die Funktionstabellen von Objekten zu ändern, die nicht gemeinsam genutzte Objekttabellen (z. B. Ergebnismenge, Netzwerk, Wire-Protokoll) haben.

Status des Destruktors
Typ | Muss die abgeleitete Methode die Elternmethode aufrufen? | Destruktor
--- | --- | ---
Verbindung | ja, nachdem die Methode ausgeführt wurde | free_contents(), end_psession()
Ergebnismenge | ja, nachdem die Methode ausgeführt wurde | free_result()
Metadaten der Ergebnismenge | ja, nachdem die Methode ausgeführt wurde | free()
Anweisung | ja, nachdem die Methode ausgeführt wurde | dtor(), free_stmt_content()
Netzwerk | ja, nachdem die Methode ausgeführt wurde | free()
Wire-Protokoll | ja, nachdem die Methode ausgeführt wurde | free()

Der Destruktor ist der geeignete Ort, um Ressourcen freizugeben, die von `mysqlnd_plugin_get_plugin_<object>_data()`-Eigenschaften belegt sind.

Die aufgeführten Destruktoren entsprechen nicht unbedingt der eigentlichen `mysqlnd`-Methode, die das Objekt selbst freigibt. Dennoch sind sie der bestmögliche Ort, um die Plugin-Daten einzuhängen und freizugeben. Wie bei den Konstruktoren können die Methoden vollständig ersetzt werden, was jedoch nicht empfohlen wird. Wenn in der obigen Tabelle mehrere Methoden aufgeführt sind, müssen alle aufgeführten Methoden eingehängt und die Plugin-Daten in der Methode freigegeben werden, die von `mysqlnd` zuerst aufgerufen wird.

Die empfohlene Methode für Plugins ist, einfach die Methoden einzuhängen, den Speicher freizugeben und unmittelbar danach die übergeordnete Implementierung aufzurufen.

## Die Plugin-API von mysqlnd

Es folgt eine Liste der Funktionen, die in der Plugin-API von `mysqlnd` zur Verfügung stehen:

- mysqlnd_plugin_register()
- mysqlnd_plugin_count()
- mysqlnd_plugin_get_plugin_connection_data()
- mysqlnd_plugin_get_plugin_result_data()
- mysqlnd_plugin_get_plugin_stmt_data()
- mysqlnd_plugin_get_plugin_net_data()
- mysqlnd_plugin_get_plugin_protocol_data()
- mysqlnd_conn_get_methods()
- mysqlnd_result_get_methods()
- mysqlnd_result_meta_get_methods()
- mysqlnd_stmt_get_methods()
- mysqlnd_net_get_methods()
- mysqlnd_protocol_get_methods()

Es gibt keine formale Definition dafür, was ein Plugin ist und wie ein Plugin-Mechanismus funktioniert.

Folgende Komponenten werden häufig in Plugin-Mechanismen verwendet:

- Ein Plugin-Manager
- Eine Plugin-API
- Anwendungsdienste (oder Module)
- Anwendungsdienst-APIs (oder Modul-APIs)

Das Plugin-Konzept von `mysqlnd` nutzt diese Merkmale und zeichnet sich zudem durch eine offene Architektur aus.

Keine Einschränkungen

Ein Plugin hat uneingeschränkten Zugriff auf die inneren Abläufe von `mysqlnd`. Es gibt keine Sicherheitsbeschränkungen oder Einschränkungen. Alles kann überschrieben werden, um nützliche oder schädliche Algorithmen zu implementieren. Es wird empfohlen, nur Plugins aus einer vertrauenswürdigen Quelle einzusetzen.

Wie bereits erwähnt, können Plugins Zeiger beliebig verwenden. Diese Zeiger sind in keiner Weise eingeschränkt und können auf die Daten eines anderen Plugins zeigen. Mit einer einfachen Offset-Berechnung können die Daten eines anderen Plugins gelesen werden.

Es wird empfohlen, kooperative Plugins zu schreiben und immer die Elternmethode aufzurufen. Die Plugins sollten immer mit `mysqlnd` selbst zusammenarbeiten.

Zum Thema: Ein Beispiel für Verkettung und Kooperation
Erweiterung | mysqlnd.query()-Zeiger | Aufrufstapel (Call Stack) bei Aufruf der Elternmethode
--- | --- | ---
ext/mysqlnd | mysqlnd.query() | mysqlnd.query
ext/mysqlnd_cache | mysqlnd_cache.query() | mysqlnd_cache.query() mysqlnd.query
ext/mysqlnd_monitor | mysqlnd_monitor.query() | mysqlnd_monitor.query() mysqlnd_cache.query() mysqlnd.query

In diesem Szenario werden ein Cache-Plugin (`ext/mysqlnd_cache`) und ein Überwachungs-Plugin (`ext/mysqlnd_monitor`) geladen. Beide sind Unterklassen von `Connection::query()`. Die Registrierung der Plugins erfolgt während `MINIT` gemäß der zuvor gezeigten Logik. PHP ruft Erweiterungen standardmäßig in alphabetischer Reihenfolge auf. Die Plugins wissen nichts voneinander und definieren keine Abhängigkeiten von den Erweiterungen.

Standardmäßig rufen die Plugins die übergeordnete Implementierung der Abfragemethode in ihrer abgeleiteten Version der Methode auf.

Zusammenfassung des Verhaltens einer PHP-Erweiterung

Die folgende Zusammenfassung zeigt, was passiert, wenn das Beispiel-Plugin `ext/mysqlnd_plugin` verwendet wird, das die C-Plugin-API von `mysqlnd` für PHP verfügbar macht:

- Jede PHP-Anwendung, die MySQL verwendet, versucht, eine Verbindung zu 192.168.2.29 herzustellen
- Die PHP-Anwendung verwendet entweder `ext/mysql`, `ext/mysqli` oder `PDO_MYSQL`. Alle drei PHP-MySQL-Erweiterungen verwenden `mysqlnd`, um die Verbindung zu 192.168.2.29 herzustellen.
- `Mysqlnd` ruft seine Verbindungsmethode auf, die von `ext/mysqlnd_plugin` abgeleitet wurde.
- `ext/mysqlnd_plugin` ruft den vom Benutzer registrierten Userspace-Hook, die Methode `proxy::connect()`, auf.
- Dieser Userspace-Hook ändert die IP-Adresse des Hosts, zu dem eine Verbindung aufgebaut werden soll, von 192.168.2.29 auf 127.0.0.1 und gibt die von `parent::connect()` hergestellte Verbindung zurück.
- `ext/mysqlnd_plugin` bewirkt dasselbe wie `parent::connect(127.0.0.1)`, indem es die ursprüngliche `mysqlnd`-Methode aufruft, um eine Verbindung herzustellen.
- `ext/mysqlnd` stellt die Verbindung her und gibt sie an `ext/mysqlnd_plugin` zurück, das sie seinerseits zurückgibt.
- Unabhängig davon, welche PHP-MySQL-Erweiterung die Anwendung verwendet, erhält sie eine Verbindung zu 127.0.0.1. Die PHP-MySQL-Erweiterung übergibt die Kontrolle wieder an die PHP-Anwendung. Der Zyklus ist geschlossen.

## Einführung in die Erstellung eines mysqlnd-Plugins

Es ist wichtig zu bedenken, dass ein `mysqlnd`-Plugin selbst eine PHP-Erweiterung ist.

Der folgende Code zeigt die grundlegende Struktur der MINIT-Funktion, die in einem typischen `mysqlnd`-Plugin verwendet wird:

    /* my_php_mysqlnd_plugin.c */

     static PHP_MINIT_FUNCTION(mysqlnd_plugin) {
      /* Globals, ini-Einträge, Ressourcen, Klassen */

      /* Registrieren des mysqlnd-Plugins */
      mysqlnd_plugin_id = mysqlnd_plugin_register();

      conn_m = mysqlnd_get_conn_methods();
      memcpy(org_conn_m, conn_m,
        sizeof(struct st_mysqlnd_conn_methods));

      conn_m->query = MYSQLND_METHOD(mysqlnd_plugin_conn, query);
      conn_m->connect = MYSQLND_METHOD(mysqlnd_plugin_conn, connect);
    }

    /* my_mysqlnd_plugin.c */

     enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, query)(/* ... */) {
      /* ... */
    }
    enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, connect)(/* ... */) {
      /* ... */
    }

Analyse der Aufgaben: von C zum Userspace

     class proxy extends mysqlnd_plugin_connection {
      public function connect($host, ...) { .. }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

Ablauf:

1. PHP: Benutzer registriert den Plugin-Callback
2. PHP: Benutzer ruft eine beliebige PHP-MySQL-API auf, um sich mit MySQL zu verbinden
3. C: ext/*mysql* ruft die mysqlnd-Methode auf
4. C: mysqlnd endet in ext/mysqlnd_plugin

5. C: ext/mysqlnd_plugin

   1. Ruft einen benutzerdefinierten Callback auf
   2. oder die ursprüngliche `mysqlnd`-Methode, wenn der Userspace-Callback nicht definiert ist

Folgende Aufgaben sind dafür auszuführen:

1. In C eine Klasse namens "mysqlnd_plugin_connection" erstellen
2. Ein Proxy-Objekt mittels "mysqlnd_plugin_set_conn_proxy()" annehmen und registrieren
3. Userspace-Proxy-Methoden aus C aufrufen (Optimierung - zend_interfaces.h)

Die Methoden von Userspace-Objekten können entweder mittels `call_user_function()` aufgerufen werden oder auf einer Ebene näher an der Zend Engine mittels `zend_call_method()`.

Optimierung: Aufruf von Methoden aus C mit zend_call_method

Der folgende Codeschnipsel zeigt den Prototyp für die Funktion `zend_call_method` und stammt aus zend_interfaces.h.

     ZEND_API zval* zend_call_method(
      zval **object_pp, zend_class_entry *obj_ce,
      zend_function **fn_proxy, char *function_name,
      int function_name_len, zval **retval_ptr_ptr,
      int param_count, zval* arg1, zval* arg2 TSRMLS_DC
    );

Die Zend-API erlaubt nur zwei Parameter. Eventuell werden mehr benötigt, zum Beispiel:

     enum_func_status (*func_mysqlnd_conn__connect)(
      MYSQLND *conn, const char *host,
      const char * user, const char * passwd,
      unsigned int passwd_len, const char * db,
      unsigned int db_len, unsigned int port,
      const char * socket, unsigned int mysql_flags TSRMLS_DC
    );

Um dieses Problem zu umgehen, muss eine Kopie von `zend_call_method()` erzeugt werden, die mit zusätzlichen Parametern versehen werden kann. Dafür kann eine Reihe von `MY_ZEND_CALL_METHOD_WRAPPER`-Makros erstellt werden.

Aufruf des PHP-Userspaces

Dieser Codeschnipsel zeigt die optimierte Methode für den Aufruf einer Userspace-Funktion von C aus:

    /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class,connect)(
      MYSQLND *conn, const char *host /* ... */ TSRMLS_DC) {
      enum_func_status ret = FAIL;
      zval * global_user_conn_proxy = fetch_userspace_proxy();
      if (global_user_conn_proxy) {
        /* Aufrufen eines Userspace-Proxys */
        ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/);
      } else {
        /* oder die ursprüngliche mysqlnd-Methode = nichts tun, transparent sein */
        ret = org_methods.connect(conn, host, user, passwd,
              passwd_len, db, db_len, port,
              socket, mysql_flags TSRMLS_CC);
      }
      return ret;
    }

Aufruf des Userspaces: einfache Argumente

    /* my_mysqlnd_plugin.c */

     MYSQLND_METHOD(my_conn_class,connect)(
      /* ... */, const char *host, /* ...*/) {
      /* ... */
      if (global_user_conn_proxy) {
        /* ... */
        zval* zv_host;
        MAKE_STD_ZVAL(zv_host);
        ZVAL_STRING(zv_host, host, 1);
        MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_host /*, ...*/);
        zval_ptr_dtor(&zv_host);
        /* ... */
      }
      /* ... */
    }

Aufruf des Userspaces: Strukturen als Argumente

    /* my_mysqlnd_plugin.c */

    MYSQLND_METHOD(my_conn_class, connect)(
      MYSQLND *conn, /* ...*/) {
      /* ... */
      if (global_user_conn_proxy) {
        /* ... */
        zval* zv_conn;
        ZEND_REGISTER_RESOURCE(zv_conn, (void *)conn, le_mysqlnd_plugin_conn);
        MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_conn, zv_host /*, ...*/);
        zval_ptr_dtor(&zv_conn);
        /* ... */
      }
      /* ... */
    }

Bei vielen `mysqlnd`-Methoden ist das erste Argument ein C-"Objekt". Zum Beispiel ist das erste Argument der Methode connect() ein Zeiger auf `MYSQLND`. Die Struktur MYSQLND stellt ein `mysqlnd`-Verbindungsobjekt dar.

Der Zeiger auf das `mysqlnd`-Verbindungsobjekt kann mit einem Standard-I/O-Dateihandle verglichen werden. Genau wie ein Standard-I/O-Dateihandle muss ein `mysqlnd`-Verbindungsobjekt mit Hilfe einer PHP-Variablen vom Typ Ressource mit dem Userspace verbunden werden.

Von C zum Userspace und zurück

     class proxy extends mysqlnd_plugin_connection {
      public function connect($conn, $host, ...) {
        /* vor der Implementierung ("pre"-Hook) */
        printf("Verbinden mit dem Host '%s'\n", $host);
        debug_print_backtrace();
        return parent::connect($conn);
      }

      public function query($conn, $query) {
        /* nach der Implementierung ("post"-Hook) */
        $ret = parent::query($conn, $query);
        printf("Abfrage = '%s'\n", $query);
        return $ret;
      }
    }
    mysqlnd_plugin_set_conn_proxy(new proxy());

PHP-Benutzer müssen die Möglichkeit haben, die übergeordnete Implementierung einer überschriebenen Methode aufzurufen.

Durch Vererbung ist es möglich, nur ausgewählte Methoden zu "verfeinern", und man kann wählen, wann der eigene Code ausgeführt werden soll, vor oder nach der übergeordneten Methode ("pre"- oder "post"-Hook).

Eingebaute Klasse: mysqlnd_plugin_connection::connect()

    /*  my_mysqlnd_plugin_classes.c */

     PHP_METHOD("mysqlnd_plugin_connection", connect) {
      /* ... vereinfacht! ... */
      zval* mysqlnd_rsrc;
      MYSQLND* conn;
      char* host; int host_len;
      if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "rs",
        &mysqlnd_rsrc, &host, &host_len) == FAILURE) {
        RETURN_NULL();
      }
      ZEND_FETCH_RESOURCE(conn, MYSQLND* conn, &mysqlnd_rsrc, -1,
        "Mysqlnd-Verbindung", le_mysqlnd_plugin_conn);
      if (PASS == org_methods.connect(conn, host, /* simplified! */ TSRMLS_CC))
        RETVAL_TRUE;
      else
        RETVAL_FALSE;
    }

- Übersicht
- Installation
- Laufzeit-Konfiguration
- Inkompatibilitäten
- Persistente (dauerhafte) Verbindungen
- Statistiken
- Hinweise
- Speicherverwaltung
- Plugin-API des MySQL Native Drivers
  - Vergleich der mysqlnd-Plugins mit dem MySQL-Proxy
  - Bezugsquellen für die mysqlnd-Plugin-API
  - Plugin-Architektur des MySQL Native Drivers
  - Die Plugin-API von mysqlnd
  - Einführung in die Erstellung eines mysqlnd-Plugins

- Übersicht über die PHP-Treiber für MySQL
  - Übersicht über die Terminologie
  - Auswahl einer API
  - Auswahl einer Bibliothek
  - Konzepte
- Mysqli — MySQL Improved Extension
  - Übersicht
  - Kurzanleitung für den schnellen Einstieg
  - Installation/Konfiguration
  - Die Erweiterung mysqli und persistente (beständige) Verbindungen
  - Vordefinierte Konstanten
  - Hinweise
  - Die Funktionen der Erweiterung MySQLi im Überblick
  - mysqli — Die Klasse mysqli
  - mysqli_stmt — Die Klasse mysqli_stmt
  - mysqli_result — Die Klasse mysqli_result
  - mysqli_driver — Die Klasse mysqli_driver
  - mysqli_warning — Die Klasse mysqli_warning
  - mysqli_sql_exception — Die Klasse mysqli_sql_exception
  - Aliase und veraltete MySQLi Funktionen
  - Changelog
- Mysql_xdevapi
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Changelog
  - Beispiele
  - Mysql_xdevapi-Funktionen
  - mysql_xdevapi\BaseResult — Die BaseResult-Schnittstelle
  - mysql_xdevapi\Client — Die Klasse Client
  - mysql_xdevapi\Collection — Die Klasse Collection
  - mysql_xdevapi\CollectionAdd — Die Klasse CollectionAdd
  - mysql_xdevapi\CollectionFind — Die Klasse CollectionFind
  - mysql_xdevapi\CollectionModify — Die Klasse CollectionModify
  - mysql_xdevapi\CollectionRemove — Die Klasse CollectionRemove
  - mysql_xdevapi\ColumnResult — Die Klasse ColumnResult
  - mysql_xdevapi\CrudOperationBindable — Die CrudOperationBindable-Schnittstelle
  - mysql_xdevapi\CrudOperationLimitable — Die CrudOperationLimitable-Schnittstelle
  - mysql_xdevapi\CrudOperationSkippable — Die CrudOperationSkippable-Schnittstelle
  - mysql_xdevapi\CrudOperationSortable — Die CrudOperationSortable-Schnittstelle
  - mysql_xdevapi\DatabaseObject — Die DatabaseObject-Schnittstelle
  - mysql_xdevapi\DocResult — Die Klasse DocResult
  - mysql_xdevapi\Exception — Die Klasse Exception
  - mysql_xdevapi\Executable — Die Executable-Schnittstelle
  - mysql_xdevapi\ExecutionStatus — Die Klasse ExecutionStatus
  - mysql_xdevapi\Expression — Die Klasse Expression
  - mysql_xdevapi\Result — Die Klasse Result
  - mysql_xdevapi\RowResult — Die Klasse RowResult
  - mysql_xdevapi\Schema — Die Klasse Schema
  - mysql_xdevapi\SchemaObject — Die SchemaObject-Schnittstelle
  - mysql_xdevapi\Session — Die Klasse Session
  - mysql_xdevapi\SqlStatement — Die Klasse SqlStatement
  - mysql_xdevapi\SqlStatementResult — Die Klasse SqlStatementResult
  - mysql_xdevapi\Statement — Die Klasse Statement
  - mysql_xdevapi\Table — Die Klasse Table
  - mysql_xdevapi\TableDelete — Die Klasse TableDelete
  - mysql_xdevapi\TableInsert — Die Klasse TableInsert
  - mysql_xdevapi\TableSelect — Die Klasse TableSelect
  - mysql_xdevapi\TableUpdate — Die Klasse TableUpdate
  - mysql_xdevapi\Warning — Die Klasse Warning
- MySQL (Original) — Ursprüngliche MySQL API
  - Installation/Konfiguration
  - Changelog
  - Vordefinierte Konstanten
  - Beispiele
  - MySQL Funktionen
- Mysqlnd — MySQL Native Driver
  - Übersicht
  - Installation
  - Laufzeit-Konfiguration
  - Inkompatibilitäten
  - Persistente (dauerhafte) Verbindungen
  - Statistiken
  - Hinweise
  - Speicherverwaltung
  - Plugin-API des MySQL Native Drivers

# Oracle OCI8

# Einführung

Warnung

Diese Erweiterung ist seit PHP 8.4.0 UNBUNDLED (entbündelt).

Diese Funktionen ermöglichen den Zugriff auf Oracle-Datenbanken. Sie unterstützen SQL- und PL/SQL-Anweisungen. Zu den grundlegenden Funktionen gehören die Transaktionskontrolle, die Bindung von PHP-Variablen an Oracle-Platzhalter und die Unterstützung für Large Object Typen (LOB) und Sammlungen. Die Skalierbarkeitsfunktionen von Oracle wie Database Resident Connection Pooling (DRCP) und Ergebnis-Caching werden ebenfalls unterstützt.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Testing
- Laufzeit-Konfiguration

## Anforderungen

OCI8 3.0 is included with PHP 8. It is also available from » PECL. For PHP 7, use OCI8 2.2 from » PECL. OCI8 requires Oracle 10g or later Oracle client libraries.

If the Oracle Database is on the same machine as PHP, the database software already contains the necessary libraries and header files. When PHP is on a different machine, use the free » Oracle Instant Client libraries.

To use Oracle Instant Client, install the `Basic` or `Basic Light` Oracle Instant Client ZIP file, RPM package, or DMG package. When building OCI8 from source code, also install the Instant Client `SDK`.

You must run PHP with the same, or a more recent, version of the Oracle libraries that OCI8 was built with.

> Hinweis:

> Oracle's standard client-server network interoperability allows connections between different versions of Oracle Client and Oracle Database. For certified configurations see Oracle Support's Doc ID 207303.1. In summary, Oracle Client 19, 18 and 12.2 can connect to Oracle Database 11.2 or greater. Oracle Client 12.1 can connect to Oracle Database 10.2 or greater. Oracle Client 11.2 can connect to Oracle Database 9.2 or greater.

> Hinweis:

> Full OCI8 feature support is only available when using the most recent versions of the Oracle client libraries and database.

## Installation

## Configuring PHP with OCI8

Review the previous Requirements section before configuring OCI8.

Before starting the web server, OCI8 typically requires several Oracle environment variables (see below) to locate libraries, point to configuration files, and set some basic properties such as the character set used by Oracle libraries. The variables must be set before any PHP process starts.

The PHP binary must link with the same, or more recent, major version of Oracle libraries as it was configured with. For example, if you build OCI8 with Oracle 19 libraries, then PHP should also be deployed and run with Oracle 19 libraries. PHP applications can connect to other versions of Oracle Database, since Oracle has client-server cross-version compatibility.

## Installing OCI8 from PECL Using the pecl Command

The OCI8 extension can be added to an existing PHP installation by using the » PECL repository.

- If you are behind a firewall, set PEAR's proxy, for example:

      pear config-set http_proxy http://my-proxy.example.com:80/

- Run

      pecl install oci8

  For PHP 7, use `pecl install oci8-2.2.0`

- When prompted, enter either the value of `$ORACLE_HOME`, or `instantclient,/path/to/instant/client/lib`.

  Note: Do not enter variable names like `$ORACLE_HOME` or `$HOME` because `pecl` will not expand them. Instead, enter an expanded path, for example `/opt/oracle/product/19c/dbhome_1` or `instantclient,/Users/myname/Downloads/instantclient_19_8`

- If you get an error `oci8_dtrace_gen.h: No such file or directory`, it means PHP was built with DTrace Dynamic Tracing enabled. Install using:

      $ export PHP_DTRACE=yes
      $ pecl install oci8

- Edit your php.ini file and add the line:

      extension=oci8.so

  Make sure the php.ini directive extension_dir is set to the directory that oci8.so was installed in.

## Installing OCI8 from PECL Using phpize

To install OCI8 on an existing PHP installation when the `pecl` command is not available, manually download the » PECL OCI8 package, e.g. oci8-3.0.0.tgz.

- Extract the package:

      tar -zxf oci8-3.0.0.tgz
      cd oci8-3.0.0

- Prepare the package:

      phpize

- Configure the package, either using `$ORACLE_HOME` or Instant Client

      ./configure -with-oci8=shared,$ORACLE_HOME

  or

      ./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib

- Install the package:

      make install

- If you get an error `oci8_dtrace_gen.h: No such file or directory`, it means PHP was built with DTrace Dynamic Tracing enabled. Re-run the `configure` and `make` commands after setting this environment variable:

      $ export PHP_DTRACE=yes

- Edit your php.ini file and add the line:

      extension=oci8.so

  Make sure the php.ini directive extension_dir is set to the directory that oci8.so was installed in.

## Installing OCI8 as a Shared Extension when Building PHP

If you are building PHP from source code, the configuration `shared` option can be used to build OCI8 as a shared library that can be dynamically loaded into PHP. Building a shared extension allows OCI8 to be upgraded easily without impacting the rest of PHP.

Configure OCI8 using one of the following configure options.

- If using the free » Oracle Instant Client libraries, then do:

      ./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib

  If Instant Client 12.2 (or earlier) is installed from ZIP files, make sure to create the library symbolic link first, for example `ln -s libclntsh.so.12.1 libclntsh.so`.

  If using an RPM-based installation of Oracle Instant Client, the configure line will look like this:

      ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib

  For example, --with-oci8=shared,instantclient,/usr/lib/oracle/19.9/client/lib

- If using an Oracle database or full Oracle Client installation then do:

      ./configure --with-oci8=shared,$ORACLE_HOME

  Make sure the web server user (`nobody`, `www`) has access to the libraries, initialization files and tnsnames.ora (if used) under the `$ORACLE_HOME` directory. With Oracle 10gR2, you may need to run the $ORACLE_HOME/install/changePerm.sh utility to give directory access.

After configuration, follow the usual PHP building procedure, e.g. make install. The OCI8 shared extension oci8.so library will be created. It may need to be manually moved to the PHP extension directory, specified by the extension_dir option in your php.ini file.

To complete installation of OCI8, edit php.ini and add the line:

    extension=oci8.so

## Installing OCI8 as a Statically Compiled Extension when Building PHP

If you are building PHP from source code, you can configure PHP to include OCI8 as a static extension using one of the following configure options.

- If using Oracle Instant Client, then do:

      ./configure --with-oci8=instantclient,/path/to/instant/client/lib

- If using an Oracle database or full Oracle Client installation then do:

      ./configure --with-oci8=$ORACLE_HOME

After configuration, follow the usual PHP building procedure, e.g. make install. After successful compilation, you do not need to add oci8.so to php.ini. No additional build steps are required.

## Installing OCI8 on Windows

The OCI8 extension can be added to an existing PHP installation by using the DLLs from » PECL repository or the libraries in your PHP installation's `ext` directory.

With Oracle 12c (or later) libraries, uncomment one of the php.ini lines `extension=php_oci8_12c.dll` or `extension=php_oci8_11g.dll` or `extension=php_oci8.dll`. Only one of these DLLs may be enabled at a time. DLLs with higher versions may contain more functionality. Not all DLLs may be available for all versions of PHP. Make sure extension_dir is set to the directory containing the PHP extension DLLs.

If using Instant Client, set the system PATH environment variable to the Oracle library directory.

## Setting the Oracle Environment

Before using this extension, make sure that the Oracle environment variables are properly set for the web daemon user. If your web server is automatically started at boot time then make sure that the boot-time environment is also configured correctly.

> Hinweis:

> Do not set Oracle environment variables using putenv() in a PHP script because Oracle libraries may be loaded and initialized before your script runs. Variables set with putenv() may then cause conflicts, crashes, or unpredictable behavior. Some functions may work but others might give subtle errors. The variables should be set up before the web server is started.

On Red Hat Linux and variants, export variables at the end of /etc/sysconfig/httpd. Other systems with Apache 2 may use an envvars script in the Apache bin directory. A third option, the Apache `SetEnv` directive in httpd.conf, may work in some systems but is known to be insufficient in others.

To check that environment variables are set correctly, use phpinfo() and check the Environment (not the Apache Environment) section contains the expected variables.

The variables that might be needed are included in the following table. Refer to the Oracle documentation for more information on all the available variables.

Common Oracle Environment Variables
Name | Purpose
--- | ---
ORACLE_HOME | Contains the directory of the full Oracle Database software. Do not set this when using Oracle Instant Client as it is unnecessary and may cause installation problems.
ORACLE_SID | Contains the name of the database on the local machine to be connected to. There is no need to set this if you using Oracle Instant Client, or always pass the connection parameter to oci_connect().
LD_LIBRARY_PATH | Set this (or its platform equivalent, such as `LIBPATH`, or `SHLIB_PATH`) to the location of the Oracle libraries, for example $ORACLE_HOME/lib or /usr/lib/oracle/18.5/client/lib. Note with Instant Client ZIP files on Linux it is more reliable to use ldconfig instead, see the Instant Client installation instructions. With Instant Client 19 (or later) RPM files, `ldconfig` is automatically run for you. Some users use `LD_PRELOAD` instead of `LD_LIBRARY_PATH`.
NLS_LANG | This is the primary variable for setting the character set and globalization information used by the Oracle libraries.
ORA_SDTZ | Sets the Oracle session timezone.
TNS_ADMIN | Contains the directory where the Oracle Net Services configuration files such as tnsnames.ora and sqlnet.ora are kept. Not needed if the oci_connect() connection string uses the Easy Connect naming syntax such as `localhost/XE`. Not needed if the network configuration files are in one of the default locations such as /usr/lib/oracle/VERSION/client/lib/network/admin, $ORACLE_HOME/network/admin or /etc.

Less frequently used Oracle environment variables include `TWO_TASK`, `ORA_TZFILE`, and the various Oracle globalization settings like `NLS*` and the `ORA_NLS_*` variables.

## Troubleshooting

The most common problem with installing OCI8 is not having the Oracle environment correctly set. This typically appears as a problem using oci_connect() or oci_pconnect(). The error may be a PHP error such as Call to undefined function oci_connect(), an Oracle error such as ORA-12705, or even an Apache crash. Check the Apache log files for startup errors and see the sections above to resolve this problem.

While network errors like ORA-12154 or ORA-12514 indicate an Oracle network naming or configuration issue, the root cause may be because the PHP environment is incorrectly set up and Oracle libraries are unable to locate the tnsnames.ora configuration file.

On Windows, having multiple versions of Oracle on the one machine can easily cause library clashes unless care is taken to make sure PHP only uses the correct version of Oracle.

A utility to examine what libraries are being looked for and loaded can help resolve missing or clashing library issues, particularly on Windows.

> Hinweis: If the web server doesn't start or crashes at startup

> Check that Apache is linked with the pthread library:

>     # ldd /www/apache/bin/httpd
>       libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
>       libm.so.6 => /lib/libm.so.6 (0x4002f000)
>       libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
>       libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
>       libc.so.6 => /lib/libc.so.6 (0x4007e000)
>       /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

> If the libpthread is not listed, then reinstall Apache:

>     # cd /usr/src/apache_1.3.xx
>     # make clean
>     # LIBS=-lpthread ./config.status
>     # make
>     # make install

> Please note that on some systems like UnixWare, it is libthread instead of libpthread. PHP and Apache have to be configured with EXTRA_LIBS=-lthread.

## Testing

The OCI8 test suite is in ext/oci8/tests. After OCI8 tests are run this directory will also contain logs of any failures.

Before running PHP's tests, edit details.inc and set $user, $password and the $dbase connection string. The OCI8 test suite has been developed using the `SYSTEM` account. Some tests will fail if the test user does not have equivalent permissions.

If Oracle Database Resident Connection Pooling is being tested, set $test_drcp to `true` and ensure the connection string uses an appropriate DRCP pooled server.

An alternative to editing details.inc is the set environment variables, for example:

        $ export PHP_OCI8_TEST_USER=system
        $ export PHP_OCI8_TEST_PASS=oracle
        $ export PHP_OCI8_TEST_DB=localhost/XE
        $ export PHP_OCI8_TEST_DRCP=FALSE

Note in some shells these variables are not propagated correctly to the PHP process and tests will fail to connect if this method is used.

Next, set any necessary environment for the Oracle database. If you are running PHP on the same machines as Oracle Database, you can run:

        $ . /usr/local/bin/oraenv

With Oracle 11gR2 XE do:

        $ . /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh

Some shells require that php.ini has `E` in the variables_order parameter, for example:

        variables_order = "EGPCS"

Run all the PHP tests with:

        $ cd your_php_src_directory
        $ make test

or run only the OCI8 tests with

        $ cd your_php_src_directory
        $ make test TESTS=ext/oci8

When the tests have completed, review any test failures. On slow systems, some tests may take longer than the default test timeout in run-tests.php. To correct this, set the environment variable `TEST_TIMEOUT` to a larger number of seconds.

On fast machines with a local database configured for light load (e.g. Oracle 11gR2 XE) some tests might fail with ORA-12516 or ORA-12520 errors. To prevent this, increase the database `PROCESSES` parameter using the following steps:

Connect as the oracle software owner:

        $ su - oracle

Set the necessary Oracle environment with oracle_env.sh or oraenv, as described above.

Start the SQL*Plus command line tool and increase `PROCESSES`

        $ sqlplus / as sysdba
        SQL> alter system set processes=100 scope=spfile

Restart the database:

        SQL> startup force

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

OCI8-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
oci8.connection_class | "" | `INI_ALL` |
oci8.default_prefetch | "100" | `INI_SYSTEM` |
oci8.events | Off | `INI_SYSTEM` |
oci8.max_persistent | "-1" | `INI_SYSTEM` |
oci8.old_oci_close_semantics | Off | `INI_SYSTEM` | Ab PHP 8.1.0 veraltet.
oci8.persistent_timeout | "-1" | `INI_SYSTEM` |
oci8.ping_interval | "60" | `INI_SYSTEM` |
oci8.prefetch_lob_size | "0" | `INI_SYSTEM` | Verfügbar seit PECL OCI8 3.2.
oci8.privileged_connect | Off | `INI_SYSTEM` |
oci8.statement_cache_size | "20" | `INI_SYSTEM` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`oci8.connection_class` string

  Dieser benutzerdefinierte Text sollte immer festgelegt werden, wenn Oracle Database Resident Connection Pooling (DRCP) verwendet wird. Er ermöglicht die Partitionierung des DRCP-Verbindungspools, sodass persistente OCI8-Verbindungen einer Anwendung Datenbanksessions aus einem vorherigen PHP-Skript wiederverwenden können, was eine bessere Skalierbarkeit ermöglicht. Wenn eine Anwendung einen Datenbankpool-Prozess verwendet, der zuvor mit einer anderen Verbindungsklasse verwendet wurde, werden die Session-Einstellungen, z. B. das standardmäßige Oracle-Datumsformat, zurückgesetzt. Dies verhindert eine versehentliche gemeinsame Nutzung von Informationen zwischen verschiedenen Anwendungen.

  Der Wert kann zur Laufzeit vor dem Aufbau der Verbindung mit ini_set() gesetzt werden.

  Um DRCP zu verwenden, muss OCI8 gegen Bibliotheken von Oracle 11g (oder höher) gelinkt sein und die Datenbank muss Oracle 11g (oder höher) sein. Der DRCP-Verbindungspool muss in der Datenbank aktiviert sein, die `oci8.connection_class` muss für alle Webserver, auf denen dieselbe Anwendung läuft, auf dieselbe Zeichenkette gesetzt werden und die OCI8-Verbindungszeichenkette muss angeben, dass ein Server mit einem Pool verwendet werden soll. Die Anwendung sollte persistente Verbindungen verwenden.

`oci8.default_prefetch` int

  Diese Option legt die Standard-Anzahl der zusätzlichen Zeilen fest, die automatisch abgerufen und zwischengespeichert werden, wenn eine Low-Level-Anforderung von Daten aus der Datenbank erfolgt. Das Setzen des Wertes `0` deaktiviert das Prefetching.

  Der Prefetch-Wert ändert nicht die Anzahl der Zeilen, die Funktionen wie oci_fetch_array() an den Benutzer zurückgeben; das Prefetching und Caching von Zeilen wird intern in OCI8 verwaltet.

  Der Wert kann pro Anweisung mit oci_set_prefetch() vor der Ausführung der Anweisung gesetzt werden.

  Bei Verwendung von Oracle Database 12c (oder höher) kann der von PHP festgelegte Prefetch-Wert von Oracles Client-Konfigurationsdatei `oraaccess.xml` überschrieben werden. Siehe in der Oracle-Dokumentation für weitere Details.

  > Hinweis: Ein größerer Prefetch kann zu einer verbesserten Leistung führen, allerdings auf Kosten eines erhöhten Speicherverbrauchs. Bei Abfragen, die große Datenmengen zurückgeben, kann der Leistungsvorteil deutlich sein.

`oci8.events` bool

  Wenn diese Option aktiv ist (`On`), kann PHP über FAN- (Fast Application Notification) Datenbankereignisse benachrichtigt werden.

  Ohne FAN kann es bei einem plötzlichen Ausfall einer Datenbankinstanz oder eines Rechnerknotens dazu kommen, dass PHP-Anwendungen beim Warten auf eine Datenbankantwort hängen bleiben, bis der TCP-Timeout abgelaufen ist. Mit FAN-Ereignissen werden PHP-Anwendungen schnell über Fehler informiert, die Datenbankverbindungen betreffen. Die OCI8-Erweiterung entfernt unbrauchbare Verbindungen aus dem persistenten Verbindungscache.

  Wenn diese Option verwendet wird (`On`), muss die Datenbank auch konfiguriert werden, FAN-Ereignisse zu melden.

  Die FAN-Unterstützung ist verfügbar, wenn OCI8 gegen Bibliotheken von Oracle 10gR2 (oder höher) gelinkt ist und mit einer Oracle-Datenbank 10gR2 (oder höher) verbunden ist.

`oci8.max_persistent` int

  Die maximale Anzahl persistenter OCI8-Verbindungen pro PHP-Prozess. Wenn diese Option auf -1 gesetzt ist, ist die Anzahl der Verbindungen nicht limitiert.

`oci8.old_oci_close_semantics` bool

  Diese Option kontrolliert das Verhalten der Funktion oci_close(). Wenn sie aktiviert wird, zeigt der Aufruf von oci_close() keine Reaktion; die Verbindung wird nicht vor dem Ende des Skripts beendet. Die Funktion existiert nur aus Gründen der Abwärtskompatibilität. Wenn Sie in eine Situation kommen, in der Sie diese Option aktivieren müssen, sei Ihnen dringend empfohlen, stattdessen alle oci_close()-Aufrufe aus Ihrer Anwendung zu entfernen.

`oci8.persistent_timeout` int

  Die maximale Dauer (in Sekunden), über die der angegebene Prozess eine ungenutzte persistente Verbindung aufrechterhalten darf. Ist diese Option auf -1 gesetzt, werden ungenutzte persistente Verbindungen aufrecht erhalten, bis der PHP-Prozess endet oder die Verbindung mittels oci_close() ausdrücklich geschlossen wird.

  > Hinweis: In PHP ist das Ablaufen ungenutzter Ressourcen nicht alarmgesteuert. Es erfolgt, wenn PHP die Verarbeitung eines Skripts beendet und den Zeitstempel der zuletzt verwendeten Ressourcen überprüft. Dies führt zu dem Paradoxon, dass ungenutzte Verbindungen nur geschlossen werden können, wenn es im PHP-Prozess irgendeine Aktivität gibt (wenn auch nicht unbedingt OCI8-bezogen). Wenn es mehr als einen PHP-Prozess gibt, muss jeder Prozess einzeln aktiviert werden, um den Ablauf der seiner ungenutzten Ressourcen auszulösen. Die Einführung von Database Resident Connection Pooling (DRCP) in Oracle 11g behebt die Speicher- und Ressourcenprobleme, die `oci8.max_persistent` und `oci8.persistent_timeout` zuvor versuchten, zu beheben.

`oci8.ping_interval` int

  Die Dauer (in Sekunden), die vergehen muss, bevor ein Ping während eines oci_pconnect() abgeschickt wird. Ein Ping stellt sicher, dass die Datenbankverbindung gültig ist. Wenn dies auf 0 gesetzt ist, werden persistente Verbindungen bei jeder Verwendung von oci_pconnect() gepingt. Um Pings völlig zu deaktivieren, muss die Option auf -1 gesetzt werden.

  > Hinweis: Das Deaktivieren von Pings lässt oci_pconnect() mit höchster Effizienz arbeiten, kann aber dazu führen, dass PHP unbrauchbare Verbindungen nicht bemerkt, die z. B. entstehen können, wenn das Netzwerk unterbrochen wird oder der Oracle-Server bei bestehender Verbindung heruntergefahren wird. Konsultieren Sie die Dokumentation zu oci_pconnect(), um weitere Informationen zu erhalten.

`oci8.prefetch_lob_size` int

  Dies ist ein Optimierungsparameter, der die interne Pufferung von LOB-Daten betrifft. Wenn dieser Wert erhöht wird, kann dies die Leistung beim Abrufen von kleineren LOBs verbessern, indem die Anzahl der Umläufe (Roundtrips) zwischen PHP und der Datenbank reduziert wird. Die Speichernutzung wird sich ändern.

  Der Wert betrifft LOBs, die als Instanzen von OCILob zurückgegeben werden und auch solche die unter Verwendung von `OCI_RETURN_LOBS` zurückgegeben werden.

  Der Wert kann bei jeder Anweisung mittels oci_set_prefetch_lob() vor der Ausführung der Anweisung festgelegt werden.

  > Hinweis: Zu verwenden mit Oracle Database 12.2 oder höher.

`oci8.privileged_connect` bool

  Diese Option aktiviert privilegierte Verbindungen unter Verwendung externer Berechtigungen (`OCI_SYSOPER` oder `OCI_SYSDBA`).

  > Hinweis: Wenn diese Option auf `On` gesetzt ist, können Webserver-Skripte, die über die entsprechenden Systembenutzerrechte verfügen, eine Verbindung zur Datenbank mit diesen Rechten herstellen, ohne ein Passwort für die Datenbank angeben zu müssen. Dies kann ein Sicherheitsrisiko darstellen.

`oci8.statement_cache_size` int

  Diese Option aktiviert den Anweisungs-Cache und definiert, wie viele Anweisungen gecacht werden. Um das Caching zu deaktivieren, muss die Option auf 0 gesetzt werden.

  Durch das Anweisungs-Caching entfällt die Notwendigkeit, den Anweisungstext an die Datenbank zu übermitteln, und es müssen auch keine Metadaten über die Anweisung zurück an PHP übertragen werden. Dies kann die Gesamtleistung des Systems in Anwendungen, die Anweisungen während der Lebensdauer einer Verbindung wiederverwenden, deutlich verbessern. Einige zusätzliche Datenbank-"Cursor" werden möglicherweise unter der Annahme offen gehalten, dass Anweisungen wiederverwendet werden.

  Setzen Sie diesen Wert auf die Größe der aktuellen Menge an Anweisungen, die von Ihrer Anwendung verwendet wird. Die Einstellung eines zu kleinen Wertes kann dazu führen, dass Anweisungen aus dem Cache entfernt werden, bevor sie wiederverwendet werden.

  Diese Option ist vor allem bei persistenten Verbindungen von Nutzen.

  Wenn Sie Oracle Database 12c (oder höher) verwenden, kann dieser Wert von Oracles Client-Datei `oraaccess.xml` überschrieben und automatisch eingestellt werden. Siehe die Oracle-Dokumentation für weitere Details.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

OCI8 Function and Method Modes
Constant | Description
--- | ---
`OCI_ASSOC` | Used with oci_fetch_all() and oci_fetch_array() to get results as an associative array.
`OCI_BOTH` | Used with oci_fetch_all() and oci_fetch_array() to get results as an array with both associative and number indices.
`OCI_COMMIT_ON_SUCCESS` | Statement execution mode for oci_execute() call. Automatically commit changes when the statement has succeeded.
`OCI_CRED_EXT` | Used with oci_connect() for using Oracles' External or OS authentication.
`OCI_DEFAULT` | See `OCI_NO_AUTO_COMMIT`.
`OCI_DESCRIBE_ONLY` | Statement execution mode for oci_execute(). Use this mode if you want meta data such as the column names but don't want to fetch rows from the query.
`OCI_EXACT_FETCH` | Obsolete. Statement fetch mode. Used when the application knows in advance exactly how many rows it will be fetching. This mode turns prefetching off for Oracle release 8 or later mode. The cursor is canceled after the desired rows are fetched which may result in reduced server-side resource usage.
`OCI_FETCHSTATEMENT_BY_COLUMN` | Default mode of oci_fetch_all().
`OCI_FETCHSTATEMENT_BY_ROW` | Alternative mode of oci_fetch_all().
`OCI_LOB_BUFFER_FREE` | Used with OCILob::flush to free buffers used.
`OCI_NO_AUTO_COMMIT` | Statement execution mode for oci_execute(). The transaction is not automatically committed when using this mode. For readability in new code, use this value instead of the older, equivalent `OCI_DEFAULT` constant.
`OCI_NUM` | Used with oci_fetch_all() and oci_fetch_array() to get results as an enumerated array.
`OCI_RETURN_LOBS` | Used with oci_fetch_array() to get the data value of the LOB instead of the descriptor.
`OCI_RETURN_NULLS` | Used with oci_fetch_array() to get empty array elements if the row items value is `null`.
`OCI_SEEK_CUR` | Used with OCILob::seek to set the seek position.
`OCI_SEEK_END` | Used with OCILob::seek to set the seek position.
`OCI_SEEK_SET` | Used with OCILob::seek to set the seek position.
`OCI_SYSDATE` | Obsolete.
`OCI_SYSDBA` | Used with oci_connect() to connect with the SYSDBA privilege. The php.ini setting oci8.privileged_connect should be enabled to use this.
`OCI_SYSOPER` | Used with oci_connect() to connect with the SYSOPER privilege. The php.ini setting oci8.privileged_connect should be enabled to use this.
`OCI_TEMP_BLOB` | Used with OCILob::writeTemporary to indicate that a temporary BLOB should be created.
`OCI_TEMP_CLOB` | Used with OCILob::writeTemporary to indicate that a temporary CLOB should be created.

OCI8 Bind and Define Types
Constant | Description
--- | ---
`OCI_B_BFILE` | Used with oci_bind_by_name() when binding BFILEs.
`OCI_B_BIN` | Used with oci_bind_by_name() to bind RAW values.
`OCI_B_BLOB` | Used with oci_bind_by_name() when binding BLOBs.
`OCI_B_BOL` | Used with oci_bind_by_name() to bind a PL/SQL BOOLEAN variable.
`OCI_B_CFILEE` | Used with oci_bind_by_name() when binding CFILEs.
`OCI_B_CLOB` | Used with oci_bind_by_name() when binding CLOBs.
`OCI_B_CURSOR` | Used with oci_bind_by_name() when binding cursors, previously allocated with oci_new_descriptor().
`OCI_B_INT` | Used with oci_bind_array_by_name() to bind arrays of INTEGER.
`OCI_B_NTY` | Used with oci_bind_by_name() when binding named data types.
`OCI_B_NUM` | Used with oci_bind_array_by_name() to bind arrays of NUMBER.
`OCI_B_ROWID` | Used with oci_bind_by_name() when binding ROWIDs.
`SQLT_AFC` | Used with oci_bind_array_by_name() to bind arrays of CHAR.
`SQLT_AVC` | Used with oci_bind_array_by_name() to bind arrays of VARCHAR2.
`SQLT_BDOUBLE` | Not supported.
`SQLT_BFILEE` | The same as `OCI_B_BFILE`.
`SQLT_BFLOAT` | Not supported.
`SQLT_BIN` | The same as `OCI_B_BIN`.
`SQLT_BLOB` | The same as `OCI_B_BLOB`.
`SQLT_BOL` | The same as `OCI_B_BOL`.
`SQLT_CFILEE` | The same as `OCI_B_CFILEE`.
`SQLT_CHR` | Used with oci_bind_array_by_name() to bind arrays of VARCHAR2. Also used with oci_bind_by_name().
`SQLT_CLOB` | The same as `OCI_B_CLOB`.
`SQLT_FLT` | Used with oci_bind_array_by_name() to bind arrays of FLOAT.
`SQLT_INT` | The same as `OCI_B_INT`.
`SQLT_LBI` | Used with oci_bind_by_name() to bind LONG RAW values.
`SQLT_LNG` | Used with oci_bind_by_name() to bind LONG values.
`SQLT_LVC` | Used with oci_bind_array_by_name() to bind arrays of LONG VARCHAR.
`SQLT_NTY` | The same as `OCI_B_NTY`.
`SQLT_NUM` | The same as `OCI_B_NUM`.
`SQLT_ODT` | Used with oci_bind_array_by_name() to bind arrays of LONG.
`SQLT_RDD` | The same as `OCI_B_ROWID`.
`SQLT_RSET` | The same as `OCI_B_CURSOR`.
`SQLT_STR` | Used with oci_bind_array_by_name() to bind arrays of STRING.
`SQLT_UIN` | Not supported.
`SQLT_VCS` | Used with oci_bind_array_by_name() to bind arrays of VARCHAR.

OCI8 Descriptor Types
Constant | Description
--- | ---
`OCI_DTYPE_FILE` | This flag tells oci_new_descriptor() to initialize a new FILE descriptor.
`OCI_DTYPE_LOB` | This flag tells oci_new_descriptor() to initialize a new LOB descriptor.
`OCI_DTYPE_ROWID` | This flag tells oci_new_descriptor() to initialize a new ROWID descriptor.
`OCI_D_FILE` | The same as `OCI_DTYPE_FILE`.
`OCI_D_LOB` | The same as `OCI_DTYPE_LOB`.
`OCI_D_ROWID` | The same as `OCI_DTYPE_ROWID`.

Konstanten | Beschreibung
--- | ---
OCI8 Transparent Application Failover (TAF) Constants
`OCI_FO_ABORT` (int) | Failover was unsuccessful and there is no option of retrying.
`OCI_FO_BEGIN` (int) | Failover has detected a lost connection and failover is starting.
`OCI_FO_END` (int) | Failover completed successfully.
`OCI_FO_ERROR` (int) | Failover was unsuccessful but it gives the application the opportunity to handle the error and return `OCI_FO_RETRY` to retry failover.
`OCI_FO_NONE` (int) | The user has not requested a failover type.
`OCI_FO_REAUTH` (int) | An Oracle user has been re-authenticated.
`OCI_FO_RETRY` (int) | The failover should be attempted again by Oracle. In case of an error while failing over to a new connection, TAF is able to retry the failover. Typically, the application code should sleep for a while before returning `OCI_FO_RETRY`.
`OCI_FO_SELECT` (int) | The user has requested SELECT failover as well. It allows users with open cursors to continue fetching from them after failure.
`OCI_FO_SESSION` (int) | The user has requested only session failover. For example, if a user's connection is lost, then a new session is automatically created for the user on the backup. This type of failover does not attempt to recover SELECTs.
`OCI_FO_TXNAL` (int) | The user has requested a transaction failover.

# Beispiele

These examples connect as the `HR` user, which is the sample "Human Resources" schema supplied with the Oracle database. The account may need to be unlocked and the password reset before you can use it.

The examples connect to the `XE` database on your machine. Change the connect string to your database before running the examples.

Beispiel #1 Basic query

This shows querying and displaying results. Statements in OCI8 use a prepare-execute-fetch sequence of steps.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Prepare the statement
    $stid = oci_parse($conn, 'SELECT * FROM departments');
    if (!$stid) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Perform the logic of the query
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Fetch the results of the query
    print "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        print "<tr>\n";
        foreach ($row as $item) {
            print "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        print "</tr>\n";
    }
    print "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #2 Inserting with bind variables

Bind variables improve performance by allowing reuse of execution contexts and caches. Bind variables improve security by preventing some kinds of SQL Injection problems.

    <?php

    // Before running, create the table:
    //   CREATE TABLE MYTABLE (mid NUMBER, myd VARCHAR2(20));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO MYTABLE (mid, myd) VALUES(:myid, :mydata)');

    $id = 60;
    $data = 'Some data';

    oci_bind_by_name($stid, ':myid', $id);
    oci_bind_by_name($stid, ':mydata', $data);

    $r = oci_execute($stid);  // executes and commits

    if ($r) {
        print "One row inserted";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #3 Binding in the WHERE clause of a query

This shows a single scalar bind.

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // Output is
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #4 Inserting and fetching a CLOB

For large data use binary long object (BLOB) or character long object (CLOB) types. This example uses CLOB.

    <?php

    // Before running, create the table:
    //     CREATE TABLE MYTABLE (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $mykey = 12343;  // arbitrary key for this example;

    $sql = "INSERT INTO mytable (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_NO_AUTO_COMMIT);
    $clob->save("A very long string");

    oci_commit($conn);

    // Fetching CLOB data

    $query = 'SELECT myclob FROM mytable WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // In a loop, freeing the large variable before the 2nd fetch reduces PHP's peak memory usage
        unset($row);
    }
    print '</table>';

    ?>

Beispiel #5 Using a PL/SQL stored function

You must bind a variable for the return value and optionally for any PL/SQL function arguments.

    <?php

    /*
      Before running the PHP program, create a stored function in
      SQL*Plus or SQL Developer:

      CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
      BEGIN
          RETURN p * 3;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // prints 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #6 Using a PL/SQL stored procedure

With stored procedures, you should bind variables for any arguments.

    <?php

    /*
      Before running the PHP program, create a stored procedure in
      SQL*Plus or SQL Developer:

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // prints 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #7 Calling a PL/SQL function that returns a `REF CURSOR`

Each returned value from the query is a `REF CURSOR` that can be fetched from.

    <?php
    /*
      Create the PL/SQL stored function as:

      CREATE OR REPLACE FUNCTION myfunc(p1 IN NUMBER) RETURN SYS_REFCURSOR AS
          rc SYS_REFCURSOR;
      BEGIN
          OPEN rc FOR SELECT city FROM locations WHERE ROWNUM < p1;
          RETURN rc;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myfunc(5) AS mfrc FROM dual');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC))) {
        echo "<tr>\n";
        $rc = $row['MFRC'];
        oci_execute($rc);  // returned column value from the query is a ref cursor
        while (($rc_row = oci_fetch_array($rc, OCI_ASSOC))) {
            echo "    <td>" . $rc_row['CITY'] . "</td>\n";
        }
        oci_free_statement($rc);
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Output is:
    //   Beijing
    //   Bern
    //   Bombay
    //   Geneva

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# OCI8 Connection Handling and Connection Pooling

## Connection Functions

The OCI8 extension provides three different functions for connecting to Oracle. The standard connection function is oci_connect(). This creates a connection to an Oracle database and returns a resource used by subsequent database calls.

Connecting to an Oracle server is a reasonably expensive operation in terms of the time that it takes to complete. The oci_pconnect() function uses a persistent cache of connections that can be re-used across different script requests. This means that the connection overhead will typically only occur once per PHP process (or Apache child).

If the application connects to Oracle using a different set of database credentials for each web user, the persistent cache employed by oci_pconnect() will become less useful as the number of concurrent users increases, to the point where it may start to adversely affect the overall performance of the Oracle server due to maintaining too many idle connections. If the application is structured in this way, it is recommended to either tune the application using the oci8.max_persistent and oci8.persistent_timeout configuration settings (these will give control over the persistent connection cache size and lifetime), use Oracle Database Resident Connection Pooling (in Oracle Database 11g or later), or use oci_connect() instead.

Both oci_connect() and oci_pconnect() employ a connection cache; if multiple calls to oci_connect() use the same parameters in a given script, the second and subsequent calls return the existing connection handle. The cache used by oci_connect() is cleaned up at the end of the script run, or when the connection handle is explicitly closed. The function oci_pconnect() has similar behavior, although its cache is maintained separately and survives between HTTP requests.

This caching feature means the two handles are not transactionally isolated (they are in fact the same connection handle, so there is no isolation of any kind). If the application needs two separate, transactionally isolated connections, then use oci_new_connect().

The oci_pconnect() cache is cleared and any database connections closed when the PHP process terminates, so effective use of persistent connections requires that PHP be an Apache module or used with FPM, or similar. Persistent connections will not have any benefits over oci_connect() when PHP is used with CGI or via the command-line.

The function oci_new_connect() always creates a new connection to the Oracle server, regardless of what other connections might already exist. High traffic web applications should avoid using oci_new_connect(), especially in the busiest sections of the application.

Persistent connections can be closed by the user, allowing greater control over connection resource usage. Persistent connections will now also be closed automatically when there is no PHP variable referencing them, such as at the end of scope of a PHP user function. This will rollback any uncommitted transaction. These changes to persistent connections make them behave similarly to non-persistent connections, simplifying the interface, allowing for greater application consistency and predictability. Use oci8.old_oci_close_semantics set to On to retain the historical behavior.

The automatic re-establishment of PHP persistent connections after an Apache or FPM process respawns means Oracle Database `LOGON` triggers are only recommended for setting session attributes and not for per-application user connection requests.

## DRCP Connection Pooling

PHP supports Oracle Database Resident Connection Pooling (DRCP). DRCP allows more efficient use of database machine memory and provides high scalability. No, or minimal, application changes are needed to use DRCP.

DRCP is suited for applications that connect using few database schemas and hold database connections open for a short period of time. Other applications should use Oracle's default `Dedicated` database server processes, or use `Shared` servers.

DRCP benefits all three connection functions, but gives the highest scalability when connections are created with oci_pconnect().

For DRCP to be available in OCI8, Oracle client libraries used by PHP and the version of the Oracle Database must both be 11g or greater.

Documentation on DRCP is found in several Oracle manuals. For example, see » Configuring Database Resident Connection Pooling in the Oracle documentation for usage information. A » DRCP white paper contains background information on DRCP.

To use DRCP, install the OCI8 extension and Oracle 11g (or later) libraries and then follow these steps:

- As a privileged database administrator, use a program like SQL*Plus to start the connection pool in the database:

          SQL> execute dbms_connection_pool.start_pool;

- Optionally use `dbms_connection_pool.alter_param()` to configure DRCP settings. The current pool settings can be queried from the `DBA_CPOOL_INFO` view.

- Update the connection strings used. For PHP applications that currently connect using a Network Connect Name like `MYDB`:

          $c = oci_pconnect("myuser", "mypassword", "MYDB");

  modify the tnsnames.ora file and add a `(SERVER=POOLED)` clause, for example:

          MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com)
                 (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales)
                 (SERVER=POOLED)))

  Alternatively, modify the Easy Connect syntax in PHP and add `:POOLED` after the service name:

          $c = oci_pconnect("myuser", "mypassword", "myhost.dom.com:1521/sales:POOLED");

- Edit php.ini and choose a connection class name. This name indicates a logical division of the connection pool and can be used to isolate pooling for separate applications. Any PHP applications with the same user name and connection class value will be able to share connections in the pool, giving greater scalability.

          oci8.connection_class = "MY_APPLICATION_NAME"

- Run the application, connecting to the 11g (or later) database.

> Hinweis:

> Applications using Oracle Client libraries 10g that require the performance of persistent connections can reduce the amount of database server memory needed by using Oracle `Shared` servers (previously known as Multi Threaded Servers). Refer to Oracle documentation for information.

> Hinweis:

> Changing a password over DRCP connections will fail with the error ORA-56609: Usage not supported with DRCP. This is a documented restriction of Oracle Database 11g.

# OCI8 Fast Application Notification (FAN) Support

FAN support gives fast connection failover, an Oracle Database high availability feature. This allows PHP OCI8 scripts to be notified when a database machine or database instance becomes unavailable. Without FAN, OCI8 can hang until a TCP timeout occurs and an error is returned, which might be several minutes. Enabling FAN in OCI8 can allow applications to detect errors and re-connect to an available database instance without the web user being aware of an outage.

FAN support is available when the Oracle client libraries that PHP links with and the Oracle Database are either version 10gR2 or later.

FAN benefits users of Oracle's clustering technology (RAC) because connections to surviving database instances can be immediately made. Users of Oracle's Data Guard with a broker will see the FAN events generated when the standby database goes online. Standalone databases will send FAN events when the database restarts.

For active connections, when a machine or database instance becomes unavailable, a connection failure error will be returned by the OCI8 extension function currently being called. On a subsequent PHP script re-connect, a connection to a surviving database instance will be established. The OCI8 extension also transparently cleans up any idle connections affected by a database machine or instance failure so PHP connect calls will establish a fresh connection without the script being aware of any service disruption.

When oci8.events is `On`, it is suggested to set oci8.ping_interval to -1 to disable pinging, since enabling FAN events provide pro-active connection management of idle connections made invalid by a service disruption.

To enable FAN support in PHP OCI8, build PHP OCI8 with Oracle 10gR2 or later libraries and then follow these steps:

- As a privileged database administrator, use a program like SQL*Plus to enable the database service to post FAN events, for example:

          SQL> execute dbms_service.modify_service(
                         SERVICE_NAME        => 'sales',
                         AQ_HA_NOTIFICATIONS => TRUE);

- Edit php.ini and add

          oci8.events = On

- If the application does not already handle OCI8 error conditions, modify it to detect failures and take appropriate action. This may include re-connecting and re-executing statements.
- Run the application, connecting to Oracle Database 10gR2 or later.

# OCI8 Transparent Application Failover (TAF) Support

TAF is an Oracle Database feature that provides high availability. It enables PHP OCI8 applications to automatically reconnect to a preconfigured database when database connectivity fails due to instance or network failure.

In a configured Oracle Database system, TAF occurs when the PHP application detects that the database instance is down or unreachable. It establishes a connection to another node in an Oracle » RAC configuration, a hot standby database, or the same database instance itself. See » Oracle Call Interface Programmer's Guide for more information about OCI TAF.

An application callback can be registered with oci_register_taf_callback(). During failover, normal application processing stops and the registered callback is invoked. The callback notifies the application of the failover events. If the failover succeeds, normal processing will be resumed. If the failover aborts, any following database operations in the application will fail due to no connection being available.

When a connection fails over to another database, the callback can reset any necessary connection state, for example replaying any necessary ALTER SESSION commands if the database service did not have -failover_restore enabled.

An application callback can be removed by calling oci_unregister_taf_callback().

## Configuring Transparent Application Failover

TAF can be configured on the PHP OCI8 side or in the database configuration. If both are configured, database-side settings take precedence.

Configure TAF in PHP OCI8 (the client side) by including the FAILOVER_MODE parameter in the CONNECT_DATA portion of a connect descriptor. See Configuring Transparent Application Failover in » Oracle Database Net Services Administrator's Guide for more information about client side configuration of TAF.

An example tnsnames.ora to configure TAF reconnecting to the same database instance:

        ORCL =
          (DESCRIPTION =
            (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
            (CONNECT_DATA =
              (SERVICE_NAME = orclpdb1)
              (FAILOVER_MODE =
                (TYPE = SELECT)
                (METHOD = BASIC)
                (RETRIES = 20)
                (DELAY = 15))))

Alternatively configure TAF on the database side by modifying the target service with » srvctl (for RAC) or the » DBMS_SERVICE.MODIFY_SERVICE packaged procedure (for single instance databases).

## Using TAF Callbacks in OCI8

A TAF callback is an application function that can be registered to be called during failover. It is called several times while re-establishing the application's connection.

Callback first occurs when a loss of connection is detected. This allows the application to act accordingly for the upcoming delay of the failover. If the failover is successful, the callback is invoked after connection is re-established and usable. At this time, the application can resynchronize session settings and take actions such as informing the user that failover occurred. If failover is unsuccessful, a callback occurs to inform the application that a failover did not take place and the connection is unusable.

The interface of a TAF user-defined callback function is as follows:

function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

`connection`

  The Oracle connection on which the TAF callback was registered via oci_register_taf_callback(). The connection is not valid until the failover completes successfully.

`event`

  The failover event indicates the current status of the failover.

  - `OCI_FO_BEGIN` indicates that failover has detected a lost connection and failover is starting.

  - `OCI_FO_END` indicates successful completion of failover.

  - `OCI_FO_ABORT` indicates that failover was unsuccessful, and there is no option of retrying.

  - `OCI_FO_ERROR` also indicates that failover was unsuccessful, but it gives the application the opportunity to handle the error and return OCI_FO_RETRY to retry failover.

  - `OCI_FO_REAUTH` indicates that an Oracle user has been re-authenticated.

`type`

  The failover type. This lets the callback know what type of failover the application has requested. The usual values are as follows:

  - `OCI_FO_SESSION` indicates that the user has requested only session failover. For example, if a user's connection is lost, then a new session is automatically created for the user on the backup. This type of failover does not attempt to recover SELECTs.

  - `OCI_FO_SELECT` indicates that the user has requested SELECT failover as well. It allows users with open cursors to continue fetching from them after failure.

`return value`

  - `0` indicates the failover steps should continue normally.

  - `OCI_FO_RETRY` indicates that the failover should be attempted again by Oracle. In case of an error while failing over to a new connection, TAF is able to retry the failover. Typically, the application code should sleep for a while before returning OCI_FO_RETRY.

Beispiel #1 Registering a TAF callback

    <?php

    // Define userspace callback
    class MyClass {
        public static $retry_count;
        public static function TAFCallback($conn, $event, $type)
        {
            switch ($event) {
                case OCI_FO_BEGIN:
                    printf(" Failing Over ... Please stand by\n");
                    printf(" Failover type was found to be %s \n",
                           (($type==OCI_FO_SESSION) ? "SESSION"
                            :(($type==OCI_FO_SELECT) ? "SELECT" : "UNKNOWN!")));
                    self::$retry_count = 0;
                    break;
                case OCI_FO_ABORT:
                    // The application cannot continue using the database
                    printf(" Failover aborted. Failover will not take place.\n");
                    break;
                case OCI_FO_END:
                    // Failover completes successfully. Inform users a failover occurs.
                    printf(" Failover ended ... resuming services\n");
                    break;
                case OCI_FO_REAUTH:
                    printf(" Failed over user ... resuming services\n");
                    // Replay any ALTER SESSION commands associated with this connection
                    // eg. oci_parse($conn, ‘ALTER SESSION …’) ;
                    break;
                case OCI_FO_ERROR:
                    // Stop retrying if we have already attempted for 20 times.
                    if (self::$retry_count >= 20)
                        return 0;
                    printf(" Failover error received. Sleeping...\n");
                    sleep(10);
                    self::$retry_count++;
                    return OCI_FO_RETRY; // retry failover
                    break;
                default:
                    printf("Bad Failover Event: %d.\n", $event);
                    break;
            }
            return 0;
        }
    }

    $fn_name = 'MyClass::TAFCallback';

    $conn = oci_connect('hr', 'welcome', 'orcl');
    $sysconn = oci_connect('system', 'oracle', 'orcl');

    // Use a privileged connection to construct a SQL statement that will initiate failover
    $sql = <<< 'END'
    select unique 'alter system disconnect session '''||sid||','||serial#||''''
    from v$session_connect_info
    where sid = sys_context('USERENV', 'SID')
    END;

    $s = oci_parse($conn, $sql);
    oci_execute($s);
    $r = oci_fetch_array($s);
    $disconnectssql = $r[0];

    oci_register_taf_callback($conn, $fn_name); // Register TAFCallback to Oracle TAF

    print "Parsing user query\n";
    $sql = "select systimestamp from dual";
    $stmt = oci_parse($conn, $sql);

    // For example, if a connection loss occurs at this point, oci_execute() will
    // detect the loss and failover begins. During failover, oci_execute() will
    // invoke the TAF callback function several times. If the failover is successful,
    // a new connection is transparently created and oci_execute() will continue as
    // usual. The connection session settings can be reset in the TAF callback
    // function. If the failover is aborted, oci_execute() will return an error
    // because a valid connection is not available.

    // Disconnect the user, which initiates failover
    print "Disconnecting the user\n";
    $discsql = oci_parse($sysconn, $disconnectssql);
    oci_execute($discsql);

    print "Executing user query\n";
    $e = oci_execute($stmt);
    if (!$e) {
        $m = oci_error($stmt);
        trigger_error("Could not execute statement: ". $m['message'], E_USER_ERROR);
    }
    $row = oci_fetch_array($stmt);
    print $row[0] . "\n";

    // do other SQL statements with the new connection, if it is valid
    // $stmt = oci_parse($conn,  . . .);

    ?>

## Siehe auch

- oci_register_taf_callback()
- oci_unregister_taf_callback()

# OCI8 and DTrace Dynamic Tracing

OCI8 2.0 introduced static DTrace probes that can be used on operating systems that support DTrace. See DTrace Dynamic Tracing for an overview of PHP and DTrace.

## Installing OCI8 with DTrace Support

To enable DTrace support in PHP OCI8, build OCI8 as a shared extension after setting `PHP_DTRACE`.

    $ export PHP_DTRACE=yes
    $ pecl install oci8

Edit php.ini, set extension_dir to the directory with the created oci8.so and also enable the extension by adding:

    extension=oci8.so

If you install PHP OCI8 from PECL using phpize and configure (instead of pecl), you will still need to set `PHP_DTRACE=yes`. This is because the `--enable-dtrace` option will be ignored by the limited configure script of a PECL bundle.

See Installation of PECL extensions for general PECL installation instructions.

## DTrace Static Probes in PHP OCI8

The following static probes are available in PHP OCI8
Probe Name | Probe Description | Probe Arguments
--- | --- | ---
`oci8-connect-entry` | Initiated by oci_connect(), oci_pconnect() and oci_new_connect(). Fires before database connection is established. | char *username, char *dbname, char *charset, long session_mode, int persistent, int exclusive
`oci8-connect-return` | Fires at the end of connection. | void *connection
`oci8-check-connection` | Fires if an Oracle error might have caused the connection to become invalid. | void *connection, char *client_id, int is_open, long errcode, unsigned long server_status
`oci8-sqltext` | Fires when oci_parse() is executed. | void *connection, char *client_id, void *statement, char *sql
`oci8-connection-close` | Fires when the connection to the database is completely destroyed. | void *connection
`oci8-error` | Fires if an Oracle error occurs. | int status, long errcode
`oci8-execute-mode` | Fires at oci_execute() to show the execution mode. | void *connection, char *client_id, void *statement, unsigned int mode

These probes are useful for tracing OCI8 scripts.

The connection and statement are the pointers to internal structures used for tracking PHP connections and executed statements.

The client_id is the value set by oci_set_client_identifier().

Core PHP also has static probes. See DTrace Static Probes in Core PHP.

Internal Debugging DTrace Probes in OCI8
Probe Name
`oci8-connect-expiry`
`oci8-connect-lookup`
`oci8-connect-p-dtor-close`
`oci8-connect-p-dtor-release`
`oci8-connect-type`
`oci8-sesspool-create`
`oci8-sesspool-stats`
`oci8-sesspool-type`

These probes are useful for OCI8 maintainers. Refer to the OCI8 source code for arguments and to see when the will fire.

## Listing DTrace Static Probes in PHP OCI8

To list available probes, start a PHP process and then run:

    # dtrace -l

The output will be similar to:

       ID   PROVIDER            MODULE                          FUNCTION NAME
       [ . . . ]
       17 phpoci22116           oci8.so   php_oci_dtrace_check_connection oci8-check-connection
       18 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-entry
       19 phpoci22116           oci8.so         php_oci_persistent_helper oci8-connect-expiry
       20 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-lookup
       21 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-close
       22 phpoci22116           oci8.so  php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-release
       23 phpoci22116           oci8.so                php_oci_do_connect oci8-connect-return
       24 phpoci22116           oci8.so             php_oci_do_connect_ex oci8-connect-type
       25 phpoci22116           oci8.so          php_oci_connection_close oci8-connection-close
       26 phpoci22116           oci8.so                     php_oci_error oci8-error
       27 phpoci22116           oci8.so         php_oci_statement_execute oci8-execute-mode
       28 phpoci22116           oci8.so              php_oci_create_spool oci8-sesspool-create
       29 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-stats
       30 phpoci22116           oci8.so            php_oci_create_session oci8-sesspool-type
       31 phpoci22116           oci8.so          php_oci_statement_create oci8-sqltext

The Provider column values consist of `phpoci` and the process id of the currently running PHP process.

The Function column refers to PHP's internal C implementation function names where each provider is located.

If a PHP process is not running, then no PHP probes will be shown.

## DTrace with PHP OCI8 Example

This example shows the basics of the DTrace D scripting language.

Beispiel #1 user_oci8_probes.d for tracing all user-level PHP OCI8 Static Probes with DTrace

    #!/usr/sbin/dtrace -Zs

    #pragma D option quiet

    php*:::oci8-connect-entry
    {
        printf("%lld: PHP connect-entry\n", walltimestamp);
        printf("  credentials=\"%s@%s\"\n", arg0 ? copyinstr(arg0) : "", arg1 ? copyinstr(arg1) : "");
        printf("  charset=\"%s\"\n", arg2 ? copyinstr(arg2) : "");
        printf("  session_mode=%ld\n", (long)arg3);
        printf("  persistent=%d\n", (int)arg4);
        printf("  exclusive=%d\n", (int)arg5);
    }

    php*:::oci8-connect-return
    {
        printf("%lld: PHP oci8-connect-return\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-connection-close
    {
        printf("%lld: PHP oci8-connect-close\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
    }

    php*:::oci8-error
    {
        printf("%lld: PHP oci8-error\n", walltimestamp);
        printf("  status=%d\n", (int)arg0);
        printf("  errcode=%ld\n", (long)arg1);
    }

    php*:::oci8-check-connection
    {
        printf("%lld: PHP oci8-check-connection\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  is_open=%d\n", arg2);
        printf("  errcode=%ld\n", (long)arg3);
        printf("  server_status=%lu\n", (unsigned long)arg4);
    }

    php*:::oci8-sqltext
    {
        printf("%lld: PHP oci8-sqltext\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  sql=\"%s\"\n", arg3 ? copyinstr(arg3) : "");
    }

    php*:::oci8-execute-mode
    {
        printf("%lld: PHP oci8-execute-mode\n", walltimestamp);
        printf("  connection=0x%p\n", (void *)arg0);
        printf("  client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
        printf("  statement=0x%p\n", (void *)arg2);
        printf("  mode=0x%x\n", arg3);
    }

This script uses the `-Z` option to dtrace, allowing it to be run when there is no PHP process executing. If this option were omitted the script would immediately terminate when no PHP executable was running because it knows none of the probes to be monitored are in existence.

On multi-CPU machines the probe ordering might not appear to be sequential. This depends on which CPU was processing the probes, and how threads migrate across CPUs. Displaying probe time stamps helps reduce confusion.

The script traces all user-level PHP OCI8 static probe points throughout the duration of a running PHP script. Run the D script:

    # ./user_oci8_probes.d

Run a PHP script or application. The monitoring D script will output each probe's arguments as it fires. For example, a simple PHP script that queries a table might produce the following trace output:

    1381794982092854582: PHP connect-entry
      credentials="hr@localhost/pdborcl"
      charset=""
      session_mode=0
      persistent=0
      exclusive=0
    1381794982183158766: PHP oci8-connect-return
      connection=0x7f4a7907bfb8
    1381794982183594576: PHP oci8-sqltext
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      sql="select * from employees"
    1381794982183783706: PHP oci8-execute-mode
      connection=0x7f4a7907bfb8
      client_id="Chris"
      statement=0x7f4a7907c2a0
      mode=0x20
    1381794982444344390: PHP oci8-connect-close
      connection=0x7f4a7907bfb8

When monitoring is complete, the D script can be terminated with a ``CTRL`+`C``.

## Siehe auch

- DTrace Dynamic Tracing

# Supported Datatypes

The driver supports the following types when binding parameters using the oci_bind_by_name() function:
Type | Mapping
--- | ---
`SQLT_NTY` | Maps a native collection type from a PHP collection object, such as those created by oci_new_collection().
`SQLT_BFILEE` | Maps a native descriptor, such as those created by oci_new_descriptor().
`SQLT_CFILEE` | Maps a native descriptor, such as those created by oci_new_descriptor().
`SQLT_CLOB` | Maps a native descriptor, such as those created by oci_new_descriptor().
`SQLT_BLOB` | Maps a native descriptor, such as those created by oci_new_descriptor().
`SQLT_RDD` | Maps a native descriptor, such as those created by oci_new_descriptor().
`SQLT_NUM` | Converts the PHP parameter to a 'C' long type, and binds to that value.
`SQLT_RSET` | Maps a native statement handle, such as those created by oci_parse() or those retrieved from other OCI queries.
`SQLT_BOL` | Bind the PHP parameter to a PL/SQL BOOLEAN
`SQLT_CHR` and any other type | Converts the PHP parameter to a string type and binds as a string.

The following types are supported when retrieving columns from a result set:
Type | Mapping
--- | ---
`SQLT_RSET` | Creates an oci statement resource to represent the cursor.
`SQLT_RDD` | Creates a ROWID object.
`SQLT_BLOB` | Creates a LOB object.
`SQLT_CLOB` | Creates a LOB object.
`SQLT_BFILE` | Creates a LOB object.
`SQLT_LNG` | Bound as SQLT_CHR, returned as a string
`SQLT_LBI` | Bound as `SQLT_BIN`, returned as a string
Any other type | Bound as `SQLT_CHR`, returned as a string

# OCI8 Funktionen

# oci_bind_array_by_name

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL OCI8 >= 1.2.0)

oci_bind_array_by_name — Bindet ein PHP-Array an einen Oracle-PL/SQL-Arrayparameter

### Beschreibung

function oci_bind_array_by_name(
resource `$statement`,
string `$param`,
array `&$var`,
int `$max_array_length`,
int `$max_item_length` = -1,
int `$type` = `SQLT_AFC`
): bool

Bindet die PHP-Variable `var` an den Oracle-Platzhalter `param`, der auf ein Oracle-PL/SQL-Array zeigt. Ob dieser zur Ein- oder Ausgabe genutzt wird, wird zur Laufzeit ermittelt.

### Parameter-Liste

`statement`

  Ein gültiger Zeiger auf ein OCI-Statement.

`param`

  Der Oracle-Platzhalter.

`var`

  Ein Array.

`max_array_length`

  Setzt die maximale Länge sowohl für die Eingabe- als auch die Ergebnis-Arrays.

`max_item_length`

  Setzt die maximale Länge für Array-Elemente. Wenn dieser nicht spezifiziert oder gleich -1 ist, sucht oci_bind_array_by_name() das längste Element im Eingabe-Array und nutzt dieses als maximale Länge der Array-Elemente.

`type`

  Sollte benutzt werden, um den Typ der PL/SQL-Array-Elemente zu bestimmen. Siehe untenstehende Liste verfügbarer Typen.

  - `SQLT_NUM` - für NUMBER-Arrays.

  - `SQLT_INT` - für INTEGER-Arrays (beachte: INTEGER ist ein Synonym für NUMBER(38), aber der `SQLT_NUM`-Typ wird nicht funktionieren, obwohl es Synonyme sind).

  - `SQLT_FLT` - für FLOAT-Arrays.

  - `SQLT_AFC` - für CHAR-Arrays.

  - `SQLT_CHR` - für VARCHAR2-Arrays.

  - `SQLT_VCS` - für VARCHAR-Arrays.

  - `SQLT_AVC` - für CHARZ-Arrays.

  - `SQLT_STR` - für STRING-Arrays.

  - `SQLT_LVC` - für LONG-VARCHAR-Arrays.

  - `SQLT_ODT` - für DATE-Arrays.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_bind_array_by_name()-Beispiel

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $create = "CREATE TABLE bind_example(name VARCHAR(20))";
    $stid = oci_parse($conn, $create);
    oci_execute($stid);

    $create_pkg = "
    CREATE OR REPLACE PACKAGE ARRAYBINDPKG1 AS
      TYPE ARRTYPE IS TABLE OF VARCHAR(20) INDEX BY BINARY_INTEGER;
      PROCEDURE iobind(c1 IN OUT ARRTYPE);
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg);
    oci_execute($stid);

    $create_pkg_body = "
    CREATE OR REPLACE PACKAGE BODY ARRAYBINDPKG1 AS
      CURSOR CUR IS SELECT name FROM bind_example;
      PROCEDURE iobind(c1 IN OUT ARRTYPE) IS
        BEGIN
        -- Masseneinfügung
        FORALL i IN INDICES OF c1
          INSERT INTO bind_example VALUES (c1(i));

        -- Abrufen und umkehren
        IF NOT CUR%ISOPEN THEN
          OPEN CUR;
        END IF;
        FOR i IN REVERSE 1..5 LOOP
          FETCH CUR INTO c1(i);
          IF CUR%NOTFOUND THEN
            CLOSE CUR;
            EXIT;
          END IF;
        END LOOP;
      END iobind;
    END ARRAYBINDPKG1;";
    $stid = oci_parse($conn, $create_pkg_body);
    oci_execute($stid);

    $stid = oci_parse($conn, "BEGIN arraybindpkg1.iobind(:c1); END;");
    $array = array("one", "two", "three", "four", "five");
    oci_bind_array_by_name($stid, ":c1", $array, 5, -1, SQLT_CHR);
    oci_execute($stid);

    var_dump($array);

    ?>

# oci_bind_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_bind_by_name — Binds a PHP variable to an Oracle placeholder

### Beschreibung

function oci_bind_by_name(
resource `$statement`,
string `$param`,
mixed `&$var`,
int `$max_length` = -1,
int `$type` = 0
): bool

Binds a PHP variable `var` to the Oracle bind variable placeholder `param`. Binding is important for Oracle database performance and also as a way to avoid SQL Injection security issues.

Binding allows the database to reuse the statement context and caches from previous executions of the statement, even if another user or process originally executed it. Binding reduces SQL Injection concerns because the data associated with a bind variable is never treated as part of the SQL statement. It does not need quoting or escaping.

PHP variables that have been bound can be changed and the statement re-executed without needing to re-parse the statement or re-bind.

In Oracle, bind variables are commonly divided into `IN` binds for values that are passed into the database, and `OUT` binds for values that are returned to PHP. A bind variable may be both `IN` and `OUT`. Whether a bind variable will be used for input or output is determined at run-time.

You must specify `max_length` when using an `OUT` bind so that PHP allocates enough memory to hold the returned value.

For `IN` binds it is recommended to set the `max_length` length if the statement is re-executed multiple times with different values for the PHP variable. Otherwise Oracle may truncate data to the length of the initial PHP variable value. If you don't know what the maximum length will be, then re-call oci_bind_by_name() with the current data size prior to each oci_execute() call. Binding an unnecessarily large length will have an impact on process memory in the database.

A bind call tells Oracle which memory address to read data from. For `IN` binds that address needs to contain valid data when oci_execute() is called. This means that the variable bound must remain in scope until execution. If it doesn't, unexpected results or errors such as "ORA-01460: unimplemented or unreasonable conversion requested" may occur. For `OUT` binds one symptom is no value being set in the PHP variable.

For a statement that is repeatedly executed, binding values that never change may reduce the ability of the Oracle optimizer to choose the best statement execution plan. Long running statements that are rarely re-executed may not benefit from binding. However in both cases, binding might be safer than joining strings into a SQL statement, as this can be a security risk if unfiltered user text is concatenated.

### Parameter-Liste

`statement`

  A valid OCI8 statement identifier.

`param`

  The colon-prefixed bind variable placeholder used in the statement. The colon is optional in `param`. Oracle does not use question marks for placeholders.

`var`

  The PHP variable to be associated with `param`

`max_length`

  Sets the maximum length for the data. If you set it to -1, this function will use the current length of `var` to set the maximum length. In this case the `var` must exist and contain data when oci_bind_by_name() is called.

`type`

  The datatype that Oracle will treat the data as. The default `type` used is `SQLT_CHR`. Oracle will convert the data between this type and the database column (or PL/SQL variable type), when possible.

  If you need to bind an abstract datatype (LOB/ROWID/BFILE) you need to allocate it first using the oci_new_descriptor() function. The `length` is not used for abstract datatypes and should be set to -1.

  Possible values for `type` are:

  - `SQLT_BFILEE` or `OCI_B_BFILE` - for BFILEs;

  - `SQLT_CFILEE` or `OCI_B_CFILEE` - for CFILEs;

  - `SQLT_CLOB` or `OCI_B_CLOB` - for CLOBs;

  - `SQLT_BLOB` or `OCI_B_BLOB` - for BLOBs;

  - `SQLT_RDD` or `OCI_B_ROWID` - for ROWIDs;

  - `SQLT_NTY` or `OCI_B_NTY` - for named datatypes;

  - `SQLT_INT` or `OCI_B_INT` - for integers;

  - `SQLT_CHR` - for VARCHARs;

  - `SQLT_BIN` or `OCI_B_BIN` - for RAW columns;

  - `SQLT_LNG` - for LONG columns;

  - `SQLT_LBI` - for LONG RAW columns;

  - `SQLT_RSET` - for cursors created with oci_new_cursor();

  - `SQLT_BOL` or `OCI_B_BOL` - for PL/SQL BOOLEANs (Requires Oracle Database 12c)

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Inserting data with oci_bind_by_name()

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (id NUMBER, text VARCHAR2(40));

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn,"INSERT INTO mytab (id, text) VALUES(:id_bv, :text_bv)");

    $id = 1;
    $text = "Data to insert     ";
    oci_bind_by_name($stid, ":id_bv", $id);
    oci_bind_by_name($stid, ":text_bv", $text);
    oci_execute($stid);

    // Table now contains: 1, 'Data to insert     '

    ?>

Beispiel #2 Binding once for multiple executions

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (id NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $a = array(1,3,5,7,11);  // data to insert

    $stid = oci_parse($conn, 'INSERT INTO mytab (id) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $v, 20);
    foreach ($a as $v) {
        $r = oci_execute($stid, OCI_DEFAULT);  // don't auto commit
    }
    oci_commit($conn); // commit everything at once

    // Table contains five rows: 1, 3, 5, 7, 11

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #3 Binding with a `foreach` loop

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT * FROM departments WHERE department_name = :dname AND location_id = :loc';
    $stid = oci_parse($conn, $sql);

    $ba = array(':dname' => 'IT Support', ':loc' => 1700);

    foreach ($ba as $key => $val) {

        // oci_bind_by_name($stid, $key, $val) does not work
        // because it binds each placeholder to the same location: $val
        // instead use the actual location of the data: $ba[$key]
        oci_bind_by_name($stid, $key, $ba[$key]);
    }

    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    foreach ($row as $item) {
        print $item."<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #4 Binding in a WHERE clause

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
    $stid = oci_parse($conn, $sql);
    $didbv = 60;
    oci_bind_by_name($stid, ':didbv', $didbv);
    oci_execute($stid);
    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['LAST_NAME'] ."<br>\n";
    }

    // Output is
    //    Austin
    //    Ernst
    //    Hunold
    //    Lorentz
    //    Pataballa

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #5 Binding with a LIKE clause

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Find all cities that begin with 'South'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE city LIKE :bv");
    $city = 'South%';  // '%' is a wildcard in SQL
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // Output is
    //   South Brunswick
    //   South San Francisco
    //   Southlake

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #6 Binding with REGEXP_LIKE

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    // Find all cities that contain 'ing'
    $stid = oci_parse($conn, "SELECT city FROM locations WHERE REGEXP_LIKE(city, :bv)");
    $city = '.*ing.*';
    oci_bind_by_name($stid, ":bv", $city);
    oci_execute($stid);
    oci_fetch_all($stid, $res);

    foreach ($res['CITY'] as $c) {
        print $c . "<br>\n";
    }
    // Output is
    //   Beijing
    //   Singapore

    oci_free_statement($stid);
    oci_close($conn);

    ?>

For a small, fixed number of IN clause conditions, use individual bind variables. Values unknown at run time can be set to NULL. This allows a single statement to be used by all application users, maximizing Oracle DB cache efficiency.

Beispiel #7 Binding Multiple Values in an IN Clause

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = 'SELECT last_name FROM employees WHERE employee_id in (:e1, :e2, :e3)';
    $stid = oci_parse($conn, $sql);
    $mye1 = 103;
    $mye2 = 104;
    $mye3 = NULL; // pretend we were not given this value
    oci_bind_by_name($stid, ':e1', $mye1);
    oci_bind_by_name($stid, ':e2', $mye2);
    oci_bind_by_name($stid, ':e3', $mye3);
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    foreach ($res['LAST_NAME'] as $name) {
        print $name ."<br>\n";
    }

    // Output is
    //   Ernst
    //   Hunold

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #8 Binding a ROWID returned by a query

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //   INSERT INTO mytab (id, salary, name) VALUES (1, 100, 'Chris');
    //   COMMIT;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT ROWID, name FROM mytab WHERE id = :id_bv FOR UPDATE');
    $id = 1;
    oci_bind_by_name($stid, ':id_bv', $id);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);
    $rid = $row['ROWID'];
    $name = $row['NAME'];

    // Change name to upper case & save the changes
    $name = strtoupper($name);
    $stid = oci_parse($conn, 'UPDATE mytab SET name = :n_bv WHERE ROWID = :r_bv');
    oci_bind_by_name($stid, ':n_bv', $name);
    oci_bind_by_name($stid, ':r_bv', $rid, -1, OCI_B_ROWID);
    oci_execute($stid);

    // The table now contains 1, 100, CHRIS

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #9 Binding a ROWID on INSERT

    <?php

    // This example inserts an id & name, and then updates the salary
    // Create the table with:
    //   CREATE TABLE mytab (id NUMBER, salary NUMBER, name VARCHAR2(40));
    //
    // Based on original ROWID example by thies at thieso dot net (980221)

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $sql = "INSERT INTO mytab (id, name) VALUES(:id_bv, :name_bv)
            RETURNING ROWID INTO :rid";

    $ins_stid = oci_parse($conn, $sql);

    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_bind_by_name($ins_stid, ":id_bv",   $id,    10);
    oci_bind_by_name($ins_stid, ":name_bv", $name,  32);
    oci_bind_by_name($ins_stid, ":rid",     $rowid, -1, OCI_B_ROWID);

    $sql = "UPDATE mytab SET salary = :salary WHERE ROWID = :rid";
    $upd_stid = oci_parse($conn, $sql);
    oci_bind_by_name($upd_stid, ":rid", $rowid, -1, OCI_B_ROWID);
    oci_bind_by_name($upd_stid, ":salary", $salary,   32);

    // ids and names to insert
    $data = array(1111 => "Larry",
                  2222 => "Bill",
                  3333 => "Jim");

    // Salary of each person
    $salary = 10000;

    // Insert and immediately update each row
    foreach ($data as $id => $name) {
        oci_execute($ins_stid);
        oci_execute($upd_stid);
    }

    $rowid->free();
    oci_free_statement($upd_stid);
    oci_free_statement($ins_stid);

    // Show the new rows
    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        var_dump($row);
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #10 Binding for a PL/SQL stored function

    <?php

    //  Before running the PHP program, create a stored function in
    //  SQL*Plus or SQL Developer:
    //
    //  CREATE OR REPLACE FUNCTION myfunc(p IN NUMBER) RETURN NUMBER AS
    //  BEGIN
    //      RETURN p * 3;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p = 8;

    $stid = oci_parse($conn, 'begin :r := myfunc(:p); end;');
    oci_bind_by_name($stid, ':p', $p);

    // The return value is an OUT bind. The default type will be a string
    // type so binding a length 40 means that at most 40 digits will be
    // returned.
    oci_bind_by_name($stid, ':r', $r, 40);

    oci_execute($stid);

    print "$r\n";   // prints 24

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #11 Binding parameters for a PL/SQL stored procedure

    <?php

    //  Before running the PHP program, create a stored procedure in
    //  SQL*Plus or SQL Developer:
    //
    //  CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
    //  BEGIN
    //      p2 := p1 * 2;
    //  END;

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $p1 = 8;

    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);

    // The second procedure parameter is an OUT bind. The default type
    // will be a string type so binding a length 40 means that at most 40
    // digits will be returned.
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // prints 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #12 Binding a CLOB column

    <?php

    // Before running, create the table:
    //     CREATE TABLE mytab (mykey NUMBER, myclob CLOB);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $mykey = 12343;  // arbitrary key for this example;

    $sql = "INSERT INTO mytab (mykey, myclob)
            VALUES (:mykey, EMPTY_CLOB())
            RETURNING myclob INTO :myclob";

    $stid = oci_parse($conn, $sql);
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
    oci_execute($stid, OCI_DEFAULT);
    $clob->save("A very long string");

    oci_commit($conn);

    // Fetching CLOB data

    $query = 'SELECT myclob FROM mytab WHERE mykey = :mykey';

    $stid = oci_parse ($conn, $query);
    oci_bind_by_name($stid, ":mykey", $mykey, 5);
    oci_execute($stid);

    print '<table border="1">';
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
        print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
        // In a loop, freeing the large variable before the 2nd fetch reduces PHP's peak memory usage
        unset($row);
    }
    print '</table>';

    ?>

Beispiel #13 Binding a PL/SQL BOOLEAN

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $plsql =
      "begin
        :output1 := true;
        :output2 := false;
       end;";

    $s = oci_parse($c, $plsql);
    oci_bind_by_name($s, ':output1', $output1, -1, OCI_B_BOL);
    oci_bind_by_name($s, ':output2', $output2, -1, OCI_B_BOL);
    oci_execute($s);
    var_dump($output1);  // true
    var_dump($output2);  // false

    ?>

### Anmerkungen

Warnung

Do not use addslashes() and oci_bind_by_name() simultaneously as no quoting is needed. Any magically applied quotes will be written into your database because oci_bind_by_name() inserts data verbatim and does not remove quotes or escape characters.

> Hinweis:

> If you bind a string to a `CHAR` column in a `WHERE` clause, remember that Oracle uses blank-padded comparison semantics for `CHAR` columns. Your PHP variable should be blank padded to the same width as the column for the `WHERE` clause to succeed.

> Hinweis:

> The PHP `var` argument is a reference. Some forms of loops do not work as expected:

>     <?php
>     foreach ($myarray as $key => $value)  {
>         oci_bind_by_name($stid, $key, $value);
>     }
>     ?>

> This binds each key to the location of $value, so all bound variables end up pointing to the last loop iteration's value. Instead use the following:

>     <?php
>     foreach ($myarray as $key => $value) {
>         oci_bind_by_name($stid, $key, $myarray[$key]);
>     }
>     ?>

### Siehe auch

- oci_bind_array_by_name() - Bindet ein PHP-Array an einen Oracle-PL/SQL-Arrayparameter
- oci_parse() - Prepares an Oracle statement for execution

# oci_cancel

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_cancel — Bricht das Lesen eines Zeigers ab

### Beschreibung

function oci_cancel(resource `$statement`): bool

Annulliert einen Zeiger, gibt alle verknüpften Ressourcen frei und beendet die Möglichkeit von dem Zeiger zu lesen.

### Parameter-Liste

`statement`

  Ein OCI-Statement.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# oci_client_version

(PHP 5 >= 5.3.7, PHP 7, PHP 8, PECL OCI8 >= 1.4.6)

oci_client_version — Returns the Oracle client library version

### Beschreibung

function oci_client_version(): string

Returns a string containing the version number of the Oracle C client library that PHP is linked with.

### Parameter-Liste

None

### Rückgabewerte

Returns the version number as a String.

### Beispiele

Beispiel #1 oci_client_version() example

    <?php
        echo "Client Version: " . oci_client_version(); // Client version: 19.9.0.0.0
    ?>

### Anmerkungen

> Hinweis:

> Oracle libraries before 10gR2 do not have the underlying functionality to get the client library version number. The string "Unknown" will be returned in this case.

### Siehe auch

- oci_server_version() - Returns the Oracle Database version

# oci_close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_close — Schließt eine Oracle-Verbindung

### Beschreibung

function oci_close(resource `$connection`): ?bool

Hebt die Verbindung `connection` auf. Die zugrundeliegende Datenbank-Verbindung wird geschlossen, wenn sie von keiner anderen Ressource verwendet wird und mit oci_connect() oder oci_new_connect() erzeugt wurde.

Es wird empfohlen, nicht mehr benötigte Verbindungen zu schließen, da dies Datenbankressourcen für andere Nutzer freigibt.

### Parameter-Liste

`connection`

  Ein Zeiger auf eine Oracle-Verbindung, die von oci_connect(), oci_pconnect() oder oci_new_connect() zurückgegeben wurde.

### Rückgabewerte

Gibt `null` zurück, wenn oci8.old_oci_close_semantics aktiviert ist, und andernfalls `true`.

### Beispiele

Beispiel #1 Schließen einer Verbindung

Ressourcen, die mit einer Verbindung assoziiert sind, sollten geschlossen werden, um sicherzustellen, dass die zugrundeliegende Datenbankverbindung ordnungsgemäß beendet wird und die Datenbankressourcen freigegeben werden.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');
    $r = oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    // Freigeben des Anweisungsbezeichners, wenn die Verbindung geschlossen wird
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #2 Datenbankverbindungen werden nicht geschlossen, bevor alle Referenzen geschlossen wurden

Der interne Referenzzähler eines Verbindungsbezeichners muss null (0) sein, bevor die zugrundeliegende Verbindung zur Datenbank geschlossen wird.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM departments');  // dies erhöht den Referenzzähler von $conn
    oci_execute($stid);
    oci_fetch_all($stid, $res);
    var_dump($res);

    oci_close($conn);

    // $conn ist im Skript nicht mehr verwendbar, aber die zugrundeliegende
    // Datenbankverbindung wird solange offengehalten, bis $stid freigegeben wird.
    var_dump($conn);  // gibt NULL aus

    // Während PHP schläft, zeigt das Abfragen der Oracle-V$SESSION-Ansicht in
    // einem Terminal-Fenster, dass der Datenbanknutzer immer noch verbunden ist.
    sleep(10);

    // Wenn $stid freigegegben wird, wird die Datenbankverbindung tatsächlich
    // geschlossen
    oci_free_statement($stid);

    // Während PHP schläft, zeigt das Abfragen der Oracle-V$SESSION-Ansicht in
    // einem Terminal-Fenster, dass der Datenbanknutzer getrennt wurde
    sleep(10);

    ?>

Beispiel #3 Schließen einer Verbindung, die mehr als einmal geöffnet wurde

Wenn Datenbank-Anmeldedaten wiederverwendet wurden, müssen beide Verbindungen geschlossen werden, bevor die zugrundeliegende Datenbankverbindung geschlossen wird.

    <?php

    $conn1 = oci_connect('hr', 'welcome', 'localhost/XE');

    // Die Verwendung derselben Anmeldedaten benutzt dieselbe zugrundeliegende
    // Datenbankverbindung nochmals. Jegliche unbestätigten Änderungen, die auf
    // $conn1 durchgeführt wurden, sind in $conn2 sichtbar
    $conn2 = oci_connect('hr', 'welcome', 'localhost/XE');

    // Während PHP schläft, zeigt das Abfragen der Oracle V$SESSION Ansicht in einem
    // Terminal-Fenster, dass nur ein Datenbanknutzer verbunden ist.
    sleep(10);

    oci_close($conn1); // schließt nicht die zugrundeliegende Datenbankverbindung
    var_dump($conn1);  // gibt NULL aus, weil die Variable $conn1 nicht mehr verwendbar ist
    var_dump($conn2);  // zeigt an, dass $conn2 noch immer eine gültige Verbindungsressource ist

    ?>

Beispiel #4 Verbindungen werden geschlossen, wenn die Variablen den Geltungsbereich verlassen

Wenn alle Variablen, die eine Verbindung referenzieren, den Geltungsbereich verlassen und von PHP freigegeben werden, erfolgt ein Rollback (falls nötig) und die zugrundeliegende Verbindung zur Datenbank wird geschlossen.

    <?php

    function myfunc() {
        $conn = oci_connect('hr', 'hrpwd', 'localhost/XE');
        if (!$conn) {
            $e = oci_error();
            trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
        }

        $stid = oci_parse($conn, 'UPDATE mytab SET id = 100');
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
        return "Beendet";
    }

    $r = myfunc();
    // In diesem Moment erfolgte ein Rollback und die zugrundeliegende
    // Datenbankverbindung wurde freigegeben.

    print $r;  // zeigt den Funktionsrückgabewert "Beendet" an

    ?>

### Anmerkungen

> Hinweis:

> Variablen, die eine Abhängigkeit vom Verbindungsbezeichner haben, wie von oci_parse() zurückgegebene Anweisungsbezeichner, müssen ebenfalls freigegeben werden, bevor die zugrundeliegende Datenbankverbindung geschlossen wird.

> Hinweis:

> Die Funktion oci_close() schließt nicht zugrundeliegende Datenbankverbindungen, die mit oci_pconnect() erzeugt wurden.

### Siehe auch

- oci_connect() - Connect to an Oracle database
- oci_free_statement() - Gibt alle verknüpften Ressourcen eines Statements oder Zeigers frei.

# oci_commit

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_commit — Commits the outstanding database transaction

### Beschreibung

function oci_commit(resource `$connection`): bool

Commits the outstanding transaction for the Oracle `connection`. A commit ends the current transaction and makes permanent all changes. It releases all locks held.

A transaction begins when the first SQL statement that changes data is executed with oci_execute() using the `OCI_NO_AUTO_COMMIT` flag. Further data changes made by other statements become part of the same transaction. Data changes made in a transaction are temporary until the transaction is committed or rolled back. Other users of the database will not see the changes until they are committed.

When inserting or updating data, using transactions is recommended for relational data consistency and for performance reasons.

### Parameter-Liste

`connection`

  An Oracle connection identifier, returned by oci_connect(), oci_pconnect(), or oci_new_connect().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_commit() example

    <?php

    // Insert into several tables, rolling back the changes if an error occurs

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // The OCI_NO_AUTO_COMMIT flag tells Oracle not to commit the INSERT immediately
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // rollback changes to both tables
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Commit the changes to both tables
    $r = oci_commit($conn);
    if (!$r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

### Anmerkungen

> Hinweis:

> Transactions are automatically rolled back when you close the connection, or when the script ends, whichever is soonest. You need to explicitly call oci_commit() to commit the transaction.

> Any call to oci_execute() that uses `OCI_COMMIT_ON_SUCCESS` mode explicitly or by default will commit any previous uncommitted transaction.

> Any Oracle DDL statement such as `CREATE` or `DROP` will automatically commit any uncommitted transaction.

### Siehe auch

- oci_execute() - Executes a statement
- oci_rollback() - Rolls back the outstanding database transaction

# oci_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_connect — Connect to an Oracle database

### Beschreibung

function oci_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Returns a connection identifier needed for most other OCI8 operations.

For performance, most applications should use persistent connections with oci_pconnect() instead of oci_connect(). See Connection Handling for general information on connection management and connection pooling.

The second and subsequent calls to oci_connect() with the same parameters will return the connection handle returned from the first call. This means that transactions in one handle are also in the other handles, because they use the same underlying database connection. If two handles need to be transactionally isolated from each other, use oci_new_connect() instead.

### Parameter-Liste

`username`

  The Oracle user name.

`password`

  The password for `username`.

`connection_string`

  Beinhaltet die `Oracle-Instanz`, mit der verbunden werden soll. Dies kann eine » Easy-Connect-Zeichenkette, ein Connect-Name aus der Datei tnsnames.ora oder der Name einer lokalen Oracle-Instanz sein.

  Wenn dies nicht angegebe wird oder `null` ist, verwendet PHP Umgebungsvariablen wie `TWO_TASK` (unter Linux), `LOCAL` (unter Windows) oder `ORACLE_SID` um die `Oracle-Instanz` zu ermitteln, mit der verbunden werden soll.

  Um die benannte Easy Connect Methode zu verwenden, muss PHP gegen die Clientbibliotheken von Oracle 10g oder höher gelinkt sein. Die Easy-Connect-Zeichenkette für Oracle 10g hat den Aufbau: [//]host_name[:port][/service_name]. Für Oracle 11g ist die Syntax: [//]host_name[:port][/service_name][:server_type][/instance_name]. Weitere Optionen wurden mit Oracle 19c eingeführt, darunter die timeout- und die keep-alive-Einstellungen. Siehe dazu die Oracle-Dokumentation. Die Servicenamen können ermittelt werden, indem man das Oracle-Hilfswerkzeug `lsnrctl status` auf dem Datenbankserver ausführt.

  Die Datei tnsnames.ora kann sich im Oracle Net Suchpfad befinden, welcher /der/pfad/zu/instantclient/network/admin, $ORACLE_HOME/network/admin sowie /etc beinhaltet. Alternativ kann `TNS_ADMIN` so gesetzt werden, dass $TNS_ADMIN/tnsnames.ora gelesen wird. Es muss sichergestellt sein, dass der Webserver eine Leseberechtigung für die Datei besitzt.

`encoding`

  Bestimmt den Zeichensatz, der von den Oracle Client Bibliotheken verwendet wird. Dieser Zeichensatz muss nicht dem von der Datenbank verwendeten Zeichensatz entsprechen. Wenn diese nicht übereinstimmen, wird Oracle bestmöglich versuchen, die Daten in den Datenbankzeichensatz zu übersetzen. Abhängig von den Zeichensätzen kann dies zu unbrauchbaren Ergebnissen führen. Diese Konvertierung führt auch zu einem erhöhten Zeitbedarf.

  Falls nicht angegeben, werden die Oracle Client Bibliotheken versuchen, den Zeichensatz aus der Umgebungsvariablen `NLS_LANG` auszulesen.

  Die Übergabe dieses Parameters verringert die Zeit für den Verbindungsaufbau.

`session_mode`

  Dieser Parameter ist seit PHP 5 (PECL OCI8 1.1) verfügbar und akzeptiert die folgenden Werte: `OCI_DEFAULT`, `OCI_SYSOPER` und `OCI_SYSDBA`. Falls entweder `OCI_SYSOPER` oder `OCI_SYSDBA` angegeben wurden wird diese Funktion versuchen die priviligierte Verbindung mit externen Credentials aufzubauen. Um diese einzuschalten muss man oci8.privileged_connect auf `On` setzen.

  PHP 5.3 (PECL OCI8 1.3.4) hat den Wert `OCI_CRED_EXT` eingeführt. Dies konfiguriert Oracle dazu eine externe oder Os-Authentifizierung vorzunehmen, welche in der Datenbank konfiguriert werden muss. Der Schalter `OCI_CRED_EXT` kann nur mit dem Benutzernamen "/" und einem leeren Passwort verwendet werden. oci8.privileged_connect kann entweder `On` oder `Off` sein.

  `OCI_CRED_EXT` kann mit `OCI_SYSOPER` oder `OCI_SYSDBA` kombiniert werden.

  `OCI_CRED_EXT` ist auf Windows-Systemen aus sicherheitsgründen nicht unterstützt.

### Rückgabewerte

Returns a connection identifier or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` is now nullable.

### Beispiele

Beispiel #1 Basic oci_connect() using Easy Connect syntax

    <?php

    // Connects to the XE service (i.e. database) on the "localhost" machine
    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Beispiel #2 Basic oci_connect() using a Network Connect name

    <?php

    // Connects to the MYDB database described in tnsnames.ora file,
    // One example tnsnames.ora entry for MYDB could be:
    //   MYDB =
    //     (DESCRIPTION =
    //       (ADDRESS = (PROTOCOL = TCP)(HOST = mymachine.oracle.com)(PORT = 1521))
    //       (CONNECT_DATA =
    //         (SERVER = DEDICATED)
    //         (SERVICE_NAME = XE)
    //       )
    //     )

    $conn = oci_connect('hr', 'welcome', 'MYDB');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Beispiel #3 oci_connect() with an explicit character set

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE', 'AL32UTF8');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Beispiel #4 Using multiple calls to oci_connect()

    <?php

    $c1 = oci_connect("hr", "welcome", 'localhost/XE');
    $c2 = oci_connect("hr", "welcome", 'localhost/XE');

    // Both $c1 and $c2 show the same PHP resource id meaning they use the
    // same underlying database connection
    echo "c1 is $c1<br>\n";
    echo "c2 is $c2<br>\n";

    function create_table($conn)
    {
        $stmt = oci_parse($conn, "create table hallo (test varchar2(64))");
        oci_execute($stmt);
        echo "Created table<br>\n";
    }

    function drop_table($conn)
    {
        $stmt = oci_parse($conn, "drop table hallo");
        oci_execute($stmt);
        echo "Dropped table<br>\n";
    }

    function insert_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "insert into hallo
                  values(to_char(sysdate,'DD-MON-YY HH24:MI:SS'))");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname inserted row without committing<br>\n";
    }

    function rollback($connname, $conn)
    {
        oci_rollback($conn);
        echo "$connname rollback<br>\n";
    }

    function select_data($connname, $conn)
    {
        $stmt = oci_parse($conn, "select * from hallo");
        oci_execute($stmt, OCI_DEFAULT);
        echo "$connname ----selecting<br>\n";
        while (oci_fetch($stmt)) {
            echo "    " . oci_result($stmt, "TEST") . "<br>\n";
        }
        echo "$connname ----done<br>\n";
    }

    create_table($c1);

    insert_data('c1', $c1);   // Insert a row using c1
    sleep(2);                 // sleep to show a different timestamp for the 2nd row
    insert_data('c2', $c2);   // Insert a row using c2

    select_data('c1', $c1);   // Results of both inserts are returned
    select_data('c2', $c2);   // Results of both inserts are returned

    rollback('c1', $c1);      // Rollback using c1

    select_data('c1', $c1);   // Both inserts have been rolled back
    select_data('c2', $c2);

    drop_table($c1);

    // Closing one of the connections makes the PHP variable unusable, but
    // the other could be used
    oci_close($c1);
    echo "c1 is $c1<br>\n";
    echo "c2 is $c2<br>\n";

    // Output is:
    //    c1 is Resource id #5
    //    c2 is Resource id #5
    //    Created table
    //    c1 inserted row without committing
    //    c2 inserted row without committing
    //    c1 ----selecting
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c1 ----done
    //    c2 ----selecting
    //        09-DEC-09 12:14:43
    //        09-DEC-09 12:14:45
    //    c2 ----done
    //    c1 rollback
    //    c1 ----selecting
    //    c1 ----done
    //    c2 ----selecting
    //    c2 ----done
    //    Dropped table
    //    c1 is
    //    c2 is Resource id #5

    ?>

### Anmerkungen

> Hinweis:

> An incorrectly installed or configured OCI8 extension will often manifest itself as a connection problem or error. See Installing/Configuring for troubleshooting information.

### Siehe auch

- oci_pconnect() - Connect to an Oracle database using a persistent connection
- oci_new_connect() - Connect to the Oracle server using a unique connection
- oci_close() - Schließt eine Oracle-Verbindung

# oci_define_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_define_by_name — Associates a PHP variable with a column for query fetches

### Beschreibung

function oci_define_by_name(
resource `$statement`,
string `$column`,
mixed `&$var`,
int `$type` = 0
): bool

Associates a PHP variable with a column for query fetches using oci_fetch().

The oci_define_by_name() call must occur before executing oci_execute().

### Parameter-Liste

`statement`

  Der Identifizierer eines gültigen OCI8-Ausdrucks, der von oci_parse() erzeugt und von oci_execute() oder einem `REF CURSOR`-Ausdruck verwendet wird.

`column`

  The column name used in the query.

  Use uppercase for Oracle's default, non-case sensitive column names. Use the exact column name case for case-sensitive column names.

`var`

  The PHP variable that will contain the returned column value.

`type`

  The data type to be returned. Generally not needed. Note that Oracle-style data conversions are not performed. For example, `SQLT_INT` will be ignored and the returned data type will still be `SQLT_CHR`.

  You can optionally use oci_new_descriptor() to allocate LOB/ROWID/BFILE descriptors.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_define_by_name() example

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // The defines MUST be done before executing
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // Each fetch populates the previously defined variables with the next row's data
    while (oci_fetch($stid)) {
        echo "Location id $locid is $city<br>\n";
    }

    // Displays:
    //   Location id 1000 is Roma
    //   Location id 1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #2 oci_define_by_name() with case sensitive column names

    <?php

    /*
      Before running, create the table with a case sensitive column name:
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Use uppercase for non case-sensitive column names
    oci_define_by_name($stid, 'ID', $id);

    // Use the exact case for case-sensitive column names
    oci_define_by_name($stid, 'MyDescription', $mydesc);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo "id $id is $mydesc<br>\n";
    }

    // Displays:
    //   id 1 is Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #3 oci_define_by_name() with LOB columns

    <?php

    /*
      Before running, create the table:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // The defines MUST be done before executing
    oci_define_by_name($stid, 'ID', $id);
    oci_define_by_name($stid, 'FRUIT', $fruit);  // $fruit will become a LOB descriptor

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " is " . $fruit->load(100) . "<br>\n";
    }

    // Displays:
    //   1 is apple
    //   2 is orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #4 oci_define_by_name() with an explicit type

    <?php

    /*
      Before running, create the table:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // The defines MUST be done before executing
    oci_define_by_name($stid, 'ID', $id);

    $fruit = oci_new_descriptor($conn, OCI_D_LOB);
    oci_define_by_name($stid, 'FRUIT', $fruit, OCI_D_CLOB);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " is " . $fruit->load(100) . "<br>\n";
    }

    // Displays:
    //   1 is apple
    //   2 is orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Siehe auch

- oci_fetch() - Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab
- oci_new_descriptor() - Initializes a new empty LOB or FILE descriptor

# oci_error

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_error — Liefert den letzten Fehler

### Beschreibung

function oci_error(?resource `$connection_or_statement` = `null`): array|false

Gibt den zuletzt gefundenen Fehler zurück.

Die Funktion sollte unmittelbar nach dem Auftreten eines Fehlers aufgerufen werden. Fehler werden durch eine erfolgreiche Anweisung gelöscht.

### Parameter-Liste

`connection_or_statement`

  Bei den meisten Fehlern ist `connection_or_statement` die Ressourcen-Kennung, die an den fehlschlagenden Funktionsaufruf übergeben wurde. Bei Verbindungsfehlern mit oci_connect(), oci_new_connect() oder oci_pconnect() sollte `null` übergeben werden.

### Rückgabewerte

Wenn kein Fehler gefunden wurde, gibt oci_error() `false` zurück. Andernfalls gibt oci_error() die Fehlerinformationen als assoziatives Array zurück.

Beschreibung des oci_error()-Arrays
Schlüssel | Typ | Beschreibung
--- | --- | ---
`code` | int | Die Oracle-Fehlernummer.
`message` | string | Die Oracle-Fehlermeldung.
`offset` | int | Die Byteposition des Fehlers in einer SQL-Anweisung. Gab es keine Anweisung, dann ist dies `0`.
`sqltext` | string | Der Text der SQL-Anweisung. Gab es keine Anweisung, dann ist dies eine leere Zeichenkette.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_or_statement` ist jetzt nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 Zeigt die Oracle-Fehlermeldung nach einem Verbindungsfehler an

    <?php
    $conn = oci_connect("hr", "welcome", "localhost/XE");
    if (!$conn) {
        $e = oci_error();   // bei oci_connect-Fehlern keine Kennung übergeben
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Beispiel #2 Zeigt die Oracle-Fehlermeldung nach einem Parser-Fehler an

    <?php
    $stid = oci_parse($conn, "select ' from dual");  // fehlerhaftes Anführungszeichen
    if (!$stid) {
        $e = oci_error($conn);  // bei oci_parse-Fehlern Verbindungskennung übergeben
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }
    ?>

Beispiel #3 Anzeigen der Oracle-Fehlermeldung, der problematischen Anweisung und der Position des Problems nach einem Ausführungsfehler

    <?php
    $stid = oci_parse($conn, "select does_not_exist from dual");
    $r = oci_execute($stid);
    if (!$r) {
        $e = oci_error($stid); // bei oci_execute-Fehlern die Anweisungskennung übergeben
        print htmlentities($e['message']);
        print "\n<pre>\n";
        print htmlentities($e['sqltext']);
        printf("\n%".($e['offset']+1)."s", "^");
        print  "\n</pre>\n";
    }
    ?>

# oci_execute

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_execute — Executes a statement

### Beschreibung

function oci_execute(resource `$statement`, int `$mode` = `OCI_COMMIT_ON_SUCCESS`): bool

Executes a `statement` previously returned from oci_parse().

After execution, statements like `INSERT` will have data committed to the database by default. For statements like `SELECT`, execution performs the logic of the query. Query results can subsequently be fetched in PHP with functions like oci_fetch_array().

Each parsed statement may be executed multiple times, saving the cost of re-parsing. This is commonly used for `INSERT` statements when data is bound with oci_bind_by_name().

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

`mode`

  An optional second parameter can be one of the following constants:

  Execution Modes
  Constant | Description
  --- | ---
  `OCI_COMMIT_ON_SUCCESS` | Automatically commit all outstanding changes for this connection when the statement has succeeded. This is the default.
  `OCI_DESCRIBE_ONLY` | Make query meta data available to functions like oci_field_name() but do not create a result set. Any subsequent fetch call such as oci_fetch_array() will fail.
  `OCI_NO_AUTO_COMMIT` | Do not automatically commit changes.

  Using `OCI_NO_AUTO_COMMIT` mode starts or continues a transaction. Transactions are automatically rolled back when the connection is closed, or when the script ends. Explicitly call oci_commit() to commit a transaction, or oci_rollback() to abort it.

  When inserting or updating data, using transactions is recommended for relational data consistency and for performance reasons.

  If `OCI_NO_AUTO_COMMIT` mode is used for any statement including queries, and oci_commit() or oci_rollback() is not subsequently called, then OCI8 will perform a rollback at the end of the script even if no data was changed. To avoid an unnecessary rollback, many scripts do not use `OCI_NO_AUTO_COMMIT` mode for queries or PL/SQL. Be careful to ensure the appropriate transactional consistency for the application when using oci_execute() with different modes in the same script.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_execute() for queries

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Beispiel #2 oci_execute() without specifying a mode example

    <?php

    // Before running, create the table:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');

    oci_execute($stid); // The row is committed and immediately visible to other users

    ?>

Beispiel #3 oci_execute() with `OCI_NO_AUTO_COMMIT` example

    <?php

    // Before running, create the table:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (:bv)');
    oci_bind_by_name($stid, ':bv', $i, 10);
    for ($i = 1; $i <= 5; ++$i) {
        oci_execute($stid, OCI_NO_AUTO_COMMIT);
    }
    oci_commit($conn);  // commits all new values: 1, 2, 3, 4, 5

    ?>

Beispiel #4 oci_execute() with different commit modes example

    <?php

    // Before running, create the table:
    //   CREATE TABLE MYTABLE (col1 NUMBER);

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);  // data not committed

    $stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (456)');
    oci_execute($stid);  // commits both 123 and 456 values

    ?>

Beispiel #5 oci_execute() with `OCI_DESCRIBE_ONLY` example

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM locations');
    oci_execute($s, OCI_DESCRIBE_ONLY);
    for ($i = 1; $i <= oci_num_fields($stid); ++$i) {
        echo oci_field_name($stid, $i) . "<br>\n";
    }

    ?>

### Anmerkungen

> Hinweis:

> Transactions are automatically rolled back when connections are closed, or when the script ends, whichever is soonest. Explicitly call oci_commit() to commit a transaction.

> Any call to oci_execute() that uses `OCI_COMMIT_ON_SUCCESS` mode explicitly or by default will commit any previous uncommitted transaction.

> Any Oracle DDL statement such as `CREATE` or `DROP` will automatically commit any uncommitted transaction.

> Hinweis:

> Because the oci_execute() function generally sends the statement to the database, oci_execute() can identify some statement syntax errors that the lightweight, local oci_parse() function does not.

### Siehe auch

- oci_parse() - Prepares an Oracle statement for execution

# oci_fetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch — Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab

### Beschreibung

function oci_fetch(resource `$statement`): bool

Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab, auf den entweder mit oci_result() zugegriffen werden kann, oder unter Verwendung von Variablen, die zuvor mit oci_define_by_name() definiert wurden.

Allgemeine Information zum Abrufen von Daten sind der Dokumentation von oci_fetch_array() zu entnehmen.

### Parameter-Liste

`statement`

  Der Identifizierer eines gültigen OCI8-Ausdrucks, der von oci_parse() erzeugt und von oci_execute() oder einem `REF CURSOR`-Ausdruck verwendet wird.

### Rückgabewerte

Gibt im Erfolgsfall `true` zurück, `false` wird zurückgegeben, wenn keine weiteren Zeilen mehr in `statement` vorhanden sind.

### Beispiele

Beispiel #1 oci_fetch() mit definierten Variablen

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // Die Definitionen MÜSSEN vor der Ausführung erfolgen
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // Jedes Abrufen füllt die zuvor definierten Variablen mit den Daten der
    // nächsten Zeile
    while (oci_fetch($stid)) {
        echo "Standort-ID $locid ist $city<br>\n";
    }

    // Ausgabe:
    //   Standort-ID 1000 ist Rom
    //   Standort-ID 1100 ist Venedig

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #2 oci_fetch() mit oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " ist ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Ausgabe:
    //   1000 ist Rom
    //   1100 ist Venedig

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion gibt keine Zeilen aus einer impliziten Ergebnismenge einer Oracle-Datenbank zurück. Verwenden Sie stattdessen die Funktion oci_fetch_array().

### Siehe auch

- oci_define_by_name() - Associates a PHP variable with a column for query fetches
- oci_fetch_all() - Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab
- oci_fetch_array() - Liefert die nächste Zeile einer Abfrage als assoziatives oder numerisches Array
- oci_fetch_assoc() - Liefert die nächste Zeile einer Abfrage als assoziatives Array
- oci_fetch_object() - Liefert die nächste Zeile einer Abfrage als Objekt
- oci_fetch_row() - Liefert die nächste Zeile einer Abfrage als numerisches Array
- oci_result() - Returns field's value from the fetched row

# oci_fetch_all

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_all — Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab

### Beschreibung

function oci_fetch_all(
resource `$statement`,
array `&$output`,
int `$offset` = 0,
int `$limit` = -1,
int `$flags` = OCI_FETCHSTATEMENT_BY_COLUMN | OCI_ASSOC
): int

Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab. Standardmäßig werden alle Datensätze zurückgegeben.

Diese Funktion kann nur einmal für jede Abfrage, die mit oci_execute() ausgeführt wurde, aufgerufen werden.

### Parameter-Liste

`statement`

  Der Identifizierer eines gültigen OCI8-Ausdrucks, der von oci_parse() erzeugt und von oci_execute() oder einem `REF CURSOR`-Ausdruck verwendet wird.

`output`

  Die Variable, die die zurückgegebenen Datensätze enthalten wird.

  LOB-Spalten werden als Zeichenketten zurückgegeben, sofern Oracle die Umwandlung unterstützt.

  Informationen, wie Daten und Typen abgerufen werden, sind der Dokumentation von oci_fetch_array() zu entnehmen.

`offset`

  Die Anzahl der zu verwerfenden Anfangsdatensätze beim Abrufen des Ergebnisses. Standardwert ist 0, sodass vom ersten Datensatz an zurückgegeben wird.

`limit`

  Die Anzahl der zurückzugebenden Datensätze. Der Standardwert ist -1, was bedeutet, dass alle Datensätze von `offset` + 1 an zurückgegeben werden.

`flags`

  Der Parameter `flags` legt die Array-Struktur fest und ob assoziative Arrays verwendet werden sollen.

  Struktur-Modi für das oci_fetch_all()-Array
  Konstante | Beschreibung
  --- | ---
  `OCI_FETCHSTATEMENT_BY_ROW` | Das äußere Array wird ein Unterarray pro Abfragedatensatz enthalten.
  `OCI_FETCHSTATEMENT_BY_COLUMN` | Das äußere Array wird ein Unterarray pro Abfragespalte enthalten. Das ist der Standardwert.

  Arrays können entweder nach Spaltennamen oder numerisch indexiert werden. Nur ein Index-Modus wird zurückgegeben.

  Index-Modi für das oci_fetch_all()-Array
  Konstante | Beschreibung
  --- | ---
  `OCI_NUM` | Numerische Indizes werden für das Array jeder Spalte verwendet.
  `OCI_ASSOC` | Assoziative Indizes werden für das Array jeder Spalte verwendet. Das ist der Standardwert.

  Der Additionsoperator "+" ist zu verwenden, um eine Kombination von Array-Struktur- und Index-Modi zu wählen.

  Für Spaltennamen, die Groß- und Kleinschreibung nicht unterscheiden, was bei Oracle der Standard ist, werden Arrayschlüssel in Großschreibung verwendet. Spalten, die Groß- und Kleinschreibung unterscheiden, verwenden die genaue Schreibweise. var_dump() kann auf `output` angewendet werden, um die richtige Schreibweise für jede Abfrage zu prüfen.

  Abfragen, die mehr als eine Spalte mit demselben Namen haben, sollten Spaltenaliase verwenden. Andernfalls wird nur eine der Spalten in einem assoziativen Array auftauchen.

### Rückgabewerte

Gibt die Anzahl der Datensätze in `output` zurück, die 0 oder mehr sein kann.

### Beispiele

Beispiel #1 oci_fetch_all()-Beispiel

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res);

    echo "$nrows Datensätze abgerufen<br>\n";
    var_dump($res);

    // die var_dump Ausgabe ist:
    //    2 Datensätze abgerufen
    //    array(2) {
    //      ["POSTAL_CODE"]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(6) "10934x"
    //      }
    //      ["CITY"]=>
    //      array(2) {
    //        [0]=>
    //        string(4) "Rom"
    //        [1]=>
    //        string(6) "Venedig"
    //      }
    //    }

    // ordentliche Ausgabe der Ergebnisse
    echo "<table border='1'>\n";
    foreach ($res as $col) {
        echo "<tr>\n";
        foreach ($col as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #2 oci_fetch_all()-Beispiel mit `OCI_FETCHSTATEMENT_BY_ROW`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW);

    echo "$nrows Datensätze abgerufen<br>\n";
    var_dump($res);

    // die Ausgabe ist:
    //    2 Datensätze abgerufen
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "00989x"
    //        ["CITY"]=>
    //        string(4) "Rom"
    //      }
    //      [1]=>
    //      array(2) {
    //        ["POSTAL_CODE"]=>
    //        string(6) "10934x"
    //        ["CITY"]=>
    //        string(6) "Venedig"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #3 oci_fetch_all() mit `OCI_NUM`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
    oci_execute($stid);

    $nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW + OCI_NUM);

    echo "$nrows Datensätze abgerufen<br>\n";
    var_dump($res);

    // die Ausgabe ist:
    //    2 Datensätze abgerufen
    //    array(2) {
    //      [0]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "00989x"
    //        [1]=>
    //        string(4) "Rom"
    //      }
    //      [1]=>
    //      array(2) {
    //        [0]=>
    //        string(6) "10934x"
    //        [1]=>
    //        string(6) "Venedig"
    //      }
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Anmerkungen

> Hinweis:

> Die Verwendung von `offset` ist sehr ineffizient. All die zu überspringenden Datensätze sind in der Ergebnismenge, die von der Datenbank an PHP zurückgegeben wird. Dann werden sie verworfen. Es ist effizienter SQL zu nutzen, um den Offset und den Bereich der Datensätze in der Abfrage zu beschränken. Ein Beispiel kann der Dokumentation von oci_fetch_array() entnommen werden.

> Hinweis:

> Abfragen, die eine große Anzahl von Datensätze liefern, sind speichereffizienter, wenn eine Funktion wie oci_fetch_array() verwendet wird, die nur einzelne Datensätze abruft.

> Hinweis:

> Bei Queries, die eine große Anzahl an Zeilen zurückgeben, kann die Laufzeit beträchtlich verbessert werden, indem man oci8.default_prefetch erhöht oder oci_set_prefetch() verwendet.

> Hinweis:

> Diese Funktion gibt keine Datensätze aus einer impliziten Ergebnismenge einer Oracle 12c-Datenbank zurück. Verwenden Sie stattdessen die Funktion oci_fetch_array().

### Siehe auch

- oci_fetch() - Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab
- oci_fetch_array() - Liefert die nächste Zeile einer Abfrage als assoziatives oder numerisches Array
- oci_fetch_assoc() - Liefert die nächste Zeile einer Abfrage als assoziatives Array
- oci_fetch_object() - Liefert die nächste Zeile einer Abfrage als Objekt
- oci_fetch_row() - Liefert die nächste Zeile einer Abfrage als numerisches Array
- oci_set_prefetch() - Sets number of rows to be prefetched by queries

# oci_fetch_array

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_array — Liefert die nächste Zeile einer Abfrage als assoziatives oder numerisches Array

### Beschreibung

function oci_fetch_array(resource `$statement`, int `$mode` = OCI_BOTH | OCI_RETURN_NULLS): array|false

Gibt ein Array zurück, das die nächste Zeile der Ergebnismenge einer Abfrage enthält. Jedes Array-Element entspricht einer Spalte der Zeile. Diese Funktion wird üblicherweise in einer Schleife aufgerufen, bis sie `false` zurückgibt, was anzeigt, dass es keine weiteren Zeilen gibt.

Bezieht sich `statement` auf einen PL/SQL-Block, der implizite Ergebnismengen einer Oracle-Datenbank zurückgibt, dann werden die Zeilen aller Mengen nacheinander abgerufen. Wurde `statement` von oci_get_implicit_resultset() zurückgegeben, dann wird nur die Teilmenge der Zeilen für eine Kindabfrage zurückgegeben.

Für Details zur vom OCI8-Treiber durchgeführten Umsetzung von Datentypen siehe die vom Treiber unterstützen Datentypen.

### Parameter-Liste

`statement`

  Der Identifizierer eines gültigen OCI8-Ausdrucks, der von oci_parse() erzeugt und von oci_execute() oder einem `REF CURSOR`-Ausdruck verwendet wird.

  Kann auch eine Anweisungskennung sein, die von oci_get_implicit_resultset() zurückgegeben wurde.

`mode`

  Der optionale zweite Parameter kann eine beliebige Kombination aus den folgenden Konstanten sein:

  oci_fetch_array()-Modi
  Konstante | Beschreibung
  --- | ---
  `OCI_BOTH` | Gibt ein Array mit sowohl assoziativen als auch numerischen Indizes zurück. Das ist dasselbe wie `OCI_ASSOC` + `OCI_NUM` und ist das Standardverhalten.
  `OCI_ASSOC` | Gibt ein assoziatives Array zurück.
  `OCI_NUM` | Gibt ein numerisches Array zurück.
  `OCI_RETURN_NULLS` | Erzeugt Elemente für `null`-Felder. Die Elementwerte sind PHP-`null`-Werte.
  `OCI_RETURN_LOBS` | Gibt den Inhalt von LOBs statt der LOB-Kennungen zurück.

  Der Standard-`mode` ist `OCI_BOTH`.

  Der Additionsoperator "+" ist zu verwenden, um mehr als einen Modus auf einmal anzugeben.

### Rückgabewerte

Gibt ein Array mit assoziativen und/oder numerischen Indizes zurück. Gibt es keine weiteren Zeilen in `statement`, wird `false` zurückgegeben.

Standardmäßig werden `LOB`-Spalten als LOB-Kennungen zurückgegeben.

`DATE`-Spalten werden als gemäß des aktuellen Datumsformats formatierte Zeichenketten zurückgegeben. Das Standardformat kann mit Oracle-Umgebungsvariablen wie `NLS_LANG` geändert werden oder auch durch den zuvor ausgeführten Befehl `ALTER SESSION SET NLS_DATE_FORMAT`.

Die standardmäßigen Oracle-Spaltennamen, die nicht zwischen Groß- und Kleinschreibung unterscheiden, erzeugen Arrayschlüssel in Großbuchstaben. Spaltennamen, die zwischen Groß- und Kleinschreibung unterscheiden, verwenden die genaue Schreibweise. var_dump() kann auf das Ergebnisarray angewendet werden, um die richtige Schreibweise für jede Abfrage zu prüfen.

Der Tabellenname ist nicht im Arrayschlüssel enthalten. Enthält die Abfrage zwei unterschiedliche Spalten mit demselben Namen ist `OCI_NUM` zu verwenden, oder ein Spaltenalias sollte in der Abfrage definiert werden, um die Eindeutigkeit der Namen sicherzustellen; siehe Beispiel #7. Andernfalls wird nur eine der Spalten von PHP zurückgegeben.

### Beispiele

Beispiel #1 oci_fetch_array() mit `OCI_BOTH`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_BOTH)) != false) {
        // verwende Spaltennamen in Großschreibung für die assoziativen Arrayschlüssel
        echo $row[0] . " und " . $row['DEPARTMENT_ID']   . " sind dasselbe<br>\n";
        echo $row[1] . " und " . $row['DEPARTMENT_NAME'] . " sind dasselbe<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #2 oci_fetch_array() mit `OCI_NUM`

    <?php

    /*
      Vor der Ausführung ist die Tabelle zu erstellen:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'Eine sehr lange Zeichenkette');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_NUM)) != false) {
        echo $row[0] . "<br>\n";
        echo $row[1]->read(15) . "<br>\n"; // dies gibt die ersten 15 Bytes von DESCRIPTION aus
    }

    // die Ausgabe ist:
    //    1
    //    Eine sehr lange

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #3 oci_fetch_array() mit `OCI_ASSOC`

    <?php

    /*
      Vor der Ausführung ist die Tabelle zu erstellen:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'Eine sehr lange Zeichenkette');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION']->read(15) . "<br>\n"; // dies gibt die ersten 15 Bytes von DESCRIPTION aus
    }

    // die Ausgabe ist:
    //    1
    //    Eine sehr lange

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #4 oci_fetch_array() mit `OCI_RETURN_NULLS`

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC)) != false) { // ignoriere NULL-Werte
        var_dump($row);
    }

    /*
    Der obige Code gibt aus:
      array(1) {
        [1]=>
        string(1) "1"
      }
    */

    $stid = oci_parse($conn, 'SELECT 1, null FROM dual');
    oci_execute($stid);
    while (($row = oci_fetch_array ($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) { // hole NULL-Werte
        var_dump($row);
    }

    /*
    Der obige Code gibt aus:
      array(2) {
        [1]=>
        string(1) "1"
        ["NULL"]=>
        NULL
      }
    */

    ?>

Beispiel #5 oci_fetch_array() mit `OCI_RETURN_LOBS`

    <?php

    /*
      Vor der Ausführung ist die Tabelle zu erstellen:
          CREATE TABLE mytab (id NUMBER, description CLOB);
          INSERT INTO mytab (id, description) values (1, 'Eine sehr lange Zeichenkette');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) != false) {
        echo $row['ID'] . "<br>\n";
        echo $row['DESCRIPTION'] . "<br>\n"; // dies enthält die gesamte DESCRIPTION
        // das Freigeben der großen Variable in einer Schleife vor dem zweiten Fetch
        // verringert die maximale Speicherbelegung von PHP
        unset($row);
    }

    // die Ausgabe ist:
    //    1
    //    Eine sehr lange Zeichenkette

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #6 oci_fetch_array() mit Spaltennamen, die zwischen Groß- und Kleinschreibung unterscheiden

    <?php

    /*
       Vor der Ausführung ist die Tabelle zu erstellen:
          CREATE TABLE mytab ("Name" VARCHAR2(20), city VARCHAR2(20));
          INSERT INTO mytab ("Name", city) values ('Chris', 'Melbourne');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS);

    // Da 'Name' als Spalte erstellt wurde, die zwischen Groß- und Kleinschreibung
    // unterscheidet, muss genau dieselbe Schreibweise für den Arrayschlüssel
    // verwendet werden. Allerding muss das groß geschriebene 'CITY' für den
    // Spaltenschlüssel verwendet werden, der nicht zwischen Groß- und
    // Kleinschreibung unterscheidet.
    print $row['Name'] . "<br>\n";   //  gibt Chris aus
    print $row['CITY'] . "<br>\n";   //  gibt Melbourne aus

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #7 oci_fetch_array() mit Spalten, die doppelte Namen haben

    <?php

    /*
      Vor der Ausführung ist die Tabelle zu erstellen:
          CREATE TABLE mycity (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycity (id, name) values (1, 'Melbourne');
          CREATE TABLE mycountry (id NUMBER, name VARCHAR2(20));
          INSERT INTO mycountry (id, name) values (1, 'Australien');
          COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT mycity.name, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // die Ausgabe enthält nur ein "NAME"-Element:
    //    array(1) {
    //      ["NAME"]=>
    //      string(9) "Australien"
    //    }

    // um einen sich wiederholenden Spaltennamen abzufragen, ist ein
    // SQL-Spaltenalias wie "AS ctnm" zu verwenden:
    $sql = 'SELECT mycity.name AS ctnm, mycountry.name
            FROM mycity, mycountry
            WHERE mycity.id = mycountry.id';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    var_dump($row);

    // die Ausgabe enthält nun die beiden gewählten Spalten:
    //    array(2) {
    //      ["CTNM"]=>
    //      string(9) "Melbourne"
    //      ["NAME"]=>
    //      string(9) "Australien"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #8 oci_fetch_array() mit `DATE`-Spalten

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Lege das Datumsformat für diese Verbindung fest.
    // Aus Effizienzgründen ist zu erwägen, das Format stattdessen in
    // einem Trigger oder mit Umgebungsvariablen zu ändern.
    $stid = oci_parse($conn, "ALTER SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD'");
    oci_execute($stid);

    $stid = oci_parse($conn, 'SELECT hire_date FROM employees WHERE employee_id = 188');
    oci_execute($stid);
    $row = oci_fetch_array($stid, OCI_ASSOC);
    echo $row['HIRE_DATE'] . "<br>\n";  // gibt 1997-06-14 aus

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #9 oci_fetch_array() mit `REF CURSOR`

    <?php
    /*
      Erzeuge die PL/SQL gespeicherte Prozedur mit:

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // führe den zurückgegebenen REF CURSOR aus und lies
    // von ihm wie mit einer Anweisungskennung
    oci_execute($refcur);
    echo "<table border='1'>\n";
    while (($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #10 Seitenweise Darstellung mit oci_fetch_array() unter Verwendung einer `LIMIT`-Klausel

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // ermittle die Datenbankversion
    preg_match('/Release ([0-9]+)\./', oci_server_version($conn), $matches);
    $oracleversion = $matches[1];

    // dies ist die Abfrage, durch die seitenweise geblättert werden soll
    $sql = 'SELECT city, postal_code FROM locations ORDER BY city';

    if ($oracleversion >= 12) {
        // verwende die OFFSET / FETCH NEXT-Syntax von Oracle 12c
        $sql = $sql . ' OFFSET :offset ROWS FETCH NEXT :numrows ROWS ONLY';
    } else {
        // Ältere Oracle-Versionen benötigten eine verschachtelte Abfrage, die
        // eine Teilmenge von $sql auswählt. Wenn die SQL-Anweisung zum Zeitpunkt
        // der Programmentwicklung bekannt ist, sollte statt dieser Methode eine
        // row_number()-Funktion verwendet werden. In Produktionsumgebungen ist
        // darauf zu achten, dass SQL-Injection-Probleme durch
        // Zeichenkettenverknüpfung vermieden werden.
        $sql = "SELECT * FROM (SELECT a.*, ROWNUM AS my_rnum
                               FROM ($sql) a
                               WHERE ROWNUM <= :offset + :numrows)
                WHERE my_rnum > :offset";
    }

    $offset  = 0;  // lasse so viele Zeilen aus
    $numrows = 5;  // gib 5 Zeilen zurück
    $stid = oci_parse($conn, $sql);
    oci_bind_by_name($stid, ':numrows', $numrows);
    oci_bind_by_name($stid, ':offset', $offset);
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_NULLS)) != false) {
        echo $row['CITY'] . " " . $row['POSTAL_CODE'] . "<br>\n";
    }

    // die Ausgabe ist:
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    Geneva 1730
    //    Hiroshima 6823

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #11 oci_fetch_array() mit impliziten Ergebnismengen einer Oracle-Datenbank

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    // Benötigt OCI8 2.0 (oder höher) und Oracle Database 12c (oder höher)
    // siehe auch oci_get_implicit_resultset()
    $sql = 'DECLARE
               c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Beachte: oci_fetch_all und oci_fetch() können nicht auf diese Weise
    // verwendet werden
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // die Ausgabe ist:
    //    Beijing 190518
    //    Bern    3095
    //    Bombay  490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Anmerkungen

> Hinweis:

> Assoziative Arrayschlüssel müssen für Standard-Oracle-Spalten, die mit Namen ohne Berücksichtigung der Groß- und Kleinschreibung erstellt wurden, in Großbuchstaben sein.

> Hinweis:

> Bei Queries, die eine große Anzahl an Zeilen zurückgeben, kann die Laufzeit beträchtlich verbessert werden, indem man oci8.default_prefetch erhöht oder oci_set_prefetch() verwendet.

> Hinweis:

> Die Funktion oci_fetch_array() ist unwesentlich langsamer als oci_fetch_assoc() oder oci_fetch_row(), ist aber flexibler.

### Siehe auch

- oci_fetch() - Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab
- oci_fetch_all() - Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab
- oci_fetch_assoc() - Liefert die nächste Zeile einer Abfrage als assoziatives Array
- oci_fetch_object() - Liefert die nächste Zeile einer Abfrage als Objekt
- oci_fetch_row() - Liefert die nächste Zeile einer Abfrage als numerisches Array
- oci_set_prefetch() - Sets number of rows to be prefetched by queries

# oci_fetch_assoc

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_assoc — Liefert die nächste Zeile einer Abfrage als assoziatives Array

### Beschreibung

function oci_fetch_assoc(resource `$statement`): array|false

Gibt ein assoziatives Array zurück, das die nächste Zeile der Ergebnismenge einer Abfrage enthält. Jedes Array-Element entspricht einer Spalte der Zeile. Diese Funktion wird üblicherweise in einer Schleife aufgerufen bis sie `false` zurückgibt, was anzeigt, dass es keine weitere Zeilen gibt.

Ein oci_fetch_assoc()-Aufruf ist identisch mit einem oci_fetch_array()-Aufruf und `OCI_ASSOC` + `OCI_RETURN_NULLS`.

### Parameter-Liste

`statement`

  Der Identifizierer eines gültigen OCI8-Ausdrucks, der von oci_parse() erzeugt und von oci_execute() oder einem `REF CURSOR`-Ausdruck verwendet wird.

### Rückgabewerte

Gibt ein assoziatives Array zurück. Gibt es keine weiteren Zeilen für die Anweisung `statement`, dann wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_fetch_assoc()-Beispiel

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_assoc($stid)) != false) {
        echo $row['DEPARTMENT_ID'] . " " . $row['DEPARTMENT_NAME'] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Anmerkungen

> Hinweis:

> Weitere Beispiele für das Abrufen von Zeilen sind der Dokumentation von oci_fetch_array() zu entnehmen.

### Siehe auch

- oci_fetch() - Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab
- oci_fetch_all() - Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab
- oci_fetch_array() - Liefert die nächste Zeile einer Abfrage als assoziatives oder numerisches Array
- oci_fetch_object() - Liefert die nächste Zeile einer Abfrage als Objekt
- oci_fetch_row() - Liefert die nächste Zeile einer Abfrage als numerisches Array

# oci_fetch_object

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_object — Liefert die nächste Zeile einer Abfrage als Objekt

### Beschreibung

function oci_fetch_object(resource `$statement`, int `$mode` = OCI_ASSOC | OCI_RETURN_NULLS): stdClass|false

Gibt ein Objekt zurück, das die nächste Zeile der Ergebnismenge einer Abfrage enthält. Jede Eigenschaft des Objekts entspricht einer Spalte der Zeile. Diese Funktion wird üblicherweise in einer Schleife aufgerufen bis sie `false` zurückgibt, was anzeigt, dass es keine weitere Zeilen gibt.

Für Details zur vom OCI8-Treiber durchgeführten Umsetzung von Datentypen siehe die vom Treiber unterstützen Datentypen.

### Parameter-Liste

`statement`

  Der Identifizierer eines gültigen OCI8-Ausdrucks, der von oci_parse() erzeugt und von oci_execute() oder einem `REF CURSOR`-Ausdruck verwendet wird.

### Rückgabewerte

Gibt ein Objekt zurück. Jede Eigenschaft des Objekts entspricht einer Spalte der Zeile. Gibt es keine weiteren Zeilen in `statement`, dann wird `false` zurückgegeben.

Jegliche `LOB`-Spalten werden als LOB-Kennungen zurückgegeben.

`DATE`-Spalten werden als gemäß des aktuellen Datumsformats formatierte Zeichenketten zurückgegeben. Das Standardformat kann mit Oracle-Umgebungsvariablen wie `NLS_LANG` geändert werden oder auch durch den zuvor ausgeführten Befehl `ALTER SESSION SET NLS_DATE_FORMAT`.

Die standardmäßigen Oracle-Spaltennamen, die nicht zwischen Groß- und Kleinschreibung unterscheiden, erzeugen Eigenschaftsnamen in Großbuchstaben. Spaltennamen, die zwischen Groß- und Kleinschreibung unterscheiden, verwenden die genaue Schreibweise. var_dump() kann auf das Ergebnisobjekt angewendet werden, um die richtige Schreibweise für den Eigenschaftszugriff zu prüfen.

Die Eigenschaftswerte sind `null` für jegliche `NULL`-Datenfelder.

### Beispiele

Beispiel #1 oci_fetch_object()-Beispiel

    <?php

    /*
      Vor der Ausführung ist die Tabelle zu erstellen:
        CREATE TABLE mytab (id NUMBER, description VARCHAR2(30));
        INSERT INTO mytab (id, description) values (1, 'Currywurst mit Pommes');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // verwende Eigenschaftsnamen in Großschrift für jede Standard-Oracle-Spalte
        echo $row->ID . "<br>\n";
        echo $row->DESCRIPTION . "<br>\n";
    }

    // Ausgabe:
    //    1
    //    Currywurst mit Pommes

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #2 oci_fetch_object() mit Spaltennamen, die zwischen Groß- und Kleinschreibung unterscheiden.

    <?php

    /*
      Vor der Ausführung ist die Tabelle mit Spaltennamen, die zwischen Groß- und
      Kleinschreibung unterscheiden, zu erstellen:
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Eiskaffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, "MyDescription" FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        // verwende Eigenschaftsnamen in Großschrift für jede Standard-Oracle-Spalte
        echo $row->ID . "<br>\n";
        // verwende die genaue Schreibweise für Spaltennamen, die zwischen Groß-
        // und Kleinschreibung unterscheiden
        echo $row->MyDescription . "<br>\n";
    }

    // Ausgabe:
    //    1
    //    Eiskaffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #3 oci_fetch_object() mit LOBs

    <?php

    /*
      Vor der Ausführung ist die Tabelle zu erstellen:
        CREATE TABLE mytab (id NUMBER, description CLOB);
        INSERT INTO mytab (id, description) values (1, 'Eine sehr lange Zeichenkette');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT id, description FROM mytab');
    oci_execute($stid);

    while (($row = oci_fetch_object($stid)) != false) {
        echo $row->ID . "<br>\n";
        // das folgende gibt die ersten 15 Bytes von DESCRIPTION aus
        echo $row->DESCRIPTION->read(15) . "<br>\n";
    }

    // Ausgabe:
    //    1
    //    Eine sehr lange

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Siehe auch

- oci_fetch() - Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab
- oci_fetch_all() - Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab
- oci_fetch_assoc() - Liefert die nächste Zeile einer Abfrage als assoziatives Array
- oci_fetch_array() - Liefert die nächste Zeile einer Abfrage als assoziatives oder numerisches Array
- oci_fetch_row() - Liefert die nächste Zeile einer Abfrage als numerisches Array

# oci_fetch_row

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_row — Liefert die nächste Zeile einer Abfrage als numerisches Array

### Beschreibung

function oci_fetch_row(resource `$statement`): array|false

Gibt ein numerisch indexiertes Array zurück, das die nächste Zeile der Ergebnismenge einer Abfrage enthält. Jedes Array-Element entspricht einer Spalte der Zeile. Diese Funktion wird üblicherweise in einer Schleife aufgerufen bis sie `false` zurückgibt, was anzeigt, dass es keine weitere Zeilen gibt.

Ein oci_fetch_row()-Aufruf ist identisch mit einem oci_fetch_array()-Aufruf und `OCI_NUM` + `OCI_RETURN_NULLS`.

### Parameter-Liste

`statement`

  Der Identifizierer eines gültigen OCI8-Ausdrucks, der von oci_parse() erzeugt und von oci_execute() oder einem `REF CURSOR`-Ausdruck verwendet wird.

### Rückgabewerte

Gibt ein numerisch indexiertes Array zurück. Gibt es keine weiteren Zeilen für die Anweisung `statement`, dann wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_fetch_row()-Beispiel

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT department_id, department_name FROM departments');
    oci_execute($stid);

    while (($row = oci_fetch_row($stid)) != false) {
        echo $row[0] . " " . $row[1] . "<br>\n";
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Anmerkungen

> Hinweis:

> Weitere Beispiele für das Abrufen von Zeilen sind der Dokumentation von oci_fetch_array() zu entnehmen.

### Siehe auch

- oci_fetch() - Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab
- oci_fetch_all() - Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab
- oci_fetch_array() - Liefert die nächste Zeile einer Abfrage als assoziatives oder numerisches Array
- oci_fetch_assoc() - Liefert die nächste Zeile einer Abfrage als assoziatives Array
- oci_fetch_object() - Liefert die nächste Zeile einer Abfrage als Objekt

# oci_field_is_null

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_is_null — Checks if a field in the currently fetched row is `null`

### Beschreibung

function oci_field_is_null(resource `$statement`, string|int `$column`): bool

Checks if the given `column` from the current row of `statement` is `null`.

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

`column`

  Can be the field's index (1-based) or name.

### Rückgabewerte

Returns `true` if `column` is `null`, `false` otherwise.

### Beispiele

Beispiel #1 oci_field_name() example

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (c1 NUMBER);
    //   INSERT INTO mytab VALUES (1);
    //   INSERT INTO mytab VALUES (NULL);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid);

    while (($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) != false) {
        $ncols = oci_num_fields($stid);
        for ($col = 1; $col <= $ncols; $col++) {
            var_dump(oci_field_is_null($stid, $col));
        }
    }

    // Outputs:
    //    bool(false)
    //    bool(true)

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_field_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_name — Returns the name of a field from the statement

### Beschreibung

function oci_field_name(resource `$statement`, string|int `$column`): string|false

Returns the name of the `column`.

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

`column`

  Can be the field's index (1-based) or name.

### Rückgabewerte

Returns the name as a string,Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_field_name() example

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY if not fetching rows

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Outputs:
    //    Name           Type
    //    NUMBER_COL    NUMBER
    //    VARCHAR2_COL  VARCHAR2
    //    CLOB_COL      CLOB
    //    DATE_COL      DATE

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Siehe auch

- oci_num_fields() - Returns the number of result columns in a statement
- oci_field_type() - Returns a field's data type name
- oci_field_size() - Returns field's size

# oci_field_precision

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_precision — Tell the precision of a field

### Beschreibung

function oci_field_precision(resource `$statement`, string|int `$column`): int|false

Returns precision of the `column`.

For FLOAT columns, precision is nonzero and scale is -127. If precision is 0, then column is NUMBER. Else it's NUMBER(precision, scale).

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

`column`

  Can be the field's index (1-based) or name.

### Rückgabewerte

Returns the precision as an integer,Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_field_precision() Example

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY if not fetching rows

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Outputs:
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Siehe auch

- oci_field_scale() - Tell the scale of the field
- oci_field_type() - Returns a field's data type name

# oci_field_scale

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_scale — Tell the scale of the field

### Beschreibung

function oci_field_scale(resource `$statement`, string|int `$column`): int|false

Returns the scale of the column with `column` index.

For FLOAT columns, precision is nonzero and scale is -127. If precision is 0, then column is NUMBER. Else it's NUMBER(precision, scale).

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

`column`

  Can be the field's index (1-based) or name.

### Rückgabewerte

Returns the scale as an integer,Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_field_scale() Example

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (c1 NUMBER, c2 FLOAT, c3 NUMBER(4), c4 NUMBER(5,3));

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY if not fetching rows

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " "
            . oci_field_precision($stid, $i) . " "
            . oci_field_scale($stid, $i) . "<br>\n";
    }

    // Outputs:
    //   C1    0 -127
    //   C2  126 -127
    //   C3    4    0
    //   C4    5    3

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Siehe auch

- oci_field_precision() - Tell the precision of a field
- oci_field_type() - Returns a field's data type name

# oci_field_size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_size — Returns field's size

### Beschreibung

function oci_field_size(resource `$statement`, string|int `$column`): int|false

Returns the size of a `column`.

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

`column`

  Can be the field's index (1-based) or name.

### Rückgabewerte

Returns the size of a `column` in bytes,Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_field_size() example

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY if not fetching rows

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Outputs:
    //    Name           Type       Length
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Siehe auch

- oci_num_fields() - Returns the number of result columns in a statement
- oci_field_name() - Returns the name of a field from the statement

# oci_field_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type — Returns a field's data type name

### Beschreibung

function oci_field_type(resource `$statement`, string|int `$column`): string|int|false

Returns a field's data type name.

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

`column`

  Can be the field's index (1-based) or name.

### Rückgabewerte

Returns the field data type as a String or an Integer,Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_field_type() example

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1),
    //                       clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY if not fetching rows

    echo "<table border=\"1\">\n";
    echo "<tr>";
    echo "<th>Name</th>";
    echo "<th>Type</th>";
    echo "<th>Length</th>";
    echo "</tr>\n";

    $ncols = oci_num_fields($stid);

    for ($i = 1; $i <= $ncols; $i++) {
        $column_name  = oci_field_name($stid, $i);
        $column_type  = oci_field_type($stid, $i);
        $column_size  = oci_field_size($stid, $i);

        echo "<tr>";
        echo "<td>$column_name</td>";
        echo "<td>$column_type</td>";
        echo "<td>$column_size</td>";
        echo "</tr>\n";
    }

    echo "</table>\n";

    // Outputs:
    //    Name           Type       Length
    //    NUMBER_COL    NUMBER        22
    //    VARCHAR2_COL  VARCHAR2       1
    //    CLOB_COL      CLOB        4000
    //    DATE_COL      DATE           7

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Siehe auch

- oci_num_fields() - Returns the number of result columns in a statement
- oci_field_name() - Returns the name of a field from the statement
- oci_field_size() - Returns field's size

# oci_field_type_raw

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type_raw — Tell the raw Oracle data type of the field

### Beschreibung

function oci_field_type_raw(resource `$statement`, string|int `$column`): int|false

Returns Oracle's raw "SQLT" data type of the `column`.

If you want a field's type name, then use oci_field_type() instead.

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

`column`

  Can be the field's index (1-based) or name.

### Rückgabewerte

Returns Oracle's raw data type as a number,Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_field_type_raw() Example

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (number_col NUMBER, varchar2_col varchar2(1), clob_col CLOB, date_col DATE);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'select * from mytab');
    oci_execute($stid, OCI_DESCRIBE_ONLY);  // Use OCI_DESCRIBE_ONLY if not fetching rows
    $n = oci_num_fields($stid);
    for ($i = 1; $i <= $n; ++$i) {
        echo oci_field_name($stid, $i) . " is raw type: " . oci_field_type_raw($stid, $i) . "<br>\n";
    }

    // Output is:
    //    NUMBER_COL is raw type: 2
    //    VARCHAR2_COL is raw type: 1
    //    CLOB_COL is raw type: 112
    //    DATE_COL is raw type: 12

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_free_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_descriptor — Frees a descriptor

### Beschreibung

function oci_free_descriptor(OCILob `$lob`): bool

Frees a descriptor allocated by oci_new_descriptor().

### Parameter-Liste

`lob`

  Descriptor allocated by oci_new_descriptor().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Anmerkungen

> Hinweis:

> This function is commonly used as a method OCILOB::free.

### Siehe auch

- OCILOB::free

# oci_free_statement

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_statement — Gibt alle verknüpften Ressourcen eines Statements oder Zeigers frei.

### Beschreibung

function oci_free_statement(resource `$statement`): bool

Gibt alle verknüpften Ressourcen eines Oracle-Statements oder -Zeigers frei, die durch das Ergebnis von oci_parse() zugewiesen oder von Oracle eingeholt wurden.

### Parameter-Liste

`statement`

  Ein gültiger Zeiger auf ein OCI-Statement.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# oci_get_implicit_resultset

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL OCI8 >= 2.0.0)

oci_get_implicit_resultset — Returns the next child statement resource from a parent statement resource that has Oracle Database Implicit Result Sets

### Beschreibung

function oci_get_implicit_resultset(resource `$statement`): resource|false

Used to fetch consecutive sets of query results after the execution of a stored or anonymous Oracle PL/SQL block where that block returns query results with the Oracle Database 12 (or later) DBMS_SQL.RETURN_RESULT PL/SQL function. This allows PL/SQL blocks to easily return query results.

The child statement can be used with any of the OCI8 fetching functions: oci_fetch(), oci_fetch_all(), oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() or oci_fetch_row()

Child statements inherit their parent statement's prefetch value, or it can be explicitly set with oci_set_prefetch().

### Parameter-Liste

`statement`

  A valid OCI8 statement identifier created by oci_parse() and executed by oci_execute(). The statement identifier may or may not be associated with a SQL statement that returns Implicit Result Sets.

### Rückgabewerte

Returns a statement handle for the next child statement available on `statement`. Returns `false` when child statements do not exist, or all child statements have been returned by previous calls to oci_get_implicit_resultset().

### Beispiele

Beispiel #1 Fetching Implicit Result Sets in a loop

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (($stid_c = oci_get_implicit_resultset($stid))) {
        echo "<h2>New Implicit Result Set:</h2>\n";
        echo "<table>\n";
        while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
            echo "<tr>\n";
            foreach ($row as $item) {
                echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
            }
            echo "</tr>\n";
        }
        echo "</table>\n";
    }

    // Output is:
    //    New Implicit Result Set:
    //     Beijing 190518
    //     Bern    3095
    //     Bombay  490231
    //    New Implicit Result Set:
    //     CN
    //     CH
    //     IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #2 Getting child statement handles individually

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_1 = oci_get_implicit_resultset($stid);
    $stid_2 = oci_get_implicit_resultset($stid);

    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_1, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);
    $row = oci_fetch_array($stid_2, OCI_ASSOC+OCI_RETURN_NULLS);
    var_dump($row);

    // Output is:
    //    array(2) {
    //      ["CITY"]=>
    //      string(7) "Beijing"
    //      ["POSTAL_CODE"]=>
    //      string(6) "190518"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CN"
    //    }
    //    array(2) {
    //      ["CITY"]=>
    //      string(4) "Bern"
    //      ["POSTAL_CODE"]=>
    //      string(4) "3095"
    //    }
    //    array(1) {
    //      ["COUNTRY_ID"]=>
    //      string(2) "CH"
    //    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #3 Explicitly setting the Prefetch Count

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    $stid_c = oci_get_implicit_resultset($stid);
    oci_set_prefetch($stid_c, 200);   // Set the prefetch before fetching from the child statement
    echo "<table>\n";
    while (($row = oci_fetch_array($stid_c, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #4 Implicit Result Set example without using oci_get_implicit_resultset()

All results from all queries are returned consecutively.

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/pdborcl');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'DECLARE
                c1 SYS_REFCURSOR;
            BEGIN
               OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
               OPEN c1 FOR SELECT country_id FROM locations WHERE ROWNUM < 4 ORDER BY city;
               DBMS_SQL.RETURN_RESULT(c1);
            END;';

    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    // Note: oci_fetch_all and oci_fetch() cannot be used in this manner
    echo "<table>\n";
    while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "  <td>".($item!==null?htmlentities($item, ENT_QUOTES|ENT_SUBSTITUTE):"&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    // Output is:
    //    Beijing 190518
    //    Bern 3095
    //    Bombay 490231
    //    CN
    //    CH
    //    IN

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Anmerkungen

> Hinweis:

> Bei Queries, die eine große Anzahl an Zeilen zurückgeben, kann die Laufzeit beträchtlich verbessert werden, indem man oci8.default_prefetch erhöht oder oci_set_prefetch() verwendet.

# oci_lob_copy

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_copy — Copies large object

### Beschreibung

function oci_lob_copy(OCILob `$to`, OCILob `$from`, ?int `$length` = `null`): bool

Copies a large object or a part of a large object to another large object. Old LOB-recipient data will be overwritten.

If you need to copy a particular part of a LOB to a particular position of a LOB, use OCILob::seek() to move LOB internal pointers.

### Parameter-Liste

`to`

  The destination LOB.

`from`

  The copied LOB.

`length`

  Indicates the length of data to be copied.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` is now nullable.

### Anmerkungen

> Hinweis:

> The OCILob class was called OCI-Lob prior to PHP 8 and PECL OCI8 3.0.0.

# oci_lob_is_equal

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_is_equal — Compares two LOB/FILE locators for equality

### Beschreibung

function oci_lob_is_equal(OCILob `$lob1`, OCILob `$lob2`): bool

Compares two LOB/FILE locators.

### Parameter-Liste

`lob1`

  A LOB identifier.

`lob2`

  A LOB identifier.

### Rückgabewerte

Returns `true` if these objects are equal, `false` otherwise.

### Anmerkungen

> Hinweis:

> The OCILob class was called OCI-Lob prior to PHP 8 and PECL OCI8 3.0.0.

# oci_new_collection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_collection — Allocates new collection object

### Beschreibung

function oci_new_collection(resource `$connection`, string `$type_name`, ?string `$schema` = `null`): OCICollection|false

Allocates a new collection object.

### Parameter-Liste

`connection`

  An Oracle connection identifier, returned by oci_connect() or oci_pconnect().

`type_name`

  Should be a valid named type (uppercase).

`schema`

  Should point to the scheme, where the named type was created. The name of the current user is used when `null` is passed.

### Rückgabewerte

Returns a new OCICollection object or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | `schema` is now nullable.

### Anmerkungen

> Hinweis:

> The OCICollection class was called OCI-Collection prior to PHP 8 and OCI8 3.0.0.

# oci_new_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_connect — Connect to the Oracle server using a unique connection

### Beschreibung

function oci_new_connect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Establishes a new connection to an Oracle server and logs on.

Unlike oci_connect() and oci_pconnect(), oci_new_connect() does not cache connections and will always return a brand-new freshly opened connection handle. This is useful if your application needs transactional isolation between two sets of queries.

### Parameter-Liste

`username`

  The Oracle user name.

`password`

  The password for `username`.

`connection_string`

  Beinhaltet die `Oracle-Instanz`, mit der verbunden werden soll. Dies kann eine » Easy-Connect-Zeichenkette, ein Connect-Name aus der Datei tnsnames.ora oder der Name einer lokalen Oracle-Instanz sein.

  Wenn dies nicht angegebe wird oder `null` ist, verwendet PHP Umgebungsvariablen wie `TWO_TASK` (unter Linux), `LOCAL` (unter Windows) oder `ORACLE_SID` um die `Oracle-Instanz` zu ermitteln, mit der verbunden werden soll.

  Um die benannte Easy Connect Methode zu verwenden, muss PHP gegen die Clientbibliotheken von Oracle 10g oder höher gelinkt sein. Die Easy-Connect-Zeichenkette für Oracle 10g hat den Aufbau: [//]host_name[:port][/service_name]. Für Oracle 11g ist die Syntax: [//]host_name[:port][/service_name][:server_type][/instance_name]. Weitere Optionen wurden mit Oracle 19c eingeführt, darunter die timeout- und die keep-alive-Einstellungen. Siehe dazu die Oracle-Dokumentation. Die Servicenamen können ermittelt werden, indem man das Oracle-Hilfswerkzeug `lsnrctl status` auf dem Datenbankserver ausführt.

  Die Datei tnsnames.ora kann sich im Oracle Net Suchpfad befinden, welcher /der/pfad/zu/instantclient/network/admin, $ORACLE_HOME/network/admin sowie /etc beinhaltet. Alternativ kann `TNS_ADMIN` so gesetzt werden, dass $TNS_ADMIN/tnsnames.ora gelesen wird. Es muss sichergestellt sein, dass der Webserver eine Leseberechtigung für die Datei besitzt.

`encoding`

  Bestimmt den Zeichensatz, der von den Oracle Client Bibliotheken verwendet wird. Dieser Zeichensatz muss nicht dem von der Datenbank verwendeten Zeichensatz entsprechen. Wenn diese nicht übereinstimmen, wird Oracle bestmöglich versuchen, die Daten in den Datenbankzeichensatz zu übersetzen. Abhängig von den Zeichensätzen kann dies zu unbrauchbaren Ergebnissen führen. Diese Konvertierung führt auch zu einem erhöhten Zeitbedarf.

  Falls nicht angegeben, werden die Oracle Client Bibliotheken versuchen, den Zeichensatz aus der Umgebungsvariablen `NLS_LANG` auszulesen.

  Die Übergabe dieses Parameters verringert die Zeit für den Verbindungsaufbau.

`session_mode`

  Dieser Parameter ist seit PHP 5 (PECL OCI8 1.1) verfügbar und akzeptiert die folgenden Werte: `OCI_DEFAULT`, `OCI_SYSOPER` und `OCI_SYSDBA`. Falls entweder `OCI_SYSOPER` oder `OCI_SYSDBA` angegeben wurden wird diese Funktion versuchen die priviligierte Verbindung mit externen Credentials aufzubauen. Um diese einzuschalten muss man oci8.privileged_connect auf `On` setzen.

  PHP 5.3 (PECL OCI8 1.3.4) hat den Wert `OCI_CRED_EXT` eingeführt. Dies konfiguriert Oracle dazu eine externe oder Os-Authentifizierung vorzunehmen, welche in der Datenbank konfiguriert werden muss. Der Schalter `OCI_CRED_EXT` kann nur mit dem Benutzernamen "/" und einem leeren Passwort verwendet werden. oci8.privileged_connect kann entweder `On` oder `Off` sein.

  `OCI_CRED_EXT` kann mit `OCI_SYSOPER` oder `OCI_SYSDBA` kombiniert werden.

  `OCI_CRED_EXT` ist auf Windows-Systemen aus sicherheitsgründen nicht unterstützt.

### Rückgabewerte

Returns a connection identifier or `false` on error.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | `connection_string` is now nullable.

### Beispiele

The following demonstrates how you can separate connections.

Beispiel #1 oci_new_connect() example

    <?php

    // create table mytab (mycol number);

    function query($name, $c)
    {
        echo "Querying $name\n";
        $s = oci_parse($c, "select * from mytab");
        oci_execute($s, OCI_NO_AUTO_COMMIT);
        $row = oci_fetch_array($s, OCI_ASSOC);
        if (!$row) {
            echo "No rows\n";
        } else {
            do {
                foreach ($row as $item)
                    echo $item . " ";
                echo "\n";
            } while (($row = oci_fetch_array($s, OCI_ASSOC)) != false);
        }
    }

    $c1 = oci_connect("hr", "welcome", "localhost/orcl");
    $c2 = oci_new_connect("hr", "welcome", "localhost/orcl");

    $s = oci_parse($c1, "insert into mytab values(1234)");
    oci_execute($s, OCI_NO_AUTO_COMMIT);

    query("basic connection", $c1);
    query("new connection", $c2);
    oci_commit($c1);
    query("new connection after commit", $c2);

    // Output is:
    //   Querying basic connection
    //   1234
    //   Querying new connection
    //   No rows
    //   Querying new connection after commit
    //   1234

    ?>

See oci_connect() for further examples of parameter usage.

### Siehe auch

- oci_connect() - Connect to an Oracle database
- oci_pconnect() - Connect to an Oracle database using a persistent connection

# oci_new_cursor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_cursor — Allocates and returns a new cursor (statement handle)

### Beschreibung

function oci_new_cursor(resource `$connection`): resource|false

Allocates a new statement handle on the specified connection.

### Parameter-Liste

`connection`

  An Oracle connection identifier, returned by oci_connect() or oci_pconnect().

### Rückgabewerte

Returns a new statement handle, or `false` on error.

### Beispiele

Beispiel #1 Binding a REF CURSOR in an Oracle stored procedure call

    <?php

    // Precreate:
    //   create or replace procedure myproc(myrc out sys_refcursor) as
    //   begin
    //     open myrc for select first_name from employees;
    //   end;

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $curs = oci_new_cursor($conn);
    $stid = oci_parse($conn, "begin myproc(:cursbv); end;");
    oci_bind_by_name($stid, ":cursbv", $curs, -1, OCI_B_CURSOR);
    oci_execute($stid);

    oci_execute($curs);  // Execute the REF CURSOR like a normal statement id
    while (($row = oci_fetch_array($curs, OCI_ASSOC+OCI_RETURN_NULLS)) != false) {
        echo $row['FIRST_NAME'] . "<br />\n";
    }

    oci_free_statement($stid);
    oci_free_statement($curs);
    oci_close($conn);

    ?>

# oci_new_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_descriptor — Initializes a new empty LOB or FILE descriptor

### Beschreibung

function oci_new_descriptor(resource `$connection`, int `$type` = `OCI_DTYPE_LOB`): ?OCILob

Allocates resources to hold descriptor or LOB locator.

### Parameter-Liste

`connection`

  An Oracle connection identifier, returned by oci_connect() or oci_pconnect().

`type`

  Valid values for `type` are: `OCI_DTYPE_FILE`, `OCI_DTYPE_LOB` and `OCI_DTYPE_ROWID`.

### Rückgabewerte

Returns a new LOB or FILE descriptor on success, or `null` on failure.

### Beispiele

Beispiel #1 oci_new_descriptor() example

    <?php
    /* This script is designed to be called from a HTML form.
     * It expects $user, $password, $table, $where, and $commitsize
     * to be passed in from the form.  The script then deletes
     * the selected rows using the ROWID and commits after each
     * set of $commitsize rows. (Use with care, there is no rollback)
     */
    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "select rowid from $table $where");
    $rowid = oci_new_descriptor($conn, OCI_D_ROWID);
    oci_define_by_name($stmt, "ROWID", $rowid);
    oci_execute($stmt);
    while (oci_fetch($stmt)) {
        $nrows = oci_num_rows($stmt);
        $delete = oci_parse($conn, "delete from $table where ROWID = :rid");
        oci_bind_by_name($delete, ":rid", $rowid, -1, OCI_B_ROWID);
        oci_execute($delete);
        echo "$nrows\n";
        if (($nrows % $commitsize) == 0) {
            oci_commit($conn);
        }
    }
    $nrows = oci_num_rows($stmt);
    echo "$nrows deleted...\n";
    oci_free_statement($stmt);
    oci_close($conn);
    ?>

    <?php
        /* This script demonstrates file upload to LOB columns
         * The formfield used for this example looks like this
         * <form action="upload.php" method="post" enctype="multipart/form-data">
         * <input type="file" name="lob_upload" />
         * ...
         */
      if (!isset($lob_upload) || $lob_upload == 'none'){
    ?>
    <form action="upload.php" method="post" enctype="multipart/form-data">
    Upload file: <input type="file" name="lob_upload" /><br />
    <input type="submit" value="Upload" /> - <input type="reset" value="Reset" />
    </form>
    <?php
      } else {

         // $lob_upload contains the temporary filename of the uploaded file

         // see also the features section on file upload,
         // if you would like to use secure uploads

         $conn = oci_connect($user, $password);
         $lob = oci_new_descriptor($conn, OCI_D_LOB);
         $stmt = oci_parse($conn, "insert into $table (id, the_blob)
                   values(my_seq.NEXTVAL, EMPTY_BLOB()) returning the_blob into :the_blob");
         oci_bind_by_name($stmt, ':the_blob', $lob, -1, OCI_B_BLOB);
         oci_execute($stmt, OCI_DEFAULT);
         if ($lob->savefile($lob_upload)){
            oci_commit($conn);
            echo "Blob successfully uploaded\n";
         }else{
            echo "Couldn't upload Blob\n";
         }
         $lob->free();
         oci_free_statement($stmt);
         oci_close($conn);
      }
    ?>

Beispiel #2 oci_new_descriptor() example

    <?php
    /* Calling PL/SQL stored procedures which contain clobs as input
     * parameters.
     * Example PL/SQL stored procedure signature is:
     *
     * PROCEDURE save_data
     *   Argument Name                  Type                    In/Out Default?
     *   ------------------------------ ----------------------- ------ --------
     *   KEY                            NUMBER(38)              IN
     *   DATA                           CLOB                    IN
     *
     */

    $conn = oci_connect($user, $password);
    $stmt = oci_parse($conn, "begin save_data(:key, :data); end;");
    $clob = oci_new_descriptor($conn, OCI_D_LOB);
    oci_bind_by_name($stmt, ':key', $key);
    oci_bind_by_name($stmt, ':data', $clob, -1, OCI_B_CLOB);
    $clob->write($data);
    oci_execute($stmt, OCI_DEFAULT);
    oci_commit($conn);
    $clob->free();
    oci_free_statement($stmt);
    ?>

### Siehe auch

- oci_bind_by_name() - Binds a PHP variable to an Oracle placeholder

# oci_num_fields

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_fields — Returns the number of result columns in a statement

### Beschreibung

function oci_num_fields(resource `$statement`): int

Gets the number of columns in the given `statement`.

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

### Rückgabewerte

Returns the number of columns as an int.

### Beispiele

Beispiel #1 oci_num_fields() example

    <?php

    // Create the table with:
    //   CREATE TABLE mytab (id NUMBER, quantity NUMBER);

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "SELECT * FROM mytab");
    oci_execute($stid, OCI_DESCRIBE_ONLY); // Use OCI_DESCRIBE_ONLY if not fetching rows

    $ncols = oci_num_fields($stid);
    for ($i = 1; $i <= $ncols; $i++) {
        echo oci_field_name($stid, $i) . " " . oci_field_type($stid, $i) . "<br>\n";
    }

    // Outputs:
    //    ID NUMBER
    //    QUANTITY NUMBER

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_num_rows

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_rows — Returns number of rows affected during statement execution

### Beschreibung

function oci_num_rows(resource `$statement`): int|false

Gets the number of rows affected during statement execution.

### Parameter-Liste

`statement`

  A valid OCI statement identifier.

### Rückgabewerte

Returns the number of rows affected as an integer,Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_num_rows() example

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    if (!$conn) {
        $m = oci_error();
        trigger_error(htmlentities($m['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, "create table emp2 as select * from employees");
    oci_execute($stid);
    echo oci_num_rows($stid) . " rows inserted.<br />\n";
    oci_free_statement($stid);

    $stid = oci_parse($conn, "delete from emp2");
    oci_execute($stid, OCI_DEFAULT);
    echo oci_num_rows($stid) . " rows deleted.<br />\n";
    oci_commit($conn);
    oci_free_statement($stid);

    $stid = oci_parse($conn, "drop table emp2");
    oci_execute($stid);
    oci_free_statement($stid);

    oci_close($conn);

    ?>

### Anmerkungen

> Hinweis:

> This function does not return number of rows selected! For SELECT statements this function will return the number of rows, that were fetched to the buffer with oci_fetch*() functions.

# oci_parse

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_parse — Prepares an Oracle statement for execution

### Beschreibung

function oci_parse(resource `$connection`, string `$sql`): resource|false

Prepares `sql` using `connection` and returns the statement identifier, which can be used with oci_bind_by_name(), oci_execute() and other functions.

Statement identifiers can be freed with oci_free_statement() or by setting the variable to `null`.

### Parameter-Liste

`connection`

  An Oracle connection identifier, returned by oci_connect(), oci_pconnect(), or oci_new_connect().

`sql`

  The SQL or PL/SQL statement.

  SQL statements should not end with a semi-colon (";"). PL/SQL statements should end with a semi-colon (";").

### Rückgabewerte

Returns a statement handle on success, or `false` on error.

### Beispiele

Beispiel #1 oci_parse() example for SQL statements

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    // Parse the statement. Note there is no final semi-colon in the SQL statement
    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

Beispiel #2 oci_parse() example for PL/SQL statements

    <?php

    /*
      Before running the PHP program, create a stored procedure in
      SQL*Plus or SQL Developer:

      CREATE OR REPLACE PROCEDURE myproc(p1 IN NUMBER, p2 OUT NUMBER) AS
      BEGIN
          p2 := p1 * 2;
      END;

    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $p1 = 8;

    // When parsing PL/SQL programs, there should be a final semi-colon in the string
    $stid = oci_parse($conn, 'begin myproc(:p1, :p2); end;');
    oci_bind_by_name($stid, ':p1', $p1);
    oci_bind_by_name($stid, ':p2', $p2, 40);

    oci_execute($stid);

    print "$p2\n";   // prints 16

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Anmerkungen

> Hinweis:

> This function does not validate `sql`. The only way to find out if `sql` is a valid SQL or PL/SQL statement is to execute it.

### Siehe auch

- oci_execute() - Executes a statement
- oci_free_statement() - Gibt alle verknüpften Ressourcen eines Statements oder Zeigers frei.

# oci_password_change

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_password_change — Changes password of Oracle's user

### Beschreibung

function oci_password_change(
resource `$connection`,
string `$username`,
string `$old_password`,
string `$new_password`
): bool
function oci_password_change(
string `$database_name`,
string `$username`,
string `$old_password`,
string `$new_password`
): resource

Changes password for user with `username`.

The oci_password_change() function is most useful for PHP command-line scripts, or when non-persistent connections are used throughout the PHP application.

### Parameter-Liste

`connection`

  An Oracle connection identifier, returned by oci_connect() or oci_pconnect().

`username`

  The Oracle user name.

`old_password`

  The old password.

`new_password`

  The new password to be set.

`database_name`

  The database name.

### Rückgabewerte

When `database_name` is provided, oci_password_change() returns `true` on success, Bei einem Fehler wird `false` zurückgegeben.. When `connection` is provided, oci_password_change() returns the connection resource on success,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 oci_password_change() example changing the password of an already connected user

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    oci_password_change($c, $user, $current_pw, $new_pw);
    echo "New password is : " . $new_pw . "\n";

    ?>

Beispiel #2 oci_password_change() example of connecting and changing the password in one step

    <?php

    $dbase      = 'localhost/orcl';
    $user       = 'cj';
    $current_pw = 'welcome';
    $new_pw     = 'geelong';

    $c = oci_pconnect($user, $current_pw, $dbase);
    if (!$c) {
        $m = oci_error();
        if ($m['code'] == 28001) { // "ORA-28001: the password has expired"
            // Login and reset password at the same time
            $c = oci_password_change($dbase, $user, $current_pw, $new_pw);
            if ($c) {
                echo "New password is : " . $new_pw . "\n";
            }
        }
    }

    if (!$c) {  // The original error wasn't 28001, or the password change failed
        $m = oci_error();
        trigger_error('Could not connect to database: '. $m['message'], E_USER_ERROR);
    }

    // Use the connection $c
    // ...

    ?>

### Anmerkungen

> Hinweis:

> Changing the password either with this function or directly in Oracle should be done carefully. This is because PHP applications may continue to successfully reuse persistent connections by authenticating with the old password. The best practice is to restart all web servers whenever the user password is changed.

> Hinweis:

> If upgrading the Oracle client libraries or the database from a release prior to 11.2.0.3 to version 11.2.0.3 or higher, oci_password_change() may give the error "ORA-1017: invalid username/password" unless both client and server versions are upgraded at the same time.

> Hinweis:

> The second oci_password_change() syntax is available since OCI8 version 1.1.

# oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — Connect to an Oracle database using a persistent connection

### Beschreibung

function oci_pconnect(
string `$username`,
string `$password`,
?string `$connection_string` = `null`,
string `$encoding` = "",
int `$session_mode` = `OCI_DEFAULT`
): resource|false

Creates a persistent connection to an Oracle server and logs on.

Persistent connections are cached and re-used between requests, resulting in reduced overhead on each page load; a typical PHP application will have a single persistent connection open against an Oracle server per Apache child process (or PHP FPM process). See the OCI8 Connection Handling and Connection Pooling section for more information.

### Parameter-Liste

`username`

  The Oracle user name.

`password`

  The password for `username`.

`connection_string`

  Beinhaltet die `Oracle-Instanz`, mit der verbunden werden soll. Dies kann eine » Easy-Connect-Zeichenkette, ein Connect-Name aus der Datei tnsnames.ora oder der Name einer lokalen Oracle-Instanz sein.

  Wenn dies nicht angegebe wird oder `null` ist, verwendet PHP Umgebungsvariablen wie `TWO_TASK` (unter Linux), `LOCAL` (unter Windows) oder `ORACLE_SID` um die `Oracle-Instanz` zu ermitteln, mit der verbunden werden soll.

  Um die benannte Easy Connect Methode zu verwenden, muss PHP gegen die Clientbibliotheken von Oracle 10g oder höher gelinkt sein. Die Easy-Connect-Zeichenkette für Oracle 10g hat den Aufbau: [//]host_name[:port][/service_name]. Für Oracle 11g ist die Syntax: [//]host_name[:port][/service_name][:server_type][/instance_name]. Weitere Optionen wurden mit Oracle 19c eingeführt, darunter die timeout- und die keep-alive-Einstellungen. Siehe dazu die Oracle-Dokumentation. Die Servicenamen können ermittelt werden, indem man das Oracle-Hilfswerkzeug `lsnrctl status` auf dem Datenbankserver ausführt.

  Die Datei tnsnames.ora kann sich im Oracle Net Suchpfad befinden, welcher /der/pfad/zu/instantclient/network/admin, $ORACLE_HOME/network/admin sowie /etc beinhaltet. Alternativ kann `TNS_ADMIN` so gesetzt werden, dass $TNS_ADMIN/tnsnames.ora gelesen wird. Es muss sichergestellt sein, dass der Webserver eine Leseberechtigung für die Datei besitzt.

`encoding`

  Bestimmt den Zeichensatz, der von den Oracle Client Bibliotheken verwendet wird. Dieser Zeichensatz muss nicht dem von der Datenbank verwendeten Zeichensatz entsprechen. Wenn diese nicht übereinstimmen, wird Oracle bestmöglich versuchen, die Daten in den Datenbankzeichensatz zu übersetzen. Abhängig von den Zeichensätzen kann dies zu unbrauchbaren Ergebnissen führen. Diese Konvertierung führt auch zu einem erhöhten Zeitbedarf.

  Falls nicht angegeben, werden die Oracle Client Bibliotheken versuchen, den Zeichensatz aus der Umgebungsvariablen `NLS_LANG` auszulesen.

  Die Übergabe dieses Parameters verringert die Zeit für den Verbindungsaufbau.

`session_mode`

  Dieser Parameter ist seit PHP 5 (PECL OCI8 1.1) verfügbar und akzeptiert die folgenden Werte: `OCI_DEFAULT`, `OCI_SYSOPER` und `OCI_SYSDBA`. Falls entweder `OCI_SYSOPER` oder `OCI_SYSDBA` angegeben wurden wird diese Funktion versuchen die priviligierte Verbindung mit externen Credentials aufzubauen. Um diese einzuschalten muss man oci8.privileged_connect auf `On` setzen.

  PHP 5.3 (PECL OCI8 1.3.4) hat den Wert `OCI_CRED_EXT` eingeführt. Dies konfiguriert Oracle dazu eine externe oder Os-Authentifizierung vorzunehmen, welche in der Datenbank konfiguriert werden muss. Der Schalter `OCI_CRED_EXT` kann nur mit dem Benutzernamen "/" und einem leeren Passwort verwendet werden. oci8.privileged_connect kann entweder `On` oder `Off` sein.

  `OCI_CRED_EXT` kann mit `OCI_SYSOPER` oder `OCI_SYSDBA` kombiniert werden.

  `OCI_CRED_EXT` ist auf Windows-Systemen aus sicherheitsgründen nicht unterstützt.

### Rückgabewerte

Returns a connection identifier or `false` on error.

### Beispiele

Beispiel #1 Basic oci_pconnect() Example using Easy Connect syntax

    <?php

    // Connects to the XE service (i.e. database) on the "localhost" machine
    $conn = oci_pconnect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM employees');
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    ?>

See oci_connect() for further examples of parameter usage.

### Anmerkungen

> Hinweis: The lifetime and maximum number of persistent Oracle connections per PHP process can be tuned by setting the following configuration values: oci8.persistent_timeout, oci8.ping_interval and oci8.max_persistent.

### Siehe auch

- oci_connect() - Connect to an Oracle database
- oci_new_connect() - Connect to the Oracle server using a unique connection

# oci_register_taf_callback

(PHP 7.0 >= 7.0.21, PHP 8, PHP 7 >= 7.1.7, PHP 8, PECL OCI8 >= 2.1.7)

oci_register_taf_callback — Register a user-defined callback function for Oracle Database TAF

### Beschreibung

function oci_register_taf_callback(resource `$connection`, ?callable `$callback`): bool

Registers a user-defined callback function to `connection`. If `connection` fails due to instance or network failure, the registered callback function will be invoked for several times during failover. See OCI8 Transparent Application Failover (TAF) Support for information.

When oci_register_taf_callback() is called multiple times, each registration overwrites the previous one.

Use oci_unregister_taf_callback() to explicitly unregister a user-defined callback.

TAF callback registration will NOT be saved across persistent connections, therefore the callback needs to be re-registered for a new persistent connection.

### Parameter-Liste

`connection`

  An Oracle connection identifier.

`callback`

  A user-defined callback to register for Oracle TAF. It can be a string of the function name or a Closure (anonymous function).

  The interface of a TAF user-defined callback function is as follows:

  function userCallbackFn(resource `$connection`, int `$event`, int `$type`): int

  See the parameter description and an example on OCI8 Transparent Application Failover (TAF) Support page.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- oci_unregister_taf_callback() - Unregister a user-defined callback function for Oracle Database TAF

# oci_result

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_result — Returns field's value from the fetched row

### Beschreibung

function oci_result(resource `$statement`, string|int `$column`): mixed

Returns the data from `column` in the current row, fetched by oci_fetch().

Für Details zur vom OCI8-Treiber durchgeführten Umsetzung von Datentypen siehe die vom Treiber unterstützen Datentypen.

### Parameter-Liste

`statement`

`column`

  Can be either use the column number (1-based) or the column name. The case of the column name must be the case that Oracle meta data describes the column as, which is uppercase for columns created case insensitively.

### Rückgabewerte

Returns everything as strings except for abstract types (ROWIDs, LOBs and FILEs). Returns `false` on error.

### Beispiele

Beispiel #1 oci_fetch() with oci_result()

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);
    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo oci_result($stid, 'LOCATION_ID') . " is ";
        echo oci_result($stid, 'CITY') . "<br>\n";
    }

    // Displays:
    //   1000 is Roma
    //   1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Siehe auch

- oci_fetch_array() - Liefert die nächste Zeile einer Abfrage als assoziatives oder numerisches Array
- oci_fetch_assoc() - Liefert die nächste Zeile einer Abfrage als assoziatives Array
- oci_fetch_object() - Liefert die nächste Zeile einer Abfrage als Objekt
- oci_fetch_row() - Liefert die nächste Zeile einer Abfrage als numerisches Array
- oci_fetch_all() - Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab

# oci_rollback

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_rollback — Rolls back the outstanding database transaction

### Beschreibung

function oci_rollback(resource `$connection`): bool

Reverts all uncommitted changes for the Oracle `connection` and ends the transaction. It releases all locks held. All Oracle `SAVEPOINTS` are erased.

A transaction begins when the first SQL statement that changes data is executed with oci_execute() using the `OCI_NO_AUTO_COMMIT` flag. Further data changes made by other statements become part of the same transaction. Data changes made in a transaction are temporary until the transaction is committed or rolled back. Other users of the database will not see the changes until they are committed.

When inserting or updating data, using transactions is recommended for relational data consistency and for performance reasons.

### Parameter-Liste

`connection`

  An Oracle connection identifier, returned by oci_connect(), oci_pconnect() or oci_new_connect().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 oci_rollback() example

    <?php

    // Insert into several tables, rolling back the changes if an error occurs

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

    // The OCI_NO_AUTO_COMMIT flag tells Oracle not to commit the INSERT immediately
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
    $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
    if (!$r) {
        $e = oci_error($stid);
        oci_rollback($conn);  // rollback changes to both tables
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    // Commit the changes to both tables
    $r = oci_commit($conn);
    if (!r) {
        $e = oci_error($conn);
        trigger_error(htmlentities($e['message']), E_USER_ERROR);
    }

    ?>

Beispiel #2 Rolling back to a `SAVEPOINT` example

    <?php
    $stid = oci_parse($conn, 'UPDATE mytab SET id = 1111');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // Create the savepoint
    $stid = oci_parse($conn, 'SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    $stid = oci_parse($conn, 'UPDATE mytab SET id = 2222');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    // Use an explicit SQL statement to rollback to the savepoint
    $stid = oci_parse($conn, 'ROLLBACK TO SAVEPOINT mysavepoint');
    oci_execute($stid, OCI_NO_AUTO_COMMIT);

    oci_commit($conn);  // mytab now has id of 1111
    ?>

### Anmerkungen

> Hinweis:

> Transactions are automatically rolled back when you close the connection, or when the script ends, whichever is soonest. You need to explicitly call oci_commit() to commit the transaction.

> Any call to oci_execute() that uses `OCI_COMMIT_ON_SUCCESS` mode explicitly or by default will commit any previous uncommitted transaction.

> Any Oracle DDL statement such as `CREATE` or `DROP` will automatically commit any uncommitted transaction.

### Siehe auch

- oci_commit() - Commits the outstanding database transaction
- oci_execute() - Executes a statement

# oci_server_version

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_server_version — Returns the Oracle Database version

### Beschreibung

function oci_server_version(resource `$connection`): string|false

Returns a string with the Oracle Database version and available options

### Parameter-Liste

`connection`

### Rückgabewerte

Returns the version information as a string or `false` on error.

### Beispiele

Beispiel #1 oci_server_version() example

    <?php

    $conn = oci_connect("hr", "hrpwd", "localhost/XE");
    echo "Server Version: " . oci_server_version($conn);

    // Displays:
    // Server Version: Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit Production
    // With the Partitioning, OLAP, Data Mining and Real Application Testing option

    oci_close($conn);

    ?>

### Siehe auch

- oci_client_version() - Returns the Oracle client library version

# oci_set_action

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_action — Sets the action name

### Beschreibung

function oci_set_action(resource `$connection`, string `$action`): bool

Sets the action name for Oracle tracing.

The action name is registered with the database when the next 'round-trip' from PHP to the database occurs, typically when an SQL statement is executed.

The action name can subsequently be queried from database administration views such as `V$SESSION`. It can be used for tracing and monitoring such as with `V$SQLAREA` and `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

The value may be retained across persistent connections.

### Parameter-Liste

`connection`

  Ein Oracle-Verbindungs-Identifiierer, der von oci_connect(), oci_pconnect(), oder oci_new_connect() zurückgegeben wurde.

`action`

  User chosen string up to 32 bytes long.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Setting the action

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Record the action
    oci_set_action($c, 'Friend Lookup');

    // Code that causes a round-trip, for example a query:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // While the script is running, the administrator can see the actions
    // being performed:

    sqlplus system/welcome
    SQL> select action from v$session;

### Anmerkungen

> Hinweis: Oracle Versionsanforderungen

> Diese Funktion ist verfügbar, wenn PHP gegen die Bibliotheken der Oracle-Datenbank in Version 10g und höher gelinkt ist.

Tipp

# Performance

Bei älteren Versionen von OCI8 oder der Oracle-Datenbank können die Client- Informationen mit einem `DBMS_APPLICATION_INFO`-Paket gesetzt werden. Dies ist weniger effizient als die Verwendung von oci_set_client_info().

Achtung

# Roundtrip Hinweis

Einige, aber nicht alle OCI8-Funktionen verursachen Roundtrips. Roundtrips zur Datenbank dürfen nicht für Queries auftreten, wenn der Ergebniscache aktiviert ist.

### Siehe auch

- oci_set_module_name() - Sets the module name
- oci_set_client_info() - Sets the client information
- oci_set_client_identifier() - Sets the client identifier
- oci_set_db_operation() - Sets the database operation

# oci_set_call_timeout

(PHP 7.2 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_call_timeout — Sets a millisecond timeout for database calls

### Beschreibung

function oci_set_call_timeout(resource `$connection`, int `$timeout`): bool

Sets a timeout limiting the maximum time a database round-trip using this connection may take.

Each OCI8 operation may make zero or more calls to Oracle's client library. These internal calls may then may make zero or more round-trips to Oracle Database. If any one of those round-trips takes more than `time_out` milliseconds, then the operation is cancelled and an error is returned to the application.

The `time_out` value applies to each round-trip individually, not to the sum of all round-trips. Time spent processing in PHP OCI8 before or after the completion of each round-trip is not counted.

When a call is interrupted, Oracle will attempt to clean up the connection for reuse. This operation is allowed to run for another `time_out` period. Depending on the outcome of the cleanup, the connection may or may not be reusable.

When persistent connections are used, the timeout value will be retained across PHP requests.

The oci_set_call_timeout() function is available when OCI8 uses Oracle 18 (or later) Client libraries.

### Parameter-Liste

`connection`

  Ein Oracle-Verbindungs-Identifiierer, der von oci_connect(), oci_pconnect(), oder oci_new_connect() zurückgegeben wurde.

`timeout`

  The maximum time in milliseconds that any single round-trip between PHP and Oracle Database may take.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Setting the timeout

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    oci_set_call_timeout($conn, 5000);

    ?>

# oci_set_client_identifier

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_identifier — Sets the client identifier

### Beschreibung

function oci_set_client_identifier(resource `$connection`, string `$client_id`): bool

Sets the client identifier used by various database components to identify lightweight application users who authenticate as the same database user.

The client identifier is registered with the database when the next 'round-trip' from PHP to the database occurs, typically when an SQL statement is executed.

The identifier can subsequently be queried, for example with `SELECT SYS_CONTEXT('USERENV','CLIENT_IDENTIFIER') FROM DUAL`. Database administration views such as `V$SESSION` will also contain the value. It can be used with `DBMS_MONITOR.CLIENT_ID_TRACE_ENABLE` for tracing and can also be used for auditing.

The value may be retained across page requests that use the same persistent connection.

### Parameter-Liste

`connection`

  Ein Oracle-Verbindungs-Identifiierer, der von oci_connect(), oci_pconnect(), oder oci_new_connect() zurückgegeben wurde.

`client_id`

  User chosen string up to 64 bytes long.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Setting the client identifier to the application user

    <?php

    // Find the application user's login name
    session_start();
    $un = my_validate_session($_SESSION['username']);
    $c = oci_connect('myschema', 'welcome', 'localhost/XE');

    // Tell Oracle who that user is
    oci_set_client_identifier($c, $un);

    // The next round-trip to the database will piggyback the identifier
    $s = oci_parse($c, 'select mydata from mytable');
    oci_execute($s);

    // ...

    ?>

### Anmerkungen

Achtung

# Roundtrip Hinweis

Einige, aber nicht alle OCI8-Funktionen verursachen Roundtrips. Roundtrips zur Datenbank dürfen nicht für Queries auftreten, wenn der Ergebniscache aktiviert ist.

### Siehe auch

- oci_set_module_name() - Sets the module name
- oci_set_action() - Sets the action name
- oci_set_client_info() - Sets the client information
- oci_set_db_operation() - Sets the database operation

# oci_set_client_info

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_info — Sets the client information

### Beschreibung

function oci_set_client_info(resource `$connection`, string `$client_info`): bool

Sets the client information for Oracle tracing.

The client information is registered with the database when the next 'round-trip' from PHP to the database occurs, typically when an SQL statement is executed.

The client information can subsequently be queried from database administration views such as `V$SESSION`.

The value may be retained across persistent connections.

### Parameter-Liste

`connection`

  Ein Oracle-Verbindungs-Identifiierer, der von oci_connect(), oci_pconnect(), oder oci_new_connect() zurückgegeben wurde.

`client_info`

  User chosen string up to 64 bytes long.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Setting the client information

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Record the client information
    oci_set_client_info($c, 'My Application Version 2');

    // Code that causes a round-trip, for example a query:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // While the script is running, the administrator can see the client
    // information:

    sqlplus system/welcome
    SQL> select client_info from v$session;

### Anmerkungen

> Hinweis: Oracle Versionsanforderungen

> Diese Funktion ist verfügbar, wenn PHP gegen die Bibliotheken der Oracle-Datenbank in Version 10g und höher gelinkt ist.

Tipp

# Performance

Bei älteren Versionen von OCI8 oder der Oracle-Datenbank können die Client- Informationen mit einem `DBMS_APPLICATION_INFO`-Paket gesetzt werden. Dies ist weniger effizient als die Verwendung von oci_set_client_info().

Achtung

# Roundtrip Hinweis

Einige, aber nicht alle OCI8-Funktionen verursachen Roundtrips. Roundtrips zur Datenbank dürfen nicht für Queries auftreten, wenn der Ergebniscache aktiviert ist.

### Siehe auch

- oci_set_module_name() - Sets the module name
- oci_set_action() - Sets the action name
- oci_set_client_identifier() - Sets the client identifier
- oci_set_db_operation() - Sets the database operation

# oci_set_db_operation

(PHP 7 >= 7.2.14, PHP 8, PHP 7 >= 7.3.1, PHP 8, PECL OCI8 >= 2.2.0)

oci_set_db_operation — Sets the database operation

### Beschreibung

function oci_set_db_operation(resource `$connection`, string `$action`): bool

Sets the DBOP for Oracle tracing.

The database operation name is registered with the database when the next 'round-trip' from PHP to the database occurs, typically when a SQL statement is executed.

The database operation can subsequently be queried from database administration views such as `V$SQL_MONITOR`.

The oci_set_db_operation() function is available when OCI8 uses Oracle 12 (or later) Client libraries and Oracle Database 12 (or later).

### Parameter-Liste

`connection`

  Ein Oracle-Verbindungs-Identifiierer, der von oci_connect(), oci_pconnect(), oder oci_new_connect() zurückgegeben wurde.

`action`

  User chosen string.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Setting the DBOP

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Record the operation
    oci_set_db_operation($c, 'main query');

    // Code that causes a round-trip, for example a query:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);

    ?>

    // While the script is running, the administrator can see the database operations
    // being performed:

    sqlplus system/welcome
    SQL> select dbop_name from v$sql_monitor;

### Anmerkungen

Achtung

# Roundtrip Hinweis

Einige, aber nicht alle OCI8-Funktionen verursachen Roundtrips. Roundtrips zur Datenbank dürfen nicht für Queries auftreten, wenn der Ergebniscache aktiviert ist.

### Siehe auch

- oci_set_action() - Sets the action name
- oci_set_module_name() - Sets the module name
- oci_set_client_info() - Sets the client information
- oci_set_client_identifier() - Sets the client identifier

# oci_set_edition

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_edition — Sets the database edition

### Beschreibung

function oci_set_edition(string `$edition`): bool

Sets the database "edition" of objects to be used by a subsequent connections.

Oracle Editions allow concurrent versions of applications to run using the same schema and object names. This is useful for upgrading live systems.

Call oci_set_edition() before calling oci_connect(), oci_pconnect() or oci_new_connect().

If an edition is set that is not valid in the database, connection will fail even if oci_set_edition() returns success.

When using persistent connections, if a connection with the requested edition setting already exists, it is reused. Otherwise, a different persistent connection is created

### Parameter-Liste

`edition`

  Oracle Database edition name previously created with the SQL "`CREATE EDITION`" command.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Two scripts can use different versions of myfunc() at the same time

    <?php

    // File 1

    echo "Version 1 of application\n";

    oci_set_edition('ORA$BASE');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "The result is $r\n";

    ?>

    <?php

    // File 2

    echo "Version 2 of application\n";

    oci_set_edition('E1');
    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    $s = oci_parse($c, "begin :r := myfunc(); end;");
    oci_bind_by_name($s, ":r", $r, 20);
    oci_execute($s);
    echo "The result is $r\n";

    ?>

### Anmerkungen

> Hinweis: Oracle version requirement

> This function is available from Oracle 11gR2 onwards.

Achtung

# Persistent connections

To avoid inconsistencies and unexpected errors, do not use ALTER SESSION SET EDITION to change the edition on persistent connections.

Achtung

# DRCP Connection Pooling

To avoid inconsistencies and unexpected errors when using editions and DRCP with Oracle 11.2.0.1, keep a one-to-one correspondence between the oci8.connection_class and the edition name used by applications. Each pooled server of a given connection class should only be used with one edition. This restriction has been removed with Oracle 11.2.0.2.

# oci_set_module_name

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_module_name — Sets the module name

### Beschreibung

function oci_set_module_name(resource `$connection`, string `$name`): bool

Sets the module name for Oracle tracing.

The module name is registered with the database when the next 'round-trip' from PHP to the database occurs, typically when an SQL statement is executed.

The name can subsequently be queried from database administration views such as `V$SESSION`. It can be used for tracing and monitoring such as with `V$SQLAREA` and `DBMS_MONITOR.SERV_MOD_ACT_STAT_ENABLE`.

The value may be retained across persistent connections.

### Parameter-Liste

`connection`

  Ein Oracle-Verbindungs-Identifiierer, der von oci_connect(), oci_pconnect(), oder oci_new_connect() zurückgegeben wurde.

`name`

  User chosen string up to 48 bytes long.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Setting the module name

    <?php

    $c = oci_connect('hr', 'welcome', 'localhost/XE');

    // Record the module
    oci_set_module_name($c, 'Home Page');

    // Code that causes a round-trip, for example a query:
    $s = oci_parse($c, 'select * from dual');
    oci_execute($s);
    oci_fetch_all($s, $res);

    sleep(30);
    ?>

    // While the script is running, the administrator can see the
    // modules in use:

    sqlplus system/welcome
    SQL> select module from v$session;

### Anmerkungen

> Hinweis: Oracle Versionsanforderungen

> Diese Funktion ist verfügbar, wenn PHP gegen die Bibliotheken der Oracle-Datenbank in Version 10g und höher gelinkt ist.

Tipp

# Performance

Bei älteren Versionen von OCI8 oder der Oracle-Datenbank können die Client- Informationen mit einem `DBMS_APPLICATION_INFO`-Paket gesetzt werden. Dies ist weniger effizient als die Verwendung von oci_set_client_info().

Achtung

# Roundtrip Hinweis

Einige, aber nicht alle OCI8-Funktionen verursachen Roundtrips. Roundtrips zur Datenbank dürfen nicht für Queries auftreten, wenn der Ergebniscache aktiviert ist.

### Siehe auch

- oci_set_action() - Sets the action name
- oci_set_client_info() - Sets the client information
- oci_set_client_identifier() - Sets the client identifier
- oci_set_db_operation() - Sets the database operation

# oci_set_prefetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_set_prefetch — Sets number of rows to be prefetched by queries

### Beschreibung

function oci_set_prefetch(resource `$statement`, int `$rows`): bool

Sets the number of rows to be buffered by the Oracle Client libraries after a successful query call to oci_execute() and for each subsequent internal fetch request to the database. For queries returning a large number of rows, performance can be significantly improved by increasing the prefetch count above the default oci8.default_prefetch value.

Prefetching is Oracle's efficient way of returning more than one data row from the database in each network request. This can result in better network and CPU utilization. The buffering of rows is internal to OCI8 and the behavior of OCI8 fetching functions is unchanged regardless of the prefetch count. For example, oci_fetch_row() will always return one row. The prefetch buffer is per-statement and is not used by re-executed statements or by other connections.

Call oci_set_prefetch() before calling oci_execute().

A tuning goal is to set the prefetch value to a reasonable size for the network and database to handle. For queries returning a very large number of rows, overall system efficiency might be better if rows are retrieved from the database in several chunks (i.e set the prefetch value smaller than the number of rows). This allows the database to handle other users' statements while the PHP script is processing the current set of rows.

Query prefetching was introduced in Oracle 8i. REF CURSOR prefetching was introduced in Oracle 11gR2 and occurs when PHP is linked with Oracle 11gR2 (or later) Client libraries. Nested cursor prefetching was introduced in Oracle 11gR2 and requires both the Oracle Client libraries and the database to be version 11gR2 or greater.

Prefetching is not supported when queries contain LONG or LOB columns. The prefetch value is ignored and single-row fetches will be used in all the situations when prefetching is not supported.

When using Oracle Database 12c, the prefetch value set by PHP can be overridden by Oracle's client `oraaccess.xml` configuration file. Refer to Oracle documentation for more detail.

### Parameter-Liste

`statement`

  Der Identifizierer eines gültigen OCI8-Ausdrucks, der von oci_parse() erzeugt und von oci_execute() oder einem `REF CURSOR`-Ausdruck verwendet wird.

`rows`

  The number of rows to be prefetched, >= 0

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Changing the default prefetch value for a query

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
    oci_set_prefetch($stid, 300);  // Set before calling oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

Beispiel #2 Changing the default prefetch for a REF CURSOR fetch

    <?php
    /*
      Create the PL/SQL stored procedure as:

      CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
      BEGIN
        OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
      END;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Change the prefetch before executing the cursor.
    // REF CURSOR prefetching works when PHP is linked with Oracle 11gR2 or later Client libraries
    oci_set_prefetch($refcur, 200);
    oci_execute($refcur);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($refcur);
    oci_free_statement($stid);
    oci_close($conn);

    ?>

If PHP OCI8 fetches from a REF CURSOR and then passes the REF CURSOR back to a second PL/SQL procedure for further processing, then set the REF CURSOR prefetch count to `0` to avoid rows being "lost" from the result set. The prefetch value is the number of extra rows fetched in each OCI8 internal request to the database, so setting it to `0` means only fetch one row at a time.

Beispiel #3 Setting the prefetch value when passing a REF CURSOR back to Oracle

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/orcl');

    // get the REF CURSOR
    $stid = oci_parse($conn, 'BEGIN myproc(:rc_out); END;');
    $refcur = oci_new_cursor($conn);
    oci_bind_by_name($stid, ':rc_out', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    // Display two rows, but don't prefetch any extra rows otherwise
    // those extra rows would not be passed back to myproc_use_rc().
    oci_set_prefetch($refcur, 0);
    oci_execute($refcur);
    $row = oci_fetch_array($refcur);
    var_dump($row);
    $row = oci_fetch_array($refcur);
    var_dump($row);

    // pass the REF CURSOR to myproc_use_rc() to do more data processing
    // with the result set
    $stid = oci_parse($conn, 'begin myproc_use_rc(:rc_in); end;');
    oci_bind_by_name($stid, ':rc_in', $refcur, -1, OCI_B_CURSOR);
    oci_execute($stid);

    ?>

### Siehe auch

- oci8.default_prefetch ini option

# oci_set_prefetch_lob

(PHP 8.2, PECL OCI8 >= 3.2)

oci_set_prefetch_lob — Sets the amount of data prefetched for each CLOB or BLOB.

### Beschreibung

function oci_set_prefetch_lob(resource `$statement`, int `$prefetch_lob_size`): bool

Sets the internal buffer size used to fetch each CLOB or BLOB value when the implementation gets the internal Oracle LOB locator from the database after a successful query call to oci_execute() and for each subsequent internal fetch request to the database. Increasing this value can improve the performance of fetching smaller LOBs by reducing round-trips between PHP and the database. Memory usage will change.

The value affects LOBs returned as OCILob instances and also those returned using `OCI_RETURN_LOBS`.

Call oci_set_prefetch_lob() before calling oci_execute(). If it is not called, the value of oci8.prefetch_lob_size is used.

The LOB prefetch value should only be set with Oracle Database 12.2 or later.

### Parameter-Liste

`statement`

  Der Identifizierer eines gültigen OCI8-Ausdrucks, der von oci_parse() erzeugt und von oci_execute() oder einem `REF CURSOR`-Ausdruck verwendet wird.

`prefetch_lob_size`

  The number of bytes of each LOB to be prefetched, >= 0

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Changing the LOB prefetch value for a query

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'SELECT myclob FROM mytable');
    oci_set_prefetch_lob($stid, 100000);  // Set before calling oci_execute()
    oci_execute($stid);

    echo "<table border='1'>\n";
    while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS+OCI_RETURN_LOBS)) {
        echo "<tr>\n";
        foreach ($row as $item) {
            echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### Siehe auch

- oci8.prefetch_lob_size ini option

# oci_statement_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_statement_type — Returns the type of a statement

### Beschreibung

function oci_statement_type(resource `$statement`): string|false

Returns a keyword identifying the type of the OCI8 `statement`.

### Parameter-Liste

`statement`

  A valid OCI8 statement identifier from oci_parse().

### Rückgabewerte

Returns the type of `statement` as one of the following strings.

Statement type
Return String | Notes
--- | ---
`ALTER` |
`BEGIN` |
`CALL` |
`CREATE` |
`DECLARE` |
`DELETE` |
`DROP` |
`INSERT` |
`SELECT` |
`UPDATE` |
`UNKNOWN` |

Returns `false` on error.

### Beispiele

Beispiel #1 oci_statement_type() example

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');

    $stid = oci_parse($conn, 'DELETE FROM departments WHERE department_id = 130;');
    if (oci_statement_type($stid) == "DELETE") {
        trigger_error('You are not allowed to delete from this table', E_USER_ERROR);
    }
    else {
        oci_execute($stid);  // delete the row
    }

    oci_free_statement($stid);
    oci_close($conn);

    ?>

# oci_unregister_taf_callback

(PHP 7.0 >= 7.0.23, PHP 8, PHP 7 >= 7.1.9, PHP 8, PECL OCI8 >= 2.1.7)

oci_unregister_taf_callback — Unregister a user-defined callback function for Oracle Database TAF

### Beschreibung

function oci_unregister_taf_callback(resource `$connection`): bool

Unregister the user-defined callback function registered to `connection` by oci_register_taf_callback(). See OCI8 Transparent Application Failover (TAF) Support for information.

### Parameter-Liste

`connection`

  An Oracle connection identifier.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- oci_register_taf_callback() - Register a user-defined callback function for Oracle Database TAF

## Inhaltsverzeichnis

- oci_bind_array_by_name — Bindet ein PHP-Array an einen Oracle-PL/SQL-Arrayparameter
- oci_bind_by_name — Binds a PHP variable to an Oracle placeholder
- oci_cancel — Bricht das Lesen eines Zeigers ab
- oci_client_version — Returns the Oracle client library version
- oci_close — Schließt eine Oracle-Verbindung
- oci_commit — Commits the outstanding database transaction
- oci_connect — Connect to an Oracle database
- oci_define_by_name — Associates a PHP variable with a column for query fetches
- oci_error — Liefert den letzten Fehler
- oci_execute — Executes a statement
- oci_fetch — Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab
- oci_fetch_all — Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab
- oci_fetch_array — Liefert die nächste Zeile einer Abfrage als assoziatives oder numerisches Array
- oci_fetch_assoc — Liefert die nächste Zeile einer Abfrage als assoziatives Array
- oci_fetch_object — Liefert die nächste Zeile einer Abfrage als Objekt
- oci_fetch_row — Liefert die nächste Zeile einer Abfrage als numerisches Array
- oci_field_is_null — Checks if a field in the currently fetched row is null
- oci_field_name — Returns the name of a field from the statement
- oci_field_precision — Tell the precision of a field
- oci_field_scale — Tell the scale of the field
- oci_field_size — Returns field's size
- oci_field_type — Returns a field's data type name
- oci_field_type_raw — Tell the raw Oracle data type of the field
- oci_free_descriptor — Frees a descriptor
- oci_free_statement — Gibt alle verknüpften Ressourcen eines Statements oder Zeigers frei.
- oci_get_implicit_resultset — Returns the next child statement resource from a parent statement resource that has Oracle Database Implicit Result Sets
- oci_lob_copy — Copies large object
- oci_lob_is_equal — Compares two LOB/FILE locators for equality
- oci_new_collection — Allocates new collection object
- oci_new_connect — Connect to the Oracle server using a unique connection
- oci_new_cursor — Allocates and returns a new cursor (statement handle)
- oci_new_descriptor — Initializes a new empty LOB or FILE descriptor
- oci_num_fields — Returns the number of result columns in a statement
- oci_num_rows — Returns number of rows affected during statement execution
- oci_parse — Prepares an Oracle statement for execution
- oci_password_change — Changes password of Oracle's user
- oci_pconnect — Connect to an Oracle database using a persistent connection
- oci_register_taf_callback — Register a user-defined callback function for Oracle Database TAF
- oci_result — Returns field's value from the fetched row
- oci_rollback — Rolls back the outstanding database transaction
- oci_server_version — Returns the Oracle Database version
- oci_set_action — Sets the action name
- oci_set_call_timeout — Sets a millisecond timeout for database calls
- oci_set_client_identifier — Sets the client identifier
- oci_set_client_info — Sets the client information
- oci_set_db_operation — Sets the database operation
- oci_set_edition — Sets the database edition
- oci_set_module_name — Sets the module name
- oci_set_prefetch — Sets number of rows to be prefetched by queries
- oci_set_prefetch_lob — Sets the amount of data prefetched for each CLOB or BLOB.
- oci_statement_type — Returns the type of a statement
- oci_unregister_taf_callback — Unregister a user-defined callback function for Oracle Database TAF

# The OCICollection class

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Einführung

OCI8 Collection functionality.

> Hinweis:

> The OCI-Collection class was renamed to OCICollection in PHP 8 OCI8 3.0.0 to align with PHP naming standards.

## Klassenbeschreibung

class OCICollection {
/* Methoden */
public function append(string `$value`): bool
public function assign(OCICollection `$from`): bool
public function assignElem(int `$index`, string `$value`): bool
public function free(): bool
public function getElem(int `$index`): string|float|null|false
public function max(): int|false
public function size(): int|false
public function trim(int `$num`): bool
}

# OCICollection::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::append — Hängt ein Element an eine Sammlung

### Beschreibung

public function OCICollection::append(string `$value`): bool

Hängt ein Element ans Ende einer Sammlung.

### Parameter-Liste

`value`

  Der Wert, der der Sammlung hinzugefügt werden soll.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | Die Klasse OCI-Collection wurde in OCICollection umbenannt, um den PHP-Namensstandards zu entsprechen.

### Siehe auch

- OCICollection::assign

# OCICollection::assign

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assign — Weist einer Sammlung einen Wert aus einer anderen Sammlung zu

### Beschreibung

public function OCICollection::assign(OCICollection `$from`): bool

Weist einer Sammlung den Wert einer vorher erstellten Sammlung zu. Beide Sammlungen müssen mit oci_new_collection() erstellt worden sein, bevor sie verwendet werden.

### Parameter-Liste

`from`

  Eine Instanz einer OCI-Sammlung.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | Die Klasse OCI-Collection wurde in OCICollection umbenannt, um den PHP-Namensstandards zu entsprechen.

### Siehe auch

- OCICollection::append

# OCICollection::assignElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assignElem — Weist einem Element einer Sammlung einen Wert zu

### Beschreibung

public function OCICollection::assignElem(int `$index`, string `$value`): bool

Weist dem Element mit dem Index `index` einen Wert zu.

### Parameter-Liste

`index`

  Der Index des Elements. Der erste Index ist 0.

`value`

  Kann eine Zeichenkette oder eine Zahl sein.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | Die Klasse OCI-Collection wurde in OCICollection umbenannt, um den PHP-Namensstandards zu entsprechen.

### Siehe auch

- OCICollection::getElem

# OCICollection::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::free — Gibt die mit einem Sammelobjekt verknüpften Ressourcen frei

### Beschreibung

public function OCICollection::free(): bool

Gibt die mit einem Sammelobjekt verknüpften Ressourcen frei.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | Die Klasse OCI-Collection wurde in OCICollection umbenannt, um den PHP-Namensstandards zu entsprechen.

### Siehe auch

- oci_new_collection

# OCICollection::getElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::getElem — Liefert den Wert eines Elements

### Beschreibung

public function OCICollection::getElem(int `$index`): string|float|null|false

Gibt den Wert des Elements mit dem Index `index` (beginnend bei 0) zurück.

### Parameter-Liste

`index`

  Der Index des Elements. Der erste Index ist 0.

### Rückgabewerte

Gibt `false` zurück, wenn ein solches Element nicht existiert, `null`, wenn das Element `null` ist, eine Zeichenkette, wenn das Element zu einer Spalte vom Datentyp Zeichenkette gehört und eine Nummer, wenn das Element ein numerisches Feld ist.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | Die Klasse OCI-Collection wurde in OCICollection umbenannt, um den PHP-Namensstandards zu entsprechen.

### Siehe auch

- OCICollection::assignElem

# OCICollection::max

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::max — Liefert die maximale Anzahl der Elemente in einer Sammlung

### Beschreibung

public function OCICollection::max(): int|false

Gibt die maximale Anzahl der Elemente in einer Sammlung zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die maximale Anzahl als Integer zurück oder `false` bei Fehlern.

Wenn der zurückgegebene Wert 0 ist, ist die Anzahl der Elemente nicht begrenzt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | Die Klasse OCI-Collection wurde in OCICollection umbenannt, um den PHP-Namensstandards zu entsprechen.

### Siehe auch

- OCICollection::size

# OCICollection::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::size — Liefert die Größe der Sammlung

### Beschreibung

public function OCICollection::size(): int|false

Gibt die Größe der Sammlung zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl Elemente der Sammlung zurück oder `false` bei einem Fehler.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | Die Klasse OCI-Collection wurde in OCICollection umbenannt, um den PHP-Namensstandards zu entsprechen.

### Siehe auch

- OCICollection::max

# OCICollection::trim

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::trim — Entfernt Elemente vom Ende einer Sammlung

### Beschreibung

public function OCICollection::trim(int `$num`): bool

Entfernt `num` Elemente vom Ende einer Sammlung.

### Parameter-Liste

`num`

  Die zu entfernende Anzahl Elemente.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | Die Klasse OCI-Collection wurde in OCICollection umbenannt, um den PHP-Namensstandards zu entsprechen.

### Siehe auch

- OCICollection::size

## Inhaltsverzeichnis

- OCICollection::append — Hängt ein Element an eine Sammlung
- OCICollection::assign — Weist einer Sammlung einen Wert aus einer anderen Sammlung zu
- OCICollection::assignElem — Weist einem Element einer Sammlung einen Wert zu
- OCICollection::free — Gibt die mit einem Sammelobjekt verknüpften Ressourcen frei
- OCICollection::getElem — Liefert den Wert eines Elements
- OCICollection::max — Liefert die maximale Anzahl der Elemente in einer Sammlung
- OCICollection::size — Liefert die Größe der Sammlung
- OCICollection::trim — Entfernt Elemente vom Ende einer Sammlung

# The OCILob class

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

## Einführung

OCI8 LOB functionality for large binary (BLOB) and character (CLOB) objects.

> Hinweis:

> The OCI-Lob class was renamed to OCILob in PHP 8 and PECL OCI8 3.0.0 to align with PHP naming standards.

## Klassenbeschreibung

class OCILob {
/* Methoden */
public function append(OCILob `$from`): bool
public function close(): bool
public function eof(): bool
public function erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false
public function export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool
public function flush(int `$flag` = 0): bool
public function free(): bool
public function getBuffering(): bool
public function import(string `$filename`): bool
public function load(): string|false
public function read(int `$length`): string|false
public function rewind(): bool
public function save(string `$data`, int `$offset` = 0): bool
public function seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool
public function setBuffering(bool `$mode`): bool
public function size(): int|false
public function tell(): int|false
public function truncate(int `$length` = 0): bool
public function write(string `$data`, ?int `$length` = `null`): int|false
public function writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool
}

# OCILob::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::append — Appends data from the large object to another large object

### Beschreibung

public function OCILob::append(OCILob `$from`): bool

Appends data from the large object to the end of another large object.

Writing to the large object with this method will fail if buffering was previously enabled. You must disable buffering before appending. You may need to flush buffers with OCILob::flush before disabling buffering.

### Parameter-Liste

`from`

  The copied LOB.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::flush
- OCILob::setBuffering
- OCILob::getBuffering

# OCILob::close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::close — Closes LOB descriptor

### Beschreibung

public function OCILob::close(): bool

Closes descriptor of LOB or FILE. This function should be used only with OCILob::writeTemporary.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::writeTemporary

# OCILob::eof

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::eof — Tests for end-of-file on a large object's descriptor

### Beschreibung

public function OCILob::eof(): bool

Tells whether the internal pointer of large object is at the end of LOB.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if internal pointer of large object is at the end of LOB. Otherwise returns `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Anmerkungen

> Hinweis:

> This function will return an Oracle error if OCILob::setBuffering is enabled on the LOB.

### Siehe auch

- OCILob::size

# OCILob::erase

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::erase — Erases a specified portion of the internal LOB data

### Beschreibung

public function OCILob::erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false

Erases a specified portion of the internal LOB data starting at a specified `offset`. If called without parameters, it erases all LOB data.

For BLOBs, erasing means that the existing LOB value is overwritten with zero-bytes. For CLOBs, the existing LOB value is overwritten with spaces.

### Parameter-Liste

`offset`

`length`

### Rückgabewerte

Returns the actual number of characters/bytes erased Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` and `length` are now nullable.
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::truncate

# OCILob::export

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::export — Exports LOB's contents to a file

### Beschreibung

public function OCILob::export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool

Exports LOB contents to a file.

### Parameter-Liste

`filename`

  Path to the file.

`offset`

  Indicates from where to start exporting.

`length`

  Indicates the length of data to be exported.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` and `length` are now nullable.
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::import

# OCILob::flush

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::flush — Flushes/writes buffer of the LOB to the server

### Beschreibung

public function OCILob::flush(int `$flag` = 0): bool

OCILob::flush() actually writes data to the server.

### Parameter-Liste

`flag`

  By default, resources are not freed, but using flag `OCI_LOB_BUFFER_FREE` you can do it explicitly. Be sure you know what you're doing - next read/write operation to the same part of LOB will involve a round-trip to the server and initialize new buffer resources. It is recommended to use `OCI_LOB_BUFFER_FREE` flag only when you are not going to work with the LOB anymore.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Returns `false` if buffering was not enabled or an error occurred.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::getBuffering
- OCILob::setBuffering

# OCILob::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::free — Frees resources associated with the LOB descriptor

### Beschreibung

public function OCILob::free(): bool

Frees resources associated with the descriptor, previously allocated with oci_new_descriptor().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

# OCILob::getBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::getBuffering — Returns current state of buffering for the large object

### Beschreibung

public function OCILob::getBuffering(): bool

Tells whether the buffering for the large object is on or off.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `false` if buffering for the large object is off and `true` if buffering is used.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::setBuffering

# OCILob::import

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::import — Imports file data to the LOB

### Beschreibung

public function OCILob::import(string `$filename`): bool

Writes data from the `filename` in to the current position of large object.

### Parameter-Liste

`filename`

  Path to the file.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::export
- OCILob::write

# OCILob::load

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::load — Returns large object's contents

### Beschreibung

public function OCILob::load(): string|false

Returns large object's contents. As script execution is terminated when the memory_limit is reached, ensure that the LOB does not exceed this limit. In most cases it's recommended to use OCILob::read instead.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the contents of the object, or `false` on errors.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::read

# OCILob::read

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::read — Reads part of the large object

### Beschreibung

public function OCILob::read(int `$length`): string|false

Reads `length` of bytes (BLOB) or characters (CLOB) from the current position of LOB's internal pointer.

Reading stops when `length` of bytes have been read for a BLOB, when `length` of characters have been read for a CLOB, or when the end of the large object is reached. Internal pointer of the large object will be shifted on the amount of bytes/characters read.

### Parameter-Liste

`length`

  The length of data to read, in bytes (BLOB) or characters (CLOB). Large values will be rounded down to 1 MB.

### Rückgabewerte

Returns the contents as a string, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::load
- OCILob::write

# OCILob::rewind

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::rewind — Moves the internal pointer to the beginning of the large object

### Beschreibung

public function OCILob::rewind(): bool

Sets the internal pointer to the beginning of the large object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::seek
- OCILob::tell

# OCILob::save

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::save — Saves data to the large object

### Beschreibung

public function OCILob::save(string `$data`, int `$offset` = 0): bool

Saves `data` to the large object.

### Parameter-Liste

`data`

  The data to be saved.

`offset`

  Can be used to indicate offset from the beginning of the large object.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::write
- OCILob::import

# OCILob::saveFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::saveFile — Alias von OCILob::import()

### Beschreibung

Diese Funktion ist ein Alias für: OCILob::import().

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | Die Klasse OCI-Lob wurde in OCILob umbenannt, um den PHP-Namensstandards zu entsprechen.

# OCILob::seek

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::seek — Sets the internal pointer of the large object

### Beschreibung

public function OCILob::seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool

Sets the internal pointer of the large object.

### Parameter-Liste

`offset`

  Indicates the amount of bytes, on which internal pointer should be moved from the position, pointed by `whence`.

`whence`

  May be one of:

  - `OCI_SEEK_SET` - sets the position equal to `offset`
  - `OCI_SEEK_CUR` - adds `offset` bytes to the current position
  - `OCI_SEEK_END` - adds `offset` bytes to the end of large object (use negative value to move to a position before the end of large object)

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::rewind
- OCILob::tell
- OCILob::eof

# OCILob::setBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::setBuffering — Changes current state of buffering for the large object

### Beschreibung

public function OCILob::setBuffering(bool `$mode`): bool

Sets the buffering for the large object, depending on the value of the `mode` parameter.

Use of this function may provide performance improvements by buffering small reads and writes of LOBs by reducing the number of network round-trips and LOB versions. OCILob::flush() should be used to flush buffers, when you have finished working with the large object.

### Parameter-Liste

`mode`

  `true` for on and `false` for off.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. Repeated calls to this method with the same flag will return `true`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::getBuffering

# OCILob::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::size — Returns size of large object

### Beschreibung

public function OCILob::size(): int|false

Gets the size of the large object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns length of large object value Bei einem Fehler wird `false` zurückgegeben.. Empty objects have zero length.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

# OCILob::tell

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::tell — Returns the current position of internal pointer of large object

### Beschreibung

public function OCILob::tell(): int|false

Gets the current position of a LOB's internal pointer.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns current position of a LOB's internal pointer or `false` if an error occurred.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::rewind
- OCILob::size
- OCILob::eof

# OCILob::truncate

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::truncate — Truncates large object

### Beschreibung

public function OCILob::truncate(int `$length` = 0): bool

Truncates the LOB.

### Parameter-Liste

`length`

  If provided, this method will truncate the LOB to `length` bytes. Otherwise, it will completely purge the LOB.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::erase

# OCILob::write

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::write — Writes data to the large object

### Beschreibung

public function OCILob::write(string `$data`, ?int `$length` = `null`): int|false

Writes data from the parameter `data` into the current position of LOB's internal pointer.

### Parameter-Liste

`data`

  The data to write in the LOB.

`length`

  If this parameter is an integer, writing will stop after `length` bytes have been written or the end of `data` is reached, whichever comes first.

### Rückgabewerte

Returns the number of bytes written Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | `length` is now nullable.
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::read

# OCILob::writeTemporary

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeTemporary — Writes a temporary large object

### Beschreibung

public function OCILob::writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool

Creates a temporary large object and writes `data` to it.

You should use OCILob::close when you are done with this object.

### Parameter-Liste

`data`

  The data to write.

`type`

  Can be one of the following:

  - `OCI_TEMP_BLOB` is used to create temporary BLOBs
  - `OCI_TEMP_CLOB` is used to create temporary CLOBs

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

### Siehe auch

- OCILob::close

# OCILob::writeToFile

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeToFile — Alias von OCILob::export()

### Beschreibung

Diese Funktion ist ein Alias für: OCILob::export().

### Changelog

Version | Beschreibung
--- | ---
8.0.0, PECL OCI8 3.0.0 | `offset` and `length` are now nullable.
8.0.0, PECL OCI8 3.0.0 | The OCI-Lob class was renamed to OCILob to align with PHP naming standards.

## Inhaltsverzeichnis

- OCILob::append — Appends data from the large object to another large object
- OCILob::close — Closes LOB descriptor
- OCILob::eof — Tests for end-of-file on a large object's descriptor
- OCILob::erase — Erases a specified portion of the internal LOB data
- OCILob::export — Exports LOB's contents to a file
- OCILob::flush — Flushes/writes buffer of the LOB to the server
- OCILob::free — Frees resources associated with the LOB descriptor
- OCILob::getBuffering — Returns current state of buffering for the large object
- OCILob::import — Imports file data to the LOB
- OCILob::load — Returns large object's contents
- OCILob::read — Reads part of the large object
- OCILob::rewind — Moves the internal pointer to the beginning of the large object
- OCILob::save — Saves data to the large object
- OCILob::saveFile — Alias von OCILob::import
- OCILob::seek — Sets the internal pointer of the large object
- OCILob::setBuffering — Changes current state of buffering for the large object
- OCILob::size — Returns size of large object
- OCILob::tell — Returns the current position of internal pointer of large object
- OCILob::truncate — Truncates large object
- OCILob::write — Writes data to the large object
- OCILob::writeTemporary — Writes a temporary large object
- OCILob::writeToFile — Alias von OCILob::export

# OCI8 - Veraltete Aliase und Funktionen

# oci_internal_debug

(PHP 5, PHP 7, PECL OCI8 >= 1.1.0, PECL OCI8 <= 2.2.0)

oci_internal_debug — Enables or disables internal debug output

### Beschreibung

function oci_internal_debug(bool `$onoff`): void

Enables or disables internal debug output.

### Parameter-Liste

`onoff`

  Set this to `false` to turn debug output off or `true` to turn it on.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Anmerkungen

> Hinweis:

> This function was removed in PHP 8 and PECL OCI8 3.0.

# ocibindbyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocibindbyname — Alias von oci_bind_by_name()

### Beschreibung

Alias von oci_bind_by_name()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicancel

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicancel — Alias von oci_cancel()

### Beschreibung

Alias von oci_cancel()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicloselob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ocicloselob — Alias von OCILob::close()

### Beschreibung

Alias von OCILob::close()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicollappend

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollappend — Alias von OCICollection::append()

### Beschreibung

Alias von OCICollection::append()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicollassign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 >= 1.0.0)

ocicollassign — Alias von OCICollection::assign()

### Beschreibung

Alias von OCICollection::assign()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicollassignelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollassignelem — Alias von OCICollection::assignElem()

### Beschreibung

Alias von OCICollection::assignElem()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicollgetelem

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollgetelem — Alias von OCICollection::getElem()

### Beschreibung

Alias von OCICollection::getElem()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicollmax

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollmax — Alias von OCICollection::max()

### Beschreibung

Alias von OCICollection::max()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicollsize

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicollsize — Alias von OCICollection::size()

### Beschreibung

Alias von OCICollection::size()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicolltrim

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolltrim — Alias von OCICollection::trim()

### Beschreibung

Alias von OCICollection::trim()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicolumnisnull

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnisnull — Alias von oci_field_is_null()

### Beschreibung

Alias von oci_field_is_null()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicolumnname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnname — Alias von oci_field_name()

### Beschreibung

Alias von oci_field_name()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicolumnprecision

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnprecision — Alias von oci_field_precision()

### Beschreibung

Alias von oci_field_precision()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicolumnscale

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnscale — Alias von oci_field_scale()

### Beschreibung

Alias von oci_field_scale()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicolumnsize

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumnsize — Alias von oci_field_size()

### Beschreibung

Alias von oci_field_size()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicolumntype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntype — Alias von oci_field_type()

### Beschreibung

Alias von oci_field_type()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicolumntyperaw

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicolumntyperaw — Alias von oci_field_type_raw()

### Beschreibung

Alias von oci_field_type_raw()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocicommit

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicommit — Alias von oci_commit()

### Beschreibung

Alias von oci_commit()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocidefinebyname

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocidefinebyname — Alias von oci_define_by_name()

### Beschreibung

Alias von oci_define_by_name()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocierror

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocierror — Alias von oci_error()

### Beschreibung

Alias von oci_error()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ociexecute

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociexecute — Alias von oci_execute()

### Beschreibung

Alias von oci_execute()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocifetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetch — Alias von oci_fetch()

### Beschreibung

Alias von oci_fetch()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocifetchinto

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchinto — Veraltete Variante von oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() und oci_fetch_row()

### Beschreibung

Veraltete Variante von oci_fetch_array(), oci_fetch_object(), oci_fetch_assoc() und oci_fetch_row().

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocifetchstatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetchstatement — Alias von oci_fetch_all()

### Beschreibung

Alias von oci_fetch_all()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocifreecollection

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecollection — Alias von OCICollection::free()

### Beschreibung

Alias von OCICollection::free()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocifreecursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreecursor — Alias von oci_free_statement()

### Beschreibung

Alias von oci_free_statement()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocifreedesc

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreedesc — Alias von OCILob::free()

### Beschreibung

Alias von OCILob::free()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocifreestatement

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreestatement — Alias von oci_free_statement()

### Beschreibung

Alias von oci_free_statement()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ociinternaldebug

(PHP 4, PHP 5, PHP 7, PECL OCI8 >= 1.0.0, PECL OCI8 <= 2.2.0)

ociinternaldebug — Alias von oci_internal_debug()

### Beschreibung

Alias von oci_internal_debug()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ociloadlob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociloadlob — Alias von OCILob::load()

### Beschreibung

Alias von OCILob::load()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocilogoff

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogoff — Alias von oci_close()

### Beschreibung

Alias von oci_close()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocilogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogon — Alias von oci_connect()

### Beschreibung

Alias von oci_connect()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocinewcollection

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcollection — Alias von oci_new_collection()

### Beschreibung

Alias von oci_new_collection()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocinewcursor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewcursor — Alias von oci_new_cursor()

### Beschreibung

Alias von oci_new_cursor()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocinewdescriptor

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinewdescriptor — Alias von oci_new_descriptor()

### Beschreibung

Alias von oci_new_descriptor()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocinlogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinlogon — Alias von oci_new_connect()

### Beschreibung

Alias von oci_new_connect()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocinumcols

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocinumcols — Alias von oci_num_fields()

### Beschreibung

Alias von oci_num_fields()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ociparse

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociparse — Alias von oci_parse()

### Beschreibung

Alias von oci_parse()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ociplogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociplogon — Alias von oci_pconnect()

### Beschreibung

Alias von oci_pconnect()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ociresult

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociresult — Alias von oci_result()

### Beschreibung

Alias von oci_result()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocirollback

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirollback — Alias von oci_rollback()

### Beschreibung

Alias von oci_rollback()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocirowcount

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirowcount — Alias von oci_num_rows()

### Beschreibung

Alias von oci_num_rows()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocisavelob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelob — Alias von OCILob::save()

### Beschreibung

Alias von OCILob::save()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocisavelobfile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelobfile — Alias von OCILob::import()

### Beschreibung

Alias von OCILob::import()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ociserverversion

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociserverversion — Alias von oci_server_version()

### Beschreibung

Alias von oci_server_version()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocisetprefetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisetprefetch — Alias von oci_set_prefetch()

### Beschreibung

Alias von oci_set_prefetch()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ocistatementtype

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocistatementtype — Alias von oci_statement_type()

### Beschreibung

Alias von oci_statement_type()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ociwritelobtofile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociwritelobtofile — Alias von OCILob::export()

### Beschreibung

Alias von OCILob::export()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

# ociwritetemporarylob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ociwritetemporarylob — Alias von OCILob::writeTemporary()

### Beschreibung

Alias von OCILob::writeTemporary()

Warnung

Dieser Alias wurde mit PHP 5.4.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Aliases wird dringend abgeraten.

## Inhaltsverzeichnis

- oci_internal_debug — Enables or disables internal debug output
- ocibindbyname — Alias von oci_bind_by_name
- ocicancel — Alias von oci_cancel
- ocicloselob — Alias von OCILob::close
- ocicollappend — Alias von OCICollection::append
- ocicollassign — Alias von OCICollection::assign
- ocicollassignelem — Alias von OCICollection::assignElem
- ocicollgetelem — Alias von OCICollection::getElem
- ocicollmax — Alias von OCICollection::max
- ocicollsize — Alias von OCICollection::size
- ocicolltrim — Alias von OCICollection::trim
- ocicolumnisnull — Alias von oci_field_is_null
- ocicolumnname — Alias von oci_field_name
- ocicolumnprecision — Alias von oci_field_precision
- ocicolumnscale — Alias von oci_field_scale
- ocicolumnsize — Alias von oci_field_size
- ocicolumntype — Alias von oci_field_type
- ocicolumntyperaw — Alias von oci_field_type_raw
- ocicommit — Alias von oci_commit
- ocidefinebyname — Alias von oci_define_by_name
- ocierror — Alias von oci_error
- ociexecute — Alias von oci_execute
- ocifetch — Alias von oci_fetch
- ocifetchinto — Veraltete Variante von oci_fetch_array, oci_fetch_object, oci_fetch_assoc und oci_fetch_row
- ocifetchstatement — Alias von oci_fetch_all
- ocifreecollection — Alias von OCICollection::free
- ocifreecursor — Alias von oci_free_statement
- ocifreedesc — Alias von OCILob::free
- ocifreestatement — Alias von oci_free_statement
- ociinternaldebug — Alias von oci_internal_debug
- ociloadlob — Alias von OCILob::load
- ocilogoff — Alias von oci_close
- ocilogon — Alias von oci_connect
- ocinewcollection — Alias von oci_new_collection
- ocinewcursor — Alias von oci_new_cursor
- ocinewdescriptor — Alias von oci_new_descriptor
- ocinlogon — Alias von oci_new_connect
- ocinumcols — Alias von oci_num_fields
- ociparse — Alias von oci_parse
- ociplogon — Alias von oci_pconnect
- ociresult — Alias von oci_result
- ocirollback — Alias von oci_rollback
- ocirowcount — Alias von oci_num_rows
- ocisavelob — Alias von OCILob::save
- ocisavelobfile — Alias von OCILob::import
- ociserverversion — Alias von oci_server_version
- ocisetprefetch — Alias von oci_set_prefetch
- ocistatementtype — Alias von oci_statement_type
- ociwritelobtofile — Alias von OCILob::export
- ociwritetemporarylob — Alias von OCILob::writeTemporary

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Testing
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Beispiele
- OCI8 Connection Handling and Connection Pooling
- OCI8 Fast Application Notification (FAN) Support
- OCI8 Transparent Application Failover (TAF) Support
- OCI8 and DTrace Dynamic Tracing
- Supported Datatypes
- OCI8 Funktionen
  - oci_bind_array_by_name — Bindet ein PHP-Array an einen Oracle-PL/SQL-Arrayparameter
  - oci_bind_by_name — Binds a PHP variable to an Oracle placeholder
  - oci_cancel — Bricht das Lesen eines Zeigers ab
  - oci_client_version — Returns the Oracle client library version
  - oci_close — Schließt eine Oracle-Verbindung
  - oci_commit — Commits the outstanding database transaction
  - oci_connect — Connect to an Oracle database
  - oci_define_by_name — Associates a PHP variable with a column for query fetches
  - oci_error — Liefert den letzten Fehler
  - oci_execute — Executes a statement
  - oci_fetch — Ruft die nächste Zeile einer Abfrage in einen internen Puffer ab
  - oci_fetch_all — Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab
  - oci_fetch_array — Liefert die nächste Zeile einer Abfrage als assoziatives oder numerisches Array
  - oci_fetch_assoc — Liefert die nächste Zeile einer Abfrage als assoziatives Array
  - oci_fetch_object — Liefert die nächste Zeile einer Abfrage als Objekt
  - oci_fetch_row — Liefert die nächste Zeile einer Abfrage als numerisches Array
  - oci_field_is_null — Checks if a field in the currently fetched row is null
  - oci_field_name — Returns the name of a field from the statement
  - oci_field_precision — Tell the precision of a field
  - oci_field_scale — Tell the scale of the field
  - oci_field_size — Returns field's size
  - oci_field_type — Returns a field's data type name
  - oci_field_type_raw — Tell the raw Oracle data type of the field
  - oci_free_descriptor — Frees a descriptor
  - oci_free_statement — Gibt alle verknüpften Ressourcen eines Statements oder Zeigers frei.
  - oci_get_implicit_resultset — Returns the next child statement resource from a parent statement resource that has Oracle Database Implicit Result Sets
  - oci_lob_copy — Copies large object
  - oci_lob_is_equal — Compares two LOB/FILE locators for equality
  - oci_new_collection — Allocates new collection object
  - oci_new_connect — Connect to the Oracle server using a unique connection
  - oci_new_cursor — Allocates and returns a new cursor (statement handle)
  - oci_new_descriptor — Initializes a new empty LOB or FILE descriptor
  - oci_num_fields — Returns the number of result columns in a statement
  - oci_num_rows — Returns number of rows affected during statement execution
  - oci_parse — Prepares an Oracle statement for execution
  - oci_password_change — Changes password of Oracle's user
  - oci_pconnect — Connect to an Oracle database using a persistent connection
  - oci_register_taf_callback — Register a user-defined callback function for Oracle Database TAF
  - oci_result — Returns field's value from the fetched row
  - oci_rollback — Rolls back the outstanding database transaction
  - oci_server_version — Returns the Oracle Database version
  - oci_set_action — Sets the action name
  - oci_set_call_timeout — Sets a millisecond timeout for database calls
  - oci_set_client_identifier — Sets the client identifier
  - oci_set_client_info — Sets the client information
  - oci_set_db_operation — Sets the database operation
  - oci_set_edition — Sets the database edition
  - oci_set_module_name — Sets the module name
  - oci_set_prefetch — Sets number of rows to be prefetched by queries
  - oci_set_prefetch_lob — Sets the amount of data prefetched for each CLOB or BLOB.
  - oci_statement_type — Returns the type of a statement
  - oci_unregister_taf_callback — Unregister a user-defined callback function for Oracle Database TAF
- OCICollection — The OCICollection class
  - OCICollection::append — Hängt ein Element an eine Sammlung
  - OCICollection::assign — Weist einer Sammlung einen Wert aus einer anderen Sammlung zu
  - OCICollection::assignElem — Weist einem Element einer Sammlung einen Wert zu
  - OCICollection::free — Gibt die mit einem Sammelobjekt verknüpften Ressourcen frei
  - OCICollection::getElem — Liefert den Wert eines Elements
  - OCICollection::max — Liefert die maximale Anzahl der Elemente in einer Sammlung
  - OCICollection::size — Liefert die Größe der Sammlung
  - OCICollection::trim — Entfernt Elemente vom Ende einer Sammlung
- OCILob — The OCILob class
  - OCILob::append — Appends data from the large object to another large object
  - OCILob::close — Closes LOB descriptor
  - OCILob::eof — Tests for end-of-file on a large object's descriptor
  - OCILob::erase — Erases a specified portion of the internal LOB data
  - OCILob::export — Exports LOB's contents to a file
  - OCILob::flush — Flushes/writes buffer of the LOB to the server
  - OCILob::free — Frees resources associated with the LOB descriptor
  - OCILob::getBuffering — Returns current state of buffering for the large object
  - OCILob::import — Imports file data to the LOB
  - OCILob::load — Returns large object's contents
  - OCILob::read — Reads part of the large object
  - OCILob::rewind — Moves the internal pointer to the beginning of the large object
  - OCILob::save — Saves data to the large object
  - OCILob::saveFile — Alias von OCILob::import
  - OCILob::seek — Sets the internal pointer of the large object
  - OCILob::setBuffering — Changes current state of buffering for the large object
  - OCILob::size — Returns size of large object
  - OCILob::tell — Returns the current position of internal pointer of large object
  - OCILob::truncate — Truncates large object
  - OCILob::write — Writes data to the large object
  - OCILob::writeTemporary — Writes a temporary large object
  - OCILob::writeToFile — Alias von OCILob::export
- OCI8 - Veraltete Aliase und Funktionen
  - oci_internal_debug — Enables or disables internal debug output
  - ocibindbyname — Alias von oci_bind_by_name
  - ocicancel — Alias von oci_cancel
  - ocicloselob — Alias von OCILob::close
  - ocicollappend — Alias von OCICollection::append
  - ocicollassign — Alias von OCICollection::assign
  - ocicollassignelem — Alias von OCICollection::assignElem
  - ocicollgetelem — Alias von OCICollection::getElem
  - ocicollmax — Alias von OCICollection::max
  - ocicollsize — Alias von OCICollection::size
  - ocicolltrim — Alias von OCICollection::trim
  - ocicolumnisnull — Alias von oci_field_is_null
  - ocicolumnname — Alias von oci_field_name
  - ocicolumnprecision — Alias von oci_field_precision
  - ocicolumnscale — Alias von oci_field_scale
  - ocicolumnsize — Alias von oci_field_size
  - ocicolumntype — Alias von oci_field_type
  - ocicolumntyperaw — Alias von oci_field_type_raw
  - ocicommit — Alias von oci_commit
  - ocidefinebyname — Alias von oci_define_by_name
  - ocierror — Alias von oci_error
  - ociexecute — Alias von oci_execute
  - ocifetch — Alias von oci_fetch
  - ocifetchinto — Veraltete Variante von oci_fetch_array, oci_fetch_object, oci_fetch_assoc und oci_fetch_row
  - ocifetchstatement — Alias von oci_fetch_all
  - ocifreecollection — Alias von OCICollection::free
  - ocifreecursor — Alias von oci_free_statement
  - ocifreedesc — Alias von OCILob::free
  - ocifreestatement — Alias von oci_free_statement
  - ociinternaldebug — Alias von oci_internal_debug
  - ociloadlob — Alias von OCILob::load
  - ocilogoff — Alias von oci_close
  - ocilogon — Alias von oci_connect
  - ocinewcollection — Alias von oci_new_collection
  - ocinewcursor — Alias von oci_new_cursor
  - ocinewdescriptor — Alias von oci_new_descriptor
  - ocinlogon — Alias von oci_new_connect
  - ocinumcols — Alias von oci_num_fields
  - ociparse — Alias von oci_parse
  - ociplogon — Alias von oci_pconnect
  - ociresult — Alias von oci_result
  - ocirollback — Alias von oci_rollback
  - ocirowcount — Alias von oci_num_rows
  - ocisavelob — Alias von OCILob::save
  - ocisavelobfile — Alias von OCILob::import
  - ociserverversion — Alias von oci_server_version
  - ocisetprefetch — Alias von oci_set_prefetch
  - ocistatementtype — Alias von oci_statement_type
  - ociwritelobtofile — Alias von OCILob::export
  - ociwritetemporarylob — Alias von OCILob::writeTemporary

# PostgreSQL

# Einführung

PostgreSQL ist ein kostenloses Open-Source-Datenbanksystem. Es wurde ursprünglich im UC Berkeley Computer Science Department entwickelt und hat Pionierarbeit bei objektrelationalen Datenbankkonzepten geleistet, die jetzt Einzug in einige kommerzielle Datenbanken halten. PostgreSQL bietet SQL92/SQL99 Sprachunterstützung, Transaktionen, referentielle Integrität, benutzerdefinierte Funktionen und ein erweiterbares Typkonzept. PostgreSQL ist eine Weiterentwicklung des ursprünglichen Berkeley-Codes.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

Um PostgreSQL benutzen zu können, brauchen Sie mindestens eine Version 6.5 oder neuer. Um alle Leistungsmerkmale des PostgreSQL-Moduls nutzen zu können, müssen Sie eine Version ab 8.0 haben. PostgreSQL unterstützt viele Zeichenkodierungen, einschließlich Multibyte-Character-Encoding. Die aktuelle Version sowie weitere Informationen über PostgreSQL sind auf den Seiten » http://www.postgresql.org/ erhältlich und die ausführliche Dokumentation finden Sie unter » PostgreSQL-Documentation.

## Installation

Um die PostgreSQL-Unterstützung zu aktivieren, müssen Sie PHP mit der Option --with-pgsql[=DIR] kompilieren. `DIR` ist das Basis-Installationsverzeichnis von PostgreSQL, normalerweise /usr/local/pgsql. Falls das shared-object-Modul verfügbar ist, kann PostgreSQL mit der extension-Directive in der php.ini oder der Funktion dl() geladen werden.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

PostgreSQL-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
pgsql.allow_persistent | "1" | `INI_SYSTEM` |
pgsql.max_persistent | "-1" | `INI_SYSTEM` |
pgsql.max_links | "-1" | `INI_SYSTEM` |
pgsql.auto_reset_persistent | "0" | `INI_SYSTEM` |
pgsql.ignore_notice | "0" | `INI_ALL` |
pgsql.log_notice | "0" | `INI_ALL` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`pgsql.allow_persistent` bool

  Bestimmt, ob persistente PostgreSQL-Verbindungen zulässig sind.

`pgsql.max_persistent` int

  Legt die maximale Anzahl persistenter PostgreSQL-Verbindungen pro Prozess fest.

`pgsql.max_links` int

  Legt die maximale Anzahl aller PostgreSQL-Verbindungen, einschließlich der persistenten Verbindungen, pro Prozess fest.

`pgsql.auto_reset_persistent` int

  Findet ungültige persistente Verbindungen, die mit der Funktion pg_pconnect() geöffnet wurden. Erfordert ein wenig Mehraufwand.

`pgsql.ignore_notice` int

  Bestimmt, ob Notice-Meldungen vom PostgreSQL-Server ignoriert werden sollen.

`pgsql.log_notice` int

  Bestimmt, ob Notice-Meldungen vom PostgreSQL-Server protokolliert werden sollen. Die PHP-Direktive pgsql.ignore_notice muss deaktiviert sein, um die Meldungen zu protokollieren.

## Ressource-Typen

Vor PHP 8.1.0 wurden im PostgreSQL-Modul zwei Ressource-Typen verwendet: Der erste ist die Verbindungskennung für Datenbankverbindungen, die zweite Ressource ist die Ergebniskennung, die auf ein Abfrageergebnis verweist.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`PGSQL_LIBPQ_VERSION` (string)
  Kurze libpq-Version, die nur Zahlen und Punkte enthält.
`PGSQL_LIBPQ_VERSION_STR` (string)
  Vor PHP 8.0.0 die lange libpq-Version, die Compiler-Informationen enthält. Ab PHP 8.0.0 ist der Wert identisch mit `PGSQL_LIBPQ_VERSION` und die Verwendung von `PGSQL_LIBPQ_VERSION_STR` ist veraltet.
`PGSQL_ASSOC` (int)
  Wird an die Funktion pg_fetch_array() übergeben. Gibt ein assoziatives Array zurück, mit den Feldnamen als Indizes und den entsprechenden Werten.
`PGSQL_NUM` (int)
  Wird an die Funktion pg_fetch_array() übergeben. Gibt ein numerisches Array zurück, mit den Feldnummern als Indizes und den entsprechenden Werten.
`PGSQL_BOTH` (int)
  Wird an die Funktion pg_fetch_array() übergeben. Gibt ein Array zurück, das sowohl assoziativ (mit den Feldnamen) als auch numerisch (mit den Feldnummern) indiziert ist, und den entsprechenden Werten.
`PGSQL_CONNECT_FORCE_NEW` (int)
  Wird an die Funktion pg_connect() übergeben, um eine neue Verbindung zu erzwingen, anstatt eine identische, bereits geöffnete Verbindung wieder zu benutzen.
`PGSQL_CONNECT_ASYNC` (int)
  Wird an pg_connect() übergeben, um eine asynchrone Verbindung zu erzeugen.
`PGSQL_CONNECTION_AUTH_OK` (int)
`PGSQL_CONNECTION_AWAITING_RESPONSE` (int)
`PGSQL_CONNECTION_BAD` (int)
  Wird von der Funktion pg_connection_status() zurückgegeben und zeigt an, dass der Status der Datenbankverbindung ungültig ist.
`PGSQL_CONNECTION_MADE` (int)
`PGSQL_CONNECTION_OK` (int)
  Wird von der Funktion pg_connection_status() zurückgegeben und zeigt an, dass der Status der Datenbankverbindung gültig ist.
`PGSQL_CONNECTION_SETENV` (int)
`PGSQL_CONNECTION_SSL_STARTUP` (int)
`PGSQL_CONNECTION_STARTED` (int)
`PGSQL_SEEK_SET` (int)
  Wird an die Funktion pg_lo_seek() übergeben. Das Objekt wird von Beginn an durchsucht.
`PGSQL_SEEK_CUR` (int)
  Wird an die Funktion pg_lo_seek() übergeben. Das Objekt wird ab der aktuellen Position durchsucht.
`PGSQL_SEEK_END` (int)
  Wird an die Funktion pg_lo_seek() übergeben. Das Objekt wird ausgehend vom Ende durchsucht.
`PGSQL_EMPTY_QUERY` (int)
  Wird von der Funktion pg_result_status() zurückgegeben, wenn der an den Server gesendete String leer war.
`PGSQL_COMMAND_OK` (int)
  Wird von der Funktion pg_result_status() zurückgegeben. Ein Kommando wurde erfolgreich ausgeführt, aber es wurden keine Daten zurückgegeben.
`PGSQL_TUPLES_OK` (int)
  Wird von der Funktion pg_result_status() zurückgegeben. Ein Kommando wurde erfolgreich ausgeführt und es wurden Daten (wie etwa ein `SELECT` oder `SHOW`) zurückgegeben.
`PGSQL_TUPLES_CHUNK` (int)
  Wird von der Funktion pg_result_status() zurückgegeben. Zeigt den erfolgreichen Abschluss eines Befehls an, der Daten im Blockmodus (Chunked Mode) zurückgibt. Wird für `SELECT`-Befehle zurückgegeben, wenn pg_set_chunked_rows_size() gesetzt ist. Die Ergebnismenge wird in mehrere Blöcke aufgeteilt, die jeweils eine vordefinierte Anzahl von Zeilen enthalten. Verfügbar seit PHP 8.4.0 und libpq 17.
`PGSQL_COPY_OUT` (int)
  Wird von der Funktion pg_result_status() zurückgegeben. Ein Datentransfer vom Server wurde gestartet.
`PGSQL_COPY_IN` (int)
  Wird von der Funktion pg_result_status() zurückgegeben. Ein Datentransfer zum Server wurde gestartet.
`PGSQL_BAD_RESPONSE` (int)
  Wird von der Funktion pg_result_status() zurückgegeben. Die Serverantwort wurde nicht verstanden.
`PGSQL_NONFATAL_ERROR` (int)
  Wird von der Funktion pg_result_status() zurückgegeben. Ein nicht-fataler Fehler (eine Notiz oder Warnung) ist aufgetreten.
`PGSQL_FATAL_ERROR` (int)
  Wird von der Funktion pg_result_status() zurückgegeben. Ein fataler Fehler ist aufgetreten.
`PGSQL_TRANSACTION_IDLE` (int)
  Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung wird momentan nicht benutzt, es findet aktuell keine Transaktion statt.
`PGSQL_TRANSACTION_ACTIVE` (int)
  Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung wird momentan benutzt. Es wird eine Abfrage ausgeführt, die noch nicht beendet ist.
`PGSQL_TRANSACTION_INTRANS` (int)
  Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung wird von einer Transaktion benutzt, ist aber momentan nicht aktiv.
`PGSQL_TRANSACTION_INERROR` (int)
  Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung wurde von einer abgebrochenen Transaktion benutzt und ist momentan nicht aktiv.
`PGSQL_TRANSACTION_UNKNOWN` (int)
  Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung ist ungültig.
`PGSQL_DIAG_SEVERITY` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Gibt den Schweregrad des Fehlers zurück. Die Feldinhalte sind `ERROR`, `FATAL` oder `PANIC` (in einer Fehlermeldung) oder `WARNING`, `NOTICE`, `DEBUG`, `INFO` oder `LOG` (in einer Notice-Meldung) oder eine lokalisierte Übersetzung davon. Dieses Feld ist immer verfügbar.
`PGSQL_DIAG_SQLSTATE` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Gibt den SQLSTATE-Code des Fehlers zurück. Der SQLSTATE-Code identifiziert den Typ des aufgetretenen Fehlers. Dieser kann von Anwendungen ausgewertet werden, um entsprechende Operationen auszuführen (beispielsweise Fehlerbehandlungsroutinen), als Reaktion auf einen bestimmten Datenbankfehler. dieses Feld kann nicht lokalisiert werden und ist immer verfügbar.
`PGSQL_DIAG_MESSAGE_PRIMARY` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Dies ist die primäre, für Menschen lesbare Fehlermeldung (normalerweise in einer Zeile) und ist immer verfügbar.
`PGSQL_DIAG_MESSAGE_DETAIL` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Detail: eine optionale untergeordnete Fehlermeldung, in der das Problem genauer beschrieben wird. Diese Meldung kann mehrere Zeilen lang sein.
`PGSQL_DIAG_MESSAGE_HINT` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Hint: ein optionaler Hinweis, wie mit dem Problem umzugehen ist. Dies wurde eingeführt, um (möglicherweise unpassende) Lösungen zur Verfügung zu stellen, anstatt harte Fakten, wie bei Details. Diese Meldung kann mehrere Zeilen lang sein.
`PGSQL_DIAG_STATEMENT_POSITION` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Dies ist ein String, der eine dezimale Integerzahl enthält, die die Cursorposition des originalen SQL-Strings angibt, an der ein Fehler auftrat. Das erste Zeichen hat die Position 1 und zur Bestimmung der Positionen werden Zeichen zugrundegelegt und nicht Bytes.
`PGSQL_DIAG_INTERNAL_POSITION` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Per Definition ist das dasselbe wie das Feld `PG_DIAG_STATEMENT_POSITION`, es wird aber benutzt, wenn die Cursorposition auf ein intern generiertes Kommando verweist und nicht auf eines, das vom Benutzer eingegeben wurde. Das Feld `PG_DIAG_INTERNAL_QUERY` wird immer gesetzt, wenn dieses Feld gesetzt ist.
`PGSQL_DIAG_INTERNAL_QUERY` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Dies ist der Text eines fehlgeschlagenen, intern generierten Kommandos. Das kann beispielsweise eine SQL-Abfrage sein, die von einer PL/pgSQL-Funktion gesendet wurde.
`PGSQL_DIAG_CONTEXT` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Dies gibt einen Hinweis auf den Kontext, in dem ein Fehler auftrat. Gegenwärtig sind Zurückverfolgungen des Aufrufstacks von Funktionen aktivierter prozeduraler Sprachen darin enthalten, sowie intern generierte Abfragen. Die Ablaufverfolgung enthält einen Eintrag pro Zeile, die neuesten Einträge zuerst.
`PGSQL_DIAG_SOURCE_FILE` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Dies ist der Name der Datei im PostgreSQL-Quellcode, bei der der Fehler gemeldet wurde.
`PGSQL_DIAG_SOURCE_LINE` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Die Zeilennummer in der Datei im PostgreSQL-Quellcode, bei der der Fehler gemeldet wurde.
`PGSQL_DIAG_SOURCE_FUNCTION` (int)
  Wird an die Funktion pg_result_error_field() übergeben. Der Name der Funktion im PostgreSQL-Quellcode, bei der der Fehler gemeldet wurde.
`PGSQL_DIAG_SCHEMA_NAME` (int)
  Verfügbar seit PHP 7.3.0.
`PGSQL_DIAG_TABLE_NAME` (int)
  Verfügbar seit PHP 7.3.0.
`PGSQL_DIAG_COLUMN_NAME` (int)
  Verfügbar seit PHP 7.3.0.
`PGSQL_DIAG_DATATYPE_NAME` (int)
  Verfügbar seit PHP 7.3.0.
`PGSQL_DIAG_CONSTRAINT_NAME` (int)
  Verfügbar seit PHP 7.3.0.
`PGSQL_ERRORS_TERSE` (int)
  Wird an die Funktion pg_set_error_verbosity() übergeben. Damit wird festgelegt, dass Fehlermeldungen die Felder severity, primary text und position enthalten. Normalerweise passt das alles in eine Zeile.
`PGSQL_ERRORS_DEFAULT` (int)
  Wird an die Funktion pg_set_error_verbosity() übergeben. Die Standardeinstellung gibt Meldungen mit den oben beschriebenen Inhalten zurück, zuzüglich aller Details, Hinweise und Kontext-Informationen (dies kann mehrere Zeilen umfassen).
`PGSQL_ERRORS_VERBOSE` (int)
  Wird an die Funktion pg_set_error_verbosity() übergeben. In diesem Modus werden alle verfügbaren Felder zurückgegeben.
`PGSQL_ERRORS_SQLSTATE` (int)
  Wird an die Funktion pg_set_error_verbosity(). übergeben. Enthält nur den Schweregrad des Fehlers und den `SQLSTATE`-Fehlercode. Wenn kein Fehlercode verfügbar ist, entspricht die Ausgabe der im Modus `PGSQL_ERRORS_TERSE`. Vor PostgreSQL 11.1 ist die Ausgabe immer dieselbe wie im Modus `PGSQL_ERRORS_TERSE`.
`PGSQL_NOTICE_LAST` (int)
  Verwendet von pg_last_notice(). Verfügbar seit PHP 7.1.0.
`PGSQL_NOTICE_ALL` (int)
  Verwendet von pg_last_notice(). Verfügbar seit PHP 7.1.0.
`PGSQL_NOTICE_CLEAR` (int)
  Verwendet von pg_last_notice(). Verfügbar seit PHP 7.1.0.
`PGSQL_STATUS_LONG` (int)
  Wird an die Funktion pg_result_status() übergeben. Zeigt an, dass ein numerischer Ergebniscode gewünscht ist.
`PGSQL_STATUS_STRING` (int)
  Wird an die Funktion pg_result_status() übergeben. Zeigt an, dass eine textuelles Ergebnis gewünscht ist.
`PGSQL_CONV_IGNORE_DEFAULT` (int)
  Wird an die Funktion pg_convert() übergeben. Während der Konversion werden Standardwerte in der Tabelle ignoriert.
`PGSQL_CONV_FORCE_NULL` (int)
  Wird an die Funktion pg_convert() übergeben. Anstelle eines leeren Strings string wird der SQL-Nullwert `NULL` benutzt.
`PGSQL_CONV_IGNORE_NOT_NULL` (int)
  Wird an die Funktion pg_convert() übergeben. Die Konversion von `null` in SQL `NOT NULL`-Spalten wird ignoriert.
`PGSQL_DML_NO_CONV` (int)
  Wird an pg_insert(), pg_select(), pg_update() und pg_delete() übergeben. Alle Parameter werden übergeben wie sie sind. Manuelles Maskieren ist erforderlich, wenn Parameter Anwenderdaten enthalten. Dafür ist pg_escape_string() zu verwenden.
`PGSQL_DML_EXEC` (int)
  Wird an pg_insert(), pg_select(), pg_update() und pg_delete() übergeben. Führt eine Abfrage durch diese Funktionen aus.
`PGSQL_DML_ASYNC` (int)
  Wird an pg_insert(), pg_select(), pg_update() und pg_delete() übergeben. Führt eine asynchrone Abfrage durch diese Funktionen aus.
`PGSQL_DML_STRING` (int)
  Wird an pg_insert(), pg_select(), pg_update() und pg_delete() übergeben. Gibt den ausgeführten Abfragestring zurück.
`PGSQL_DML_ESCAPE` (int)
  Wird an pg_insert(), pg_select(), pg_update() und pg_delete() übergeben. Maskiert alle Parameter anstatt pg_convert() intern aufzurufen. Diese Option verzichtet auf das Nachschlagen von Meta-Daten. Die Abfrage kann so schnell sein wie pg_query() und pg_send_query().
`PGSQL_POLLING_FAILED` (int)
  Wird von pg_connect_poll() zurückgegeben, um anzuzeigen, dass der Verbindungsversuch fehlschlug.
`PGSQL_POLLING_READING` (int)
  Wird von pg_connect_poll() zurückgegeben, um anzuzeigen, dass die Verbindung auf Lesebereitschaft des PostgreSQL-Socket wartet.
`PGSQL_POLLING_WRITING` (int)
  Wird von pg_connect_poll() zurückgegeben, um anzuzeigen, dass die Verbindung auf Schreibbereitschaft des PostgreSQL-Socket wartet.
`PGSQL_POLLING_OK` (int)
  Wird von pg_connect_poll() zurückgegeben, um anzuzeigen, dass die Verbindung bereit zur Verwendung ist.
`PGSQL_POLLING_ACTIVE` (int)
  Wird von pg_connect_poll() zurückgegeben, um anzuzeigen, dass die Verbindung zur Zeit aktiv ist.
`PGSQL_DIAG_SEVERITY_NONLOCALIZED` (int)
  Der Schweregrad. Das Feld enthält ERROR, FATAL oder PANIC (in einer Fehlermeldung), oder WARNING, NOTICE, DEBUG, INFO oder LOG (in einer Hinweismeldung). Dies ist identisch zum PG_DIAG_SEVERITY Feld, außer dass der Inhalt nie lokalisiert ist. Es ist nur ab Version 9.6 vorhanden.
`PGSQL_SHOW_CONTEXT_NEVER` (int)
  Wird in pg_set_error_context_visibility() verwendet, damit der Kontext nie angezeigt wird. Verfügbar seit PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ERRORS` (int)
  Wird in pg_set_error_context_visibility() verwendet, damit die Felder des Kontexts nur in Fehlermeldungen enthalten sind. Dies ist das standardmäßige Verhalten. Verfügbar seit PHP 8.3.0.
`PGSQL_SHOW_CONTEXT_ALWAYS` (int)
  Wird in pg_set_error_context_visibility() verwendet, damit die Felder des Kontexts in Fehler-, Hinweis- und Warnmeldungen enthalten sind. Verfügbar seit PHP 8.3.0.
`PGSQL_TRACE_SUPPRESS_TIMESTAMPS` (int)
  Wird in pg_trace() verwendet, damit der Zeitstempel nicht in den Meldungen der Ablaufverfolgung enthalten ist. Verfügbar seit PHP 8.4.20.
`PGSQL_TRACE_REGRESS_MODE` (int)
  Wird in pg_trace() verwendet, damit solche Felder wie OIDs in die Meldungen der Ablaufverfolgung aufgenommen werden. Verfügbar seit PHP 8.3.0.

# Beispiele

## Inhaltsverzeichnis

- Grundlegende Nutzung
- Grundlegende Verwendung

## Grundlegende Nutzung

Dieses einfache Beispiel zeigt den Verbindungsaufbau, die Ausführung einer einfachen Abfrage, die Ausgabe der Abfrageergebnisse und, wie eine Verbindung wieder geschlossen wird.

Beispiel #1 Beispiel für die Benutzung der PostgreSQL-Erweiterung

    <?php

    // Verbindungsaufbau und Auswahl der Datenbank
    $dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
        or die('Verbindungsaufbau fehlgeschlagen: ' . pg_last_error());

    // Eine SQL-Abfrage ausführen
    $query = 'SELECT * FROM authors';
    $result = pg_query($dbconn, $query) or die('Abfrage fehlgeschlagen: ' . pg_last_error());

    // Ergebnisse in HTML ausgeben
    echo "<table>\n";
    while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
        echo "\t<tr>\n";
        foreach ($line as $col_value) {
            echo "\t\t<td>$col_value</td>\n";
        }
        echo "\t</tr>\n";
    }
    echo "</table>\n";

    // Speicher freigeben
    pg_free_result($result);

    // Verbindung schließen
    pg_close($dbconn);

    ?>

## Grundlegende Verwendung

Diese Beispiele enthalten benutzerdefinierte Funktion, ähnlich veralteten MySQL-Funktionen.

Beispiel #1 benutzerdefinierte PostgreSQL Funktionen Beispiel

    <?php
    // Diese Funktion sollte benötigt werden, da PostgreSQL-Verbindung die Datenbank anbinden.
    function pg_list_dbs($db)
    {
        assert(is_resource($db));
        $query = '
    SELECT
     d.datname as "Name",
     u.usename as "Owner",
     pg_encoding_to_char(d.encoding) as "Encoding"
    FROM
     pg_database d LEFT JOIN pg_user u ON d.datdba = u.usesysid
    ORDER BY 1;
    ';
        return pg_query($db, $query);
    }

    // Tabellen auflisten.
    function pg_list_tables($db)
    {
        assert(is_resource($db));
        $query = "
    SELECT
     c.relname as \"Name\",
     CASE c.relkind WHEN 'r' THEN 'table' WHEN 'v' THEN 'view' WHEN 'i' THEN 'index' WHEN 'S' THEN 'sequence' WHEN 's' THEN 'special' END as \"Type\",
      u.usename as \"Owner\"
    FROM
     pg_class c LEFT JOIN pg_user u ON c.relowner = u.usesysid
    WHERE
     c.relkind IN ('r','v','S','')
     AND c.relname !~ '^pg_'
    ORDER BY 1;
    ";
        return pg_query($db, $query);
    }

    // Siehe auch pg_meta_data(). Felddefinitionen werden als Array zurückgegeben.
    function pg_list_fields($db, $table)
    {
        assert(is_resource($db));
        $query = "
    SELECT
     a.attname,
     format_type(a.atttypid, a.atttypmod),
     a.attnotnull,
     a.atthasdef,
     a.attnum
    FROM
     pg_class c,
     pg_attribute a
    WHERE
     c.relname = '".$table."'
     AND a.attnum > 0 AND a.attrelid = c.oid
    ORDER BY a.attnum;
    ";
        return pg_query($db, $query);
    }
    ?>

# PostgreSQL-Funktionen

## Anmerkungen

> Hinweis:

> Nicht alle Funktionen sind in allen Versionen verfügbar. Es hängt davon ab, welche libpq-Version (die PostgreSQL-C-Client-Bibliothek) auf Ihrem Rechner verfügbar ist und wie libpq kompiliert wurde. Falls eine Funktion nicht verfügbar ist, liegt es daran, dass libpq die nötigen Routinen nicht unterstützt, die diese Funktion braucht.

> Hinweis:

> Die meisten PostgreSQL-Funktionen nehmen den Parameter `connection` als optionalen ersten Parameter entgegen. Falls er nicht angegeben wurde, wird die zuletzt geöffnete Verbindung benutzt. Wenn keine geöffnete Verbindung existiert, geben die Funktionen `false` zurück.

> Hinweis:

> PostgreSQL wandelt automatisch alle Bezeichner (beispielsweise Tabellen- oder Spaltennamen) in Kleinbuchstaben um, und zwar sowohl bei der Erzeugung der Objekte als auch in Abfragen. Um Namen in Groß- und Kleinschreibung oder in Großbuchstaben zu erzwingen, müssen diese in doppelte Anführungszeichen ("") eingeschlossen werden.

> Hinweis:

> PostgreSQL stellt keine speziellen Kommandos zur Verfügung, um Informationen über ein Datenbank-Schema (z. B. alle Tabellen in der aktuellen Datenbank) zu erhalten. Stattdessen gibt es ein Standard-Schema namens `information_schema`, in dem alle notwendigen Informationen in System-Views enthalten und die einfach abzufragen sind. Ausführliche Informationen darüber gibt es in der » PostgreSQL-Dokumentation.

# pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_affected_rows — Gibt die Anzahl betroffener Datensätze (Tupel) zurück

### Beschreibung

function pg_affected_rows(PgSql\Result `$result`): int

pg_affected_rows() gibt die Anzahl der Tupels (Instanzen/Datensätze/Zeilen) zurück, die von einer ausgeführten `INSERT`-, `UPDATE`- oder `DELETE`-Abfrage betroffen sind.

Der Server gibt auch die Anzahl der SELECTierten Zeilen zurück.

> Hinweis:

> Diese Funktion hieß vormals pg_cmdtuples().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

### Rückgabewerte

Die Anzahl der Zeilen, die von der Abfrage betroffen wurden. Wurde keine Zeile betroffen, wird `0` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_affected_rows()-Beispiel

    <?php
    $result = pg_query($conn, "INSERT INTO authors VALUES ('Orwell', 2002, 'Animal Farm')");

    $cmdtuples = pg_affected_rows($result);

    echo $cmdtuples . " Zeile(n) wurden betroffen.\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1 Zeile(n) wurden betroffen.

### Siehe auch

- pg_query() - Führt eine Abfrage aus
- pg_query_params() - Sendet ein Kommando zum Server und wartet seine Ausführung ab. Getrennt vom SQL-Kommando können dabei Parameter übergeben werden
- pg_execute() - Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis
- pg_num_rows() - Gibt die Anzahl der Zeilen in einem Abfrageergebnis zurück

# pg_cancel_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_cancel_query — Löscht eine asynchrone Abfrage

### Beschreibung

function pg_cancel_query(PgSql\Connection `$connection`): bool

pg_cancel_query() löscht eine asynchrone Abfrage, die mit pg_send_query(), pg_send_query_params() oder pg_send_execute() an den Datenbankserver gesendet wurde. Eine Abfrage, die mit pg_query() gesendet wurde, kann nicht gelöscht werden.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_cancel_query() Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Keine Verbindung möglich");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Erster Aufruf von pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 hat $rows1 Zeilen.\n\n";

      // Die aktuell ausgeführte Abfrage löschen. Falls die
      // erste Abfrage abgeschlossen ist, wird die zweite
      // gelöscht,sofern sie noch nicht beendet ist.
      pg_cancel_query($dbconn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Erster Aufruf von pg_get_result(): Resource id #3
    Resource id #3 hat 3 Zeilen.

### Siehe auch

- pg_send_query() - Sendet eine asynchrone Abfrage
- pg_connection_busy() - Gibt den Status der Verbindung zurück (busy/not busy)

# pg_change_password

(PHP 8 >= 8.4.0)

pg_change_password — Change a PostgreSQL user's password

### Beschreibung

function pg_change_password(PgSql\Connection `$connection`, string `$user`, string `$password`): bool

pg_change_password() changes the password of a PostgreSQL user. This function uses the `PQchangePassword` libpq function which handles password encryption automatically based on the server's settings.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`user`
  The name of the PostgreSQL user whose password to change.
`password`
  The new password.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- pg_connect() - Öffnet eine PostgreSQL-Verbindung

# pg_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_client_encoding — Liefert die Kodierung des Clients

### Beschreibung

function pg_client_encoding(?PgSql\Connection `$connection` = `null`): string

PostgreSQL unterstützt die automatische Konvertierung von Zeichensätzen zwischen Server und Client für bestimmte Zeichensätze. pg_client_encoding() gibt die Kodierung des Clients in einem String zurück, der den Namen einer PostgreSQL-Standardkodierung enthält.

> Hinweis:

> Wenn die libpq ohne multibyte-Unterstützung kompiliert wurde, gibt pg_client_encoding() immer `SQL_ASCII` zurück. Die unterstützten Kodierungen sind von der PostgreSQL-Version abhängig. Weitere Informationen entnehmen Sie bitte der PostgreSQL-Dokumentation.

> Diese Funktion ersetzt die Funktion pg_clientencoding().

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Die Kodierung des Clients.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_client_encoding()-Beispiel

    <?php
    // Angenommen, $conn sei eine Verbindung zu einer ISO-8859-1 Datenbank
    $encoding = pg_client_encoding($conn);

    echo "Der Client benutzt die Kodierung: ", $encoding, "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Der Client benutzt die Kodierung: ISO-8859-1

### Siehe auch

- pg_set_client_encoding() - Setzt die Kodierung des Clients

# pg_close

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_close — Schließt eine PostgreSQL-Verbindung

### Beschreibung

function pg_close(?PgSql\Connection `$connection` = `null`): true

pg_close() schließt die nicht-persistente Verbindung, die durch die `connection`-Instanz bezeichnet wird.

> Hinweis:

> Die Verwendung von pg_close() ist normalerweise nicht notwendig, da geöffnete, nicht-persistente Verbindungen automatisch geschlossen werden, wenn das Skript beendet wird.

Falls es auf dieser Verbindung geöffnete PgSql\Lob-Instanzen gibt, sollten alle PgSql\Lob-Instanzen geschlossen werden, bevor die Verbindung geschlossen wird.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Der Rückgabewert ist nun `true` vorher war es bool.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_close()-Beispiel

    <?php
    $dbconn = pg_connect("host=localhost port=5432 dbname=mary")
       or die("Keine Verbindung möglich");
    echo "Verbindung hergestellt";
    pg_close($dbconn);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Verbindung hergestellt

### Siehe auch

- pg_connect() - Öffnet eine PostgreSQL-Verbindung

# pg_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_connect — Öffnet eine PostgreSQL-Verbindung

### Beschreibung

function pg_connect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_connect() öffnet eine Verbindung zu der PostgreSQL-Datenbank, die durch den `connection_string` bezeichnet wird.

Falls ein zweiter Aufruf von pg_connect() mit demselben `connection_string` gemacht wird, wird die Verbindungskennung der bereits geöffneten Verbindung zurückgegeben, es sei denn, Sie übergeben die Konstante `PGSQL_CONNECT_FORCE_NEW` im Parameter `flags`.

Die alte Syntax $conn = pg_connect ("host", "port", "options", "tty", "dbname") sollte nicht mehr benutzt werden.

### Parameter-Liste

`connection_string`

  Der `connection_string` darf leer sein. Dann werden Standard-Parameter benutzt. Er kann auch einen oder mehrere Parameter, durch Leerzeichen getrennt, enthalten. Jeder Parameter muss in der Form `keyword = value` angegeben werden, wobei das Gleichheitszeichen optional ist. Um einen leeren Wert oder einen Wert, der Leerzeichen enthält, zu übergeben, muss dieser in einfache Anführungszeichen eingeschlossen sein, etwa so: `keyword = 'ein Wert'`. Einfache Anführungszeichen oder Backslashes innerhalb von Werten müssen mit einem Backslash maskiert werden: \' und \\.

  Diese Schlüsselwörter für die Parameter werden aktuell erkannt: `host`, `hostaddr`, `port`, `dbname` (standardmäßig der Wert von `user`), `user`, `password`, `connect_timeout`, `options`, `tty` (wird ignoriert), `sslmode`, `requiressl` (zugunsten von `sslmode` ausgemustert) und `service`. Welche dieser Parameter zur Verfügung stehen, ist von Ihrer PostgreSQL-Version abhängig.

  Der Parameter `options` kann verwendet werden, um vom Server auszuführende Kommandozeilenparameter zu setzen.

`flags`

  Wenn `PGSQL_CONNECT_FORCE_NEW` übergeben wird, wird eine neue Verbindung aufgebaut, auch wenn der `connection_string` identisch zu der aktuell geöffneten Verbindung ist.

  Ist `PGSQL_CONNECT_ASYNC` angegeben, dann wird die Verbindung asynchron hergestellt. Der Zustand der Verbindung kann dann per pg_connect_poll() oder pg_connection_status() überprüft werden.

### Rückgabewerte

Bei Erfolg wird eine PgSql\Connection-Instanz zurückgegeben. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PgSql\Connection-Instanz zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 pg_connect() benutzen

    <?php
    // Verbindungsaufbau zu einer Datenbank namens "mary"
    $dbconn = pg_connect("dbname=mary");

    // Verbindungsaufbau zu einer Datenbank namens "mary" auf dem
    // Host "localhost" über den (Standard-)Port "5432"
    $dbconn2 = pg_connect("host=localhost port=5432 dbname=mary");

    // Verbindungsaufbau zu einer Datenbank namens "mary" auf dem Host
    // "sheep" mit dem Benutzernamen "lamb" und dem Passwort "foo"
    $dbconn3 = pg_connect("host=sheep port=5432 dbname=mary user=lamb password=foo");

    // Verbindungsaufbau zu einer Datenbank namens "test" auf dem Host
    // "sheep" mit dem Benutzernamen "lamb" und dem Passwort "bar"
    $conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
    $dbconn4 = pg_connect($conn_string);

    // Verbindungsaufbau zu einer Datenbank auf dem Host "localhost" mit Setzen
    // des Kommandozeilenparameters, der die Zeichenkodierung UTF-8 angibt
    $dbconn5 = pg_connect("host=localhost options='--client_encoding=UTF8'");
    ?>

### Siehe auch

- pg_pconnect() - Öffnet eine persistente PostgreSQL-Verbindung
- pg_close() - Schließt eine PostgreSQL-Verbindung
- pg_host() - Liefert den Namen des Host, zu dem verbunden wurde
- pg_port() - Liefert die Portnummer, über die die Verbindung aufgebaut wurde
- pg_tty() - Liefert den TTY-Namen für die Verbindung
- pg_options() - Liefert die Verbindungsoptionen der aktuellen Verbindung
- pg_dbname() - Liefert den Namen der Datenbank

# pg_connect_poll

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_connect_poll — Poll the status of an in-progress asynchronous PostgreSQL connection attempt

### Beschreibung

function pg_connect_poll(PgSql\Connection `$connection`): int

pg_connect_poll() polls the status of a PostgreSQL connection created by calling pg_connect() with the `PGSQL_CONNECT_ASYNC` option.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

Returns `PGSQL_POLLING_FAILED`, `PGSQL_POLLING_READING`, `PGSQL_POLLING_WRITING`, `PGSQL_POLLING_OK`, or `PGSQL_POLLING_ACTIVE`.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

# pg_connection_busy

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_busy — Gibt den Status der Verbindung zurück (busy/not busy)

### Beschreibung

function pg_connection_busy(PgSql\Connection `$connection`): bool

pg_connection_busy() stellt fest, ob eine Verbindung gerade benutzt wird. Falls ja, wird eine zuvor gesendete Abfrage noch bearbeitet. Falls die Funktion pg_get_result() aufgerufen wird, wird sie blockiert.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

Gibt `true` zurück, falls die Verbindung gerade benutzt wird, ansonsten `false`.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_connection_busy() Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte keine Verbindung aufbauen.");
      $bs = pg_connection_busy($dbconn);
      if ($bs) {
          echo 'Die Verbindung wird gerade benutzt.';
      } else {
         echo 'Die Verbindung ist frei.';
      }
    ?>

### Siehe auch

- pg_connection_status() - Gibt den Verbindungsstatus zurück
- pg_get_result() - Liefert asynchrone Abfrageergebnisse

# pg_connection_reset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_reset — Setzt die Verbindung zurück und verbindet neu

### Beschreibung

function pg_connection_reset(PgSql\Connection `$connection`): bool

pg_connection_reset() setzt die Verbindung zurück. Dies ist nützlich bei der Fehlerbehandlung.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_connection_reset() Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte keine Verbindung aufbauen.");
      $dbconn2 = pg_connection_reset($dbconn);
      if ($dbconn2) {
          echo "Verbindung erfolgreich zurückgesetzt\n";
      } else {
          echo "Konnte die Verbindung nicht zurücksetzen\n";
      }
    ?>

### Siehe auch

- pg_connect() - Öffnet eine PostgreSQL-Verbindung
- pg_pconnect() - Öffnet eine persistente PostgreSQL-Verbindung
- pg_connection_status() - Gibt den Verbindungsstatus zurück

# pg_connection_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_status — Gibt den Verbindungsstatus zurück

### Beschreibung

function pg_connection_status(PgSql\Connection `$connection`): int

pg_connection_status() gibt den Status der angegebenen `connection` zurück.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

`PGSQL_CONNECTION_OK` oder `PGSQL_CONNECTION_BAD`.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_connection_status() Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte keine Verbindung aufbauen");
      $stat = pg_connection_status($dbconn);
      if ($stat === PGSQL_CONNECTION_OK) {
          echo 'Verbindungsstatus ok';
      } else {
          echo 'Verbindungsstatus bad';
      }
    ?>

### Siehe auch

- pg_connection_busy() - Gibt den Status der Verbindung zurück (busy/not busy)

# pg_consume_input

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_consume_input — Reads input on the connection

### Beschreibung

function pg_consume_input(PgSql\Connection `$connection`): bool

pg_consume_input() consumes any input waiting to be read from the database server.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

`true` if no error occurred, or `false` if there was an error. Note that `true` does not necessarily indicate that input was waiting to be read.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

# pg_convert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_convert — Konvertiert die Werte eines assoziativen Arrays in die für SQL-Anweisungen passende Form

### Beschreibung

function pg_convert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = 0
): array|false

pg_convert() prüft und konvertiert die Werte in `values` in passende Werte für ein SQL-Kommando. Voraussetzung für pg_convert() ist die Existenz einer Tabelle `table_name`, die mindestens so viele Spalten hat, wie `values` Elemente. Die Feldnamen in `table_name` müssen mit den Schlüsseln von `values` übereinstimmen und die entsprechenden Datentypen müssen kompatibel sein. Zurückgegeben wird bei Erfolg ein Array mit den konvertierten Werten oder `false`, falls ein Fehler auftrat.

> Hinweis:

> Boolesche Werte werden akzeptiert und zu booleschen PostgreSQL-Werten konvertiert. Zeichenkettendarstellungen von booleschen Werten werden ebenfalls unterstützt. `null` wird in PostgreSQL-NULL konvertiert.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`table_name`

  Der Name der Tabelle, für die die Arrayelemente konvertiert werden.

`values`

  Die Daten, die konvertiert werden.

`flags`

  Eie beliebige Kombination der Konstanten `PGSQL_CONV_IGNORE_DEFAULT`, `PGSQL_CONV_FORCE_NULL` und `PGSQL_CONV_IGNORE_NOT_NULL`.

### Rückgabewerte

Ein Array mit den konvertierten Werten. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn der Wert oder der Typ eines Feldes nicht mit einem PostgreSQL-Typ übereinstimmt, wird ein ValueError oder TypeError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wenn der Wert oder Typ eines Feldes nicht mit einem PostgreSQL-Typ übereinstimmt, wird nun ein ValueError oder TypeError geworfen; zuvor wurde ein `E_WARNING` ausgegeben.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_convert()-Beispiel

    <?php
    $dbconn = pg_connect('dbname=foo');

    $tmp = array(
        'author' => 'Joe Thackery',
        'year' => 2005,
        'title' => 'My Life, von Joe Thackery'
    );

    $vals = pg_convert($dbconn, 'authors', $tmp);
    ?>

### Siehe auch

- pg_meta_data() - Liefert die Metadaten einer Tabelle als Array
- pg_insert() - Überträgt Werte aus einem Array in eine Tabelle
- pg_select() - Wählt Datensätze aus
- pg_update() - Aktualisiert eine Tabelle
- pg_delete() - Löscht Datensätze

# pg_copy_from

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_from — Fügt Datensätze aus einem Array in eine Tabelle ein

### Beschreibung

function pg_copy_from(
PgSql\Connection `$connection`,
string `$table_name`,
array|Traversable `$rows`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): bool

pg_copy_from() fügt Datensätze aus `rows` in eine Tabelle ein. Intern wird dazu der `COPY FROM`-SQL-Befehl verwendet.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`table_name`

  Name der Tabelle, in die die `rows` eingefügt werden.

`rows`

  iterable Daten, die in `table_name` eingefügt werden. Jedes Element von `rows` wird zu einer Zeile in `table_name`. Die Elemente in `rows` müssen Strings mit Feldbegrenzern sein, und mit einem Zeilenvorschub abgeschlossen sein.

`separator`

  Der Feldbegrenzer, mit dem die Werte in den Elementen von `rows` separiert werden. Der Vorgabewert ist `\t`.

`null_as`

  Bestimmt, wie SQL `NULL` Werte in `rows` dargestellt werden. Der Standardwert ist `\\N` (`"\\\\N"`).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | `rows` hat nun den Typ iterable; vorher war er vom Typ array.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_copy_from() Beispiel

    <?php
       $db = pg_connect("dbname=publisher") or die("Konnte keine Verbindung aufbauen");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Siehe auch

- pg_copy_to() - Kopiert eine Tabelle in ein Array

# pg_copy_to

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_to — Kopiert eine Tabelle in ein Array

### Beschreibung

function pg_copy_to(
PgSql\Connection `$connection`,
string `$table_name`,
string `$separator` = "\t",
string `$null_as` = "\\\\N"
): array|false

pg_copy_to() kopiert eine Tabelle in ein Array. Intern wird das SQL-Kommando `COPY TO` aufgerufen, um die Datensätze einzufügen.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`table_name`

  Der Name der Tabelle, aus der die Daten in das Array `rows` kopiert werden.

`separator`

  Der Feldbegrenzer, mit dem die Werte in den Elementen von `rows` separiert werden. Der Vorgabewert ist `\t`.

`null_as`

  Bestimmt, wie SQL `NULL`-Werte in `rows` dargestellt werden. Der Standardwert ist `\\N` (`"\\\\N"`).

### Rückgabewerte

Die Funktion gibt ein array zurück, in dem jedes Element eine Zeile der mit `COPY` erzeugten Daten enthält. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_copy_to()-Beispiel

    <?php
       $db = pg_connect("dbname=publisher") or die("Konnte keine Verbindung aufbauen");

       $rows = pg_copy_to($db, $table_name);

       pg_query($db, "DELETE FROM $table_name");

       pg_copy_from($db, $table_name, $rows);
    ?>

### Siehe auch

- pg_copy_from() - Fügt Datensätze aus einem Array in eine Tabelle ein

# pg_dbname

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_dbname — Liefert den Namen der Datenbank

### Beschreibung

function pg_dbname(?PgSql\Connection `$connection` = `null`): string

pg_dbname() gibt den Namen der Datenbank zurück, deren `connection`-Instanz übergeben wurde.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Ein string mit dem Namen der Datenbank, zu der eine `connection` besteht.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_dbname()-Beispiel

    <?php
      error_reporting(E_ALL);

      pg_connect("host=localhost port=5432 dbname=mary");
      echo pg_dbname(); // mary
    ?>

# pg_delete

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_delete — Löscht Datensätze

### Beschreibung

function pg_delete(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_delete() löscht die Datensätze aus `table_name`, deren Feldnamen und Werte im Array `conditions` angegeben wurden.

Falls `flags` angegeben wurde, wird pg_convert() mit den angegebenen Flags auf das Array `conditions` angewendet.

Standardmäßig übergibt pg_delete() Rohwerte. Die Werte müssen entweder maskiert werden oder es muss das Flag `PGSQL_DML_ESCAPE` in `flags` angegeben werden. `PGSQL_DML_ESCAPE` maskiert Parameter und Bezeichner und setzt sie in Anführungszeichen. Daher muss bei Tabellen- und Spaltennamen zwischen Groß- und Kleinschreibung unterschieden werden.

Es ist zu beachten, dass weder die Maskierung noch eine vorbereitete Abfrage LIKE-Abfragen, JSON, Array, Regex usw. schützen können. Diese Parameter sollten im Kontext behandelt werden, d. h. Werte maskieren und validieren.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`table_name`

  Der Name der Tabelle, aus der Zeilen gelöscht werden.

`conditions`

  Ein Array dessen Schlüssel den Spaltennamen der Tabelle `table_name` entsprechen und dessen Werte den zu löschenden Spaltenwerten entsprechen.

`flags`

  Jede Kombination aus `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` und `PGSQL_DML_STRING`. Falls `PGSQL_DML_STRING` in den `flags` enthalten ist, wird der Abfragestring zurückgegeben. Werden `PGSQL_DML_NO_CONV` oder `PGSQL_DML_ESCAPE` angegeben, wird pg_convert() intern nicht aufgerufen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. Falls die Konstante `PGSQL_DML_STRING` im Parameter `flags` übergeben wurde, wird ein String zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_delete()-Beispiel

    <?php
      $db = pg_connect('dbname=foo');
      // Das ist einigermaßen sicher, da alle Werte maskiert werden.
      // Allerdings unterstützt PostgreSQL JSON/Array. Diese sind nicht
      // sicher, da sie Abfragen weder maskieren noch vorbereiten.
      $res = pg_delete($db, 'post_log', $_POST, PG_DML_ESCAPE);
      if ($res) {
          echo "POST-Daten wurden gelöscht: $res\n";
      } else {
          echo "Aufruf erfolgte mit falschen Angaben\n";
      }
    ?>

### Siehe auch

- pg_convert() - Konvertiert die Werte eines assoziativen Arrays in die für SQL-Anweisungen passende Form

# pg_end_copy

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_end_copy — Synchronisation mit dem PostgreSQL-Server

### Beschreibung

function pg_end_copy(?PgSql\Connection `$connection` = `null`): bool

pg_end_copy() synchronisiert das PostgreSQL-Frontend (normalerweise ein Prozess des Webservers) mit dem PostgreSQL-Server nach einer Kopier-Operation, die von der Funktion pg_put_line() durchgeführt wurde. pg_end_copy() muss aufgerufen werden, da sonst der PostgreSQL-Server einen "out of sync" Fehler mit dem Frontend meldet. Die Funktion gibt bei Erfolg `true` zurück, und bei Misserfolg einen Fehler.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_end_copy() Beispiel

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\thello world\t4.5\n");
      pg_put_line($conn, "4\tgoodbye world\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Siehe auch

- pg_put_line() - Sendet eine NULL-terminierte Zeichenkette zum PostgreSQL-Server

# pg_escape_bytea

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_bytea — Maskiert Zeichenketten zum Einfügen in ein Feld vom Typ bytea

### Beschreibung

function pg_escape_bytea(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_bytea() maskiert `string` für den Datentyp bytea und gibt den maskierten String zurück.

> Hinweis:

> Wenn Daten vom Typ bytea mit `SELECT` abgefragt werden, gibt PostgreSQL die Oktalwerte der einzelnen Datenbytes zurück, denen ein Backslash vorangestellt ist (z. B. \032). Diese Werte müssen vom Benutzer in das Binärformat zurückkonvertiert werden.

> Diese Funktion setzt PostgreSQL 7.2 oder höher voraus. Bei PostgreSQL 7.2.0 und 7.2.1 muss der Typ bytea konvertiert werden, falls die multi-byte-Unterstützung benutzt wird, z. B. `INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea);`. Ab PostgreSQL 7.2.2 und höher, muss keine Typkonvertierung mehr durchgeführt werden. Es sei denn, die Codierungen von Client und Server passen nicht zusammen, was zu einem multi-byte Streamfehler führen kann. Um diesen Fehler zu vermeiden, muss der Stream in den Typ bytea konvertiert werden.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`string`

  Ein string, der Text oder Binärdaten enthält, die in eine Spalte vom Typ bytea eingefügt werden sollen.

### Rückgabewerte

Ein string mit den maskierten Daten.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_escape_bytea()-Beispiel

    <?php
      // Zur Datenbank verbinden
      $dbconn = pg_connect('dbname=foo');

      // eine Binärdatei auslesen
      $data = file_get_contents('image1.jpg');

      // Die Binärdaten maskieren
      $escaped = pg_escape_bytea($data);

      // und in die Datenbank einfügen
      pg_query("INSERT INTO gallery (name, data) VALUES ('Pine trees', '{$escaped}')");
    ?>

### Siehe auch

- pg_unescape_bytea() - Entfernt Maskierungen für den Typ bytea
- pg_escape_string() - Maskiert einen String für Abfragen

# pg_escape_identifier

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_identifier — Escape an identifier for insertion into a text field

### Beschreibung

function pg_escape_identifier(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_identifier() escapes an identifier (e.g. table, field names) for querying the database. It returns an escaped identifier string for PostgreSQL server. pg_escape_identifier() adds double quotes before and after data. Users should not add double quotes. Use of this function is recommended for identifier parameters in query. For SQL literals (i.e. parameters except bytea), pg_escape_literal() or pg_escape_string() must be used. For bytea type fields, pg_escape_bytea() must be used instead.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`string`

  A string containing text to be escaped.

### Rückgabewerte

A string containing the escaped data, or `false` on failure.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_escape_identifier() example

    <?php
      // Connect to the database
      $dbconn = pg_connect('dbname=foo');

      // Escape the table name data
      $escaped = pg_escape_identifier($table_name);

      // Select rows from $table_name
      pg_query("SELECT * FROM {$escaped};");
    ?>

### Siehe auch

- pg_escape_literal() - Escape a literal for insertion into a text field
- pg_escape_bytea() - Maskiert Zeichenketten zum Einfügen in ein Feld vom Typ bytea
- pg_escape_string() - Maskiert einen String für Abfragen

# pg_escape_literal

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_literal — Escape a literal for insertion into a text field

### Beschreibung

function pg_escape_literal(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_literal() escapes a literal for querying the PostgreSQL database. It returns an escaped literal in the PostgreSQL format. pg_escape_literal() adds quotes before and after data. Users should not add quotes. Use of this function is recommended instead of pg_escape_string(). If the type of the column is bytea, pg_escape_bytea() must be used instead. For escaping identifiers (e.g. table, field names), pg_escape_identifier() must be used.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`string`

  A string containing text to be escaped.

### Rückgabewerte

A string containing the escaped data, or `false` on failure.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_escape_literal() example

    <?php
      // Connect to the database
      $dbconn = pg_connect('dbname=foo');

      // Read in a text file (containing apostrophes and backslashes)
      $data = file_get_contents('letter.txt');

      // Escape the text data
      $escaped = pg_escape_literal($data);

      // Insert it into the database. Note that no quotes around {$escaped}
      pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', {$escaped})");
    ?>

### Siehe auch

- pg_escape_identifier() - Escape an identifier for insertion into a text field
- pg_escape_bytea() - Maskiert Zeichenketten zum Einfügen in ein Feld vom Typ bytea
- pg_escape_string() - Maskiert einen String für Abfragen

# pg_escape_string

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_string — Maskiert einen String für Abfragen

### Beschreibung

function pg_escape_string(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_string() maskiert einen String für Datenbankabfragen. Der Rückgabewert ist der maskierte String im PostgreSQL-Format ohne Anführungszeichen. pg_escape_literal() ist die bevorzugte Weise um SQL-Parameter für PostgreSQL zu maskieren. addslashes() darf nicht mit PostgreSQL verwendet werden. Falls der Datentyp der Spalte bytea ist, müssen Sie stattdessen pg_escape_bytea() verwenden. pg_escape_identifier() muss verwendet werden, um Bezeichner (z. B. Tabellenamen, Feldnamen) zu maskieren.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`string`

  Ein string mit den Daten, die maskiert werden müssen.

### Rückgabewerte

Ein string mit den maskierten Daten.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_escape_string()-Beispiel

    <?php
      // Datenbankverbindung öffnen
      $dbconn = pg_connect('dbname=foo');

      // Eine Textdatei (mit Hochkommas und Backslashes) auslesen
      $data = file_get_contents('letter.txt');

      // Die Textdaten maskieren
      $escaped = pg_escape_string($data);

      // und in die Datenbank einfügen
      pg_query("INSERT INTO correspondence (name, data) VALUES ('My letter', '{$escaped}')");
    ?>

### Siehe auch

- pg_escape_bytea() - Maskiert Zeichenketten zum Einfügen in ein Feld vom Typ bytea

# pg_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_execute — Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis

### Beschreibung

function pg_execute(PgSql\Connection `$connection` = ?, string `$statement_name`, array `$params`): PgSql\Result|false

Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis.

pg_execute() ist ähnlich wie pg_query_params(), mit dem Unterschied, dass das auszuführende Kommando zuvor als vorbereitete Abfrage definiert wurde und kein SQL-String ist. Damit werden Abfragen, die wiederholt verwendet werden, nur ein einziges Mal geparst und geplant und nicht jedesmal, wenn sie ausgeführt werden. Das Kommando muss zuvor in der aktuellen Datenbanksitzung vorbereitet worden sein.

Die Parameter sind identisch zu denen in pg_query_params(), außer dass der Name eines vorbereiteten Kommandos anstatt einer SQL-Abfrage übergeben wird.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`statement_name`

  Der Name der vorbereiteten Abfrage, die ausgeführt werden soll. Falls "" angegeben wurde, wird die unbenannte Abfrage ausgeführt. Dieser Name muss zuvor mit pg_prepare(), pg_send_prepare() oder dem SQL-Kommando `PREPARE` vorbereitet worden sein.

`params`

  Ein Array, das die Parameter enthält, mit denen die Platzhalter $1, $2 usw. im originalen Abfragestring ersetzt werden. Die Anzahl der Arrayelemente muss mit der Anzahl der Platzhalter übereinstimmen.

  Warnung

  Beim Aufruf dieser Funktion werden die Elemente in Strings konvertiert.

### Rückgabewerte

Bei Erfolg wird eine PgSql\Result-Instanz zurückgegeben. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PgSql\Result-Instanz zurück; vorher wurde eine Ressource zurückgegeben.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_execute() benutzen:

    <?php
    // Zu der Datenbank "mary" verbinden
    $dbconn = pg_connect("dbname=mary");

    // Eine Abfrage zur Ausführung vorbereiten
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // Die vorbereitete Abfrage ausführen. Es ist nicht notwendig,
    // den String "Joe's Widgets" zu maskieren
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Dieselbe vorbereitete Abfrage nochmal ausführen,
    // diesmal mit einem anderen Parameter
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

### Siehe auch

- pg_prepare() - Sendet eine Aufforderung an den Server, eine vorbereitete Anfrage mit den übergebenen Parametern zu erzeugen und wartet auf ihre Beendigung
- pg_send_prepare() - Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern zu erzeugen, ohne auf ihre Beendigung zu warten
- pg_query_params() - Sendet ein Kommando zum Server und wartet seine Ausführung ab. Getrennt vom SQL-Kommando können dabei Parameter übergeben werden

# pg_fetch_all

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_all — Liefert alle Zeilen eines Abfrageergebnisses als Array

### Beschreibung

function pg_fetch_all(PgSql\Result `$result`, int `$mode` = `PGSQL_ASSOC`): array

pg_fetch_all() gibt ein Array zurück, das alle Zeilen einer PgSql\Result-Instanz enthält.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`mode`

  Ein optionaler Parameter, der bestimmt, wie das zurückgegebene Array indiziert werden soll. `mode` ist eine Konstante, die einen der folgenden Werte annehmen kann: `PGSQL_ASSOC`, `PGSQL_NUM` und `PGSQL_BOTH`. Wenn die Funktion mit `PGSQL_NUM` aufgerufen wird, wird ein Array mit numerischen Indizes zurückgegeben, mit `PGSQL_ASSOC` wird ein Array mit assoziatives Indizes zurückgegeben und mit `PGSQL_BOTH` ein Array mit beiden Indizes.

### Rückgabewerte

Ein Array mit allen Zeilen des Abfrageergebnisses. Jede Zeile ist ein assoziatives Array mit den Spaltennamen als Indizes und den Werten der Tabellenspalte als Werte.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | pg_fetch_all() gibt bei Ergebnismengen mit null Zeilen nun ein leeres Array statt `false` zurück.
7.1.0 | Der Parameter `mode` wurde hinzugefügt.

### Beispiele

Beispiel #1 pg_fetch_all()-Beispiel

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
        echo "Konnte keine Verbindung aufbauen.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT * FROM authors");
    if (!$result) {
        echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    $arr = pg_fetch_all($result);

    print_r($arr);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [id] => 1
                [name] => Fred
            )

        [1] => Array
            (
                [id] => 2
                [name] => Bob
            )

    )

### Siehe auch

- pg_fetch_row() - Liefert einen Datensatz als numerisches Array
- pg_fetch_array() - Liefert eine Zeile als Array
- pg_fetch_object() - Liefert einen Datensatz als Objekt
- pg_fetch_result() - Liefert Werte aus einer Ergebnisinstanz

# pg_fetch_all_columns

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_fetch_all_columns — Gibt alle Werte einer bestimmten Spalte eines Abfrageergebnisses in einem Array zurück

### Beschreibung

function pg_fetch_all_columns(PgSql\Result `$result`, int `$field` = 0): array

pg_fetch_all_columns() gibt ein Array zurück, das alle Werte einer bestimmten Spalte einer PgSql\Result-Instanz enthält.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`field`

  Die Nummer der Spalte. Falls nichts angegeben wurde, wird die erste Spalte ausgelesen.

### Rückgabewerte

Ein array, in dem alle Werte der Ergebnisspalte gespeichert sind.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_fetch_all_columns()-Beispiel

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT title, name, address FROM authors");
    if (!$result) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    // Die Namen aller Autoren in einem Array holen
    $arr = pg_fetch_all_columns($result, 1);

    var_dump($arr);

    ?>

### Siehe auch

- pg_fetch_all() - Liefert alle Zeilen eines Abfrageergebnisses als Array

# pg_fetch_array

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_array — Liefert eine Zeile als Array

### Beschreibung

function pg_fetch_array(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_BOTH`): array|false

pg_fetch_array() gibt ein Array zurück, das die gelesene Zeile (Tupel, Datensatz) enthält.

pg_fetch_array() ist eine erweiterte Version von pg_fetch_row(). Zusätzlich zur Speicherung der Daten in einem numerischen Array (mit den Feldindizes) speichert diese Funktion die Daten auch in einem assoziativen Array mit den Feldnamen als Indizes. In der Standardeinstellung wird ein Array mit beiden Indextypen zurückgegeben.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

pg_fetch_array() ist NICHT wesentlich langsamer als pg_fetch_row() oder pg_fetch_assoc(), ist aber viel einfacher zu benutzen.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`row`

  Die Nummer der Zeile des Abfrageergebnisses, das abgerufen werden soll. Die Nummerierung beginnt bei 0. Fehlt dieser Parameter oder ist er `null`, so wird jeweils die nächste Zeile abgerufen.

`mode`

  Ein optionaler Parameter, der bestimmt, wie das zurückgegebene Array indiziert werden soll. `mode` ist eine Konstante, die einen der folgenden Werte annehmen kann: `PGSQL_ASSOC`, `PGSQL_NUM` und `PGSQL_BOTH`. Wenn die Funktion mit `PGSQL_NUM` aufgerufen wird, wird ein Array mit numerischen Indizes zurückgegeben, mit `PGSQL_ASSOC` wird ein Array mit assoziatives Indizes zurückgegeben und mit `PGSQL_BOTH` ein Array mit beiden Indizes.

### Rückgabewerte

Ein Array, das entweder numerisch (bei 0 beginnend) oder assoziativ indiziert ist, oder beides. Jeder Wert im Array wird als String dargestellt. Nullwerte der Datenbank (`NULL`) werden als `null` zurückgegeben.

Bei einem Fehler oder wenn der Parameter `row` größer als die Anzahl der Datensätze im Abfrageergebnis ist oder wenn kein Datensatz mehr gelesen werden kann, wird `false` zurückgegeben. Der Versuch, das Ergebnis einer anderen als einer SELECT-Abfrage abzurufen, gibt ebenfalls `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_fetch_array()-Beispiel

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Konnte keine Verbindung aufbauen.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    $arr = pg_fetch_array($result, 0, PGSQL_NUM);
    echo $arr[0] . " <- Zeile 1 Autor\n";
    echo $arr[1] . " <- Zeile 1 E-mail\n";

    // Der Parameter row ist optional. Stattdessen kann
    // NULL übergeben werden. Aufeinanderfolgende Aufrufe von
    // pg_fetch_array liefern jeweils den nächsten Datensatz.
    $arr = pg_fetch_array($result, NULL, PGSQL_ASSOC);
    echo $arr["author"] . " <- Zeile 2 Autor\n";
    echo $arr["email"] . " <- Zeile 2 E-mail\n";

    $arr = pg_fetch_array($result);
    echo $arr["author"] . " <- Zeile 3 Autor\n";
    echo $arr[1] . " <- Zeile 3 E-mail\n";

    ?>

### Siehe auch

- pg_fetch_row() - Liefert einen Datensatz als numerisches Array
- pg_fetch_object() - Liefert einen Datensatz als Objekt
- pg_fetch_result() - Liefert Werte aus einer Ergebnisinstanz

# pg_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_assoc — Liefert eine Zeile als assoziatives Array

### Beschreibung

function pg_fetch_assoc(PgSql\Result `$result`, ?int `$row` = `null`): array|false

pg_fetch_assoc() gibt eine Zeile eines Abfrageergebnisses als assoziatives Array zurück.

pg_fetch_assoc() ist äquivalent zu pg_fetch_array() mit `PGSQL_ASSOC` als optionalem dritten Parameter. Zurückgegeben wird nur ein assoziatives Array. Falls Sie ein numerisches Array brauchen, müssen Sie die Funktion pg_fetch_row() benutzen.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

pg_fetch_assoc() ist nur unwesentlich langsamer als pg_fetch_row(), aber wesentlich einfacher zu benutzen.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`row`

  Die Nummer der Zeile des Abfrageergebnisses, die geholt werden soll. Die Nummerierung beginnt bei 0. Fehlt dieser Parameter oder ist er `null`, so wird jeweils die nächste Zeile geholt.

### Rückgabewerte

Ein array, das mit den Feldnamen des Abfrageergebnisses indiziert ist. Jeder Wert im array wird als string repräsentiert. Nullwerte der Datenbank (`NULL`) werden als `null` zurückgegeben.

Bei einem Fehler oder wenn der Parameter `row` größer als die Anzahl der Zeilen im Abfrageergebnis ist oder wenn kein Datensatz mehr gelesen werden kann, wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_fetch_assoc()-Beispiel

    <?php
    $conn = pg_connect("dbname=publisher");
    if (!$conn) {
      echo "Konnte keine Verbindung aufbauen.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT id, author, email FROM authors");
    if (!$result) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    while ($row = pg_fetch_assoc($result)) {
      echo $row['id'];
      echo $row['author'];
      echo $row['email'];
    }
    ?>

### Siehe auch

- pg_fetch_row() - Liefert einen Datensatz als numerisches Array
- pg_fetch_array() - Liefert eine Zeile als Array
- pg_fetch_object() - Liefert einen Datensatz als Objekt
- pg_fetch_result() - Liefert Werte aus einer Ergebnisinstanz

# pg_fetch_object

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_object — Liefert einen Datensatz als Objekt

### Beschreibung

function pg_fetch_object(
PgSql\Result `$result`,
?int `$row` = `null`,
string `$class` = "stdClass",
array `$constructor_args` = []
): object|false

pg_fetch_object() gibt ein Objekt zurück, dessen Eigenschaften mit den Feldern des geholten Datensatzes übereinstimmen. Optional kann pg_fetch_object() ein Objekt der angegebenen Klasse instantiieren und Parameter an den Konstruktor dieser Klasse übergeben.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

Von der Geschwindigkeit her ist die Funktion mit pg_fetch_array() identisch und fast so schnell wie pg_fetch_row() (der Unterschied ist unwesentlich).

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`row`

  Die Nummer der Zeile des Abfrageergebnisses, die geholt werden soll. Die Nummerierung beginnt bei 0. Fehlt dieser Parameter oder ist er `null`, so wird jeweils die nächste Zeile geholt.

`class`

  Der Name der Klasse, die instantiiert werden soll. Ein Objekt dieser Klasse mit den gesetzten Eigenschaften wird zurückgegeben. Fehlt dieser Parameter, wird eine Objekt der Klasse stdClass zurückgegeben.

`constructor_args`

  Ein optionales array mit Parametern, die an den Konstruktor von `class` übergeben werden.

### Rückgabewerte

Ein object, das für jeden Feldnamen des geholten Datensatzes eine Eigenschaft enthält. `NULL`-Werte der Datenbank werden als `null` zurückgegeben.

Bei einem Fehler oder wenn der Parameter `row` größer als die Anzahl der Zeilen im Abfrageergebnis ist oder wenn kein Datensatz mehr gelesen werden kann, wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn `constructor_args` nicht leer ist, die Klasse aber keinen Konstruktor hat, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wenn `constructor_args` nicht leer ist, die Klasse aber keinen Konstruktor hat, wird nun ein ValueError geworfen; zuvor wurde eine Exception geworfen.
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_fetch_object()-Beispiel

    <?php

    $database = "store";

    $db_conn = pg_connect("host=localhost port=5432 dbname=$database");
    if (!$db_conn) {
      echo "Konnte keine Verbindung zu $database aufbauen.\n";
      exit;
    }

    $qu = pg_query($db_conn, "SELECT * FROM books ORDER BY author");

    while ($data = pg_fetch_object($qu)) {
      echo $data->author . " (";
      echo $data->year . "): ";
      echo $data->title . "<br />";
    }

    pg_free_result($qu);
    pg_close($db_conn);

    ?>

### Siehe auch

- pg_query() - Führt eine Abfrage aus
- pg_fetch_array() - Liefert eine Zeile als Array
- pg_fetch_assoc() - Liefert eine Zeile als assoziatives Array
- pg_fetch_row() - Liefert einen Datensatz als numerisches Array
- pg_fetch_result() - Liefert Werte aus einer Ergebnisinstanz

# pg_fetch_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_fetch_result — Liefert Werte aus einer Ergebnisinstanz

### Beschreibung

function pg_fetch_result(PgSql\Result `$result`, string|false|null `$row`, mixed `$field`): string|false|null
function pg_fetch_result(PgSql\Result `$result`, mixed `$field`): string|false|null

pg_fetch_result() liefert den Wert einer bestimmten Zeile und Spalte eines PostgreSQL PgSql\Result-Instanz.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_result().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`row`

  Die Nummer der Zeile des Abfrageergebnisses, die geholt werden soll. Die Nummerierung beginnt bei 0. Fehlt dieser Parameter, so wird jeweils die nächste Zeile geholt.

`field`

  Ein string, der den Feldnamen des gewünschten Feldes enthält oder dessen numerischen Feldindex (beginnend bei 0).

### Rückgabewerte

Boolesche Werte werden als "t" oder "f" zurückgegeben. Alle anderen Typen, einschließlich Arrays, werden als Strings in der vom psql-Befehl bekannten PostgreSQL-Standardformatierung zurückgegeben,. Nullwerte der Datenbank `NULL` werden als `null` zurückgegeben.

Bei einem Fehler oder wenn der Parameter `row` größer als die Anzahl der Zeilen im Abfrageergebnis ist, wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | `row` ist nun nullable (akzeptiert den `null`-Wert).
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_fetch_result()-Beispiel

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "Das erste Feld in der zweiten Zeile enthält: ", $val, "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Das erste Feld in der zweiten Zeile enthält: 2

### Siehe auch

- pg_query() - Führt eine Abfrage aus
- pg_fetch_array() - Liefert eine Zeile als Array

# pg_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_row — Liefert einen Datensatz als numerisches Array

### Beschreibung

function pg_fetch_row(PgSql\Result `$result`, ?int `$row` = `null`, int `$mode` = `PGSQL_NUM`): array|false

pg_fetch_row() holt einen Datensatz der Ergebnismenge, die durch die `result`-Instanz bezeichnet wird.

> Hinweis: Diese Funktion setzt NULL-Felder auf den PHP-Wert `null`.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`row`

  Die Nummer der Zeile des Abfrageergebnisses, die geholt werden soll. Die Nummerierung beginnt bei 0. Fehlt dieser Parameter oder ist er `null`, so wird jeweils die nächste Zeile geholt.

`mode`

  Ein optionaler Parameter, der bestimmt, wie das zurückgegebene Array indiziert werden soll. `mode` ist eine Konstante, die einen der folgenden Werte annehmen kann: `PGSQL_ASSOC`, `PGSQL_NUM` und `PGSQL_BOTH`. Wenn die Funktion mit `PGSQL_NUM` aufgerufen wird, wird ein Array mit numerischen Indizes zurückgegeben, mit `PGSQL_ASSOC` wird ein Array mit assoziatives Indizes zurückgegeben und mit `PGSQL_BOTH` ein Array mit beiden Indizes.

### Rückgabewerte

Ein array, beginnend bei Index 0, bei dem jeder Wert als string dargestellt wird. Nullwerte der Datenbank (`NULL`) werden als `null` zurückgegeben.

Bei einem Fehler oder wenn der Parameter `row` größer als die Anzahl der Zeilen im Abfrageergebnis ist oder wenn kein Datensatz mehr gelesen werden kann, wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_fetch_row()-Beispiel

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Konnte keine Verbindung aufbauen.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Autor: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### Siehe auch

- pg_query() - Führt eine Abfrage aus
- pg_fetch_array() - Liefert eine Zeile als Array
- pg_fetch_object() - Liefert einen Datensatz als Objekt
- pg_fetch_result() - Liefert Werte aus einer Ergebnisinstanz

# pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_is_null — Prüft, ob ein Feld einen SQL-`NULL`-Wert enthält

### Beschreibung

function pg_field_is_null(PgSql\Result `$result`, string|false|null `$row`, mixed `$field`): int
function pg_field_is_null(PgSql\Result `$result`, mixed `$field`): int

pg_field_is_null() prüft, ob ein Feld einer PgSql\Result-Instanz einen SQL-`NULL`-Wert enthält.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_fieldisnull().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`row`

  Die Nummer der Zeile im Abfrageergebnis. Die Nummerierung beginnt bei 0. Fehlt dieser Parameter, wird die aktuelle Zeile geholt.

`field`

  Die Nummer des Feldes (beginnend bei 0) als int oder der Feldname als string.

### Rückgabewerte

Gibt `1` zurück, falls das Feld in der übergebenen Zeile einen SQL-`NULL`-Wert enthält und `0`, falls nicht. Bei einem Fehler oder wenn der Parameter `row` größer als die Anzahl der Zeilen im Abfrageergebnis ist, wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | `row` ist nun nullable (akzeptiert den `null`-Wert).
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_field_is_null()-Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die
                ("Konnte keine Verbindung aufbauen");
      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      if ($res) {
          if (pg_field_is_null($res, 0, "year") == 1) {
              echo "Der Wert im Feld year ist NULL.\n";
          }
          if (pg_field_is_null($res, 0, "year") == 0) {
              echo "Der Wert im Feld year ist nicht NULL.\n";
        }
     }
    ?>

# pg_field_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_name — Liefert den Namen eines Feldes

### Beschreibung

function pg_field_name(PgSql\Result `$result`, int `$field`): string

pg_field_name() gibt den Namen des Feldes zurück, das in der PostgreSQL-Ergebnismenge der durch `result` angegebenen Instanz das Feld mit der Nummer `field` belegt. Die Feldnummerierung beginnt bei 0.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_fieldname().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`field`

  Die Feldnummer, beginnend bei 0.

### Rückgabewerte

Den Feldnamen.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Informationen über Felder abfragen

    <?php
      $dbconn = pg_connect("dbname=publisher") or die
               ("Konnte keine Verbindung aufbauen.");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "Spalte $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "Feldname: $fieldname\n";
          echo "Feldlänge in Zeichen: " . pg_field_prtlen($res, $fieldname) . " Zeichen\n";
          echo "Feldlänge in Bytes: " . pg_field_size($res, $j) . " Bytes\n";
          echo "Feldtyp: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Spalte 0
    Feldname: author
    Feldlänge in Zeichen: 6 Zeichen
    Feldlänge in Bytes: -1 Bytes
    Feldtyp: varchar

    Spalte 1
    Feldname: year
    Feldlänge in Zeichen: 4 Zeichen
    Feldlänge in Bytes: 2 Bytes
    Feldtyp: int2

    Spalte 2
    Feldname: title
    Feldlänge in Zeichen: 24 Zeichen
    Feldlänge in Bytesr: -1 Bytes
    Feldtyp: varchar

### Siehe auch

- pg_field_num() - Liefert die Feldnummer des angegebenen Feldes

# pg_field_num

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_num — Liefert die Feldnummer des angegebenen Feldes

### Beschreibung

function pg_field_num(PgSql\Result `$result`, string `$field`): int

pg_field_num() gibt die Nummer des Feldes zurück, das dem angegebenen Feld `field` in der durch `result` bezeichneten Instanz entspricht.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_fieldnum().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`field`

  Der Name des Feldes. Der angegebene Name wird wie ein Bezeichner in einem SQL-Befehl behandelt, d. h. wenn er nicht in doppelten Anführungszeichen steht, wird er in Kleinschreibung umgewandelt.

### Rückgabewerte

Die Feldnummer (beginnend bei 0) oder -1, falls ein Fehler auftrat.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Die Nummer eines Feldes ermitteln

    <?php
      $dbconn = pg_connect("dbname=publisher") or die
                ("Konnte keine Verbindung aufbauen.");

      $res = pg_query($dbconn, "select author, year, title from authors where author = 'Orwell'");

      echo "Die Spalte 'title' hat die Feldnummer: ", pg_field_num($res, 'title');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Die Spalte 'title' hat die Feldnummer: 2

### Siehe auch

- pg_field_name() - Liefert den Namen eines Feldes

# pg_field_prtlen

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_prtlen — Liefert die Länge des Feldes

### Beschreibung

function pg_field_prtlen(PgSql\Result `$result`, string|false|null `$row`, mixed `$field_name_or_number`): int
function pg_field_prtlen(PgSql\Result `$result`, mixed `$field_name_or_number`): int

pg_field_prtlen() gibt die aktuelle Länge (Anzahl der Zeichen) eines bestimmten Wertes in einem PostgreSQL-`result` zurück. Die Feldnummerierung beginnt bei 0. Die Funktion gibt bei einem Fehler `false` zurück.

`field_name_or_number` kann als int oder als string übergeben werden. Ein int wird von PHP als Feldnummer interpretiert, ein string als Feldname.

Sehen Sie sich dazu das Beispiel bei pg_field_name() an.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_fieldprtlen().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`row`

  Die Nummer der Zeile im Abfrageergebnis. Die Nummerierung beginnt bei 0. Fehlt dieser Parameter, so wird jeweils die nächste Zeile geholt.

### Rückgabewerte

Die Anzahl der Zeichen in dem Feld.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | `row` ist nun nullable (akzeptiert den `null`-Wert).
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Informationen über Spalten ermitteln

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Verbindungsaufbau fehlgeschlagen");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "Spalte $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "Spaltenname: $fieldname\n";
          echo "Anzahl Druckzeichen: " . pg_field_prtlen($res, $fieldname) . " characters\n";
          echo "Anzahl Bytes im speicher: " . pg_field_size($res, $j) . " bytes\n";
          echo "Spaltentyp: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Spalte 0
    Spaltenname: author
    Anzahl Druckzeichen: 6 characters
    Anzahl Bytes im speicher: -1 bytes
    Spaltentyp: varchar

    Spalte 1
    Spaltenname: year
    Anzahl Druckzeichen: 4 characters
    Anzahl Bytes im speicher: 2 bytes
    Spaltentyp: int2

    Spalte 2
    Spaltenname: title
    Anzahl Druckzeichen: 24 characters
    Anzahl Bytes im speicher: -1 bytes
    Spaltentyp: varchar

### Siehe auch

- pg_field_size() - Liefert die interne Größe des belegten Speichers für ein Feld

# pg_field_size

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_size — Liefert die interne Größe des belegten Speichers für ein Feld

### Beschreibung

function pg_field_size(PgSql\Result `$result`, int `$field`): int

pg_field_size() gibt die interne Größe (in Bytes) des Feldes mit der Nummer `field_number` im PostgreSQL-Abfrageergebnis `result` zurück.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_fieldsize().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`field`

  Die Feldnummer, beginnend bei 0.

### Rückgabewerte

Die interne Größe des Feldes in Byte. Eine Feldgröße von -1 beschreibt ein Feld mit variabler Länge.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Informationen über Felder abfragen

    <?php
      $dbconn = pg_connect("dbname=publisher") or die
               ("Konnte keine Verbindung aufbauen.");

      $res = pg_query($dbconn, "select * from authors where author = 'Orwell'");
      $i = pg_num_fields($res);
      for ($j = 0; $j < $i; $j++) {
          echo "Spalte $j\n";
          $fieldname = pg_field_name($res, $j);
          echo "Feldname: $fieldname\n";
          echo "Feldlänge in Zeichen: " . pg_field_prtlen($res, $fieldname) . " Zeichen\n";
          echo "Feldlänge in Bytes: " . pg_field_size($res, $j) . " Bytes\n";
          echo "Feldtyp: " . pg_field_type($res, $j) . " \n\n";
      }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Spalte 0
    Feldname: author
    Feldlänge in Zeichen: 6 Zeichen
    Feldlänge in Bytes: -1 Bytes
    Feldtyp: varchar

    Spalte 1
    Feldname: year
    Feldlänge in Zeichen: 4 Zeichen
    Feldlänge in Bytes: 2 Bytes
    Feldtyp: int2

    Spalte 2
    Feldname: title
    Feldlänge in Zeichen: 24 Zeichen
    Feldlänge in Bytesr: -1 Bytes
    Feldtyp: varchar

### Siehe auch

- pg_field_prtlen() - Liefert die Länge des Feldes
- pg_field_type() - Liefert den Datentyp eines Feldes

# pg_field_table

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

pg_field_table — Gibt zu einem Feldnamen den Namen der Tabelle oder deren oid zurück, in der das Feld definiert ist

### Beschreibung

function pg_field_table(PgSql\Result `$result`, int `$field`, bool `$oid_only` = `false`): string|int|false

pg_field_table() gibt den Namen der Tabelle zurück, in der das Feld definiert ist, oder den oid (Object Identifier) der Tabelle, falls der Parameter `oid_only` `true` ist.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`field`

  Index des Feldes, beginnend bei 0.

`oid_only`

  In der Standardeinstellung wird der Name der Tabelle zurückgegeben, zu der dieses Feld gehört. Wenn der Parameter `oid_only` den Wert `true` hat, wird stattdessen der oid der Tabelle zurückgegeben.

### Rückgabewerte

Bei Erfolg wird entweder der Name oder der oid der Tabelle zurückgegeben. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Informationen über Felder abfragen

    <?php
    $dbconn = pg_connect("dbname=publisher")
              or die("Konnte keine Verbindung aufbauen.");

    $res = pg_query($dbconn, "SELECT bar FROM foo");

    echo pg_field_table($res, 0);
    echo pg_field_table($res, 0, true);

    $res = pg_query($dbconn, "SELECT version()");
    var_dump(pg_field_table($res, 0));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    foo
    14379580

    bool(false)

### Anmerkungen

> Hinweis:

> Die Funktion ist viel schneller, wenn man sich den oid zurückgeben lässt, weil zur Ermittlung des Tabellennamens die Systemkataloge der Datenbank abgefragt werden müssen.

### Siehe auch

- pg_field_name() - Liefert den Namen eines Feldes
- pg_field_type() - Liefert den Datentyp eines Feldes

# pg_field_type

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_type — Liefert den Datentyp eines Feldes

### Beschreibung

function pg_field_type(PgSql\Result `$result`, int `$field`): string

pg_field_type() gibt den Basistyp des Feldes mit der Nummer `field` in der PostgreSQL `result`-Instanz zurück.

> Hinweis:

> Wenn das Feld anstatt eines Basis-Datentyps einen Typ einer PostgreSQL-Domain besitzt, wird der Name des Datentyps zurückgegeben, auf dem die Domain definiert ist und nicht der Name der Domain.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_fieldtype().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`field`

  Die Feldnummer, beginnend bei 0.

### Rückgabewerte

Ein string, der den Datentyp des Feldes enthält.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Informationen über Felder holen

    <?php
      $dbconn = pg_connect("dbname=publisher") or die
                ("Konnte keine Verbindung aufbauen");

      // Angenommen 'title' hat den Typ varchar
      $res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

      echo "Der Datentyp von title ist: ", pg_field_type($res, 0);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Der Datentyp von title ist: varchar

### Siehe auch

- pg_field_prtlen() - Liefert die Länge des Feldes
- pg_field_name() - Liefert den Namen eines Feldes
- pg_field_type_oid() - Liefert die ID des PostgreSQL-Datentyps (OID) eines Feldes

# pg_field_type_oid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_field_type_oid — Liefert die ID des PostgreSQL-Datentyps (OID) eines Feldes

### Beschreibung

function pg_field_type_oid(PgSql\Result `$result`, int `$field`): string|int

pg_field_type_oid() gibt einen Integer zurück, der die OID des Datentyps für das Feld mit der Nummer `field` in der PostgreSQL `result`-Instanz enthält.

Mehr Informationen über Feldtypen erhalten Sie, wenn Sie den PostgreSQL-Systemkatalog `pg_type` mit der OID, die von dieser Funktion zurückgegeben wird, abfragen. Die PostgreSQL-Funktion format_type() konvertiert diesen OID in einen Standard-SQL-Typnamen.

> Hinweis:

> Wenn das Feld anstatt eines Basis-Datentyps einen Typ einer PostgreSQL-Domain besitzt, wird der Name des Datentyps zurückgegeben, auf dem die Domain definiert ist und nicht der Name der Domain.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`field`

  Die Feldnummer, beginnend bei 0.

### Rückgabewerte

Den OID (Object Identifier) des Basistyps dieses Feldes.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Informationen über Felder holen

    <?php
      $dbconn = pg_connect("dbname=publisher") or die
                ("Konnte keine Verbindung aufbauen");

      // Angenommen 'title' ist vom Typ varchar
      $res = pg_query($dbconn, "select title from authors where author = 'Orwell'");

      echo "Der OID des Feldes title ist: ", pg_field_type_oid($res, 0);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Der OID des Feldes title ist: 1043

### Siehe auch

- pg_field_type() - Liefert den Datentyp eines Feldes
- pg_field_prtlen() - Liefert die Länge des Feldes
- pg_field_name() - Liefert den Namen eines Feldes

# pg_flush

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_flush — Flush outbound query data on the connection

### Beschreibung

function pg_flush(PgSql\Connection `$connection`): int|bool

pg_flush() flushes any outbound query data waiting to be sent on the connection.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

Returns `true` if the flush was successful or no data was waiting to be flushed, `0` if part of the pending data was flushed but more remainsBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

# pg_free_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_free_result — Gibt den durch Ergebnisse belegten Speicher frei

### Beschreibung

function pg_free_result(PgSql\Result `$result`): bool

pg_free_result() gibt den Speicher und die Daten, die mit der PgSql\Result-Instanz assoziiert sind, frei.

Die Funktion braucht nur aufgerufen zu werden, wenn man befürchten muss, dass während der Ausführung des Skripts zu viel Speicher verbraucht wird. Ansonsten wird der Speicherplatz, den Ergebnisse belegen, automatisch nach Beendigung des Skriptes freigegeben.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_freeresult().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_free_result()-Beispiel

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, "SELECT 1 UNION ALL SELECT 2");

    $val = pg_fetch_result($res, 1, 0);

    echo "Das erste Feld in der zweiten Zeile enthält: ", $val, "\n";

    pg_free_result($res);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Das erste Feld in der zweiten Zeile enthält: 2

### Siehe auch

- pg_query() - Führt eine Abfrage aus
- pg_query_params() - Sendet ein Kommando zum Server und wartet seine Ausführung ab. Getrennt vom SQL-Kommando können dabei Parameter übergeben werden
- pg_execute() - Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis
- pg_result_memory_size() - Returns the amount of memory allocated for a query result

# pg_get_notify

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_notify — Liefert eine SQL-NOTIFY-Nachricht

### Beschreibung

function pg_get_notify(PgSql\Connection `$connection`, int `$mode` = `PGSQL_ASSOC`): array|false

pg_get_notify() gibt eine NOTIFY-Nachricht zurück, die vom SQL-Kommando `NOTIFY` gesendet wurde. Um diese Nachrichten zu erhalten, muss zuvor das SQL-Kommando `LISTEN` ausgeführt worden sein.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`mode`

  Ein optionaler Parameter, der bestimmt, wie das zurückgegebene Array indiziert werden soll. `mode` ist eine Konstante, die einen der folgenden Werte annehmen kann: `PGSQL_ASSOC`, `PGSQL_NUM` und `PGSQL_BOTH`. Wenn die Funktion mit `PGSQL_NUM` aufgerufen wird, wird ein Array mit numerischen Indizes zurückgegeben, mit `PGSQL_ASSOC` wird ein Array mit assoziatives Indizes zurückgegeben und mit `PGSQL_BOTH` ein Array mit beiden Indizes.

### Rückgabewerte

Ein Array, das die `NOTIFY`-Nachricht und die PID des Datenbankprozesses enthält. Falls vom Server unterstützt, enthält das Array ebenfalls die Serverversion und die Nutzdaten. Existiert kein `NOTIFY`, wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 PostgreSQL-NOTIFY-Nachricht

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Konnte keine Verbindung aufbauen.\n";
      exit;
    }

    // Listen-Kommando 'author_updated', um Benachrichtigungen
    // von anderen Prozessen zu erhalten
    pg_query($conn, 'LISTEN author_updated;');
    $notify = pg_get_notify($conn);
    if (!$notify) {
      echo "Keine Nachrichten\n";
    } else {
      print_r($notify);
    }
    ?>

### Siehe auch

- pg_get_pid() - Prüft die Datenbankverbindung

# pg_get_pid

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_pid — Prüft die Datenbankverbindung

### Beschreibung

function pg_get_pid(PgSql\Connection `$connection`): int

pg_get_pid() gibt die Prozess-ID (PID) des Datenbankservers zurück. Diese ist nützlich, wenn man mit pg_get_notify() feststellen möchte, ob ein anderer Prozess eine `NOTIFY`-Benachrichtigung gesendet hat.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

Die Prozess-ID des Datenbankservers.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 PostgreSQL Prozess-ID

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Konnte keine Verbindung aufbauen.\n";
      exit;
    }

    // Holt die Prozess-ID (zur Weiterverwendung in pg_get_notify())
    $pid = pg_get_pid($conn);
    ?>

### Siehe auch

- pg_get_notify() - Liefert eine SQL-NOTIFY-Nachricht

# pg_get_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_get_result — Liefert asynchrone Abfrageergebnisse

### Beschreibung

function pg_get_result(PgSql\Connection `$connection`): PgSql\Result|false

pg_get_result() gibt die PgSql\Result-Instanz einer asynchronen Abfrage zurück, die mit pg_send_query(), pg_send_query_params() oder pg_send_execute() an den Datenbankserver gesendet wurde.

Mit pg_send_query() und auch den anderen asynchronen Abfragefunktionen können mehrere Abfragen an den Server geschickt werden. Deren Ergebnisse können mit pg_get_result() nacheinander abgefragt werden.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

Bei Erfolg wird eine PgSql\Result-Instanz zurückgegeben oder `false`, falls es keine Ergebnisse gibt.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PgSql\Result-Instanz zurück; vorher wurde eine Ressource zurückgegeben.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_get_result()-Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Verbindungsaufbau fehlgeschlagen");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Der erste Aufruf von pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 hat $rows1 Zeilen\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Der zweite Aufruf von pg_get_result(): $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 hat $rows2 Zeilen\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Der erste Aufruf von pg_get_result(): Resource id #3
    Resource id #3 hat 3 Zeilen

    Der zweite Aufruf von pg_get_result(): Resource id #4
    Resource id #4 hat 1 Zeilen

### Siehe auch

- pg_send_query() - Sendet eine asynchrone Abfrage

# pg_host

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_host — Liefert den Namen des Host, zu dem verbunden wurde

### Beschreibung

function pg_host(?PgSql\Connection `$connection` = `null`): string

pg_host() gibt den Namen des Hosts zurück, zu dem mit der angegebenen PostgreSQL `connection`-Instanz verbunden wurde.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Ein string, der den Namen des Hosts enthält, zu dem die `connection` besteht oder ein leerer String, falls ein Fehler auftrat.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_host()-Beispiel

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Sie sind verbunden mit: " . pg_host($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Siehe auch

- pg_connect() - Öffnet eine PostgreSQL-Verbindung
- pg_pconnect() - Öffnet eine persistente PostgreSQL-Verbindung

# pg_insert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_insert — Überträgt Werte aus einem Array in eine Tabelle

### Beschreibung

function pg_insert(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
int `$flags` = `PGSQL_DML_EXEC`
): PgSql\Result|string|bool

pg_insert() fügt die Werte des `values` in die Tabelle `table_name` ein.

Falls `flags` angegeben wurde, wird pg_convert() mit den angegebenen Flags auf das Array `values` angewendet.

Standardmäßig übergibt pg_insert() Rohwerte. Die Werte müssen entweder maskiert werden oder es muss die Option `PGSQL_DML_ESCAPE` angegeben werden. `PGSQL_DML_ESCAPE` maskiert Parameter und Bezeichner und setzt sie in Anführungszeichen. Daher muss bei Tabellen- und Spaltennamen zwischen Groß- und Kleinschreibung unterschieden werden.

Es ist zu beachten, dass weder die Maskierung noch eine vorbereitete Abfrage LIKE-Abfragen, JSON, Array, Regex usw. schützen können. Diese Parameter sollten im Kontext behandelt werden, d. h. Werte maskieren und validieren.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`table_name`

  Der Name der Tabelle, in die die Zeilen eingefügt werden sollen. `table_name` muss mindestens soviele Spalten haben, wie das `values` Elemente.

`values`

  Ein array, dessen Indizes die Feldnamen der Tabelle `table_name` sind und dessen Werte die Werte sind, die in die entprechenden Spalten eingefügt werden sollen.

`flags`

  Jede Kombination aus `PGSQL_CONV_OPTS`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` und `PGSQL_DML_STRING`. Falls `PGSQL_DML_STRING` bei den `flags` angegeben wurde, wird der Abfrage-String zurückgegeben. Werden `PGSQL_DML_NO_CONV` oder `PGSQL_DML_ESCAPE` angegeben, wird pg_convert() intern nicht aufgerufen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.. Oder gibt bei Erfolg einen String zurück, wenn `PGSQL_DML_STRING` über `flags` übergeben wird.

### Fehler/Exceptions

Wenn die angegebene Tabelle ungültig ist, wird ein ValueError geworfen.

Wenn der Wert oder der Typ eines Feldes nicht mit einem PostgreSQL-Typ übereinstimmt, wird ein ValueError oder TypeError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wenn die angegebene Tabelle ungültig ist, wird nun ein ValueError geworfen; zuvor wurde ein `E_WARNING` ausgegeben.
8.3.0 | Wenn der Wert oder Typ eines Feldes nicht mit einem PostgreSQL-Typ übereinstimmt, wird nun ein ValueError oder TypeError geworfen; zuvor wurde ein `E_WARNING` ausgegeben.
8.1.0 | Gibt nun eine PgSql\Result-Instanz zurück; vorher wurde eine Ressource zurückgegeben.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_insert()-Beispiel

    <?php
      $dbconn = pg_connect('dbname=foo');
      // Das ist einigermaßen sicher, da alle Werte maskiert werden.
      // Allerdings unterstützt PostgreSQL JSON/Array. Diese sind nicht
      // sicher, da sie Abfragen weder maskieren noch vorbereiten.
      $res = pg_insert($dbconn, 'post_log', $_POST, PGSQL_DML_ESCAPE);
      if ($res) {
          echo "Der Inhalt von $_POST wurde protokolliert\n";
      } else {
          echo "Vermutlich wurden falsche Eingabedaten gesendet\n";
      }
    ?>

### Siehe auch

- pg_convert() - Konvertiert die Werte eines assoziativen Arrays in die für SQL-Anweisungen passende Form

# pg_jit

(PHP 8 >= 8.4.0)

pg_jit — Returns the JIT information of the server

### Beschreibung

function pg_jit(?PgSql\Connection `$connection` = `null`): array

pg_jit() returns an array with the JIT (Just-In-Time compilation) information of the PostgreSQL server.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Returns an Array containing the JIT information of the server.

### Siehe auch

- pg_version() - Liefert ein Array, das die Versionen von Client, Protokoll und Server enthält (falls verfügbar).

# pg_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_error — Liefert die letzte Fehlermeldung einer Verbindung

### Beschreibung

function pg_last_error(?PgSql\Connection `$connection` = `null`): string

pg_last_error() gibt die letzte Fehlermeldung der durch `connection` gegebenen Verbindung als String zurück.

Fehlermeldungen können durch interne PostgreSQL- (libpq) Funktionsaufrufe überschrieben werden. Falls mehrere Fehler innerhalb einer internen PostgreSQL-Funktion auftreten, wird möglicherweise keine passende Fehlermeldung angezeigt.

Verwenden Sie pg_result_error(), pg_result_error_field(), pg_result_status() und pg_connection_status() um genauere Fehlermeldungen zu erhalten.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_errormessage().

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Ein string, der die letzte Fehlermeldung der aktuellen `connection` enthält.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_last_error()-Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("konnte nicht verbinden");

      // Eine Abfrage, die fehlschlägt
      $res = pg_query($dbconn, "select * from doesnotexist");

      echo pg_last_error($dbconn);
    ?>

### Siehe auch

- pg_result_error() - Liefert die mit der Ergebniskennung verknüpfte Fehlermeldung
- pg_result_error_field() - Liefert den Inhalt eines bestimmtes Feldes zu einer Fehlermeldung

# pg_last_notice

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

pg_last_notice — Liefert die letzte NOTICE-Meldung des PostgreSQL-Servers

### Beschreibung

function pg_last_notice(PgSql\Connection `$connection`, int `$mode` = `PGSQL_NOTICE_LAST`): array|string|bool

pg_last_notice() gibt die letzte NOTICE-Meldung des PostgreSQL-Servers für die angegebene `connection` zurück. Der PostgreSQL-Server sendet zu unterschiedlichen Anlässen NOTICE-Meldungen an den Client, beispielsweise, wenn in einer Tabelle eine Spalte vom Typ `SERIAL` erzeugt wurde.

Mit pg_last_notice() kann das Senden überflüssiger Abfragen vermieden werden, indem man prüft, ob eine NOTICE-Meldung sich auf die aktuelle Transaktion bezieht oder nicht.

Die Verfolgung von NOTICE-Benachrichtigungen kann auf optional gesetzt werden, indem die Direktive `pgsql.ignore_notice` in php.ini den Wert 1 erhält.

Die Protokollierung von Notice-Benachrichtigungen kann auf optional gesetzt werden, indem die Direktive `pgsql.log_notice` in php.ini den Wert 0 erhält. Nur wenn die Direktive `pgsql.ignore_notice` den Wert 0 hat, können Notice-Benachrichtigungen protokolliert werden.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`mode`

  Entweder `PGSQL_NOTICE_LAST` (um die letzte Notice zu erhalten), `PGSQL_NOTICE_ALL` (um alle Notices zu erhalten) oder `PGSQL_NOTICE_CLEAR` (um die Notices zu löschen).

### Rückgabewerte

Ein String, der die letzte NOTICE-Meldung für die übergebene `connection` enthält bei `PGSQL_NOTICE_LAST`, ein Array bei `PGSQL_NOTICE_ALL`, ein bool bei `PGSQL_NOTICE_CLEAR`.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
7.1.0 | Der Parameter `mode` wurde hinzugefügt.

### Beispiele

Beispiel #1 pg_last_notice()-Beispiel

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    $res = pg_query("CREATE TABLE test (id SERIAL)");

    $notice = pg_last_notice($pgsql_conn);

    echo $notice;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CREATE TABLE will create implicit sequence "test_id_seq" for "serial" column "test.id"

### Siehe auch

- pg_query() - Führt eine Abfrage aus
- pg_last_error() - Liefert die letzte Fehlermeldung einer Verbindung

# pg_last_oid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_oid — Liefert den Objektbezeichner (OID) des zuletzt eingefügten Datensatzes

### Beschreibung

function pg_last_oid(PgSql\Result `$result`): string|int|false

pg_last_oid() wird benutzt, um den Object-Identifier OID des zuletzt eingefügten Datensatzes zu ermitteln.

Ab PostgreSQL 7.2 ist das Feld OID optional und ab der Version 8.1 wird es nicht mehr standardmäßig in den Tabellen enthalten sein. Falls eine Tabelle ohne OID definiert wurde, muss mit der Funktion pg_result_status() geprüft werden, ob ein Datensatz korrekt eingefügt wurde.

Um den Wert eines `SERIAL`-Feldes in einem gerade eingefügten Datensatz zu erhalten, ist der Aufruf der PostgreSQL-Funktion `CURRVAL` notwendig. Dem Aufruf muss der Name der in dieser Datenbanksitzung zuletzt benutzten Sequenz übergeben werden. Ist der Name dieser Sequenz unbekannt, muss er ab PostgreSQL 8.0 mittels der Funktion `pg_get_serial_sequence` ermittelt werden.

PostgreSQL enthält eine Funktion `LASTVAL`, die den Wert der zuletzt benutzten Sequenz der aktuellen Datenbanksitzung zurückgibt. Sie macht die Angabe von Sequenz, Tabelle und Spalte überflüssig.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_getlastoid().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

### Rückgabewerte

Ein int oder string mit der OID des zuletzt eingefügten Datensatzes für die angegebene `connection` oder `false`, falls ein Fehler auftrat oder falls es keine OID gibt.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_last_oid()-Beispiel

    <?php
      // Mit der Datenbank verbinden
      pg_connect("dbname=mark host=localhost");

      // Beispieltabelle erzeugen
      pg_query("CREATE TABLE test (a INTEGER) WITH OIDS");

      // Daten einfügen
      $res = pg_query("INSERT INTO test VALUES (1)");

      $oid = pg_last_oid($res);
    ?>

### Siehe auch

- pg_query() - Führt eine Abfrage aus
- pg_result_status() - Liefert den Status eines Abfrageergebnisses

# pg_lo_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_close — Schließt ein Large Object

### Beschreibung

function pg_lo_close(PgSql\Lob `$lob`): bool

pg_lo_close() schließt ein Large Object.

Um die Large Object (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_loclose().

### Parameter-Liste

`lob`

  Eine PgSql\Lob-Instanz, die von pg_lo_open() zurückgegeben wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `lob` erwartet nun eine PgSql\Lob-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_close() Beispiel

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "Daten fuer das Large Object");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Siehe auch

- pg_lo_open() - Öffnet ein Large Object
- pg_lo_create() - Erzeugt ein Large Object
- pg_lo_import() - Importiert ein Large Object aus einer Datei

# pg_lo_create

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_create — Erzeugt ein Large Object

### Beschreibung

function pg_lo_create(PgSql\Connection `$connection` = ?, mixed `$object_id` = ?): int
function pg_lo_create(mixed `$object_id`): int

pg_lo_create() erzeugt ein Large Object und gibt dessen OID zurück. Die `INV_READ`- und `INV_WRITE`-Zugriffsmodi von PostgreSQL werden nicht unterstützt. Ein Large Object wird immer mit Lese- und Schreibzugriff erzeugt.

Um die Large Object (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

Anstelle der Large-Object-Schnittstelle (für die es keine Zugriffssteuerung gibt und deren Benutzung etwas schwerfällig ist) können Sie den PostgreSQL-Datentyp bytea und die Funktion pg_escape_bytea() benutzen.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_locreate().

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`object_id`

  Wenn es einen Parameter `object_id` gibt, wird diese Funktion versuchen, ein Large Object mit dieser ID zu erzeugen. Anderenfalls wird dem Large Object vom Server eine freie ID zugewiesen.

### Rückgabewerte

Ein Large Object OID. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_create()-Beispiel

    <?php
     $database = pg_connect("dbname=jacarta");
     pg_query($database, "begin");
     $oid = pg_lo_create($database);
     echo "$oid\n";
     $handle = pg_lo_open($database, $oid, "w");
     echo "$handle\n";
     pg_lo_write($handle, "Daten fuer das Large Object");
     pg_lo_close($handle);
     pg_query($database, "commit");
    ?>

# pg_lo_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_export — Exportiert ein Large Object in eine Datei

### Beschreibung

function pg_lo_export(PgSql\Connection `$connection` = ?, int `$oid`, string `$filename`): bool

pg_lo_export() liest die Inhalte eines Large Objects aus einer PostgreSQL Datenbank aus und speichert sie in einer Datei im lokalen Dateisystem.

Um die Large Object (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_loexport().

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`oid`

  Der OID des Large Objects in der Datenbank.

`filename`

  Der vollständige Pfad und Dateiname der Datei, in der die Inhalte des Large Objects im lokalen Dateisystem gespeichert werden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_export() Beispiel

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       $handle = pg_lo_open($database, $oid, "w");
       pg_lo_write($handle, "Die Daten des Large Objects");
       pg_lo_close($handle);
       pg_lo_export($database, $oid, '/tmp/lob.dat');
       pg_query($database, "commit");
    ?>

### Siehe auch

- pg_lo_import() - Importiert ein Large Object aus einer Datei

# pg_lo_import

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_import — Importiert ein Large Object aus einer Datei

### Beschreibung

function pg_lo_import(PgSql\Connection `$connection` = ?, string `$pathname`, mixed `$object_id` = ?): int|string|false

pg_lo_import() erzeugt aus einer Datei im Dateisystem als Datenquelle ein neues Large Object in der Datenbank.

Um die Large Object- (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_loimport().

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`pathname`

  Der vollständige Pfad- und Dateiname der Datei im lokalen Dateisystem des Clients, aus der die Daten des Large Objects gelesen werden.

`object_id`

  Wenn es einen Parameter `object_id` gibt, wird diese Funktion versuchen, ein Large Object mit dieser ID zu erzeugen. Anderenfalls wird dem Large Object vom Server eine freie ID zugewiesen. Dieser Parameter basiert auf Funktionalitäten, die seit PostgreSQL 8.1 implementiert sind.

### Rückgabewerte

Die OID des neu erzeugten Large Objects. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_import()-Beispiel

    <?php
    $database = pg_connect("dbname=jacarta");
    pg_query($database, "begin");
    $oid = pg_lo_import($database, '/tmp/lob.dat');
    pg_query($database, "commit");
    ?>

### Siehe auch

- pg_lo_export() - Exportiert ein Large Object in eine Datei
- pg_lo_open() - Öffnet ein Large Object

# pg_lo_open

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_open — Öffnet ein Large Object

### Beschreibung

function pg_lo_open(PgSql\Connection `$connection`, int `$oid`, string `$mode`): PgSql\Lob|false

pg_lo_open() öffnet ein Large Object in einer Datenbank und gibt eine PgSql\Lob-Instanz zurück, über die das Large Object modifiziert werden kann.

Warnung

Bevor die Datenbankverbindung geschlossen wird, müssen die PgSql\Lob-Instanzen wieder geschlossen werden.

Um die Large Object- (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_loopen().

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`oid`

  Die OID des Large Objects in der Datenbank.

`mode`

  Dies kann entweder "r" für nur lesen, "w" für nur schreiben oder "rw" für lesen und schreiben sein.

### Rückgabewerte

Eine PgSql\Lob-Instanz. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PgSql\Lob-Instanz zurück; vorher wurde eine Ressource zurückgegeben.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_open()-Beispiel

    <?php
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $oid = pg_lo_create($database);
       echo "$oid\n";
       $handle = pg_lo_open($database, $oid, "w");
       echo "$handle\n";
       pg_lo_write($handle, "Daten des Large Objects");
       pg_lo_close($handle);
       pg_query($database, "commit");
    ?>

### Siehe auch

- pg_lo_close() - Schließt ein Large Object
- pg_lo_create() - Erzeugt ein Large Object

# pg_lo_read

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read — Liest ein Large Object

### Beschreibung

function pg_lo_read(PgSql\Lob `$lob`, int `$length` = 8192): string|false

pg_lo_read() liest höchstens `length` Bytes eines Large Objects und gibt die gelesenen Daten als String zurück.

Um die Large Object (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_loread().

### Parameter-Liste

`lob`

  Eine PgSql\Lob-Instanz, die von pg_lo_open() zurückgegeben wurde.

`length`

  Die (optionale) maximale Anzahl der zu lesenden Bytes.

### Rückgabewerte

Ein string, der `length` Bytes aus dem Large Object enthält, oder `false`, falls ein Fehler auftritt.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `lob` erwartet nun eine PgSql\Lob-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_read()-Beispiel

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       $data = pg_lo_read($handle, 50000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Siehe auch

- pg_lo_read_all() - Liest ein ganzes Large Object und reicht es direkt an den Browser weiter

# pg_lo_read_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read_all — Liest ein ganzes Large Object und reicht es direkt an den Browser weiter

### Beschreibung

function pg_lo_read_all(PgSql\Lob `$lob`): int

pg_lo_read_all() liest ein ganzes Large Object und übergibt es direkt an den Browser, nachdem alle entsprechenden Header gesendet wurden. Die Funktion wird hauptsächlich für Binärdaten wie Bilder oder Audiodaten genutzt.

Um die Large Object-Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_loreadall().

### Parameter-Liste

`lob`

  Eine PgSql\Lob-Instanz, die von pg_lo_open() zurückgegeben wurde.

### Rückgabewerte

Die Anzahl der gelesenen Bytes.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `lob` erwartet nun eine PgSql\Lob-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_read_all()-Beispiel

    <?php
       header('Content-type: image/jpeg');
       $image_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $image_oid, "r");
       pg_lo_read_all($handle);
       pg_query($database, "commit");
    ?>

### Siehe auch

- pg_lo_read() - Liest ein Large Object

# pg_lo_seek

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_seek — Setzt die Lese- oder Schreibposition in einem Large Object

### Beschreibung

function pg_lo_seek(PgSql\Lob `$lob`, int `$offset`, int `$whence` = `SEEK_CUR`): bool

pg_lo_seek() setzt den internen Zeiger einer PgSql\Lob-Instanz auf die angegebenen Position.

Um die Large Object (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

### Parameter-Liste

`lob`

  Eine PgSql\Lob-Instanz, die von pg_lo_open() zurückgegeben wurde.

`offset`

  Die Anzahl der Bytes, hinter die der interne Zeiger gesetzt wird.

`whence`

  Eine der Konstanten `PGSQL_SEEK_SET` (bewegt den internen Zeiger vom Anfang ausgehend), `PGSQL_SEEK_CUR` (bewegt den internen Zeiger ab der aktuellen Position) oder `PGSQL_SEEK_END` (bewegt den internen Zeiger vom Ende ausgehend).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `lob` erwartet nun eine PgSql\Lob-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_seek()-Beispiel

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Die ersten 50000 Bytes ueberspringen
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // Die naechsten 10000 Bytes lesen
       $data = pg_lo_read($handle, 10000);
       pg_query($database, "commit");
       echo $data;
    ?>

### Siehe auch

- pg_lo_tell() - Liefert die aktuelle Lese- oder Schreibposition in einem Large Object

# pg_lo_tell

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_tell — Liefert die aktuelle Lese- oder Schreibposition in einem Large Object

### Beschreibung

function pg_lo_tell(PgSql\Lob `$lob`): int

pg_lo_tell() gibt die aktuelle Position (Offset vom Anfang des Large Objects aus) des internen Zeigers zurück.

Um die Large Object (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

### Parameter-Liste

`lob`

  Eine PgSql\Lob-Instanz, die von pg_lo_open() zurückgegeben wurde.

### Rückgabewerte

Die aktuelle Lese- oder Schreibposition in einem (in Bytes) vom Anfang des Large Objects aus. Falls ein Fehler auftritt, ist der Rückgabewert negativ.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `lob` erwartet nun eine PgSql\Lob-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_tell()-Beispiel

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Überspringe die ersten 50000 Bytes
       pg_lo_seek($handle, 50000, PGSQL_SEEK_SET);
       // Test, wieviele Bytes übersprungen wurden
       $offset = pg_lo_tell($handle);
       echo "Die aktuelle Position ist: $offset";
       pg_query($database, "commit");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Die aktuelle Position ist: 50000

### Siehe auch

- pg_lo_seek() - Setzt die Lese- oder Schreibposition in einem Large Object

# pg_lo_truncate

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_lo_truncate — Truncates a large object

### Beschreibung

function pg_lo_truncate(PgSql\Lob `$lob`, int `$size`): bool

pg_lo_truncate() truncates an PgSql\Lob instance.

To use the large object interface, it is necessary to enclose it within a transaction block.

### Parameter-Liste

`lob`

  Eine PgSql\Lob-Instanz, die von pg_lo_open() zurückgegeben wurde.

`size`

  The number of bytes to truncate.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `lob` erwartet nun eine PgSql\Lob-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_truncate() example

    <?php
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "r");
       // Truncate to 0
       pg_lo_truncate($handle, 0);
       pg_query($database, "commit");
       echo $data;
    ?>

### Siehe auch

- pg_lo_tell() - Liefert die aktuelle Lese- oder Schreibposition in einem Large Object

# pg_lo_unlink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_unlink — Löscht ein Large Object

### Beschreibung

function pg_lo_unlink(PgSql\Connection `$connection`, int `$oid`): bool

pg_lo_unlink() löscht das Large Object mit dem Objektbezeichner `oid`. Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Um die Large Object (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_lounlink()().

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`oid`

  Der OID des Large Objects in der Datenbank.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_lo_unlink() Beispiel

    <?php
       // OID des Large Objects, das gelöscht werden soll
       $doc_oid = 189762345;
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       pg_lo_unlink($database, $doc_oid);
       pg_query($database, "commit");
    ?>

### Siehe auch

- pg_lo_create() - Erzeugt ein Large Object
- pg_lo_import() - Importiert ein Large Object aus einer Datei

# pg_lo_write

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_write — Schreibt in ein Large Object

### Beschreibung

function pg_lo_write(PgSql\Lob `$lob`, string `$data`, ?int `$length` = `null`): int|false

pg_lo_write() schreibt Daten ab der aktuellen Position der internen Schreib-Lese-Marke in ein Large Object.

Um die Large Object- (lo) Schnittstelle benutzen zu können, müssen die Kommandos innerhalb einer Transaktion ausgeführt werden.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_lowrite().

### Parameter-Liste

`lob`

  Eine PgSql\Lob-Instanz, die von pg_lo_open() zurückgegeben wurde.

`data`

  Die Daten, die in das Large Object geschrieben werden. Falls `length` vom Typ int ist und kleiner als die Länge von `data`, werden nur `length` Bytes geschrieben.

`length`

  Die maximale Anzahl der Bytes, die geschrieben werden. Die Anzahl muss größer als 0 und kleiner als die Länge von `data` sein. Der Vorgabewert ist die Länge von `data`. Diese Angabe ist optional.

### Rückgabewerte

Die Anzahl der Bytes, die in das Large Object geschrieben wurden, oder `false`, falls ein Fehler auftrat.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `lob` erwartet nun eine PgSql\Lob-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `length` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_lo_write()-Beispiel

    <?php
       $doc_oid = 189762345;
       $data = "Hiermit wird der Anfang des Large Objects überschrieben.";
       $database = pg_connect("dbname=jacarta");
       pg_query($database, "begin");
       $handle = pg_lo_open($database, $doc_oid, "w");
       $data = pg_lo_write($handle, $data);
       pg_query($database, "commit");
    ?>

### Siehe auch

- pg_lo_create() - Erzeugt ein Large Object
- pg_lo_open() - Öffnet ein Large Object

# pg_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_meta_data — Liefert die Metadaten einer Tabelle als Array

### Beschreibung

function pg_meta_data(PgSql\Connection `$connection`, string `$table_name`, bool `$extended` = `false`): array|false

pg_meta_data() gibt die Tabellendefinition für `table_name` in einem Array zurück.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`table_name`

  Der Tabellenname.

`extended`

  Das Flag, um erweiterte Metadaten zurückzugeben. Vorgabewert ist `false`.

### Rückgabewerte

Ein Array, das die Tabellendefinition enthält. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Metadaten für eine Tabelle ermitteln

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Verbindungsaufbau fehlgeschlagen");

      $meta = pg_meta_data($dbconn, 'authors');
      if (is_array($meta)) {
          echo '<pre>';
          var_dump($meta);
          echo '</pre>';
      }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
    ["author"]=>
    array(5) {
      ["num"]=>
      int(1)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["year"]=>
    array(5) {
      ["num"]=>
      int(2)
      ["type"]=>
      string(4) "int2"
      ["len"]=>
      int(2)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    ["title"]=>
    array(5) {
      ["num"]=>
      int(3)
      ["type"]=>
      string(7) "varchar"
      ["len"]=>
      int(-1)
      ["not null"]=>
      bool(false)
      ["has default"]=>
      bool(false)
    }
    }

### Siehe auch

- pg_convert() - Konvertiert die Werte eines assoziativen Arrays in die für SQL-Anweisungen passende Form

# pg_num_fields

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_fields — Gibt die Anzahl der Felder in einem Abfrageergebnis zurück

### Beschreibung

function pg_num_fields(PgSql\Result `$result`): int

pg_num_fields() gibt die Anzahl der Felder (Spalten) in einer PostgreSQL PgSql\Result-Instanz zurück.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_numfields().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

### Rückgabewerte

Die Anzahl der Felder (Spalten) in einem Abfrageergebnis. Tritt ein Fehler auf, wird -1 zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_num_fields() Beispiel

    <?php
    $result = pg_query($conn, "SELECT 1, 2");

    $num = pg_num_fields($result);

    echo $num . " Feld(er) gefunden.\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2 Feld(er) gefunden.

### Siehe auch

- pg_num_rows() - Gibt die Anzahl der Zeilen in einem Abfrageergebnis zurück
- pg_affected_rows() - Gibt die Anzahl betroffener Datensätze (Tupel) zurück

# pg_num_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_rows — Gibt die Anzahl der Zeilen in einem Abfrageergebnis zurück

### Beschreibung

function pg_num_rows(PgSql\Result `$result`): int

pg_num_rows() gibt die Anzahl der Zeilen in einer PostgreSQL PgSql\Result-Instanz zurück.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_numrows().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

### Rückgabewerte

Die Anzahl der Zeilen in einem Abfrageergebnis. Tritt ein Fehler auf, wird `-1` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_num_rows() Beispiel

    <?php
    $result = pg_query($conn, "SELECT 1");

    $rows = pg_num_rows($result);

    echo $rows . " Zeile(n) gefunden.\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1 Zeile(n) gefunden.

### Siehe auch

- pg_num_fields() - Gibt die Anzahl der Felder in einem Abfrageergebnis zurück
- pg_affected_rows() - Gibt die Anzahl betroffener Datensätze (Tupel) zurück

# pg_options

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_options — Liefert die Verbindungsoptionen der aktuellen Verbindung

### Beschreibung

function pg_options(?PgSql\Connection `$connection` = `null`): string

pg_options() gibt einen string zurück, der die Verbindungsoptionen der angegebenen PostgreSQL `connection`-Instanz enthält.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Ein string, der die Verbindungsoptionen von `connection` enthält.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_options()-Beispiel

    <?php
       $pgsql_conn = pg_connect("dbname=mark host=localhost");
       echo pg_options($pgsql_conn);
    ?>

### Siehe auch

- pg_connect() - Öffnet eine PostgreSQL-Verbindung

# pg_parameter_status

(PHP 5, PHP 7, PHP 8)

pg_parameter_status — Liefert den aktuellen Wert eines Parameters des Servers

### Beschreibung

function pg_parameter_status(PgSql\Connection `$connection` = ?, string `$param_name`): string

Ermittelt die aktuelle Einstellung eines Parameters des Servers.

Bestimmte Servereinstellungen (Parameter) werden beim Verbindungsaufbau oder, wenn sich ihr Wert ändert, automatich vom Server gemeldet. Mit pg_parameter_status() können Sie diese Einstellungen abfragen. Zurückgegeben wird der aktuelle Wert des Parameters, falls dieser bekannt ist, anderenfalls `false`.

Zu den vom Server gemeldeten Parametern gehören `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone` und `integer_datetimes`. Beachten Sie, dass `server_version`, `server_encoding` und `integer_datetimes` nach dem Start von PostgreSQL nicht mehr verändert werden können.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`param_name`

  Mögliche Werte für `param_name` sind: `server_version`, `server_encoding`, `client_encoding`, `is_superuser`, `session_authorization`, `DateStyle`, `TimeZone` und `integer_datetimes`. Es ist zu beachten, dass bei diesem Wert zwischen Groß- und Kleinschreibung unterschieden wird.

### Rückgabewerte

Ein string, der den Wert des Parameters enthält, oder `false`, falls ein Fehler auftrat oder der Parameter `param_name` ungültig ist.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_parameter_status()-Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Verbindungsaufbau fehlgeschlagen");

      echo "Server encoding: ", pg_parameter_status($dbconn, "server_encoding");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Server encoding: SQL_ASCII

# pg_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_pconnect — Öffnet eine persistente PostgreSQL-Verbindung

### Beschreibung

function pg_pconnect(string `$connection_string`, int `$flags` = 0): PgSql\Connection|false

pg_pconnect() öffnet eine persistente Verbindung zu einer PostgreSQL-Datenbank. Zurückgegeben wird eine PgSql\Connection-Instanz, die von anderen PostgreSQL-Funktionen benötigt wird.

Falls pg_pconnect() ein zweites Mal mit demselben `connection_string` einer bereits existierenden Verbindung aufgerufen wird, wird die Verbindungskennung dieser existierenden Verbindung zurückgegeben, es sei denn, die Konstante `PGSQL_CONNECT_FORCE_NEW` wird als `flags` übergeben.

Um persistente Verbindungen zu ermöglichen, muss die php.ini-Direktive pgsql.allow_persistent auf den Wert `"On"` gesetzt sein (was der Standardeinstellung entspricht). Die maximale Anzahl geöffneter persistenter Verbindungen kann mit der php.ini-Direktive pgsql.max_persistent definiert werden (der Standardwert ist `-1`, der für unbegrenzt steht). Die Gesamtanzahl der Verbindungen kann mit der php.ini-Direktive pgsql.max_links gesetzt werden.

pg_close() schließt keine persistenten Verbindungen, die mit pg_pconnect() erzeugt wurden.

### Parameter-Liste

`connection_string`

  Der `connection_string` kann leer sein, um die Standardwerte für die Parameter zu benutzen. Er kann auch einen oder mehrere durch Whitespace-Zeichen getrennte Parameter enthalten. Jeder Parameter wird in der Form `keyword = Wert` angegeben, Leerzeichen vor und nach dem Gleichheitszeichen sind optional. Um einen leeren Wert oder einen Wert, der Leerzeichen enthält, anzugeben, müssen Sie den Wert in einfache Anführungszeichen einschließen, zum Beispiel `keyword = 'ein Wert'`. Einfache Anführungszeichen und Backslashes innerhalb des Wertes müssen mit einem Backslash maskiert werden, d. h. `\'` und `\\`.

  Gegenwärtig werden die folgenden Schlüsselwörter als Parameter erkannt: `host`, `hostaddr`, `port`, `dbname`, `user`, `password`, `connect_timeout`, `options`, `tty` (wird ignoriert), `sslmode`, `requiressl` (veraltet zugunsten von `sslmode`) und `service`. Welche dieser Parameter zur Verfügung stehen, hängt von Ihrer PostgreSQL-Version ab.

`flags`

  Falls `PGSQL_CONNECT_FORCE_NEW` übergeben wurde, wird eine neue Verbindung aufgebaut, auch wenn der `connection_string` identisch zu dem einer existierenden Verbindung ist.

### Rückgabewerte

Bei Erfolg wird eine PgSql\Connection-Instanz zurückgegeben. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PgSql\Connection-Instanz zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 pg_pconnect() benutzen:

    <?php
    // Verbindungsaufbau zu einer Datenbank namens "mary"
    $dbconn = pg_pconnect("dbname=mary");

    // Verbindungsaufbau zu einer Datenbank namens "mary" auf "localhost" und port "5432"
    $dbconn2 = pg_pconnect("host=localhost port=5432 dbname=mary");

    // Verbindungsaufbau zu einer Datenbank namens "mary" auf dem Host
    // "sheep" mit Benutzername und Passwort
    $dbconn3 = pg_pconnect("host=sheep port=5432 dbname=mary user=lamb password=foo");

    // Verbindungsaufbau zu einer Datenbank namens "test" auf dem Host
    // "sheep" mit Benutzername und Passwort
    $conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
    $dbconn4 = pg_pconnect($conn_string);
    ?>

### Siehe auch

- pg_connect() - Öffnet eine PostgreSQL-Verbindung
- Persistente Datenbankverbindungen

# pg_ping

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_ping — Prüft die Datenbankverbindung

### Beschreibung

function pg_ping(?PgSql\Connection `$connection` = `null`): bool

pg_ping() prüft eine Datenbankverbindung und versucht einen erneuten Verbindungsaufbau, falls die Verbindung abbricht.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_ping() Beispiel

    <?php
    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    if (!pg_ping($conn))
      die("Die Verbindung ist unterbrochen\n");
    ?>

### Siehe auch

- pg_connection_status() - Gibt den Verbindungsstatus zurück
- pg_connection_reset() - Setzt die Verbindung zurück und verbindet neu

# pg_port

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_port — Liefert die Portnummer, über die die Verbindung aufgebaut wurde

### Beschreibung

function pg_port(?PgSql\Connection `$connection` = `null`): string

pg_port() gibt die Nummer des Ports zurück, über die die angegebene `connection` zum PostgreSQL-Datenbankserver aufgebaut wurde.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Ein Wert vom Typ string, der die Portnummer angibt, über die die `connection` zum PostgreSQL-Datenbankserver aufgebaut wurde oder ein leerer String, falls ein Fehler auftrat.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_port()-Beispiel

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "Verbindungsaufbau über Port " . pg_port($pgsql_conn) . " erfolgreich<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — Sendet eine Aufforderung an den Server, eine vorbereitete Anfrage mit den übergebenen Parametern zu erzeugen und wartet auf ihre Beendigung

### Beschreibung

function pg_prepare(PgSql\Connection `$connection` = ?, string `$stmtname`, string `$query`): PgSql\Result|false

pg_prepare() erzeugt eine vorbereitete Abfrage, die später mit pg_execute() oder pg_send_execute() ausgeführt werden kann. Dank dieser Eigenschaft brauchen wiederholt ausgeführte Abfragen nur ein einziges Mal geparst und geplant werden, anstatt bei jeder Ausführung.

Diese Funktion erzeugt aus der Abfrage `query` eine vorbereitete Abfrage mit dem Namen `stmtname`. `query` darf nur ein einzelnes SQL-Kommando enthalten. `stmtname` kann `""` sein, um eine unbenannte Abfrage zu erzeugen, wobei zuvor definierte unbenannte Abfragen automatisch überschrieben werden. Falls der Name der vorbereiteten Abfrage in der aktuellen Datenbanksitzung schon vergeben ist, wird ein Fehler zurückgegeben. Falls irgendwelche Parameter übergeben wurden, werden diese in `query` als `$1`, `$2` usw. referenziert.

Vorbereitete Abfragen, die mit pg_prepare() erzeugt wurden, können ebenso mit dem SQL-Kommando `PREPARE` erzeugt werden (allerdings ist pg_prepare() flexibler, weil Parametertypen nicht vorab deklariert werden müssen). Obwohl es keine PHP-Funktion zum Löschen vorbereiteter Anfragen gibt, können diese mit dem SQL-Kommando `DEALLOCATE` gelöscht werden.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`stmtname`

  Der Name, unter dem die vorbereitete Abfrage gespeichert wird. Dieser muss für jede Verbindung eindeutig sein. Falls `""` angegeben wurde, wird eine unbenannte Abfrage erzeugt, die alle zuvor definierten unbenannten Abfragen überschreibt.

`query`

  Die parametrisierte vorbereitete Abfrage. Diese darf nur ein einziges SQL-Kommando enthalten (mehrere Kommandos, durch Semikolon getrennt, sind nicht zulässig). Falls Parameter übergeben werden, werden sie als `$1`, `$2`, ... referenziert.

### Rückgabewerte

Bei Erfolg wird eine PgSql\Result-Instanz zurückgegeben. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PgSql\Result-Instanz zurück; vorher wurde eine Ressource zurückgegeben.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_prepare()-Beispiel

    <?php

    // Verbindung zu einer Datenbank namens "mary" aufbauen
    $dbconn = pg_connect("dbname=mary");

    // Abfrage vorbereiten
    $result = pg_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');

    // Die vorbereitete Abfrage ausführen. Es ist zu beachten, dass es
    // nicht nötig ist, den String "Joe's Widgets" zu maskieren.
    $result = pg_execute($dbconn, "my_query", array("Joe's Widgets"));

    // Dieselbe Abfrage mit einem anderen Parameter nochmal ausführen
    $result = pg_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));

    ?>

### Siehe auch

- pg_execute() - Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis
- pg_send_execute() - Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern auszuführen, ohne auf die Ergebnisse zu warten

# pg_put_copy_data

(PHP 8 >= 8.4.0)

pg_put_copy_data — Send data to the server during a COPY operation

### Beschreibung

function pg_put_copy_data(PgSql\Connection `$connection`, string `$cmd`): int

Sends data to the server during a `COPY FROM STDIN` operation. A `COPY` command must have been issued via pg_query() before calling this function.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`cmd`
  The data to send to the server. A final newline is automatically added if not present. The data must be formatted according to the `COPY` command's format.

### Rückgabewerte

Returns `1` on success, `0` if the data could not be queued (only in non-blocking mode), or `-1` on error.

### Siehe auch

- pg_put_copy_end() - Signal the completion of a COPY operation to the server
- pg_query() - Führt eine Abfrage aus

# pg_put_copy_end

(PHP 8 >= 8.4.0)

pg_put_copy_end — Signal the completion of a COPY operation to the server

### Beschreibung

function pg_put_copy_end(PgSql\Connection `$connection`, ?string `$error` = `null`): int

Sends an end-of-data indication to the server during a `COPY FROM STDIN` operation.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`error`
  If not `null`, the `COPY` operation is forced to fail with the given error message.

### Rückgabewerte

Returns `1` on success, `0` if the data could not be queued (only in non-blocking mode), or `-1` on error.

### Siehe auch

- pg_put_copy_data() - Send data to the server during a COPY operation
- pg_query() - Führt eine Abfrage aus

# pg_put_line

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_put_line — Sendet eine NULL-terminierte Zeichenkette zum PostgreSQL-Server

### Beschreibung

function pg_put_line(PgSql\Connection `$connection` = ?, string `$query`): bool

pg_put_line() sendet eine NULL-terminierte Zeichenkette an den PostgreSQL-Server. Das ist in Verbindung mit dem PostgreSQL-Befehl `COPY FROM` notwendig.

`COPY` ist eine PostgreSQL-Anweisung, mit der Daten mit hoher Geschwindigkeit in eine Tabelle eingefügt werden können. Die Daten werden ungeparst und in einer einzigen Transaktion übertragen.

Alternativ zu pg_put_line() kann pg_copy_from() verwendet werden. Dies ist weitaus einfacher.

> Hinweis:

> Eine Anwendung muss explizit die beiden Zeichen "\." in der letzten Zeile an PostgreSQL übertragen, um anzuzeigen, dass die Datenübertragung beendet ist, bevor pg_end_copy() aufgerufen wird.

Warnung

Die Verwendung von pg_put_line() führt bei den meisten Operationen mit Large Objects zu Fehlern. So etwa bei pg_lo_read() und pg_lo_tell(). Stattdessen sollten Sie pg_copy_from() und pg_copy_to() benutzen.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`query`

  Eine Textzeile, die direkt an den PostgreSQL Datenbankserver gesendet wird. Dabei wird automatisch ein `NULL` an das Zeilenende angehängt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_put_line() Beispiel

    <?php
      $conn = pg_pconnect("dbname=foo");
      pg_query($conn, "create table bar (a int4, b char(16), d float8)");
      pg_query($conn, "copy bar from stdin");
      pg_put_line($conn, "3\thello world\t4.5\n");
      pg_put_line($conn, "4\tgoodbye world\t7.11\n");
      pg_put_line($conn, "\\.\n");
      pg_end_copy($conn);
    ?>

### Siehe auch

- pg_end_copy() - Synchronisation mit dem PostgreSQL-Server

# pg_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_query — Führt eine Abfrage aus

### Beschreibung

function pg_query(PgSql\Connection `$connection` = ?, string `$query`): PgSql\Result|false

pg_query() führt die `query` auf der angegebenen Datenbank-Verbindung `connection` aus. In der Regel sollte pg_query_params() bevorzugt werden.

Falls ein Fehler auftritt und `false` zurückgegeben wird, können Sie Details zu diesem Fehler mit pg_last_error() anzeigen, vorausgesetzt, die Verbindungskennung ist gültig.

> Hinweis: Obwohl der Parameter `connection` weggelassen werden kann, ist dies nicht empfehlenswert, da es die Fehlersuche in Skripten erschweren kann.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_exec(). pg_exec() wird aus Gründen der Kompatibilität immer noch unterstützt, es wird jedoch empfohlen, den neuen Funktionsnamen zu verwenden.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`query`

  Die auszuführende(n) SQL-Anweisung(en). Werden mehrere Anweisungen an pg_query() übergeben, werden sie automatisch in einer einzigen Transaktion ausgeführt, es sei denn, die Anweisungsfolge enthält explizite BEGIN/COMMIT-Anweisungen. Von der Ausführung mehrerer Transaktionen innerhalb eines Funktionsaufrufs wird abgeraten.

  Warnung

  String-Interpolation von Anwenderdaten ist sehr gefährlich, und führt wahrscheinlich zu SQL-Injection-Sicherheistlücken. In der Regel sollte pg_query_params() bevorzugt werden, wobei Anwenderdaten als Parameter übergeben werden anstatt sie in der Abfragezeichenkette zu ersetzen.

  Jegliche Anwenderdaten, die direkt in eine Abfragezeichenkette interpoliert werden, sollten ordnungsgemäß maskiert werden.

### Rückgabewerte

Bei Erfolg wird eine PgSql\Result-Instanz zurückgegeben. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PgSql\Result-Instanz zurück; vorher wurde eine Ressource zurückgegeben.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_query()-Beispiel

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    while ($row = pg_fetch_row($result)) {
      echo "Autor: $row[0]  E-Mail: $row[1]";
      echo "<br />\n";
    }

    ?>

Beispiel #2 pg_query() mit mehreren Anweisungen

    <?php

    $conn = pg_pconnect("dbname=publisher");

    // diese Anweisungen werden in einer einzigen Transaktion ausgeführt.

    $query = "UPDATE authors SET author=UPPER(author) WHERE id=1;";
    $query .= "UPDATE authors SET author=LOWER(author) WHERE id=2;";
    $query .= "UPDATE authors SET author=NULL WHERE id=3;";

    pg_query($conn, $query);

    ?>

### Siehe auch

- pg_connect() - Öffnet eine PostgreSQL-Verbindung
- pg_pconnect() - Öffnet eine persistente PostgreSQL-Verbindung
- pg_fetch_array() - Liefert eine Zeile als Array
- pg_fetch_object() - Liefert einen Datensatz als Objekt
- pg_num_rows() - Gibt die Anzahl der Zeilen in einem Abfrageergebnis zurück
- pg_affected_rows() - Gibt die Anzahl betroffener Datensätze (Tupel) zurück

# pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — Sendet ein Kommando zum Server und wartet seine Ausführung ab. Getrennt vom SQL-Kommando können dabei Parameter übergeben werden

### Beschreibung

function pg_query_params(PgSql\Connection `$connection` = ?, string `$query`, array `$params`): PgSql\Result|false

Sendet ein Kommando zum Server und wartet seine Ausführung ab. Getrennt vom SQL-Kommando können dabei Parameter übergeben werden.

pg_query_params() ist ähnlich wie pg_query(), bietet aber zusätzlich die Möglichkeit, Parameterwerte ausserhalb des SQL-Kommandos separat zu übergeben.

Falls irgendwelche Parameter übergeben wurden, werden diese in `query` als $1, $2 usw. referenziert. Der gleiche Parameter darf mehrmals in `query` auftauchen; in diesem Fall wird der selbe Wert verwendet. Im Array `params` werden die aktuellen Parameterwerte übergeben. Der Wert `null` in diesem Array repräsentiert den SQL-Wert `NULL`.

Der Hauptvorteil von pg_query_params() gegenüber pg_query() liegt darin, dass Parameterwerte vom SQL-Kommando getrennt übergeben werden können und damit das fehlerträchtige und lästige Maskieren und Setzen von Anführungszeichen vermieden werden kann. Im Unterschied zu pg_query() ist bei pg_query_params() nur ein einziges SQL-Kommando erlaubt. (Es können auch Semikolons enthalten sein, aber nicht mehr als ein nichtleeres Kommando.)

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`query`

  Die parametrisierte Abfrage. Diese darf nur ein einziges SQL-Kommando enthalten (mehrere Kommandos, durch Semikolon getrennt, sind nicht zulässig). Falls Parameter übergeben werden, werden sie als $1, $2, ... referenziert.

  Anwenderdaten sollten immer als Parameter übergeben werden, und nicht in die Abfragezeichenkette interpoliert werden, wo sie mögliche SQL-Injection-Angriffsvektoren bilden und Bugs einführen, wenn die zu behandelnden Daten Anführungszeichen enthalten. Wenn aus irgendeinem Grund Parameter nicht verwendet werden können, ist sicherzustellen, dass Werte ordnungsgemäß maskiert sind.

`params`

  Ein Array mit Parameterwerten, mit denen die Platzhalter $1, $2 usw. in der ursprünglichen vorbereiteten Abfrage ersetzt werden. Die Anzahl der Elemente dieses Arrays muss mit der Anzahl der Platzhalter übereinstimmen.

  Werte, die für `bytea` Felder vorgesehen sind, werden nicht als Parameter unterstützt. Statt dessen sind pg_escape_bytea() oder die Funktionen für große Objekte zu verwenden.

### Rückgabewerte

Bei Erfolg wird eine PgSql\Result-Instanz zurückgegeben. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PgSql\Result-Instanz zurück; vorher wurde eine Ressource zurückgegeben.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_query_params()-Beispiel

    <?php
    // Verbindung zu einer Datenbank namens "mary" aufbauen
    $dbconn = pg_connect("dbname=mary");

    // Alle Shops mit dem Namen Joe's Widgets finden. Beachten Sie, dass es
    // nicht nötig ist, den String "Joe's Widgets" zu maskieren.
    $result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));

    // Vergleich mit pg_query
    $str = pg_escape_string("Joe's Widgets");
    $result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");

    ?>

### Siehe auch

- pg_query() - Führt eine Abfrage aus

# pg_result_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_error — Liefert die mit der Ergebniskennung verknüpfte Fehlermeldung

### Beschreibung

function pg_result_error(PgSql\Result `$result`): string|false

pg_result_error() gibt alle Fehlermeldungen zurück, die mit der `result`-Instanz verknüpft ist. Aus diesem Grund bekommt man mit pg_result_error() viel eher eine korrekte Fehlermeldung als mit pg_last_error().

Mit pg_result_error_field() bekommt man weitaus genauere Informationen über Fehler als mit pg_result_error().

Weil pg_query() bei einem Fehlschlag nur `false` zurückgibt, muss man pg_send_query() und pg_get_result() benutzen, um die Ergebniskennung zu erhalten.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

### Rückgabewerte

Gibt einen string zurück. Ist kein Fehler aufgetreten, ist dies eine leere Zeichenkette. Falls ein Fehler mit dem Parameter `result` verknüpft ist wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_result_error()-Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte nicht verbinden");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Siehe auch

- pg_result_error_field() - Liefert den Inhalt eines bestimmtes Feldes zu einer Fehlermeldung
- pg_query() - Führt eine Abfrage aus
- pg_send_query() - Sendet eine asynchrone Abfrage
- pg_get_result() - Liefert asynchrone Abfrageergebnisse
- pg_last_error() - Liefert die letzte Fehlermeldung einer Verbindung
- pg_last_notice() - Liefert die letzte NOTICE-Meldung des PostgreSQL-Servers

# pg_result_error_field

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_result_error_field — Liefert den Inhalt eines bestimmtes Feldes zu einer Fehlermeldung

### Beschreibung

function pg_result_error_field(PgSql\Result `$result`, int `$field_code`): string|false|null

pg_result_error_field() gibt ein Feld der ausführlichen Fehlerbeschreibung zurück, die mit der `result`-Instanz verbunden ist. Das gewünschte Feld wird im Parameter `field_code` übergeben.

Da pg_query() und pg_query_params() `false` zurückgeben, wenn eine Abfrage fehlschlägt, müssen Sie pg_send_query() und pg_get_result() benutzen, um eine Ergebniskennung zu erhalten.

Falls Sie weitergehende Informationen über einen aufgetretenen Fehler bei pg_query() brauchen, können Sie pg_set_error_verbosity() oder pg_last_error() aufrufen und deren Ergebnisse analysieren.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`field_code`

  Mögliche Werte von `field_code` sind: `PGSQL_DIAG_SEVERITY`, `PGSQL_DIAG_SQLSTATE`, `PGSQL_DIAG_MESSAGE_PRIMARY`, `PGSQL_DIAG_MESSAGE_DETAIL`, `PGSQL_DIAG_MESSAGE_HINT`, `PGSQL_DIAG_STATEMENT_POSITION`, `PGSQL_DIAG_INTERNAL_POSITION`, `PGSQL_DIAG_INTERNAL_QUERY`, `PGSQL_DIAG_CONTEXT`, `PGSQL_DIAG_SOURCE_FILE`, `PGSQL_DIAG_SOURCE_LINE` und `PGSQL_DIAG_SOURCE_FUNCTION`.

### Rückgabewerte

Ein string, der den Inhalt des Fehlerfeldes enthält, oder `null`, falls das Feld nicht existiert. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_result_error_field()-Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte nicht verbinden.");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      $res1 = pg_get_result($dbconn);
      echo pg_result_error_field($res1, PGSQL_DIAG_SQLSTATE);
    ?>

### Siehe auch

- pg_result_error() - Liefert die mit der Ergebniskennung verknüpfte Fehlermeldung

# pg_result_memory_size

(PHP 8 >= 8.4.0)

pg_result_memory_size — Returns the amount of memory allocated for a query result

### Beschreibung

function pg_result_memory_size(PgSql\Result `$result`): int

Returns the amount of memory, in bytes, allocated to the specified query result PgSql\Result instance. This value is the same amount that would be freed by pg_free_result().

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

### Rückgabewerte

Returns the memory amount in bytes.

### Beispiele

Beispiel #1 pg_result_memory_size() example

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, 'SELECT 1');

    $size = pg_result_memory_size($res);

    var_dump($size);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(3288)

### Siehe auch

- pg_free_result() - Gibt den durch Ergebnisse belegten Speicher frei

# pg_result_seek

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_result_seek — Setzt den internen Datensatzzeiger auf die angegebene Position in einem Abfrageergebnis

### Beschreibung

function pg_result_seek(PgSql\Result `$result`, int `$row`): bool

pg_result_seek() setzt den internen Datensatzzeiger auf die angegebene Zeile in einer `result`-Instanz.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`row`

  Die Zeile in der PgSql\Result-Instanz, auf die der interne Datensatzzeiger gesetzt werden soll. Die Zeilennummern beginnen bei null.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_result_seek() Beispiel

    <?php

    // Zur Datenbank verbinden
    $conn = pg_pconnect("dbname=publisher");

    // Eine Abfrage ausführen
    $result = pg_query($conn, "SELECT author, email FROM authors");

    // Den Zeiger auf die dritte Zeile setzen (vorausgesetzt, es gibt 3 Zeilen)
    pg_result_seek($result, 2);

    // Die dritte Zeile lesen
    $row = pg_fetch_row($result);

    ?>

### Siehe auch

- pg_fetch_row() - Liefert einen Datensatz als numerisches Array
- pg_fetch_assoc() - Liefert eine Zeile als assoziatives Array
- pg_fetch_array() - Liefert eine Zeile als Array
- pg_fetch_object() - Liefert einen Datensatz als Objekt
- pg_fetch_result() - Liefert Werte aus einer Ergebnisinstanz

# pg_result_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_status — Liefert den Status eines Abfrageergebnisses

### Beschreibung

function pg_result_status(PgSql\Result `$result`, int `$mode` = `PGSQL_STATUS_LONG`): string|int

pg_result_status() gibt den Status einer PgSql\Result-Instanz zurück oder das mit dem Ergebnis verknüpfte PostgreSQL-Kommandoabschluss-Tag.

### Parameter-Liste

`result`

  Eine PgSql\Result-Instanz, die von pg_query(), pg_query_params() oder pg_execute() (unter anderen) zurückgegeben wurde.

`mode`

  Entweder `PGSQL_STATUS_LONG`, um die Statusnummer von `result` zu erhalten, oder `PGSQL_STATUS_STRING`, um das PostgreSQL-Kommando-Tag für `result` zu erhalten. Falls nichts angegeben wurde, wird der Vorgabewert `PGSQL_STATUS_LONG` zurückgegeben.

### Rückgabewerte

Mögliche Rückgabewerte sind `PGSQL_EMPTY_QUERY`, `PGSQL_COMMAND_OK`, `PGSQL_TUPLES_OK`, `PGSQL_TUPLES_CHUNK`, `PGSQL_COPY_OUT`, `PGSQL_COPY_IN`, `PGSQL_BAD_RESPONSE`, `PGSQL_NONFATAL_ERROR` und `PGSQL_FATAL_ERROR`, falls `PGSQL_STATUS_LONG` angegeben wurde. Anderenfalls wird ein String zurückgegeben, der das PostgreSQL-Kommando-Tag enthält.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `result` erwartet nun eine PgSql\Result-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_result_status()-Beispiel

    <?php

    // Mit der Datenbank verbinden
    $conn = pg_pconnect("dbname=publisher");

    // Eine Abfrage ausführen
    $result = pg_query($conn, "COPY authors FROM STDIN;");

    // Den Status des Abfrageergebnisses holen
    $status = pg_result_status($result);

    // Den Status ermitteln
    if ($status == PGSQL_COPY_IN)
       echo "Copy begonnen.";
    else
       echo "Copy fehlgeschlagen.";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Copy begonnen.

### Siehe auch

- pg_connection_status() - Gibt den Verbindungsstatus zurück

# pg_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_select — Wählt Datensätze aus

### Beschreibung

function pg_select(
PgSql\Connection `$connection`,
string `$table_name`,
array `$conditions` = [],
int `$flags` = `PGSQL_DML_EXEC`,
int `$mode` = `PGSQL_ASSOC`
): array|string|false

pg_select() wählt die Datensätze aus der Tabelle `table_name` aus, die den Elementen (`field=>value`) in `conditions` entsprechen. Wenn die Abfrage erfolgreich war, wird ein assoziatives Array mit allen Datensätzen und Werten aus `table_name` zurückgegeben, die mit den Datensätzen und Werten in `conditions` identisch sind.

Falls `flags` gesetzt ist, wird pg_convert() mit den angegebenen Flags auf `conditions` angewendet.

Wenn `mode` gesetzt ist, ist der Rückgabewert bei `PGSQL_NUM` ein Array, bei `PGSQL_ASSOC` (Standard) ein assoziatives Array und bei `PGSQL_BOTH` beides.

Standardmäßig übergibt pg_select() Rohwerte. Die Werte müssen entweder maskiert werden oder es muss die Option PGSQL_DML_ESCAPE angegeben werden. PGSQL_DML_ESCAPE maskiert Parameter und Bezeichner und setzt sie in Anführungszeichen. Daher muss bei Tabellen- und Spaltennamen zwischen Groß- und Kleinschreibung unterschieden werden.

Es ist zu beachten, dass weder die Maskierung noch eine vorbereitete Abfrage LIKE-Abfragen, JSON, Array, Regex usw. schützen können. Diese Parameter sollten im Kontext behandelt werden, d. h. Werte maskieren und validieren.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`table_name`

  Der Name der Tabelle, aus der die Datensätze ausgewählt werden.

`conditions`

  Ein Array, dessen Schlüssel Feldnamen von `table_name` sind und dessen Werte mit den entsprechenden Werten in `table_name` übereinstimmen müssen, damit der Datensatz zurückgegeben werden kann. Seit PHP 8.4.0 gelten keine Bedingungen mehr, wenn ein leeres Array angegeben wird. Zuvor schlug die Funktion fehl, wenn das Argument für `conditions` leer war.

`flags`

  Eine beliebige Kombination aus `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` und `PGSQL_DML_STRING`. Falls `PGSQL_DML_STRING` in den `options` enthalten ist, wird der Abfragestring zurückgegeben. Werden `PGSQL_DML_NO_CONV` oder `PGSQL_DML_ESCAPE` angegeben, wird pg_convert() intern nicht aufgerufen.

`mode`

  Eine beliebige Kombination aus `PGSQL_ASSOC`, `PGSQL_NUM` und `PGSQL_BOTH`. Wenn `PGSQL_ASSOC` gesetzt ist, ist der Rückgabewert ein assoziatives Array, bei `PGSQL_NUM` ist es ein Array, und bei `PGSQL_BOTH` ist es ein sowohl assoziativ als auch numerisch indiziertes Array.

### Rückgabewerte

Gibt einen String zurück, falls `PGSQL_DML_STRING` im Parameter `flags` übergeben wurde, andernfalls wird bei Erfolg ein Array zurückgegeben. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `conditions` ist nun optional.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
7.1.0 | Der Parameter `mode` wurde hinzugefügt.

### Beispiele

Beispiel #1 pg_select()-Beispiel

    <?php
    $db = pg_connect('dbname=foo');
    // Das ist einigermaßen sicher, da alle Werte maskiert werden.
    // Allerdings unterstützt PostgreSQL JSON/Array. Diese sind nicht
    // sicher, da sie Abfragen weder maskieren noch vorbereiten.
    $rec = pg_select($db, 'post_log', $_POST, PG_DML_ESCAPE);
    if ($rec) {
        echo "Datensätze ausgewählt\n";
        var_dump($rec);
    } else {
        echo "Falsche Eingabe\n";
    }
    ?>

### Siehe auch

- pg_convert() - Konvertiert die Werte eines assoziativen Arrays in die für SQL-Anweisungen passende Form

# pg_send_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_execute — Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern auszuführen, ohne auf die Ergebnisse zu warten

### Beschreibung

function pg_send_execute(PgSql\Connection `$connection`, string `$statement_name`, array `$params`): int|bool

Sendet eine Aufforderung an den Server, eine vorbereitete Anfrage mit den übergebenen Parametern auszuführen, ohne auf die Ergebnisse zu warten.

Dies ist ähnlich wie die Funktion pg_send_query_params(), aber das auszuführende Kommando wird statt durch einen Abfragestring durch den Namen einer zuvor vorbereiteten Anweisung angegeben. Die Parameter der Funktion werden genauso verarbeitet, wie bei der Funktion pg_execute() beschrieben und genau wie diese kann pg_send_execute() nicht mit PostgreSQL-Versionen vor 7.4 benutzt werden.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`statement_name`

  Der Name der auszuführenden vorbereiteten Anweisung. Falls "" angegeben wird, wird eine unbenannte Abfrage ausgeführt. Der Name muss zuvor mit pg_prepare(), pg_send_prepare() oder dem SQL-Kommando `PREPARE` definiert worden sein.

`params`

  Ein Array mit Parameterwerten, mit denen die Platzhalter $1, $2 usw. in der ursprünglichen vorbereiteten Anweisung ersetzt werden. Die Anzahl der Elemente dieses Arrays muss mit der Anzahl der Platzhalter übereinstimmen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück und `false` oder `0`, falls ein Fehler auftrat. Benutzen Sie pg_get_result(), um das Abfrageergebnis zu erhalten.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Die Verwendung von pg_send_execute():

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte nicht verbinden");

      // Die Abfrage vorbereiten
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
        $res1 = pg_get_result($dbconn);
      }

      // Die vorbereitete Abfrage ausführen. Beachten Sie, dass es
      // nicht nötig ist, den String "Joe's Widgets" zu maskieren
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Dieselbe vorbereitete Abfrage, diesmal mit einem anderen Parameter.
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### Siehe auch

- pg_prepare() - Sendet eine Aufforderung an den Server, eine vorbereitete Anfrage mit den übergebenen Parametern zu erzeugen und wartet auf ihre Beendigung
- pg_send_prepare() - Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern zu erzeugen, ohne auf ihre Beendigung zu warten
- pg_execute() - Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis

# pg_send_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_prepare — Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern zu erzeugen, ohne auf ihre Beendigung zu warten

### Beschreibung

function pg_send_prepare(PgSql\Connection `$connection`, string `$statement_name`, string `$query`): int|bool

Sendet eine Aufforderung an den Server, eine vorbereitete Anfrage mit den übergebenen Parametern zu erzeugen, ohne auf ihre Beendigung zu warten.

Dies ist eine asynchrone Version von pg_prepare(): Sie gibt `true` zurück, falls es möglich war, die Aufforderung abzusenden, ansonsten `false`. Nach einem erfolgreichen Absenden rufen Sie pg_get_result() auf, um festzustellen, ob der Server die vorbereitete Abfrage erfolgreich erzeugt hat. Die Parameter der Funktion werden genauso verarbeitet, wie bei der Funktion pg_prepare() beschrieben und genau wie diese kann pg_send_prepare() nicht mit PostgreSQL Versionen vor 7.4 benutzet werden.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`statement_name`

  Der Name der vorbereiteten Abfrage. Dieser Name muss in der aktuellen Datenbanksitzung eindeutig sein. Falls "" angegeben wird, wird eine unbenannte Abfrage erzeugt, die alle zuvor definierten unbenannten Abfragen überschreibt.

`query`

  Die parametrisierte Abfrage. Diese darf nur ein einziges SQL-Kommando enthalten (mehrere Kommandos, durch Semikolon getrennt, sind nicht zulässig). Falls Parameter übergeben werden, werden sie als $1, $2, ... referenziert.

### Rückgabewerte

Gibt bei Erfolg `true` zurück und `false` oder `0`, falls ein Fehler auftrat. Benutzen Sie pg_get_result(), um das Abfrageergebnis zu erhalten.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_send_prepare() Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte nicht verbinden");

      // Eine Abfrage vorbereiten
      if (!pg_connection_busy($dbconn)) {
        pg_send_prepare($dbconn, "my_query", 'SELECT * FROM shops WHERE name = $1');
        $res1 = pg_get_result($dbconn);
      }

      // die vorbereitete Abfrage ausführen. Beachten Sie, dass es
      // nicht nötig ist, den String "Joe's Widgets" zu maskieren
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Joe's Widgets"));
        $res2 = pg_get_result($dbconn);
      }

      // Dieselbe vorbereitete Abfrage, diesmal mit einem anderen Parameter.
      if (!pg_connection_busy($dbconn)) {
        pg_send_execute($dbconn, "my_query", array("Clothes Clothes Clothes"));
        $res3 = pg_get_result($dbconn);
      }

    ?>

### Siehe auch

- pg_connect() - Öffnet eine PostgreSQL-Verbindung
- pg_pconnect() - Öffnet eine persistente PostgreSQL-Verbindung
- pg_execute() - Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis
- pg_send_execute() - Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern auszuführen, ohne auf die Ergebnisse zu warten
- pg_send_query_params() - Sendet ein Kommando und separate Parameter zum Server, ohne auf die Rückgabe der Ergebnisse zu warten

# pg_send_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_send_query — Sendet eine asynchrone Abfrage

### Beschreibung

function pg_send_query(PgSql\Connection `$connection`, string `$query`): int|bool

pg_send_query() sendet eine oder mehrere asynchrone Abfragen über die Verbindung `connection`. Im Unterschied zu pg_query() können hier mehrere Abfragen auf einmal an PostgreSQL gesendet und die Ergebnisse nacheinander mit pg_get_result() geholt werden.

Die Ausführung eines Skripts wird während der Abarbeitung der Anfragen nicht blockiert. Benutzen Sie die Funktion pg_connection_busy(), um zu prüfen, ob die Verbindung gerade benutzt wird (z. B. ob gerade eine Abfrage ausgeführt wird). Mit der Funktion pg_cancel_query() können Abfragen gelöscht werden.

Obwohl man mehrere Abfragen auf einmal an den Server senden kann, können die Abfragen nicht über eine gerade benutzte Verbindung geschickt werden. Falls eine Abfrage gesendet wird, während die Verbindung benutzt wird, wird abgewartet, bis die letzte Abfrage fertig ist, und alle Ergebnisse werden verworfen.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`query`

  Das oder die SQL-Anweisung(en), die ausgeführt werden sollen.

  Daten innerhalb der Abfrage sollten ordnungsgemäß maskiert sein.

### Rückgabewerte

Gibt bei Erfolg `true` zurück und `false` oder `0`, falls ein Fehler auftrat. Benutzen Sie pg_get_result() um die Abfrageergebnisse zu ermitteln.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_send_query()-Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Verbindungsaufbau fehlgeschlagen");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from authors; select count(*) from authors;");
      }

      $res1 = pg_get_result($dbconn);
      echo "Der erste Aufruf von pg_get_result(): $res1\n";
      $rows1 = pg_num_rows($res1);
      echo "$res1 hat $rows1 Zeilen\n\n";

      $res2 = pg_get_result($dbconn);
      echo "Der zweite Aufruf von pg_get_result(): $res2\n";
      $rows2 = pg_num_rows($res2);
      echo "$res2 hat $rows2 Zeilen\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Der erste Aufruf von pg_get_result(): Resource id #3
    Resource id #3 hat 3 Zeilen

    Der zweite Aufruf von pg_get_result(): Resource id #4
    Resource id #4 hat 1 Zeilen

### Siehe auch

- pg_query() - Führt eine Abfrage aus
- pg_cancel_query() - Löscht eine asynchrone Abfrage
- pg_get_result() - Liefert asynchrone Abfrageergebnisse
- pg_connection_busy() - Gibt den Status der Verbindung zurück (busy/not busy)

# pg_send_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_query_params — Sendet ein Kommando und separate Parameter zum Server, ohne auf die Rückgabe der Ergebnisse zu warten

### Beschreibung

function pg_send_query_params(PgSql\Connection `$connection`, string `$query`, array `$params`): int|bool

Sendet ein Kommando und separate Parameter zum Server ohne auf die Rückgabe der Ergebnisse zu warten.

Diese Funktion ist gleichwertig zu pg_send_query() mit dem Unterschied, dass Parameter für die Abfrage außerhalb des `query`-Strings übergeben werden können. Diese Parameter werden genauso verarbeitet, wie bei pg_query_params() beschrieben. Genau wie pg_query_params() kann diese Funktion nur mit PostgreSQL ab der Version 7.4 verwendet werden und es darf nur ein einziges Kommando im Abfragestring enthalten sein.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`query`

  Die parametrisierte Abfrage. Diese darf nur ein einziges SQL-Kommando enthalten (mehrere Kommandos, durch Semikolon getrennt, sind nicht zulässig). Falls Parameter übergeben werden, werden sie als $1, $2, ... referenziert.

`params`

  Ein Array mit Parameterwerten, mit denen die Platzhalter $1, $2 usw. in der ursprünglichen vorbereiteten Abfrage ersetzt werden. Die Anzahl der Elemente dieses Arrays muss mit der Anzahl der Platzhalter übereinstimmen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück und `false` oder `0`, falls ein Fehler auftrat. Benutzen Sie pg_get_result(), um das Abfrageergebnis zu erhalten.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_send_query_params()-Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte nicht verbinden");

      // Die Parameter benutzen: Beachten Sie, dass es
      // nicht nötig ist, diese zu maskieren.
      pg_send_query_params($dbconn, 'select count(*) from authors where city = $1', array('Perth'));

      // Zum Vergleich: die Funktion pg_send_query
      $str = pg_escape_string('Perth');
      pg_send_query($dbconn, "select count(*) from authors where city = '{$str}'");
    ?>

### Siehe auch

- pg_send_query() - Sendet eine asynchrone Abfrage

# pg_set_chunked_rows_size

(PHP 8 >= 8.4.0)

pg_set_chunked_rows_size — Set the query results to be retrieved in chunk mode

### Beschreibung

function pg_set_chunked_rows_size(PgSql\Connection `$connection`, int `$size`): bool

Set the query results to be retrieved in chunk mode. The query results returned afterward will be divided into multiple chunks, each containing up to `size` rows. This function must be called before retrieving results with pg_get_result(). This function is only available when libpq is version 17 or higher.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`size`
  The number of rows to be retrieved in each chunk.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

If `size` is less than `1`, a ValueError will be thrown.

### Beispiele

Beispiel #1 pg_result_memory_size() example

    <?php

    $conn = pg_connect($conn_str);

    for ($i = 0; $i < 10; $i ++) {
      pg_query($conn, "INSERT INTO users DEFAULT VALUES");
    }

    pg_send_query($conn, "SELECT * FROM users");
    pg_set_chunked_rows_size($conn, 1);

    $result = pg_get_result($conn);
    var_dump(pg_num_rows($result));

    // No effect after the result is retrieved
    var_dump(pg_set_chunked_rows_size($conn, 10));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)
    bool(false)

### Siehe auch

- pg_get_result() - Liefert asynchrone Abfrageergebnisse
- pg_result_status() - Liefert den Status eines Abfrageergebnisses

# pg_set_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_set_client_encoding — Setzt die Kodierung des Clients

### Beschreibung

function pg_set_client_encoding(PgSql\Connection `$connection` = ?, string `$encoding`): int

pg_set_client_encoding() setzt die Kodierung des Clients und gibt bei Erfolg 0 zurück, anderenfalls -1.

PostgreSQL konvertiert Daten automatisch aus der Kodierung des Backends in die des Frontends.

> Hinweis:

> Diese Funktion ersetzt die Funktion pg_setclientencoding().

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`encoding`

  Die gewünschte Kodierung des Clients. Sie können aus den folgenden Kodierungen wählen: `SQL_ASCII`, `EUC_JP`, `EUC_CN`, `EUC_KR`, `EUC_TW`, `UNICODE`, `MULE_INTERNAL`, `LATINX` (X=1...9), `KOI8`, `WIN`, `ALT`, `SJIS`, `BIG5` or `WIN1250`.

  Welche Kodierungen genau verfügbar sind, hängt von der verwendeten PostgreSQL-Version ab. Schauen Sie daher im PostgreSQL-Handbuch, welche Kodierungen unterstützt werden.

### Rückgabewerte

Gibt bei Erfolg `0` zurück oder `-1` bei einem Fehler.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_set_client_encoding() Beispiel

    <?php

    $conn = pg_pconnect("dbname=publisher");
    if (!$conn) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    // Die Kodierung des Clients wird auf UNICODE gesetzt. Die Daten werden
    // automatisch aus der Kodierung des Backends nach UNICODE konvertiert.
    pg_set_client_encoding($conn, UNICODE);

    $result = pg_query($conn, "SELECT author, email FROM authors");
    if (!$result) {
      echo "Ein Fehler ist aufgetreten.\n";
      exit;
    }

    // UTF-8 Daten ausgeben
    while ($row = pg_fetch_row($result)) {
      echo "Autor: $row[0]  E-mail: $row[1]";
      echo "<br />\n";
    }

    ?>

### Siehe auch

- pg_client_encoding() - Liefert die Kodierung des Clients

# pg_set_error_context_visibility

(PHP 8 >= 8.3.0)

pg_set_error_context_visibility — Determines the visibility of the context's error messages returned by pg_last_error() and pg_result_error()

### Beschreibung

function pg_set_error_context_visibility(PgSql\Connection `$connection`, int `$visibility`): int

Determines the visibility of the context's error messages returned by pg_last_error() and pg_result_error()

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`visibility`

  The required visibility: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` or `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Rückgabewerte

The previous visibility level: `PGSQL_SHOW_CONTEXT_NEVER`, `PGSQL_SHOW_CONTEXT_ERRORS` or `PGSQL_SHOW_CONTEXT_ALWAYS`.

### Beispiele

Beispiel #1 pg_set_error_context_visibility() example

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Could not connect");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      pg_set_error_context_visibility($dbconn, PGSQL_SHOW_CONTEXT_ALWAYS);
      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Siehe auch

- pg_last_error() - Liefert die letzte Fehlermeldung einer Verbindung
- pg_result_error() - Liefert die mit der Ergebniskennung verknüpfte Fehlermeldung

# pg_set_error_verbosity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_set_error_verbosity — Bestimmt den Detaillierungsgrad von Fehlermeldungen, die von pg_last_error() und pg_result_error() zurückgegeben werden

### Beschreibung

function pg_set_error_verbosity(PgSql\Connection `$connection` = ?, int `$verbosity`): int|false

Bestimmt den Detaillierungsgrad von Fehlermeldungen, die von pg_last_error() und pg_result_error() zurückgegeben werden.

pg_set_error_verbosity() setzt einen neuen Modus für Fehlermeldungen und gibt die zuvor gesetzte Einstellung zurück. Im Modus `PGSQL_ERRORS_TERSE` enthalten die Meldungen nur Angaben über den Detaillierungsgrad, einen Kurztext, sowie die Position des Fehlers. Dies passt normalerweise in eine Zeile. Im Standard-Modus, `PGSQL_ERRORS_DEFAULT`, wird das obige samt aller Einzelheiten, Hinweise oder Kontextfelder des Fehlers ausgegeben (was mehrere Zeilen in Anspruch nehmen kann). Der Modus `PGSQL_ERRORS_VERBOSE` schließt alle verfügbaren Felder ein. Eine Änderung des Detaillierungsgrads hat keine Auswirkung auf Meldungen bereits existierender Ergebnisse, sondern nur auf die, die danach erzeugt wurden.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` nicht angegeben wurde, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`verbosity`

  Der gewünschte Detaillierungsgrad: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` oder `PGSQL_ERRORS_VERBOSE`.

### Rückgabewerte

Der vorher eingestellte Detaillierungsgrad: `PGSQL_ERRORS_TERSE`, `PGSQL_ERRORS_DEFAULT` oder `PGSQL_ERRORS_VERBOSE`, oder `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_set_error_verbosity() Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte nicht verbinden");

      if (!pg_connection_busy($dbconn)) {
          pg_send_query($dbconn, "select * from doesnotexist;");
      }

      pg_set_error_verbosity($dbconn, PGSQL_ERRORS_VERBOSE);
      $res1 = pg_get_result($dbconn);
      echo pg_result_error($res1);
    ?>

### Siehe auch

- pg_last_error() - Liefert die letzte Fehlermeldung einer Verbindung
- pg_result_error() - Liefert die mit der Ergebniskennung verknüpfte Fehlermeldung

# pg_socket

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_socket — Get a read only handle to the socket underlying a PostgreSQL connection

### Beschreibung

function pg_socket(PgSql\Connection `$connection`): resource|false

pg_socket() returns a read only resource corresponding to the socket underlying the given PostgreSQL connection.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

A socket resource on successBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

# pg_socket_poll

(PHP 8 >= 8.4.0)

pg_socket_poll — Poll a PostgreSQL connection socket for read/write readiness

### Beschreibung

function pg_socket_poll(
resource `$socket`,
int `$read`,
int `$write`,
int `$timeout` = -1
): int

Polls a PostgreSQL connection socket for read and/or write readiness. The socket can be obtained using pg_socket(). This function is useful for implementing non-blocking, asynchronous query workflows.

### Parameter-Liste

`socket`
  A socket resource obtained from pg_socket().
`read`
  Whether to check for read readiness. Pass `1` to check, `0` to skip.
`write`
  Whether to check for write readiness. Pass `1` to check, `0` to skip.
`timeout`
  The maximum number of milliseconds to wait. Pass `-1` to wait indefinitely, or `0` to not wait at all.

### Rückgabewerte

Returns a positive value if the socket is ready, `0` if the timeout was reached, or `-1` on error.

### Siehe auch

- pg_socket() - Get a read only handle to the socket underlying a PostgreSQL connection
- pg_consume_input() - Reads input on the connection
- pg_send_query() - Sendet eine asynchrone Abfrage

# pg_trace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_trace — Ermöglicht die Ablaufverfolgung einer Verbindung

### Beschreibung

function pg_trace(
string `$filename`,
string `$mode` = "w",
?PgSql\Connection `$connection` = `null`,
int `$trace_mode` = 0
): bool

pg_trace() ermöglicht die Protokollierung der frontend/backend Kommunikation in eine Datei, die durch den Pfadnamen `pathname` bestimmt wurde. Um die Ergebnisse ganz zu verstehen, sollte man sich mit den Interna des PostgreSQL-Kommunikationsprotokolls auskennen.

Für diejenigen, die sich damit nicht auskennen kann es trotzdem hilfreich sein, um Fehler in Abfragen zu finden, die an den Server gesendet wurden. Beispielsweise können Sie das Kommando grep '^To backend' trace.log eingeben und schauen, welche Abfrage gerade an den PostgreSQL Server geschickt wurde. Weitere Informationen finden Sie in der » PostgreSQL Documentation.

### Parameter-Liste

`filename`

  Der vollständige Pfad- und Dateiname der Datei, in die das Ablauf-Protokoll geschrieben werden soll. Genau wie bei fopen().

`mode`

  Optional kann ein Zugriffsmodus übergeben werden, genauso wie bei fopen().

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

`trace_mode`

  Ein optionaler Modus für die Ablaufverfolgung mit den Konstanten `PGSQL_TRACE_SUPPRESS_TIMESTAMPS` und `PGSQL_TRACE_REGRESS_MODE`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | `trace_mode` wurde hinzugefügt.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_trace()-Beispiel

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Jetzt enthält  /tmp/trace.log die Kommunikation mit dem Server
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Siehe auch

- fopen() - Öffnet eine Datei oder URL
- pg_untrace() - Beendet die Ablaufverfolgung einer PostgreSQL-Verbindung

# pg_transaction_status

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_transaction_status — Gibt den aktuellen Transaktionsstatus des Servers zurück

### Beschreibung

function pg_transaction_status(PgSql\Connection `$connection`): int

Gibt den aktuellen Transaktionsstatus des Servers zurück.

Achtung

Die Funktion pg_transaction_status() gibt ungültige Ergebnisse zurück, wenn sie für einen PostgreSQL-Server der Version 7.3 aufgerufen wird, bei dem der Parameter `autocommit` auf off gesetzt ist. Die serverseitige Eigenschaft autocommit ist veraltet und existiert in den neueren PostgreSQL-Versionen nicht mehr.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

### Rückgabewerte

Mögliche Stati sind: `PGSQL_TRANSACTION_IDLE` (zur Zeit untätig), `PGSQL_TRANSACTION_ACTIVE` (ein Kommando wird abgearbeitet), `PGSQL_TRANSACTION_INTRANS` (untätig, aber innerhalb eines gültigen Transaktionsblocks) oder `PGSQL_TRANSACTION_INERROR` (untätig, innerhalb einer fehlgeschlagenen Transaktion). `PGSQL_TRANSACTION_UNKNOWN` wird zurückgegeben, falls eine Transaktion ungültig ist. `PGSQL_TRANSACTION_ACTIVE` wird nur dann zurückgegeben, wenn eine Abfrage zum Server gesendet wurde und noch nicht fertig abgearbeitet ist.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_transaction_status()-Beispiel

    <?php
      $dbconn = pg_connect("dbname=publisher") or die("Konnte nicht verbinden");
      $stat = pg_transaction_status($dbconn);
      if ($stat === PGSQL_TRANSACTION_UNKNOWN) {
          echo 'Verbindung ist ungültig';
      } else if ($stat === PGSQL_TRANSACTION_IDLE) {
          echo 'Verbindung ist zur Zeit untätig';
      } else {
          echo 'Verbindung meldet eine Transaktion';
      }
    ?>

# pg_tty

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_tty — Liefert den TTY-Namen für die Verbindung

### Beschreibung

function pg_tty(?PgSql\Connection `$connection` = `null`): string

pg_tty() gibt den TTY-Namen zurück, an den Debug-Meldungen der übergebenen `connection` gesendet werden.

> Hinweis:

> pg_tty() ist überflüssig geworden, da der Server TTY-Einstellungen ignoriert. Wegen der Abwärtskompatibilität bleibt die Funktion dennoch erhalten.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Ein string, der die TTY-Debugmeldungen für die `connection` enthält.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_tty()-Beispiel

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       print "TTY Debugmeldung des Servers: " . pg_tty($pgsql_conn) . "<br/>\n";
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

# pg_unescape_bytea

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_unescape_bytea — Entfernt Maskierungen für den Typ bytea

### Beschreibung

function pg_unescape_bytea(string `$string`): string

pg_unescape_bytea() entfernt Maskierungen von Daten des PostgreSQL-Typs bytea. Zurückgegeben wird ein String ohne Maskierungen, der möglicherweise Binärdaten enthält.

> Hinweis:

> Wenn Daten vom Typ bytea mit `SELECT` ausgewählt werden, gibt PostgreSQL Bytewerte als Oktalzahlen zurück, denen ein '\' vorangestellt ist (z. B. \032). Benutzer müssen diese Werte manuell in ein binäres Format konvertieren.

### Parameter-Liste

`string`

  Ein String, der Daten vom PostgreSQL-Typ bytea enthält, die in einen PHP-Binärstring konvertiert werden.

### Rückgabewerte

Ein String, der die unmaskierten Daten enthält.

### Beispiele

Beispiel #1 pg_unescape_bytea()-Beispiel

    <?php
      // Zur Datenbank verbinden
      $dbconn = pg_connect('dbname=foo');

      // Die Daten vom Typ  bytea holen
      $res = pg_query("SELECT data FROM gallery WHERE name='Pine trees'");
      $raw = pg_fetch_result($res, 'data');

      // In Binärdaten konvertieren und an den Browser senden
      header('Content-type: image/jpeg');
      echo pg_unescape_bytea($raw);
    ?>

### Siehe auch

- pg_escape_bytea() - Maskiert Zeichenketten zum Einfügen in ein Feld vom Typ bytea
- pg_escape_string() - Maskiert einen String für Abfragen

# pg_untrace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_untrace — Beendet die Ablaufverfolgung einer PostgreSQL-Verbindung

### Beschreibung

function pg_untrace(?PgSql\Connection `$connection` = `null`): true

Beendet die Ablaufverfolgung, die mit pg_trace() aktiviert wurde.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Der Rückgabewert ist nun `true` vorher war es bool.
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_untrace()-Beipiel

    <?php
    $pgsql_conn = pg_connect("dbname=mark host=localhost");

    if ($pgsql_conn) {
       pg_trace('/tmp/trace.log', 'w', $pgsql_conn);
       pg_query("SELECT 1");
       pg_untrace($pgsql_conn);
       // Jetzt ist die Ablaufverfolgung beendet
    } else {
       print pg_last_error($pgsql_conn);
       exit;
    }
    ?>

### Siehe auch

- pg_trace() - Ermöglicht die Ablaufverfolgung einer Verbindung

# pg_update

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_update — Aktualisiert eine Tabelle

### Beschreibung

function pg_update(
PgSql\Connection `$connection`,
string `$table_name`,
array `$values`,
array `$conditions`,
int `$flags` = `PGSQL_DML_EXEC`
): string|bool

pg_update() überschreibt alle Datensätze in `table_name`, die die Bedingungen in `conditions` erfüllen, mit den Werten aus `values`.

Falls `flags` angegeben wurde, wird pg_convert() mit den angegebenen Flags auf `values` angewendet.

Standardmäßig übergibt pg_update() Rohwerte. Die Werte müssen entweder maskiert werden oder das Flag `PGSQL_DML_ESCAPE` muss in `flags` angegeben werden. `PGSQL_DML_ESCAPE` maskiert Parameter und Bezeichner und setzt sie in Anführungszeichen. Daher muss bei Tabellen- und Spaltennamen zwischen Groß- und Kleinschreibung unterschieden werden.

Es ist zu beachten, dass weder die Maskierung noch eine vorbereitete Abfrage LIKE-Abfragen, JSON, Array, Regex usw. schützen können. Diese Parameter sollten im Kontext behandelt werden, d. h. Werte maskieren und validieren.

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz.

`table_name`

  Der Name der Tabelle, die aktualisiert werden soll.

`values`

  Ein Array, dessen Schlüssel Feldnamen von `table_name` sind und mit dessen Werten die entsprechenden Datensätze aktualisiert werden.

`conditions`

  Ein Array, dessen Schlüssel Feldnamen von `table_name` sind und dessen Werte die Bedingungen sind, die ein Datensatz erfüllen muss, um aktualisiert zu werden.

`flags`

  Jede Kombination aus `PGSQL_CONV_FORCE_NULL`, `PGSQL_DML_NO_CONV`, `PGSQL_DML_ESCAPE`, `PGSQL_DML_EXEC`, `PGSQL_DML_ASYNC` und `PGSQL_DML_STRING`. Falls `PGSQL_DML_STRING` in den `flags` enthalten ist, wird der Abfragestring zurückgegeben. Werden `PGSQL_DML_NO_CONV` oder `PGSQL_DML_ESCAPE` angegeben, wird pg_convert() intern nicht aufgerufen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. Gibt einen String zurück, falls `PGSQL_DML_STRING` mit dem Parameter `flags` übergeben wurde.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pg_update()-Beispiel

    <?php
      $db = pg_connect('dbname=foo');
      $data = array('field1'=>'AA', 'field2'=>'BB');
      // Das ist einigermaßen sicher, da alle Werte maskiert werden.
      // Allerdings unterstützt PostgreSQL JSON/Array. Diese sind nicht
      // sicher, da sie Abfragen weder maskieren noch vorbereiten.
      $res = pg_update($db, 'post_log', $_POST, $data);
      if ($res) {
          echo "Daten wurden aktualisiert: $res\n";
      } else {
          echo "Falsche Eingabe\n";
      }
    ?>

### Siehe auch

- pg_convert() - Konvertiert die Werte eines assoziativen Arrays in die für SQL-Anweisungen passende Form

# pg_version

(PHP 5, PHP 7, PHP 8)

pg_version — Liefert ein Array, das die Versionen von Client, Protokoll und Server enthält (falls verfügbar).

### Beschreibung

function pg_version(?PgSql\Connection `$connection` = `null`): array

pg_version() Gibt ein Array zurück, das die Versionen von Client, Protokoll und Server enthält.

Um genauere Informationen über den Server zu erhalten, verwenden Sie pg_parameter_status().

### Parameter-Liste

`connection`

  Eine PgSql\Connection-Instanz. Falls `connection` `null` ist, wird die Standardverbindung benutzt. Das ist die zuletzt mit pg_connect() oder pg_pconnect() aufgebaute Verbindung.

  Warnung

  Seit PHP 8.1.0 ist die Verwendung der Standardverbindung veraltet.

### Rückgabewerte

Gibt ein Array mit den Schlüsseln `client`, `protocol` und `server` zurück, in dem die entsprechenden Werte gespeichert sind, falls sie verfügbar sind.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `connection` erwartet nun eine PgSql\Connection-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `connection` ist jetzt nullbar.

### Beispiele

Beispiel #1 pg_version()-Beispiel

    <?php
      $dbconn = pg_connect("host=localhost port=5432 dbname=mary")
         or die("Verbindungsaufbau fehlgeschlagen");

      $v = pg_version($dbconn);

      echo $v['client'];
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    7.4

### Siehe auch

- pg_parameter_status() - Liefert den aktuellen Wert eines Parameters des Servers

## Inhaltsverzeichnis

- pg_affected_rows — Gibt die Anzahl betroffener Datensätze (Tupel) zurück
- pg_cancel_query — Löscht eine asynchrone Abfrage
- pg_change_password — Change a PostgreSQL user's password
- pg_client_encoding — Liefert die Kodierung des Clients
- pg_close — Schließt eine PostgreSQL-Verbindung
- pg_connect — Öffnet eine PostgreSQL-Verbindung
- pg_connect_poll — Poll the status of an in-progress asynchronous PostgreSQL connection attempt
- pg_connection_busy — Gibt den Status der Verbindung zurück (busy/not busy)
- pg_connection_reset — Setzt die Verbindung zurück und verbindet neu
- pg_connection_status — Gibt den Verbindungsstatus zurück
- pg_consume_input — Reads input on the connection
- pg_convert — Konvertiert die Werte eines assoziativen Arrays in die für SQL-Anweisungen passende Form
- pg_copy_from — Fügt Datensätze aus einem Array in eine Tabelle ein
- pg_copy_to — Kopiert eine Tabelle in ein Array
- pg_dbname — Liefert den Namen der Datenbank
- pg_delete — Löscht Datensätze
- pg_end_copy — Synchronisation mit dem PostgreSQL-Server
- pg_escape_bytea — Maskiert Zeichenketten zum Einfügen in ein Feld vom Typ bytea
- pg_escape_identifier — Escape an identifier for insertion into a text field
- pg_escape_literal — Escape a literal for insertion into a text field
- pg_escape_string — Maskiert einen String für Abfragen
- pg_execute — Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis
- pg_fetch_all — Liefert alle Zeilen eines Abfrageergebnisses als Array
- pg_fetch_all_columns — Gibt alle Werte einer bestimmten Spalte eines Abfrageergebnisses in einem Array zurück
- pg_fetch_array — Liefert eine Zeile als Array
- pg_fetch_assoc — Liefert eine Zeile als assoziatives Array
- pg_fetch_object — Liefert einen Datensatz als Objekt
- pg_fetch_result — Liefert Werte aus einer Ergebnisinstanz
- pg_fetch_row — Liefert einen Datensatz als numerisches Array
- pg_field_is_null — Prüft, ob ein Feld einen SQL-NULL-Wert enthält
- pg_field_name — Liefert den Namen eines Feldes
- pg_field_num — Liefert die Feldnummer des angegebenen Feldes
- pg_field_prtlen — Liefert die Länge des Feldes
- pg_field_size — Liefert die interne Größe des belegten Speichers für ein Feld
- pg_field_table — Gibt zu einem Feldnamen den Namen der Tabelle oder deren oid zurück, in der das Feld definiert ist
- pg_field_type — Liefert den Datentyp eines Feldes
- pg_field_type_oid — Liefert die ID des PostgreSQL-Datentyps (OID) eines Feldes
- pg_flush — Flush outbound query data on the connection
- pg_free_result — Gibt den durch Ergebnisse belegten Speicher frei
- pg_get_notify — Liefert eine SQL-NOTIFY-Nachricht
- pg_get_pid — Prüft die Datenbankverbindung
- pg_get_result — Liefert asynchrone Abfrageergebnisse
- pg_host — Liefert den Namen des Host, zu dem verbunden wurde
- pg_insert — Überträgt Werte aus einem Array in eine Tabelle
- pg_jit — Returns the JIT information of the server
- pg_last_error — Liefert die letzte Fehlermeldung einer Verbindung
- pg_last_notice — Liefert die letzte NOTICE-Meldung des PostgreSQL-Servers
- pg_last_oid — Liefert den Objektbezeichner (OID) des zuletzt eingefügten Datensatzes
- pg_lo_close — Schließt ein Large Object
- pg_lo_create — Erzeugt ein Large Object
- pg_lo_export — Exportiert ein Large Object in eine Datei
- pg_lo_import — Importiert ein Large Object aus einer Datei
- pg_lo_open — Öffnet ein Large Object
- pg_lo_read — Liest ein Large Object
- pg_lo_read_all — Liest ein ganzes Large Object und reicht es direkt an den Browser weiter
- pg_lo_seek — Setzt die Lese- oder Schreibposition in einem Large Object
- pg_lo_tell — Liefert die aktuelle Lese- oder Schreibposition in einem Large Object
- pg_lo_truncate — Truncates a large object
- pg_lo_unlink — Löscht ein Large Object
- pg_lo_write — Schreibt in ein Large Object
- pg_meta_data — Liefert die Metadaten einer Tabelle als Array
- pg_num_fields — Gibt die Anzahl der Felder in einem Abfrageergebnis zurück
- pg_num_rows — Gibt die Anzahl der Zeilen in einem Abfrageergebnis zurück
- pg_options — Liefert die Verbindungsoptionen der aktuellen Verbindung
- pg_parameter_status — Liefert den aktuellen Wert eines Parameters des Servers
- pg_pconnect — Öffnet eine persistente PostgreSQL-Verbindung
- pg_ping — Prüft die Datenbankverbindung
- pg_port — Liefert die Portnummer, über die die Verbindung aufgebaut wurde
- pg_prepare — Sendet eine Aufforderung an den Server, eine vorbereitete Anfrage mit den übergebenen Parametern zu erzeugen und wartet auf ihre Beendigung
- pg_put_copy_data — Send data to the server during a COPY operation
- pg_put_copy_end — Signal the completion of a COPY operation to the server
- pg_put_line — Sendet eine NULL-terminierte Zeichenkette zum PostgreSQL-Server
- pg_query — Führt eine Abfrage aus
- pg_query_params — Sendet ein Kommando zum Server und wartet seine Ausführung ab. Getrennt vom SQL-Kommando können dabei Parameter übergeben werden
- pg_result_error — Liefert die mit der Ergebniskennung verknüpfte Fehlermeldung
- pg_result_error_field — Liefert den Inhalt eines bestimmtes Feldes zu einer Fehlermeldung
- pg_result_memory_size — Returns the amount of memory allocated for a query result
- pg_result_seek — Setzt den internen Datensatzzeiger auf die angegebene Position in einem Abfrageergebnis
- pg_result_status — Liefert den Status eines Abfrageergebnisses
- pg_select — Wählt Datensätze aus
- pg_send_execute — Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern auszuführen, ohne auf die Ergebnisse zu warten
- pg_send_prepare — Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern zu erzeugen, ohne auf ihre Beendigung zu warten
- pg_send_query — Sendet eine asynchrone Abfrage
- pg_send_query_params — Sendet ein Kommando und separate Parameter zum Server, ohne auf die Rückgabe der Ergebnisse zu warten
- pg_set_chunked_rows_size — Set the query results to be retrieved in chunk mode
- pg_set_client_encoding — Setzt die Kodierung des Clients
- pg_set_error_context_visibility — Determines the visibility of the context's error messages returned by pg_last_error and pg_result_error
- pg_set_error_verbosity — Bestimmt den Detaillierungsgrad von Fehlermeldungen, die von pg_last_error und pg_result_error zurückgegeben werden
- pg_socket — Get a read only handle to the socket underlying a PostgreSQL connection
- pg_socket_poll — Poll a PostgreSQL connection socket for read/write readiness
- pg_trace — Ermöglicht die Ablaufverfolgung einer Verbindung
- pg_transaction_status — Gibt den aktuellen Transaktionsstatus des Servers zurück
- pg_tty — Liefert den TTY-Namen für die Verbindung
- pg_unescape_bytea — Entfernt Maskierungen für den Typ bytea
- pg_untrace — Beendet die Ablaufverfolgung einer PostgreSQL-Verbindung
- pg_update — Aktualisiert eine Tabelle
- pg_version — Liefert ein Array, das die Versionen von Client, Protokoll und Server enthält (falls verfügbar).

# The PgSql\Connection class

(PHP 8 >= 8.1.0)

## Einführung

A fully opaque class which replaces a `pgsql link` resource as of PHP 8.1.0.

## Klassenbeschreibung

namespace PgSql;
final class Connection {
}

# The PgSql\Result class

(PHP 8 >= 8.1.0)

## Einführung

A fully opaque class which replaces a `pgsql result` resource as of PHP 8.1.0.

## Klassenbeschreibung

namespace PgSql;
final class Result {
}

# The PgSql\Lob class

(PHP 8 >= 8.1.0)

## Einführung

A fully opaque class which replaces a `pgsql large object` resource as of PHP 8.1.0.

## Klassenbeschreibung

namespace PgSql;
final class Lob {
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Beispiele
  - Grundlegende Nutzung
  - Grundlegende Verwendung
- PostgreSQL-Funktionen
  - pg_affected_rows — Gibt die Anzahl betroffener Datensätze (Tupel) zurück
  - pg_cancel_query — Löscht eine asynchrone Abfrage
  - pg_change_password — Change a PostgreSQL user's password
  - pg_client_encoding — Liefert die Kodierung des Clients
  - pg_close — Schließt eine PostgreSQL-Verbindung
  - pg_connect — Öffnet eine PostgreSQL-Verbindung
  - pg_connect_poll — Poll the status of an in-progress asynchronous PostgreSQL connection attempt
  - pg_connection_busy — Gibt den Status der Verbindung zurück (busy/not busy)
  - pg_connection_reset — Setzt die Verbindung zurück und verbindet neu
  - pg_connection_status — Gibt den Verbindungsstatus zurück
  - pg_consume_input — Reads input on the connection
  - pg_convert — Konvertiert die Werte eines assoziativen Arrays in die für SQL-Anweisungen passende Form
  - pg_copy_from — Fügt Datensätze aus einem Array in eine Tabelle ein
  - pg_copy_to — Kopiert eine Tabelle in ein Array
  - pg_dbname — Liefert den Namen der Datenbank
  - pg_delete — Löscht Datensätze
  - pg_end_copy — Synchronisation mit dem PostgreSQL-Server
  - pg_escape_bytea — Maskiert Zeichenketten zum Einfügen in ein Feld vom Typ bytea
  - pg_escape_identifier — Escape an identifier for insertion into a text field
  - pg_escape_literal — Escape a literal for insertion into a text field
  - pg_escape_string — Maskiert einen String für Abfragen
  - pg_execute — Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis
  - pg_fetch_all — Liefert alle Zeilen eines Abfrageergebnisses als Array
  - pg_fetch_all_columns — Gibt alle Werte einer bestimmten Spalte eines Abfrageergebnisses in einem Array zurück
  - pg_fetch_array — Liefert eine Zeile als Array
  - pg_fetch_assoc — Liefert eine Zeile als assoziatives Array
  - pg_fetch_object — Liefert einen Datensatz als Objekt
  - pg_fetch_result — Liefert Werte aus einer Ergebnisinstanz
  - pg_fetch_row — Liefert einen Datensatz als numerisches Array
  - pg_field_is_null — Prüft, ob ein Feld einen SQL-NULL-Wert enthält
  - pg_field_name — Liefert den Namen eines Feldes
  - pg_field_num — Liefert die Feldnummer des angegebenen Feldes
  - pg_field_prtlen — Liefert die Länge des Feldes
  - pg_field_size — Liefert die interne Größe des belegten Speichers für ein Feld
  - pg_field_table — Gibt zu einem Feldnamen den Namen der Tabelle oder deren oid zurück, in der das Feld definiert ist
  - pg_field_type — Liefert den Datentyp eines Feldes
  - pg_field_type_oid — Liefert die ID des PostgreSQL-Datentyps (OID) eines Feldes
  - pg_flush — Flush outbound query data on the connection
  - pg_free_result — Gibt den durch Ergebnisse belegten Speicher frei
  - pg_get_notify — Liefert eine SQL-NOTIFY-Nachricht
  - pg_get_pid — Prüft die Datenbankverbindung
  - pg_get_result — Liefert asynchrone Abfrageergebnisse
  - pg_host — Liefert den Namen des Host, zu dem verbunden wurde
  - pg_insert — Überträgt Werte aus einem Array in eine Tabelle
  - pg_jit — Returns the JIT information of the server
  - pg_last_error — Liefert die letzte Fehlermeldung einer Verbindung
  - pg_last_notice — Liefert die letzte NOTICE-Meldung des PostgreSQL-Servers
  - pg_last_oid — Liefert den Objektbezeichner (OID) des zuletzt eingefügten Datensatzes
  - pg_lo_close — Schließt ein Large Object
  - pg_lo_create — Erzeugt ein Large Object
  - pg_lo_export — Exportiert ein Large Object in eine Datei
  - pg_lo_import — Importiert ein Large Object aus einer Datei
  - pg_lo_open — Öffnet ein Large Object
  - pg_lo_read — Liest ein Large Object
  - pg_lo_read_all — Liest ein ganzes Large Object und reicht es direkt an den Browser weiter
  - pg_lo_seek — Setzt die Lese- oder Schreibposition in einem Large Object
  - pg_lo_tell — Liefert die aktuelle Lese- oder Schreibposition in einem Large Object
  - pg_lo_truncate — Truncates a large object
  - pg_lo_unlink — Löscht ein Large Object
  - pg_lo_write — Schreibt in ein Large Object
  - pg_meta_data — Liefert die Metadaten einer Tabelle als Array
  - pg_num_fields — Gibt die Anzahl der Felder in einem Abfrageergebnis zurück
  - pg_num_rows — Gibt die Anzahl der Zeilen in einem Abfrageergebnis zurück
  - pg_options — Liefert die Verbindungsoptionen der aktuellen Verbindung
  - pg_parameter_status — Liefert den aktuellen Wert eines Parameters des Servers
  - pg_pconnect — Öffnet eine persistente PostgreSQL-Verbindung
  - pg_ping — Prüft die Datenbankverbindung
  - pg_port — Liefert die Portnummer, über die die Verbindung aufgebaut wurde
  - pg_prepare — Sendet eine Aufforderung an den Server, eine vorbereitete Anfrage mit den übergebenen Parametern zu erzeugen und wartet auf ihre Beendigung
  - pg_put_copy_data — Send data to the server during a COPY operation
  - pg_put_copy_end — Signal the completion of a COPY operation to the server
  - pg_put_line — Sendet eine NULL-terminierte Zeichenkette zum PostgreSQL-Server
  - pg_query — Führt eine Abfrage aus
  - pg_query_params — Sendet ein Kommando zum Server und wartet seine Ausführung ab. Getrennt vom SQL-Kommando können dabei Parameter übergeben werden
  - pg_result_error — Liefert die mit der Ergebniskennung verknüpfte Fehlermeldung
  - pg_result_error_field — Liefert den Inhalt eines bestimmtes Feldes zu einer Fehlermeldung
  - pg_result_memory_size — Returns the amount of memory allocated for a query result
  - pg_result_seek — Setzt den internen Datensatzzeiger auf die angegebene Position in einem Abfrageergebnis
  - pg_result_status — Liefert den Status eines Abfrageergebnisses
  - pg_select — Wählt Datensätze aus
  - pg_send_execute — Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern auszuführen, ohne auf die Ergebnisse zu warten
  - pg_send_prepare — Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern zu erzeugen, ohne auf ihre Beendigung zu warten
  - pg_send_query — Sendet eine asynchrone Abfrage
  - pg_send_query_params — Sendet ein Kommando und separate Parameter zum Server, ohne auf die Rückgabe der Ergebnisse zu warten
  - pg_set_chunked_rows_size — Set the query results to be retrieved in chunk mode
  - pg_set_client_encoding — Setzt die Kodierung des Clients
  - pg_set_error_context_visibility — Determines the visibility of the context's error messages returned by pg_last_error and pg_result_error
  - pg_set_error_verbosity — Bestimmt den Detaillierungsgrad von Fehlermeldungen, die von pg_last_error und pg_result_error zurückgegeben werden
  - pg_socket — Get a read only handle to the socket underlying a PostgreSQL connection
  - pg_socket_poll — Poll a PostgreSQL connection socket for read/write readiness
  - pg_trace — Ermöglicht die Ablaufverfolgung einer Verbindung
  - pg_transaction_status — Gibt den aktuellen Transaktionsstatus des Servers zurück
  - pg_tty — Liefert den TTY-Namen für die Verbindung
  - pg_unescape_bytea — Entfernt Maskierungen für den Typ bytea
  - pg_untrace — Beendet die Ablaufverfolgung einer PostgreSQL-Verbindung
  - pg_update — Aktualisiert eine Tabelle
  - pg_version — Liefert ein Array, das die Versionen von Client, Protokoll und Server enthält (falls verfügbar).
- PgSql\Connection — The PgSql\Connection class
- PgSql\Result — The PgSql\Result class
- PgSql\Lob — The PgSql\Lob class

# SQLite3

# Einführung

Unterstützung für SQLite3-Datenbanken.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

Von PHP 7.4.0 an wird » libsqlite ≥ 3.7.4 benötigt. Zuvor konnte statt dessen das gebündelte libsqlite verwendet werden.

## Installation

Die SQLite3-Erweiterung ist standardmäßig aktiviert. Es ist möglich, sie durch die Angabe von `--without-sqlite3` zur Kompilierzeit, zu deaktivieren.

Windows-Nutzer müssen php_sqlite3.dll aktivieren, wenn sie diese Erweiterung nutzen wollen. Die DLL-Datei wird mit den Windows-Distributionen von PHP ausgeliefert.

> Hinweis: Zusätzliche Einrichtung für Windows von PHP 7.4.0 an

> Diese Erweiterung benötigt DLL-Dateien. die für Windows verfügbar seien müssen. Der FAQ-Eintrag " Wie füge ich unter Windows PATH mein PHP-Verzeichnis hinzu?" gibt hierzu weitere Informationen. Obwohl ein einfaches Kopieren der DLL-Dateien vom PHP-Verzeichnis in den Windows-Systemordner auch funktioniert (weil der Systemordner immer im PATH enthalten ist), ist dieses Vorgehen nicht empfehlenswert. Diese Erweiterung benötigt die folgenden Dateien im PATH: libsqlite3.dll.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

SQLite3-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
sqlite3.extension_dir | "" | `INI_SYSTEM` |
sqlite3.defensive | 1 | `INI_USER` | Verfügbar von PHP 7.2.17 und 7.3.4 an für libsqlite ≥ 3.26.0. Vor PHP 8.2.0 war diese Einstellung nur über `INI_SYSTEM` änderbar.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`sqlite3.extension_dir` string

  Pfad zu dem Verzeichnis, welches die ladbare Erweiterung für SQLite beinhaltet.

`sqlite3.defensive` bool

  Ist das defensive-Flag aktiviert, dann sind Sprachfeatures, die es gewöhnlichem SQL ermöglichen, absichtlich die Datenbankdatei zu beschädigen, deaktiviert. Dies verbietet das direkte Schreiben des Schemas, von Schattentabellen (z. B. FTS Datentabellen), oder der virtuellen sqlite_dbpage Tabelle. Diese php.ini-Direktive wirkt nur für libsqlite ≥ 3.26.0.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`SQLITE3_ASSOC` (int)
  Legt fest, dass die Sqlite3Result::fetchArray()-Methode eine assoziative Liste zurückgeben soll. Die Liste wird durch den Spaltennamen indiziert, wie er in dem Anfrageergebnis zurückgegeben wurde.
`SQLITE3_NUM` (int)
  Legt fest, dass die Sqlite3Result::fetchArray()-Methode eine Liste zurückgeben soll, die durch die Spaltennummer indiziert wird, wie sie in dem Anfrageergebnis zurückgegeben wurde, beginnend mit Spalte 0.
`SQLITE3_BOTH` (int)
  Legt fest, dass die Sqlite3Result::fetchArray()-Methode eine Liste zurückgeben soll, die sowohl durch den Spaltennamen, als auch durch die Spaltennummer indiziert wird. Die geschieht analog dazu, wie es im Anfrageergebnis zurückgegeben wurde, beginnend mit Spalte 0.
`SQLITE3_INTEGER` (int)
  Repräsentiert die SQLite3 'INTEGER'-Speicherklasse.
`SQLITE3_FLOAT` (int)
  Repräsentiert die SQLite3 'REAL (FLOAT)'-Speicherklasse.
`SQLITE3_TEXT` (int)
  Repräsentiert die SQLite3 'TEXT'-Speicherklasse.
`SQLITE3_BLOB` (int)
  Repräsentiert die SQLite3 'BLOB'-Speicherklasse.
`SQLITE3_NULL` (int)
  Repräsentiert die SQLite3 'NULL'-Speicherklasse.
`SQLITE3_OPEN_READONLY` (int)
  Legt fest, dass die SQLite3-Datenbank nur für den lesenden Zugriff geöffnet wird.
`SQLITE3_OPEN_READWRITE` (int)
  Legt fest, dass die SQLite3 Datenbank für den Lese- und Schreibzugriff geöffnet wird.
`SQLITE3_OPEN_CREATE` (int)
  Legt fest, dass die SQLite3 Datenbank vor dem Öffnen angelegt wird, wenn diese noch nicht existiert.
`SQLITE3_DETERMINISTIC` (int)
  Gibt an, dass eine Funktion, die mit SQLite3::createFunction() erzeugt wurde, deterministisch ist, d.h. dass sie in einer einzelnen SQL-Anweisung immer dasselbe Ergebnis für dieselben Eingaben liefert. (Verfügbar von PHP 7.1.4 an.)

# Die Klasse SQLite3

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Einführung

Eine Klasse, die eine Schnittstelle zu SQLite3-Datenbanken zur Verfügung stellt.

## Klassenbeschreibung

class SQLite3 {
/* Konstanten */
public const int OK;
public const int DENY;
public const int IGNORE;
public const int CREATE_INDEX;
public const int CREATE_TABLE;
public const int CREATE_TEMP_INDEX;
public const int CREATE_TEMP_TABLE;
public const int CREATE_TEMP_TRIGGER;
public const int CREATE_TEMP_VIEW;
public const int CREATE_TRIGGER;
public const int CREATE_VIEW;
public const int DELETE;
public const int DROP_INDEX;
public const int DROP_TABLE;
public const int DROP_TEMP_INDEX;
public const int DROP_TEMP_TABLE;
public const int DROP_TEMP_TRIGGER;
public const int DROP_TEMP_VIEW;
public const int DROP_TRIGGER;
public const int DROP_VIEW;
public const int INSERT;
public const int PRAGMA;
public const int READ;
public const int SELECT;
public const int TRANSACTION;
public const int UPDATE;
public const int ATTACH;
public const int DETACH;
public const int ALTER_TABLE;
public const int REINDEX;
public const int ANALYZE;
public const int CREATE_VTABLE;
public const int DROP_VTABLE;
public const int FUNCTION;
public const int SAVEPOINT;
public const int COPY;
public const int RECURSIVE;
/* Methoden */
public function __construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")
public function backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool
public function busyTimeout(int `$milliseconds`): bool
public function changes(): int
public function close(): bool
public function createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool
public function enableExceptions(bool `$enable` = `false`): bool
public static function escapeString(string `$string`): string
public function exec(string `$query`): bool
public function lastErrorCode(): int
public function lastErrorMsg(): string
public function lastInsertRowID(): int
public function loadExtension(string `$name`): bool
public function open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false
public function prepare(string `$query`): SQLite3Stmt|false
public function query(string `$query`): SQLite3Result|false
public function querySingle(string `$query`, bool `$entireRow` = `false`): mixed
public function setAuthorizer(?callable `$callback`): bool
public static function version(): array
}

## Vordefinierte Konstanten

`SQLite3::OK`

`SQLite3::DENY`

`SQLite3::IGNORE`

`SQLite3::CREATE_INDEX`

`SQLite3::CREATE_TABLE`

`SQLite3::CREATE_TEMP_INDEX`

`SQLite3::CREATE_TEMP_TABLE`

`SQLite3::CREATE_TEMP_TRIGGER`

`SQLite3::CREATE_TEMP_VIEW`

`SQLite3::CREATE_TRIGGER`

`SQLite3::CREATE_VIEW`

`SQLite3::DELETE`

`SQLite3::DROP_INDEX`

`SQLite3::DROP_TABLE`

`SQLite3::DROP_TEMP_INDEX`

`SQLite3::DROP_TEMP_TABLE`

`SQLite3::DROP_TEMP_TRIGGER`

`SQLite3::DROP_TEMP_VIEW`

`SQLite3::DROP_TRIGGER`

`SQLite3::DROP_VIEW`

`SQLite3::INSERT`

`SQLite3::PRAGMA`

`SQLite3::READ`

`SQLite3::SELECT`

`SQLite3::TRANSACTION`

`SQLite3::UPDATE`

`SQLite3::ATTACH`

`SQLite3::DETACH`

`SQLite3::ALTER_TABLE`

`SQLite3::REINDEX`

`SQLite3::ANALYZE`

`SQLite3::CREATE_VTABLE`

`SQLite3::DROP_VTABLE`

`SQLite3::FUNCTION`

`SQLite3::SAVEPOINT`

`SQLite3::COPY`

`SQLite3::RECURSIVE`

# SQLite3::backup

(PHP 7 >= 7.4.0, PHP 8)

SQLite3::backup — Backup one database to another database

### Beschreibung

public function SQLite3::backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool

SQLite3::backup() copies the contents of one database into another, overwriting the contents of the destination database. It is useful either for creating backups of databases or for copying in-memory databases to or from persistent files.

Tipp

As of SQLite 3.27.0 (2019-02-07), it is also possible to use the statement `VACUUM INTO 'file.db';` to backup the database to a new file.

### Parameter-Liste

`destination`

  A database connection opened with SQLite3::open().

`sourceDatabase`

  The database name is `"main"` for the main database, `"temp"` for the temporary database, or the name specified after the `AS` keyword in an `ATTACH` statement for an attached database.

`destinationDatabase`

  Analogous to `sourceDatabase` but for the `destination`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Backup an existing database

    <?php
    // $conn is a connection to an already opened sqlite3 database

    $backup = new SQLite3('backup.sqlite');
    $conn->backup($backup);
    ?>

# SQLite3::busyTimeout

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

SQLite3::busyTimeout — Sets the busy connection handler

### Beschreibung

public function SQLite3::busyTimeout(int `$milliseconds`): bool

Sets a busy handler that will sleep until the database is not locked or the timeout is reached.

### Parameter-Liste

`milliseconds`

  The milliseconds to sleep. Setting this value to a value less than or equal to zero, will turn off an already set timeout handler.

### Rückgabewerte

Returns `true` on success, Bei einem Fehler wird `false` zurückgegeben..

# SQLite3::changes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::changes — Gibt die Anzahl der Datenbankreihen zurück, die durch die letzte SQL-Anfrage verändert, gelöscht oder hinzugefügt wurden.

### Beschreibung

public function SQLite3::changes(): int

Gibt die Anzahl der Datenbankreihen zurück, die durch die letzte SQL-Anfrage verändert, gelöscht oder hinzugefügt wurden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen int-Wert zurück, der der Anzahl an geänderten, gelöschten oder hinzugefügten Datenbankreihen der letzten SQL-Anfrage widerspiegelt.

### Beispiele

Beispiel #1 SQLite3::changes()-Beispiel

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $query = $db->exec('UPDATE counter SET views=0 WHERE page="test"');
    if ($query) {
        echo 'Anzahl der modifizierten Reihen: ', $db->changes();
    }
    ?>

# SQLite3::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::close — Beendet eine Datenbankverbindung

### Beschreibung

public function SQLite3::close(): bool

Beendet eine Datenbankverbindung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 SQLite3::close() Beispiel

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->close();
    ?>

# SQLite3::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::__construct — Instanziiert ein SQLite3-Objekt und öffnet eine SQLite3-Datenbank

### Beschreibung

public function SQLite3::__construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")

Instanziiert ein SQLite3-Objekt und öffnet eine Verbindung zu einer SQLite3-Datenbank. Wurde libsqlite3 mit Unterstützung für Verschlüsselung kompiliert, wird versucht den angegebenen Schlüssel zu nutzen.

### Parameter-Liste

`filename`

  Pfad zur SQLite-Datenbank oder `:memory:`, um eine im Speicher befindliche Datenbank zu nutzen. Ist `filename` eine leere Zeichenkette, dann wird eine private, temporäre Datenbank auf der Festplatte erzeugt. Diese private Datenbank wird automatisch gelöscht, sobald die Datenbankverbindung geschlossen wird.

`flags`

  Optionale Schalter, die die Art bestimmen, wie die SQLite-Datenbank geöffnet wird. Standardmäßig wird `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE` zum Öffnen genutzt.

  - `SQLITE3_OPEN_READONLY`: Öffnet die Datenbank im "nur-lese"-Modus.

  - `SQLITE3_OPEN_READWRITE`: Öffnet die Datenbank zum Lesen und Schreiben.

  - `SQLITE3_OPEN_CREATE`: erzeugt die Datenbank, sollte diese nicht existieren.

`encryptionKey`

  Eine optionale Verschlüsselungs-Phrase, die zur Ver- und Entschlüsselung der Datenbank genutzt wird. Ist das SQLite-Verschlüsselungsmodul nicht installiert, dann hat dieser Parameter keine Wirkung.

### Fehler/Exceptions

Löst im Fehlerfall eine Exception aus.

### Changelog

Version | Beschreibung
--- | ---
7.0.10 | Der Parameter `filename` kann nun leer sein, um eine private, temporäre Datenbank auf der Festplatte zu verwenden.

### Beispiele

Beispiel #1 SQLite3::__construct()-Beispiel

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (bar TEXT)');
    $db->exec("INSERT INTO foo (bar) VALUES ('Dies ist ein Test')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());
    ?>

# SQLite3::createAggregate

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createAggregate — Registriert eine PHP-Funktion zum Gebrauch als SQL-Aggregat-Funktion

### Beschreibung

public function SQLite3::createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool

Registriert eine PHP-Funktion zum Gebrauch als SQL-Aggregat-Funktion.

### Parameter-Liste

`name`

  Name des erstellten oder neu definierten SQL-Aggregates.

`stepCallback`

  'Callback'-Funktion, welche für jede Reihe des Abfrageergebnisses ausgeführt wird. Ihr PHP sollte das Ergebnis akkumulieren und es im Aggregations-Kontext speichern.

  Es ist notwendig, diese Funktion wie folgt zu definieren:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`

    `null` für die erste Reihe. Folgende Reihen werden den zuvor zurückgegebenen Wert haben. Sie sollten diesen nutzen, um den Status der Aggregation zu pflegen.

  `rownumber`

    Die Nummer der aktuellen Reihe.

  `value`

    Das erste Argument, das an das Aggregat übergeben wurde.

  `values`

    Weitere Argumente, die an das Aggregat übergeben wurden.

  Der Rückgabewert dieser Funktion wird als `context` Argument im nächsten Aufruf der step oder finalize Funktion verwendet.
`finalCallback`

  'Callback'-Funktion, die die Informationen aller Reihen aggregiert. Sind alle Reihen abgearbeitet, wird diese Funktion aufgerufen. Diese sollte dann die Daten der Aggregation 'context' auswerten und das Ergebnis zurückgeben. 'Callback'-Funktionen sollten einen Variablentyp liefern, der von SQLite erwartet wird (z. B. scalar type).

  Diese Funktion ist wie folgt zu definieren:

  function fini(mixed `$context`, int `$rownumber`): mixed
  `context`

    Enthält den Rückgabewert des letzten Aufrufs der Schritt-Funktion.

  `rownumber`

    Immer `0`.

  Der Rückgabewert dieser Funktion wird als Rückgabewert für die Aggregation genutzt.
`argCount`

  Anzahl der Argumente, welche das SQL-Aggregat erwartet. Ist dieser Parameter negativ, wird das SQL-Aggregat jedwede Zahl von Argumenten erkennen.

### Rückgabewerte

Gibt `true` zurück, wenn die Aggregierung erfolgreich war. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Beispiel für eine 'max_length'-Aggregierungs-Funktion

    <?php
    $data = array(
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
       );
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE strings(a)");
    $insert = $db->prepare('INSERT INTO strings VALUES (?)');
    foreach ($data as $str) {
        $insert->bindValue(1, $str);
        $insert->execute();
    }
    $insert = null;

    function max_len_step($context, $rownumber, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $rownumber)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->querySingle('SELECT max_len(a) from strings'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(5)

In diesem Beispiel erzeugen wir eine Aggregat-Funktion, die die Länge der längsten Zeichenkette innerhalb einer der Tabellenspalten ermittelt. Die `max_len_step`-Funktion wird für jede durchlaufene Reihe mit dem Parameter `$context` aufgerufen. Der Parameter 'context' ist eine normal PHP Variable, welche Listen oder Objektinhalte beinhalten kann. In diesem Beispiel benötigen wir sie als Speicher für die größte bisher gefundene Länge der geprüften Zeichenketten. Wenn also die die Zeichenkette in `$string` länger ist, als die aktuell Längste, wird der Inhalt von 'context' mit der neuen Länge überschrieben.

Nachdem alle Reihen abgearbeitet wurden, ruft SQLite die `max_len_finalize`-Funktion auf, um das Endergebnis zu ermitteln. Hier können wir nun jede Art von Berechnungen, basierend auf den in `$context` gesammelten Daten, durchführen. In unserem Beispiel haben wir die Berechgungen bereits bei der Datenerhebung getätigt, dass wir nun nur noch das Ergebnis - den Inhalt von 'context' - zurückgeben brauchen.

Tipp

Es ist nicht ratsam, eine Kopie der Inhalte in 'context' zu speichern, um diese dann am Ende auszuwerten. Das würde dazu führen, dass SQLite eine große Menge an Speicher benötigt, um die Abfrage abzuarbeiten. Überlegen Sie nur mal, wieviel Speicher eine Abfrage braucht, die 1 Millionen Reihen mit je 32 Byte Inhalt aus der Datenbank liest.

Tipp

SQLite3::createAggregate() kann verwendet werden, um native SQL-Funktionen von SQLite zu übersteuern.

# SQLite3::createCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

SQLite3::createCollation — Registers a PHP function for use as an SQL collating function

### Beschreibung

public function SQLite3::createCollation(string `$name`, callable `$callback`): bool

Registers a PHP function or user-defined function for use as a collating function within SQL statements.

### Parameter-Liste

`name`

  Name of the SQL collating function to be created or redefined

`callback`

  The name of a PHP function or user-defined function to apply as a callback, defining the behavior of the collation. It should accept two values and return as strcmp() does, i.e. it should return -1, 1, or 0 if the first string sorts before, sorts after, or is equal to the second.

  This function need to be defined as:

  function collation(mixed `$value1`, mixed `$value2`): int

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 SQLite3::createCollation() example

Register the PHP function strnatcmp() as a collating sequence in the SQLite3 database.

    <?php

    $db = new SQLite3(":memory:");
    $db->exec("CREATE TABLE test (col1 string)");
    $db->exec("INSERT INTO test VALUES ('a1')");
    $db->exec("INSERT INTO test VALUES ('a10')");
    $db->exec("INSERT INTO test VALUES ('a2')");

    $db->createCollation('NATURAL_CMP', 'strnatcmp');

    $defaultSort = $db->query("SELECT col1 FROM test ORDER BY col1");
    $naturalSort = $db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP");

    echo "default:\n";
    while ($row = $defaultSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    echo "\nnatural:\n";
    while ($row = $naturalSort->fetchArray()){
        echo $row['col1'], "\n";
    }

    $db->close();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    default:
    a1
    a10
    a2

    natural:
    a1
    a2
    a10

### Siehe auch

- The SQLite collation documentation: » http://sqlite.org/datatype3.html#collation

# SQLite3::createFunction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createFunction — Registriert eine PHP-Funktion, die als SQL-Skalar-Funktion genutzt werden kann

### Beschreibung

public function SQLite3::createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool

Registriert eine PHP- oder benutzerdefinierte Funktion, die als SQL-Skalar-Funktion innerhalb einer SQL-Anweisung genutzt werden kann.

### Parameter-Liste

`name`

  Name der SQL-Funktion, die erstellt oder neu definiert werden soll.

`callback`

  Der Name der PHP- oder benutzerdefinierten Funktion, welche als Callback-Funktion agieren soll und das Verhalten der SQL-Funktion definiert.

  Diese Funktion muss wie folgt definiert werden:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    Das erste Argument, dass an die SQL-Funktion übergeben wurde.

  `values`

    Weitere Argumente, die an die SQL-Funktion übergeben wurden.

`argCount`

  Die Anzahl an Argumenten, die die SQL-Funktion entgegen nimmt. Ist der Parameter gleich `-1`, ist die SQL-Funktion nicht auf eine Parameteranzahl eingeschränkt.

`flags`

  Ein bitweise Oder-Verknüpfung von Flags. Zurzeit wird nur `SQLITE3_DETERMINISTIC` unterstützt, das angibt, dass die Funktion in einer einzelnen SQL-Anweisung immer dasselbe Ergebnis für dieselben Eingaben liefert.

### Rückgabewerte

Gibt `true` zurück, wenn die Funktion erfolgreich erstellt wurde. Anderenfalls wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
7.1.4 | Der `flags`-Parameter wurde hinzugefügt.

### Beispiele

Beispiel #1 SQLite3::createFunction()-Beispiel

    <?php
    function my_udf_md5($string) {
        return hash('md5', $string);
    }

    $db = new SQLite3('mysqlitedb.db');
    $db->createFunction('my_udf_md5', 'my_udf_md5');

    var_dump($db->querySingle('SELECT my_udf_md5("test")'));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(32) "098f6bcd4621d373cade4e832627b4f6"

# SQLite3::enableExceptions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::enableExceptions — Enable throwing exceptions

### Beschreibung

public function SQLite3::enableExceptions(bool `$enable` = `false`): bool

Controls whether the SQLite3 instance will throw exceptions or warnings on error.

### Parameter-Liste

`enable`

  When `true`, the SQLite3 instance, and SQLite3Stmt and SQLite3Result instances derived from it, will throw exceptions on error.

  When `false`, the SQLite3 instance, and SQLite3Stmt and SQLite3Result instances derived from it, will raise warnings on error.

  For either mode, the error code and message, if any, will be available via SQLite3::lastErrorCode() and SQLite3::lastErrorMsg() respectively.

### Rückgabewerte

Returns the old value; `true` if exceptions were enabled, `false` otherwise.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Calling SQLite3::enableExceptions() with `enable` as `false` will trigger a `E_DEPRECATED` warning.

### Beispiele

Beispiel #1 SQLite3::enableExceptions() example

    <?php
    $sqlite = new SQLite3(':memory:');
    try {
        $sqlite->exec('create table foo');
        $sqlite->enableExceptions(true);
        $sqlite->exec('create table bar');
    } catch (Exception $e) {
        echo 'Caught exception: ' . $e->getMessage();
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Warning: SQLite3::exec(): near "foo": syntax error in example.php on line 4
    Caught exception: near "bar": syntax error

# SQLite3::escapeString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::escapeString — Gibt eine passend maskierte Zeichenkette zurück

### Beschreibung

public static function SQLite3::escapeString(string `$string`): string

Gibt eine Zeichenkette zurück, die für eine sichere Einbindung in die SQL-Anfrage passend maskiert wurde.

Warnung

Diese Funktion ist (bis jetzt) nicht binärsicher!

Um BLOB-Felder, die ein NUL-Zeichen enthalten können, verlässlich zu behandeln, sollte stattdessen SQLITE3Stmt::bindParam() verwendet werden.

### Parameter-Liste

`string`

  Die maskierte Zeichenkette.

### Rückgabewerte

Gibt eine passend maskierte Zeichenkette zurück, welche ohne Bedenken in einer SQL-Anfrage benutzt werden kann.

### Anmerkungen

Warnung

Die Funktion addslashes() sollte NICHT genutzt werden, um eine Zeichenkette für den Gebrauch in einer SQL-Anfrage zu maskieren; dies kann bei der Datenabfrage zu unvorhersehbaren Resultaten führen.

# SQLite3::exec

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::exec — Führt eine ergebnislose Abfrage an eine Datenbank aus

### Beschreibung

public function SQLite3::exec(string `$query`): bool

Führt eine Abfrage an die angegebene Datenbank aus, die kein Ergebnis zurückgibt.

> Hinweis: SQLite3 muss möglicherweise während der Ausführung von Abfragen » temporäre Dateien erzeugen, so dass die entsprechenden Verzeichnisse beschreibbar sein müssen.

### Parameter-Liste

`query`

  Die auszuführende SQL-Anfrage (normalerweise eine INSERT-, UPDATE- oder DELETE-Anweisung)

### Rückgabewerte

Gibt `true` zurück, wenn die Anfrage erfolgreich war; andernfalls `false`

### Beispiele

Beispiel #1 SQLite3::exec()-Beispiel

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE bar (bar TEXT)');
    ?>

# SQLite3::lastErrorCode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorCode — Gibt den numerischen Ergebniscode der letzten fehlgeschlagenen SQLite-Anweisung zurück

### Beschreibung

public function SQLite3::lastErrorCode(): int

Gibt den numerischen Ergebniscode der letzten fehlgeschlagenen SQLite-Anweisung zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert einen Integerwert, der das numerische Ergebnis der letzten fehlgeschlagenen SQLite-Anweisung repräsentiert.

# SQLite3::lastErrorMsg

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorMsg — Gibt einen englischen Text zurück, der die letzten fehlgeschlagenen SQLite-Anfrage beschreibt.

### Beschreibung

public function SQLite3::lastErrorMsg(): string

Gibt einen englischen Text zurück, der die letzten fehlgeschlagenen SQLite-Anfrage beschreibt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen englischen Text zurück, der die letzten fehlgeschlagenen SQLite-Anfrage beschreibt.

# SQLite3::lastInsertRowID

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastInsertRowID — Gibt die Datensatz-Id des zuletzt getätigten INSERT in die Datenbank zurück

### Beschreibung

public function SQLite3::lastInsertRowID(): int

Gibt die Datensatz-Id des zuletzt getätigten INSERT in die Datenbank zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Datensatz-Id des zuletzt getätigten INSERT in die Datenbank zurück. Wenn es bei dieser Datenbankverbindung keine erfolgreichen INSERTs in rowid-Tabellen gegeben hat, dann gibt SQLite3::lastInsertRowID() `0` zurück.

# SQLite3::loadExtension

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::loadExtension — Versucht eine SQLite-Erweiterungsbibliothek zu laden

### Beschreibung

public function SQLite3::loadExtension(string `$name`): bool

Versucht eine SQLite-Erweiterungsbibliothek zu laden.

### Parameter-Liste

`name`

  Name der zu ladenden Bibliothek. Die Bibliothek muss in dem Verzeichnis existieren, das in der Konfigurationsoption sqlite3.extension_dir spezifiziert wurde.

### Rückgabewerte

Gibt `true` zurück, wenn die Erweiterung erfolgreich geladen wurde und `false` im Fehlerfall.

### Beispiele

Beispiel #1 SQLite3::loadExtension()-Beispiel

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->loadExtension('libagg.so');
    ?>

# SQLite3::open

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::open — Öffnet eine SQlite-Datenbank

### Beschreibung

public function SQLite3::open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void

Öffnet eine SQLite3-Datenbank. Sollte diese verschlüsselt sein, wird unter Anwendung des Schlüssels versucht, diese zu entschlüsseln.

### Parameter-Liste

`filename`

  Pfad zu der SQLite-Datenbank oder `:memory:`, um eine im Arbeitsspeicher liegende Datenbank zu erstellen.

`flags`

  Optionale Parameter zur Bestimmung, wie die SQLite-Datenbank geöffnet werden soll. Im Normalfall wird open `SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE` nutzen.

  - `SQLITE3_OPEN_READONLY`: Öffnet die Datenbank ausschließlich für lesende Zugriffe.

  - `SQLITE3_OPEN_READWRITE`: Öffnet die Datenbank für lesende und schreibende Zugriffe.

  - `SQLITE3_OPEN_CREATE`: Erzeugt eine Datenbank, wenn diese nicht existiert.

`encryptionKey`

  Ein optionaler Schlüssel zur Verschlüsselung der Datenbank. Dieser wird zum Ent- und Verschlüsseln einer SQLite Datenbank genutzt. Wenn das SQlite Encryption-Modul nicht installiert ist, wird dieser Parameter ignoriert.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 SQLite3::open()-Beispiel

    <?php
    /**
     * Ein einfaches Beispiel, wie man die SQLite3-Klasse erweitert, die Parameter
     * des Konstruktors (__construct) verändert und mit Hilfe der open-Methode dann
     * die Datenbank initialisiert.
     */
    class MyDB extends SQLite3
    {
        function __construct()
        {
            $this->open('mysqlitedb.db');
        }
    }

    $db = new MyDB();

    $db->exec('CREATE TABLE foo (bar STRING)');
    $db->exec("INSERT INTO foo (bar) VALUES ('This is a test')");

    $result = $db->query('SELECT bar FROM foo');
    var_dump($result->fetchArray());
    ?>

# SQLite3::openBlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::openBlob — Opens a stream resource to read a BLOB

### Beschreibung

public function SQLite3::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false

Opens a stream resource to read or write a BLOB, which would be selected by:

SELECT `column` FROM `database`.`table` WHERE rowid = `rowid`

> Hinweis: It is not possible to change the size of a BLOB by writing to the stream. Instead, an UPDATE statement has to be executed, possibly using SQLite's zeroblob() function to set the desired BLOB size.

### Parameter-Liste

`table`

  The table name.

`column`

  The column name.

`rowid`

  The row ID.

`database`

  The symbolic name of the DB

`flags`

  Either `SQLITE3_OPEN_READONLY` or `SQLITE3_OPEN_READWRITE` to open the stream for reading only, or for reading and writing, respectively.

### Rückgabewerte

Returns a stream resource, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | The `flags` parameter has been added, allowing to write BLOBs; formerly only reading was supported.

### Beispiele

Beispiel #1 SQLite3::openBlob() example

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES ('Lorem ipsum')");
    $stream = $conn->openBlob('test', 'text', 1);
    echo stream_get_contents($stream);
    fclose($stream); // mandatory, otherwise the next line would fail
    $conn->close();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Lorem ipsum

Beispiel #2 Incrementally writing a BLOB

    <?php
    $conn = new SQLite3(':memory:');
    $conn->exec('CREATE TABLE test (text text)');
    $conn->exec("INSERT INTO test VALUES (zeroblob(36))");
    $stream = $conn->openBlob('test', 'text', 1, 'main', SQLITE3_OPEN_READWRITE);
    for ($i = 0; $i < 3; $i++) {
        fwrite($stream,  "Lorem ipsum\n");
    }
    fclose($stream);
    echo $conn->querySingle("SELECT text FROM test");
    $conn->close();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Lorem ipsum
    Lorem ipsum
    Lorem ipsum

# SQLite3::prepare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::prepare — Bereitet eine SQL-Anweisung für die Ausführung vor

### Beschreibung

public function SQLite3::prepare(string `$query`): SQLite3Stmt|false

Bereitet eine SQL-Anweisung für die Ausführung vor und gibt ein SQLite3Stmt zurück.

### Parameter-Liste

`query`

  Die vorzubereitende SQL-Anfrage.

### Rückgabewerte

Gibt im Erfolgsfall ein SQLite3Stmt-Objekt zurück. Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 SQLite3::prepare()-Beispiel

    <?php
    unlink('mysqlitedb.db');
    $db = new SQLite3('mysqlitedb.db');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'This is a test')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray());
    ?>

### Siehe auch

- SQLite3Stmt::paramCount() - Returns the number of parameters within the prepared statement
- SQLite3Stmt::bindValue() - Binds the value of a parameter to a statement variable
- SQLite3Stmt::bindParam() - Binds a parameter to a statement variable

# SQLite3::query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::query — Führt eine SQL-Anfrage aus

### Beschreibung

public function SQLite3::query(string `$query`): SQLite3Result|false

Führt eine SQL-Anfrage aus, welche ein SQLite3Result-Objekt zurück gibt. Liefert die Abfrage kein Ergebnis (so wie DML Anweisungen), dann ist das zürckgelieferte SQLite3Result-Objekt nicht wirklich nutzbar. Statt dessen sollte für solche Abfragen SQLite3::exec() verwendet werden.

### Parameter-Liste

`query`

  Die auszuführende SQL-Anfrage.

### Rückgabewerte

Liefert ein SQLite3Result-Objekt. Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 SQLite3::query()-Beispiel

    <?php
    $db = new SQLite3('mysqlitedb.db');

    $results = $db->query('SELECT bar FROM foo');
    while ($row = $results->fetchArray()) {
        var_dump($row);
    }
    ?>

# SQLite3::querySingle

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::querySingle — Executes a query and returns a single result

### Beschreibung

public function SQLite3::querySingle(string `$query`, bool `$entireRow` = `false`): mixed

Executes a query and returns a single result.

### Parameter-Liste

`query`

  The SQL query to execute.

`entireRow`

  By default, querySingle() returns the value of the first column returned by the query. If `entireRow` is `true`, then it returns an array of the entire first row.

### Rückgabewerte

Returns the value of the first column of results or an array of the entire first row (if `entireRow` is `true`).

If the query is valid but no results are returned, then `null` will be returned if `entireRow` is `false`, otherwise an empty array is returned.

Invalid or failing queries will return `false`.

### Beispiele

Beispiel #1 SQLite3::querySingle() example

    <?php
    $db = new SQLite3('mysqlitedb.db');

    var_dump($db->querySingle('SELECT username FROM user WHERE userid=1'));
    print_r($db->querySingle('SELECT username, email FROM user WHERE userid=1', true));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(5) "Scott"
    Array
    (
        [username] => Scott
        [email] => scott@example.com
    )

# SQLite3::setAuthorizer

(PHP 8)

SQLite3::setAuthorizer — Configures a callback to be used as an authorizer to limit what a statement can do

### Beschreibung

public function SQLite3::setAuthorizer(?callable `$callback`): bool

Sets a callback that will be called by SQLite every time an action is performed (reading, deleting, updating, etc.). This is used when preparing a SQL statement from an untrusted source to ensure that the SQL statements do not try to access data they are not allowed to see, or that they do not try to execute malicious statements that damage the database. For example, an application may allow a user to enter arbitrary SQL queries for evaluation by a database. But the application does not want the user to be able to make arbitrary changes to the database. An authorizer could then be put in place while the user-entered SQL is being prepared that disallows everything except SELECT statements.

The authorizer callback may be called multiple times for each statement prepared by SQLite. A `SELECT` or `UPDATE` query will call the authorizer for every column that would be read or updated.

The authorizer is called with up to five parameters. The first parameter is always given, and is an int (action code) matching a constant from `SQLite3`. The other parameters are only passed for some actions. The following table describes the second and third parameters according to the action:

List of action codes and parameters
Action | Second parameter | Third parameter
--- | --- | ---
`SQLite3::CREATE_INDEX` | Index Name | Table Name
`SQLite3::CREATE_TABLE` | Table Name | `null`
`SQLite3::CREATE_TEMP_INDEX` | Index Name | Table Name
`SQLite3::CREATE_TEMP_TABLE` | Table Name | `null`
`SQLite3::CREATE_TEMP_TRIGGER` | Trigger Name | Table Name
`SQLite3::CREATE_TEMP_VIEW` | View Name | `null`
`SQLite3::CREATE_TRIGGER` | Trigger Name | Table Name
`SQLite3::CREATE_VIEW` | View Name | `null`
`SQLite3::DELETE` | Table Name | `null`
`SQLite3::DROP_INDEX` | Index Name | Table Name
`SQLite3::DROP_TABLE` | Table Name | `null`
`SQLite3::DROP_TEMP_INDEX` | Index Name | Table Name
`SQLite3::DROP_TEMP_TABLE` | Table Name | `null`
`SQLite3::DROP_TEMP_TRIGGER` | Trigger Name | Table Name
`SQLite3::DROP_TEMP_VIEW` | View Name | `null`
`SQLite3::DROP_TRIGGER` | Trigger Name | Table Name
`SQLite3::DROP_VIEW` | View Name | `null`
`SQLite3::INSERT` | Table Name | `null`
`SQLite3::PRAGMA` | Pragma Name | First argument passed to the pragma, or `null`
`SQLite3::READ` | Table Name | Column Name
`SQLite3::SELECT` | `null` | `null`
`SQLite3::TRANSACTION` | Operation | `null`
`SQLite3::UPDATE` | Table Name | Column Name
`SQLite3::ATTACH` | Filename | `null`
`SQLite3::DETACH` | Database Name | `null`
`SQLite3::ALTER_TABLE` | Database Name | Table Name
`SQLite3::REINDEX` | Index Name | `null`
`SQLite3::ANALYZE` | Table Name | `null`
`SQLite3::CREATE_VTABLE` | Table Name | Module Name
`SQLite3::DROP_VTABLE` | Table Name | Module Name
`SQLite3::FUNCTION` | `null` | Function Name
`SQLite3::SAVEPOINT` | Operation | Savepoint Name
`SQLite3::RECURSIVE` | `null` | `null`

The 4th parameter will be the name of the database (`"main"`, `"temp"`, etc.) if applicable.

The 5th parameter to the authorizer callback is the name of the inner-most trigger or view that is responsible for the access attempt or `null` if this access attempt is directly from top-level SQL code.

When the callback returns `SQLite3::OK`, that means the operation requested is accepted. When the callback returns `SQLite3::DENY`, the call that triggered the authorizer will fail with an error message explaining that access is denied.

If the action code is `SQLite3::READ` and the callback returns `SQLite3::IGNORE` then the prepared statement is constructed to substitute a `null` value in place of the table column that would have been read if `SQLite3::OK` had been returned. The `SQLite3::IGNORE` return can be used to deny an untrusted user access to individual columns of a table.

When a table is referenced by a `SELECT` but no column values are extracted from that table (for example in a query like `"SELECT count(*) FROM table"`) then the `SQLite3::READ` authorizer callback is invoked once for that table with a column name that is an empty string.

If the action code is `SQLite3::DELETE` and the callback returns `SQLite3::IGNORE` then the DELETE operation proceeds but the truncate optimization is disabled and all rows are deleted individually.

Only a single authorizer can be in place on a database connection at a time. Each call to SQLite3::setAuthorizer() overrides the previous call. Disable the authorizer by installing a `null` callback. The authorizer is disabled by default.

The authorizer callback must not do anything that will modify the database connection that invoked the authorizer callback.

Note that the authorizer is only called when a statement is prepared, not when it's executed.

More details can be found in the » SQLite3 documentation.

### Parameter-Liste

`callback`

  The callable to be called.

  If `null` is passed instead, this will disable the current authorizer callback.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

This method doesn't throw any error, but if an authorizer is enabled and returns an invalid value, the statement preparation will throw an error (or exception, depending on the use of the SQLite3::enableExceptions() method).

### Beispiele

Beispiel #1 SQLite3::setAuthorizer() example

This only allows access to reading, and only some columns of the `users` table will be returned. Other columns will be replaced with `null`.

    <?php
    $db = new SQLite3('data.sqlite');
    $db->exec('CREATE TABLE users (id, name, password);');
    $db->exec('INSERT INTO users VALUES (1, \'Pauline\', \'Snails4eva\');');

    $allowed_columns = ['id', 'name'];

    $db->setAuthorizer(function (int $action, ...$args) use ($allowed_columns) {
        if ($action === SQLite3::READ) {
            list($table, $column) = $args;

            if ($table === 'users' && in_array($column, $allowed_columns)) {
                return SQLite3::OK;
            }

            return SQLite3::IGNORE;
        }

        return SQLite3::DENY;
    });

    print_r($db->querySingle('SELECT * FROM users WHERE id = 1;'));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [id] => 1
        [name] => Pauline
        [password] =>
    )

# SQLite3::version

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::version — Returns the SQLite3 library version as a string constant and as a number

### Beschreibung

public static function SQLite3::version(): array

Returns the SQLite3 library version as a string constant and as a number.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an associative array with the keys "versionString" and "versionNumber".

### Beispiele

Beispiel #1 SQLite3::version() example

    <?php
    print_r(SQLite3::version());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [versionString] => 3.5.9
        [versionNumber] => 3005009
    )

## Inhaltsverzeichnis

- SQLite3::backup — Backup one database to another database
- SQLite3::busyTimeout — Sets the busy connection handler
- SQLite3::changes — Gibt die Anzahl der Datenbankreihen zurück, die durch die letzte SQL-Anfrage verändert, gelöscht oder hinzugefügt wurden.
- SQLite3::close — Beendet eine Datenbankverbindung
- SQLite3::__construct — Instanziiert ein SQLite3-Objekt und öffnet eine SQLite3-Datenbank
- SQLite3::createAggregate — Registriert eine PHP-Funktion zum Gebrauch als SQL-Aggregat-Funktion
- SQLite3::createCollation — Registers a PHP function for use as an SQL collating function
- SQLite3::createFunction — Registriert eine PHP-Funktion, die als SQL-Skalar-Funktion genutzt werden kann
- SQLite3::enableExceptions — Enable throwing exceptions
- SQLite3::escapeString — Gibt eine passend maskierte Zeichenkette zurück
- SQLite3::exec — Führt eine ergebnislose Abfrage an eine Datenbank aus
- SQLite3::lastErrorCode — Gibt den numerischen Ergebniscode der letzten fehlgeschlagenen SQLite-Anweisung zurück
- SQLite3::lastErrorMsg — Gibt einen englischen Text zurück, der die letzten fehlgeschlagenen SQLite-Anfrage beschreibt.
- SQLite3::lastInsertRowID — Gibt die Datensatz-Id des zuletzt getätigten INSERT in die Datenbank zurück
- SQLite3::loadExtension — Versucht eine SQLite-Erweiterungsbibliothek zu laden
- SQLite3::open — Öffnet eine SQlite-Datenbank
- SQLite3::openBlob — Opens a stream resource to read a BLOB
- SQLite3::prepare — Bereitet eine SQL-Anweisung für die Ausführung vor
- SQLite3::query — Führt eine SQL-Anfrage aus
- SQLite3::querySingle — Executes a query and returns a single result
- SQLite3::setAuthorizer — Configures a callback to be used as an authorizer to limit what a statement can do
- SQLite3::version — Returns the SQLite3 library version as a string constant and as a number

# The SQLite3Exception class

(PHP 8 >= 8.3.0)

## Einführung

Represents a SQLite3 specific exception.

## Klassenbeschreibung

class SQLite3Exception extends Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Die Klasse SQLite3Stmt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Einführung

Ein Klasse, die vorbereitete Anweisungen für die SQLite-3-Erweiterung bearbeitet.

## Klassenbeschreibung

class SQLite3Stmt {
/* Methoden */
private function __construct(SQLite3 `$sqlite3`, string `$query`)
public function bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool
public function clear(): bool
public function close(): true
public function execute(): SQLite3Result|false
public function getSQL(bool `$expand` = `false`): string|false
public function paramCount(): int
public function readOnly(): bool
public function reset(): bool
}

# SQLite3Stmt::bindParam

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindParam — Binds a parameter to a statement variable

### Beschreibung

public function SQLite3Stmt::bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool

Binds a parameter to a statement variable.

Achtung

Before PHP 7.2.14 and 7.3.0, respectively, SQLite3Stmt::reset() must be called after the first call to SQLite3Stmt::execute() if the bound value should be properly updated on following calls to SQLite3Stmt::execute(). If SQLite3Stmt::reset() is not called, the bound value will not change, even if the value assigned to the variable passed to SQLite3Stmt::bindParam() has changed, or SQLite3Stmt::bindParam() has been called again.

### Parameter-Liste

`param`
  Either a string (for named parameters) or an int (for positional parameters) identifying the statement variable to which the value should be bound. If a named parameter does not start with a colon (`:`) or an at sign (`@`), a colon (`:`) is automatically prepended. Positional parameters start with `1`.
`var`

  The parameter to bind to a statement variable.

`type`

  The data type of the parameter to bind.

  - `SQLITE3_INTEGER`: The value is a signed integer, stored in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.

  - `SQLITE3_FLOAT`: The value is a floating point value, stored as an 8-byte IEEE floating point number.

  - `SQLITE3_TEXT`: The value is a text string, stored using the database encoding (UTF-8, UTF-16BE or UTF-16-LE).

  - `SQLITE3_BLOB`: The value is a blob of data, stored exactly as it was input.

  - `SQLITE3_NULL`: The value is a NULL value.

  As of PHP 7.0.7, if `type` is omitted, it is automatically detected from the type of the `var`: bool and int are treated as `SQLITE3_INTEGER`, float as `SQLITE3_FLOAT`, null as `SQLITE3_NULL` and all others as `SQLITE3_TEXT`. Formerly, if `type` has been omitted, it has defaulted to `SQLITE3_TEXT`.

  > Hinweis:

  > If `var` is `null`, it is always treated as `SQLITE3_NULL`, regardless of the given `type`.

### Rückgabewerte

Returns `true` if the parameter is bound to the statement variable, `false` on failure.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | `param` now also supports the `@param` notation.

### Beispiele

Beispiel #1 SQLite3Stmt::bindParam() Usage

This example shows how a single prepared statement with a single parameter binding can be used to insert multiple rows with different values.

    <?php
    $db = new SQLite3(':memory:');
    $db->exec("CREATE TABLE foo (bar TEXT)");

    $stmt = $db->prepare("INSERT INTO foo VALUES (:bar)");
    $stmt->bindParam(':bar', $bar, SQLITE3_TEXT);

    $bar = 'baz';
    $stmt->execute();

    $bar = 42;
    $stmt->execute();

    $res = $db->query("SELECT * FROM foo");
    while (($row = $res->fetchArray(SQLITE3_ASSOC))) {
        var_dump($row);
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["bar"]=>
      string(3) "baz"
    }
    array(1) {
      ["bar"]=>
      string(2) "42"
    }

### Siehe auch

- SQLite3Stmt::bindValue() - Binds the value of a parameter to a statement variable
- SQLite3::prepare() - Bereitet eine SQL-Anweisung für die Ausführung vor

# SQLite3Stmt::bindValue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindValue — Binds the value of a parameter to a statement variable

### Beschreibung

public function SQLite3Stmt::bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool

Binds the value of a parameter to a statement variable.

Achtung

Before PHP 7.2.14 and 7.3.0, respectively, once the statement has been executed, SQLite3Stmt::reset() needs to be called to be able to change the value of bound parameters.

### Parameter-Liste

`param`
  Either a string (for named parameters) or an int (for positional parameters) identifying the statement variable to which the value should be bound. If a named parameter does not start with a colon (`:`) or an at sign (`@`), a colon (`:`) is automatically prepended. Positional parameters start with `1`.
`value`

  The value to bind to a statement variable.

`type`

  The data type of the value to bind.

  - `SQLITE3_INTEGER`: The value is a signed integer, stored in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.

  - `SQLITE3_FLOAT`: The value is a floating point value, stored as an 8-byte IEEE floating point number.

  - `SQLITE3_TEXT`: The value is a text string, stored using the database encoding (UTF-8, UTF-16BE or UTF-16-LE).

  - `SQLITE3_BLOB`: The value is a blob of data, stored exactly as it was input.

  - `SQLITE3_NULL`: The value is a NULL value.

  As of PHP 7.0.7, if `type` is omitted, it is automatically detected from the type of the `value`: bool and int are treated as `SQLITE3_INTEGER`, float as `SQLITE3_FLOAT`, null as `SQLITE3_NULL` and all others as `SQLITE3_TEXT`. Formerly, if `type` has been omitted, it has defaulted to `SQLITE3_TEXT`.

  > Hinweis:

  > If `value` is `null`, it is always treated as `SQLITE3_NULL`, regardless of the given `type`.

### Rückgabewerte

Returns `true` if the value is bound to the statement variable, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | `param` now also supports the `@param` notation.

### Beispiele

Beispiel #1 SQLite3Stmt::bindValue() example

    <?php
    $db = new SQLite3(':memory:');

    $db->exec('CREATE TABLE foo (id INTEGER, bar STRING)');
    $db->exec("INSERT INTO foo (id, bar) VALUES (1, 'This is a test')");

    $stmt = $db->prepare('SELECT bar FROM foo WHERE id=:id');
    $stmt->bindValue(':id', 1, SQLITE3_INTEGER);

    $result = $stmt->execute();
    var_dump($result->fetchArray(SQLITE3_ASSOC));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(1) {
      ["bar"]=>
      string(14) "This is a test"
    }

### Siehe auch

- SQLite3Stmt::bindParam() - Binds a parameter to a statement variable
- SQLite3::prepare() - Bereitet eine SQL-Anweisung für die Ausführung vor

# SQLite3Stmt::clear

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::clear — Clears all current bound parameters

### Beschreibung

public function SQLite3Stmt::clear(): bool

Clears all current bound parameters (sets them to `null`).

Achtung

This method needs to be used with SQLite3Stmt::reset(). If used alone, any call to SQLite3Stmt::bindValue() or SQLite3Stmt::bindParam() will be of no effect and all bound parameters will have the `null` value.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` on successful clearing of bound parameters, `false` on failure.

# SQLite3Stmt::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::close — Closes the prepared statement

### Beschreibung

public function SQLite3Stmt::close(): true

Closes the prepared statement.

> Hinweis: Note that all SQLite3Results that have been retrieved by executing this statement will be invalidated when the statement is closed.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

An Error is thrown if the method is called on an uninitialized object.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | This method now throws an Error exception if the object is not correct initialized. Previously, it returned `false`.

# SQLite3Stmt::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::__construct — Constructs an SQLite3Stmt object

### Beschreibung

private function SQLite3Stmt::__construct(SQLite3 `$sqlite3`, string `$query`)

SQLite3Stmt instances are created by SQLite3::prepare().

### Parameter-Liste

`sqlite3`

`query`

# SQLite3Stmt::execute

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::execute — Executes a prepared statement and returns a result set object

### Beschreibung

public function SQLite3Stmt::execute(): SQLite3Result|false

Executes a prepared statement and returns a result set object.

Achtung

Result set objects retrieved by calling this method on the same statement object are not independent, but rather share the same underlying structure. Therefore it is recommended to call SQLite3Result::finalize(), before calling SQLite3Stmt::execute() on the same statement object again.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an SQLite3Result object on successful execution of the prepared statement, `false` on failure.

### Siehe auch

- SQLite3::prepare() - Bereitet eine SQL-Anweisung für die Ausführung vor
- SQLite3Stmt::bindValue() - Binds the value of a parameter to a statement variable
- SQLite3Stmt::bindParam() - Binds a parameter to a statement variable

# SQLite3Stmt::getSQL

(PHP 7 >= 7.4.0, PHP 8)

SQLite3Stmt::getSQL — Get the SQL of the statement

### Beschreibung

public function SQLite3Stmt::getSQL(bool `$expand` = `false`): string|false

Retrieves the SQL of the prepared statement. If `expand` is `false`, the unmodified SQL is retrieved. If `expand` is `true`, all query parameters are replaced with their bound values, or with an SQL `NULL`, if not already bound.

### Parameter-Liste

`expand`

  Whether to retrieve the expanded SQL. Passing `true` is only supported as of libsqlite 3.14.

### Rückgabewerte

Returns the SQL of the prepared statement, Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

If `expand` is `true`, but the libsqlite version is less than 3.14, an error of level `E_WARNING` or an Exception is issued, according to SQLite3::enableExceptions().

### Beispiele

Beispiel #1 Inspecting the expanded SQL

    <?php
    $db = new SQLite3(':memory:');
    $stmt = $db->prepare("SELECT :a, ?, :c");
    $stmt->bindValue(':a', 'foo');
    $answer = 42;
    $stmt->bindParam(2, $answer);
    var_dump($stmt->getSQL(true));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(24) "SELECT 'foo', '42', NULL"

# SQLite3Stmt::paramCount

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::paramCount — Returns the number of parameters within the prepared statement

### Beschreibung

public function SQLite3Stmt::paramCount(): int

Returns the number of parameters within the prepared statement.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of parameters within the prepared statement.

### Siehe auch

- SQLite3::prepare() - Bereitet eine SQL-Anweisung für die Ausführung vor

# SQLite3Stmt::readOnly

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SQLite3Stmt::readOnly — Returns whether a statement is definitely read only

### Beschreibung

public function SQLite3Stmt::readOnly(): bool

Returns whether a statement is definitely read only. A statement is considered read only, if it makes no direct changes to the content of the database file. Note that user defined SQL functions might change the database indirectly as a side effect.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if a statement is definitely read only, `false` otherwise.

# SQLite3Stmt::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::reset — Resets the prepared statement

### Beschreibung

public function SQLite3Stmt::reset(): bool

Resets the prepared statement to its state prior to execution. All bindings remain intact after reset.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the statement is successfully reset, Bei einem Fehler wird `false` zurückgegeben..

## Inhaltsverzeichnis

- SQLite3Stmt::bindParam — Binds a parameter to a statement variable
- SQLite3Stmt::bindValue — Binds the value of a parameter to a statement variable
- SQLite3Stmt::clear — Clears all current bound parameters
- SQLite3Stmt::close — Closes the prepared statement
- SQLite3Stmt::__construct — Constructs an SQLite3Stmt object
- SQLite3Stmt::execute — Executes a prepared statement and returns a result set object
- SQLite3Stmt::getSQL — Get the SQL of the statement
- SQLite3Stmt::paramCount — Returns the number of parameters within the prepared statement
- SQLite3Stmt::readOnly — Returns whether a statement is definitely read only
- SQLite3Stmt::reset — Resets the prepared statement

# Die Klasse SQLite3Result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Einführung

Eine Klasse, die Ergebnismengen der SQLite-3-Erweiterung bearbeitet.

## Klassenbeschreibung

class SQLite3Result {
/* Methoden */
private function __construct()
public function columnName(int `$column`): string|false
public function columnType(int `$column`): int|false
public function fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false
public function finalize(): true
public function numColumns(): int
public function reset(): bool
}

# SQLite3Result::columnName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnName — Returns the name of the nth column

### Beschreibung

public function SQLite3Result::columnName(int `$column`): string|false

Returns the name of the column specified by the `column`. Note that the name of a result column is the value of the `AS` clause for that column, if there is an `AS` clause. If there is no `AS` clause then the name of the column is unspecified and may change from one release of libsqlite3 to the next.

### Parameter-Liste

`column`

  The numeric zero-based index of the column.

### Rückgabewerte

Returns the string name of the column identified by `column`, or `false` if the column does not exist.

# SQLite3Result::columnType

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnType — Returns the type of the nth column

### Beschreibung

public function SQLite3Result::columnType(int `$column`): int|false

Returns the type of the column identified by `column`.

### Parameter-Liste

`column`

  The numeric zero-based index of the column.

### Rückgabewerte

Returns the data type index of the column identified by `column` (one of `SQLITE3_INTEGER`, `SQLITE3_FLOAT`, `SQLITE3_TEXT`, `SQLITE3_BLOB`, or `SQLITE3_NULL`), or `false` if the column does not exist.

# SQLite3Result::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::__construct — Constructs an SQLite3Result

### Beschreibung

private function SQLite3Result::__construct()

SQLite3Result instances are created by SQLite3::query() and SQLite3Stmt::execute().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# SQLite3Result::fetchArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::fetchArray — Fetches a result row as an associative or numerically indexed array or both

### Beschreibung

public function SQLite3Result::fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false

Fetches a result row as an associative or numerically indexed array or both. By default, fetches as both.

### Parameter-Liste

`mode`

  Controls how the next row will be returned to the caller. This value must be one of either `SQLITE3_ASSOC`, `SQLITE3_NUM`, or `SQLITE3_BOTH`.

  - `SQLITE3_ASSOC`: returns an array indexed by column name as returned in the corresponding result set

  - `SQLITE3_NUM`: returns an array indexed by column number as returned in the corresponding result set, starting at column 0

  - `SQLITE3_BOTH`: returns an array indexed by both column name and number as returned in the corresponding result set, starting at column 0

### Rückgabewerte

Returns a result row as an associatively or numerically indexed array or both. Alternately will return `false` if there are no more rows.

The types of the values of the returned array are mapped from SQLite3 types as follows: integers are mapped to int if they fit into the range `PHP_INT_MIN`..`PHP_INT_MAX`, and to string otherwise. Floats are mapped to float, `NULL` values are mapped to null, and strings and blobs are mapped to string.

# SQLite3Result::finalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::finalize — Closes the result set

### Beschreibung

public function SQLite3Result::finalize(): true

Closes the result set.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

An Error is thrown if the method is called on an uninitialized object.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | This method now throws an Error exception if the object is not correct initialized. Previously, it returned `false`.

# SQLite3Result::numColumns

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::numColumns — Returns the number of columns in the result set

### Beschreibung

public function SQLite3Result::numColumns(): int

Returns the number of columns in the result set.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of columns in the result set.

# SQLite3Result::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::reset — Resets the result set back to the first row

### Beschreibung

public function SQLite3Result::reset(): bool

Resets the result set back to the first row.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the result set is successfully reset back to the first row, `false` on failure.

## Inhaltsverzeichnis

- SQLite3Result::columnName — Returns the name of the nth column
- SQLite3Result::columnType — Returns the type of the nth column
- SQLite3Result::__construct — Constructs an SQLite3Result
- SQLite3Result::fetchArray — Fetches a result row as an associative or numerically indexed array or both
- SQLite3Result::finalize — Closes the result set
- SQLite3Result::numColumns — Returns the number of columns in the result set
- SQLite3Result::reset — Resets the result set back to the first row

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- SQLite3 — Die Klasse SQLite3
  - SQLite3::backup — Backup one database to another database
  - SQLite3::busyTimeout — Sets the busy connection handler
  - SQLite3::changes — Gibt die Anzahl der Datenbankreihen zurück, die durch die letzte SQL-Anfrage verändert, gelöscht oder hinzugefügt wurden.
  - SQLite3::close — Beendet eine Datenbankverbindung
  - SQLite3::__construct — Instanziiert ein SQLite3-Objekt und öffnet eine SQLite3-Datenbank
  - SQLite3::createAggregate — Registriert eine PHP-Funktion zum Gebrauch als SQL-Aggregat-Funktion
  - SQLite3::createCollation — Registers a PHP function for use as an SQL collating function
  - SQLite3::createFunction — Registriert eine PHP-Funktion, die als SQL-Skalar-Funktion genutzt werden kann
  - SQLite3::enableExceptions — Enable throwing exceptions
  - SQLite3::escapeString — Gibt eine passend maskierte Zeichenkette zurück
  - SQLite3::exec — Führt eine ergebnislose Abfrage an eine Datenbank aus
  - SQLite3::lastErrorCode — Gibt den numerischen Ergebniscode der letzten fehlgeschlagenen SQLite-Anweisung zurück
  - SQLite3::lastErrorMsg — Gibt einen englischen Text zurück, der die letzten fehlgeschlagenen SQLite-Anfrage beschreibt.
  - SQLite3::lastInsertRowID — Gibt die Datensatz-Id des zuletzt getätigten INSERT in die Datenbank zurück
  - SQLite3::loadExtension — Versucht eine SQLite-Erweiterungsbibliothek zu laden
  - SQLite3::open — Öffnet eine SQlite-Datenbank
  - SQLite3::openBlob — Opens a stream resource to read a BLOB
  - SQLite3::prepare — Bereitet eine SQL-Anweisung für die Ausführung vor
  - SQLite3::query — Führt eine SQL-Anfrage aus
  - SQLite3::querySingle — Executes a query and returns a single result
  - SQLite3::setAuthorizer — Configures a callback to be used as an authorizer to limit what a statement can do
  - SQLite3::version — Returns the SQLite3 library version as a string constant and as a number
- SQLite3Exception — The SQLite3Exception class
- SQLite3Stmt — Die Klasse SQLite3Stmt
  - SQLite3Stmt::bindParam — Binds a parameter to a statement variable
  - SQLite3Stmt::bindValue — Binds the value of a parameter to a statement variable
  - SQLite3Stmt::clear — Clears all current bound parameters
  - SQLite3Stmt::close — Closes the prepared statement
  - SQLite3Stmt::__construct — Constructs an SQLite3Stmt object
  - SQLite3Stmt::execute — Executes a prepared statement and returns a result set object
  - SQLite3Stmt::getSQL — Get the SQL of the statement
  - SQLite3Stmt::paramCount — Returns the number of parameters within the prepared statement
  - SQLite3Stmt::readOnly — Returns whether a statement is definitely read only
  - SQLite3Stmt::reset — Resets the prepared statement
- SQLite3Result — Die Klasse SQLite3Result
  - SQLite3Result::columnName — Returns the name of the nth column
  - SQLite3Result::columnType — Returns the type of the nth column
  - SQLite3Result::__construct — Constructs an SQLite3Result
  - SQLite3Result::fetchArray — Fetches a result row as an associative or numerically indexed array or both
  - SQLite3Result::finalize — Closes the result set
  - SQLite3Result::numColumns — Returns the number of columns in the result set
  - SQLite3Result::reset — Resets the result set back to the first row

# Microsoft SQL Server Driver for PHP

# Einführung

The SQLSRV extension allows you to access Microsoft SQL Server and SQL Azure databases. The 3.0 release of the driver supports SQL Server, beginning with SQL Server 2005, including SQL Server 2012 and SQL Server 2012 LocalDB. (For more information about LocalDB, see » PHP Driver for SQL Server Support for LocalDB and » SQL Server 2012 Express LocalDB.)

The SQLSRV extension is supported by Microsoft and available for download here: » http://msdn.microsoft.com/en-us/sqlserver/ff657782.aspx. SQL Server 2012 LocalDB can be downloaded here: » http://go.microsoft.com/fwlink/?LinkID=237665.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

The SQLSRV extension can be used on the following operating systems:

- Windows Vista Service Pack 2 or later
- Windows Server 2008 Service Pack 2 or later
- Windows Server 2008 R2
- Windows 7

The SQLSRV extension requires that the Microsoft SQL Server 2012 Native Client be installed on the same computer that is running PHP. If the Microsoft SQL Server 2012 Native Client is not already installed, click the appropriate link below to download it:

- » Download the x86 package
- » Download the x64 package

The SQLSRV download comes 8 driver files, four of which are for PDO support.

The most recent version of the driver is available for download here: » SQLSRV download.

For more information about SQLSRV requirements, see » SQLSRV System Requirements.

## Installation

The SQLSRV extension is enabled by adding appropriate DLL file to your PHP extension directory and the corresponding entry to the php.ini file. The SQLSRV download comes with 8 driver files, four of which are for PDO support.

The most recent version of the driver is available for download here: » SQLSRV download.

For more information about SQLSRV requirements, see » SQLSRV System Requirements.

Since version 4.0 the SQLSRV extension is compatible only with PHP 7.0 running on Linux or Windows.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

The following table lists the configuration options available in the SQLSRV extension. For more information about these options, see » Handling SQLSRV Warnings and Errors.

SQLSRV Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
sqlsrv.WarningsReturnAsErrors | 1 (`true`) | `INI_ALL` | Available since SQLSRV 1.0
sqlsrv.LogSubsystems | 0 | `INI_ALL` | Available since SQLSRV 1.0
sqlsrv.LogSeverity | 1 | `INI_ALL` | Available since SQLSRV 1.0

## Ressource-Typen

## Connection resource

A connection resource returned by sqlsrv_connect().

## Statement resource

A statement resource returned by sqlsrv_query() or by sqlsrv_prepare().

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`SQLSRV_FETCH_ASSOC` (int)
  Forces sqlsrv_fetch_array() to return an associative array when passed as a parameter.
`SQLSRV_FETCH_NUMERIC` (int)
  Forces sqlsrv_fetch_array() to return an array with numeric when passed as a parameter.
`SQLSRV_FETCH_BOTH` (int)
  Forces sqlsrv_fetch_array() to return an array with both associative and numeric keys when passed as a parameter (the default behavior).
`SQLSRV_ERR_ALL` (int)
  Forces sqlsrv_errors() to return both errors and warnings when passed as a parameter (the default behavior).
`SQLSRV_ERR_ERRORS` (int)
  Forces sqlsrv_errors() to return errors only (no warnings) when passed as a parameter.
`SQLSRV_ERR_WARNINGS` (int)
  Forces sqlsrv_errors() to return warnings only (no errors) when passed as a parameter.
`SQLSRV_LOG_SYSTEM_ALL` (int)
  Turns on logging of all subsystems when passed to sqlsrv_configure() as a parameter.
`SQLSRV_LOG_SYSTEM_CONN` (int)
  Turns on logging of connection activity when passed to sqlsrv_configure() as a parameter.
`SQLSRV_LOG_SYSTEM_INIT` (int)
  Turns on logging of initialization activity when passed to sqlsrv_configure() as a parameter.
`SQLSRV_LOG_SYSTEM_OFF` (int)
  Turns off logging of all subsystems when passed to sqlsrv_configure() as a parameter.
`SQLSRV_LOG_SYSTEM_STMT` (int)
  Turns on logging of statement activity when passed to sqlsrv_configure() as a parameter.
`SQLSRV_LOG_SYSTEM_UTIL` (int)
  Turns on logging of error function activity when passed to sqlsrv_configure() as a parameter.
`SQLSRV_LOG_SEVERITY_ALL` (int)
  Specifies that errors, warnings, and notices will be logged when passed to sqlsrv_configure() as a parameter.
`SQLSRV_LOG_SEVERITY_ERROR` (int)
  Specifies that errors will be logged when passed to sqlsrv_configure() as a parameter.
`SQLSRV_LOG_SEVERITY_NOTICE` (int)
  Specifies that notices will be logged when passed to sqlsrv_configure() as a parameter.
`SQLSRV_LOG_SEVERITY_WARNING` (int)
  Specifies that warnings will be logged when passed to sqlsrv_configure() as a parameter.
`SQLSRV_NULLABLE_YES` (int)
  Indicates that a column is nullable.
`SQLSRV_NULLABLE_NO` (int)
  Indicates that a column is not nullable.
`SQLSRV_NULLABLE_UNKNOWN` (int)
  Indicates that it is not known if a column is nullable.
`SQLSRV_PARAM_IN` (int)
  Indicates an input parameter when passed to sqlsrv_query() or sqlsrv_prepare().
`SQLSRV_PARAM_INOUT` (int)
  Indicates a bidirectional parameter when passed to sqlsrv_query() or sqlsrv_prepare().
`SQLSRV_PARAM_OUT` (int)
  Indicates an output parameter when passed to sqlsrv_query() or sqlsrv_prepare().
`SQLSRV_PHPTYPE_INT` (int)
  Specifies an integer PHP data type. For usage information, see » How to: Specify PHP Types.
`SQLSRV_PHPTYPE_DATETIME` (int)
  Specifies a datetime PHP data type. For usage information, see » How to: Specify PHP Types.
`SQLSRV_PHPTYPE_FLOAT` (int)
  Specifies a float PHP data type. For usage information, see » How to: Specify PHP Types.
`SQLSRV_PHPTYPE_STREAM` (int)
  Specifies a PHP stream. This constant works like a function and accepts an encoding constant. See the SQLSRV_ENC_* constants. For usage information, see » How to: Specify PHP Types.
`SQLSRV_PHPTYPE_STRING` (int)
  Specifies a string PHP data type. This constant works like a function and accepts an encoding constant. See the SQLSRV_ENC_* constants. For usage information, see » How to: Specify PHP Types.
`SQLSRV_ENC_BINARY` (int)
  Specifies that data is returned as a raw byte stream from the server without performing encoding or translation. For usage information, see » How to: Specify PHP Types.
`SQLSRV_ENC_CHAR` (int)
  Data is returned in 8-bit characters as specified in the code page of the Windows locale that is set on the system. Any multi-byte characters or characters that do not map into this code page are substituted with a single byte question mark (?) character. This is the default encoding. For usage information, see » How to: Specify PHP Types.
`SQLSRV_SQLTYPE_BIGINT` (int)
  Describes the bigint SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_BINARY` (int)
  Describes the binary SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_BIT` (int)
  Describes the bit SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_CHAR` (int)
  Describes the char SQL Server data type. This constant works like a function and accepts a parameter indicating the number characters. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_DATE` (int)
  Describes the date SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_DATETIME` (int)
  Describes the datetime SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_DATETIME2` (int)
  Describes the datetime2 SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_DATETIMEOFFSET` (int)
  Describes the datetimeoffset SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_DECIMAL` (int)
  Describes the decimal SQL Server data type. This constant works like a function and accepts two parameters indicating (in order) precision and scale. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_FLOAT` (int)
  Describes the float SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_IMAGE` (int)
  Describes the image SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_INT` (int)
  Describes the int SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_MONEY` (int)
  Describes the money SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_NCHAR` (int)
  Describes the nchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_NUMERIC` (int)
  Describes the numeric SQL Server data type. This constant works like a function and accepts two parameter indicating (in order) precision and scale. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_NVARCHAR` (int)
  Describes the nvarchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_NVARCHAR`('max') (int)
  Describes the nvarchar(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_NTEXT` (int)
  Describes the ntext SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_REAL` (int)
  Describes the real SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_SMALLDATETIME` (int)
  Describes the smalldatetime SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_SMALLINT` (int)
  Describes the smallint SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_SMALLMONEY` (int)
  Describes the smallmoney SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_TEXT` (int)
  Describes the text SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_TIME` (int)
  Describes the time SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_TIMESTAMP` (int)
  Describes the timestamp SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_TINYINT` (int)
  Describes the tinyint SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_UNIQUEIDENTIFIER` (int)
  Describes the uniqueidentifier SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_UDT` (int)
  Describes the UDT SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_VARBINARY` (int)
  Describes the varbinary SQL Server data type. This constant works like a function and accepts a single parameter indicating the byte count. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_VARBINARY`('max') (int)
  Describes the varbinary(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_VARCHAR` (int)
  Describes the varchar SQL Server data type. This constant works like a function and accepts a single parameter indicating the character count. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_VARCHAR`('max') (int)
  Describes the varchar(MAX) SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_SQLTYPE_XML` (int)
  Describes the XML SQL Server data type. For usage information, see » How to: Specify SQL Types.
`SQLSRV_TXN_READ_UNCOMMITTED` (int)
  Indicates a transaction isolation level of READ UNCOMMITTED. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
`SQLSRV_TXN_READ_COMMITTED` (int)
  Indicates a transaction isolation level of READ COMMITTED. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
`SQLSRV_TXN_REPEATABLE_READ` (int)
  Indicates a transaction isolation level of REPEATABLE READ. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
`SQLSRV_TXN_SNAPSHOT` (int)
  Indicates a transaction isolation level of SNAPSHOT. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
`SQLSRV_TXN_READ_SERIALIZABLE` (int)
  Indicates a transaction isolation level of SERIALIZABLE. This value is used to set the TransactionIsolation level in the $connectionOptions array passed to sqlsrv_connect().
`SQLSRV_CURSOR_FORWARD` (int)
  Indicates a forward-only cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_CURSOR_STATIC` (int)
  Indicates a static cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_CURSOR_DYNAMIC` (int)
  Indicates a dynamic cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_CURSOR_KEYSET` (int)
  Indicates a keyset cursor. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_CURSOR_BUFFERED` (int)
  Creates a client-side cursor query. Lets you access rows in any order. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_SCROLL_NEXT` (int)
  Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_SCROLL_PRIOR` (int)
  Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_SCROLL_FIRST` (int)
  Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_SCROLL_LAST` (int)
  Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_SCROLL_ABSOLUTE` (int)
  Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.
`SQLSRV_SCROLL_RELATIVE` (int)
  Specifies which row to select in a result set. For usage information, see » Specifying a Cursor Type and Selecting Rows.

# SQLSRV Funktionen

# sqlsrv_begin_transaction

(No version information available, might only be in Git)

sqlsrv_begin_transaction — Begins a database transaction

### Beschreibung

function sqlsrv_begin_transaction(resource `$conn`): bool

The transaction begun by sqlsrv_begin_transaction() includes all statements that were executed after the call to sqlsrv_begin_transaction() and before calls to sqlsrv_rollback() or sqlsrv_commit(). Explicit transactions should be started and committed or rolled back using these functions instead of executing SQL statements that begin and commit/roll back transactions. For more information, see » SQLSRV Transactions.

### Parameter-Liste

`conn`
  The connection resource returned by a call to sqlsrv_connect().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 sqlsrv_begin_transaction() example

The following example demonstrates how to use sqlsrv_begin_transaction() together with sqlsrv_commit() and sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Begin the transaction. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Initialize parameter values. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Set up and execute the first query. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
              VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Set up and execute the second query. */
    $sql2 = "UPDATE InventoryTable
              SET Quantity = (Quantity - ?)
              WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* If both queries were successful, commit the transaction. */
    /* Otherwise, rollback the transaction. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaction committed.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaction rolled back.<br />";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- sqlsrv_commit() - Commits a transaction that was begun with sqlsrv_begin_transaction
- sqlsrv_rollback() - Rolls back a transaction that was begun with sqlsrv_begin_transaction

# sqlsrv_cancel

(No version information available, might only be in Git)

sqlsrv_cancel — Cancels a statement

### Beschreibung

function sqlsrv_cancel(resource `$stmt`): bool

Cancels a statement. Any results associated with the statement that have not been consumed are deleted. After sqlsrv_cancel() has been called, the specified statement can be re-executed if it was created with sqlsrv_prepare(). Calling sqlsrv_cancel() is not necessary if all the results associated with the statement have been consumed.

### Parameter-Liste

`stmt`
  The statement resource to be cancelled.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 sqlsrv_cancel() example

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Sales FROM Table_1";

    $stmt = sqlsrv_prepare( $conn, $sql);

    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    if( sqlsrv_execute( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    $salesTotal = 0;
    $count = 0;

    while( ($row = sqlsrv_fetch_array( $stmt)) && $salesTotal <=100000)
    {
         $qty = $row[0];
         $price = $row[1];
         $salesTotal += ( $price * $qty);
         $count++;
    }

    echo "$count sales accounted for the first $$salesTotal in revenue.<br />";

    // Cancel the pending results. The statement can be reused.
    sqlsrv_cancel( $stmt);
    ?>

### Anmerkungen

The main difference between sqlsrv_cancel() and sqlsrv_free_stmt() is that a statement resource cancelled with sqlsrv_cancel() can be re-executed if it was created with sqlsrv_prepare(). A statement resource cancelled with sqlsrv_free_statement() cannot be re-executed.

### Siehe auch

- sqlsrv_free_stmt() - Frees all resources for the specified statement
- sqlsrv_prepare() - Prepares a query for execution

# sqlsrv_client_info

(No version information available, might only be in Git)

sqlsrv_client_info — Returns information about the client and specified connection

### Beschreibung

function sqlsrv_client_info(resource `$conn`): array

Returns information about the client and specified connection

### Parameter-Liste

`conn`
  The connection about which information is returned.

### Rückgabewerte

Returns an associative array with keys described in the table below. Returns `false` otherwise.

Array returned by sqlsrv_client_info
Key | Description
--- | ---
DriverDllName | SQLNCLI10.DLL
DriverODBCVer | ODBC version (xx.yy)
DriverVer | SQL Server Native Client DLL version (10.5.xxx)
ExtensionVer | php_sqlsrv.dll version (2.0.xxx.x)

### Beispiele

Beispiel #1 sqlsrv_client_info() example

    <?php
    $serverName = "serverName\sqlexpress";
    $connOptions = array("UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connOptions );

    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    if( $client_info = sqlsrv_client_info( $conn)) {
        foreach( $client_info as $key => $value) {
            echo $key.": ".$value."<br />";
        }
    } else {
        echo "Error in retrieving client info.<br />";
    }
    ?>

### Siehe auch

- sqlsrv_server_info() - Returns information about the server

# sqlsrv_close

(No version information available, might only be in Git)

sqlsrv_close — Closes an open connection and releases resources associated with the connection

### Beschreibung

function sqlsrv_close(resource `$conn`): bool

Closes an open connection and releases resources associated with the connection.

### Parameter-Liste

`conn`
  The connection to be closed.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 sqlsrv_close() example

    <?php
    $serverName = "serverName\sqlexpres";
    $connOptions = array("UID"=>"username", "PWD"=>"password", "Database"=>"dbname");
    $conn = sqlsrv_connect( $serverName, $connOptions );
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    //-------------------------------------
    // Perform database operations here.
    //-------------------------------------

    // Close the connection.
    sqlsrv_close( $conn );
    ?>

### Siehe auch

- sqlsrv_connect() - Opens a connection to a Microsoft SQL Server database

# sqlsrv_commit

(No version information available, might only be in Git)

sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction()

### Beschreibung

function sqlsrv_commit(resource `$conn`): bool

Commits a transaction that was begun with sqlsrv_begin_transaction(). The connection is returned to auto-commit mode after sqlsrv_commit() is called. The transaction that is committed includes all statements that were executed after the call to sqlsrv_begin_transaction(). Explicit transactions should be started and committed or rolled back using these functions instead of executing SQL statements that begin and commit/roll back transactions. For more information, see » SQLSRV Transactions.

### Parameter-Liste

`conn`
  The connection on which the transaction is to be committed.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 sqlsrv_commit() example

The following example demonstrates how to use sqlsrv_commit() together with sqlsrv_begin_transaction() and sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Begin the transaction. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Initialize parameter values. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Set up and execute the first query. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Set up and execute the second query. */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* If both queries were successful, commit the transaction. */
    /* Otherwise, rollback the transaction. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaction committed.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaction rolled back.<br />";
    }
    ?>

### Siehe auch

- sqlsrv_begin_transaction() - Begins a database transaction
- sqlsrv_rollback() - Rolls back a transaction that was begun with sqlsrv_begin_transaction

# sqlsrv_configure

(No version information available, might only be in Git)

sqlsrv_configure — Changes the driver error handling and logging configurations

### Beschreibung

function sqlsrv_configure(string `$setting`, mixed `$value`): bool

Changes the driver error handling and logging configurations.

### Parameter-Liste

`setting`
  The name of the setting to set. The possible values are "WarningsReturnAsErrors", "LogSubsystems", and "LogSeverity".
`value`

  The value of the specified setting. The following table shows possible values:

  Error and Logging Setting Options
  Setting | Options
  --- | ---
  WarningsReturnAsErrors | 1 (`true`) or 0 (`false`)
  LogSubsystems | SQLSRV_LOG_SYSTEM_ALL (-1) SQLSRV_LOG_SYSTEM_CONN (2) SQLSRV_LOG_SYSTEM_INIT (1) SQLSRV_LOG_SYSTEM_OFF (0) SQLSRV_LOG_SYSTEM_STMT (4) SQLSRV_LOG_SYSTEM_UTIL (8)
  LogSeverity | SQLSRV_LOG_SEVERITY_ALL (-1) SQLSRV_LOG_SEVERITY_ERROR (1) SQLSRV_LOG_SEVERITY_NOTICE (4) SQLSRV_LOG_SEVERITY_WARNING (2)

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- » SQLSRV Error Handling.
- » Logging SQLSRV Activity.

# sqlsrv_connect

(No version information available, might only be in Git)

sqlsrv_connect — Opens a connection to a Microsoft SQL Server database

### Beschreibung

function sqlsrv_connect(string `$serverName`, array `$connectionInfo` = ?): resource

Opens a connection to a Microsoft SQL Server database. By default, the connection is attempted using Windows Authentication. To connect using SQL Server Authentication, include "UID" and "PWD" in the connection options array.

### Parameter-Liste

`serverName`
  The name of the server to which a connection is established. To connect to a specific instance, follow the server name with a backward slash and the instance name (e.g. serverName\sqlexpress).
`connectionInfo`
  An associative array that specifies options for connecting to the server. If values for the UID and PWD keys are not specified, the connection will be attempted using Windows Authentication. For a complete list of supported keys, see » SQLSRV Connection Options.

### Rückgabewerte

A connection resource. If a connection cannot be successfully opened, `false` is returned.

### Beispiele

Beispiel #1 Connect using Windows Authentication.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName

    // Since UID and PWD are not specified in the $connectionInfo array,
    // The connection will be attempted using Windows Authentication.
    $connectionInfo = array( "Database"=>"dbName");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Connection established.<br />";
    }else{
         echo "Connection could not be established.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Beispiel #2 Connect by specifying a user name and password.

    <?php
    $serverName = "serverName\\sqlexpress"; //serverName\instanceName
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Connection established.<br />";
    }else{
         echo "Connection could not be established.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

Beispiel #3 Connect on a specified port.

    <?php
    $serverName = "serverName\\sqlexpress, 1542"; //serverName\instanceName, portNumber (default is 1433)
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    if( $conn ) {
         echo "Connection established.<br />";
    }else{
         echo "Connection could not be established.<br />";
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Anmerkungen

By default, the sqlsrv_connect() uses connection pooling to improve connection performance. To turn off connection pooling (i.e. force a new connection on each call), set the "ConnectionPooling" option in the $connectionOptions array to 0 (or `false`). For more information, see » SQLSRV Connection Pooling.

The SQLSRV extension does not have a dedicated function for changing which database is connected to. The target database is specified in the $connectionOptions array that is passed to sqlsrv_connect. To change the database on an open connection, execute the following query "USE dbName" (e.g. sqlsrv_query($conn, "USE dbName")).

### Siehe auch

- sqlsrv_close() - Closes an open connection and releases resources associated with the connection
- sqlsrv_errors() - Returns error and warning information about the last SQLSRV operation performed
- sqlsrv_query() - Prepares and executes a query

# sqlsrv_errors

(No version information available, might only be in Git)

sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed

### Beschreibung

function sqlsrv_errors(int `$errorsOrWarnings` = ?): mixed

Returns error and warning information about the last SQLSRV operation performed.

### Parameter-Liste

`errorsOrWarnings`
  Determines whether error information, warning information, or both are returned. If this parameter is not supplied, both error information and warning information are returned. The following are the supported values for this parameter: SQLSRV_ERR_ALL, SQLSRV_ERR_ERRORS, SQLSRV_ERR_WARNINGS.

### Rückgabewerte

If errors and/or warnings occurred on the last sqlsrv operation, an array of arrays containing error information is returned. If no errors and/or warnings occurred on the last sqlsrv operation, `null` is returned. The following table describes the structure of the returned arrays:

Array returned by sqlsrv_errors
Key | Description
--- | ---
SQLSTATE | For errors that originate from the ODBC driver, the SQLSTATE returned by ODBC. For errors that originate from the Microsoft Drivers for PHP for SQL Server, a SQLSTATE of IMSSP. For warnings that originate from the Microsoft Drivers for PHP for SQL Server, a SQLSTATE of 01SSP.
code | For errors that originate from SQL Server, the native SQL Server error code. For errors that originate from the ODBC driver, the error code returned by ODBC. For errors that originate from the Microsoft Drivers for PHP for SQL Server, the Microsoft Drivers for PHP for SQL Server error code.
message | A description of the error.

### Beispiele

Beispiel #1 functionname() example

    <?php
    $serverName = "serverName/sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /* Set up a query to select an invalid column name. */
    $sql = "SELECT BadColumnName FROM Table_1";

    /* Execution of the query will fail because of the bad column name. */
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false ) {
        if( ($errors = sqlsrv_errors() ) != null) {
            foreach( $errors as $error ) {
                echo "SQLSTATE: ".$error[ 'SQLSTATE']."<br />";
                echo "code: ".$error[ 'code']."<br />";
                echo "message: ".$error[ 'message']."<br />";
            }
        }
    }
    ?>

### Anmerkungen

By default, warnings generated on a call to any SQLSRV function are treated as errors. This means that if a warning occurs on a call to a SQLSRV function, the function returns `false`. However, warnings that correspond to SQLSTATE values 01000, 01001, 01003, and 01S02 are never treated as errors. For information about changing this behavior, see sqlsrv_configure() and the WarningsReturnAsErrors setting.

### Siehe auch

- sqlsrv_configure() - Changes the driver error handling and logging configurations

# sqlsrv_execute

(No version information available, might only be in Git)

sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare()

### Beschreibung

function sqlsrv_execute(resource `$stmt`): bool

Executes a statement prepared with sqlsrv_prepare(). This function is ideal for executing a prepared statement multiple times with different parameter values.

### Parameter-Liste

`stmt`
  A statement resource returned by sqlsrv_prepare().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 sqlsrv_execute() example

This example demonstrates how to prepare a statement with sqlsrv_prepare() and re-execute it multiple times (with different parameter values) using sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Initialize parameters and prepare the statement.
    // Variables $qty and $id are bound to the statement, $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Set up the SalesOrderDetailID and OrderQty information.
    // This array maps the order ID to order quantity in key=>value pairs.
    $orders = array( 1=>10, 2=>20, 3=>30);

    // Execute the statement for each order.
    foreach( $orders as $id => $qty) {
        // Because $id and $qty are bound to $stmt1, their updated
        // values are used with each execution of the statement.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Anmerkungen

When you prepare a statement that uses variables as parameters, the variables are bound to the statement. This means that if you update the values of the variables, the next time you execute the statement it will run with updated parameter values. For statements that you plan to execute only once, use sqlsrv_query().

### Siehe auch

- sqlsrv_prepare() - Prepares a query for execution
- sqlsrv_query() - Prepares and executes a query

# sqlsrv_fetch

(No version information available, might only be in Git)

sqlsrv_fetch — Makes the next row in a result set available for reading

### Beschreibung

function sqlsrv_fetch(resource `$stmt`, int `$row` = ?, int `$offset` = ?): mixed

Makes the next row in a result set available for reading. Use sqlsrv_get_field() to read the fields of the row.

### Parameter-Liste

`stmt`
  A statement resource created by executing sqlsrv_query() or sqlsrv_execute().
`row`

  The row to be accessed. This parameter can only be used if the specified statement was prepared with a scrollable cursor. In that case, this parameter can take on one of the following values:

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Specifies the row to be accessed if the row parameter is set to `SQLSRV_SCROLL_ABSOLUTE` or `SQLSRV_SCROLL_RELATIVE`. Note that the first row in a result set has index 0.

### Rückgabewerte

Returns `true` if the next row of a result set was successfully retrieved, `false` if an error occurs, and `null` if there are no more rows in the result set.

### Beispiele

Beispiel #1 sqlsrv_fetch() example

The following example demonstrates how to retrieve a row with sqlsrv_fetch() and get the row fields with sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Make the first (and in this case, only) row of the result set available for reading.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Get the row fields. Field indices start at 0 and must be retrieved in order.
    // Retrieving row fields by name is not supported by sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Siehe auch

- sqlsrv_get_field() - Gets field data from the currently selected row
- sqlsrv_fetch_array() - Returns a row as an array
- sqlsrv_fetch_object() - Retrieves the next row of data in a result set as an object

# sqlsrv_fetch_array

(No version information available, might only be in Git)

sqlsrv_fetch_array — Returns a row as an array

### Beschreibung

function sqlsrv_fetch_array(
resource `$stmt`,
int `$fetchType` = ?,
int `$row` = ?,
int `$offset` = ?
): array

Returns the next available row of data as an associative array, a numeric array, or both (the default).

### Parameter-Liste

`stmt`
  A statement resource returned by sqlsrv_query or sqlsrv_prepare.
`fetchType`
  A predefined constant specifying the type of array to return. Possible values are `SQLSRV_FETCH_ASSOC`, `SQLSRV_FETCH_NUMERIC`, and `SQLSRV_FETCH_BOTH` (the default). A fetch type of SQLSRV_FETCH_ASSOC should not be used when consuming a result set with multiple columns of the same name.
`row`
  Specifies the row to access in a result set that uses a scrollable cursor. Possible values are `SQLSRV_SCROLL_NEXT`, `SQLSRV_SCROLL_PRIOR`, `SQLSRV_SCROLL_FIRST`, `SQLSRV_SCROLL_LAST`, `SQLSRV_SCROLL_ABSOLUTE` and, `SQLSRV_SCROLL_RELATIVE` (the default). When this parameter is specified, the `fetchType` must be explicitly defined.
`offset`
  Specifies the row to be accessed if the row parameter is set to `SQLSRV_SCROLL_ABSOLUTE` or `SQLSRV_SCROLL_RELATIVE`. Note that the first row in a result set has index 0.

### Rückgabewerte

Returns an array on success, `null` if there are no more rows to return, and `false` if an error occurs.

### Beispiele

Beispiel #1 Retrieving an associative array.

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC) ) {
          echo $row['LastName'].", ".$row['FirstName']."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

Beispiel #2 Retrieving a numeric array.

    <?php
    $serverName = "serverName\instanceName";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo );
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT FirstName, LastName FROM SomeTable";
    $stmt = sqlsrv_query( $conn, $sql );
    if( $stmt === false) {
        die( print_r( sqlsrv_errors(), true) );
    }

    while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_NUMERIC) ) {
          echo $row[0].", ".$row[1]."<br />";
    }

    sqlsrv_free_stmt( $stmt);
    ?>

### Anmerkungen

Not specifying the `fetchType` or explicitly using the `SQLSRV_FETCH_TYPE` constant in the examples above will return an array that has both associative and numeric keys.

If more than one column is returned with the same name, the last column will take precedence. To avoid field name collisions, use aliases.

If a column with no name is returned, the associative key for the array element will be an empty string ("").

### Siehe auch

- sqlsrv_connect() - Opens a connection to a Microsoft SQL Server database
- sqlsrv_query() - Prepares and executes a query
- sqlsrv_errors() - Returns error and warning information about the last SQLSRV operation performed
- sqlsrv_fetch() - Makes the next row in a result set available for reading

# sqlsrv_fetch_object

(No version information available, might only be in Git)

sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object

### Beschreibung

function sqlsrv_fetch_object(
resource `$stmt`,
string `$className` = ?,
array `$ctorParams` = ?,
int `$row` = ?,
int `$offset` = ?
): mixed

Retrieves the next row of data in a result set as an instance of the specified class with properties that match the row field names and values that correspond to the row field values.

### Parameter-Liste

`stmt`
  A statement resource created by sqlsrv_query() or sqlsrv_execute().
`className`
  The name of the class to instantiate. If no class name is specified, stdClass is instantiated.
`ctorParams`
  Values passed to the constructor of the specified class. If the constructor of the specified class takes parameters, the ctorParams array must be supplied.
`row`

  The row to be accessed. This parameter can only be used if the specified statement was prepared with a scrollable cursor. In that case, this parameter can take on one of the following values:

  - SQLSRV_SCROLL_NEXT
  - SQLSRV_SCROLL_PRIOR
  - SQLSRV_SCROLL_FIRST
  - SQLSRV_SCROLL_LAST
  - SQLSRV_SCROLL_ABSOLUTE
  - SQLSRV_SCROLL_RELATIVE
`offset`
  Specifies the row to be accessed if the row parameter is set to `SQLSRV_SCROLL_ABSOLUTE` or `SQLSRV_SCROLL_RELATIVE`. Note that the first row in a result set has index 0.

### Rückgabewerte

Returns an object on success, `null` if there are no more rows to return, and `false` if an error occurs or if the specified class does not exist.

### Beispiele

Beispiel #1 sqlsrv_fetch_object() example

The following example demonstrates how to retrieve a row as a stdClass object.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT fName, lName FROM Table_1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Retrieve each row as an object.
    // Because no class is specified, each row will be retrieved as a stdClass object.
    // Property names correspond to field names.
    while( $obj = sqlsrv_fetch_object( $stmt)) {
          echo $obj->fName.", ".$obj->lName."<br />";
    }
    ?>

### Anmerkungen

If a class name is specified with the optional $className parameter and the class has properties whose names match the result set field names, the corresponding result set values are applied to the properties. If a result set field name does not match a class property, a property with the result set field name is added to the object and the result set value is applied to the property. The following rules apply when using the $className parameter:

- Field-property name matching is case-sensitive.
- Field-property matching occurs regardless of access modifiers.
- Class property data types are ignored when applying a field value to a property.
- If the class does not exist, the function returns `false` and adds an error to the error collection.

Regardless of whether the $className parameter is supplied, if a field with no name is returned, the field value will be ignored and a warning will be added to the error collection.

When consuming a result set that has multiple columns with the same name, it may be better to use sqlsrv_fetch_array() or the combination of sqlsrv_fetch() and sqlsrv_get_field().

### Siehe auch

- sqlsrv_fetch() - Makes the next row in a result set available for reading
- sqlsrv_fetch_array() - Returns a row as an array

# sqlsrv_field_metadata

(No version information available, might only be in Git)

sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare() or sqlsrv_query()

### Beschreibung

function sqlsrv_field_metadata(resource `$stmt`): mixed

Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare() or sqlsrv_query(). sqlsrv_field_metadata() can be called on a statement before or after statement execution.

### Parameter-Liste

`stmt`
  The statement resource for which metadata is returned.

### Rückgabewerte

Returns an array of arrays on success. Otherwise, `false` is returned. Each returned array is described by the following table:

Array returned by sqlsrv_field_metadata
Key | Description
--- | ---
Name | The name of the field.
Type | The numeric value for the SQL type.
Size | The number of characters for fields of character type, the number of bytes for fields of binary type, or `null` for other types.
Precision | The precision for types of variable precision, `null` for other types.
Scale | The scale for types of variable scale, `null` for other types.
Nullable | An enumeration indicating whether the column is nullable, not nullable, or if it is not known.

For more information, see » sqlsrv_field_metadata in the Microsoft SQLSRV documentation.

### Beispiele

Beispiel #1 sqlsrv_field_metadata() example

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"AdventureWorks", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_prepare( $conn, $sql );

    foreach( sqlsrv_field_metadata( $stmt ) as $fieldMetadata ) {
        foreach( $fieldMetadata as $name => $value) {
           echo "$name: $value<br />";
        }
          echo "<br />";
    }
    ?>

### Siehe auch

- sqlsrv_client_info() - Returns information about the client and specified connection

# sqlsrv_free_stmt

(No version information available, might only be in Git)

sqlsrv_free_stmt — Frees all resources for the specified statement

### Beschreibung

function sqlsrv_free_stmt(resource `$stmt`): bool

Frees all resources for the specified statement. The statement cannot be used after sqlsrv_free_stmt() has been called on it. If sqlsrv_free_stmt() is called on an in-progress statement that alters server state, statement execution is terminated and the statement is rolled back.

### Parameter-Liste

`stmt`
  The statement for which resources are freed. Note that `null` is a valid parameter value. This allows the function to be called multiple times in a script.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 sqlsrv_free_stmt() example

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    /*-------------------------------
         Process query results here.
    -------------------------------*/

    /* Free the statement resources. */
    sqlsrv_free_stmt( $stmt);

    ?>

### Anmerkungen

The main difference between sqlsrv_free_stmt() and sqlsrv_cancel() is that a statement resource cancelled with sqlsrv_cancel() can be re-executed if it was created with sqlsrv_prepare(). A statement resource cancelled with sqlsrv_free_statement() cannot be re-executed.

### Siehe auch

- sqlsrv_cancel() - Cancels a statement

# sqlsrv_get_config

(No version information available, might only be in Git)

sqlsrv_get_config — Returns the value of the specified configuration setting

### Beschreibung

function sqlsrv_get_config(string `$setting`): mixed

Returns the value of the specified configuration setting.

### Parameter-Liste

`setting`
  The name of the setting for which the value is returned. For a list of configurable settings, see sqlsrv_configure().

### Rückgabewerte

Returns the value of the specified setting. If an invalid setting is specified, `false` is returned.

### Siehe auch

- sqlsrv_configure() - Changes the driver error handling and logging configurations

# sqlsrv_get_field

(No version information available, might only be in Git)

sqlsrv_get_field — Gets field data from the currently selected row

### Beschreibung

function sqlsrv_get_field(resource `$stmt`, int `$fieldIndex`, int `$getAsType` = ?): mixed

Gets field data from the currently selected row. Fields must be accessed in order. Field indices start at 0.

### Parameter-Liste

`stmt`
  A statement resource returned by sqlsrv_query() or sqlsrv_execute().
`fieldIndex`
  The index of the field to be retrieved. Field indices start at 0. Fields must be accessed in order. i.e. If you access field index 1, then field index 0 will not be available.
`getAsType`
  The PHP data type for the returned field data. If this parameter is not set, the field data will be returned as its default PHP data type. For information about default PHP data types, see » Default PHP Data Types in the Microsoft SQLSRV documentation.

### Rückgabewerte

Returns data from the specified field on success. Returns `false` otherwise.

### Beispiele

Beispiel #1 sqlsrv_get_field() example

The following example demonstrates how to retrieve a row with sqlsrv_fetch() and get the row fields with sqlsrv_get_field().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT Name, Comment
            FROM Table_1
            WHERE ReviewID=1";
    $stmt = sqlsrv_query( $conn, $sql);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Make the first (and in this case, only) row of the result set available for reading.
    if( sqlsrv_fetch( $stmt ) === false) {
         die( print_r( sqlsrv_errors(), true));
    }

    // Get the row fields. Field indices start at 0 and must be retrieved in order.
    // Retrieving row fields by name is not supported by sqlsrv_get_field.
    $name = sqlsrv_get_field( $stmt, 0);
    echo "$name: ";

    $comment = sqlsrv_get_field( $stmt, 1);
    echo $comment;
    ?>

### Siehe auch

- sqlsrv_fetch() - Makes the next row in a result set available for reading
- sqlsrv_fetch_array() - Returns a row as an array
- sqlsrv_fetch_object() - Retrieves the next row of data in a result set as an object

# sqlsrv_has_rows

(No version information available, might only be in Git)

sqlsrv_has_rows — Indicates whether the specified statement has rows

### Beschreibung

function sqlsrv_has_rows(resource `$stmt`): bool

Indicates whether the specified statement has rows.

### Parameter-Liste

`stmt`
  A statement resource returned by sqlsrv_query() or sqlsrv_execute().

### Rückgabewerte

Returns `true` if the specified statement has rows and `false` if the statement does not have rows or if an error occurred.

### Beispiele

Beispiel #1 sqlsrv_has_rows() example

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $stmt = sqlsrv_query( $conn, "SELECT * FROM Table_1");

    if ($stmt) {
       $rows = sqlsrv_has_rows( $stmt );
       if ($rows === true)
          echo "There are rows. <br />";
       else
          echo "There are no rows. <br />";
    }
    ?>

### Siehe auch

- sqlsrv_num_rows() - Retrieves the number of rows in a result set
- sqlsrv_query() - Prepares and executes a query

# sqlsrv_next_result

(No version information available, might only be in Git)

sqlsrv_next_result — Makes the next result of the specified statement active

### Beschreibung

function sqlsrv_next_result(resource `$stmt`): mixed

Makes the next result of the specified statement active. Results include result sets, row counts, and output parameters.

### Parameter-Liste

`stmt`
  The statement on which the next result is being called.

### Rückgabewerte

Returns `true` if the next result was successfully retrieved, `false` if an error occurred, and `null` if there are no more results to retrieve.

### Beispiele

Beispiel #1 sqlsrv_next_result() example

The following example executes a batch query that inserts into a table and then selects from the table. This produces two results on the statement: one for the rows affected by the INSERT and one for the rows returned by the SELECT. To get to the rows returned by the SELECT, sqlsrv_next_result() must be called to move past the first result.

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array("Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);

    $query = "INSERT INTO Table_1 (id, data) VALUES (?,?); SELECT * FROM TABLE_1;";
    $params = array(1, "some data");
    $stmt = sqlsrv_query($conn, $query, $params);

    // Consume the first result (rows affected by INSERT) without calling sqlsrv_next_result.
    echo "Rows affected: ".sqlsrv_rows_affected($stmt)."<br />";

    // Move to the next result and display results.
    $next_result = sqlsrv_next_result($stmt);
    if( $next_result ) {
       while( $row = sqlsrv_fetch_array( $stmt, SQLSRV_FETCH_ASSOC)){
          echo $row['id'].": ".$row['data']."<br />";
       }
    } elseif( is_null($next_result)) {
         echo "No more results.<br />";
    } else {
         die(print_r(sqlsrv_errors(), true));
    }
    ?>

### Siehe auch

- sqlsrv_query() - Prepares and executes a query
- sqlsrv_fetch_array() - Returns a row as an array
- sqlsrv_rows_affected() - Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

# sqlsrv_num_fields

(No version information available, might only be in Git)

sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement

### Beschreibung

function sqlsrv_num_fields(resource `$stmt`): mixed

Retrieves the number of fields (columns) on a statement.

### Parameter-Liste

`stmt`
  The statement for which the number of fields is returned. sqlsrv_num_fields() can be called on a statement before or after statement execution.

### Rückgabewerte

Returns the number of fields on success. Returns `false` otherwise.

### Beispiele

Beispiel #1 sqlsrv_num_fields() example

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
       die( print_r( sqlsrv_errors(), true));
    }

    $sql = "SELECT * FROM Table_1";
    $stmt = sqlsrv_query($conn, $sql);
    if( $stmt === false) {
       die( print_r( sqlsrv_errors(), true));
    }

    $numFields = sqlsrv_num_fields( $stmt );

    while( sqlsrv_fetch( $stmt )) {
       // Iterate through the fields of each row.
       for($i = 0; $i < $numFields; $i++) {
          echo sqlsrv_get_field($stmt, $i)." ";
       }
       echo "<br />";
    }
    ?>

### Siehe auch

- sqlsrv_field_metadata() - Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
- sqlsrv_fetch() - Makes the next row in a result set available for reading
- sqlsrv_get_field() - Gets field data from the currently selected row

# sqlsrv_num_rows

(No version information available, might only be in Git)

sqlsrv_num_rows — Retrieves the number of rows in a result set

### Beschreibung

function sqlsrv_num_rows(resource `$stmt`): mixed

Retrieves the number of rows in a result set. This function requires that the statement resource be created with a static or keyset cursor. For more information, see sqlsrv_query(), sqlsrv_prepare(), or » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

### Parameter-Liste

`stmt`
  The statement for which the row count is returned. The statement resource must be created with a static or keyset cursor. For more information, see sqlsrv_query(), sqlsrv_prepare(), or » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

### Rückgabewerte

Returns the number of rows retrieved on success and `false` if an error occurred. If a forward cursor (the default) or dynamic cursor is used, `false` is returned.

### Beispiele

Beispiel #1 sqlsrv_num_rows() example

    <?php
    $server = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $server, $connectionInfo );

    $sql = "SELECT * FROM Table_1";
    $params = array();
    $options =  array( "Scrollable" => SQLSRV_CURSOR_KEYSET );
    $stmt = sqlsrv_query( $conn, $sql , $params, $options );

    $row_count = sqlsrv_num_rows( $stmt );

    if ($row_count === false)
       echo "Error in retrieving row count.";
    else
       echo $row_count;
    ?>

### Siehe auch

- sqlsrv_has_rows() - Indicates whether the specified statement has rows
- sqlsrv_rows_affected() - Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

# sqlsrv_prepare

(No version information available, might only be in Git)

sqlsrv_prepare — Prepares a query for execution

### Beschreibung

function sqlsrv_prepare(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Prepares a query for execution. This function is ideal for preparing a query that will be executed multiple times with different parameter values.

### Parameter-Liste

`conn`
  A connection resource returned by sqlsrv_connect().
`sql`
  The string that defines the query to be prepared and executed.
`params`

  An array specifying parameter information when executing a parameterized query. Array elements can be any of the following:

  - A literal value
  - A PHP variable
  - An array with this structure: array($value [, $direction [, $phpType [, $sqlType]]])
  The following table describes the elements in the array structure above:

  Array structure
  Element | Description
  --- | ---
  $value | A literal value, a PHP variable, or a PHP by-reference variable.
  $direction (optional) | One of the following SQLSRV constants used to indicate the parameter direction: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. The default value is SQLSRV_PARAM_IN.
  $phpType (optional) | A SQLSRV_PHPTYPE_* constant that specifies PHP data type of the returned value.
  $sqlType (optional) | A SQLSRV_SQLTYPE_* constant that specifies the SQL Server data type of the input value.

`options`
  An array specifying query property options. The supported keys are described in the following table:

  Query Options
  Key | Values | Description
  --- | --- | ---
  QueryTimeout | A positive integer value. | Sets the query timeout in seconds. By default, the driver will wait indefinitely for results.
  SendStreamParamsAtExec | `true` or `false` (the default is `true`) | Configures the driver to send all stream data at execution (`true`), or to send stream data in chunks (`false`). By default, the value is set to `true`. For more information, see sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, or SQLSRV_CURSOR_KEYSET | See » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

### Rückgabewerte

Returns a statement resource on success and `false` if an error occurred.

### Beispiele

Beispiel #1 sqlsrv_prepare() example

This example demonstrates how to prepare a statement with sqlsrv_prepare() and re-execute it multiple times (with different parameter values) using sqlsrv_execute().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false) {
        die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1
            SET OrderQty = ?
            WHERE SalesOrderID = ?";

    // Initialize parameters and prepare the statement.
    // Variables $qty and $id are bound to the statement, $stmt.
    $qty = 0; $id = 0;
    $stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
    if( !$stmt ) {
        die( print_r( sqlsrv_errors(), true));
    }

    // Set up the SalesOrderDetailID and OrderQty information.
    // This array maps the order ID to order quantity in key=>value pairs.
    $orders = array( 1=>10, 2=>20, 3=>30);

    // Execute the statement for each order.
    foreach( $orders as $id => $qty) {
        // Because $id and $qty are bound to $stmt1, their updated
        // values are used with each execution of the statement.
        if( sqlsrv_execute( $stmt ) === false ) {
              die( print_r( sqlsrv_errors(), true));
        }
    }
    ?>

### Anmerkungen

When you prepare a statement that uses variables as parameters, the variables are bound to the statement. This means that if you update the values of the variables, the next time you execute the statement it will run with updated parameter values. For statements that you plan to execute only once, use sqlsrv_query().

### Siehe auch

- sqlsrv_execute() - Executes a statement prepared with sqlsrv_prepare
- sqlsrv_query() - Prepares and executes a query

# sqlsrv_query

(No version information available, might only be in Git)

sqlsrv_query — Prepares and executes a query

### Beschreibung

function sqlsrv_query(
resource `$conn`,
string `$sql`,
array `$params` = ?,
array `$options` = ?
): mixed

Prepares and executes a query.

### Parameter-Liste

`conn`
  A connection resource returned by sqlsrv_connect().
`sql`
  The string that defines the query to be prepared and executed.
`params`

  An array specifying parameter information when executing a parameterized query. Array elements can be any of the following:

  - A literal value
  - A PHP variable
  - An array with this structure: array($value [, $direction [, $phpType [, $sqlType]]])
  The following table describes the elements in the array structure above:

  Array structure
  Element | Description
  --- | ---
  $value | A literal value, a PHP variable, or a PHP by-reference variable.
  $direction (optional) | One of the following SQLSRV constants used to indicate the parameter direction: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. The default value is SQLSRV_PARAM_IN.
  $phpType (optional) | A SQLSRV_PHPTYPE_* constant that specifies PHP data type of the returned value.
  $sqlType (optional) | A SQLSRV_SQLTYPE_* constant that specifies the SQL Server data type of the input value.

`options`
  An array specifying query property options. The supported keys are described in the following table:

  Query Options
  Key | Values | Description
  --- | --- | ---
  QueryTimeout | A positive integer value. | Sets the query timeout in seconds. By default, the driver will wait indefinitely for results.
  SendStreamParamsAtExec | `true` or `false` (the default is `true`) | Configures the driver to send all stream data at execution (`true`), or to send stream data in chunks (`false`). By default, the value is set to `true`. For more information, see sqlsrv_send_stream_data().
  Scrollable | SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, or SQLSRV_CURSOR_KEYSET | See » Specifying a Cursor Type and Selecting Rows in the Microsoft SQLSRV documentation.

### Rückgabewerte

Returns a statement resource on success and `false` if an error occurred.

### Beispiele

Beispiel #1 sqlsrv_query() example

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "INSERT INTO Table_1 (id, data) VALUES (?, ?)";
    $params = array(1, "some data");

    $stmt = sqlsrv_query( $conn, $sql, $params);
    if( $stmt === false ) {
         die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Anmerkungen

For statements that you plan to execute only once, use sqlsrv_query(). If you intend to re-execute a statement with different parameter values, use the combination of sqlsrv_prepare() and sqlsrv_execute().

### Siehe auch

- sqlsrv_prepare() - Prepares a query for execution
- sqlsrv_execute() - Executes a statement prepared with sqlsrv_prepare

# sqlsrv_rollback

(No version information available, might only be in Git)

sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction()

### Beschreibung

function sqlsrv_rollback(resource `$conn`): bool

Rolls back a transaction that was begun with sqlsrv_begin_transaction() and returns the connection to auto-commit mode.

### Parameter-Liste

`conn`
  The connection resource returned by a call to sqlsrv_connect().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 sqlsrv_rollback() example

The following example demonstrates how to use sqlsrv_begin_transaction() together with sqlsrv_commit() and sqlsrv_rollback().

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"userName", "PWD"=>"password");
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
        die( print_r( sqlsrv_errors(), true ));
    }

    /* Begin the transaction. */
    if ( sqlsrv_begin_transaction( $conn ) === false ) {
         die( print_r( sqlsrv_errors(), true ));
    }

    /* Initialize parameter values. */
    $orderId = 1; $qty = 10; $productId = 100;

    /* Set up and execute the first query. */
    $sql1 = "INSERT INTO OrdersTable (ID, Quantity, ProductID)
             VALUES (?, ?, ?)";
    $params1 = array( $orderId, $qty, $productId );
    $stmt1 = sqlsrv_query( $conn, $sql1, $params1 );

    /* Set up and execute the second query. */
    $sql2 = "UPDATE InventoryTable
             SET Quantity = (Quantity - ?)
             WHERE ProductID = ?";
    $params2 = array($qty, $productId);
    $stmt2 = sqlsrv_query( $conn, $sql2, $params2 );

    /* If both queries were successful, commit the transaction. */
    /* Otherwise, rollback the transaction. */
    if( $stmt1 && $stmt2 ) {
         sqlsrv_commit( $conn );
         echo "Transaction committed.<br />";
    } else {
         sqlsrv_rollback( $conn );
         echo "Transaction rolled back.<br />";
    }
    ?>

### Siehe auch

- sqlsrv_begin_transaction() - Begins a database transaction
- sqlsrv_commit() - Commits a transaction that was begun with sqlsrv_begin_transaction

# sqlsrv_rows_affected

(No version information available, might only be in Git)

sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

### Beschreibung

function sqlsrv_rows_affected(resource `$stmt`): int|false

Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed. For information about the number of rows returned by a SELECT query, see sqlsrv_num_rows().

### Parameter-Liste

`stmt`
  The executed statement resource for which the number of affected rows is returned.

### Rückgabewerte

Returns the number of rows affected by the last INSERT, UPDATE, or DELETE query. If no rows were affected, 0 is returned. If the number of affected rows cannot be determined, -1 is returned. If an error occurred, `false` is returned.

### Beispiele

Beispiel #1 sqlsrv_rows_affected() example

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ? WHERE id = ?";

    $params = array("updated data", 1);

    $stmt = sqlsrv_query( $conn, $sql, $params);

    $rows_affected = sqlsrv_rows_affected( $stmt);
    if( $rows_affected === false) {
         die( print_r( sqlsrv_errors(), true));
    } elseif( $rows_affected == -1) {
          echo "No information available.<br />";
    } else {
          echo $rows_affected." rows were updated.<br />";
    }
    ?>

### Siehe auch

- sqlsrv_num_rows() - Retrieves the number of rows in a result set

# sqlsrv_send_stream_data

(No version information available, might only be in Git)

sqlsrv_send_stream_data — Sends data from parameter streams to the server

### Beschreibung

function sqlsrv_send_stream_data(resource `$stmt`): bool

Send data from parameter streams to the server. Up to 8 KB of data is sent with each call.

### Parameter-Liste

`stmt`
  A statement resource returned by sqlsrv_query() or sqlsrv_execute().

### Rückgabewerte

Returns `true` if there is more data to send and `false` if there is not.

### Beispiele

Beispiel #1 sqlsrv_send_stream_data() example

    <?php
    $serverName = "serverName\sqlexpress";
    $connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
    $conn = sqlsrv_connect( $serverName, $connectionInfo);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $sql = "UPDATE Table_1 SET data = ( ?) WHERE id = 100";

    // Open parameter data as a stream and put it in the $params array.
    $data = fopen( "data://text/plain,[ Lengthy content here. ]", "r");
    $params = array( &$data);

    // Prepare the statement. Use the $options array to turn off the
    // default behavior, which is to send all stream data at the time of query
    // execution.
    $options = array("SendStreamParamsAtExec"=>0);
    $stmt = sqlsrv_prepare( $conn, $sql, $params, $options);

    sqlsrv_execute( $stmt);

    // Send up to 8K of parameter data to the server
    // with each call to sqlsrv_send_stream_data.
    $i = 1;
    while( sqlsrv_send_stream_data( $stmt)) {
          $i++;
    }
    echo "$i calls were made.";
    ?>

### Siehe auch

- sqlsrv_prepare() - Prepares a query for execution
- sqlsrv_query() - Prepares and executes a query

# sqlsrv_server_info

(No version information available, might only be in Git)

sqlsrv_server_info — Returns information about the server

### Beschreibung

function sqlsrv_server_info(resource `$conn`): array

Returns information about the server.

### Parameter-Liste

`conn`
  The connection resource that connects the client and the server.

### Rückgabewerte

Returns an array as described in the following table:

Returned Array
CurrentDatabase | The connected-to database.
--- | ---
SQLServerVersion | The SQL Server version.
SQLServerName | The name of the server.

### Beispiele

Beispiel #1 sqlsrv_server_info() example

    <?php
    $serverName = "serverName\sqlexpress";
    $conn = sqlsrv_connect( $serverName);
    if( $conn === false ) {
         die( print_r( sqlsrv_errors(), true));
    }

    $server_info = sqlsrv_server_info( $conn);
    if( $server_info )
    {
        foreach( $server_info as $key => $value) {
           echo $key.": ".$value."<br />";
        }
    } else {
          die( print_r( sqlsrv_errors(), true));
    }
    ?>

### Siehe auch

- sqlsrv_client_info() - Returns information about the client and specified connection

## Inhaltsverzeichnis

- sqlsrv_begin_transaction — Begins a database transaction
- sqlsrv_cancel — Cancels a statement
- sqlsrv_client_info — Returns information about the client and specified connection
- sqlsrv_close — Closes an open connection and releases resources associated with the connection
- sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction
- sqlsrv_configure — Changes the driver error handling and logging configurations
- sqlsrv_connect — Opens a connection to a Microsoft SQL Server database
- sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed
- sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare
- sqlsrv_fetch — Makes the next row in a result set available for reading
- sqlsrv_fetch_array — Returns a row as an array
- sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object
- sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
- sqlsrv_free_stmt — Frees all resources for the specified statement
- sqlsrv_get_config — Returns the value of the specified configuration setting
- sqlsrv_get_field — Gets field data from the currently selected row
- sqlsrv_has_rows — Indicates whether the specified statement has rows
- sqlsrv_next_result — Makes the next result of the specified statement active
- sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement
- sqlsrv_num_rows — Retrieves the number of rows in a result set
- sqlsrv_prepare — Prepares a query for execution
- sqlsrv_query — Prepares and executes a query
- sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction
- sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
- sqlsrv_send_stream_data — Sends data from parameter streams to the server
- sqlsrv_server_info — Returns information about the server

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- SQLSRV Funktionen
  - sqlsrv_begin_transaction — Begins a database transaction
  - sqlsrv_cancel — Cancels a statement
  - sqlsrv_client_info — Returns information about the client and specified connection
  - sqlsrv_close — Closes an open connection and releases resources associated with the connection
  - sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction
  - sqlsrv_configure — Changes the driver error handling and logging configurations
  - sqlsrv_connect — Opens a connection to a Microsoft SQL Server database
  - sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed
  - sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare
  - sqlsrv_fetch — Makes the next row in a result set available for reading
  - sqlsrv_fetch_array — Returns a row as an array
  - sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object
  - sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare or sqlsrv_query
  - sqlsrv_free_stmt — Frees all resources for the specified statement
  - sqlsrv_get_config — Returns the value of the specified configuration setting
  - sqlsrv_get_field — Gets field data from the currently selected row
  - sqlsrv_has_rows — Indicates whether the specified statement has rows
  - sqlsrv_next_result — Makes the next result of the specified statement active
  - sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement
  - sqlsrv_num_rows — Retrieves the number of rows in a result set
  - sqlsrv_prepare — Prepares a query for execution
  - sqlsrv_query — Prepares and executes a query
  - sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction
  - sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed
  - sqlsrv_send_stream_data — Sends data from parameter streams to the server
  - sqlsrv_server_info — Returns information about the server

- CUBRID
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - CUBRID Funktionen
  - CUBRID MySQL Compatibility Functions
  - CUBRID Obsolete Aliases and Functions
- dBase
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - dBase Funktionen
- Firebird/InterBase
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Firebird/InterBase Funktionen
- IBM DB2 — IBM DB2, Cloudscape and Apache Derby
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - IBM DB2 Funktionen
- MongoDB — MongoDB Extension
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Tutorials
  - Driver Architecture and Internals — Explains the driver architecture, and special features
  - Security
  - MongoDB\Driver — MongoDB Extension Classes
  - MongoDB\BSON — MongoDB BSON Classes and Functions
  - MongoDB\Driver\Monitoring — Monitoring classes and subscriber functions
  - MongoDB\Driver\Exception — Exception classes
- MySQL — Treiber und Plugins für MySQL
  - Übersicht über die PHP-Treiber für MySQL
  - Mysqli — MySQL Improved Extension
  - Mysql_xdevapi
  - MySQL (Original) — Ursprüngliche MySQL API
  - Mysqlnd — MySQL Native Driver
- OCI8 — Oracle OCI8
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - OCI8 Connection Handling and Connection Pooling
  - OCI8 Fast Application Notification (FAN) Support
  - OCI8 Transparent Application Failover (TAF) Support
  - OCI8 and DTrace Dynamic Tracing
  - Supported Datatypes
  - OCI8 Funktionen
  - OCICollection — The OCICollection class
  - OCILob — The OCILob class
  - OCI8 - Veraltete Aliase und Funktionen
- PostgreSQL
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - PostgreSQL-Funktionen
  - PgSql\Connection — The PgSql\Connection class
  - PgSql\Result — The PgSql\Result class
  - PgSql\Lob — The PgSql\Lob class
- SQLite3
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - SQLite3 — Die Klasse SQLite3
  - SQLite3Exception — The SQLite3Exception class
  - SQLite3Stmt — Die Klasse SQLite3Stmt
  - SQLite3Result — Die Klasse SQLite3Result
- SQLSRV — Microsoft SQL Server Driver for PHP
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - SQLSRV Funktionen

- Abstraktionsebenen
  - DBA — Abstraktionsschicht für dbm-style-Datenbanken
  - ODBC — ODBC (Unified)
  - PDO — PHP Data Objects
- Anbieterspezifische Datenbankerweiterungen
  - CUBRID
  - dBase
  - Firebird/InterBase
  - IBM DB2 — IBM DB2, Cloudscape and Apache Derby
  - MongoDB — MongoDB Extension
  - MySQL — Treiber und Plugins für MySQL
  - OCI8 — Oracle OCI8
  - PostgreSQL
  - SQLite3
  - SQLSRV — Microsoft SQL Server Driver for PHP

# Datums- und zeitrelevante Erweiterungen

# Kalender

# Einführung

Die Kalender-Extension enthält eine Reihe von Funktionen, mit denen die Umwandlung zwischen verschiedenen Kalenderformaten vereinfacht wird. Die Umwandlung basiert dabei auf einer zwischengeschalteten Umrechnung in das Julianische Datum (J.D.). Das Julianische Datum zählt die seit dem ersten Januar 4713 vor Christus vergangenen Tage. Um ein Datum von einem Kalender in einen anderen umzurechnen, müssen Sie es zunächst in das entsprechende Julianische Datum konvertieren und von da aus weiter in den gewünschten Kalender. Beachten Sie, dass das Julianische Datum und der Julianische Kalender zwei komplett unterschiedliche Dinge sind. Nähere Informationen zum Julianischen Datum finden Sie unter » http://www.hermetic.ch/cal_stud/jdn.htm. Weitere Informationen zu verschiedenen Kalendersystemen finden Sie unter » http://www.fourmilab.ch/documents/calendar/. Auszüge aus dieser Seite sind in die folgende Dokumentation eingearbeitet und als Zitat markiert.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation

## Installation

Um diese Funktionen nutzen zu können müssen sie PHP mit --enable-calendar kompilieren.

Die Windowsversion von PHP enthält diese Erweiterung. Um diese Funktionen zu verwenden, müssen Sie keine zusätzlichen Erweiterungen aktivieren.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`CAL_EASTER_DEFAULT` (int)
  Für easter_days(): berechne Ostern für Jahre vor 1753 gemäß dem julianischen Kalender, und für spätere Jahre gemäß dem gregorianischen Kalender.
`CAL_EASTER_ROMAN` (int)
  Für easter_days(): berechne Ostern für Jahre vor 1583 gemäß dem julianischen Kalender, und für spätere Jahre gemäß dem gregorianischen Kalender.
`CAL_EASTER_ALWAYS_GREGORIAN` (int)
  Für easter_days(): berechne Ostern gemäß dem proleptischen gregorianischen Kalender.
`CAL_EASTER_ALWAYS_JULIAN` (int)
  Für easter_days(): berechne Ostern gemäß dem julianischen Kalender.
`CAL_GREGORIAN` (int)
  Für cal_days_in_month(), cal_from_jd(), cal_info() und cal_to_jd(): verwende den proleptischen gregorianischen Kalender.
`CAL_JULIAN` (int)
  Für cal_days_in_month(), cal_from_jd(), cal_info() und cal_to_jd(): verwende den julianischen Kalender.
`CAL_JEWISH` (int)
  Für cal_days_in_month(), cal_from_jd(), cal_info() und cal_to_jd(): verwende den jüdischen Kalender.
`CAL_FRENCH` (int)
  Für cal_days_in_month(), cal_from_jd(), cal_info() und cal_to_jd(): verwende den französischen Revolutionskalender.
`CAL_NUM_CALS` (int)
  Die Anzahl verfügbarer Kalender.
`CAL_JEWISH_ADD_ALAFIM_GERESH` (int)
  Für jdtojewish(): fügt ein geresh Symbol (das einem einfachen Anführungszeichen ähnelt) als Tausender-Trenner zur Jahreszahl hinzu.
`CAL_JEWISH_ADD_ALAFIM` (int)
  Für jdtojewish(): fügt das Wort alafim als Tausender-Trenner zur Jahreszahl hinzu.
`CAL_JEWISH_ADD_GERESHAYIM` (int)
  Für jdtojewish(): fügt ein gershayim Symbol (das einem doppelten Anführungszeichen ähnelt) vor dem letzten Buchstaben des Tages und der Jahreszahl hinzu.
`CAL_DOW_DAYNO` (int)
  Für jddayofweek(): der Wochentag als int, wobei `0` Sonntag bedeutet, und `6` Samstag.
`CAL_DOW_SHORT` (int)
  Für jddayofweek(): der abgekürzte englische Name des Wochentages.
`CAL_DOW_LONG` (int)
  Für jddayofweek(): der englische Name des Wochentages.
`CAL_MONTH_GREGORIAN_SHORT` (int)
  Für jdmonthname(): der abgekürzte gregorianische Monatsname.
`CAL_MONTH_GREGORIAN_LONG` (int)
  Für jdmonthname(): der gregorianische Monatsname.
`CAL_MONTH_JULIAN_SHORT` (int)
  Für jdmonthname(): der abgekürzte julianische Monatsname.
`CAL_MONTH_JULIAN_LONG` (int)
  Für jdmonthname(): der julianische Monatsname.
`CAL_MONTH_JEWISH` (int)
  Für jdmonthname(): der jüdische Monatsname.
`CAL_MONTH_FRENCH` (int)
  Für jdmonthname(): der Monatsname des französische Revolutionskalenders.

# Calendar Funktionen

# cal_days_in_month

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_days_in_month — Gibt die Anzahl der Tage eines bestimmten Monats in einem bestimmten Jahr in einem bestimmten Kalender zurück

### Beschreibung

function cal_days_in_month(int `$calendar`, int `$month`, int `$year`): int

Diese Funktion gibt die Anzahl der Tage in einem `Monat` eines `Jahres` für den angegebenen `Kalender` zurück.

### Parameter-Liste

`calendar`

  Der zu benutzende Kalender

`month`

  Der Monat im gewünschten Kalender

`year`

  Das Jahr im gewünschten Kalender

### Rückgabewerte

Die Länge des Monats im gewünschten Kalender in Tagen

### Beispiele

Beispiel #1 cal_days_in_month() Beispiel

    <?php
    $number = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
    echo "August 2003 hatte {$number} Tage";
    ?>

# cal_from_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_from_jd — Konvertiert von Julian Day Count zu einem unterstützten Kalender

### Beschreibung

function cal_from_jd(int `$julian_day`, int `$calendar`): array

cal_from_jd() Konvertiert den Julian-Tag gegeben in `julian_day` in ein Datum des `calendar`. Unterstützte `calendar` Werte sind `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` und `CAL_FRENCH`.

### Parameter-Liste

`julian_day`

  Julian Tag als Integer(Ganzzahl)

`calendar`

  Zu konvertierender Kalender.

### Rückgabewerte

Gibt ein Array zurück, das Kalenderinformationen enthält, wie z. B. Monat, Tag, Jahr, Wochentag (`dow`), abgekürzter und ausgeschriebener Wochentag und Monat und das Datum in einer String-Form wie "month/day/year". Der Wochentag liegt im Bereich von `0` (Sonntag) bis `6` (Samstag).

### Beispiele

Beispiel #1 cal_from_jd()-Beispiel

    <?php
    $today = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
    print_r(cal_from_jd($today, CAL_GREGORIAN));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [date] => 8/16/2003
        [month] => 8
        [day] => 16
        [year] => 2003
        [dow] => 6
        [abbrevdayname] => Sat
        [dayname] => Saturday
        [abbrevmonth] => Aug
        [monthname] => August
    )

### Siehe auch

- cal_to_jd() - Konvertiert von einem unterstützten Kalenderformat in Julian-Format
- jdtofrench() - Konvertiert ein Julianisches Datum zum Kalender der Französischen Revolution
- jdtogregorian() - Wandelt eine julianische Tageszahl in ein gregorianischen Datum um
- jdtojewish() - Konvertierung vom Julianischen Datum zum Jüdischen Kalender
- jdtojulian() - Wandelt eine julianische Tageszahl in ein julianisches Kalenderdatum um
- jdtounix() - Konvertiert ein julianisches Datum in einen Unix-Timestamp

# cal_info

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_info — Gibt Informationen zu einem bestimmten Kalender zurück

### Beschreibung

function cal_info(int `$calendar` = -1): array

cal_info() liefert Informationen zum angegebenen Kalender `calendar`.

Kalenderinformationen werden als ein Array mit den Elementen `calname`, `calsymbol`, `month`, `abbrevmonth` und `maxdaysinmonth` zurückgegeben. Als Parameter `calendar` können folgende Konstanten benutzt werden:

- 0 oder `CAL_GREGORIAN` - Gregorianischer Kalender
- 1 oder `CAL_JULIAN` - Julianischer Kalender
- 2 oder `CAL_JEWISH` - Jüdischer Kalender
- 3 oder `CAL_FRENCH` - Kalender der französischen Revolution

Wird kein `calendar` spezifiziert so werden Informationen über alle unterstützten Kalender als Array zurückgegeben. Diese Funktionalität existiert seit PHP 5.

### Parameter-Liste

`calendar`

  Der Kalender für den Informationen zurückgegeben werden sollen. Wird kein Kalender angegeben so werden Informationen für alle Kalender zurckgegeben.

### Rückgabewerte

### Beispiele

Beispiel #1 cal_info() Beispiel

    <?php
    $info = cal_info(0);
    print_r($info);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [months] => Array
            (
                [1] => January
                [2] => February
                [3] => March
                [4] => April
                [5] => May
                [6] => June
                [7] => July
                [8] => August
                [9] => September
                [10] => October
                [11] => November
                [12] => December
            )

        [abbrevmonths] => Array
            (
                [1] => Jan
                [2] => Feb
                [3] => Mar
                [4] => Apr
                [5] => May
                [6] => Jun
                [7] => Jul
                [8] => Aug
                [9] => Sep
                [10] => Oct
                [11] => Nov
                [12] => Dec
            )

        [maxdaysinmonth] => 31
        [calname] => Gregorian
        [calsymbol] => CAL_GREGORIAN
    )

# cal_to_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_to_jd — Konvertiert von einem unterstützten Kalenderformat in Julian-Format

### Beschreibung

function cal_to_jd(
int `$calendar`,
int `$month`,
int `$day`,
int `$year`
): int

cal_to_jd() errechnet den Julian-Tag für ein Datum in `calendar`. Unterstützte `calendar` sind `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` und `CAL_FRENCH`.

### Parameter-Liste

`calendar`

  Der zu konvertierende Kalender, einer aus `CAL_GREGORIAN`, `CAL_JULIAN`, `CAL_JEWISH` oder `CAL_FRENCH`.

`month`

  Der Monat als Nummer, die gültige Begrenzung ist abhängig von `calendar`.

`day`

  Der Tag als Nummer, die gültige Begrenzung ist abhängig von `calendar`.

`year`

  Jahr als Nummer, die gültige Begrenzung hängt ab von `calendar`.

### Rückgabewerte

Die Julian Tag-Nummer

### Siehe auch

- cal_from_jd() - Konvertiert von Julian Day Count zu einem unterstützten Kalender
- frenchtojd() - Konvertiert ein Datum des Französischen Revolutionskalenders zu einer julianischen Tageszahl
- gregoriantojd() - Konvertierung vom Gregorianischen Kalender zum Julianischen Datum
- jewishtojd() - Konvertiert vom Jüdischen Kalender zum Julianischen Datum
- juliantojd() - Konvertierung vom Julianischen Kalender zum Julianischen Datum
- unixtojd() - Konvertiert Unix-Timestamp in Julianisches Datum

# easter_date

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_date — Liefert den Unix-Zeitstempel für die lokale Mitternacht am Ostersonntag des angegebenen Jahres

### Beschreibung

function easter_date(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

Diese Funktion gibt den Unix-Timestamp (in Sekunden seit 1970) zurück, der dem Begin des Ostersonntag im durch `year` spezifizierten Jahr entspricht.

Das Datum des Osterfestes wurde im Jahre 325 auf dem Konzil von Nicaea auf den ersten Sonntag nach Frühlingsvollmond, also dem Vollmond während oder direkt nach der Tagundnachtgleiche am 21. März, festgelegt. Der hier genutzte Algorithmus wurde um das Jahr 532 von Dionysius Exiguus eingeführt. Bis zum Jahr 1752 wird nach dem Julianischen Kalender ein einfacher 19jähriger Zyklus für die Bestimmung der Mondphasen benutzt. Im September 1752 übernahmen dann auch Britannien und seine Kolonien den von Clavius und Lilius vorgeschlagenen und im Oktober 1582 von Papst Gregor dem XIII. eingeführten Gregorianischen Kalender. Hierdurch wurden zwei Korrekturfaktoren eingeführt, um den Zyklus genauer abzubilden.

### Parameter-Liste

`year`

  Das Jahr muss auf 32-Bit-Systemen eine Zahl zwischen 1970 und 2037 sein und auf 64-Bit-Systemen eine Zahl zwischen 1970 und 2.000.000.000. Wenn nicht angegeben oder `null`, wird das aktuelle Jahr gemäß der lokalen Zeit verwendet.

`mode`

  Ermöglicht die Berechnung des Osterdatums basierend auf dem Julianischen Kalender, wenn auf `CAL_EASTER_ALWAYS_JULIAN` gesetzt. Siehe auch Kalender-Konstanten.

### Rückgabewerte

Das Osterdatum als Unix-Timestamp.

### Fehler/Exceptions

Wenn auf einem 32-bit System eine Jahreszahl vor 1970 oder nach 2037 oder auf einem 64-Bit-System eine Jahreszahl nach 2.000.000.000 angegeben wird, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Auf 64-Bit-Systemen akzeptiert der Parameter `Jahr` nun Werte innerhalb des Bereichs von 1970 bis 2.000.000.000.
8.0.0 | `year` ist jetzt nullbar.
8.0.0 | Wenn `year` außerhalb des zulässigen Bereichs liegt, wird nun ein ValueError geworfen; zuvor wurde ein Fehler der Stufe `E_WARNING` ausgegeben und die Funktion gab `false` zurück.

### Beispiele

Beispiel #1 easter_date()-Beispiel

    <?php

    echo date("M-d-Y", easter_date(1999));        // Apr-04-1999
    echo date("M-d-Y", easter_date(2000));        // Apr-23-2000
    echo date("M-d-Y", easter_date(2001));        // Apr-15-2001

    ?>

Beispiel #2 Verwendung von easter_date() mit DateTime

    <?php

    $timestamp = easter_date(2023);

    $datetime = new \DateTime();
    $datetime->setTimestamp($timestamp);

    echo $datetime->format('M-d-Y'); // Apr-09-2023

    ?>

### Anmerkungen

> Hinweis:

> easter_date() verlässt sich auf die Zeitfunktionen der C-Bibliothek des Systems, anstatt die internen Datums- und Zeitfunktionen von PHP zu verwenden. Infolgedessen verwendet easter_date() die Umgebungsvariable `TZ`, um die Zeitzone zu bestimmen, in der sie arbeiten soll, anstatt die Standardzeitzone von PHP zu verwenden. Dies kann unerwartetes Verhalten zur Folge haben, wenn diese Funktion in Verbindung mit anderen Datumsfunktionen in PHP verwendet wird.

> Als Workaround kann easter_days() mit DateTime und DateInterval verwendet werden, um den Beginn von Ostern in der von PHP eingestellten Zeitzone wie folgt zu berechnen:

>     <?php
>     function get_easter_datetime($year) {
>         $base = new DateTime("$year-03-21");
>         $days = easter_days($year);

>         return $base->add(new DateInterval("P{$days}D"));
>     }

>     foreach (range(2012, 2015) as $year) {
>         printf("Ostern %d ist am %s\n",
>                $year,
>                get_easter_datetime($year)->format('j.n.'));
>     }
>     ?>

> Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

>     Ostern 2012 ist am 8.4.
>     Ostern 2013 ist am 31.3.
>     Ostern 2014 ist am 20.4.
>     Ostern 2015 ist am 5.4.

### Siehe auch

- easter_days() - Anzahl der Tage zwischen dem 21. März und Ostersonntag zur Berechnung des Osterdatums vor 1970 oder nach 2037

# easter_days

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_days — Anzahl der Tage zwischen dem 21. März und Ostersonntag

### Beschreibung

function easter_days(?int `$year` = `null`, int `$mode` = `CAL_EASTER_DEFAULT`): int

Berechnet die Anzahl der Tage zwischen dem 21. März und Ostersonntag für das Jahr `year`.

Die Funktion kann an Stelle von easter_date() genutzt werden um auch für Jahre außerhalb des Wertebereichs von Unix Timestamps (also vor 1970 bzw. nach 2037) das Osterdatum zu bestimmen.

Das Osterdatum wurde von dem Konzil von Nicea im Jahr 325 auf den ersten Sonntag nach dem ersten Frühlingsvollmond nach der Tag- und Nachtgleiche festgelegt. Es wird dabei angenommen das die Tag- und Nachtgleiche immer auf den 21. März fällt so daß sich die Berechnung auf die Bestimmung des nächsten Vollmonds und des darauf folgenden Sonntags reduziert. Die dazu benutzten Algorithmen wurden um das Jahr 532 von Dionysius Exiguus eingeführt. Innerhalb des Julianischen Kalenders (für Jahre vor 1753) wird der Bestimmung der Mondphasen ein einfacher Zyklus von 19 Jahren zugrunde gelegt. Im Gregorianischen Kalender (für Jahre nach 1753 - erdacht von Clavius und Lilius, zuerst eingeführt von Papst Gregor XIII im Oktober 1582 und im September 1752 auch von Britanien und seinen Kolonien übernommen) wurden zwei zusätzliche Korrekturfaktoren eingeführt um die Genauigkeit der Berechnungen zu erhöhen.

### Parameter-Liste

`year`

  Das Jahr als eine Zahl größer 0. Wenn nicht angegeben oder `null`, wird das aktuelle Jahr gemäß der lokalen Zeit verwendet.

`mode`

  Ermöglicht die Berechnung auf Basis des Gregorianischen Kalenders für den Zeitraum von 1582 bis 1752 wenn `CAL_EASTER_ROMAN` übergeben wird. Eine vollständige Liste der Kalenderkonstanten finden Sie unter Kalendarkonstanten.

### Rückgabewerte

Die Anzahl der Tage die der Ostersonntag im gegebenen Jahr hinter dem 21ten März liegt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `year` ist jetzt nullbar.

### Beispiele

Beispiel #1 easter_days() Beispiel

    <?php

    echo easter_days(1999);        // 14, also April 4
    echo easter_days(1492);        // 32, also April 22
    echo easter_days(1913);        //  2, also March 23

    ?>

### Siehe auch

- easter_date() - Liefert den Unix-Zeitstempel für die lokale Mitternacht am Ostersonntag des angegebenen Jahres

# frenchtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

frenchtojd — Konvertiert ein Datum des Französischen Revolutionskalenders zu einer julianischen Tageszahl

### Beschreibung

function frenchtojd(int `$month`, int `$day`, int `$year`): int

Konvertiert ein Datum des Französischen Revolutionskalenders zu einer julianischen Tageszahl.

Diese Routinen verarbeiten nur Daten der Jahre 1 bis 14 (22. September 1792 bis 22. September 1806 im Gregorianischen Kalender). Dieser Zeitraum geht aber immer noch über die Lebensdauer des Revolutionskalenders hinaus.

### Parameter-Liste

`month`

  Der Monat als Zahl von 1 (für Vendémiaire) bis 13 (für den Zeitraum von 5-6 Tagen am Ende jeden Jahres)

`day`

  Der Tag als Zahl von 1 bis 30

`year`

  Das Jahr als Zahl von 1 bis 14

### Rückgabewerte

Der Julianische Tag für das übergebene Französische Revolutionsdatum als Integer.

### Siehe auch

- jdtofrench() - Konvertiert ein Julianisches Datum zum Kalender der Französischen Revolution
- cal_to_jd() - Konvertiert von einem unterstützten Kalenderformat in Julian-Format

# gregoriantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

gregoriantojd — Konvertierung vom Gregorianischen Kalender zum Julianischen Datum

### Beschreibung

function gregoriantojd(int `$month`, int `$day`, int `$year`): int

Diese Funktion konvertiert das in `month`, `day` und `year` übergebene Datum im Gregorianischen Kalender in einen Tag im Julianischen Datum.

Der gültige Zeitraum für den gregorianischen Kalender ist vom 25. November 4714 v. Chr. bis mindestens zum 31. Dezember 9999 n. Chr. Der Gregorianische Kalender wurde allerdings erst am 15. Oktober 1582 (bzw. am 5. Oktober nach dem bis dahin gültigen Julianischen Kalender) von Papst Gregor XIII. eingeführt, in einigen Ländern erst sehr viel später. So übernahmen die Briten den Gregorianischen Kalender 1752, die UDSSR 1918 und Griechenland erst im Jahre 1923. In den meisten europäischen Ländern wurde vor dem Gregorianischen der Julianische Kalender benutzt.

### Parameter-Liste

`month`

  Der Monat als Zahl zwischen 1 (für Januar) und 12 (für Dezember)

`day`

  Der Tag als Zahl zwischen 1 und 31. Hat der Monat weniger Tage als angegeben, tritt ein Überlauf auf; siehe das Beispiel weiter unten.

`year`

  Das Jahr als Zahl zwischen -4714 und 9999. Negative Zahlen bedeuten v. Chr., positive Zahlen bedeuten n.Chr. Es ist zu beachten, dass es kein Jahr `0` gibt; auf den 31. Dezember 1 v.Chr. folgt direkt der 1. Januar 1 n. Chr.

### Rückgabewerte

Der Julianische Tag für das gegebene Gregorianische Datum als Integer. Für Daten außerhalb des gültigen Bereichs wird `0` zurückgegeben.

### Beispiele

Beispiel #1 Caledar Funktionen

    <?php
    $jd = gregoriantojd(10, 11, 1970);
    echo "$jd\n";
    $gregorian = jdtogregorian($jd);
    echo "$gregorian\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2440871
    10/11/1970

Beispiel #2 Überlaufverhalten

    <?php
    echo gregoriantojd(2, 31, 2018), PHP_EOL,
         gregoriantojd(3,  3, 2018), PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2458181
    2458181

### Siehe auch

- jdtogregorian() - Wandelt eine julianische Tageszahl in ein gregorianischen Datum um
- cal_to_jd() - Konvertiert von einem unterstützten Kalenderformat in Julian-Format

# jddayofweek

(PHP 4, PHP 5, PHP 7, PHP 8)

jddayofweek — Bestimmt den Wochentag aus einem Julianischen Datum

### Beschreibung

function jddayofweek(int `$julian_day`, int `$mode` = `CAL_DOW_DAYNO`): int|string

Diese Funktion bestimmt den Wochentag für den in `julianday` übergebenen Tag im Julianischen Datum. Die Ausgabe erfolgt in Abhängigkeit von `mode` als integer oder string.

### Parameter-Liste

`julian_day`

  Ein Julianischer Tag als Integer

`mode`

  Calendar Wochenmodi
  Modus | Bedeutung
  --- | ---
  0 (Default) | Rückgabe des Wochentages als Zahl (0=Sonntag, 1=Montag, etc.)
  1 | Rückgabe des Wochentages als String (in Englisch) (English-Gregorian)
  2 | Rückgabe des Wochentages als abgekürzter String (in Englisch)

### Rückgabewerte

Der Gregorianische Wochentag als Integer oder String.

# jdmonthname

(PHP 4, PHP 5, PHP 7, PHP 8)

jdmonthname — Liefert den Monatsnamen

### Beschreibung

function jdmonthname(int `$julian_day`, int `$mode`): string

Gibt eine Zeichenkette zurück, die einen Monatsnamen enthält. `mode` teilt dieser Funktion mit, in welchen Kalender die julianische Tageszahl umgewandelt werden soll, und welche Art von Monatsnamen zurückgegeben werden sollen.

Mögliche `mode`-Werte
Modus | Bedeutung | Werte
--- | --- | ---
`CAL_MONTH_GREGORIAN_SHORT` | Gregorianisch (Abk.) | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_GREGORIAN_LONG` | Gregorianisch | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JULIAN_SHORT` | Julianisch - (Abk.) | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
`CAL_MONTH_JULIAN_LONG` | Julianisch | January, February, March, April, May, June, July, August, September, October, November, December
`CAL_MONTH_JEWISH` | Jüdisch | Tishri, Heshvan, Kislev, Tevet, Shevat, Adar, AdarI, AdarII, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
`CAL_MONTH_FRENCH` | Französisch revolutionär | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

### Parameter-Liste

`julian_day`

  Ein Julianischer Tag als Integer.

`mode`

  Der Kalender-Modus (siehe Tabelle weiter oben).

### Rückgabewerte

Der Monatsname für den gegebene julianischen Tag im gewünschten `mode`.

# jdtofrench

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtofrench — Konvertiert ein Julianisches Datum zum Kalender der Französischen Revolution

### Beschreibung

function jdtofrench(int `$julian_day`): string

Konvertiert ein Julianisches Datum zum Kalender der Französischen Revolution

### Parameter-Liste

`julian_day`

  Ein Julianischer Tag als Integer

### Rückgabewerte

Ein Französisches Revolutionsdatum als String in der Form "Monat/Tag/Yahr"

### Siehe auch

- frenchtojd() - Konvertiert ein Datum des Französischen Revolutionskalenders zu einer julianischen Tageszahl
- cal_from_jd() - Konvertiert von Julian Day Count zu einem unterstützten Kalender

# jdtogregorian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtogregorian — Wandelt eine julianische Tageszahl in ein gregorianischen Datum um

### Beschreibung

function jdtogregorian(int `$julian_day`): string

Wandelt eine julianische Tageszahl in eine Zeichenkette um, die das gregorianische Datum im Format "Monat/Tag/Jahr" enthält.

### Parameter-Liste

`julian_day`

  Eine julianischer Tageszahl als Integer.

### Rückgabewerte

Das gregorianische Datum als Zeichenkette der Form "Monat/Tag/Jahr".

### Siehe auch

- gregoriantojd() - Konvertierung vom Gregorianischen Kalender zum Julianischen Datum
- cal_from_jd() - Konvertiert von Julian Day Count zu einem unterstützten Kalender

# jdtojewish

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojewish — Konvertierung vom Julianischen Datum zum Jüdischen Kalender

### Beschreibung

function jdtojewish(int `$julian_day`, bool `$hebrew` = `false`, int `$flags` = 0): string

Diese Funktion konvertiert den in `julianday` angegebenen Tag im Julianischen Datum in den Jüdischen Kalender.

### Parameter-Liste

`julian_day`

  Ein Julianischer Tag als Integer

`hebrew`

  Wird dieser Parameter auf `true` gesetzt, so wird das Jüdische Datum als hebräischer ISO-8859-8 kodierter String gemäß dem im Parameter `flags` festgelegten Format zurückgegeben.

`flags`

  Eine Bitmaske bestehend aus `CAL_JEWISH_ADD_ALAFIM_GERESH`, `CAL_JEWISH_ADD_ALAFIM` und `CAL_JEWISH_ADD_GERESHAYIM`.

### Rückgabewerte

Das jüdische Datum als String in der Form "Monat/Tag/Jahr", oder eine ISO-8859-8 kodierte hebräische Datumszeichenkette gemäß dem `hebrew` Parameter.

### Beispiele

Beispiel #1 jdtojewish()-Beispiel

    <?php
    $jd = gregoriantojd(10, 8, 2002);
    echo jdtojewish($jd, true), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_GERESHAYIM), PHP_EOL,
         jdtojewish($jd, true, CAL_JEWISH_ADD_ALAFIM), PHP_EOL,
         jdtojewish($jd, true,CAL_JEWISH_ADD_ALAFIM_GERESH), PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ב חשון התשסג
    ב' חשון התשס"ג
    ב חשון ה אלפים תשסג
    ב חשון ה'תשסג

### Siehe auch

- jewishtojd() - Konvertiert vom Jüdischen Kalender zum Julianischen Datum
- cal_from_jd() - Konvertiert von Julian Day Count zu einem unterstützten Kalender

# jdtojulian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojulian — Wandelt eine julianische Tageszahl in ein julianisches Kalenderdatum um

### Beschreibung

function jdtojulian(int `$julian_day`): string

Wandelt eine julianische Tageszahl in eine Zeichenkette um, die das julianische Kalenderdatum im Form "Monat/Tag/Year" enthält.

### Parameter-Liste

`julian_day`

  Eine julianische Tageszahl als Integer.

### Rückgabewerte

Ein julianisches Kalenderdatum als Zeichenkette in der Form "Monat/Tag/Jahr".

### Siehe auch

- juliantojd() - Konvertierung vom Julianischen Kalender zum Julianischen Datum
- cal_from_jd() - Konvertiert von Julian Day Count zu einem unterstützten Kalender

# jdtounix

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtounix — Konvertiert ein julianisches Datum in einen Unix-Timestamp

### Beschreibung

function jdtounix(int `$julian_day`): int

Diese Funktion gibt einen Unix-Timestamp (in Sekunden seit dem 1.1.1970) zurück, der dem in `julian_day` übergebenen julianischen Datum entspricht. Die zurückgegebene Zeit ist UTC.

### Parameter-Liste

`julian_day`

  Die Zahl eines julianischen Tages zwischen `2440588` und `106751993607888` auf 64-Bit-Systemen oder zwischen `2440588` und `2465443` auf 32-Bit-Systemen.

### Rückgabewerte

Der Unix-Timestamp für den Anfang (Mitternacht, nicht Mittag) des angegebenen julianischen Tages.

### Fehler/Exceptions

Falls `julian_day` außerhalb des zulässigen Bereichs liegt, wird ein ValueError ausgelöst.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion gibt im Fehlerfall nicht mehr `false` zurück, sondern löst stattdessen einen ValueError aus.
7.3.24, 7.4.12 | Die Obergrenze von `julian_day` wurde erweitert. Bisher lag sie unabhängig von der Architektur bei `2465342`.

### Siehe auch

- unixtojd() - Konvertiert Unix-Timestamp in Julianisches Datum

# jewishtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

jewishtojd — Konvertiert vom Jüdischen Kalender zum Julianischen Datum

### Beschreibung

function jewishtojd(int `$month`, int `$day`, int `$year`): int

Obwohl diese Funktion mit Werten bis zurück zum Jahr 1 (3761 v.Chr.) arbeiten kann, wird eine solche Nutzen nicht empfohlen. Der Jüdische Kalender wurde mehrere tausend Jahre lang benutzt, aber in den frühen Tagen existierte keine Formel, um den Monatsanfang zu bestimmen. Ein neuer Monat begann, wenn der Neumond beobachtet wurde.

### Parameter-Liste

`month`

  Der Monat als Zahl zwischen `1` und `13`, wobei `1` für `Tishri`, `13` für `Elul`, und `6` und `7` für `Adar` in regulären Jahren steht, aber für `Adar I` bzw. `Adar II` in Schaltjahren.

`day`

  Der Tag als Zahl zwischen `1` und `30`. Hat der Monat nur 29 Tage, wird der erste Tag des folgenden Monats angenommen.

`year`

  Das Jahr als Zahl zwischen 1 und 9999

### Rückgabewerte

Der Julianische Tag für das gegebene Jüdische Datum als Integer.

### Siehe auch

- jdtojewish() - Konvertierung vom Julianischen Datum zum Jüdischen Kalender
- cal_to_jd() - Konvertiert von einem unterstützten Kalenderformat in Julian-Format

# juliantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

juliantojd — Konvertierung vom Julianischen Kalender zum Julianischen Datum

### Beschreibung

function juliantojd(int `$month`, int `$day`, int `$year`): int

Diese Funktion konvertiert das in `month`, `day` und `year` übergebene Datum im Gregorianischen Kalender in einen Tag im Julianischen Datum.

Gültige Daten liegen im Bereich von 4714 v.Chr. bis 9999 n.Chr. Der Julianische Kalender wurde allerdings erst 46 v.Chr. eingeführt, und die Details der Anwendung stabilisierten sich frühestens im Jahre 8 n. Chr., z. T. vielleicht sogar erst im vierten Jahrhundert nach Christus. Weiterhin betrachteten nicht alle Kulturen, die sich nach diesem Kalender richteten, den Januar als den ersten Monat des Jahres.

Achtung

Bitte beachten Sie, dass der weltweit genutzte Kalender der Gregorianische und nicht der Julianische Kalender ist. Für diesen Kalender kann die Funktion gregoriantojd() genutzt werden.

### Parameter-Liste

`month`

  Der Monat als Zahl von 1 (für Januar) bis 12 (für Dezember)

`day`

  Der Tag als Zahl von 1 bis 31

`year`

  Das Jahr als Zahl zwischen -4713 und 9999

### Rückgabewerte

Der Julianische Tag für das angegebene Julianische Datum als Integer.

### Siehe auch

- jdtojulian() - Wandelt eine julianische Tageszahl in ein julianisches Kalenderdatum um
- cal_to_jd() - Konvertiert von einem unterstützten Kalenderformat in Julian-Format

# unixtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

unixtojd — Konvertiert Unix-Timestamp in Julianisches Datum

### Beschreibung

function unixtojd(?int `$timestamp` = `null`): int|false

Diese Funktion konvertiert den in `timestamp` übergebenen Wert (in Sekunden seit dem 1.1.1970) in das entsprechende Julianische Datum. Wird kein `timestamp` übergeben, so wird das Julianische Datum des aktuellen Tages zurückgegeben. In beiden Fällen wird die Zeit als lokale Zeit (nicht UTC) angesehen.

### Parameter-Liste

`timestamp`

  Ein zu konvertierender Unix Timestamp.

### Rückgabewerte

Ein Julianischer Tag als Integer, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `timestamp` ist jetzt nullbar.

### Siehe auch

- jdtounix() - Konvertiert ein julianisches Datum in einen Unix-Timestamp

## Inhaltsverzeichnis

- cal_days_in_month — Gibt die Anzahl der Tage eines bestimmten Monats in einem bestimmten Jahr in einem bestimmten Kalender zurück
- cal_from_jd — Konvertiert von Julian Day Count zu einem unterstützten Kalender
- cal_info — Gibt Informationen zu einem bestimmten Kalender zurück
- cal_to_jd — Konvertiert von einem unterstützten Kalenderformat in Julian-Format
- easter_date — Liefert den Unix-Zeitstempel für die lokale Mitternacht am Ostersonntag des angegebenen Jahres
- easter_days — Anzahl der Tage zwischen dem 21. März und Ostersonntag
- frenchtojd — Konvertiert ein Datum des Französischen Revolutionskalenders zu einer julianischen Tageszahl
- gregoriantojd — Konvertierung vom Gregorianischen Kalender zum Julianischen Datum
- jddayofweek — Bestimmt den Wochentag aus einem Julianischen Datum
- jdmonthname — Liefert den Monatsnamen
- jdtofrench — Konvertiert ein Julianisches Datum zum Kalender der Französischen Revolution
- jdtogregorian — Wandelt eine julianische Tageszahl in ein gregorianischen Datum um
- jdtojewish — Konvertierung vom Julianischen Datum zum Jüdischen Kalender
- jdtojulian — Wandelt eine julianische Tageszahl in ein julianisches Kalenderdatum um
- jdtounix — Konvertiert ein julianisches Datum in einen Unix-Timestamp
- jewishtojd — Konvertiert vom Jüdischen Kalender zum Julianischen Datum
- juliantojd — Konvertierung vom Julianischen Kalender zum Julianischen Datum
- unixtojd — Konvertiert Unix-Timestamp in Julianisches Datum

- Installation/Konfiguration
  - Installation
- Vordefinierte Konstanten
- Calendar Funktionen
  - cal_days_in_month — Gibt die Anzahl der Tage eines bestimmten Monats in einem bestimmten Jahr in einem bestimmten Kalender zurück
  - cal_from_jd — Konvertiert von Julian Day Count zu einem unterstützten Kalender
  - cal_info — Gibt Informationen zu einem bestimmten Kalender zurück
  - cal_to_jd — Konvertiert von einem unterstützten Kalenderformat in Julian-Format
  - easter_date — Liefert den Unix-Zeitstempel für die lokale Mitternacht am Ostersonntag des angegebenen Jahres
  - easter_days — Anzahl der Tage zwischen dem 21. März und Ostersonntag
  - frenchtojd — Konvertiert ein Datum des Französischen Revolutionskalenders zu einer julianischen Tageszahl
  - gregoriantojd — Konvertierung vom Gregorianischen Kalender zum Julianischen Datum
  - jddayofweek — Bestimmt den Wochentag aus einem Julianischen Datum
  - jdmonthname — Liefert den Monatsnamen
  - jdtofrench — Konvertiert ein Julianisches Datum zum Kalender der Französischen Revolution
  - jdtogregorian — Wandelt eine julianische Tageszahl in ein gregorianischen Datum um
  - jdtojewish — Konvertierung vom Julianischen Datum zum Jüdischen Kalender
  - jdtojulian — Wandelt eine julianische Tageszahl in ein julianisches Kalenderdatum um
  - jdtounix — Konvertiert ein julianisches Datum in einen Unix-Timestamp
  - jewishtojd — Konvertiert vom Jüdischen Kalender zum Julianischen Datum
  - juliantojd — Konvertierung vom Julianischen Kalender zum Julianischen Datum
  - unixtojd — Konvertiert Unix-Timestamp in Julianisches Datum

# Datum und Uhrzeit

# Einführung

Die Klasse DateTimeImmutable und verwandte Klassen ermöglichen die Darstellung von Datums- und Zeitinformationen. Die Objekte können entweder aus einer Zeichenkette erstellt werden, die die Datums- und Zeitinformationen darstellt, oder aus der aktuellen Systemzeit.

Es steht außerdem ein umfangreicher Satz von Methoden zur Verfügung, um diese Informationen zu ändern und zu formatieren. Dabei können auch Zeitzonen und Sommerzeit-Umstellungen berücksichtigt werden.

Die Datums- und Zeitfunktionen in PHP implementieren den ISO 8601-Kalender, einen » proleptischen gregorianischen Kalender, der die aktuellen Regeln für Schalttage aus der Zeit vor der Einführung des gregorianischen Kalenders anwendet und auch das Jahr `0` als Jahreszahl zwischen `-1 BCE` und `1 CE` enthält. Schaltsekunden werden nicht berücksichtigt.

Die Datums- und Zeitinformationen werden intern in einem 64-Bit-Integer gespeichert, sodass alle denkbaren sinnvollen Daten unterstützt werden (unter anderem negative Jahre). Der darstellbare Bereich reicht von etwa 292 Milliarden Jahren in der Vergangenheit bis zur gleichen Zeit in der Zukunft.

> Hinweis: Die in diesem Abschnitt referenzierten Zeitzonen können in Liste unterstützter Zeitzonen gefunden werden.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Laufzeit-Konfiguration

## Installation

Für diese Funktionen ist keine Installation erforderlich, diese gehören zum Grundbestand von PHP.

> Hinweis: Aktualisieren der Zeitzonen-Datenbank

> Die jeweils aktuellste Version der Zeitzonen-Datenbank kann über das PECL-Paket » timezonedb installiert werden.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Konfigurationsoptionen für Datum und Uhrzeit
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
date.default_latitude | "31.7667" | `INI_ALL` |
date.default_longitude | "35.2333" | `INI_ALL` |
date.sunrise_zenith | "90.833333" | `INI_ALL` | Vor PHP 8.0.0 war der Standardwert "90.583333"
date.sunset_zenith | "90.833333" | `INI_ALL` | Vor PHP 8.0.0 war der Standardwert "90.583333"
date.timezone | "UTC" | `INI_ALL` | Seit PHP 8.2 wird eine Warnung ausgegeben, wenn dies auf einen ungültigen Wert oder eine leere Zeichenkette gesetzt wird.

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`date.default_latitude` float

  Der voreingestellte Breitengrad reicht von `0` am Äquator bis `+90` im Norden und `-90` im Süden.

`date.default_longitude` float

  Der voreingestellte Längengrad reicht von `0` am Nullmeridian bis `+180` im Osten und `−180` im Westen.

`date.sunrise_zenith` float

  Der voreingestellte Winkel, in dem die Sonne bei Sonnenaufgang scheint.

`date.sunset_zenith` float

  Der voreingestellte Winkel, in dem die Sonne bei Sonnenuntergang scheint.

`date.timezone` string

  Die voreingestellte Zeitzone, die von allen Datums- und Zeitfunktionen genutzt wird. Die Rangfolge dafür, welche Zeitzone verwendet wird, wenn keine explizit angegeben ist, wird auf der Seite date_default_timezone_get() beschrieben. Siehe Liste unterstützter Zeitzonen für eine Liste der unterstützten Zeitzonen.

> Hinweis: Die ersten vier Konfigurationsoptionen werden zur Zeit nur von den Funktionen date_sunrise() und date_sunset() genutzt.

# Vordefinierte Konstanten

Die `DATE_*`-Konstanten sind definiert und bieten Standarddarstellungen von Datumsangaben, die zusammen mit den Funktionen für Datumsformatierung (wie date()) verwendet werden können.

Verfügbare Werte für den Parameter `returnFormat` der Funktionen date_sunrise() und date_sunset()
Warnung

Diese Konstanten sind seit PHP 8.4.0 veraltet. Die zugehörigen Funktionen date_sunrise() und date_sunset() sind seit PHP 8.1.0 veraltet.

`SUNFUNCS_RET_TIMESTAMP` (int)
  Zeitstempel
`SUNFUNCS_RET_STRING` (int)
  Stunde:Minute (z. B. `08:02`)
`SUNFUNCS_RET_DOUBLE` (int)
  Stunden als Gleitkommawert (z. B. `8.75`)

`DATE_*` constants
`DATE_ATOM` (string)
  Atom (z. B. `2005-08-15T15:52:01+00:00`); kompatibel mit ISO-8601, RFC 3339 und XML Schema
`DATE_COOKIE` (string)
  HTTP-Cookies (z. B. `Monday, 15-Aug-2005 15:52:01 UTC`)
`DATE_ISO8601` (string)
  ISO-8601-ähnlich (z. B. `2005-08-15T15:52:01+0000`)

  > Hinweis: Dieses Format ist nicht kompatibel zu ISO-8601, wird aber aus Gründen der Abwärtskompatibilität so belassen. Für ISO-8601-Kompatibilität sollte stattdessen `DATE_ISO8601_EXPANDED` oder `DATE_ATOM` verwendet werden (siehe ISO8601:2004 Abschnitt 4.3.3 Punkt d).

`DATE_ISO8601_EXPANDED` (string)
  ISO-8601 Expanded (z. B. `+10191-07-26T08:59:52+01:00`)

  > Hinweis: Dadurch, dass dieses Format immer ein Vorzeichen enthält, können Jahresangaben außerhalb des normalen Bereichs von ISO-8601 (`0000`-`9999`) angegeben werden. Es stellt außerdem sicher, dass der Teil mit der Zeitzone (`+01:00`) mit ISO-8601 kompatibel ist.

`DATE_RFC822` (string)
  RFC 822 (z. B. `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC850` (string)
  RFC 850 (z. B. `Monday, 15-Aug-05 15:52:01 UTC`)
`DATE_RFC1036` (string)
  RFC 1036 (z. B. `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC1123` (string)
  RFC 1123 (z. B. `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC7231` (string)
  RFC 7231 (seit PHP 7.0.19 und 7.1.5) (z. B. `Sat, 30 Apr 2016 17:52:13 GMT`)
`DATE_RFC2822` (string)
  RFC 2822 (z. B. `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC3339` (string)
  Dasselbe wie `DATE_ATOM`.
`DATE_RFC3339_EXTENDED` (string)
  RFC 3339 EXTENDED Format (z. B. `2005-08-15T15:52:01.000+00:00`)
`DATE_RSS` (string)
  RSS (z. B. `Mon, 15 Aug 2005 15:52:01 +0000`). Alias von `DATE_RFC1123`.
`DATE_W3C` (string)
  World Wide Web Consortium (z. B. `2005-08-15T15:52:01+00:00`). Alias von `DATE_RFC3339`.

# Beispiele

## Inhaltsverzeichnis

- Rechnen mit Datum und Uhrzeit

## Rechnen mit Datum und Uhrzeit

Die folgenden Beispiele zeigen einige Fallstricke beim Rechnen mit Datum und Uhrzeit bezüglich der Sommerzeitumstellungen sowie der Monate mit unterschiedlicher Anzahl von Tagen.

Beispiel #1 DateTimeImmutable::add/sub addiert Intervalle, die die verstrichene Zeit umfassen

Wenn PT24H über den Zeitpunkt einer Sommerzeitumstellung hinzugefügt wird, scheinen 23/25 Stunden hinzugefügt zu werden (bei den meisten Zeitzonen).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Beginn: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->add(new DateInterval("PT3H"));
    echo "Ende:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Beginn: 2015-11-01 00:00:00 -04:00
    Ende:   2015-11-01 02:00:00 -05:00

Beispiel #2 DateTimeImmutable::modify und strtotime erhöhen oder verringern die Werte einzelner Komponenten

Wenn +24 Stunden über den Zeitpunkt einer Sommerzeitumstellung hinzugefügt werden, werden genau 24 Stunden hinzugefügt, wie sie in der Datum/Zeit-Zeichenkette zu sehen sind (es sei denn, die Anfangs- oder Endzeit liegt auf einem Übergangspunkt).

    <?php
    $dt = new DateTimeImmutable("2015-11-01 00:00:00", new DateTimeZone("America/New_York"));
    echo "Beginn: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+24 hours");
    echo "Ende:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Beginn: 2015-11-01 00:00:00 -04:00
    Ende:   2015-11-02 00:00:00 -05:00

Beispiel #3 Durch die Addition oder Subtraktion von Zeiten kann das Datum über- oder unterschritten werden

Zum Beispiel ergibt der 31. Januar + 1 Monat den 2. März (Schaltjahr) oder den 3. März (normales Jahr).

    <?php
    echo "Normales Jahr:\n"; // Februar hat 28 Tage
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Beginn: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "Ende:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Schaltjahr:\n"; // Februar hat 29 Tage
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Beginn: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("+1 month");
    echo "Ende:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Normales Jahr:
    Beginn: 2015-01-31 00:00:00 -05:00
    Ende:   2015-03-03 00:00:00 -05:00
    Schaltjahr:
    Beginn: 2016-01-31 00:00:00 -05:00
    Ende:   2016-03-02 00:00:00 -05:00

Um den letzten Tag des nächsten Monats zu erhalten (d. h. um den Überlauf zu verhindern), gibt es das Format `last day of`.

    <?php
    echo "Normales Jahr:\n"; // Februar hat 28 Tage
    $dt = new DateTimeImmutable("2015-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Beginn: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "Ende:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

    echo "Schaltjahr:\n"; // Februar hat 29 Tage
    $dt = new DateTimeImmutable("2016-01-31 00:00:00", new DateTimeZone("America/New_York"));
    echo "Beginn: ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;
    $dt = $dt->modify("last day of next month");
    echo "Ende:   ", $dt->format("Y-m-d H:i:s P"), PHP_EOL;

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Normales Jahr:
    Beginn: 2015-01-31 00:00:00 -05:00
    Ende:   2015-02-28 00:00:00 -05:00
    Schaltjahr:
    Beginn: 2016-01-31 00:00:00 -05:00
    Ende:   2016-02-29 00:00:00 -05:00

# Die Klasse DateTime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Einführung

Stellt Datum und Uhrzeit dar.

Diese Klasse verhält sich wie die Klasse DateTimeImmutable, außer dass die Objekte selbst verändert werden, wenn Modifizierungsmethoden wie DateTime::modify() aufgerufen werden.

Warnung

Der Aufruf von Methoden auf Objekten der Klasse DateTime verändert die in diesen Objekten gekapselten Informationen. Wenn das verhindert werden soll, muss der Operator `clone` verwendet werden, um ein neues Objekt zu erzeugen. Um dieses empfohlene Verhalten standardmäßig zu erhalten, sollte DateTimeImmutable anstelle von DateTime verwendet werden.

## Klassenbeschreibung

class DateTime implements DateTimeInterface {
/* Geerbte Konstanten */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Methoden */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
public function add(DateInterval `$interval`): DateTime
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false
public static function createFromImmutable(DateTimeImmutable `$object`): static
public static function createFromInterface(DateTimeInterface `$object`): DateTime
public static function createFromTimestamp(int|float `$timestamp`): static
public function modify(string `$modifier`): DateTime
public static function __set_state(array `$array`): DateTime
public function setDate(int `$year`, int `$month`, int `$day`): DateTime
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime
public function setMicrosecond(int `$microsecond`): static
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime
public function setTimestamp(int `$timestamp`): DateTime
public function setTimezone(DateTimeZone `$timezone`): DateTime
public function sub(DateInterval `$interval`): DateTime
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Klassenkonstanten sind nun typisiert.
7.2.0 | Die Klassenkonstanten von DateTime sind nun in DateTimeInterface definiert.
7.1.0 | Der Konstruktor von DateTime bezieht nun die aktuellen Mikrosekunden in den erzeugten Wert ein. Vorher wurden die Mikrosekunden immer mit `0` initialisiert.

# DateTime::add

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::add -- date_add — Ändert ein DateTime-Objekt, wobei die Anzahl der Tage, Monate, Jahre, Stunden, Minuten und Sekunden hinzugefügt wird

### Beschreibung

Objektorientierter Stil

public function DateTime::add(DateInterval `$interval`): DateTime

Prozeduraler Stil

function date_add(DateTime `$object`, DateInterval `$interval`): DateTime

Addiert das gegebene DateInterval-Objekt zu dem angegebenen DateTime-Objekt.

Wie DateTimeImmutable::add(), verwendet aber DateTime.

Die prozedurale Version verwendet das DateTime-Objekt als ersten Parameter.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt. Diese Funktion verändert dieses Objekt.

`interval`

  Ein DateInterval-Objekt

### Rückgabewerte

Gibt das geänderte DateTime-Objekt für die Methodenverkettung zurück.

### Siehe auch

- DateTimeImmutable::add() - Liefert ein neues Objekt, bei dem eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden zu einem bestehenden Objekt addiert wurde

# DateTime::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::__construct — Liefert ein neues DateTime-Objekt

### Beschreibung

public function DateTime::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Wie DateTimeImmutable::__construct(), verwendet aber DateTime. Es sollte in Betracht gezogen werden, die Klasse DateTimeImmutable und deren Features zu verwenden.

Gibt ein neues DateTime-Objekt zurück.

### Parameter-Liste

`datetime`

  Ein Datums/Zeit Zeichenkette. Gültige Formate werden unter Datums- und Zeitformate erläutert.

  Wenn der Parameter `$timezone` verwendet wird, kann hier mit der Übergabe von `"now"` die aktuelle Zeit ermittelt werden.

`timezone`

  Ein DateTimeZone-Objekt, welches die Zeitzone von `$datetime` repräsentiert.

  Wenn `$timezone` nicht übergeben wird oder `null` ist, wird die aktuelle Zeitzone verwendet.

  > Hinweis:

  > Der Parameter `$timezone` und die aktuelle Zeitzone werden ignoriert, wenn der Parameter `$datetime` entweder ein UNIX-Zeitstempel ist (z. B. `@946684800`), oder wenn in ihm eine Zeitzone spezifiziert wird (z. B. `2010-01-28T15:00:00+02:00`).

### Rückgabewerte

Gibt eine neue Instanz von DateTime zurück.

### Fehler/Exceptions

Wenn eine ungültige Datum/Uhrzeit-Zeichenkette übergeben wird, wird eine DateMalformedStringException geworfen. Vor PHP 8.3 wird eine Exception geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wirft nun eine DateMalformedStringException anstelle von Exception, wenn eine ungültige Zeichenkette übergeben wird.

### Siehe auch

- DateTimeImmutable::__construct() - Liefert ein neues DateTimeImmutable-Objekt

# DateTime::createFromFormat

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — Wertet eine Zeitangabe gemäß dem angegebenen Format aus

### Beschreibung

Objektorientierter Stil

public static function DateTime::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Prozeduraler Stil

function date_create_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

Gibt ein neues DateTime-Objekt zurück. Es stellt das Datum und die Uhrzeit dar, die in der Zeichenkette `datetime` angegeben sind und gemäß dem angegebenen `format` formatiert wurden.

Wie DateTimeImmutable::createFromFormat() bzw. date_create_immutable_from_format(), erzeugt aber ein DateTime-Objekt.

Diese Methode ist einschließlich Parametern, Beispielen und Überlegungen auf der Seite DateTimeImmutable::createFromFormat dokumentiert.

### Parameter-Liste

Siehe DateTimeImmutable::createFromFormat.

### Rückgabewerte

Gibt eine neue DateTime-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn der Parameter `datetime` NULL-Bytes enthält, wirft diese Methode einen ValueError.

### Changelog

Version | Beschreibung
--- | ---
8.0.21, 8.1.8, 8.2.0 | Wenn in `datetime` NULL-Bytes übergeben werden, wird nun ein ValueError geworfen; vorher wurde dies stillschweigend ignoriert.

### Beispiele

Eine umfangreiche Sammlung von Beispielen ist unter DateTimeImmutable::createFromFormat zu finden.

### Siehe auch

- DateTimeImmutable::createFromFormat() - Wertet eine Zeitangabe gemäß dem angegebenen Format aus

# DateTime::createFromImmutable

(PHP 7 >= 7.3.0, PHP 8)

DateTime::createFromImmutable — Liefert eine neue DateTime-Instanz, die das angegebene DateTimeImmutable-Objekt kapselt

### Beschreibung

public static function DateTime::createFromImmutable(DateTimeImmutable `$object`): static

### Parameter-Liste

`object`

  Das unveränderbare DateTimeImmutable-Objekt, das in eine veränderbare Version umgewandelt werden soll. Dieses Objekt wird nicht verändert, sondern es wird stattdessen eine neue DateTime-Instanz erstellt, das die gleichen Informationen über Datum, Uhrzeit und Zeitzone enthält.

### Rückgabewerte

Gibt eine neue DateTime-Instanz zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Die Methode gibt nun eine Instanz der aktuell aufgerufenen Klasse zurück. Zuvor hat sie eine neue Instanz von DateTime erzeugt.

### Beispiele

Beispiel #1 Erstellen eines veränderbaren DateTime-Objekts

    <?php
    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $mutable = DateTime::createFromImmutable( $date );

# DateTime::createFromInterface

(PHP 8)

DateTime::createFromInterface — Liefert ein neues DateTime-Objekt, das das angegebene DateTimeInterface-Objekt kapselt

### Beschreibung

public static function DateTime::createFromInterface(DateTimeInterface `$object`): DateTime

### Parameter-Liste

`object`

  Das DateTimeInterface-Objekt, das in eine veränderbare Version umgewandelt werden soll. Dieses Objekt wird nicht verändert, sondern es wird stattdessen ein neues DateTime-Objekt erstellt, das die gleichen Informationen über Datum, Uhrzeit und Zeitzone enthält.

### Rückgabewerte

Gibt eine neue DateTime-Instanz zurück.

### Beispiele

Beispiel #1 Erstellen eines veränderbaren DateTime-Objekts

    <?php
    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $mutable = DateTime::createFromInterface($date);

    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $also_mutable = DateTime::createFromInterface($date);

# DateTime::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTime::createFromTimestamp — Creates an instance from a Unix timestamp

### Beschreibung

public static function DateTime::createFromTimestamp(int|float `$timestamp`): static

Creates an instance from a Unix timestamp.

### Parameter-Liste

`timestamp`
  Unix timestamp representing the date. A Float value is also accepted which allows for microsecond precision.

### Rückgabewerte

Returns a new DateTime instance.

### Fehler/Exceptions

If the `timestamp` is outside the range [`PHP_INT_MIN`, `PHP_INT_MAX`], a DateRangeError is thrown.

### Beispiele

Beispiel #1 DateTime::createFromTimestamp() example

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1970-01-01 00:02:03.456789

# DateTime::getLastErrors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getLastErrors — Alias von DateTimeImmutable::getLastErrors()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeImmutable::getLastErrors()

# DateTime::modify

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::modify -- date_modify — Ändert den Zeitstempel

### Beschreibung

Objektorientierter Stil

public function DateTime::modify(string `$modifier`): DateTime

Prozeduraler Stil

function date_modify(DateTime `$object`, string `$modifier`): DateTime|false

Ändert den Zeitstempel eines DateTime-Objektes durch Erhöhen oder Verringern in einem von DateTimeImmutable::__construct() aktzeptierten Format.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt. Diese Funktion verändert dieses Objekt.

`modifier`

  Ein Datums/Zeit Zeichenkette. Gültige Formate werden unter Datums- und Zeitformate erläutert.

### Rückgabewerte

Gibt bei Erfolg eine Instanz von DateTime zurück. Prozeduraler Stil Im Fehlerfall wird `false` zurückgegeben.

### Fehler/Exceptions

Nur bei objektorientierter API: Wenn eine ungültige Datum/Uhrzeit-Zeichenkette übergeben wird, wird eine DateMalformedStringException ausgelöst.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | DateTime::modify() löst nun eine DateMalformedStringException aus, wenn eine ungültige Zeichenkette übergeben wird. Zuvor wurde `false` zurückgegeben, und eine Warnung wurde ausgegeben. Die Funktion date_modify() wurde nicht geändert.

### Beispiele

Beispiel #1 DateTime::modify()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTime('2006-12-12');
    $date->modify('+1 day');
    echo $date->format('Y-m-d');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2006-12-13

Prozeduraler Stil

    <?php
    $date = date_create('2006-12-12');
    date_modify($date, '+1 day');
    echo date_format($date, 'Y-m-d');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2006-12-13

Beispiel #2 Vorsicht beim Addieren oder Subtrahieren von Monaten

    <?php
    $date = new DateTime('2000-12-31');

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

    $date->modify('+1 month');
    echo $date->format('Y-m-d') . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2001-01-31
    2001-03-03

Beispiel #3 Alle Formate von Datum und Zeit werden unterstützt

    <?php
    $date = new DateTime('2020-12-31');

    $date->modify('July 1st, 2023');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('Monday next week');
    echo $date->format('Y-m-d H:i') . "\n";

    $date->modify('17:30');
    echo $date->format('Y-m-d H:i') . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2023-07-01 00:00
    2023-07-03 00:00
    2023-07-03 17:30

### Siehe auch

- strtotime() - Wandelt eine textuelle englische Datums- und Zeitbeschreibung in einen Unix-Zeitstempel um
- DateTimeImmutable::modify() - Erzeugt ein neues Objekt mit geändertem Zeitstempel
- DateTime::add() - Ändert ein DateTime-Objekt, wobei die Anzahl der Tage, Monate, Jahre, Stunden, Minuten und Sekunden hinzugefügt wird
- DateTime::sub() - Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden von einem DateTime-Objekt.
- DateTime::setDate() - Legt das Datum fest
- DateTime::setISODate() - Legt das ISO-Datum fest
- DateTime::setTime() - Legt die Uhrzeit fest
- DateTime::setTimestamp() - Legt Datum und Zeit basierend auf einem Unix-Zeitstempel fest

# DateTime::__set_state

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__set_state — Der __set_state-Handler

### Beschreibung

public static function DateTime::__set_state(array `$array`): DateTime

Der __set_state()-Handler.

Wie DateTimeImmutable::__set_state(), verwendet aber DateTime.

### Parameter-Liste

`array`

  Das Array für die Initialisierung.

### Rückgabewerte

Gibt eine neue Instanz eines DateTime-Objekts zurück.

# DateTime::setDate

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setDate -- date_date_set — Legt das Datum fest

### Beschreibung

Objektorientierter Stil

public function DateTime::setDate(int `$year`, int `$month`, int `$day`): DateTime

Prozeduraler Stil

function date_date_set(
DateTime `$object`,
int `$year`,
int `$month`,
int `$day`
): DateTime

Ändert das aktuelle Datum des DateTime-Objekts auf ein anderes Datum.

Wie DateTimeImmutable::setDate(), verwendet aber DateTime und ändert das bestehende Objekt.

Die prozedurale Version verwendet das DateTime-Objekt als ersten Parameter.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt. Diese Funktion verändert dieses Objekt.

`year`

  Das Jahr des Datums.

`month`

  Der Monat des Datums.

`day`

  Der Tag des Datums.

### Rückgabewerte

Gibt das geänderte DateTime-Objekt für die Methodenverkettung zurück.

### Siehe auch

- DateTimeImmutable::setDate() - Legt das Datum fest

# DateTime::setISODate

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setISODate -- date_isodate_set — Legt das ISO-Datum fest

### Beschreibung

Objektorientierter Stil

public function DateTime::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime

Prozeduraler Stil

function date_isodate_set(
DateTime `$object`,
int `$year`,
int `$week`,
int `$dayOfWeek` = 1
): DateTime

Legt ein Datum nach dem ISO 8601-Standard fest, d. h. mit Wochen- und Tagesoffsets anstelle von bestimmten Datumsangaben.

Wie DateTimeImmutable::setISODate(), verwendet aber DateTime und ändert das bestehende Objekt.

Die prozedurale Version verwendet das DateTime-Objekt als ersten Parameter.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt. Diese Funktion verändert dieses Objekt.

`year`

  Das Jahr des Datums.

`week`

  Die Woche des Datums.

`dayOfWeek`

  Der Abstand zum ersten Tag der Woche.

### Rückgabewerte

Gibt das geänderte DateTime-Objekt für die Methodenverkettung zurück.

### Siehe auch

- DateTimeImmutable::setISODate() - Legt das ISO-Datum fest

# DateTime::setMicrosecond

(PHP 8 >= 8.4.0)

DateTime::setMicrosecond — Sets microsecond part of the time

### Beschreibung

public function DateTime::setMicrosecond(int `$microsecond`): static

Sets microsecond part of the time.

Like DateTimeImmutable::setMicrosecond() but works with DateTime.

### Parameter-Liste

`microsecond`
  The microsecond value to set (`0` to `999999`).

### Rückgabewerte

Gibt das geänderte DateTime-Objekt für die Methodenverkettung zurück.

### Fehler/Exceptions

If the `microsecond` is outside the range [`0`, `999999`], a DateRangeError is thrown.

### Beispiele

Beispiel #1 DateTime::setMicrosecond() example

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Siehe auch

- DateTimeInterface::getMicrosecond() - Gets the microsecond part of the Unix timestamp

# DateTime::setTime

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTime -- date_time_set — Legt die Uhrzeit fest

### Beschreibung

Objektorientierter Stil

public function DateTime::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Prozeduraler Stil

function date_time_set(
DateTime `$object`,
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

Ändert die aktuelle Uhrzeit des DateTime-Objekts auf eine andere Uhrzeit.

Wie DateTimeImmutable::setTime(), verwendet aber DateTime und ändert das bestehende Objekt.

Die prozedurale Version verwendet das DateTime-Objekt als ersten Parameter.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt. Diese Funktion verändert dieses Objekt.

`hour`

  Die Stunde der Uhrzeit.

`minute`

  Die Minute der Uhrzeit.

`second`

  Die Sekunde der Uhrzeit.

`microsecond`

  Die Mikrosekunde der Uhrzeit.

### Rückgabewerte

Gibt das geänderte DateTime-Objekt für die Methodenverkettung zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Das Verhalten bei doppelt vorhandenen Stunden (während der Umstellung von Sommer- auf Normalzeit) wurde geändert. Bisher wählte PHP die zweite Stundenzahl (nach der Zeitumstellung), statt der ersten (vor der Zeitumstellung).
7.1.0 | Der Parameter `microsecond` wurde hinzugefügt.

### Siehe auch

- DateTimeImmutable::setTime() - Legt die Uhrzeit fest

# DateTime::setTimestamp

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::setTimestamp -- date_timestamp_set — Legt Datum und Zeit basierend auf einem Unix-Zeitstempel fest

### Beschreibung

Objektorientierter Stil

public function DateTime::setTimestamp(int `$timestamp`): DateTime

Prozeduraler Stil

function date_timestamp_set(DateTime `$object`, int `$timestamp`): DateTime

Legt Datum und Zeit basierend auf einem Unix-Zeitstempel fest.

Wie DateTimeImmutable::setTimestamp(), verwendet aber DateTime.

Die prozedurale Version verwendet das DateTime-Objekt als ersten Parameter.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt. Diese Funktion verändert dieses Objekt.

`timestamp`

  Ein Unix-Zeitstempel, der das Datum angibt. Es ist möglich, Zeitstempel außerhalb des Bereichs von Integer zu setzen, indem man DateTimeImmutable::modify() mit dem `@`-Format verwendet.

### Rückgabewerte

Gibt das geänderte DateTime-Objekt für die Methodenverkettung zurück.

### Siehe auch

- DateTimeImmutable::setTimestamp() - Legt das Datum und die Uhrzeit basierend auf einem Unix-Zeitstempel fest

# DateTime::setTimezone

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTimezone -- date_timezone_set — Legt die Zeitzone für ein DateTime-Objekt fest

### Beschreibung

Objektorientierter Stil

public function DateTime::setTimezone(DateTimeZone `$timezone`): DateTime

Prozeduraler Stil

function date_timezone_set(DateTime `$object`, DateTimeZone `$timezone`): DateTime

Legt eine neue Zeitzone für ein DateTime-Objekt fest.

Wie DateTimeImmutable::setTimezone(), verwendet aber DateTime.

Die prozedurale Version verwendet das DateTime-Objekt als ersten Parameter.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt. Diese Funktion verändert dieses Objekt.

`timezone`

  Ein DateTimeZone-Objekt, das die gewünschte Zeitzone repräsentiert.

### Rückgabewerte

Gibt das DateTime-Objekt für die Methodenverkettung zurück. Der zugrunde liegende Zeitpunkt wird beim Aufruf dieser Methode nicht verändert.

### Beispiele

Beispiel #1 DateTime::setTimeZone()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTime('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

Prozeduraler Stil

    <?php
    $date = date_create('2000-01-01', timezone_open('Pacific/Nauru'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

    date_timezone_set($date, timezone_open('Pacific/Chatham'));
    echo date_format($date, 'Y-m-d H:i:sP') . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Siehe auch

- DateTimeImmutable::setTimezone() - Legt die Zeitzone fest
- DateTime::getTimezone() - Liefert die Zeitzone relativ zur angegebenen DateTime
- DateTimeZone::__construct() - Erstellt neues DateTimeZone-Objekt

# DateTime::sub

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::sub -- date_sub — Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden von einem DateTime-Objekt.

### Beschreibung

Objektorientierter Stil

public function DateTime::sub(DateInterval `$interval`): DateTime

Prozeduraler Stil

function date_sub(DateTime `$object`, DateInterval `$interval`): DateTime

Ändert das gegebene DateTime-Objekt indem das angegebene DateInterval-Objekt abgezogen wird.

Wie DateTimeImmutable::sub(), verwendet aber DateTime.

Die prozedurale Version verwendet das DateTime-Objekt als ersten Parameter.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt. Diese Funktion verändert dieses Objekt.

`interval`

  Ein DateInterval-Objekt

### Rückgabewerte

Gibt das geänderte DateTime-Objekt für die Methodenverkettung zurück.

### Fehler/Exceptions

Nur bei objektorientierter API: Wenn versucht wird, eine nicht unterstützte Operation durchzuführen, z. B. mit einem DateInterval-Objekt, das relative Zeitangaben wie `next weekday` enthält, wird eine DateInvalidOperationException ausgelöst.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Löst nun eine DateInvalidOperationException aus, statt eine Warnung auszugeben, wenn versucht wird, mit DateTime::sub() eine nicht unterstützte Operation durchzuführen. Die Funktion date_sub() wurde nicht geändert.

### Siehe auch

- DateTimeImmutable::sub() - Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden

## Inhaltsverzeichnis

- DateTime::add — Ändert ein DateTime-Objekt, wobei die Anzahl der Tage, Monate, Jahre, Stunden, Minuten und Sekunden hinzugefügt wird
- DateTime::__construct — Liefert ein neues DateTime-Objekt
- DateTime::createFromFormat — Wertet eine Zeitangabe gemäß dem angegebenen Format aus
- DateTime::createFromImmutable — Liefert eine neue DateTime-Instanz, die das angegebene DateTimeImmutable-Objekt kapselt
- DateTime::createFromInterface — Liefert ein neues DateTime-Objekt, das das angegebene DateTimeInterface-Objekt kapselt
- DateTime::createFromTimestamp — Creates an instance from a Unix timestamp
- DateTime::getLastErrors — Alias von DateTimeImmutable::getLastErrors
- DateTime::modify — Ändert den Zeitstempel
- DateTime::__set_state — Der __set_state-Handler
- DateTime::setDate — Legt das Datum fest
- DateTime::setISODate — Legt das ISO-Datum fest
- DateTime::setMicrosecond — Sets microsecond part of the time
- DateTime::setTime — Legt die Uhrzeit fest
- DateTime::setTimestamp — Legt Datum und Zeit basierend auf einem Unix-Zeitstempel fest
- DateTime::setTimezone — Legt die Zeitzone für ein DateTime-Objekt fest
- DateTime::sub — Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden von einem DateTime-Objekt.

# Die Klasse DateTimeImmutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

Stellt Datum und Uhrzeit dar.

Diese Klasse verhält sich wie die Klasse DateTime mit der Ausnahme, dass neue Objekte zurückgegeben werden, wenn Modifizierungsmethoden wie DateTime::modify() aufgerufen werden.

## Klassenbeschreibung

class DateTimeImmutable implements DateTimeInterface {
/* Geerbte Konstanten */
public const string DateTimeInterface::ATOM = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::COOKIE = "l, d-M-Y H:i:s T";
public const string DateTimeInterface::ISO8601 = "Y-m-d\\TH:i:sO";
public const string DateTimeInterface::ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC822 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC850 = "l, d-M-y H:i:s T";
public const string DateTimeInterface::RFC1036 = "D, d M y H:i:s O";
public const string DateTimeInterface::RFC1123 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string DateTimeInterface::RFC2822 = "D, d M Y H:i:s O";
public const string DateTimeInterface::RFC3339 = "Y-m-d\\TH:i:sP";
public const string DateTimeInterface::RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string DateTimeInterface::RSS = "D, d M Y H:i:s O";
public const string DateTimeInterface::W3C = "Y-m-d\\TH:i:sP";
/* Methoden */
public function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
#[\NoDiscard]
public function add(DateInterval `$interval`): DateTimeImmutable
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = null): DateTimeImmutable|false
public static function createFromInterface(DateTimeInterface `$object`): DateTimeImmutable
public static function createFromMutable(DateTime `$object`): static
public static function createFromTimestamp(int|float `$timestamp`): static
public static function getLastErrors(): array|false
#[\NoDiscard]
public function modify(string `$modifier`): DateTimeImmutable
public static function __set_state(array `$array`): DateTimeImmutable
#[\NoDiscard]
public function setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable
#[\NoDiscard]
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function setMicrosecond(int `$microsecond`): static
#[\NoDiscard]
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable
#[\NoDiscard]
public function setTimestamp(int `$timestamp`): DateTimeImmutable
#[\NoDiscard]
public function setTimezone(DateTimeZone `$timezone`): DateTimeImmutable
#[\NoDiscard]
public function sub(DateInterval `$interval`): DateTimeImmutable
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = false): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Klassenkonstanten sind nun typisiert.
7.1.0 | Der Konstruktor von DateTimeImmutable bezieht nun die aktuellen Mikrosekunden in den erzeugten Wert ein. Vorher wurden die Mikrosekunden immer mit `0` initialisiert.

# DateTimeImmutable::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::add — Liefert ein neues Objekt, bei dem eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden zu einem bestehenden Objekt addiert wurde

### Beschreibung

#[\NoDiscard]
public function DateTimeImmutable::add(DateInterval `$interval`): DateTimeImmutable

Erzeugt ein neues DateTimeImmutable-Objekt und addiert das angegebene DateInterval-Objekt zu diesem, das dann den neuen Wert darstellt.

### Parameter-Liste

`interval`

  Ein DateInterval-Objekt

### Rückgabewerte

Gibt ein neues DateTimeImmutable-Objekt mit den geänderten Daten zurück.

### Beispiele

Beispiel #1 DateTimeImmutable::add()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

Beispiel #2 Weitere DateTimeImmutable::add()-Beispiele

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-01');
    $newDate = $date->add(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2000-01-01 10:00:30
    2007-06-05 04:03:02

Beispiel #3 Vorsicht beim Addieren von Monaten

    <?php
    $date = new DateTimeImmutable('2000-12-31');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->add($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->add($interval);
    echo $newDate2->format('Y-m-d') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2001-01-31
    2001-03-03

### Siehe auch

- DateTimeImmutable::sub() - Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden
- DateTimeImmutable::diff() - Liefert die Differenz zwischen zwei DateTime-Objekten
- DateTimeImmutable::modify() - Erzeugt ein neues Objekt mit geändertem Zeitstempel

# DateTimeImmutable::__construct

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__construct -- date_create_immutable — Liefert ein neues DateTimeImmutable-Objekt

### Beschreibung

Objektorientierter Stil

public function DateTimeImmutable::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

Prozeduraler Stil

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Gibt ein neues DateTimeImmutable-Objekt zurück.

### Parameter-Liste

`datetime`

  Ein Datums/Zeit Zeichenkette. Gültige Formate werden unter Datums- und Zeitformate erläutert.

  Wenn der Parameter `$timezone` verwendet wird, kann hier mit der Übergabe von `"now"` die aktuelle Zeit ermittelt werden.

`timezone`

  Ein DateTimeZone-Objekt, das die Zeitzone von `$datetime` darstellt.

  Wenn `$timezone` nicht übergeben wird oder `null` ist, wird die aktuelle Zeitzone verwendet.

  > Hinweis:

  > Der Parameter `$timezone` und die aktuelle Zeitzone werden ignoriert, wenn der Parameter `$datetime` entweder ein UNIX-Zeitstempel ist (z. B. `@946684800`) oder eine Zeitzone vorgibt (z. B. `2010-01-28T15:00:00+02:00` oder `2010-07-05T06:00:00Z`).

### Rückgabewerte

Gibt eine neue DateTimeImmutable-Instanz zurück.

### Fehler/Exceptions

Wenn eine ungültige Datum/Uhrzeit-Zeichenkette übergeben wird, wird eine DateMalformedStringException geworfen. Vor PHP 8.3 wird eine Exception geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wirft nun eine DateMalformedStringException anstelle von Exception, wenn eine ungültige Zeichenkette übergeben wird.
7.1.0 | Von nun an werden die Mikrosekunden mit dem aktuellen Wert belegt, nicht mit '00000'.

### Beispiele

Beispiel #1 DateTimeImmutable::__construct()-Beispiel

Objektorientierter Stil

    <?php
    try {
        $date = new DateTimeImmutable('2000-01-01');
    } catch (Exception $e) {
        echo $e->getMessage();
        exit(1);
    }

    echo $date->format('Y-m-d');
    ?>

Prozeduraler Stil

    <?php
    $date = date_create('2000-01-01');
    if (!$date) {
        $e = date_get_last_errors();
        foreach ($e['errors'] as $error) {
            echo "$error\n";
        }
        exit(1);
    }

    echo date_format($date, 'Y-m-d');
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    2000-01-01

Beispiel #2 Die Besonderheiten von DateTimeImmutable::__construct()

    <?php
    // Datums- und Zeitangaben in der Zeitzone des Computers.
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Datums- und Zeitangaben in der angegebenen Zeitzone.
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Aktuelles Datum und aktuelle Uhrzeit in der Zeitzone des Computers.
    $date = new DateTimeImmutable();
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Aktuelles Datum und aktuelle Uhrzeit in der angegebenen Zeitzone.
    $date = new DateTimeImmutable('now', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Verwendung eines UNIX-Zeitstempels. Zu beachten ist,
    // dass das Ergebnis in der Zeitzone UTC liegt.
    $date = new DateTimeImmutable('@946684800');
    echo $date->format('Y-m-d H:i:sP') . "\n";

    // Nicht vorhandene Werte werden fortgeschrieben.
    $date = new DateTimeImmutable('2000-02-30');
    echo $date->format('Y-m-d H:i:sP') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2000-01-01 00:00:00-05:00
    2000-01-01 00:00:00+12:00
    2010-04-24 10:24:16-04:00
    2010-04-25 02:24:16+12:00
    2000-01-01 00:00:00+00:00
    2000-03-01 00:00:00-05:00

Beispiel #3 Ändern der zugehörigen Zeitzone

    <?php
    $timeZone = new \DateTimeZone('Asia/Tokyo');

    $time = new \DateTimeImmutable();
    $time = $time->setTimezone($timeZone);

    echo $time->format('Y/m/d H:i:s'), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2022/08/12 23:49:23

Beispiel #4 Verwenden einer Zeichenkette mit relativen Datums- und Zeitangaben

    <?php
    $time = new \DateTimeImmutable("-1 year");

    echo $time->format('Y/m/d H:i:s'), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2021/08/12 15:43:51

# DateTimeImmutable::createFromFormat

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::createFromFormat -- date_create_immutable_from_format — Wertet eine Zeitangabe gemäß dem angegebenen Format aus

### Beschreibung

Objektorientierter Stil

public static function DateTimeImmutable::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Prozeduraler Stil

function date_create_immutable_from_format(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Gibt ein neues DateTimeImmutable-Objekt zurück. Es stellt das Datum und die Uhrzeit dar, die in der Zeichenkette `datetime` angegeben sind und gemäß dem angegebenen `format` formatiert wurden.

### Parameter-Liste

`format`

  Das Format, in dem der übergebene String sein soll. Siehe die nachfolgenden Formatierungsoptionen. In den meisten Fällen können die gleichen Buchstaben verwendet werden wie für die Funktion date().

  Alle Felder werden mit den aktuellen Werten für Datum und Uhrzeit initialisiert. In den meisten Fällen wird man diese auf "Null" zurücksetzen wollen (die Unix-Epoche, `1970-01-01 00:00:00 UTC`). Dies wird erreicht, indem das Zeichen `!` als erstes Zeichen in den Parameter `format` eingefügt wird, oder `|` als letztes Zeichen. Weitere Informationen zu den einzelnen Zeichen sind in der folgenden Beschreibung zu finden.

  Das Format wird von links nach rechts ausgewertet, was bedeutet, dass die Reihenfolge, in der die Formatzeichen angeordnet sind, in manchen Situationen das Ergebnis beeinflusst. Im Fall von `z` (der Tag des Jahres) ist es erforderlich, dass bereits ein Jahr ausgewertet wurde, zum Beispiel durch die Zeichen `Y` oder `y`.

  Buchstaben, die für die Auswertung von Zahlen verwendet werden, lassen eine große Bandbreite von Werten zu, die außerhalb des logischen Bereichs liegen. Zum Beispiel akzeptiert das `d` (Tag des Monats) Werte im Bereich von `00` bis `99`. Die einzige Einschränkung betrifft die Anzahl der Ziffern. Wenn ein Wert außerhalb des Bereichs angegeben wird, wird der Überlaufmechanismus des Parsers für Datum und Uhrzeit verwendet. Im Folgenden sind einige Beispiele für dieses Überlaufverhalten aufgeführt.

  Das bedeutet auch, dass die Daten, die für einen Formatbuchstaben ausgewertet werden, gierig sind und so viele Ziffern lesen, wie ihr Format zulässt. Das kann dann auch bedeuten, dass in der Zeichenkette `datetime` nicht mehr genügend Zeichen für nachfolgende Formatzeichen vorhanden sind. Ein Beispiel auf dieser Seite veranschaulicht auch dieses Problem.

  Die folgenden Zeichen werden in der Parameterzeichenkette `format` erkannt
  `format`-Zeichen | Beschreibung | Beispiele zulässiger Werte
  --- | --- | ---
  Tag | --- | ---
  `d` und `j` | Tag des Monats; zwei Ziffern mit oder ohne vorangestellter Null | `01` bis `31` oder `1` bis `31` (2-stellige Zahlen, die höher sind als die Anzahl der Tage im Monat, werden akzeptiert, führen aber zu einem Überlauf des Monats. Zum Beispiel bedeutet die 33 bei Januar den 2. Februar)
  `D` und `l` | Textuelle Darstellung eines Tages | `Mon` bis `Sun` oder `Sonntag` bis `Samstag`. Wenn der angegebene Tagesname vom ausgewerteten (oder voreingestellten) Datum abweicht, kommt es zu einem Überlauf bis zum nächsten Datum mit dem angegebenen Tagesnamen. Siehe die Beispiele unten für eine Erklärung.
  `S` | Englisches Ordnungssuffix für einen Tag des Monats; zwei Buchstaben. Es wird bei der Auswertung ignoriert. | `st`, `nd`, `rd` oder `th`.
  `z` | Tag des Jahres (beginnend bei 0); es muss ein `Y` oder `y` vorangestellt werden. | `0` bis `365` (es können auch dreistellige Zahlen angegeben werden, die größer sind als die Anzahl der Tage in einem Jahr; in diesem Fall wird die Differenz auf das nächste Jahr übertragen. Zum Beispiel bedeutet 366 in Verbindung mit 2022 den 2. Januar 2023)
  Monat | --- | ---
  `F` und `M` | Textuelle Darstellung eines Monats, z. B. January oder Sept | `January` bis `December` oder `Jan` bis `Dec`
  `m` und `n` | Numerische Darstellung eines Monats; mit oder ohne vorangestellter Null | `01` bis `12` oder `1` bis `12` (es können auch zweistellige Zahlen größer als 12 angegeben werden; in diesem Fall wird die Differenz auf das nächste Jahr übertragen. Zum Beispiel bedeutet 13 den Januar des nächsten Jahres)
  Jahr | --- | ---
  `X` und `x` | Vollständige numerische Darstellung einer Jahreszahl; bis zu 19 Ziffern, optional mit vorangestelltem `+` oder `-` | Beispiele: `0055`, `787`, `1999`, `-2003`, `+10191`
  `Y` | Vollständige numerische Darstellung einer Jahreszahl; bis zu vier Ziffern | Beispiele: `0055`, `787`, `1999`, `2003`
  `y` | Eine zweistellige Jahreszahl (für den Bereich 1970-2069). | Beispiele: `99` oder `03` (werden interpretiert als `1999` bzw. `2003`)
  Zeit | --- | ---
  `a` und `A` | Ante meridiem (vor Mittag) und post meridiem (nach Mittag) | `am` oder `pm`
  `g` und `h` | Stunde im 12-Stunden-Format; mit oder ohne vorangestellter Null | `1` bis `12` oder `01` bis `12` (es können auch zweistellige Zahlen größer als 12 angegeben werden; in diesem Fall wird die Differenz auf den nächsten Tag übertragen. `14` bedeutet zum Beispiel `02` im nächsten AM/PM-Zeitraum)
  `G` und `H` | Stunde im 24-Stunden-Format; mit oder ohne vorangestellter Null | `0` bis `23` oder `00` bis `23` (es können auch zweistellige Zahlen größer als 24 angegeben werden; in diesem Fall wird die Differenz auf den nächsten Tag übertragen. `26` bedeutet zum Beispiel `02:00` am nächsten Tag)
  `i` | Minuten; mit vorangestellter Null | `00` to `59` (es können auch zweistellige Zahlen größer als 59 angegeben werden; in diesem Fall wird die Differenz auf die nächste Stunde übertragen. `66` bedeutet zum Beispiel `:06` in der nächsten Stunde)
  `s` | Sekunden; mit vorangestellter Null | `00` bis `59` (es können auch zweistellige Zahlen größer als 59 angegeben werden; in diesem Fall wird die Differenz auf den nächsten Tag übertragen. `90` bedeutet zum Beispiel `:30` in der nächsten Minute)
  `v` | Bruchteil in Millisekunden (bis zu drei Ziffern) | Beispiel: `12` (`0.12` Sekunden), `345` (`0.345` Sekunden)
  `u` | Bruchteil in Mikrosekunden (bis zu sechs Ziffern) | Beispiel: `45` (`0.45` Sekunden), `654321` (`0.654321` Sekunden)
  Zeitzone | --- | ---
  `e`, `O`, `p`, `P` und `T` | Bezeichner der Zeitzone, Differenz zu UTC (in Stunden), Differenz zu UTC (mit Doppelpunkt zwischen Stunden und Minuten) oder Zeitzonenkürzel | Beispiele: `UTC`, `GMT`, `Atlantic/Azores`, `+0200`, `+02:00`, `EST`, `MDT`
  Datum und Uhrzeit in voller Länge | --- | ---
  `U` | Sekunden seit der Unix-Epoche (1. Januar 1970 00:00:00 GMT) | Beispiel: `1292177455`
  Whitespace und Trennzeichen | --- | ---
  `` (Leerraum) | Leerzeichen, Tabulatoren, oder NBSP (U+A0)- oder NNBSP (U+202F)-Zeichen | Beispiele: `"\t"`, `" "`
  `#` | Eins der folgenden Trennzeichen: `;`, `:`, `/`, `.`, `,`, `-`, `(` oder `)` | Beispiel: `/`
  `;`, `:`, `/`, `.`, `,`, `-`, `(` oder `)` | Das angegebene Zeichen | Beispiel: `-`
  `?` | Ein beliebiges Byte | Beispiel: `^` (es ist zu beachten, dass für UTF-8-Zeichen möglicherweise mehr als ein `?` benötigt wird. In diesem Fall ist es wahrscheinlich besser, `*` zu verwenden)
  `*` | Beliebige Bytes bis zum nächsten Trennzeichen oder zur nächsten Ziffer | Beispiel: `*` in `Y-*-d` entspricht in Verbindung mit der Zeichenkette `2009-aWort-08` dem Wert `aWort`
  `!` | Setzt alle Felder (Jahr, Monat, Tag, Stunde, Minute, Sekunde, Bruchteil und Zeitzone) auf ihre Ausgangswerte zurück (`0` bei Stunde, Minute, Sekunde und Bruchteil; `1` bei Monat und Tag; `1970` bei Jahr und `UTC` bei der Zeitzone) | Ohne `!` werden alle Felder auf das aktuelle Datum und die aktuelle Uhrzeit gesetzt.
  `|` | Setzt die Werte der noch nicht ausgewerteten Felder (Jahr, Monat, Tag, Stunde, Minute, Sekunde, Zeitzone) auf ihre Ausgangswerte zurück | `Y-m-d|` setzt Jahr, Monat und Tag entsprechend der Informationen aus der ausgewerteten Zeichenkette und setzt Stunde, Minute und Sekunde auf 0
  `+` | Wenn dieses Formatzeichen verwendet wird, führen nachfolgende Daten in der Zeichenkette nicht zu einem Fehler, sondern zu einer Warnung | Um zu überprüfen, ob nachfolgende Daten vorhanden waren, kann DateTimeImmutable::getLastErrors() verwendet werden.

  Wenn die Formatzeichenkette Zeichen enthält, die nicht erkannt werden, schlägt die Auswertung fehl und es wird eine Fehlermeldung an die zurückgegebene Struktur angehängt. Die Fehlermeldungen können mit DateTimeImmutable::getLastErrors() abgefragt werden.

  Wenn literale Zeichen in `format` verwendet werden, müssen diese mit einem Backslash (`\`) maskiert werden.

  Wenn `format` nicht das Zeichen `!` enthält, werden die Teile des Datums und der Uhrzeit, die nicht in `format` angegeben sind, auf die aktuelle Systemzeit gesetzt.

  Wenn `format` das Zeichen `!` enthält, werden die Teile des Datums und der Uhrzeit, die nicht in `format` angegeben sind, sowie die Werte links von `!` auf die entsprechenden Werte der Unix-Epoche gesetzt.

  Wenn ein Zeichen der Uhrzeit ausgewertet wird, werden alle anderen zeitbezogenen Felder auf "0" gesetzt, sofern sie nicht ebenfalls ausgewertet werden.

  Die Unix-Epoche ist 1970-01-01 00:00:00 UTC.

`datetime`

  Eine Zeichenkette, die die Zeit angibt.

`timezone`

  Ein DateTimeZone-Objekt, das die gewünschte Zeitzone darstellt.

  Wenn `timezone` nicht angegeben wird oder `null` ist und `datetime` keine Zeitzone enthält, wird die aktuelle Zeitzone verwendet.

  > Hinweis:

  > Wenn der Parameter `datetime` entweder einen UNIX-Zeitstempel enthält (z. B. `946684800`) oder eine Zeitzone vorgibt (z. B. `2010-01-28T15:00:00+02:00`), werden der Parameter `timezone` und die aktuelle Zeitzone ignoriert.

### Rückgabewerte

Gibt eine neue DateTimeImmutable-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn der Parameter `datetime` NULL-Bytes enthält, wirft diese Methode einen ValueError.

### Changelog

Version | Beschreibung
--- | ---
8.2.9 | Das `` - (Leerraum) Zeichen unterstützt nun auch die Zeichen NBSP (U+A0) und NNBSP (U+202F).
8.2.0 | Die `format`-Zeichen `X` und `x` wurden hinzugefügt.
8.0.21, 8.1.8, 8.2.0 | Wenn in `datetime` NULL-Bytes übergeben werden, wird nun ein ValueError geworfen; vorher wurde dies stillschweigend ignoriert.
7.3.0 | Das `format`-Zeichen `v` wurde hinzugefügt.

### Beispiele

Beispiel #1 DateTimeImmutable::createFromFormat()-Beispiel

Objektorientierter Stil

    <?php
    $date = DateTimeImmutable::createFromFormat('j-M-Y', '15-Feb-2009');
    echo $date->format('Y-m-d');
    ?>

Beispiel #2 Verwendung von DateTimeImmutable::createFromFormat() mit vordefinierten Formatkonstanten

Objektorientierter Stil

    <?php
    $date = DateTimeImmutable::createFromFormat(DateTimeInterface::ISO8601, '2004-02-12T15:19:21+00:00');
    $date = DateTimeImmutable::createFromFormat(DateTimeInterface::RFC3339_EXTENDED, '2013-10-14T09:00:00.000+02:00');
    ?>

Die in diesem Beispiel verwendeten Formatierungskonstanten bestehen aus einer Reihe von Zeichen für die Formatierung eines DateTimeImmutable-Objekts. In den meisten Fällen stimmen diese Buchstaben mit den entsprechenden Elementen der Datums-/Zeitinformationen überein, wie sie im obigen Abschnitt parameters definiert sind, aber sie sind in der Regel etwas weniger strikt.

Beispiel #3 Besonderheiten von DateTimeImmutable::createFromFormat()

    <?php
    echo 'Aktuelle Zeit: ' . date('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-!d H:i:s';
    $date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = '!d';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'i';
    $date = DateTimeImmutable::createFromFormat($format, '15');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Aktuelle Zeit: 2022-06-02 15:50:46
    Format: Y-m-d; 2009-02-15 15:50:46
    Format: Y-m-d H:i:s; 2009-02-15 15:16:17
    Format: Y-m-!d H:i:s; 1970-01-15 15:16:17
    Format: !d; 1970-01-15 00:00:00
    Format: i; 2022-06-02 00:15:00

Beispiel #4 Formatzeichenkette mit literalen Zeichen

    <?php
    echo DateTimeImmutable::createFromFormat('H\h i\m s\s','23h 15m 03s')->format('H:i:s');
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    23:15:03

Beispiel #5 Verhalten bei einem Überlauf

    <?php
    echo DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97')->format(DateTimeImmutable::RFC2822);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Sat, 04 Jun 2022 17:01:37 +0000

Das Ergebnis sieht zwar merkwürdig aus, ist aber korrekt, da die folgenden Überläufe erfolgen:

1. `97` Sekunden überschreiten `1` Minute, sodass `37` Sekunden übrig bleiben.
2. `61` Minuten überschreiten `1` Stunde, sodass `1` Minute übrig bleibt.
3. `35` Tage überschreiten `1` Monat, sodass `4` Tage übrig bleiben. Da nicht jeder Monat die gleiche Anzahl von Tagen hat, hängt die Anzahl der Tage, die übrig bleiben, vom Monat ab.
4. `18` Monate überschreiten `1` Jahr, sodass `6` Monate übrig bleiben.

Beispiel #6 Verhalten bei überlaufenden Tagesnamen

    <?php
    $d = DateTime::createFromFormat(DateTimeInterface::RFC1123, 'Mon, 3 Aug 2020 25:00:00 +0000');
    echo $d->format(DateTime::RFC1123), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Mon, 10 Aug 2020 01:00:00 +0000

Das Ergebnis sieht zwar merkwürdig aus, ist aber korrekt, da die folgenden Überläufe erfolgen:

1. `3 Aug 2020 25:00:00` geht über in `(Tue) 4 Aug 2020 01:00`.
2. `Mon` wird eingesetzt, was das Datum auf `Mon, 10 Aug 2020 01:00:00` vorverlegt. Relative Schlüsselwörter wie `Mon` werden im Abschnitt über relative Formate erläutert.

Um Überläufe in Daten zu erkennen, kann die Methode DateTimeImmutable::getLastErrors() verwendet werden, die eine Warnung enthält, wenn ein Überlauf aufgetreten ist.

Beispiel #7 Erkennen von übergelaufenen Daten

    <?php
    $d = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2021-17-35 16:60:97');
    echo $d->format(DateTimeImmutable::RFC2822), "\n\n";

    var_dump(DateTimeImmutable::GetLastErrors());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Sat, 04 Jun 2022 17:01:37 +0000

    array(4) {
      'warning_count' =>
      int(2)
      'warnings' =>
      array(1) {
        [19] =>
        string(27) "The parsed date was invalid"
      }
      'error_count' =>
      int(0)
      'errors' =>
      array(0) {
      }
    }

Beispiel #8 Gieriges Verhalten beim Auswerten

    <?php
    print_r(date_parse_from_format('Gis', '60101'));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [year] =>
        [month] =>
        [day] =>
        [hour] => 60
        [minute] => 10
        [second] => 0
        [fraction] => 0
        [warning_count] => 1
        [warnings] => Array
            (
                [5] => The parsed time was invalid
            )

        [error_count] => 1
        [errors] => Array
            (
                [4] => A two digit second could not be found
            )

        [is_localtime] =>
    )

Das Format `G` dient der Auswertung von Uhrzeiten im 24-Stunden-Format, mit oder ohne vorangestellter Null. Dies erfordert die Analyse von 1 oder 2 Ziffern. Da zwei Ziffern folgen, wird dies gierig als `60` gelesen.

Die folgenden Formatzeichen `i` und `s` benötigen beide zwei Ziffern. Das bedeutet, dass `10` als Minute (`i`) übergeben wird, und dass dann nicht mehr genug Ziffern übrig sind, um sie als Sekunde (`s`) zu verarbeiten.

Das Array `errors` zeigt dieses Problem an.

Außerdem liegt der Wert `60` für die Stunde außerhalb des Bereichs `0`-`24`, was dazu führt, dass das Array `warnings` eine Warnung enthält, dass die Zeit ungültig ist.

### Siehe auch

- DateTimeImmutable::__construct() - Liefert ein neues DateTimeImmutable-Objekt
- DateTimeImmutable::getLastErrors() - Liefert die Warnungen und Fehler
- checkdate() - Prüft ein Gregorianisches Datum auf Gültigkeit
- strptime() - Wertet eine Zeit-/Datumsangabe aus, die mit strftime erzeugt wurde

# DateTimeImmutable::createFromInterface

(PHP 8)

DateTimeImmutable::createFromInterface — Liefert ein neues DateTimeImmutable-Objekt, das das angegebene DateTimeInterface-Objekt kapselt

### Beschreibung

public static function DateTimeImmutable::createFromInterface(DateTimeInterface `$object`): DateTimeImmutable

### Parameter-Liste

`object`

  Das DateTimeInterface-Objekt, das in eine nicht veränderbare Version konvertiert werden soll. Dieses Objekt wird nicht verändert, sondern es wird ein neues DateTimeImmutable-Objekt erstellt, das dieselben Informationen über Datum, Uhrzeit und Zeitzone enthält.

### Rückgabewerte

Gibt eine neue DateTimeImmutable-Instanz zurück.

### Beispiele

Beispiel #1 Erstellen eines unveränderbaren DateTime-Objekts

    <?php
    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromInterface($date);

    $date = new DateTimeImmutable("2014-06-20 11:45 Europe/London");
    $also_immutable = DateTimeImmutable::createFromInterface($date);

# DateTimeImmutable::createFromMutable

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

DateTimeImmutable::createFromMutable — Liefert eine neue DateTimeImmutable-Instanz, die das angegebene DateTime-Objekt kapselt

### Beschreibung

public static function DateTimeImmutable::createFromMutable(DateTime `$object`): static

### Parameter-Liste

`object`

  Das veränderbare DateTime-Objekt, das in eine nicht veränderbare Version konvertiert werden soll. Dieses Objekt wird nicht verändert, sondern es wird eine neue DateTimeImmutable-Instanz erstellt, das dieselben Informationen über Datum, Uhrzeit und Zeitzone enthält.

### Rückgabewerte

Gibt eine neue DateTimeImmutable-Instanz zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Die Methode gibt nun eine Instanz der aktuell aufgerufenen Klasse zurück. Zuvor hat sie eine neue Instanz von DateTimeImmutable erzeugt.

### Beispiele

Beispiel #1 Erstellen eines nicht veränderbaren DateTime-Objekts

    <?php
    $date = new DateTime("2014-06-20 11:45 Europe/London");
    $immutable = DateTimeImmutable::createFromMutable( $date );

# DateTimeImmutable::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTimeImmutable::createFromTimestamp — Creates an instance from a Unix timestamp

### Beschreibung

public static function DateTimeImmutable::createFromTimestamp(int|float `$timestamp`): static

Creates an instance from a Unix timestamp.

### Parameter-Liste

`timestamp`
  Unix timestamp representing the date. A Float value is also accepted which allows for microsecond precision.

### Rückgabewerte

Returns a new DateTimeImmutable instance.

### Fehler/Exceptions

If the `timestamp` is outside the range [`PHP_INT_MIN`, `PHP_INT_MAX`], a DateRangeError is thrown.

### Beispiele

Beispiel #1 DateTimeImmutable::createFromTimestamp() example

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1970-01-01 00:02:03.456789

# DateTimeImmutable::getLastErrors

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::getLastErrors — Liefert die Warnungen und Fehler

### Beschreibung

public static function DateTimeImmutable::getLastErrors(): array|false

Gibt ein Array von Warnungen und Fehlern zurück, die beim Parsen einer Datum/Zeit-Zeichenkette gefunden wurden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array zurück, das Informationen über Warnungen und Fehler enthält, oder `false`, wenn es weder Warnungen noch Fehler gibt.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Vor PHP 8.2.0 gab diese Funktion nicht `false` zurück, wenn es keine Warnungen oder Fehler gab. Stattdessen gab sie immer die dokumentierte Array-Struktur zurück.

### Beispiele

Beispiel #1 DateTimeImmutable::getLastErrors()-Beispiel

    <?php
    try {
        $date = new DateTimeImmutable('asdfasdf');
    } catch (Exception $e) {
        // Nur zur Veranschaulichung...
        print_r(DateTimeImmutable::getLastErrors());

        // Wirklich objektorientiert geht dies folgendermaßen
        // echo $e->getMessage();
    }
    ?>

Die obigen Bespiele erzeugen folgende Ausgabe:

    Array
    (
       [warning_count] => 1
       [warnings] => Array
           (
               [6] => Double timezone specification
           )

       [error_count] => 1
       [errors] => Array
           (
               [0] => The timezone could not be found in the database
           )

    )

Die Indizes 6 und 0 in der Beispielausgabe beziehen sich auf den Zeichenindex in der Zeichenkette, in der der Fehler aufgetreten ist.

# DateTimeImmutable::modify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::modify — Erzeugt ein neues Objekt mit geändertem Zeitstempel

### Beschreibung

#[\NoDiscard]
public function DateTimeImmutable::modify(string `$modifier`): DateTimeImmutable

Erzeugt ein neues DateTimeImmutable-Objekt mit einem geänderten Zeitstempel. Das ursprüngliche Objekt wird nicht verändert.

### Parameter-Liste

`modifier`

  Ein Datums/Zeit Zeichenkette. Gültige Formate werden unter Datums- und Zeitformate erläutert.

### Rückgabewerte

Gibt eine Instanz von DateTimeImmutable zurück. Prozeduraler Stil Im Fehlerfall wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn eine ungültige Datum/Uhrzeit-Zeichenkette übergeben wird, wird eine DateMalformedStringException ausgelöst. Vor PHP 8.3 wurde eine Warnung ausgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | DateTimeImmutable::modify() löst nun eine DateMalformedStringException aus, wenn eine ungültige Zeichenkette übergeben wird. Zuvor wurde `false` zurückgegeben, und eine Warnung wurde ausgegeben.

### Beispiele

Beispiel #1 DateTimeImmutable::modify()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable('2006-12-12');
    $newDate = $date->modify('+1 day');
    echo $newDate->format('Y-m-d');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2006-12-13

Beispiel #2 Vorsicht beim Addieren oder Subtrahieren von Monaten

    <?php
    $date = new DateTimeImmutable('2000-12-31');

    $newDate1 = $date->modify('+1 month');
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->modify('+1 month');
    echo $newDate2->format('Y-m-d') . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2001-01-31
    2001-03-03

### Siehe auch

- DateTimeImmutable::add() - Liefert ein neues Objekt, bei dem eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden zu einem bestehenden Objekt addiert wurde
- DateTimeImmutable::sub() - Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden
- DateTimeImmutable::setDate() - Legt das Datum fest
- DateTimeImmutable::setISODate() - Legt das ISO-Datum fest
- DateTimeImmutable::setTime() - Legt die Uhrzeit fest
- DateTimeImmutable::setTimestamp() - Legt das Datum und die Uhrzeit basierend auf einem Unix-Zeitstempel fest

# DateTimeImmutable::__set_state

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__set_state — Der __set_state-Handler

### Beschreibung

public static function DateTimeImmutable::__set_state(array `$array`): DateTimeImmutable

Der __set_state()-Handler.

### Parameter-Liste

`array`

  Das Array für die Initialisierung.

### Rückgabewerte

Gibt eine neue Instanz eines DateTimeImmutable-Objekts zurück.

# DateTimeImmutable::setDate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setDate — Legt das Datum fest

### Beschreibung

#[\NoDiscard]
public function DateTimeImmutable::setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable

Gibt ein neues DateTimeImmutable-Objekt zurück, bei dem das aktuelle Datum des DateTimeImmutable-Objekts auf das angegebene Datum gesetzt wurde.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt. Diese Funktion verändert dieses Objekt.

`year`

  Das Jahr des Datums

`month`

  Der Monat des Datums

`day`

  Der Tag des Datums

### Rückgabewerte

Gibt ein neues DateTimeImmutable-Objekt mit den geänderten Daten zurück.

### Beispiele

Beispiel #1 DateTimeImmutable::setDate()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable();
    $newDate = $date->setDate(2001, 2, 3);
    echo $newDate->format('Y-m-d');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2001-02-03

Beispiel #2 Werte, die einen Bereich überschreiten, werden zu ihren übergeordneten Werten hinzugefügt

    <?php
    $date = new DateTimeImmutable();

    $newDate = $date->setDate(2001, 2, 28);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 2, 29);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setDate(2001, 14, 3);
    echo $newDate->format('Y-m-d') . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2001-02-28
    2001-03-01
    2002-02-03

### Siehe auch

- DateTimeImmutable::setISODate() - Legt das ISO-Datum fest
- DateTimeImmutable::setTime() - Legt die Uhrzeit fest

# DateTimeImmutable::setISODate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setISODate — Legt das ISO-Datum fest

### Beschreibung

#[\NoDiscard]
public function DateTimeImmutable::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable

Gibt ein neues DateTimeImmutable-Objekt zurück, bei dem das Datum gemäß dem ISO 8601-Standard gesetzt wurde, d. h. mit Wochen- und Tagesoffsets statt mit konkreten Daten.

### Parameter-Liste

`year`

  Das Jahr des Datums

`week`

  Die Woche des Datums

`dayOfWeek`

  Der Abstand zum ersten Tag der Woche

### Rückgabewerte

Gibt ein neues DateTimeImmutable-Objekt mit den geänderten Daten zurück.

### Beispiele

Beispiel #1 DateTimeImmutable::setISODate()-Beispiel

Objektorientierter Stil

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2008-01-07
    2008-01-13

Prozeduraler Stil

    <?php

    $date = date_create();

    date_isodate_set($date, 2008, 2);
    echo date_format($date, 'Y-m-d') . "\n";

    date_isodate_set($date, 2008, 2, 7);
    echo date_format($date, 'Y-m-d') . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2008-01-07
    2008-01-13

Beispiel #2 Werte, die einen Bereich überschreiten, werden zu ihren übergeordneten Werten hinzugefügt

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 8);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 53, 7);
    echo $newDate->format('Y-m-d') . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2008-01-13
    2008-01-14
    2009-01-04

Beispiel #3 Ermitteln des Monats, in dem eine Woche liegt

    <?php

    $date = new DateTimeImmutable();
    $newDate = $date->setISODate(2008, 14);
    echo $newDate->format('n');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3

### Siehe auch

- DateTimeImmutable::setDate() - Legt das Datum fest
- DateTimeImmutable::setTime() - Legt die Uhrzeit fest

# DateTimeImmutable::setMicrosecond

(PHP 8 >= 8.4.0)

DateTimeImmutable::setMicrosecond — Sets microsecond part of the time

### Beschreibung

#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function DateTimeImmutable::setMicrosecond(int `$microsecond`): static

Returns a new DateTimeImmutable object constructed from the old one, with modified microsecond part.

### Parameter-Liste

`microsecond`
  The microsecond value to set (`0` to `999999`).

### Rückgabewerte

Gibt ein neues DateTimeImmutable-Objekt mit den geänderten Daten zurück.

### Fehler/Exceptions

If the `microsecond` is outside the range [`0`, `999999`], a DateRangeError is thrown.

### Beispiele

Beispiel #1 DateTimeImmutable::setMicrosecond() example

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date = $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### Siehe auch

- DateTimeInterface::getMicrosecond() - Gets the microsecond part of the Unix timestamp

# DateTimeImmutable::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTime — Legt die Uhrzeit fest

### Beschreibung

#[\NoDiscard]
public function DateTimeImmutable::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable

Gibt ein neues DateTimeImmutable-Objekt zurück, bei dem die Uhrzeit auf die angegebene Zeit gesetzt ist.

### Parameter-Liste

`hour`

  Die Stunde der Uhrzeit

`minute`

  Die Minute der Uhrzeit

`second`

  Die Sekunde der Uhrzeit

`microsecond`

  Die Mikrosekunde der Uhrzeit

### Rückgabewerte

Gibt ein neues DateTimeImmutable-Objekt mit den geänderten Daten zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Das Verhalten bei doppelt vorhandenen Stunden (während der Umstellung von Sommer- auf Normalzeit) wurde geändert. Bisher wählte PHP die zweite Stundenzahl (nach der Zeitumstellung), statt der ersten (vor der Zeitumstellung).
7.1.0 | Der Parameter `microsecond` wurde hinzugefügt.

### Beispiele

Beispiel #1 DateTimeImmutable::setTime()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2001-01-01 14:55:00
    2001-01-01 14:55:24

Beispiel #2 Werte, die einen Bereich überschreiten, werden zu ihren übergeordneten Werten hinzugefügt

    <?php
    $date = new DateTimeImmutable('2001-01-01');

    $newDate = $date->setTime(14, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 55, 65);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(14, 65, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $newDate = $date->setTime(25, 55, 24);
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2001-01-01 14:55:24
    2001-01-01 14:56:05
    2001-01-01 15:05:24
    2001-01-02 01:55:24

### Siehe auch

- DateTimeImmutable::setDate() - Legt das Datum fest
- DateTimeImmutable::setISODate() - Legt das ISO-Datum fest

# DateTimeImmutable::setTimestamp

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimestamp — Legt das Datum und die Uhrzeit basierend auf einem Unix-Zeitstempel fest

### Beschreibung

#[\NoDiscard]
public function DateTimeImmutable::setTimestamp(int `$timestamp`): DateTimeImmutable

Gibt ein neues DateTimeImmutable-Objekt zurück, das aus dem alten Objekt erstellt wurde, wobei das Datum und die Uhrzeit auf der Basis eines Unix-Zeitstempels gesetzt wurden.

### Parameter-Liste

`timestamp`

  Ein Unix-Zeitstempel, der das Datum darstellt. Um Zeitstempel außerhalb des Bereichs von Integer zu setzen, kann die Methode DateTimeImmutable::modify() mit dem `@`-Format verwendet werden.

### Rückgabewerte

Gibt ein neues DateTimeImmutable-Objekt mit den geänderten Daten zurück.

### Beispiele

Beispiel #1 DateTimeImmutable::setTimestamp()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable();
    echo $date->format('U = Y-m-d H:i:s') . "\n";

    $newDate = $date->setTimestamp(1171502725);
    echo $newDate->format('U = Y-m-d H:i:s') . "\n";

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1272508903 = 2010-04-28 22:41:43
    1171502725 = 2007-02-14 20:25:25

### Siehe auch

- DateTimeImmutable::getTimestamp() - Liefert den Unix-Zeitstempel

# DateTimeImmutable::setTimezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimezone — Legt die Zeitzone fest

### Beschreibung

#[\NoDiscard]
public function DateTimeImmutable::setTimezone(DateTimeZone `$timezone`): DateTimeImmutable

Gibt ein neues DateTimeImmutable-Objekt mit einer neu gesetzten Zeitzone zurück.

### Parameter-Liste

`timezone`

  Ein DateTimeZone-Objekt, das die gewünschte Zeitzone repräsentiert.

### Rückgabewerte

Gibt ein neues geändertes DateTimeImmutable-Objekt für die Methodenverkettung zurück. Der zugrunde liegende Zeitpunkt wird beim Aufruf dieser Methode nicht verändert.

### Beispiele

Beispiel #1 DateTimeImmutable::setTimeZone()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru'));
    echo $date->format('Y-m-d H:i:sP') . "\n";

    $newDate = $date->setTimezone(new DateTimeZone('Pacific/Chatham'));
    echo $newDate->format('Y-m-d H:i:sP') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

### Siehe auch

- DateTimeImmutable::getTimezone() - Liefert die Zeitzone relativ zur angegebenen DateTime
- DateTimeZone::__construct() - Erstellt neues DateTimeZone-Objekt

# DateTimeImmutable::sub

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::sub — Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden

### Beschreibung

#[\NoDiscard]
public function DateTimeImmutable::sub(DateInterval `$interval`): DateTimeImmutable

Gibt ein neues DateTimeImmutable-Objekt zurück, bei dem das angegebene DateInterval-Objekt vom angegebenen DateTimeImmutable-Objekt subtrahiert wurde.

### Parameter-Liste

`interval`

  Ein DateInterval-Objekt

### Rückgabewerte

Gibt ein neues DateTimeImmutable-Objekt mit den geänderten Daten zurück.

### Fehler/Exceptions

Wenn versucht wird, eine nicht unterstützte Operation durchzuführen, z. B. mit einem DateInterval-Objekt, das relative Zeitangaben wie `next weekday` enthält, wird eine DateInvalidOperationException geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wirft nun eine DateInvalidOperationException, statt eine Warnung auszugeben, wenn versucht wird, eine nicht unterstützte Operation durchzuführen.

### Beispiele

Beispiel #1 DateTimeImmutable::sub()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P10D'));
    echo $newDate->format('Y-m-d') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2000-01-10

Beispiel #2 Weitere DateTimeImmutable::sub()-Beispiele

    <?php
    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('PT10H30S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";

    $date = new DateTimeImmutable('2000-01-20');
    $newDate = $date->sub(new DateInterval('P7Y5M4DT4H3M2S'));
    echo $newDate->format('Y-m-d H:i:s') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2000-01-19 13:59:30
    1992-08-15 19:56:58

Beispiel #3 Vorsicht beim Subtrahieren von Monaten

    <?php
    $date = new DateTimeImmutable('2001-04-30');
    $interval = new DateInterval('P1M');

    $newDate1 = $date->sub($interval);
    echo $newDate1->format('Y-m-d') . "\n";

    $newDate2 = $newDate1->sub($interval);
    echo $newDate2->format('Y-m-d') . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2001-03-30
    2001-03-02

### Siehe auch

- DateTimeImmutable::add() - Liefert ein neues Objekt, bei dem eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden zu einem bestehenden Objekt addiert wurde
- DateTimeImmutable::diff() - Liefert die Differenz zwischen zwei DateTime-Objekten
- DateTimeImmutable::modify() - Erzeugt ein neues Objekt mit geändertem Zeitstempel

## Inhaltsverzeichnis

- DateTimeImmutable::add — Liefert ein neues Objekt, bei dem eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden zu einem bestehenden Objekt addiert wurde
- DateTimeImmutable::__construct — Liefert ein neues DateTimeImmutable-Objekt
- DateTimeImmutable::createFromFormat — Wertet eine Zeitangabe gemäß dem angegebenen Format aus
- DateTimeImmutable::createFromInterface — Liefert ein neues DateTimeImmutable-Objekt, das das angegebene DateTimeInterface-Objekt kapselt
- DateTimeImmutable::createFromMutable — Liefert eine neue DateTimeImmutable-Instanz, die das angegebene DateTime-Objekt kapselt
- DateTimeImmutable::createFromTimestamp — Creates an instance from a Unix timestamp
- DateTimeImmutable::getLastErrors — Liefert die Warnungen und Fehler
- DateTimeImmutable::modify — Erzeugt ein neues Objekt mit geändertem Zeitstempel
- DateTimeImmutable::__set_state — Der __set_state-Handler
- DateTimeImmutable::setDate — Legt das Datum fest
- DateTimeImmutable::setISODate — Legt das ISO-Datum fest
- DateTimeImmutable::setMicrosecond — Sets microsecond part of the time
- DateTimeImmutable::setTime — Legt die Uhrzeit fest
- DateTimeImmutable::setTimestamp — Legt das Datum und die Uhrzeit basierend auf einem Unix-Zeitstempel fest
- DateTimeImmutable::setTimezone — Legt die Zeitzone fest
- DateTimeImmutable::sub — Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden

# Das DateTimeInterface-Interface

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

Das DateTimeInterface wurde eingeführt, damit Parameter-, Rückgabe- oder Eigenschaftstyp-Deklarationen entweder DateTimeImmutable oder DateTime als Wert annehmen können. Es ist nicht möglich, dieses Interface in benutzerdefinierten Klassen zu implementieren.

Gemeinsame Konstanten, die es ermöglichen, DateTimeImmutable- oder DateTime-Objekte durch DateTimeImmutable::format() und DateTime::format() zu formatieren, sind in diesem Interface ebenfalls definiert.

## Interface-Übersicht

interface DateTimeInterface {
/* Konstanten */
public const string ATOM = "Y-m-d\\TH:i:sP";
public const string COOKIE = "l, d-M-Y H:i:s T";
public const string ISO8601 = "Y-m-d\\TH:i:sO";
public const string ISO8601_EXPANDED = "X-m-d\\TH:i:sP";
public const string RFC822 = "D, d M y H:i:s O";
public const string RFC850 = "l, d-M-y H:i:s T";
public const string RFC1036 = "D, d M y H:i:s O";
public const string RFC1123 = "D, d M Y H:i:s O";
public const string RFC7231 = "D, d M Y H:i:s \\G\\M\\T";
public const string RFC2822 = "D, d M Y H:i:s O";
public const string RFC3339 = "Y-m-d\\TH:i:sP";
public const string RFC3339_EXTENDED = "Y-m-d\\TH:i:s.vP";
public const string RSS = "D, d M Y H:i:s O";
public const string W3C = "Y-m-d\\TH:i:sP";
/* Methoden */
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## Vordefinierte Konstanten

DateTimeInterface::ATOM string
DATE_ATOM
  Atom (Beispiel: 2005-08-15T15:52:01+00:00)
DateTimeInterface::COOKIE string
DATE_COOKIE
  HTTP-Cookies (Beispiel: Monday, 15-Aug-05 15:52:01 UTC)
DateTimeInterface::ISO8601 string
DATE_ISO8601
  ISO-8601 (Beispiel: 2005-08-15T15:52:01+0000)

  > Hinweis: Dieses Format ist nicht kompatibel zu ISO-8601, wird aber aus Gründen der Abwärtskompatibilität so belassen. Für ISO-8601-Kompatibilität sollte stattdessen DateTimeInterface::ISO8601_EXPANDED oder DateTimeInterface::ATOM verwendet werden (siehe ISO8601:2004 Abschnitt 4.3.3 Punkt d).

DateTimeInterface::ISO8601_EXPANDED string
DATE_ISO8601_EXPANDED
  ISO-8601 erweitert (Beispiel: +10191-07-26T08:59:52+01:00)

  > Hinweis: Dadurch, dass dieses Format immer ein Vorzeichen enthält, können Jahresangaben außerhalb des normalen Bereichs von ISO-8601 (`0000`-`9999`) angegeben werden. Es stellt außerdem sicher, dass der Teil mit der Zeitzone (`+01:00`) mit ISO-8601 kompatibel ist.

DateTimeInterface::RFC822 string
DATE_RFC822
  RFC 822 (Beispiel: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC850 string
DATE_RFC850
  RFC 850 (Beispiel: Monday, 15-Aug-05 15:52:01 UTC)
DateTimeInterface::RFC1036 string
DATE_RFC1036
  RFC 1036 (Beispiel: Mon, 15 Aug 05 15:52:01 +0000)
DateTimeInterface::RFC1123 string
DATE_RFC1123
  RFC 1123 (Beispiel: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC7231 string
DATE_RFC7231
  RFC 7231 (seit PHP 7.0.19 und 7.1.5) (Beispiel: Sat, 30 Apr 2016 17:52:13 GMT)
DateTimeInterface::RFC2822 string
DATE_RFC2822
  RFC 2822 (Beispiel: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::RFC3339 string
DATE_RFC3339
  Genau wie DATE_ATOM
DateTimeInterface::RFC3339_EXTENDED string
DATE_RFC3339_EXTENDED
  RFC 3339 EXTENDED Format (Beispiel: 2005-08-15T15:52:01.000+00:00)
DateTimeInterface::RSS string
DATE_RSS
  RSS (Beispiel: Mon, 15 Aug 2005 15:52:01 +0000)
DateTimeInterface::W3C string
DATE_W3C
  World Wide Web Consortium (Beispiel: 2005-08-15T15:52:01+00:00)

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Klassenkonstanten sind nun typisiert.
8.2.0 | Die Konstante `DateTimeInterface::ISO8601_EXPANDED` wurde hinzugefügt.
7.2.0 | Die Klassenkonstanten von DateTime sind nun in DateTimeInterface definiert.

# DateTimeInterface::diff

# DateTimeImmutable::diff

# DateTime::diff

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::diff -- DateTimeImmutable::diff -- DateTime::diff -- date_diff — Liefert die Differenz zwischen zwei DateTime-Objekten

### Beschreibung

Objektorientierter Stil

public function DateTimeInterface::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTimeImmutable::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTime::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Prozeduraler Stil

function date_diff(DateTimeInterface `$baseObject`, DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

Gibt die Differenz zwischen zwei DateTimeInterface-Objekten zurück.

### Parameter-Liste

`datetime`

  Das Datum, mit dem verglichen werden soll.

`absolute`

  Soll das Intervall zwingend positiv sein?

### Rückgabewerte

Das DateInterval-Objekt stellt die Differenz zwischen den beiden Daten dar.

Der Parameter `absolute` wirkt sich nur auf die Eigenschaft `invert` des DateInterval-Objekts aus.

Genauer gesagt stellt der Rückgabewert das Zeitintervall dar, das auf das ursprüngliche Objekt (`$this` oder `$originObject`) anzuwenden ist, um das `$targetObject` zu erhalten. Dieser Prozess ist nicht immer umkehrbar.

Die Methode berücksichtigt die Zeitumstellung und kann daher ein Intervall von `24 Stunden und 30 Minuten` zurückgeben, wie in einem der Beispiele. Wenn mit absoluter Zeit gerechnet werden soll, müssen die beiden Parameter `$this`/`$baseObject` und `$targetObject` zuerst in UTC umgewandelt werden.

### Beispiele

Beispiel #1 DateTimeImmutable::diff()-Beispiel

Objektorientierter Stil

    <?php
    $origin = new DateTimeImmutable('2009-10-11');
    $target = new DateTimeImmutable('2009-10-13');
    $interval = $origin->diff($target);
    echo $interval->format('%R%a Tage');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    +2 days

Prozeduraler Stil

    <?php
    $origin = date_create('2009-10-11');
    $target = date_create('2009-10-13');
    $interval = date_diff($origin, $target);
    echo $interval->format('%R%a Tage');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    +2 Tage

Beispiel #2 DateTimeInterface::diff() während der Zeitumstellung

    <?php
    $originalTime = new DateTimeImmutable("2021-10-30 09:00:00 Europe/London");
    $targetTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
    $interval = $originalTime->diff($targetTime);
    echo $interval->format("%H:%I:%S (Full days: %a)"), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    24:30:00 (Full days: 0)

Beispiel #3 Zeitspanne von DateTimeInterface::diff()

Der Wert, den die Methode zurückgibt, ist die genaue Zeitspanne zwischen `$this` und `$targetObject`. Der Vergleich zwischen dem 1. Januar und dem 31. Dezember ergibt also 364 Tage und nicht 365 (in einem Nicht-Schaltjahr).

    <?php
    $originalTime = new DateTimeImmutable("2023-01-01 UTC");
    $targetTime = new DateTimeImmutable("2023-12-31 UTC");
    $interval = $originalTime->diff($targetTime);
    echo "Full days: ", $interval->format("%a"), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Full days: 364

Beispiel #4 Vergleich von DateTime-Objekten

> Hinweis:

> DateTimeImmutable- und DateTime-Objekte können mit Vergleichs-Operatoren verglichen werden.

    <?php
    $date1 = new DateTime("now");
    $date2 = new DateTime("tomorrow");

    var_dump($date1 == $date2);
    var_dump($date1 < $date2);
    var_dump($date1 > $date2);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(false)

### Siehe auch

- DateInterval::format() - Formatiert ein Intervall
- DateTime::add() - Ändert ein DateTime-Objekt, wobei die Anzahl der Tage, Monate, Jahre, Stunden, Minuten und Sekunden hinzugefügt wird
- DateTime::sub() - Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden von einem DateTime-Objekt.

# DateTimeInterface::format

# DateTimeImmutable::format

# DateTime::format

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::format -- DateTimeImmutable::format -- DateTime::format -- date_format — Liefert das Datum formatiert gemäß dem angegebenen Format

### Beschreibung

Objektorientierter Stil

public function DateTimeInterface::format(string `$format`): string
public function DateTimeImmutable::format(string `$format`): string
public function DateTime::format(string `$format`): string

Prozeduraler Stil

function date_format(DateTimeInterface `$object`, string `$format`): string

Gibt das Datum im angegebenen Format zurück.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt.

`format`

  Das Format des ausgegebenen Datums vom Typ string. Siehe die Formatierungsoptionen unten. Es gibt auch mehrere vordefinierte Datumskonstanten, die stattdessen verwendet werden können, z. B. enthält `DATE_RSS` die Formatzeichenkette `'D, d M Y H:i:s'`.

  Die folgenden Zeichen werden in der Parameterzeichenkette `format` erkannt
  `format`-Zeichen | Beschreibung | Mögliche Rückgabewerte
  --- | --- | ---
  Tag | --- | ---
  `d` | Tag des Monats; zwei Ziffern mit vorangestellter Null | `01` bis `31`
  `D` | Textuelle Darstellung eines Tages; drei Buchstaben | `Mon` bis `Sun`
  `j` | Tag des Monats; zwei Ziffern ohne vorangestellte Null | `1` bis `31`
  `l` (kleines 'L') | Vollständige textuelle Darstellung eines Tages | `Sunday` bis `Saturday`
  `N` | Numerische Darstellung eines Wochentags gemäß ISO-8601 | `1` (für Montag) bis `7` (für Sonntag)
  `S` | Englisches Ordnungssuffix für den Tag des Monats; zwei Buchstaben | `st`, `nd`, `rd` oder `th`; funktioniert gut mit `j`
  `w` | Numerische Darstellung eines Wochentags | `0` (für Sonntag) bis `6` (für Samstag)
  `z` | Tag des Jahres (beginnend bei 0) | `0` bis `365`
  Woche | --- | ---
  `W` | Wochennummer eines Jahres gemäß ISO-8601; die Wochen beginnen am Montag | Beispiel: `42` (die 42. Woche des Jahres)
  Monat | --- | ---
  `F` | Vollständige textuelle Darstellung eines Monats, z. B. January oder March | `January` bis `December`
  `m` | Numerische Darstellung eines Monats; mit vorangestellter Null | `01` bis `12`
  `M` | Kurze textuelle Darstellung eines Monats; drei Buchstaben | `Jan` bis `Dec`
  `n` | Numerische Darstellung eines Monats; ohne vorangestellte Null | `1` bis `12`
  `t` | Anzahl der Tage des angegebenen Monats | `28` bis `31`
  Jahr | --- | ---
  `L` | Gibt an, ob es ein Schaltjahr ist | `1` wenn es ein Schaltjahr ist, andernfalls `0`
  `o` | Jahreszahl gemäß ISO 8601-Wochennummer. Dies hat den gleichen Wert wie `Y`, außer wenn die ISO-Wochennummer (`W`) zum vorherigen oder nächsten Jahr gehört; dann wird stattdessen das Jahr dieser Woche verwendet. | Beispiele: `1999` oder `2003`
  `X` | Erweiterte vollständige numerische Darstellung einer Jahreszahl, mindestens 4-stellig, mit `-` für Jahre vor Christus und `+` für Jahre nach Christus. | Beispiele: `-0055`, `+0787`, `+1999`, `+10191`
  `x` | Erweiterte vollständige numerische Darstellung einer Jahreszahl, falls erforderlich, oder standardmäßige vollständige numerische Darstellung, falls möglich (wie `Y`). Mindestens vier Ziffern. Jahren vor Christi Geburt wird ein `-` vorangestellt. Jahreszahlen über (und einschließlich) `10000` werden mit einem `+` eingeleitet. | Beispiele: `-0055`, `0787`, `1999`, `+10191`
  `Y` | Vollständige numerische Darstellung einer Jahreszahl; mindestens vier Ziffern, mit `-` für die Jahre vor Christus | Beispiele: `-0055`, `0787`, `1999`, `2003`, `10191`
  `y` | Darstellung einer Jahreszahl; zwei Ziffern | Beispiele: `99` oder `03`
  Zeit | --- | ---
  `a` | Ante meridiem und Post meridiem in Kleinbuchstaben | `am` oder `pm`
  `A` | Ante meridiem und Post meridiem in Großbuchstaben | `AM` oder `PM`
  `B` | Swatch-Internetzeit | `000` bis `999`
  `g` | Stunde im 12-Stunden-Format; ohne vorangestellte Null | `1` bis `12`
  `G` | Stunde im 24-Stunden-Format; ohne vorangestellte Null | `0` bis `23`
  `h` | Stunde im 12-Stunden-Format; mit vorangestellter Null | `01` bis `12`
  `H` | Stunde im 24-Stunden-Format; mit vorangestellter Null | `00` bis `23`
  `i` | Minuten; mit vorangestellter Null | `00` bis `59`
  `s` | Sekunden; mit vorangestellter Null | `00` bis `59`
  `u` | Mikrosekunden. Es ist zu beachten, dass die Funktion date() immer `000000` ausgibt, weil sie einen Parameter vom Typ int erwartet, während DateTimeInterface::format() Mikrosekunden unterstützt, wenn ein Objekt vom Typ DateTimeInterface mit Mikrosekunden erstellt wurde. | Beispiel: `654321`
  `v` | Millisekunden. Es gilt der gleiche Hinweis wie für `u`. | Beispiel: `654`
  Zeitzone | --- | ---
  `e` | Bezeichner der Zeitzone | Beispiele: `UTC`, `GMT`, `Atlantic/Azores`
  `I` (großes i) | Gibt an, ob das Datum in der Sommerzeit liegt oder nicht | `1` für Sommerzeit, andernfalls `0`
  `O` | Differenz zur Greenwich-Zeit (GMT); ohne Doppelpunkt zwischen Stunden und Minuten | Beispiel: `+0200`
  `P` | Differenz zur Greenwich-Zeit (GMT); mit Doppelpunkt zwischen Stunden und Minuten | Beispiel: `+02:00`
  `p` | Dasselbe wie `P`, gibt aber `Z` zurück anstelle von `+00:00` (verfügbar seit PHP 8.0.0) | Beispiele: `Z` oder `+02:00`
  `T` | Zeitzonenkürzel, falls bekannt; andernfalls die Abweichung von der GMT | Beispiele: `EST`, `MDT`, `+05`
  `Z` | Zeitverschiebung in Sekunden. Der Wert ist für Zeitzonen westlich von der UTC immer negativ und für die Zeitzonen östlich von der UTC immer positiv. | `-43200` bis `50400`
  Datum und Uhrzeit vollständig | --- | ---
  `c` | Datum gemäß ISO 8601. Nur kompatibel mit dem nicht erweiterten Format (bis zum Jahr 9999). Spätere Daten führen zu einer ungültigen Zeichenkette. Für spätere Daten und das erweiterte Format siehe `x` und `X`. | 2004-02-12T15:19:21+00:00
  `r` | Datum im Format » RFC 2822/» RFC 5322 | Beispiel: `Thu, 21 Dec 2000 16:01:07 +0200`
  `U` | Sekunden seit der Unix-Epoche (1. Januar 1970 00:00:00 GMT) | Siehe auch time()

  In der Formatzeichenkette nicht erkannte Zeichen werden unverändert ausgegeben. In Verbindung mit der Funktion gmdate() gibt das Format `Z` immer `0` zurück.

  > Hinweis:

  > Da diese Funktion nur Zeitstempel vom Typ int akzeptiert, ist das Formatzeichen `u` nur dann nützlich, wenn die Funktion date_format() mit benutzerdefinierten Zeitstempeln verwendet wird, die mit date_create() erstellt wurden.

### Rückgabewerte

Gibt bei Erfolg eine Zeichenkette mit dem formatierten Datum zurück.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Die `format`-Zeichen `X` und `x` wurden hinzugefügt.
8.0.0 | Vor dieser Version wurde bei einem Fehler `false` zurückgegeben.

### Beispiele

Beispiel #1 DateTimeInterface::format()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable('2000-01-01');
    echo $date->format('Y-m-d H:i:s');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2000-01-01 00:00:00

Prozeduraler Stil

    <?php
    $date = date_create('2000-01-01');
    echo date_format($date, 'Y-m-d H:i:s');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2000-01-01 00:00:00

Beispiel #2 Weitere Beispiele

    <?php
    // Die Standard-Zeitzone setzen, die verwendet werden soll.
    date_default_timezone_set('UTC');

    // Jetzt
    $date = new DateTimeImmutable();

    // Gibt z. B. Folgendes aus: Wednesday
    echo $date->format('l'), "\n";

    // Gibt z. B. Folgendes aus: Wednesday 19th of October 2022 08:40:48 AM
    echo $date->format('l jS \o\f F Y h:i:s A'), "\n";

    /* Verwenden von Konstanten im Format-Parameter */
    // Gibt z. B. Folgendes aus: Wed, 19 Oct 2022 08:40:48 +0000
    echo $date->format(DateTimeInterface::RFC2822), "\n";
    ?>

Um zu verhindern, dass ein bekanntes Zeichen in der Formatzeichenkette interpretiert wird, kann es mit einem vorangestellten Backslash maskiert werden. Wenn das Zeichen mit dem Backslash bereits eine spezielle Zeichenfolge ist, muss eventuell auch der Backslash maskiert werden.

Beispiel #3 Zeichen beim Formatieren maskieren

    <?php
    $date = new DateTimeImmutable();

    // Gibt z. B. Folgendes aus: Wednesday the 19th
    echo $date->format('l \t\h\e jS');
    ?>

Um Daten in anderen Sprachen zu formatieren, kann IntlDateFormatter::format() anstelle von DateTimeInterface::format() verwendet werden.

### Anmerkungen

Diese Methode verwendet keine Gebietsschemata; die gesamte Ausgabe erfolgt auf englisch.

### Siehe auch

- date() - Formatiert einen Unix-Zeitstempel

# DateTimeInterface::getMicrosecond

# DateTimeImmutable::getMicrosecond

# DateTime::getMicrosecond

(PHP 8 >= 8.4.0)

DateTimeInterface::getMicrosecond -- DateTimeImmutable::getMicrosecond -- DateTime::getMicrosecond — Gets the microsecond part of the Unix timestamp

### Beschreibung

public function DateTimeInterface::getMicrosecond(): int
public function DateTimeImmutable::getMicrosecond(): int
public function DateTime::getMicrosecond(): int

Gets the microsecond part of the Unix timestamp.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the microsecond part of the Unix timestamp representing the date.

### Beispiele

Beispiel #1 DateTimeInterface::getMicrosecond() example

    <?php
    $date = new DateTimeImmutable('2024-01-01 12:34:56.789123');
    var_dump($date->format('u'));
    var_dump($date->getMicrosecond());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(6) "789123"
    int(789123)

### Siehe auch

- DateTimeInterface::getTimestamp() - Liefert den Unix-Zeitstempel
- DateTimeInterface::format() - Liefert das Datum formatiert gemäß dem angegebenen Format

# DateTimeInterface::getOffset

# DateTimeImmutable::getOffset

# DateTime::getOffset

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getOffset -- DateTimeImmutable::getOffset -- DateTime::getOffset -- date_offset_get — Liefert die Zeitverschiebung

### Beschreibung

Objektorientierter Stil

public function DateTimeInterface::getOffset(): int
public function DateTimeImmutable::getOffset(): int
public function DateTime::getOffset(): int

Prozeduraler Stil

function date_offset_get(DateTimeInterface `$object`): int

Gibt die Zeitverschiebung zurück.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt.

### Rückgabewerte

Gibt bei Erfolg die Abweichung der Zeitzone von der UTC in Sekunden zurück.

### Beispiele

Beispiel #1 DateTime::getOffset()-Beispiel

Objektorientierter Stil

    <?php
    $winter = new DateTimeImmutable('2010-12-21', new DateTimeZone('America/New_York'));
    $summer = new DateTimeImmutable('2008-06-21', new DateTimeZone('America/New_York'));

    echo $winter->getOffset() . "\n";
    echo $summer->getOffset() . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    -18000
    -14400

Prozeduraler Stil

    <?php
    $winter = date_create('2010-12-21', timezone_open('America/New_York'));
    $summer = date_create('2008-06-21', timezone_open('America/New_York'));

    echo date_offset_get($winter) . "\n";
    echo date_offset_get($summer) . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    -18000
    -14400

Anmerkung: -18000 = -5 Stunden, -14400 = -4 Stunden.

# DateTimeInterface::getTimestamp

# DateTimeImmutable::getTimestamp

# DateTime::getTimestamp

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeInterface::getTimestamp -- DateTimeImmutable::getTimestamp -- DateTime::getTimestamp -- date_timestamp_get — Liefert den Unix-Zeitstempel

### Beschreibung

Objektorientierter Stil

public function DateTimeInterface::getTimestamp(): int
public function DateTimeImmutable::getTimestamp(): int
public function DateTime::getTimestamp(): int

Prozeduraler Stil

function date_timestamp_get(DateTimeInterface `$object`): int

Gibt den Unix-Zeitstempel zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Unix-Zeitstempel zurück, der das Datum darstellt.

### Fehler/Exceptions

Wenn der Zeitstempel nicht als Integer dargestellt werden kann, wird ein DateRangeError geworfen. Vor PHP 8.3.0 wird ein ValueError geworfen und vor PHP 8.0.0 wurde in diesem Fall `false` zurückgegeben. Wenn DateTimeInterface::format() mit dem Format `U` verwendet wird, kann der Zeitstempel trotzdem als String abgerufen werden.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Die Exception für das Verlassen eines Wertebereichs (out-of-range) heißt nun DateRangeError.
8.0.0 | Diese Funktionen geben bei einem Fehler nicht mehr `false` zurück.

### Beispiele

Beispiel #1 DateTime::getTimestamp()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable();
    echo $date->getTimestamp();

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1272509157

Prozeduraler Stil

    <?php
    $date = date_create();
    echo date_timestamp_get($date);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1272509157

Wenn der Zeitstempel mit einer Auflösung im Milli- oder Mikrosekundenbereich benötigt wird, kann die Funktion DateTimeInterface::format() verwendet werden.

Beispiel #2 Auslesen des Zeitstempels mit einer Auflösung im Milli- und Mikrosekundenbereich

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable();
    $milli = (int) $date->format('Uv'); // Zeitstempel in Millisekunden
    $micro = (int) $date->format('Uu'); // Zeitstempel in Mikrosekunden

    echo $milli, "\n", $micro, "\n";

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1674057635586
    1674057635586918

### Siehe auch

- DateTime::setTimestamp() - Legt Datum und Zeit basierend auf einem Unix-Zeitstempel fest
- DateTimeImmutable::setTimestamp() - Legt das Datum und die Uhrzeit basierend auf einem Unix-Zeitstempel fest
- DateTimeInterface::format() - Liefert das Datum formatiert gemäß dem angegebenen Format

# DateTimeInterface::getTimezone

# DateTimeImmutable::getTimezone

# DateTime::getTimezone

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeInterface::getTimezone -- DateTimeImmutable::getTimezone -- DateTime::getTimezone -- date_timezone_get — Liefert die Zeitzone relativ zur angegebenen DateTime

### Beschreibung

Objektorientierter Stil

public function DateTimeInterface::getTimezone(): DateTimeZone|false
public function DateTimeImmutable::getTimezone(): DateTimeZone|false
public function DateTime::getTimezone(): DateTimeZone|false

Prozeduraler Stil

function date_timezone_get(DateTimeInterface `$object`): DateTimeZone|false

Gibt die Zeitzone relativ zur angegebenen DateTime zurück.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTime-Objekt.

### Rückgabewerte

Gibt bei Erfolg ein DateTimeZone-Objekt zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 DateTime::getTimezone()-Beispiel

Objektorientierter Stil

    <?php
    $date = new DateTimeImmutable("now", new DateTimeZone('Europe/London'));
    $tz = $date->getTimezone();
    echo $tz->getName();

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Europe/London

Prozeduraler Stil

    <?php
    $date = date_create("now", timezone_open('Europe/London'));
    $tz = date_timezone_get($date);
    echo timezone_name_get($tz);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Europe/London

### Siehe auch

- DateTime::setTimezone() - Legt die Zeitzone für ein DateTime-Objekt fest

# DateTime::__serialize

# DateTimeImmutable::__serialize

# DateTimeInterface::__serialize

(PHP 8 >= 8.2.0)

DateTime::__serialize -- DateTimeImmutable::__serialize -- DateTimeInterface::__serialize — Serialize a DateTime

### Beschreibung

public function DateTime::__serialize(): array
public function DateTimeImmutable::__serialize(): array
public function DateTimeInterface::__serialize(): array

The __serialize() handler.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The serialized representation of the DateTime object.

### Beispiele

Beispiel #1 DateTime::serialize() example

    <?php
    $date = new DateTime('2025-03-27');
    var_dump(serialize($date));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(114) "O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}"

### Siehe auch

- DateTime::__unserialize() - Unserialize an Datetime

# DateTime::__unserialize

# DateTimeImmutable::__unserialize

# DateTimeInterface::__unserialize

(PHP 8 >= 8.2.0)

DateTime::__unserialize -- DateTimeImmutable::__unserialize -- DateTimeInterface::__unserialize — Unserialize an Datetime

### Beschreibung

public function DateTime::__unserialize(array `$data`): void
public function DateTimeImmutable::__unserialize(array `$data`): void
public function DateTimeInterface::__unserialize(array `$data`): void

The __unserialize() handler.

### Parameter-Liste

`data`

  The serialized DateTime.

### Rückgabewerte

The DateTime object.

### Beispiele

Beispiel #1 DateTime::unserialize() example

    <?php
    $serializedDate = 'O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}';
    var_dump(unserialize($serializedDate));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(DateTime)#1 (3) {
      ["date"]=>
      string(26) "2025-03-27 00:00:00.000000"
      ["timezone_type"]=>
      int(3)
      ["timezone"]=>
      string(3) "UTC"
    }

### Siehe auch

- DateTime::__serialize() - Serialize a DateTime

# DateTime::__wakeup

# DateTimeImmutable::__wakeup

# DateTimeInterface::__wakeup

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__wakeup -- DateTimeImmutable::__wakeup -- DateTimeInterface::__wakeup — Der __wakeup-Handler

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
public function DateTime::__wakeup(): void
#[\Deprecated]
public function DateTimeImmutable::__wakeup(): void
#[\Deprecated]
public function DateTimeInterface::__wakeup(): void

Der __wakeup()-Handler.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Initialisiert ein DateTime-Objekt.

## Inhaltsverzeichnis

- DateTimeInterface::diff — Liefert die Differenz zwischen zwei DateTime-Objekten
- DateTimeInterface::format — Liefert das Datum formatiert gemäß dem angegebenen Format
- DateTimeInterface::getMicrosecond — Gets the microsecond part of the Unix timestamp
- DateTimeInterface::getOffset — Liefert die Zeitverschiebung
- DateTimeInterface::getTimestamp — Liefert den Unix-Zeitstempel
- DateTimeInterface::getTimezone — Liefert die Zeitzone relativ zur angegebenen DateTime
- DateTime::__serialize — Serialize a DateTime
- DateTime::__unserialize — Unserialize an Datetime
- DateTime::__wakeup — Der __wakeup-Handler

# Die Klasse DateTimeZone

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

## Einführung

Stellt die Zeitzone dar.

## Klassenbeschreibung

class DateTimeZone {
/* Konstanten */
public const int AFRICA;
public const int AMERICA;
public const int ANTARCTICA;
public const int ARCTIC;
public const int ASIA;
public const int ATLANTIC;
public const int AUSTRALIA;
public const int EUROPE;
public const int INDIAN;
public const int PACIFIC;
public const int UTC;
public const int ALL;
public const int ALL_WITH_BC;
public const int PER_COUNTRY;
/* Methoden */
public function __construct(string `$timezone`)
public function getLocation(): array|false
public function getName(): string
public function getOffset(DateTimeInterface `$datetime`): int
public function getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = `PHP_INT_MAX`): array|false
public static function listAbbreviations(): array
public static function listIdentifiers(int `$timezoneGroup` = DateTimeZone::ALL, ?string `$countryCode` = `null`): array
}

## Vordefinierte Konstanten

`DateTimeZone::AFRICA` int

  Afrikanische Zeitzonen

`DateTimeZone::AMERICA` int

  Amerikanische Zeitzonen

`DateTimeZone::ANTARCTICA` int

  Antarktische Zeitzonen

`DateTimeZone::ARCTIC` int

  Arktische Zeitzonen

`DateTimeZone::ASIA` int

  Asiatische Zeitzonen

`DateTimeZone::ATLANTIC` int

  Atlantische Zeitzonen

`DateTimeZone::AUSTRALIA` int

  Australische Zeitzonen

`DateTimeZone::EUROPE` int

  Europäische Zeitzonen

`DateTimeZone::INDIAN` int

  Indische Zeitzonen

`DateTimeZone::PACIFIC` int

  Pazifische Zeitzonen

`DateTimeZone::UTC` int

  UTC Zeitzonen

`DateTimeZone::ALL` int

  Alle Zeitzonen

`DateTimeZone::ALL_WITH_BC` int

  Alle Zeitzonen, auch abwärtskompatible

`DateTimeZone::PER_COUNTRY` int

  Zeitzonen pro Land

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Klassenkonstanten sind nun typisiert.

# DateTimeZone::__construct

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::__construct -- timezone_open — Erstellt neues DateTimeZone-Objekt

### Beschreibung

Objektorientierter Stil

public function DateTimeZone::__construct(string `$timezone`)

Prozeduraler Stil

function timezone_open(string `$timezone`): DateTimeZone|false

Erstellt neues DateTimeZone-Objekt.

Ein DateTimeZone-Objekt bietet Zugriff auf drei verschiedene Arten von Zeitzonen-Regeln: UTC-Offset (Typ `1`), Zeitzonen-Abkürzung (Typ `2`), und Zeitzonen-Kennungen wie in der IANA-Zeitzonendatenbank angegeben (Typ `3`).

Das DateTimeZone-Objekt kann an DateTime- und DateTimeImmutable-Objekte angehängt werden, um die Zeitzone, die in diesen Objekten enthalten ist, in einer lokalen Zeitzone wiederzugeben.

### Parameter-Liste

`timezone`

  Eine der unterstützten Zeitzonen-Kennungen, ein Offset-Wert (+0200) oder eine Zeitzonen-Abkürzung (BST).

### Rückgabewerte

Gibt bei Erfolg ein DateTimeZone-Objekt zurück. Prozeduraler Stil Im Fehlerfall wird `false` zurückgegeben.

### Fehler/Exceptions

Wenn die angegebene Zeitzone als nicht korrekt eingestuft wird, wirft diese Methode eine DateInvalidTimeZoneException. Vor PHP 8.3 wird stattdessen eine Exception geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Ungültige Werte geben nun eine DateInvalidTimeZoneException statt einer allgemeinen Exception zurück.

### Beispiele

Beispiel #1 Erstellen und Anhängen von DateTimeZone an ein DateTimeImmutable

    <?php
    $d = new DateTimeImmutable("2022-06-02 15:44:48 UTC");

    $timezones = [ 'Europe/London', 'GMT+04:45', '-06:00', 'CEST' ];

    foreach ($timezones as $tz) {
        $tzo = new DateTimeZone($tz);

        $local = $d->setTimezone($tzo);
        echo $local->format(DateTimeInterface::RFC2822 . ' — e') . "\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Thu, 02 Jun 2022 16:44:48 +0100 — Europe/London
    Thu, 02 Jun 2022 20:29:48 +0445 — +04:45
    Thu, 02 Jun 2022 09:44:48 -0600 — -06:00
    Thu, 02 Jun 2022 17:44:48 +0200 — CEST

Beispiel #2 Fehler beim Initialisieren von DateTimeZone abfangen

    <?php
    // Fehlerbehandlung durch Abfangen von Exceptions
    $timezones = array('Europe/London', 'Mars/Phobos', 'Jupiter/Europa');

    foreach ($timezones as $tz) {
        try {
            $mars = new DateTimeZone($tz);
            echo $mars->getName() . "\n";
        } catch(Exception $e) {
            echo $e->getMessage() . "\n";
        }
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Europe/London
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Mars/Phobos)
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Jupiter/Europa)

# DateTimeZone::getLocation

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeZone::getLocation -- timezone_location_get — Liefert Standortinformationen zu einer Zeitzone

### Beschreibung

Objektorientierter Stil

public function DateTimeZone::getLocation(): array|false

Prozeduraler Stil

function timezone_location_get(DateTimeZone `$object`): array|false

Gibt Standortinformationen zu einer Zeitzone zurück, einschließlich Ländercode, Breitengrad/Längengrad und Anmerkungen.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTimeZone-Objekt.

### Rückgabewerte

Array mit Ortsangaben zur Zeitzone. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 DateTimeZone::getLocation()-Beispiel

    <?php
    $tz = new DateTimeZone("Europe/Prague");
    print_r($tz->getLocation());
    print_r(timezone_location_get($tz));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [country_code] => CZ
        [latitude] => 50.08333
        [longitude] => 14.43333
        [comments] =>
    )
    Array
    (
        [country_code] => CZ
        [latitude] => 50.08333
        [longitude] => 14.43333
        [comments] =>
    )

### Siehe auch

- DateTimeZone::listIdentifiers() - Liefert ein numerisch indiziertes Array, das alle definierten Bezeichner der Zeitzonen enthält, um eine vollständige oder teilweise Liste aller unterstützten Zeitzonenbezeichner zu erhalten

# DateTimeZone::getName

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getName -- timezone_name_get — Liefert den Namen einer Zeitzone

### Beschreibung

Objektorientierter Stil

public function DateTimeZone::getName(): string

Prozeduraler Stil

function timezone_name_get(DateTimeZone `$object`): string

Gibt den Namen einer Zeitzone zurück.

### Parameter-Liste

`object`

  Die DateTimeZone, deren Name ermittelt werden soll.

### Rückgabewerte

Je nach Typ der Zeitzone werden unterschiedliche Werte zurückgegeben: die Zeitverschiebung gegenüber UTC (für Typ 1), das Zeitzonenkürzel (für Typ 2) oder die in der IANA-Zeitzonendatenbank registrierte Zeitzonenkennung (für Typ 3). Dies sind Zeichenketten, um ein DateTimeZone-Objekt mit derselben Zeitverschiebung und/oder denselben Regeln zu erstellen. Zum Beispiel `02:00`, `CEST` oder einer der Namen der Zeitzonen aus der Liste der Zeitzonen.

# DateTimeZone::getOffset

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getOffset -- timezone_offset_get — Liefert die Zeitverschiebung gegenüber der GMT

### Beschreibung

Objektorientierter Stil

public function DateTimeZone::getOffset(DateTimeInterface `$datetime`): int

Prozeduraler Stil

function timezone_offset_get(DateTimeZone `$object`, DateTimeInterface `$datetime`): int

Diese Funktion gibt für das im Parameter `datetime` angegebene Datum und die Uhrzeit die Zeitverschiebung gegenüber der GMT zurück. Die Abweichung von der GMT wird mit den Zeitzoneninformationen berechnet, die im verwendeten DateTimeZone-Objekt enthalten sind.

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTimeZone-Objekt.

`datetime`

  Das DateTime-Objekt, das das Datum und die Uhrzeit enthält, von dem/der aus die Zeitverschiebung berechnet werden soll.

### Rückgabewerte

Gibt die Zeitverschiebung in Sekunden zurück.

### Beispiele

Beispiel #1 DateTimeZone::getOffset()-Beispiele

    <?php
    // Erstellen zweier Zeitzonenobjekte, eines für Taipeh (Taiwan) und eines für
    // Tokio (Japan)
    $dateTimeZoneTaipei = new DateTimeZone("Asia/Taipei");
    $dateTimeZoneJapan = new DateTimeZone("Asia/Tokyo");

    // Erstellen zweier DateTime-Objekte, die denselben Unix-Zeitstempel enthalten,
    // aber unterschiedliche Zeitzonen zugewiesen bekommen.
    $dateTimeTaipei = new DateTime("now", $dateTimeZoneTaipei);
    $dateTimeJapan = new DateTime("now", $dateTimeZoneJapan);

    // Berechnen der Abweichung des im Objekt $dateTimeTaipei enthaltenen
    // Datums und der Uhrzeit von der GMT, wobei allerdings die für Tokio
    // ($dateTimeZoneJapan) festgelegten Zeitzonenregeln verwendet werden.
    $timeOffset = $dateTimeZoneJapan->getOffset($dateTimeTaipei);

    // Sollte int(32400) anzeigen (für Daten nach
    // Samstag, 8. September 01:00:00 1951 JST).
    var_dump($timeOffset);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(32400)

# DateTimeZone::getTransitions

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getTransitions -- timezone_transitions_get — Liefert alle Übergänge einer Zeitzone

### Beschreibung

Objektorientierter Stil

public function DateTimeZone::getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = `PHP_INT_MAX`): array|false

Prozeduraler Stil

function timezone_transitions_get(DateTimeZone `$object`, int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = `PHP_INT_MAX`): array|false

### Parameter-Liste

`object`

  Nur bei prozeduralem Aufruf: Ein von date_create() zurückgegebenes DateTimeZone-Objekt.

`timestampBegin`

  Der Zeitstempel des Beginns

`timestampEnd`

  Der Zeitstempel des Endes

### Rückgabewerte

Gibt bei Erfolg ein numerisch indiziertes Array von Übergangs-Arrays zurück. Bei einem Fehler wird `false` zurückgegeben. DateTimeZone-Objekte des Typs 1 (UTC-Offsets) und des Typs 2 (Abkürzungen) enthalten keine Übergänge und der Aufruf dieser Methode für sie gibt `false` zurück.

Wenn `timestampBegin` angegeben wird, enthält der erste Eintrag im zurückgegebenen Array Informationen über den Übergang zum Zeitpunkt `timestampBegin`.

Array-Struktur der Übergänge
Schlüssel | Typ | Beschreibung
--- | --- | ---
`ts` | int | Unix-Zeitstempel
`time` | string | Zeichenkette im Format `DateTimeInterface::ISO8601_EXPANDED` (ab PHP 8.2) oder `DateTimeInterface::ISO8601` (bis einschließlich PHP 8.1)
`offset` | int | Abweichung von der UTC in Sekunden
`isdst` | bool | Gibt an, ob es eine Sommerzeit gibt
`abbr` | string | Kurzbezeichnung der Zeitzone

### Beispiele

Beispiel #1 timezone_transitions_get()-Beispiel

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions();
    print_r(array_slice($transitions, 0, 3));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [ts] => -2147483648
                [time] => 1901-12-13T20:45:52+00:00
                [offset] => -75
                [isdst] =>
                [abbr] => LMT
            )

        [1] => Array
            (
                [ts] => 442304971
                [time] => 1847-12-01T00:01:15+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => -1691964000
                [time] => 1916-05-21T02:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

Beispiel #2 timezone_transitions_get()-Beispiel mit gesetztem `timestampBegin`

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions(time());
    print_r(array_slice($transitions, 0, 3));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [ts] => 1759058251
                [time] => 2025-09-28T11:17:31+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

        [1] => Array
            (
                [ts] => 1761440400
                [time] => 2025-10-26T01:00:00+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => 1774746000
                [time] => 2026-03-29T01:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

# DateTimeZone::listAbbreviations

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listAbbreviations -- timezone_abbreviations_list — Liefert ein assoziatives Array mit dst, offset und dem Namen der Zeitzone

### Beschreibung

Objektorientierter Stil

public static function DateTimeZone::listAbbreviations(): array

Prozeduraler Stil

function timezone_abbreviations_list(): array

Die zurückgegebene Liste der Abkürzungen enthält alle historischen Verwendungen von Abkürzungen, was zu korrekten, aber verwirrenden Einträgen führen kann. Außerdem gibt es Überschneidungen, da `PST` sowohl in den USA als auch auf den Philippinen verwendet wird.

Die Liste, die diese Funktion zurückgibt, ist daher nicht geeignet, ein Array mit Optionen zu erstellen, um den Benutzern eine Auswahl an Zeitzonen anzubieten.

> Hinweis:

> Die Daten für diese Funktion sind aus Gründen der Performance vorkompiliert und werden bei Verwendung einer neueren » timezonedb nicht aktualisiert.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array von Zeitzonenkürzeln zurück.

### Beispiele

Beispiel #1 timezone_abbreviations_list()-Beispiel

    <?php
    $timezone_abbreviations = DateTimeZone::listAbbreviations();
    print_r($timezone_abbreviations["acst"]);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Adelaide
            )

        [1] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Broken_Hill
            )

        [2] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Darwin
            )

        [3] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/North
            )

        [4] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/South
            )

        [5] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Yancowinna
            )

    )

### Siehe auch

- timezone_identifiers_list() - Alias von DateTimeZone::listIdentifiers

# DateTimeZone::listIdentifiers

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — Liefert ein numerisch indiziertes Array, das alle definierten Bezeichner der Zeitzonen enthält

### Beschreibung

Objektorientierter Stil

public static function DateTimeZone::listIdentifiers(int `$timezoneGroup` = DateTimeZone::ALL, ?string `$countryCode` = `null`): array

Prozeduraler Stil

function timezone_identifiers_list(int `$timezoneGroup` = DateTimeZone::ALL, ?string `$countryCode` = `null`): array

### Parameter-Liste

`timezoneGroup`

  Eine der DateTimeZone-Klassenkonstanten (oder eine Kombination).

`countryCode`

  Ein Ländercode aus zwei Großbuchstaben, der mit ISO 3166-1 kompatibel ist.

  > Hinweis: Diese Option wird nur verwendet, wenn `timezoneGroup` auf `DateTimeZone::PER_COUNTRY` gesetzt ist.

### Rückgabewerte

Gibt ein Array von Zeitzonenbezeichnern zurück. Es werden nur nicht veraltete Elemente zurückgegeben. Um alle, auch veraltete Zeitzonenbezeichner zu erhalten, muss `DateTimeZone::ALL_WITH_BC` als Wert für `timezoneGroup` verwendet werden.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Vor dieser Version wurde bei einem Fehler `false` zurückgegeben.
7.1.0 | `countryCode` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 DateTimeZone::listIdentifiers()-Beispiel

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers();
    for ($i=0; $i < 5; $i++) {
        echo "$timezone_identifiers[$i]\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Africa/Abidjan
    Africa/Accra
    Africa/Addis_Ababa
    Africa/Algiers
    Africa/Asmara

Beispiel #2 Auflisten der Bezeichner für eine bestimmte Region

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA );
    for ($i=0; $i < 5; $i++) {
        echo "$timezone_identifiers[$i]\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Asia/Aden
    Asia/Almaty
    Asia/Amman
    Asia/Anadyr
    Asia/Aqtau

Beispiel #3 Auflisten der Bezeichner für mehrere Regionen

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA | DateTimeZone::PACIFIC );
    echo join( ', ', $timezone_identifiers );
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Asia/Aden, Asia/Almaty, Asia/Amman, Asia/Anadyr, Asia/Aqtau, Asia/Aqtobe,
    Asia/Ashgabat, Asia/Atyrau, Asia/Baghdad, Asia/Bahrain, Asia/Baku,
    Asia/Bangkok, Asia/Barnaul, Asia/Beirut, Asia/Bishkek, Asia/Brunei,
    Asia/Chita, Asia/Choibalsan, Asia/Colombo, Asia/Damascus, Asia/Dhaka,
    Asia/Dili, Asia/Dubai, Asia/Dushanbe, Asia/Famagusta, Asia/Gaza, Asia/Hebron,
    Asia/Ho_Chi_Minh, Asia/Hong_Kong, Asia/Hovd, Asia/Irkutsk, Asia/Jakarta,
    Asia/Jayapura, Asia/Jerusalem, Asia/Kabul, Asia/Kamchatka, Asia/Karachi,
    Asia/Kathmandu, Asia/Khandyga, Asia/Kolkata, Asia/Krasnoyarsk,
    Asia/Kuala_Lumpur, Asia/Kuching, Asia/Kuwait, Asia/Macau, Asia/Magadan,
    Asia/Makassar, Asia/Manila, Asia/Muscat, Asia/Nicosia, Asia/Novokuznetsk,
    Asia/Novosibirsk, Asia/Omsk, Asia/Oral, Asia/Phnom_Penh, Asia/Pontianak,
    Asia/Pyongyang, Asia/Qatar, Asia/Qostanay, Asia/Qyzylorda, Asia/Riyadh,
    Asia/Sakhalin, Asia/Samarkand, Asia/Seoul, Asia/Shanghai, Asia/Singapore,
    Asia/Srednekolymsk, Asia/Taipei, Asia/Tashkent, Asia/Tbilisi, Asia/Tehran,
    Asia/Thimphu, Asia/Tokyo, Asia/Tomsk, Asia/Ulaanbaatar, Asia/Urumqi,
    Asia/Ust-Nera, Asia/Vientiane, Asia/Vladivostok, Asia/Yakutsk, Asia/Yangon,
    Asia/Yekaterinburg, Asia/Yerevan, Pacific/Apia, Pacific/Auckland,
    Pacific/Bougainville, Pacific/Chatham, Pacific/Chuuk, Pacific/Easter,
    Pacific/Efate, Pacific/Fakaofo, Pacific/Fiji, Pacific/Funafuti,
    Pacific/Galapagos, Pacific/Gambier, Pacific/Guadalcanal, Pacific/Guam,
    Pacific/Honolulu, Pacific/Kanton, Pacific/Kiritimati, Pacific/Kosrae,
    Pacific/Kwajalein, Pacific/Majuro, Pacific/Marquesas, Pacific/Midway,
    Pacific/Nauru, Pacific/Niue, Pacific/Norfolk, Pacific/Noumea,
    Pacific/Pago_Pago, Pacific/Palau, Pacific/Pitcairn, Pacific/Pohnpei,
    Pacific/Port_Moresby, Pacific/Rarotonga, Pacific/Saipan, Pacific/Tahiti,
    Pacific/Tarawa, Pacific/Tongatapu, Pacific/Wake, Pacific/Wallis

Beispiel #4 Auflisten der Bezeichner für ein einzelnes Land

    <?php
    $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::PER_COUNTRY, "UA" );
    foreach( $timezone_identifiers as $identifier ) {
        echo "$identifier\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Europe/Kyiv
    Europe/Simferopol
    Europe/Uzhgorod
    Europe/Zaporozhye

### Siehe auch

- timezone_abbreviations_list() - Alias von DateTimeZone::listAbbreviations

## Inhaltsverzeichnis

- DateTimeZone::__construct — Erstellt neues DateTimeZone-Objekt
- DateTimeZone::getLocation — Liefert Standortinformationen zu einer Zeitzone
- DateTimeZone::getName — Liefert den Namen einer Zeitzone
- DateTimeZone::getOffset — Liefert die Zeitverschiebung gegenüber der GMT
- DateTimeZone::getTransitions — Liefert alle Übergänge einer Zeitzone
- DateTimeZone::listAbbreviations — Liefert ein assoziatives Array mit dst, offset und dem Namen der Zeitzone
- DateTimeZone::listIdentifiers — Liefert ein numerisch indiziertes Array, das alle definierten Bezeichner der Zeitzonen enthält

# Die Klasse DateInterval

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Einführung

Repräsentiert eine Zeitspanne.

Eine Zeitspanne wird entweder als feste Zeitspanne (in Jahren, Monaten, Tagen, Stunden etc.) oder als relative Zeitangabe in einem Format dargestellt, das vom Konstruktor der Klassen DateTimeImmutable und DateTime unterstützt wird.

Genauer gesagt ist die Information in einem Objekt der Klasse DateInterval eine Anweisung, um von einem Datum/Zeit-Wert zu einem anderen Datum/Zeit-Wert zu kommen. Dieser Prozess ist nicht immer umkehrbar.

Eine übliche Methode, um ein DateInterval-Objekt zu erzeugen, ist die Berechnung des Unterschieds zwischen zwei Datum/Zeit-Objekten durch DateTimeInterface::diff().

Da es keine eindeutig definierte Möglichkeit gibt, Zeitspannen zu vergleichen, sind DateInterval-Instanzen nicht vergleichbar.

## Klassenbeschreibung

class DateInterval {
/* Eigenschaften */
public int $y;
public int $m;
public int $d;
public int $h;
public int $i;
public int $s;
public float $f;
public int $invert;
public mixed $days;
public bool $from_string;
public string $date_string;
/* Methoden */
public function __construct(string `$duration`)
public static function createFromDateString(string `$datetime`): DateInterval
public function format(string `$format`): string
}

## Eigenschaften

Warnung

Die unten aufgeführten verfügbaren Eigenschaften hängen von der PHP-Version ab und sollten als nur lesbar eingestuft werden.

y

  Anzahl der Jahre.

m

  Anzahl der Monate.

d

  Anzahl der Tage.

h

  Anzahl der Stunden.

i

  Anzahl der Minuten.

s

  Anzahl der Sekunden.

f

  Anzahl der Mikrosekunden als Bruchteil einer Sekunde.

invert

  Ist `1`, wenn die Zeitspanne negativ ist, und sonst `0`. Siehe DateInterval::format().

days

  Wenn das DateInterval-Objekt durch DateTimeImmutable::diff() oder DateTime::diff() erstellt wurde, dann enthält diese Eigenschaft die Gesamtanzahl der vollen Tage zwischen dem Start- und Enddatum. Ansonsten enthält days den Wert `false`.

from_string

  Wenn das DateInterval-Objekt durch DateInterval::createFromDateString() erstellt wurde, dann ist der Wert dieser Eigenschaft `true` und die Eigenschaft date_string wird mit Daten belegt. Andernfalls ist der Wert `false` und die Eigenschaften y bis f, invert, und Tage werden mit Daten belegt.

date_string

  Die Zeichenkette, die als Parameter für DateInterval::createFromDateString() verwendet wird.

## Changelog

Version | Beschreibung
--- | ---
8.2.0 | Die Eigenschaften from_string und date_string wurden für DateInterval-Instanzen hinzugefügt, die mit der Methode DateInterval::createFromDateString() erstellt wurden.
8.2.0 | Nur die Eigenschaften `y` bis `f`, `invert` und `days` sind sichtbar.
7.4.0 | DateInterval-Instanzen sind nun nicht mehr vergleichbar; bisher wurden alle DateInterval-Instanzen als gleich angesehen.
7.1.0 | Die Eigenschaft f wurde hinzugefügt.

# DateInterval::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::__construct — Erstellt ein neues DateInterval-Objekt

### Beschreibung

public function DateInterval::__construct(string `$duration`)

Erstellt ein neues DateInterval-Objekt.

### Parameter-Liste

`duration`

  Eine Intervall-Spezifikation

  Das Format beginnt mit dem Buchstaben `P` für period. Jede Periodendauer wird als Integer-Wert, gefolgt von einem Perioden-Bezeichner, repräsentiert. Enthält die Dauer Zeitelemente, wird diesem Teil der Spezifikation der Buchstabe `T` vorangestellt.

  Perioden-Bezeichner für `duration`
  Perioden-Bezeichner | Beschreibung
  --- | ---
  `Y` | Jahre
  `M` | Monate
  `D` | Tage
  `W` | Wochen. Diese werden in Tage umgerechnet. Vor PHP 8.0.0 konnte es nicht mit `D` kombiniert werden.
  `H` | Stunden
  `M` | Minuten
  `S` | Sekunden

  Hier sind ein paar einfache Beispiele: Zwei Tage entsprechen `P2D`. Zwei Sekunden entsprechen `PT2S`. Sechs Jahre und fünf Minuten entsprechen `P6YT5M`.

  > Hinweis:

  > Die Einheitstypen müssen von der größten Einheit links bis zur kleinsten Einheit rechts angegeben werden. Also Jahre vor Monaten, Monate vor Tagen, Tage vor Minuten etc. Also muss ein Jahr und vier Tage als `P1Y4D` dargestellt werden, nicht als `P4D1Y`.

  Die Spezifikation kann aber auch als Zeitstempel angegeben werden. Ein Beispiel für ein Jahr und vier Tage wäre also `P0001-00-04T00:00:00`. Die Werte in diesem Format können allerdings den jeweiligen Übersprungspunkt der Periode nicht überschreiten (z. B. ist `25` Stunden ungültig).

  Diese Formate basieren auf der » ISO 8601-Spezifikation für die Dauer.

### Fehler/Exceptions

Wenn `duration` nicht als Intervall geparst werden kann, wird eine DateMalformedIntervalStringException geworfen. Vor PHP 8.3 wird eine Exception geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wirft nun eine DateMalformedIntervalStringException anstelle von Exception.
8.2.0 | Nur die Eigenschaften `y` bis `f`, `invert` und `days` sowie die neue boolesche Eigenschaft `from_string` sind sichtbar.
8.0.0 | `W` kann mit `D` kombiniert werden.

### Beispiele

Beispiel #1 Erstellen und Verwenden von DateInterval-Objekten

    <?php
    // Ein konkretes Datum erstellen
    $someDate = \DateTime::createFromFormat("Y-m-d H:i", "2022-08-25 14:18");

    // Ein Intervall erstellen
    $interval = new \DateInterval("P7D");

    // Das Intervall hinzufügen
    $someDate->add($interval);

    // Das Intervall in eine Zeichenkette umwandeln
    echo $interval->format("%d");

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    7

Beispiel #2 DateInterval-Beispiel

    <?php
    $interval = new DateInterval('P1W2D');
    var_dump($interval);

Das oben gezeigte Beispiel erzeugt mit PHP 8.2 folgende Ausgabe:

    object(DateInterval)#1 (10) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["from_string"]=>
      bool(false)
    }

Das oben gezeigte Beispiel erzeugt mit PHP 8 folgende Ausgabe:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(9)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

Das oben gezeigte Beispiel erzeugt mit PHP 7 folgende Ausgabe:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(2)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }

### Siehe auch

- DateInterval::format() - Formatiert ein Intervall
- DateTime::add() - Ändert ein DateTime-Objekt, wobei die Anzahl der Tage, Monate, Jahre, Stunden, Minuten und Sekunden hinzugefügt wird
- DateTime::sub() - Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden von einem DateTime-Objekt.
- DateTime::diff() - Liefert die Differenz zwischen zwei DateTime-Objekten

# DateInterval::createFromDateString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::createFromDateString — Bildet ein DateInterval aus relativen Teilen eines Strings

### Beschreibung

Objektorientierter Stil

public static function DateInterval::createFromDateString(string `$datetime`): DateInterval

Prozeduraler Stil

function date_interval_create_from_date_string(string `$datetime`): DateInterval|false

Verwendet die Datum/Zeit-Parser, wie sie im Konstruktor von DateTimeImmutable verwendet werden, um aus den relativen Teilen der ausgewerteten Zeichenkette ein DateInterval zu erstellen.

### Parameter-Liste

`datetime`

  Eine Datum mit relativen Teilen. Genauer gesagt, werden die relativen Formate zur Konstruktion des DateInterval verwendet, die von dem für DateTimeImmutable, DateTime und strtotime() verwendeten Parser unterstützt werden.

  Um eine Zeichenkette im ISO-8601-Format zu verwenden, z. B. `P7D`, muss der Konstruktor DateInterval::__construct()verwendet werden.

### Rückgabewerte

Gibt bei Erfolg eine Instanz von DateInterval zurück. Prozeduraler Stil Im Fehlerfall wird `false` zurückgegeben.

### Fehler/Exceptions

Nur bei objektorientierter API: Wenn eine ungültige Datum/Uhrzeit-Zeichenkette übergeben wird, wird eine DateMalformedIntervalStringException ausgelöst.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | DateInterval::createFromDateString() löst nun eine DateMalformedIntervalStringException aus, wenn eine ungültige Zeichenkette übergeben wird. Zuvor wurde `false` zurückgegeben, und eine Warnung wurde ausgegeben. Die Funktion date_interval_create_from_date_string() wurde nicht geändert.
8.2.0 | Wenn ein DateInterval mit dieser Methode erstellt wird, sind nur die Eigenschaften `from_string` und `date_string` sichtbar.

### Beispiele

Beispiel #1 Parsen gültiger Datums-Intervalle

    <?php
    // Jede Gruppe von Intervallen ist gleich.
    $i = new DateInterval('P1D');
    $i = DateInterval::createFromDateString('1 day');

    $i = new DateInterval('P2W');
    $i = DateInterval::createFromDateString('2 weeks');

    $i = new DateInterval('P3M');
    $i = DateInterval::createFromDateString('3 months');

    $i = new DateInterval('P4Y');
    $i = DateInterval::createFromDateString('4 years');

    $i = new DateInterval('P1Y1D');
    $i = DateInterval::createFromDateString('1 year + 1 day');

    $i = new DateInterval('P1DT12H');
    $i = DateInterval::createFromDateString('1 day + 12 hours');

    $i = new DateInterval('PT3600S');
    $i = DateInterval::createFromDateString('3600 seconds');

Beispiel #2 Parsen von Kombinationen und negativen Intervallen

    <?php
    $i = DateInterval::createFromDateString('62 weeks + 1 day + 2 weeks + 2 hours + 70 minutes');
    echo $i->format('%d %h %i'), "\n";

    $i = DateInterval::createFromDateString('1 year - 10 days');
    echo $i->format('%y %d'), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    449 2 70
    1 -10

Beispiel #3 Parsen spezieller relativer Datums-Intervalle

    <?php
    $i = DateInterval::createFromDateString('last day of next month');
    var_dump($i);

    $i = DateInterval::createFromDateString('last weekday');
    var_dump($i);

Das oben gezeigte Beispiel erzeugt mit PHP 8.2 folgende Ausgabe:

    object(DateInterval)#1 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(22) "last day of next month"
    }
    object(DateInterval)#2 (2) {
      ["from_string"]=>
      bool(true)
      ["date_string"]=>
      string(12) "last weekday"
    }

Das oben gezeigte Beispiel erzeugt mit PHP 8 eine ähnliche Ausgabe wie:

    object(DateInterval)#1 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(1)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(2)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(0)
      ["special_amount"]=>
      int(0)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(0)
    }
    object(DateInterval)#2 (16) {
      ["y"]=>
      int(0)
      ["m"]=>
      int(0)
      ["d"]=>
      int(0)
      ["h"]=>
      int(0)
      ["i"]=>
      int(0)
      ["s"]=>
      int(0)
      ["f"]=>
      float(0)
      ["weekday"]=>
      int(0)
      ["weekday_behavior"]=>
      int(0)
      ["first_last_day_of"]=>
      int(0)
      ["invert"]=>
      int(0)
      ["days"]=>
      bool(false)
      ["special_type"]=>
      int(1)
      ["special_amount"]=>
      int(-1)
      ["have_weekday_relative"]=>
      int(0)
      ["have_special_relative"]=>
      int(1)
    }

# DateInterval::format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::format — Formatiert ein Intervall

### Beschreibung

public function DateInterval::format(string `$format`): string

Formatiert ein Intervall.

### Parameter-Liste

`format`

  Die folgenden Zeichen werden in der Zeichenkette des Parameters `format` erkannt. Jedem Formatzeichen muss ein Prozentzeichen (`%`) vorangestellt werden.
  `format`-Zeichen | Beschreibung | Beispielwerte
  --- | --- | ---
  `%` | `%`-Zeichen | `%`
  `Y` | Jahre, numerisch, mindestens 2 Ziffern mit vorangestellter 0 | `01`, `03`
  `y` | Jahre, numerisch | `1`, `3`
  `M` | Monate, numerisch, mindestens 2 Ziffern mit vorangestellter 0 | `01`, `03`, `12`
  `m` | Monate, numerisch | `1`, `3`, `12`
  `D` | Tage, numerisch, mindestens 2 Ziffern mit vorangestellter 0 | `01`, `03`, `31`
  `d` | Tage, numerisch | `1`, `3`, `31`
  `a` | Gesamtzahl der Tage als Ergebnis von DateTime::diff(), andernfalls `(unknown)` | `4`, `18`, `8123`
  `H` | Stunden, numerisch, mindestens 2 Ziffern mit vorangestellter 0 | `01`, `03`, `23`
  `h` | Stunden, numerisch | `1`, `3`, `23`
  `I` | Minuten, numerisch, mindestens 2 Ziffern mit vorangestellter 0 | `01`, `03`, `59`
  `i` | Minuten, numerisch | `1`, `3`, `59`
  `S` | Sekunden, numerisch, mindestens 2 Ziffern mit vorangestellter 0 | `01`, `03`, `57`
  `s` | Sekunden, numerisch | `1`, `3`, `57`
  `F` | Mikrosekunden, numerisch, mindestens 6 Ziffern mit vorangestellter 0 | `007701`, `052738`, `428291`
  `f` | Mikrosekunden, numerisch | `7701`, `52738`, `428291`
  `R` | Vorzeichen "`-`" wenn negativ, "`+`" wenn positiv | `-`, `+`
  `r` | Vorzeichen "`-`" wenn negativ, leer wenn positiv | `-`, ``

### Rückgabewerte

Gibt ein formatiertes Intervall zurück.

### Changelog

Version | Beschreibung
--- | ---
7.2.12 | Die Formate `F` und `f` sind nun immer positiv.
7.1.0 | Die Formatzeichen `F` und `f` wurden hinzugefügt.

### Beispiele

Beispiel #1 DateInterval-Beispiel

    <?php
    $interval = new DateInterval('P2Y4DT6H8M');
    echo $interval->format('%d Tage');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    4 Tage

Beispiel #2 DateInterval und Überträge

    <?php
    $interval = new DateInterval('P32D');
    echo $interval->format('%d Tage');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    32 Tage

Beispiel #3 DateInterval und DateTime::diff() mit den Modifikatoren %a und %d

    <?php
    $january = new DateTime('2010-01-01');
    $february = new DateTime('2010-02-01');
    $interval = $february->diff($january);

    // %a gibt die Gesamtzahl der Tage aus.
    echo $interval->format('%a Tage insgesamt')."\n";

    // Während %d nur die Anzahl der Tage ausgibt, die noch nicht durch den
    // Monat abgedeckt sind.
    echo $interval->format('%m Monat, %d Tage)');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    31 Tage insgesamt
    1 Monat, 0 Tage

### Anmerkungen

> Hinweis:

> Die Methode DateInterval::format() berechnet die Zeiteinheiten nicht neu und überträgt sie nicht, wenn die Datumswerte überlaufen. Dies ist beabsichtigt, weil es nicht möglich ist, Werte wie `"32 days"` zu übertragen, die als alles von `"1 month and 4 days"` bis `"1 month and 1 day"` interpretiert werden könnten.

### Siehe auch

- DateTime::diff() - Liefert die Differenz zwischen zwei DateTime-Objekten

## Inhaltsverzeichnis

- DateInterval::__construct — Erstellt ein neues DateInterval-Objekt
- DateInterval::createFromDateString — Bildet ein DateInterval aus relativen Teilen eines Strings
- DateInterval::format — Formatiert ein Intervall

# Die Klasse DatePeriod

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Einführung

Stellt einen Datumsbereich dar.

Ein Datumsbereich ermöglicht die Iteration über eine Reihe von Datumsangaben und Uhrzeiten, die sich im angegebenen Zeitraum in regelmäßigen Intervallen wiederholen.

## Klassenbeschreibung

class DatePeriod implements IteratorAggregate {
/* Konstanten */
public const int EXCLUDE_START_DATE;
public const int INCLUDE_END_DATE;
/* Eigenschaften */
public readonly ?DateTimeInterface $start;
public readonly ?DateTimeInterface $current;
public readonly ?DateTimeInterface $end;
public readonly ?DateInterval $interval;
public readonly int $recurrences;
public readonly bool $include_start_date;
public readonly bool $include_end_date;
/* Methoden */
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
public function __construct(string `$isostr`, int `$options` = 0)
public static function createFromISO8601String(string `$specification`, int `$options` = 0): static
public function getDateInterval(): DateInterval
public function getEndDate(): ?DateTimeInterface
public function getRecurrences(): ?int
public function getStartDate(): DateTimeInterface
}

## Vordefinierte Konstanten

`DatePeriod::EXCLUDE_START_DATE` int

  Anfangsdatum ausschließen; verwendet in DatePeriod::__construct().

`DatePeriod::INCLUDE_END_DATE` int

  Enddatum einschließen; verwendet in DatePeriod::__construct().

## Eigenschaften

recurrences

  Die minimale Anzahl von Instanzen, die vom Iterator zurückgegeben wird.

  Wenn im Konstruktor der DatePeriod-Instanz die Anzahl der Wiederholungen explizit über den Parameter recurrences übergeben wurde, dann enthält diese Eigenschaft diesen Wert, plus eins, wenn das Startdatum nicht mittels `DatePeriod::EXCLUDE_START_DATE` deaktiviert wurde, plus eins, wenn das Enddatum mittels `DatePeriod::INCLUDE_END_DATE` aktiviert wurde.

  Wenn die Anzahl der Wiederholungen nicht explizit übergeben wurde, dann enthält diese Eigenschaft die Mindestanzahl der zurückgegebenen Instanzen. Dies wäre `0`, plus eins, wenn das Startdatum nicht mittels `DatePeriod::EXCLUDE_START_DATE` deaktiviert wurde, plus eins, wenn das Enddatum mittels `DatePeriod::INCLUDE_END_DATE` aktiviert wurde.

      <?php
      $start = new DateTime('2018-12-31 00:00:00');
      $end   = new DateTime('2021-12-31 00:00:00');
      $interval = new DateInterval('P1M');
      $recurrences = 5;

      // Wiederholungen explizit im Konstruktor gesetzt
      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
      echo $period->recurrences, "\n";

      // Wiederholungen nicht im Konstruktor gesetzt
      $period = new DatePeriod($start, $interval, $end);
      echo $period->recurrences, "\n";

      $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
      echo $period->recurrences, "\n";

  Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

      5
      6
      7
      1
      0

  Siehe auch DatePeriod::getRecurrences().

include_end_date

  Legt fest, ob das Enddatum in der Menge der wiederkehrenden Termine enthalten sein soll oder nicht.

include_start_date

  Legt fest, ob das Anfangsdatum in der Menge der wiederkehrenden Termine enthalten sein soll, oder nicht.

start

  Das Anfangsdatum des Zeitraums.

current

  Während einer Iteration enthält diese Eigenschaft das aktuelle Datum innerhalb des Zeitraums.

end

  Das Enddatum des Zeitraums.

interval

  Eine ISO-8601-konforme Angabe eines sich wiederholenden Intervalls.

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Klassenkonstanten sind nun typisiert.
8.2.0 | Die Konstante `DatePeriod::INCLUDE_END_DATE` und die Eigenschaft include_end_date wurden hinzugefügt.
8.0.0 | DatePeriod implementiert nun IteratorAggregate. Zuvor wurde stattdessen Traversable implementiert.

# DatePeriod::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DatePeriod::__construct — Erstellt ein neues DatePeriod-Objekt

### Beschreibung

public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
Warnung

Die folgende Konstruktorvariante ist veraltet:

public function DatePeriod::__construct(string `$isostr`, int `$options` = 0)

Stattdessen sollte DatePeriod::createFromISO8601String() verwendet werden.

Erstellt ein neues DatePeriod-Objekt.

DatePeriod-Objekte können als Iterator verwendet werden, um aus einem `start`-Datum, einem `interval` und einem `end`-Datum oder der Anzahl der `recurrences` (Wiederholungen) eine Reihe von DateTimeImmutable- oder DateTime-Objekten zu erzeugen.

Die Klasse der zurückgegebenen Objekte entspricht der DateTimeImmutable- oder DateTime-Elternklasse des `start`-Objekts.

### Parameter-Liste

`start`

  Das Startdatum des Zeitraums; wird standardmäßig in die Ergebnismenge aufgenommen.

`interval`

  Das Intervall zwischen den Wiederholungen innerhalb des Zeitraums.

`recurrences`

  Die Anzahl der Wiederholungen. Die Anzahl der zurückgegebenen Ergebnisse ist um eins größer, da das Startdatum standardmäßig in die Ergebnismenge aufgenommen wird; muss größer als `0` sein.

`end`

  Das Enddatum des Zeitraums; wird standardmäßig nicht in die Ergebnismenge aufgenommen.

`isostr`

  Eine Teilmenge der » ISO-8601-Spezifikation für sich wiederholende Intervalle.

  Beispiele für Features der ISO-8601-Spezifikation für Intervalle, die von PHP nicht unterstützt werden, sind:

  1. null Vorkommen (`R0/`)
  2. andere Zeitabweichungen als UTC (`Z`), wie `+02:00`.
`options`

  Ein Bitfeld, mit dem ein bestimmtes Verhalten bezüglich der Start- und Enddaten gesteuert werden kann.

  Mit `DatePeriod::EXCLUDE_START_DATE` wird das Startdatum aus der Menge der wiederkehrenden Termine innerhalb des Zeitraums ausgeschlossen.

  Mit `DatePeriod::INCLUDE_END_DATE` wird das Enddatum in die Menge der wiederkehrenden Termine innerhalb des Zeitraums aufgenommen.

### Fehler/Exceptions

Wenn `isostr` nicht als gültiger ISO-8601-Zeitraum geparst werden kann, wird eine DateMalformedPeriodStringException geworfen. Vor PHP 8.3 wird eine Exception geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Wirft nun eine DateMalformedPeriodStringException anstelle von Exception.
8.2.0 | Die Konstante `DatePeriod::INCLUDE_END_DATE` wurde hinzugefügt.
7.2.19, 7.3.6, 7.4.0 | `recurrences` muss jetzt größer als `0` sein.

### Beispiele

Beispiel #1 DatePeriod-Beispiel

    <?php
    $start = new DateTime('2012-07-01');
    $interval = new DateInterval('P7D');
    $end = new DateTime('2012-07-31');
    $recurrences = 4;
    $iso = 'R4/2012-07-01T00:00:00Z/P7D';

    // Alle diese Zeiträume sind gleichwertig.
    $period = new DatePeriod($start, $interval, $recurrences);
    $period = new DatePeriod($start, $interval, $end);
    $period = new DatePeriod($iso);

    // Durch Iterieren über das DatePeriod-Objekt, werden alle sich
    // wiederholenden Termine innerhalb des Zeitraums ausgegeben.
    foreach ($period as $date) {
        echo $date->format('Y-m-d')."\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Deprecated: Calling DatePeriod::__construct(string $isostr, int $options = 0) is deprecated, use DatePeriod::createFromISO8601String() instead in script on line 11
    2012-07-01
    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Beispiel #2 DatePeriod-Beispiel mit `DatePeriod::EXCLUDE_START_DATE`

    <?php
    $start = new DateTime('2012-07-01');
    $interval = new DateInterval('P7D');
    $end = new DateTime('2012-07-31');

    $period = new DatePeriod($start, $interval, $end,
                             DatePeriod::EXCLUDE_START_DATE);

    // Durch Iterieren über das DatePeriod-Objekt werden alle sich
    // wiederholenden Termine innerhalb des Zeitraums ausgegeben.
    // Es ist zu beachten, dass in diesem Fall 2012-07-01 nicht ausgegeben wird.
    foreach ($period as $date) {
        echo $date->format('Y-m-d')."\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2012-07-08
    2012-07-15
    2012-07-22
    2012-07-29

Beispiel #3 Ein DatePeriod-Beispiel, das alle letzten Donnerstage eines Jahres anzeigt

    <?php
    $begin = new DateTime('2021-12-31');
    $end = new DateTime('2022-12-31 23:59:59');

    $interval = DateInterval::createFromDateString('last thursday of next month');
    $period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);

    foreach ($period as $dt) {
        echo $dt->format('l Y-m-d'), "\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Thursday 2022-01-27
    Thursday 2022-02-24
    Thursday 2022-03-31
    Thursday 2022-04-28
    Thursday 2022-05-26
    Thursday 2022-06-30
    Thursday 2022-07-28
    Thursday 2022-08-25
    Thursday 2022-09-29
    Thursday 2022-10-27
    Thursday 2022-11-24
    Thursday 2022-12-29

### Anmerkungen

Die unbegrenzte Anzahl von Wiederholungen, wie von ISO 8601, Abschnitt 4.5 "Recurring time interval" spezifiziert, wird nicht unterstützt, d. h. weder die Übergabe von `"R/..."` an `isostr` noch die Übergabe von `null` an `end` funktioniert.

# DatePeriod::createFromISO8601String

(PHP 8 >= 8.3.0)

DatePeriod::createFromISO8601String — Erstellt ein neues DatePeriod-Objekt aus einer ISO8601-Zeichenkette

### Beschreibung

public static function DatePeriod::createFromISO8601String(string `$specification`, int `$options` = 0): static

Erstellt ein neues DatePeriod-Objekt aus der mit `specification` angegebenen ISO8601-Zeichenkette.

### Parameter-Liste

`specification`

  Eine Teilmenge der » ISO-8601-Spezifikation für sich wiederholende Intervalle.

  Ein Beispiel für eine zulässige ISO 8601-Intervallangabe ist R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M und bedeutet:

  - 5 Wiederholungen (`R5/`)
  - Beginnend ab `2008-03-01T13:00:00Z`.
  - Jede Wiederholung ist ein Intervall von 1 Jahr, 2 Monaten, 10 Tagen, 2 Stunden und 30 Minuten (`/P1Y2M10DT2H30M`).

  Beispiele für Features der ISO-8601-Spezifikation für Intervalle, die von PHP nicht unterstützt werden, sind:

  1. null Vorkommen (`R0/`)
  2. andere Zeitabweichungen als UTC (`Z`), wie `+02:00`.
`options`

  Ein Bitfeld, mit dem ein bestimmtes Verhalten bezüglich der Start- und Enddaten gesteuert werden kann.

  Mit `DatePeriod::EXCLUDE_START_DATE` wird das Startdatum aus der Menge der wiederkehrenden Termine innerhalb des Zeitraums ausgeschlossen.

  Mit `DatePeriod::INCLUDE_END_DATE` wird das Enddatum in die Menge der wiederkehrenden Termine innerhalb des Zeitraums aufgenommen.

### Rückgabewerte

Erstellt ein neues DatePeriod-Objekt.

DatePeriod-Objekte können als Iterator verwendet werden, um eine Reihe von DateTimeImmutable-Objekten zu erzeugen.

### Fehler/Exceptions

Wenn `specification` nicht als gültiger ISO-8601-Zeitraum analysiert werden kann, wird eine DateMalformedPeriodStringException geworfen.

### Beispiele

Beispiel #1 DatePeriod::createFromISO8601String-Beispiel

    <?php
    $iso = 'R4/2023-07-01T00:00:00Z/P7D';
    $period = DatePeriod::createFromISO8601String($iso);

    // Durch Iterieren über das DatePeriod-Objekt werden alle sich
    // wiederholenden Termine innerhalb des Zeitraums ausgegeben.
    foreach ($period as $date) {
        echo $date->format('Y-m-d'), "\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2023-07-01
    2023-07-08
    2023-07-15
    2023-07-22
    2023-07-29

# DatePeriod::getDateInterval

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getDateInterval — Liefert ein Intervall

### Beschreibung

Objektorientierter Stil

public function DatePeriod::getDateInterval(): DateInterval

Gibt ein DateInterval-Objekt zurück, das das zur Erstellung des Zeitraums verwendete Intervall darstellt.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein DateInterval-Objekt zurück.

### Beispiele

Beispiel #1 DatePeriod::getDateInterval()-Beispiel

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $interval = $period->getDateInterval();
    echo $interval->format('%d Tag');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1 Tag

### Siehe auch

- DatePeriod::getStartDate() - Liefert das Startdatum
- DatePeriod::getEndDate() - Liefert das Enddatum

# DatePeriod::getEndDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getEndDate — Liefert das Enddatum

### Beschreibung

Objektorientierter Stil

public function DatePeriod::getEndDate(): ?DateTimeInterface

Ermittelt das Enddatum eines Zeitraums.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt `null` zurück, wenn das DatePeriod-Objekt kein Enddatum enthält. Zum Beispiel, wenn es mit dem Parameter `recurrences` oder dem Parameter `isostr` ohne Enddatum initialisiert wurde.

Wenn DatePeriod mit einem DateTimeImmutable-Objekt als Parameter `end` initialisiert wird, wird ein DateTimeImmutable-Objekt zurückgegeben.

Andernfalls wird ein geklontes DateTime-Objekt zurückgegeben, das das Enddatum darstellt.

### Beispiele

Beispiel #1 DatePeriod::getEndDate()-Beispiel

    <?php
    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        new DateTime('2016-05-20T00:00:00Z')
    );
    $start = $period->getEndDate();
    echo $start->format(DateTime::ISO8601);

Die obigen Bespiele erzeugen folgende Ausgabe:

    2016-05-20T00:00:00+0000

Beispiel #2 DatePeriod::getEndDate() ohne Enddatum

    <?php
    $period = new DatePeriod(
        new DateTime('2016-05-16T00:00:00Z'),
        new DateInterval('P1D'),
        7
    );
    var_dump($period->getEndDate());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL

### Siehe auch

- DatePeriod::getStartDate() - Liefert das Startdatum
- DatePeriod::getDateInterval() - Liefert ein Intervall

# DatePeriod::getRecurrences

(PHP 7 >= 7.2.17/7.3.4, PHP 8)

DatePeriod::getRecurrences — Liefert die Anzahl der Wiederholungen

### Beschreibung

Objektorientierter Stil

public function DatePeriod::getRecurrences(): ?int

Ermittelt die Anzahl der Wiederholungen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt die Anzahl der Wiederholungen zurück, wie sie explizit mittels `$recurrences` an den Konstruktor der Klasse DatePeriod übergeben wurde, oder `null` andernfalls.

### Beispiele

Beispiel #1 Unterschiedliche Werte bei DatePeriod::getRecurrences()

    <?php
    $start = new DateTime('2018-12-31 00:00:00');
    $end   = new DateTime('2021-12-31 00:00:00');
    $interval = new DateInterval('P1M');
    $recurrences = 5;

    // Wiederholungen explizit im Konstruktor gesetzt
    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences);
    echo $period->getRecurrences(), "\n";

    $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
    echo $period->getRecurrences(), "\n\n";

    // Wiederholungen nicht im Konstruktor gesetzt
    $period = new DatePeriod($start, $interval, $end);
    var_dump($period->getRecurrences());

    $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
    var_dump($period->getRecurrences());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    5
    5
    5

    NULL
    NULL

### Siehe auch

- DatePeriod::$recurrences

# DatePeriod::getStartDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getStartDate — Liefert das Startdatum

### Beschreibung

Objektorientierter Stil

public function DatePeriod::getStartDate(): DateTimeInterface

Ermittelt das Startdatum eines Zeitraums.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein DateTimeImmutable-Objekt zurück, wenn DatePeriod mit einem DateTimeImmutable-Objekt als Parameter `start` initialisiert wird.

Andernfalls wird ein DateTime-Objekt zurückgegeben.

### Beispiele

Beispiel #1 DatePeriod::getStartDate()-Beispiel

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $start = $period->getStartDate();
    echo $start->format(DateTime::ISO8601);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2016-05-16T00:00:00+0000

### Siehe auch

- DatePeriod::getEndDate() - Liefert das Enddatum
- DatePeriod::getDateInterval() - Liefert ein Intervall

## Inhaltsverzeichnis

- DatePeriod::__construct — Erstellt ein neues DatePeriod-Objekt
- DatePeriod::createFromISO8601String — Erstellt ein neues DatePeriod-Objekt aus einer ISO8601-Zeichenkette
- DatePeriod::getDateInterval — Liefert ein Intervall
- DatePeriod::getEndDate — Liefert das Enddatum
- DatePeriod::getRecurrences — Liefert die Anzahl der Wiederholungen
- DatePeriod::getStartDate — Liefert das Startdatum

# Datum/Uhrzeit-Funktionen

# checkdate

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdate — Prüft ein Gregorianisches Datum auf Gültigkeit

### Beschreibung

function checkdate(int `$month`, int `$day`, int `$year`): bool

Prüft die Gültigkeit des durch die Funktionsargumente beschriebenen Datums. Ein Datum wird als gültig betrachtet, wenn jeder Parameter korrekt definiert wurde.

### Parameter-Liste

`month`

  Die Monatsangabe umfasst Werte von 1 bis 12 (inklusive).

`day`

  Der Tag liegt innerhalb der für den angegebenen Monat `month` erlaubten Anzahl von Tagen. Schaltjahre werden entsprechend berücksichtigt.

`year`

  Die Jahresangabe ist eine Zahl zwischen 1 und 32767 (inklusive).

### Rückgabewerte

Gibt `true` zurück, wenn das übergebene Datum gültig ist, andernfalls `false`.

### Beispiele

Beispiel #1 checkdate()-Beispiel

    <?php
    var_dump(checkdate(12, 31, 2000));
    var_dump(checkdate(2, 29, 2001));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)

### Siehe auch

- mktime() - Liefert den Unix-Zeitstempel für ein Datum
- strtotime() - Wandelt eine textuelle englische Datums- und Zeitbeschreibung in einen Unix-Zeitstempel um

# date

(PHP 4, PHP 5, PHP 7, PHP 8)

date — Formatiert einen Unix-Zeitstempel

### Beschreibung

function date(string `$format`, ?int `$timestamp` = `null`): string

Gibt einen formatierten String anhand eines vorzugebenden Musters zurück. Dabei wird entweder der angegebene Unix-Zeitstempel `timestamp` verwendet oder die gegenwärtige Zeit, wenn kein Zeitstempel angegegeben wird. Mit anderen Worten ausgedrückt: Der Parameter `timestamp` ist optional und wird mit dem Wert der Funktion time() vorbelegt.

Warnung

Unix-Zeitstempel berücksichtigen keine Zeitzonen. Mit der Klasse DateTimeImmutable und ihrer Formatierungsmethode DateTimeInterface::format() können Datums- und Zeitangaben mit einer angehängten Zeitzone formatiert werden.

### Parameter-Liste

`format`

  Von DateTimeInterface::format() akzeptiertes Format.

  > Hinweis: Die Funktion date() gibt immer `000000` als Mikrosekunden aus, weil sie einen Parameter vom Typ int benötigt, während DateTimeInterface::format() Mikrosekunden unterstützt, wenn ein Objekt vom Typ DateTimeInterface mit Mikrosekunden erstellt wurde.

`timestamp`

  Der optionale Parameter `timestamp` ist ein Unix-Zeitstempel vom Typ int. Falls `timestamp` nicht übergeben wird oder `null` ist, wird die aktuelle lokale Zeit als Standardwert verwendet. Er entspricht dann also dem Ergebnis der Funktion time().

### Rückgabewerte

Gibt eine formatierte Datums-Zeichenkette zurück.

### Fehler/Exceptions

Wenn die Zeitzone ungültig ist, wird bei jedem Aufruf einer Datums/Zeit-Funktion ein Fehler der Stufe `E_WARNING` erzeugt. Siehe auch date_default_timezone_set()

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `timestamp` ist jetzt nullbar.

### Beispiele

Beispiel #1 date()-Beispiele

    <?php
    // Die Standard-Zeitzone setzen, die verwendet werden soll.
    date_default_timezone_set('UTC');

    // Gibt etwas aus wie: Monday
    echo date("l") . "\n";

    // Gibt etwas aus wie: Monday 8th of August 2005 03:12:46 PM
    echo date('l jS \of F Y h:i:s A') . "\n";

    // Gibt aus: July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    /* Verwenden von Konstanten im Format-Parameter */
    // Gibt etwas aus wie: Wed, 25 Sep 2013 15:28:57 -0700
    echo date(DATE_RFC2822) . "\n";

    // Gibt etwas aus wie: 2000-07-01T00:00:00+00:00
    echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));

Um zu verhindern, dass ein erkanntes Zeichen im Formatstring ersetzt wird, sollte dieses Zeichen mit einem vorangestellten Backslash maskiert werden. Ist das Zeichen mit dem Backslash bereits eine spezielle Zeichenfolge, muss dieser Backslash ebenso maskiert werden.

Beispiel #2 Maskieren von Zeichen in date()

    <?php
    // Gibt etwas ähnliches aus wie: Wednesday the 15th
    echo date('l \t\h\e jS');

Es folgen einige Beispiele zur date()-Formatierung. Es ist zu beachten, dass alle anderen Zeichen maskiert werden sollten, da alle Zeichen, die im Augenblick eine spezielle Bedeutung haben, unerwünschte Resultate liefern. Bei allen weiteren Zeichen kann es durchaus möglich sein, dass diesen in zukünftigen PHP-Versionen eine Bedeutung zukommt. Beim Maskieren sollte darauf geachtet werden, einfache Anführungszeichen zu benutzen, damit Zeichenfolgen wie zum Beispiel \n zu keinem Zeilenumbruch führen.

Beispiel #3 date()-Formatierungen

    <?php
    // Angenommen, heute ist der 10. März 2001, 17:16:18 Uhr und wir
    // befinden uns in der Zeitzone Mountain Standard Time (MST)

    echo date("F j, Y, g:i a") . "\n";                 // March 10, 2001, 5:16 pm
    echo date("m.d.y") . "\n";                         // 03.10.01
    echo date("j, n, Y") . "\n";                       // 10, 3, 2001
    echo date("Ymd") . "\n";                           // 20010310
    echo date('h-i-s, j-m-y, it is w Day') . "\n";     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
    echo date('\i\t \i\s \t\h\e jS \d\a\y.') . "\n";   // it is the 10th day.
    echo date("D M j G:i:s T Y") . "\n";               // Sat Mar 10 17:16:18 MST 2001
    echo date('H:m:s \m \i\s\ \m\o\n\t\h') . "\n";     // 17:03:18 m is month
    echo date("H:i:s") . "\n";                         // 17:16:18
    echo date("Y-m-d H:i:s") . "\n";                   // 2001-03-10 17:16:18 (the MySQL DATETIME format)

Um Datumsangaben in anderen Sprachen auszugeben, kann IntlDateFormatter::format() statt date() verwendet werden.

### Anmerkungen

> Hinweis:

> Um einen Zeitstempel aus einer Textrepräsentation eines Datums zu erzeugen, kann die Funktion strtotime() verwendet werden. Einige Datenbanken haben außerdem Funktionen, mit denen ihre Datumsformate in Zeitstempel konvertiert werden können (wie z. B. die Funktion » UNIX_TIMESTAMP von MySQL).

Tipp

Der Zeitstempel des Verarbeitungsbeginns der HTTP-Anfrage wird in $_SERVER['REQUEST_TIME'] bereitgestellt.

### Siehe auch

- DateTimeImmutable::__construct() - Liefert ein neues DateTimeImmutable-Objekt
- DateTimeInterface::format() - Liefert das Datum formatiert gemäß dem angegebenen Format
- gmdate() - Formatiert eine GMT/UTC Zeit-/Datumsangabe
- idate() - Formatiert einen Teil der lokalen Zeit/des lokalen Datums als Integer
- getdate() - Liefert Datums- und Zeitinformationen
- getlastmod() - Liefert die Uhrzeit der letzten Änderung eines Skripts
- mktime() - Liefert den Unix-Zeitstempel für ein Datum
- IntlDateFormatter::format() - Format the date/time value as a string
- time() - Liefert den aktuellen Unix-Zeitstempel
- Vordefinierte DateTime-Konstanten

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_add — Alias von DateTime::add()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::add()

# date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_create — Erstellt ein neues DateTime-Objekt

### Beschreibung

function date_create(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTime|false

Dies ist die prozedurale Version von DateTime::__construct().

Anders als der DateTime-Konstruktor gibt diese Funktion `false` anstelle einer Exception zurück, wenn der übergebene Parameter `datetime` ungültig ist.

### Parameter-Liste

Siehe DateTimeImmutable::__construct.

### Rückgabewerte

Gibt eine neue DateTime-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- DateTimeImmutable::__construct() - Liefert ein neues DateTimeImmutable-Objekt
- DateTimeImmutable::createFromFormat() - Wertet eine Zeitangabe gemäß dem angegebenen Format aus
- DateTime::__construct() - Liefert ein neues DateTime-Objekt

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_create_from_format — Alias von DateTime::createFromFormat()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::createFromFormat()

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable — Erstellt ein neues DateTimeImmutable-Objekt

### Beschreibung

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

Dies ist die prozedurale Version von DateTimeImmutable::__construct().

Anders als der DateTimeImmutable-Konstruktor gibt diese Funktion `false` anstelle einer Exception zurück, wenn der übergebene Parameter `datetime` ungültig ist.

### Parameter-Liste

Siehe DateTimeImmutable::__construct.

### Rückgabewerte

Gibt eine neue DateTimeImmutable-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- DateTimeImmutable::createFromFormat() - Wertet eine Zeitangabe gemäß dem angegebenen Format aus

# date_create_immutable_from_format

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable_from_format — Alias von DateTimeImmutable::createFromFormat()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeImmutable::createFromFormat()

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_date_set — Alias von DateTime::setDate()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::setDate()

# date_default_timezone_get

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_get — Ermittelt die Standardzeitzone, die von allen Datums- und Zeitfunktionen in einem Skript verwendet wird

### Beschreibung

function date_default_timezone_get(): string

Diese Funktion versucht, die Standardzeitzone in folgender Reihenfolge zu ermitteln und zurückzugeben:

- Lesen der mit der Funktion date_default_timezone_set() eingestellten Zeitzone (falls vorhanden)

- Lesen der INI-Option date.timezone (falls gesetzt)

Wenn keiner der oben genannten Versuche zum Erfolg führt, gibt date_default_timezone_get() `UTC` als Standardzeitzone zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen Wert vom Typ string zurück.

### Beispiele

Beispiel #1 Ermitteln der Standardzeitzone

    <?php
    date_default_timezone_set('Europe/London');

    if (date_default_timezone_get()) {
        echo 'date_default_timezone_set: ' . date_default_timezone_get() . "\n";
    }

    if (ini_get('date.timezone')) {
        echo 'date.timezone: ' . ini_get('date.timezone');
    }

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    date_default_timezone_set: Europe/London
    date.timezone: Europe/London

Beispiel #2 Ermitteln der Abkürzung einer Zeitzone

    <?php
    date_default_timezone_set('America/Los_Angeles');
    echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    America/Los_Angeles => America/Los_Angeles => PST

### Siehe auch

- date_default_timezone_set() - Setzt die Standardzeitzone, die von allen Datums- und Zeitfunktionen benutzt wird.
- Liste unterstützter Zeitzonen

# date_default_timezone_set

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_set — Setzt die Standardzeitzone, die von allen Datums- und Zeitfunktionen benutzt wird.

### Beschreibung

function date_default_timezone_set(string `$timezoneId`): bool

date_default_timezone_set() setzt die Standardzeitzone, die von allen Datums- und Zeitfunktionen benutzt wird.

Anstatt diese Funktion zu benutzen, um die Zeitzone im Script zu setzen, kann man auch die INI-Einstellung date.timezone verwenden, um die Standardzeitzone setzen.

### Parameter-Liste

`timezoneId`

  Der Zeitzonenbezeichner, z. B. `UTC`, `Africa/Lagos`, `Asia/Hong_Kong` oder `Europe/Lisbon`. Eine Liste von gültigen Bezeichnern ist unter Liste unterstützter Zeitzonen zu finden.

### Rückgabewerte

Die Funktion gibt `false` zurück, wenn `timezoneId` ungültig ist, ansonsten `true`.

### Beispiele

Beispiel #1 Ermittlung der Standardzeitzone

    <?php
    date_default_timezone_set('America/Los_Angeles');

    $script_tz = date_default_timezone_get();
    $ini_tz = ini_get('date.timezone');

    if (strcmp($script_tz, $ini_tz)){
        echo 'Die Script-Zeitzone unterscheidet sich von der ini-set-Zeitzone.';
    } else {
        echo 'Die Script-Zeitzone und die ini-set-Zeitzone stimmen überein.';
    }

### Siehe auch

- date_default_timezone_get() - Ermittelt die Standardzeitzone, die von allen Datums- und Zeitfunktionen in einem Skript verwendet wird
- Liste unterstützter Zeitzonen

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_diff — Alias von DateTime::diff()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::diff()

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_format — Alias von DateTime::format()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::format()

# date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_get_last_errors — Alias von DateTimeImmutable::getLastErrors()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeImmutable::getLastErrors()

# date_interval_create_from_date_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_create_from_date_string — Alias von DateInterval::createFromDateString()

### Beschreibung

Diese Funktion ist ein Alias für: DateInterval::createFromDateString()

# date_interval_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_format — Alias von DateInterval::format()

### Beschreibung

Diese Funktion ist ein Alias für: DateInterval::format()

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_isodate_set — Alias von DateTime::setISODate()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::setISODate()

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_modify — Alias von DateTime::modify()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::modify()

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_offset_get — Alias von DateTime::getOffset()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::getOffset()

# date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — Liefert ein assoziatives Array mit detaillierten Informationen zu einem gegebenen Datum/Zeitpunkt

### Beschreibung

function date_parse(string `$datetime`): array

date_parse() wertet die angegebene Zeichenkette `datetime` nach den gleichen Regeln aus wie strtotime() und DateTimeImmutable::__construct(). Anstelle eines Unix-Zeitstempels (mit strtotime()) oder eines DateTimeImmutable-Objekts (mit DateTimeImmutable::__construct()) gibt diese Funktion ein assoziatives Array mit den Informationen zurück, die sie aus dem angegebenen `datetime` ermitteln konnte.

Wenn über eine bestimmte Gruppe von Elementen keine Informationen gefunden werden können, werden diese Array-Elemente auf `false` gesetzt oder sie fehlen. Wenn sie benötigt werden, um einen Zeitstempel oder ein DateTimeImmutable-Objekt aus dieser `datetime`-Zeichenkette zu konstruieren, können mehrere Felder auf einen anderen Wert als `false` gesetzt werden. Die Beispiele zeigen, wo dies der Fall ist.

### Parameter-Liste

`datetime`

  Datum und Uhrzeit in einem Format, das von DateTimeImmutable::__construct() akzeptiert wird.

### Rückgabewerte

Gibt ein Array mit Informationen zu Datum und Uhrzeit zurück.

Das zurückgegebene Array hat Schlüssel für `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction` und `is_localtime`.

Wenn `is_localtime` angegeben ist, gibt `zone_type` den Typ der Zeitzone an. Für Typ `1` (UTC-Offset) werden die Felder `zone` und `is_dst` hinzugefügt; für Typ `2` (Zeitzonen-Abkürzung) werden die Felder `tz_abbr` und `is_dst` hinzugefügt; und für Typ `3` (Zeitzonen-Kennung) werden die Felder `tz_abbr` und `tz_id` hinzugefügt.

Wenn relative Zeitelemente in der Zeichenkette `datetime` vorhanden sind, z. B. `+3 days`, dann enthält das zurückgegebene Array ein untergeordnetes Array mit dem Schlüssel `relative`. Dieses Array enthält dann die Schlüssel `year`, `month`, `day`, `hour`, `minute`, `second` und, abhängig von der übergebenen Zeichenkette, `weekday` und `weekdays`.

Das Array enthält die Felder `warning_count` und `warnings`. Das erste gibt an, wie viele Warnungen es gab. Die Schlüssel des Arrays `warnings` geben die Positionen im angegebenen `datetime` an, an denen die Warnungen aufgetreten sind, während die Werte die Warnungen selbst beschreiben.

Das Array enthält auch die Felder `error_count` und `errors`. Das erste Feld gibt an, wie viele Fehler gefunden wurden. Die Schlüssel des Arrays `errors` geben die Positionen im angegebenen `datetime` an, an denen die Fehler aufgetreten sind, während die Werte die Fehler selbst beschreiben.

Warnung

Die Anzahl der Array-Elemente in den Arrays `warnings` und `errors` kann kleiner sein als `warning_count` oder `error_count`, wenn die Warnungen bzw. Fehler an derselben Stelle aufgetreten sind.

### Fehler/Exceptions

Falls das Datums-/Zeitformat fehlerhaft ist, enthält das Element 'errors' die Fehlermeldungen.

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | Das Element `zone` des zurückgegebenen Arrays stellt nun Sekunden statt Minuten dar und das Vorzeichen ist umgekehrt. Zum Beispiel wird aus `-120` nun `7200`.

### Beispiele

Beispiel #1 Ein date_parse()-Beispiel mit einer vollständigen `datetime`-Zeichenkette

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5"));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(12) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Die Zeitzonen-Elemente werden nur angezeigt, wenn sie in der angegebenen `datetime`-Zeichenkette enthalten sind. In diesem Fall gibt es immer ein Element `zone_type` und ein paar andere, die von seinem Wert abhängen.

Beispiel #2 date_parse() mit Zeitzonenkürzel

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 BST"));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(16) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(2)
      ["zone"]=>
      int(0)
      ["is_dst"]=>
      bool(true)
      ["tz_abbr"]=>
      string(3) "BST"
    }

Beispiel #3 date_parse() mit Zeitzonenkennung

    <?php
    var_dump(date_parse("June 2nd, 2022, 10:28:17 Europe/London"));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(14) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(28)
      ["second"]=>
      int(17)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(true)
      ["zone_type"]=>
      int(3)
      ["tz_id"]=>
      string(13) "Europe/London"
    }

Wenn eine kürzere `datetime`-Zeichenkette ausgewertet wird, stehen weniger Informationen zur Verfügung. In diesem Beispiel werden alle Bestandteile der Uhrzeit als `false` zurückgegeben.

Beispiel #4 date_parse() mit einer minimalen Zeichenkette

    <?php
    var_dump(date_parse("June 2nd, 2022"));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(12) {
      ["year"]=>
      int(2022)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      bool(false)
      ["minute"]=>
      bool(false)
      ["second"]=>
      bool(false)
      ["fraction"]=>
      bool(false)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
    }

Relative Formate haben keinen Einfluss auf die Werte, die aus absoluten Formaten gewonnen werden, sondern werden in das Element "relativ" eingefügt.

Beispiel #5 date_parse() mit relativen Formaten

    <?php
    var_dump(date_parse("2006-12-12 10:00:00.5 +1 week +1 hour"));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(13) {
      ["year"]=>
      int(2006)
      ["month"]=>
      int(12)
      ["day"]=>
      int(12)
      ["hour"]=>
      int(10)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0.5)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(6) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(7)
        ["hour"]=>
        int(1)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
      }
    }

Einige Textbausteine, z. B. `Thursday`, setzen den Zeitanteil der Zeichenkette auf `0`. Wenn `Thursday` an DateTimeImmutable::__construct() übergeben wird, führt dies ebenfalls dazu, dass hour, minute, second und fraction auf `0` gesetzt werden. Im folgenden Beispiel wird das Element year jedoch auf `false` belassen.

Beispiel #6 date_parse() mit Nebeneffekten

    <?php
    var_dump(date_parse("Thursday, June 2nd"));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(13) {
      ["year"]=>
      bool(false)
      ["month"]=>
      int(6)
      ["day"]=>
      int(2)
      ["hour"]=>
      int(0)
      ["minute"]=>
      int(0)
      ["second"]=>
      int(0)
      ["fraction"]=>
      float(0)
      ["warning_count"]=>
      int(0)
      ["warnings"]=>
      array(0) {
      }
      ["error_count"]=>
      int(0)
      ["errors"]=>
      array(0) {
      }
      ["is_localtime"]=>
      bool(false)
      ["relative"]=>
      array(7) {
        ["year"]=>
        int(0)
        ["month"]=>
        int(0)
        ["day"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["weekday"]=>
        int(4)
      }
    }

### Siehe auch

- date_parse_from_format() - Ermittelt Informationen über das angegebene Datum anhand des angegebenen Formats - Ermittelt Informationen über das angegebene Datum anhand des angegebenen Formats
- checkdate() - Prüft ein Gregorianisches Datum auf Gültigkeit für die Überprüfung eines gregorianischen Datums
- getdate() - Liefert Datums- und Zeitinformationen

# date_parse_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_parse_from_format — Ermittelt Informationen über das angegebene Datum anhand des angegebenen Formats

### Beschreibung

function date_parse_from_format(string `$format`, string `$datetime`): array

Gibt ein assoziatives Array mit detaillierten Informationen über das angegebene Datum und die angegebene Uhrzeit zurück.

### Parameter-Liste

`format`

  Zur Verwendung des Parameters `format` siehe die Dokumentation von DateTimeImmutable::createFromFormat(). Es gelten die gleichen Regeln.

`datetime`

  Eine Zeichenkette, die Datum und Uhrzeit angibt.

### Rückgabewerte

Gibt ein assoziatives Array mit detaillierten Informationen über das angegebene Datum und die angegebene Uhrzeit zurück.

Das zurückgegebene Array hat Schlüssel für `year`, `month`, `day`, `hour`, `minute`, `second`, `fraction` und `is_localtime`.

Wenn `is_localtime` angegeben ist, gibt `zone_type` den Typ der Zeitzone an. Für Typ `1` (UTC-Offset) werden die Felder `zone` und `is_dst` hinzugefügt; für Typ `2` (Zeitzonen-Abkürzung) werden die Felder `tz_abbr` und `is_dst` hinzugefügt; und für Typ `3` (Zeitzonen-Kennung) werden die Felder `tz_abbr` und `tz_id` hinzugefügt.

Das Array enthält die Felder `warning_count` und `warnings`. Das erste gibt an, wie viele Warnungen es gab. Die Schlüssel des Arrays `warnings` geben die Positionen im angegebenen `datetime` an, an denen die Warnungen aufgetreten sind, während die Werte die Warnungen selbst beschreiben. Das folgende Beispiel zeigt eine solche Warnung.

Das Array enthält auch die Felder `error_count` und `errors`. Das erste Feld gibt an, wie viele Fehler gefunden wurden. Die Schlüssel des Arrays `errors` geben die Positionen im angegebenen `datetime` an, an denen die Fehler aufgetreten sind, während die Werte die Fehler selbst beschreiben. Das folgende Beispiel zeigt einen solchen Fehler.

Warnung

Die Anzahl der Array-Elemente in den Arrays `warnings` und `errors` kann kleiner sein als `warning_count` oder `error_count`, wenn die Warnungen bzw. Fehler an derselben Stelle aufgetreten sind.

### Fehler/Exceptions

Wenn der Parameter `datetime` NULL-Bytes enthält, wirft diese Funktion einen ValueError.

### Changelog

Version | Beschreibung
--- | ---
8.0.21, 8.1.8, 8.2.0 | Wenn in `datetime` NULL-Bytes übergeben werden, wird nun ein ValueError geworfen; vorher wurde dies stillschweigend ignoriert.
7.2.0 | Das Element `zone` des zurückgegebenen Arrays stellt nun Sekunden statt Minuten dar und das Vorzeichen ist umgekehrt. Zum Beispiel wird aus `-120` nun `7200`.

### Beispiele

Beispiel #1 date_parse_from_format()-Beispiel

    <?php
    $date = "6.1.2009 13:00+01:00";
    print_r(date_parse_from_format("j.n.Y H:iP", $date));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [year] => 2009
        [month] => 1
        [day] => 6
        [hour] => 13
        [minute] => 0
        [second] => 0
        [fraction] => 0
        [warning_count] => 0
        [warnings] => Array
            (
            )

        [error_count] => 0
        [errors] => Array
            (
            )

        [is_localtime] => 1
        [zone_type] => 1
        [zone] => 3600
        [is_dst] =>
    )

Beispiel #2 date_parse_from_format()-Beispiel mit Warnungen

    <?php
    $date = "26 August 2022 22:30 pm";
    $parsed = date_parse_from_format("j F Y G:i a", $date);

    echo "Anzahl der Warnungen: ", $parsed['warning_count'], "\n";
    foreach ($parsed['warnings'] as $position => $message) {
        echo "\tAn Position {$position}: {$message}\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Anzahl der Warnungen: 1
    	An Position 23: The parsed time was invalid

Beispiel #3 date_parse_from_format()-Beispiel mit Fehlern

    <?php
    $date = "26 August 2022 CEST";
    $parsed = date_parse_from_format("j F Y H:i", $date);

    echo "Anzahl der Fehler: ", $parsed['error_count'], "\n";
    foreach ($parsed['errors'] as $position => $message) {
        echo "\tAn Position {$position}: {$message}\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Anzahl der Fehler: 3
    	An Position 15: A two digit hour could not be found
    	An Position 19: Not enough data available to satisfy format

### Siehe auch

- DateTimeImmutable::createFromFormat() - Wertet eine Zeitangabe gemäß dem angegebenen Format aus
- checkdate() - Prüft ein Gregorianisches Datum auf Gültigkeit

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_sub — Alias von DateTime::sub()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::sub()

### Siehe auch

- DateTimeImmutable::sub() - Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden
- DateTime::sub() - Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden von einem DateTime-Objekt.

# date_sun_info

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

date_sun_info — Liefert ein Array mit Informationen über Sonnenauf- und -untergang sowie Beginn und Ende der Dämmerung

### Beschreibung

function date_sun_info(int `$timestamp`, float `$latitude`, float `$longitude`): array

### Parameter-Liste

`timestamp`

  Ein Unix-Zeitstempel

`latitude`

  Eine geografische Breite in Grad

`longitude`

  Eine geografische Länge in Grad

### Rückgabewerte

Gibt bei Erfolg ein Array zurück, dessen Struktur in der folgenden Liste beschrieben wird:

`sunrise`
  Der Zeitstempel des Sonnenaufgangs (Zenitwinkel = 90°35').
`sunset`
  Der Zeitstempel des Sonnenuntergangs (Zenitwinkel = 90°35').
`transit`
  Der Zeitstempel, wenn die Sonne im Zenit steht, d. h. wenn sie ihren höchsten Punkt erreicht hat.
`civil_twilight_begin`
  Der Beginn der bürgerlichen Morgendämmerung (Zenitwinkel = 96°); sie endet bei `sunrise`.
`civil_twilight_end`
  Das Ende der bürgerlichen Abenddämmerung (Zenitwinkel = 96°); sie beginnt bei `sunset`.
`nautical_twilight_begin`
  Der Beginn der nautischen Morgendämmerung (Zenitwinkel = 102°); sie endet bei `civil_twilight_begin`.
`nautical_twilight_end`
  Das Ende der nautischen Abenddämmerung (Zenitwinkel = 102°); sie beginnt bei `civil_twilight_end`.
`astronomical_twilight_begin`
  Der Beginn der astronomischen Morgendämmerung (Zenitwinkel = 108°); sie endet bei `nautical_twilight_begin`.
`astronomical_twilight_end`
  Das Ende der astronomischen Abenddämmerung (Zenitwinkel = 108°); sie beginnt bei `nautical_twilight_end`.

Die Werte der Array-Elemente sind entweder UNIX-Zeitstempel, `false`, wenn die Sonne den ganzen Tag unter dem jeweiligen Zenit steht, oder `true`, wenn die Sonne den ganzen Tag über dem jeweiligen Zenit steht.

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | Die Berechnung wurde korrigiert und bezieht sich nun auf die lokale Mitternacht statt auf die lokale Mittagszeit, was die Ergebnisse leicht verändert.

### Beispiele

Beispiel #1 Ein date_sun_info()-Beispiel

    <?php
    $sun_info = date_sun_info(strtotime("2006-12-12"), 31.7667, 35.2333);
    foreach ($sun_info as $key => $val) {
        echo "$key: " . date("H:i:s", $val) . "\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    sunrise: 05:52:11
    sunset: 15:41:21
    transit: 10:46:46
    civil_twilight_begin: 05:24:08
    civil_twilight_end: 16:09:24
    nautical_twilight_begin: 04:52:25
    nautical_twilight_end: 16:41:06
    astronomical_twilight_begin: 04:21:32
    astronomical_twilight_end: 17:12:00

Beispiel #2 Polarnacht mit etwas Nachbearbeitung

    <?php
    $tz = new \DateTimeZone('America/Anchorage');

    $si = date_sun_info(strtotime("2022-12-21"), 70.21, -148.51);
    foreach ($si as $key => $value) {
        echo
            match ($value) {
                true => 'always',
                false => 'never',
                default => date_create("@{$value}")->setTimeZone($tz)->format( 'H:i:s T' ),
            },
            ": {$key}",
            "\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    never: sunrise
    never: sunset
    12:52:18 AKST: transit
    10:53:19 AKST: civil_twilight_begin
    14:51:17 AKST: civil_twilight_end
    09:01:47 AKST: nautical_twilight_begin
    16:42:48 AKST: nautical_twilight_end
    07:40:47 AKST: astronomical_twilight_begin
    18:03:49 AKST: astronomical_twilight_end

Beispiel #3 Mitternachtssonne (Tromsø, Norwegen)

    <?php
    $si = date_sun_info(strtotime("2022-06-26"), 69.68, 18.94);
    print_r($si);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [sunrise] => 1
        [sunset] => 1
        [transit] => 1656240426
        [civil_twilight_begin] => 1
        [civil_twilight_end] => 1
        [nautical_twilight_begin] => 1
        [nautical_twilight_end] => 1
        [astronomical_twilight_begin] => 1
        [astronomical_twilight_end] => 1
    )

Beispiel #4 Berechnung der Länge des Tages (Kiew)

    <?php
    $si = date_sun_info(strtotime('2022-08-26'), 50.45, 30.52);
    $diff = $si['sunset'] - $si['sunrise'];
    echo "Länge des Tages: ",
        floor($diff / 3600), "h ",
        floor(($diff % 3600) / 60), "s\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Länge des Tages: 13h 56s

# date_sunrise

(PHP 5, PHP 7, PHP 8)

date_sunrise — Liefert die Uhrzeit des Sonnenaufgangs für den angegebenen Tag und Ort

Warnung

Diese Funktion ist seit PHP 8.1.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten. Stattdessen sollte date_sun_info() verwendet werden.

### Beschreibung

#[\Deprecated]
function date_sunrise(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

date_sunrise() gibt die Uhrzeit des Sonnenaufgangs für den angegebenen Tag (angegeben als `timestamp`) und Ort zurück.

### Parameter-Liste

`timestamp`

  Der Zeitstempel des Tages, für den die Uhrzeit des Sonnenaufgangs ermittelt wird.

`returnFormat`

  `returnFormat`-Konstanten
  Konstante | Beschreibung | Beispiel
  --- | --- | ---
  SUNFUNCS_RET_STRING | Gibt das Ergebnis als String zurück | 16:46
  SUNFUNCS_RET_DOUBLE | Gibt das Ergebnis als Float zurück | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Gibt das Ergebnis als Int zurück (Zeitstempel) | 1095034606

`latitude`

  Voreingestellt ist Nord, für Süd muss ein negativer Wert übergeben werden. Siehe auch: date.default_latitude

`longitude`

  Voreingestellt ist Ost, für West muss ein negativer Wert übergeben werden. Siehe auch: date.default_longitude

`zenith`

  `zenith` ist der Winkel zwischen dem Mittelpunkt der Sonne und einer Linie senkrecht zur Erdoberfläche. Voreingestellt ist date.sunrise_zenith

  Gebräuchliche `zenith`-Winkel
  Winkel | Beschreibung
  --- | ---
  90°50' | Sonnenaufgang: der Punkt, an dem die Sonne sichtbar wird.
  96° | Bürgerliche Dämmerung: wird üblicherweise verwendet, um den Beginn der Morgendämmerung zu kennzeichnen.
  102° | Nautische Dämmerung: der Punkt, an dem der Horizont auf See sichtbar wird.
  108° | Astronomische Dämmerung: Der Punkt, an dem die Sonne beginnt, die Quelle von Licht zu sein.

`utcOffset`

  Wird in Stunden angegeben. Wenn `returnFormat` `SUNFUNCS_RET_TIMESTAMP` ist, wird `utcOffset` ignoriert.

### Rückgabewerte

Gibt bei Erfolg die Uhrzeit des Sonnenaufgangs im angegebenen `returnFormat` zurück. Bei einem Fehler wird `false` zurückgegeben. Ein möglicher Grund für einen Fehler ist, dass die Sonne überhaupt nicht aufgeht, was innerhalb der Polargebiete während eines Teils des Jahres der Fall ist.

### Fehler/Exceptions

Wenn die Zeitzone ungültig ist, wird bei jedem Aufruf einer Datums/Zeit-Funktion ein Fehler der Stufe `E_WARNING` erzeugt. Siehe auch date_default_timezone_set()

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Diese Funktion ist veraltet und wurde durch date_sun_info() ersetzt.
8.0.0 | `latitude`, `longitude`, `zenith` und `utcOffset` sind nun nullable (akzeptieren den `null`-Wert).

### Beispiele

Beispiel #1 date_sunrise()-Beispiel

    <?php

    /* Berechnung der Uhrzeit des Sonnenaufgangs für Lissabon, Portugal
    Breitengrad: 38.4 Nord
    Längengrad: 9 West
    Zenit ~= 90
    Zeitverschiebung: +1 GMT
    */

    echo date("D M d Y"). ', sunrise time : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, sunrise time : 08:54

Beispiel #2 Kein Sonnenaufgang

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunrise($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Siehe auch

- date_sun_info() - Liefert ein Array mit Informationen über Sonnenauf- und -untergang sowie Beginn und Ende der Dämmerung

# date_sunset

(PHP 5, PHP 7, PHP 8)

date_sunset — Liefert die Uhrzeit des Sonnenuntergangs für den angegebenen Tag und Ort

Warnung

Diese Funktion ist seit PHP 8.1.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten. Stattdessen sollte date_sun_info() verwendet werden.

### Beschreibung

#[\Deprecated]
function date_sunset(
int `$timestamp`,
int `$returnFormat` = SUNFUNCS_RET_STRING,
?float `$latitude` = null,
?float `$longitude` = null,
?float `$zenith` = null,
?float `$utcOffset` = null
): string|int|float|false

date_sunset() gibt die Uhrzeit des Sonnenuntergangs für den angegebenen Tag (angegeben als `timestamp`) und Ort zurück.

### Parameter-Liste

`timestamp`

  Der Zeitstempel des Tages, für den die Uhrzeit des Sonnenuntergangs ermittelt wird.

`returnFormat`

  `returnFormat`-Konstanten
  Konstante | Beschreibung | Beispiel
  --- | --- | ---
  SUNFUNCS_RET_STRING | Gibt das Ergebnis als String zurück | 16:46
  SUNFUNCS_RET_DOUBLE | Gibt das Ergebnis als Float zurück | 16.78243132
  SUNFUNCS_RET_TIMESTAMP | Gibt das Ergebnis als Int zurück (Zeitstempel) | 1095034606

`latitude`

  Voreingestellt ist Nord, für Süd muss ein negativer Wert übergeben werden. Siehe auch: date.default_latitude

`longitude`

  Voreingestellt ist Ost, für West muss ein negativer Wert übergeben werden. Siehe auch: date.default_longitude

`zenith`

  `zenith` ist der Winkel zwischen dem Mittelpunkt der Sonne und einer Linie senkrecht zur Erdoberfläche. Voreingestellt ist date.sunset_zenith

  Gebräuchliche `zenith`-Winkel
  Winkel | Beschreibung
  --- | ---
  90°50' | Sonnenuntergang: der Punkt, an dem die Sonne aus dem Blickfeld verschwindet.
  96° | Bürgerliche Dämmerung: wird üblicherweise verwendet, um das Ende der Abenddämmerung zu kennzeichnen.
  102° | Nautische Dämmerung: der Punkt, an dem der Horizont auf See nicht mehr sichtbar ist.
  108° | Astronomische Dämmerung: Der Punkt, an dem die Sonne aufhört, die Quelle von Licht zu sein.

`utcOffset`

  Wird in Stunden angegeben. Wenn `returnFormat` `SUNFUNCS_RET_TIMESTAMP` ist, wird `utcOffset` ignoriert.

### Rückgabewerte

Gibt bei Erfolg die Uhrzeit des Sonnenuntergangs im angegebenen `returnFormat` zurück. Bei einem Fehler wird `false` zurückgegeben. Ein möglicher Grund für einen Fehler ist, dass die Sonne überhaupt nicht untergeht, was innerhalb der Polargebiete während eines Teils des Jahres der Fall ist.

### Fehler/Exceptions

Wenn die Zeitzone ungültig ist, wird bei jedem Aufruf einer Datums/Zeit-Funktion ein Fehler der Stufe `E_WARNING` erzeugt. Siehe auch date_default_timezone_set()

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Diese Funktion ist veraltet und wurde durch date_sun_info() ersetzt.
8.0.0 | `latitude`, `longitude`, `zenith` und `utcOffset` sind nun nullable (akzeptieren den `null`-Wert).

### Beispiele

Beispiel #1 date_sunset()-Beispiel

    <?php

    /* Berechnung der Uhrzeit des Sonnenuntergangs für Lissabon, Portugal
    Breitengrad: 38.4 Nord
    Längengrad: 9 West
    Zenit ~= 90
    Zeitverschiebung: +1 GMT
    */

    echo date("D M d Y"). ', sunset time : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    Mon Dec 20 2004, sunset time : 18:13

Beispiel #2 Kein Sonnenuntergang

    <?php
    $solstice = strtotime('2017-12-21');
    var_dump(date_sunset($solstice, SUNFUNCS_RET_STRING, 69.245833, -53.537222));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### Siehe auch

- date_sun_info() - Liefert ein Array mit Informationen über Sonnenauf- und -untergang sowie Beginn und Ende der Dämmerung

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_time_set — Alias von DateTime::setTime()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::setTime()

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_get — Alias von DateTime::getTimestamp()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::getTimestamp()

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_set — Alias von DateTime::setTimestamp()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::setTimestamp()

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_get — Alias von DateTime::getTimezone()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::getTimezone()

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_set — Alias von DateTime::setTimezone()

### Beschreibung

Diese Funktion ist ein Alias für: DateTime::setTimezone()

# getdate

(PHP 4, PHP 5, PHP 7, PHP 8)

getdate — Liefert Datums- und Zeitinformationen

### Beschreibung

function getdate(?int `$timestamp` = `null`): array

Gibt ein assoziatives array mit Datums- und Zeitangaben des angegebenen `timestamp` zurück oder die lokal gültige Zeit, wenn `timestamp` weggelassen wird oder `null` ist.

### Parameter-Liste

`timestamp`

  Der optionale Parameter `timestamp` ist ein Unix-Zeitstempel vom Typ int. Falls `timestamp` nicht übergeben wird oder `null` ist, wird die aktuelle lokale Zeit als Standardwert verwendet. Er entspricht dann also dem Ergebnis der Funktion time().

### Rückgabewerte

Gibt ein assoziatives Array mit Informationen zum `timestamp` zurück. Die Elemente des zurückgegebenen assoziativen Arrays sind folgende:

Schlüsselelemente des zurückgegebenen assoziativen Arrays
Key | Beschreibung | Mögliche Rückgabewerte
--- | --- | ---
`"seconds"` | Numerische Repräsentation der Sekunden | `0` bis `59`
`"minutes"` | Numerische Repräsentation der Minuten | `0` bis `59`
`"hours"` | Numerische Repräsentation der Stunden | `0` bis `23`
`"mday"` | Numerische Repräsentation des Monatstags | `1` bis `31`
`"wday"` | Numerische Repräsentation des Wochentags | `0` (für Sonntag) bis `6` (für Sonnabend)
`"mon"` | Numerische Repräsentation des Monats | `1` bis `12`
`"year"` | Eine vollständige numerische Repräsentation der Jahreszahl (vierstellig) | Beispiele: `1999` oder `2003`
`"yday"` | Numerische Repräsentation des Tages des Jahres | `0` bis `365`
`"weekday"` | Eine vollständige textuelle Repräsentation des Wochentags | `Sonntag` bis `Sonnabend`
`"month"` | Eine vollständige textuelle Repräsentation des Monatsnamens, wie Januar oder März | `Januar` bis `Dezember`
`0` | Sekunden seit der Unix-Epoche, ähnlich den Werten, die von der Funktion time() zurückgegeben und von der Funktion date() verwendet werden. | Abhängig vom System, typischerweise ein Wert von `-2147483648` bis `2147483647`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `timestamp` ist jetzt nullbar.

### Beispiele

Beispiel #1 getdate()-Beispiel

    <?php
    $heute = getdate();
    print_r($heute);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [seconds] => 40
        [minutes] => 58
        [hours] => 21
        [mday] => 17
        [wday] => 2
        [mon] => 6
        [year] => 2003
        [yday] => 167
        [weekday] => Tuesday
        [month] => June
        [0] => 1055901520
    )

### Siehe auch

- date() - Formatiert einen Unix-Zeitstempel
- idate() - Formatiert einen Teil der lokalen Zeit/des lokalen Datums als Integer
- localtime() - Ermittelt die lokale Zeit
- time() - Liefert den aktuellen Unix-Zeitstempel
- setlocale() - Legt regionale (locale) Einstellungen fest

# gettimeofday

(PHP 4, PHP 5, PHP 7, PHP 8)

gettimeofday — Ermittelt die aktuelle Zeit

### Beschreibung

function gettimeofday(bool `$as_float` = `false`): array|float

Es handelt sich um eine Schnittstelle zum Systemaufruf von gettimeofday(2). Die Funktion gibt ein assoziatives Array zurück, das die Daten enthält, die der Systemaufruf produziert hat.

### Parameter-Liste

`as_float`

  Sofern auf `true` gesetzt, wird eine Fließkommazahl anstelle des Arrays zurückgegeben.

### Rückgabewerte

Standardmäßig wird ein Array zurückgegeben. Wenn der Parameter `as_float` angegeben wurde, ist der Rückgabewert vom Typ float.

Array-Schlüssel:

- "sec" - Sekunden seit der Unix-Epoche
- "usec" - Mikrosekunden
- "minuteswest" - Minuten westlich von Greenwich
- "dsttime" - Art der Korrektur der Sommerzeit

### Beispiele

Beispiel #1 gettimeofday()-Beispiel

    <?php
    print_r(gettimeofday());

    echo gettimeofday(true);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [sec] => 1073504408
        [usec] => 238215
        [minuteswest] => 0
        [dsttime] => 1
    )
    1073504408.23910

# gmdate

(PHP 4, PHP 5, PHP 7, PHP 8)

gmdate — Formatiert eine GMT/UTC Zeit-/Datumsangabe

### Beschreibung

function gmdate(string `$format`, ?int `$timestamp` = `null`): string

Identisch mit der Funktion date(), ausgenommen, dass die zurückgegebene Zeitangabe Greenwich Mean Time (GMT) entspricht.

### Parameter-Liste

`format`

  Das Format des ausgegebenen Datumsstrings. Siehe auch die Formatierungsoptionen der Funktion date().

`timestamp`

  Der optionale Parameter `timestamp` ist ein Unix-Zeitstempel vom Typ int. Falls `timestamp` nicht übergeben wird oder `null` ist, wird die aktuelle lokale Zeit als Standardwert verwendet. Er entspricht dann also dem Ergebnis der Funktion time().

### Rückgabewerte

Gibt einen formatierten Datumsstring zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `timestamp` ist jetzt nullbar.

### Beispiele

Beispiel #1 gmdate()-Beispiel

    <?php
    date_default_timezone_set("Europe/Helsinki");

    echo date("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo gmdate("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Jan 01 1998 00:00:00 Europe/Helsinki
    Dec 31 1997 22:00:00 UTC

### Siehe auch

- DateTimeImmutable::__construct() - Liefert ein neues DateTimeImmutable-Objekt
- DateTimeInterface::format() - Liefert das Datum formatiert gemäß dem angegebenen Format
- date() - Formatiert einen Unix-Zeitstempel
- mktime() - Liefert den Unix-Zeitstempel für ein Datum
- gmmktime() - Liefert den Unix-Zeitstempel für ein GMT-Datum
- IntlDateFormatter::format() - Format the date/time value as a string

# gmmktime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmmktime — Liefert den Unix-Zeitstempel für ein GMT-Datum

### Beschreibung

function gmmktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

Identisch zu mktime() mit der Ausnahme, dass die übergebenen Parameter ein GMT-Datum repräsentieren. gmmktime() greift intern auf mktime() zurück, sodass nur Zeitangaben valide sind, die in der ausgewählten lokalen Zeitzone genutzt werden können.

Wie bei mktime() können optionale Argumente von rechts nach links weggelassen werden, wobei jedes fehlende Argument auf den gegenwärtigen entsprechenden GMT-Wert gesetzt wird.

Der Aufruf von gmmktime() ohne Argumente wird nicht unterstützt und führt zu einem ArgumentCountError. time() kann verwendet werden, um den aktuellen Zeitstempel zu erhalten.

### Parameter-Liste

`hour`

  Die Zahl der Stunden relativ zum Beginn des Tages, der durch `month`, `day` und `year` bestimmt ist. Negative Werte beziehen sich auf die Stunde vor Mitternacht des jeweiligen Tages. Werte größer als 23 beziehen sich auf die entsprechende Stunde des/der folgenden Tages/Tage.

`minute`

  Die Zahl der Minuten relativ zum Beginn der `hour`. Negative Werte beziehen sich auf die Minute in der vorherigen Stunde. Werte größer als 59 beziehen sich auf die entsprechende Minute der folgenden Stunde(n).

`second`

  Die Zahl der Sekunden relativ zum Beginn der `minute`. Negative Werte beziehen sich auf die Sekunde der vorherigen Minute. Werte größer als 59 beziehen sich auf die entsprechende Minute der folgenden Minute(n).

`month`

  Die Zahl des Monats relativ zum Ende des vorherigen Jahres. Die Werte 1 bis 12 beziehen sich auf normale Kalendermonate des jeweiligen Jahres. Werte kleiner als 1 (einschließlich negativer Werte) beziehen sich auf die Monate des vorherigen Jahres in umgekehrter Reihenfolge, sodass 0 Dezember ist, -1 November usw. Werte größer als 12 beziehen sich auf den entsprechenden Monat des/der folgenden Jahres/Jahre.

`day`

  Die Zahl des Tages relativ zum Ende des vorherigen Monats. Die Werte 1 bis 28, 29, 30 oder 31 (in Abhängigkeit vom Monat) beziehen sich auf normale Tage im aktuellen Monat. Werte kleiner als 1 (einschließlich negativer Werte) beziehen sich auf die Tage im vorherigen Monat, sodass 0 der letzte Tag des vorherigen Monats ist, -1 der vorletzte usw. Werte größer als die Anzahl von Tagen im aktuellen Monat beziehen sich auf den entsprechenden Tag in dem/den folgenden Monat(en).

`year`

  Das Jahr

### Rückgabewerte

Gibt einen Unix-Zeitstempel vom Typ int zurück oder `false`, wenn der Zeitstempel nicht in einen PHP-Integer passt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `hour` ist nicht mehr optional. Falls ein Unix-Zeitstempel benötigt wird, sollte time() verwendet werden.
8.0.0 | `minute`, `second`, `month`, `day` und `year` sind nun nullable (akzeptieren den `null`-Wert).

### Beispiele

Beispiel #1 Grundlegendes gmmktime()-Beispiel

    <?php
    date_default_timezone_set("Indian/Maldives");

    echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    July 1, 2000 is on a Saturday

### Siehe auch

- Die Klasse DateTimeImmutable
- mktime() - Liefert den Unix-Zeitstempel für ein Datum
- date() - Formatiert einen Unix-Zeitstempel
- time() - Liefert den aktuellen Unix-Zeitstempel

# gmstrftime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmstrftime — Formatiert eine Datums-/Zeitangabe in GMT/UTC-Format entsprechend den Locale-Einstellungen

Warnung

Diese Funktion wurde in PHP 8.1.0 als DEPRECATED (veraltet) markiert. Es wird dringend davon abgeraten, sich auf diese Funktion zu verlassen.

Alternativ können die folgenden Funktionen verwendet werden:

- gmdate()
- IntlDateFormatter::format()

### Beschreibung

#[\Deprecated]
function gmstrftime(string `$format`, ?int `$timestamp` = null): string|false

Bewirkt das gleiche wie strftime(), mit dem Unterschied, dass die Zeit nach Greenwich Mean Time (GMT) zurückgegeben wird. Wenn das Skript beispielsweise unter Eastern Standard Time (GMT -0500) läuft, gibt die erste Zeile unten "Dec 31 1998 20:00:00" aus, während die zweite "Jan 01 1999 01:00:00" ausgibt.

Warnung

Diese Funktion hängt von den Locale-Informationen des Betriebssystems ab und diese sind möglicherweise nicht kompatibel oder gar nicht verfügbar. Stattdessen sollte die Methode IntlDateFormatter::format() verwendet werden.

### Parameter-Liste

`format`

  Siehe die Beschreibung bei strftime().

`timestamp`

  Der optionale Parameter `timestamp` ist ein Unix-Zeitstempel vom Typ int. Falls `timestamp` nicht übergeben wird oder `null` ist, wird die aktuelle lokale Zeit als Standardwert verwendet. Er entspricht dann also dem Ergebnis der Funktion time().

### Rückgabewerte

Gibt eine entsprechend der übergebenen Formatzeichenkette formatierte Zeichenkette zurück. Die verwendete Zeitangabe wird durch den übergebenen `timestamp` oder die aktuelle lokale Zeit festgelegt, wenn kein Timestamp angegeben wurde. Monats- und Wochentagsnamen sowie andere sprachabhängige Zeichenketten beziehen sich auf die via setlocale() festgelegte aktuelle Locale-Angabe. Gibt bei einem Fehler `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `timestamp` ist jetzt nullbar.

### Beispiele

Beispiel #1 gmstrftime()-Beispiel

    <?php
    setlocale(LC_TIME, 'en_US');
    echo strftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";
    echo gmstrftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";

### Siehe auch

- IntlDateFormatter::format() - Format the date/time value as a string
- DateTimeInterface::format() - Liefert das Datum formatiert gemäß dem angegebenen Format
- strftime() - Formatiert eine Zeit-/Datumsangabe gemäß dem Gebietsschema

# idate

(PHP 5, PHP 7, PHP 8)

idate — Formatiert einen Teil der lokalen Zeit/des lokalen Datums als Integer

### Beschreibung

function idate(string `$format`, ?int `$timestamp` = `null`): int|false

Formatiert den angegebenen ganzzahligen Zeitstempel `timestamp` entsprechend dem angegebenen Formatzeichen und gibt eine Datumszahl zurück. Wenn kein Zeitstempel angegeben wird, wird die aktuelle Ortszeit verwendet. Mit anderen Worten: `timestamp` ist optional und wird mit dem Wert der Funktion time() vorbelegt.

Anders als die Funktion date() akzeptiert idate() nur ein Zeichen im Parameter `format`.

### Parameter-Liste

`format`

  Die folgenden Zeichen werden in der Parameterzeichenkette `format` erkannt
  `format`-Zeichen | Beschreibung
  --- | ---
  `B` | Swatch-Internetzeit (Swatch-Beat)
  `d` | Tag des Monats
  `h` | Stunde (12-Stunden-Format)
  `H` | Stunde (24-Stunden-Format)
  `i` | Minuten
  `I` (großes i) | Gibt `1` zurück, wenn die Sommerzeit aktiviert ist, andernfalls `0`
  `L` (großes l) | Gibt bei einem Schaltjahr `1` zurück, andernfalls `0`
  `m` | Nummer des Monats
  `N` | ISO-8601-Wochentag (`1` für Montag bis `7` für Sonntag)
  `o` | ISO-8601-Jahr (4 Ziffern)
  `s` | Sekunden
  `t` | Anzahl der Tage im aktuellen Monat
  `U` | Anzahl der Sekunden seit der Unix-Epoche - 1. Januar 1970 00:00:00 UTC - dies ist gleichbedeutend mit time()
  `w` | Wochentag (`0` für Sonntag)
  `W` | ISO-8601-Wochennummer des Jahres, Wochen beginnend am Montag
  `y` | Jahr (1 oder 2 Ziffern - siehe Hinweis unten)
  `Y` | Jahr (4 Ziffern)
  `z` | Tag des Jahres
  `Z` | Zeitverschiebung in Sekunden

`timestamp`

  Der optionale Parameter `timestamp` ist ein Unix-Zeitstempel vom Typ int. Falls `timestamp` nicht übergeben wird oder `null` ist, wird die aktuelle lokale Zeit als Standardwert verwendet. Er entspricht dann also dem Ergebnis der Funktion time().

### Rückgabewerte

Gibt bei Erfolg einen Wert vom Typ int zurück. Bei einem Fehler wird `false` zurückgegeben.

Da idate() immer einen Wert vom Typ int zurückgibt und dieser nicht mit einer "0" beginnen kann, gibt idate() möglicherweise weniger Ziffern zurück, als zu erwarten wäre. Siehe das Beispiel unten.

### Fehler/Exceptions

Wenn die Zeitzone ungültig ist, wird bei jedem Aufruf einer Datums/Zeit-Funktion ein Fehler der Stufe `E_WARNING` erzeugt. Siehe auch date_default_timezone_set()

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Die Zeichen `N` (ISO-8601-Wochentag) und `o` (ISO-8601-Jahr) wurden hinzugefügt.
8.0.0 | `timestamp` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 idate()-Beispiel

    <?php
    $timestamp = strtotime('1st January 2004'); // 1072915200

    // dies gibt die Jahreszahl in einem zweistelligen Format aus
    // da diese jedoch mit einer "0" beginnen würde, wird
    // nur "4" ausgegeben.
    echo idate('y', $timestamp) . "\n";

    $timestamp = strtotime('1st January 2024'); // 1704067200
    echo idate('y', $timestamp);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    4
    24

### Siehe auch

- DateTimeInterface::format() - Liefert das Datum formatiert gemäß dem angegebenen Format
- date() - Formatiert einen Unix-Zeitstempel
- getdate() - Liefert Datums- und Zeitinformationen
- time() - Liefert den aktuellen Unix-Zeitstempel

# localtime

(PHP 4, PHP 5, PHP 7, PHP 8)

localtime — Ermittelt die lokale Zeit

### Beschreibung

function localtime(?int `$timestamp` = `null`, bool `$associative` = `false`): array

Die Funktion localtime() gibt ein Array zurück, welches hinsichtlich seiner Struktur identisch ist mit der des Funktionsaufrufs in C.

### Parameter-Liste

`timestamp`

  Der optionale Parameter `timestamp` ist ein Unix-Zeitstempel vom Typ int. Falls `timestamp` nicht übergeben wird oder `null` ist, wird die aktuelle lokale Zeit als Standardwert verwendet. Er entspricht dann also dem Ergebnis der Funktion time().

`associative`

  Bestimmt, ob die Funktion ein gewöhnliches numerisch indiziertes Array zurückgeben soll, oder ein assoziatives.

### Rückgabewerte

Ist `associative` nicht angegeben oder `false`, ist das zurückgegebene Array ein gewöhnliches numerisch indiziertes Array. Hat `associative` den Wert `true`, gibt localtime() ein assoziatives Array zurück, das die Strukturelemente enthält, die beim Aufruf der C-Funktion an localtime zurückgegeben werden. Die Namen der Schlüssel des assoziativen Arrays lauten:

- "tm_sec" - Sekunden, `0` bis `59`
- "tm_min" - Minuten, `0` bis `59`
- "tm_hour" - Stunden, `0` bis `23`
- "tm_mday" - Tag des Monats, `1` bis `31`
- "tm_mon" - Monat des Jahres, `0` (Jan) bis `11` (Dez)
- "tm_year" - Jahre seit 1900
- "tm_wday" - Tag der Woche, `0` (Son) bis `6` (Sam)
- "tm_yday" - Tag des Jahres, `0` bis `365`
- "tm_isdst" - ist für das Datum die Sommerzeit zu berücksichtigen? Positiv wenn ja, `0` wenn nein, negativ wenn unbekannt.

### Fehler/Exceptions

Wenn die Zeitzone ungültig ist, wird bei jedem Aufruf einer Datums/Zeit-Funktion ein Fehler der Stufe `E_WARNING` erzeugt. Siehe auch date_default_timezone_set()

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `timestamp` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 localtime()-Beispiel

    <?php
    $localtime = localtime();
    $localtime_assoc = localtime(time(), true);
    print_r($localtime);
    print_r($localtime_assoc);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 24
        [1] => 3
        [2] => 19
        [3] => 3
        [4] => 3
        [5] => 105
        [6] => 0
        [7] => 92
        [8] => 1
    )

    Array
    (
        [tm_sec] => 24
        [tm_min] => 3
        [tm_hour] => 19
        [tm_mday] => 3
        [tm_mon] => 3
        [tm_year] => 105
        [tm_wday] => 0
        [tm_yday] => 92
        [tm_isdst] => 1
    )

### Siehe auch

- getdate() - Liefert Datums- und Zeitinformationen

# microtime

(PHP 4, PHP 5, PHP 7, PHP 8)

microtime — Liefert den aktuellen Unix-Zeitstempel mit Mikrosekunden

### Beschreibung

function microtime(bool `$as_float` = `false`): string|float

microtime() gibt den aktuellen Unix-Zeitstempel mit Mikrosekunden zurück. Diese Funktion steht nur auf Systemen zur Verfügung, die den Systemaufruf gettimeofday() unterstützen.

Für Leistungsfähigkeitsmessungen wird die Verwendung von hrtime() empfohlen.

### Parameter-Liste

`as_float`

  Wenn auf `true` gesetzt, gibt microtime() einen Float anstatt eines Strings zurück, wie im Abschnitt Rückgabewerte unten genauer erläutert wird.

### Rückgabewerte

Standardmäßig gibt microtime() einen String im Format "msec sec" zurück, wobei `sec` die Sekunden seit Beginn der Unix-Epoche (01. Januar 1970 00:00:00 GMT) sind und `msec` die Anzahl an Mikrosekunden misst, die seit `sec` vergangen sind, was als Dezimalzahl mit Nachkommastellen ebenso in Sekunden ausgedrückt wird.

Wenn `as_float` `true` ist, gibt microtime() einen Float zurück, welcher die aktuelle Zeit in Sekunden seit Beginn der Unix-Epoche angibt (die Nachkommastellen geben die Mikrosekunden an).

### Beispiele

Beispiel #1 Zeitmessung einer Skriptausführung

    <?php
    $time_start = microtime(true);

    // Die Skriptverarbeitung fuer einen bestimmten Zeitraum unterbrechen
    usleep(10_000);

    $time_end = microtime(true);
    $time = $time_end - $time_start;

    echo "In $time Sekunden nichts getan\n";

Beispiel #2 microtime() und `REQUEST_TIME_FLOAT`

    <?php
    // zufällige Pausendauer
    usleep(random_int(10_000, 1_000_000));

    // REQUEST_TIME_FLOAT ist im superglobalen Array $_SERVER verfügbar.
    // Es enthält den Zeitstempel des Beginns der Anfrage in Mikrosekunden-Auflösung.
    $time = microtime(true) - $_SERVER["REQUEST_TIME_FLOAT"];

    echo "Nichts getan in $time Sekunden\n";

### Siehe auch

- time() - Liefert den aktuellen Unix-Zeitstempel
- hrtime() - Get the system's high resolution time

# mktime

(PHP 4, PHP 5, PHP 7, PHP 8)

mktime — Liefert den Unix-Zeitstempel für ein Datum

### Beschreibung

function mktime(
int `$hour`,
?int `$minute` = `null`,
?int `$second` = `null`,
?int `$month` = `null`,
?int `$day` = `null`,
?int `$year` = `null`
): int|false

Gibt den Unix-Zeitstempel entsprechend der gegebenen Argumente zurück. Dieser Zeitstempel ist ein Long Integer, der die Anzahl der Sekunden zwischen der Unix-Epoche (01. Januar 1970 00:00:00 GMT) und dem angegebenen Zeitpunkt enthält.

Jedes optionale Argument, das weggelassen wird oder `null` ist, wird auf den aktuellen Wert des lokalen Datums und der lokalen Uhrzeit gesetzt.

Warnung

Es ist zu beachten, dass die Argumente in einer seltsamen Reihenfolge angeordnet sind: `month`, `day`, `year`, und nicht in der sinnvolleren Reihenfolge `year`, `month`, `day`.

Der Aufruf von mktime() ohne Argumente wird nicht unterstützt und führt zu einem ArgumentCountError. time() kann verwendet werden, um den aktuellen Zeitstempel zu erhalten.

### Parameter-Liste

`hour`

  Die Anzahl der Stunden relativ zum Beginn des Tages, der durch `month`, `day` und `year` bestimmt ist. Negative Werte beziehen sich auf die Stunden vor Mitternacht des jeweiligen Tages. Werte größer als 23 beziehen sich auf die entsprechende Stunde des/der folgenden Tages/Tage.

`minute`

  Die Anzahl der Minuten relativ zum Beginn der `hour`. Negative Werte beziehen sich auf die Minuten in der vorherigen Stunde. Werte größer als 59 beziehen sich auf die entsprechende Minute der folgenden Stunde(n).

`second`

  Die Anzahl der Sekunden relativ zum Beginn der `minute`. Negative Werte beziehen sich auf die Sekunden der vorherigen Minute. Werte größer als 59 beziehen sich auf die entsprechende Minute der folgenden Minute(n).

`month`

  Die Anzahl der Monate relativ zum Ende des vorherigen Jahres. Die Werte 1 bis 12 beziehen sich auf normale Kalendermonate des jeweiligen Jahres. Werte kleiner als 1 (einschließlich negativer Werte) beziehen sich auf die Monate des vorherigen Jahres in umgekehrter Reihenfolge, sodass 0 Dezember ist, -1 November, usw. Werte größer als 12 beziehen sich auf den entsprechenden Monat des/der folgenden Jahres/Jahre.

`day`

  Die Anzahl der Tage relativ zum Ende des vorherigen Monats. Die Werte 1 bis 28, 29, 30 oder 31 (in Abhängigkeit vom Monat) beziehen sich auf normale Tage im aktuellen Monat. Werte kleiner als 1 (einschließlich negativer Werte) beziehen sich auf die Tage im vorherigen Monat, sodass 0 der letzte Tag des vorherigen Monats ist, -1 der vorletzte usw. Werte größer als die Anzahl von Tagen im aktuellen Monat beziehen sich auf den entsprechenden Tag in dem/den folgenden Monat(en).

`year`

  Die Jahreszahl, die zwei- oder vierstellig angegeben werden kann. Werte von 0-69 werden den Jahren 2000-2069 zugeordnet, Werte von 70-100 den Jahren 1970-2000. Auf Systemen, auf denen time_t ein 32-Bit-Integer mit Vorzeichen ist (das sind die meisten der heutigen Systeme), beginnt der gültige Wertebereich für `year` bei 1901 und endet bei 2038.

### Rückgabewerte

mktime() gibt den zu den übergebenen Argumenten passenden Unix-Zeitstempel zurück oder `false`, wenn der Zeitstempel nicht in einen PHP-Integer passt..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `hour` ist nicht mehr optional. Falls ein Unix-Zeitstempel benötigt wird, sollte time() verwendet werden.
8.0.0 | `minute`, `second`, `month`, `day` und `year` sind nun nullable (akzeptieren den `null`-Wert).

### Beispiele

Beispiel #1 Einfaches mktime()-Beispiel

    <?php
    // Setzt die zu verwendende Standardzeitzone.
    date_default_timezone_set('UTC');

    // Gibt aus: July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    // Gibt etwas aus wie: 2006-04-05T01:02:03+00:00
    echo date('c', mktime(1, 2, 3, 4, 5, 2006)) . "\n";

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    July 1, 2000 is on a Saturday
    2006-04-05T01:02:03+00:00

Beispiel #2 mktime()-Beispiel

mktime() ist hilfreich bei Datumsberechnungen und -prüfungen, da automatisch das korrekte Datum für Werte außerhalb der gültigen Bereiche berechnet wird. So wird in den folgenden Beispielen immer die Zeichenkette "Jan-01-1998" ausgegeben.

    <?php
    date_default_timezone_set('America/New_York');

    echo date("c", mktime(0, 0, 0, 12, 32, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 13, 1, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 98)) . "\n";

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00

Beispiel #3 Mit mktime relative Datumsangaben ermitteln

    <?php
    date_default_timezone_set('Asia/Tokyo');

    $tomorrow  = mktime(0, 0, 0, date("m")  , date("d")+1, date("Y"));
    print date('c', $tomorrow) . "\n";

    $lastmonth = mktime(0, 0, 0, date("m")-1, date("d"),   date("Y"));
    print date('c', $lastmonth) . "\n";

    $nextyear  = mktime(0, 0, 0, date("m"),   date("d"),   date("Y")+1) . "\n";
    print date('c', $nextyear) . "\n";

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2025-09-30T00:00:00+09:00
    2025-08-29T00:00:00+09:00
    2026-09-29T00:00:00+09:00

> Hinweis:

> Dies kann aufgrund der Sommerzeit zuverlässiger sein als die einfache Addition oder Subtraktion der Anzahl der Sekunden eines Tages oder Monats zu einem Zeitstempel.

Beispiel #4 Letzter Tag eines Monats

Der letzte Tag eines gegebenen Monats kann als Tag "0" des folgenden Monats ausgedrückt werden, nicht jedoch als Tag "-1". Beide folgenden Beispiele ergeben die Zeichenkette "Der letzte Tag im Februar 2000 ist der 29.".

    <?php

    $letzterTag = mktime(0, 0, 0, 3, 0, 2000);
    echo 'Der letzte Tag im Februar 2000 ist der ', date('d.', $letzterTag) . "\n";

    $letzterTag = mktime(0, 0, 0, 4, -31, 2000);
    echo 'Der letzte Tag im Februar 2000 ist der ', date('d.', $letzterTag) . "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Der letzte Tag im Februar 2000 ist der 29.
    Der letzte Tag im Februar 2000 ist der 29.

### Siehe auch

- The DateTimeImmutable class
- checkdate() - Prüft ein Gregorianisches Datum auf Gültigkeit
- gmmktime() - Liefert den Unix-Zeitstempel für ein GMT-Datum
- date() - Formatiert einen Unix-Zeitstempel
- time() - Liefert den aktuellen Unix-Zeitstempel

# strftime

(PHP 4, PHP 5, PHP 7, PHP 8)

strftime — Formatiert eine Zeit-/Datumsangabe gemäß dem Gebietsschema

Warnung

Diese Funktion wurde in PHP 8.1.0 als DEPRECATED (veraltet) markiert. Es wird dringend davon abgeraten, sich auf diese Funktion zu verlassen.

Alternativ können die folgenden Funktionen verwendet werden:

- date()
- IntlDateFormatter::format()

### Beschreibung

#[\Deprecated]
function strftime(string `$format`, ?int `$timestamp` = null): string|false

Formatiert eine Zeit-/Datumsangabe gemäß dem Gebietsschema. Monats- und Wochentagsnamen sowie andere sprachabhängige Zeichenketten werden entsprechend des per setlocale() eingestellten Wertes dargestellt.

Warnung

Es ist durchaus möglich, dass die verwendete C-Bibliothek nicht alle angegebenen Formatierungszeichen erkennt. In diesem Fall werden diese Zeichen von der PHP-Funktion strftime() nicht unterstützt. Außerdem unterstützen nicht alle Plattformen negative Zeitstempel, weshalb der Wertebereich eines Datums durch den Beginn der Unix-Epoche begrenzt sein könnte. Das bedeutet, dass z. B. %e, %T, %R und %D (und vielleicht noch weitere) und Zeitangaben vor dem `Jan 1, 1970` auf Windows-Systemen, einigen Linux-Distributionen und einigen anderen Betriebssytemen nicht funktionieren. Für Windows-Systeme gibt es im » MSDN eine komplette Übersicht der gültigen Platzhalter im Formatierungsstring. Stattdessen sollte die Methode IntlDateFormatter::format() verwendet werden.

### Parameter-Liste

`format`

  Folgende Zeichen werden in der Zeichenkette des Parameters `format` erkannt
  `format` | Beschreibung | Wertebeispiel
  --- | --- | ---
  Tag | --- | ---
  `%a` | Abgekürzter Name des Wochentages | `So` bis `Sa`
  `%A` | Ausgeschriebener Name des Wochentages | `Sonntag` bis `Samstag`
  `%d` | Tag des Monats als zweistellige Zahl (ggf. mit vorangestellter Null) | `01` bis `31`
  `%e` | Tag des Monats; einstelligen Werten wird ein Leerzeichen vorangestellt. Unter Windows nicht wie beschrieben implementiert; siehe weiter unten für weitere Informationen. | `1` bis `31`
  `%j` | Tag des Jahres als dreistellige Zahl, ggf. mit vorangestellten Nullen | `001` bis `366`
  `%u` | Numerische Darstellung des Wochentags nach ISO-8601 | `1` (für Montag) bis `7` (für Sonntag)
  `%w` | Numerische Darstellung des Wochentags | `0` (für Sonntag) bis `6` (für Samstag)
  Woche | --- | ---
  `%U` | Nummer der Kalenderwoche des gegebenen Jahres, beginnend mit dem ersten Sonntag als erste Woche | `13` (für die 13. Kalenderwoche des Jahres)
  `%V` | Nummer der Kalenderwoche des gegebenen Jahres nach ISO-8601:1988, beginnend mit der ersten Woche des Jahres mit wenigstens 4 Wochentagen, wobei Montag der Start der Kalenderwoche ist | `01` bis `53` (wobei 53 eine überlappende Woche repräsentiert)
  `%W` | Numerische Darstellung der Kalenderwoche, beginnend mit dem ersten Montag als erste Woche | `46` (für die 46. Woche des Jahres, die mit einem Montag beginnt)
  Monat | --- | ---
  `%b` | Abgekürzter Monatsname gemäß dem Gebietsschema | `Jan` bis `Dez`
  `%B` | Vollständiger Monatsname gemäß dem Gebietsschema | `Januar` bis `Dezember`
  `%h` | Abgekürzter Monatsname gemäß dem Gebietsschema (ein Alias von %b) | `Jan` bis `Dez`
  `%m` | Zweistellige numerische Darstellung des Monats | `01` (für Januar) bis `12` (für Dezember)
  Jahr | --- | ---
  `%C` | Zweistellige numerische Darstellung des Jahrhunders (Jahr geteilt durch 100, abgerundet zu einer Ganzzahl) | `19` für das 20. Jahrhundert
  `%g` | Zweistellige numerische Darstellung des Jahres gemäß dem ISO-8601:1988-Standard (siehe %V) | Beispiel: `09` für die Woche des 6. Januar 2009
  `%G` | Die vollständige vierstellige numerische Version von %g | Beispiel: `2009` für die Woche des 3. Januar 2009
  `%y` | Zweistellige numerische Darstellung des Jahres | Beispiel: `09` für 2009, `79` für 1979
  `%Y` | Vierstellige numerische Darstellung des Jahres | Beispiel: `2038`
  Zeit | --- | ---
  `%H` | Zweistellige numerische Darstellung der Stunde im 24-Stunden-Format | `00` bis `23`
  `%k` | Stunde im 24-Stunden-Format mit einem Leerzeichen vor einstelligen Stunden | `0` bis `23`
  `%I` | Zweistellige numerische Darstellung der Stunde im 12-Stunden-Format | `01` bis `12`
  `%l (kleines 'L')` | Stunde im 12-Stunden-Format mit einem Leerzeichen vor einstelligen Stunden | `1` bis `12`
  `%M` | Zweistellige numerische Darstellung der Minute | `00` bis `59`
  `%p` | 'AM' oder 'PM' in Großbuchstaben, basierend auf der gegebenen Zeit | Beispiel: `AM` für 00:31, `PM` für 22:23. Das genaue Ergebnis hängt vom Betriebssystem ab und es können auch Varianten in Kleinbuchstaben oder mit Punkten (wie `a.m.`) zurückgegeben werden.
  `%P` | 'am' oder 'pm' in Kleinbuchstaben, basierend auf der gegebenen Zeit | Beispiel: `am` für 00:31, `pm` für 22:23; wird nicht von allen Betriebssystem unterstützt.
  `%r` | Das gleiche wie "%I:%M:%S %p" | Beispiel: `09:34:17 PM` für 21:34:17
  `%R` | Das gleiche wie "%H:%M" | Beispiel: `00:35` für 12:35 AM, `16:44` für 4:44 PM
  `%S` | Zweistellige numerische Darstellung der Sekunde | `00` bis `59`
  `%T` | Das gleiche wie "%H:%M:%S" | Beispiel: `21:34:17` für 09:34:17 PM
  `%X` | Bevorzugte Zeitdarstellung gemäß dem Gebietsschema, ohne Datumsangabe | Beispiel: `03:59:16` oder `15:59:16`
  `%z` | Die Zeitverschiebung. Unter Windows nicht wie beschrieben implementiert; siehe weiter unten für weitere Informationen. | Beispiel: `-0500` für US Eastern Time
  `%Z` | Das Zeitzonenkürzel. Unter Windows nicht wie beschrieben implementiert; siehe weiter unten für weitere Informationen. | Beispiel: `EST` für Eastern Time
  Datums- und Zeitstempel | --- | ---
  `%c` | Bevorzugter Datums- und Zeitstempel gemäß dem Gebietsschema | Beispiel: `05.02.2009 00:45:10` für den 5. Februar 2009 um 00:45:10
  `%D` | Das gleiche wie "%m/%d/%y" | Beispiel: `02/05/09` für den 5. Februar 2009
  `%F` | Das gleiche wie "%Y-%m-%d" (oft verwendet für Datenbankzeitstempel) | Beispiel: `2009-02-05` für den 5. Februar 2009
  `%s` | Zeitstempel der Unix-Epochenzeit (das gleiche wie die Funktion time()) | Beispiel: `305815200` für den 10. September 1979, 08:40:00
  `%x` | Bevorzugte Datumsdarstellung gemäß dem Gebietsschema, ohne Zeitangabe | Beispiel: `02/05/09` für den 5. Februar 2009
  Verschiedenes | --- | ---
  `%n` | Ein Zeilenvorschubzeichen ("\n") | ---
  `%t` | Ein Tabulatorzeichen ("\t") | ---
  `%%` | Ein buchstäbliches Prozentzeichen ("%") | ---

  Warnung

  Im Gegensatz zu ISO-9899:1999 beginnt Sun Solaris mit Sonntag als 1. Daraus folgt, dass `%u` nicht wie in diesem Handbuch beschrieben funktionieren kann.

  Warnung

  Nur für Windows:

  Der Platzhalter `%e` wird in der Windows-Implementierung dieser Funktion nicht unterstützt. Um diesen Wert zu erhalten, kann stattdessen der Platzhalter `%#d` verwendet werden. Das Beispiel weiter unten zeigt, wie eine Plattformübergreifende kompatible Funktion geschrieben werden kann.

  Die Platzhalter `%z` und `%Z` geben beide den Namen der Zeitzone anstelle der Zeitverschiebung oder des Kürzels zurück.

  Warnung

  Nur für macOS und musl: Der Platzhalter `%P` wird in der macOS-Implementierung dieser Funktion nicht unterstützt.

`timestamp`

  Der optionale Parameter `timestamp` ist ein Unix-Zeitstempel vom Typ int. Falls `timestamp` nicht übergeben wird oder `null` ist, wird die aktuelle lokale Zeit als Standardwert verwendet. Er entspricht dann also dem Ergebnis der Funktion time().

### Rückgabewerte

Gibt eine Zeichenkette zurück, die gemäß `format` formatiert ist, wobei der angegebene Zeitstempel `timestamp` verwendet wird, oder die aktuelle Ortszeit, falls kein Zeitstempel angegeben wurde. Monats- und Wochentagsnamen sowie andere sprachabhängige Zeichenketten werden entsprechend des per setlocale() eingestellten Wertes dargestellt. Die Funktion gibt `false` zurück, wenn `format` leer ist, nicht unterstützte Konvertierungsangaben enthält, oder wenn die Länge der zurückgegebenen Zeichenkette größer als `4095` wäre.

### Fehler/Exceptions

Wenn die Zeitzone ungültig ist, wird bei jedem Aufruf einer Datums/Zeit-Funktion ein Fehler der Stufe `E_WARNING` erzeugt. Siehe auch date_default_timezone_set()

Da die Ausgabe von der zugrundeliegenden C-Bibliothek abhängt, werden einige Konvertierungszeichen nicht unterstützt. Unter Windows führt die Angabe unbekannter Konvertierungszeichen zu 5 `E_WARNING`-Meldungen und die Funktion gibt `false` zurück. Unter anderen Betriebssystemen werden unter Umständen keine `E_WARNING`-Meldungen erzeugt und die Ausgabe enthält möglicherweise unveränderte Konvertierungszeichen.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `timestamp` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Dieses Beispiel funktioniert nur, wenn auf dem System die entsprechenden Gebietsschemen installiert sind.

Beispiel #1 strftime()-Gebietsschema-Beispiele

    <?php
    setlocale(LC_TIME, "C");
    echo strftime("%A");
    setlocale(LC_TIME, "fi_FI");
    echo strftime(" in Finnish is %A,");
    setlocale(LC_TIME, "fr_FR");
    echo strftime(" in French %A and");
    setlocale(LC_TIME, "de_DE");
    echo strftime(" in German %A.\n");

Beispiel #2 ISO 8601:1988 Wochennummer-Beispiel

    <?php
    /*     Dezember 2002 / Januar 2003
    ISOWk  Mo  Di  Mi  Do  Fr  Sa  So
    ----- ----------------------------
    51     16  17  18  19  20  21  22
    52     23  24  25  26  27  28  29
    1      30  31   1   2   3   4   5
    2       6   7   8   9  10  11  12
    3      13  14  15  16  17  18  19   */

    // Ausgabe: 28.12.2002 - %V,%G,%Y = 52,2002,2002
    echo "28.12.2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n";

    // Ausgabe: 30.12.2002 - %V,%G,%Y = 1,2003,2002
    echo "30.12.2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n";

    // Ausgabe: 03.01.2003 - %V,%G,%Y = 1,2003,2003
    echo "03.01.2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n";

    // Ausgabe: 10.01.2003 - %V,%G,%Y = 2,2003,2003
    echo "10.01.2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n";

    /*     Dezember 2004 / Januar 2005
    ISOWk  Mo  Di  Mi  Do  Fr  Sa  So
    ----- ----------------------------
    51     13  14  15  16  17  18  19
    52     20  21  22  23  24  25  26
    53     27  28  29  30  31   1   2
    1       3   4   5   6   7   8   9
    2      10  11  12  13  14  15  16   */

    // Ausgabe: 23.12.2004 - %V,%G,%Y = 52,2004,2004
    echo "23.12.2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n";

    // Ausgabe: 31.12.2004 - %V,%G,%Y = 53,2004,2004
    echo "31.12.2004- %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n";

    // Ausgabe: 02.01.2005 - %V,%G,%Y = 53,2004,2005
    echo "02.01.2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n";

    // Ausgabe: 03.01.2005 - %V,%G,%Y = 1,2005,2005
    echo "03.01.2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n";

Beispiel #3 Plattformübergreifendes Beispiel unter Verwendung des Platzhalters `%e`

    <?php

    // 1. Januar ergibt: '%e%1%' (%%, e, %%, %e, %%)
    $format = '%%e%%%e%%';

    // Prüfe auf Windows, um den Platzhalter %e korrekt zu ersetzen
    if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') {
        $format = preg_replace('#(?<!%)((?:%%)*)%e#', '\1%#d', $format);
    }

    echo strftime($format);

Beispiel #4 Zeige alle bekannten und unbekannten Formate an

    <?php

    // Beschreibe die Formate
    $strftimeFormats = array(
        'A' => 'Ausgeschriebener Name des Wochentages',
        'B' => 'Vollständiger Monatsname gemäß dem Gebietsschema',
        'C' => 'Zweistellige numerische Darstellung des Jahrhunders (Jahr geteilt durch 100, abgerundet zu einer Ganzzahl)',
        'D' => 'Das gleiche wie "%m/%d/%y"',
        'E' => '',
        'F' => 'Das gleiche wie "%Y-%m-%d"',
        'G' => 'Vollständige vierstellige numerische Version von %g',
        'H' => 'Zweistellige numerische Darstellung der Stunde im 24-Stunden-Format',
        'I' => 'Zweistellige numerische Darstellung der Stunde im 12-Stunden-Format',
        'J' => '',
        'K' => '',
        'L' => '',
        'M' => 'Zweistellige numerische Darstellung der Minute',
        'N' => '',
        'O' => '',
        'P' => '"am" oder "pm" in Kleinbuchstaben, basierend auf der gegebenen Zeit',
        'Q' => '',
        'R' => 'Das gleiche wie "%H:%M"',
        'S' => 'Zweistellige numerische Darstellung der Sekunde',
        'T' => 'Das gleiche wie "%H:%M:%S"',
        'U' => 'Nummer der Kalenderwoche des angegebenen Jahres, beginnend mit dem ersten Sonntag als erste Woche',
        'V' => 'Nummer der Kalenderwoche des angegebenen Jahres gemäß ISO-8601:1988, beginnend mit der ersten Woche des Jahres mit wenigstens 4 Wochentagen, wobei Montag der Start der Kalenderwoche ist',
        'W' => 'Numerische Darstellung der Kalenderwoche, beginnend mit dem ersten Montag als erste Woche',
        'X' => 'Bevorzugte Zeitdarstellung gemäß dem Gebietsschema, ohne Datumsangabe',
        'Y' => 'Vierstellige numerische Darstellung des Jahres',
        'Z' => 'Das Zeitzonenkürzel oder die Zeitzone (abhängig vom Betriebssystem)',
        'a' => 'Abgekürzter Name des Wochentages',
        'b' => 'Abgekürzter Monatsname gemäß dem Gebietsschema',
        'c' => 'Bevorzugter Datums- und Zeitstempel gemäß dem Gebietsschema',
        'd' => 'Tag des Monats als zweistellige Zahl (ggf. mit vorangestellten Nullen)',
        'e' => 'Tag des Monats als Dezimalwert; einstelligen Werten wird ein Leerzeichen vorangestellt',
        'f' => '',
        'g' => 'Zweistellige numerische Darstellung  des Jahres gemäß dem ISO-8601:1988-Standard (siehe %V)',
        'h' => 'Abgekürzter Monatsname gemäß dem Gebietsschema (ein Alias von %b)',
        'i' => '',
        'j' => 'Tag des Jahres als dreistellige Zahl, ggf. mit vorangestellten Nullen',
        'k' => 'Stunde im 24-Stunden-Format mit einem Leerzeichen vor einstelligen Stunden',
        'l' => 'Stunde im 12-Stunden-Format mit einem Leerzeichen vor einstelligen Stunden',
        'm' => 'Zweistellige numerische Darstellung des Monats',
        'n' => 'Ein Zeilenvorschubzeichen ("\n")',
        'o' => '',
        'p' => '"AM" oder "PM" in Großbuchstaben, basierend auf der gegebenen Zeit',
        'q' => '',
        'r' => 'Das gleiche wie "%I:%M:%S %p"',
        's' => 'Zeitstempel der Unix-Epochenzeit',
        't' => 'Ein Tabulatorzeichen ("\t")',
        'u' => 'Numerische Darstellung des Wochentags gemäß ISO-8601',
        'v' => '',
        'w' => 'Numerische Darstellung des Wochentags',
        'x' => 'Bevorzugte Datumsdarstellung gemäß dem Gebietsschema, ohne Zeitangabe',
        'y' => 'Zweistellige numerische Darstellung des Jahres',
        'z' => 'Entweder die Zeitverschiebung gegenüber UTC oder das Zeitzonenkürzel (abhängig vom Betriebssystem)',
        '%' => 'Ein buchstäbliches Prozentzeichen ("%")',
    );

    // Ergebnisse
    $strftimeValues = array();

    // Werte die Formate aus und unterdrücke dabei eventuelle Fehler
    foreach ($strftimeFormats as $format => $description) {
        if (false !== ($value = @strftime("%{$format}"))) {
            $strftimeValues[$format] = $value;
        }
    }

    // Ermittle den längsten Wert
    $maxValueLength = 2 + max(array_map('strlen', $strftimeValues));

    // Melde bekannte Formate
    foreach ($strftimeValues as $format => $value) {
        echo "Bekanntes Format   : '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n";
    }

    // Melde unbekannte Formate
    foreach (array_diff_key($strftimeFormats, $strftimeValues) as $format => $description) {
        echo "Unbekanntes Format : '{$format}'   ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n";
    }

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Bekanntes Format   : 'A' = 'Freitag'                ( Ausgeschriebener Name des Wochentages )
    Bekanntes Format   : 'B' = 'Dezember'               ( Vollständiger Monatsname gemäß dem Gebietsschema )
    Bekanntes Format   : 'C' = '20'                     ( Zweistellige numerische Darstellung des Jahrhunders (Jahr geteilt durch 100, abgerundet zu einer Ganzzahl) )
    Bekanntes Format   : 'D' = '12/03/10'               ( Das gleiche wie "%m/%d/%y" )
    Bekanntes Format   : 'F' = '2010-12-03'             ( Das gleiche wie "%Y-%m-%d" )
    Bekanntes Format   : 'G' = '2010'                   ( Vollständige vierstellige numerische Version von %g )
    Bekanntes Format   : 'H' = '11'                     ( Zweistellige numerische Darstellung der Stunde im 24-Stunden-Format )
    Bekanntes Format   : 'I' = '11'                     ( Zweistellige numerische Darstellung der Stunde im 12-Stunden-Format )
    Bekanntes Format   : 'M' = '24'                     ( Zweistellige numerische Darstellung der Minute )
    Bekanntes Format   : 'R' = '11:24'                  ( Das gleiche wie "%H:%M" )
    Bekanntes Format   : 'S' = '44'                     ( Zweistellige numerische Darstellung der Sekunde )
    Bekanntes Format   : 'T' = '11:24:44'               ( Das gleiche wie "%H:%M:%S" )
    Bekanntes Format   : 'U' = '48'                     ( Nummer der Kalenderwoche des angegebenen Jahres, beginnend mit dem ersten Sonntag als erste Woche )
    Bekanntes Format   : 'V' = '48'                     ( Nummer der Kalenderwoche des angegebenen Jahres gemäß ISO-8601:1988, beginnend mit der ersten Woche des Jahres mit wenigstens 4 Wochentagen, wobei Montag der Start der Kalenderwoche ist )
    Bekanntes Format   : 'W' = '48'                     ( Numerische Darstellung der Kalenderwoche, beginnend mit dem ersten Montag als erste Woche )
    Bekanntes Format   : 'X' = '11:24:44'               ( Bevorzugte Zeitdarstellung gemäß dem Gebietsschema, ohne Datumsangabe )
    Bekanntes Format   : 'Y' = '2010'                   ( Vierstellige numerische Darstellung des Jahres )
    Bekanntes Format   : 'Z' = 'Mitteleuropäische Zeit' ( Das Zeitzonenkürzel oder die Zeitzone (abhängig vom Betriebssystem) )
    Bekanntes Format   : 'a' = 'Fr'                     ( Abgekürzter Name des Wochentages )
    Bekanntes Format   : 'b' = 'Dez'                    ( Abgekürzter Monatsname gemäß dem Gebietsschema )
    Bekanntes Format   : 'c' = '03.12.2010 11:24:44'    ( Bevorzugter Datums- und Zeitstempel gemäß dem Gebietsschema )
    Bekanntes Format   : 'd' = '03'                     ( Tag des Monats als zweistellige Zahl (ggf. mit vorangestellten Nullen) )
    Bekanntes Format   : 'e' = ' 3'                     ( Tag des Monats als Dezimalwert; einstelligen Werten wird ein Leerzeichen voran gestellt )
    Bekanntes Format   : 'g' = '10'                     ( Zweistellige numerische Darstellung  des Jahres gemäß dem ISO-8601:1988-Standard (siehe %V) )
    Bekanntes Format   : 'h' = 'Dez'                    ( Abgekürzter Monatsname gemäß dem Gebietsschema (ein Alias von %b) )
    Bekanntes Format   : 'j' = '337'                    ( Tag des Jahres als dreistellige Zahl, ggf. mit vorangestellten Nullen )
    Bekanntes Format   : 'm' = '12'                     ( Zweistellige numerische Darstellung des Monats )
    Bekanntes Format   : 'n' = '
    '                      ( Ein Zeilenvorschubzeichen ("\n") )
    Bekanntes Format   : 'r' = '11:24:44'               ( Das gleiche wie "%I:%M:%S %p" )
    Bekanntes Format   : 't' = '    '                   ( Ein Tabulatorzeichen ("\t") )
    Bekanntes Format   : 'u' = '5'                      ( Numerische Darstellung des Wochentags gemäß ISO-8601 )
    Bekanntes Format   : 'w' = '5'                      ( Numerische Darstellung des Wochentags )
    Bekanntes Format   : 'x' = '03.12.2010'             ( Bevorzugte Datumsdarstellung gemäß dem Gebietsschema, ohne Zeitangabe )
    Bekanntes Format   : 'y' = '10'                     ( Zweistellige numerische Darstellung des Jahres )
    Bekanntes Format   : 'z' = '+0100'                  ( Entweder der Zeitverschiebung gegenüber UTC oder das Zeitzonenkürzel (abhängig vom Betriebssystem) )
    Bekanntes Format   : '%' = '%'                      ( Ein buchstäbliches Prozentzeichen ("%") )
    Unbekanntes Format : 'E'
    Unbekanntes Format : 'J'
    Unbekanntes Format : 'K'
    Unbekanntes Format : 'L'
    Unbekanntes Format : 'N'
    Unbekanntes Format : 'O'
    Unbekanntes Format : 'P'                            ( "am" oder "pm" in Kleinbuchstaben, basierend auf der gegebenen Zeit )
    Unbekanntes Format : 'Q'
    Unbekanntes Format : 'f'
    Unbekanntes Format : 'i'
    Unbekanntes Format : 'k'                            ( Stunde im 24-Stunden-Format mit einem Leerzeichen vor einstelligen Stunden )
    Unbekanntes Format : 'l'                            ( Stunde im 12-Stunden-Format mit einem Leerzeichen vor einstelligen Stunden )
    Unbekanntes Format : 'o'
    Unbekanntes Format : 'p'                            ( "AM" oder "PM" in Großbuchstaben, basierend auf der gegebenen Zeit )
    Unbekanntes Format : 'q'
    Unbekanntes Format : 's'                            ( Zeitstempel der Unix-Epochenzeit )
    Unbekanntes Format : 'v'

### Anmerkungen

> Hinweis: %G und %V, die auf ISO 8601:1988-Wochennummern basieren, können unerwartete (obgleich richtige) Ergebnisse ergeben, wenn das Nummernsystem nicht genau verstanden wird. Siehe die %V Beispiele auf dieser Handbuchseite.

### Siehe auch

- IntlDateFormatter::format() - Format the date/time value as a string
- DateTimeInterface::format() - Liefert das Datum formatiert gemäß dem angegebenen Format
- » Online strftime() Format-Erstellungstool
- setlocale() - Legt regionale (locale) Einstellungen fest
- mktime() - Liefert den Unix-Zeitstempel für ein Datum
- strptime() - Wertet eine Zeit-/Datumsangabe aus, die mit strftime erzeugt wurde
- gmstrftime() - Formatiert eine Datums-/Zeitangabe in GMT/UTC-Format entsprechend den Locale-Einstellungen
- » Open-Group-Spezifikation von strftime()

# strptime

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

strptime — Wertet eine Zeit-/Datumsangabe aus, die mit strftime() erzeugt wurde

Warnung

Diese Funktion ist seit PHP 8.1.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function strptime(string `$timestamp`, string `$format`): array|false

strptime() gibt ein Array mit dem ausgewerteten Zeitstempel `timestamp` zurück oder false, falls ein Fehler auftritt.

Monats- und Wochentagsnamen und andere sprachabhängige Zeichenketten werden unter Berücksichtigung des aktuellen Gebietsschemas zurückgegeben, das mit setlocale() festgelegt wurde (LC_TIME).

### Parameter-Liste

`timestamp` (string)

  Die Zeichenkette, die ausgewertet werden soll (z. B. zurückgegeben von strftime()).

`format` (string)

  Das in `timestamp` verwendete Format (z. B. das gleiche wie das von strftime() verwendete). Es ist zu beachten, dass einige der in strftime() verfügbaren Formatierungsoptionen in strptime() möglicherweise keine Wirkung haben. Welche von ihnen genau unterstützt werden, hängt vom Betriebssystem und der verwendeten C-Bibliothek ab.

  Weitere Informationen zu den Formatierungsoptionen sind auf der Seite strftime() zu finden.

### Rückgabewerte

Gibt ein Array zurück. Bei einem Fehler wird `false` zurückgegeben.

Die folgenden Parameter werden im Array zurückgegeben
Parameter | Beschreibung
--- | ---
`"tm_sec"` | Sekunden nach der Minute (0-61)
`"tm_min"` | Minuten nach der Stunde (0-59)
`"tm_hour"` | Stunden seit Mitternacht (0-23)
`"tm_mday"` | Tag des Monats (1-31)
`"tm_mon"` | Monate seit Januar (0-11)
`"tm_year"` | Jahre seit 1900
`"tm_wday"` | Tage seit Sonntag (0-6)
`"tm_yday"` | Tage seit dem 1. Januar (0-365)
`"unparsed"` | Der Teil von `timestamp`, der mit dem angegebenen `format` nicht erkannt wurde

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Diese Funktion ist veraltet. Stattdessen sollte date_parse_from_format() verwendet werden (für eine Auswertung, die nicht vom Gebietsschema abhängig ist) oder IntlDateFormatter::parse() (für eine Auswertung, die vom Gebietsschema abhängig ist)

### Beispiele

Beispiel #1 strptime()-Beispiel

    <?php
    $format = '%d/%m/%Y %H:%M:%S';
    $strf = strftime($format);

    echo "$strf\n";

    print_r(strptime($strf, $format));

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    03/10/2004 15:54:19

    Array
    (
        [tm_sec] => 19
        [tm_min] => 54
        [tm_hour] => 15
        [tm_mday] => 3
        [tm_mon] => 9
        [tm_year] => 104
        [tm_wday] => 0
        [tm_yday] => 276
        [unparsed] =>
    )

### Anmerkungen

> Hinweis: Diese Funktion ist auf Windows-Plattformen nicht verfügbar.

> Hinweis:

> Intern ruft diese Funktion die Funktion strptime() der C-Bibliothek des Betriebssystems auf. Diese Funktion kann sich auf verschiedenen Betriebssystemen deutlich unterschiedlich verhalten. Es wird daher empfohlen, die Funktion date_parse_from_format() zu verwenden, die von diesem Problem nicht betroffen ist.

> Hinweis:

> `"tm_sec"` berücksichtigt alle Schaltsekunden (derzeit bis zu 2 pro Jahr). Weitere Informationen zu Schaltsekunden sind im » Wikipedia-Artikel über Schaltsekunden zu finden.

### Siehe auch

- IntlDateFormatter::parse() - Parse string to a timestamp value
- DateTime::createFromFormat() - Wertet eine Zeitangabe gemäß dem angegebenen Format aus
- checkdate() - Prüft ein Gregorianisches Datum auf Gültigkeit
- strftime() - Formatiert eine Zeit-/Datumsangabe gemäß dem Gebietsschema
- date_parse_from_format() - Ermittelt Informationen über das angegebene Datum anhand des angegebenen Formats

# strtotime

(PHP 4, PHP 5, PHP 7, PHP 8)

strtotime — Wandelt eine textuelle englische Datums- und Zeitbeschreibung in einen Unix-Zeitstempel um

### Beschreibung

function strtotime(string `$datetime`, ?int `$baseTimestamp` = `null`): int|false

Diese Funktion erwartet eine Zeichenkette mit einem Datum im englischen Datumsformat und versucht, dieses Format in einen Unix-Zeitstempel (die Anzahl der Sekunden seit dem 1. Januar 1970 00:00:00 UTC) zu übersetzen. Die Angabe wird relativ zum Zeitstempel ausgewertet, der im Parameter `baseTimestamp` übergebenen wurde, oder, falls `baseTimestamp` nicht übergeben wurde, relativ zur aktuellen Zeit. Das Format der Zeichenkette, die das auszuwertende Datum enthält, ist in Unterstützte Datums- und Zeitformate definiert, wobei einige Feinheiten zu beachten sind. Es wird dringend empfohlen, sich dort mit allen Details vertraut zu machen.

Warnung

Der Unix-Zeitstempel, den diese Funktion zurückgibt, enthält keine Informationen über Zeitzonen. Um Berechnungen mit Datums- und Zeitwerten durchzuführen, sollte das leistungsfähigere DateTimeImmutable verwendet werden.

Jeder Parameter dieser Funktion verwendet die Standardzeitzone, es sei denn, im betreffenden Parameter wird eine Zeitzone angegeben. Es ist darauf zu achten, nicht etwa verschiedene Zeitzonen je Parameter zu verwenden, außer es ist beabsichtigt. Die verschiedenen Möglichkeiten, die Standardzeitzone zu definieren, sind date_default_timezone_get() zu entnehmen.

### Parameter-Liste

`datetime`

  Ein Datums/Zeit Zeichenkette. Gültige Formate werden unter Datums- und Zeitformate erläutert.

`baseTimestamp`

  Der Zeitstempel, der als Basis zur Berechnung relativer Daten verwendet wird.

### Rückgabewerte

Gibt im Erfolgsfall einen Zeitstempel zurück, andernfalls `false`.

### Fehler/Exceptions

Wenn die Zeitzone ungültig ist, wird bei jedem Aufruf einer Datums/Zeit-Funktion ein Fehler der Stufe `E_WARNING` erzeugt. Siehe auch date_default_timezone_set()

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `baseTimestamp` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 Ein strtotime()-Beispiel

    <?php
    echo strtotime("now"), "\n";
    echo strtotime("10 September 2000"), "\n";
    echo strtotime("+1 day"), "\n";
    echo strtotime("+1 week"), "\n";
    echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n";
    echo strtotime("next Thursday"), "\n";
    echo strtotime("last Monday"), "\n";

Beispiel #2 Test auf Fehler

    <?php
    $str = 'Not Good';

    if (($timestamp = strtotime($str)) === false) {
        echo "Die Zeichenkette ($str) ist fehlerhaft.";
    } else {
        echo "$str == " . date('l dS \o\f F Y h:i:s A', $timestamp);
    }

### Anmerkungen

> Hinweis:

> "Relatives" Datum bedeutet in diesem Fall auch, dass nicht angegebene Komponenten des Datums-/Zeitstempels unverändert aus dem `baseTimestamp` übernommen werden. Das heißt, dass `strtotime('February')` am 31. Mai 2022 als `31 February 2022` interpretiert wird, was zum Zeitstempel `3 March` führt (in einem Schaltjahr wäre es `2 March`). Stattdessen `strtotime('1 February')` oder `strtotime('first day of February')` zu verwenden, würde dieses Problem vermeiden.

> Hinweis:

> Wenn die Angabe der Jahreszahl zweistellig erfolgt, werden Werte von 0-69 den Jahren 2000-2069 zugeordnet, die Werte 70-99 ergeben die Jahreszahlen 1970-1999. Zu möglichen Unterschieden auf 32-Bit-Systemen (mögliche Datumsangaben könnten am 2038-01-19 03:14:07 enden) ist der folgende Hinweis zu beachten.

> Hinweis:

> Der gültige Bereich eines Zeitstempels liegt typischerweise zwischen Fri, 13 Dec 1901 20:45:54 UTC und Tue, 19 Jan 2038 03:14:07 UTC (das sind die Datumsangaben, die dem minimalen und maximalen Wert eines vorzeichenbehafteten 32-bit Integer entsprechen).

> Bei 64-Bit-Versionen von PHP ist der gültige Bereich für Zeitstempel praktisch unendlich groß, da 64 Bit etwa 293 Milliarden Jahre in beide Richtungen darstellen können.

> Hinweis:

> Es ist nicht empfehlenswert, diese Funktion für mathematische Berechnungen zu verwenden. Dafür sollten stattdessen DateTime::add() und DateTime::sub() verwendet werden.

### Siehe auch

- DateTimeImmutable
- DateTimeImmutable::createFromFormat() - Wertet eine Zeitangabe gemäß dem angegebenen Format aus
- Datums- und Zeitformate
- checkdate() - Prüft ein Gregorianisches Datum auf Gültigkeit
- strptime() - Wertet eine Zeit-/Datumsangabe aus, die mit strftime erzeugt wurde

# time

(PHP 4, PHP 5, PHP 7, PHP 8)

time — Liefert den aktuellen Unix-Zeitstempel

### Beschreibung

function time(): int

Gibt die Anzahl der seit Beginn der Unix-Epoche (Januar 1 1970 00:00:00 GMT) bis jetzt vergangenen Sekunden zurück.

> Hinweis:

> Unix-Zeitstempel enthalten keine Informationen über eine lokale Zeitzone. Um die Fallstricke zu vermeiden, die mit reinen Unix-Zeitstempeln einhergehen, wird daher empfohlen, für den Umgang mit Datums- und Zeitinformationen die Klasse DateTimeImmutable zu verwenden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den aktuellen Unix-Zeitstempel zurück.

### Beispiele

Beispiel #1 time()-Beispiel

    <?php
    echo 'Jetzt: '. time();

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Jetzt: 1660338149

### Anmerkungen

Tipp

Der Zeitstempel des Beginns der aktuellen Anfrage steht in der Variablen $_SERVER['REQUEST_TIME'] zur Verfügung.

### Siehe auch

- DateTimeImmutable
- date() - Formatiert einen Unix-Zeitstempel
- microtime() - Liefert den aktuellen Unix-Zeitstempel mit Mikrosekunden

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_abbreviations_list — Alias von DateTimeZone::listAbbreviations()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeZone::listAbbreviations()

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_identifiers_list — Alias von DateTimeZone::listIdentifiers()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeZone::listIdentifiers()

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_location_get — Alias von DateTimeZone::getLocation()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeZone::getLocation()

# timezone_name_from_abbr

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

timezone_name_from_abbr — Liefert den Namen einer Zeitzone, ausgehend von der Abkürzung und der UTC-Abweichung

### Beschreibung

function timezone_name_from_abbr(string `$abbr`, int `$utcOffset` = -1, int `$isDST` = -1): string|false

### Parameter-Liste

`abbr`

  Das Zeitzonenkürzel

`utcOffset`

  Die Abweichung von GMT in Sekunden. Der Standardwert ist -1, was bedeutet, dass die erste gefundene Zeitzone zurückgegeben wird, die `abbr` entspricht. Andernfalls wird die exakte Abweichung gesucht und nur wenn diese nicht gefunden wird, wird die erste Zeitzone mit einer Abweichung zurückgegeben.

`isDST`

  Der Sommerzeit-Indikator. Voreinstellung ist -1, was bedeutet, dass bei der Suche nicht berücksichtigt wird, ob die Zeitzone Sommerzeit hat oder nicht. Wenn dies auf 1 gesetzt ist, dann wird angenommen, dass `utcOffset` eine Abweichung mit Sommerzeit ist; wenn 0, dann wird angenommen, dass `utcOffset` eine Abweichung ohne Sommerzeit ist. Wenn `abbr` nicht existiert, wird die Zeitzone ausschließlich anhand von `utcOffset` und `isDST` gesucht.

### Rückgabewerte

Gibt im Erfolgsfall den Namen der Zeitzone zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Ein timezone_name_from_abbr()-Beispiel

    <?php
    echo timezone_name_from_abbr("CET") . "\n";
    echo timezone_name_from_abbr("", 3600, 0) . "\n";

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Europe/Berlin
    Europe/Paris

### Siehe auch

- timezone_abbreviations_list() - Alias von DateTimeZone::listAbbreviations

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_name_get — Alias von DateTimeZone::getName()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeZone::getName()

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_offset_get — Alias von DateTimeZone::getOffset()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeZone::getOffset()

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_open — Alias von DateTimeZone::__construct()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeZone::__construct()

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_transitions_get — Alias von DateTimeZone::getTransitions()

### Beschreibung

Diese Funktion ist ein Alias für: DateTimeZone::getTransitions()

# timezone_version_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_version_get — Liefert die Version der timezonedb

### Beschreibung

function timezone_version_get(): string

Gibt die aktuelle Version der timezonedb zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen Wert vom Typ string im Format `YYYY.increment` zurück, z. B. `2022.2`.

Wenn die Version der verwendeten Zeitzonendatenbank veraltet ist (z. B. zeigt sie das aktuelle Jahr nicht an), können die Zeitzoneninformationen entweder durch ein PHP-Upgrade oder durch die Installation des PECL-Pakets » timezonedb aktualisiert werden.

Einige Linux-Distributionen patchen PHPs Unterstützung für Datum und Uhrzeit, damit es eine alternative Quelle für Zeitzoneninformationen verwendet. Diese Funktion gibt in einem solchen Fall `0.system` zurück. Auch in diesem Fall wird empfohlen, das PECL-Paket » timezonedb zu installieren.

### Beispiele

Beispiel #1 Ermitteln der timezonedb-Version

    <?php
    echo timezone_version_get();

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    2022.2

### Siehe auch

- Liste der unterstützten Zeitzonen

## Inhaltsverzeichnis

- checkdate — Prüft ein Gregorianisches Datum auf Gültigkeit
- date — Formatiert einen Unix-Zeitstempel
- date_add — Alias von DateTime::add
- date_create — Erstellt ein neues DateTime-Objekt
- date_create_from_format — Alias von DateTime::createFromFormat
- date_create_immutable — Erstellt ein neues DateTimeImmutable-Objekt
- date_create_immutable_from_format — Alias von DateTimeImmutable::createFromFormat
- date_date_set — Alias von DateTime::setDate
- date_default_timezone_get — Ermittelt die Standardzeitzone, die von allen Datums- und Zeitfunktionen in einem Skript verwendet wird
- date_default_timezone_set — Setzt die Standardzeitzone, die von allen Datums- und Zeitfunktionen benutzt wird.
- date_diff — Alias von DateTime::diff
- date_format — Alias von DateTime::format
- date_get_last_errors — Alias von DateTimeImmutable::getLastErrors
- date_interval_create_from_date_string — Alias von DateInterval::createFromDateString
- date_interval_format — Alias von DateInterval::format
- date_isodate_set — Alias von DateTime::setISODate
- date_modify — Alias von DateTime::modify
- date_offset_get — Alias von DateTime::getOffset
- date_parse — Liefert ein assoziatives Array mit detaillierten Informationen zu einem gegebenen Datum/Zeitpunkt
- date_parse_from_format — Ermittelt Informationen über das angegebene Datum anhand des angegebenen Formats
- date_sub — Alias von DateTime::sub
- date_sun_info — Liefert ein Array mit Informationen über Sonnenauf- und -untergang sowie Beginn und Ende der Dämmerung
- date_sunrise — Liefert die Uhrzeit des Sonnenaufgangs für den angegebenen Tag und Ort
- date_sunset — Liefert die Uhrzeit des Sonnenuntergangs für den angegebenen Tag und Ort
- date_time_set — Alias von DateTime::setTime
- date_timestamp_get — Alias von DateTime::getTimestamp
- date_timestamp_set — Alias von DateTime::setTimestamp
- date_timezone_get — Alias von DateTime::getTimezone
- date_timezone_set — Alias von DateTime::setTimezone
- getdate — Liefert Datums- und Zeitinformationen
- gettimeofday — Ermittelt die aktuelle Zeit
- gmdate — Formatiert eine GMT/UTC Zeit-/Datumsangabe
- gmmktime — Liefert den Unix-Zeitstempel für ein GMT-Datum
- gmstrftime — Formatiert eine Datums-/Zeitangabe in GMT/UTC-Format entsprechend den Locale-Einstellungen
- idate — Formatiert einen Teil der lokalen Zeit/des lokalen Datums als Integer
- localtime — Ermittelt die lokale Zeit
- microtime — Liefert den aktuellen Unix-Zeitstempel mit Mikrosekunden
- mktime — Liefert den Unix-Zeitstempel für ein Datum
- strftime — Formatiert eine Zeit-/Datumsangabe gemäß dem Gebietsschema
- strptime — Wertet eine Zeit-/Datumsangabe aus, die mit strftime erzeugt wurde
- strtotime — Wandelt eine textuelle englische Datums- und Zeitbeschreibung in einen Unix-Zeitstempel um
- time — Liefert den aktuellen Unix-Zeitstempel
- timezone_abbreviations_list — Alias von DateTimeZone::listAbbreviations
- timezone_identifiers_list — Alias von DateTimeZone::listIdentifiers
- timezone_location_get — Alias von DateTimeZone::getLocation
- timezone_name_from_abbr — Liefert den Namen einer Zeitzone, ausgehend von der Abkürzung und der UTC-Abweichung
- timezone_name_get — Alias von DateTimeZone::getName
- timezone_offset_get — Alias von DateTimeZone::getOffset
- timezone_open — Alias von DateTimeZone::__construct
- timezone_transitions_get — Alias von DateTimeZone::getTransitions
- timezone_version_get — Liefert die Version der timezonedb

# Fehler und Exceptions bei Datum/Uhrzeit

- DateError (erweitert Error)
  - DateObjectError DateRangeError
- DateException (erweitert Exception)
  - - DateInvalidOperationException
    - DateInvalidTimezoneException
    - DateMalformedIntervalStringException
    - DateMalformedPeriodStringException
    - DateMalformedStringException

# Unterstützte Datums- und Zeitformate

Dieser Abschnitt beschreibt alle verschiedenen Formate in einem BNF-ähnlichen Format, das der Parser von DateTimeImmutable, DateTime, date_create_immutable(), date_create(), date_parse() und strtotime() versteht. Die Formate sind in Abschnitte gegliedert. In den meisten Fällen können Formate aus verschiedenen Abschnitten durch Leerzeichen, Komma oder Punkt getrennt in derselben Zeichenkette für Datum und Uhrzeit verwendet werden. Für jedes der unterstützten Formate werden ein oder mehrere Beispiele sowie eine Beschreibung des Formats angegeben. Bei Formatzeichen in einfachen Anführungszeichen wird nicht zwischen Groß- und Kleinschreibung unterschieden (`'t'` könnte `t` oder `T` sein), bei Zeichen in doppelten Anführungszeichen wird zwischen Groß- und Kleinschreibung unterschieden (`"T"` ist nur `T`).

Die Formatierung von DateTimeImmutable- und DateTime-Objekten wird in der Dokumentation zur Methode DateTimeInterface::format() beschrieben.

Es sollten ein paar allgemeine Regeln beachtet werden.

1. Der Parser erlaubt für jede Einheit (Jahr, Monat, Tag, Stunde, Minute, Sekunde) die gesamte Bandbreite an Werten. Für ein Jahr sind das einfach 4 Ziffern, für einen Monat ist es 0-12, für einen Tag 0-31, für Stunden 0-24 und für Minuten 0-59.
2. Weil es Datumsangaben gibt, die eine Schaltsekunde enthalten, ist bei Sekunden die 60 erlaubt. PHP implementiert jedoch die Unix-Zeit, bei der "60" keine gültige Sekundenzahl ist, sodass es zu einem Überlauf kommt.
3. Wenn eine Zahl außerhalb des zulässigen Bereichs liegt, gibt strtotime() `false` zurück, und DateTimeImmutable::__construct() löst eine Ausnahme aus.
4. Wenn eine Zeichenkette ein Datum enthält, werden alle Zeitelemente auf 0 zurückgesetzt.
5. Wenn irgendein Teil einer Zeit in der angegebenen Zeichenkette vorhanden ist, werden alle kleineren Zeitelemente auf 0 zurückgesetzt.
6. Um den Parser schneller (und universeller) zu machen, führt er keinerlei Prüfungen durch.
7. Neben den Regeln für einzelne Zeitelemente versteht der Parser auch spezifischere zusammengesetzte Formate, so kann er z. B. Unix-Zeitstempel (`@1690388256`) und ISO-Wochentage (`2008-W28-3`) auswerten.

8. Es gibt eine Möglichkeit, zu prüfen, ob ein ungültiges Datum oder eine ungültige Uhrzeit angegeben wurde:

       <?php
       $res = date_parse("2015-09-31");
       var_dump($res["warnings"]);

   Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

       array(1) {
         [11] =>
         string(27) "The parsed date was invalid"
       }

9. Es ist bereits möglich, die Grenzfälle zu berücksichtigen, aber dafür muss DateTimeImmutable::createFromFormat() mit dem korrekten Format verwendet werden.

       <?php
       $res = DateTimeImmutable::createFromFormat("Y-m-d", "2015-09-34");
       var_dump($res);

   Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

       object(DateTimeImmutable)#1 (3) {
         ["date"]=>
         string(26) "2015-10-04 17:24:43.000000"
         ["timezone_type"]=>
         int(3)
         ["timezone"]=>
         string(13) "Europe/London"
       }

## Zeitformate

Diese Seite beschreibt die verschiedenen Zeitformate in einem BNF-ähnlichen Format, das der Parser von DateTimeImmutable, DateTime, date_create(), date_create_immutable() und strtotime() versteht.

Die Formatierung von DateTimeImmutable- und DateTime-Objekten wird in der Dokumentation zur Methode DateTimeInterface::format() beschrieben.

Verwendete Symbole
Beschreibung | Formate | Beispiele
--- | --- | ---
`frac` (Bruchteil) | . [0-9]+ | ".21342", ".85"
`hh` (Stunden im 12-Stunden-Format) | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` (Stunden im 24-Stunden-Format) | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridian` (a.m.=vormittags oder p.m.=nachmittags) | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`MM` (Minuten; mit vorangestellter Null) | [0-5][0-9] | "00", "12", "59"
`II` (Sekunden; mit vorangestellter Null) | [0-5][0-9] | "00", "12", "59"
`space` (Leer- und Tabulatorzeichen) | [ \t] |
`tz` (Zeitzone) | "("? [A-Za-z]{1,6} ")"? | [A-Z][a-z]+([_/][A-Z][a-z]+)+ | "CEST", "Europe/Amsterdam", "America/Indiana/Knox"
`tzcorrection` (Zeitverschiebung) | "GMT"? [+-] `hh` ":"? `MM`? | "+0400", "GMT-07:00", "-07:00"

12-Stunden-Schreibweise
Beschreibung | Format | Beispiele
--- | --- | ---
Nur die Stunde mit Meridian | `hh` `space`? `meridian` | "4 am", "5PM"
Stunde und Minuten; mit Meridian | `hh` [.:] `MM` `space`? `meridian` | "4:08 am", "7:19P.M."
Stunde, Minuten und Sekunden; mit Meridian | `hh` [.:] `MM` [.:] `II` `space`? `meridian` | "4:08:37 am", "7:19:19P.M."
MS SQL (Stunde, Minuten, Sekunden und Bruchteil; mit Meridian) | `hh` ":" `MM` ":" `II` [.:] [0-9]+ `meridian` | "4:08:39:12313am"

24-Stunden-Schreibweise
Beschreibung | Format | Beispiele
--- | --- | ---
Stunde und Minuten | 't'? `HH` [.:] `MM` | "04:08", "19.19", "T23:43"
Stunde und Minuten; ohne Doppelpunkt | 't'? `HH` `MM` | "0408", "t1919", "T2343"
Stunde, Minuten und Sekunden | 't'? `HH` [.:] `MM` [.:] `II` | "04.08.37", "t19:19:19"
Stunde, Minuten und Sekunden; ohne Doppelpunkt | 't'? `HH` `MM` `II` | "040837", "T191919"
Stunde, Minuten, Sekunden und Zeitzone | 't'? `HH` [.:] `MM` [.:] `II` `space`? ( `tzcorrection` | `tz` ) | "040837CEST", "T191919-0700"
Stunde, Minuten, Sekunden und Bruchteil | 't'? `HH` [.:] `MM` [.:] `II` `frac` | "04.08.37.81412", "19:19:19.532453"
Informationen über die Zeitzone | `tz` | `tzcorrection` | "CEST", "Europe/Amsterdam", "+0430", "GMT-06:00"

## Datumsformate

Diese Seite beschreibt die verschiedenen Datumsformate in einem BNF-ähnlichen Format, das der Parser von DateTimeImmutable, DateTime, date_create(), date_create_immutable() und strtotime() versteht.

Die Formatierung von DateTimeImmutable- und DateTime-Objekten wird in der Dokumentation zur Methode DateTimeInterface::format() beschrieben.

Verwendete Symbole
Beschreibung | Format | Beispiele
--- | --- | ---
`daysuf` (Suffix für einen Tag des Monats) | "st" | "nd" | "rd" | "th" |
`dd` (Tag des Monats; ohne vorangestellte Null) | ([0-2]?[0-9] | "3"[01]) `daysuf`? | "7th", "22nd", "31"
`DD` (Tag des Monats; zwei Ziffern mit vorangestellter Null) | "0" [0-9] | [1-2][0-9] | "3" [01] | "07", "31"
`m` (vollständiger oder abgekürzter Monatsname) | 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' | "I" | "II" | "III" | "IV" | "V" | "VI" | "VII" | "VIII" | "IX" | "X" | "XI" | "XII" |
`M` (Monatskürzel) | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`mm` (Nummer des Monats) | "0"? [0-9] | "1"[0-2] | "0", "04", "7", "12"
`MM` (Nummer des Monats; mit vorangestellter Null) | "0" [0-9] | "1"[0-2] | "00", "04", "07", "12"
`y` (Jahr) | [0-9]{1,4} | "00", "78", "08", "8", "2008"
`yy` (Jahr; zwei Ziffern) | [0-9]{2} | "00", "08", "78"
`YY` (Jahr; vier Ziffern) | [0-9]{4} | "2000", "2008", "1978"
`YYY` (Jahr; erweitert, 5-19 Ziffern) | [0-9]{5,19} | "81412", "20192"

Lokalisierte Schreibweisen
Beschreibung | Format | Beispiele
--- | --- | ---
Monat und Tag; amerikanische Schreibweise | `mm` "/" `dd` | "5/12", "10/27"
Monat, Tag und Jahr; amerikanische Schreibweise | `mm` "/" `dd` "/" `y` | "12/22/78", "1/17/2006", "1/17/6"
Jahr (vier Ziffern), Monat und Tag; getrennt durch Schrägstriche | `YY` "/" `mm` "/" `dd` | "2008/6/30", "1978/12/22"
Jahr (vier Ziffern) und Monat (GNU) | `YY` "-" `mm` | "2008-6", "2008-06", "1978-12"
Jahr, Monat und Tag; getrennt durch Bindestriche | `y` "-" `mm` "-" `dd` | "2008-6-30", "78-12-22", "8-6-21"
Tag, Monat und Jahr (vier Ziffern); getrennt durch Punkte, Tabulatorzeichen oder Bindestriche | `dd` [.\t-] `mm` [.-] `YY` | "30-6-2008", "22.12.1978"
Tag, Monat und Jahr (zwei Ziffern); getrennt durch Punkte oder Tabulatorzeichen | `dd` [.\t] `mm` "." `yy` | "30.6.08", "22\t12.78"
Tag, Monat (textuell) und Jahr | `dd` ([ \t.-])* `m` ([ \t.-])* `y` | "30-June 2008", "22DEC78", "14 III 1879"
Monat (textuell) und Jahr (vier Ziffern); der Tag wird auf den 1. zurückgesetzt | `m` ([ \t.-])* `YY` | "June 2008", "DEC1978", "March 1879"
Jahr (vier Ziffern) und Monat (textuell); der Tag wird auf den 1. zurückgesetzt | `YY` ([ \t.-])* `m` | "2008 June", "1978-XII", "1879.MArCH"
Monat (textuell), Tag und Jahr | `m` ([ .\t-])* `dd` [,.stndrh\t ]+ `y` | "July 1st, 2008", "April 17, 1790", "May.9,78"
Monat (textuell) und Tag | `m` ([ .\t-])* `dd` [,.stndrh\t ]* | "July 1st,", "Apr 17", "May.9"
Tag und Monat (textuell) | `dd` ([ .\t-])* `m` | "1 July", "17 Apr", "9.May"
Monatskürzel, Tag und Jahr | `M` "-" `DD` "-" `y` | "May-09-78", "Apr-17-1790"
Jahr, Monatskürzel und Tag | `y` "-" `M` "-" `DD` | "78-Dec-22", "1814-MAY-17"
Jahr (und zwar nur das Jahr) | `YY` | "1978", "2008"
Jahr (erweitert; 5-19 Ziffern mit Vorzeichen) | [+-] `YYY` | "-81120", "+20192"
Monat (textuell) (und zwar nur der Monat) | `m` | "March", "jun", "DEC"

Schreibweisen nach ISO8601
Beschreibung | Format | Beispiele
--- | --- | ---
Acht Ziffern für Jahr, Monat und Tag | `YY` `MM` `DD` | "15810726", "19780417", "18140517"
Jahr (vier Ziffern), Monat und Tag; getrennt durch Schrägstriche | `YY` "/" `MM` "/" `DD` | "2008/06/30", "1978/12/22"
Jahr (zwei Ziffern), Monat und Tag; getrennt durch Schrägstriche | `yy` "-" `MM` "-" `DD` | "08-06-30", "78-12-22"
Jahr (vier Ziffern, optional mit Vorzeichen), Monat und Tag | [+-]? `YY` "-" `MM` "-" `DD` | "-0002-07-26", "+1978-04-17", "1814-05-17"
Jahr (5+ Ziffern mit erforderlichem Vorzeichen), Monat und Tag | [+-] `YYY` "-" `MM` "-" `DD` | "-81120-02-26", "+20192-04-17"

> Hinweis:

> Bei den Formaten `y` und `yy` werden Jahreszahlen unter 100 auf besondere Weise behandelt. Liegt die Jahreszahl im Bereich 0-69 (einschließlich), wird 2000 addiert, liegt sie im Bereich 70-99 (einschließlich), wird 1900 addiert. Das bedeutet, dass "00-01-01" als "2000-01-01" interpretiert wird.

> Hinweis:

> Das Format "Tag, Monat und Jahr (zwei Ziffern); getrennt durch Punkte oder Tabulatorzeichen" (`dd` [.\t] `mm` ". " `yy`) funktioniert nur für Jahre im Bereich 61-99 (einschließlich). Außerhalb dieses Bereichs hat das Zeitformat "`HH` [.:] `MM` [.:] `SS`" Vorrang.

> Hinweis:

> Das Format "Jahr (und zwar nur das Jahr)" funktioniert nur dann zuverlässig, wenn die Zeitangabe bereits gefunden wurde. Andernfalls, wenn das vierstellige Jahr als `HH` `MM` interpretiert werden kann, werden stattdessen diese beiden Datumselemente gesetzt.

> Damit konsistent nur ein Jahreswert interpretiert wird, sollte DateTimeImmutable::createFromFormat() mit dem Spezifizierer `Y` verwendet werden.

Achtung

Es ist möglich, die Formate `dd` und `DD` zu über- oder unterschreiten. Dabei bezeichnet der Tag 0 den letzten Tag des vorherigen Monats, während eine Überschreitung zum nächsten Monat gezählt wird. Somit entspricht "2008-08-00" dem "2008-07-31" und "2008-06-31" dem "2008-07-01" (der Juni hat nur 30 Tage).

Wie aus dem obigen regulären Ausdruck hervorgeht, ist der Wertebereich für den Tag auf 0-31 beschränkt. So ist z. B. "2008-06-32" keine gültige Datumsangabe.

Es ist auch möglich, die Formate `mm` und `MM` mit dem Wert 0 zu unterschreiten. Dabei steht der Monat 0 für den Dezember des Vorjahres. Zum Beispiel ist "2008-00-22" gleichbedeutend mit "2007-12-22".

Wenn die beiden vorherigen Fälle kombiniert werden und sowohl der Tag als auch der Monat unterlaufen werden, geschieht Folgendes: "2008-00-00" wird zunächst in "2007-12-00" umgewandelt, das dann in "2007-11-30" umgewandelt wird. Dies geschieht auch mit der Zeichenkette "0000-00-00", die in "-0001-11-30" umgewandelt wird (das Jahr -1 im ISO 8601-Kalender, das dem Jahr 2 vor Christus im proleptischen gregorianischen Kalender entspricht).

## Zusammengesetzte Formate

Diese Seite beschreibt die verschiedenen zusammengesetzten Datums- und Zeitformate in einem BNF-ähnlichen Format, das der Parser von DateTimeImmutable, DateTime, date_create(), date_create_immutable() und strtotime() versteht.

Die Formatierung von DateTimeImmutable- und DateTime-Objekten wird in der Dokumentation zur Methode DateTimeInterface::format() beschrieben.

Verwendete Symbole
Beschreibung | Formate | Beispiele
--- | --- | ---
`DD` (Tag des Monats; zwei Ziffern mit vorangestellter Null) | "0" [0-9] | [1-2][0-9] | "3" [01] | "02", "12", "31"
`doy` (Tag des Jahres; drei Ziffern) | "00"[1-9] | "0"[1-9][0-9] | [1-2][0-9][0-9] | "3"[0-5][0-9] | "36"[0-6] | "001", "012", "180", "350", "366"
`frac` (Bruchteil) | . [0-9]+ | ".21342", ".85"
`hh` (Stunden im 12-Stunden-Format) | "0"?[1-9] | "1"[0-2] | "04", "7", "12"
`HH` (Stunden im 24-Stunden-Format) | [01][0-9] | "2"[0-4] | "04", "07", "19"
`meridian` (a.m.=vormittags oder p.m.=nachmittags) | [AaPp] .? [Mm] .? [\0\t ] | "A.m.", "pM", "am."
`ii` (Minuten) | [0-5]?[0-9] | "04", "8", "59"
`II` (Minuten; mit vorangestellter Null) | [0-5][0-9] | "04", "08", "59"
`M` (Monatskürzel) | 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' |
`MM` (Nummer des Monats; mit vorangestellter Null) | [0-1][0-9] | "00", "12"
`space` (Leer- und Tabulatorzeichen) | [ \t] |
`ss` (Sekunden) | ([0-5]?[0-9])|60 | "04", "8", "59", "60" (Schaltsekunde)
`SS` (Sekunden; mit vorangestellter Null) | [0-5][0-9] | "04", "08", "59"
`W` (Woche des Jahres) | "0"[1-9] | [1-4][0-9] | "5"[0-3] | "05", "17", "53"
`tzcorrection` (Zeitverschiebung) | "GMT"? [+-] `hh` ":"? `II`? | "+0400", "GMT-07:00", "-07:00"
`YY` (Jahr; vier Ziffern) | [0-9]{4} | "2000", "2008", "1978"

Standardformate
Beschreibung | Beispiele
--- | ---
ATOM | "2022-06-02T16:58:35+00:00"
COOKIE | "Thursday, 02-Jun-2022 16:58:35 UTC"
ISO8601 | "2022-06-02T16:58:35+0000"
» RFC 822 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 850 | "Thursday, 02-Jun-22 16:58:35 UTC"
» RFC 1036 | "Thu, 02 Jun 22 16:58:35 +0000"
» RFC 1123 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 2822 | "Thu, 02 Jun 2022 16:58:35 +0000"
» RFC 3339 | "2022-06-02T16:58:35+00:00"
» RFC 3339 Erweitert | "2022-06-02T16:58:35.698+00:00"
» RFC 7231 | "Thu, 02 Jun 2022 16:58:35 GMT"
RSS | "Thu, 02 Jun 2022 16:58:35 +0000"
W3C | "2022-06-02T16:58:35+00:00"

Lokalisierte Schreibweisen
Beschreibung | Format | Beispiele
--- | --- | ---
Gebräuchliches Protokollformat | `dd` "/" `M` "/" `YY` : `HH` ":" `II` ":" `SS` `space` `tzcorrection` | "10/Oct/2000:13:55:36 -0700"
EXIF | `YY` ":" `MM` ":" `DD` " " `HH` ":" `II` ":" `SS` | "2008:08:07 18:11:31"
ISO-Jahr mit ISO-Woche | `YY` "-"? "W" `W` | "2008W27", "2008-W28"
ISO-Jahr mit ISO-Woche und -Tag | `YY` "-"? "W" `W` "-"? [0-7] | "2008W273", "2008-W28-3"
MySQL | `YY` "-" `MM` "-" `DD` " " `HH` ":" `II` ":" `SS` | "2008-08-07 18:11:31"
PostgreSQL: Jahr mit Tag des Jahres | `YY` "."? `doy` | "2008.197", "2008197"
SOAP | `YY` "-" `MM` "-" `DD` "T" `HH` ":" `II` ":" `SS` `frac` `tzcorrection`? | "2008-07-01T22:35:17.02", "2008-07-01T22:35:17.03+08:00"
Unix-Zeitstempel | "@" "-"? [0-9]+ | "@1215282385"
Unix-Zeitstempel mit Mikrosekunden | "@" "-"? [0-9]+ "." [0-9]{0,6} | "@1607974647.503686"
XMLRPC | `YY` `MM` `DD` "T" `hh` ":" `II` ":" `SS` | "20080701T22:38:07", "20080701T9:38:07"
XMLRPC (kompakt) | `YY` `MM` `DD` 't' `hh` `II` `SS` | "20080701t223807", "20080701T093807"
WDDX | `YY` "-" `mm` "-" `dd` "T" `hh` ":" `ii` ":" `ss` | "2008-7-1T9:3:37"

> Hinweis:

> Beim "W" in den Formaten "ISO-Jahr mit ISO-Woche" und "ISO-Jahr mit ISO-Woche und -Tag" wird zwischen Groß- und Kleinschreibung unterschieden, d. h. es darf nur ein großes "W" verwendet werden.

> Beim "T" in den Formaten SOAP, XMLRPC und WDDX wird zwischen Groß- und Kleinschreibung unterschieden, d. h. es darf nur ein großes "T" verwendet werden.

> Das Format "Unix-Zeitstempel" setzt die Zeitzone auf UTC.

## Relative Formate

Diese Seite beschreibt die verschiedenen relativen Datums- und Zeitformate in einem BNF-ähnlichen Format, das der Parser von DateTimeImmutable, DateTime, date_create(), date_create_immutable() und strtotime() versteht.

Die Formatierung von DateTimeImmutable- und DateTime-Objekten wird in der Dokumentation zur Methode DateTimeInterface::format() beschrieben.

Verwendete Symbole
Beschreibung | Format
--- | ---
`dayname` (Name eines Tages) | 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
`daytext` (Intervalle in Wochen) | 'weekday' | 'weekdays'
`number` | [+-]?[0-9]+
`ordinal` (Ordnungszahlen und Indizes) | 'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | 'next' | 'last' | 'previous' | 'this'
`reltext` (Zeiger) | 'next' | 'last' | 'previous' | 'this'
`space` (Leer- und Tabulatorzeichen) | [ \t]+
`unit` (Intervalle) | 'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond' | 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | `daytext`

Tagesbezogene Schreibweisen
Format | Beschreibung | Beispiele
--- | --- | ---
'yesterday' | Mitternacht von gestern | "yesterday 14:00"
'midnight' | Die Zeit wird auf 00:00:00 gesetzt |
'today' | Die Zeit wird auf 00:00:00 gesetzt |
'now' | Jetzt - dies wird einfach ignoriert |
'noon' | Die Zeit wird auf 12:00:00 gesetzt | "yesterday noon"
'tomorrow' | Mitternacht von morgen |
'back of' `hour` | 15 Minuten nach der angegebenen Stunde | "back of 7pm", "back of 15"
'front of' `hour` | 15 Minuten vor der angegebenen Stunde | "front of 5am", "front of 23"
'first day of' | Wird auf den ersten Tag des aktuellen Monats gesetzt. Da dies nur den aktuellen Monat betrifft, ist es in der Regel am besten, dieses Format gefolgt vom Namen des Monats zu verwenden. | "first day of January 2008"
'last day of' | Wird auf den letzten Tag des aktuellen Monats gesetzt. Da dies nur den aktuellen Monat betrifft, ist es in der Regel am besten, dieses Format gefolgt vom Namen des Monats zu verwenden. | "last day of next month"
`ordinal` `space` `dayname` `space` 'of' | Berechnet den `x`-ten Wochentag des aktuellen Monats. | "first sat of July 2008"
'last' `space` `dayname` `space` 'of' | Berechnet den letzten Wochentag des aktuellen Monats. | "last sat of July 2008"
`number` `space`? (`unit` | 'week') | Verarbeitet relative Zeitelemente, deren Wert eine Zahl ist. | "+5 weeks", "12 day", "-7 weekdays"
`ordinal` `space` `unit` | Verarbeitet relative Zeitelemente, deren Wert ein Text ist. `last` und `previous` entsprechen `-1`, `this` entspricht nichts, und `next` entspricht `+1`. | "fifth day", "second month", "last day", "previous year"
'ago' | Kehrt alle Werte der zuvor gefundenen relativen Zeitpunkte um. | "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago"
`dayname` | Springt zum nächsten Tag mit diesem Namen (siehe Hinweis). | "Monday"
`reltext` `space` 'week' | Verarbeitet das spezielle Format "Wochentag + letzte/diese/nächste Woche". | "Monday next week"

> Hinweis:

> Relative Angaben werden immer nach nicht-relativen Angaben verarbeitet. Das bedeutet, dass "+1 week july 2008" und "july 2008 +1 week" gleichwertig sind.

> Ausnahmen von dieser Regel sind: "yesterday", "midnight", "today", "noon" und "tomorrow". Zu beachten ist, dass sich "tomorrow 11:00" und "11:00 tomorrow" unterscheiden. Angenommen, das heutige Datum ist "23. Juli 2008", dann gibt die erste Variante "2008-07-24 11:00" zurück, während die zweite Variante "2008-07-24 00:00" zurückgibt. Der Grund für dieses Verhalten ist, dass sich diese fünf Ausdrücke direkt auf die aktuelle Zeit auswirken.

> Schlüsselwörter wie "first day of" hängen vom Zusammenhang ab, in dem die relative Formatierung verwendet wird. Wenn sie in einer statischen Methode oder Funktion verwendet wird, ist der Referenzpunkt der aktuelle Zeitstempel des Systems. Wenn sie jedoch in DateTime::modify() oder DateTimeImmutable::modify() verwendet wird, bezieht sie sich auf das Objekt, für das die Methode `modify()` aufgerufen wird.

> Hinweis:

> Wenn der in der Zeichenkette für Datum und Uhrzeit verwendete Wochentag mit dem aktuellen Wochentag übereinstimmt, sind die folgenden Hinweise zu beachten. Der aktuelle Wochentag kann auch aus nicht-relativen Teilen der Zeichenkette (neu) berechnet worden sein.

> 1. "`dayname`" rückt nicht auf einen anderen Tag vor (Beispiel: "Wed July 23rd, 2008" bedeutet "2008-07-23").
> 2. "`number` `dayname`" rückt nicht auf einen anderen Tag vor (Beispiel: "1 wednesday july 23rd, 2008" bedeutet "2008-07-23").
> 3. "`number` week `dayname`" fügt zuerst die Anzahl der Wochen hinzu, rückt aber nicht auf einen anderen Tag vor. In diesem Fall sind "`number` week" und "`dayname`" zwei getrennte Blöcke (Beispiel: "+1 week wednesday july 23rd, 2008" bedeutet "2008-07-30").
> 4. "`ordinal` `dayname`" rückt auf einen anderen Tag vor (Beispiel "first wednesday july 23rd, 2008" bedeutet "2008-07-30").
> 5. "`number` week `ordinal` `dayname`" fügt zuerst die Anzahl der Wochen hinzu und rückt dann auf einen anderen Tag vor. In diesem Fall sind "`number` week" und "`ordinal` `dayname`" zwei getrennte Blöcke (Beispiel: "+1 week first wednesday july 23rd, 2008" bedeutet "2008-08-06").
> 6. "`ordinal` `dayname` 'of' " rückt nicht auf einen anderen Tag vor (Beispiel: "first wednesday of july 23rd, 2008" bedeutet "2008-07-02", weil die spezifische Formulierung mit 'of' den Tag des Monats auf '1' zurücksetzt und das "23rd" hier ignoriert wird).

> Zu beachten ist auch, dass das "of" in "`ordinal` `space` `dayname` `space` 'of' " und "'last' `space` `dayname` `space` 'of' " etwas Besonderes bewirkt.

> 1. Es setzt den Tag des Monats auf 1.
> 2. "`ordinal` `dayname` 'of' " rückt nicht auf einen anderen Tag vor (Beispiel: "first tuesday of july 2008" bedeutet "2008-07-01").
> 3. "`ordinal` `dayname` " rückt nicht auf einen anderen Tag vor (Beispiel: "first tuesday july 2008" bedeutet "2008-07-08", siehe auch Punkt 4 in obiger Liste).
> 4. "'last' `dayname` 'of' " gibt den letzten `dayname` des aktuellen Monats zurück (Beispiel: "last wed of july 2008" bedeutet "2008-07-30")
> 5. "'last' `dayname`" gibt den letzten `dayname` vor dem aktuellen Tag zurück (Beispiel: "last wed july 2008" bedeutet "2008-06-25"; "july 2008" setzt zuerst das aktuelle Datum auf "2008-07-01" und mit "last wed" verschiebt sich das Datum auf den vorherigen Mittwoch, d. h. auf den "2008-06-25").

> Hinweis:

> Relative Monatswerte werden auf der Grundlage der Länge der Monate berechnet, die sie durchlaufen. Ein Beispiel wäre "+2 month 2011-11-30", was "2012-01-30" ergeben würde. Das liegt daran, dass der November 30 Tage hat und der Dezember 31 Tage, was insgesamt 61 Tage ergibt.

> Hinweis:

> `number` ist eine ganzzahlige Zahl; wenn eine Dezimalzahl angegeben wird, wird der Punkt (oder das Komma) in der Regel als Begrenzungszeichen interpretiert. Zum Beispiel wird `'+1.5 hours'` als `'+1 5 hours'` interpretiert und nicht als `'+1 hour +30 minutes'`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `number` akzeptiert nun wieder ein Pluszeichen gefolgt von einem Minuszeichen, z. B. `+-2` und andere Kombinationen von mehreren Zeichen.
8.2.0 | `number` akzeptiert kein Pluszeichen gefolgt von einem Minuszeichen mehr, z. B. `+-2`.
7.0.8 | Wochen beginnen immer am Montag. Bisher galt auch der Sonntag als Wochenbeginn.

# Liste unterstützter Zeitzonen

## Inhaltsverzeichnis

- Afrika
- Amerika
- Antarktis
- Arktis
- Asien
- Atlantisch
- Australien
- Europa
- Indisch
- Pazifisch
- Andere

Hier finden Sie die vollständige Liste aller von PHP unterstützen Zeitzonen, wie sie z.b mit date_default_timezone_set() genutzt werden können.

> Hinweis: Die jeweils aktuellste Version der Zeitzonendatenbank kann über das » timezonedb-Paket in PECL installiert werden. Für Windows existiert eine vorkompilierte DLL auf der PECL4Win-Seite: php_timezonedb.dll.

> Hinweis: Diese Liste basiert auf der Version der Zeitzonen-Datenbank 2026.1.

## Afrika

Afrika
Africa/Abidjan | Africa/Accra | Africa/Addis_Ababa | Africa/Algiers
Africa/Asmara | Africa/Bamako | Africa/Bangui | Africa/Banjul
Africa/Bissau | Africa/Blantyre | Africa/Brazzaville | Africa/Bujumbura
Africa/Cairo | Africa/Casablanca | Africa/Ceuta | Africa/Conakry
Africa/Dakar | Africa/Dar_es_Salaam | Africa/Djibouti | Africa/Douala
Africa/El_Aaiun | Africa/Freetown | Africa/Gaborone | Africa/Harare
Africa/Johannesburg | Africa/Juba | Africa/Kampala | Africa/Khartoum
Africa/Kigali | Africa/Kinshasa | Africa/Lagos | Africa/Libreville
Africa/Lome | Africa/Luanda | Africa/Lubumbashi | Africa/Lusaka
Africa/Malabo | Africa/Maputo | Africa/Maseru | Africa/Mbabane
Africa/Mogadishu | Africa/Monrovia | Africa/Nairobi | Africa/Ndjamena
Africa/Niamey | Africa/Nouakchott | Africa/Ouagadougou | Africa/Porto-Novo
Africa/Sao_Tome | Africa/Tripoli | Africa/Tunis | Africa/Windhoek

## Amerika

Amerika
America/Adak | America/Anchorage | America/Anguilla | America/Antigua
America/Araguaina | America/Argentina/Buenos_Aires | America/Argentina/Catamarca | America/Argentina/Cordoba
America/Argentina/Jujuy | America/Argentina/La_Rioja | America/Argentina/Mendoza | America/Argentina/Rio_Gallegos
America/Argentina/Salta | America/Argentina/San_Juan | America/Argentina/San_Luis | America/Argentina/Tucuman
America/Argentina/Ushuaia | America/Aruba | America/Asuncion | America/Atikokan
America/Bahia | America/Bahia_Banderas | America/Barbados | America/Belem
America/Belize | America/Blanc-Sablon | America/Boa_Vista | America/Bogota
America/Boise | America/Cambridge_Bay | America/Campo_Grande | America/Cancun
America/Caracas | America/Cayenne | America/Cayman | America/Chicago
America/Chihuahua | America/Ciudad_Juarez | America/Costa_Rica | America/Coyhaique
America/Creston | America/Cuiaba | America/Curacao | America/Danmarkshavn
America/Dawson | America/Dawson_Creek | America/Denver | America/Detroit
America/Dominica | America/Edmonton | America/Eirunepe | America/El_Salvador
America/Fort_Nelson | America/Fortaleza | America/Glace_Bay | America/Goose_Bay
America/Grand_Turk | America/Grenada | America/Guadeloupe | America/Guatemala
America/Guayaquil | America/Guyana | America/Halifax | America/Havana
America/Hermosillo | America/Indiana/Indianapolis | America/Indiana/Knox | America/Indiana/Marengo
America/Indiana/Petersburg | America/Indiana/Tell_City | America/Indiana/Vevay | America/Indiana/Vincennes
America/Indiana/Winamac | America/Inuvik | America/Iqaluit | America/Jamaica
America/Juneau | America/Kentucky/Louisville | America/Kentucky/Monticello | America/Kralendijk
America/La_Paz | America/Lima | America/Los_Angeles | America/Lower_Princes
America/Maceio | America/Managua | America/Manaus | America/Marigot
America/Martinique | America/Matamoros | America/Mazatlan | America/Menominee
America/Merida | America/Metlakatla | America/Mexico_City | America/Miquelon
America/Moncton | America/Monterrey | America/Montevideo | America/Montserrat
America/Nassau | America/New_York | America/Nome | America/Noronha
America/North_Dakota/Beulah | America/North_Dakota/Center | America/North_Dakota/New_Salem | America/Nuuk
America/Ojinaga | America/Panama | America/Paramaribo | America/Phoenix
America/Port-au-Prince | America/Port_of_Spain | America/Porto_Velho | America/Puerto_Rico
America/Punta_Arenas | America/Rankin_Inlet | America/Recife | America/Regina
America/Resolute | America/Rio_Branco | America/Santarem | America/Santiago
America/Santo_Domingo | America/Sao_Paulo | America/Scoresbysund | America/Sitka
America/St_Barthelemy | America/St_Johns | America/St_Kitts | America/St_Lucia
America/St_Thomas | America/St_Vincent | America/Swift_Current | America/Tegucigalpa
America/Thule | America/Tijuana | America/Toronto | America/Tortola
America/Vancouver | America/Whitehorse | America/Winnipeg | America/Yakutat

## Antarktis

Antarktis
Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie
Antarctica/Mawson | Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera
Antarctica/Syowa | Antarctica/Troll | Antarctica/Vostok |

## Arktis

Arktis
Arctic/Longyearbyen

## Asien

Asien
Asia/Aden | Asia/Almaty | Asia/Amman | Asia/Anadyr
Asia/Aqtau | Asia/Aqtobe | Asia/Ashgabat | Asia/Atyrau
Asia/Baghdad | Asia/Bahrain | Asia/Baku | Asia/Bangkok
Asia/Barnaul | Asia/Beirut | Asia/Bishkek | Asia/Brunei
Asia/Chita | Asia/Colombo | Asia/Damascus | Asia/Dhaka
Asia/Dili | Asia/Dubai | Asia/Dushanbe | Asia/Famagusta
Asia/Gaza | Asia/Hebron | Asia/Ho_Chi_Minh | Asia/Hong_Kong
Asia/Hovd | Asia/Irkutsk | Asia/Jakarta | Asia/Jayapura
Asia/Jerusalem | Asia/Kabul | Asia/Kamchatka | Asia/Karachi
Asia/Kathmandu | Asia/Khandyga | Asia/Kolkata | Asia/Krasnoyarsk
Asia/Kuala_Lumpur | Asia/Kuching | Asia/Kuwait | Asia/Macau
Asia/Magadan | Asia/Makassar | Asia/Manila | Asia/Muscat
Asia/Nicosia | Asia/Novokuznetsk | Asia/Novosibirsk | Asia/Omsk
Asia/Oral | Asia/Phnom_Penh | Asia/Pontianak | Asia/Pyongyang
Asia/Qatar | Asia/Qostanay | Asia/Qyzylorda | Asia/Riyadh
Asia/Sakhalin | Asia/Samarkand | Asia/Seoul | Asia/Shanghai
Asia/Singapore | Asia/Srednekolymsk | Asia/Taipei | Asia/Tashkent
Asia/Tbilisi | Asia/Tehran | Asia/Thimphu | Asia/Tokyo
Asia/Tomsk | Asia/Ulaanbaatar | Asia/Urumqi | Asia/Ust-Nera
Asia/Vientiane | Asia/Vladivostok | Asia/Yakutsk | Asia/Yangon
Asia/Yekaterinburg | Asia/Yerevan |  |

## Atlantisch

Atlantisch
Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde
Atlantic/Faroe | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia
Atlantic/St_Helena | Atlantic/Stanley |  |

## Australien

Australien
Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Darwin
Australia/Eucla | Australia/Hobart | Australia/Lindeman | Australia/Lord_Howe
Australia/Melbourne | Australia/Perth | Australia/Sydney |

## Europa

Europa
Europe/Amsterdam | Europe/Andorra | Europe/Astrakhan | Europe/Athens
Europe/Belgrade | Europe/Berlin | Europe/Bratislava | Europe/Brussels
Europe/Bucharest | Europe/Budapest | Europe/Busingen | Europe/Chisinau
Europe/Copenhagen | Europe/Dublin | Europe/Gibraltar | Europe/Guernsey
Europe/Helsinki | Europe/Isle_of_Man | Europe/Istanbul | Europe/Jersey
Europe/Kaliningrad | Europe/Kirov | Europe/Kyiv | Europe/Lisbon
Europe/Ljubljana | Europe/London | Europe/Luxembourg | Europe/Madrid
Europe/Malta | Europe/Mariehamn | Europe/Minsk | Europe/Monaco
Europe/Moscow | Europe/Oslo | Europe/Paris | Europe/Podgorica
Europe/Prague | Europe/Riga | Europe/Rome | Europe/Samara
Europe/San_Marino | Europe/Sarajevo | Europe/Saratov | Europe/Simferopol
Europe/Skopje | Europe/Sofia | Europe/Stockholm | Europe/Tallinn
Europe/Tirane | Europe/Ulyanovsk | Europe/Vaduz | Europe/Vatican
Europe/Vienna | Europe/Vilnius | Europe/Volgograd | Europe/Warsaw
Europe/Zagreb | Europe/Zurich |  |

## Indisch

Indisch
Indian/Antananarivo | Indian/Chagos | Indian/Christmas | Indian/Cocos
Indian/Comoro | Indian/Kerguelen | Indian/Mahe | Indian/Maldives
Indian/Mauritius | Indian/Mayotte | Indian/Reunion |

## Pazifisch

Pazifisch
Pacific/Apia | Pacific/Auckland | Pacific/Bougainville | Pacific/Chatham
Pacific/Chuuk | Pacific/Easter | Pacific/Efate | Pacific/Fakaofo
Pacific/Fiji | Pacific/Funafuti | Pacific/Galapagos | Pacific/Gambier
Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Kanton
Pacific/Kiritimati | Pacific/Kosrae | Pacific/Kwajalein | Pacific/Majuro
Pacific/Marquesas | Pacific/Midway | Pacific/Nauru | Pacific/Niue
Pacific/Norfolk | Pacific/Noumea | Pacific/Pago_Pago | Pacific/Palau
Pacific/Pitcairn | Pacific/Pohnpei | Pacific/Port_Moresby | Pacific/Rarotonga
Pacific/Saipan | Pacific/Tahiti | Pacific/Tarawa | Pacific/Tongatapu
Pacific/Wake | Pacific/Wallis |  |

## Andere

Warnung

Die folgenden Zeitzonen (mit Ausnahme von UTC) existieren nur aus Gründen der Rückwärtskompatibilität und sollten nicht mehr benutzt werden, da sie sich fehlerhaft verhalten können. Außerdem können diese Zeitzonen jederzeit aus der IANA-Zeitzonendatenbank entfernt werden.

Warnung

Falls Sie die obige Warnung außer Acht lassen beachten Sie bitte, dass die IANA-Datenbank, die die Unterstützung für Zeitzonen für PHP bereitstellt, die Vorzeichen in POSIX-Stil verwendet. Dies kann dazu führen, dass die Angaben von Zeitzonen als `Etc/GMT+n` und `Etc/GMT-n` umgekehrt zur geläufigen Angabe ist.

Die Zeitzone 8 Stunden vor GMT, welche unter anderem in China und Westaustralien verwendet wird, ist beispielsweise `Etc/GMT-8` in dieser Datenbank statt `Etc/GMT+8` die man üblicherweise erwarten würde.

Es wird daher nochmals empfohlen die für den jeweiligen Standort korrekte Zeitzone zu verwenden, beispielsweise `Asia/Shanghai` oder `Australia/Perth` für das obige Beispiel.

Andere
Africa/Asmera | Africa/Timbuktu | America/Argentina/ComodRivadavia | America/Atka
America/Buenos_Aires | America/Catamarca | America/Coral_Harbour | America/Cordoba
America/Ensenada | America/Fort_Wayne | America/Godthab | America/Indianapolis
America/Jujuy | America/Knox_IN | America/Louisville | America/Mendoza
America/Montreal | America/Nipigon | America/Pangnirtung | America/Porto_Acre
America/Rainy_River | America/Rosario | America/Santa_Isabel | America/Shiprock
America/Thunder_Bay | America/Virgin | America/Yellowknife | Antarctica/South_Pole
Asia/Ashkhabad | Asia/Calcutta | Asia/Choibalsan | Asia/Chongqing
Asia/Chungking | Asia/Dacca | Asia/Harbin | Asia/Istanbul
Asia/Kashgar | Asia/Katmandu | Asia/Macao | Asia/Rangoon
Asia/Saigon | Asia/Tel_Aviv | Asia/Thimbu | Asia/Ujung_Pandang
Asia/Ulan_Bator | Atlantic/Faeroe | Atlantic/Jan_Mayen | Australia/ACT
Australia/Canberra | Australia/Currie | Australia/LHI | Australia/North
Australia/NSW | Australia/Queensland | Australia/South | Australia/Tasmania
Australia/Victoria | Australia/West | Australia/Yancowinna | Brazil/Acre
Brazil/DeNoronha | Brazil/East | Brazil/West | Canada/Atlantic
Canada/Central | Canada/Eastern | Canada/Mountain | Canada/Newfoundland
Canada/Pacific | Canada/Saskatchewan | Canada/Yukon | CET
Chile/Continental | Chile/EasterIsland | CST6CDT | Cuba
EET | Egypt | Eire | EST
EST5EDT | Etc/GMT | Etc/GMT+0 | Etc/GMT+1
Etc/GMT+10 | Etc/GMT+11 | Etc/GMT+12 | Etc/GMT+2
Etc/GMT+3 | Etc/GMT+4 | Etc/GMT+5 | Etc/GMT+6
Etc/GMT+7 | Etc/GMT+8 | Etc/GMT+9 | Etc/GMT-0
Etc/GMT-1 | Etc/GMT-10 | Etc/GMT-11 | Etc/GMT-12
Etc/GMT-13 | Etc/GMT-14 | Etc/GMT-2 | Etc/GMT-3
Etc/GMT-4 | Etc/GMT-5 | Etc/GMT-6 | Etc/GMT-7
Etc/GMT-8 | Etc/GMT-9 | Etc/GMT0 | Etc/Greenwich
Etc/UCT | Etc/Universal | Etc/UTC | Etc/Zulu
Europe/Belfast | Europe/Kiev | Europe/Nicosia | Europe/Tiraspol
Europe/Uzhgorod | Europe/Zaporozhye | Factory | GB
GB-Eire | GMT | GMT+0 | GMT-0
GMT0 | Greenwich | Hongkong | HST
Iceland | Iran | Israel | Jamaica
Japan | Kwajalein | Libya | MET
Mexico/BajaNorte | Mexico/BajaSur | Mexico/General | MST
MST7MDT | Navajo | NZ | NZ-CHAT
Pacific/Enderbury | Pacific/Johnston | Pacific/Ponape | Pacific/Samoa
Pacific/Truk | Pacific/Yap | Poland | Portugal
PRC | PST8PDT | ROC | ROK
Singapore | Turkey | UCT | Universal
US/Alaska | US/Aleutian | US/Arizona | US/Central
US/East-Indiana | US/Eastern | US/Hawaii | US/Indiana-Starke
US/Michigan | US/Mountain | US/Pacific | US/Samoa
UTC | W-SU | WET | Zulu

# Die Klasse DateError

(PHP 8 >= 8.3.0)

## Einführung

Wird geworfen, wenn die Zeitzonen-Datenbank nicht gefunden wird oder ungültige Daten enthält.

Dieser Fehler sollte nie auftreten und hängt nicht vom Code ab. Es gibt zwei untergeordnete Exceptions (DateObjectError und DateRangeError), die wegen Programmierfehlern oder Problemen im Zusammenhang mit dem Datumsbereich geworfen werden.

## Klassenbeschreibung

class DateError extends Error {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Siehe auch

- DateObjectError
- DateRangeError

# Die Klasse DateObjectError

(PHP 8 >= 8.3.0)

## Einführung

Wird geworfen, wenn eine der Datum/Uhrzeit-Klassen nicht korrekt initialisiert wurde.

Da Datum/Uhrzeit-Klassen nicht final sind, können diese Klassen vererbt werden. Wenn der Konstruktor der übergeordneten Klasse nicht aufgerufen wird, wird dieser Fehler geworfen. Es handelt sich hierbei immer um einen Programmierfehler.

## Klassenbeschreibung

class DateObjectError extends DateError {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Siehe auch

- DateError
- DateRangeError

# Die Klasse DateRangeError

(PHP 8 >= 8.3.0)

## Einführung

Wird auf 32-Bit-Plattformen von DateTime::getTimestamp(), DateTimeImmutable::getTimestamp() und date_timestamp_get() geworfen, wenn das Datumsobjekt ein Datum darstellt, das außerhalb des vorzeichenbehafteten 32-Bit-Bereichs liegt.

## Klassenbeschreibung

class DateRangeError extends DateError {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## Siehe auch

- DateError
- DateObjectError

# Die Klasse DateException

(PHP 8 >= 8.3.0)

## Einführung

Die übergeordnete Klasse der Datum/Uhrzeit-Exceptions für Probleme, die aufgrund von Benutzereingaben oder frei formulierten Textargumenten, die analysiert werden müssen, auftreten.

Die folgenden untergeordneten Exceptions werden von der Erweiterung geworfen:

- DateInvalidOperationException
- DateInvalidTimezoneException
- DateMalformedIntervalStringException
- DateMalformedPeriodStringException
- DateMalformedStringException

## Klassenbeschreibung

class DateException extends Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Die Klasse DateInvalidOperationException

(PHP 8 >= 8.3.0)

## Einführung

Wird von DateTimeImmutable::sub() und DateTime::sub() geworfen, wenn versucht wird, eine nicht unterstützte Operation durchzuführen.

Ein Beispiel für eine solche nicht unterstützte Operation ist die Verwendung eines DateInterval-Objekts, das relative Zeitangaben wie `next weekday` darstellt, weil es nicht möglich ist, daraus eine logische Umkehranweisung zu konstruieren.

## Klassenbeschreibung

class DateInvalidOperationException extends DateException {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Die Klasse DateInvalidTimeZoneException

(PHP 8 >= 8.3.0)

## Einführung

Wird geworfen, wenn ein ungültiger Wert an DateTimeZone::__construct() übergeben wird.

## Klassenbeschreibung

class DateInvalidTimeZoneException extends DateException {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Die Klasse DateMalformedIntervalStringException

(PHP 8 >= 8.3.0)

## Einführung

Wird geworfen, wenn ein ungültiges `duration`-Argument an DateInterval::__construct() übergeben wird.

## Klassenbeschreibung

class DateMalformedIntervalStringException extends DateException {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Die Klasse DateMalformedPeriodStringException

(PHP 8 >= 8.3.0)

## Einführung

Wird geworfen, wenn ein ungültiges `isostr`-Argument an DatePeriod::__construct() übergeben wird.

## Klassenbeschreibung

class DateMalformedPeriodStringException extends DateException {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# Die Klasse DateMalformedStringException

(PHP 8 >= 8.3.0)

## Einführung

Wird geworfen, wenn eine ungültige Datum/Uhrzeit-Zeichenkette erkannt wird.

Eine solche Zeichenkette kann als Wert an DateTimeImmutable::__construct(), DateTimeImmutable::modify(), DateTime::__construct() oder DateTime::modify() übergeben werden.

## Klassenbeschreibung

class DateMalformedStringException extends DateException {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- Installation/Konfiguration
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Beispiele
  - Rechnen mit Datum und Uhrzeit
- DateTime — Die Klasse DateTime
  - DateTime::add — Ändert ein DateTime-Objekt, wobei die Anzahl der Tage, Monate, Jahre, Stunden, Minuten und Sekunden hinzugefügt wird
  - DateTime::__construct — Liefert ein neues DateTime-Objekt
  - DateTime::createFromFormat — Wertet eine Zeitangabe gemäß dem angegebenen Format aus
  - DateTime::createFromImmutable — Liefert eine neue DateTime-Instanz, die das angegebene DateTimeImmutable-Objekt kapselt
  - DateTime::createFromInterface — Liefert ein neues DateTime-Objekt, das das angegebene DateTimeInterface-Objekt kapselt
  - DateTime::createFromTimestamp — Creates an instance from a Unix timestamp
  - DateTime::getLastErrors — Alias von DateTimeImmutable::getLastErrors
  - DateTime::modify — Ändert den Zeitstempel
  - DateTime::__set_state — Der __set_state-Handler
  - DateTime::setDate — Legt das Datum fest
  - DateTime::setISODate — Legt das ISO-Datum fest
  - DateTime::setMicrosecond — Sets microsecond part of the time
  - DateTime::setTime — Legt die Uhrzeit fest
  - DateTime::setTimestamp — Legt Datum und Zeit basierend auf einem Unix-Zeitstempel fest
  - DateTime::setTimezone — Legt die Zeitzone für ein DateTime-Objekt fest
  - DateTime::sub — Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden von einem DateTime-Objekt.
- DateTimeImmutable — Die Klasse DateTimeImmutable
  - DateTimeImmutable::add — Liefert ein neues Objekt, bei dem eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden zu einem bestehenden Objekt addiert wurde
  - DateTimeImmutable::__construct — Liefert ein neues DateTimeImmutable-Objekt
  - DateTimeImmutable::createFromFormat — Wertet eine Zeitangabe gemäß dem angegebenen Format aus
  - DateTimeImmutable::createFromInterface — Liefert ein neues DateTimeImmutable-Objekt, das das angegebene DateTimeInterface-Objekt kapselt
  - DateTimeImmutable::createFromMutable — Liefert eine neue DateTimeImmutable-Instanz, die das angegebene DateTime-Objekt kapselt
  - DateTimeImmutable::createFromTimestamp — Creates an instance from a Unix timestamp
  - DateTimeImmutable::getLastErrors — Liefert die Warnungen und Fehler
  - DateTimeImmutable::modify — Erzeugt ein neues Objekt mit geändertem Zeitstempel
  - DateTimeImmutable::__set_state — Der __set_state-Handler
  - DateTimeImmutable::setDate — Legt das Datum fest
  - DateTimeImmutable::setISODate — Legt das ISO-Datum fest
  - DateTimeImmutable::setMicrosecond — Sets microsecond part of the time
  - DateTimeImmutable::setTime — Legt die Uhrzeit fest
  - DateTimeImmutable::setTimestamp — Legt das Datum und die Uhrzeit basierend auf einem Unix-Zeitstempel fest
  - DateTimeImmutable::setTimezone — Legt die Zeitzone fest
  - DateTimeImmutable::sub — Subtrahiert eine Anzahl von Tagen, Monaten, Jahren, Stunden, Minuten und Sekunden
- DateTimeInterface — Das DateTimeInterface-Interface
  - DateTimeInterface::diff — Liefert die Differenz zwischen zwei DateTime-Objekten
  - DateTimeInterface::format — Liefert das Datum formatiert gemäß dem angegebenen Format
  - DateTimeInterface::getMicrosecond — Gets the microsecond part of the Unix timestamp
  - DateTimeInterface::getOffset — Liefert die Zeitverschiebung
  - DateTimeInterface::getTimestamp — Liefert den Unix-Zeitstempel
  - DateTimeInterface::getTimezone — Liefert die Zeitzone relativ zur angegebenen DateTime
  - DateTime::__serialize — Serialize a DateTime
  - DateTime::__unserialize — Unserialize an Datetime
  - DateTime::__wakeup — Der __wakeup-Handler
- DateTimeZone — Die Klasse DateTimeZone
  - DateTimeZone::__construct — Erstellt neues DateTimeZone-Objekt
  - DateTimeZone::getLocation — Liefert Standortinformationen zu einer Zeitzone
  - DateTimeZone::getName — Liefert den Namen einer Zeitzone
  - DateTimeZone::getOffset — Liefert die Zeitverschiebung gegenüber der GMT
  - DateTimeZone::getTransitions — Liefert alle Übergänge einer Zeitzone
  - DateTimeZone::listAbbreviations — Liefert ein assoziatives Array mit dst, offset und dem Namen der Zeitzone
  - DateTimeZone::listIdentifiers — Liefert ein numerisch indiziertes Array, das alle definierten Bezeichner der Zeitzonen enthält
- DateInterval — Die Klasse DateInterval
  - DateInterval::__construct — Erstellt ein neues DateInterval-Objekt
  - DateInterval::createFromDateString — Bildet ein DateInterval aus relativen Teilen eines Strings
  - DateInterval::format — Formatiert ein Intervall
- DatePeriod — Die Klasse DatePeriod
  - DatePeriod::__construct — Erstellt ein neues DatePeriod-Objekt
  - DatePeriod::createFromISO8601String — Erstellt ein neues DatePeriod-Objekt aus einer ISO8601-Zeichenkette
  - DatePeriod::getDateInterval — Liefert ein Intervall
  - DatePeriod::getEndDate — Liefert das Enddatum
  - DatePeriod::getRecurrences — Liefert die Anzahl der Wiederholungen
  - DatePeriod::getStartDate — Liefert das Startdatum
- Datum/Uhrzeit-Funktionen
  - checkdate — Prüft ein Gregorianisches Datum auf Gültigkeit
  - date — Formatiert einen Unix-Zeitstempel
  - date_add — Alias von DateTime::add
  - date_create — Erstellt ein neues DateTime-Objekt
  - date_create_from_format — Alias von DateTime::createFromFormat
  - date_create_immutable — Erstellt ein neues DateTimeImmutable-Objekt
  - date_create_immutable_from_format — Alias von DateTimeImmutable::createFromFormat
  - date_date_set — Alias von DateTime::setDate
  - date_default_timezone_get — Ermittelt die Standardzeitzone, die von allen Datums- und Zeitfunktionen in einem Skript verwendet wird
  - date_default_timezone_set — Setzt die Standardzeitzone, die von allen Datums- und Zeitfunktionen benutzt wird.
  - date_diff — Alias von DateTime::diff
  - date_format — Alias von DateTime::format
  - date_get_last_errors — Alias von DateTimeImmutable::getLastErrors
  - date_interval_create_from_date_string — Alias von DateInterval::createFromDateString
  - date_interval_format — Alias von DateInterval::format
  - date_isodate_set — Alias von DateTime::setISODate
  - date_modify — Alias von DateTime::modify
  - date_offset_get — Alias von DateTime::getOffset
  - date_parse — Liefert ein assoziatives Array mit detaillierten Informationen zu einem gegebenen Datum/Zeitpunkt
  - date_parse_from_format — Ermittelt Informationen über das angegebene Datum anhand des angegebenen Formats
  - date_sub — Alias von DateTime::sub
  - date_sun_info — Liefert ein Array mit Informationen über Sonnenauf- und -untergang sowie Beginn und Ende der Dämmerung
  - date_sunrise — Liefert die Uhrzeit des Sonnenaufgangs für den angegebenen Tag und Ort
  - date_sunset — Liefert die Uhrzeit des Sonnenuntergangs für den angegebenen Tag und Ort
  - date_time_set — Alias von DateTime::setTime
  - date_timestamp_get — Alias von DateTime::getTimestamp
  - date_timestamp_set — Alias von DateTime::setTimestamp
  - date_timezone_get — Alias von DateTime::getTimezone
  - date_timezone_set — Alias von DateTime::setTimezone
  - getdate — Liefert Datums- und Zeitinformationen
  - gettimeofday — Ermittelt die aktuelle Zeit
  - gmdate — Formatiert eine GMT/UTC Zeit-/Datumsangabe
  - gmmktime — Liefert den Unix-Zeitstempel für ein GMT-Datum
  - gmstrftime — Formatiert eine Datums-/Zeitangabe in GMT/UTC-Format entsprechend den Locale-Einstellungen
  - idate — Formatiert einen Teil der lokalen Zeit/des lokalen Datums als Integer
  - localtime — Ermittelt die lokale Zeit
  - microtime — Liefert den aktuellen Unix-Zeitstempel mit Mikrosekunden
  - mktime — Liefert den Unix-Zeitstempel für ein Datum
  - strftime — Formatiert eine Zeit-/Datumsangabe gemäß dem Gebietsschema
  - strptime — Wertet eine Zeit-/Datumsangabe aus, die mit strftime erzeugt wurde
  - strtotime — Wandelt eine textuelle englische Datums- und Zeitbeschreibung in einen Unix-Zeitstempel um
  - time — Liefert den aktuellen Unix-Zeitstempel
  - timezone_abbreviations_list — Alias von DateTimeZone::listAbbreviations
  - timezone_identifiers_list — Alias von DateTimeZone::listIdentifiers
  - timezone_location_get — Alias von DateTimeZone::getLocation
  - timezone_name_from_abbr — Liefert den Namen einer Zeitzone, ausgehend von der Abkürzung und der UTC-Abweichung
  - timezone_name_get — Alias von DateTimeZone::getName
  - timezone_offset_get — Alias von DateTimeZone::getOffset
  - timezone_open — Alias von DateTimeZone::__construct
  - timezone_transitions_get — Alias von DateTimeZone::getTransitions
  - timezone_version_get — Liefert die Version der timezonedb
- Fehler und Exceptions bei Datum/Uhrzeit
- Unterstützte Datums- und Zeitformate
- Liste unterstützter Zeitzonen
  - Afrika
  - Amerika
  - Antarktis
  - Arktis
  - Asien
  - Atlantisch
  - Australien
  - Europa
  - Indisch
  - Pazifisch
  - Andere
- DateError — Die Klasse DateError
- DateObjectError — Die Klasse DateObjectError
- DateRangeError — Die Klasse DateRangeError
- DateException — Die Klasse DateException
- DateInvalidOperationException — Die Klasse DateInvalidOperationException
- DateInvalidTimeZoneException — Die Klasse DateInvalidTimeZoneException
- DateMalformedIntervalStringException — Die Klasse DateMalformedIntervalStringException
- DateMalformedPeriodStringException — Die Klasse DateMalformedPeriodStringException
- DateMalformedStringException — Die Klasse DateMalformedStringException

# High resolution timing

# Einführung

The HRTime extension implements a high resolution StopWatch class. It uses the best possible APIs on different platforms which brings resolution up to nanoseconds. It also makes possible to implement a custom stopwatch using low level ticks delivered by the underlying APIs.

> Hinweis: As of PHP 7.3.0 the related function hrtime() is part of the core.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/hrtime.

# Beispiele

## Inhaltsverzeichnis

- Basic usage

## Basic usage

The example illustrates the basic StopWatch class usage

Beispiel #1 Measure several code blocks execution and get the total

    <?php

    $c = new HRTime\StopWatch;

    $c->start();
    /* measure this code block execution */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $elapsed0 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    /* measurement is not running here*/
    for ($i = 0; $i < 1024*1024; $i++);

    $c->start();
    /* measure this code block execution */
    for ($i = 0; $i < 1024*1024; $i++);
    $c->stop();
    $elapsed1 = $c->getLastElapsedTime(HRTime\Unit::NANOSECOND);

    $elapsed_total = $c->getElapsedTime(HRTime\Unit::NANOSECOND);

    ?>

# The HRTime\PerformanceCounter class

(PECL hrtime >= 0.4.3)

## Einführung

## Klassenbeschreibung

class HRTime\PerformanceCounter {
/* Methoden */
public static function getFrequency(): int
public static function getTicks(): int
public static function getTicksSince(int `$start`): int
}

# HRTime\PerformanceCounter::getFrequency

(PECL hrtime >= 0.4.3)

HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second

### Beschreibung

public static function HRTime\PerformanceCounter::getFrequency(): int

Returns the timer frequency in ticks per second. This value is constant after the system start on almost any operating system.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns Integer indicating the timer frequency.

# HRTime\PerformanceCounter::getTicks

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicks — Current ticks from the system

### Beschreibung

public static function HRTime\PerformanceCounter::getTicks(): int

Returns the ticks count.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns Integer indicating the ticks count.

# HRTime\PerformanceCounter::getTicksSince

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value

### Beschreibung

public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int

Returns the ticks count elapsed since the given start value.

### Parameter-Liste

`start`
  Starting ticks value.

### Rückgabewerte

Returns Integer indicating the ticks count.

## Inhaltsverzeichnis

- HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second
- HRTime\PerformanceCounter::getTicks — Current ticks from the system
- HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value

# The HRTime\StopWatch class

(PECL hrtime >= 0.4.3)

## Einführung

## Klassenbeschreibung

class HRTime\StopWatch extends HRTime\PerformanceCounter {
/* Methoden */
public function getElapsedTicks(): int
public function getElapsedTime(int `$unit` = ?): float
public function getLastElapsedTicks(): int
public function getLastElapsedTime(int `$unit` = ?): float
public function isRunning(): bool
public function start(): void
public function stop(): void
/* Geerbte Methoden */
public static function HRTime\PerformanceCounter::getFrequency(): int
public static function HRTime\PerformanceCounter::getTicks(): int
public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int
}

# HRTime\StopWatch::getElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTicks — Get elapsed ticks for all intervals

### Beschreibung

public function HRTime\StopWatch::getElapsedTicks(): int

Get elapsed ticks for all the previously closed intervals.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns Integer indicating elapsed ticks.

# HRTime\StopWatch::getElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals

### Beschreibung

public function HRTime\StopWatch::getElapsedTime(int `$unit` = ?): float

Get elapsed time for all the previously closed intervals.

### Parameter-Liste

`unit`
  Time unit represented by a HRTime\Unit constant. Default is HRTime\Unit::SECOND.

### Rückgabewerte

Returns Float indicating elapsed time.

# HRTime\StopWatch::getLastElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval

### Beschreibung

public function HRTime\StopWatch::getLastElapsedTicks(): int

Get elapsed ticks for the previously closed interval.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns Integer indicating elapsed ticks.

# HRTime\StopWatch::getLastElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval

### Beschreibung

public function HRTime\StopWatch::getLastElapsedTime(int `$unit` = ?): float

Get elapsed time for the previously closed interval.

### Parameter-Liste

`unit`
  Time unit represented by a HRTime\Unit constant. Default is HRTime\Unit::SECOND.

### Rückgabewerte

Returns Float indicating elapsed time.

# HRTime\StopWatch::isRunning

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::isRunning — Whether the measurement is running

### Beschreibung

public function HRTime\StopWatch::isRunning(): bool

Reveals whether the measurement was started.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns Boolean indicating whether the measurement is running.

# HRTime\StopWatch::start

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::start — Start time measurement

### Beschreibung

public function HRTime\StopWatch::start(): void

Starts the time measurement. It has no effect if the measurement was already started. The measurement will be continued if it was previously stopped.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns void.

# HRTime\StopWatch::stop

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::stop — Stop time measurement

### Beschreibung

public function HRTime\StopWatch::stop(): void

Stop the time measurement for the previously started interval.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns void.

## Inhaltsverzeichnis

- HRTime\StopWatch::getElapsedTicks — Get elapsed ticks for all intervals
- HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals
- HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval
- HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval
- HRTime\StopWatch::isRunning — Whether the measurement is running
- HRTime\StopWatch::start — Start time measurement
- HRTime\StopWatch::stop — Stop time measurement

# The HRTime\Unit class

(PECL hrtime >= 0.4.3)

## Einführung

## Klassenbeschreibung

class HRTime\Unit {
/* Konstanten */
const int SECOND = 0;
const int MILLISECOND = 1;
const int MICROSECOND = 2;
const int NANOSECOND = 3;
/* Methoden */
}

## Vordefinierte Konstanten

`HRTime\Unit::SECOND`
`HRTime\Unit::MILLISECOND`
`HRTime\Unit::MICROSECOND`
`HRTime\Unit::NANOSECOND`

- Installation/Konfiguration
  - Installation
- Beispiele
  - Basic usage
- HRTime\PerformanceCounter — The HRTime\PerformanceCounter class
  - HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second
  - HRTime\PerformanceCounter::getTicks — Current ticks from the system
  - HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value
- HRTime\StopWatch — The HRTime\StopWatch class
  - HRTime\StopWatch::getElapsedTicks — Get elapsed ticks for all intervals
  - HRTime\StopWatch::getElapsedTime — Get elapsed time for all intervals
  - HRTime\StopWatch::getLastElapsedTicks — Get elapsed ticks for the last interval
  - HRTime\StopWatch::getLastElapsedTime — Get elapsed time for the last interval
  - HRTime\StopWatch::isRunning — Whether the measurement is running
  - HRTime\StopWatch::start — Start time measurement
  - HRTime\StopWatch::stop — Stop time measurement
- HRTime\Unit — The HRTime\Unit class

- Kalender
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Calendar Funktionen
- Datum/Uhrzeit — Datum und Uhrzeit
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - DateTime — Die Klasse DateTime
  - DateTimeImmutable — Die Klasse DateTimeImmutable
  - DateTimeInterface — Das DateTimeInterface-Interface
  - DateTimeZone — Die Klasse DateTimeZone
  - DateInterval — Die Klasse DateInterval
  - DatePeriod — Die Klasse DatePeriod
  - Datum/Uhrzeit-Funktionen
  - Fehler und Exceptions bei Datum/Uhrzeit
  - Unterstützte Datums- und Zeitformate
  - Liste unterstützter Zeitzonen
  - DateError — Die Klasse DateError
  - DateObjectError — Die Klasse DateObjectError
  - DateRangeError — Die Klasse DateRangeError
  - DateException — Die Klasse DateException
  - DateInvalidOperationException — Die Klasse DateInvalidOperationException
  - DateInvalidTimeZoneException — Die Klasse DateInvalidTimeZoneException
  - DateMalformedIntervalStringException — Die Klasse DateMalformedIntervalStringException
  - DateMalformedPeriodStringException — Die Klasse DateMalformedPeriodStringException
  - DateMalformedStringException — Die Klasse DateMalformedStringException
- HRTime — High resolution timing
  - Installation/Konfiguration
  - Beispiele
  - HRTime\PerformanceCounter — The HRTime\PerformanceCounter class
  - HRTime\StopWatch — The HRTime\StopWatch class
  - HRTime\Unit — The HRTime\Unit class

# Dateisystemrelevante Erweiterungen

# Direct-IO

# Einführung

PHP unterstützt die direkten Ein-/Ausgabe-Funktionen, beschrieben im Posix-Standard (Kapitel 6) für die Ein- und Ausgabe auf einer niederen Ebene als die standardmäßig verwendeten C-Funktionen (fopen(), fread(), ...). Die Verwendung der DIO-Funktionen sollten Sie nur in Erwägung ziehen, wenn Sie die direkte Kontrolle über ein Gerät benötigen. In allen anderen Fällen sind die Standard-filesystem-Funktionen mehr als ausreichend.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Ressource-Typen

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/dio.

## Ressource-Typen

Der einzige von dieser Extension definierte Ressourcentyp ist der von dio_open() zurückgegebene Dateideskriptor.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`F_DUPFD` (int)

`F_GETFD` (int)

`F_GETFL` (int)

`F_GETLK` (int)

`F_GETOWN` (int)

`F_RDLCK` (int)

`F_SETFL` (int)

`F_SETLK` (int)

`F_SETLKW` (int)

`F_SETOWN` (int)

`F_UNLCK` (int)

`F_WRLCK` (int)

`O_APPEND` (int)

`O_ASYNC` (int)

`O_CREAT` (int)

`O_EXCL` (int)

`O_NDELAY` (int)

`O_NOCTTY` (int)

`O_NONBLOCK` (int)

`O_RDONLY` (int)

`O_RDWR` (int)

`O_SYNC` (int)

`O_TRUNC` (int)

`O_WRONLY` (int)

`S_IRGRP` (int)

`S_IROTH` (int)

`S_IRUSR` (int)

`S_IRWXG` (int)

`S_IRWXO` (int)

`S_IRWXU` (int)

`S_IWGRP` (int)

`S_IWOTH` (int)

`S_IWUSR` (int)

`S_IXGRP` (int)

`S_IXOTH` (int)

`S_IXUSR` (int)

# Direct-IO-Funktionen

# dio_close

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_close — Schließt eine Datei

### Beschreibung

function dio_close(resource `$fd`): void

Die Funktion dio_close() schließt die Datei `fd`.

### Parameter-Liste

`fd`

  Eine von dio_open() zurückgegebene Dateideskriptorresource.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 Schließen eines geöffneten Dateideskriptors

    <?php
    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_close($fd);
    ?>

### Siehe auch

- dio_open() - Öffnet eine Datei (falls nötig, wird diese erzeugt) auf einem niedrigeren Level als es die C-Bibliotheks Ein-/Ausgabe-Stream-Funktionen erlauben

# dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_fcntl — Modifiziert einen Dateideskriptor

### Beschreibung

function dio_fcntl(resource `$fd`, int `$cmd`, mixed `$args` = ?): mixed

Die Funktion dio_fcntl() führt die mit `cmd` festgelegte Operation auf dem Dateideskriptor `fd` aus. Für einige dieser Operationen müssen zusätzliche Argumente im Parameter `args` übergeben werden.

### Parameter-Liste

`fd`

  Ein von dio_open() zurückgegebener Dateideskriptor.

`cmd`

  Eine der folgenden Operationen:

  - `F_SETLK` - Setzt oder löscht eine Dateisperre. Wenn diese Sperre bereits von jemand anderem gehalten wird, gibt dio_fcntl() -1 zurück.

  - `F_SETLKW` - ähnlich `F_SETLK`, hier wird aber in dem Fall, dass bereits jemand anderes die Sperre hält, gewartet bis diese wieder freigegeben wird.

  - `F_GETLK` - dio_fcntl() gibt ein assoziatives Array mit Informationen (wie weiter unten beschrieben) zurück, wenn jemand anderes bereits eine Sperre hält. Existiert keine andere Sperre, wird das Element "type" auf `F_UNLCK` gesetzt.

  - `F_DUPFD` - Findet den kleinsten verfügbaren Dateideskriptor >= `args` und gibt diesen zurück.

  - `F_SETFL` - Setzt die Flags des Dateideskriptors auf den in `args` angegebenen Wert. Die verfügbaren Flags sind `O_APPEND`, `O_NONBLOCK` und `O_ASYNC`. Um `O_ASYNC` setzen zu können, benötigen Sie die PCNTL-Extension.

`args`

  Die `cmd`-Operationen `F_SETLK` und `F_SETLKW` erwarten ein Array mit den folgenden Elementen:

  - `start` - Offset an dem die Sperre beginnt

  - `length` - Länge des gesperrten Bereichs, 0 bedeutet dabei "bis zum Dateiende"

  - `whence` - Die Position, auf die sich `start` bezieht, dabei steht `SEEK_SET` für den Dateianfang, `SEEK_END` für das Dateiende und `SEEK_CUR` für die aktuelle Schreib-/Leseposition.

  - `type` - Art der Sperre: `F_RDLCK` (Lesesperre), `F_WRLCK` (Schreibsperre) oder `F_UNLCK` (Sperre aufheben)

### Rückgabewerte

Gibt das Ergebnis des entsprechenden C-Aufrufs zurück.

### Beispiele

Beispiel #1 Setzen und Löschen einer Sperre

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    if (dio_fcntl($fd, F_SETLK, Array("type"=>F_WRLCK)) == -1) {
        // Die Datei ist anscheinend schon anderweitig gesperrt
        echo "Sperrung fehlgeschlagen, die Datei wird schon von jemand anderem gesperrt.";
    } else {
        echo "Sperrung erfolgreich durchgeführt";
    }

    dio_close($fd);
    ?>

### Anmerkungen

> Hinweis: Diese Funktion ist auf Windows-Plattformen nicht verfügbar.

# dio_open

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_open — Öffnet eine Datei (falls nötig, wird diese erzeugt) auf einem niedrigeren Level als es die C-Bibliotheks Ein-/Ausgabe-Stream-Funktionen erlauben

### Beschreibung

function dio_open(string `$filename`, int `$flags`, int `$mode` = 0): resource

dio_open() öffnet eine Datei und liefert einen Dateideskriptor zurück.

### Parameter-Liste

`filename`

  Der Pfadname der zu öffnenden Datei.

`flags`

  Der Parameter `flags` ist ein bitweise ODER verknüpfter Wert bestehend aus Flags der folgende Liste. Dieser Wert muss entweder `O_RDONLY`, `O_WRONLY`, oder `O_RDWR` enthalten. Zusätzlich kann er eine beliebige Kombination der anderen Flags dieser Liste enthalten.

  - `O_RDONLY` - öffnet die Datei zum Lesezugriff.

  - `O_WRONLY` - öffnet die Datei zum Schreibzugriff.

  - `O_RDWR` - öffnet die Datei zum Lesen und Schreiben.

  - `O_CREAT` - erzeugt die Datei, falls diese nicht existiert

  - `O_EXCL` - wird sowohl `O_CREAT` als auch `O_EXCL` angegeben und die Datei existiert bereits, schlägt dio_open() fehl.

  - `O_TRUNC` - falls die Datei bereits existiert, und sie für Schreibzugriff geöffnet wird, wird diese auf die Grösse 0 zurückgesetzt

  - `O_APPEND` - setzt den Zeiger für Schreiboperationen an das Ende der Datei

  - `O_NONBLOCK` - Setzt den Modus auf "nonblocking"

  - `O_NOCTTY` - hält das Betriebssystem davon ab, die geöffnete Datei als Prozess steuerndes Terminal zuzuweisen, wenn eine TTY Gerätedatei geöffnet wird.

`mode`

  Wenn `flags` das Flag `O_CREAT` enthält, setzt `mode` die Dateizugriffsrechte. `mode` wird für die korrekte Ausführung benötigt, wenn `O_CREAT` in `flags` angegeben wird, und wird ansonsten ignoriert.

  Die tatsächlichen Dateizugriffsrechte, die der erzeugten Datei zugewiesen werden, werden von der umask Einstellung des Prozesses wie üblich beeinflusst.

### Rückgabewerte

Ein Dateideskriptor oder `false` bei Fehlern.

### Beispiele

Beispiel #1 Öffnen eines Dateideskriptors

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_close($fd);
    ?>

### Siehe auch

- dio_close() - Schließt eine Datei

# dio_read

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_read — Liest von einem Dateideskriptor

### Beschreibung

function dio_read(resource `$fd`, int `$len` = 1024): string

Die Funktion dio_read() liest `len` Bytes aus der Datei `fd`.

### Parameter-Liste

`fd`

  Ein von dio_open() zurückgegebener Dateideskriptor.

`len`

  Die Anzahl zu lesender Bytes. Wird diese nicht angegeben so wird in 1KB-Blöcken gelesen.

### Rückgabewerte

Die vom Deskriptor `fd` gelesenen Daten.

### Siehe auch

- dio_write() - Schreibt Daten in eine Datei

# dio_seek

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_seek — Setzt den Dateizeiger

### Beschreibung

function dio_seek(resource `$fd`, int `$pos`, int `$whence` = SEEK_SET): int

Die Funktion dio_seek() setzt den Dateizeiger des angegebenen Dateideskriptors.

### Parameter-Liste

`fd`

  Der von dio_open() zurückgegebene Dateideskriptor.

`pos`

  Die neue Position.

`whence`

  Gibt an, wie die Position `pos` interpretiert werden soll:

  - `SEEK_SET` (Standardwert) - gibt an, dass `pos` die Position vom Anfang der Datei ist

  - `SEEK_CUR` - gibt an, dass `pos` die Position relativ von der momentanen Dateizeigerposition ist. Die Position kann positiv oder negativ sein.

  - `SEEK_END` - gibt an, dass `pos` die Position relativ zum Dateiende ist. Eine negative Zahl setzt den Dateizeiger innerhalb der Datei, ein positiver Wert bewirkt, dass die Datei vom Ende bis zur neuen Position mit Nullen aufgefüllt wird, sobald tatsächlich weitere Daten geschrieben werden.

### Rückgabewerte

### Beispiele

Beispiel #1 Positionieren in einer Datei

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR);

    dio_seek($fd, 10, SEEK_SET);
    // Position ist jetzt beim 10. Zeichen vom Anfang der Datei

    dio_seek($fd, -2, SEEK_CUR);
    // Position ist jetzt beim 8. Zeichen vom Anfang der Datei

    dio_seek($fd, -5, SEEK_END);
    // Position ist jetzt beim 5. Zeichen vom Ende der Datei

    dio_seek($fd, 10, SEEK_END);
    // Position ist jetzt beim 10. Zeichen hinter dem Ende der Datei.
    // Die 10 Zeichen zwischen dem Ende der Datei und der aktuellen Position
    // werden mit Nullen gefüllt.

    dio_close($fd);
    ?>

# dio_stat

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_stat — Liefert Statusinformationen über einen Dateideskriptor

### Beschreibung

function dio_stat(resource `$fd`): array

Die Funktion dio_stat() gibt Informationen über den angegebenen Dateideskriptor zurück.

### Parameter-Liste

`fd`

  Ein von dio_open() zurückgegebener Dateideskriptor.

### Rückgabewerte

Gibt ein Array mit den folgenden Elementen zurück:

- "device" - Gerät

- "inode" - Inode

- "mode" - Modus

- "nlink" - Anzahl harter Links

- "uid" - Benutzer-ID

- "gid" - Gruppen-ID

- "device_type" - Gerätetyp (falls Inode-Gerät)

- "size" - Gesamtgröße in Bytes

- "blocksize" - Blockgröße

- "blocks" - Anzahl allozierter Blöcke

- "atime" - Zeit des letzten Zugriffs

- "mtime" - Zeit der letzen Modifikation

- "ctime" - Zeit der letzten Änderung

Im Fehlerfall gibt dio_stat() `null` zurück.

# dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)

dio_tcsetattr — Setzt Terminalattribute und Baudrate für eine serielle Schnittstelle

### Beschreibung

function dio_tcsetattr(resource `$fd`, array `$options`): bool

dio_tcsetattr() legt die Terminalattribute und die Baudrate für den geöffneten Dateideskriptor `fd` fest.

### Parameter-Liste

`fd`

  Ein von dio_open() zurückgegebener Dateideskriptor.

`options`

  Folgende Optionen sind derzeit verfügbar:

  - "baud" - Baudrate des Ports - kann 38400, 19200, 9600, 4800, 2400, 1800, 1200, 600, 300, 200, 150, 134, 110, 75 oder 50 sein. Die Voreinstellung ist 9600.

  - "bits" - Datenbits - kann 8, 7, 6 oder 5 sein. Die Voreinstellung ist 8.

  - "stop" - Stopbits - kann 1 oder 2 sein. Die Voreinstellung ist 1.

  - "parity" - kann 0, 1 oder 2 sein. Die Voreinstellung ist 0.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 Einstellen der Baudrate an einer seriellen Schnittstelle

    <?php

    $fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

    dio_fcntl($fd, F_SETFL, O_SYNC);

    dio_tcsetattr($fd, array(
      'baud' => 9600,
      'bits' => 8,
      'stop'  => 1,
      'parity' => 0
    ));

    while (1) {

      $data = dio_read($fd, 256);

      if ($data) {
          echo $data;
      }
    }

    ?>

### Anmerkungen

> Hinweis: Diese Funktion ist auf Windows-Plattformen nicht verfügbar.

# dio_truncate

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_truncate — Schneidet eine Datei ab

### Beschreibung

function dio_truncate(resource `$fd`, int `$offset`): bool

dio_truncate() schneidet eine Datei nach maximal `offset` ab.

War die Datei ursprünglich größer, so gehen die Daten verloren. War sie kleiner, ist nicht definiert, ob die Datei nicht geändert wird oder ob sie erweitert wird. Im letzteren Fall wird der erweiterte Teil mit Nullen aufgefüllt.

### Parameter-Liste

`fd`

  Ein von dio_open() zurückgegebener Dateideskriptor.

`offset`

  Der Offset in Bytes.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Anmerkungen

> Hinweis: Diese Funktion ist auf Windows-Plattformen nicht verfügbar.

# dio_write

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_write — Schreibt Daten in eine Datei

### Beschreibung

function dio_write(resource `$fd`, string `$data`, int `$len` = 0): int

Die Funktion dio_write() schreibt bis zu `len` Bytes `data` auf den Dateideskriptor `fd`.

### Parameter-Liste

`fd`

  Ein von dio_open() zurückgegebener Dateideskriptor.

`data`

  Die zu schreibenden Daten.

`len`

  Die Anzahl der zu schreibenden Bytes. Wenn nicht angegeben, werden die vollständigen Daten in die angegebene Datei geschrieben.

### Rückgabewerte

Gibt die Anzahl der tatsächlich geschriebenen Bytes zurück.

### Siehe auch

- dio_read() - Liest von einem Dateideskriptor

## Inhaltsverzeichnis

- dio_close — Schließt eine Datei
- dio_fcntl — Modifiziert einen Dateideskriptor
- dio_open — Öffnet eine Datei (falls nötig, wird diese erzeugt) auf einem niedrigeren Level als es die C-Bibliotheks Ein-/Ausgabe-Stream-Funktionen erlauben
- dio_read — Liest von einem Dateideskriptor
- dio_seek — Setzt den Dateizeiger
- dio_stat — Liefert Statusinformationen über einen Dateideskriptor
- dio_tcsetattr — Setzt Terminalattribute und Baudrate für eine serielle Schnittstelle
- dio_truncate — Schneidet eine Datei ab
- dio_write — Schreibt Daten in eine Datei

- Installation/Konfiguration
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- Direct-IO-Funktionen
  - dio_close — Schließt eine Datei
  - dio_fcntl — Modifiziert einen Dateideskriptor
  - dio_open — Öffnet eine Datei (falls nötig, wird diese erzeugt) auf einem niedrigeren Level als es die C-Bibliotheks Ein-/Ausgabe-Stream-Funktionen erlauben
  - dio_read — Liest von einem Dateideskriptor
  - dio_seek — Setzt den Dateizeiger
  - dio_stat — Liefert Statusinformationen über einen Dateideskriptor
  - dio_tcsetattr — Setzt Terminalattribute und Baudrate für eine serielle Schnittstelle
  - dio_truncate — Schneidet eine Datei ab
  - dio_write — Schreibt Daten in eine Datei

# Verzeichnis-Funktionen

# Vordefinierte Konstanten

`DIRECTORY_SEPARATOR` (string)
`PATH_SEPARATOR` (string)
  Strichpunkt bei Windows Systemen, Doppelpunkt bei UNIX basierten.
`SCANDIR_SORT_ASCENDING` (int)
`SCANDIR_SORT_DESCENDING` (int)
`SCANDIR_SORT_NONE` (int)

# Die Klasse Directory

(PHP 4, PHP 5, PHP 7, PHP 8)

## Einführung

Instanzen von Directory werden mithilfe der Funktion dir() erstellt, und nicht mit dem Operator new.

## Klassenbeschreibung

class Directory {
/* Eigenschaften */
public readonly string $path;
public readonly resource $handle;
/* Methoden */
public function close(): void
public function read(): string|false
public function rewind(): void
}

## Eigenschaften

path

  Das Verzeichnis, das geöffnet wurde.

handle

  Kann zusammen mit anderen Funktionen wie zum Beispiel readdir(), rewinddir() und closedir() benutzt werden.

## Changelog

Version | Beschreibung
--- | ---
8.1.0 | Die Eigenschaften path und handle sind nun schreibgeschützt.

# Directory::close

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::close — Schließt das Verzeichnis-Handle

### Beschreibung

public function Directory::close(): void

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Es wird kein Parameter akzeptiert. Zuvor konnte ein Verzeichnis-Handle als Parameter übergeben werden.

# Directory::read

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::read — Liest einen Eintrag vom Verzeichnis-Handle

### Beschreibung

public function Directory::read(): string|false

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Es wird kein Parameter akzeptiert. Zuvor konnte ein Verzeichnis-Handle als Parameter übergeben werden.

# Directory::rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::rewind — Setzt das Verzeichnis-Handle zurück

### Beschreibung

public function Directory::rewind(): void

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Es wird kein Parameter akzeptiert. Zuvor konnte ein Verzeichnis-Handle als Parameter übergeben werden.

## Inhaltsverzeichnis

- Directory::close — Schließt das Verzeichnis-Handle
- Directory::read — Liest einen Eintrag vom Verzeichnis-Handle
- Directory::rewind — Setzt das Verzeichnis-Handle zurück

# Verzeichnis-Funktionen

# Siehe auch

Für verwandte Funktionen wie zum Beispiel dirname(), is_dir(), mkdir() und rmdir(), lesen Sie auch das Filesystem-Kapitel.

# chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

chdir — Wechseln des Verzeichnisses

### Beschreibung

function chdir(string `$directory`): bool

Wechselt das aktuelle Verzeichnis von PHP zu `directory`.

### Parameter-Liste

`directory`

  Das neue aktuelle Verzeichnis

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Erzeugt einen Fehler des Levels `E_WARNING` bei Misserfolg.

### Beispiele

Beispiel #1 chdir() Beispiel

    <?php

    // aktuelles Verzeichnis
    echo getcwd() . "\n";

    chdir('public_html');

    // aktuelles Verzeichnis
    echo getcwd() . "\n";

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    /home/vincent
    /home/vincent/public_html

### Anmerkungen

Achtung

Wurde der PHP-Interpreter mit ZTS (Zend Thread Safety) kompiliert, sind Änderungen des aktuellen Arbeitsverzeichnisses durch chdir() für das Betriebssystem unsichtbar. Alle eingebauten PHP Funktionen berücksichtigen die Änderung des aktuellen Verzeichnisses, aber externe Bibliotheksfunktionen, die unter Verwendung von FFI aufgerufen werden, nicht. Um festzustellen, ob das verwendete PHP mit ZTS kompiliert wurde, kann php -i oder die eingebaute Konstante `PHP_ZTS` verwendet werden.

### Siehe auch

- getcwd() - Ermittelt das aktuelle Arbeitsverzeichnis

# chroot

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

chroot — Wechselt das Wurzelverzeichnis

### Beschreibung

function chroot(string `$directory`): bool

Wechselt das Wurzelverzeichnis des aktuellen Prozesses zu `directory`, und wechselt das aktuelle Arbeitsverzeichnis zu "/".

Diese Funktion ist nur unter GNU- und BSD-Systemen verfügbar und nur bei Verwendung der CLI-, CGI- oder Embed-SAPI. Zusätzlich benötigt die Funktion Root-Rechte.

Der Aufruf dieser Funktion ändert nicht die Werte der magischen Kontanten `__DIR__` und `__FILE__`.

### Parameter-Liste

`directory`

  Der Pfad, zu dem das Wurzelverzeichnis geändert werden soll.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 chroot()-Beispiel

    <?php
    chroot("/pfad/zu/ihrem/chroot/");
    echo getcwd();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    /

### Anmerkungen

> Hinweis: Diese Funktion ist auf Windows-Plattformen nicht verfügbar.

> Hinweis: Diese Funktion ist in PHP-Interpretern, die mit ZTS (Zend Thread Safety) kompiliert wurden, nicht verfügbar. Ob das verwendete PHP mit ZTS kompiliert wurde, kann durch Aufruf von php -i, oder unter Verwendung der eingebauten Konstante `PHP_ZTS` geprüft werden.

# closedir

(PHP 4, PHP 5, PHP 7, PHP 8)

closedir — Schließt ein Verzeichnis-Handle

### Beschreibung

function closedir(?resource `$dir_handle` = `null`): void

Schließt den in `dir_handle` angegebenen Verzeichnis-Stream. Der Stream muss zuvor mittels opendir() geöffnet worden sein.

### Parameter-Liste

`dir_handle`

  Die Verzeichnis-Handle-Ressource, die zuvor mit opendir() geöffnet wurde. Wenn das Verzeichnis-Handle nicht angegeben ist, wird dasjenige verwendet, das auf das zuletzt mittels opendir() geöffnete Verzeichnis zeigt.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 closedir()-Beispiel

    <?php
    $dir = "/etc/php5/";

    // Öffnet ein bekanntes Verzeichnis, liest das Verzeichnis in eine Variable
    // ein und schließt es danach
    if (is_dir($dir)) {
        if ($dh = opendir($dir)) {
            $directory = readdir($dh);
            closedir($dh);
        }
    }
    ?>

# dir

(PHP 4, PHP 5, PHP 7, PHP 8)

dir — Liefert eine Instanz der Directory-Klasse

### Beschreibung

function dir(string `$directory`, ?resource `$context` = `null`): Directory|false

Ein pseudo-objektorientierter Mechanismus zum Lesen eines Verzeichnisses. Das in `directory` angegebene Verzeichnis wird geöffnet.

### Parameter-Liste

`directory`

  Das zu öffnende Verzeichnis.

`context`

  Eine Stream-Kontext-Ressource.

### Rückgabewerte

Gibt eine Instanz der Directory-Klasse zurück oder `false` im Falle eines Fehlers.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `context` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 dir()-Beispiel

Beachten Sie im nachfolgenden Beispiel, wie der Rückgabewert der Funktion Directory::read() überprüft wird. Es wird explizit getestet, ob der Rückgabewert identisch (den gleichen Wert und Datentyp hat, siehe Vergleichs-0peratoren) mit `false` ist, weil sonst jeder Verzeichniseintrag, der zu `false` ausgewertet wird, die Schleife abbricht.

    <?php
    $d = dir("/etc/php5");
    echo "Handle: " . $d->handle . "\n";
    echo "Pfad: " . $d->path . "\n";
    while (false !== ($entry = $d->read())) {
       echo $entry."\n";
    }
    $d->close();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Handle: Resource id #2
    Pfad: /etc/php5
    .
    ..
    apache
    cgi
    cli

### Anmerkungen

> Hinweis:

> Die Reihenfolge der Verzeichniseinträge, die von der read-Methode zurückgegeben werden, ist systemabhängig.

# getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

getcwd — Ermittelt das aktuelle Arbeitsverzeichnis

### Beschreibung

function getcwd(): string|false

Gibt das aktuelle Arbeitsverzeichnis zurück.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg das aktuelle Arbeitsverzeichnis zurück, im Fehlerfall `false`.

Auf einigen Unix-Varianten gibt getcwd() `false` zurück, wenn eines der darüber liegenden Verzeichnisse keine Lese- oder Suchrechte haben, auch wenn das aktuelle Verzeichnis diese hat. Lesen Sie chmod() für weitergehende Informationen über Modi und Zugriffsrechte.

### Beispiele

Beispiel #1 getcwd()-Beispiel

    <?php

    // aktuelles Verzeichnis
    echo getcwd() . "\n";

    chdir('cvs');

    // aktuelles Verzeichnis
    echo getcwd() . "\n";

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    /home/didou
    /home/didou/cvs

### Anmerkungen

Achtung

Wurde der PHP-Interpreter mit ZTS (Zend Thread Safety) kompiliert, kann sich das aktuelle Arbeitsverzeichnis, das von getcwd() zurückgegeben wird, von dem was von Betriebssystemschnittstellen zurückgegeben wird, unterscheiden. Externe Bibliotheken (die durch FFI aufgerufen werden), die sich nach dem aktuellen Arbeitsverzeichnis richten, sind davon betroffen.

### Siehe auch

- chdir() - Wechseln des Verzeichnisses
- chmod() - Ändert den Modus für die Zugriffsrechte einer Datei

# opendir

(PHP 4, PHP 5, PHP 7, PHP 8)

opendir — Öffnet ein Verzeichnis-Handle

### Beschreibung

function opendir(string `$directory`, ?resource `$context` = `null`): resource|false

Öffnet ein Verzeichnis-Handle zur Verwendung in nachfolgenden Aufrufen von closedir(), readdir() und rewinddir().

### Parameter-Liste

`directory`

  Der zu öffnende Verzeichnis-Pfad.

`context`

  Für eine Beschreibung des Parameters `context` siehe das Kapitel über Streams im Handbuch.

### Rückgabewerte

Gibt bei Erfolg eine Verzeichnis-Handle-Ressource zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

Dies kann passieren, wenn `directory` kein valides Verzeichnis ist oder das Verzeichnis auf Grund von Zugriffsbeschränkungen oder Dateisystem-Problemen nicht geöffnet werden kann.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `context` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 opendir()-Beispiel

    <?php
    $dir = "/etc/php5/";

    // Ein bekanntes Verzeichnis öffnen und danach seinen Inhalt einlesen
    if (is_dir($dir)) {
        if ($dh = opendir($dir)) {
            while (($file = readdir($dh)) !== false) {
                echo "Dateiname: $file : Dateityp: " . filetype($dir . $file) . "\n";
            }
            closedir($dh);
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Dateiname: . : Dateityp: dir
    Dateiname: .. : Dateityp: dir
    Dateiname: apache : Dateityp: dir
    Dateiname: cgi : Dateityp: dir
    Dateiname: cli : Dateityp: dir

### Siehe auch

- is_dir() - Prüft, ob der angegebene Dateiname ein Verzeichnis ist
- readdir() - Liest einen Eintrag aus einem Verzeichnis-Handle
- dir() - Liefert eine Instanz der Directory-Klasse

# readdir

(PHP 4, PHP 5, PHP 7, PHP 8)

readdir — Liest einen Eintrag aus einem Verzeichnis-Handle

### Beschreibung

function readdir(?resource `$dir_handle` = `null`): string|false

Gibt den Namen des nächsten Eintrags des Verzeichnisses zurück. Die Einträge werden in der Reihenfolge zurückgegeben, in der sie innerhalb des Dateisystems angelegt wurden.

### Parameter-Liste

`dir_handle`

  Die Verzeichnis-Handle-Ressource, die zuvor mit opendir() geöffnet wurde. Wenn das Verzeichnis-Handle nicht angegeben ist, wird dasjenige verwendet, das auf das zuletzt mittels opendir() geöffnete Verzeichnis zeigt.

### Rückgabewerte

Gibt bei Erfolg den Namen des Eintrags zurück. Bei einem Fehler wird `false` zurückgegeben.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `dir_handle` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 Alle Einträge eines Verzeichnisses auflisten

Bitte beachten Sie die Art und Weise, in der die Rückgabewerte von readdir() in untenstehenden Beispielen geprüft werden. Wir testen explizit, ob der Rückgabewert identisch (also den gleichen Wert und Datentyp hat - siehe Kapitel Vergleichs-Operatoren für weitere Informationen) zu `false` ist, andernfalls würde jeder Verzeichnis-Eintrag, dessen Name als `false` ausgewertet wird, das Durchlaufen der Schleife beenden (z. B. ein Verzeichnis namens "0").

    <?php

    if ($handle = opendir('/path/to/files')) {
        echo "Verzeichnis-Handle: $handle\n";
        echo "Einträge:\n";

        /* Dies ist der korrekte Weg, ein Verzeichnis zu durchlaufen. */
        while (false !== ($entry = readdir($handle))) {
            echo "$entry\n";
        }

        /* Dies ist der FALSCHE Weg, ein Verzeichnis zu durchlaufen. */
        while ($entry = readdir($handle)) {
            echo "$entry\n";
        }

        closedir($handle);
    }
    ?>

Beispiel #2 Listet alle Einträge des aktuellen Verzeichnisses auf und blendet dabei die Verzeichnisse `.` und `..` aus.

    <?php
    if ($handle = opendir('.')) {
        while (false !== ($entry = readdir($handle))) {
            if ($entry != "." && $entry != "..") {
                echo "$entry\n";
            }
        }
        closedir($handle);
    }
    ?>

### Siehe auch

- is_dir() - Prüft, ob der angegebene Dateiname ein Verzeichnis ist
- glob() - Findet Dateinamen, die mit einem Muster übereinstimmen
- opendir() - Öffnet ein Verzeichnis-Handle
- scandir() - Listet Dateien und Verzeichnisse innerhalb eines angegebenen Pfades auf

# rewinddir

(PHP 4, PHP 5, PHP 7, PHP 8)

rewinddir — Setzt das Verzeichnis-Handle an den Anfang zurück

### Beschreibung

function rewinddir(?resource `$dir_handle` = `null`): void

Setzt den mit `dir_handle` angegebenen Verzeichnis-Stream auf den Anfang des Verzeichnisses zurück (Reset).

### Parameter-Liste

`dir_handle`

  Die Verzeichnis-Handle-Ressource, die zuvor mit opendir() geöffnet wurde. Wenn das Verzeichnis-Handle nicht angegeben ist, wird dasjenige verwendet, das auf das zuletzt mittels opendir() geöffnete Verzeichnis zeigt.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `dir_handle` ist nun nullable (akzeptiert den `null`-Wert).

# scandir

(PHP 5, PHP 7, PHP 8)

scandir — Listet Dateien und Verzeichnisse innerhalb eines angegebenen Pfades auf

### Beschreibung

function scandir(string `$directory`, int `$sorting_order` = `SCANDIR_SORT_ASCENDING`, ?resource `$context` = `null`): array|false

Gibt ein Array aus Dateien und Verzeichnissen des aktuellen `directory` zurück.

### Parameter-Liste

`directory`

  Das zu untersuchende Verzeichnis.

`sorting_order`

  Standardmäßig ist die Sortierreihenfolge alphabetisch in aufsteigender Reihenfolge. Wenn der optionale Parameter `sorting_order` auf `SCANDIR_SORT_DESCENDING` gesetzt wird, ist die Sortierreihenfolge alphabetisch absteigend. Wenn er auf `SCANDIR_SORT_NONE` gesetzt wird, ist das Ergebnis unsortiert.

`context`

  Für eine Beschreibung des Parameters `context` siehe das Kapitel über Streams im Handbuch.

### Rückgabewerte

Gibt bei Erfolg ein Array von Dateinamen zurück oder im Fehlerfall `false`. Wenn `directory` kein Verzeichnis ist, wird der boolsche Wert `false` zurückgegeben und ein Fehler vom Typ `E_WARNING` erzeugt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `context` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 Ein einfaches scandir()-Beispiel

    <?php
    $dir    = '/tmp';
    $files1 = scandir($dir);
    $files2 = scandir($dir, SCANDIR_SORT_DESCENDING);

    print_r($files1);
    print_r($files2);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => .
        [1] => ..
        [2] => bar.php
        [3] => foo.txt
        [4] => somedir
    )
    Array
    (
        [0] => somedir
        [1] => foo.txt
        [2] => bar.php
        [3] => ..
        [4] => .
    )

### Anmerkungen

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Siehe auch

- opendir() - Öffnet ein Verzeichnis-Handle
- readdir() - Liest einen Eintrag aus einem Verzeichnis-Handle
- glob() - Findet Dateinamen, die mit einem Muster übereinstimmen
- is_dir() - Prüft, ob der angegebene Dateiname ein Verzeichnis ist
- sort() - Sortiert ein Array in aufsteigender Reihenfolge

## Inhaltsverzeichnis

- chdir — Wechseln des Verzeichnisses
- chroot — Wechselt das Wurzelverzeichnis
- closedir — Schließt ein Verzeichnis-Handle
- dir — Liefert eine Instanz der Directory-Klasse
- getcwd — Ermittelt das aktuelle Arbeitsverzeichnis
- opendir — Öffnet ein Verzeichnis-Handle
- readdir — Liest einen Eintrag aus einem Verzeichnis-Handle
- rewinddir — Setzt das Verzeichnis-Handle an den Anfang zurück
- scandir — Listet Dateien und Verzeichnisse innerhalb eines angegebenen Pfades auf

- Vordefinierte Konstanten
- Directory — Die Klasse Directory
  - Directory::close — Schließt das Verzeichnis-Handle
  - Directory::read — Liest einen Eintrag vom Verzeichnis-Handle
  - Directory::rewind — Setzt das Verzeichnis-Handle zurück
- Verzeichnis-Funktionen
  - chdir — Wechseln des Verzeichnisses
  - chroot — Wechselt das Wurzelverzeichnis
  - closedir — Schließt ein Verzeichnis-Handle
  - dir — Liefert eine Instanz der Directory-Klasse
  - getcwd — Ermittelt das aktuelle Arbeitsverzeichnis
  - opendir — Öffnet ein Verzeichnis-Handle
  - readdir — Liest einen Eintrag aus einem Verzeichnis-Handle
  - rewinddir — Setzt das Verzeichnis-Handle an den Anfang zurück
  - scandir — Listet Dateien und Verzeichnisse innerhalb eines angegebenen Pfades auf

# Dateiinformation

# Einführung

Die Funktionen in diesem Modul versuchen den Typ und die Codierung des Inhaltes einer Datei durch untersuchen bestimmter magischen Byte-Sequenzen an spezifischen Stellen innerhalb der Datei. Obwohl dies kein "kugelsicherer" Ansatz ist machen sie dennoch gute Arbeit.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Ressource-Typen

## Installation

Diese Erweiterung ist standardmäßig aktiviert.

Windows-Benutzer müssen für die Aktivierung der Erweiterung die gebündelte php_fileinfo.dll DLL-Datei in die php.ini einbinden.

Die libmagic-Bibliothek ist mit PHP gebündelt, aber bindet PHP-spezifische änderungen ein. Ein Patch für libmagic, genannt libmagic.patch, wird entwickelt und kann eventuell in den Quelladateien der fileinfio-Erweiterung gefunden werden.

## Ressource-Typen

Vor PHP 8.1.0 wurde von der Fileinfo-Erweiterung eine Ressource verwendet: ein magischer Datenbank-Deskriptor, der von der Funktion finfo_open() zurückgegeben wird.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`FILEINFO_NONE` (int)
  Keine spezielle Fehlerbehandlung.
`FILEINFO_SYMLINK` (int)
  Folge symlinks.
`FILEINFO_MIME_TYPE` (int)
  Gibt den MIME-Typ zurück.
`FILEINFO_MIME_ENCODING` (int)
  Gibt die MIME-Kodierung der Datei zurück.
`FILEINFO_MIME` (int)
  Gibt den MIME-Typ und die MIME-Kodierung gemäß RFC 2045 zurück.
`FILEINFO_COMPRESS` (int)
  Dekomprimiert komprimierte Dateien. Deaktiviert aufgrund von Fragen bei der Thread-Sicherheit.
`FILEINFO_DEVICES` (int)
  Schaut auf Inhalte von Blöcken oder Chatacter-Spezialgeräte.
`FILEINFO_CONTINUE` (int)
  Gibt alle Übereinstimmungen zurück; nicht bloß die erste.
`FILEINFO_PRESERVE_ATIME` (int)
  Behält falls möglich die ursprüngliche Zugriffszeit bei.
`FILEINFO_RAW` (int)
  Übersetzt nicht druckbare Buchstaben nicht in eine oktale `\ooo`-Darstellung.
`FILEINFO_EXTENSION` (int)
  Liefert die passende Dateierweiterung zum erkannten MIME-Typen der Datei. Für Typen, die üblicherweise mehrere Dateierweiterungen haben, wie `JPEG`-Bilder, enthält der Rückgabewert mehrere durch Schrägstriche getrennte Erweiterungen, z. B.: `"jpeg/jpg/jpe/jfif"`. Für unbekannte Typen, die nicht in der magic.mime Datenbank verfügbar sind, ist der Rückgabewert `"???"`. Verfügbar seit PHP 7.2.0.
`FILEINFO_APPLE` (int)
  Gibt den Apple-Ersteller und -Typ zurück.

# Fileinfo Funktionen

# finfo_buffer

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_buffer -- finfo::buffer — Return information about a string buffer

### Beschreibung

Prozeduraler Stil

function finfo_buffer(
finfo `$finfo`,
string `$string`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Objektorientierter Stil

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

This function is used to get information about binary data in a string.

### Parameter-Liste

`finfo`

  Eine finfo-Instanz, die von finfo_open() zurückgegeben wurde.

`string`
  Content of a file to be checked.
`flags`
  One or disjunction of more Fileinfo constants.
`context`

### Rückgabewerte

Returns a textual description of the `string` argument, or `false` if an error occurred.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The `context` parameter has been deprecated as it is ignored.
8.1.0 | Der Parameter `finfo` erwartet nun eine finfo-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `context` is nullable now.

### Beispiele

Beispiel #1 A finfo_buffer() example

    <?php
    $finfo = new finfo(FILEINFO_MIME);
    echo $finfo->buffer($_POST["script"]) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    application/x-sh; charset=us-ascii

### Siehe auch

- finfo_file() - Liefert Informationen über eine Datei

# finfo_close

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_close — Schließt eine Fileinfo-Instanz

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function finfo_close(finfo `$finfo`): bool

Diese Funktion schließt die mit finfo_open() geöffnete Instanz.

### Parameter-Liste

`finfo`

  Eine finfo-Instanz, die von finfo_open() zurückgegeben wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `finfo` erwartet nun eine finfo-Instanz; vorher wurde eine Ressource erwartet.

# finfo_file

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_file -- finfo::file — Liefert Informationen über eine Datei

### Beschreibung

Prozeduraler Stil

function finfo_file(
finfo `$finfo`,
string `$filename`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

Objektorientierter Stil

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Diese Funktion wird benutzt, um Informationen über eine Datei zu erhalten.

### Parameter-Liste

`finfo`

  Eine finfo-Instanz, die von finfo_open() zurückgegeben wurde.

`filename`
  Name einer zu prüfenden Datei.
`flags`
  Eine Fileinfo-Konstante oder mehrere, die durch binäres ODER kombiniert werden.
`context`
  Für eine Beschreibung von `context` siehe Stream-Funktionen.

### Rückgabewerte

Gibt eine textliche Beschreibung des Inhalts des Arguments `filename` zurück oder `false`, falls ein Fehler auftrat.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `finfo` erwartet nun eine finfo-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | `context` ist jetzt nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 Ein finfo_file()-Beispiel

    <?php
    $finfo = finfo_open(FILEINFO_MIME_TYPE); // gibt den MIME-Typ (auch bekannt
                                             // als MIME-Type-Erweiterung) zurück
    foreach (glob("*") as $filename) {
        echo finfo_file($finfo, $filename) . "\n";
    }
    finfo_close($finfo);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    text/html
    image/gif
    application/vnd.ms-excel

### Siehe auch

- finfo_buffer() - Return information about a string buffer

# finfo_open

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_open -- finfo::__construct — Erstellt eine neue Fileinfo-Instanz

### Beschreibung

Prozeduraler Stil

function finfo_open(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`): finfo|false

Objektorientierter Stil (constructor):

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Diese Funktion öffnet eine magische Datenbank und gibt ihre Instanz zurück.

### Parameter-Liste

`flags`
  Eine Fileinfo-Konstante oder mehrere, die durch binäres ODER kombiniert werden.
`magic_database`
  Name einer magischen Datenbankdatei, gewöhnlich ungefähr so: /path/to/magic.mime. Falls nicht spezifiziert, wird die `MAGIC`-Umgebungsvariable verwendet. Falls die Umgebungsvariable nicht gesetzt ist, wird die PHP-eigene magische Datenbank benutzt. Übergibt `null` oder eine leere Zeichenfolge gleichbedeutend mit dem Standardwert.

### Rückgabewerte

(Nur prozeduraler Stil) Gibt bei Erfolg eine finfo-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine finfo-Instanz zurück; vorher wurde eine Ressource zurückgegeben.
8.0.3 | `magic_database` ist jetzt nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 Objektorientierter Stil

    <?php
    $finfo = new finfo(FILEINFO_MIME, "/usr/share/misc/magic"); // gib den MIME-Typ ala mimetype-Erweiterung zurück

    /* MIME-Typ für eine bestimmte Datei ermitteln */
    $filename = "/usr/local/something.txt";
    echo $finfo->file($filename);

    ?>

Beispiel #2 Prozeduraler Stil

    <?php
    $finfo = finfo_open(FILEINFO_MIME, "/usr/share/misc/magic"); // gib den MIME-Typ ala mimetype-Erweiterung zurück

    if (!$finfo) {
        echo "Öffnen der Fileinfo-Datenbank fehlgeschlagen";
        exit();
    }

    /* MIME-Typ für eine bestimmte Datei ermitteln */
    $filename = "/usr/local/something.txt";
    echo finfo_file($finfo, $filename);

    /* Verbindung schließen */
    finfo_close($finfo);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    text/plain; charset=us-ascii

### Anmerkungen

> Hinweis: Das Benutzen der eingebundenen magischen Datenbank (indem `magic_database` und die `MAGIC`-Umgebungsvariable nicht gesetzt werden) wird generell empfohlen, sofern keine benutzerdefinierte magische Datenbank benötigt wird.

### Siehe auch

- finfo_close() - Schließt eine Fileinfo-Instanz

# finfo_set_flags

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_set_flags -- finfo::set_flags — Setzt libmagic-Konfigurationsoptionen

### Beschreibung

Prozeduraler Stil

function finfo_set_flags(finfo `$finfo`, int `$flags`): true

Objektorientierter Stil

public function finfo::set_flags(int `$flags`): true

Diese Funktion setzt verschiedene Fileinfo-Optionen. Optionen können auch direkt in finfo_open() oder anderen Fileinfo-Funktionen gesetzt werden.

### Parameter-Liste

`finfo`

  Eine finfo-Instanz, die von finfo_open() zurückgegeben wurde.

`flags`
  Eine Fileinfo-Konstante oder mehrere, die durch binäres ODER kombiniert werden.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `finfo` erwartet nun eine finfo-Instanz; vorher wurde eine Ressource erwartet.

# mime_content_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mime_content_type — Ermittelt den MIME-Typ des Inhalts einer Datei

### Beschreibung

function mime_content_type(resource|string `$filename`): string|false

Gibt den MIME-Inhaltstyp für eine Datei unter verwendung von Informationen von der magic.mime-Datei.

### Parameter-Liste

`filename`
  Pfad zur zu testenden Datei

### Rückgabewerte

Gibt den Inhaltstyp im MIME-Format zurück, wie z. B. `text/plain` oder `application/octet-stream`. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 mime_content_type() Example

    <?php
    echo mime_content_type('php.gif') . "\n";
    echo mime_content_type('test.php');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    image/gif
    text/plain

### Siehe auch

- finfo_file() - Liefert Informationen über eine Datei
- finfo_buffer() - Return information about a string buffer

## Inhaltsverzeichnis

- finfo_buffer — Return information about a string buffer
- finfo_close — Schließt eine Fileinfo-Instanz
- finfo_file — Liefert Informationen über eine Datei
- finfo_open — Erstellt eine neue Fileinfo-Instanz
- finfo_set_flags — Setzt libmagic-Konfigurationsoptionen
- mime_content_type — Ermittelt den MIME-Typ des Inhalts einer Datei

# The finfo class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

## Einführung

This class provides an object-oriented interface into the fileinfo functions.

## Klassenbeschreibung

class finfo {
/* Methoden */
public function __construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)
public function buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function set_flags(int `$flags`): true
}

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::buffer — Alias von finfo_buffer()

### Beschreibung

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Diese Funktion ist ein Alias für: finfo_buffer()

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::__construct — Alias von finfo_open()

### Beschreibung

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

Diese Funktion ist ein Alias für: finfo_open()

### Changelog

Version | Beschreibung
--- | ---
8.0.3 | `magic_database` is nullable now.

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::file — Alias von finfo_file()

### Beschreibung

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

Diese Funktion ist ein Alias für: finfo_file()

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::set_flags — Alias von finfo_set_flags()

### Beschreibung

public function finfo::set_flags(int `$flags`): true

Diese Funktion ist ein Alias für: finfo_set_flags()

## Inhaltsverzeichnis

- finfo::buffer — Alias von finfo_buffer()
- finfo::__construct — Alias von finfo_open
- finfo::file — Alias von finfo_file()
- finfo::set_flags — Alias von finfo_set_flags()

- Installation/Konfiguration
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- Fileinfo Funktionen
  - finfo_buffer — Return information about a string buffer
  - finfo_close — Schließt eine Fileinfo-Instanz
  - finfo_file — Liefert Informationen über eine Datei
  - finfo_open — Erstellt eine neue Fileinfo-Instanz
  - finfo_set_flags — Setzt libmagic-Konfigurationsoptionen
  - mime_content_type — Ermittelt den MIME-Typ des Inhalts einer Datei
- finfo — The finfo class
  - finfo::buffer — Alias von finfo_buffer()
  - finfo::__construct — Alias von finfo_open
  - finfo::file — Alias von finfo_file()
  - finfo::set_flags — Alias von finfo_set_flags()

# Dateisystem

# Einführung

Diese Extension benötigt keine externen Bibliotheken. Wenn Sie PHP allerdings mit Large File System (LFS) Unterstützung kompilieren wollen, müssen Sie zusätzlich die folgende Compilerflags angeben: `-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64`.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Laufzeit-Konfiguration
- Ressource-Typen

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Dateisystem- und Stream-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
allow_url_fopen | "1" | `INI_SYSTEM` |
allow_url_include | "0" | `INI_SYSTEM` | Missbilligt von PHP 7.4.0 an.
user_agent | NULL | `INI_ALL` |
default_socket_timeout | "60" | `INI_ALL` |
from | "" | `INI_ALL` |
auto_detect_line_endings | "0" | `INI_ALL` | Missbilligt von PHP 8.1.0 an.
sys_temp_dir | "" | `INI_SYSTEM` |

Hier eine kurze Erklärung der Konfigurationsoptionen:

`allow_url_fopen` bool

  Diese Option aktiviert die URL-fähigen fopen()-Wrapper, die es ermöglichen, auf URL-Objekte zuzugreifen, als wären sie Dateien. Für den Zugriff auf entfernte Dateien über das FTP- und HTTP-Protokoll werden Standardwrapper mitgeliefert und einige Erweiterungen wie zlib registrieren eventuell weitere Wrapper.

`allow_url_include` bool

  Diese Option ermöglicht die Verwendung von URL-Wrappern mit folgenden Funktionen: include, include_once, require und require_once.

  > Hinweis:

  > Diese Einstellung funktioniert nur, wenn auch allow_url_fopen aktiviert ist.

`user_agent` string

  Definiert die von PHP verwendete HTTP-User-Agent-Kennung.

`default_socket_timeout` int

  Standardzeitbeschränkung für Socket-basierende Streams in Sekunden. Ein negativer Wert bedeutet eine unendliche Zeitbeschränkung.

`from` string

  Bei Nutzung der FTP- bzw. HTTP-Wrapper: E-Mail-Adresse für nicht authentifizierte FTP-Verbindungen bzw. From-Header in HTTP-Verbindungen.

`auto_detect_line_endings` bool

  Wenn diese Option aktiviert ist, prüft PHP die von den Funktionen fgets() und file() gelesenen Daten, um festzustellen, ob diese Unix-, MS-DOS- oder Macintosh-Zeilenenden verwenden.

  Dies ermöglicht es PHP, mit Macintosh-Systemen zusammenzuarbeiten, ist aber standardmäßig nicht aktiviert, da es zu einem geringfügigen Performanceverlust beim Einlesen der ersten Zeile führt. Weiterhin würden Anwender, die Carriage-Return-Zeichen unter Unix als Feldtrenner benutzen, ein nicht abwärtskompatibles Verhalten feststellen.

`sys_temp_dir` string

## Ressource-Typen

Das Dateisystem nutzt `Streams` als Ressourcentyp. Streams sind in einem eigenen Kapitel dokumentiert: Streams.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`SEEK_SET` (int)
`SEEK_CUR` (int)
`SEEK_END` (int)
`LOCK_SH` (int)
`LOCK_EX` (int)
`LOCK_UN` (int)
`LOCK_NB` (int)

Verfügbare `flags` für file()
`FILE_USE_INCLUDE_PATH` (int)
  Suche den Dateinamen `filename` im include_path.
`FILE_NO_DEFAULT_CONTEXT` (int)
`FILE_APPEND` (int)
  An vorhandene Datei anfügen.
`FILE_IGNORE_NEW_LINES` (int)
  EOL-Zeichen entfernen.
`FILE_SKIP_EMPTY_LINES` (int)
  Leerzeilen überspringen.
`FILE_BINARY` (int)

  Binärmodus.

  Warnung

  Diese Konstante hat keine Auswirkung und ist seit PHP 8.1.0 veraltet.

`FILE_TEXT` (int)

  Textmodus.

  Warnung

  Diese Konstante hat keine Auswirkung und ist seit PHP 8.1.0 veraltet.

Verfügbare `flags` für glob()
`GLOB_AVAILABLE_FLAGS` (int)
  Die Kombination aller `GLOB_*`-Flags. Entspricht `0` | `GLOB_BRACE` | `GLOB_MARK` | `GLOB_NOSORT` | `GLOB_NOCHECK` | `GLOB_NOESCAPE` | `GLOB_ERR` | `GLOB_ONLYDIR`
`GLOB_BRACE` (int)
  {a,b,c} expandieren, sodass es auf 'a', 'b' oder 'c' passt

  > Hinweis: `GLOB_BRACE` ist auf einigen Nicht-GNU-Systemen, wie Solaris oder Alpine Linux, nicht verfügbar.

`GLOB_ERR` (int)
  Bei Lesefehlern (z. B. unlesbare Verzeichnisse) stoppen; standardmäßig werden Fehler ignoriert.
`GLOB_MARK` (int)
  An jedes zurückgegebene Verzeichnis einen Schrägstrich anhängen (unter Windows einen Backslash)
`GLOB_NOCHECK` (int)
  Wenn keine passenden Dateien gefunden wurden, wird das Suchmuster zurückgegeben.
`GLOB_NOESCAPE` (int)
  Backslashes bewirken keine Maskierung von Metazeichen
`GLOB_NOSORT` (int)
  Die Dateien so zurückgeben, wie sie im Verzeichnis erscheinen (keine Sortierung). Ohne dieses Flag werden die Pfadnamen alphabetisch sortiert
`GLOB_ONLYDIR` (int)
  Nur Verzeichniseinträge zurückgeben, die dem Muster entsprechen

Verfügbare `flags` für pathinfo()
`PATHINFO_ALL` (int)
  Alle Teile der Pfadinformationen werden als assoziatives Array zurückgegeben.
`PATHINFO_DIRNAME` (int)
  Der Pfad des Verzeichnisses oder der Datei.
`PATHINFO_BASENAME` (int)
  Der Name des Verzeichnisses oder der Name und die Erweiterung der Datei.
`PATHINFO_EXTENSION` (int)
  Die Erweiterung der Datei.
`PATHINFO_FILENAME` (int)
  Der Name der Datei (ohne Erweiterung) oder des Verzeichnisses.

Verfügbare `scanner_mode`s für parse_ini_file() und parse_ini_string()
`INI_SCANNER_NORMAL` (int)
  Normaler INI-Scanner-Modus.
`INI_SCANNER_RAW` (int)
  Unverarbeiteter INI-Scanner-Modus.
`INI_SCANNER_TYPED` (int)
  Typisierter INI-Scanner-Modus.

Verfügbare `flags` für fnmatch()
`FNM_NOESCAPE` (int)
  Deaktivieren der Maskierung durch einen Backslash.
`FNM_PATHNAME` (int)
  Ein Slash in einer Zeichenkette matcht nur den Slash im übergebenen Muster.
`FNM_PERIOD` (int)
  Ein führender Punkt in einer Zeichenkette muss von einem Punkt im übergebenen Muster gematcht werden.
`FNM_CASEFOLD` (int)
  Match, der unabhängig von der Groß-/Kleinschreibung ist. Teil der GNU-Extension.

PHP-Konstanten für den Datei-Upload
`UPLOAD_ERR_CANT_WRITE` (int)

  Die Datei konnte nicht auf den Datenträger geschrieben werden. Der Wert der Konstanten ist `7`.

`UPLOAD_ERR_EXTENSION` (int)

  Eine PHP-Erweiterung hat den Datei-Upload gestoppt. PHP bietet keine Möglichkeit, herauszufinden, welche Erweiterung den Datei-Upload gestoppt hat; eine Untersuchung der Liste der geladenen Erweiterungen mit phpinfo() könnte hilfreich sein. Der Wert der Konstanten ist `8`.

`UPLOAD_ERR_FORM_SIZE` (int)

  Die hochgeladene Datei überschreitet die im HTML-Formular angegebene Direktive MAX_FILE_SIZE. Der Wert der Konstanten ist `2`.

`UPLOAD_ERR_INI_SIZE` (int)

  Die hochgeladene Datei überschreitet die Direktive upload_max_filesize der php.ini. Der Wert der Konstanten ist `1`.

`UPLOAD_ERR_NO_FILE` (int)

  Es wurde keine Datei hochgeladen.

`UPLOAD_ERR_NO_TMP_DIR` (int)

  Es fehlt ein temporäres Verzeichnis. Der Wert der Konstanten ist `6`.

`UPLOAD_ERR_OK`

  Es ist kein Fehler aufgetreten, die Datei wurde erfolgreich hochgeladen. Der Wert der Konstanten ist `0`.

`UPLOAD_ERR_PARTIAL` (int)

  Die hochgeladene Datei wurde nur teilweise hochgeladen. Der Wert der Konstanten ist `3`.

# Dateisystem-Funktionen

# Siehe auch

Verwandte Funktionen finden Sie in den Abschnitten Verzeichnis-Funktionen und Funktionen zur Programmausführung.

Eine Liste mit Erklärungen der verschiedenen URL-Wrapper, welche Sie auch als entfernte Dateien nutzen können, finden Sie unter Unterstützte Protokolle und Wrapper.

# basename

(PHP 4, PHP 5, PHP 7, PHP 8)

basename — Liefert den letzten Namensteil einer Pfadangabe

### Beschreibung

function basename(string `$path`, string `$suffix` = ""): string

Aus einer übergebenen Zeichenkette, die den Pfad zu einer Datei oder einem Verzeichnis enthält, gibt diese Funktion den letzten Namensteil zurück.

> Hinweis:

> basename() arbeitet nur mit der Eingabezeichenkette und beachtet nicht das eigentliche Dateisystem oder Pfadbestandteile wie etwa "`..`".

Achtung

basename() beachtet die Spracheinstellungen (Locale); soll sie die korrekte Namensbasis in Pfaden mit Mehrbytezeichen erkennen, muss daher die passende Locale mit der Funktion setlocale() gesetzt werden. Wenn `path` Zeichen enthält, die für die aktuelle Locale ungültig sind, ist das Verhalten von basename() undefiniert.

### Parameter-Liste

`path`

  Ein Pfad.

  Unter Windows wird sowohl der Slash (`/`) als auch der Backslash (`\`) als Trennzeichen bei Pfadangaben benutzt. Unter anderen Betriebssystemen hingegen nur der Slash (`/`).

`suffix`

  Wenn der Namensteil mit `suffix` endet, wird dieser ebenfalls abgetrennt.

### Rückgabewerte

Gibt den abschließenden Namen des übergebenen `path` zurück.

### Beispiele

Beispiel #1 basename()-Beispiel

    <?php
    echo "1) ".basename("/etc/sudoers.d", ".d").PHP_EOL;
    echo "2) ".basename("/etc/sudoers.d").PHP_EOL;
    echo "3) ".basename("/etc/passwd").PHP_EOL;
    echo "4) ".basename("/etc/").PHP_EOL;
    echo "5) ".basename(".").PHP_EOL;
    echo "6) ".basename("/");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1) sudoers
    2) sudoers.d
    3) passwd
    4) etc
    5) .
    6)

### Siehe auch

- dirname() - Liefert den Pfad des übergeordneten Verzeichnisses
- pathinfo() - Liefert Informationen über einen Dateipfad

# chgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

chgrp — Ändert die Gruppenzugehörigkeit einer Datei

### Beschreibung

function chgrp(string `$filename`, string|int `$group`): bool

Versucht, die Gruppenzugehörigkeit der Datei `filename` zu `group` zu ändern.

Nur der Superuser kann die Gruppe einer Datei beliebig ändern; andere Benutzer können die Gruppenzugehörigkeit einer Datei in jede Gruppe ändern, der sie angehören.

### Parameter-Liste

`filename`

  Pfad zu einer Datei.

`group`

  Ein Gruppenname oder eine Gruppennummer.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Gruppe einer Datei ändern

    <?php
    $filename = 'shared_file.txt';
    $format = "%s's Group ID @ %s: %d\n";
    printf($format, $filename, date('r'), filegroup($filename));
    chgrp($filename, 8);
    clearstatcache(); // Ergebnisse von filegroup() nicht zwischenspeichern
    printf($format, $filename, date('r'), filegroup($filename));
    ?>

### Anmerkungen

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

> Hinweis: Unter Windows schlägt diese Funktion stillschweigend fehl, wenn sie auf eine reguläre Datei angewendet wird.

### Siehe auch

- chown() - Ändert den Eigentümer einer Datei
- chmod() - Ändert den Modus für die Zugriffsrechte einer Datei

# chmod

(PHP 4, PHP 5, PHP 7, PHP 8)

chmod — Ändert den Modus für die Zugriffsrechte einer Datei

### Beschreibung

function chmod(string `$filename`, int `$permissions`): bool

Versucht, den Modus für die Zugriffsrechte der angegebenen Datei zu dem in `permissions` definierten zu ändern.

### Parameter-Liste

`filename`

  Pfad zu der Datei.

`permissions`

  Es ist zu beachten, dass `permissions` nicht automatisch für einen Oktalwert gehalten wird. Um also sicherzustellen, dass die Operation wie erwartet verläuft, muss `permissions` mit dem Präfix Null (0) versehen werden. Zeichenketten wie etwa "g+w" funktionieren nicht korrekt.

      <?php
      chmod("/einverzeichnis/einedatei", 755);   // dezimal; wahrscheinlich falsch
      chmod("/einverzeichnis/einedatei", "u+rwx,go+rx"); // Zeichenkette; falsch
      chmod("/einverzeichnis/einedatei", 0755);  // oktal; richtiger Wert für den Modus
      ?>

  Der Parameter `permissions` besteht aus drei oktalen Zifferkomponenten, die die Zugriffsberechtigungen für den Besitzer, für die Gruppe, in der der Besitzer ist, und für alle anderen in dieser Reihenfolge festlegen. Eine Komponete kann durch Addition der benötigten Rechte für das jeweilige Ziel berechnet werden. Die Ziffer 1 bedeutet, dass man Ausführrechte gewährt, die Ziffer 2 bedeutet, dass die Datei beschreibbar ist, die Ziffer 4 bedeutet, dass die Datei lesbar ist. Addieren Sie diese Zahlen, um die benötigten Rechte anzugeben. In unixoiden Betriebssystemen können Sie mit 'man 1 chmod' und 'man 2 chmod' mehr über diese Modi lesen.

      <?php
      // Lese- und Schreibrechte für den Besitzer, keine für alle anderen
      chmod("/somedir/somefile", 0600);

      // Lese- und Schreibrechte für den Besitzer, Leserechte für alle anderen
      chmod("/somedir/somefile", 0644);

      // Alle Rechte für den Besitzer, Lese- und Ausführrechte für andere
      chmod("/somedir/somefile", 0755);

      // Alle Rechte für den Besitzer, Lese- und Ausführrechte für die Gruppe
      chmod("/somedir/somefile", 0750);
      ?>

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Bei einem Fehler wird ein `E_WARNING` ausgegeben.

### Anmerkungen

> Hinweis:

> Der aktuelle Nutzer ist der Nutzer, unter dem PHP läuft. Dies ist möglicherweise nicht der gleiche Nutzer wie der, der für den Shell- oder FTP-Zugang verwendet wird. Auf den meisten Betriebssystemen können die Zugriffsrechte nur durch den Besitzer der Datei geändert werden.

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

### Siehe auch

- chown() - Ändert den Eigentümer einer Datei
- chgrp() - Ändert die Gruppenzugehörigkeit einer Datei
- fileperms() - Liefert die Zugriffsrechte einer Datei
- stat() - Sammelt Informationen über eine Datei

# chown

(PHP 4, PHP 5, PHP 7, PHP 8)

chown — Ändert den Eigentümer einer Datei

### Beschreibung

function chown(string `$filename`, string|int `$user`): bool

Ändert den Eigentümer der Datei `filename` in Benutzer `user`. Nur der Superuser kann den Eigentümer einer Datei ändern.

### Parameter-Liste

`filename`

  Pfad zur Zieldatei.

`user`

  Ein Benutzername oder eine numerische Benutzer-ID.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Einfache chown()-Benutzung

    <?php

    // Datei- und Benutzernamen setzen
    $file_name= "foo.php";
    $path = "/home/sites/php.net/public_html/sandbox/" . $file_name ;
    $user_name = "root";

    // Benutzer setzen
    chown($path, $user_name);

    // Ergebnis prüfen
    $stat = stat($path);
    print_r(posix_getpwuid($stat['uid']));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [name] => root
        [passwd] => x
        [uid] => 0
        [gid] => 0
        [gecos] => root
        [dir] => /root
        [shell] => /bin/bash
    )

### Anmerkungen

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

> Hinweis: Unter Windows schlägt diese Funktion stillschweigend fehl, wenn sie auf eine reguläre Datei angewendet wird.

### Siehe auch

- chmod() - Ändert den Modus für die Zugriffsrechte einer Datei
- chgrp() - Ändert die Gruppenzugehörigkeit einer Datei

# clearstatcache

(PHP 4, PHP 5, PHP 7, PHP 8)

clearstatcache — Löscht den Status-Cache

### Beschreibung

function clearstatcache(bool `$clear_realpath_cache` = `false`, string `$filename` = ""): void

Wenn stat(), lstat() oder eine andere der in der nachstehenden Liste aufgeführten betroffenen Funktionen verwendet wird, speichert (cached) PHP die von diesen Funktionen zurückgegebenen Informationen temporär, um eine bessere Performance zu bieten. In bestimmten Fällen kann es jedoch erforderlich sein, diese zwischengespeicherten Informationen zu löschen. Wird z. B. dieselbe Datei innerhalb eines Skriptes mehrmals geprüft und wird diese Datei möglicherweise während der Ausführung des Skriptes gelöscht oder verändert, könnte es sinnvoll sein, den Status-Cache zu löschen. In solchen Fällen empfiehlt es sich, die von PHP über eine Datei zwischengespeicherten Informationen mittels clearstatcache() zu löschen.

Zu beachten ist auch, dass PHP die Informationen über nicht existente Dateien nicht zwischenspeichert. Falls also file_exists() für eine Datei aufgerufen wird, die nicht existiert, wird `false` zurückgegeben, bis sie erzeugt wird. Wenn die Datei erzeugt wurde, wird `true` zurückgegeben, auch wenn die Datei danach gelöscht wird. unlink() leert den Zwischenspeicher jedoch automatisch.

> Hinweis:

> Diese Funktion speichert Informationen über bestimmte Dateinamen, weshalb clearstatcache() nur aufgerufen werden muss, wenn mehrere Operationen an demselben Dateinamen durchgeführt werden, und die Informationen über genau diese Datei nicht gespeichert werden sollen.

Betroffene Funktionen sind stat(), lstat(), file_exists(), is_writable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype() und fileperms().

### Parameter-Liste

`clear_realpath_cache`

  Ob der realpath-Zwischenspeicher ebenfalls geleert werden soll.

`filename`

  Leere den realpath- und den Stat-Zwischenspeicher nur für einen bestimmten Dateinamen; wird nur genutzt, wenn `clear_realpath_cache` `true` ist.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 clearstatcache()-Beispiel

    <?php
    $file = 'output_log.txt';

    function get_owner($file)
    {
        $stat = stat($file);
        $user = posix_getpwuid($stat['uid']);
        return $user['name'];
    }

    $format = "UID @ %s: %s\n";

    printf($format, date('r'), get_owner($file));

    chown($file, 'ross');
    printf($format, date('r'), get_owner($file));

    clearstatcache();
    printf($format, date('r'), get_owner($file));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: root
    UID @ Sun, 12 Oct 2008 20:48:28 +0100: ross

# copy

(PHP 4, PHP 5, PHP 7, PHP 8)

copy — Kopiert eine Datei

### Beschreibung

function copy(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Kopiert die Datei `from` nach `to`.

Um eine Datei zu verschieben, kann die Funktion rename() verwendet werden.

### Parameter-Liste

`from`

  Pfad zu der Quelldatei.

`to`

  Der Zielpfad. Wenn `to` eine URL ist, kann der Kopiervorgang fehlschlagen, wenn der Wrapper das Überschreiben existierender Dateien nicht unterstützt.

  Warnung

  Wenn die Zieldatei schon existiert, wird sie überschrieben.

`context`

  Eine gültige Context-Ressource, die mit stream_context_create() erzeugt wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 copy()-Beispiel

    <?php
    $file = 'example.txt';
    $newfile = 'example.txt.bak';

    if (!copy($file, $newfile)) {
        echo "das Kopieren von $file schlug fehl...\n";
    }
    ?>

### Siehe auch

- move_uploaded_file() - Verschiebt eine hochgeladene Datei an einen neuen Ort
- rename() - Benennt eine Datei oder ein Verzeichnis um
- Der Abschnitt des Handbuches über den Umgang mit Datei-Uploads

# delete

delete — Siehe unlink() oder unset()

### Beschreibung

Es gibt kein delete Schlüsselwort in der PHP Sprache. Um eine Datei zu löschen, kann unlink() verwendet werden. Um eine Variable im lokalen Geltungsbereich zu löschen, kann unset() verwendet werden.

### Siehe auch

- unlink() - Löscht eine Datei
- unset() - unset (löschen) einer angegebenen Variablen

# dirname

(PHP 4, PHP 5, PHP 7, PHP 8)

dirname — Liefert den Pfad des übergeordneten Verzeichnisses

### Beschreibung

function dirname(string `$path`, int `$levels` = 1): string

Aus einer übergebenen Zeichenkette, die den Pfad zu einer Datei oder einem Verzeichnis enthält, gibt diese Funktion den Pfad des Verzeichnisses zurück, welches `levels` Ebenen über dem angegebenen liegt.

> Hinweis:

> dirname() arbeitet nur mit der Eingabezeichenkette und beachtet nicht das eigentliche Dateisystem oder Pfadbestandteile wie etwa "`..`".

Achtung

Unter Windows geht dirname() von der aktuell eingestellten Codepage aus. Damit diese Funktion also bei Pfaden mit Mehrbytezeichen den korrekten Verzeichnisnamen erkennt, muss die passende Codepage gesetzt sein. Wenn `path` Zeichen enthält, die für die aktuelle Codepage ungültig sind, ist das Verhalten von dirname() undefiniert.

Auf anderen Systemen nimmt dirname() an, dass `path` in einer ASCII-kompatiblen Kodierung vorliegen muss. Andernfalls ist das Verhalten der Funktion undefiniert.

### Parameter-Liste

`path`

  Ein Pfad.

  Unter Windows wird sowohl der Slash (`/`) als auch der Backslash (`\`) als Trennzeichen bei Pfadangaben benutzt. Unter anderen Betriebssystemen hingegen nur der Slash (`/`).

`levels`

  Die Anzahl an übergeordneten Verzeichnissen, die aufgestiegen werden soll.

  Dies muss eine ganze Zahl größer 0 sein.

### Rückgabewerte

Gibt den Pfad eines übergeordneten Verzeichnisses zurück. Sind keine Pfadtrenner in `path`, wird ein Punkt ('`.`') zurückgegeben, der das aktuelle Verzeichnis angibt. Ansonsten ist die zurückgegebene Zeichenkette der `path`, von dem die abschließendene `/komponente` entfernt wurde.

Achtung

Vorsicht ist geboten, wenn diese Funktion in einer Schleife verwendet wird, die die oberste Verzeichnis-Ebene erreichen kann, da dies zu einer Endlosschleife führen kann.

    <?php
    dirname('.');    // Ergibt '.'.
    dirname('/');    // Ergibt '/' unter Windows und '/' auf *nix-Systemen.
    dirname('\\');   // Ergibt `\` unter Windows und '.' auf *nix-Systemen.
    dirname('C:\\'); // Ergibt 'C:\' unter Windows und '.' auf *nix-Systemen.
    ?>

### Beispiele

Beispiel #1 dirname()-Beispiel

    <?php
    echo dirname("/etc/passwd") . PHP_EOL;
    echo dirname("/etc/") . PHP_EOL;
    echo dirname(".") . PHP_EOL;
    echo dirname("C:\\") . PHP_EOL;
    echo dirname("/usr/local/lib", 2);

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    /etc
    / (oder \ unter Windows)
    .
    C:\
    /usr

### Siehe auch

- basename() - Liefert den letzten Namensteil einer Pfadangabe
- pathinfo() - Liefert Informationen über einen Dateipfad
- realpath() - Löst einen Pfad in einen absoluten und eindeutigen auf

# disk_free_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_free_space — Liefert den verfügbaren Platz auf einem Dateisystem oder einer Partition

### Beschreibung

function disk_free_space(string `$directory`): float|false

Wenn eine Zeichenkette angegeben wird, die ein Verzeichnis enthält, gibt diese Funktion die Anzahl verfügbarer (freier) Bytes auf dem entsprechenden Dateisystem oder der Partition zurück.

### Parameter-Liste

`directory`

  Ein Verzeichnis des Dateisystems oder der Partition.

  > Hinweis:

  > Wird ein Dateiname anstatt eines Verzeichnisses übergeben, ist das Verhalten der Funktion unspezifiziert und kann sich zwischen Betriebssystemen und PHP-Versionen unterscheiden.

### Rückgabewerte

Gibt die Anzahl der freien Bytes als Gleitkommazahl (float) zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 disk_free_space()-Beispiel

    <?php
    // $df enthält die Anzahl freier Bytes auf "/"
    $df = disk_free_space("/");

    // Unter Windows:
    $df_c = disk_free_space("C:");
    $df_d = disk_free_space("D:");
    ?>

### Anmerkungen

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

### Siehe auch

- disk_total_space() - Liefert die Gesamtgröße eines Dateisystemes oder einer Partition

# disk_total_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_total_space — Liefert die Gesamtgröße eines Dateisystemes oder einer Partition

### Beschreibung

function disk_total_space(string `$directory`): float|false

Wenn eine Zeichenkette angegeben wird, die ein Verzeichnis enthält, gibt diese Funktion die Gesamtzahl der Bytes auf dem entsprechenden Dateisystem oder der Partition zurück.

### Parameter-Liste

`directory`

  Ein Verzeichnis des Dateisystems oder der Partition.

### Rückgabewerte

Gibt die Gesamtanzahl Bytes als Gleitkommazahl (float) zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 disk_total_space()-Beispiel

    <?php
    // $ds enthält die Gesamtanzahl verfügbarer Bytes auf "/"
    $ds = disk_total_space("/");

    // Unter Windows:
    $ds = disk_total_space("C:");
    $ds = disk_total_space("D:");
    ?>

### Anmerkungen

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

### Siehe auch

- disk_free_space() - Liefert den verfügbaren Platz auf einem Dateisystem oder einer Partition

# diskfreespace

(PHP 4, PHP 5, PHP 7, PHP 8)

diskfreespace — Alias von disk_free_space()

### Beschreibung

Diese Funktion ist ein Alias für: disk_free_space().

# fclose

(PHP 4, PHP 5, PHP 7, PHP 8)

fclose — Schließt einen offenen Dateizeiger

### Beschreibung

function fclose(resource `$stream`): bool

Die Datei, auf die `stream` zeigt, wird geschlossen.

### Parameter-Liste

`stream`

  Der Datei-Zeiger muss gültig sein, d.h. die Datei, auf die gezeigt wird muss zuvor mit fopen() oder fsockopen() geöffnet worden sein.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Ein einfaches fclose() Beispiel

    <?php

    $handle = fopen('somefile.txt', 'r');

    fclose($handle);

    ?>

### Siehe auch

- fopen() - Öffnet eine Datei oder URL
- fsockopen() - Stellt eine Internet- oder Unix-Domain-Socket-Verbindung her

# fdatasync

(PHP 8 >= 8.1.0)

fdatasync — Synchronizes data (but not meta-data) to the file

### Beschreibung

function fdatasync(resource `$stream`): bool

This function synchronizes `stream` contents to storage media, just like fsync() does, but it does not synchronize file meta-data. Note that this function is only effectively different in POSIX systems. In Windows, this function is aliased to fsync().

### Parameter-Liste

`stream`

  Der Zeiger auf eine Datei muss gültig sein und auf eine Datei verweisen, die vorher erfolgreich mit fopen() oder fsockopen() geöffnet (und nicht bereits von fclose() geschlossen) wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 fdatasync() example

    <?php

    $file = 'test.txt';

    $stream = fopen($file, 'w');
    fwrite($stream, 'test data');
    fwrite($stream, "\r\n");
    fwrite($stream, 'additional data');

    fdatasync($stream);
    fclose($stream);
    ?>

### Siehe auch

- fflush() - Schreibt den Ausgabepuffer in eine Datei
- fsync() - Synchronizes changes to the file (including meta-data)

# feof

(PHP 4, PHP 5, PHP 7, PHP 8)

feof — Prüft, ob ein Dateizeiger am Ende der Datei steht

### Beschreibung

function feof(resource `$stream`): bool

Prüft, ob ein Dateizeiger am Ende der Datei steht.

### Parameter-Liste

`stream`

  Der Zeiger auf eine Datei muss gültig sein und auf eine Datei verweisen, die vorher erfolgreich mit fopen() oder fsockopen() geöffnet (und nicht bereits von fclose() geschlossen) wurde.

### Rückgabewerte

Gibt `true` zurück, wenn der Dateizeiger an EOF (Dateiende) steht oder ein Fehler auftritt (inklusive Socket-Zeitüberschreitung); ansonsten wird `false` zurückgegeben.

### Anmerkungen

Warnung

Wenn eine mit fsockopen() geöffnete Verbindung nicht durch den Server geschlossen wurde, bleibt feof() hängen. Um dies zu umgehen, siehe folgendes Beispiel:

Beispiel #1 Handhabung von Zeitüberschreitungen mit feof()

    <?php
    function safe_feof($fp, &$start = NULL) {
     $start = microtime(true);

     return feof($fp);
    }

    /* Annahme: $fp wurde zuvor mit fsockopen() geöffnet */

    $start = NULL;
    $timeout = ini_get('default_socket_timeout');

    while(!safe_feof($fp, $start) && (microtime(true) - $start) < $timeout)
    {
     /* Verarbeiten */
    }
    ?>

Warnung

Wenn der übergebene Dateizeiger nicht gültig ist, kann es zu einer Endlosschleife kommen, weil feof() nicht `true` zurückgibt.

Beispiel #2 feof()-Beispiel mit einem ungültigen Dateizeiger

    <?php
    // Wenn $file nicht gelesen werden kann oder nicht existiert, gibt fopen FALSE zurück
    $file = @fopen("no_such_file", "r");

    // Ein FALSE von fopen löst eine Warnung aus und führt hier zu einer Endlosschleife
    while (!feof($file)) {
    }

    fclose($file);
    ?>

# fflush

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fflush — Schreibt den Ausgabepuffer in eine Datei

### Beschreibung

function fflush(resource `$stream`): bool

Diese Funktion erzwingt das Schreiben des gesamten Ausgabepuffers in die von dem Dateizeiger `stream` angegebene Datei.

### Parameter-Liste

`stream`

  Der Zeiger auf eine Datei muss gültig sein und auf eine Datei verweisen, die vorher erfolgreich mit fopen() oder fsockopen() geöffnet (und nicht bereits von fclose() geschlossen) wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 File write example using fflush()

    <?php
    $filename = 'bar.txt';

    $file = fopen($filename, 'r+');
    rewind($file);
    fwrite($file, 'Foo');
    fflush($file);
    ftruncate($file, ftell($file));
    fclose($file);
    ?>

### Siehe auch

- clearstatcache() - Löscht den Status-Cache
- fwrite() - Binär-sicheres Dateischreiben

# fgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetc — Liest das Zeichen, auf welches der Dateizeiger zeigt

### Beschreibung

function fgetc(resource `$stream`): string|false

Liest ein Zeichen von dem übergebenen Dateizeiger.

### Parameter-Liste

`stream`

  Der Zeiger auf eine Datei muss gültig sein und auf eine Datei verweisen, die vorher erfolgreich mit fopen() oder fsockopen() geöffnet (und nicht bereits von fclose() geschlossen) wurde.

### Rückgabewerte

Gibt einen String zurück, welcher ein einzelnes Zeichen von der aktuellen Position des Dateizeigers `stream` enthält. Gibt `false` zurück, wenn der Dateizeiger am Ende der Datei steht (EOF).

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Beispiele

Beispiel #1 Ein fgetc()-Beispiel

    <?php
    $fp = fopen('somefile.txt', 'r');
    if (!$fp) {
        echo 'Konnte Datei somefile.txt nicht öffnen';
    }
    while (false !== ($char = fgetc($fp))) {
        echo "$char\n";
    }
    ?>

### Anmerkungen

> Hinweis: Diese Funktion ist binärsicher.

### Siehe auch

- fread() - Liest Binärdaten aus einer Datei
- fopen() - Öffnet eine Datei oder URL
- popen() - Öffnet einen Dateizeiger für einen Prozess
- fsockopen() - Stellt eine Internet- oder Unix-Domain-Socket-Verbindung her
- fgets() - Liest die Zeile von der Position des Dateizeigers

# fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetcsv — Liest eine Zeile von der Position des Dateizeigers und prüft diese auf kommaseparierte Werte (CSV)

### Beschreibung

function fgetcsv(
resource `$stream`,
?int `$length` = `null`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\"
): array|false

Die Funktion fgetcsv() ist ähnlich der Funktion fgets(), nur dass fgetcsv() die eingelesene Zeile auf Felder im CSV-Format (kommaseparierte Felder) hin überprüft und ein Array mit den gelesenen Feldern zurückgibt.

> Hinweis: Die Spracheinstellung (Locale) wird von dieser Funktion beachtet. Beispielsweise können Daten, die in bestimmten Ein-Byte-Kodierungen kodiert sind, falsch interpretiert werden, wenn `LC_CTYPE` den Wert `en_US.UTF-8` hat.

### Parameter-Liste

`stream`

  Ein gültiger Dateizeiger auf eine Datei, die zuvor mit fopen(), popen() oder fsockopen() geöffnet wurde.

`length`

  Muss größer als die längste Zeile (in Zeichen) sein, die in der CSV-Datei zu finden ist (dies erlaubt die Erkennung abschließender Zeilenende-Zeichen). Andernfalls wird die Zeile in Blöcke von `length` Zeichen aufgeteilt, es sei denn, die Aufteilung würde innerhalb einer Feldbegrenzung erfolgen.

  Wird dieser Paramter ausgelassen (oder in PHP 8.0.0 oder später auf 0 oder `null` gesetzt), ist die maximale Zeilenlänge nicht begrenzt, was ein wenig langsamer ist.

`separator`

  Der Parameter `separator` setzt das Feld-Trennzeichen. Es muss ein Single-Byte-Zeichen sein.

`enclosure`

  Der Parameter `enclosure` setzt das Feld-Begrenzungszeichen. Es muss ein Single-Byte-Zeichen sein.

`escape`

  Der Parameter `escape` setzt das Maskierungs-Zeichen. Es muss ein Single-Byte-Zeichen oder die leere Zeichenkette sein. Die leere Zeichenkette (`""`) deaktiviert den proprietären Maskierungsmechanismus.

  Warnung

  Im Eingabe Stream kann das `enclosure`-Zeichen immer maskiert werden, indem es innerhalb einer in Anführungszeichen gesetzten Zeichenkette verdoppelt wird, was zu einem einzelnen `enclosure`-Zeichen im geparsten Ergebnis führt. Das `escape`-Zeichen funktioniert anders: wenn eine Sequenz aus `escape`- und `enclosure`-Zeichen in der Eingabe erscheint, werden beide Zeichen im geparsten Ergebnis vorhanden sein. Für die Standardparameter wird also eine CSV-Zeile wie `"a""b","c\"d"` die Felder als `a"b` und `c\"d` parsen.

  Warnung

  Seit PHP 8.4.0 ist es veraltet, sich auf den Standardwert von `escape` zu verlassen. Er muss explizit angegeben werden, entweder an der richtigen Stelle oder durch die Verwendung von benannten Argumenten.

Warnung

Wenn `escape` auf etwas anderes als eine leere Zeichenkette (`""`) gesetzt wird, kann dies zu einer CSV-Datei führen, die nicht mit » RFC 4180 konform ist oder die den Umlauf durch die PHP-CSV-Funktionen nicht übersteht. Der Standardwert für `escape` ist `"\\"`, weshalb empfohlen wird, diesen Parameter explizit auf eine leere Zeichenkette zu setzen. Der Standardwert wird sich in einer zukünftigen Version von PHP ändern, jedoch nicht vor PHP 9.0.

### Rückgabewerte

Gibt bei Erfolg ein numerisch indexiertes Array zurück, das die gelesenen Felder enthält. Bei einem Fehler wird `false` zurückgegeben.

> Hinweis:

> Ein leere Zeile in einer CSV-Datei wird als ein Array zurückgegeben, das ein einzelnes null-Feld enthält, und wird nicht als Fehler behandelt.

> Hinweis: Wenn PHP Zeilenendezeichen nicht richtig erkennt, entweder beim Lesen von Dateien auf einem Macintosh oder bei Dateien, die auf einem Macintosh erstellt wurden, kann die Option auto_detect_line_endings aktiviert werden.

### Fehler/Exceptions

Wenn `separator` oder `enclosure` nicht ein Byte lang ist, wird ein ValueError geworfen.

Wenn `escape` nicht ein Byte lang oder eine leere Zeichenkette ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Sich auf den Standardwert von `escape` zu verlassen, ist nun veraltet.
8.3.0 | Eine leere Zeichenkette wird anstelle einer Zeichenkette mit einem einzelnen Null-Byte für das letzte Feld zurückgegeben, wenn es nur einen nicht abgeschlossenen Feld-Begrenzer enthält.
8.0.0 | `length` ist jetzt nullbar.
7.4.0 | Der Parameter `escape` akzeptiert nun auch eine leere Zeichenkette, um den proprietären Maskierungsmechanismus zu deaktivieren.

### Beispiele

Beispiel #1 Lesen und Ausgeben des gesamten Inhalts einer CSV-Datei

    <?php
    $row = 1;
    if (($handle = fopen("test.csv", "r")) !== FALSE) {
        while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
            $num = count($data);
            echo "<p> $num Felder in Zeile $row: <br /></p>\n";
            $row++;
            for ($c=0; $c < $num; $c++) {
                echo $data[$c] . "<br />\n";
            }
        }
        fclose($handle);
    }
    ?>

### Siehe auch

- fputcsv() - Format line as CSV and write to file pointer
- str_getcsv() - Parst einen CSV-String in ein Array
- SplFileObject::fgetcsv() - Gets line from file and parse as CSV fields
- SplFileObject::fputcsv() - Write a field array as a CSV line
- SplFileObject::setCsvControl() - Set the delimiter, enclosure and escape character for CSV
- SplFileObject::getCsvControl() - Get the delimiter, enclosure and escape character for CSV
- explode() - Teilt eine Zeichenkette anhand einer Zeichenkette
- file() - Liest eine komplette Datei in ein Array
- pack() - Packt Daten in eine binäre Zeichenkette

# fgets

(PHP 4, PHP 5, PHP 7, PHP 8)

fgets — Liest die Zeile von der Position des Dateizeigers

### Beschreibung

function fgets(resource `$stream`, ?int `$length` = `null`): string|false

Liest die Zeile von der Position des Dateizeigers.

### Parameter-Liste

`stream`

  Der Zeiger auf eine Datei muss gültig sein und auf eine Datei verweisen, die vorher erfolgreich mit fopen() oder fsockopen() geöffnet (und nicht bereits von fclose() geschlossen) wurde.

`length`

  Der Lesevorgang endet, wenn `length` - 1 Bytes gelesen wurden, bei einem Zeilenumbruch (der im Rückgabewert enthalten ist) oder am Dateiende (EOF) (je nachdem, was zuerst kommt). Wurde keine Länge übergeben, wird aus dem Stream gelesen, bis das Zeilenende erreicht ist.

### Rückgabewerte

Gibt eine Zeichenkette mit einer Länge von bis zu `length` - 1 Bytes zurück, die aus der Datei gelesen wurde, auf die `stream` zeigt. Wenn keine Daten mehr aus dem Dateizeiger zu lesen sind, wird `false` zurückgegeben.

Wenn ein Fehler auftritt, wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Eine Datei Zeile für Zeile lesen

    <?php

    $fp = @fopen("/tmp/inputfile.txt", "r");

    if ($fp) {
        while (($buffer = fgets($fp, 4096)) !== false) {
            echo $buffer, PHP_EOL;
        }

        if (!feof($fp)) {
            echo "Fehler: fgets() schlug unerwartet fehl\n";
        }

        fclose($fp);
    }

    ?>

### Anmerkungen

> Hinweis: Wenn PHP Zeilenendezeichen nicht richtig erkennt, entweder beim Lesen von Dateien auf einem Macintosh oder bei Dateien, die auf einem Macintosh erstellt wurden, kann die Option auto_detect_line_endings aktiviert werden.

> Hinweis:

> Wer die C-Semantik von fgets() gewohnt ist, sollte den Unterschied in der Rückgabe des Dateiende-Zeichens (`EOF`) beachten.

### Siehe auch

- fgetss() - Liest eine Zeile von der Position des Dateizeigers und entfernt HTML Tags.
- fread() - Liest Binärdaten aus einer Datei
- fgetc() - Liest das Zeichen, auf welches der Dateizeiger zeigt
- stream_get_line() - Gets line from stream resource up to a given delimiter
- fopen() - Öffnet eine Datei oder URL
- popen() - Öffnet einen Dateizeiger für einen Prozess
- fsockopen() - Stellt eine Internet- oder Unix-Domain-Socket-Verbindung her
- stream_set_timeout() - Set timeout period on a stream

# fgetss

(PHP 4, PHP 5, PHP 7)

fgetss — Liest eine Zeile von der Position des Dateizeigers und entfernt HTML Tags.

Warnung

Diese Funktion ist seit PHP 7.3.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function fgetss(resource `$handle`, int `$length` = ?, string `$allowable_tags` = ?): string

Diese Funktion ist identisch mit der Funktion fgets(), außer dass fgetss() versucht, vorhandene NUL-Bytes sowie HTML und PHP-Tags aus dem gelesenen Text zu entfernen. Die Funktion erhält den Parse-Zustand von Aufruf zu Aufruf, und ist daher nicht gleichwertig zum Aufruf von strip_tags() auf den Rückgabewert von fgets().

### Parameter-Liste

`handle`

  Der Zeiger auf eine Datei muss gültig sein und auf eine Datei verweisen, die vorher erfolgreich mit fopen() oder fsockopen() geöffnet (und nicht bereits von fclose() geschlossen) wurde.

`length`

  Länge der zu lesende Eingabe.

`allowable_tags`

  Über den optionalen dritten Parameter können Tags angegeben werden die nicht entfernt werden sollen. Siehe strip_tags() zu Details bezüglich `allowable_tags`.

### Rückgabewerte

Returns a string of up to `length` - 1 bytes read from the file pointed to by `handle`, with all HTML and PHP code striped.

Falls ein Fehler auftritt wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Reading a PHP file line-by-line

    <?php
    $str = <<<EOD
    <html><body>
     <p>Welcome! Today is the <?php echo(date('jS')); ?> of <?= date('F'); ?>.</p>
    </body></html>
    Text outside of the HTML block.
    EOD;
    file_put_contents('sample.php', $str);

    $handle = @fopen("sample.php", "r");
    if ($handle) {
      while (!feof($handle)) {
        $buffer = fgetss($handle, 4096);
        echo $buffer;
      }
      fclose($handle);
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Welcome! Today is the of .

    Text outside of the HTML block.

### Anmerkungen

> Hinweis: Wenn PHP Zeilenendezeichen nicht richtig erkennt, entweder beim Lesen von Dateien auf einem Macintosh oder bei Dateien, die auf einem Macintosh erstellt wurden, kann die Option auto_detect_line_endings aktiviert werden.

### Siehe auch

- fgets() - Liest die Zeile von der Position des Dateizeigers
- fopen() - Öffnet eine Datei oder URL
- popen() - Öffnet einen Dateizeiger für einen Prozess
- fsockopen() - Stellt eine Internet- oder Unix-Domain-Socket-Verbindung her
- strip_tags() - Entfernt HTML- und PHP-Tags aus einem String
- SplFileObject::fgetss() - Gets line from file and strip HTML tags
- Den string.strip_tags Filter

# file

(PHP 4, PHP 5, PHP 7, PHP 8)

file — Liest eine komplette Datei in ein Array

### Beschreibung

function file(string `$filename`, int `$flags` = 0, ?resource `$context` = `null`): array|false

Liest eine komplette Datei in ein Array.

> Hinweis:

> Sie können file_get_contents() benutzen, um den Inhalt einer Datei als String zurückgegeben zu bekommen.

### Parameter-Liste

`filename`

  Der Pfad zur Datei.

  Tipp

  Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

`flags`

  Der optionale Parameter `flags` kann aus einer oder mehreren der folgenden Konstanten bestehen:

  `FILE_USE_INCLUDE_PATH`
    Suche nach der Datei im include_path
  `FILE_IGNORE_NEW_LINES`
    Entferne den Zeilenumbruch am Ende jedes Array-Elements.
  `FILE_SKIP_EMPTY_LINES`
    Überspringe leere Zeilen.
  `FILE_NO_DEFAULT_CONTEXT`
    Verwende nicht den Standardkontext.
`context`

  Eine Stream-Kontext-Ressource.

### Rückgabewerte

Gibt die Datei in einem Array zurück. Jedes Element des Arrays entspricht einer Zeile in der Datei, ohne dass der Zeilenumbruch entfernt wird. Im Fehlerfall gibt file() `false` zurück.

> Hinweis:

> Jede Zeile im resultierenden Array enthält den Zeilenumbruch, außer es wird `FILE_IGNORE_NEW_LINES` verwendet.

> Hinweis: Wenn PHP Zeilenendezeichen nicht richtig erkennt, entweder beim Lesen von Dateien auf einem Macintosh oder bei Dateien, die auf einem Macintosh erstellt wurden, kann die Option auto_detect_line_endings aktiviert werden.

### Fehler/Exceptions

Wenn `flags` ungültige Werte enthält, z. B. `FILE_APPEND`, wird seit PHP 8.3.0 ein ValueError ausgelöst.

Erzeugt einen Fehler der Stufe `E_WARNING`, wenn die Datei nicht existiert.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Für alle ungültigen Werte von `flags` wird ein ValueError ausgelöst.

### Beispiele

Beispiel #1 file()-Beispiel

    <?php
    // Liest eine Datei in ein Array. Hier gehen wir über HTTP, um den
    // HTML-Quelltext einer URL zu bekommen
    $lines = file('http://www.example.com/');

    // Durchgehen des Arrays und Anzeigen des HTML-Quelltexts inkl. Zeilennummern
    foreach ($lines as $line_num => $line) {
        echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
    }

    // Benutzung des optionalen Parameters flags
    $trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    ?>

### Anmerkungen

Warnung

Bei SSL-Verbindungen zusammen mit Microsoft IIS hält sich dieser Webserver nicht an das Protokoll und schließt die Verbindung ohne ein `close_notify` zu senden. PHP quittiert dieses Fehlverhalten mit "SSL: Fatal Protocol Error", wenn das Ende der Daten erreicht ist. Eine mögliche Lösung besteht darin, den Level von error_reporting herabzusetzten und Warnings auszuschließen. PHP kann fehlerhafte IIS-Serversoftware erkennen, wenn Sie einen Stream mit dem `https://`-Wrapper öffnen, und unterdrückt die Warnung für Sie. Falls Sie fsockopen() benutzen, um einen `ssl://`-Socket zu öffnen, müssen Sie selbst dafür Sorge tragen, die Warnung zu erkennen und diese zu unterdrücken.

### Siehe auch

- file_get_contents() - Liest die gesamte Datei in einen String
- readfile() - Gibt eine Datei aus
- fopen() - Öffnet eine Datei oder URL
- fsockopen() - Stellt eine Internet- oder Unix-Domain-Socket-Verbindung her
- popen() - Öffnet einen Dateizeiger für einen Prozess
- include - include
- stream_context_create() - Creates a stream context

# file_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

file_exists — Prüft, ob eine Datei oder ein Verzeichnis existiert

### Beschreibung

function file_exists(string `$filename`): bool

Prüft, ob eine Datei oder ein Verzeichnis existiert.

### Parameter-Liste

`filename`

  Pfad zu der Datei oder dem Verzeichnis

  Unter Windows können Dateien auf Netzwerkfreigaben mit //computername/share/filename oder \\computername\share\filename überprüft werden.

### Rückgabewerte

Gibt `true` zurück, wenn die Datei oder das Verzeichnis, die durch `filename` spezifiziert sind, existieren; ansonsten `false`.

> Hinweis:

> Diese Funktion gibt bei symbolischen Links, die auf nicht existierende Dateien verweisen, `false` zurück.

> Hinweis:

> Die Prüfung wird mit der realen UID/GID anstelle der effektiven durchgeführt.

> Hinweis: Weil PHPs Integer Typ vorzeichenbehaftet ist und viele Platformen 32bit Integer verwenden, können einige Dateisystem-Funktionen für Dateien größer als 2GB unerwartete Ergebnisse liefern.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 Prüfen, ob eine Datei existiert

    <?php
    $filename = '/path/to/foo.txt';

    if (file_exists($filename)) {
        echo "Die Datei $filename existiert";
    } else {
        echo "Die Datei $filename existiert nicht";
    }
    ?>

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- is_readable() - Prüft, ob eine Datei existiert und lesbar ist
- is_writable() - Prüft, ob in eine Datei geschrieben werden kann
- is_file() - Prüft, ob der Dateiname eine reguläre Datei ist
- file() - Liest eine komplette Datei in ein Array
- SplFileInfo

# file_get_contents

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

file_get_contents — Liest die gesamte Datei in einen String

### Beschreibung

function file_get_contents(
string `$filename`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`,
int `$offset` = 0,
?int `$length` = `null`
): string|false

Diese Funktion ist mit file() identisch, außer dass file_get_contents() die Datei in einem String zurückgibt, beginnend am angebenen `offset` über bis zu `length` Bytes. Im Fehlerfall gibt file_get_contents() `false` zurück.

file_get_contents() ist der empfohlene Weg, um den Inhalt einer Datei in einen String zu lesen. Es werden Techniken zur Speicherabbildung genutzt, um die Performance zu erhöhen, falls das Betriebssystem dies unterstützt.

> Hinweis:

> Falls Sie einen URI mit speziellen Zeichen, wie z. B. Leerzeichen, öffnen, müssen Sie den URI mittels urlencode() enkodieren.

### Parameter-Liste

`filename`

  Name der zu lesenden Datei.

`use_include_path`

  > Hinweis:

  > Die Konstante `FILE_USE_INCLUDE_PATH` kann genutzt werden, um eine Suche im include path auszulösen. Dies ist nicht möglich, wenn strenge Typisierung aktiviert wurde, da `FILE_USE_INCLUDE_PATH` ein int ist. Statt dessen ist `true` zu verwenden.

`context`

  Eine gültige Context-Ressource, die mit stream_context_create() erstellt wurde. Falls Sie keinen eigenen Context benötigen, können Sie diesen Parameter mit `null` überspringen.

`offset`

  Die Position, an der das Lesen im Originalstream beginnt. Negative Offsets zählen vom Ende des Streams an.

  Das Springen an bestimmte Positionen (`offset`) wird nicht für entfernte Dateien unterstützt. Für kleine Offsets kann der Sprung funktionieren, allerdings ist dies nicht vorhersagbar, weil hierbei auf dem gepufferten Stream gearbeitet wird.

`length`

  Maximale Länge der zu lesenden Daten. Standardmäßig wird solange gelesen bis das Ende der Datei erreicht wird. Beachten Sie, dass dieser Parameter auf den Stream angewendet wird, der durch die Filter verarbeitet wird.

### Rückgabewerte

Die Funktion gibt die gelesenen Daten zurück. Bei einem Fehler wird `false` zurückgegeben.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Fehler/Exceptions

Ein Fehler der Stufe `E_WARNING` wird generiert, wenn `filename` nicht gefunden werden kann, `length` kleiner als Null ist oder wenn das Aufsuchen des angegebenen `offset` im Streams fehlschlägt.

Wenn file_get_contents() für ein Verzeichnis aufgerufen wird, wird unter Windows und ab PHP 7.4 auch auf anderen Betriebssystemen ein Fehler der Ebene `E_WARNING` generiert.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `length` ist jetzt nullbar.
7.1.0 | Unterstützung für negative `offset`s wurde hinzugefügt.

### Beispiele

Beispiel #1 Holen und Ausgeben des Quelltextes der Startseite einer Webseite

    <?php
    $homepage = file_get_contents('http://www.example.com/');
    echo $homepage;
    ?>

Beispiel #2 Suche im include_path

    <?php
    // Wenn strikte Typisierung aktiviert wurde, d. h. declare(strict_types=1);
    $file = file_get_contents('./leute.txt', true);
    // Andernfalls
    $file = file_get_contents('./leute.txt', FILE_USE_INCLUDE_PATH);
    ?>

Beispiel #3 Lesen einen Abschnitts einer Datei

    <?php
    // Lese 14 Zeichen, beginnend mit dem 21. Zeichen
    $section = file_get_contents('./leute.txt', FALSE, NULL, 20, 14);
    var_dump($section);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(14) "lle Bjori Ro"

Beispiel #4 Nutzung von Stream-Contexten

    <?php
    // Erzeugen eines Streams
    $opts = [
      'http' => [
        'method' => "GET",
        'header' => "Accept-language: en\r\n" .
                    "Cookie: foo=bar",
      ]
    ];

    $context = stream_context_create($opts);

    // Öffnen der Datei mit den oben definierten HTTP-Headern
    $file = file_get_contents('http://www.example.com/', false, $context);
    ?>

### Anmerkungen

> Hinweis: Diese Funktion ist binärsicher.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

Warnung

Bei SSL-Verbindungen zusammen mit Microsoft IIS hält sich dieser Webserver nicht an das Protokoll und schließt die Verbindung ohne ein `close_notify` zu senden. PHP quittiert dieses Fehlverhalten mit "SSL: Fatal Protocol Error", wenn das Ende der Daten erreicht ist. Eine mögliche Lösung besteht darin, den Level von error_reporting herabzusetzten und Warnings auszuschließen. PHP kann fehlerhafte IIS-Serversoftware erkennen, wenn Sie einen Stream mit dem `https://`-Wrapper öffnen, und unterdrückt die Warnung für Sie. Falls Sie fsockopen() benutzen, um einen `ssl://`-Socket zu öffnen, müssen Sie selbst dafür Sorge tragen, die Warnung zu erkennen und diese zu unterdrücken.

### Siehe auch

- file() - Liest eine komplette Datei in ein Array
- fgets() - Liest die Zeile von der Position des Dateizeigers
- fread() - Liest Binärdaten aus einer Datei
- readfile() - Gibt eine Datei aus
- file_put_contents() - Schreibt Daten in eine Datei
- stream_get_contents() - Reads remainder of a stream into a string
- stream_context_create() - Creates a stream context
- $http_response_header

# file_put_contents

(PHP 5, PHP 7, PHP 8)

file_put_contents — Schreibt Daten in eine Datei

### Beschreibung

function file_put_contents(
string `$filename`,
mixed `$data`,
int `$flags` = 0,
?resource `$context` = `null`
): int|false

Diese Funktion entspricht fopen(), fwrite() und fclose(), um Daten in eine Datei zu schreiben.

Wenn `filename` nicht existiert, wird die Datei erstellt. Sonst wird die existierende Datei überschrieben, es sei denn `FILE_APPEND` ist gesetzt.

### Parameter-Liste

`filename`

  Pfad zur Datei in die die Daten geschrieben werden sollen.

`data`

  Die zu schreibenden Daten. Kann entweder string, oder array sowie stream sein.

  Wenn `data` eine stream-Quelle ist, wird der verbleibende Puffer des Streams in die festgelegte Datei kopiert. Dies ähnelt der Funktion stream_copy_to_stream().

  Sie können auch den Parameter `data` als eindimensionales Array angeben. Dies ist äquivalent zu `file_put_contents($filename, implode('', $array))`.

`flags`

  Der Wert von `flags` kann eine Kombination der folgenden Flags sein, verbunden mit dem binären OR(`|`) -Operator.

  verfügbare Flags
  Flag | Beschreibung
  --- | ---
  `FILE_USE_INCLUDE_PATH` | Sucht nach `filename` im enthaltenen Verzeichnis. Siehe include_path für mehr Information.
  `FILE_APPEND` | Falls die Datei `filename` bereits existiert, füge die Daten an die Datei an anstatt diese zu überschreiben.
  `LOCK_EX` | Erwirbt exklusive Schreibrechte auf die Datei während mit dem Schreiben fortgefahren wird. Anders ausgedrückt erfolgt ein flock() Aufruf zwischen dem fopen() Aufruf und dem fwrite() Aufruf. Das ist nicht das gleiche wie ein fopen() Aufruf mit Modus "x".

`context`

  Eine gültige Kontakt-Ressource erstellt mit der Funktion stream_context_create().

### Rückgabewerte

Diese Funktion gibt die Anzahl der geschriebenen Bytes oder `false` bei einem Fehler zurück.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Beispiele

Beispiel #1 Einfaches Verwendungsbeispiel

    <?php
    $file = 'people.txt';
    // Öffnet die Datei, um den vorhandenen Inhalt zu laden
    $current = file_get_contents($file);
    // Fügt eine neue Person zur Datei hinzu
    $current .= "John Smith\n";
    // Schreibt den Inhalt in die Datei zurück
    file_put_contents($file, $current);
    ?>

Beispiel #2 Verwendung der Flags

    <?php
    $file = 'people.txt';
    //Die neue Person, die zur Datei hinzugefügt werden soll
    $person = "John Smith\n";
    // Schreibt den Inhalt in die Datei
    // unter Verwendung des Flags FILE_APPEND, um den Inhalt an das Ende der Datei anzufügen
    // und das Flag LOCK_EX, um ein Schreiben in die selbe Datei zur gleichen Zeit zu verhindern
    file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
    ?>

### Anmerkungen

> Hinweis: Diese Funktion ist binärsicher.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Siehe auch

- fopen() - Öffnet eine Datei oder URL
- fwrite() - Binär-sicheres Dateischreiben
- file_get_contents() - Liest die gesamte Datei in einen String
- stream_context_create() - Creates a stream context

# fileatime

(PHP 4, PHP 5, PHP 7, PHP 8)

fileatime — Liefert die Zeit des letzten Zugriffs auf eine Datei

### Beschreibung

function fileatime(string `$filename`): int|false

Gibt Zeit des letzten Zugriffs auf die übergebene Datei zurück.

### Parameter-Liste

`filename`

  Pfad zu der Datei.

### Rückgabewerte

Gibt die Zeit des letzten Zugriffs auf eine Datei zurück. Bei einem Fehler wird `false` zurückgegeben. Die Zeit wird als UNIX-Zeitstempel zurückgegeben.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 fileatime()-Beispiel

    <?php

    // Ausgabe z. B.: Letzer Zugriff auf somefile.txt: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "Letzer Zugriff auf $filename: " . date("F d Y H:i:s.", fileatime($filename));
    }

    ?>

### Anmerkungen

> Hinweis:

> Der atime-Wert einer Datei soll sich immer dann ändern, wenn die Dateiblöcke einer Datei gelesen werden. Dies kann in Bezug auf die Performance teuer sein, falls eine Anwendung regelmäßig auf eine sehr große Anzahl an Dateien oder Verzeichnissen zugreift.

> Einige Unix-Dateisysteme können so eingebunden werden, dass die Aktualisierung von atime ausgeschaltet ist, um die Performace solcher Anwendungen zu steigern. USENET-News-Spools sind ein bekanntes Beispiel. Auf solchen Dateisystemen ist diese Funktion nutzlos.

> Hinweis:

> Beachten Sie, dass die zeitliche Auflösung bei verschiedenen Dateisystemen unterschiedlich sein kann.

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- filemtime() - Liefert die Zeit der letzten Dateiänderung
- fileinode() - Liefert die Inode-Nummer einer Datei
- date() - Formatiert einen Unix-Zeitstempel

# filectime

(PHP 4, PHP 5, PHP 7, PHP 8)

filectime — Liefert die Änderungszeit eines Datei-Inodes

### Beschreibung

function filectime(string `$filename`): int|false

Gibt die Zeit der letzten Änderung eines Datei-Inodes zurück.

### Parameter-Liste

`filename`

  Pfad zu der Datei.

### Rückgabewerte

Gibt die Zeit der letzten Änderung einer Datei zurück. Bei einem Fehler wird `false` zurückgegeben. Die Zeit wird als UNIX-Zeitstempel zurückgegeben.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 filectime()-Beispiel

    <?php

    // Ausgabe z. B. somefile.txt wurde zuletzt geändert: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename wurde zuletzt geändert: " . date("F d Y H:i:s.", filectime($filename));
    }

    ?>

### Anmerkungen

> Hinweis:

> Anmerkung: Bei den meisten Unix-Dateisystemen gilt eine Datei als geändert, sobald ihre Inode-Daten geändert wurden; d. h. wenn die Berechtigungen, Eigentümer, Gruppe oder andere Metadaten des Inodes aktualisiert werden. Siehe auch filemtime() (was man verwenden sollte, um Fußzeilen mit "Zuletzt Aktualisiert" für Webseiten zu erstellen) und fileatime().

> Hinweis:

> Es ist auch zu beachten, dass in einigen Unix-Texten ctime als die Zeit der Erstellung der Datei beschrieben wird. Das ist falsch. Bei den meisten Unix-Dateisystemen gibt es keine Zeitangabe für die Erstellung von Unix-Dateien.

> Hinweis:

> Beachten Sie, dass die zeitliche Auflösung bei verschiedenen Dateisystemen unterschiedlich sein kann.

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- filemtime() - Liefert die Zeit der letzten Dateiänderung

# filegroup

(PHP 4, PHP 5, PHP 7, PHP 8)

filegroup — Liefert die Gruppenzugehörigkeit einer Datei

### Beschreibung

function filegroup(string `$filename`): int|false

Ermittelt die Gruppenzugehörigkeit einer Datei. Die Gruppen-ID wird in numerischer Form zurückgegeben, der zugehörige Gruppenname kann mit posix_getgrgid() ermittelt werden.

### Parameter-Liste

`filename`

  Path to the file.

### Rückgabewerte

Gibt die Gruppen ID einer Datei zurück, oder `false` wenn ein Fehler aufgetreten ist. Die Gruppen ID wird im numerischen Format zurückgegeben. Mit der Funktion posix_getgrgid() können Sie diese zu ihrem Gruppennamen auflösen.

### Fehler/Exceptions

Im Fehlerfall wird ein `E_WARNING` Fehler gemeldet.

### Beispiele

Beispiel #1 Finding the group of a file

    <?php
    $filename = 'index.php';
    print_r(posix_getgrgid(filegroup($filename)));
    ?>

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- fileowner() - Liefert den Eigentümer einer Datei
- posix_getgrgid() - Liefert zu einer Gruppen-ID Informationen über diese Gruppe

# fileinode

(PHP 4, PHP 5, PHP 7, PHP 8)

fileinode — Liefert die Inode-Nummer einer Datei

### Beschreibung

function fileinode(string `$filename`): int|false

Gibt die Inode-Nummer einer Datei zurück.

### Parameter-Liste

`filename`

  Pfad zu der Datei.

### Rückgabewerte

Gibt die Inode-Nummer der Datei zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 Vergleich des Inodes einer Datei mit dem der aktuellen Datei

    <?php
    $filename = 'index.php';
    if (getmyinode() == fileinode($filename)) {
        echo 'Sie prüfen die aktuelle Datei.';
    }
    ?>

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- getmyinode() - Liefert den Inode des aktuellen Skripts
- stat() - Sammelt Informationen über eine Datei

# filemtime

(PHP 4, PHP 5, PHP 7, PHP 8)

filemtime — Liefert die Zeit der letzten Dateiänderung

### Beschreibung

function filemtime(string `$filename`): int|false

Diese Funktion gibt die Zeit zurück, zu der die Datenblöcke einer Datei beschrieben wurden, das heißt, den Zeitpunkt, zu dem der Inhalt der Datei zuletzt geändert wurde.

### Parameter-Liste

`filename`

  Pfad zu der Datei.

### Rückgabewerte

Gibt die Zeit zurück, zu der die Datei zuletzt modifiziert wurde. Bei einem Fehler wird `false` zurückgegeben. Die Zeit wird als UNIX-Zeitstempel zurückgegeben, was für die Funktion date() passend ist.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 filemtime()-Beispiel

    <?php
    // Ausgabe z. B. somefile.txt wurde zuletzt modifiziert: December 29 2002 22:16:23.

    $filename = 'somefile.txt';
    if (file_exists($filename)) {
        echo "$filename wurde zuletzt modifiziert: " . date ("F d Y H:i:s.", filemtime($filename));
    }
    ?>

### Anmerkungen

> Hinweis:

> Beachten Sie, dass die zeitliche Auflösung bei verschiedenen Dateisystemen unterschiedlich sein kann.

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- filectime() - Liefert die Änderungszeit eines Datei-Inodes
- stat() - Sammelt Informationen über eine Datei
- touch() - Setzt die Zugriffs- und Modifikationszeit einer Datei
- getlastmod() - Liefert die Uhrzeit der letzten Änderung eines Skripts

# fileowner

(PHP 4, PHP 5, PHP 7, PHP 8)

fileowner — Liefert den Eigentümer einer Datei

### Beschreibung

function fileowner(string `$filename`): int|false

Gibt den Eigentümer einer Datei zurück.

### Parameter-Liste

`filename`

  Pfad zu der Datei.

### Rückgabewerte

Gibt die Benutzer-ID des Eigentümers einer Datei zurück. Bei einem Fehler wird `false` zurückgegeben. Die Benutzer-ID wird in numerischem Format zurückgegeben und kann mit der Funktion posix_getpwuid() zum Benutzernamen aufgelöst werden.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 Den Eigentümer einer Datei finden

    <?php
    $filename = 'index.php';
    print_r(posix_getpwuid(fileowner($filename)));
    ?>

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- filegroup() - Liefert die Gruppenzugehörigkeit einer Datei
- stat() - Sammelt Informationen über eine Datei
- posix_getpwuid() - Liefert zu einer Benutzer-ID Informationen über diesen Benutzer

# fileperms

(PHP 4, PHP 5, PHP 7, PHP 8)

fileperms — Liefert die Zugriffsrechte einer Datei

### Beschreibung

function fileperms(string `$filename`): int|false

Gibt die Zugriffsrechte für die übergebene Datei zurück.

### Parameter-Liste

`filename`

  Der Pfad zur Datei.

### Rückgabewerte

Gibt die Zugriffsrechte einer Datei als numerischen Modus zurück. Die niedrigen Bits dieses Modus sind die gleichen wie die Zugriffsrechte, die chmod() erwartet, allerdings beinhaltet der Rückgabewert auf den meisten Plattformen ebenfalls Informationen über den Typ der Datei, die als `filename` angegeben wurde. Die Beispiele weiter unten demonstrieren wie der Rückgabewert auf spezifische Zugriffsrechte und Dateitypen auf POSIX-Systemen einschließlich Linux und macOS geprüft werden kann.

Für lokale Dateien wird der spezifische `st_mode`-Wert der C-Struktur verwendet, die von der Funktion stat() zurückgegeben wird. Die betroffenen Bits können sich je nach Plattform ändern und wenn es erforderlich ist, Bits des Rückgabewertes zu analysieren, die nicht die Zugriffsrechte betreffen, wird empfohlen, in der Dokumentation der jeweiligen Plattform nachzuschlagen.

Gibt bei einem Fehler `false` zurück.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 Zeige die Zugriffsrechte als Oktalwert an

    <?php
    echo substr(sprintf('%o', fileperms('/tmp')), -4);
    echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1777
    0644

Beispiel #2 Zeige die kompletten Zugriffsrechte an

    <?php
    $perms = fileperms('/etc/passwd');

    switch ($perms & 0xF000) {
        case 0xC000: // Socket
            $info = 's';
            break;
        case 0xA000: // Symbolischer Link
            $info = 'l';
            break;
        case 0x8000: // Regulär
            $info = 'r';
            break;
        case 0x6000: // Block special
            $info = 'b';
            break;
        case 0x4000: // Verzeichnis
            $info = 'd';
            break;
        case 0x2000: // Character special
            $info = 'c';
            break;
        case 0x1000: // FIFO pipe
            $info = 'p';
            break;
        default: // unbekannt
            $info = 'u';
    }

    // Besitzer
    $info .= (($perms & 0x0100) ? 'r' : '-');
    $info .= (($perms & 0x0080) ? 'w' : '-');
    $info .= (($perms & 0x0040) ?
                (($perms & 0x0800) ? 's' : 'x' ) :
                (($perms & 0x0800) ? 'S' : '-'));

    // Gruppe
    $info .= (($perms & 0x0020) ? 'r' : '-');
    $info .= (($perms & 0x0010) ? 'w' : '-');
    $info .= (($perms & 0x0008) ?
                (($perms & 0x0400) ? 's' : 'x' ) :
                (($perms & 0x0400) ? 'S' : '-'));

    // Andere
    $info .= (($perms & 0x0004) ? 'r' : '-');
    $info .= (($perms & 0x0002) ? 'w' : '-');
    $info .= (($perms & 0x0001) ?
                (($perms & 0x0200) ? 't' : 'x' ) :
                (($perms & 0x0200) ? 'T' : '-'));

    echo $info;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    -rw-r--r--

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- chmod() - Ändert den Modus für die Zugriffsrechte einer Datei
- is_readable() - Prüft, ob eine Datei existiert und lesbar ist
- stat() - Sammelt Informationen über eine Datei

# filesize

(PHP 4, PHP 5, PHP 7, PHP 8)

filesize — Liefert die Größe einer Datei

### Beschreibung

function filesize(string `$filename`): int|false

Gibt die Größe der übergebenen Datei zurück.

### Parameter-Liste

`filename`

  Pfad zu der Datei.

### Rückgabewerte

Gibt die Größe einer Datei in Bytes zurück, oder `false` (und erzeugt einen Fehler der Stufe `E_WARNING`), wenn ein Fehler auftrat.

> Hinweis: Weil PHPs Integer Typ vorzeichenbehaftet ist und viele Platformen 32bit Integer verwenden, können einige Dateisystem-Funktionen für Dateien größer als 2GB unerwartete Ergebnisse liefern.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 filesize()-Beispiel

    <?php

    // Ausgabe z. B. somefile.txt: 1024 Byte

    $filename = 'somefile.txt';
    echo $filename . ': ' . filesize($filename) . ' Byte';

    ?>

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- file_exists() - Prüft, ob eine Datei oder ein Verzeichnis existiert

# filetype

(PHP 4, PHP 5, PHP 7, PHP 8)

filetype — Liefert den Typ einer Datei

### Beschreibung

function filetype(string `$filename`): string|false

Liefert den Typ der übergebenen Datei.

### Parameter-Liste

`filename`

  Pfad zu der Datei

### Rückgabewerte

Gibt den Typ einer Datei zurück. Mögliche Werte sind fifo, char, dir, block, link, file, socket und unknown.

Gibt `false` zurück, wenn ein Fehler auftrat. filetype() erzeugt auch eine `E_NOTICE`-Meldung, wenn der stat-Aufruf fehlschlägt oder der Dateityp unbekannt ist.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 filetype()-Beispiel

    <?php

    echo filetype('/etc/passwd');
    echo "\n";
    echo filetype('/etc/');

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    file
    dir

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- is_dir() - Prüft, ob der angegebene Dateiname ein Verzeichnis ist
- is_file() - Prüft, ob der Dateiname eine reguläre Datei ist
- is_link() - Prüft, ob der Dateiname ein symbolischer Link ist
- file_exists() - Prüft, ob eine Datei oder ein Verzeichnis existiert
- mime_content_type() - Ermittelt den MIME-Typ des Inhalts einer Datei
- pathinfo() - Liefert Informationen über einen Dateipfad
- stat() - Sammelt Informationen über eine Datei

# flock

(PHP 4, PHP 5, PHP 7, PHP 8)

flock — Portables Datei-Sperrverfahren (advisory locking)

### Beschreibung

function flock(resource `$stream`, int `$operation`, int `&$would_block` = `null`): bool

flock() erlaubt, ein einfaches Leser-/Schreiber-Modell umzusetzen, was auf nahezu jeder Plattform (inklusive der meisten Unix-Abkömmlinge und sogar Windows) genutzt werden kann.

Die Sperre wird auch von fclose() gelöst oder wenn `stream` vom Garbage-Collector eingesammelt wird.

PHP unterstützt ein portables Verfahren, um komplette Dateien "beratend" zu sperren (was bedeutet, dass alle zugreifenden Programme das gleiche Sperrverfahren nutzen müssen, oder die Sperre wird nicht wirken). Standardmäßig wird diese Funktion blockieren, bis die angefragte Sperre erlangt wurde; dies kann mit der unten dokumentierten Option `LOCK_NB` gesteuert werden.

### Parameter-Liste

`stream`

  Eine Dateisystemressource (resource), wie sie in der Regel von fopen() zurückgegeben wird.

`operation`

  `operation` ist einer der folgenden Werte:

  - `LOCK_SH`, um eine geteilte Sperre (Leser) zu erhalten.
  - `LOCK_EX`, um eine exklusive Sperre (Schreiber) zu erhalten.
  - `LOCK_UN`, um eine Sperre zu lösen (geteilt oder exklusiv).

  Man kann auch `LOCK_NB` als Bitmaske zu einer der obigen Operationen hinzufügen, wenn flock() während des Sperrversuchs nicht blockieren soll.

`would_block`

  Das optionale dritte Argument wird auf 1 gesetzt, falls die Sperre blockieren würde (EWOULDBLOCK-Fehlernummer).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 flock()-Beispiel

    <?php

    $fp = fopen("/tmp/lock.txt", "r+");

    if (flock($fp, LOCK_EX)) { // exklusive Sperre
        ftruncate($fp, 0); // kürze Datei
        fwrite($fp, "Schreibe hier irgendwas\n");
        fflush($fp); // leere Ausgabepuffer, bevor die Sperre aufgehoben wird
        flock($fp, LOCK_UN); // hebe Sperre auf
    } else {
        echo "Konnte Sperre nicht erhalten!";
    }

    fclose($fp);

    ?>

Beispiel #2 flock() mit der Option `LOCK_NB`

    <?php
    $fp = fopen('/tmp/lock.txt', 'r+');

    /* Aktiviere die LOCK_NB-Option bei einer LOCK_EX-Operation */
    if(!flock($fp, LOCK_EX | LOCK_NB)) {
        echo 'Kann Sperre nicht erhalten';
        exit(-1);
    }

    /* ... */

    fclose($fp);
    ?>

### Anmerkungen

> Hinweis:

> flock() nutzt unter Windows "verbindliche" (mandatory) anstatt "beratende" (advisory) Sperren. "Verbindliches" Sperren wird auch unter Linux und System-V-basierten Betriebssystemen durch den üblichen Mechanismus, der von dem fcntl()-Systemaufruf geliefert wird, unterstützt: das heißt, falls bei der fraglichen Datei das setgid-Zugriffs-Bit gesetzt ist und das Ausführungs-Bit für Gruppen null ist. Unter Linux muss das Dateisystem zusätzlich mit der Mount-Option mand eingebunden sein, damit dies Auswirkungen hat.

> Hinweis:

> Da flock() einen Dateizeiger benötigt, muss unter Umständen eine spezielle Sperrdatei benutzt werden, um den Zugriff auf eine Datei zu schützen, welche Sie mittels Öffnen im Schreibmodus (mit dem Argument "w" or "w+" von fopen()) kürzen wollen.

> Hinweis:

> Kann nur mit Dateizeigern verwendet werden, die von fopen() für lokale Dateien zurückgegeben wurden, oder mit Dateizeigern, die auf Userspace-Streams zeigen, die die streamWrapper::stream_lock()-Methode implementieren.

Warnung

Weist man dem `stream`-Argument einen anderen Wert zu, wird nachfolgender Code die Sperre lösen.

Warnung

Bei einigen Betriebssystemen ist flock() auf dem Prozesslevel implementiert. Wenn Sie eine Multithreaded-Server-API benutzen, können Sie sich nicht auf flock() verlassen, um Dateien vor anderen PHP-Skripten zu schützen, welche in parallelen Threads der gleichen Server-Instanz laufen!

flock() wird von antiquierten Dateisystemen wie `FAT` und dessen Derivaten nicht unterstützt, und gibt deshalb in solchen Umgebungen immer `false` zurück.

> Hinweis:

> Wenn der sperrende Prozess unter Windows die Datei ein zweites Mal öffnet, kann er auf die Datei über dieses zweite Handle zugreifen, bis er die Datei entsperrt.

# fnmatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

fnmatch — Match filename against a pattern

### Beschreibung

function fnmatch(string `$pattern`, string `$filename`, int `$flags` = 0): bool

fnmatch() checks if the passed `filename` would match the given shell wildcard `pattern`.

### Parameter-Liste

`pattern`

  The `pattern` to match against. Usually, the `pattern` will contain wildcards like `'?'` and `'*'`.

  Wildcards to be used in `pattern` parameter
  Wildcard | Beschreibung
  --- | ---
  `?` | Question mark will match any single character. For example, pattern `"file?.txt"` will match `"file1.txt"` and `"fileA.txt"`, but will not match `"file10.txt"`.
  `*` | Asterisk will match zero or more characters. For example, pattern `"foo*.xml"` will match `"foo.xml"` and `"foobar.xml"`.
  `[ ]` | Square brackets are used to create ranges of ASCII codepoints or sets of characters. For example, pattern `"index.php[45]"` will match `"index.php4"` and `"index.php5"`, but will not match `"index.phpt"`. Well known ranges are `[0-9]`, `[a-z]`, and `[A-Z]`. Multiple sets and ranges can be used at the same time, for example `[0-9a-zABC]`.
  `!` | Exclamation mark is used to negate characters within square brackets. For example, `"[!A-Z]*.html"` will match `"demo.html"`, but will not match `"Demo.html"`.
  `\` | Backslash is used to escape special characters. For example, `"Name\?"` will match `"Name?"`, but will not match `"Names"`.

`filename`

  The tested string. This function is especially useful for filenames, but may also be used on regular strings.

  The average user may be used to shell patterns or at least in their simplest form to `'?'` and `'*'` wildcards so using fnmatch() instead of preg_match() for frontend search expression input may be way more convenient for non-programming users.

`flags`

  The value of `flags` can be any combination of the following flags, joined with the binary OR (|) operator.

  A list of possible flags for fnmatch()
  `Flag` | Description
  --- | ---
  `FNM_NOESCAPE` | Disable backslash escaping.
  `FNM_PATHNAME` | Slash in string only matches slash in the given pattern.
  `FNM_PERIOD` | Leading period in string must be exactly matched by period in the given pattern.
  `FNM_CASEFOLD` | Caseless match. Part of the GNU extension.

### Rückgabewerte

Returns `true` if there is a match, `false` otherwise.

### Beispiele

Beispiel #1 Checking a color name against a shell wildcard pattern

    <?php
    if (fnmatch("*gr[ae]y", $color)) {
      echo "some form of gray ...";
    }
    ?>

### Anmerkungen

Warnung

For now, this function is not available on non-POSIX compliant systems except Windows.

### Siehe auch

- glob() - Findet Dateinamen, die mit einem Muster übereinstimmen
- preg_match() - Führt eine Suche mit einem regulären Ausdruck durch
- sscanf() - Überträgt einen String in ein angegebenes Format
- printf() - Liefert einen formatierten String
- sprintf() - Gibt einen formatierten String zurück

# fopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fopen — Öffnet eine Datei oder URL

### Beschreibung

function fopen(
string `$filename`,
string `$mode`,
bool `$use_include_path` = `false`,
?resource `$context` = `null`
): resource|false

fopen() bindet eine benannte Ressource, die durch `filename` spezifiziert wurde, an einen Stream.

### Parameter-Liste

`filename`

  Wenn `filename` die Form "schema://..." hat, wird angenommen, dass es sich hier um eine URL handelt, und PHP sucht nach einem Protokollhandler (auch als Wrapper bekannt) für dieses Schema. Sind keine Wrapper für dieses Protokoll registriert, gibt PHP einen Hinweis aus, um Ihnen zu helfen, mögliche Probleme in Ihrem Skript zu erkennen, und fährt dann fort, als ob `filename` eine reguläre Datei spezifiziert.

  Ist PHP zu dem Schluss gekommen, dass `filename` eine lokale Datei spezifiziert, wird es versuchen, einen Stream an dieser Datei zu öffnen. Die Datei muss für PHP zugreifbar sein, weshalb Sie sicherstellen müssen, dass die Dateirechte diesen Zugriff ermöglichen. Wenn Sie open_basedir aktiviert haben, können weitere Einschränkungen gelten.

  Kam PHP zum Schluss, dass es sich bei `filename` um ein registriertes Protokoll handelt, und ist dieses Protokoll als eine Netzwerk-URL registriert, prüft PHP, ob allow_url_fopen aktiviert ist. Ist es nicht aktiviert, gibt PHP eine Warnung aus und der Aufruf von fopen() scheitert.

  > Hinweis:

  > Die Liste der unterstützten Protokolle ist unter Unterstützte Protokolle und Wrapper zu finden. Einige Protokolle (auch als `Wrapper` bezeichnet) unterstützen `context` und/oder php.ini-Optionen. Eine Liste der verfügbaren Optionen finden Sie auf den Handbuchseiten zum verwendeten Protokoll (z. B. die php.ini-Option `user_agent`, die vom `http`-Wrapper verwendet wird).

  Es ist darauf zu achten, unter Windows alle Backslash-Zeichen, die in Pfaden genutzt werden, zu maskieren oder Schrägstriche (Slashes) zu nutzen.

      <?php
      $handle = fopen("c:\\verzeichnis\\ressource.txt", "r");
      ?>

`mode`

  Der Parameter `mode` spezifiziert den Zugriffstyp, der vom Stream gefordert wird. Es kann einer der folgenden sein:

  Eine Liste der möglichen Modi von fopen() mittels `mode`
  `mode` | Beschreibung
  --- | ---
  `'r'` | Nur zum Lesen geöffnet; platziere den Dateizeiger auf den Dateianfang.
  `'r+'` | Zum Lesen und Schreiben geöffnet; platziere den Dateizeiger auf den Dateianfang.
  `'w'` | Nur zum Schreiben geöffnet; platziere den Dateizeiger auf den Dateianfang und kürze die Datei auf eine Länge von 0. Existiert die Datei nicht, versuche, diese zu erzeugen.
  `'w+'` | Zum Schreiben und Lesen geöffnet; ansonsten verhält es sich wie `'w'`..
  `'a'` | Nur zum Schreiben geöffnet; platziere den Dateizeiger auf das Dateiende. Existiert die Datei nicht, versuche, diese zu erzeugen. In diesem Modus ist fseek() wirkungslos; beim Schreiben wird immer angehängt.
  `'a+'` | Zum Schreiben und Lesen geöffnet; platziere den Dateizeiger auf das Dateiende. Existiert die Datei nicht, versuche, diese zu erzeugen. In diesem Modus wirkt sich fseek() nur auf die Leseposition aus; beim Schreiben wird immer angehängt.
  `'x'` | Erzeuge und öffne nur zum Schreiben; platziere den Dateizeiger auf den Dateianfang. Falls die Datei schon existiert, wird der fopen()-Aufruf fehlschlagen, indem er `false` zurückgibt und dem einen Fehler der Stufe `E_WARNING` auslöst. Existiert die Datei nicht, versuche, diese zu erzeugen. Dies ist zur Angabe der `O_EXCL|O_CREAT`-Flags für den darunterliegenden `open(2)`-Systemaufruf äquivalent.
  `'x+'` | Erzeuge und öffne zum Schreiben und Lesen; ansonsten ist das Verhalten gleich wie bei `'x'`.
  `'c'` | Öffne die Datei nur zum Schreiben. Wenn die Datei nicht existiert, wird diese erzeugt. Wenn sie existiert, wird sie weder gekürzt (im Gegensatz zu `'w'`), noch schlägt der Aufruf dieser Funktion fehl (wie dies mit `'x'` der Fall ist). Der Dateizeiger wird auf den Dateianfang platziert. Dies kann nützlich sein, wenn man eine "beratende" (kooperative) Sperre erhalten möchte (siehe flock()), bevor man versucht, die Datei zu ändern, da die Nutzung von `'w'` die Datei kürzen könnte, bevor die Sperre erhalten wurde (falls das Kürzen gewünscht ist, kann ftruncate() genutzt werden, nachdem die Sperre angefragt wurde).
  `'c+'` | Öffne Datei zum Lesen und Schreiben; ansonsten ist das Verhalten gleich wie bei `'c'`.
  `'e'` | Setzt das Flag close-on-exec für den geöffneten Datei-Deskriptor. Nur verfügbar, wenn PHP auf POSIX.1-2008-konformen System kompiliert wurde.
  `'n'` | Setzt das Flag non-blocking flag für den geöffneten Datei-Deskriptor. Nur verfügbar, wenn PHP auf POSIX.1-2008-konformen System kompiliert wurde.

  > Hinweis:

  > Verschiedene Betriebssysteme haben unterschiedliche Konventionen für das Zeilenende. Wenn Sie eine Textdatei schreiben und einen Zeilenumbruch einfügen möchten, müssen Sie das/die korrekte(n) Zeilenendezeichen für Ihr Betriebssystem nutzen. Unix-basierte Systeme nutzen `\n` als Zeilenendezeichen, Windows-basierte Systeme nutzen `\r\n` als Zeilenendezeichen und Macintosh-basierte Systeme (Mac OS Classic) nutzten `\r` als Zeilenendezeichen.

  > Wenn Sie die falschen Zeilenendezeichen beim Schreiben Ihrer Dateien nutzen, kann es sein, dass andere Anwendungen, die diese Dateien öffnen, "seltsam aussehen".

  > Windows bietet ein Übersetzungs-Flag (`'t'`) fur den Textmodus an, das `\n` transparent in `\r\n` übersetzt, wenn mit der Datei gearbeitet wird. Andererseits kann auch `'b'` genutzt werden, um den Binärmodus zu erzwingen, der die Daten nicht übersetzt. Um diese Flags zu nutzen, wird entweder `'b'` oder `'t'` als das letzte Zeichen des Parameters `mode` angegeben.

  > Der Standard-Übersetzungsmodus ist `'b'`. Es kann der Modus `'t'` genutzt werden, wenn mit Textdateien gearbeitet wird und `\n` verwendet wird, um die Zeilenenden im Skript zu begrenzen, aber erwartet wird, dass die Dateien mit Anwendungen wie etwa alten Versionen von Notepad lesbar sind. Ansonsten sollte `'b'` genutzt werden.

  > Wird beim Arbeiten mit binären Dateien das Flag 't' angegeben, können seltsame Probleme mit den Daten auftreten, einschließlich zerstörter Bilddateien und merkwürdiger Probleme mit `\r\n`-Zeichen.

  > Hinweis:

  > Aus Portabilitätsgründen wird ebenfalls dringend empfohlen, dass Code, der den Modus `'t'` nutzt oder sich darauf verlässt, so umgeschrieben wird, dass stattdessen die korrekten Zeilenendungen und der Modus `'b'` genutzt werden.

  > Hinweis: Der Parameter `mode` wird bei den Stream-Wrappern php://output, php://input, php://stdin, php://stdout, php://stderr und php://fd ignoriert.

`use_include_path`

  Der optionale dritte Parameter `use_include_path` kann auf `true` gesetzt werden, wenn auch im include_path nach der Datei gesucht werden soll.

`context`

  Eine Stream-Kontext-Ressource.

### Rückgabewerte

Gibt bei Erfolg eine Dateizeiger-Ressource zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Changelog

Version | Beschreibung
--- | ---
7.0.16, 7.1.2 | Die Option `'e'` wurde hinzugefügt.

### Beispiele

Beispiel #1 fopen()-Beispiele

    <?php
    $handle = fopen("/home/rasmus/file.txt", "r");
    $handle = fopen("/home/rasmus/file.gif", "wb");
    $handle = fopen("http://www.example.com/", "r");
    $handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
    ?>

### Anmerkungen

Warnung

Bei SSL-Verbindungen zusammen mit Microsoft IIS hält sich dieser Webserver nicht an das Protokoll und schließt die Verbindung ohne ein `close_notify` zu senden. PHP quittiert dieses Fehlverhalten mit "SSL: Fatal Protocol Error", wenn das Ende der Daten erreicht ist. Eine mögliche Lösung besteht darin, den Level von error_reporting herabzusetzten und Warnings auszuschließen. PHP kann fehlerhafte IIS-Serversoftware erkennen, wenn Sie einen Stream mit dem `https://`-Wrapper öffnen, und unterdrückt die Warnung für Sie. Falls Sie fsockopen() benutzen, um einen `ssl://`-Socket zu öffnen, müssen Sie selbst dafür Sorge tragen, die Warnung zu erkennen und diese zu unterdrücken.

> Hinweis:

> Wenn die Servermodul-Version von PHP wird verwendet wird und beim Lesen und Schreiben von Dateien Probleme auftreten, ist sicherzustellen, dass die Dateien und Verzeichnisse, die genutzt werden, für den Server-Prozess zugänglich sind.

> Hinweis:

> Diese Funktion kann auch dann funktionieren, wenn `filename` ein Verzeichnis ist. Im Zweifelsfall sollte vor dem Aufruf von fopen() mit is_dir() geprüft werden, ob `filename` eine Datei oder ein Verzeichnis ist.

### Siehe auch

- Unterstützte Protokolle und Wrapper
- fclose() - Schließt einen offenen Dateizeiger
- fgets() - Liest die Zeile von der Position des Dateizeigers
- fread() - Liest Binärdaten aus einer Datei
- fwrite() - Binär-sicheres Dateischreiben
- fsockopen() - Stellt eine Internet- oder Unix-Domain-Socket-Verbindung her
- file() - Liest eine komplette Datei in ein Array
- file_exists() - Prüft, ob eine Datei oder ein Verzeichnis existiert
- is_readable() - Prüft, ob eine Datei existiert und lesbar ist
- stream_set_timeout() - Set timeout period on a stream
- popen() - Öffnet einen Dateizeiger für einen Prozess
- stream_context_create() - Creates a stream context
- umask() - Changes the current umask
- SplFileObject

# fpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

fpassthru — Gibt alle verbleibenden Daten eines Dateizeigers aus

### Beschreibung

function fpassthru(resource `$stream`): int

Die Funktion liest alle Daten von der aktuellen Position des Dateizeigers bis EOF aus und schreibt die Daten in den Ausgabepuffer.

Eventuell muss rewind() aufgerufen werden, um den Dateizeiger auf den Beginn der Datei zurückzusetzen, wenn bereits Daten in die Datei geschrieben wurden.

Wenn nur der Inhalt einer Datei in den Ausgabepuffer geschrieben werden soll, ohne diese ändern bzw. an eine bestimmte Stelle zu gehen, sollte besser readfile() benutzt werden, bei der man sich den Aufruf von fopen() ersparen kann.

### Parameter-Liste

`stream`

  Der Zeiger auf eine Datei muss gültig sein und auf eine Datei verweisen, die vorher erfolgreich mit fopen() oder fsockopen() geöffnet (und nicht bereits von fclose() geschlossen) wurde.

### Rückgabewerte

Gibt die Anzahl der von `stream` gelesenen und zur Ausgabe weitergeleiteten Zeichen zurück.

### Beispiele

Beispiel #1 Nutzung von fpassthru() mit binären Dateien

    <?php

    // Öffne Datei im binären Modus
    $name = './img/ok.png';
    $fp = fopen($name, 'rb');

    // Schicke passende Header
    header("Content-Type: image/png");
    header("Content-Length: " . filesize($name));

    // Gib Bild aus und stoppe Skript
    fpassthru($fp);
    exit;

    ?>

### Anmerkungen

> Hinweis:

> Wenn Sie fpassthru() auf eine binäre Datei unter Windows anwenden, sollten Sie sicherstellen, dass die Datei im Binärmodus geöffnet wurde, indem Sie ein `b` an den Mode-Parameter von fopen() anhängen.

> Auch wenn es Ihr System nicht verlangt, sollten Sie bei Binärdateien das Flag `b` verwenden, um die Portabilität Ihrer Skripte zu erhöhen.

### Siehe auch

- readfile() - Gibt eine Datei aus
- fopen() - Öffnet eine Datei oder URL
- popen() - Öffnet einen Dateizeiger für einen Prozess
- fsockopen() - Stellt eine Internet- oder Unix-Domain-Socket-Verbindung her

# fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsv — Format line as CSV and write to file pointer

### Beschreibung

function fputcsv(
resource `$stream`,
array `$fields`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\",
string `$eol` = "\n"
): int|false

fputcsv() formats a line (passed as a `fields` array) as CSV and writes it (terminated by a `eol`) to the specified `stream`.

### Parameter-Liste

`stream`

  Der Zeiger auf eine Datei muss gültig sein und auf eine Datei verweisen, die vorher erfolgreich mit fopen() oder fsockopen() geöffnet (und nicht bereits von fclose() geschlossen) wurde.

`fields`

  An array of strings.

`separator`

  Der Parameter `separator` setzt das Feld-Trennzeichen. Es muss ein Single-Byte-Zeichen sein.

`enclosure`

  Der Parameter `enclosure` setzt das Feld-Begrenzungszeichen. Es muss ein Single-Byte-Zeichen sein.

`escape`

  Der Parameter `escape` setzt das Maskierungs-Zeichen. Es muss ein Single-Byte-Zeichen oder die leere Zeichenkette sein. Die leere Zeichenkette (`""`) deaktiviert den proprietären Maskierungsmechanismus.

  Warnung

  Im Eingabe Stream kann das `enclosure`-Zeichen immer maskiert werden, indem es innerhalb einer in Anführungszeichen gesetzten Zeichenkette verdoppelt wird, was zu einem einzelnen `enclosure`-Zeichen im geparsten Ergebnis führt. Das `escape`-Zeichen funktioniert anders: wenn eine Sequenz aus `escape`- und `enclosure`-Zeichen in der Eingabe erscheint, werden beide Zeichen im geparsten Ergebnis vorhanden sein. Für die Standardparameter wird also eine CSV-Zeile wie `"a""b","c\"d"` die Felder als `a"b` und `c\"d` parsen.

  Warnung

  Seit PHP 8.4.0 ist es veraltet, sich auf den Standardwert von `escape` zu verlassen. Er muss explizit angegeben werden, entweder an der richtigen Stelle oder durch die Verwendung von benannten Argumenten.

`eol`

  The optional `eol` parameter sets a custom End of Line sequence.

Warnung

Wenn `escape` auf etwas anderes als eine leere Zeichenkette (`""`) gesetzt wird, kann dies zu einer CSV-Datei führen, die nicht mit » RFC 4180 konform ist oder die den Umlauf durch die PHP-CSV-Funktionen nicht übersteht. Der Standardwert für `escape` ist `"\\"`, weshalb empfohlen wird, diesen Parameter explizit auf eine leere Zeichenkette zu setzen. Der Standardwert wird sich in einer zukünftigen Version von PHP ändern, jedoch nicht vor PHP 9.0.

> Hinweis:

> If an `enclosure` character is contained in a field, it will be escaped by doubling it, unless it is immediately preceded by an `escape`.

### Rückgabewerte

Returns the length of the written string Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

Wenn `separator` oder `enclosure` nicht ein Byte lang ist, wird ein ValueError geworfen.

Wenn `escape` nicht ein Byte lang oder eine leere Zeichenkette ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Sich auf den Standardwert von `escape` zu verlassen, ist nun veraltet.
8.1.0 | The optional `eol` parameter has been added.
7.4.0 | The `escape` parameter now also accepts an empty string to disable the proprietary escape mechanism.

### Beispiele

Beispiel #1 fputcsv() example

    <?php

    $list = [
        ['aaa', 'bbb', 'ccc', 'dddd'],
        ['123', '456', '789'],
        ['"aaa"', '"bbb"']
    ];

    $fp = fopen('file.csv', 'w');

    foreach ($list as $fields) {
        fputcsv($fp, $fields, ',', '"', '');
    }

    fclose($fp);
    ?>

The above example will write the following to `file.csv`:

    aaa,bbb,ccc,dddd
    123,456,789
    """aaa""","""bbb"""

### Siehe auch

- fgetcsv() - Liest eine Zeile von der Position des Dateizeigers und prüft diese auf kommaseparierte Werte (CSV)
- str_getcsv() - Parst einen CSV-String in ein Array
- SplFileObject::fgetcsv() - Gets line from file and parse as CSV fields
- SplFileObject::fputcsv() - Write a field array as a CSV line
- SplFileObject::setCsvControl() - Set the delimiter, enclosure and escape character for CSV
- SplFileObject::getCsvControl() - Get the delimiter, enclosure and escape character for CSV

# fputs

(PHP 4, PHP 5, PHP 7, PHP 8)

fputs — Alias von fwrite()

### Beschreibung

Diese Funktion ist ein Alias für: fwrite().

# fread

(PHP 4, PHP 5, PHP 7, PHP 8)

fread — Liest Binärdaten aus einer Datei

### Beschreibung

function fread(resource `$stream`, int `$length`): string|false

fread() liest bis zu `length` Bytes vom Dateizeiger `stream`. Das Lesen wird beendet, sobald eine der folgenden Bedingungen eintritt:

- `length` Bytes wurden gelesen
- Das Dateiende (EOF, end of file) wurde erreicht
- Ein Paket wird verfügbar oder eine Socket-Zeitüberschreitung tritt auf (Bei Netzwerk-Streams)
- Falls dieser Stream beim Lesen gepuffert wird und keine reguläre Datei repräsentiert, wird maximal einmal ein Stück bis zur maximalen Chunkgröße (normalerweise 8192 Bytes) gelesen. Abhängig von den bisher gepufferten Daten können die zurückgelieferten Daten größer als die Chunkgröße sein.

### Parameter-Liste

`stream`

  Eine Dateisystemressource (resource), wie sie in der Regel von fopen() zurückgegeben wird.

`length`

  Bis zu `length` Bytes lesen.

### Rückgabewerte

Gibt die ausgelesene Zeichenkette zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Ein einfaches fread()-Beispiel

    <?php
    // liest den Inhalt einer Datei in einen String
    $filename = "/usr/local/etwas.txt";
    $handle = fopen($filename, "r");
    $contents = fread($handle, filesize($filename));
    fclose($handle);
    ?>

Beispiel #2 Ein fread()-Beispiel mit einer Binärdatei

Warnung

Auf Systemen, welche zwischen Binär- und Textdateien (z. B. Windows) unterscheiden, muss die Datei mit 'b' im fopen() Mode-Parameter geöffnet werden.

    <?php
    $filename = "c:\\files\\somepic.gif";
    $handle = fopen($filename, "rb");
    $contents = fread($handle, filesize($filename));
    fclose($handle);
    ?>

Beispiel #3 fread()-Beispiele für entfernte Dateien

Warnung

Wenn aus etwas gelesen werden soll, was keine normale lokale Datei ist, wie etwa Streams von entfernten Dateien oder von popen() und fsockopen(), so wird das Lesen beendet sobald ein Paket verfügbar ist. Das bedeutet, dass man die Daten in Stücken sammeln muss. Dies wird im unteren Beispiel gezeigt.

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    $contents = stream_get_contents($handle);
    fclose($handle);
    ?>

    <?php
    $handle = fopen("http://www.example.com/", "rb");
    if (FALSE === $handle) {
        exit("Konnte Stream von URL nicht öffnen");
    }

    $contents = '';

    while (!feof($handle)) {
      $contents .= fread($handle, 8192);
    }
    fclose($handle);
    ?>

### Anmerkungen

> Hinweis:

> Wenn man nur den Inhalt einer Datei in eine Zeichenkette lesen will, so sollte man file_get_contents() verwenden, da dies eine bessere Performance hat als der obige Code.

> Hinweis:

> Beachten Sie, dass fread() an der aktuellen Position im Dateizeiger zu lesen beginnt. Verwenden Sie ftell(), um herauszufinden wo dieser Zeiger steht und die Funktion rewind(), um den Zeiger zurückzustellen.

### Siehe auch

- fwrite() - Binär-sicheres Dateischreiben
- fopen() - Öffnet eine Datei oder URL
- fsockopen() - Stellt eine Internet- oder Unix-Domain-Socket-Verbindung her
- popen() - Öffnet einen Dateizeiger für einen Prozess
- fgets() - Liest die Zeile von der Position des Dateizeigers
- fgetss() - Liest eine Zeile von der Position des Dateizeigers und entfernt HTML Tags.
- fscanf() - Interpretiert den Input einer Datei entsprechend einem angegebenen Format
- file() - Liest eine komplette Datei in ein Array
- fpassthru() - Gibt alle verbleibenden Daten eines Dateizeigers aus
- fseek() - Positioniert den Dateizeiger
- ftell() - Ermittelt die aktuelle Position des Dateizeigers
- rewind() - Setzt die Position eines Dateizeigers auf den Anfang
- unpack() - Entpackt die Daten einer binäre Zeichenkette

# fscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fscanf — Interpretiert den Input einer Datei entsprechend einem angegebenen Format

### Beschreibung

function fscanf(resource `$stream`, string `$format`, mixed `&...$vars`): array|int|false|null

Die Funktion fscanf() ist ähnlich zu sscanf(), wobei sie ihren Input aus der mit `stream` angegebenen Datei liest, und entsprechend dem angegebenen `format` interpretiert.

Beliebige Whitespace-Zeichen (z. B. Leerzeichen, Tabulator etc.) im Format String gelten mit beliebigen Whitespace-Zeichen des Input-Streams als übereinstimmend. Das heißt, dass auch ein Tabulator (`\t`) im Formatstring mit einem einzigen Leerzeichen im Input-Stream als übereinstimmend gelten kann.

Jeder fscanf()-Aufruf liest eine Zeile aus der Datei aus.

### Parameter-Liste

`stream`

  Eine Dateisystemressource (resource), wie sie in der Regel von fopen() zurückgegeben wird.

`format`

  Das interpretierte Format für `string`, wie es in der Dokumentation zu sprintf() beschrieben ist, mit den folgenden Unterschieden:

  - Die Funktion beachtet die Locale nicht.
  - `F`, `g`, `G` und `b` werden nicht unterstützt.
  - `D` steht für eine Dezimalzahl.
  - `i` steht für eine Ganzzahl mit Angabe der Basis.
  - `n` steht für die Anzahl der bisher verarbeiteten Zeichen.
  - `s` beendet das Lesen beim ersten Whitespace-Zeichen.
  - `*` anstelle von `argnum$` unterdrückt die Zuweisung dieser Umwandlungsspezifikation.
`vars`
  Die optional zugewiesenen Werte.

### Rückgabewerte

Wenn nur zwei Parameter an die Funktion übergeben wurden, werden die geparseten Werte als array zurückgegeben. Andernfalls gibt die Funktion die Anzahl der zugewiesenen Werte zurück. Die optionalen Parameter müssen per Referenz übergeben werden.

Wenn im `format` mehr Teilstrings erwartet werden, als in `string` verfügbar sind, wird `null` zurückgegeben. Bei anderen Fehlern wird `false` zurückgegeben.

Wenn optionale Parameter verwendet werden und das Ende des aus `stream` gelesenen Inputs erreicht wird, bevor ein Wert geparst werden konnte, wird `-1` zurückgegeben.

### Beispiele

Beispiel #1 fscanf()-Beispiel

    <?php
    $handle = fopen("users.txt", "r");
    while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
        list ($name, $profession, $countrycode) = $userinfo;
        // Tue etwas mit den Werten ...
    }
    fclose($handle);
    ?>

Beispiel #2 Inhalt der Datei users.txt

    javier  argonaut        pe
    hiroshi sculptor        jp
    robert  slacker us
    luigi   florist it

### Siehe auch

- fread() - Liest Binärdaten aus einer Datei
- fgets() - Liest die Zeile von der Position des Dateizeigers
- fgetss() - Liest eine Zeile von der Position des Dateizeigers und entfernt HTML Tags.
- sscanf() - Überträgt einen String in ein angegebenes Format
- printf() - Liefert einen formatierten String
- sprintf() - Gibt einen formatierten String zurück

# fseek

(PHP 4, PHP 5, PHP 7, PHP 8)

fseek — Positioniert den Dateizeiger

### Beschreibung

function fseek(resource `$stream`, int `$offset`, int `$whence` = `SEEK_SET`): int

Setzt den Dateizeiger einer mit `stream` angegebenen Datei auf eine neue Position. Diese neue Position, angegeben in Bytes vom Beginn der Datei an, wird definiert durch Hinzufügen von `offset` zu der Position spezifiziert durch `whence`.

Im Allgemeinen ist es erlaubt hinter das Ende der Datei (EOF) zu positionieren; wenn dann Daten geschrieben werden, ergeben Leseoperation in einer unbeschriebenen Region zwischen dem EOF und der gesetzten Position Bytes mit dem Wert 0. Allerdings unterstützen bestimmte Streams dieses Verhalten möglicherweise nicht, besonders wenn sie einen unterliegenden Speicher fester Größe haben.

### Parameter-Liste

`stream`

  Eine Dateisystemressource (resource), wie sie in der Regel von fopen() zurückgegeben wird.

`offset`

  Der Offset.

  Um zu einer Position vor EOF zu gelangen, muss in `offset` ein negativer Wert übergeben werden und `whence` auf `SEEK_END` gesetzt werden.

`whence`

  `whence` Werte sind:

  - `SEEK_SET` - Setzt Position gleich `offset` Bytes vom Anfang der Datei.
  - `SEEK_CUR` - Setzt Position auf die aktuelle Stelle plus `offset` Bytes.
  - `SEEK_END` - Setzt die Position ans Ende der Datei plus `offset` Bytes.

### Rückgabewerte

Bei Erfolg wird `0` zurückgegeben, andernfalls `-1`.

Warnung

Diese Funktion wurde erstellt, um die gleichnamige Funktion der Sprache C nachzuahmen. Es ist wichtig, auf die Rückgabewerte zu achten, da sie sich dem unterscheiden, was man in PHP erwarten würde.

### Beispiele

Beispiel #1 fseek()-Beispiel

    <?php

    $fp = fopen('somefile.txt', 'r');

    // lies einige Daten
    $data = fgets($fp, 4096);

    // gehe zurück an den Anfang der Datei
    // das selbe wie rewind($fp);
    fseek($fp, 0);

    ?>

### Anmerkungen

> Hinweis:

> Wenn Sie die Datei im Anfügemodus (`a` oder `a+`) geöffnet haben, werden jegliche Daten, die sie in die Datei schreiben, immer angehängt, unabhängig vom Dateizeiger, und das Ergebnis des Aufrufs von seek() ist undefiniert.

> Hinweis:

> Nicht alle Streams unterstützen Positionierung. Für jene, die Positionierung nicht unterstützen, kann Vorwärtspositionierung durch Lesen und Verwerfen von Daten erreicht werden; andere Formen der Positionierung schlagen fehl.

### Siehe auch

- ftell() - Ermittelt die aktuelle Position des Dateizeigers
- rewind() - Setzt die Position eines Dateizeigers auf den Anfang

# fstat

(PHP 4, PHP 5, PHP 7, PHP 8)

fstat — Sammelt Informationen über eine Datei mittels eines offenen Dateizeigers

### Beschreibung

function fstat(resource `$stream`): array|false

Sammelt die Statistiken der Datei, die durch den Dateizeiger `stream` geöffnet wurde. Diese Funktion ist ähnlich zur Funktion stat(), mit dem Unterschied, dass sie mit einem offenen Dateizeiger anstatt eines Dateinamens arbeitet.

### Parameter-Liste

`stream`

  Eine Dateisystemressource (resource), wie sie in der Regel von fopen() zurückgegeben wird.

### Rückgabewerte

Gibt ein Array mit den Statistiken der Datei zurück. Das Format des Arrays wird auf der stat()-Handbuchseite im Detail beschrieben. Gibt bei einem Fehler `false` zurück.

### Beispiele

Beispiel #1 fstat()-Beispiel

    <?php

    // öffne eine Datei
    $fp = fopen("/etc/passwd", "r");

    // sammle Statistiken
    $fstat = fstat($fp);

    // schließe die Datei
    fclose($fp);

    // gebe nur den assoziativen Teil aus
    print_r(array_slice($fstat, 13));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [dev] => 771
        [ino] => 488704
        [mode] => 33188
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 1114
        [atime] => 1061067181
        [mtime] => 1056136526
        [ctime] => 1056136526
        [blksize] => 4096
        [blocks] => 8
    )

### Anmerkungen

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

# fsync

(PHP 8 >= 8.1.0)

fsync — Synchronizes changes to the file (including meta-data)

### Beschreibung

function fsync(resource `$stream`): bool

This function synchronizes changes to the file, including its meta-data. This is similar to fflush(), but it also instructs the operating system to write to the storage media.

### Parameter-Liste

`stream`

  Der Zeiger auf eine Datei muss gültig sein und auf eine Datei verweisen, die vorher erfolgreich mit fopen() oder fsockopen() geöffnet (und nicht bereits von fclose() geschlossen) wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 fsync() example

    <?php

    $file = 'test.txt';

    $stream = fopen($file, 'w');
    fwrite($stream, 'test data');
    fwrite($stream, "\r\n");
    fwrite($stream, 'additional data');

    fsync($stream);
    fclose($stream);
    ?>

### Siehe auch

- fdatasync() - Synchronizes data (but not meta-data) to the file
- fflush() - Schreibt den Ausgabepuffer in eine Datei

# ftell

(PHP 4, PHP 5, PHP 7, PHP 8)

ftell — Ermittelt die aktuelle Position des Dateizeigers

### Beschreibung

function ftell(resource `$stream`): int|false

Gibt die aktuelle Position des Dateizeigers, der durch `stream` referenziert wird, zurück.

### Parameter-Liste

`stream`

  Der Dateizeiger muss gültig sein und auf eine erfolgreich durch fopen() oder popen() geöffnete Datei zeigen. ftell() liefert undefinierte Ergebnisse für reine Anfüge-Streams (geöffnet mit einem "a" Flag).

### Rückgabewerte

Gibt die aktuelle Position des Dateizeigers, der durch `stream` referenziert wird, als Integerzahl zurück, d.h. den Offset im Dateistream.

Wenn ein Fehler auftritt, wird `false` zurückgegeben.

> Hinweis: Weil PHPs Integer Typ vorzeichenbehaftet ist und viele Platformen 32bit Integer verwenden, können einige Dateisystem-Funktionen für Dateien größer als 2GB unerwartete Ergebnisse liefern.

### Beispiele

Beispiel #1 ftell() Beispiel

    <?php

    // öffnet eine Datei und liest einige Daten
    $fp = fopen("/etc/passwd", "r");
    $data = fgets($fp, 12);

    // wo sind wir?
    echo ftell($fp); // 11

    fclose($fp);

    ?>

### Siehe auch

- fopen() - Öffnet eine Datei oder URL
- popen() - Öffnet einen Dateizeiger für einen Prozess
- fseek() - Positioniert den Dateizeiger
- rewind() - Setzt die Position eines Dateizeigers auf den Anfang

# ftruncate

(PHP 4, PHP 5, PHP 7, PHP 8)

ftruncate — Kürzt eine Datei auf die angegebene Länge

### Beschreibung

function ftruncate(resource `$stream`, int `$size`): bool

Nimmt den Dateizeiger `stream`, und verkürzt die Datei auf die Länge `size`.

### Parameter-Liste

`stream`

  Der Dateizeiger.

  > Hinweis:

  > `stream` muss zum Schreiben geöffnet sein.

`size`

  Die Länge, auf die gekürzt werden soll.

  > Hinweis:

  > Ist `size` größer als die Datei, wird die Datei mit Null-Bytes aufgefüllt.

  > Ist `size` kleiner als die Datei, wird die Datei auf diese Größe gekürzt.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Dateikürzungsbeispiel

    <?php
    $filename = 'lorem_ipsum.txt';

    $handle = fopen($filename, 'r+');
    ftruncate($handle, rand(1, filesize($filename)));
    rewind($handle);
    echo fread($handle, filesize($filename));
    fclose($handle);
    ?>

### Anmerkungen

> Hinweis:

> Der Dateizeiger wird nicht geändert.

### Siehe auch

- fopen() - Öffnet eine Datei oder URL
- fseek() - Positioniert den Dateizeiger

# fwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

fwrite — Binär-sicheres Dateischreiben

### Beschreibung

function fwrite(resource `$stream`, string `$data`, ?int `$length` = `null`): int|false

fwrite() schreibt den Inhalt der Zeichenkette `data` in die Datei, auf welche der Dateizeiger `stream` zeigt.

### Parameter-Liste

`stream`

  Eine Dateisystemressource (resource), wie sie in der Regel von fopen() zurückgegeben wird.

`data`

  Die zu schreibende Zeichenkette.

`length`

  Wenn Parameter `length` eine Integer ist, wird das Schreiben nach `length` Bytes beendet, oder wenn das Ende von `data` erreicht ist, je nachdem was eher eintritt.

### Rückgabewerte

fwrite() gibt die Anzahl der geschriebenen Bytes zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

fwrite() erzeugt bei einem Fehler ein `E_WARNING`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `length` ist jetzt nullbar.

### Beispiele

Beispiel #1 Ein einfaches Beispiel für fwrite()

    <?php
    $filename = 'test.txt';
    $somecontent = "Füge dies der Datei hinzu\n";

    // Sichergehen, dass die Datei existiert und beschreibbar ist.
    if (is_writable($filename)) {

        // Wir öffnen $filename im Anfüge-Modus.
        // Der Dateizeiger befindet sich am Ende der Datei, und daher
        // wird später $somecontent mit fwrite() dorthin geschrieben.
        if (!$fp = fopen($filename, "a")) {
             print "Kann die Datei $filename nicht öffnen";
             exit;
        }

        // Schreibe $somecontent in die geöffnete Datei.
        if (fwrite($fp, $somecontent) === FALSE) {
            print "Kann nicht in die Datei $filename schreiben";
            exit;
        }

        print "Fertig, in die Datei $filename wurde $somecontent geschrieben";

        fclose($fp);

    } else {
        print "Die Datei $filename ist nicht schreibbar";
    }
    ?>

### Anmerkungen

> Hinweis:

> Das Schreiben in einen Netzwerkstream kann enden, bevor die gesamte Zeichenkette geschrieben wurde. Der Rückgabewert von fwrite() kann wie folgt überprüft werden:

>     <?php
>     function fwrite_stream($fp, $string) {
>         for ($written = 0; $written < strlen($string); $written += $fwrite) {
>             $fwrite = fwrite($fp, substr($string, $written));
>             if ($fwrite === false) {
>                 return $written;
>             }
>         }
>         return $written;
>     }
>     ?>

> Hinweis:

> Auf Systemen, welche zwischen Binär- und Textdateien unterscheiden (z. B. Windows), muss die Datei mit dem fopen()-Modus-Parameter 'b' geöffnet werden.

> Hinweis:

> Wurde `stream` mit fopen() im Anfügemodus geöffnet, ist das Schreiben mit fwrite() atomar (außer wenn die Länge von `data` die Blockgröße des Dateisystems auf manchen Systemen überschreitet, und solange sich die Datei in einem lokalen Dateisystem befindet), d. h. es besteht keine Notwendigkeit, eine Ressource vor dem Aufruf von fwrite() mit flock() zu sperren; alle Daten werden ohne Unterbrechung geschrieben.

> Hinweis:

> Wird zweimalig in den Dateizeiger geschrieben, werden die Daten an das Ende des Dateiinhalts angehängt:

>     <?php
>     $fp = fopen('data.txt', 'w');
>     fwrite($fp, '1');
>     fwrite($fp, '23');
>     fclose($fp);

>     // der Inhalt von 'data.txt' ist nun 123 und nicht 23!
>     ?>

### Siehe auch

- fread() - Liest Binärdaten aus einer Datei
- fopen() - Öffnet eine Datei oder URL
- fsockopen() - Stellt eine Internet- oder Unix-Domain-Socket-Verbindung her
- popen() - Öffnet einen Dateizeiger für einen Prozess
- file_get_contents() - Liest die gesamte Datei in einen String
- pack() - Packt Daten in eine binäre Zeichenkette

# glob

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

glob — Findet Dateinamen, die mit einem Muster übereinstimmen

### Beschreibung

function glob(string `$pattern`, int `$flags` = 0): array|false

glob() findet Dateipfade, die mit dem angegebenen Muster `pattern` übereinstimmen. Die Übereinstimmung wird nach den gleichen Regeln geprüft, wie in der glob()-Funktion der C-Bibliothek und entspricht weitgehend den Regeln in den üblichen Kommandozeilen-Shells.

Das Verhalten auf Unix- und macOS-Systemen wird durch die systemeigene Implementierung von glob() bestimmt. Unter Windows wird eine Implementierung verwendet, die der POSIX-Definition 1003.2 für glob() entspricht und eine Erweiterung enthält, mit der die `[!...]`-Konvention für die Negierung eines Bereichs behandelt werden kann.

### Parameter-Liste

`pattern`

  Das Suchmuster. Parameter- und Tilde-Ersetzungen finden nicht statt.

  Sonderzeichen:

  - `*` - Kein oder mehr Zeichen.
  - `?` - Genau ein (beliebiges) Zeichen.
  - `[...]` - Ein Zeichen einer Gruppe von Zeichen. Ist erste das Zeichen ein `!`, dann jedes Zeichen, das nicht in der Gruppe enthalten ist.
  - `{a,b,c}` - Wenn das Flag `GLOB_BRACE` verwendet wird, eine Zeichenkette aus einer Gruppe von Zeichenketten, die durch ein Komma getrennt sind.
  - `\` - Maskiert das folgende Zeichen, es sei denn, das Flag `GLOB_NOESCAPE` wurde verwendet.
`flags`

  Jede der `GLOB_*`-Konstanten.

### Rückgabewerte

Gibt ein Array mit den übereinstimmenden Datei- und Verzeichnisnamen zurück. Wenn keine Treffer gefunden wurden, wird ein leeres Array zurückgegeben, und im Fehlerfall `false`. Wenn nicht `GLOB_NOSORT` verwendet wird, werden die Namen alphanumerisch sortiert.

### Beispiele

Beispiel #1 Einfacher Ersatz von opendir() etc. durch glob()

    <?php
    foreach (glob("*.txt") as $filename) {
        echo "$filename - Größe: " . filesize($filename) . "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    funclist.txt - Größe: 44686
    funcsummary.txt - Größe: 267625
    quickref.txt - Größe: 137820

Beispiel #2 Beispiel mit einem komplexeren Muster

    <?php
    foreach (glob("path/*/*.{txt,md}", \GLOB_BRACE) as $filename) {
        echo "$filename\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    path/docs/mailinglist-rules.md
    path/docs/README.md
    path/docs/release-process.md
    path/pear/install-pear.txt
    path/Zend/README.md

### Anmerkungen

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

> Hinweis: Diese Funktion ist nicht auf allen Systemen verfügbar (z. B. alten Sun-OS-Versionen).

### Siehe auch

- opendir() - Öffnet ein Verzeichnis-Handle
- readdir() - Liest einen Eintrag aus einem Verzeichnis-Handle
- closedir() - Schließt ein Verzeichnis-Handle
- fnmatch() - Match filename against a pattern

# is_dir

(PHP 4, PHP 5, PHP 7, PHP 8)

is_dir — Prüft, ob der angegebene Dateiname ein Verzeichnis ist

### Beschreibung

function is_dir(string `$filename`): bool

Prüft, ob der angegebene Dateiname ein Verzeichnis ist.

### Parameter-Liste

`filename`

  Pfad zur Datei. Wenn `filename` ein relativer Dateiname ist, so wird er auch relativ zu dem aktuellen Verzeichnis geprüft. Wenn `filename` ein symbolischer oder harter Link ist, so wird der Link aufgelöst und geprüft. Falls open_basedir aktiviert ist, können weitere Einschränkungen berücksichtigt werden.

### Rückgabewerte

Gibt `true` zurück, wenn der Dateiname existiert und ein Verzeichnis ist, sonst `false`.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 is_dir()-Beispiel

    <?php
    var_dump(is_dir('eine_datei.txt'));
    var_dump(is_dir('kein_verzeichnis/abc'));

    var_dump(is_dir('..')); //ein Verzeichnis hoch
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(false)
    bool(true)

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- chdir() - Wechseln des Verzeichnisses
- dir() - Liefert eine Instanz der Directory-Klasse
- opendir() - Öffnet ein Verzeichnis-Handle
- is_file() - Prüft, ob der Dateiname eine reguläre Datei ist
- is_link() - Prüft, ob der Dateiname ein symbolischer Link ist

# is_executable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_executable — Prüft, ob der Dateiname ausführbar ist

### Beschreibung

function is_executable(string `$filename`): bool

Prüft, ob der Dateiname ausführbar ist.

### Parameter-Liste

`filename`

  Der Pfad zur Datei.

### Rückgabewerte

Gibt `true` zurück, wenn der Dateiname existiert und ausführbar ist, oder `false` im Fehlerfall. Auf POSIX-Systemen ist eine Datei ausführbar, wenn in den Dateiberechtigungen das Ausführungsbit gesetzt ist. Für Windows siehe den Hinweis unten.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 is_executable()-Beispiel

    <?php

    $file = '/home/vincent/somefile.sh';

    if (is_executable($file)) {
        echo $file.' ist ausführbar';
    } else {
        echo $file.' ist nicht ausführbar';
    }

    ?>

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

> Hinweis: Unter Windows gilt eine Datei als ausführbar, wenn es sich laut der Win-API `GetBinaryType()` um eine ordnungsgemäß ausführbare Datei handelt; aus Gründen der Abwärtskompatibilität gelten auch Dateien mit der Erweiterung .bat oder .cmd als ausführbar. Vor PHP 7.4.0 wurde jede nicht-leere Datei mit der Erweiterung .exe oder .com als ausführbar angesehen. Zu beachten ist, dass PATHEXT für is_executable() irrelevant ist.

### Siehe auch

- is_file() - Prüft, ob der Dateiname eine reguläre Datei ist
- is_link() - Prüft, ob der Dateiname ein symbolischer Link ist

# is_file

(PHP 4, PHP 5, PHP 7, PHP 8)

is_file — Prüft, ob der Dateiname eine reguläre Datei ist

### Beschreibung

function is_file(string `$filename`): bool

Prüft, ob der Dateiname eine reguläre Datei ist.

### Parameter-Liste

`filename`

  Pfad zur Datei.

### Rückgabewerte

Gibt `true` zurück, wenn der Dateiname existiert und eine reguläre Datei ist, sonst `false`.

> Hinweis: Weil PHPs Integer Typ vorzeichenbehaftet ist und viele Platformen 32bit Integer verwenden, können einige Dateisystem-Funktionen für Dateien größer als 2GB unerwartete Ergebnisse liefern.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 is_file()-Beispiel

    <?php
    var_dump(is_file('eine_datei.txt')) . "\n";
    var_dump(is_file('/usr/bin/')) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- is_dir() - Prüft, ob der angegebene Dateiname ein Verzeichnis ist
- is_link() - Prüft, ob der Dateiname ein symbolischer Link ist
- SplFileInfo

# is_link

(PHP 4, PHP 5, PHP 7, PHP 8)

is_link — Prüft, ob der Dateiname ein symbolischer Link ist

### Beschreibung

function is_link(string `$filename`): bool

Prüft, ob der angegebene Dateiname ein symbolischer Link ist.

### Parameter-Liste

`filename`

  Pfad zur Datei.

### Rückgabewerte

Gibt `true` zurück, wenn der Dateiname existiert und es sich um einen symbolischen Link handelt, sonst `false`.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 Erstelle und bestätige, dass eine Datei ein symbolischer Link ist

    <?php
    $link = 'uploads';

    if (is_link($link)) {
        echo readlink($link);
    } else {
        symlink('uploads.php', $link);
    }
    ?>

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- is_dir() - Prüft, ob der angegebene Dateiname ein Verzeichnis ist
- is_file() - Prüft, ob der Dateiname eine reguläre Datei ist
- readlink() - Liefert das Ziel eines symbolischen Links
- symlink() - Erzeugt einen symbolischen Link

# is_readable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_readable — Prüft, ob eine Datei existiert und lesbar ist

### Beschreibung

function is_readable(string `$filename`): bool

Gibt `true` zurück, wenn die Datei existiert und lesbar ist.

### Parameter-Liste

`filename`

  Pfad zur Datei.

### Rückgabewerte

Gibt `true` zurück, wenn die Datei oder das Verzeichnis (angegeben durch `filename`) existiert und lesbar ist, sonst `false`.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 is_readable()-Beispiel

    <?php
    $filename = 'test.txt';
    if (is_readable($filename)) {
        echo 'Die Datei ist lesbar';
    } else {
        echo 'Die Datei ist nicht lesbar';
    }
    ?>

### Anmerkungen

Bedenken Sie, dass PHP mit der Benutzer-ID auf die Datei zugreift, unter der der Webserver läuft (oftmals ist dies 'nobody').

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

> Hinweis:

> Die Prüfung wird mit der echten UID/GID anstelle der effektiven ID ausgeführt.

Diese Funktion kann `true` für Verzeichnisse zurück liefern. Mittels is_dir() kann zwischen Dateien und Verzeichnissen unterschieden werden.

### Siehe auch

- is_writable() - Prüft, ob in eine Datei geschrieben werden kann
- file_exists() - Prüft, ob eine Datei oder ein Verzeichnis existiert
- fgets() - Liest die Zeile von der Position des Dateizeigers

# is_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

is_uploaded_file — Prüft, ob die Datei mittels HTTP-POST upgeloadet wurde

### Beschreibung

function is_uploaded_file(string `$filename`): bool

Gibt `true` zurück, wenn die Datei `filename` mittels HTTP-POST hochgeladen wurde. Dies ist hilfreich, um sicherzustellen, dass kein böswilliger Nutzer versucht hat, das Skript zu überlisten, indem er es Dateien bearbeiten lässt, die es gar nicht bearbeiten sollte, zum Beispiel /etc/passwd.

Diese Prüfung ist insbesondere dort interessant, wo irgendeine Aktion mit upgeloadeten Dateien deren Inhalt dem Nutzer (oder sogar anderen Nutzern auf dem gleichen System) zugänglich machen könnte.

Um korrekt arbeiten zu können, benötigt die Funktion is_uploaded_file() einen Parameter wie $_FILES['userfile']['tmp_name']. Der Name der upgeloadeten Datei auf dem Anwenderrechner $_FILES['userfile']['name'] funktioniert nicht.

### Parameter-Liste

`filename`

  Der zu prüfende Dateiname.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 is_uploaded_file()-Beispiel

    <?php

    if (is_uploaded_file($_FILES['userfile']['tmp_name'])) {
       echo "Datei ". $_FILES['userfile']['name'] ." erfolgreich upgeloadet.\n";
       echo "Anzeige des Inhalts\n";
       readfile($_FILES['userfile']['tmp_name']);
    } else {
       echo "Mögliche Dateiupload-Attacke: ";
       echo "Dateiname '". $_FILES['userfile']['tmp_name'] . "'.";
    }

    ?>

### Siehe auch

- move_uploaded_file() - Verschiebt eine hochgeladene Datei an einen neuen Ort
- $_FILES
- Siehe Steuerung von Dateiuploads für ein einfaches Anwendungsbeispiel.

# is_writable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writable — Prüft, ob in eine Datei geschrieben werden kann

### Beschreibung

function is_writable(string `$filename`): bool

Gibt `true` zurück, wenn `filename` existiert und schreibbar ist. Der Dateinamens-Parameter kann auch ein Verzeichnisname sein, um prüfen zu können, ob ein Verzeichnis schreibbar ist.

Bedenken Sie, dass PHP mit der Benutzer-ID auf die Datei zugreift, unter der der Webserver läuft (oftmals ist dies 'nobody').

### Parameter-Liste

`filename`

  Der zu prüfende Dateiname.

### Rückgabewerte

Gibt `true` zurück, wenn `filename` existiert und schreibbar ist.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 is_writable()-Beispiel

    <?php
    $filename = 'test.txt';
    if (is_writable($filename)) {
        echo 'Die Datei kann geschrieben werden';
    } else {
        echo 'Die Datei kann nicht geschrieben werden';
    }
    ?>

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- is_readable() - Prüft, ob eine Datei existiert und lesbar ist
- file_exists() - Prüft, ob eine Datei oder ein Verzeichnis existiert
- fwrite() - Binär-sicheres Dateischreiben

# is_writeable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writeable — Alias von is_writable()

### Beschreibung

Diese Funktion ist ein Alias für: is_writable().

# lchgrp

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchgrp — Changes group ownership of symlink

### Beschreibung

function lchgrp(string `$filename`, string|int `$group`): bool

Attempts to change the group of the symlink `filename` to `group`.

Only the superuser may change the group of a symlink arbitrarily; other users may change the group of a symlink to any group of which that user is a member.

### Parameter-Liste

`filename`

  Path to the symlink.

`group`

  The group specified by name or number.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Changing the group of a symbolic link

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchgrp($link, 8);
    ?>

### Anmerkungen

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

> Hinweis: Diese Funktion ist auf Windows-Plattformen nicht verfügbar.

### Siehe auch

- chgrp() - Ändert die Gruppenzugehörigkeit einer Datei
- lchown() - Changes user ownership of symlink
- chown() - Ändert den Eigentümer einer Datei
- chmod() - Ändert den Modus für die Zugriffsrechte einer Datei

# lchown

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchown — Changes user ownership of symlink

### Beschreibung

function lchown(string `$filename`, string|int `$user`): bool

Attempts to change the owner of the symlink `filename` to user `user`.

Only the superuser may change the owner of a symlink.

### Parameter-Liste

`filename`

  Path to the file.

`user`

  User name or number.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Changing the owner of a symbolic link

    <?php
    $target = 'output.php';
    $link = 'output.html';
    symlink($target, $link);

    lchown($link, 8);
    ?>

### Anmerkungen

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

> Hinweis: Diese Funktion ist auf Windows-Plattformen nicht verfügbar.

### Siehe auch

- chown() - Ändert den Eigentümer einer Datei
- lchgrp() - Changes group ownership of symlink
- chgrp() - Ändert die Gruppenzugehörigkeit einer Datei
- chmod() - Ändert den Modus für die Zugriffsrechte einer Datei

# link

(PHP 4, PHP 5, PHP 7, PHP 8)

link — Erzeugt einen harten Link

### Beschreibung

function link(string `$target`, string `$link`): bool

link() erzeugt einen harten Link.

### Parameter-Liste

`target`

  Das Ziel des Links.

`link`

  Der Name des Links.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Die Funktion schlägt fehl und gibt einen Fehler der Stufe `E_WARNING` aus, wenn `link` bereits existiert oder wenn `target` nicht existiert.

### Beispiele

Beispiel #1 Erstellen eines harten Links

    <?php
    $target = 'quelle.ext';    // Die ist die bereits existierende Datei
    $link   = 'neuedatei.ext'; // Dies ist der Dateiname, auf den verlinkt
                               // werden soll

    link($target, $link);
    ?>

### Anmerkungen

> Hinweis: Diese Funktion kann nicht mit entfernten Dateien arbeiten, da der Zugriff auf die Datei, die bearbeitet werden soll, über das Dateisystem des Servers möglich sein muss.

> Hinweis: Nur für Windows: Diese Funktion setzt voraus, dass PHP in einem erhöhten Modus oder mit deaktivierter Benutzerkontensteuerung (UAC) läuft.

### Siehe auch

- symlink() - Erzeugt einen symbolischen Link
- readlink() - Liefert das Ziel eines symbolischen Links
- linkinfo() - Liefert Informationen über einen Link
- unlink() - Löscht eine Datei

# linkinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

linkinfo — Liefert Informationen über einen Link

### Beschreibung

function linkinfo(string `$path`): int|false

Liefert Informationen über einen Link.

Diese Funktion wird benutzt, um zu verifizieren, ob ein Link (auf den mit `path` gezeigt wird) wirklich existiert. Dabei wird die gleiche Methode benutzt, die in dem S_ISLNK-Makro in stat.h definiert ist).

### Parameter-Liste

`path`

  Pfad zum Link.

### Rückgabewerte

linkinfo() gibt das `st_dev`-Feld der Unix-C-Stat-Struktur, die vom `lstat`-Systemaufruf zurückgegeben wird, zurück. Gibt im Erfolgsfall eine nicht-negative Ganzzahl zurück; -1 im Fall, dass der Link nicht gefunden wurde, oder `false` falls ein open_base_dir Verstoß erfolgt.

### Beispiele

Beispiel #1 linkinfo()-Beispiel

    <?php

    echo linkinfo('/vmlinuz'); // 835

    ?>

### Siehe auch

- symlink() - Erzeugt einen symbolischen Link
- link() - Erzeugt einen harten Link
- readlink() - Liefert das Ziel eines symbolischen Links

# lstat

(PHP 4, PHP 5, PHP 7, PHP 8)

lstat — Sammelt Informationen über eine Datei oder einen symbolischen Link

### Beschreibung

function lstat(string `$filename`): array|false

Sammelt Statistiken über die Datei oder den symbolischen Link, die bzw. der in `filename` angegeben ist.

### Parameter-Liste

`filename`

  Pfad zur Datei oder zum symbolischen Link.

### Rückgabewerte

Bitte lesen Sie die Handbuchseite zu stat() für Informationen über die Struktur des Arrays, das lstat() zurückgibt. Diese Funktion ist identisch zur stat()-Funktion, mit dem Unterschied, dass, falls `filename` ein symbolischer Link ist, dessen Statistik zurückgegeben wird und nicht der Status der Datei, auf die der symbolische Link zeigt.

Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 Vergleich von stat() und lstat()

    <?php
    symlink('uploads.php', 'uploads');

    // Vergleiche die Informationen von uploads.php und uploads
    array_diff(stat('uploads'), lstat('uploads'));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Unterschiede in den Informationen beider Dateien.

    Array
    (
        [ino] => 97236376
        [mode] => 33188
        [size] => 34
        [atime] => 1223580003
        [mtime] => 1223581848
        [ctime] => 1223581848
        [blocks] => 8
    )

### Anmerkungen

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- stat() - Sammelt Informationen über eine Datei

# mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

mkdir — Erstellt ein Verzeichnis

### Beschreibung

function mkdir(
string `$directory`,
int `$permissions` = 0777,
bool `$recursive` = `false`,
?resource `$context` = `null`
): bool

Versucht, das durch `directory` angegebene Verzeichnis zu erstellen.

### Parameter-Liste

`directory`

  Der Verzeichnispfad.

`permissions`

  Der Zugriffsberechtigungen sind standardmäßig 0777, was den größtmöglichen Zugang umfasst. Für weitere Informationen lesen Sie bitte die Details auf der chmod()-Seite.

  > Hinweis:

  > `permissions` wird unter Windows ignoriert.

  Beachten Sie, dass Sie `permissions` als oktalen Wert angeben sollten, d. h., dass er eine führende Null haben sollte. `permissions` wird auch durch das aktuelle umask verändert, das Sie mit umask() ändern können.

`recursive`

  Falls `true`, werden auch die übergeordneten Verzeichnisse des angegebenen `directory` erstellt, wobei die gleichen Zugriffsrechte gelten.

`context`

  Eine Stream-Kontext-Ressource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

> Hinweis:

> Wenn das zu erstellende Verzeichnis bereits existiert, wird dies als Fehler angesehen und es wird `false` zurückgegeben. Bevor versucht wird, ein Verzeichnis zu erstellen, sollte mit is_dir() oder file_exists() geprüft werden, ob es bereits existiert.

### Fehler/Exceptions

Gibt einen Fehler der Stufe `E_WARNING` aus, falls das Verzeichnis bereits existiert.

Gibt einen Fehler der Stufe `E_WARNING` aus, falls die zugehörigen Berechtigungen verhindern, dass das Verzeichnis erstellt wird.

### Beispiele

Beispiel #1 mkdir()-Beispiel

    <?php
    mkdir("/path/to/my/dir", 0700);
    ?>

Beispiel #2 mkdir() mit dem Parameter `recursive` benutzen

    <?php
    // Gewünschte Verzeichnisstruktur
    $structure = './stufe1/stufe2/stufe3/';

    // Zur Erstellung der verschachtelten Struktur muss der Parameter $recursive
    // von mkdir() angegeben werden

    if (!mkdir($structure, 0777, true)) {
        die('Erstellung der Verzeichnisse schlug fehl...');
    }

    // ...
    ?>

### Siehe auch

- is_dir() - Prüft, ob der angegebene Dateiname ein Verzeichnis ist
- rmdir() - Löscht ein Verzeichnis
- umask() - Changes the current umask

# move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

move_uploaded_file — Verschiebt eine hochgeladene Datei an einen neuen Ort

### Beschreibung

function move_uploaded_file(string `$from`, string `$to`): bool

Diese Funktion prüft, dass die mit `from` bezeichnete Datei eine gültige Upload-Datei ist (d. h., dass sie mittels PHPs HTTP POST Upload-Mechanismus hochgeladen wurde). Ist die Datei gültig, wird sie zum in `to` bezeichneten Dateinamen verschoben.

Diese Art der Prüfung ist besonders wichtig, wo irgendeine Aktion mit hochgeladenen Dateien deren Inhalt dem User zugänglich machen könnte, oder gar anderen Usern auf dem selben System.

### Parameter-Liste

`from`

  Der Dateiname der hochgeladenen Datei.

`to`

  Das Ziel der zu verschiebenden Datei.

### Rückgabewerte

Gibt bei Erfolg `true` zurück.

Ist `from` keine gültige Datei, wird keine Aktion ausgeführt, und move_uploaded_file() gibt `false` zurück.

Ist `from` eine gültige Datei, jedoch aus irgendeinem Grund nicht verschoben werden kann, wird keine Aktion ausgeführt, und move_uploaded_file() gibt `false` zurück. Zusätzlich wird eine Warnung ausgegeben.

### Beispiele

Beispiel #1 Hochladen mehrerer Dateien

    <?php
    $uploads_dir = '/uploads';
    foreach ($_FILES["pictures"]["error"] as $key => $error) {
        if ($error == UPLOAD_ERR_OK) {
            $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
            // basename() kann Directory-Traversal-Angriffe verhindern;
            // weitere Validierung/Bereinigung des Dateinamens kann angebracht sein
            $name = basename($_FILES["pictures"]["name"][$key]);
            move_uploaded_file($tmp_name, "$uploads_dir/$name");
        }
    }
    ?>

### Anmerkungen

> Hinweis:

> move_uploaded_file() berücksichtigt open_basedir. Allerdings werden die Beschränkungen nur auf den `to` Pfad angewandt, um das Verschieben von hochgeladenen Dateien zu erlauben, bei denen sich `from` mit den Beschränkungen im Konflikt befinden könnte. move_uploaded_file() gewährleistet die Sicherheit dieser Operation dadurch, dass nur diejenigen Dateien verschoben werden dürfen, die mit PHP hochgeladen wurden.

Warnung

Existiert die Zieldatei bereits, wird sie überschrieben.

### Siehe auch

- is_uploaded_file() - Prüft, ob die Datei mittels HTTP-POST upgeloadet wurde
- rename() - Benennt eine Datei oder ein Verzeichnis um
- See Handling file uploads for a simple usage example

# parse_ini_file

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_ini_file — Parst eine Konfigurationsdatei

### Beschreibung

function parse_ini_file(string `$filename`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_file() lädt die in `filename` angegebene Datei, und gibt die darin enthaltenen Einstellungen in einem assoziativen Array zurück.

Die Struktur der Ini-Datei ist identisch zur php.ini.

Warnung

Diese Funktion darf nicht mit unvertrauenswürdigen Eingaben verwendet werden, es sei denn, `scanner_mode` ist `INI_SCANNER_RAW`, da die geparste Ausgabe Werte von sensiblen Konstanten enthalten könnte, wie beispielsweise Konstanten, die ein Datenbank-Passwort enthalten.

### Parameter-Liste

`filename`

  Der Dateiname der zu parsenden ini-Datei. Wenn ein relativer Pfad verwendet wird, wird er relativ zum aktuellen Arbeitsverzeichnis ausgewertet und dann entsprechend dem include_path.

`process_sections`

  Setzt man den Parameter `process_sections` auf `true`, erhält man ein mehrdimensionales Array mit den Gruppennamen und Einstellungen. Der Standardwert für `process_sections` ist `false`

`scanner_mode`

  Kann entweder `INI_SCANNER_NORMAL` (Standard) oder `INI_SCANNER_RAW` sein. Ist `INI_SCANNER_RAW` gesetzt, so werden die Werte der Optionen nicht geparst.

  Seit PHP 5.6.1 kann auch `INI_SCANNER_TYPED` angegeben werden. In diesem Modus werden soweit möglich die Typen von Boolean-, Null- oder Integer-Werten beibehalten. Die Zeichenketten `"true"`, `"on"` und `"yes"` werden zu `true` konvertiert. `"false"`, `"off"`, `"no"` und `"none"` werden als `false` angesehen. `"null"` wird in diesem Modus zu `null`. Soweit möglich werden alle numerischen Zeichenketten zu Integertypen umgewandelt.

### Rückgabewerte

Im Erfolgsfall werden die Einstellungen als assoziatives Array zurückgegeben, ansonsten `false`.

### Beispiele

Beispiel #1 Inhalt der sample.ini

    ; Dies ist ein Beispiel für eine Konfigurationsdatei
    ; Kommentare beginnen wie in der php.ini mit ';'

    [erste_gruppe]
    eins = 1
    fünf = 5
    tier = VOGEL

    [zweite_gruppe]
    pfad = /usr/local/bin
    URL = "http://www.example.com/~username"

    [dritte_gruppe]
    phpversion[] = "5.0"
    phpversion[] = "5.1"
    phpversion[] = "5.2"
    phpversion[] = "5.3"

    urls[svn] = "http://svn.php.net"
    urls[git] = "http://git.php.net"

Beispiel #2 parse_ini_file()-Beispiel

Abgesehen von "magischen Konstanten" wie `__FILE__` können auch Konstanten in einer Ini-Datei geparst werden, indem man einen INI-Wert als Konstante definiert, bevor parse_ini_file() aufgerufen wird. Diese Konstante wird in die Ergebnisse integriert. Dabei werden nur INI-Werte ausgewertet und der Wert muss genau die Konstante sein. Zum Beispiel:

    <?php

    define ('VOGEL', 'Amsel');

    // Ohne Gruppen analysieren
    $ini_array = parse_ini_file("sample.ini");
    print_r($ini_array);

    // Mit Gruppen analysieren
    $ini_array = parse_ini_file("sample.ini", TRUE);
    print_r($ini_array);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [eins] => 1
        [fünf] => 5
        [tier] => Amsel
        [pfad] => /usr/local/bin
        [URL] => http://www.example.com/~username
        [phpversion] => Array
            (
                [0] => 5.0
                [1] => 5.1
                [2] => 5.2
                [3] => 5.3
            )

        [urls] => Array
            (
                [svn] => http://svn.php.net
                [git] => http://git.php.net
            )

    )
    Array
    (
        [erste_gruppe] => Array
            (
                [eins] => 1
                [fünf] => 5
                [tier] => Amsel
            )

        [zweite_gruppe] => Array
            (
                [pfad] => /usr/local/bin
                [URL] => http://www.example.com/~username
            )

        [dritte_gruppe] => Array
            (
                [phpversion] => Array
                    (
                        [0] => 5.0
                        [1] => 5.1
                        [2] => 5.2
                        [3] => 5.3
                    )

                [urls] => Array
                    (
                        [svn] => http://svn.php.net
                        [git] => http://git.php.net
                    )

            )

    )

Beispiel #3 parse_ini_file() parst eine php.ini

    <?php
    // Eine einfache Funktion, um das Ergebnis zu vergleichen
    function janein($expression)
    {
        return($expression ? 'Ja' : 'Nein');
    }

    // Pfad der php.ini mittels der Funktion php_ini_loaded_file() holen
    $ini_path = php_ini_loaded_file();

    // Parsen der php.ini
    $ini = parse_ini_file($ini_path);

    // Werte ausgeben und vergleichen. Beachten Sie dass die Verwendung von
    // get_cfg_var() die gleichen Ergebnisse für geparste und geladene
    // Werte geben wird
    echo '(geparst) magic_quotes_gpc = ' . janein($ini['magic_quotes_gpc']) . PHP_EOL;
    echo '(geladen) magic_quotes_gpc = ' . janein(get_cfg_var('magic_quotes_gpc')) . PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    (geparst) magic_quotes_gpc = Ja
    (geladen) magic_quotes_gpc = Nein

Beispiel #4 Wert-Interpolation

Neben der Auswertung von Konstanten haben bestimmte Zeichen eine besondere Bedeutung in einem ini-Wert. Darüber hinaus können Umgebungsvariablen und zuvor definierte Konfigurationsoptionen (siehe get_cfg_var()) mit der `${}`-Syntax gelesen werden.

    ; | wird für bitweises OR verwendet
    three = 2|3

    ; & wird für bitweises AND verwendet
    four = 6&5

    ; ^ wird für bitweises XOR verwendet
    five = 3^6

    ; ~ wird für bitweises Negieren verwendet
    negative_two = ~1

    ; () wird für die Gruppierung verwendet
    seven = (8|7)&(6|5)

    ; Auswerten der Umgebungsvariablen PATH
    path = ${PATH}

    ; Auswerten der Konfigurationsoption "memory_limit".
    configured_memory_limit = ${memory_limit}

Beispiel #5 Zeichen maskieren

Einige Zeichen haben in Zeichenketten in doppelten Anführungszeichen eine besondere Bedeutung und müssen durch das Backslash-Präfix maskiert werden. Dies sind vor allem das doppelte Anführungszeichen `"` als Begrenzungszeichen und der Backslash `\` selbst (wenn darauf ein Sonderzeichen folgt):

    quoted = "She said \"Exactly my point\"." ; Ergibt eine Zeichenkette mit Anführungszeichen darin.
    hint = "Use \\\" to escape double quote" ; Ergibt: Use \" to escape double quote

Es gibt eine Ausnahme für Windows-ähnliche Pfade: Es ist möglich, den abschließenden Backslash nicht zu maskieren, wenn auf die Zeichenkette in Anführungsstrichen direkt ein Zeilenumbruch folgt:

    save_path = "C:\Temp\"

Wenn man doppelte Anführungszeichen gefolgt von einem Zeilenumbruch in einem mehrzeiligen Wert vermeiden muss, ist es möglich, die Verkettung von Werten auf folgende Weise zu verwenden (eine Zeichenkette mit zwei direkt aufeinanderfolgenden Anführungszeichen):

    long_text = "Lorem \"ipsum\"""
     dolor" ; Ergibt: Lorem "ipsum"\n dolor

Ein weiteres Zeichen mit besonderer Bedeutung ist `$` (das Dollarzeichen). Wenn darauf eine öffnende geschweifte Klammer folgt, muss es maskiert werden:

    code = "\${test}"

Das Maskieren von Zeichen wird im Modus `INI_SCANNER_RAW` nicht unterstützt (in diesem Modus werden alle Zeichen verarbeitet wie sie sind).

Zu beachten ist, dass der ini-Parser keine Standard-Maskierungssequenzen unterstützt (`\n`, `\t` etc.). Falls erforderlich, muss das Ergebnis von parse_ini_file() mit der Funktion stripcslashes() nachbearbeitet werden.

### Anmerkungen

> Hinweis:

> Diese Funktion hat nichts mit dem Laden der php.ini-Datei zu tun. Diese ist zum Ausführungszeitpunkt Ihres Skriptes bereits vollständig verarbeitet. Diese Funktion kann verwendet werden, um die Konfigurationsdateien Ihrer eigenen Anwendung zu lesen.

> Hinweis:

> Falls ein Wert der Ini-Datei ein nicht alphanumerisches Zeichen enthält muss dieser Wert in doppelte Anführungszeichen (") eingeschlossen werden.

> Hinweis: Es gibt reservierte Schlüsselwörter, welche nicht als Schlüssel in Ini-Dateien verwendet werden dürfen. Diese umfassen: `null`, `yes`, `no`, `true`, `false`, `on`, `off`, `none`. Die Werte `null`, `off`, `no` und `false` ergeben `""` und die Werte `on`, `yes` and `true` ergeben `"1"`, solange der Modus `INI_SCANNER_TYPED` nicht verwendet wird . Die Zeichen `?{}|&~!()^"` dürfen in einem Schlüssel nicht verwendet werden und haben im Wert besondere Bedeutung.

> Hinweis:

> Einträge ohne Gleichheitszeichen werden ignoriert. Beispielsweise würde "foo" ignoriert werden, während "bar =" geparst und mit einem leeren Wert hinzugefügt würde. Beispielsweise hat MySQL eine Einstellung "no-auto-rehash" in der my.cnf welche keinen Wert enthält und somit ignoriert würde.

> Hinweis:

> Ini-Dateien werden von Webservern in der Regel als reiner Text behandelt und daher den Browsern auf Anfrage zur Verfügung gestellt. Das bedeutet, dass Sie aus Sicherheitsgründen entweder Ihre ini-Dateien außerhalb des Web-Wurzelverzeichnisses (DocRoot) aufbewahren müssen oder Ihren Webserver so umkonfigurieren, dass sie nicht ausgeliefert werden. Wenn Sie beides nicht tun, kann dies ein Sicherheitsrisiko darstellen.

### Siehe auch

- parse_ini_string() - Analysiert einen Konfigurations-String

# parse_ini_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

parse_ini_string — Analysiert einen Konfigurations-String

### Beschreibung

function parse_ini_string(string `$ini_string`, bool `$process_sections` = `false`, int `$scanner_mode` = `INI_SCANNER_NORMAL`): array|false

parse_ini_string() Gibt die Konfiguration aus dem String `ini_string` in einem assoziativen Array zurück.

Die Struktur des ini-Strings ist die selbe wie die der php.ini

Warnung

Diese Funktion darf nicht mit unvertrauenswürdigen Eingaben verwendet werden, es sei denn, `scanner_mode` ist `INI_SCANNER_RAW`, da die geparste Ausgabe Werte von sensiblen Konstanten enthalten könnte, wie beispielsweise Konstanten, die ein Datenbank-Passwort enthalten.

### Parameter-Liste

`ini_string`

  Der Inhalt der ini-Datei die analysiert wird.

`process_sections`

  Ist der Parameter `process_sections` als `true` gesetzt, werden Sie ein mehrdimensionales Array zurückbekommen, welches die Abschnitte und Einstellungen enthält. Die Standardeinstellung `process_sections` ist `false`

`scanner_mode`

  Kann entweder `INI_SCANNER_NORMAL` (normal) oder `INI_SCANNER_RAW` sein. Wenn `INI_SCANNER_RAW` angegeben ist, werden optionale Inhalte nicht analysiert.

  Seit PHP 5.6.1 kann auch `INI_SCANNER_TYPED` angegeben werden. In diesem Modus werden soweit möglich die Typen von Boolean-, Null- oder Integer-Werten beibehalten. Die Zeichenketten `"true"`, `"on"` und `"yes"` werden zu `true` konvertiert. `"false"`, `"off"`, `"no"` und `"none"` werden als `false` angesehen. `"null"` wird in diesem Modus zu `null`. Soweit möglich werden alle numerischen Zeichenketten zu Integertypen umgewandelt.

### Rückgabewerte

Die Einstellungen werden als assoziatives Array bei Erfolg, und `false` bei einem Fehler zurückgegeben..

### Anmerkungen

> Hinweis: Es gibt reservierte Wörter die nicht als Keys für die ini-Dateien benutzt werden dürfen. Dies schließt `null`, `yes`, `no`, `true`, `false`, `on`, `off` und `none` ein. Die Werte `null`, `off`, `no` und `false` geben `""` zurück, und die Werte `on`, `yes` und `true` `"1"`, es sei denn der `INI_SCANNER_TYPED`-Modus wird verwendet. Die Buchstaben `?{}|&~![()^"` dürfen nirgendwo inm Key benutzt werden und haben eine spezielle Bedeutung.

### Siehe auch

- parse_ini_file() - Parst eine Konfigurationsdatei

# pathinfo

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pathinfo — Liefert Informationen über einen Dateipfad

### Beschreibung

function pathinfo(string `$path`, int `$flags` = `PATHINFO_ALL`): array|string

pathinfo() gibt Informationen über einen Dateipfad (`path`) zurück: entweder als assoziatives Array oder als String, abhängig vom Parameter `flags`.

> Hinweis:

> Wie die aktuellen Pfadinformationen ermittelt werden können, ist im Abschnitt Vordefinierte Variablen beschrieben.

> Hinweis:

> pathinfo() verarbeitet lediglich den Eingabestring und kennt weder das tatsächliche Dateisystem noch Pfadkomponenten wie "`..`".

> Hinweis:

> Das Zeichen `\` wird nur auf Windows-Systemen als Trennzeichen zwischen Verzeichnissen interpretiert. Auf anderen Systemen wird es wie jedes andere Zeichen behandelt.

Achtung

pathinfo() berücksichtigt die Locale-Einstellung. Um einen Pfad, der Multibyte-Zeichen enthält, korrekt parsen zu können, muss die entsprechende Locale mit der Funktion setlocale() gesetzt werden.

### Parameter-Liste

`path`

  Der zu analysierende Dateipfad.

`flags`

  Gibt, falls vorhanden, ein bestimmtes Element an, das zurückgegeben werden soll. Mögliche Werte: `PATHINFO_DIRNAME`, `PATHINFO_BASENAME`, `PATHINFO_EXTENSION` oder `PATHINFO_FILENAME`.

  Falls `flags` nicht angegeben wird, werden alle verfügbaren Elemente zurückgegeben.

### Rückgabewerte

Falls der Parameter `flags` nicht angegeben wird, wird ein assoziatives Array mit den folgenden Elementen zurückgegeben: `dirname`, `basename`, `extension` (falls vorhanden) und `filename`.

> Hinweis:

> Wenn `path` mehr als eine Erweiterung hat, gibt `PATHINFO_EXTENSION` nur die letzte zurück, und `PATHINFO_FILENAME` entfernt nur die letzte. (Siehe auch das erste Beispiel weiter unten.)

> Hinweis:

> Falls `path` keine Erweiterung hat, wird das Element `extension` nicht zurückgegeben (siehe das zweite Beispiel unten).

> Hinweis:

> Beginnt `basename` von `path` mit einem Punkt, werden die folgenden Zeichen als `extension` interpretiert, und `filename` ist leer (siehe das dritte Beispiel unten).

Falls `flags` genutzt wird, gibt diese Funktion einen String mit dem gewünschten Element zurück.

### Beispiele

Beispiel #1 pathinfo()-Beispiel

    <?php
    $path_parts = pathinfo('/www/htdocs/inc/lib.inc.php');

    echo $path_parts['dirname'], "\n";
    echo $path_parts['basename'], "\n";
    echo $path_parts['extension'], "\n";
    echo $path_parts['filename'], "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    /www/htdocs/inc
    lib.inc.php
    php
    lib.inc

Beispiel #2 pathinfo()-Beispiel für den Unterschied zwischen einer leeren und keiner Erweiterung

    <?php
    $path_parts = pathinfo('/path/emptyextension.');
    var_dump($path_parts['extension']);

    $path_parts = pathinfo('/path/noextension');
    var_dump($path_parts['extension']);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(0) ""

    Notice: Undefined index: extension in test.php on line 6
    NULL

Beispiel #3 pathinfo()-Beispiel für eine Punktdatei

    <?php
    print_r(pathinfo('/some/path/.test'));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [dirname] => /some/path
        [basename] => .test
        [extension] => test
        [filename] =>
    )

Beispiel #4 pathinfo()-Beispiel mit Array-Dereferenzierung

Der Parameter `flags` ist keine Bitmaske. Es kann nur ein einziger Wert angegeben werden. Um nur eine begrenzte Menge von geparsten Werten auszuwählen, kann das Array wie folgt zerlegt werden:

    <?php
    ['basename' => $basename, 'dirname' => $dirname] = pathinfo('/www/htdocs/inc/lib.inc.php');

    var_dump($basename, $dirname);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    string(11) "lib.inc.php"
    string(15) "/www/htdocs/inc"

### Siehe auch

- dirname() - Liefert den Pfad des übergeordneten Verzeichnisses
- basename() - Liefert den letzten Namensteil einer Pfadangabe
- parse_url() - Analysiert eine URL und gibt ihre Bestandteile zurück
- realpath() - Löst einen Pfad in einen absoluten und eindeutigen auf

# pclose

(PHP 4, PHP 5, PHP 7, PHP 8)

pclose — Schließt einen Prozess-Dateizeiger

### Beschreibung

function pclose(resource `$handle`): int

Schließt einen Prozess-Dateizeiger, der durch einen Aufruf von popen() geöffnet wurde.

### Parameter-Liste

`handle`

  Der Dateizeiger muss gültig und durch einen erfolgreichen Funktionsaufruf von popen() zurückgegeben worden sein.

### Rückgabewerte

Gibt den End-Status des ausgeführten Prozesses zurück. Im Fehlerfall wird `-1` zurückgegeben.

> Hinweis:

> Falls PHP mit der Option --enable-sigchild kompiliert wurde, ist die Rückgabe dieser Funktion nicht definiert.

### Beispiele

Beispiel #1 pclose() Beispiel

    <?php
    $handle = popen('/bin/ls', 'r');
    pclose($handle);
    ?>

### Anmerkungen

> Hinweis: Nur unter Unix:

> pclose() ist intern unter Verwendung des `waitpid(3)` Systemaufrufs implementiert. Um den wirklichen Exit-Statuscode zu erhalten, sollte die Funktion pcntl_wexitstatus() verwendet werden.

### Siehe auch

- popen() - Öffnet einen Dateizeiger für einen Prozess

# popen

(PHP 4, PHP 5, PHP 7, PHP 8)

popen — Öffnet einen Dateizeiger für einen Prozess

### Beschreibung

function popen(string `$command`, string `$mode`): resource|false

Öffnet eine Pipe zu einem Prozess durch Forken des Befehls, der durch `command` angegeben wurde.

### Parameter-Liste

`command`

  Das Kommando

`mode`

  Der Modus. Entweder `'r'` zum Lesen, oder `'w'` zum Schreiben.

  Unter Windows ist popen() standardmäßig auf den Textmodus eingestellt, d. h. alle in die Pipe geschriebenen oder aus ihr gelesenen `\n`-Zeichen werden in `\r\n` übersetzt. Wenn dies nicht gewünscht ist, kann der Binärmodus erzwungen werden, indem `mode` auf `'rb'` bzw. `'wb'` gesetzt wird.

### Rückgabewerte

Gibt einen Dateizeiger zurück, der identisch ist mit dem, der bei der Funktion fopen() zurückgegeben wird, außer dass dieser nur in eine Richtung funktioniert (entweder lesend oder schreibend) und mit der Funktion pclose() geschlossen werden muss. Dieser Zeiger kann mit den Funktionen fgets(), fgetss() und fwrite() benutzt werden. Ist der Modus 'r', ist der zurückgegebene Dateizeiger das STDOUT des Kommandos; ist der Modus 'w', ist der zurückgegebene Dateizeiger das STDIN des Kommandos.

Wenn ein Fehler auftritt, wird `false` zurückgegeben.

### Beispiele

Beispiel #1 popen()-Beispiel

    <?php
    $handle = popen("/bin/ls", "r");
    ?>

Wenn das auszuführende Kommando nicht gefunden werden konnte, wird eine gültige Ressource zurückgegeben. Das mag seltsam erscheinen, ist aber sinnvoll; es ermöglicht Ihnen, auf von der Konsole zurückgegebene Fehlermeldungen zuzugreifen:

Beispiel #2 popen()-Beispiel

    <?php
    error_reporting(E_ALL);

    /* Umleitung hinzufügen, sodass wir stderr erhalten können */
    $handle = popen('/path/to/executable 2>&1', 'r');
    echo "'$handle'; " . gettype($handle) . "\n";
    $read = fread($handle, 2096);
    echo $read;
    pclose($handle);
    ?>

### Anmerkungen

> Hinweis:

> Wenn Sie bidirektionale Unterstützung wünschen, verwenden Sie proc_open().

### Siehe auch

- pclose() - Schließt einen Prozess-Dateizeiger
- fopen() - Öffnet eine Datei oder URL
- proc_open() - Führt ein Kommando aus und öffnet Dateizeiger für die Ein- und Ausgabe

# readfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readfile — Gibt eine Datei aus

### Beschreibung

function readfile(string `$filename`, bool `$use_include_path` = `false`, ?resource `$context` = `null`): int|false

Liest den Inhalt einer Datei und schreibt ihn in den Ausgabepuffer.

### Parameter-Liste

`filename`

  Der Name der Datei, die gelesen werden soll.

`use_include_path`

  Sie können optional den zweiten Parameter benutzen und diesen auf `true` setzen, wenn Sie auch im include_path nach der Datei suchen möchten.

`context`

  Eine Stream-Kontext-Ressource.

### Rückgabewerte

Gibt bei Erfolg die Anzahl der gelesenen Bytes einer Datei zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` ausgegeben.

### Beispiele

Beispiel #1 Einen Download unter Verwendung von readfile() erzwingen

    <?php
    $file = 'monkey.gif';

    if (file_exists($file)) {
        header('Content-Description: File Transfer');
        header('Content-Type: application/octet-stream');
        header('Content-Disposition: attachment; filename="'.basename($file).'"');
        header('Expires: 0');
        header('Cache-Control: must-revalidate');
        header('Pragma: public');
        header('Content-Length: ' . filesize($file));
        readfile($file);
        exit;
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Anmerkungen

> Hinweis:

> readfile() weist für sich allein keine Speicherprobleme auf, selbst wenn große Dateien gesendet werden. Wenn Sie auf einen out-of-memory-Fehler treffen, stellen Sie mit ob_get_level() sicher, dass die Ausgabepufferung deaktiviert ist.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Siehe auch

- fpassthru() - Gibt alle verbleibenden Daten eines Dateizeigers aus
- file() - Liest eine komplette Datei in ein Array
- fopen() - Öffnet eine Datei oder URL
- include - include
- require - require
- virtual() - Führt eine Apache-Unteranfrage durch
- file_get_contents() - Liest die gesamte Datei in einen String
- Unterstützte Protokolle und Wrapper

# readlink

(PHP 4, PHP 5, PHP 7, PHP 8)

readlink — Liefert das Ziel eines symbolischen Links

### Beschreibung

function readlink(string `$path`): string|false

readlink() ist von der Funktionalität her identisch mit der C Funktion readlink.

### Parameter-Liste

`path`

  Der Pfad des symbolischen Links.

### Rückgabewerte

Gibt den Inhalt des Pfades des symbolischen Links zurück oder `false` im Fehlerfall.

> Hinweis: Die Funktion schlägt fehl, wenn `path` kein Symlink ist, außer unter Windows, wo der normalisierte Pfad zurückgegeben wird.

### Beispiele

Beispiel #1 readlink() example

    <?php

    // gibt z. B. /boot/vmlinux-2.4.20-xfs aus
    echo readlink('/vmlinuz');

    ?>

### Siehe auch

- is_link() - Prüft, ob der Dateiname ein symbolischer Link ist
- symlink() - Erzeugt einen symbolischen Link
- linkinfo() - Liefert Informationen über einen Link

# realpath

(PHP 4, PHP 5, PHP 7, PHP 8)

realpath — Löst einen Pfad in einen absoluten und eindeutigen auf

### Beschreibung

function realpath(string `$path`): string|false

realpath() löst alle symbolischen Verweise, `/./`, `/../` und mehrere aufeinanderfolgende `/` Zeichen, die in `path` enthalten sind, auf und gibt den so entstehenden absoluten Pfad zurück.

### Parameter-Liste

`path`

  Der Pfad, der aufgelöst werden soll.

  > Hinweis:

  > Der Pfad muss angegeben werden, kann allerdings auch ein leerer String sein, in diesem Fall wird dann das aktuelle Verzeichnis benutzt.

### Rückgabewerte

Gibt bei Erfolg den eindeutigen und absoluten Pfadnamen zurück. Dieser wird keine symbolischen Links, `/./` oder `/../` mehr enthalten. Abschließende Trennzeichen wie `\` und `/` werden ebenfalls entfernt.

realpath() gibt `false` zurück, wenn ein Fehler auftritt, beispielsweise wenn die Datei nicht existiert.

> Hinweis:

> Das ausführende Script muss alle Verzeichnisse im Pfad öffnen können (auf unixoiden Systemen wäre das das "execute" Recht). Ist dies nicht der Fall, gibt realpath() `false` zurück.

> Hinweis:

> Bei Dateisystemen, bei denen Groß-/Kleinschreibung keine Rolle spielt, kann realpath() die Schreibweise kanonisieren, oder auch nicht.

> Hinweis:

> Die Funktion realpath() funktioniert nicht für Dateien in einem Phar, da solche Pfade virtuelle Pfade sind, aber keine realen Pfade.

> Hinweis:

> Unter Windows werden Junctions und symbolische Links zu Verzeichnissen nur um eine Ebene erweitert.

> Hinweis: Weil PHPs Integer Typ vorzeichenbehaftet ist und viele Platformen 32bit Integer verwenden, können einige Dateisystem-Funktionen für Dateien größer als 2GB unerwartete Ergebnisse liefern.

### Beispiele

Beispiel #1 realpath()

    <?php
    chdir('/var/www/');
    echo realpath('./../../etc/passwd') . PHP_EOL;

    echo realpath('/tmp/') . PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    /etc/passwd
    /tmp

Beispiel #2 realpath() auf Windows

Unter Windows wandelt realpath() Unix-artige Pfade in gültige Windows-Pfade um:

    <?php
    echo realpath('/windows/system32'), PHP_EOL;

    echo realpath('C:\Program Files\\'), PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    C:\WINDOWS\System32
    C:\Program Files

### Siehe auch

- basename() - Liefert den letzten Namensteil einer Pfadangabe
- dirname() - Liefert den Pfad des übergeordneten Verzeichnisses
- pathinfo() - Liefert Informationen über einen Dateipfad

# realpath_cache_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_get — Get realpath cache entries

### Beschreibung

function realpath_cache_get(): array

Get the contents of the realpath cache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of realpath cache entries. The keys are original path entries, and the values are arrays of data items, containing the resolved path, expiration date, and other options kept in the cache.

### Beispiele

Beispiel #1 realpath_cache_get() example

    <?php
    var_dump(realpath_cache_get());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(2) {
      ["/test"]=>
      array(4) {
        ["key"]=>
        int(123456789)
        ["is_dir"]=>
        bool(true)
        ["realpath"]=>
        string(5) "/test"
        ["expires"]=>
        int(1260318939)
      }
      ["/test/test.php"]=>
      array(4) {
        ["key"]=>
        int(987654321)
        ["is_dir"]=>
        bool(false)
        ["realpath"]=>
        string(12) "/root/test.php"
        ["expires"]=>
        int(1260318939)
      }
    }

### Siehe auch

- realpath_cache_size() - Get realpath cache size

# realpath_cache_size

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_size — Get realpath cache size

### Beschreibung

function realpath_cache_size(): int

Get the amount of memory used by the realpath cache.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns how much memory realpath cache is using.

### Beispiele

Beispiel #1 realpath_cache_size() example

    <?php
    var_dump(realpath_cache_size());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(412)

### Siehe auch

- realpath_cache_get() - Get realpath cache entries
- The realpath_cache_size configuration option

# rename

(PHP 4, PHP 5, PHP 7, PHP 8)

rename — Benennt eine Datei oder ein Verzeichnis um

### Beschreibung

function rename(string `$from`, string `$to`, ?resource `$context` = `null`): bool

Versucht `from` in `to` umzubenennen, wobei bei Bedarf zwischen Verzeichnissen verschoben wird. Wird eine Datei umbenannt und `to` exisitiert bereits, wird es überschrieben. Wird ein Verzeichnis umbenannt und `to` exisitiert bereits, wird eine Warnung erzeugt.

### Parameter-Liste

`from`

  Der alte Name.

  > Hinweis:

  > Der Wrapper, der in `from` verwendet wird, muss mit dem Wrapper, der in `to` verwendet wird, übereinstimmen.

`to`

  Der neue Name.

  > Hinweis: Wenn unter Windows `to` bereits existiert, muss er beschreibbar sein. Andernfalls schlägt rename() fehl und gibt ein `E_WARNING` aus.

`context`

  Eine Stream-Kontext-Ressource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Beispiel mit rename()

    <?php
    rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt");
    ?>

### Siehe auch

- copy() - Kopiert eine Datei
- unlink() - Löscht eine Datei
- move_uploaded_file() - Verschiebt eine hochgeladene Datei an einen neuen Ort

# rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

rewind — Setzt die Position eines Dateizeigers auf den Anfang

### Beschreibung

function rewind(resource `$stream`): bool

Setzt den Datei-Positions-Indikator für `stream` an den Anfang des Dateistreams.

> Hinweis:

> Wurde die Datei im Anfüge-Modus ("a" oder "a+") geöffnet, werden unabhängig von der Position des Dateizeigers alle zu schreibenden Daten angehängt.

### Parameter-Liste

`stream`

  Der Dateizeiger muss gültig sein und auf eine Datei zeigen, die zuvor erfolgreich durch fopen() geöffnet wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Beispiel zum Überschreiben mit rewind()

    <?php
    $handle = fopen('output.txt', 'r+');

    fwrite($handle, 'Wirklich langer Satz.');
    rewind($handle);
    fwrite($handle, 'Foo');
    rewind($handle);

    echo fread($handle, filesize('output.txt'));

    fclose($handle);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Fooklich langer Satz.

### Siehe auch

- fread() - Liest Binärdaten aus einer Datei
- fseek() - Positioniert den Dateizeiger
- ftell() - Ermittelt die aktuelle Position des Dateizeigers
- fwrite() - Binär-sicheres Dateischreiben

# rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

rmdir — Löscht ein Verzeichnis

### Beschreibung

function rmdir(string `$directory`, ?resource `$context` = `null`): bool

Versucht das durch `directory` angegebene Verzeichnis zu löschen. Das Verzeichnis muss dafür leer sein und PHP muss die notwendigen Rechte besitzen. Ansonsten wird ein `E_WARNING` geworfen.

### Parameter-Liste

`directory`

  Pfad zum Verzeichnis.

`context`

  Eine Stream-Kontext-Ressource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 rmdir() Beispiel

    <?php
    if (!is_dir('Verzeichnis')) {
        mkdir('Verzeichnis');
    }

    rmdir('Verzeichnis');
    ?>

### Siehe auch

- is_dir() - Prüft, ob der angegebene Dateiname ein Verzeichnis ist
- mkdir() - Erstellt ein Verzeichnis
- unlink() - Löscht eine Datei

# set_file_buffer

(PHP 4, PHP 5, PHP 7, PHP 8)

set_file_buffer — Alias von stream_set_write_buffer()

### Beschreibung

Diese Funktion ist ein Alias für: stream_set_write_buffer().

# stat

(PHP 4, PHP 5, PHP 7, PHP 8)

stat — Sammelt Informationen über eine Datei

### Beschreibung

function stat(string `$filename`): array|false

Sammelt Statistiken über die per `filename` angegebene Datei. Falls `filename` ein symbolischer Link ist, beziehen sich die Statistiken auf die Datei selbst, nicht auf den symbolischen Link. Unter Windows NTS-Builds vor PHP 7.4.0 bezogen sich in diesem Fall die `size`-, `atime`-, `mtime`- und `ctime`-Statistiken auf den symbolischen Link.

lstat() ist identisch zu stat(), mit dem Unterschied, dass es sich auf den Status des symbolischen Links bezieht.

### Parameter-Liste

`filename`

  Pfad zur Datei.

### Rückgabewerte

stat()- und fstat()-Ergebnisformat
Numerisch | Assoziativ | Beschreibung
--- | --- | ---
0 | dev | Gerätenummer ***
1 | ino | Inode-Nummer ****
2 | mode | Inode-Schutzmodus *****
3 | nlink | Anzahl der Links
4 | uid | userid des Besitzers *
5 | gid | groupid des Besitzers *
6 | rdev | Gerätetyp, falls Inode-Gerät
7 | size | Größe in Bytes
8 | atime | Zeitpunkt des letzten Zugriffs (Unix-Timestamp)
9 | mtime | Zeitpunkt der letzten Änderung (Unix-Timestamp)
10 | ctime | Zeitpunkt der letzten Inode-Änderung (Unix-Timestamp)
11 | blksize | Blockgröße des Dateisystem-I/O **
12 | blocks | Anzahl der zugewiesenen 512-Byte-Blöcke **

* Unter Windows wird dies immer `0` sein.

** Nur gültig unter Systemen, die den st_blksize-Typ unterstützen - andere Systeme (z. B. Windows) geben `-1` zurück.

*** Unter Windows, von PHP 7.4.0 an, ist dies die Seriennummer des Laufwerks, das die Datei enhält, welches eine 64-bit Ganzzahl ohne Vorzeichen ist, so dass auf 32-bit-Systemen ein Überlauf erfolgen kann. Zuvor war es die numerische Darstellung des Laufwerksbuchstabens (z. B. `2` für `C:`) für stat(), und `0` für lstat().

**** Unter Windows, von PHP 7.4.0 an, ist dies die mit der Datei assozierte Kennung, welche eine 64-bit Ganzzahl ohne Vorzeichen ist, so dass ein Überlauf erfolgen kann. Zuvor war es immer `0`.

***** Unter Windows wird das Schreibberechtigungsbit entsprechend dem schreibgeschützten Dateiattribut gesetzt, und derselbe Wert wird für alle Benutzer, Gruppen und Besitzer gemeldet. Die ACL wird im Gegensatz zu is_writable() nicht berücksichtigt.

Der Wert von `mode` enthält Informationen, die von mehreren Funktionen gelesen werden. Wenn als Oktalzahl dargestellt und von rechts betrachtet, werden die ersten drei Ziffern von chmod() zurückgegeben. Die nächste Ziffer wird von PHP ignoriert. Die nächsten beiden Ziffern geben den Dateityp an:

`mode` Dateitypen
`mode` als Oktalzahl | Bedeutung
--- | ---
`0140000` | socket
`0120000` | Verknüpfung
`0100000` | reguläre Datei
`0060000` | Block-Gerät
`0040000` | Verzeichnis
`0020000` | zeichenorientiertes Gerät
`0010000` | FIFO

So könnte beispielsweise eine reguläre Datei `0100644`, und ein Verzeichnis `0040755` sein.

Im Fehlerfall gibt stat() `false` zurück.

> Hinweis: Weil PHPs Integer Typ vorzeichenbehaftet ist und viele Platformen 32bit Integer verwenden, können einige Dateisystem-Funktionen für Dateien größer als 2GB unerwartete Ergebnisse liefern.

### Fehler/Exceptions

Im Fehlerfall wird eine `E_WARNING` geworfen.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Unter Windows ist die Gerätenummer nun die Seriennummer des Laufwerks, das die Datei enthält, und die Inode-Nummer ist die mit der Datei assozierte Kennung.
7.4.0 | Die `size`-, `atime`-, `mtime`- und `ctime`-Statistiken symbolischer Links sind nun immer die des Ziels. Dies war zuvor nicht der Fall für NTS-Builds unter Windows.

### Beispiele

Beispiel #1 stat()-Beispiel

    <?php
    /* Hole Datei-Statistik */
    $stat = stat('C:\php\php.exe');

    /*
     * Gebe den Zugriffszeitpunkt der Datei aus; dies entspricht dem
     * Aufruf von fileatime()
     */
    echo 'Zugriffszeitpunkt: ' . $stat['atime'];

    /*
     * Gebe den Änderungszeitpunkt der Datei aus; dies entspricht dem
     * Aufruf von filemtime()
     */
    echo 'Änderungszeitpunkt: ' . $stat['mtime'];

    /* Gebe die Gerätenummer aus */
    echo 'Gerätenummer: ' . $stat['dev'];
    ?>

Beispiel #2 Nutzung von stat()-Informationen zusammen mit touch()

    <?php
    /* Hole Datei-Statistik */
    $stat = stat('C:\php\php.exe');

    /* Hat das Holen der Statistik-Informationen geklappt? */
    if (!$stat) {
        echo 'stat()-Aufruf schlug fehl ...';
    } else {
        /*
         * Wir wollen den Zugriffszeitpunkt auf eine Woche nach dem aktuellen
         * Zugriffszeitpunkt setzen.
         */
        $atime = $stat['atime'] + 604800;

        /* Ändere die Datei */
        if (!touch('eine_datei.txt', time(), $atime)) {
            echo 'Ändern der Datei schlug fehl ...';
        } else {
            echo 'touch()-Befehl war erfolgreich ...';
        }
    }
    ?>

### Anmerkungen

> Hinweis:

> Beachten Sie, dass die zeitliche Auflösung bei verschiedenen Dateisystemen unterschiedlich sein kann.

> Hinweis: Die Ergebnisse dieser Funktion werden zwischengespeichert. Weitere Details sind bei clearstatcache() zu finden.

Tipp

Seit PHP 5.0.0 kann diese Funktion mit einigen URL-Wrappern benutzt werden. Schauen Sie in der Liste unter Unterstützte Protokolle und Wrapper nach, welcher Wrapper die Funktionalität von stat() unterstützt.

### Siehe auch

- lstat() - Sammelt Informationen über eine Datei oder einen symbolischen Link
- fstat() - Sammelt Informationen über eine Datei mittels eines offenen Dateizeigers
- filemtime() - Liefert die Zeit der letzten Dateiänderung
- filegroup() - Liefert die Gruppenzugehörigkeit einer Datei
- SplFileInfo

# symlink

(PHP 4, PHP 5, PHP 7, PHP 8)

symlink — Erzeugt einen symbolischen Link

### Beschreibung

function symlink(string `$target`, string `$link`): bool

symlink() erzeugt einen symbolischen Link auf das existierende Ziel (`target`) mit dem angegebenen Namen (`link`).

### Parameter-Liste

`target`

  Das Ziel des Links.

`link`

  Der Name des Links.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Falls `link` bereits existiert, schlägt die Funktion fehl und gibt ein `E_WARNING` aus. Unter Windows schlägt die Funktion ebenfalls fehl und gibt ein `E_WARNING` aus, falls `target` nicht vorhanden ist.

### Beispiele

Beispiel #1 Einen symbolischen Link erzeugen

    <?php
    $target = 'uploads.php';
    $link = 'uploads';
    symlink($target, $link);

    echo readlink($link);
    ?>

### Siehe auch

- is_link() - Prüft, ob der Dateiname ein symbolischer Link ist
- link() - Erzeugt einen harten Link
- readlink() - Liefert das Ziel eines symbolischen Links
- linkinfo() - Liefert Informationen über einen Link
- unlink() - Löscht eine Datei

# tempnam

(PHP 4, PHP 5, PHP 7, PHP 8)

tempnam — Erzeugt eine Datei mit eindeutigem Dateinamen

### Beschreibung

function tempnam(string `$directory`, string `$prefix`): string|false

Erzeugt eine Datei mit einem eindeutigen Dateinamen in dem angegebenen Verzeichnis, wobei die Zugriffsberechtigungen auf 0600 gesetzt werden. Wenn das Verzeichnis nicht existiert oder nicht beschreibbar ist, erstellt tempnam() eine Datei im temporären Verzeichnis des Systems und gibt den vollständigen Pfad zu dieser Datei, der den Namen beinhaltet, zurück.

### Parameter-Liste

`directory`

  Das Verzeichnis, in dem die temporäre Datei erstellt werden soll.

`prefix`

  Der Präfix des genererierten temporären Dateinamens.

  > Hinweis: Es werden nur die ersten 63 Zeichen des Präfixes verwendet, der Rest wird ignoriert. Windows nutzt nur die ersten drei Zeichen des Präfixes.

### Rückgabewerte

Gibt den neuen temporären Dateinamen (mit Pfad) zurück oder `false` bei einem Fehler.

### Changelog

Version | Beschreibung
--- | ---
7.1.0 | tempnam() gibt nun eine Meldung aus, wenn sie ins temporäre Verzeichnis des Systems zurückfällt.

### Beispiele

Beispiel #1 tempnam()-Beispiel

    <?php
    $tmpfname = tempnam("/tmp", "FOO");

    $handle = fopen($tmpfname, "w");
    fwrite($handle, "schreiben in Temporärdatei");
    fclose($handle);

    // tue etwas

    unlink($tmpfname);
    ?>

### Anmerkungen

> Hinweis: Wenn PHP die Datei nicht im angegebenen Verzeichnis `directory` erzeugen kann, fällt es auf den Standardwert des Systems zurück. Unter NTFS geschieht dies auch, wenn `directory` mehr als 65534 Dateien enthält.

### Siehe auch

- tmpfile() - Erstellt eine temporäre Datei
- sys_get_temp_dir() - Returns directory path used for temporary files
- unlink() - Löscht eine Datei

# tmpfile

(PHP 4, PHP 5, PHP 7, PHP 8)

tmpfile — Erstellt eine temporäre Datei

### Beschreibung

function tmpfile(): resource|false

Erstellt eine temporäre Datei mit einem eindeutigen Dateinamen im Lese-Schreib-Modus (w+b) und gibt einen Dateizeiger zurück.

Die Datei wird automatisch gelöscht, wenn sie geschlossen wird (zum Beispiel durch den Aufruf von fclose() oder wenn es keine verbleibenden Referenzen auf das von tmpfile() zurückgegebenen Datei-Handle mehr gibt) oder wenn das Skript beendet wird.

Achtung

Wird das Skript unerwartet beendet, wird die temporäre Datei möglicherweise nicht gelöscht.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt einen Dateizeiger für die neue Datei zurück, der ähnlich zu dem Zeiger ist, den fopen() zurückgibt. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 tmpfile()-Beispiel

    <?php
    $temp = tmpfile();
    fwrite($temp, "schreiben in Temporärdatei");
    fseek($temp, 0);
    echo fread($temp, 1024);
    fclose($temp); // dies entfernt die Datei

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    schreiben in Temporärdatei

### Siehe auch

- tempnam() - Erzeugt eine Datei mit eindeutigem Dateinamen
- sys_get_temp_dir() - Returns directory path used for temporary files

# touch

(PHP 4, PHP 5, PHP 7, PHP 8)

touch — Setzt die Zugriffs- und Modifikationszeit einer Datei

### Beschreibung

function touch(string `$filename`, ?int `$mtime` = `null`, ?int `$atime` = `null`): bool

Versucht, die Zugriffs- und Modifikationszeit der im Parameter `filename` angegebenen Datei auf `mtime` zu setzen. Zu beachten ist, dass die Zugriffszeit unabhängig von der Anzahl der Parameter immer geändert wird.

Wenn die Datei nicht existiert, wird sie erzeugt.

### Parameter-Liste

`filename`

  Der Name der zu ändernden Datei.

`mtime`

  Die Modifikationszeit. Wenn `mtime` `null` ist, wird die aktuelle Systemzeit (time()) verwendet.

`atime`

  Wenn nicht `null`, wird die Zugriffszeit der angegebenen Datei auf `atime` gesetzt. Andernfalls wird sie auf den Wert des angegebenen Parameters `mtime` gesetzt. Wenn beide `null` sind, wird die aktuelle Systemzeit verwendet.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `mtime` und `atime` sind jetzt nullbar.

### Beispiele

Beispiel #1 touch()-Beispiel

    <?php
    if (touch($filename)) {
        echo 'Die Modifikationszeit von ' . $filename
             . ' wurde auf die aktuelle Zeit gesetzt.';
    } else {
        echo 'Entschuldigung, die Änderung der Modifikationszeit von ' . $filename
             . ' war nicht möglich.';
    }
    ?>

Beispiel #2 Nutzung von touch() mit dem Parameter `mtime`

    <?php
    // Modifikationszeit (eine Stunde in der Vergangenheit)
    $time = time() - 3600;

    // Ändern der Datei
    if (!touch('eine_datei.txt', $time)) {
        echo 'Ein Fehler ist aufgetreten ...';
    } else {
        echo 'Änderung der Modifikationszeit war erfolgreich';
    }
    ?>

### Anmerkungen

> Hinweis:

> Beachten Sie, dass die zeitliche Auflösung bei verschiedenen Dateisystemen unterschiedlich sein kann.

# umask

(PHP 4, PHP 5, PHP 7, PHP 8)

umask — Changes the current umask

### Beschreibung

function umask(?int `$mask` = `null`): int

umask() setzt die umask von PHP auf `mask` & 0777 und gibt die alte umask zurück. Wird PHP als Servermodul benutzt, wird die umask wiederhergestellt, wenn die jeweilige Anfrage beendet ist.

### Parameter-Liste

`mask`

  Die neue umask.

### Rückgabewerte

Wenn `mask` `null` ist, gibt umask() einfach die aktuelle umask zurück, ansonsten wird die alte umask zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `mask` ist jetzt nullbar.

### Beispiele

Beispiel #1 umask()-Beispiel

    <?php
    $old = umask(0);
    chmod("/pfad/ein_verzeichnis/eine_datei.txt", 0755);
    umask($old);

    // Prüfung
    if ($old != umask()) {
        die('Ein Fehler trat beim Wiederherstellen der umask auf');
    }
    ?>

### Anmerkungen

> Hinweis:

> Sie sollten diese Funktion nicht in Multithreaded-Webservern nutzen. Der bessere Weg ist, die Dateiberechtigungen mit chmod() zu ändern nachdem die Datei erstellt wurde. Die Nutzung von umask() kann zu unerwartetem Verhalten von gleichzeitig ausgeführten Skripten und des Webservers führen, weil die gleiche umask genutzt wird.

# unlink

(PHP 4, PHP 5, PHP 7, PHP 8)

unlink — Löscht eine Datei

### Beschreibung

function unlink(string `$filename`, ?resource `$context` = `null`): bool

Löscht `filename`, ähnlich der UNIX-C-Funktion unlink(). Bei einem Fehler wird ein Fehler der Stufe `E_WARNING` erzeugt.

### Parameter-Liste

`filename`

  Der Pfad zur Datei.

  Wenn die Datei ein Symlink ist, wird der Symlink gelöscht. Unter Windows muss zum Löschen eines Symlinks auf ein Verzeichnis stattdessen rmdir() verwendet werden.

`context`

  Eine Stream-Kontext-Ressource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
7.3.0 | Unter Windows ist es nun möglich, Dateien mit verwendeten Handles per unlink() zu löschen, während dies zuvor fehlschlug. Es ist allerdings noch immer nicht möglich, die gelöschte Datei neu zu erzeugen, bevor alle Handles geschlossen wurden.

### Beispiele

Beispiel #1 Einfache Nutzung von unlink()

    <?php
    $fh = fopen('test.html', 'a');
    fwrite($fh, '<h1>Hallo Welt!</h1>');
    fclose($fh);

    unlink('test.html');
    ?>

### Siehe auch

- rmdir() - Löscht ein Verzeichnis

## Inhaltsverzeichnis

- basename — Liefert den letzten Namensteil einer Pfadangabe
- chgrp — Ändert die Gruppenzugehörigkeit einer Datei
- chmod — Ändert den Modus für die Zugriffsrechte einer Datei
- chown — Ändert den Eigentümer einer Datei
- clearstatcache — Löscht den Status-Cache
- copy — Kopiert eine Datei
- delete — Siehe unlink oder unset
- dirname — Liefert den Pfad des übergeordneten Verzeichnisses
- disk_free_space — Liefert den verfügbaren Platz auf einem Dateisystem oder einer Partition
- disk_total_space — Liefert die Gesamtgröße eines Dateisystemes oder einer Partition
- diskfreespace — Alias von disk_free_space
- fclose — Schließt einen offenen Dateizeiger
- fdatasync — Synchronizes data (but not meta-data) to the file
- feof — Prüft, ob ein Dateizeiger am Ende der Datei steht
- fflush — Schreibt den Ausgabepuffer in eine Datei
- fgetc — Liest das Zeichen, auf welches der Dateizeiger zeigt
- fgetcsv — Liest eine Zeile von der Position des Dateizeigers und prüft diese auf kommaseparierte Werte (CSV)
- fgets — Liest die Zeile von der Position des Dateizeigers
- fgetss — Liest eine Zeile von der Position des Dateizeigers und entfernt HTML Tags.
- file — Liest eine komplette Datei in ein Array
- file_exists — Prüft, ob eine Datei oder ein Verzeichnis existiert
- file_get_contents — Liest die gesamte Datei in einen String
- file_put_contents — Schreibt Daten in eine Datei
- fileatime — Liefert die Zeit des letzten Zugriffs auf eine Datei
- filectime — Liefert die Änderungszeit eines Datei-Inodes
- filegroup — Liefert die Gruppenzugehörigkeit einer Datei
- fileinode — Liefert die Inode-Nummer einer Datei
- filemtime — Liefert die Zeit der letzten Dateiänderung
- fileowner — Liefert den Eigentümer einer Datei
- fileperms — Liefert die Zugriffsrechte einer Datei
- filesize — Liefert die Größe einer Datei
- filetype — Liefert den Typ einer Datei
- flock — Portables Datei-Sperrverfahren (advisory locking)
- fnmatch — Match filename against a pattern
- fopen — Öffnet eine Datei oder URL
- fpassthru — Gibt alle verbleibenden Daten eines Dateizeigers aus
- fputcsv — Format line as CSV and write to file pointer
- fputs — Alias von fwrite
- fread — Liest Binärdaten aus einer Datei
- fscanf — Interpretiert den Input einer Datei entsprechend einem angegebenen Format
- fseek — Positioniert den Dateizeiger
- fstat — Sammelt Informationen über eine Datei mittels eines offenen Dateizeigers
- fsync — Synchronizes changes to the file (including meta-data)
- ftell — Ermittelt die aktuelle Position des Dateizeigers
- ftruncate — Kürzt eine Datei auf die angegebene Länge
- fwrite — Binär-sicheres Dateischreiben
- glob — Findet Dateinamen, die mit einem Muster übereinstimmen
- is_dir — Prüft, ob der angegebene Dateiname ein Verzeichnis ist
- is_executable — Prüft, ob der Dateiname ausführbar ist
- is_file — Prüft, ob der Dateiname eine reguläre Datei ist
- is_link — Prüft, ob der Dateiname ein symbolischer Link ist
- is_readable — Prüft, ob eine Datei existiert und lesbar ist
- is_uploaded_file — Prüft, ob die Datei mittels HTTP-POST upgeloadet wurde
- is_writable — Prüft, ob in eine Datei geschrieben werden kann
- is_writeable — Alias von is_writable
- lchgrp — Changes group ownership of symlink
- lchown — Changes user ownership of symlink
- link — Erzeugt einen harten Link
- linkinfo — Liefert Informationen über einen Link
- lstat — Sammelt Informationen über eine Datei oder einen symbolischen Link
- mkdir — Erstellt ein Verzeichnis
- move_uploaded_file — Verschiebt eine hochgeladene Datei an einen neuen Ort
- parse_ini_file — Parst eine Konfigurationsdatei
- parse_ini_string — Analysiert einen Konfigurations-String
- pathinfo — Liefert Informationen über einen Dateipfad
- pclose — Schließt einen Prozess-Dateizeiger
- popen — Öffnet einen Dateizeiger für einen Prozess
- readfile — Gibt eine Datei aus
- readlink — Liefert das Ziel eines symbolischen Links
- realpath — Löst einen Pfad in einen absoluten und eindeutigen auf
- realpath_cache_get — Get realpath cache entries
- realpath_cache_size — Get realpath cache size
- rename — Benennt eine Datei oder ein Verzeichnis um
- rewind — Setzt die Position eines Dateizeigers auf den Anfang
- rmdir — Löscht ein Verzeichnis
- set_file_buffer — Alias von stream_set_write_buffer
- stat — Sammelt Informationen über eine Datei
- symlink — Erzeugt einen symbolischen Link
- tempnam — Erzeugt eine Datei mit eindeutigem Dateinamen
- tmpfile — Erstellt eine temporäre Datei
- touch — Setzt die Zugriffs- und Modifikationszeit einer Datei
- umask — Changes the current umask
- unlink — Löscht eine Datei

- Installation/Konfiguration
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Dateisystem — Dateisystem-Funktionen
  - basename — Liefert den letzten Namensteil einer Pfadangabe
  - chgrp — Ändert die Gruppenzugehörigkeit einer Datei
  - chmod — Ändert den Modus für die Zugriffsrechte einer Datei
  - chown — Ändert den Eigentümer einer Datei
  - clearstatcache — Löscht den Status-Cache
  - copy — Kopiert eine Datei
  - delete — Siehe unlink oder unset
  - dirname — Liefert den Pfad des übergeordneten Verzeichnisses
  - disk_free_space — Liefert den verfügbaren Platz auf einem Dateisystem oder einer Partition
  - disk_total_space — Liefert die Gesamtgröße eines Dateisystemes oder einer Partition
  - diskfreespace — Alias von disk_free_space
  - fclose — Schließt einen offenen Dateizeiger
  - fdatasync — Synchronizes data (but not meta-data) to the file
  - feof — Prüft, ob ein Dateizeiger am Ende der Datei steht
  - fflush — Schreibt den Ausgabepuffer in eine Datei
  - fgetc — Liest das Zeichen, auf welches der Dateizeiger zeigt
  - fgetcsv — Liest eine Zeile von der Position des Dateizeigers und prüft diese auf kommaseparierte Werte (CSV)
  - fgets — Liest die Zeile von der Position des Dateizeigers
  - fgetss — Liest eine Zeile von der Position des Dateizeigers und entfernt HTML Tags.
  - file — Liest eine komplette Datei in ein Array
  - file_exists — Prüft, ob eine Datei oder ein Verzeichnis existiert
  - file_get_contents — Liest die gesamte Datei in einen String
  - file_put_contents — Schreibt Daten in eine Datei
  - fileatime — Liefert die Zeit des letzten Zugriffs auf eine Datei
  - filectime — Liefert die Änderungszeit eines Datei-Inodes
  - filegroup — Liefert die Gruppenzugehörigkeit einer Datei
  - fileinode — Liefert die Inode-Nummer einer Datei
  - filemtime — Liefert die Zeit der letzten Dateiänderung
  - fileowner — Liefert den Eigentümer einer Datei
  - fileperms — Liefert die Zugriffsrechte einer Datei
  - filesize — Liefert die Größe einer Datei
  - filetype — Liefert den Typ einer Datei
  - flock — Portables Datei-Sperrverfahren (advisory locking)
  - fnmatch — Match filename against a pattern
  - fopen — Öffnet eine Datei oder URL
  - fpassthru — Gibt alle verbleibenden Daten eines Dateizeigers aus
  - fputcsv — Format line as CSV and write to file pointer
  - fputs — Alias von fwrite
  - fread — Liest Binärdaten aus einer Datei
  - fscanf — Interpretiert den Input einer Datei entsprechend einem angegebenen Format
  - fseek — Positioniert den Dateizeiger
  - fstat — Sammelt Informationen über eine Datei mittels eines offenen Dateizeigers
  - fsync — Synchronizes changes to the file (including meta-data)
  - ftell — Ermittelt die aktuelle Position des Dateizeigers
  - ftruncate — Kürzt eine Datei auf die angegebene Länge
  - fwrite — Binär-sicheres Dateischreiben
  - glob — Findet Dateinamen, die mit einem Muster übereinstimmen
  - is_dir — Prüft, ob der angegebene Dateiname ein Verzeichnis ist
  - is_executable — Prüft, ob der Dateiname ausführbar ist
  - is_file — Prüft, ob der Dateiname eine reguläre Datei ist
  - is_link — Prüft, ob der Dateiname ein symbolischer Link ist
  - is_readable — Prüft, ob eine Datei existiert und lesbar ist
  - is_uploaded_file — Prüft, ob die Datei mittels HTTP-POST upgeloadet wurde
  - is_writable — Prüft, ob in eine Datei geschrieben werden kann
  - is_writeable — Alias von is_writable
  - lchgrp — Changes group ownership of symlink
  - lchown — Changes user ownership of symlink
  - link — Erzeugt einen harten Link
  - linkinfo — Liefert Informationen über einen Link
  - lstat — Sammelt Informationen über eine Datei oder einen symbolischen Link
  - mkdir — Erstellt ein Verzeichnis
  - move_uploaded_file — Verschiebt eine hochgeladene Datei an einen neuen Ort
  - parse_ini_file — Parst eine Konfigurationsdatei
  - parse_ini_string — Analysiert einen Konfigurations-String
  - pathinfo — Liefert Informationen über einen Dateipfad
  - pclose — Schließt einen Prozess-Dateizeiger
  - popen — Öffnet einen Dateizeiger für einen Prozess
  - readfile — Gibt eine Datei aus
  - readlink — Liefert das Ziel eines symbolischen Links
  - realpath — Löst einen Pfad in einen absoluten und eindeutigen auf
  - realpath_cache_get — Get realpath cache entries
  - realpath_cache_size — Get realpath cache size
  - rename — Benennt eine Datei oder ein Verzeichnis um
  - rewind — Setzt die Position eines Dateizeigers auf den Anfang
  - rmdir — Löscht ein Verzeichnis
  - set_file_buffer — Alias von stream_set_write_buffer
  - stat — Sammelt Informationen über eine Datei
  - symlink — Erzeugt einen symbolischen Link
  - tempnam — Erzeugt eine Datei mit eindeutigem Dateinamen
  - tmpfile — Erstellt eine temporäre Datei
  - touch — Setzt die Zugriffs- und Modifikationszeit einer Datei
  - umask — Changes the current umask
  - unlink — Löscht eine Datei

# Inotify

# Einführung

The inotify extension exposes the inotify functions inotify_init(), inotify_add_watch() and inotify_rm_watch().

As the C inotify_init() function returns a file descriptor, PHP's inotify_init() returns a stream resource, usable with standard stream functions, like stream_select(), stream_set_blocking() and fclose(). inotify_read() replaces the C way of reading inotify events.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation/Konfiguration
- Ressource-Typen

## Installation/Konfiguration

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/inotify.

## Ressource-Typen

This extension defines a stream resource returned by inotify_init().

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

Inotify constants usable with inotify_add_watch() and/or returned by inotify_read()
`IN_ACCESS` (int)
  File was accessed (read) (*)
`IN_MODIFY` (int)
  File was modified (*)
`IN_ATTRIB` (int)
  Metadata changed (e.g. permissions, mtime, etc.) (*)
`IN_CLOSE_WRITE` (int)
  File opened for writing was closed (*)
`IN_CLOSE_NOWRITE` (int)
  File not opened for writing was closed (*)
`IN_OPEN` (int)
  File was opened (*)
`IN_MOVED_TO` (int)
  File moved into watched directory (*)
`IN_MOVED_FROM` (int)
  File moved out of watched directory (*)
`IN_CREATE` (int)
  File or directory created in watched directory (*)
`IN_DELETE` (int)
  File or directory deleted in watched directory (*)
`IN_DELETE_SELF` (int)
  Watched file or directory was deleted
`IN_MOVE_SELF` (int)
  Watch file or directory was moved
`IN_CLOSE` (int)
  Equals to IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
`IN_MOVE` (int)
  Equals to IN_MOVED_FROM | IN_MOVED_TO
`IN_ALL_EVENTS` (int)
  Bitmask of all the above constants
`IN_UNMOUNT` (int)
  File system containing watched object was unmounted
`IN_Q_OVERFLOW` (int)
  Event queue overflowed (wd is -1 for this event)
`IN_IGNORED` (int)
  Watch was removed (explicitly by inotify_rm_watch() or because file was removed or filesystem unmounted
`IN_ISDIR` (int)
  Subject of this event is a directory
`IN_ONLYDIR` (int)
  Only watch pathname if it is a directory (Since Linux 2.6.15)
`IN_DONT_FOLLOW` (int)
  Do not dereference pathname if it is a symlink (Since Linux 2.6.15)
`IN_MASK_ADD` (int)
  Add events to watch mask for this pathname if it already exists (instead of replacing mask).
`IN_ONESHOT` (int)
  Monitor pathname for one event, then remove from watch list.

> Hinweis: The events marked with an asterisk (*) above can occur for files in watched directories.

# Inotify Funktionen

# inotify_add_watch

(PECL inotify >= 0.1.2)

inotify_add_watch — Add a watch to an initialized inotify instance

### Beschreibung

function inotify_add_watch(resource `$inotify_instance`, string `$pathname`, int `$mask`): int|false

inotify_add_watch() adds a new watch or modify an existing watch for the file or directory specified in `pathname`.

Using inotify_add_watch() on a watched object replaces the existing watch. Using the `IN_MASK_ADD` constant adds (OR) events to the existing watch.

### Parameter-Liste

`inotify_instance`
  Von inotify_init() zurückgegebene Ressource
`pathname`
  File or directory to watch
`mask`
  Events to watch for. See Vordefinierte Konstanten.

### Rückgabewerte

The return value is a unique (inotify instance wide) watch descriptor, Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- inotify_init() - Initialize an inotify instance

# inotify_init

(PECL inotify >= 0.1.2)

inotify_init — Initialize an inotify instance

### Beschreibung

function inotify_init(): resource|false

Initialize an inotify instance for use with inotify_add_watch()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

A stream resource or `false` on error.

### Beispiele

Beispiel #1 Example usage of inotify

    <?php
    // Open an inotify instance
    $fd = inotify_init();

    // Watch __FILE__ for metadata changes (e.g. mtime)
    $watch_descriptor = inotify_add_watch($fd, __FILE__, IN_ATTRIB);

    // generate an event
    touch(__FILE__);

    // Read events
    $events = inotify_read($fd);
    print_r($events);

    // The following methods allows to use inotify functions without blocking on inotify_read():

    // - Using stream_select() on $fd:
    $read = array($fd);
    $write = null;
    $except = null;
    stream_select($read,$write,$except,0);

    // - Using stream_set_blocking() on $fd
    stream_set_blocking($fd, 0);
    inotify_read($fd); // Does no block, and return false if no events are pending

    // - Using inotify_queue_len() to check if event queue is not empty
    $queue_len = inotify_queue_len($fd); // If > 0, inotify_read() will not block

    // Stop watching __FILE__ for metadata changes
    inotify_rm_watch($fd, $watch_descriptor);

    // Close the inotify instance
    // This may have closed all watches if this was not already done
    fclose($fd);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(
      array(
        'wd' => 1,     // Equals $watch_descriptor
        'mask' => 4,   // IN_ATTRIB bit is set
        'cookie' => 0, // unique id to connect related events (e.g.
                       // IN_MOVE_FROM and IN_MOVE_TO events)
        'name' => '',  // the name of a file (e.g. if we monitored changes
                       // in a directory)
      ),
    );

### Siehe auch

- inotify_add_watch() - Add a watch to an initialized inotify instance
- inotify_rm_watch() - Remove an existing watch from an inotify instance
- inotify_queue_len() - Return a number upper than zero if there are pending events
- inotify_read() - Read events from an inotify instance
- fclose() - Schließt einen offenen Dateizeiger

# inotify_queue_len

(PECL inotify >= 0.1.2)

inotify_queue_len — Return a number upper than zero if there are pending events

### Beschreibung

function inotify_queue_len(resource `$inotify_instance`): int

This function allows to know if inotify_read() will block or not. If a number upper than zero is returned, there are pending events and inotify_read() will not block.

### Parameter-Liste

`inotify_instance`
  Von inotify_init() zurückgegebene Ressource

### Rückgabewerte

Returns a number upper than zero if there are pending events.

### Siehe auch

- inotify_init() - Initialize an inotify instance
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by seconds and microseconds
- stream_set_blocking() - Set blocking/non-blocking mode on a stream

# inotify_read

(PECL inotify >= 0.1.2)

inotify_read — Read events from an inotify instance

### Beschreibung

function inotify_read(resource `$inotify_instance`): array

Read inotify events from an inotify instance.

### Parameter-Liste

`inotify_instance`
  Von inotify_init() zurückgegebene Ressource

### Rückgabewerte

An array of inotify events or `false` if no events was pending and `inotify_instance` is non-blocking. Each event is an array with the following keys:

- wd is a watch descriptor returned by inotify_add_watch()
- mask is a bit mask of events
- cookie is a unique id to connect related events (e.g. `IN_MOVE_FROM` and `IN_MOVE_TO`)
- name is the name of a file (e.g. if a file was modified in a watched directory)

### Siehe auch

- inotify_init() - Initialize an inotify instance
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by seconds and microseconds
- stream_set_blocking() - Set blocking/non-blocking mode on a stream
- inotify_queue_len() - Return a number upper than zero if there are pending events

# inotify_rm_watch

(PECL inotify >= 0.1.2)

inotify_rm_watch — Remove an existing watch from an inotify instance

### Beschreibung

function inotify_rm_watch(resource `$inotify_instance`, int `$watch_descriptor`): bool

inotify_rm_watch() removes the watch `watch_descriptor` from the inotify instance `inotify_instance`.

### Parameter-Liste

`inotify_instance`
  Von inotify_init() zurückgegebene Ressource
`watch_descriptor`
  Watch to remove from the instance

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- inotify_init() - Initialize an inotify instance

## Inhaltsverzeichnis

- inotify_add_watch — Add a watch to an initialized inotify instance
- inotify_init — Initialize an inotify instance
- inotify_queue_len — Return a number upper than zero if there are pending events
- inotify_read — Read events from an inotify instance
- inotify_rm_watch — Remove an existing watch from an inotify instance

- Installation/Konfiguration
  - Installation/Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Inotify Funktionen
  - inotify_add_watch — Add a watch to an initialized inotify instance
  - inotify_init — Initialize an inotify instance
  - inotify_queue_len — Return a number upper than zero if there are pending events
  - inotify_read — Read events from an inotify instance
  - inotify_rm_watch — Remove an existing watch from an inotify instance

# xattr

# Einführung

The xattr extension allows for the manipulation of extended attributes on a filesystem.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

To use xattr, you will need libattr installed. It is available at » http://savannah.nongnu.org/projects/attr/.

> Hinweis:

> These functions only work on filesystems that support extended attributes, and have them enabled at mount time. Some common filesystems that support extended attributes are `ext2`, `ext3`, `reiserfs`, `jfs`, and `xfs`.

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/xattr.

Eine DLL-Datei für diese PECL-Erweiterung steht derzeit nicht zur Verfügung. Weitere Details finden Sie im Abschnitt zum Kompilieren für Windows.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`XATTR_ROOT` (int)
  Set attribute in root (trusted) namespace. Requires root privileges.
`XATTR_DONTFOLLOW` (int)
  Do not follow the symbolic link but operate on symbolic link itself.
`XATTR_CREATE` (int)
  Function will fail if extended attribute already exists.
`XATTR_REPLACE` (int)
  Function will fail if extended attribute doesn't exist.

# xattr Funktionen

# xattr_get

(PECL xattr >= 0.9.0)

xattr_get — Get an extended attribute

### Beschreibung

function xattr_get(string `$filename`, string `$name`, int `$flags` = 0): string|false

This function gets the value of an extended attribute of a file.

Erweiterte Eigenschaften haben zwei verschiedene Namensräume: den User- und den Root-Namensraum. Der User-Namensraum steht allen Benutzern zur Verfügung, während der Root-Namensraum nur Benutzern mit Root-Rechten zur Verfügung steht. xattr operiert standardmäßig im User-Namensraum, aber das können Sie mit dem Parameter `flags` ändern.

### Parameter-Liste

`filename`

  The file from which we get the attribute.

`name`

  The name of the attribute.

`flags`

  Supported xattr flags
  `XATTR_DONTFOLLOW` | Do not follow the symbolic link but operate on symbolic link itself.
  `XATTR_ROOT` | Set attribute in root (trusted) namespace. Requires root privileges.

### Rückgabewerte

Returns a string containing the value or `false` if the attribute doesn't exist.

### Beispiele

Beispiel #1 Checks if system administrator has signed the file

    <?php
    $file = '/usr/local/sbin/some_binary';
    $signature = xattr_get($file, 'Root signature', XATTR_ROOT);

    /* ... check if $signature is valid ... */

    ?>

### Siehe auch

- xattr_list() - Get a list of extended attributes
- xattr_set() - Set an extended attribute
- xattr_remove() - Remove an extended attribute

# xattr_list

(PECL xattr >= 0.9.0)

xattr_list — Get a list of extended attributes

### Beschreibung

function xattr_list(string `$filename`, int `$flags` = 0): array

This functions gets a list of names of extended attributes of a file.

Erweiterte Eigenschaften haben zwei verschiedene Namensräume: den User- und den Root-Namensraum. Der User-Namensraum steht allen Benutzern zur Verfügung, während der Root-Namensraum nur Benutzern mit Root-Rechten zur Verfügung steht. xattr operiert standardmäßig im User-Namensraum, aber das können Sie mit dem Parameter `flags` ändern.

### Parameter-Liste

`filename`

  The path of the file.

`flags`

  Supported xattr flags
  `XATTR_DONTFOLLOW` | Do not follow the symbolic link but operate on symbolic link itself.
  `XATTR_ROOT` | Set attribute in root (trusted) namespace. Requires root privileges.

### Rückgabewerte

This function returns an array with names of extended attributes.

### Beispiele

Beispiel #1 Prints names of all extended attributes of file

    <?php
    $file = 'some_file';
    $root_attributes = xattr_list($file, XATTR_ROOT);
    $user_attributes = xattr_list($file);

    echo "Root attributes: \n";
    foreach ($root_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    echo "\n User attributes: \n";
    foreach ($user_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    ?>

### Siehe auch

- xattr_get() - Get an extended attribute

# xattr_remove

(PECL xattr >= 0.9.0)

xattr_remove — Remove an extended attribute

### Beschreibung

function xattr_remove(string `$filename`, string `$name`, int `$flags` = 0): bool

This function removes an extended attribute of a file.

Erweiterte Eigenschaften haben zwei verschiedene Namensräume: den User- und den Root-Namensraum. Der User-Namensraum steht allen Benutzern zur Verfügung, während der Root-Namensraum nur Benutzern mit Root-Rechten zur Verfügung steht. xattr operiert standardmäßig im User-Namensraum, aber das können Sie mit dem Parameter `flags` ändern.

### Parameter-Liste

`filename`

  The file from which we remove the attribute.

`name`

  The name of the attribute to remove.

`flags`

  Supported xattr flags
  `XATTR_DONTFOLLOW` | Do not follow the symbolic link but operate on symbolic link itself.
  `XATTR_ROOT` | Set attribute in root (trusted) namespace. Requires root privileges.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Removes all extended attributes of a file

    <?php
    $file = 'some_file';
    $attributes = xattr_list($file);

    foreach ($attributes as $attr_name) {
        xattr_remove($file, $attr_name);
    }
    ?>

### Siehe auch

- xattr_list() - Get a list of extended attributes
- xattr_set() - Set an extended attribute
- xattr_get() - Get an extended attribute

# xattr_set

(PECL xattr >= 0.9.0)

xattr_set — Set an extended attribute

### Beschreibung

function xattr_set(
string `$filename`,
string `$name`,
string `$value`,
int `$flags` = 0
): bool

This function sets the value of an extended attribute of a file.

Erweiterte Eigenschaften haben zwei verschiedene Namensräume: den User- und den Root-Namensraum. Der User-Namensraum steht allen Benutzern zur Verfügung, während der Root-Namensraum nur Benutzern mit Root-Rechten zur Verfügung steht. xattr operiert standardmäßig im User-Namensraum, aber das können Sie mit dem Parameter `flags` ändern.

### Parameter-Liste

`filename`

  The file in which we set the attribute.

`name`

  The name of the extended attribute. This attribute will be created if it doesn't exist or replaced otherwise. You can change this behaviour by using the `flags` parameter.

`value`

  The value of the attribute.

`flags`

  Supported xattr flags
  `XATTR_CREATE` | Function will fail if extended attribute already exists.
  `XATTR_REPLACE` | Function will fail if extended attribute doesn't exist.
  `XATTR_DONTFOLLOW` | Do not follow the symbolic link but operate on symbolic link itself.
  `XATTR_ROOT` | Set attribute in root (trusted) namespace. Requires root privileges.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Sets extended attributes on .wav file

    <?php
    $file = 'my_favourite_song.wav';
    xattr_set($file, 'Artist', 'Someone');
    xattr_set($file, 'My ranking', 'Good');
    xattr_set($file, 'Listen count', '34');

    /* ... other code ... */

    printf("You've played this song %d times", xattr_get($file, 'Listen count'));
    ?>

### Siehe auch

- xattr_get() - Get an extended attribute
- xattr_remove() - Remove an extended attribute

# xattr_supported

(PECL xattr >= 1.0.0)

xattr_supported — Check if filesystem supports extended attributes

### Beschreibung

function xattr_supported(string `$filename`, int `$flags` = 0): bool

This functions checks if the filesystem holding the given file supports extended attributes. Read access to the file is required.

### Parameter-Liste

`filename`

  The path of the tested file.

`flags`

  Supported xattr flags
  `XATTR_DONTFOLLOW` | Do not follow the symbolic link but operate on symbolic link itself.

### Rückgabewerte

This function returns `true` if filesystem supports extended attributes, `false` if it doesn't and `null` if it can't be determined (for example wrong path or lack of permissions to file).

### Beispiele

Beispiel #1 xattr_supported() example

The following code checks if we can use extended attributes.

    <?php
    $file = 'some_file';

    if (xattr_supported($file)) {
        /* ... make use of some xattr_* functions ... */
    }

    ?>

### Siehe auch

- xattr_get() - Get an extended attribute
- xattr_list() - Get a list of extended attributes

## Inhaltsverzeichnis

- xattr_get — Get an extended attribute
- xattr_list — Get a list of extended attributes
- xattr_remove — Remove an extended attribute
- xattr_set — Set an extended attribute
- xattr_supported — Check if filesystem supports extended attributes

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Vordefinierte Konstanten
- xattr Funktionen
  - xattr_get — Get an extended attribute
  - xattr_list — Get a list of extended attributes
  - xattr_remove — Remove an extended attribute
  - xattr_set — Set an extended attribute
  - xattr_supported — Check if filesystem supports extended attributes

# xdiff

# Einführung

xdiff extension enables you to create and apply patch files containing differences between different revisions of files.

This extension supports two modes of operation - on strings and on files, as well as two different patch formats - unified and binary. Unified patches are excellent for text files as they are human-readable and easy to review. For binary files like archives or images, binary patches will be adequate choice as they are binary safe and handle non-printable characters well.

Starting from version 1.5.0 there are two different sets of functions for generating binary patches. New functions - xdiff_string_rabdiff() and xdiff_file_rabdiff() generate output compatible with older functions but are typically faster and generate smaller results. For more details about methods of generating binary patches and differences between them, please check » libxdiff website.

This extension uses libxdiff to implement these functions. Please see » http://www.xmailserver.org/xdiff-lib.html for more information.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

To use xdiff, you will need libxdiff installed, available on the libxdiff homepage » http://www.xmailserver.org/xdiff-lib.html.

> Hinweis:

> You'll need at least libxdiff 0.7 for these functions to be aware of memory_limit.

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/xdiff.

Windows-Binaries (DLL-Dateien) für diese PECL-Erweiterung sind auf der PECL-Website erhältlich.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`XDIFF_PATCH_NORMAL` (int)
  This flag indicates that xdiff_string_patch() and xdiff_file_patch() functions should create result by applying patch to original content thus creating newer version of file. This is the default mode of operation.
`XDIFF_PATCH_REVERSE` (int)
  This flag indicated that xdiff_string_patch() and xdiff_file_patch() functions should create result by reversing patch changed from newer content thus creating original version.

# xdiff Funktionen

# xdiff_file_bdiff

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff — Make binary diff of two files

### Beschreibung

function xdiff_file_bdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Makes a binary diff of two files and stores the result in a patch file. This function works with both text and binary files. Resulting patch file can be later applied using xdiff_file_bpatch()/xdiff_string_bpatch().

### Parameter-Liste

`old_file`

  Path to the first file. This file acts as "old" file.

`new_file`

  Path to the second file. This file acts as "new" file.

`dest`

  Path of the resulting patch file. Resulting file contains differences between "old" and "new" files. It is in binary format and is human-unreadable.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 xdiff_file_bdiff() example

The following code makes binary diff of two archives.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_bdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Anmerkungen

> Hinweis:

> Both files will be loaded into memory so ensure that your memory_limit is set high enough.

### Siehe auch

- xdiff_file_bpatch() - Patch a file with a binary diff

# xdiff_file_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff_size — Read a size of file created by applying a binary diff

### Beschreibung

function xdiff_file_bdiff_size(string `$file`): int

Returns a size of a result file that would be created after applying binary patch from file `file` to the original file.

### Parameter-Liste

`file`

  The path to the binary patch created by xdiff_string_bdiff() or xdiff_string_rabdiff() function.

### Rückgabewerte

Returns the size of file that would be created.

### Beispiele

Beispiel #1 xdiff_file_bdiff_size() example

The following code applies reads a size of file that would be created after applying a binary diff.

    <?php
    $length = xdiff_string_bdiff_size('file.bdiff');
    echo "Resulting file will be $length bytes long";
    ?>

### Siehe auch

- xdiff_file_bdiff() - Make binary diff of two files
- xdiff_file_rabdiff() - Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
- xdiff_file_bpatch() - Patch a file with a binary diff

# xdiff_file_bpatch

(PECL xdiff >= 1.5.0)

xdiff_file_bpatch — Patch a file with a binary diff

### Beschreibung

function xdiff_file_bpatch(string `$file`, string `$patch`, string `$dest`): bool

Patches a `file` with a binary `patch` and stores the result in a file `dest`. This function accepts patches created both via xdiff_file_bdiff() and xdiff_file_rabdiff() functions or their string counterparts.

### Parameter-Liste

`file`

  The original file.

`patch`

  The binary patch file.

`dest`

  Path of the resulting file.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 xdiff_file_bpatch() example

The following code applies binary diff to a file.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_bpatch($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "File patched";
    } else {
       echo "File couldn't be patched";
    }

    ?>

### Anmerkungen

> Hinweis:

> Both files (`file` and `patch`) will be loaded into memory so ensure that your memory_limit is set high enough.

### Siehe auch

- xdiff_file_bdiff() - Make binary diff of two files
- xdiff_file_rabdiff() - Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm

# xdiff_file_diff

(PECL xdiff >= 0.2.0)

xdiff_file_diff — Make unified diff of two files

### Beschreibung

function xdiff_file_diff(
string `$old_file`,
string `$new_file`,
string `$dest`,
int `$context` = 3,
bool `$minimal` = `false`
): bool

Makes an unified diff containing differences between `old_file` and `new_file` and stores it in `dest` file. The resulting file is human-readable. An optional `context` parameter specifies how many lines of context should be added around each change. Setting `minimal` parameter to true will result in outputting the shortest patch file possible (can take a long time).

### Parameter-Liste

`old_file`

  Path to the first file. This file acts as "old" file.

`new_file`

  Path to the second file. This file acts as "new" file.

`dest`

  Path of the resulting patch file.

`context`

  Indicates how many lines of context you want to include in diff result.

`minimal`

  Set this parameter to `true` if you want to minimalize size of the result (can take a long time).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 xdiff_file_diff() example

The following code makes unified diff of two php files with context length of 2.

    <?php
    $old_version = 'my_script.php';
    $new_version = 'my_new_script.php';

    xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
    ?>

### Anmerkungen

> Hinweis:

> This function doesn't work well with binary files. To make diff of binary files use xdiff_file_bdiff()/xdiff_file_rabdiff() function.

### Siehe auch

- xdiff_file_patch() - Patch a file with an unified diff

# xdiff_file_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_file_diff_binary — Alias von xdiff_file_bdiff()

### Beschreibung

function xdiff_file_diff_binary(string `$old_file`, string `$new_file`, string `$dest`): bool

Makes a binary diff of two files and stores the result in a patch file. This function works with both text and binary files. Resulting patch file can be later applied using xdiff_file_bpatch().

Starting with version 1.5.0 this function is an alias of xdiff_file_bdiff().

### Parameter-Liste

`old_file`

  Path to the first file. This file acts as "old" file.

`new_file`

  Path to the second file. This file acts as "new" file.

`dest`

  Path of the resulting patch file. Resulting file contains differences between "old" and "new" files. It is in binary format and is human-unreadable.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 xdiff_file_diff_binary() example

The following code makes binary diff of two archives.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
    ?>

### Anmerkungen

> Hinweis:

> Both files will be loaded into memory so ensure that your memory_limit is set high enough.

### Siehe auch

- xdiff_file_bdiff() - Make binary diff of two files
- xdiff_file_bpatch() - Patch a file with a binary diff

# xdiff_file_merge3

(PECL xdiff >= 0.2.0)

xdiff_file_merge3 — Merge 3 files into one

### Beschreibung

function xdiff_file_merge3(
string `$old_file`,
string `$new_file1`,
string `$new_file2`,
string `$dest`
): mixed

Merges three files into one and stores the result in a file `dest`. The `old_file` is an original version while `new_file1` and `new_file2` are modified versions of an original.

### Parameter-Liste

`old_file`

  Path to the first file. It acts as "old" file.

`new_file1`

  Path to the second file. It acts as modified version of `old_file`.

`new_file2`

  Path to the third file. It acts as modified version of `old_file`.

`dest`

  Path of the resulting file, containing merged changed from both `new_file1` and `new_file2`.

### Rückgabewerte

Returns `true` if merge was successful, string with rejected chunks if it was not or `false` if an internal error happened.

### Beispiele

Beispiel #1 xdiff_file_merge3() example

The following code merges three files into one.

    <?php
    $old_version = 'original_script.php';
    $fix1 = 'script_with_fix1.php';
    $fix2 = 'script_with_fix2.php';

    $errors = xdiff_file_merge3($old_version, $fix1, $fix2, 'fixed_script.php');
    if (is_string($errors)) {
        echo "Rejects:\n";
        echo $errors;
    }
    ?>

### Siehe auch

- xdiff_string_merge3() - Merge 3 strings into one

# xdiff_file_patch

(PECL xdiff >= 0.2.0)

xdiff_file_patch — Patch a file with an unified diff

### Beschreibung

function xdiff_file_patch(
string `$file`,
string `$patch`,
string `$dest`,
int `$flags` = DIFF_PATCH_NORMAL
): mixed

Patches a `file` with a `patch` and stores the result in a file. `patch` has to be an unified diff created by xdiff_file_diff()/xdiff_string_diff() function. An optional `flags` parameter specifies mode of operation.

### Parameter-Liste

`file`

  The original file.

`patch`

  The unified patch file. It has to be created using xdiff_string_diff(), xdiff_file_diff() functions or compatible tools.

`dest`

  Path of the resulting file.

`flags`

  Can be either `XDIFF_PATCH_NORMAL` (default mode, normal patch) or `XDIFF_PATCH_REVERSE` (reversed patch).

  Starting from version 1.5.0, you can also use binary OR to enable `XDIFF_PATCH_IGNORESPACE` flag.

### Rückgabewerte

Returns `false` if an internal error happened, string with rejected chunks if patch couldn't be applied or `true` if patch has been successfully applied.

### Beispiele

Beispiel #1 xdiff_file_patch() example

The following code applies unified diff to a file.

    <?php
    $old_version = 'my_script-1.0.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($old_version, $patch, 'my_script-1.1.php');
    if (is_string($errors)) {
       echo "Rejects:\n";
       echo $errors;
    }

    ?>

Beispiel #2 Patch reversing example

The following code reverses a patch.

    <?php
    $new_version = 'my_script-1.1.php';
    $patch = 'my_script.patch';

    $errors = xdiff_file_patch($new_version, $patch, 'my_script-1.0.php', XDIFF_PATCH_REVERSE);
    if (is_string($errors)) {
       echo "Rejects:\n";
       echo $errors;
    }

    ?>

### Siehe auch

- xdiff_file_diff() - Make unified diff of two files

# xdiff_file_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_file_patch_binary — Alias von xdiff_file_bpatch()

### Beschreibung

function xdiff_file_patch_binary(string `$file`, string `$patch`, string `$dest`): bool

Patches a `file` with a binary `patch` and stores the result in a file `dest`. This function accepts patches created both via xdiff_file_bdiff() or xdiff_file_rabdiff() functions or their string counterparts.

Starting with version 1.5.0 this function is an alias of xdiff_file_bpatch().

### Parameter-Liste

`file`

  The original file.

`patch`

  The binary patch file.

`dest`

  Path of the resulting file.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 xdiff_file_patch_binary() example

The following code applies binary diff to a file.

    <?php
    $old_version = 'archive-1.0.tgz';
    $patch = 'archive.bpatch';

    $result = xdiff_file_patch_binary($old_version, $patch, 'archive-1.1.tgz');
    if ($result) {
       echo "File patched";
    } else {
       echo "File couldn't be patched";
    }

    ?>

### Anmerkungen

> Hinweis:

> Both files (`file` and `patch`) will be loaded into memory so ensure that your memory_limit is set high enough.

### Siehe auch

- xdiff_string_patch_binary() - Alias von xdiff_string_bpatch

# xdiff_file_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_file_rabdiff — Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm

### Beschreibung

function xdiff_file_rabdiff(string `$old_file`, string `$new_file`, string `$dest`): bool

Makes a binary diff of two files and stores the result in a patch file. The difference between this function and xdiff_file_bdiff() is different algorithm used which should result in faster execution and smaller diff produced. This function works with both text and binary files. Resulting patch file can be later applied using xdiff_file_bpatch()/xdiff_string_bpatch().

For more details about differences between algorithm used please check » libxdiff website.

### Parameter-Liste

`old_file`

  Path to the first file. This file acts as "old" file.

`new_file`

  Path to the second file. This file acts as "new" file.

`dest`

  Path of the resulting patch file. Resulting file contains differences between "old" and "new" files. It is in binary format and is human-unreadable.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 xdiff_file_rabdiff() example

The following code makes binary diff of two archives.

    <?php
    $old_version = 'my_script_1.0.tgz';
    $new_version = 'my_script_1.1.tgz';

    xdiff_file_rabdiff($old_version, $new_version, 'my_script.bdiff');
    ?>

### Anmerkungen

> Hinweis:

> Both files will be loaded into memory so ensure that your memory_limit is set high enough.

### Siehe auch

- xdiff_file_bpatch() - Patch a file with a binary diff

# xdiff_string_bdiff

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff — Make binary diff of two strings

### Beschreibung

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Makes a binary diff of two strings and returns the result. This function works with both text and binary data. Resulting patch can be later applied using xdiff_string_bpatch()/xdiff_file_bpatch().

### Parameter-Liste

`old_data`

  First string with binary data. It acts as "old" data.

`new_data`

  Second string with binary data. It acts as "new" data.

### Rückgabewerte

Returns string with binary diff containing differences between "old" and "new" data or `false` if an internal error occurred.

### Siehe auch

- xdiff_string_bpatch() - Patch a string with a binary diff

# xdiff_string_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff_size — Read a size of file created by applying a binary diff

### Beschreibung

function xdiff_string_bdiff_size(string `$patch`): int

Returns a size of a result file that would be created after applying binary `patch` to the original file.

### Parameter-Liste

`patch`

  The binary patch created by xdiff_string_bdiff() or xdiff_string_rabdiff() function.

### Rückgabewerte

Returns the size of file that would be created.

### Beispiele

Beispiel #1 xdiff_string_bdiff_size() example

The following code applies reads a size of file that would be created after applying a binary diff.

    <?php
    $binary_patch = file_get_contents('file.bdiff');
    $length = xdiff_string_bdiff_size($binary_patch);
    echo "Resulting file will be $length bytes long";
    ?>

### Siehe auch

- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_rabdiff() - Make a binary diff of two strings using the Rabin's polynomial fingerprinting algorithm
- xdiff_string_bpatch() - Patch a string with a binary diff

# xdiff_string_bpatch

(PECL xdiff >= 1.5.0)

xdiff_string_bpatch — Patch a string with a binary diff

### Beschreibung

function xdiff_string_bpatch(string `$str`, string `$patch`): string

Patches a string `str` with a binary `patch`. This function accepts patches created both via xdiff_string_bdiff() and xdiff_string_rabdiff() functions or their file counterparts.

### Parameter-Liste

`str`

  The original binary string.

`patch`

  The binary patch string.

### Rückgabewerte

Returns the patched string, or `false` on error.

### Siehe auch

- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_rabdiff() - Make a binary diff of two strings using the Rabin's polynomial fingerprinting algorithm

# xdiff_string_diff

(PECL xdiff >= 0.2.0)

xdiff_string_diff — Make unified diff of two strings

### Beschreibung

function xdiff_string_diff(
string `$old_data`,
string `$new_data`,
int `$context` = 3,
bool `$minimal` = `false`
): string

Makes an unified diff containing differences between `old_data` string and `new_data` string and returns it. The resulting diff is human-readable. An optional `context` parameter specifies how many lines of context should be added around each change. Setting `minimal` parameter to true will result in outputting the shortest patch file possible (can take a long time).

### Parameter-Liste

`old_data`

  First string with data. It acts as "old" data.

`new_data`

  Second string with data. It acts as "new" data.

`context`

  Indicates how many lines of context you want to include in the diff result.

`minimal`

  Set this parameter to `true` if you want to minimalize the size of the result (can take a long time).

### Rückgabewerte

Returns string with resulting diff or `false` if an internal error happened.

### Beispiele

Beispiel #1 xdiff_string_diff() example

The following code makes unified diff of two articles.

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $new_article = $_REQUEST['article']; /* Let's say that someone pasted a new article to html form */

    $diff = xdiff_string_diff($old_article, $new_article, 1);
    if (is_string($diff)) {
        echo "Differences between two articles:\n";
        echo $diff;
    }

    ?>

### Anmerkungen

> Hinweis:

> This function doesn't work well with binary strings. To make diff of binary strings use xdiff_string_bdiff()/xdiff_string_rabdiff().

### Siehe auch

- xdiff_string_patch() - Patch a string with an unified diff

# xdiff_string_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_string_diff_binary — Alias von xdiff_string_bdiff()

### Beschreibung

function xdiff_string_bdiff(string `$old_data`, string `$new_data`): string

Makes a binary diff of two strings and returns the result. This function works with both text and binary data. Resulting patch can be later applied using xdiff_string_bpatch()/xdiff_file_bpatch().

Starting with version 1.5.0 this function is an alias of xdiff_string_bdiff().

### Parameter-Liste

`old_data`

  First string with binary data. It acts as "old" data.

`new_data`

  Second string with binary data. It acts as "new" data.

### Rückgabewerte

Returns string with result or `false` if an internal error happened.

### Siehe auch

- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_bpatch() - Patch a string with a binary diff

# xdiff_string_merge3

(PECL xdiff >= 0.2.0)

xdiff_string_merge3 — Merge 3 strings into one

### Beschreibung

function xdiff_string_merge3(
string `$old_data`,
string `$new_data1`,
string `$new_data2`,
string `&$error` = ?
): mixed

Merges three strings into one and returns the result. The `old_data` is an original version of data while `new_data1` and `new_data2` are modified versions of an original. An optional `error` is used to pass any rejected parts during merging process.

### Parameter-Liste

`old_data`

  First string with data. It acts as "old" data.

`new_data1`

  Second string with data. It acts as modified version of `old_data`.

`new_data2`

  Third string with data. It acts as modified version of `old_data`.

`error`

  If provided then rejected parts are stored inside this variable.

### Rückgabewerte

Returns the merged string, `false` if an internal error happened, or `true` if merged string is empty.

### Siehe auch

- xdiff_file_merge3() - Merge 3 files into one

# xdiff_string_patch

(PECL xdiff >= 0.2.0)

xdiff_string_patch — Patch a string with an unified diff

### Beschreibung

function xdiff_string_patch(
string `$str`,
string `$patch`,
int `$flags` = ?,
string `&$error` = ?
): string

Patches a `str` string with an unified patch in `patch` parameter and returns the result. `patch` has to be an unified diff created by xdiff_file_diff()/xdiff_string_diff() function. An optional `flags` parameter specifies mode of operation. Any rejected parts of the patch will be stored inside `error` variable if it is provided.

### Parameter-Liste

`str`

  The original string.

`patch`

  The unified patch string. It has to be created using xdiff_string_diff(), xdiff_file_diff() functions or compatible tools.

`flags`

  `flags` can be either `XDIFF_PATCH_NORMAL` (default mode, normal patch) or `XDIFF_PATCH_REVERSE` (reversed patch).

  Starting from version 1.5.0, you can also use binary OR to enable `XDIFF_PATCH_IGNORESPACE` flag.

`error`

  If provided then rejected parts are stored inside this variable.

### Rückgabewerte

Returns the patched string, or `false` on error.

### Beispiele

Beispiel #1 xdiff_string_patch() example

The following code applies changes to some article.

    <?php
    $old_article = file_get_contents('./old_article.txt');
    $diff = $_SERVER['patch']; /* Let's say that someone pasted a patch to html form */

    $errors = '';

    $new_article = xdiff_string_patch($old_article, $diff, XDIFF_PATCH_NORMAL, $errors);
    if (is_string($new_article)) {
        echo "New article:\n";
        echo $new_article;
    }

    if (strlen($errors)) {
        echo "Rejects: \n";
        echo $errors;
    }

    ?>

### Siehe auch

- xdiff_string_diff() - Make unified diff of two strings

# xdiff_string_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_string_patch_binary — Alias von xdiff_string_bpatch()

### Beschreibung

function xdiff_string_patch_binary(string `$str`, string `$patch`): string

Patches a string `str` with a binary `patch`. This function accepts patches created both via xdiff_string_bdiff() and xdiff_string_rabdiff() functions or their file counterparts.

Starting with version 1.5.0 this function is an alias of xdiff_string_bpatch().

### Parameter-Liste

`str`

  The original binary string.

`patch`

  The binary patch string.

### Rückgabewerte

Returns the patched string, or `false` on error.

### Siehe auch

- xdiff_string_bpatch() - Patch a string with a binary diff
- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_rabdiff() - Make a binary diff of two strings using the Rabin's polynomial fingerprinting algorithm

# xdiff_string_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_string_rabdiff — Make a binary diff of two strings using the Rabin's polynomial fingerprinting algorithm

### Beschreibung

function xdiff_string_rabdiff(string `$old_data`, string `$new_data`): string|false

Makes a binary diff of two strings using the Rabin's polynomial fingerprinting algorithm implemented by » libxdiff. Compared to xdiff_string_bdiff(), this algorithm generally produces smaller diffs and operates faster, while remaining fully compatible with xdiff_string_bpatch() and xdiff_file_bpatch() for applying patches.

This function can be used with both text and binary data. The resulting diff data can later be applied to recreate the new version from the old one.

For further information about the algorithm, see the » libxdiff documentation.

### Parameter-Liste

`old_data`

  The first string containing the "old" binary data.

`new_data`

  The second string containing the "new" binary data.

### Rückgabewerte

Returns a binary diff string containing the differences between the old and new data,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Creation of a binary diff between two strings

    <?php
    $old = file_get_contents('file_v1.txt');
    $new = file_get_contents('file_v2.txt');

    $diff = xdiff_string_rabdiff($old, $new);
    file_put_contents('patch.rdiff', $diff);
    ?>

### Siehe auch

- xdiff_string_bdiff() - Make binary diff of two strings
- xdiff_string_bpatch() - Patch a string with a binary diff
- xdiff_file_bpatch() - Patch a file with a binary diff

## Inhaltsverzeichnis

- xdiff_file_bdiff — Make binary diff of two files
- xdiff_file_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_file_bpatch — Patch a file with a binary diff
- xdiff_file_diff — Make unified diff of two files
- xdiff_file_diff_binary — Alias von xdiff_file_bdiff
- xdiff_file_merge3 — Merge 3 files into one
- xdiff_file_patch — Patch a file with an unified diff
- xdiff_file_patch_binary — Alias von xdiff_file_bpatch
- xdiff_file_rabdiff — Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
- xdiff_string_bdiff — Make binary diff of two strings
- xdiff_string_bdiff_size — Read a size of file created by applying a binary diff
- xdiff_string_bpatch — Patch a string with a binary diff
- xdiff_string_diff — Make unified diff of two strings
- xdiff_string_diff_binary — Alias von xdiff_string_bdiff
- xdiff_string_merge3 — Merge 3 strings into one
- xdiff_string_patch — Patch a string with an unified diff
- xdiff_string_patch_binary — Alias von xdiff_string_bpatch
- xdiff_string_rabdiff — Make a binary diff of two strings using the Rabin's polynomial fingerprinting algorithm

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Vordefinierte Konstanten
- xdiff Funktionen
  - xdiff_file_bdiff — Make binary diff of two files
  - xdiff_file_bdiff_size — Read a size of file created by applying a binary diff
  - xdiff_file_bpatch — Patch a file with a binary diff
  - xdiff_file_diff — Make unified diff of two files
  - xdiff_file_diff_binary — Alias von xdiff_file_bdiff
  - xdiff_file_merge3 — Merge 3 files into one
  - xdiff_file_patch — Patch a file with an unified diff
  - xdiff_file_patch_binary — Alias von xdiff_file_bpatch
  - xdiff_file_rabdiff — Make binary diff of two files using the Rabin's polynomial fingerprinting algorithm
  - xdiff_string_bdiff — Make binary diff of two strings
  - xdiff_string_bdiff_size — Read a size of file created by applying a binary diff
  - xdiff_string_bpatch — Patch a string with a binary diff
  - xdiff_string_diff — Make unified diff of two strings
  - xdiff_string_diff_binary — Alias von xdiff_string_bdiff
  - xdiff_string_merge3 — Merge 3 strings into one
  - xdiff_string_patch — Patch a string with an unified diff
  - xdiff_string_patch_binary — Alias von xdiff_string_bpatch
  - xdiff_string_rabdiff — Make a binary diff of two strings using the Rabin's polynomial fingerprinting algorithm

- Direct-IO
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Direct-IO-Funktionen
- Verzeichnis-Funktionen
  - Vordefinierte Konstanten
  - Directory — Die Klasse Directory
  - Verzeichnis-Funktionen
- Fileinfo — Dateiinformation
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Fileinfo Funktionen
  - finfo — The finfo class
- Dateisystem
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Dateisystem — Dateisystem-Funktionen
- Inotify
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Inotify Funktionen
- xattr
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - xattr Funktionen
- xdiff
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - xdiff Funktionen

# Unterstützung menschlicher Sprache und Zeichenkodierung

# Enchant spelling library

# Einführung

Enchant is the PHP binding for the » Enchant library. Enchant steps in to provide uniformity and conformity on top of all spelling libraries, and implement certain features that may be lacking in any individual provider library. Everything should "just work" for any and every definition of "just working."

Enchant supports the following backends:

- `Aspell/Pspell (intends to replace Ispell)`
- `Ispell (old as sin, could be interpreted as a defacto standard)`
- `MySpell/Hunspell (an OOo projects, also used by Mozilla)`
- `Uspell (primarily Yiddish, Hebrew, and Eastern European languages - hosted in AbiWord's CVS under the module "uspell")`
- `Hspell (Hebrew)`
- `AppleSpell (Mac OSX)`

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Ressource-Typen

## Anforderungen

This version uses the functions of the » Enchant library by Dom Lachowicz. You need Enchant 1.2.4 or later. Enchant 2.0.0 or later is only supported as of PHP 8.0.0.

Enchant also requires » Glib 2.6 or greater. Pre-compiled Windows libraries are available from » http://ftp.gnome.org/pub/gnome/binaries/win32/glib/.

## Installation

Provided the required libraries are installed, users may enable enchant by adding the --with-enchant[=dir] option when compiling PHP.

Windows users must enable php_enchant.dll in order to use this extension.

> Hinweis: Additional setup on Windows
> Diese Erweiterung benötigt DLL-Dateien. die für Windows verfügbar seien müssen. Der FAQ-Eintrag " Wie füge ich unter Windows PATH mein PHP-Verzeichnis hinzu?" gibt hierzu weitere Informationen. Obwohl ein einfaches Kopieren der DLL-Dateien vom PHP-Verzeichnis in den Windows-Systemordner auch funktioniert (weil der Systemordner immer im PATH enthalten ist), ist dieses Vorgehen nicht empfehlenswert. Diese Erweiterung benötigt die folgenden Dateien im PATH: libenchant.dll, glib-2.dll, gmodule-2.dll. Furthermore, it is necessary to copy at least one of the shipped providers in lib\enchant to \usr\local\lib\enchant-2 (which is an absolute path from the root of the current drive). Prior to PHP 8.0.0, i.e. using Enchant v1, the providers had to be copied to C:\enchant_plugins instead, where this path could be customized by creating the registry value `HKEY_CURRENT_USER\SOFTWARE\Enchant\Config\Module_Dir` and setting it to the desired path.

## Ressource-Typen

Prior to PHP 8.0.0, there are two types of resources in this extension. The first one is the broker (backends manager) and the second is for the dictionary.

# Vordefinierte Konstanten

`LIBENCHANT_VERSION` (string)
  The version of libenchant. Available as of PHP 8.0.0.
`ENCHANT_MYSPELL` (int)
  Dictionary type for MySpell. Used with enchant_broker_get_dict_path() and enchant_broker_set_dict_path(). Deprecated as of PHP 8.0.0.
`ENCHANT_ISPELL` (int)
  Dictionary type for Ispell. Used with enchant_broker_get_dict_path() and enchant_broker_set_dict_path(). Deprecated as of PHP 8.0.0.

# Beispiele

Beispiel #1 Enchant Usage Example

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "Current broker provides the following backend(s):\n";
    print_r($bprovides);

    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);
        $dprovides = enchant_dict_describe($d);
        echo "dictionary $tag provides:\n";
        $wordcorrect = enchant_dict_check($d, "soong");
        print_r($dprovides);
        if (!$wordcorrect) {
            $suggs = enchant_dict_suggest($d, "soong");
            echo "Suggestions for 'soong':";
            print_r($suggs);
        }
        enchant_broker_free_dict($d);
    } else {
    }
    enchant_broker_free($r);
    ?>

# Enchant Funktionen

# enchant_broker_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0)

enchant_broker_describe — Enumerates the Enchant providers

### Beschreibung

function enchant_broker_describe(EnchantBroker `$broker`): array

Enumerates the Enchant providers and tells you some rudimentary information about them. The same info is provided through phpinfo().

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

### Rückgabewerte

Returns an Array of available Enchant providers with their details.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | Prior to this version, the function returned `false` on failure.

### Beispiele

Beispiel #1 List the backends provided by the given broker

    <?php
    $r = enchant_broker_init();
    $bprovides = enchant_broker_describe($r);
    echo "Current broker provides the following backend(s):\n";
    print_r($bprovides);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Current broker provides the following backend(s):
    Array
    (
        [0] => Array
            (
                [name] => aspell
                [desc] => Aspell Provider
                [file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [name] => hspell
                [desc] => Hspell Provider
                [file] => /usr/lib/enchant/libenchant_hspell.so
            )

        [2] => Array
            (
                [name] => ispell
                [desc] => Ispell Provider
                [file] => /usr/lib/enchant/libenchant_ispell.so
            )

        [3] => Array
            (
                [name] => myspell
                [desc] => Myspell Provider
                [file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

# enchant_broker_dict_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_dict_exists — Whether a dictionary exists or not

### Beschreibung

function enchant_broker_dict_exists(EnchantBroker `$broker`, string `$tag`): bool

Tells if a dictionary exists or not, using a non-empty tags

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

`tag`
  non-empty tag in the LOCALE format, ex: us_US, ch_DE, etc.

### Rückgabewerte

Returns `true` when the tag exist or `false` when not.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 A enchant_broker_dict_exists() example

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r,$tag)) {
        echo $tag . " dictionary found.\n";
    }
    ?>

### Siehe auch

- enchant_broker_describe() - Enumerates the Enchant providers

# enchant_broker_free

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free — Free the broker resource and its dictionaries

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function enchant_broker_free(EnchantBroker `$broker`): bool

Free a broker with all its dictionaries. As of PHP 8.0.0, it is recommended to unset the object instead of calling this function.

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | This function has been deprecated in favor of unsetting the object.
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.

### Siehe auch

- enchant_broker_init() - Create a new broker object

# enchant_broker_free_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free_dict — Free a dictionary resource

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function enchant_broker_free_dict(EnchantDictionary `$dictionary`): bool

Free a dictionary. As of PHP 8.0.0, it is recommended to unset the object instead of calling this function.

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | This function has been deprecated in favor of unsetting the object.
8.0.0 | `dictionary` expects a EnchantDictionary now; previously, a Ressource was expected.

### Siehe auch

- enchant_broker_request_dict() - Create a new dictionary using a tag
- enchant_broker_request_pwl_dict() - Creates a dictionary using a PWL file

# enchant_broker_get_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_get_dict_path — Get the directory path for a given backend

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function enchant_broker_get_dict_path(EnchantBroker `$broker`, int `$type`): string|false

Get the directory path for a given backend.

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

`type`
  The type of the dictionaries, i.e. `ENCHANT_MYSPELL` or `ENCHANT_ISPELL`.

### Rückgabewerte

Returns the path of the dictionary directory on successBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | This function has been deprecated.
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.

### Anmerkungen

> Hinweis: This function is only available if the extension has been compiled with Enchant v1.

### Siehe auch

- enchant_broker_set_dict_path() - Set the directory path for a given backend

# enchant_broker_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_get_error — Returns the last error of the broker

### Beschreibung

function enchant_broker_get_error(EnchantBroker `$broker`): string|false

Returns the last error which occurred in this broker.

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

### Rückgabewerte

Return the msg string if an error was found or `false`

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.

# enchant_broker_init

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_init — Create a new broker object

### Beschreibung

function enchant_broker_init(): EnchantBroker|false

### Parameter-Liste

### Rückgabewerte

Returns a broker resource on success or `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns an EnchantBroker instance now; previously, a Ressource was returned.

### Siehe auch

- enchant_broker_free() - Free the broker resource and its dictionaries

# enchant_broker_list_dicts

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_list_dicts — Returns a list of available dictionaries

### Beschreibung

function enchant_broker_list_dicts(EnchantBroker `$broker`): array

Returns a list of available dictionaries with their details.

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

### Rückgabewerte

Returns an Array of available dictionaries with their details.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | Prior to this version, the function returned `false` on failure.

### Beispiele

Beispiel #1 List all available dictionaries for one broker

    <?php
    $r = enchant_broker_init();
    $dicts = enchant_broker_list_dicts($r);
    print_r($dicts);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => Array
            (
                [lang_tag] => de
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [1] => Array
            (
                [lang_tag] => de_DE
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [3] => Array
            (
                [lang_tag] => en
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [4] => Array
            (
                [lang_tag] => en_GB
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [5] => Array
            (
                [lang_tag] => en_US
                [provider_name] => aspell
                [provider_desc] => Aspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_aspell.so
            )

        [6] => Array
            (
                [lang_tag] => hi_IN
                [provider_name] => myspell
                [provider_desc] => Myspell Provider
                [provider_file] => /usr/lib/enchant/libenchant_myspell.so
            )

    )

### Siehe auch

- enchant_broker_describe() - Enumerates the Enchant providers

# enchant_broker_request_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_dict — Create a new dictionary using a tag

### Beschreibung

function enchant_broker_request_dict(EnchantBroker `$broker`, string `$tag`): EnchantDictionary|false

create a new dictionary using tag, the non-empty language tag you wish to request a dictionary for ("en_US", "de_DE", ...)

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

`tag`
  A tag describing the locale, for example en_US, de_DE

### Rückgabewerte

Returns a dictionary resource on successBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | On success, this function returns an EnchantDictionary instance now; previously, a Ressource was returned.

### Beispiele

Beispiel #1 A enchant_broker_request_dict() example

Check if a dictionary exists using enchant_broker_dict_exists() and request it.

    <?php
    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker,$tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        var_dump($dict);
    }
    ?>

### Siehe auch

- enchant_dict_describe() - Describes an individual dictionary
- enchant_broker_dict_exists() - Whether a dictionary exists or not
- enchant_broker_free_dict() - Free a dictionary resource

# enchant_broker_request_pwl_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_pwl_dict — Creates a dictionary using a PWL file

### Beschreibung

function enchant_broker_request_pwl_dict(EnchantBroker `$broker`, string `$filename`): EnchantDictionary|false

Creates a dictionary using a PWL file. A PWL file is a personal word file with one word per line.

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

`filename`
  Path to the PWL file. If there is no such file, a new one will be created if possible.

### Rückgabewerte

Returns a dictionary resource on successBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | On success, this function returns an EnchantDictionary instance now; previously, a Ressource was returned.

### Siehe auch

- enchant_dict_describe() - Describes an individual dictionary
- enchant_broker_dict_exists() - Whether a dictionary exists or not
- enchant_broker_free_dict() - Free a dictionary resource

# enchant_broker_set_dict_path

(PHP 5 >= 5.3.1, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_set_dict_path — Set the directory path for a given backend

Warnung

Diese Funktion ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function enchant_broker_set_dict_path(EnchantBroker `$broker`, int `$type`, string `$path`): bool

Set the directory path for a given backend.

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

`type`
  The type of the dictionaries, i.e. `ENCHANT_MYSPELL` or `ENCHANT_ISPELL`.
`path`
  The path of the dictionary directory.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | This function has been deprecated.
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.

### Anmerkungen

> Hinweis: This function is only available if the extension has been compiled with Enchant v1.

### Siehe auch

- enchant_broker_get_dict_path() - Get the directory path for a given backend

# enchant_broker_set_ordering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_set_ordering — Declares a preference of dictionaries to use for the language

### Beschreibung

function enchant_broker_set_ordering(EnchantBroker `$broker`, string `$tag`, string `$ordering`): bool

Declares a preference of dictionaries to use for the language described/referred to by 'tag'. The ordering is a comma delimited list of provider names. As a special exception, the "*" tag can be used as a language tag to declare a default ordering for any language that does not explicitly declare an ordering.

### Parameter-Liste

`broker`

  Ein Enchant-Broker, der von enchant_broker_init() zurückgegeben wird.

`tag`
  Language tag. The special "*" tag can be used as a language tag to declare a default ordering for any language that does not explicitly declare an ordering.
`ordering`
  Comma delimited list of provider names

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `broker` erwartet nun eine EnchantBroker-Instanz; vorher wurde eine Ressource erwartet.

# enchant_dict_add

(PHP 8)

enchant_dict_add — Add a word to personal word list

### Beschreibung

function enchant_dict_add(EnchantDictionary `$dictionary`, string `$word`): void

Add a word to personal word list of the given dictionary.

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

`word`
  The word to add

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `dictionary` erwartet nun eine EnchantDictionary-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Adding a word to a PWL

    <?php

    $filename = './my_word_list.pwl';
    $word = 'Supercalifragilisticexpialidocious';

    $broker = enchant_broker_init();
    $dict = enchant_broker_request_pwl_dict($broker, $filename);

    enchant_dict_add($dict, $word);

    ?>

### Siehe auch

- enchant_broker_request_pwl_dict() - Creates a dictionary using a PWL file
- enchant_broker_request_dict() - Create a new dictionary using a tag

# enchant_dict_add_to_personal

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_personal — Alias von enchant_dict_add()

Warnung

Dieser Alias ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert.

### Beschreibung

Diese Funktion ist ein Alias für: enchant_dict_add().

# enchant_dict_add_to_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_session — Add 'word' to this spell-checking session

### Beschreibung

function enchant_dict_add_to_session(EnchantDictionary `$dictionary`, string `$word`): void

Add a word to the given dictionary. It will be added only for the active spell-checking session.

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

`word`
  The word to add

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `dictionary` erwartet nun eine EnchantDictionary-Instanz; vorher wurde eine Ressource erwartet.

### Siehe auch

- enchant_broker_request_dict() - Create a new dictionary using a tag

# enchant_dict_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_check — Check whether a word is correctly spelled or not

### Beschreibung

function enchant_dict_check(EnchantDictionary `$dictionary`, string `$word`): bool

If the word is correctly spelled return `true`, otherwise return `false`

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

`word`
  The word to check

### Rückgabewerte

Returns `true` if the word is spelled correctly, `false` if not.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `dictionary` erwartet nun eine EnchantDictionary-Instanz; vorher wurde eine Ressource erwartet.

# enchant_dict_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_describe — Describes an individual dictionary

### Beschreibung

function enchant_dict_describe(EnchantDictionary `$dictionary`): array

Returns the details of the dictionary.

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `dictionary` erwartet nun eine EnchantDictionary-Instanz; vorher wurde eine Ressource erwartet.
8.0.0 | Prior to this version, the function returned `false` on failure.

### Beispiele

Beispiel #1 A enchant_dict_describe() example

Check if a dictionary exists using enchant_broker_dict_exists() and show the detail of it.

    <?php
    $tag = 'en_US';
    $broker = enchant_broker_init();
    if (enchant_broker_dict_exists($broker, $tag)) {
        $dict = enchant_broker_request_dict($broker, $tag);
        $dict_details = enchant_dict_describe($dict);
        print_r($dict_details);
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [lang] => en_US
        [name] => aspell
        [desc] => Aspell Provider
        [file] => /usr/lib/enchant/libenchant_aspell.so
    )

# enchant_dict_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_get_error — Returns the last error of the current spelling-session

### Beschreibung

function enchant_dict_get_error(EnchantDictionary `$dictionary`): string|false

Returns the last error of the current spelling-session

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

### Rückgabewerte

Returns the error message as string or `false` if no error occurred.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `dictionary` erwartet nun eine EnchantDictionary-Instanz; vorher wurde eine Ressource erwartet.

# enchant_dict_is_added

(PHP 8)

enchant_dict_is_added — Whether or not 'word' exists in this spelling-session

### Beschreibung

function enchant_dict_is_added(EnchantDictionary `$dictionary`, string `$word`): bool

Tells whether or not a word already exists in the current session.

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

`word`
  The word to lookup

### Rückgabewerte

Returns `true` if the word exists or `false`

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `dictionary` erwartet nun eine EnchantDictionary-Instanz; vorher wurde eine Ressource erwartet.

### Siehe auch

- enchant_dict_add_to_session() - Add 'word' to this spell-checking session

# enchant_dict_is_in_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_is_in_session — Alias von enchant_dict_is_added()

Warnung

Dieser Alias ist seit PHP 8.0.0 als DEPRECATED (veraltet) markiert.

### Beschreibung

Diese Funktion ist ein Alias für: enchant_dict_is_added().

# enchant_dict_quick_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant:0.2.0-1.0.1)

enchant_dict_quick_check — Check the word is correctly spelled and provide suggestions

### Beschreibung

function enchant_dict_quick_check(EnchantDictionary `$dictionary`, string `$word`, array `&$suggestions` = `null`): bool

If the word is correctly spelled return `true`, otherwise return `false`, if suggestions variable is provided, fill it with spelling alternatives.

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

`word`
  The word to check
`suggestions`
  If the word is not correctly spelled, this variable will contain an array of suggestions.

### Rückgabewerte

Returns `true` if the word is correctly spelled or `false`

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `dictionary` erwartet nun eine EnchantDictionary-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 A enchant_dict_quick_check() example

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();

    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);
        enchant_dict_quick_check($d, 'soong', $suggs);
        print_r($suggs);
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => song
        [1] => snog
        [2] => soon
        [3] => Sang
        [4] => Sung
        [5] => sang
        [6] => sung
        [7] => sponge
        [8] => spongy
        [9] => snag
        [10] => snug
        [11] => sonic
        [12] => sing
        [13] => songs
        [14] => Son
        [15] => Sonja
        [16] => Synge
        [17] => son
        [18] => Sejong
        [19] => sarong
        [20] => sooner
        [21] => Sony
        [22] => sown
        [23] => scone
        [24] => song's
    )

### Siehe auch

- enchant_dict_check() - Check whether a word is correctly spelled or not
- enchant_dict_suggest() - Schlägt Schreibweisen für ein Wort vor

# enchant_dict_store_replacement

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_store_replacement — Add a correction for a word

### Beschreibung

function enchant_dict_store_replacement(EnchantDictionary `$dictionary`, string `$misspelled`, string `$correct`): void

Add a correction for 'mis' using 'cor'. Notes that you replaced @mis with @cor, so it's possibly more likely that future occurrences of @mis will be replaced with @cor. So it might bump @cor up in the suggestion list.

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

`misspelled`
  The word to fix
`correct`
  The correct word

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `dictionary` erwartet nun eine EnchantDictionary-Instanz; vorher wurde eine Ressource erwartet.

# enchant_dict_suggest

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_suggest — Schlägt Schreibweisen für ein Wort vor

### Beschreibung

function enchant_dict_suggest(EnchantDictionary `$dictionary`, string `$word`): array

### Parameter-Liste

`dictionary`

  Ein Enchant-Wörterbuch, das von enchant_broker_request_dict() oder enchant_broker_request_pwl_dict() zurückgegeben wird.

`word`
  Das Wort, das für die Vorschläge verwendet werden soll.

### Rückgabewerte

Gibt ein Array mit Vorschlägen zurück, wenn das Wort falsch geschrieben ist.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Der Parameter `dictionary` erwartet nun eine EnchantDictionary-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Ein Beispiel für enchant_dict_suggest()

    <?php
    $tag = 'en_US';
    $r = enchant_broker_init();
    if (enchant_broker_dict_exists($r,$tag)) {
        $d = enchant_broker_request_dict($r, $tag);

        $wordcorrect = enchant_dict_check($d, "soong");
        if (!$wordcorrect) {
            $suggs = enchant_dict_suggest($d, "soong");
            echo "Suggestions for 'soong':";
            print_r($suggs);
        }
    }
    ?>

### Siehe auch

- enchant_dict_check() - Check whether a word is correctly spelled or not
- enchant_dict_quick_check() - Check the word is correctly spelled and provide suggestions

## Inhaltsverzeichnis

- enchant_broker_describe — Enumerates the Enchant providers
- enchant_broker_dict_exists — Whether a dictionary exists or not
- enchant_broker_free — Free the broker resource and its dictionaries
- enchant_broker_free_dict — Free a dictionary resource
- enchant_broker_get_dict_path — Get the directory path for a given backend
- enchant_broker_get_error — Returns the last error of the broker
- enchant_broker_init — Create a new broker object
- enchant_broker_list_dicts — Returns a list of available dictionaries
- enchant_broker_request_dict — Create a new dictionary using a tag
- enchant_broker_request_pwl_dict — Creates a dictionary using a PWL file
- enchant_broker_set_dict_path — Set the directory path for a given backend
- enchant_broker_set_ordering — Declares a preference of dictionaries to use for the language
- enchant_dict_add — Add a word to personal word list
- enchant_dict_add_to_personal — Alias von enchant_dict_add
- enchant_dict_add_to_session — Add 'word' to this spell-checking session
- enchant_dict_check — Check whether a word is correctly spelled or not
- enchant_dict_describe — Describes an individual dictionary
- enchant_dict_get_error — Returns the last error of the current spelling-session
- enchant_dict_is_added — Whether or not 'word' exists in this spelling-session
- enchant_dict_is_in_session — Alias von enchant_dict_is_added
- enchant_dict_quick_check — Check the word is correctly spelled and provide suggestions
- enchant_dict_store_replacement — Add a correction for a word
- enchant_dict_suggest — Schlägt Schreibweisen für ein Wort vor

# The EnchantBroker class

(PHP 8)

## Einführung

A fully opaque class which replaces `enchant_broker` resources as of PHP 8.0.0.

## Klassenbeschreibung

final class EnchantBroker {
}

# The EnchantDictionary class

(PHP 8)

## Einführung

A fully opaque class which replaces `enchant_dict` resources as of PHP 8.0.0.

## Klassenbeschreibung

final class EnchantDictionary {
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- Beispiele
- Enchant Funktionen
  - enchant_broker_describe — Enumerates the Enchant providers
  - enchant_broker_dict_exists — Whether a dictionary exists or not
  - enchant_broker_free — Free the broker resource and its dictionaries
  - enchant_broker_free_dict — Free a dictionary resource
  - enchant_broker_get_dict_path — Get the directory path for a given backend
  - enchant_broker_get_error — Returns the last error of the broker
  - enchant_broker_init — Create a new broker object
  - enchant_broker_list_dicts — Returns a list of available dictionaries
  - enchant_broker_request_dict — Create a new dictionary using a tag
  - enchant_broker_request_pwl_dict — Creates a dictionary using a PWL file
  - enchant_broker_set_dict_path — Set the directory path for a given backend
  - enchant_broker_set_ordering — Declares a preference of dictionaries to use for the language
  - enchant_dict_add — Add a word to personal word list
  - enchant_dict_add_to_personal — Alias von enchant_dict_add
  - enchant_dict_add_to_session — Add 'word' to this spell-checking session
  - enchant_dict_check — Check whether a word is correctly spelled or not
  - enchant_dict_describe — Describes an individual dictionary
  - enchant_dict_get_error — Returns the last error of the current spelling-session
  - enchant_dict_is_added — Whether or not 'word' exists in this spelling-session
  - enchant_dict_is_in_session — Alias von enchant_dict_is_added
  - enchant_dict_quick_check — Check the word is correctly spelled and provide suggestions
  - enchant_dict_store_replacement — Add a correction for a word
  - enchant_dict_suggest — Schlägt Schreibweisen für ein Wort vor
- EnchantBroker — The EnchantBroker class
- EnchantDictionary — The EnchantDictionary class

# Geschlecht aus Vornamen ermitteln

# Einführung

Die Gender PHP Erweiterung ist ein Port des gender.c Programms entwickelt von Joerg Michael. Der Zweck ist die Ermittlung des Geschlechts anhand des Vornamens. Die aktuelle Datenbank beinhaltet >40000 Vornamen aus 54 Ländern.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/gender.

# Beispiele

## Inhaltsverzeichnis

- Beispiel.

## Beispiel.

Gender Nutzungsbeispiel.

Beispiel #1 Beispiel.

    <?php

    namespace Gender;

    $gender = new Gender;

    $name = "Milene";
    $country = Gender::GERMANY;

    $result = $gender->get($name, $country);

    $data = $gender->country($country);

    switch($result) {
        case Gender::IS_FEMALE:
            printf("Der Name %s ist in %s weiblich\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_FEMALE:
            printf("Der Name %s ist in %s meistens weiblich\n", $name, $data['country']);
        break;

        case Gender::IS_MALE:
            printf("Der Name %s ist in %s männlich\n", $name, $data['country']);
        break;

        case Gender::IS_MOSTLY_MALE:
            printf("Der Name %s ist in %s meistens männlich\n", $name, $data['country']);
        break;

        case Gender::IS_UNISEX_NAME:
            printf("Der Name %s ist in %s geschlechtsneutral\n", $name, $data['country']);
        break;

        case Gender::IS_A_COUPLE:
            printf("Der Name %s ist in %s männlich und weiblich\n", $name, $data['country']);
        break;

        case Gender::NAME_NOT_FOUND:
            printf("Der Name %s wurde in %s nicht gefunden\n", $name, $data['country']);
        break;

        case Gender::ERROR_IN_NAME:
            echo "Der Name ist ungültig!\n";
        break;

        default:
            echo "Es ist ein Fehler aufgetreten!\n";
        break;

    }

# The Gender\Gender class

(PECL gender >= 0.6.0)

## Einführung

## Klassenbeschreibung

class Gender\Gender {
/* Konstanten */
const int IS_FEMALE = 70;
const int IS_MOSTLY_FEMALE = 102;
const int IS_MALE = 77;
const int IS_MOSTLY_MALE = 109;
const int IS_UNISEX_NAME = 63;
const int IS_A_COUPLE = 67;
const int NAME_NOT_FOUND = 32;
const int ERROR_IN_NAME = 69;
const int ANY_COUNTRY = 0;
const int BRITAIN = 1;
const int IRELAND = 2;
const int USA = 3;
const int SPAIN = 4;
const int PORTUGAL = 5;
const int ITALY = 6;
const int MALTA = 7;
const int FRANCE = 8;
const int BELGIUM = 9;
const int LUXEMBOURG = 10;
const int NETHERLANDS = 11;
const int GERMANY = 12;
const int EAST_FRISIA = 13;
const int AUSTRIA = 14;
const int SWISS = 15;
const int ICELAND = 16;
const int DENMARK = 17;
const int NORWAY = 18;
const int SWEDEN = 19;
const int FINLAND = 20;
const int ESTONIA = 21;
const int LATVIA = 22;
const int LITHUANIA = 23;
const int POLAND = 24;
const int CZECH_REP = 25;
const int SLOVAKIA = 26;
const int HUNGARY = 27;
const int ROMANIA = 28;
const int BULGARIA = 29;
const int BOSNIA = 30;
const int CROATIA = 31;
const int KOSOVO = 32;
const int MACEDONIA = 33;
const int MONTENEGRO = 34;
const int SERBIA = 35;
const int SLOVENIA = 36;
const int ALBANIA = 37;
const int GREECE = 38;
const int RUSSIA = 39;
const int BELARUS = 40;
const int MOLDOVA = 41;
const int UKRAINE = 42;
const int ARMENIA = 43;
const int AZERBAIJAN = 44;
const int GEORGIA = 45;
const int KAZAKH_UZBEK = 46;
const int TURKEY = 47;
const int ARABIA = 48;
const int ISRAEL = 49;
const int CHINA = 50;
const int INDIA = 51;
const int JAPAN = 52;
const int KOREA = 53;
/* Methoden */
public function __construct(string `$dsn` = ?)
public function connect(string `$dsn`): bool
public function country(int `$country`): array|false
public function get(string `$name`, int `$country` = ?): int
public function isNick(string `$name0`, string `$name1`, int `$country` = ?): array
public function similarNames(string `$name`, int `$country` = ?): array
}

## Vordefinierte Konstanten

`Gender\Gender::IS_FEMALE`
`Gender\Gender::IS_MOSTLY_FEMALE`
`Gender\Gender::IS_MALE`
`Gender\Gender::IS_MOSTLY_MALE`
`Gender\Gender::IS_UNISEX_NAME`
`Gender\Gender::IS_A_COUPLE`
`Gender\Gender::NAME_NOT_FOUND`
`Gender\Gender::ERROR_IN_NAME`
`Gender\Gender::ANY_COUNTRY`
`Gender\Gender::BRITAIN`
`Gender\Gender::IRELAND`
`Gender\Gender::USA`
`Gender\Gender::SPAIN`
`Gender\Gender::PORTUGAL`
`Gender\Gender::ITALY`
`Gender\Gender::MALTA`
`Gender\Gender::FRANCE`
`Gender\Gender::BELGIUM`
`Gender\Gender::LUXEMBOURG`
`Gender\Gender::NETHERLANDS`
`Gender\Gender::GERMANY`
`Gender\Gender::EAST_FRISIA`
`Gender\Gender::AUSTRIA`
`Gender\Gender::SWISS`
`Gender\Gender::ICELAND`
`Gender\Gender::DENMARK`
`Gender\Gender::NORWAY`
`Gender\Gender::SWEDEN`
`Gender\Gender::FINLAND`
`Gender\Gender::ESTONIA`
`Gender\Gender::LATVIA`
`Gender\Gender::LITHUANIA`
`Gender\Gender::POLAND`
`Gender\Gender::CZECH_REP`
`Gender\Gender::SLOVAKIA`
`Gender\Gender::HUNGARY`
`Gender\Gender::ROMANIA`
`Gender\Gender::BULGARIA`
`Gender\Gender::BOSNIA`
`Gender\Gender::CROATIA`
`Gender\Gender::KOSOVO`
`Gender\Gender::MACEDONIA`
`Gender\Gender::MONTENEGRO`
`Gender\Gender::SERBIA`
`Gender\Gender::SLOVENIA`
`Gender\Gender::ALBANIA`
`Gender\Gender::GREECE`
`Gender\Gender::RUSSIA`
`Gender\Gender::BELARUS`
`Gender\Gender::MOLDOVA`
`Gender\Gender::UKRAINE`
`Gender\Gender::ARMENIA`
`Gender\Gender::AZERBAIJAN`
`Gender\Gender::GEORGIA`
`Gender\Gender::KAZAKH_UZBEK`
`Gender\Gender::TURKEY`
`Gender\Gender::ARABIA`
`Gender\Gender::ISRAEL`
`Gender\Gender::CHINA`
`Gender\Gender::INDIA`
`Gender\Gender::JAPAN`
`Gender\Gender::KOREA`

# Gender\Gender::connect

(PECL gender >= 0.6.0)

Gender\Gender::connect — Connect to an external name dictionary

### Beschreibung

public function Gender\Gender::connect(string `$dsn`): bool

Connect to an external name dictionary. Currently only streams are supported.

### Parameter-Liste

`dsn`
  DSN to open.

### Rückgabewerte

Boolean as success of failure.

# Gender\Gender::__construct

(PECL gender >= 0.6.0)

Gender\Gender::__construct — Construct the Gender object

### Beschreibung

public function Gender\Gender::__construct(string `$dsn` = ?)

Create a Gender object optionally connecting to an external name dictionary. When no external database was given, compiled in data will be used.

### Parameter-Liste

`dsn`
  DSN to open.

# Gender\Gender::country

(PECL gender >= 0.8.0)

Gender\Gender::country — Get textual country representation

### Beschreibung

public function Gender\Gender::country(int `$country`): array|false

Returns the textual representation of a country from a Gender class constant.

### Parameter-Liste

`country`
  A country ID specified by a Gender\Gender class constant.

### Rückgabewerte

Returns an array with the short and full names of the country on success Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Using Gender\Gender::country()

    $gender = new Gender\Gender;
    var_dump($gender->country(Gender\Gender::BRITAIN));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      'country_short' =>
      string(2) "UK"
      'country' =>
      string(13) "Great Britain"
    }

# Gender\Gender::get

(PECL gender >= 0.6.0)

Gender\Gender::get — Get gender of a name

### Beschreibung

public function Gender\Gender::get(string `$name`, int `$country` = ?): int

Get the gender of the name in a particular country.

### Parameter-Liste

`name`
  Name to check.
`country`
  Country id identified by Gender class constant.

### Rückgabewerte

Returns gender of the name.

# Gender\Gender::isNick

(PECL gender >= 0.9.0)

Gender\Gender::isNick — Check if the name0 is an alias of the name1

### Beschreibung

public function Gender\Gender::isNick(string `$name0`, string `$name1`, int `$country` = ?): array

Check whether the name0 is a nick of the name1.

### Parameter-Liste

`name0`
  Name to check.
`name1`
  Name to check.
`country`
  Country id identified by Gender class constant. If ommited ANY_COUNTRY is used.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# Gender\Gender::similarNames

(PECL gender >= 0.9.0)

Gender\Gender::similarNames — Get similar names

### Beschreibung

public function Gender\Gender::similarNames(string `$name`, int `$country` = ?): array

Get similar names for the given name and country.

### Parameter-Liste

`name`
  Name to check.
`country`
  Country id identified by Gender class constant. If ommited ANY_COUNTRY is used.

### Rückgabewerte

Returns an array with the similar names found.

## Inhaltsverzeichnis

- Gender\Gender::connect — Connect to an external name dictionary
- Gender\Gender::__construct — Construct the Gender object
- Gender\Gender::country — Get textual country representation
- Gender\Gender::get — Get gender of a name
- Gender\Gender::isNick — Check if the name0 is an alias of the name1
- Gender\Gender::similarNames — Get similar names

- Installation/Konfiguration
  - Installation
- Beispiele
  - Beispiel.
- Gender\Gender — The Gender\Gender class
  - Gender\Gender::connect — Connect to an external name dictionary
  - Gender\Gender::__construct — Construct the Gender object
  - Gender\Gender::country — Get textual country representation
  - Gender\Gender::get — Get gender of a name
  - Gender\Gender::isNick — Check if the name0 is an alias of the name1
  - Gender\Gender::similarNames — Get similar names

# Gettext

# Einführung

Die gettext-Funktionen implementieren ein NLS (Native Language Support) API, das dazu verwendet werden kann, Ihre PHP-Applikationen zu internationalisieren. Bitte lesen Sie die gettext-Dokumentation für Ihr System, um eine ausführliche Erläuterung dieser Funktionen zu erhalten, oder werfen Sie einen Blick in die Dokumentation auf » http://www.gnu.org/software/gettext/manual/gettext.html.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

Um diese Funktionen zu verwenden, müssen Sie das GNU gettext Paket von » http://www.gnu.org/software/gettext/gettext.html herunterladen und installieren.

## Installation

Um GNU gettext-Unterstützung in Ihrem PHP einzubinden, müssen Sie die Option --with-gettext[=DIR] Ihrer Build-Konfiguration hinzufügen. Dabei steht DIR für das gettext-Installationsverzeichnis, standardmäßig gesetzt auf /usr/local.

# Gettext-Funktionen

# _

(PHP 4, PHP 5, PHP 7, PHP 8)

_ — Alias von gettext()

### Beschreibung

Diese Funktion ist ein Alias für: gettext().

# bind_textdomain_codeset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

bind_textdomain_codeset — Setzt oder liefert den Zeichensatz der Meldungen, die aus der Übersetzungstabelle der DOMAIN zurückgegeben werden

### Beschreibung

function bind_textdomain_codeset(string `$domain`, ?string `$codeset` = `null`): string|false

Mit bind_textdomain_codeset() können Sie bestimmen oder ermitteln, in welchem Zeichensatz Meldungen von `domain` von gettext() oder verwandten Funktionen zurückgegeben werden.

### Parameter-Liste

`domain`

  Die Domain

`codeset`

  Das Codeset; falls `null`, wird die aktuell eingestellte Kodierung zurückgegeben.

### Rückgabewerte

Bei Erfolg ein String.

### Fehler/Exceptions

Wenn `domain` der leere String ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Wirft nun einen ValueError, wenn `domain` der leere String ist.
8.4.0 | `codeset` ist nun optional; zuvor musste der Parameter immer angegeben werden.
8.0.3 | `codeset` ist nun ein Nullable-Typ. Zuvor war es nicht möglich, die aktuell eingestellte Kodierung abzurufen.

### Anmerkungen

> Hinweis:

> Die bind_textdomain_codeset()-Informationen werden pro Prozess verwaltet, nicht pro Thread.

# bindtextdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

bindtextdomain — Setzt oder liefert den Pfad für eine Domain

### Beschreibung

function bindtextdomain(string `$domain`, ?string `$directory` = `null`): string|false

Die Funktion bindtextdomain() setzt den Pfad für eine Domain oder gibt diesen zurück.

### Parameter-Liste

`domain`

  Die Domain

`directory`

  Der Verzeichnispfad. Ein leerer String bedeutet das aktuelle Verzeichnis. Falls `null`, wird das aktuell eingestellte Verzeichnis zurückgegeben.

### Rückgabewerte

Der vollständige Pfadname, der gerade für `domain` gesetzt wird. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | `directory` ist nun optional; zuvor musste der Parameter immer angegeben werden.
8.0.3 | `directory` ist nun ein Nullable-Typ. Zuvor war es nicht möglich, das aktuell eingestellte Verzeichnis abzurufen.

### Beispiele

Beispiel #1 bindtextdomain()-Beispiel

    <?php

    $domain = 'MeineAnwendung';
    echo bindtextdomain($domain, '/usr/share/MeineAnwendung/locale');

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    /usr/share/MeineAnwendung/locale

### Anmerkungen

> Hinweis:

> Die bindtextdomain()-Informationen werden pro Prozess verwaltet, nicht pro Thread.

# dcgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dcgettext — Überschreibt die gesetzte Domain für eine einzelne Abfrage

### Beschreibung

function dcgettext(string `$domain`, string `$message`, int `$category`): string

Die Funktion erlaubt es Ihnen, die aktuell gesetzte Domain für eine einzelne Meldungssuche zu überschreiben.

### Parameter-Liste

`domain`

  Die Domain

`message`

  Die Meldung

`category`

  Die Kategorie

### Rückgabewerte

Bei Erfolg ein String.

### Siehe auch

- gettext() - Sucht eine Meldung in der aktuellen Domain

# dcngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dcngettext — Pluralversion von dcgettext

### Beschreibung

function dcngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`,
int `$category`
): string

Die Funktion erlaubt es Ihnen, die aktuell gesetzte Domain für eine einzelne Plural-Meldungssuche zu überschreiben.

### Parameter-Liste

`domain`

  Die Domain

`singular`

`plural`

`count`

`category`

### Rückgabewerte

Bei Erfolg ein String.

### Siehe auch

- ngettext() - Pluralversion von gettext

# dgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dgettext — Überschreibt die aktuelle Domain

### Beschreibung

function dgettext(string `$domain`, string `$message`): string

Die Funktion dgettext() erlaubt Ihnen, die aktuelle `domain` für eine einzelne Meldungssuche zu überschreiben.

### Parameter-Liste

`domain`

  Die Domain

`message`

  Die Meldung

### Rückgabewerte

Bei Erfolg ein String.

### Fehler/Exceptions

Wenn `domain` der leere String ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Wirft nun einen ValueError, wenn `domain` der leere String ist.

### Siehe auch

- gettext() - Sucht eine Meldung in der aktuellen Domain

# dngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dngettext — Pluralversion von dgettext

### Beschreibung

function dngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`
): string

Die Funktion dngettext() erlaubt Ihnen, die aktuelle `domain` für eine einzelne Plural-Meldungssuche zu überschreiben.

### Parameter-Liste

`domain`

  Die Domain

`singular`

`plural`

`count`

### Rückgabewerte

Bei Erfolg ein String.

### Fehler/Exceptions

Wenn `domain` der leere String ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Wirft nun einen ValueError, wenn `domain` der leere String ist.

### Siehe auch

- ngettext() - Pluralversion von gettext

# gettext

(PHP 4, PHP 5, PHP 7, PHP 8)

gettext — Sucht eine Meldung in der aktuellen Domain

### Beschreibung

function gettext(string `$message`): string

Sucht nach einer Meldung in der aktuellen Domain.

### Parameter-Liste

`message`

  Die zu übersetzende Meldung.

### Rückgabewerte

Diese Funktion gibt einen übersetzten String zurück, falls einer in der Übersetzungstabelle gefunden wird, andernfalls den übergebenen Originalstring.

### Beispiele

Beispiel #1 gettext()-Suche

    <?php
    // Sprache auf Deutsch setzen
    putenv('LC_ALL=de_DE');
    setlocale(LC_ALL, 'de_DE');

    // Angeben des Pfads der Übersetzungstabellen
    bindtextdomain("meinePHPApp", "./locale");

    // Domain auswählen
    textdomain("meinePHPApp");

    // Die Übersetzung wird nun in ./locale/de_DE/LC_MESSAGES/meinePHPApp.mo gesucht

    // Ausgeben des Test-Textes
    echo gettext("Willkommen in meiner PHP-Anwendung");

    // Oder verwenden Sie den Alias _() für gettext()
    echo _("Einen schönen Tag noch");
    ?>

### Anmerkungen

> Hinweis:

> Sie können einen Unterstrich '_' als Alias für diese Funktion verwenden.

> Hinweis:

> Das reine Setzen einer Sprachangabe reicht bei einigen Systemen nicht aus. Daher sollte putenv() verwendet werden, um die aktuelle locale zu definieren.

### Siehe auch

- _() - Alias von gettext
- setlocale() - Legt regionale (locale) Einstellungen fest

# ngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ngettext — Pluralversion von gettext

### Beschreibung

function ngettext(string `$singular`, string `$plural`, int `$count`): string

Die Pluralversion von gettext(). Einige Sprachen haben abhängig von der Anzahl mehr als eine Form für den Plural von Meldungen.

### Parameter-Liste

`singular`

  Die Meldungs-ID des Singular.

`plural`

  Die Meldungs-ID des Plural.

`count`

  Die Anzahl (z. B. die Warenanzahl), die die Übersetzung für den entsprechenden grammatischen Numerus bestimmt.

### Rückgabewerte

Gibt die korrekte Pluralform der Meldung zurück, die mittels `singular` und `plural` für die Anzahl `count` bestimmt wurde.

### Beispiele

Beispiel #1 ngettext()-Beispiel

    <?php

    setlocale(LC_ALL, 'cs_CZ');
    printf(ngettext("%d window", "%d windows", 1), 1); // 1 okno
    printf(ngettext("%d window", "%d windows", 2), 2); // 2 okna
    printf(ngettext("%d window", "%d windows", 5), 5); // 5 oken

    ?>

# textdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

textdomain — Setzt die Standarddomain

### Beschreibung

function textdomain(?string `$domain` = `null`): string

Diese Funktion setzt die Domain, in der bei einem gettext()-Aufruf gesucht werden soll; gewöhnlich wird die Domain nach einer Anwendung benannt.

### Parameter-Liste

`domain`

  Die neue Meldungs-Domain oder `null`, wenn die aktuellen Werte ohne Veränderung übernommen werden sollen.

### Rückgabewerte

Im Erfolgsfall gibt die Funktion die aktuelle Meldungs-Domain zurück, nachdem sie möglicherweise verändert wurde.

### Fehler/Exceptions

Wenn `domain` der leere String ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Wirft nun einen ValueError, wenn `domain` der leere String ist.
8.4.0 | `domain` ist nun optional; zuvor musste der Parameter immer angegeben werden.

### Anmerkungen

> Hinweis:

> Die textdomain()-Informationen werden pro Prozess verwaltet, nicht pro Thread.

## Inhaltsverzeichnis

- _ — Alias von gettext
- bind_textdomain_codeset — Setzt oder liefert den Zeichensatz der Meldungen, die aus der Übersetzungstabelle der DOMAIN zurückgegeben werden
- bindtextdomain — Setzt oder liefert den Pfad für eine Domain
- dcgettext — Überschreibt die gesetzte Domain für eine einzelne Abfrage
- dcngettext — Pluralversion von dcgettext
- dgettext — Überschreibt die aktuelle Domain
- dngettext — Pluralversion von dgettext
- gettext — Sucht eine Meldung in der aktuellen Domain
- ngettext — Pluralversion von gettext
- textdomain — Setzt die Standarddomain

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Gettext-Funktionen
  - _ — Alias von gettext
  - bind_textdomain_codeset — Setzt oder liefert den Zeichensatz der Meldungen, die aus der Übersetzungstabelle der DOMAIN zurückgegeben werden
  - bindtextdomain — Setzt oder liefert den Pfad für eine Domain
  - dcgettext — Überschreibt die gesetzte Domain für eine einzelne Abfrage
  - dcngettext — Pluralversion von dcgettext
  - dgettext — Überschreibt die aktuelle Domain
  - dngettext — Pluralversion von dgettext
  - gettext — Sucht eine Meldung in der aktuellen Domain
  - ngettext — Pluralversion von gettext
  - textdomain — Setzt die Standarddomain

# iconv

# Einführung

This module contains an interface to iconv character set conversion facility. With this module, you can turn a string represented by a local character set into the one represented by another character set, which may be the Unicode character set. Supported character sets depend on the iconv implementation of your system. Note that the iconv function on some systems may not work as you expect. In such case, it'd be a good idea to install the » GNU libiconv library. It will most likely end up with more consistent results.

This extension comes with various utility functions that help you to write multilingual scripts. Let's have a look at the following sections to explore the new features.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

You will need nothing if the system you are using is one of the recent POSIX-compliant systems because standard C libraries that are supplied in them must provide iconv facility. Otherwise, you have to get the » libiconv library installed in your system.

## Installation

This extension is enabled by default, although it may be disabled by compiling with --without-iconv.

The optional --with-iconv[=DIR] directive is used to specify the location of iconv on the system that PHP is being compiled on, otherwise only the default locations are scanned.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Iconv Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
iconv.input_encoding | "" | `INI_ALL` | Deprecated in PHP 5.6.0.
iconv.output_encoding | "" | `INI_ALL` | Deprecated in PHP 5.6.0.
iconv.internal_encoding | "" | `INI_ALL` | Deprecated in PHP 5.6.0.

Hier eine kurze Erklärung der Konfigurationsoptionen:

Warnung

Some systems (like IBM AIX) use "ISO8859-1" instead of "ISO-8859-1" so this value has to be used in configuration options and function parameters.

`iconv.input_encoding` string
  Warnung

  Diese Funktion ist seit PHP 5.6.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

  PHP 5.6 and later users should leave this empty and set input_encoding instead.

`iconv.output_encoding` string
  Warnung

  Diese Funktion ist seit PHP 5.6.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

  PHP 5.6 and later users should leave this empty and set output_encoding instead.

`iconv.internal_encoding` string
  Warnung

  Diese Funktion ist seit PHP 5.6.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieses Features wird dringend abgeraten.

  PHP 5.6 and later users should leave this empty and set `default_charset` instead.

# Vordefinierte Konstanten

It is possible to identify at runtime which `iconv` implementation is adopted by this extension.

`iconv` implementation constants
Name | Type | Description
--- | --- | ---
`ICONV_IMPL` (string) | string | The implementation name
`ICONV_VERSION` (string) | string | The implementation version

> Hinweis:

> Writing implementation-dependent scripts with these constants is strongly discouraged.

The following constants are also available:

Other `iconv` constants
Name | Type | Description
--- | --- | ---
`ICONV_MIME_DECODE_STRICT` (int) | int | A bitmask used for iconv_mime_decode()
`ICONV_MIME_DECODE_CONTINUE_ON_ERROR` (int) | int | A bitmask used for iconv_mime_decode()

# iconv Funktionen

# Siehe auch

See also GNU Recode functions.

# iconv

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv — Konvertiert eine Zeichenkette von einem Zeichensatz in einen anderen

### Beschreibung

function iconv(string `$from_encoding`, string `$to_encoding`, string `$string`): string|false

Diese Funktion konvertiert die Zeichenkette `string` vom Zeichensatz `from_encoding` in den Zeichensatz `to_encoding`.

### Parameter-Liste

`from_encoding`

  Die aktuelle Kodierung, die zur Interpretation von `string` verwendet wird.

`to_encoding`

  Die gewünschte Kodierung des Ergebnisses.

  Wenn die Zeichenkette `//TRANSLIT` an `to_encoding` angehängt wird, wird die Transliteration aktiviert. Das bedeutet, dass ein Zeichen, das im Zielzeichensatz nicht dargestellt werden kann, mit einem oder mehreren ähnlich aussehenden Zeichen annähernd dargestellt werden darf. Wenn die Zeichenkette `//IGNORE` angehängt wird, werden diese nicht darstellbaren Zeichen stillschweigend verworfen. Ansonsten wird eine `E_NOTICE` erzeugt und die Funktion gibt `false` zurück.

  Achtung

  Ob und wie `//TRANSLIT` genau funktioniert, hängt von der iconv()-Implementierung des Systems ab (vgl. `ICONV_IMPL`). Einige Implementierungen sind bekannt dafür, `//TRANSLIT` zu ignorieren, sodass die Umwandlung für Zeichen, die illegal für den Zeichensatz `to_encoding` sind, vermutlich fehlschlägt.

`string`

  Die zu konvertierende Zeichenkette.

### Rückgabewerte

Gibt die konvertierte Zeichenkette zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 iconv()-Beispiel:

    <?php
    $text = "Das ist das Euro-Symbol: '€'.";

    echo 'Original     : ', $text, PHP_EOL;
    echo 'Mit TRANSLIT : ', iconv("UTF-8", "ISO-8859-1//TRANSLIT", $text), PHP_EOL;
    echo 'Mit IGNORE   : ', iconv("UTF-8", "ISO-8859-1//IGNORE", $text), PHP_EOL;
    echo 'Ohne Zusatz  : ', iconv("UTF-8", "ISO-8859-1", $text), PHP_EOL;

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Original     : Das ist das Euro-Symbol: '€'.
    Mit TRANSLIT : Das ist das Euro-Symbol: 'EUR'.
    Mit IGNORE   : Das ist das Euro-Symbol: ''.
    Ohne Zusatz  :
    Notice: iconv(): Detected an illegal character in input string in .\iconv-example.php on line 7

### Anmerkungen

> Hinweis:

> Welche Zeichenkodierungen und Optionen verfügbar sind, hängt von der installierten iconv-Implementierung ab. Wenn `from_encoding` oder `to_encoding` vom aktuellen System nicht unterstützt wird, wird `false` zurückgegeben.

### Siehe auch

- mb_convert_encoding() - Convert a string from one character encoding to another
- UConverter::transcode() - Convert a string from one character encoding to another

# iconv_get_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_get_encoding — Liefert die aktuelle Einstellung für die Zeichensatz-Konvertierung

### Beschreibung

function iconv_get_encoding(string `$type` = "all"): array|string|false

Diese Funktion gibt die internen Konfigurationsvariablen der iconv-Erweiterung zurück.

### Parameter-Liste

`type`

  Der Wert des optionalen Parameters `type` kann sein:

  - all
  - input_encoding
  - output_encoding
  - internal_encoding

### Rückgabewerte

Gibt bei Erfolg den aktuellen Wert der internen Konfigurationsvariablen zurück. Bei einem Fehler wird `false` zurückgegeben.

Wenn `type` weggelassen oder auf "all" gesetzt ist, gibt iconv_get_encoding() ein Array mit allen Variablen zurück.

### Beispiele

Beispiel #1 iconv_get_encoding()-Beispiel

    <pre>
    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    var_dump(iconv_get_encoding('all'));
    ?>
    </pre>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [input_encoding] => ISO-8859-1
        [output_encoding] => ISO-8859-1
        [internal_encoding] => UTF-8
    )

### Siehe auch

- iconv_set_encoding() - Setzt die aktuelle Einstellung für die Zeichensatzkonvertierung
- ob_iconv_handler() - Konvertiert Zeichensatzkodierung als Ausgabepuffer-Handler (output buffer handler)

# iconv_mime_decode

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode — Decodes a `MIME` header field

### Beschreibung

function iconv_mime_decode(string `$string`, int `$mode` = 0, ?string `$encoding` = `null`): string|false

Decodes a `MIME` header field.

### Parameter-Liste

`string`

  The encoded header, as a string.

`mode`

  `mode` determines the behaviour in the event iconv_mime_decode() encounters a malformed `MIME` header field. You can specify any combination of the following bitmasks.

  Bitmasks acceptable to iconv_mime_decode()
  Value | Constant | Description
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | If set, the given header is decoded in full conformance with the standards defined in » RFC2047. This option is disabled by default because there are a lot of broken mail user agents that don't follow the specification and don't produce correct `MIME` headers.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | If set, iconv_mime_decode_headers() attempts to ignore any grammatical errors and continue to process a given header.

`encoding`

  The optional `encoding` parameter specifies the character set to represent the result by. If omitted or `null`, iconv.internal_encoding will be used.

### Rückgabewerte

Returns a decoded `MIME` field on success, or `false` if an error occurs during the decoding.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` is nullable now.

### Beispiele

Beispiel #1 iconv_mime_decode() example

    <?php
    // This yields "Subject: Prüfung Prüfung"
    echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
                           0, "ISO-8859-1");
    ?>

### Siehe auch

- iconv_mime_decode_headers() - Decodes multiple MIME header fields at once
- mb_decode_mimeheader() - Decode string in MIME header field
- imap_mime_header_decode() - Dekodiert MIME-kodierte Kopfzeilen
- imap_base64() - Dekodiert Base64-kodierten Text
- imap_qprint() - Konvertiert einen quoted-printable-kodierten String in einen 8-Bit-String

# iconv_mime_decode_headers

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode_headers — Decodes multiple `MIME` header fields at once

### Beschreibung

function iconv_mime_decode_headers(string `$headers`, int `$mode` = 0, ?string `$encoding` = `null`): array|false

Decodes multiple `MIME` header fields at once.

### Parameter-Liste

`headers`

  The encoded headers, as a string.

`mode`

  `mode` determines the behaviour in the event iconv_mime_decode_headers() encounters a malformed `MIME` header field. You can specify any combination of the following bitmasks.

  Bitmasks acceptable to iconv_mime_decode_headers()
  Value | Constant | Description
  --- | --- | ---
  1 | ICONV_MIME_DECODE_STRICT | If set, the given header is decoded in full conformance with the standards defined in » RFC2047. This option is disabled by default because there are a lot of broken mail user agents that don't follow the specification and don't produce correct `MIME` headers.
  2 | ICONV_MIME_DECODE_CONTINUE_ON_ERROR | If set, iconv_mime_decode_headers() attempts to ignore any grammatical errors and continue to process a given header.

`encoding`

  The optional `encoding` parameter specifies the character set to represent the result by. If omitted or `null`, iconv.internal_encoding will be used.

### Rückgabewerte

Returns an associative array that holds a whole set of `MIME` header fields specified by `headers` on success, or `false` if an error occurs during the decoding.

Each key of the return value represents an individual field name and the corresponding element represents a field value. If more than one field of the same name are present, iconv_mime_decode_headers() automatically incorporates them into a numerically indexed array in the order of occurrence. Note that header names are not case-insensitive.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` is nullable now.

### Beispiele

Beispiel #1 iconv_mime_decode_headers() example

    <?php
    $headers_string = <<<EOF
    Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=
    To: example@example.com
    Date: Thu, 1 Jan 1970 00:00:00 +0000
    Message-Id: <example@example.com>
    Received: from localhost (localhost [127.0.0.1]) by localhost
        with SMTP id example for <example@example.com>;
        Thu, 1 Jan 1970 00:00:00 +0000 (UTC)
        (envelope-from example-return-0000-example=example.com@example.com)
    Received: (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000

    EOF;

    $headers =  iconv_mime_decode_headers($headers_string, 0, "ISO-8859-1");
    print_r($headers);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [Subject] => Prüfung Prüfung
        [To] => example@example.com
        [Date] => Thu, 1 Jan 1970 00:00:00 +0000
        [Message-Id] => <example@example.com>
        [Received] => Array
            (
                [0] => from localhost (localhost [127.0.0.1]) by localhost with SMTP id example for <example@example.com>; Thu, 1 Jan 1970 00:00:00 +0000 (UTC) (envelope-from example-return-0000-example=example.com@example.com)
                [1] => (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
            )

    )

### Siehe auch

- iconv_mime_decode() - Decodes a MIME header field
- mb_decode_mimeheader() - Decode string in MIME header field
- imap_mime_header_decode() - Dekodiert MIME-kodierte Kopfzeilen
- imap_base64() - Dekodiert Base64-kodierten Text
- imap_qprint() - Konvertiert einen quoted-printable-kodierten String in einen 8-Bit-String

# iconv_mime_encode

(PHP 5, PHP 7, PHP 8)

iconv_mime_encode — Composes a `MIME` header field

### Beschreibung

function iconv_mime_encode(string `$field_name`, string `$field_value`, array `$options` = []): string|false

Composes and returns a string that represents a valid `MIME` header field, which looks like the following:

    Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile

In the above example, "Subject" is the field name and the portion that begins with "=?ISO-8859-1?..." is the field value.

### Parameter-Liste

`field_name`

  The field name.

`field_value`

  The field value.

`options`

  You can control the behaviour of iconv_mime_encode() by specifying an associative array that contains configuration items to the optional third parameter `options`. The items supported by iconv_mime_encode() are listed below. Note that item names are treated case-sensitive.

  Configuration items supported by iconv_mime_encode()
  Item | Type | Description | Default value | Example
  --- | --- | --- | --- | ---
  scheme | string | Specifies the method to encode a field value by. The value of this item may be either "B" or "Q", where "B" stands for `base64` encoding scheme and "Q" stands for `quoted-printable` encoding scheme. | B | B
  input-charset | string | Specifies the character set in which the first parameter `field_name` and the second parameter `field_value` are presented. If not given, iconv_mime_encode() assumes those parameters are presented to it in the iconv.internal_encoding ini setting. | iconv.internal_encoding | ISO-8859-1
  output-charset | string | Specifies the character set to use to compose the `MIME` header. | iconv.internal_encoding | UTF-8
  line-length | int | Specifies the maximum length of the header lines. The resulting header is "folded" to a set of multiple lines in case the resulting header field would be longer than the value of this parameter, according to » RFC2822 - Internet Message Format. If not given, the length will be limited to 76 characters. | 76 | 996
  line-break-chars | string | Specifies the sequence of characters to append to each line as an end-of-line sign when "folding" is performed on a long header field. If not given, this defaults to "\r\n" (`CR` `LF`). Note that this parameter is always treated as an ASCII string regardless of the value of `input-charset`. | \r\n | \n

### Rückgabewerte

Returns an encoded `MIME` field on success, or `false` if an error occurs during the encoding.

### Beispiele

Beispiel #1 iconv_mime_encode() example

    <?php
    $preferences = array(
        "input-charset" => "ISO-8859-1",
        "output-charset" => "UTF-8",
        "line-length" => 76,
        "line-break-chars" => "\n"
    );
    $preferences["scheme"] = "Q";
    // This yields "Subject: =?UTF-8?Q?Pr=C3=BCfung=20Pr=C3=BCfung?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);

    $preferences["scheme"] = "B";
    // This yields "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?="
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);
    ?>

### Siehe auch

- imap_binary() - Konvertiert einen 8bit-String in einen Base64-kodierten String
- mb_encode_mimeheader() - Encode string for MIME header
- imap_8bit() - Konvertiert einen 8bit-String in einen quoted-printable String
- quoted_printable_encode() - Wandelt einen 8-Bit-String in sein 'Quoted Printable' Gegenstück

# iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_set_encoding — Setzt die aktuelle Einstellung für die Zeichensatzkonvertierung

### Beschreibung

function iconv_set_encoding(string `$type`, string `$encoding`): bool

Diese Funktion ändert den Wert der durch `type` angegebenen internen Konfigurationsvariablen auf `encoding`.

### Parameter-Liste

`type`

  Der Wert von `type` kann einer der folgenden sein:

  - input_encoding
  - output_encoding
  - internal_encoding
`encoding`

  Der Zeichensatz.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 iconv_set_encoding()-Beispiel:

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ?>

### Siehe auch

- iconv_get_encoding() - Liefert die aktuelle Einstellung für die Zeichensatz-Konvertierung
- ob_iconv_handler() - Konvertiert Zeichensatzkodierung als Ausgabepuffer-Handler (output buffer handler)

# iconv_strlen

(PHP 5, PHP 7, PHP 8)

iconv_strlen — Returns the character count of string

### Beschreibung

function iconv_strlen(string `$string`, ?string `$encoding` = `null`): int|false

In contrast to strlen(), iconv_strlen() counts the occurrences of characters in the given byte sequence `string` on the basis of the specified character set, the result of which is not necessarily identical to the length of the string in bytes.

### Parameter-Liste

`string`

  The string.

`encoding`

  If `encoding` parameter is omitted or `null`, `string` is assumed to be encoded in iconv.internal_encoding.

### Rückgabewerte

Returns the character count of `string`, as an integer, or `false` if an error occurs during the encoding.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` is nullable now.

### Siehe auch

- grapheme_strlen() - Get string length in grapheme units
- mb_strlen() - Get string length
- strlen() - Ermitteln der String-Länge

# iconv_strpos

(PHP 5, PHP 7, PHP 8)

iconv_strpos — Finds position of first occurrence of a needle within a haystack

### Beschreibung

function iconv_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Finds position of first occurrence of a `needle` within a `haystack`.

In contrast to strpos(), the return value of iconv_strpos() is the number of characters that appear before the needle, rather than the offset in bytes to the position where the needle has been found. The characters are counted on the basis of the specified character set `encoding`.

### Parameter-Liste

`haystack`

  The entire string.

`needle`

  The searched substring.

`offset`

  The optional `offset` parameter specifies the position from which the search should be performed. If the offset is negative, it is counted from the end of the string.

`encoding`

  If `encoding` parameter is omitted or `null`, `string` are assumed to be encoded in iconv.internal_encoding.

If `haystack` or `needle` is not a string, it is converted to a string and applied as the ordinal value of a character.

### Rückgabewerte

Returns the numeric position of the first occurrence of `needle` in `haystack`.

If `needle` is not found, iconv_strpos() will return `false`.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` is nullable now.
7.1.0 | Support for negative `offset`s has been added.

### Siehe auch

- strpos() - Sucht die Position des ersten Vorkommens des Suchstrings in einem String
- iconv_strrpos() - Finds the last occurrence of a needle within a haystack
- mb_strpos() - Find position of first occurrence of string in a string

# iconv_strrpos

(PHP 5, PHP 7, PHP 8)

iconv_strrpos — Finds the last occurrence of a needle within a haystack

### Beschreibung

function iconv_strrpos(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int|false

Finds the last occurrence of a `needle` within a `haystack`.

In contrast to strrpos(), the return value of iconv_strrpos() is the number of characters that appear before the needle, rather than the offset in bytes to the position where the needle has been found. The characters are counted on the basis of the specified character set `encoding`.

### Parameter-Liste

`haystack`

  The entire string.

`needle`

  The searched substring.

`encoding`

  If `encoding` parameter is omitted or `null`, `string` are assumed to be encoded in iconv.internal_encoding.

If `haystack` or `needle` is not a string, it is converted to a string and applied as the ordinal value of a character.

### Rückgabewerte

Returns the numeric position of the last occurrence of `needle` in `haystack`.

If `needle` is not found, iconv_strrpos() will return `false`.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` is nullable now.

### Siehe auch

- strrpos() - Findet die Position des letzten Vorkommens eines Teilstrings innerhalb einer Zeichenkette
- iconv_strpos() - Finds position of first occurrence of a needle within a haystack
- mb_strrpos() - Find position of last occurrence of a string in a string

# iconv_substr

(PHP 5, PHP 7, PHP 8)

iconv_substr — Cut out part of a string

### Beschreibung

function iconv_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string|false

Cuts a portion of `string` specified by the `offset` and `length` parameters.

### Parameter-Liste

`string`

  The original string.

`offset`

  If `offset` is non-negative, iconv_substr() cuts the portion out of `string` beginning at `offset`'th character, counting from zero.

  If `offset` is negative, iconv_substr() cuts out the portion beginning at the position, `offset` characters away from the end of `string`.

`length`

  If `length` is given and is positive, the return value will contain at most `length` characters of the portion that begins at `offset` (depending on the length of `string`).

  If negative `length` is passed, iconv_substr() cuts the portion out of `string` from the `offset`'th character up to the character that is `length` characters away from the end of the string. In case `offset` is also negative, the start position is calculated beforehand according to the rule explained above.

`encoding`

  If `encoding` parameter is omitted or `null`, `string` are assumed to be encoded in iconv.internal_encoding.

  Note that `offset` and `length` parameters are always deemed to represent offsets that are calculated on the basis of the character set determined by `encoding`, whilst the counterpart substr() always takes these for byte offsets.

### Rückgabewerte

Returns the portion of `string` specified by the `offset` and `length` parameters.

If `string` is shorter than `offset` characters long, `false` will be returned. If `string` is exactly `offset` characters long, an empty string will be returned.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `length` and `encoding` are nullable now.
7.0.11 | If `string` is equal to `offset` characters long, an empty string will be returned. Prior to this version, `false` was returned in this case.

### Siehe auch

- substr() - Liefert einen Teil eines Strings
- mb_substr() - Get part of string
- mb_strcut() - Get part of string

# ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ob_iconv_handler — Konvertiert Zeichensatzkodierung als Ausgabepuffer-Handler (output buffer handler)

### Beschreibung

function ob_iconv_handler(string `$contents`, int `$status`): string

Diese Funktion konvertiert die im Zeichensatz `internal_encoding` kodierte Zeichenkette in `output_encoding`.

`internal_encoding` und `output_encoding` sollten über die Konfigurationsdatei php.ini oder über die Funktion iconv_set_encoding() definiert werden.

### Parameter-Liste

ob_start() enthält Informationen über die Parameter.

### Rückgabewerte

ob_start() enthält Informationen über die Rückgabewerte.

### Beispiele

Beispiel #1 ob_iconv_handler()-Beispiel

    <?php
    iconv_set_encoding("internal_encoding", "UTF-8");
    iconv_set_encoding("output_encoding", "ISO-8859-1");
    ob_start("ob_iconv_handler"); // start output buffering
    ?>

### Siehe auch

- iconv_get_encoding() - Liefert die aktuelle Einstellung für die Zeichensatz-Konvertierung
- iconv_set_encoding() - Setzt die aktuelle Einstellung für die Zeichensatzkonvertierung
- output-control functions

## Inhaltsverzeichnis

- iconv — Konvertiert eine Zeichenkette von einem Zeichensatz in einen anderen
- iconv_get_encoding — Liefert die aktuelle Einstellung für die Zeichensatz-Konvertierung
- iconv_mime_decode — Decodes a MIME header field
- iconv_mime_decode_headers — Decodes multiple MIME header fields at once
- iconv_mime_encode — Composes a MIME header field
- iconv_set_encoding — Setzt die aktuelle Einstellung für die Zeichensatzkonvertierung
- iconv_strlen — Returns the character count of string
- iconv_strpos — Finds position of first occurrence of a needle within a haystack
- iconv_strrpos — Finds the last occurrence of a needle within a haystack
- iconv_substr — Cut out part of a string
- ob_iconv_handler — Konvertiert Zeichensatzkodierung als Ausgabepuffer-Handler (output buffer handler)

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- iconv Funktionen
  - iconv — Konvertiert eine Zeichenkette von einem Zeichensatz in einen anderen
  - iconv_get_encoding — Liefert die aktuelle Einstellung für die Zeichensatz-Konvertierung
  - iconv_mime_decode — Decodes a MIME header field
  - iconv_mime_decode_headers — Decodes multiple MIME header fields at once
  - iconv_mime_encode — Composes a MIME header field
  - iconv_set_encoding — Setzt die aktuelle Einstellung für die Zeichensatzkonvertierung
  - iconv_strlen — Returns the character count of string
  - iconv_strpos — Finds position of first occurrence of a needle within a haystack
  - iconv_strrpos — Finds the last occurrence of a needle within a haystack
  - iconv_substr — Cut out part of a string
  - ob_iconv_handler — Konvertiert Zeichensatzkodierung als Ausgabepuffer-Handler (output buffer handler)

# Internationalization Functions

# Einführung

Internationalization extension (further is referred as Intl) is a wrapper for » ICU library, enabling PHP programmers to perform various locale-aware operations including but not limited to formatting, transliteration, encoding conversion, calendar operations, » UCA-conformant collation, locating text boundaries and working with locale identifiers, timezones and graphemes.

It tends to closely follow ICU APIs, so that people having experience working with ICU in either C/C++ or Java could easily use the PHP API. Also, this way ICU documentation would be useful to understand various ICU functions.

Intl consists of several modules, each of them exposes the corresponding ICU API:

- Collator: provides string comparison capability with support for appropriate locale-sensitive sort orderings.
- Number Formatter: allows to display number according to the localized format or given pattern or set of rules, and to parse strings into numbers.
- Message Formatter: allows to create messages incorporating data (such as numbers or dates) formatted according to given pattern and locale rules, and parse messages extracting data from them. It can handle plurals, locale-aware numbers, currencies, conditions and much more.
- Normalizer: provides a function to transform text into one of the Unicode normalization forms, and provides a routine to test if a given string is already normalized.
- Locale: provides interaction with locale identifiers in the form of functions to get subtags from locale identifier; parse, compose, match(lookup and filter) locale identifiers.
- Calendar: provides a class which could be used for locale-aware calendar operations and getting various information such as timezone for locale chosen, first day of week or if it's daylight saving time now.
- Timezone: provides a wrapper around the » "Olson" database which has information about all the timezones around the world.
- Date formatter: allows to display date and time according to the localized format or given pattern or set of rules, and to parse strings into date and time.
- Transliterator: allows getting latin representation of strings in various languages.

## Links

- » Miscellaneous ICU docs

- » ICU User Guide

- » Unicode Collation Algorithm

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

To build the extension you need to install the » ICU library, version 4.0.0 or newer is required. As of PHP 7.4.0 ICU 50.1 or newer is required.

## Installation

--enable-intl will enable the extension while compiling PHP.

If your ICU is installed to a non-standard directory then you might want to specify its location in `LD_LIBRARY_PATH` environment variable so that dynamic linker can find it:

$ export LD_LIBRARY_PATH=/opt/icu/lib

Otherwise, if PHP and ICU are installed to their default locations, then the additional options to configure are not needed.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Intl Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
intl.default_locale |  | `INI_ALL` |
intl.error_level | 0 | `INI_ALL` |
intl.use_exceptions | 0 | `INI_ALL` | Available since PECL 3.0.0a1

Hier eine kurze Erklärung der Konfigurationsoptionen:

`intl.default_locale` string

  The locale that will be used in intl functions when none is specified (either by omitting the corresponding argument or by passing `NULL`). These are ICU locales, not system locales. The built-in ICU locales and their data can be explored at » https://unicode-org.github.io/icu/userguide/locale/.

  The default value is empty, which forces the usage of ICU's default locale. Once set, the ini setting cannot be reset to this default value. It is not recommended that this default be relied on, as its effective value depends on the server's environment.

`intl.error_level` int

  The type of the error messages generated when an error occurs in ICU functions. This is a PHP error level, such as `E_WARNING`. It can be set to `0` in order to inhibit the messages. This does not affect the return values indicating error or the values returned by intl_get_error_code() or by the class specific methods for retrieving error codes and messages.

  The default value is `0`.

`intl.use_exceptions` int

  If set to true, an exception will be raised whenever an error occurs in an intl function. The exception will be of type IntlException. This is possibly in addition to the error message generated due to intl.error_level.

  The default value is `false`.

# Vordefinierte Konstanten

`INTL_ICU_DATA_VERSION` (string)
  Data version in ICU4C.
`INTL_ICU_VERSION` (string)
  The current ICU library version as a dotted-decimal string.
`INTL_MAX_LOCALE_LEN` (int)
  Limit on locale length, set to 80 in PHP code. Locale names longer than this limit will not be accepted.
`IDNA_DEFAULT` (int)
  Prohibit processing of unassigned codepoints in the input for IDN functions and do not check if the input conforms to domain name ASCII rules.
`IDNA_ALLOW_UNASSIGNED` (int)
  Allow processing of unassigned codepoints in the input for IDN functions.
`IDNA_USE_STD3_RULES` (int)
  Check if the input for IDN functions conforms to domain name ASCII rules.
`IDNA_CHECK_BIDI` (int)
  Check whether the input conforms to the BiDi rules. Ignored by the IDNA2003 implementation, which always performs this check.
`IDNA_CHECK_CONTEXTJ` (int)
  Check whether the input conforms to the CONTEXTJ rules. Ignored by the IDNA2003 implementation, as this check is new in IDNA2008.
`IDNA_NONTRANSITIONAL_TO_ASCII` (int)
  Option for nontransitional processing in idn_to_ascii(). Transitional processing is activated by default. This option is ignored by the IDNA2003 implementation.
`IDNA_NONTRANSITIONAL_TO_UNICODE` (int)
  Option for nontransitional processing in idn_to_utf8(). Transitional processing is activated by default. This option is ignored by the IDNA2003 implementation.
`INTL_IDNA_VARIANT_2003` (int)
  Use IDNA 2003 algorithm in idn_to_utf8() and idn_to_ascii(). This is the default. This constant and using the default has been deprecated as of PHP 7.2.0.
`INTL_IDNA_VARIANT_UTS46` (int)
  Use UTS #46 algorithm in idn_to_utf8() and idn_to_ascii(). Available as of ICU 4.6.
`GRAPHEME_EXTR_COUNT` (int)
  The number of default grapheme clusters to extract.
`GRAPHEME_EXTR_MAXBYTES` (int)
  The maximum number of bytes returned.
`GRAPHEME_EXTR_MAXCHARS` (int)
  The maximum number of UTF-8 characters returned.

The following errors are part of a bitmask returned by the UTS #46 algorithm in idn_to_utf8() and idn_to_ascii().

`IDNA_ERROR_EMPTY_LABEL` (int)
`IDNA_ERROR_LABEL_TOO_LONG` (int)
`IDNA_ERROR_DOMAIN_NAME_TOO_LONG` (int)
`IDNA_ERROR_LEADING_HYPHEN` (int)
`IDNA_ERROR_TRAILING_HYPHEN` (int)
`IDNA_ERROR_HYPHEN_3_4` (int)
`IDNA_ERROR_LEADING_COMBINING_MARK` (int)
`IDNA_ERROR_DISALLOWED` (int)
`IDNA_ERROR_PUNYCODE` (int)
`IDNA_ERROR_LABEL_HAS_DOT` (int)
`IDNA_ERROR_INVALID_ACE_LABEL` (int)
`IDNA_ERROR_BIDI` (int)
`IDNA_ERROR_CONTEXTJ` (int)
`ULOC_ACTUAL_LOCALE` (int)
  The locale the data actually comes from.
`ULOC_VALID_LOCALE` (int)
  The most specific locale supported by ICU.
`U_AMBIGUOUS_ALIAS_WARNING` (int)
  This converter alias can go to different converter implementations.
`U_BAD_VARIABLE_DEFINITION` (int)
  Missing `'$'` or duplicate variable name.
`U_BRK_ASSIGN_ERROR` (int)
  Syntax error in RBBI rule assignment statement.
`U_BRK_ERROR_LIMIT` (int)
  This must always be the last value to indicate the limit for Break Iterator failures.
`U_BRK_ERROR_START` (int)
  Start of codes indicating Break Iterator failures.
`U_BRK_HEX_DIGITS_EXPECTED` (int)
  Hex digits expected as part of a escaped char in a rule.
`U_BRK_INIT_ERROR` (int)
  Initialization failure. Probable missing ICU Data.
`U_BRK_INTERNAL_ERROR` (int)
  An internal error (bug) was detected.
`U_BRK_MALFORMED_RULE_TAG` (int)
  The `{nnn}` tag on a rule is mal formed.
`U_BRK_MISMATCHED_PAREN` (int)
  Mis-matched parentheses in an RBBI rule.
`U_BRK_NEW_LINE_IN_QUOTED_STRING` (int)
  Missing closing quote in an RBBI rule.
`U_BRK_RULE_EMPTY_SET` (int)
  Rule contains an empty Unicode Set.
`U_BRK_RULE_SYNTAX` (int)
  Syntax error in RBBI rule.
`U_BRK_SEMICOLON_EXPECTED` (int)
  Missing `';'` at the end of a RBBI rule.
`U_BRK_UNCLOSED_SET` (int)
  UnicodeSet writing an RBBI rule missing a closing `']'`.
`U_BRK_UNDEFINED_VARIABLE` (int)
  Use of an undefined `$Variable` in an RBBI rule.
`U_BRK_UNRECOGNIZED_OPTION` (int)
  Option in RBBI rules not recognized.
`U_BRK_VARIABLE_REDFINITION` (int)
  RBBI rule variable redefined.
`U_BUFFER_OVERFLOW_ERROR` (int)
  A result would not fit in the supplied buffer.
`U_CE_NOT_FOUND_ERROR` (int)
  Currently used only while setting variable top, but can be used generally.
`U_COLLATOR_VERSION_MISMATCH` (int)
  Collator version is not compatible with the base version.
`U_DIFFERENT_UCA_VERSION` (int)
  ucol_open encountered a mismatch between UCA version and collator image version, so the collator was constructed from rules. No impact to further function.
`U_ENUM_OUT_OF_SYNC_ERROR` (int)
  `UEnumeration` out of sync with underlying collection.
`U_ERROR_LIMIT` (int)
  Alias of `U_PLUGIN_ERROR_LIMIT`.
`U_ERROR_WARNING_LIMIT` (int)
  This must always be the last warning value to indicate the limit for UErrorCode warnings (last warning code +1).
`U_ERROR_WARNING_START` (int)
  Start of information results (semantically successful).
`U_FILE_ACCESS_ERROR` (int)
  The requested file cannot be found.
`U_FMT_PARSE_ERROR_LIMIT` (int)
  The limit for format library errors.
`U_FMT_PARSE_ERROR_START` (int)
  Start of format library errors.
`U_IDNA_ACE_PREFIX_ERROR` (int)
`U_IDNA_CHECK_BIDI_ERROR` (int)
`U_IDNA_DOMAIN_NAME_TOO_LONG_ERROR` (int)
`U_IDNA_ERROR_LIMIT` (int)
`U_IDNA_ERROR_START` (int)
`U_IDNA_LABEL_TOO_LONG_ERROR` (int)
`U_IDNA_PROHIBITED_ERROR` (int)
`U_IDNA_STD3_ASCII_RULES_ERROR` (int)
`U_IDNA_UNASSIGNED_ERROR` (int)
`U_IDNA_VERIFICATION_ERROR` (int)
`U_IDNA_ZERO_LENGTH_LABEL_ERROR` (int)
`U_ILLEGAL_ARGUMENT_ERROR` (int)
  Indicates an incorrect argument value.
`U_ILLEGAL_CHAR_FOUND` (int)
  Character conversion: Illegal input sequence.
`U_ILLEGAL_CHAR_IN_SEGMENT` (int)
  Unused as of ICU 2.4.
`U_ILLEGAL_CHARACTER` (int)
  A special character is outside its allowed context.
`U_ILLEGAL_ESCAPE_SEQUENCE` (int)
  ISO-2022 illlegal escape sequence.
`U_ILLEGAL_PAD_POSITION` (int)
  Pad symbol misplaced in number pattern.
`U_INDEX_OUTOFBOUNDS_ERROR` (int)
  Trying to access the index that is out of bounds.
`U_INTERNAL_PROGRAM_ERROR` (int)
  Indicates a bug in the library code.
`U_INTERNAL_TRANSLITERATOR_ERROR` (int)
  Internal transliterator system error.
`U_INVALID_CHAR_FOUND` (int)
  Character conversion: Unmappable input sequence. In other APIs: Invalid character.
`U_INVALID_FORMAT_ERROR` (int)
  Data format is not what is expected.
`U_INVALID_FUNCTION` (int)
  A `'&fn()'` rule specifies an unknown transliterator.
`U_INVALID_ID` (int)
  A `'::id'` rule specifies an unknown transliterator.
`U_INVALID_PROPERTY_PATTERN` (int)
  Unused as of ICU 2.4.
`U_INVALID_RBT_SYNTAX` (int)
  A `'::id'` rule was passed to the RuleBasedTransliterator parser.
`U_INVALID_STATE_ERROR` (int)
  Requested operation can not be completed with ICU in its current state.
`U_INVALID_TABLE_FILE` (int)
  Conversion table file not found.
`U_INVALID_TABLE_FORMAT` (int)
  Conversion table file found, but corrupted.
`U_INVARIANT_CONVERSION_ERROR` (int)
  Unable to convert a `UChar*` string to `char*` with the invariant converter.
`U_MALFORMED_EXPONENTIAL_PATTERN` (int)
  Grouping symbol in exponent pattern.
`U_MALFORMED_PRAGMA` (int)
  A `'use'` pragma is invalid.
`U_MALFORMED_RULE` (int)
  Elements of a rule are misplaced.
`U_MALFORMED_SET` (int)
  A `UnicodeSet` pattern is invalid.
`U_MALFORMED_SYMBOL_REFERENCE` (int)
  Unused as of ICU 2.4.
`U_MALFORMED_UNICODE_ESCAPE` (int)
  A Unicode escape pattern is invalid.
`U_MALFORMED_VARIABLE_DEFINITION` (int)
  A variable definition is invalid.
`U_MALFORMED_VARIABLE_REFERENCE` (int)
  A variable reference is invalid.
`U_MEMORY_ALLOCATION_ERROR` (int)
  Memory allocation error.
`U_MESSAGE_PARSE_ERROR` (int)
  Unable to parse a message (message format).
`U_MISMATCHED_SEGMENT_DELIMITERS` (int)
  Unused as of ICU 2.4.
`U_MISPLACED_ANCHOR_START` (int)
  A start anchor appears at an illegal position.
`U_MISPLACED_COMPOUND_FILTER` (int)
  A compound filter is in an invalid location.
`U_MISPLACED_CURSOR_OFFSET` (int)
  A cursor offset occurs at an illegal position.
`U_MISPLACED_QUANTIFIER` (int)
  A quantifier appears after a segment close delimiter.
`U_MISSING_OPERATOR` (int)
  A rule contains no operator.
`U_MISSING_RESOURCE_ERROR` (int)
  The requested resource cannot be found.
`U_MISSING_SEGMENT_CLOSE` (int)
  Unused as of ICU 2.4.
`U_MULTIPLE_ANTE_CONTEXTS` (int)
  More than one ante context.
`U_MULTIPLE_COMPOUND_FILTERS` (int)
  More than one compound filter.
`U_MULTIPLE_CURSORS` (int)
  More than one cursor.
`U_MULTIPLE_DECIMAL_SEPARATORS` (int)
  More than one decimal separator in number pattern.
`U_MULTIPLE_DECIMAL_SEPERATORS` (int)
  Alias of `U_MULTIPLE_DECIMAL_SEPARATORS`.
`U_MULTIPLE_EXPONENTIAL_SYMBOLS` (int)
  More than one exponent symbol in number pattern.
`U_MULTIPLE_PAD_SPECIFIERS` (int)
  More than one pad symbol in number pattern.
`U_MULTIPLE_PERCENT_SYMBOLS` (int)
  More than one percent symbol in number pattern.
`U_MULTIPLE_PERMILL_SYMBOLS` (int)
  More than one permill symbol in number pattern.
`U_MULTIPLE_POST_CONTEXTS` (int)
  More than one post context.
`U_NO_SPACE_AVAILABLE` (int)
  No space available for in-buffer expansion for Arabic shaping.
`U_NO_WRITE_PERMISSION` (int)
  Attempt to modify read-only or constant data.
`U_PARSE_ERROR` (int)
  Equivalent to Java `ParseException`.
`U_PARSE_ERROR_LIMIT` (int)
  The limit for Transliterator errors.
`U_PARSE_ERROR_START` (int)
  Start of Transliterator errors.
`U_PATTERN_SYNTAX_ERROR` (int)
  Syntax error in format pattern.
`U_PRIMARY_TOO_LONG_ERROR` (int)
  User tried to set variable top to a primary that is longer than two bytes.
`U_REGEX_BAD_ESCAPE_SEQUENCE` (int)
  Unrecognized backslash escape sequence in pattern.
`U_REGEX_BAD_INTERVAL` (int)
  Error in `{min,max}` interval.
`U_REGEX_ERROR_LIMIT` (int)
  This must always be the last value to indicate the limit for regexp errors.
`U_REGEX_ERROR_START` (int)
  Start of codes indicating Regexp failures.
`U_REGEX_INTERNAL_ERROR` (int)
  An internal error (bug) was detected.
`U_REGEX_INVALID_BACK_REF` (int)
  Back-reference to a non-existent capture group.
`U_REGEX_INVALID_FLAG` (int)
  Invalid value for match mode flags.
`U_REGEX_INVALID_STATE` (int)
  `RegexMatcher` in invalid state for requested operation.
`U_REGEX_LOOK_BEHIND_LIMIT` (int)
  Look-Behind pattern matches must have a bounded maximum length.
`U_REGEX_MAX_LT_MIN` (int)
  In `{min,max}`, max is less than min.
`U_REGEX_MISMATCHED_PAREN` (int)
  Incorrectly nested parentheses in regexp pattern.
`U_REGEX_NUMBER_TOO_BIG` (int)
  Decimal number is too large.
`U_REGEX_PROPERTY_SYNTAX` (int)
  Incorrect Unicode property.
`U_REGEX_RULE_SYNTAX` (int)
  Syntax error in regexp pattern.
`U_REGEX_SET_CONTAINS_STRING` (int)
  Regexps cannot have `UnicodeSet`s containing strings.
`U_REGEX_UNIMPLEMENTED` (int)
  Use of regexp feature that is not yet implemented.
`U_RESOURCE_TYPE_MISMATCH` (int)
  An operation is requested over a resource that does not support it.
`U_RULE_MASK_ERROR` (int)
  A rule is hidden by an earlier more general rule.
`U_SAFECLONE_ALLOCATED_WARNING` (int)
  A `SafeClone` operation required allocating memory (informational only).
`U_SORT_KEY_TOO_SHORT_WARNING` (int)
  Number of levels requested in `getBound` is higher than the number of levels in the sort key.
`U_STANDARD_ERROR_LIMIT` (int)
  This must always be the last value to indicate the limit for standard errors.
`U_STATE_OLD_WARNING` (int)
  ICU has to use compatibility layer to construct the service. Expect performance/memory usage degradation.
`U_STATE_TOO_OLD_ERROR` (int)
  ICU cannot construct a service from this state, as it is no longer supported.
`U_STRING_NOT_TERMINATED_WARNING` (int)
  An output string could not be NUL-terminated because output `length==destCapacity`.
`U_STRINGPREP_CHECK_BIDI_ERROR` (int)
  Alias of `U_IDNA_CHECK_BIDI_ERROR`.
`U_STRINGPREP_PROHIBITED_ERROR` (int)
  Alias of `U_IDNA_PROHIBITED_ERROR`.
`U_STRINGPREP_UNASSIGNED_ERROR` (int)
  Alias of `U_IDNA_UNASSIGNED_ERROR`.
`U_TOO_MANY_ALIASES_ERROR` (int)
  There are too many aliases in the path to the requested resource. It is very possible that a circular alias definition has occurred.
`U_TRAILING_BACKSLASH` (int)
  A dangling backslash.
`U_TRUNCATED_CHAR_FOUND` (int)
  Character conversion: Incomplete input sequence.
`U_UNCLOSED_SEGMENT` (int)
  A closing `')'` is missing.
`U_UNDEFINED_SEGMENT_REFERENCE` (int)
  A segment reference does not correspond to a defined segment.
`U_UNDEFINED_VARIABLE` (int)
  A variable reference does not correspond to a defined variable.
`U_UNEXPECTED_TOKEN` (int)
  Syntax error in format pattern.
`U_UNMATCHED_BRACES` (int)
  Braces do not match in message pattern.
`U_UNQUOTED_SPECIAL` (int)
  A special character was not quoted or escaped.
`U_UNSUPPORTED_ATTRIBUTE` (int)
  Unused as of ICU 2.4.
`U_UNSUPPORTED_ERROR` (int)
  Requested operation not supported in current context.
`U_UNSUPPORTED_ESCAPE_SEQUENCE` (int)
  ISO-2022 unsupported escape sequence.
`U_UNSUPPORTED_PROPERTY` (int)
  Unused as of ICU 2.4.
`U_UNTERMINATED_QUOTE` (int)
  A closing single quote is missing.
`U_USELESS_COLLATOR_ERROR` (int)
  Collator is options only and no base is specified.
`U_USING_DEFAULT_WARNING` (int)
  A resource bundle lookup returned a result from the root locale (not an error).
`U_USING_FALLBACK_WARNING` (int)
  A resource bundle lookup returned a fallback result (not an error).
`U_VARIABLE_RANGE_EXHAUSTED` (int)
  Too many stand-ins generated for the given variable range.
`U_VARIABLE_RANGE_OVERLAP` (int)
  The variable range overlaps characters used in rules.
`U_ZERO_ERROR` (int)
  No error, no warning.

# Beispiele

## Inhaltsverzeichnis

- Basic usage of this extension

## Basic usage of this extension

Each module provides two kind of APIs: a procedural one and an object oriented one. Both are actually identical and described in the corresponding document.

> Hinweis:

> All input strings must be in UTF-8 encoding. All output strings are also in UTF-8.

Beispiel #1 Example of using the procedural API

    <?php
    $coll  = collator_create('en_US');
    $result = collator_compare($coll, "string#1", "string#2");
    ?>

Beispiel #2 Example of using the object-oriented API

    <?php
    $coll = new Collator('en_US');
    $al   = $coll->getLocale(Locale::ACTUAL_LOCALE);
    echo "Actual locale: $al\n";

    $formatter = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    echo $formatter->format(1234567);
    ?>

# The Collator class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Einführung

Provides string comparison capability with support for appropriate locale-sensitive sort orderings.

## Klassenbeschreibung

class Collator {
/* Konstanten */
public const int DEFAULT_VALUE;
public const int PRIMARY;
public const int SECONDARY;
public const int TERTIARY;
public const int DEFAULT_STRENGTH;
public const int QUATERNARY;
public const int IDENTICAL;
public const int OFF;
public const int ON;
public const int SHIFTED;
public const int NON_IGNORABLE;
public const int LOWER_FIRST;
public const int UPPER_FIRST;
public const int FRENCH_COLLATION;
public const int ALTERNATE_HANDLING;
public const int CASE_FIRST;
public const int CASE_LEVEL;
public const int NORMALIZATION_MODE;
public const int STRENGTH;
public const int HIRAGANA_QUATERNARY_MODE;
public const int NUMERIC_COLLATION;
public const int SORT_REGULAR;
public const int SORT_STRING;
public const int SORT_NUMERIC;
/* Methoden */
public function __construct(string `$locale`)
public function asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function compare(string `$string1`, string `$string2`): int|false
public static function create(string `$locale`): ?Collator
public function getAttribute(int `$attribute`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getLocale(int `$type`): string|false
public function getSortKey(string `$string`): string|false
public function getStrength(): int
public function setAttribute(int `$attribute`, int `$value`): bool
public function setStrength(int `$strength`): true
public function sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function sortWithSortKeys(array `&$array`): bool
}

## Vordefinierte Konstanten

`Collator::FRENCH_COLLATION` int

  Sort strings with different accents from the back of the string. This attribute is automatically set to On for the French locales and a few others. Users normally would not need to explicitly set this attribute. There is a string comparison performance cost when it is set On, but sort key length is unaffected. Possible values are:

  - `Collator::ON`
  - `Collator::OFF`(default)
  - `Collator::DEFAULT_VALUE`

  Beispiel #1 FRENCH_COLLATION rules

  - F=OFF cote < coté < côte < côté
  - F=ON cote < côte < coté < côté
`Collator::ALTERNATE_HANDLING`

  The Alternate attribute is used to control the handling of the so called variable characters in the UCA: whitespace, punctuation and symbols. If Alternate is set to NonIgnorable (N), then differences among these characters are of the same importance as differences among letters. If Alternate is set to Shifted (S), then these characters are of only minor importance. The Shifted value is often used in combination with Strength set to Quaternary. In such a case, whitespace, punctuation, and symbols are considered when comparing strings, but only if all other aspects of the strings (base letters, accents, and case) are identical. If Alternate is not set to Shifted, then there is no difference between a Strength of 3 and a Strength of 4. For more information and examples, see Variable_Weighting in the » UCA. The reason the Alternate values are not simply On and Off is that additional Alternate values may be added in the future. The UCA option Blanked is expressed with Strength set to 3, and Alternate set to Shifted. The default for most locales is NonIgnorable. If Shifted is selected, it may be slower if there are many strings that are the same except for punctuation; sort key length will not be affected unless the strength level is also increased.

  Possible values are:

  - `Collator::NON_IGNORABLE`(default)
  - `Collator::SHIFTED`
  - `Collator::DEFAULT_VALUE`

  Beispiel #2 ALTERNATE_HANDLING rules

  - S=3, A=N di Silva < Di Silva < diSilva < U.S.A. < USA
  - S=3, A=S di Silva = diSilva < Di Silva < U.S.A. = USA
  - S=4, A=S di Silva < diSilva < Di Silva < U.S.A. < USA
`Collator::CASE_FIRST` int

  The Case_First attribute is used to control whether uppercase letters come before lowercase letters or vice versa, in the absence of other differences in the strings. The possible values are Uppercase_First (U) and Lowercase_First (L), plus the standard Default and Off. There is almost no difference between the Off and Lowercase_First options in terms of results, so typically users will not use Lowercase_First: only Off or Uppercase_First. (People interested in the detailed differences between X and L should consult the `Collation Customization`). Specifying either L or U won't affect string comparison performance, but will affect the sort key length.

  Possible values are:

  - `Collator::OFF`(default)
  - `Collator::LOWER_FIRST`
  - `Collator::UPPER_FIRST`
  - `Collator:DEFAULT`

  Beispiel #3 CASE_FIRST rules

  - C=X or C=L "china" < "China" < "denmark" < "Denmark"
  - C=U "China" < "china" < "Denmark" < "denmark"
`Collator::CASE_LEVEL` int

  The Case_Level attribute is used when ignoring accents but not case. In such a situation, set Strength to be Primary, and Case_Level to be On. In most locales, this setting is Off by default. There is a small string comparison performance and sort key impact if this attribute is set to be On.

  Possible values are:

  - `Collator::OFF`(default)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`

  Beispiel #4 CASE_LEVEL rules

  - S=1, E=X role = Role = rôle
  - S=1, E=O role = rôle < Role
`Collator::NORMALIZATION_MODE` int

  The Normalization setting determines whether text is thoroughly normalized or not in comparison. Even if the setting is off (which is the default for many locales), text as represented in common usage will compare correctly (for details, see UTN #5). Only if the accent marks are in noncanonical order will there be a problem. If the setting is On, then the best results are guaranteed for all possible text input. There is a medium string comparison performance cost if this attribute is On, depending on the frequency of sequences that require normalization. There is no significant effect on sort key length. If the input text is known to be in NFD or NFKD normalization forms, there is no need to enable this Normalization option.

  Possible values are:

  - `Collator::OFF`(default)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  The ICU Collation Service supports many levels of comparison (named "Levels", but also known as "Strengths"). Having these categories enables ICU to sort strings precisely according to local conventions. However, by allowing the levels to be selectively employed, searching for a string in text can be performed with various matching conditions. For more detailed information, see collator_set_strength() chapter.

  Possible values are:

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(default)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  Compatibility with JIS x 4061 requires the introduction of an additional level to distinguish Hiragana and Katakana characters. If compatibility with that standard is required, then this attribute should be set On, and the strength set to Quaternary. This will affect sort key length and string comparison string comparison performance.

  Possible values are:

  - `Collator::OFF`(default)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  When turned on, this attribute generates a collation key for the numeric value of substrings of digits. This is a way to get '100' to sort AFTER '2'.

  Possible values are:

  - `Collator::OFF`(default)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::DEFAULT_VALUE` int
`Collator::PRIMARY` int
`Collator::SECONDARY` int
`Collator::TERTIARY` int
`Collator::DEFAULT_STRENGTH` int
`Collator::QUATERNARY` int
`Collator::IDENTICAL` int
`Collator::OFF` int
`Collator::ON` int
`Collator::SHIFTED` int
`Collator::NON_IGNORABLE` int
`Collator::LOWER_FIRST` int
`Collator::UPPER_FIRST` int
`Collator::SORT_REGULAR` int

`Collator::SORT_STRING` int

`Collator::SORT_NUMERIC` int

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | The class constants are now typed.

# Collator::asort

# collator_asort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::asort -- collator_asort — Sort array maintaining index association

### Beschreibung

Objektorientierter Stil

public function Collator::asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Prozeduraler Stil

function collator_asort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

This function sorts an array such that array indices maintain their correlation with the array elements they are associated with. This is used mainly when sorting associative arrays where the actual element order is significant. Array elements will have sort order according to current locale rules.

Equivalent to standard PHP asort().

### Parameter-Liste

`object`

  Collator object.

`array`

  Array of strings to sort.

`flags`

  Optional sorting type, one of the following:

  - `Collator::SORT_REGULAR` - compare items normally (don't change types)

  - `Collator::SORT_NUMERIC` - compare items numerically

  - `Collator::SORT_STRING` - compare items as strings

  Default `flags` value is `Collator::SORT_REGULAR`. It is also used if an invalid `flags` value has been specified.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 collator_asort() example

    <?php
    $coll = collator_create( 'en_US' );
    $arr = array(
         'a' => '100',
         'b' => '50',
         'c' => '7'
    );
    collator_asort( $coll, $arr, Collator::SORT_NUMERIC );
    var_export( $arr );

    collator_asort( $coll, $arr, Collator::SORT_STRING );
    var_export( $arr );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array (
      'c' => '7',
      'b' => '50',
      'a' => '100',
    )array (
      'a' => '100',
      'b' => '50',
      'c' => '7',
    )

### Siehe auch

- Collator constants
- collator_sort() - Sort array using specified collator
- collator_sort_with_sort_keys() - Sort array using specified collator and sort keys

# Collator::compare

# collator_compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::compare -- collator_compare — Compare two Unicode strings

### Beschreibung

Objektorientierter Stil

public function Collator::compare(string `$string1`, string `$string2`): int|false

Prozeduraler Stil

function collator_compare(Collator `$object`, string `$string1`, string `$string2`): int|false

Compare two Unicode strings according to collation rules.

### Parameter-Liste

`object`

  Collator object.

`string1`

  The first string to compare.

`string2`

  The second string to compare.

### Rückgabewerte

Return comparison result:

- 1 if `string1` is greater than `string2` ;

- 0 if `string1` is equal to `string2`;

- -1 if `string1` is less than `string2` .

Returns `false` on failure.
Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Beispiele

Beispiel #1 collator_compare() example

    <?php
    $s1 = 'Hello';
    $s2 = 'hello';

    $coll = collator_create( 'en_US' );
    $res  = collator_compare( $coll, $s1, $s2 );

    if ($res === false) {
        echo collator_get_error_message( $coll );
    } else if( $res > 0 ) {
        echo "s1 is greater than s2\n";
    } else if( $res < 0 ) {
        echo "s1 is less than s2\n";
    } else {
        echo "s1 is equal to s2\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

s1 is greater than s2

Beispiel #2 Comparing strings without diacritics or case-sensitivity

    <?php
    $c = new Collator( 'en' );
    $c->setStrength( Collator::PRIMARY );

    if ( $c->compare( 'Séan', 'Sean' ) == 0 )
    {
        echo "The same\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

The same

This example instructs the collator to compare with only taking the base characters into account. The documentation for Collator->setStrength() explains the different strengths.

### Siehe auch

- collator_sort() - Sort array using specified collator

# Collator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::__construct — Create a collator

### Beschreibung

public function Collator::__construct(string `$locale`)

Creates a new instance of Collator.

### Parameter-Liste

`locale`

  The locale whose collation rules should be used. Special values for locales can be passed in - if an empty String is passed for the locale, the default locale's collation rules will be used. If `"root"` is passed, » UCA rules will be used.

  The `locale` attribute is typically the most important attribute for correct sorting and matching, according to the user expectations in different countries and regions. The default » UCA ordering will only sort a few languages such as Dutch and Portuguese correctly ("correctly" meaning according to the normal expectations for users of the languages). Otherwise, you need to supply the locale to UCA in order to properly collate text for a given language. Thus a locale needs to be supplied so as to choose a collator that is correctly tailored for that locale. The choice of a locale will automatically preset the values for all of the attributes to something that is reasonable for that locale. Thus most of the time the other attributes do not need to be explicitly set. In some cases, the choice of locale will make a difference in string comparison performance and/or sort key length.

### Fehler/Exceptions

Returns an "empty" object on error. Use intl_get_error_code() and/or intl_get_error_message() to know what happened.

### Beispiele

Beispiel #1 Collator::__construct() example

    <?php
    $coll = new Collator('en_CA');
    ?>

### Siehe auch

- Collator::create() - Create a collator
- collator_create() - Create a collator

# Collator::create

# collator_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::create -- collator_create — Create a collator

### Beschreibung

Objektorientierter Stil

public static function Collator::create(string `$locale`): ?Collator

Prozeduraler Stil

function collator_create(string `$locale`): ?Collator

The strings will be compared using the options already specified.

### Parameter-Liste

`locale`

  The locale containing the required collation rules. Special values for locales can be passed in - if an empty String is passed for the locale, the default locale collation rules will be used. If `"root"` is passed, » UCA rules will be used.

### Rückgabewerte

Return new instance of Collator object, or `null` on error.

### Beispiele

Beispiel #1 collator_create() example

    <?php
    $coll = collator_create( 'en_US' );

    if( !isset( $coll ) ) {
        printf( "Collator creation failed: %s\n", intl_get_error_message() );
        exit( 1 );
    }
    ?>

### Siehe auch

- Collator::__construct() - Create a collator

# Collator::getAttribute

# collator_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getAttribute -- collator_get_attribute — Get collation attribute value

### Beschreibung

Objektorientierter Stil

public function Collator::getAttribute(int `$attribute`): int|false

Prozeduraler Stil

function collator_get_attribute(Collator `$object`, int `$attribute`): int|false

Get a value of an integer collator attribute.

### Parameter-Liste

`object`

  Collator object.

`attribute`

  Attribute to get value for.

### Rückgabewerte

Attribute value,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 collator_get_attribute() example

    <?php
    $coll = collator_create( 'en_CA' );
    $val = collator_get_attribute( $coll, Collator::NUMERIC_COLLATION );
    if( $val === false )
    {
        // Handle error.
    }
    ?>

### Siehe auch

- Collator constants
- collator_set_attribute() - Set collation attribute
- collator_get_strength() - Get current collation strength

# Collator::getErrorCode

# collator_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorCode -- collator_get_error_code — Get collator's last error code

### Beschreibung

Objektorientierter Stil

public function Collator::getErrorCode(): int|false

Prozeduraler Stil

function collator_get_error_code(Collator `$object`): int|false

### Parameter-Liste

`object`

  Collator object.

### Rückgabewerte

Error code returned by the last Collator API function call, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 collator_get_error_code() example

    <?php
    $coll = collator_create( 'en_US' );
    if( collator_get_attribute( $coll, Collator::FRENCH_COLLATION ) === false )
            handle_error( collator_get_error_code() );
    ?>

### Siehe auch

- collator_get_error_message() - Get text for collator's last error code

# Collator::getErrorMessage

# collator_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getErrorMessage -- collator_get_error_message — Get text for collator's last error code

### Beschreibung

Objektorientierter Stil

public function Collator::getErrorMessage(): string|false

Prozeduraler Stil

function collator_get_error_message(Collator `$object`): string|false

Retrieves the message for the last error.

### Parameter-Liste

`object`

  Collator object.

### Rückgabewerte

Description of an error occurred in the last Collator API function call, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 collator_get_error_message() example

    <?php
    $coll = collator_create( 'lt' );
    if( collator_compare( $coll, 'y', 'k' ) === false ) {
        echo collator_get_error_message( $coll );
    }
    ?>

### Siehe auch

- collator_get_error_code() - Get collator's last error code

# Collator::getLocale

# collator_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getLocale -- collator_get_locale — Get the locale name of the collator

### Beschreibung

Objektorientierter Stil

public function Collator::getLocale(int `$type`): string|false

Prozeduraler Stil

function collator_get_locale(Collator `$object`, int `$type`): string|false

Get collector locale name.

### Parameter-Liste

`object`

  Collator object.

`type`

  You can choose between valid and actual locale ( `Locale::VALID_LOCALE` and `Locale::ACTUAL_LOCALE`, respectively).

### Rückgabewerte

Real locale name from which the collation data comes. If the collator was instantiated from rules or an error occurred, returns `false`.

### Beispiele

Beispiel #1 collator_get_locale() example

    <?php
    $coll    = collator_create( 'en_US_California' );
    $res_val = collator_get_locale( $coll, Locale::VALID_LOCALE );
    $res_act = collator_get_locale( $coll, Locale::ACTUAL_LOCALE );
    printf( "Valid locale name: %s\nActual locale name: %s\n",
             $res_val, $res_act );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Requested locale name: en_US_California
    Valid locale name: en_US
    Actual locale name: en

### Siehe auch

- collator_create() - Create a collator

# Collator::getSortKey

# collator_get_sort_key

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 1.0.3)

Collator::getSortKey -- collator_get_sort_key — Get sorting key for a string

### Beschreibung

Objektorientierter Stil

public function Collator::getSortKey(string `$string`): string|false

Prozeduraler Stil

function collator_get_sort_key(Collator `$object`, string `$string`): string|false

Return collation key for a string. Collation keys can be compared directly instead of strings, though are implementation specific and may change between ICU library versions. Sort keys are generally only useful in databases or other circumstances where function calls are extremely expensive.

### Parameter-Liste

`object`

  Collator object.

`string`

  The string to produce the key from.

### Rückgabewerte

Returns the collation key for the string, Bei einem Fehler wird `false` zurückgegeben..

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Beispiele

Beispiel #1 collator_get_sort_key() example

    <?php

    $s1 = 'Hello';

    $coll = collator_create('en_US');
    $res  = collator_get_sort_key($coll, $s1);

    echo bin2hex($res);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

3832404046010901dc08

Beispiel #2 Collator::getSortKey() example with usort()

    <?php

    $data = [
        [ 'name' => '🇳🇱 Derick Rethans', 'linked_account' => 'https://phpc.social/users/derickr' ],
        [ 'name' => 'Elephpant', 'linked_account' => 'https://phpc.social/phpc' ],
        [ 'name' => '🇫🇷 Marcus Bointon', 'linked_account' => 'https://phpc.social/users/Synchro' ],
    ];

    /* Create the collator */
    $col = new Collator('en');

    /* Sort upper-case letters before lower-case letters */
    $col->setAttribute(Collator::CASE_FIRST, Collator::UPPER_FIRST);

    /* Use a user-defined function with sort, that strips out the emojis */
    usort(
        $data,
        function($a, $b) use ($col) {
            /* Remove the character class 'S' (the Symbols), and remove whitespace
             * (with trim) */
            $aName = trim(preg_replace('/\p{S}+/u', '', $a['name']));
            $bName = trim(preg_replace('/\p{S}+/u', '', $b['name']));

                                    /* Create the sort key */
            $aKey = $col->getSortKey($aName);
            $bKey = $col->getSortKey($bName);

                                    /* Use the sort key to signal which element sorts first */
            return $aKey <=> $bKey;
        }
    );

    var_dump($data);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

array(3) {
[0] =>
array(2) {
'name' =>
string(25) "🇳🇱 Derick Rethans"
'linked_account' =>
string(33) "https://phpc.social/users/derickr"
}
[1] =>
array(2) {
'name' =>
string(9) "Elephpant"
'linked_account' =>
string(24) "https://phpc.social/phpc"
}
[2] =>
array(2) {
'name' =>
string(25) "🇫🇷 Marcus Bointon"
'linked_account' =>
string(33) "https://phpc.social/users/Synchro"
}
}

### Siehe auch

- collator_sort() - Sort array using specified collator
- collator_sort_with_sort_keys() - Sort array using specified collator and sort keys

# Collator::getStrength

# collator_get_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getStrength -- collator_get_strength — Get current collation strength

### Beschreibung

Objektorientierter Stil

public function Collator::getStrength(): int

Prozeduraler Stil

function collator_get_strength(Collator `$object`): int

### Parameter-Liste

`object`

  Collator object.

### Rückgabewerte

Returns current collation strength,Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 collator_get_strength() example

    <?php
    $coll     = collator_create( 'en_US' );
    $strength = collator_get_strength( $coll );
    ?>

### Siehe auch

- Collator constants
- collator_set_strength() - Set collation strength
- collator_get_attribute() - Get collation attribute value

# Collator::setAttribute

# collator_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setAttribute -- collator_set_attribute — Set collation attribute

### Beschreibung

Objektorientierter Stil

public function Collator::setAttribute(int `$attribute`, int `$value`): bool

Prozeduraler Stil

function collator_set_attribute(Collator `$object`, int `$attribute`, int `$value`): bool

### Parameter-Liste

`object`

  Collator object.

`attribute`

  Attribute.

`value`

  Attribute value.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 collator_set_attribute() example

    <?php
    $coll = collator_create('en_CA');
    collator_set_attribute($coll, Collator::NORMALIZATION_MODE, Collator::ON);
    ?>

### Siehe auch

- Collator constants
- collator_get_attribute() - Get collation attribute value
- collator_set_strength() - Set collation strength

# Collator::setStrength

# collator_set_strength

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setStrength -- collator_set_strength — Set collation strength

### Beschreibung

Objektorientierter Stil

public function Collator::setStrength(int `$strength`): true

Prozeduraler Stil

function collator_set_strength(Collator `$object`, int `$strength`): true

The » ICU Collation Service supports many levels of comparison (named "Levels", but also known as "Strengths"). Having these categories enables ICU to sort strings precisely according to local conventions. However, by allowing the levels to be selectively employed, searching for a string in text can be performed with various matching conditions.

1. Primary Level: Typically, this is used to denote differences between base characters (for example, "a" < "b"). It is the strongest difference. For example, dictionaries are divided into different sections by base character. This is also called the `level 1` strength.

2. Secondary Level: Accents in the characters are considered secondary differences (for example, "as" < "às" < "at"). Other differences between letters can also be considered secondary differences, depending on the language. A secondary difference is ignored when there is a primary difference anywhere in the strings. This is also called the `level 2` strength.

   > Hinweis:

   > Note: In some languages (such as Danish), certain accented letters are considered to be separate base characters. In most languages, however, an accented letter only has a secondary difference from the unaccented version of that letter.

3. Tertiary Level: Upper and lower case differences in characters are distinguished at the tertiary level (for example, "ao" < "Ao" < "aò"). In addition, a variant of a letter differs from the base form on the tertiary level (such as "a" and "𝒶"). Another example is the difference between large and small Kana. A tertiary difference is ignored when there is a primary or secondary difference anywhere in the strings. This is also called the `level 3` strength.

4. Quaternary Level: When punctuation is ignored (see Ignoring Punctuations ) at levels 1-3, an additional level can be used to distinguish words with and without punctuation (for example, "ab" < "a-b" < "aB"). This difference is ignored when there is a primary, secondary or tertiary difference. This is also known as the `level 4` strength. The quaternary level should only be used if ignoring punctuation is required or when processing Japanese text (see Hiragana processing).

5. Identical Level: When all other levels are equal, the identical level is used as a tiebreaker. The Unicode code point values of the NFD form of each string are compared at this level, just in case there is no difference at levels 1-4. For example, Hebrew cantillation marks are only distinguished at this level. This level should be used sparingly, as only code point values differences between two strings is an extremely rare occurrence. Using this level substantially decreases the performance for both incremental comparison and sort key generation (as well as increasing the sort key length). It is also known as `level 5` strength.

For example, people may choose to ignore accents or ignore accents and case when searching for text. Almost all characters are distinguished by the first three levels, and in most locales the default value is thus Tertiary. However, if Alternate is set to be Shifted, then the Quaternary strength can be used to break ties among whitespace, punctuation, and symbols that would otherwise be ignored. If very fine distinctions among characters are required, then the Identical strength can be used (for example, Identical Strength distinguishes between the Mathematical Bold Small A and the Mathematical Italic Small A.). However, using levels higher than Tertiary the Identical strength result in significantly longer sort keys, and slower string comparison performance for equal strings.

### Parameter-Liste

`object`

  Collator object.

`strength`

  Strength to set.

  Possible values are:

  - `Collator::PRIMARY`

  - `Collator::SECONDARY`

  - `Collator::TERTIARY`

  - `Collator::QUATERNARY`

  - `Collator::IDENTICAL`

  - `Collator::DEFAULT_STRENGTH`

### Rückgabewerte

Gibt immer `true` zurück.

### Beispiele

Beispiel #1 collator_set_strength() example

    <?php
    $arr  = array( 'aò', 'Ao', 'ao' );
    $coll = collator_create( 'en_US' );

    // Sort array using default strength.
    collator_sort( $coll, $arr );
    var_export( $arr );

    // Sort array using primary strength.
    collator_set_strength( $coll, Collator::PRIMARY );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array (
      0 => 'ao',
      1 => 'Ao',
      2 => 'aò',
    )
    array (
      0 => 'aò',
      1 => 'Ao',
      2 => 'ao',
    )

### Siehe auch

- Collator constants
- collator_get_strength() - Get current collation strength

# Collator::sort

# collator_sort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sort -- collator_sort — Sort array using specified collator

### Beschreibung

Objektorientierter Stil

public function Collator::sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

Prozeduraler Stil

function collator_sort(Collator `$object`, array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

This function sorts an array according to current locale rules.

Equivalent to standard PHP sort() .

### Parameter-Liste

`object`

  Collator object.

`array`

  Array of strings to sort.

`flags`

  Optional sorting type, one of the following:

  - `Collator::SORT_REGULAR` - compare items normally (don't change types)

  - `Collator::SORT_NUMERIC` - compare items numerically

  - `Collator::SORT_STRING` - compare items as strings

  Default sorting type is `Collator::SORT_REGULAR`. It is also used if an invalid `flags` value has been specified.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 collator_sort() example

    <?php
    $coll = collator_create( 'en_US' );
    $arr  = array( 'at', 'às', 'as' );

    var_export( $arr );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array (
      0 => 'at',
      1 => 'às',
      2 => 'as',
    )array (
      0 => 'as',
      1 => 'às',
      2 => 'at',
    )

### Siehe auch

- Collator constants
- collator_asort() - Sort array maintaining index association
- collator_sort_with_sort_keys() - Sort array using specified collator and sort keys

# Collator::sortWithSortKeys

# collator_sort_with_sort_keys

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sortWithSortKeys -- collator_sort_with_sort_keys — Sort array using specified collator and sort keys

### Beschreibung

Objektorientierter Stil

public function Collator::sortWithSortKeys(array `&$array`): bool

Prozeduraler Stil

function collator_sort_with_sort_keys(Collator `$object`, array `&$array`): bool

Similar to collator_sort() but uses ICU sorting keys produced by ucol_getSortKey() to gain more speed on large arrays.

### Parameter-Liste

`object`

  Collator object.

`array`

  Array of strings to sort

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 collator_sort_with_sort_keys() example

    <?php
    $arr  = array( 'Köpfe', 'Kypper', 'Kopfe' );
    $coll = collator_create( 'sv' );

    collator_sort_with_sort_keys( $coll, $arr );
    var_export( $arr );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array (
      0 => 'Kopfe',
      1 => 'Kypper',
      2 => 'Köpfe',
    )

### Siehe auch

- Collator constants
- collator_sort() - Sort array using specified collator
- collator_asort() - Sort array maintaining index association

## Inhaltsverzeichnis

- Collator::asort — Sort array maintaining index association
- Collator::compare — Compare two Unicode strings
- Collator::__construct — Create a collator
- Collator::create — Create a collator
- Collator::getAttribute — Get collation attribute value
- Collator::getErrorCode — Get collator's last error code
- Collator::getErrorMessage — Get text for collator's last error code
- Collator::getLocale — Get the locale name of the collator
- Collator::getSortKey — Get sorting key for a string
- Collator::getStrength — Get current collation strength
- Collator::setAttribute — Set collation attribute
- Collator::setStrength — Set collation strength
- Collator::sort — Sort array using specified collator
- Collator::sortWithSortKeys — Sort array using specified collator and sort keys

# The NumberFormatter class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Einführung

Programs store and operate on numbers using a locale-independent binary representation. When displaying or printing a number it is converted to a locale-specific string. For example, the number 12345.67 is "12,345.67" in the US, "12 345,67" in France and "12.345,67" in Germany.

By invoking the methods provided by the NumberFormatter class, you can format numbers, currencies, and percentages according to the specified or default locale. NumberFormatter is locale-sensitive so you need to create a new NumberFormatter for each locale. NumberFormatter methods format primitive-type numbers, such as double and output the number as a locale-specific string.

For currencies you can use currency format type to create a formatter that returns a string with the formatted number and the appropriate currency sign. Of course, the NumberFormatter class is unaware of exchange rates so, the number output is the same regardless of the specified currency. This means that the same number has different monetary values depending on the currency locale. If the number is 9988776.65 the results will be:

- 9 988 776,65 € in France
- 9.988.776,65 € in Germany
- $9,988,776.65 in the United States

In order to format percentages, create a locale-specific formatter with percentage format type. With this formatter, a decimal fraction such as 0.75 is displayed as 75%.

For more complex formatting, like spelled-out numbers, the rule-based number formatters are used.

## Klassenbeschreibung

class NumberFormatter {
/* Konstanten */
public const int PATTERN_DECIMAL;
public const int DECIMAL;
public const int DECIMAL_COMPACT_SHORT;
public const int DECIMAL_COMPACT_LONG;
public const int CURRENCY;
public const int PERCENT;
public const int SCIENTIFIC;
public const int SPELLOUT;
public const int ORDINAL;
public const int DURATION;
public const int PATTERN_RULEBASED;
public const int IGNORE;
public const int CURRENCY_ISO;
public const int CURRENCY_PLURAL;
public const int CURRENCY_ACCOUNTING;
public const int CASH_CURRENCY;
public const int CURRENCY_STANDARD;
public const int DEFAULT_STYLE;
public const int ROUND_CEILING;
public const int ROUND_FLOOR;
public const int ROUND_DOWN;
public const int ROUND_UP;
public const int ROUND_TOWARD_ZERO;
public const int ROUND_AWAY_FROM_ZERO;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFODD;
public const int ROUND_HALFDOWN;
public const int ROUND_HALFUP;
public const int PAD_BEFORE_PREFIX;
public const int PAD_AFTER_PREFIX;
public const int PAD_BEFORE_SUFFIX;
public const int PAD_AFTER_SUFFIX;
public const int PARSE_INT_ONLY;
public const int GROUPING_USED;
public const int DECIMAL_ALWAYS_SHOWN;
public const int MAX_INTEGER_DIGITS;
public const int MIN_INTEGER_DIGITS;
public const int INTEGER_DIGITS;
public const int MAX_FRACTION_DIGITS;
public const int MIN_FRACTION_DIGITS;
public const int FRACTION_DIGITS;
public const int MULTIPLIER;
public const int GROUPING_SIZE;
public const int ROUNDING_MODE;
public const int ROUNDING_INCREMENT;
public const int FORMAT_WIDTH;
public const int PADDING_POSITION;
public const int SECONDARY_GROUPING_SIZE;
public const int SIGNIFICANT_DIGITS_USED;
public const int MIN_SIGNIFICANT_DIGITS;
public const int MAX_SIGNIFICANT_DIGITS;
public const int LENIENT_PARSE;
public const int POSITIVE_PREFIX;
public const int POSITIVE_SUFFIX;
public const int NEGATIVE_PREFIX;
public const int NEGATIVE_SUFFIX;
public const int PADDING_CHARACTER;
public const int CURRENCY_CODE;
public const int DEFAULT_RULESET;
public const int PUBLIC_RULESETS;
public const int DECIMAL_SEPARATOR_SYMBOL;
public const int GROUPING_SEPARATOR_SYMBOL;
public const int PATTERN_SEPARATOR_SYMBOL;
public const int PERCENT_SYMBOL;
public const int ZERO_DIGIT_SYMBOL;
public const int DIGIT_SYMBOL;
public const int MINUS_SIGN_SYMBOL;
public const int PLUS_SIGN_SYMBOL;
public const int CURRENCY_SYMBOL;
public const int INTL_CURRENCY_SYMBOL;
public const int MONETARY_SEPARATOR_SYMBOL;
public const int EXPONENTIAL_SYMBOL;
public const int PERMILL_SYMBOL;
public const int PAD_ESCAPE_SYMBOL;
public const int INFINITY_SYMBOL;
public const int NAN_SYMBOL;
public const int SIGNIFICANT_DIGIT_SYMBOL;
public const int MONETARY_GROUPING_SEPARATOR_SYMBOL;
public const int TYPE_DEFAULT;
public const int TYPE_INT32;
public const int TYPE_INT64;
public const int TYPE_DOUBLE;
public const int TYPE_CURRENCY;
/* Methoden */
public function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function setTextAttribute(int `$attribute`, string `$value`): bool
}

## Vordefinierte Konstanten

## Format Types

These styles are used by the numfmt_create() to define the type of the formatter.

`NumberFormatter::PATTERN_DECIMAL` int
  Decimal format defined by pattern
`NumberFormatter::DECIMAL` int
  Decimal format
`NumberFormatter::DECIMAL_COMPACT_SHORT` int
  Decimal format expressed using compact notation (short form), e.g. "23K", "45B". Available as of PHP 8.5.0 and ICU 56.
`NumberFormatter::DECIMAL_COMPACT_LONG` int
  Decimal format expressed using compact notation (long form), e.g. "23 thousand", "45 billion". Available as of PHP 8.5.0 and ICU 56.
`NumberFormatter::CURRENCY` int
  Currency format
`NumberFormatter::CURRENCY_ISO` int
  ISO currency format (e.g., "USD1.00"). Available as of PHP 8.5.0.
`NumberFormatter::CURRENCY_PLURAL` int
  Pluralized currency format (e.g., "1.00 US dollar" and "3.00 US dollars"). Available as of PHP 8.5.0.
`NumberFormatter::CASH_CURRENCY` int
  Currency symbol given CASH usage, e.g., "NT$3" instead of "NT$3.23". Available as of PHP 8.5.0 and ICU 54
`NumberFormatter::CURRENCY_STANDARD` int
  Currency symbol, e.g., "$1.00", using non-accounting style for negative values (e.g. minus sign). Available as of PHP 8.5.0 and ICU 56.
`NumberFormatter::PERCENT` int
  Percent format
`NumberFormatter::SCIENTIFIC` int
  Scientific format
`NumberFormatter::SPELLOUT` int
  Spellout rule-based format
`NumberFormatter::ORDINAL` int
  Ordinal rule-based format
`NumberFormatter::DURATION` int
  Duration rule-based format
`NumberFormatter::PATTERN_RULEBASED` int
  Rule-based format defined by pattern
`NumberFormatter::CURRENCY_ACCOUNTING` int
  Currency format for accounting, e.g., `($3.00)` for negative currency amount instead of `-$3.00`. Available as of PHP 7.4.1 and ICU 53.
`NumberFormatter::DEFAULT_STYLE` int
  Default format for the locale
`NumberFormatter::IGNORE` int
  Alias for PATTERN_DECIMAL

## Number Format Specifiers

These constants define how the numbers are parsed or formatted. They should be used as arguments to numfmt_format() and numfmt_parse().

`NumberFormatter::TYPE_DEFAULT` int
  Derive the type from variable type
`NumberFormatter::TYPE_INT32` int
  Format/parse as 32-bit integer
`NumberFormatter::TYPE_INT64` int
  Format/parse as 64-bit integer
`NumberFormatter::TYPE_DOUBLE` int
  Format/parse as floating point value
`NumberFormatter::TYPE_CURRENCY` int
  Format/parse as currency value. Deprecated as of PHP 8.3.0

## Number Format Attributes

Number format attribute used by numfmt_get_attribute() and numfmt_set_attribute().

`NumberFormatter::PARSE_INT_ONLY` int
  Parse integers only.
`NumberFormatter::GROUPING_USED` int
  Use grouping separator.
`NumberFormatter::DECIMAL_ALWAYS_SHOWN` int
  Always show decimal point.
`NumberFormatter::MAX_INTEGER_DIGITS` int
  Maximum integer digits.
`NumberFormatter::MIN_INTEGER_DIGITS` int
  Minimum integer digits.
`NumberFormatter::INTEGER_DIGITS` int
  Integer digits.
`NumberFormatter::MAX_FRACTION_DIGITS` int
  Maximum fraction digits.
`NumberFormatter::MIN_FRACTION_DIGITS` int
  Minimum fraction digits.
`NumberFormatter::FRACTION_DIGITS` int
  Fraction digits.
`NumberFormatter::MULTIPLIER` int
  Multiplier.
`NumberFormatter::GROUPING_SIZE` int
  Grouping size.
`NumberFormatter::ROUNDING_MODE` int
  Rounding Mode.
`NumberFormatter::ROUNDING_INCREMENT` int
  Rounding increment.
`NumberFormatter::FORMAT_WIDTH` int
  The width to which the output of format() is padded.
`NumberFormatter::PADDING_POSITION` int
  The position at which padding will take place. See pad position constants for possible argument values.
`NumberFormatter::SECONDARY_GROUPING_SIZE` int
  Secondary grouping size.
`NumberFormatter::SIGNIFICANT_DIGITS_USED` int
  Use significant digits.
`NumberFormatter::MIN_SIGNIFICANT_DIGITS` int
  Minimum significant digits.
`NumberFormatter::MAX_SIGNIFICANT_DIGITS` int
  Maximum significant digits.
`NumberFormatter::LENIENT_PARSE` int
  Lenient parse mode used by rule-based formats.

## Number Format Text Attributes

Number format text attribute used by numfmt_get_text_attribute() and numfmt_set_text_attribute().

`NumberFormatter::POSITIVE_PREFIX` int
  Positive prefix.
`NumberFormatter::POSITIVE_SUFFIX` int
  Positive suffix.
`NumberFormatter::NEGATIVE_PREFIX` int
  Negative prefix.
`NumberFormatter::NEGATIVE_SUFFIX` int
  Negative suffix.
`NumberFormatter::PADDING_CHARACTER` int
  The character used to pad to the format width.
`NumberFormatter::CURRENCY_CODE` int
  The ISO currency code.
`NumberFormatter::DEFAULT_RULESET` int
  The default rule set. This is only available with rule-based formatters.
`NumberFormatter::PUBLIC_RULESETS` int
  The public rule sets. This is only available with rule-based formatters. This is a read-only attribute. The public rulesets are returned as a single string, with each ruleset name delimited by ';' (semicolon).

## Symbol Format Specifiers

Number format symbols used by numfmt_get_symbol() and numfmt_set_symbol().

`NumberFormatter::DECIMAL_SEPARATOR_SYMBOL` int
  The decimal separator.
`NumberFormatter::GROUPING_SEPARATOR_SYMBOL` int
  The grouping separator.
`NumberFormatter::PATTERN_SEPARATOR_SYMBOL` int
  The pattern separator.
`NumberFormatter::PERCENT_SYMBOL` int
  The percent sign.
`NumberFormatter::ZERO_DIGIT_SYMBOL` int
  Zero.
`NumberFormatter::DIGIT_SYMBOL` int
  Character representing a digit in the pattern.
`NumberFormatter::MINUS_SIGN_SYMBOL` int
  The minus sign.
`NumberFormatter::PLUS_SIGN_SYMBOL` int
  The plus sign.
`NumberFormatter::CURRENCY_SYMBOL` int
  The currency symbol.
`NumberFormatter::INTL_CURRENCY_SYMBOL` int
  The international currency symbol.
`NumberFormatter::MONETARY_SEPARATOR_SYMBOL` int
  The monetary separator.
`NumberFormatter::EXPONENTIAL_SYMBOL` int
  The exponential symbol.
`NumberFormatter::PERMILL_SYMBOL` int
  Per mill symbol.
`NumberFormatter::PAD_ESCAPE_SYMBOL` int
  Escape padding character.
`NumberFormatter::INFINITY_SYMBOL` int
  Infinity symbol.
`NumberFormatter::NAN_SYMBOL` int
  Not-a-number symbol.
`NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL` int
  Significant digit symbol.
`NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL` int
  The monetary grouping separator.

## Rounding Modes

Rounding mode values used by numfmt_get_attribute() and numfmt_set_attribute() with `NumberFormatter::ROUNDING_MODE` attribute.

`NumberFormatter::ROUND_AWAY_FROM_ZERO`
  Alias von `NumberFormatter::ROUND_UP`.
`NumberFormatter::ROUND_CEILING` int
  Rounding mode to round towards positive infinity.
`NumberFormatter::ROUND_DOWN` int
  Rounding mode to round towards zero.
`NumberFormatter::ROUND_FLOOR` int
  Rounding mode to round towards negative infinity.
`NumberFormatter::ROUND_HALFDOWN` int
  Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down.
`NumberFormatter::ROUND_HALFEVEN` int
  Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor.
`NumberFormatter::ROUND_HALFODD`
  Rounding mode to round towards the "odd neighbor".
`NumberFormatter::ROUND_HALFUP` int
  Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up.
`NumberFormatter::ROUND_TOWARD_ZERO`
  Alias von `NumberFormatter::ROUND_DOWN`.
`NumberFormatter::ROUND_UP` int
  Rounding mode to round away from zero.

## Padding Specifiers

Pad position values used by numfmt_get_attribute() and numfmt_set_attribute() with `NumberFormatter::PADDING_POSITION` attribute.

`NumberFormatter::PAD_AFTER_PREFIX` int
  Pad characters inserted after the prefix.
`NumberFormatter::PAD_AFTER_SUFFIX` int
  Pad characters inserted after the suffix.
`NumberFormatter::PAD_BEFORE_PREFIX` int
  Pad characters inserted before the prefix.
`NumberFormatter::PAD_BEFORE_SUFFIX` int
  Pad characters inserted before the suffix.

## Siehe auch

- » ICU formatting documentation
- » ICU number formatters
- » ICU decimal formatters
- » ICU rule-based number formatters

## Changelog

Version | Beschreibung
--- | ---
8.5.0 | Added `NumberFormatter::DECIMAL_COMPACT_SHORT`, `NumberFormatter::DECIMAL_COMPACT_LONG`, `NumberFormatter::CURRENCY_ISO`, `NumberFormatter::CURRENCY_PLURAL`, `NumberFormatter::CASH_CURRENCY`, `NumberFormatter::CURRENCY_STANDARD`.
8.4.0 | The class constants are now typed.

# NumberFormatter::create

# numfmt_create

# NumberFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::create -- numfmt_create -- NumberFormatter::__construct — Create a number formatter

### Beschreibung

Objektorientierter Stil (method)

public static function NumberFormatter::create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Prozeduraler Stil

function numfmt_create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

Objektorientierter Stil (constructor):

public function NumberFormatter::__construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)

Creates a number formatter.

### Parameter-Liste

`locale`

  Locale in which the number would be formatted (locale name, e.g. en_CA).

`style`

  Style of the formatting, one of the format style constants. If `NumberFormatter::PATTERN_DECIMAL` or `NumberFormatter::PATTERN_RULEBASED` is passed then the number format is opened using the given pattern, which must conform to the syntax described in » ICU DecimalFormat documentation or » ICU RuleBasedNumberFormat documentation, respectively.

`pattern`

  Pattern string if the chosen style requires a pattern.

### Rückgabewerte

Returns NumberFormatter object or `null` on error.

### Fehler/Exceptions

A ValueError is thrown if `locale` is invalid.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | A ValueError is thrown if `locale` is invalid.
8.0.0 | `pattern` is nullable now.

### Beispiele

Beispiel #1 numfmt_create() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    $fmt = numfmt_create( 'it', NumberFormatter::SPELLOUT );
    echo numfmt_format($fmt, 1142)."\n";
    ?>

Beispiel #2 NumberFormatter::create() example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt = new NumberFormatter( 'it', NumberFormatter::SPELLOUT );
    echo $fmt->format(1142)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1.234.567,891
    millicentoquarantadue

### Siehe auch

- numfmt_format() - Format a number
- numfmt_parse() - Parse a number

# NumberFormatter::format

# numfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::format -- numfmt_format — Format a number

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Prozeduraler Stil

function numfmt_format(NumberFormatter `$formatter`, int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

Format a numeric value according to the formatter rules.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`num`

  The value to format. Can be int or float, other values will be converted to a numeric value.

`type`

  The formatting type to use. Note that `NumberFormatter::TYPE_CURRENCY` is not supported; use NumberFormatter::formatCurrency() instead.

### Rückgabewerte

Returns the string containing formatted value, or `false` on error.

### Beispiele

Beispiel #1 numfmt_format() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    var_dump($data);
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $data = $fmt->format(1234567.891234567890000);
    var_dump($data);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(13) "1.234.567,891"

### Anmerkungen

> Hinweis:

> Formats achievable by this method of formatting cannot fully use the possibilities of underlying ICU library, such as to format currency with narrow currency symbol.

> To fully utilize them use msgfmt_format_message().

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_format_currency() - Format a currency value
- numfmt_parse() - Parse a number
- msgfmt_format_message() - Quick format message

# NumberFormatter::formatCurrency

# numfmt_format_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::formatCurrency -- numfmt_format_currency — Format a currency value

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::formatCurrency(float `$amount`, string `$currency`): string|false

Prozeduraler Stil

function numfmt_format_currency(NumberFormatter `$formatter`, float `$amount`, string `$currency`): string|false

Format the currency value according to the formatter rules.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`amount`

  The numeric currency value.

`currency`

  The 3-letter ISO 4217 currency code indicating the currency to use.

### Rückgabewerte

String representing the formatted currency value, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 numfmt_format_currency() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    $fmt = numfmt_create( 'ru_RU', NumberFormatter::CURRENCY );
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "EUR")."\n";
    echo numfmt_format_currency($fmt, 1234567.891234567890000, "RUR")."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    $fmt = new NumberFormatter( 'ru_RU', NumberFormatter::CURRENCY );
    echo $fmt->formatCurrency(1234567.891234567890000, "EUR")."\n";
    echo $fmt->formatCurrency(1234567.891234567890000, "RUR")."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1.234.567,89 €
    1.234.567,89 RUR
    1 234 567,89€
    1 234 567,89р.

### Anmerkungen

> Hinweis:

> Formats achievable by this method of formatting cannot fully use the possibilities of underlying ICU library, such as to format currency with narrow currency symbol.

> To fully utilize them use msgfmt_format_message().

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_format() - Format a number
- numfmt_parse_currency() - Parse a currency number
- msgfmt_format_message() - Quick format message

# NumberFormatter::getAttribute

# numfmt_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getAttribute -- numfmt_get_attribute — Get an attribute

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::getAttribute(int `$attribute`): int|float|false

Prozeduraler Stil

function numfmt_get_attribute(NumberFormatter `$formatter`, int `$attribute`): int|float|false

Get a numeric attribute associated with the formatter. An example of a numeric attribute is the number of integer digits the formatter will produce.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`attribute`

  Attribute specifier - one of the numeric attribute constants.

### Rückgabewerte

Return attribute value on success, or `false` on error.

### Beispiele

Beispiel #1 numfmt_get_attribute() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Digits: 3
    1.234.567,891
    Digits: 2
    1.234.567,89

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_get_text_attribute() - Get a text attribute
- numfmt_set_attribute() - Set an attribute

# NumberFormatter::getErrorCode

# numfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorCode -- numfmt_get_error_code — Get formatter's last error code

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::getErrorCode(): int

Prozeduraler Stil

function numfmt_get_error_code(NumberFormatter `$formatter`): int

Get error code from the last function performed by the formatter.

### Parameter-Liste

`formatter`

  NumberFormatter object.

### Rückgabewerte

Returns error code from last formatter call.

### Beispiele

Beispiel #1 numfmt_get_error_code() example

    <?php
    $fmt  = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    if (intl_is_failure(numfmt_get_error_code($fmt))) {
        echo 'Formatter error';
    }
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    if (intl_is_failure($fmt->getErrorCode())) {
        echo 'Formatter error';
    }
    ?>

### Siehe auch

- numfmt_get_error_message() - Get formatter's last error message
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure

# NumberFormatter::getErrorMessage

# numfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getErrorMessage -- numfmt_get_error_message — Get formatter's last error message

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::getErrorMessage(): string

Prozeduraler Stil

function numfmt_get_error_message(NumberFormatter `$formatter`): string

Get error message from the last function performed by the formatter.

### Parameter-Liste

`formatter`

  NumberFormatter object.

### Rückgabewerte

Returns error message from last formatter call.

### Beispiele

Beispiel #1 numfmt_get_error_message() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $data = numfmt_format($fmt, 1234567.891234567890000);
    var_dump(numfmt_get_error_message($fmt));
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    var_dump(numfmt_get_error_message($fmt));
    ?>

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure

# NumberFormatter::getLocale

# numfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getLocale -- numfmt_get_locale — Get formatter locale

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Prozeduraler Stil

function numfmt_get_locale(NumberFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Get formatter locale name.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`type`

  You can choose between valid and actual locale ( `Locale::VALID_LOCALE`, `Locale::ACTUAL_LOCALE`, respectively). The default is the actual locale.

### Rückgabewerte

The locale name used to create the formatter, or `false` on failure.

### Beispiele

Beispiel #1 numfmt_get_locale() example

    <?php
    $req     = 'fr_FR_PARIS';
    $fmt     = numfmt_create( $req,  NumberFormatter::DECIMAL);
    $res_val = numfmt_get_locale( $fmt, Locale::VALID_LOCALE );
    $res_act = numfmt_get_locale( $fmt, Locale::ACTUAL_LOCALE );
    printf( "Requested locale name: %s\nValid locale name: %s\nActual locale name: %s\n",
             $req, $res_val, $res_act );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Requested locale name: fr_FR_PARIS
    Valid locale name: fr_FR
    Actual locale name: fr

### Siehe auch

- numfmt_create() - Create a number formatter
- numfmt_get_error_code() - Get formatter's last error code

# NumberFormatter::getPattern

# numfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getPattern -- numfmt_get_pattern — Get formatter pattern

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::getPattern(): string|false

Prozeduraler Stil

function numfmt_get_pattern(NumberFormatter `$formatter`): string|false

Extract pattern used by the formatter.

### Parameter-Liste

`formatter`

  NumberFormatter object.

### Rückgabewerte

Pattern string that is used by the formatter, or `false` if an error happens.

### Beispiele

Beispiel #1 numfmt_get_pattern() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Pattern: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Pattern: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Pattern: #,##0.###
    1.234.567,891
    Pattern: #0.# kg
    1234567,9 kg

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_set_pattern() - Set formatter pattern
- numfmt_create() - Create a number formatter

# NumberFormatter::getSymbol

# numfmt_get_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getSymbol -- numfmt_get_symbol — Get a symbol value

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::getSymbol(int `$symbol`): string|false

Prozeduraler Stil

function numfmt_get_symbol(NumberFormatter `$formatter`, int `$symbol`): string|false

Get a symbol associated with the formatter. The formatter uses symbols to represent the special locale-dependent characters in a number, for example the percent sign. This API is not supported for rule-based formatters.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`symbol`

  Symbol specifier, one of the format symbol constants.

### Rückgabewerte

The symbol string or `false` on error.

### Beispiele

Beispiel #1 numfmt_get_symbol() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Sep: .
    1.234.567,891
    Sep: *
    1*234*567,891

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_set_symbol() - Set a symbol value

# NumberFormatter::getTextAttribute

# numfmt_get_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getTextAttribute -- numfmt_get_text_attribute — Get a text attribute

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::getTextAttribute(int `$attribute`): string|false

Prozeduraler Stil

function numfmt_get_text_attribute(NumberFormatter `$formatter`, int `$attribute`): string|false

Get a text attribute associated with the formatter. An example of a text attribute is the suffix for positive numbers. If the formatter does not understand the attribute, `U_UNSUPPORTED_ERROR` error is produced. Rule-based formatters only understand `NumberFormatter::DEFAULT_RULESET` and `NumberFormatter::PUBLIC_RULESETS`.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`attribute`

  Attribute specifier - one of the text attribute constants.

### Rückgabewerte

Return attribute value on success, or `false` on error.

### Beispiele

Beispiel #1 numfmt_get_text_attribute() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Prefix: -
    -1.234.567,891
    Prefix: MINUS
    MINUS1.234.567,891

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_get_attribute() - Get an attribute
- numfmt_set_text_attribute() - Set a text attribute

# NumberFormatter::parse

# numfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parse -- numfmt_parse — Parse a number

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false

Prozeduraler Stil

function numfmt_parse(
NumberFormatter `$formatter`,
string `$string`,
int `$type` = `NumberFormatter::TYPE_DOUBLE`,
int `&$offset` = `null`
): int|float|false

Parse a string into a number using the current formatter rules.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`string`

  The string to parse for the number.

`type`

  The formatting type to use. By default, `NumberFormatter::TYPE_DOUBLE` is used. Note that `NumberFormatter::TYPE_CURRENCY` is not supported; use NumberFormatter::parseCurrency() instead.

`offset`

  Offset in the string at which to begin parsing. On return, this value will hold the offset at which parsing ended.

### Rückgabewerte

The value of the parsed number or `false` on error.

### Beispiele

Beispiel #1 numfmt_parse() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo numfmt_parse($fmt, $num)."\n";
    echo numfmt_parse($fmt, $num, NumberFormatter::TYPE_INT32)."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $num = "1.234.567,891";
    echo $fmt->parse($num)."\n";
    echo $fmt->parse($num, NumberFormatter::TYPE_INT32)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1234567.891
    1234567

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_format() - Format a number
- numfmt_parse_currency() - Parse a currency number

# NumberFormatter::parseCurrency

# numfmt_parse_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parseCurrency -- numfmt_parse_currency — Parse a currency number

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false

Prozeduraler Stil

function numfmt_parse_currency(
NumberFormatter `$formatter`,
string `$string`,
string `&$currency`,
int `&$offset` = `null`
): float|false

Parse a string into a float and a currency using the current formatter.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`currency`

  Parameter to receive the currency name (3-letter ISO 4217 currency code).

`offset`

  Offset in the string at which to begin parsing. On return, this value will hold the offset at which parsing ended.

### Rückgabewerte

The parsed numeric value or `false` on error.

### Beispiele

Beispiel #1 numfmt_parse_currency() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "We have ".numfmt_parse_currency($fmt, $num, $curr)." in $curr\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::CURRENCY );
    $num = "1.234.567,89\xc2\xa0$";
    echo "We have ".$fmt->parseCurrency($num, $curr)." in $curr\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    We have 1234567.89 in USD

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_parse() - Parse a number
- numfmt_format_currency() - Format a currency value

# NumberFormatter::setAttribute

# numfmt_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setAttribute -- numfmt_set_attribute — Set an attribute

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::setAttribute(int `$attribute`, int|float `$value`): bool

Prozeduraler Stil

function numfmt_set_attribute(NumberFormatter `$formatter`, int `$attribute`, int|float `$value`): bool

Set a numeric attribute associated with the formatter. An example of a numeric attribute is the number of integer digits the formatter will produce.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`attribute`

  Attribute specifier - one of the numeric attribute constants.

`value`

  The attribute value.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 numfmt_set_attribute() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Digits: ".numfmt_get_attribute($fmt, NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
    echo "Digits: ".$fmt->getAttribute(NumberFormatter::MAX_FRACTION_DIGITS)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Digits: 3
    1.234.567,891
    Digits: 2
    1.234.567,89

Beispiel #3 Using `NumberFormatter::ROUNDING_MODE` to truncate values

By default, NumberFormatter rounds values. Using `NumberFormatter::ROUND_DOWN` as the `NumberFormatter::ROUNDING_MODE` truncates the value to the specified number of fraction digits without rounding.

    <?php
    $fmt = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    $fmt->setAttribute(NumberFormatter::FRACTION_DIGITS, 2);

    echo "Default rounding mode:\n";
    echo $fmt->format(3.789), "\n"; // 3.79 (rounded up)
    echo $fmt->format(3.781), "\n"; // 3.78 (rounded down)

    $fmt->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_DOWN);

    echo "\nWith ROUND_DOWN (truncate):\n";
    echo $fmt->format(3.789), "\n"; // 3.78 (truncated)
    echo $fmt->format(3.781), "\n"; // 3.78 (truncated)
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Default rounding mode:
    3.79
    3.78

    With ROUND_DOWN (truncate):
    3.78
    3.78

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_get_attribute() - Get an attribute
- numfmt_set_text_attribute() - Set a text attribute

# NumberFormatter::setPattern

# numfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setPattern -- numfmt_set_pattern — Set formatter pattern

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::setPattern(string `$pattern`): bool

Prozeduraler Stil

function numfmt_set_pattern(NumberFormatter `$formatter`, string `$pattern`): bool

Set the pattern used by the formatter. Can not be used on a rule-based formatter.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`pattern`

  Pattern in syntax described in » ICU DecimalFormat documentation.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 numfmt_set_pattern() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_pattern($fmt, "#0.# kg");
    echo "Pattern: ".numfmt_get_pattern($fmt)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Pattern: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setPattern("#0.# kg");
    echo "Pattern: ".$fmt->getPattern()."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Pattern: #,##0.###
    1.234.567,891
    Pattern: #0.# kg
    1234567,9 kg

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_create() - Create a number formatter
- numfmt_get_pattern() - Get formatter pattern

# NumberFormatter::setSymbol

# numfmt_set_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setSymbol -- numfmt_set_symbol — Set a symbol value

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::setSymbol(int `$symbol`, string `$value`): bool

Prozeduraler Stil

function numfmt_set_symbol(NumberFormatter `$formatter`, int `$symbol`, string `$value`): bool

Set a symbol associated with the formatter. The formatter uses symbols to represent the special locale-dependent characters in a number, for example the percent sign. This API is not supported for rule-based formatters.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`symbol`

  Symbol specifier, one of the format symbol constants.

`value`

  Text for the symbol.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 numfmt_set_symbol() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    numfmt_set_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Sep: ".numfmt_get_symbol($fmt, NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo numfmt_format($fmt, 1234567.891234567890000)."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    $fmt->setSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL, "*");
    echo "Sep: ".$fmt->getSymbol(NumberFormatter::GROUPING_SEPARATOR_SYMBOL)."\n";
    echo $fmt->format(1234567.891234567890000)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Sep: .
    1.234.567,891
    Sep: *
    1*234*567,891

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_get_symbol() - Get a symbol value

# NumberFormatter::setTextAttribute

# numfmt_set_text_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setTextAttribute -- numfmt_set_text_attribute — Set a text attribute

### Beschreibung

Objektorientierter Stil

public function NumberFormatter::setTextAttribute(int `$attribute`, string `$value`): bool

Prozeduraler Stil

function numfmt_set_text_attribute(NumberFormatter `$formatter`, int `$attribute`, string `$value`): bool

Set a text attribute associated with the formatter. An example of a text attribute is the suffix for positive numbers. If the formatter does not understand the attribute, `U_UNSUPPORTED_ERROR` error is produced. Rule-based formatters only understand `NumberFormatter::DEFAULT_RULESET` and `NumberFormatter::PUBLIC_RULESETS`.

### Parameter-Liste

`formatter`

  NumberFormatter object.

`attribute`

  Attribute specifier - one of the text attribute constants.

`value`

  Text for the attribute value.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 numfmt_set_text_attribute() example

    <?php
    $fmt = numfmt_create( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    numfmt_set_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefix: ".numfmt_get_text_attribute($fmt, NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo numfmt_format($fmt, -1234567.891234567890000)."\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    $fmt->setTextAttribute(NumberFormatter::NEGATIVE_PREFIX, "MINUS");
    echo "Prefix: ".$fmt->getTextAttribute(NumberFormatter::NEGATIVE_PREFIX)."\n";
    echo $fmt->format(-1234567.891234567890000)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Prefix: -
    -1.234.567,891
    Prefix: MINUS
    MINUS1.234.567,891

### Siehe auch

- numfmt_get_error_code() - Get formatter's last error code
- numfmt_get_text_attribute() - Get a text attribute
- numfmt_set_attribute() - Set an attribute

## Inhaltsverzeichnis

- NumberFormatter::create — Create a number formatter
- NumberFormatter::format — Format a number
- NumberFormatter::formatCurrency — Format a currency value
- NumberFormatter::getAttribute — Get an attribute
- NumberFormatter::getErrorCode — Get formatter's last error code
- NumberFormatter::getErrorMessage — Get formatter's last error message
- NumberFormatter::getLocale — Get formatter locale
- NumberFormatter::getPattern — Get formatter pattern
- NumberFormatter::getSymbol — Get a symbol value
- NumberFormatter::getTextAttribute — Get a text attribute
- NumberFormatter::parse — Parse a number
- NumberFormatter::parseCurrency — Parse a currency number
- NumberFormatter::setAttribute — Set an attribute
- NumberFormatter::setPattern — Set formatter pattern
- NumberFormatter::setSymbol — Set a symbol value
- NumberFormatter::setTextAttribute — Set a text attribute

# The Locale class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Einführung

A "Locale" is an identifier used to get language, culture, or regionally-specific behavior from an API. PHP locales are organized and identified the same way that the CLDR locales used by ICU (and many vendors of Unix-like operating systems, the Mac, Java, and so forth) use. Locales are identified using RFC 4646 language tags (which use hyphen, not underscore) in addition to the more traditional underscore-using identifiers. Unless otherwise noted the functions in this class are tolerant of both formats.

Examples of identifiers include:

- en-US (English, United States)
- zh-Hant-TW (Chinese, Traditional Script, Taiwan)
- fr-CA, fr-FR (French for Canada and France respectively)

The Locale class (and related procedural functions) are used to interact with locale identifiers--to verify that an ID is well-formed, valid, etc. The extensions used by CLDR in UAX #35 (and inherited by ICU) are valid and used wherever they would be in ICU normally.

Locales cannot be instantiated as objects. All of the functions/methods provided are static.

The null or empty string obtains the "root" locale. The "root" locale is equivalent to "en_US_POSIX" in CLDR. Language tags (and thus locale identifiers) are case insensitive. There exists a canonicalization function to make case match the specification.

## Klassenbeschreibung

class Locale {
/* Konstanten */
public const int ACTUAL_LOCALE;
public const int VALID_LOCALE;
public const null DEFAULT_LOCALE = null;
public const string LANG_TAG;
public const string EXTLANG_TAG;
public const string SCRIPT_TAG;
public const string REGION_TAG;
public const string VARIANT_TAG;
public const string GRANDFATHERED_LANG_TAG;
public const string PRIVATE_TAG;
/* Methoden */
public static function acceptFromHttp(string `$header`): string|false
public static function canonicalize(string `$locale`): ?string
public static function composeLocale(array `$subtags`): string|false
public static function filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool
public static function getAllVariants(string `$locale`): ?array
public static function getDefault(): string
public static function getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getKeywords(string `$locale`): array|false|null
public static function getPrimaryLanguage(string `$locale`): ?string
public static function getRegion(string `$locale`): ?string
public static function getScript(string `$locale`): ?string
public static function isRightToLeft( string `$locale` = "" ): bool
public static function lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string
public static function parseLocale(string `$locale`): ?array
public static function setDefault(string `$locale`): true
}

## Vordefinierte Konstanten

`Locale::DEFAULT_LOCALE` null
  Used as locale parameter with the methods of the various locale affected classes, such as NumberFormatter. This constant would make the methods to use default locale.

These constants describe the choice of the locale for the getLocale method of different classes.

`Locale::ACTUAL_LOCALE` int
  This is locale the data actually comes from.
`Locale::VALID_LOCALE` int
  This is the most specific locale supported by ICU.

## Locale Subtags

These constants define how the Locales are parsed or composed. They should be used as keys in the argument array to locale_compose() and are returned from locale_parse() as keys of the returned associative array.

`Locale::LANG_TAG` string
  Language subtag
`Locale::EXTLANG_TAG` string
  Extended language subtag
`Locale::SCRIPT_TAG` string
  Script subtag
`Locale::REGION_TAG` string
  Region subtag
`Locale::VARIANT_TAG` string
  Variant subtag
`Locale::GRANDFATHERED_LANG_TAG` string
  Grandfathered Language subtag
`Locale::PRIVATE_TAG` string
  Private subtag

## Siehe auch

- » RFC 4646 - Tags for Identifying Languages
- » RFC 4647 - Matching of Language Tags
- » Unicode CLDR Project:Common Locale Data Repository
- » IANA Language Subtags Registry
- » ICU User Guide - Locale
- » ICU Locale api

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | The class constants are now typed.

# Locale::acceptFromHttp

# locale_accept_from_http

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::acceptFromHttp -- locale_accept_from_http — Tries to find out best available locale based on HTTP "Accept-Language" header

### Beschreibung

Objektorientierter Stil

public static function Locale::acceptFromHttp(string `$header`): string|false

Prozeduraler Stil

function locale_accept_from_http(string `$header`): string|false

Tries to find locale that can satisfy the language list that is requested by the HTTP "Accept-Language" header.

### Parameter-Liste

`header`

  The string containing the "Accept-Language" header according to format in RFC 2616.

### Rückgabewerte

The corresponding locale identifier.

Returns `false` when the length of `header` exceeds `INTL_MAX_LOCALE_LEN`.

### Beispiele

Beispiel #1 locale_accept_from_http() example

    <?php
    $locale = locale_accept_from_http($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

Beispiel #2 OO example

    <?php
    $locale = Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']);
    echo $locale;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    en_US

### Siehe auch

- locale_lookup() - Searches the language tag list for the best match to the language

# Locale::canonicalize

# locale_canonicalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::canonicalize -- locale_canonicalize — Canonicalize the locale string

### Beschreibung

public static function Locale::canonicalize(string `$locale`): ?string

Canonicalizes the passed locale string to ICU format.

This does not necessarily indicate or return a valid locale. It is only a version of the input that has been canonicalized according to ICU rules.

The behavior of this function depends on the version of ICU PHP is using (`INTL_ICU_VERSION`).

### Parameter-Liste

`locale`
  Original locale string.

### Rückgabewerte

Canonicalized locale string.

Gibt `null` zurück, wenn die Länge von `locale` `INTL_MAX_LOCALE_LEN` überschreitet.

### Beispiele

Beispiel #1 locale_canonicalize() example

    echo Locale::canonicalize('en-US.utf8') . "\n";
    echo Locale::canonicalize('totally-not-valid') . "\n";

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    en_US
    totally_NOT_VALID

# Locale::composeLocale

# locale_compose

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::composeLocale -- locale_compose — Returns a correctly ordered and delimited locale ID

### Beschreibung

Objektorientierter Stil

public static function Locale::composeLocale(array `$subtags`): string|false

Prozeduraler Stil

function locale_compose(array `$subtags`): string|false

Returns a correctly ordered and delimited locale ID the keys identify the particular locale ID subtags, and the values are the associated subtag values.

### Parameter-Liste

`subtags`

  An Array containing a list of key-value pairs, where the keys identify the particular locale ID subtags, and the values are the associated subtag values.

  > Hinweis:

  > The `'variant'` and `'private'` subtags can take maximum 15 values whereas `'extlang'` can take maximum 3 values. For instance, variants are allowed with the suffix ranging from 0-14. Hence the keys for the input array can be `variant0`, `variant1`, …,`variant14`. In the returned locale id, the subtag is ordered by suffix resulting in `variant0` followed by `variant1` followed by `variant2` and so on.

  > Alternatively, the `'variant'`, `'private'` and `'extlang'` values can be specified as array under specific key (e.g. `'variant'`). In this case no limits on the number of recognized subtags apply.

### Rückgabewerte

The corresponding locale identifier, or `false` when `subtags` is empty.

### Beispiele

Beispiel #1 locale_compose() example

    <?php
    $arr = array(
        'language'=>'en',
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2',
    );
    echo locale_compose($arr);
    ?>

Beispiel #2 OO example

    <?php
    $arr = array(
        'language'=>'en' ,
        'script'  =>'Hans',
        'region'  =>'CN',
        'variant2'=>'rozaj',
        'variant1'=>'nedis',
        'private1'=>'prv1',
        'private2'=>'prv2',
    );
    echo Locale::composeLocale($arr);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Locale: en_Hans_CN_nedis_rozaj_x_prv1_prv2

Beispiel #3 Subtag limits

If `subtags` are given as separate keys with numeric suffix, unsupported keys are silently ignored (in this case `'extlang3'`), and ordered in the result by numeric suffix. There are no limits, if subtags are given as Array; the order is as given.

    <?php
    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang3' => 'd',
        'extlang2' => 'c',
        'extlang1' => 'b',
        'extlang0' => 'a',
    );
    echo locale_compose($arr), PHP_EOL;

    $arr = array(
        'language' => 'en',
        'script'   => 'Hans',
        'region'   => 'CN',
        'extlang'  => ['a', 'b', 'c', 'd'],
    );
    echo locale_compose($arr), PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    en_a_b_c_Hans_CN
    en_a_b_c_d_Hans_CN

### Siehe auch

- locale_parse() - Returns a key-value array of locale ID subtag elements

# Locale::filterMatches

# locale_filter_matches

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::filterMatches -- locale_filter_matches — Checks if a language tag filter matches with locale

### Beschreibung

Objektorientierter Stil

public static function Locale::filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Prozeduraler Stil

function locale_filter_matches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

Checks if a `languageTag` filter matches with `locale` according to RFC 4647's basic filtering algorithm

### Parameter-Liste

`languageTag`

  The language tag to check

`locale`

  The language range to check against

`canonicalize`

  If true, the arguments will be converted to canonical form before matching.

### Rückgabewerte

`true` if `locale` matches `languageTag` `false` otherwise.

Gibt `null` zurück, wenn die Länge von `locale` `INTL_MAX_LOCALE_LEN` überschreitet.

### Beispiele

Beispiel #1 locale_filter_matches() example

    <?php
    echo (locale_filter_matches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match";
    echo '; ';
    echo (locale_filter_matches('de-DE_1996','de-DE', false)) ? "Matches" : "Does not match";
    ?>

Beispiel #2 OO example

    <?php
    echo (Locale::filterMatches('de-DEVA','de-DE', false)) ? "Matches" : "Does not match";
    echo '; ';
    echo (Locale::filterMatches('de-DE-1996','de-DE', false)) ? "Matches" : "Does not match";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Does not match; Matches

### Siehe auch

- locale_lookup() - Searches the language tag list for the best match to the language

# Locale::getAllVariants

# locale_get_all_variants

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getAllVariants -- locale_get_all_variants — Gets the variants for the input locale

### Beschreibung

Objektorientierter Stil

public static function Locale::getAllVariants(string `$locale`): ?array

Prozeduraler Stil

function locale_get_all_variants(string `$locale`): ?array

Gets the variants for the input locale

### Parameter-Liste

`locale`

  The locale to extract the variants from

### Rückgabewerte

The array containing the list of all variants subtag for the locale or `null` if not present

Gibt `null` zurück, wenn die Länge von `locale` `INTL_MAX_LOCALE_LEN` überschreitet.

### Beispiele

Beispiel #1 locale_get_all_variants() example

    <?php
    $arr = locale_get_all_variants('sl_IT_NEDIS_ROJAZ_1901');
    var_export( $arr );
    ?>

Beispiel #2 OO example

    <?php
     $arr = Locale::getAllVariants('sl_IT_NEDIS_ROJAZ_1901');
     var_export( $arr );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array (
        0 => 'NEDIS',
        1 => 'ROJAZ',
        2 => '1901',
    )

### Siehe auch

- locale_get_primary_language() - Gets the primary language for the input locale
- locale_get_script() - Gets the script for the input locale
- locale_get_region() - Gets the region for the input locale

# Locale::getDefault

# locale_get_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDefault -- locale_get_default — Gets the default locale value from the INTL global 'default_locale'

### Beschreibung

Objektorientierter Stil

public static function Locale::getDefault(): string

Prozeduraler Stil

function locale_get_default(): string

Gets the default locale value. At the PHP initialization this value is set to 'intl.default_locale' value from php.ini if that value exists or from ICU's function uloc_getDefault().

### Parameter-Liste

### Rückgabewerte

The current runtime locale

### Beispiele

Beispiel #1 locale_get_default() example

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo locale_get_default();
    echo '; ';
    locale_set_default('fr');
    echo locale_get_default();
    ?>

Beispiel #2 OO example

    <?php
    ini_set('intl.default_locale', 'de-DE');
    echo Locale::getDefault();
    echo '; ';
    Locale::setDefault('fr');
    echo Locale::getDefault();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    de-DE; fr

### Siehe auch

- locale_set_default() - Sets the default runtime locale

# Locale::getDisplayLanguage

# locale_get_display_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayLanguage -- locale_get_display_language — Returns an appropriately localized display name for language of the inputlocale

### Beschreibung

Objektorientierter Stil

public static function Locale::getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false

Prozeduraler Stil

function locale_get_display_language(string `$locale`, ?string `$displayLocale` = `null`): string|false

Returns an appropriately localized display name for language of the input locale. If is `null` then the default locale is used.

### Parameter-Liste

`locale`

  The locale to return a display language for

`displayLocale`

  Optional format locale to use to display the language name

### Rückgabewerte

Display name of the language for the `locale` in the format appropriate for `displayLocale`, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `displayLocale` is nullable now.

### Beispiele

Beispiel #1 locale_get_display_language() example

    <?php
    echo locale_get_display_language('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_language('sl-Latn-IT-nedis', 'de');
    ?>

Beispiel #2 OO example

    <?php
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayLanguage('sl-Latn-IT-nedis', 'de');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Slovenian;
    slov\xc3\xa8ne;
    Slowenisch

### Siehe auch

- locale_get_display_name() - Returns an appropriately localized display name for the input locale
- locale_get_display_script() - Returns an appropriately localized display name for script of the input locale
- locale_get_display_region() - Returns an appropriately localized display name for region of the input locale
- locale_get_display_variant() - Returns an appropriately localized display name for variants of the input locale

# Locale::getDisplayName

# locale_get_display_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayName -- locale_get_display_name — Returns an appropriately localized display name for the input locale

### Beschreibung

Objektorientierter Stil

public static function Locale::getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false

Prozeduraler Stil

function locale_get_display_name(string `$locale`, ?string `$displayLocale` = `null`): string|false

Returns an appropriately localized display name for the input locale. If `locale` is `null` then the default locale is used.

### Parameter-Liste

`locale`

  The locale to return a display name for.

`displayLocale`

  optional format locale

### Rückgabewerte

Display name of the locale in the format appropriate for `displayLocale`, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `displayLocale` is nullable now.

### Beispiele

Beispiel #1 locale_get_display_name() example

    <?php
    echo locale_get_display_name('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_name('sl-Latn-IT-nedis', 'de');
    ?>

Beispiel #2 OO example

    <?php
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayName('sl-Latn-IT-nedis', 'de');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Slovenian (Latin, Italy, Natisone dialect);
    slov\xc3\xa8ne (latin, Italie, dialecte de Natisone;
    Slowenisch (Lateinisch, Italien, NEDIS)

### Siehe auch

- locale_get_display_language() - Returns an appropriately localized display name for language of the inputlocale
- locale_get_display_script() - Returns an appropriately localized display name for script of the input locale
- locale_get_display_region() - Returns an appropriately localized display name for region of the input locale
- locale_get_display_variant() - Returns an appropriately localized display name for variants of the input locale

# Locale::getDisplayRegion

# locale_get_display_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayRegion -- locale_get_display_region — Returns an appropriately localized display name for region of the input locale

### Beschreibung

Objektorientierter Stil

public static function Locale::getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false

Prozeduraler Stil

function locale_get_display_region(string `$locale`, ?string `$displayLocale` = `null`): string|false

Returns an appropriately localized display name for region of the input locale. If is `null` then the default locale is used.

### Parameter-Liste

`locale`

  The locale to return a display region for.

`displayLocale`

  Optional format locale to use to display the region name

### Rückgabewerte

Display name of the region for the `locale` in the format appropriate for `displayLocale`, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `displayLocale` is nullable now.

### Beispiele

Beispiel #1 locale_get_display_region() example

    <?php
    echo locale_get_display_region('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_region('sl-Latn-IT-nedis', 'de');
    ?>

Beispiel #2 OO example

    <?php
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayRegion('sl-Latn-IT-nedis', 'de');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Italy;
    Italie;
    Italien

### Siehe auch

- locale_get_display_name() - Returns an appropriately localized display name for the input locale
- locale_get_display_language() - Returns an appropriately localized display name for language of the inputlocale
- locale_get_display_script() - Returns an appropriately localized display name for script of the input locale
- locale_get_display_variant() - Returns an appropriately localized display name for variants of the input locale

# Locale::getDisplayScript

# locale_get_display_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayScript -- locale_get_display_script — Returns an appropriately localized display name for script of the input locale

### Beschreibung

Objektorientierter Stil

public static function Locale::getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false

Prozeduraler Stil

function locale_get_display_script(string `$locale`, ?string `$displayLocale` = `null`): string|false

Returns an appropriately localized display name for script of the input locale. If is `null` then the default locale is used.

### Parameter-Liste

`locale`

  The locale to return a display script for

`displayLocale`

  Optional format locale to use to display the script name

### Rückgabewerte

Display name of the script for the `locale` in the format appropriate for `displayLocale`, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `displayLocale` is nullable now.

### Beispiele

Beispiel #1 locale_get_display_script() example

    <?php
    echo locale_get_display_script('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_script('sl-Latn-IT-nedis', 'de');
    ?>

Beispiel #2 OO example

    <?php
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayScript('sl-Latn-IT-nedis', 'de');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Latin;
    latin;
    Lateinisch

### Siehe auch

- locale_get_display_name() - Returns an appropriately localized display name for the input locale
- locale_get_display_language() - Returns an appropriately localized display name for language of the inputlocale
- locale_get_display_region() - Returns an appropriately localized display name for region of the input locale
- locale_get_display_variant() - Returns an appropriately localized display name for variants of the input locale

# Locale::getDisplayVariant

# locale_get_display_variant

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getDisplayVariant -- locale_get_display_variant — Returns an appropriately localized display name for variants of the input locale

### Beschreibung

Objektorientierter Stil

public static function Locale::getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Prozeduraler Stil

function locale_get_display_variant(string `$locale`, ?string `$displayLocale` = `null`): string|false

Returns an appropriately localized display name for variants of the input locale. If is `null` then the default locale is used.

### Parameter-Liste

`locale`

  The locale to return a display variant for

`displayLocale`

  Optional format locale to use to display the variant name

### Rückgabewerte

Display name of the variant for the `locale` in the format appropriate for `displayLocale`, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `displayLocale` is nullable now.

### Beispiele

Beispiel #1 locale_get_display_variant() example

    <?php
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo locale_get_display_variant('sl-Latn-IT-nedis', 'de');
    ?>

Beispiel #2 OO example

    <?php
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'en');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'fr');
    echo ";\n";
    echo Locale::getDisplayVariant('sl-Latn-IT-nedis', 'de');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Natisone dialect;
    dialecte de Natisone;
    NEDIS

### Siehe auch

- locale_get_display_name() - Returns an appropriately localized display name for the input locale
- locale_get_display_language() - Returns an appropriately localized display name for language of the inputlocale
- locale_get_display_script() - Returns an appropriately localized display name for script of the input locale
- locale_get_display_region() - Returns an appropriately localized display name for region of the input locale

# Locale::getKeywords

# locale_get_keywords

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getKeywords -- locale_get_keywords — Gets the keywords for the input locale

### Beschreibung

Objektorientierter Stil

public static function Locale::getKeywords(string `$locale`): array|false|null

Prozeduraler Stil

function locale_get_keywords(string `$locale`): array|false|null

Gets the keywords for the input locale.

### Parameter-Liste

`locale`

  The locale to extract the keywords from

### Rückgabewerte

Associative array containing the keyword-value pairs for this locale

Gibt `null` zurück, wenn die Länge von `locale` `INTL_MAX_LOCALE_LEN` überschreitet.

### Beispiele

Beispiel #1 locale_get_keywords() example

    <?php
    $keywords_arr = locale_get_keywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

Beispiel #2 OO example

    <?php
    $keywords_arr = Locale::getKeywords('de_DE@currency=EUR;collation=PHONEBOOK');
    if ($keywords_arr) {
        foreach ($keywords_arr as $key => $value) {
            echo "$key = $value\n";
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    collation = PHONEBOOK
    currency = EUR

### Siehe auch

- locale_get_all_variants() - Gets the variants for the input locale

# Locale::getPrimaryLanguage

# locale_get_primary_language

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getPrimaryLanguage -- locale_get_primary_language — Gets the primary language for the input locale

### Beschreibung

Objektorientierter Stil

public static function Locale::getPrimaryLanguage(string `$locale`): ?string

Prozeduraler Stil

function locale_get_primary_language(string `$locale`): ?string

Gets the primary language for the input locale

### Parameter-Liste

`locale`

  The locale to extract the primary language code from

### Rückgabewerte

The language code associated with the language.

Gibt `null` zurück, wenn die Länge von `locale` `INTL_MAX_LOCALE_LEN` überschreitet.

### Beispiele

Beispiel #1 locale_get_primary_language() example

    <?php
    echo locale_get_primary_language('zh-Hant');
    ?>

Beispiel #2 OO example

    <?php
    echo Locale::getPrimaryLanguage('zh-Hant');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    zh

### Siehe auch

- locale_get_script() - Gets the script for the input locale
- locale_get_region() - Gets the region for the input locale
- locale_get_all_variants() - Gets the variants for the input locale

# Locale::getRegion

# locale_get_region

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getRegion -- locale_get_region — Gets the region for the input locale

### Beschreibung

Objektorientierter Stil

public static function Locale::getRegion(string `$locale`): ?string

Prozeduraler Stil

function locale_get_region(string `$locale`): ?string

Gets the region for the input locale.

### Parameter-Liste

`locale`

  The locale to extract the region code from

### Rückgabewerte

The region subtag for the locale or `null` if not present

Gibt `null` zurück, wenn die Länge von `locale` `INTL_MAX_LOCALE_LEN` überschreitet.

### Beispiele

Beispiel #1 locale_get_region() example

    <?php
    echo locale_get_region('de-CH-1901');
    ?>

Beispiel #2 OO example

    <?php
    echo Locale::getRegion('de-CH-1901');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    CH

### Siehe auch

- locale_get_primary_language() - Gets the primary language for the input locale
- locale_get_script() - Gets the script for the input locale
- locale_get_all_variants() - Gets the variants for the input locale

# Locale::getScript

# locale_get_script

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::getScript -- locale_get_script — Gets the script for the input locale

### Beschreibung

Objektorientierter Stil

public static function Locale::getScript(string `$locale`): ?string

Prozeduraler Stil

function locale_get_script(string `$locale`): ?string

Gets the script for the input locale.

### Parameter-Liste

`locale`

  The locale to extract the script code from

### Rückgabewerte

The script subtag for the locale or `null` if not present

### Beispiele

Beispiel #1 locale_get_script() example

    <?php
    echo locale_get_script('sr-Cyrl');
    ?>

Beispiel #2 OO example

    <?php
    echo Locale::getScript('sr-Cyrl');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Cyrl

### Siehe auch

- locale_get_primary_language() - Gets the primary language for the input locale
- locale_get_region() - Gets the region for the input locale
- locale_get_all_variants() - Gets the variants for the input locale

# Locale::isRightToLeft

(No version information available, might only be in Git)

Locale::isRightToLeft — Check whether a locale uses a right-to-left writing system

### Beschreibung

public static function Locale::isRightToLeft( string `$locale` = "" ): bool

Determines whether a locale uses a right-to-left writing system.

This method relies on the ICU library and evaluates the dominant script associated with the locale.

If an empty string is provided, the default locale is used.

### Parameter-Liste

`locale`
  The locale identifier. If empty, the default locale is used.

### Rückgabewerte

Returns `true` if the locale uses a right-to-left writing system, or `false` otherwise.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | Added Locale::isRightToLeft().

### Beispiele

Beispiel #1 Checking text direction for a locale

    <?php

    var_dump(Locale::isRightToLeft('en-US'));
    var_dump(Locale::isRightToLeft('ar'));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)

# Locale::lookup

# locale_lookup

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::lookup -- locale_lookup — Searches the language tag list for the best match to the language

### Beschreibung

Objektorientierter Stil

public static function Locale::lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Prozeduraler Stil

function locale_lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

Searches the items in `languageTag` for the best match to the language range specified in `locale` according to RFC 4647's lookup algorithm.

### Parameter-Liste

`languageTag`

  An array containing a list of language tags to compare to `locale`. Maximum 100 items allowed.

`locale`

  The locale to use as the language range when matching.

`canonicalize`

  If true, the arguments will be converted to canonical form before matching.

`defaultLocale`

  The locale to use if no match is found.

### Rückgabewerte

The closest matching language tag or default value.

Gibt `null` zurück, wenn die Länge von `locale` `INTL_MAX_LOCALE_LEN` überschreitet.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | `defaultLocale` is nullable now.

### Beispiele

Beispiel #1 locale_lookup() example

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo locale_lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

Beispiel #2 OO example

    <?php
    $arr = array(
        'de-DEVA',
        'de-DE-1996',
        'de',
        'de-De'
    );
    echo Locale::lookup($arr, 'de-DE-1996-x-prv1-prv2', true, 'en_US');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    de_de_1996

### Siehe auch

- locale_filter_matches() - Checks if a language tag filter matches with locale

# Locale::parseLocale

# locale_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::parseLocale -- locale_parse — Returns a key-value array of locale ID subtag elements

### Beschreibung

Objektorientierter Stil

public static function Locale::parseLocale(string `$locale`): ?array

Prozeduraler Stil

function locale_parse(string `$locale`): ?array

Returns a key-value array of locale ID subtag elements.

### Parameter-Liste

`locale`

  The locale to extract the subtag array from. Note: The 'variant' and 'private' subtags can take maximum 15 values whereas 'extlang' can take maximum 3 values.

### Rückgabewerte

Returns an array containing a list of key-value pairs, where the keys identify the particular locale ID subtags, and the values are the associated subtag values. The array will be ordered as the locale id subtags e.g. in the locale id if variants are '-varX-varY-varZ' then the returned array will have variant0=>varX , variant1=>varY , variant2=>varZ

Returns `null` when the length of `locale` exceeds `INTL_MAX_LOCALE_LEN`.

### Beispiele

Beispiel #1 locale_parse() example

    <?php
    $arr = locale_parse('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

Beispiel #2 OO example

    <?php
    $arr = Locale::parseLocale('sl-Latn-IT-nedis');
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    language : sl , script : Latn , region : IT , variant0 : NEDIS ,

### Siehe auch

- locale_compose() - Returns a correctly ordered and delimited locale ID

# Locale::setDefault

# locale_set_default

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::setDefault -- locale_set_default — Sets the default runtime locale

### Beschreibung

Objektorientierter Stil

public static function Locale::setDefault(string `$locale`): true

Prozeduraler Stil

function locale_set_default(string `$locale`): true

Sets the default runtime locale to `locale`. This changes the value of INTL global 'default_locale' locale identifier. UAX #35 extensions are accepted.

### Parameter-Liste

`locale`

  Is a BCP 47 compliant language tag.

### Rückgabewerte

Returns `true`.

### Beispiele

Beispiel #1 locale_set_default() example

    <?php
    locale_set_default('de-DE');
    echo locale_get_default();
    ?>

Beispiel #2 OO example

    <?php
    Locale::setDefault('de-DE');
    echo Locale::getDefault();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    de-DE

### Siehe auch

- locale_get_default() - Gets the default locale value from the INTL global 'default_locale'

## Inhaltsverzeichnis

- Locale::acceptFromHttp — Tries to find out best available locale based on HTTP "Accept-Language" header
- Locale::canonicalize — Canonicalize the locale string
- Locale::composeLocale — Returns a correctly ordered and delimited locale ID
- Locale::filterMatches — Checks if a language tag filter matches with locale
- Locale::getAllVariants — Gets the variants for the input locale
- Locale::getDefault — Gets the default locale value from the INTL global 'default_locale'
- Locale::getDisplayLanguage — Returns an appropriately localized display name for language of the inputlocale
- Locale::getDisplayName — Returns an appropriately localized display name for the input locale
- Locale::getDisplayRegion — Returns an appropriately localized display name for region of the input locale
- Locale::getDisplayScript — Returns an appropriately localized display name for script of the input locale
- Locale::getDisplayVariant — Returns an appropriately localized display name for variants of the input locale
- Locale::getKeywords — Gets the keywords for the input locale
- Locale::getPrimaryLanguage — Gets the primary language for the input locale
- Locale::getRegion — Gets the region for the input locale
- Locale::getScript — Gets the script for the input locale
- Locale::isRightToLeft — Check whether a locale uses a right-to-left writing system
- Locale::lookup — Searches the language tag list for the best match to the language
- Locale::parseLocale — Returns a key-value array of locale ID subtag elements
- Locale::setDefault — Sets the default runtime locale

# The Normalizer class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Einführung

Normalization is a process that involves transforming characters and sequences of characters into a formally-defined underlying representation. This process is most important when text needs to be compared for sorting and searching, but it is also used when storing text to ensure that the text is stored in a consistent representation.

The Unicode Consortium has defined a number of normalization forms reflecting the various needs of applications:

- Normalization Form D (NFD) - Canonical Decomposition
- Normalization Form C (NFC) - Canonical Decomposition followed by Canonical Composition
- Normalization Form KD (NFKD) - Compatibility Decomposition
- Normalization Form KC (NFKC) - Compatibility Decomposition followed by Canonical Composition

The different forms are defined in terms of a set of transformations on the text, transformations that are expressed by both an algorithm and a set of data files.

## Klassenbeschreibung

class Normalizer {
/* Konstanten */
public const int FORM_D;
public const int NFD;
public const int FORM_KD;
public const int NFKD;
public const int FORM_C;
public const int NFC;
public const int FORM_KC;
public const int NFKC;
public const int FORM_KC_CF;
public const int NFKC_CF;
/* Methoden */
public static function getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string
public static function isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool
public static function normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false
}

## Vordefinierte Konstanten

The following constants define the normalization form used by the normalizer:

`Normalizer::FORM_C` int
  Normalization Form C (NFC) - Canonical Decomposition followed by Canonical Composition
`Normalizer::FORM_D` int
  Normalization Form D (NFD) - Canonical Decomposition
`Normalizer::NFD` int

`Normalizer::FORM_KC` int
  Normalization Form KC (NFKC) - Compatibility Decomposition, followed by Canonical Composition
`Normalizer::NFKC` int

`Normalizer::FORM_KC_CF` int

`Normalizer::FORM_KD` int
  Normalization Form KD (NFKD) - Compatibility Decomposition
`Normalizer::NFKD` int

`Normalizer::NFC` int

`Normalizer::NFKC_CF` int

## Siehe auch

- » Unicode Normalization
- » Unicode Normalization FAQ
- » ICU User Guide - Normalization
- » ICU API Reference - Normalization

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | The class constants are now typed.
8.0.0 | `Normalizer::NONE` has been removed.

# Normalizer::getRawDecomposition

# normalizer_get_raw_decomposition

(PHP 7 >= 7.3, PHP 8)

Normalizer::getRawDecomposition -- normalizer_get_raw_decomposition — Gets the Decomposition_Mapping property for the given UTF-8 encoded code point

### Beschreibung

Objektorientierter Stil

public static function Normalizer::getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Prozeduraler Stil

function normalizer_get_raw_decomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

Gets the Decomposition_Mapping property, as specified in the Unicode Character Database (UCD), for the given UTF-8 encoded code point.

### Parameter-Liste

`string`

  The input string, which should be a single, UTF-8 encoded, code point.

### Rückgabewerte

Returns a string containing the Decomposition_Mapping property, if present in the UCD.

Returns `null` if there is no Decomposition_Mapping property for the character.

### Beispiele

Beispiel #1 Normalizer::getRawDecomposition() example

    <?php

    $result = "";
    $strings = [
        "a",
        "\u{FFDA}",
        "\u{FDFA}",
        "",
        "aa",
        "\xF5",
    ];

    foreach ($strings as $string) {
        $decomposition = Normalizer::getRawDecomposition($string);
        // $decomposition = normalizer_get_raw_decomposition($string); Procedural way

        $error_code = intl_get_error_code();
        $error_message = intl_get_error_message();

        $string_hex = bin2hex($string);
        $result .= "---------------------\n";

        if ($decomposition === null) {
            $result .= "'$string_hex' has no decomposition mapping\n" ;
        } else {
            $result .= "'$string_hex' has the decomposition mapping '" . bin2hex($decomposition) . "'\n" ;
        }

        $result .= "error info: '$error_message' ($error_code)\n";
    }

    echo $result;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ---------------------
    '61' has no decomposition mapping
    error info: 'U_ZERO_ERROR' (0)
    ---------------------
    'efbf9a' has the decomposition mapping 'e385a1'
    error info: 'U_ZERO_ERROR' (0)
    ---------------------
    'efb7ba' has the decomposition mapping 'd8b5d984d98920d8a7d984d984d98720d8b9d984d98ad98720d988d8b3d984d985'
    error info: 'U_ZERO_ERROR' (0)
    ---------------------
    '' has no decomposition mapping
    error info: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    '6161' has no decomposition mapping
    error info: 'Input string must be exactly one UTF-8 encoded code point long.: U_ILLEGAL_ARGUMENT_ERROR' (1)
    ---------------------
    'f5' has no decomposition mapping
    error info: 'Code point out of range: U_ILLEGAL_ARGUMENT_ERROR' (1)

### Siehe auch

- Normalizer::normalize() - Normalizes the input provided and returns the normalized string
- Normalizer::isNormalized() - Checks if the provided string is already in the specified normalization form

# Normalizer::isNormalized

# normalizer_is_normalized

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::isNormalized -- normalizer_is_normalized — Checks if the provided string is already in the specified normalization form

### Beschreibung

Objektorientierter Stil

public static function Normalizer::isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Prozeduraler Stil

function normalizer_is_normalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

Checks if the provided string is already in the specified normalization form.

### Parameter-Liste

`string`

  The input string to normalize

`form`

  One of the normalization forms.

### Rückgabewerte

`true` if normalized, `false` otherwise or if there an error

### Beispiele

Beispiel #1 normalizer_is_normalized() example

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( normalizer_is_normalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( normalizer_is_normalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

Beispiel #2 OO example

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_orig = 'A' . $char_combining_ring_above;
    $char_norm = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo ( Normalizer::isNormalized($char_orig, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    echo '; ';
    echo ( Normalizer::isNormalized($char_norm, Normalizer::FORM_C) ) ? "normalized" : "not normalized";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    not normalized; normalized

### Siehe auch

- normalizer_normalize() - Normalizes the input provided and returns the normalized string

# Normalizer::normalize

# normalizer_normalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::normalize -- normalizer_normalize — Normalizes the input provided and returns the normalized string

### Beschreibung

Objektorientierter Stil

public static function Normalizer::normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Prozeduraler Stil

function normalizer_normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

Normalizes the input provided and returns the normalized string

### Parameter-Liste

`string`

  The input string to normalize

`form`

  One of the normalization forms.

### Rückgabewerte

The normalized string or `false` if an error occurred.

### Beispiele

Beispiel #1 normalizer_normalize() example

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = normalizer_normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = normalizer_normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

Beispiel #2 OO example

    <?php
    $char_A_ring = "\xC3\x85"; // 'LATIN CAPITAL LETTER A WITH RING ABOVE' (U+00C5)
    $char_combining_ring_above = "\xCC\x8A";  // 'COMBINING RING ABOVE' (U+030A)

    $char_1 = Normalizer::normalize( $char_A_ring, Normalizer::FORM_C );
    $char_2 = Normalizer::normalize( 'A' . $char_combining_ring_above, Normalizer::FORM_C );

    echo urlencode($char_1);
    echo ' ';
    echo urlencode($char_2);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    %C3%85 %C3%85

### Siehe auch

- normalizer_is_normalized() - Checks if the provided string is already in the specified normalization form

## Inhaltsverzeichnis

- Normalizer::getRawDecomposition — Gets the Decomposition_Mapping property for the given UTF-8 encoded code point
- Normalizer::isNormalized — Checks if the provided string is already in the specified normalization form
- Normalizer::normalize — Normalizes the input provided and returns the normalized string

# The MessageFormatter class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Einführung

MessageFormatter is a concrete class that enables users to produce concatenated, language-neutral messages. The methods supplied in this class are used to build all the messages that are seen by end users.

The MessageFormatter class assembles messages from various fragments (such as text fragments, numbers, and dates) supplied by the program. Because of the MessageFormatter class, the program does not need to know the order of the fragments. The class uses the formatting specifications for the fragments to assemble them into a message that is contained in a single string within a resource bundle. For example, MessageFormatter enables you to print the phrase "Finished printing x out of y files..." in a manner that still allows for flexibility in translation.

Previously, an end user message was created as a sentence and handled as a string. This procedure created problems for localizers because the sentence structure, word order, number format and so on are very different from language to language. The language-neutral way to create messages keeps each part of the message separate and provides keys to the data. Using these keys, the MessageFormatter class can concatenate the parts of the message, localize them, and display a well-formed string to the end user.

MessageFormatter takes a set of objects, formats them, and then inserts the formatted strings into the pattern at the appropriate places. Choice formats can be used in conjunction with MessageFormatter to handle plurals, match numbers, and select from an array of items. Typically, the message format will come from resources and the arguments will be dynamically set at runtime.

## Klassenbeschreibung

class MessageFormatter {
/* Methoden */
public function __construct(string `$locale`, string `$pattern`)
public static function create(string `$locale`, string `$pattern`): ?MessageFormatter
public function format(array `$values`): string|false
public static function formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(): string
public function getPattern(): string|false
public function parse(string `$string`): array|false
public static function parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false
public function setPattern(string `$pattern`): bool
}

## Siehe auch

- » ICU formatting documentation
- » ICU message formatting description
- » ICU message formatters
- » ICU choice formatters

# MessageFormatter::create

# MessageFormatter::__construct

# msgfmt_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::create -- MessageFormatter::__construct -- msgfmt_create — Constructs a new Message Formatter

### Beschreibung

Objektorientierter Stil (method)

public static function MessageFormatter::create(string `$locale`, string `$pattern`): ?MessageFormatter

Objektorientierter Stil (constructor):

public function MessageFormatter::__construct(string `$locale`, string `$pattern`)

Prozeduraler Stil

function msgfmt_create(string `$locale`, string `$pattern`): ?MessageFormatter

Constructs a new Message Formatter

### Parameter-Liste

`locale`

  The locale to use when formatting arguments

`pattern`

  The pattern string to stick arguments into. The pattern uses an 'apostrophe-friendly' syntax; see » Quoting/Escaping for details.

### Rückgabewerte

The formatter object, or `null` on failure.

### Fehler/Exceptions

When invoked as constructor, on failure an IntlException is thrown.

### Beispiele

Beispiel #1 msgfmt_create() example

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum

### Siehe auch

- msgfmt_format() - Format the message
- msgfmt_parse() - Parse input string according to pattern
- msgfmt_get_error_code() - Get the error code from last operation
- msgfmt_get_error_message() - Get the error text from the last operation

# MessageFormatter::format

# msgfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::format -- msgfmt_format — Format the message

### Beschreibung

Objektorientierter Stil

public function MessageFormatter::format(array `$values`): string|false

Prozeduraler Stil

function msgfmt_format(MessageFormatter `$formatter`, array `$values`): string|false

Format the message by substituting the data into the format string according to the locale rules

### Parameter-Liste

`formatter`

  The message formatter

`values`

  Arguments to insert into the format string

### Rückgabewerte

The formatted string, or `false` if an error occurred

### Beispiele

Beispiel #1 msgfmt_format() example

    <?php
    $fmt = msgfmt_create("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    $fmt = msgfmt_create("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo msgfmt_format($fmt, array(4560, 123, 4560/123));
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new MessageFormatter("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    echo $fmt->format(array(4560, 123, 4560/123));
    $fmt = new MessageFormatter("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    echo $fmt->format(array(4560, 123, 4560/123));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum

### Siehe auch

- msgfmt_create() - Constructs a new Message Formatter
- msgfmt_parse() - Parse input string according to pattern
- msgfmt_format_message() - Quick format message
- msgfmt_get_error_code() - Get the error code from last operation
- msgfmt_get_error_message() - Get the error text from the last operation

# MessageFormatter::formatMessage

# msgfmt_format_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::formatMessage -- msgfmt_format_message — Quick format message

### Beschreibung

Objektorientierter Stil

public static function MessageFormatter::formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false

Prozeduraler Stil

function msgfmt_format_message(string `$locale`, string `$pattern`, array `$values`): string|false

Quick formatting function that formats the string without having to explicitly create the formatter object. Use this function when the format operation is done only once and does not need any parameters or state to be kept or when wanting to customize the output by providing additional context to ICU directly.

### Parameter-Liste

`locale`

  The locale to use for formatting locale-dependent parts

`pattern`

  The pattern string to insert things into. The pattern uses an 'apostrophe-friendly' syntax; see » Quoting/Escaping for details.

`values`

  The array of values to insert into the format string

### Rückgabewerte

The formatted pattern string or `false` if an error occurred

### Beispiele

Beispiel #1 msgfmt_format_message() example

    <?php
    echo msgfmt_format_message("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo msgfmt_format_message("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo msgfmt_format_message("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";

Beispiel #2 OO example

    <?php
    echo MessageFormatter::formatMessage("en_US", "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("de", "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum\n", array(4560, 123, 4560/123));
    echo MessageFormatter::formatMessage("en", 'You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!', ['place' => 3]), "\n";
    echo MessageFormatter::formatMessage("en",
            "There {apple, plural,
                =0 {are no apples}
                =1 {is one apple...}
                other {are # apples!}
            }",
        ['apple' => 0]
    ), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    4,560 monkeys on 123 trees make 37.073 monkeys per tree
    4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum
    You finished 3rd!
    There are no apples

Beispiel #3 Instructing ICU to format currency with common and with narrow currency symbol

Requires ICU ≥ 67.

    <?php
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD}", array(123.45));
    echo msgfmt_format_message("cs_CZ", "{0, number, :: currency/CAD unit-width-narrow}", array(123.45));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    123,45 CA$
    123,45 $

### Siehe auch

- msgfmt_create() - Constructs a new Message Formatter
- msgfmt_parse() - Parse input string according to pattern
- msgfmt_get_error_code() - Get the error code from last operation
- msgfmt_get_error_message() - Get the error text from the last operation

# MessageFormatter::getErrorCode

# msgfmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorCode -- msgfmt_get_error_code — Get the error code from last operation

### Beschreibung

Objektorientierter Stil

public function MessageFormatter::getErrorCode(): int

Prozeduraler Stil

function msgfmt_get_error_code(MessageFormatter `$formatter`): int

Get the error code from last operation.

### Parameter-Liste

`formatter`

  The message formatter

### Rückgabewerte

The error code, one of UErrorCode values. Initial value is U_ZERO_ERROR.

### Siehe auch

- msgfmt_get_error_message() - Get the error text from the last operation
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure

# MessageFormatter::getErrorMessage

# msgfmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getErrorMessage -- msgfmt_get_error_message — Get the error text from the last operation

### Beschreibung

Objektorientierter Stil

public function MessageFormatter::getErrorMessage(): string

Prozeduraler Stil

function msgfmt_get_error_message(MessageFormatter `$formatter`): string

Get the error text from the last operation.

### Parameter-Liste

`formatter`

  The message formatter

### Rückgabewerte

Description of the last error.

### Beispiele

Beispiel #1 msgfmt_get_error_message() example

    <?php
    $fmt = msgfmt_create("en_US", "{0, number} monkeys on {1, number} trees");
    $str = msgfmt_format($fmt, array());
    if(!$str) {
        echo "ERROR: ".msgfmt_get_error_message($fmt) . " (" . msgfmt_get_error_code($fmt) . ")\n";
    }
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new MessageFormatter("en_US", "{0, number} monkeys on {1, number} trees");
    $str = $fmt->format(array());
    if(!$str) {
        echo "ERROR: ".$fmt->getErrorMessage() . " (" . $fmt->getErrorCode() . ")\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ERROR: msgfmt_format: not enough parameters: U_ILLEGAL_ARGUMENT_ERROR (1)

### Siehe auch

- msgfmt_get_error_code() - Get the error code from last operation
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure

# MessageFormatter::getLocale

# msgfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getLocale -- msgfmt_get_locale — Get the locale for which the formatter was created

### Beschreibung

Objektorientierter Stil

public function MessageFormatter::getLocale(): string

Prozeduraler Stil

function msgfmt_get_locale(MessageFormatter `$formatter`): string

Get the locale for which the formatter was created.

### Parameter-Liste

`formatter`

  The formatter resource

### Rückgabewerte

The locale name

### Beispiele

Beispiel #1 msgfmt_get_locale() example

    <?php
    $fmt = msgfmt_create('en_US', "Number {0,number}");
    echo msgfmt_get_locale($fmt);
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new MessageFormatter('en_US', "Number {0,number}");
    echo $fmt->getLocale();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    en_US

### Siehe auch

- msgfmt_create() - Constructs a new Message Formatter

# MessageFormatter::getPattern

# msgfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getPattern -- msgfmt_get_pattern — Get the pattern used by the formatter

### Beschreibung

Objektorientierter Stil

public function MessageFormatter::getPattern(): string|false

Prozeduraler Stil

function msgfmt_get_pattern(MessageFormatter `$formatter`): string|false

Get the pattern used by the formatter

### Parameter-Liste

`formatter`

  The message formatter

### Rückgabewerte

The pattern string for this message formatter, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 msgfmt_get_pattern() example

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Default pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Formatting result: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} trees hosting {1, number} monkeys" );
    echo "New pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Formatted number: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Default pattern: '" . $fmt->getPattern() . "'\n";
    echo "Formatting result: " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} trees hosting {1, number} monkeys" );
    echo "New pattern: '" . $fmt->getPattern() . "'\n";
    echo "Formatted number: " . $fmt->format(array(123, 456)) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Default pattern: '{0,number} monkeys on {1,number} trees'
    Formatting result: 123 monkeys on 456 trees
    New pattern: '{0,number} trees hosting {1,number} monkeys'
    Formatted number: 123 trees hosting 456 monkeys

### Siehe auch

- msgfmt_create() - Constructs a new Message Formatter
- msgfmt_set_pattern() - Set the pattern used by the formatter

# MessageFormatter::parse

# msgfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parse -- msgfmt_parse — Parse input string according to pattern

### Beschreibung

Objektorientierter Stil

public function MessageFormatter::parse(string `$string`): array|false

Prozeduraler Stil

function msgfmt_parse(MessageFormatter `$formatter`, string `$string`): array|false

Parses input string and return any extracted items as an array.

### Parameter-Liste

`formatter`

  The message formatter

`string`

  The string to parse

### Rückgabewerte

An array containing the items extracted, or `false` on error

### Beispiele

Beispiel #1 msgfmt_parse() example

    <?php
    $fmt = msgfmt_create('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    $res = msgfmt_parse($fmt, "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($res);

    $fmt = msgfmt_create('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    $res = msgfmt_parse($fmt, "4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($res);
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new MessageFormatter('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree");
    $res = $fmt->parse("4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($res);

    $fmt = new MessageFormatter('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum");
    $res = $fmt->parse("4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($res);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Siehe auch

- msgfmt_create() - Constructs a new Message Formatter
- msgfmt_format() - Format the message
- msgfmt_parse_message() - Quick parse input string

# MessageFormatter::parseMessage

# msgfmt_parse_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parseMessage -- msgfmt_parse_message — Quick parse input string

### Beschreibung

Objektorientierter Stil

public static function MessageFormatter::parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false

Prozeduraler Stil

function msgfmt_parse_message(string `$locale`, string `$pattern`, string `$message`): array|false

Parses input string without explicitly creating the formatter object. Use this function when the format operation is done only once and does not need any parameters or state to be kept.

### Parameter-Liste

`locale`

  The locale to use for parsing locale-dependent parts

`pattern`

  The pattern with which to parse the `message`.

`message`

  The string to parse, conforming to the `pattern`.

### Rückgabewerte

An array containing items extracted, or `false` on error

### Beispiele

Beispiel #1 msgfmt_parse_message() example

    <?php
    $fmt = msgfmt_parse_message('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
                                "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($fmt);

    $fmt = msgfmt_parse_message('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum",
                                "4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

Beispiel #2 OO example

    <?php
    $fmt = MessageFormatter::parseMessage('en_US', "{0,number,integer} monkeys on {1,number,integer} trees make {2,number} monkeys per tree",
                                "4,560 monkeys on 123 trees make 37.073 monkeys per tree");
    var_export($fmt);

    $fmt = MessageFormatter::parseMessage('de', "{0,number,integer} Affen auf {1,number,integer} Bäumen sind {2,number} Affen pro Baum",
                                "4.560 Affen auf 123 Bäumen sind 37,073 Affen pro Baum");
    var_export($fmt);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )
    array (
      0 => 4560,
      1 => 123,
      2 => 37.073,
    )

### Siehe auch

- msgfmt_create() - Constructs a new Message Formatter
- msgfmt_format_message() - Quick format message
- msgfmt_parse() - Parse input string according to pattern

# MessageFormatter::setPattern

# msgfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::setPattern -- msgfmt_set_pattern — Set the pattern used by the formatter

### Beschreibung

Objektorientierter Stil

public function MessageFormatter::setPattern(string `$pattern`): bool

Prozeduraler Stil

function msgfmt_set_pattern(MessageFormatter `$formatter`, string `$pattern`): bool

Set the pattern used by the formatter

### Parameter-Liste

`formatter`

  The message formatter

`pattern`

  The pattern string to use in this message formatter. The pattern uses an 'apostrophe-friendly' syntax; see » Quoting/Escaping for details.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 msgfmt_set_pattern() example

    <?php
    $fmt = msgfmt_create( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Default pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Formatting result: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";

    msgfmt_set_pattern( $fmt, "{0, number} trees hosting {1, number} monkeys" );
    echo "New pattern: '" . msgfmt_get_pattern( $fmt ) . "'\n";
    echo "Formatted number: " . msgfmt_format( $fmt, array(123, 456) ) . "\n";
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new MessageFormatter( "en_US", "{0, number} monkeys on {1, number} trees" );
    echo "Default pattern: '" . $fmt->getPattern() . "'\n";
    echo "Formatting result: " . $fmt->format(array(123, 456)) . "\n";

    $fmt->setPattern("{0, number} trees hosting {1, number} monkeys" );
    echo "New pattern: '" . $fmt->getPattern() . "'\n";
    echo "Formatted number: " . $fmt->format(array(123, 456)) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Default pattern: '{0,number} monkeys on {1,number} trees'
    Formatting result: 123 monkeys on 456 trees
    New pattern: '{0,number} trees hosting {1,number} monkeys'
    Formatted number: 123 trees hosting 456 monkeys

### Siehe auch

- msgfmt_create() - Constructs a new Message Formatter
- msgfmt_get_pattern() - Get the pattern used by the formatter

## Inhaltsverzeichnis

- MessageFormatter::create — Constructs a new Message Formatter
- MessageFormatter::format — Format the message
- MessageFormatter::formatMessage — Quick format message
- MessageFormatter::getErrorCode — Get the error code from last operation
- MessageFormatter::getErrorMessage — Get the error text from the last operation
- MessageFormatter::getLocale — Get the locale for which the formatter was created
- MessageFormatter::getPattern — Get the pattern used by the formatter
- MessageFormatter::parse — Parse input string according to pattern
- MessageFormatter::parseMessage — Quick parse input string
- MessageFormatter::setPattern — Set the pattern used by the formatter

# The IntlCalendar class

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Einführung

## Klassenbeschreibung

class IntlCalendar {
/* Konstanten */
public const int FIELD_ERA;
public const int FIELD_YEAR;
public const int FIELD_MONTH;
public const int FIELD_WEEK_OF_YEAR;
public const int FIELD_WEEK_OF_MONTH;
public const int FIELD_DATE;
public const int FIELD_DAY_OF_YEAR;
public const int FIELD_DAY_OF_WEEK;
public const int FIELD_DAY_OF_WEEK_IN_MONTH;
public const int FIELD_AM_PM;
public const int FIELD_HOUR;
public const int FIELD_HOUR_OF_DAY;
public const int FIELD_MINUTE;
public const int FIELD_SECOND;
public const int FIELD_MILLISECOND;
public const int FIELD_ZONE_OFFSET;
public const int FIELD_DST_OFFSET;
public const int FIELD_YEAR_WOY;
public const int FIELD_DOW_LOCAL;
public const int FIELD_EXTENDED_YEAR;
public const int FIELD_JULIAN_DAY;
public const int FIELD_MILLISECONDS_IN_DAY;
public const int FIELD_IS_LEAP_MONTH;
public const int FIELD_FIELD_COUNT;
public const int FIELD_DAY_OF_MONTH;
public const int DOW_SUNDAY;
public const int DOW_MONDAY;
public const int DOW_TUESDAY;
public const int DOW_WEDNESDAY;
public const int DOW_THURSDAY;
public const int DOW_FRIDAY;
public const int DOW_SATURDAY;
public const int DOW_TYPE_WEEKDAY;
public const int DOW_TYPE_WEEKEND;
public const int DOW_TYPE_WEEKEND_OFFSET;
public const int DOW_TYPE_WEEKEND_CEASE;
public const int WALLTIME_FIRST;
public const int WALLTIME_LAST;
public const int WALLTIME_NEXT_VALID;
/* Methoden */
private function __construct()
public function add(int `$field`, int `$value`): bool
public function after(IntlCalendar `$other`): bool
public function before(IntlCalendar `$other`): bool
public function clear(?int `$field` = `null`): true
public static function createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function equals(IntlCalendar `$other`): bool
public function fieldDifference(float `$timestamp`, int `$field`): int|false
public static function fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function get(int `$field`): int|false
public function getActualMaximum(int `$field`): int|false
public function getActualMinimum(int `$field`): int|false
public static function getAvailableLocales(): array
public function getDayOfWeekType(int `$dayOfWeek`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getFirstDayOfWeek(): int|false
public function getGreatestMinimum(int `$field`): int|false
public static function getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function getLeastMaximum(int `$field`): int|false
public function getLocale(int `$type`): string|false
public function getMaximum(int `$field`): int|false
public function getMinimalDaysInFirstWeek(): int|false
public function getMinimum(int `$field`): int|false
public static function getNow(): float
public function getRepeatedWallTimeOption(): int
public function getSkippedWallTimeOption(): int
public function getTime(): float|false
public function getTimeZone(): IntlTimeZone|false
public function getType(): string
public function getWeekendTransition(int `$dayOfWeek`): int|false
public function inDaylightTime(): bool
public function isEquivalentTo(IntlCalendar `$other`): bool
public function isLenient(): bool
public function isSet(int `$field`): bool
public function isWeekend(?float `$timestamp` = `null`): bool
public function roll(int `$field`, int|bool `$value`): bool
public function set(int `$field`, int `$value`): true
public function set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function setFirstDayOfWeek(int `$dayOfWeek`): true
public function setLenient(bool `$lenient`): true
public function setMinimalDaysInFirstWeek(int `$days`): true
public function setRepeatedWallTimeOption(int `$option`): true
public function setSkippedWallTimeOption(int `$option`): true
public function setTime(float `$timestamp`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function toDateTime(): DateTime|false
}

## Vordefinierte Konstanten

`IntlCalendar::FIELD_ERA` int

  Calendar field numerically representing an era, for instance `1` for AD and `0` for BC in the Gregorian/Julian calendars and `235` for the Heisei (平成) era in the Japanese calendar. Not all calendars have more than one era.

`IntlCalendar::FIELD_YEAR` int

  Calendar field for the year. This is not unique across eras. If the calendar type has more than one era, generally the minimum value for this field will be `1`.

`IntlCalendar::FIELD_MONTH` int

  Calendar field for the month. The month sequence is zero-based, so January (here used to signify the first month of the calendar; this may be called another name, such as Muharram in the Islamic calendar) is represented by `0`, February by `1`, …, December by `11` and, for calendars that have it, the 13th or leap month by `12`.

`IntlCalendar::FIELD_WEEK_OF_YEAR` int

  Calendar field for the number of the week of the year. This depends on which day of the week is deemed to start the week and the minimal number of days in a week.

`IntlCalendar::FIELD_WEEK_OF_MONTH` int

  Calendar field for the number of the week of the month. This depends on which day of the week is deemed to start the week and the minimal number of days in a week.

`IntlCalendar::FIELD_DATE` int

  Calendar field for the day of the month. The same as `IntlCalendar::FIELD_DAY_OF_MONTH`, which has a clearer name.

`IntlCalendar::FIELD_DAY_OF_YEAR` int

  Calendar field for the day of the year. For the Gregorian calendar, starts with `1` and ends with `365` or `366`.

`IntlCalendar::FIELD_DAY_OF_WEEK` int

  Calendar field for the day of the week. Its values start with `1` (Sunday, see `IntlCalendar::DOW_SUNDAY` and subsequent constants) and the last valid value is 7 (Saturday).

`IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH` int

  Given a day of the week (Sunday, Monday, …), this calendar field assigns an ordinal to such a day of the week in a specific month. Thus, if the value of this field is `1` and the value of the day of the week is `2` (Monday), then the set day of the month is the 1st Monday of the month; the maximum value is `5`.

  Additionally, the value `0` and negative values are also allowed. The value `0` encompasses the seven days that occur immediately before the first seven days of a month (which therefore have a ‘day of week in month’ with value `1`). Negative values starts counting from the end of the month – `-1` points to the last occurrence of a day of the week in a month, `-2` to the second last, and so on.

  Unlike `IntlCalendar::FIELD_WEEK_OF_MONTH` and `IntlCalendar::FIELD_WEEK_OF_YEAR`, this value does not depend on IntlCalendar::getFirstDayOfWeek() or on IntlCalendar::getMinimalDaysInFirstWeek(). The first Monday is the first Monday, even if it occurs in a week that belongs to the previous month.

`IntlCalendar::FIELD_AM_PM` int

  Calendar field indicating whether a time is before noon (value `0`, AM) or after (`1`). Midnight is AM, noon is PM.

`IntlCalendar::FIELD_HOUR` int

  Calendar field for the hour, without specifying whether itʼs in the morning or in the afternoon. Valid values are `0` to `11`.

`IntlCalendar::FIELD_HOUR_OF_DAY` int

  Calendar field for the full (24h) hour of the day. Valid values are `0` to `23`.

`IntlCalendar::FIELD_MINUTE` int

  Calendar field for the minutes component of the time.

`IntlCalendar::FIELD_SECOND` int

  Calendar field for the seconds component of the time.

`IntlCalendar::FIELD_MILLISECOND` int

  Calendar field the milliseconds component of the time.

`IntlCalendar::FIELD_ZONE_OFFSET` int

  Calendar field indicating the raw offset of the timezone, in milliseconds. The raw offset is the timezone offset, excluding any offset due to daylight saving time.

`IntlCalendar::FIELD_DST_OFFSET` int

  Calendar field for the daylight saving time offset of the calendarʼs timezone, in milliseconds, if active for calendarʼs time.

`IntlCalendar::FIELD_YEAR_WOY` int

  Calendar field representing the year for week of year purposes.

`IntlCalendar::FIELD_DOW_LOCAL` int

  Calendar field for the localized day of the week. This is a value between `1` and `7`, `1` being used for the day of the week that matches the value returned by IntlCalendar::getFirstDayOfWeek().

`IntlCalendar::FIELD_EXTENDED_YEAR` int

  Calendar field for a year number representation that is continuous across eras. For the Gregorian calendar, the value of this field matches that of `IntlCalendar::FIELD_YEAR` for AD years; a BC year `y` is represented by `-y + 1`.

`IntlCalendar::FIELD_JULIAN_DAY` int

  Calendar field for a modified Julian day number. It is different from a conventional Julian day number in that its transitions occur at local zone midnight rather than at noon UTC. It uniquely identifies a date.

`IntlCalendar::FIELD_MILLISECONDS_IN_DAY` int

  Calendar field encompassing the information in `IntlCalendar::FIELD_HOUR_OF_DAY`, `IntlCalendar::FIELD_MINUTE`, `IntlCalendar::FIELD_SECOND` and `IntlCalendar::FIELD_MILLISECOND`. Range is from the `0` to `24 * 3600 * 1000 - 1`. It is not the amount of milliseconds elapsed in the day since on DST transitions it will have discontinuities analog to those of the wall time.

`IntlCalendar::FIELD_IS_LEAP_MONTH` int

  Calendar field whose value is `1` for indicating a leap month and `0` otherwise.

`IntlCalendar::FIELD_FIELD_COUNT` int

  The total number of fields.

`IntlCalendar::FIELD_DAY_OF_MONTH` int

  Alias for `IntlCalendar::FIELD_DATE`.

`IntlCalendar::DOW_SUNDAY` int

  Sunday.

`IntlCalendar::DOW_MONDAY` int

  Monday.

`IntlCalendar::DOW_TUESDAY` int

  Tuesday.

`IntlCalendar::DOW_WEDNESDAY` int

  Wednesday.

`IntlCalendar::DOW_THURSDAY` int

  Thursday.

`IntlCalendar::DOW_FRIDAY` int

  Friday.

`IntlCalendar::DOW_SATURDAY` int

  Saturday.

`IntlCalendar::DOW_TYPE_WEEKDAY` int

  Output of IntlCalendar::getDayOfWeekType() indicating a day of week is a weekday.

`IntlCalendar::DOW_TYPE_WEEKEND` int

  Output of IntlCalendar::getDayOfWeekType() indicating a day of week belongs to the weekend.

`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` int

  Output of IntlCalendar::getDayOfWeekType() indicating the weekend begins during the given day of week.

`IntlCalendar::DOW_TYPE_WEEKEND_CEASE` int

  Output of IntlCalendar::getDayOfWeekType() indicating the weekend ends during the given day of week.

`IntlCalendar::WALLTIME_FIRST` int

  Output of IntlCalendar::getSkippedWallTimeOption() indicating that wall times in the skipped range should refer to the same instant as wall times with one hour less and of IntlCalendar::getRepeatedWallTimeOption() indicating the wall times in the repeated range should refer to the instant of the first occurrence of such wall time.

`IntlCalendar::WALLTIME_LAST` int

  Output of IntlCalendar::getSkippedWallTimeOption() indicating that wall times in the skipped range should refer to the same instant as wall times with one hour after and of IntlCalendar::getRepeatedWallTimeOption() indicating the wall times in the repeated range should refer to the instant of the second occurrence of such wall time.

`IntlCalendar::WALLTIME_NEXT_VALID` int

  Output of IntlCalendar::getSkippedWallTimeOption() indicating that wall times in the skipped range should refer to the instant when the daylight saving time transition occurs (begins).

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | The class constants are now typed.

# IntlCalendar::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::add — Add a (signed) amount of time to a field

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::add(int `$field`, int `$value`): bool

Prozeduraler Stil

function intlcal_add(IntlCalendar `$calendar`, int `$field`, int `$value`): bool

Add a signed amount to a field. Adding a positive amount allows advances in time, even if the numeric value of the field decreases (e.g. when working with years in BC dates).

Other fields may need to adjusted – for instance, adding a month to the 31st of January will result in the 28th (or 29th) of February. Contrary to IntlCalendar::roll(), when a value wraps around, more significant fields may change. For instance, adding a day to the 31st of January will result in the 1st of February, not the 1st of January.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

`value`

  The signed amount to add to the current field. If the amount is positive, the instant will be moved forward; if it is negative, the instant will be moved into the past. The unit is implicit to the field type. For instance, hours for `IntlCalendar::FIELD_HOUR_OF_DAY`.

### Rückgabewerte

Returns `true` on successBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlCalendar::add()

    <?php
    ini_set('intl.default_locale', 'fr_FR');
    ini_set('date.timezone', 'UTC');

    $cal = new IntlGregorianCalendar(2012, 0 /* January */, 31);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    echo IntlDateFormatter::formatObject($cal), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    31 janv. 2012 00:00:00
    29 févr. 2012 00:00:00
    1 mars 2012 00:00:00

# IntlCalendar::after

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::after — Whether this objectʼs time is after that of the passed object

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::after(IntlCalendar `$other`): bool

Prozeduraler Stil

function intlcal_after(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Returns whether this objectʼs time succeeds the argumentʼs time.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`other`

  The calendar whose time will be checked against the primary objectʼs time.

### Rückgabewerte

Returns `true` if this objectʼs current time is after that of the `calendar` argumentʼs time. Returns `false` otherwise.

Bei einem Fehler wird auch `false` zurückgegeben. Um Fehlerzustände zu erkennen, kann die Funktion intl_get_error_code() verwendet werden oder Intl so konfiguriert werden, dass es Exceptions auslöst.

### Beispiele

Beispiel #1 IntlCalendar::after()

    <?php
    $cal1 = IntlCalendar::createInstance();
    $cal2 = clone $cal1;

    var_dump($cal1->after($cal2), //false
            $cal2->after($cal1)); //false

    $cal1->roll(IntlCalendar::FIELD_MILLISECOND, true);

    var_dump($cal1->after($cal2), //true
            $cal2->after($cal1)); //false

# IntlCalendar::before

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::before — Whether this objectʼs time is before that of the passed object

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::before(IntlCalendar `$other`): bool

Prozeduraler Stil

function intlcal_before(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Returns whether this objectʼs time precedes the argumentʼs time.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`other`

  The calendar whose time will be checked against the primary objectʼs time.

### Rückgabewerte

Returns `true` if this objectʼs current time is before that of the `calendar` argumentʼs time. Returns `false` otherwise.

Bei einem Fehler wird auch `false` zurückgegeben. Um Fehlerzustände zu erkennen, kann die Funktion intl_get_error_code() verwendet werden oder Intl so konfiguriert werden, dass es Exceptions auslöst.

# IntlCalendar::clear

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::clear — Clear a field or all fields

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::clear(?int `$field` = `null`): true

Prozeduraler Stil

function intlcal_clear(IntlCalendar `$calendar`, ?int `$field` = `null`): true

Clears either all of the fields or a specific field. A cleared field is marked as unset, giving it the lowest priority against overlapping fields or even default values when calculating the time. Additionally, its value is set to `0`, though given the fieldʼs low priority, its value may have been internally set to another value by the time the field has finished been queried.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Der Rückgabewert ist nun `true` vorher war es bool.

### Beispiele

Beispiel #1 IntlCalendar::clear() examples

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'UTC');

    $fields = array(
        'FIELD_ERA'                  => 0,
        'FIELD_YEAR'                 => 1,
        'FIELD_MONTH'                => 2,
        'FIELD_WEEK_OF_YEAR'         => 3,
        'FIELD_WEEK_OF_MONTH'        => 4,
        'FIELD_DATE'                 => 5,
        'FIELD_DAY_OF_YEAR'          => 6,
        'FIELD_DAY_OF_WEEK'          => 7,
        'FIELD_DAY_OF_WEEK_IN_MONTH' => 8,
        'FIELD_AM_PM'                => 9,
        'FIELD_HOUR'                 => 10,
        'FIELD_HOUR_OF_DAY'          => 11,
        'FIELD_MINUTE'               => 12,
        'FIELD_SECOND'               => 13,
        'FIELD_MILLISECOND'          => 14,
        'FIELD_ZONE_OFFSET'          => 15,
        'FIELD_DST_OFFSET'           => 16,
        'FIELD_YEAR_WOY'             => 17,
        'FIELD_DOW_LOCAL'            => 18,
        'FIELD_EXTENDED_YEAR'        => 19,
        'FIELD_JULIAN_DAY'           => 20,
        'FIELD_MILLISECONDS_IN_DAY'  => 21,
        'FIELD_IS_LEAP_MONTH'        => 22,
        'FIELD_FIELD_COUNT'          => 23,
    );
    function getSetFields(IntlCalendar $cal) {
        global $fields;
        $ret = array();
        foreach ($fields as $name => $value) {
            if ($cal->isSet($value)) {
                $ret[] = $name;
            }
        }
        return $ret;
    }

    $cal = new IntlGregorianCalendar(2013, 2 /* March */, 15);
    echo "After GregorianCalendar creation\n";
    print_r(getSetFields($cal));
    echo "\n";

    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "After the formatter requested the extended year\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear(IntlCalendar::FIELD_YEAR);
    echo "After the year has been cleared, the date stays the same\n";
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "because FIELD_EXTENDED_YEAR is still set\n";
    print_r(getSetFields($cal));
    echo "\n";

    var_dump($cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR));
    echo "After the extended year has been cleared\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";
    echo "\n";

    echo "After the fields are recalculated,\n"
            . " extended year is set again (to 1970)\n";
    print_r(getSetFields($cal));
    echo "\n";

    $cal->clear();
    echo "After calling variant with no arguments\n";
    print_r(getSetFields($cal));
    echo IntlDateFormatter::formatObject($cal), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    After GregorianCalendar creation
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
    )

    15/03/2013 00:00:00
    After the formatter requested the extended year
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_YEAR
        [2] => FIELD_MONTH
        [3] => FIELD_DATE
        [4] => FIELD_EXTENDED_YEAR
    )

    After the year has been cleared, the date stays the same
    15/03/2013 00:00:00
    because FIELD_EXTENDED_YEAR is still set
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    bool(true)
    After the extended year has been cleared
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
    )
    15/03/1970 00:00:00

    After the fields are recalculated,
     extended year is set again (to 1970)
    Array
    (
        [0] => FIELD_ERA
        [1] => FIELD_MONTH
        [2] => FIELD_DATE
        [3] => FIELD_EXTENDED_YEAR
    )

    After calling variant with no arguments
    Array
    (
    )
    01/01/1970 00:00:00

# IntlCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::__construct — Private constructor for disallowing instantiation

### Beschreibung

private function IntlCalendar::__construct()

A private constructor for disallowing instantiation with the new operator.

Call IntlCalendar::createInstance() instead.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# IntlCalendar::createInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::createInstance — Create a new IntlCalendar

### Beschreibung

Objektorientierter Stil

public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

Prozeduraler Stil

function intlcal_create_instance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

Given a timezone and locale, this method creates an IntlCalendar object. This factory method may return a subclass of IntlCalendar.

The calendar created will represent the time instance at which it was created, based on the system time. The fields can all be cleared by calling IntCalendar::clear() with no arguments. See also IntlGregorianCalendar::__construct().

### Parameter-Liste

`timezone`

  The timezone to use.

  - `null`, in which case the default timezone will be used, as specified in the ini setting date.timezone or through the function date_default_timezone_set() and as returned by date_default_timezone_get().

  - An IntlTimeZone, which will be used directly.

  - A DateTimeZone. Its identifier will be extracted and an ICU timezone object will be created; the timezone will be backed by ICUʼs database, not PHPʼs.

  - A string, which should be a valid ICU timezone identifier. See IntlTimeZone::createTimeZoneIDEnumeration(). Raw offsets such as `"GMT+08:30"` are also accepted.

`locale`

  A locale to use or `null` to use the default locale.

### Rückgabewerte

The created IntlCalendar instance or `null` on failure.

### Beispiele

Beispiel #1 IntlCalendar::createInstance()

    <?php
    ini_set('intl.default_locale', 'es_ES');
    ini_set('date.timezone', 'Europe/Madrid');

    $cal = IntlCalendar::createInstance();
    echo "No arguments\n";
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Explicit timezone\n";
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT());
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));
    echo "\n";

    echo "Explicit locale (with calendar)\n";
    $cal = IntlCalendar::createInstance(NULL, 'es_ES@calendar=persian');
    var_dump(get_class($cal),
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    No arguments
    string(21) "IntlGregorianCalendar"
    string(68) "martes 18 de junio de 2013 14:11:02 Hora de verano de Europa Central"

    Explicit timezone
    string(21) "IntlGregorianCalendar"
    string(45) "martes 18 de junio de 2013 12:11:02 GMT+00:00"

    Explicit locale (with calendar)
    string(12) "IntlCalendar"
    string(70) "martes 28 de Khordad de 1392 14:11:02 Hora de verano de Europa Central"

### Siehe auch

- IntlGregorianCalendar::__construct() - Create the Gregorian Calendar class

# IntlCalendar::equals

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::equals — Compare time of two IntlCalendar objects for equality

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::equals(IntlCalendar `$other`): bool

Prozeduraler Stil

function intlcal_equals(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Returns true if this calendar and the given calendar have the same time. The settings, calendar types and field states do not have to be the same.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`other`

  The calendar to compare with the primary object.

### Rückgabewerte

Returns `true` if the current time of both this and the passed in IntlCalendar object are the same, or `false` otherwise.

Bei einem Fehler wird auch `false` zurückgegeben. Um Fehlerzustände zu erkennen, kann die Funktion intl_get_error_code() verwendet werden oder Intl so konfiguriert werden, dass es Exceptions auslöst.

### Beispiele

Beispiel #1 IntlCalendar::equals()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    $cal2 = clone $cal1;

    var_dump($cal1->equals($cal2)); //TRUE

    //The locale is not included in the comparison
    $cal2 = IntlCalendar::createInstance(NULL, 'pt_PT');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    //And set fields state is not included as well
    $cal2->clear(IntlCalendar::FIELD_YEAR);
    var_dump($cal1->isSet(IntlCalendar::FIELD_YEAR) ==
            $cal2->isSet(IntlCalendar::FIELD_YEAR)); //FALSE
    var_dump($cal1->equals($cal2)); //TRUE

    //Neither is the calendar type
    $cal2 = IntlCalendar::createInstance(NULL, 'es_ES@calendar=islamic');
    $cal2->setTime($cal1->getTime());
    var_dump($cal1->equals($cal2)); //TRUE

    //Only the time is
    $cal2 = clone $cal1;
    $cal2->setTime($cal1->getTime() + 1.);
    var_dump($cal1->equals($cal2)); //FALSE

# IntlCalendar::fieldDifference

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::fieldDifference — Calculate difference between given time and this objectʼs time

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false

Prozeduraler Stil

function intlcal_field_difference(IntlCalendar `$calendar`, float `$timestamp`, int `$field`): int|false

Return the difference between the given time and the time this object is set to, with respect to the quantity specified the `field` parameter.

This method is meant to be called successively, first with the most significant field of interest down to the least significant field. To this end, as a side effect, this calendarʼs value for the field specified is advanced by the amount returned.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`timestamp`

  The time against which to compare the quantity represented by the `field`. For the result to be positive, the time given for this parameter must be ahead of the time of the object the method is being invoked on.

`field`

  The field that represents the quantity being compared.

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

Returns a (signed) difference of time in the unit associated with the specified fieldBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlCalendar::fieldDifference()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal1 = IntlCalendar::fromDateTime('2012-02-29 09:00:11');
    $cal2 = IntlCalendar::fromDateTime('2013-03-01 09:19:29');
    $time = $cal2->getTime();

    echo "Time before: ", IntlDateFormatter::formatObject($cal1), "\n";

    printf(
        "The difference in time is %d year(s), %d month(s), "
      . "%d day(s), %d hour(s) and %d minute(s)\n",
        $cal1->fieldDifference($time, IntlCalendar::FIELD_YEAR),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_DAY_OF_MONTH),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_HOUR_OF_DAY),
        $cal1->fieldDifference($time, IntlCalendar::FIELD_MINUTE)
    );

    //now it was advanced to the target time, exception for the seconds,
    //for which we did not measure the difference
    echo "Time after: ", IntlDateFormatter::formatObject($cal1), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Time before: 29 févr. 2012 09:00:11
    The difference in time is 1 year(s), 0 month(s), 1 day(s), 0 hour(s) and 19 minute(s)
    Time after: 1 mars 2013 09:19:11

# IntlCalendar::fromDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::fromDateTime — Create an IntlCalendar from a DateTime object or string

### Beschreibung

Objektorientierter Stil

public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Prozeduraler Stil

function intlcal_from_date_time(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

Creates an IntlCalendar object either from a DateTime object or from a string from which a DateTime object can be built.

The new calendar will represent not only the same instant as the given DateTime (subject to precision loss for dates very far into the past or future), but also the same timezone (subject to the caveat that different timezone databases will be used, and therefore the results may differ).

### Parameter-Liste

`datetime`

  A DateTime object or a string that can be passed to DateTime::__construct().

### Rückgabewerte

The created IntlCalendar object or `null` in case of failure. If a string is passed, any exception that occurs inside the DateTime constructor is propagated.

### Beispiele

Beispiel #1 IntlCalendar::fromDateTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    //same as IntlCalendar::fromDateTime(new DateTime(...))
    $cal1 = IntlCalendar::fromDateTime('2013-02-28 00:01:02 Europe/Berlin', 'de_DE');

    //Note the timezone is Europe/Berlin, not the default Europe/Lisbon
    echo IntlDateFormatter::formatObject($cal1, 'yyyy MMMM d HH:mm:ss VVVV', 'de_DE'), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2013 Februar 28 00:01:02 Deutschland Zeit

# IntlCalendar::get

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::get — Get the value for a field

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::get(int `$field`): int|false

Prozeduraler Stil

function intlcal_get(IntlCalendar `$calendar`, int `$field`): int|false

Gets the value for a specific field.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

An integer with the value of the time field.

### Beispiele

Beispiel #1 IntlCalendar::get()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $class = new ReflectionClass('IntlCalendar');
    $fields = array();
    foreach ($class->getConstants() as $name => $val) {
        if (strpos($name, 'FIELD_') !== 0 || $val > 22)
            continue;
        $fields[$val] = $name;
    }

    $cal = IntlCalendar::createInstance(); // current time
    var_dump(IntlDateFormatter::formatObject($cal));
    foreach ($fields as $val => $name) {
        echo "$val ($name)", "\n    ", $cal->get($val), "\n";
    }

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(23) "Jul 1, 2013, 4:44:44 AM"
    0 (FIELD_ERA)
        1
    1 (FIELD_YEAR)
        2013
    2 (FIELD_MONTH)
        6
    3 (FIELD_WEEK_OF_YEAR)
        27
    4 (FIELD_WEEK_OF_MONTH)
        1
    5 (FIELD_DAY_OF_MONTH)
        1
    6 (FIELD_DAY_OF_YEAR)
        182
    7 (FIELD_DAY_OF_WEEK)
        2
    8 (FIELD_DAY_OF_WEEK_IN_MONTH)
        1
    9 (FIELD_AM_PM)
        0
    10 (FIELD_HOUR)
        4
    11 (FIELD_HOUR_OF_DAY)
        4
    12 (FIELD_MINUTE)
        44
    13 (FIELD_SECOND)
        44
    14 (FIELD_MILLISECOND)
        551
    15 (FIELD_ZONE_OFFSET)
        0
    16 (FIELD_DST_OFFSET)
        3600000
    17 (FIELD_YEAR_WOY)
        2013
    18 (FIELD_DOW_LOCAL)
        2
    19 (FIELD_EXTENDED_YEAR)
        2013
    20 (FIELD_JULIAN_DAY)
        2456475
    21 (FIELD_MILLISECONDS_IN_DAY)
        17084551
    22 (FIELD_IS_LEAP_MONTH)
        0

# IntlCalendar::getActualMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMaximum — The maximum value for a field, considering the objectʼs current time

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getActualMaximum(int `$field`): int|false

Prozeduraler Stil

function intlcal_get_actual_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Returns a fieldʼs relative maximum value around the current time. The exact semantics vary by field, but in the general case this is the value that would be obtained if one would set the field value into the smallest relative maximum for the field and would increment it until reaching the global maximum or the field value wraps around, in which the value returned would be the global maximum or the value before the wrapping, respectively.

For instance, in the gregorian calendar, the actual maximum value for the day of month would vary between `28` and `31`, depending on the month and year of the current time.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

An int representing the maximum value in the units associated with the given `field`Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlCalendar::getActualMaximum()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = IntlCalendar::fromDateTime('2013-02-15');
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //28

    $cal->add(IntlCalendar::FIELD_EXTENDED_YEAR, -1);
    var_dump($cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)); //29

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(28)
    int(29)

### Siehe auch

- IntlCalendar::getMaximum() - Get the global maximum value for a field
- IntlCalendar::getLeastMaximum() - Get the smallest local maximum for a field
- IntlCalendar::getActualMinimum() - The minimum value for a field, considering the objectʼs current time

# IntlCalendar::getActualMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMinimum — The minimum value for a field, considering the objectʼs current time

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getActualMinimum(int `$field`): int|false

Prozeduraler Stil

function intlcal_get_actual_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Returns a fieldʼs relative minimum value around the current time. The exact semantics vary by field, but in the general case this is the value that would be obtained if one would set the field value into the greatest relative minimum for the field and would decrement it until reaching the global minimum or the field value wraps around, in which the value returned would be the global minimum or the value before the wrapping, respectively.

For the Gregorian calendar, this is always the same as IntlCalendar::getMinimum().

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

An int representing the minimum value in the fieldʼs unitBei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- IntlCalendar::getMinimum() - Get the global minimum value for a field
- IntlCalendar::getGreatestMinimum() - Get the largest local minimum value for a field
- IntlCalendar::getActualMaximum() - The maximum value for a field, considering the objectʼs current time

# IntlCalendar::getAvailableLocales

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getAvailableLocales — Get array of locales for which there is data

### Beschreibung

Objektorientierter Stil

public static function IntlCalendar::getAvailableLocales(): array

Prozeduraler Stil

function intlcal_get_available_locales(): array

Gives the list of locales for which calendars are installed. As of ICU 51, this is the list of all installed ICU locales.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array of strings, one for each locale.

### Beispiele

Beispiel #1 IntlCalendar::getAvailableLocales()

    <?php
    print_r(IntlCalendar::getAvailableLocales());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => af
        [1] => af_NA
        [2] => af_ZA
        [3] => agq
        [4] => agq_CM
        [5] => ak
        [6] => ak_GH
        [7] => am
        [8] => am_ET
        [9] => ar
        [10] => ar_001
        [11] => ar_AE
        [12] => ar_BH
        [13] => ar_DJ
        … output abbreviated …
        [595] => zh_Hant_HK
        [596] => zh_Hant_MO
        [597] => zh_Hant_TW
        [598] => zu
        [599] => zu_ZA
    )

# IntlCalendar::getDayOfWeekType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getDayOfWeekType — Tell whether a day is a weekday, weekend or a day that has a transition between the two

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false

Prozeduraler Stil

function intlcal_get_day_of_week_type(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

Returns whether the passed day is a weekday (`IntlCalendar::DOW_TYPE_WEEKDAY`), a weekend day (`IntlCalendar::DOW_TYPE_WEEKEND`), a day during which a transition occurs into the weekend (`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET`) or a day during which the weekend ceases (`IntlCalendar::DOW_TYPE_WEEKEND_CEASE`).

If the return is either `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` or `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`, then IntlCalendar::getWeekendTransition() can be called to obtain the time of the transition.

This function requires ICU 4.4 or later.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`dayOfWeek`

  One of the constants `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Rückgabewerte

Returns one of the constants `IntlCalendar::DOW_TYPE_WEEKDAY`, `IntlCalendar::DOW_TYPE_WEEKEND`, `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` or `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlCalendar::getDayOfWeekType()

    <?php
    foreach (array('en_US', 'ar_SA') as $locale) {
        echo "Locale: ", Locale::getDisplayName($locale, "en_US"), "\n";

        $cal = IntlCalendar::createInstance('UTC', $locale);

        for ($i = IntlCalendar::DOW_SUNDAY; $i <= IntlCalendar::DOW_SATURDAY; $i++) {
            $type = $cal->getDayOfWeekType($i);
            $transition = ($type !== IntlCalendar::DOW_TYPE_WEEKDAY)
                ? $cal->getWeekendTransition($i)
                : '';
            echo $i, " ", $type, " ", $transition, "\n";
        }
        echo "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Locale: English (United States)
    1 1 86400000
    2 0
    3 0
    4 0
    5 0
    6 0
    7 1 0

    Locale: Arabic (Saudi Arabia)
    1 0
    2 0
    3 0
    4 0
    5 0
    6 1 0
    7 1 86400000

# IntlCalendar::getErrorCode

# intlcal_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorCode -- intlcal_get_error_code — Get last error code on the object

### Beschreibung

Objektorientierter Stil (method):

public function IntlCalendar::getErrorCode(): int|false

Prozeduraler Stil:

function intlcal_get_error_code(IntlCalendar `$calendar`): int|false

Returns the numeric ICU error code for the last call on this object (including cloning) or the IntlCalendar given for the `calendar` parameter (in the procedural‒style version). This may indicate only a warning (negative error code) or no error at all (`U_ZERO_ERROR`). The actual presence of an error can be tested with intl_is_failure().

Invalid arguments detected on the PHP side (before invoking functions of the ICU library) are not recorded for the purposes of this function.

The last error that occurred in any call to a function of the intl extension, including early argument errors, can be obtained with intl_get_error_code(). This function resets the global error code, but not the objectʼs error code.

### Parameter-Liste

`calendar`

  The calendar object, on the procedural style interface.

### Rückgabewerte

An ICU error code indicating either success, failure or a warning. Returns `false` on failure.

### Beispiele

Beispiel #1 IntlCalendar::getErrorCode() and IntlCalendar::getErrorMessage()

    <?php
    ini_set("intl.error_level", E_WARNING);
    ini_set("intl.default_locale", "nl");

    $intlcal = new IntlGregorianCalendar(2012, 1, 29);
    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );
    $intlcal->fieldDifference(-1e100, IntlCalendar::FIELD_SECOND);

    var_dump(
        $intlcal->getErrorCode(),
        $intlcal->getErrorMessage()
    );

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    string(12) "U_ZERO_ERROR"

    Warning: IntlCalendar::fieldDifference(): intlcal_field_difference: Call to ICU method has failed in /home/glopes/php/ws/example.php on line 10
    int(1)
    string(81) "intlcal_field_difference: Call to ICU method has failed: U_ILLEGAL_ARGUMENT_ERROR"

### Siehe auch

- IntlCalendar::getErrorMessage() - Get last error message on the object
- intl_is_failure() - Check whether the given error code indicates failure
- intl_error_name() - Get symbolic name for a given error code
- intl_get_error_code() - Get the last error code
- intl_get_error_message() - Get description of the last error

# IntlCalendar::getErrorMessage

# intlcal_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getErrorMessage -- intlcal_get_error_message — Get last error message on the object

### Beschreibung

Objektorientierter Stil (method):

public function IntlCalendar::getErrorMessage(): string|false

Prozeduraler Stil:

function intlcal_get_error_message(IntlCalendar `$calendar`): string|false

Returns the error message (if any) associated with the error reported by IntlCalendar::getErrorCode() or intlcal_get_error_code(). If there is no associated error message, only the string representation of the name of the error constant will be returned. Otherwise, the message also includes a message set on the side of the PHP binding.

### Parameter-Liste

`calendar`

  The calendar object, on the procedural style interface.

### Rückgabewerte

The error message associated with last error that occurred in a function call on this object, or a string indicating the non-existence of an error. Returns `false` on failure.

### Beispiele

Beispiel #1 IntlCalendar::getErrorMessage()

    <?php
    $cal = IntlCalendar::createInstance('UTC', 'en_US');
    var_dump($cal->getErrorMessage());

    $cal->getWeekendTransition(IntlCalendar::DOW_WEDNESDAY);
    var_dump($cal->getErrorMessage());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(12) "U_ZERO_ERROR"
    string(82) "intlcal_get_weekend_transition: Error calling ICU method: U_ILLEGAL_ARGUMENT_ERROR"

# IntlCalendar::getFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getFirstDayOfWeek — Get the first day of the week for the calendarʼs locale

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getFirstDayOfWeek(): int|false

Prozeduraler Stil

function intlcal_get_first_day_of_week(IntlCalendar `$calendar`): int|false

The week day deemed to start a week, either the default value for this locale or the value set with IntlCalendar::setFirstDayOfWeek().

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

One of the constants `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlCalendar::getFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'UTC');

    $cal1 = IntlCalendar::createInstance(NULL, 'es_ES');
    var_dump($cal1->getFirstDayOfWeek()); // Monday
    $cal1->set(2013, 1 /* February */, 3); // a Sunday
    var_dump($cal1->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 5

    $cal2 = IntlCalendar::createInstance(NULL, 'en_US');
    var_dump($cal2->getFirstDayOfWeek()); // Sunday
    $cal2->set(2013, 1 /* February */, 3); // a Sunday
    var_dump($cal2->get(IntlCalendar::FIELD_WEEK_OF_YEAR)); // 6

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(2)
    int(5)
    int(1)
    int(6)

### Siehe auch

- IntlCalendar::setFirstDayOfWeek() - Set the day on which the week is deemed to start

# IntlCalendar::getGreatestMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getGreatestMinimum — Get the largest local minimum value for a field

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getGreatestMinimum(int `$field`): int|false

Prozeduraler Stil

function intlcal_get_greatest_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Returns the largest local minimum for a field. This should be a value larger or equal to that returned by IntlCalendar::getActualMinimum(), which is in its turn larger or equal to that returned by IntlCalendar::getMinimum(). All these three functions return the same value for the Gregorian calendar.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

An int representing a field value, in the fieldʼs unit,Bei einem Fehler wird `false` zurückgegeben..

# IntlCalendar::getKeywordValuesForLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getKeywordValuesForLocale — Get set of locale keyword values

### Beschreibung

Objektorientierter Stil

public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

Prozeduraler Stil

function intlcal_get_keyword_values_for_locale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

For a given locale key, get the set of values for that key that would result in a different behavior. For now, only the `'calendar'` keyword is supported.

This function requires ICU 4.2 or later.

### Parameter-Liste

`keyword`

  The locale keyword for which relevant values are to be queried. Only `'calendar'` is supported.

`locale`

  The locale onto which the keyword/value pair are to be appended.

`onlyCommon`

  Whether to show only the values commonly used for the specified locale.

### Rückgabewerte

An iterator that yields strings with the locale keyword valuesBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlCalendar::getKeywordValuesForLocale()

    <?php
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', true)));
    print_r(
            iterator_to_array(
                    IntlCalendar::getKeywordValuesForLocale(
                            'calendar', 'fa_IR', false)));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
    )
    Array
    (
        [0] => persian
        [1] => gregorian
        [2] => islamic
        [3] => islamic-civil
        [4] => japanese
        [5] => buddhist
        [6] => roc
        [7] => hebrew
        [8] => chinese
        [9] => indian
        [10] => coptic
        [11] => ethiopic
        [12] => ethiopic-amete-alem
    )

# IntlCalendar::getLeastMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLeastMaximum — Get the smallest local maximum for a field

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getLeastMaximum(int `$field`): int|false

Prozeduraler Stil

function intlcal_get_least_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Returns the smallest local maximum for a field. This should be a value smaller or equal to that returned by IntlCalendar::getActualMaximum(), which is in its turn smaller or equal to that returned by IntlCalendar::getMaximum().

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

An int representing a field value in the fieldʼs unitBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Maxima examples

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'it_IT');

    $cal = new IntlGregorianCalendar(2013, 3 /* April */, 6);
    var_dump(
        $cal->getLeastMaximum(IntlCalendar::FIELD_DAY_OF_MONTH),  // 28
        $cal->getActualMaximum(IntlCalendar::FIELD_DAY_OF_MONTH), // 30
        $cal->getMaximum(IntlCalendar::FIELD_DAY_OF_MONTH)        // 31
    );

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(28)
    int(30)
    int(31)

### Siehe auch

- IntlCalendar::getActualMaximum() - The maximum value for a field, considering the objectʼs current time
- IntlCalendar::getMaximum() - Get the global maximum value for a field
- IntlCalendar::getGreatestMinimum() - Get the largest local minimum value for a field

# IntlCalendar::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLocale — Get the locale associated with the object

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getLocale(int `$type`): string|false

Prozeduraler Stil

function intlcal_get_locale(IntlCalendar `$calendar`, int `$type`): string|false

Returns the locale used by this calendar object.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`type`

  Whether to fetch the actual locale (the locale from which the calendar data originates, with `Locale::ACTUAL_LOCALE`) or the valid locale, i.e., the most specific locale supported by ICU relatively to the requested locale – see `Locale::VALID_LOCALE`. From the most general to the most specific, the locales are ordered in this fashion – actual locale, valid locale, requested locale.

### Rückgabewerte

A locale stringBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlCalendar::getLocale()

    <?php
    $cal = IntlCalendar::createInstance(IntlTimeZone::getGMT(), 'en_US_CALIFORNIA');
    var_dump(
        $cal->getLocale(Locale::ACTUAL_LOCALE),
        $cal->getLocale(Locale::VALID_LOCALE)
    );

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(2) "en"
    string(5) "en_US"

# IntlCalendar::getMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMaximum — Get the global maximum value for a field

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getMaximum(int `$field`): int|false

Prozeduraler Stil

function intlcal_get_maximum(IntlCalendar `$calendar`, int `$field`): int|false

Gets the global maximum for a field, in this specific calendar. This value is larger or equal to that returned by IntlCalendar::getActualMaximum(), which is in its turn larger or equal to that returned by IntlCalendar::getLeastMaximum().

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

An int representing a field value in the fieldʼs unitBei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- IntlCalendar::getActualMaximum() - The maximum value for a field, considering the objectʼs current time
- IntlCalendar::getLeastMaximum() - Get the smallest local maximum for a field
- IntlCalendar::getMinimum() - Get the global minimum value for a field

# IntlCalendar::getMinimalDaysInFirstWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimalDaysInFirstWeek — Get minimal number of days the first week in a year or month can have

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false

Prozeduraler Stil

function intlcal_get_minimal_days_in_first_week(IntlCalendar `$calendar`): int|false

Returns the smallest number of days the first week of a year or month must have in the new year or month. For instance, in the Gregorian calendar, if this value is 1, then the first week of the year will necessarily include January 1st, while if this value is 7, then the week with January 1st will be the first week of the year only if the day of the week for January 1st matches the day of the week returned by IntlCalendar::getFirstDayOfWeek(); otherwise it will be the previous yearʼs last week.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

An int representing a number of daysBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlCalendar::getMinimalDaysInFirstWeek()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'en_US');

    $cal = new IntlGregorianCalendar(2013, 0 /* January */, 2);
    var_dump(IntlDateFormatter::formatObject($cal, 'cccc')); // Wednesday

    var_dump($cal->getMinimalDaysInFirstWeek(), // 1
    $cal->getFirstDayofWeek()); // 1 (Sunday)

    // Week 1 of 2013
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

    $cal->setMinimalDaysInFirstWeek(4);
    // Still Week 1 of 2013 (1st week has 5 days in the new year)
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

    $cal->setMinimalDaysInFirstWeek(6);
    // Week 53 of 2012
    var_dump(IntlDateFormatter::formatObject($cal, "'Week 'w' of 'Y"));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(9) "Wednesday"
    int(1)
    int(1)
    string(14) "Week 1 of 2013"
    string(14) "Week 1 of 2013"
    string(15) "Week 53 of 2012"

# IntlCalendar::getMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimum — Get the global minimum value for a field

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getMinimum(int `$field`): int|false

Prozeduraler Stil

function intlcal_get_minimum(IntlCalendar `$calendar`, int `$field`): int|false

Gets the global minimum for a field, in this specific calendar. This value is smaller or equal to that returned by IntlCalendar::getActualMinimum(), which is in its turn smaller or equal to that returned by IntlCalendar::getGreatestMinimum(). For the Gregorian calendar, these three functions always return the same value (for each field).

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

An int representing a value for the given field in the fieldʼs unitBei einem Fehler wird `false` zurückgegeben..

# IntlCalendar::getNow

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getNow — Get number representing the current time

### Beschreibung

Objektorientierter Stil

public static function IntlCalendar::getNow(): float

Prozeduraler Stil

function intlcal_get_now(): float

The number of milliseconds that have passed since the reference date. This number is derived from the system time.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

A float representing a number of milliseconds since the epoch, not counting leap seconds.

### Beispiele

Beispiel #1 IntlCalendar::getNow()

    <?php
    $formatter = IntlDateFormatter::create('es_ES',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'Europe/Madrid');

    $val = IntlCalendar::getNow();

    var_dump($val);
    echo $formatter->format(IntlCalendar::getNow() / 1000.), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(1371425814666)
    lunes, 17 de junio de 2013 01:36:54 Hora de verano de Europa central

# IntlCalendar::getRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getRepeatedWallTimeOption — Get behavior for handling repeating wall time

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getRepeatedWallTimeOption(): int

Prozeduraler Stil

function intlcal_get_repeated_wall_time_option(IntlCalendar `$calendar`): int

Gets the current strategy for dealing with wall times that are repeated whenever the clock is set back during dailight saving time end transitions. The default value is `IntlCalendar::WALLTIME_LAST`.

This function requires ICU 4.9 or later.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

One of the constants `IntlCalendar::WALLTIME_FIRST` or `IntlCalendar::WALLTIME_LAST`.

### Beispiele

Beispiel #1 IntlCalendar::getRepeatedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');
    ini_set('intl.error_level', E_WARNING);

    //On October 27th at 0200, the clock goes back 1 hour and from GMT+01 to GMT+00
    $cal = new IntlGregorianCalendar(2013, 9 /* October */, 27, 1, 30);

    var_dump($cal->getRepeatedWalltimeOption()); // 0 WALLTIME_LAST

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000.));

    $cal->setRepeatedWalltimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getRepeatedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000.));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    string(42) "Sunday, October 27, 2013 at 1:30:00 AM GMT"
    int(1)
    string(43) "Sunday, October 27, 2013 at 12:30:00 AM GMT"

### Siehe auch

- IntlCalendar::getSkippedWallTimeOption() - Get behavior for handling skipped wall time
- IntlCalendar::setSkippedWallTimeOption() - Set behavior for handling skipped wall times at positive timezone offset transitions
- IntlCalendar::setRepeatedWallTimeOption() - Set behavior for handling repeating wall times at negative timezone offset transitions

# IntlCalendar::getSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getSkippedWallTimeOption — Get behavior for handling skipped wall time

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getSkippedWallTimeOption(): int

Prozeduraler Stil

function intlcal_get_skipped_wall_time_option(IntlCalendar `$calendar`): int

Gets the current strategy for dealing with wall times that are skipped whenever the clock is forwarded during dailight saving time start transitions. The default value is `IntlCalendar::WALLTIME_LAST`.

The calendar must be lenient for this option to have any effect, otherwise attempting to set a non-existing time will cause an error.

This function requires ICU 4.9 or later.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

One of the constants `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` or `IntlCalendar::WALLTIME_NEXT_VALID`.

### Beispiele

Beispiel #1 IntlCalendar::getSkippedWallTimeOption()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');
    ini_set('intl.error_level', E_WARNING);

    //On March 31st at 0100, the clock goes forward 1 hour and from GMT+00 to GMT+01
    $cal = new IntlGregorianCalendar(2013, 2 /* March */, 31, 1, 30);

    var_dump(
        $cal->isLenient(),               // true
        $cal->getSkippedWalltimeOption() // 0 WALLTIME_LAST
    );

    $formatter = IntlDateFormatter::create(
        NULL,
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'UTC'
    );
    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    var_dump($cal->getSkippedWalltimeOption()); // 1 WALLTIME_FIRST
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

    $cal->setSkippedWallTimeOption(IntlCalendar::WALLTIME_NEXT_VALID);
    var_dump($cal->getSkippedWalltimeOption()); // 2 WALLTIME_NEXT_VALID
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1);

    var_dump($formatter->format($cal->getTime() / 1000));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    int(0)
    string(40) "Sunday, March 31, 2013 at 1:30:00 AM GMT"
    int(1)
    string(41) "Sunday, March 31, 2013 at 12:30:00 AM GMT"
    int(2)
    string(40) "Sunday, March 31, 2013 at 1:00:00 AM GMT"

### Siehe auch

- IntlCalendar::getRepeatedWallTimeOption() - Get behavior for handling repeating wall time
- IntlCalendar::setSkippedWallTimeOption() - Set behavior for handling skipped wall times at positive timezone offset transitions
- IntlCalendar::setRepeatedWallTimeOption() - Set behavior for handling repeating wall times at negative timezone offset transitions

# IntlCalendar::getTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTime — Get time currently represented by the object

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getTime(): float|false

Prozeduraler Stil

function intlcal_get_time(IntlCalendar `$calendar`): float|false

Returns the time associated with this object, expressed as the number of milliseconds since the epoch.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

A float representing the number of milliseconds elapsed since the reference time (1 Jan 1970 00:00:00 UTC),Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 IntlCalendar::getTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = new IntlGregorianCalendar(2013, 4 /* May */, 1, 0, 0, 0);
    $time = $cal->getTime();
    var_dump($time, $time / 1000 == strtotime('2013-05-01 00:00:00')); //true

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(1367362800000)
    bool(true)

### Siehe auch

- IntlCalendar::getNow() - Get number representing the current time

# IntlCalendar::getTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTimeZone — Get the objectʼs timezone

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getTimeZone(): IntlTimeZone|false

Prozeduraler Stil

function intlcal_get_time_zone(IntlCalendar `$calendar`): IntlTimeZone|false

Returns the IntlTimeZone object associated with this calendar.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

An IntlTimeZone object corresponding to the one used internally in this object. Returns `false` on failure.

### Beispiele

Beispiel #1 IntlCalendar::getTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = IntlCalendar::createInstance();
    print_r($cal->getTimeZone());

    $cal->setTimeZone('UTC');
    print_r($cal->getTimeZone());

    $cal = IntlCalendar::fromDateTime('2012-01-01 00:00:00 GMT+03:33');
    print_r($cal->getTimeZone());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    IntlTimeZone Object
    (
        [valid] => 1
        [id] => Europe/Lisbon
        [rawOffset] => 0
        [currentOffset] => 3600000
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => UTC
        [rawOffset] => 0
        [currentOffset] => 0
    )
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+03:33
        [rawOffset] => 12780000
        [currentOffset] => 12780000
    )

### Siehe auch

- IntlCalendar::setTimeZone() - Set the timezone used by this calendar
- IntlCalendar::createInstance() - Create a new IntlCalendar
- IntlGregorianCalendar::__construct() - Create the Gregorian Calendar class

# IntlCalendar::getType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getType — Get the calendar type

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getType(): string

Prozeduraler Stil

function intlcal_get_type(IntlCalendar `$calendar`): string

A string describing the type of this calendar. This is one of the valid values for the calendar keyword value `'calendar'`.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

A string representing the calendar type, such as `'gregorian'`, `'islamic'`, etc.

### Beispiele

Beispiel #1 IntlCalendar::getType()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'en_US');

    $cal = IntlCalendar::createInstance(NULL, '@calendar=ethiopic-amete-alem');
    var_dump($cal->getType());

    $cal = new IntlGregorianCalendar();
    var_dump($cal->getType());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(19) "ethiopic-amete-alem"
    string(9) "gregorian"

# IntlCalendar::getWeekendTransition

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getWeekendTransition — Get time of the day at which weekend begins or ends

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false

Prozeduraler Stil

function intlcal_get_weekend_transition(IntlCalendar `$calendar`, int `$dayOfWeek`): int|false

Returns the number of milliseconds after midnight at which the weekend begins or ends.

This is only applicable for days of the week for which IntlCalendar::getDayOfWeekType() returns either `IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` or `IntlCalendar::DOW_TYPE_WEEKEND_CEASE`. Calling this function for other days of the week is an error condition.

This function requires ICU 4.4 or later.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`dayOfWeek`

  One of the constants `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Rückgabewerte

The number of milliseconds into the day at which the weekend begins or endsBei einem Fehler wird `false` zurückgegeben..

### Beispiele

See example on IntlCalendar::getDayOfWeekType().

# IntlCalendar::inDaylightTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::inDaylightTime — Whether the objectʼs time is in Daylight Savings Time

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::inDaylightTime(): bool

Prozeduraler Stil

function intlcal_in_daylight_time(IntlCalendar `$calendar`): bool

Whether, for the instant represented by this object and for this objectʼs timezone, daylight saving time is in place.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

Returns `true` if the date is in Daylight Savings Time, `false` otherwise.

Bei einem Fehler wird auch `false` zurückgegeben. Um Fehlerzustände zu erkennen, kann die Funktion intl_get_error_code() verwendet werden oder Intl so konfiguriert werden, dass es Exceptions auslöst.

### Beispiele

Beispiel #1 IntlCalendar::inDaylightTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1, 4, 56, 31);
    var_dump($cal->inDaylightTime()); // true
    $cal->set(IntlCalendar::FIELD_MONTH, 11 /* December */);
    var_dump($cal->inDaylightTime()); // false

    //DST end transition on 2013-10-27 at 0200 (wall time back 1 hour)
    $cal = new IntlGregorianCalendar(2013, 9 /* October */, 27, 1, 30, 0);

    var_dump($cal->inDaylightTime()); // false (default WALLTIME_LAST)

    $cal->setRepeatedWallTimeOption(IntlCalendar::WALLTIME_FIRST);
    $cal->set(IntlCalendar::FIELD_HOUR_OF_DAY, 1); // force time recalculation
    var_dump($cal->inDaylightTime()); // true

# IntlCalendar::isEquivalentTo

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isEquivalentTo — Whether another calendar is equal but for a different time

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool

Prozeduraler Stil

function intlcal_is_equivalent_to(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

Returns whether this and the given object are equivalent for all purposes except as to the time they have set. The locales do not have to match, as long as no change in behavior results from such mismatch. This includes the timezone, whether the lenient mode is set, the repeated and skipped wall time settings, the days of the week when the weekend starts and ceases and the times where such transitions occur. It may also include other calendar specific settings, such as the Gregorian/Julian transition instant.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`other`

  The other calendar against which the comparison is to be made.

### Rückgabewerte

Assuming there are no argument errors, returns `true` if the calendars are equivalent except possibly for their set time.

### Beispiele

Beispiel #1 IntlCalendar::isEquivalentTo()

    <?php
    $cal1 = IntlCalendar::createInstance('Europe/Lisbon', 'pt_PT');
    $cal2 = IntlCalendar::createInstance('Europe/Lisbon', 'es_ES');
    $cal2->clear();

    var_dump($cal1->isEquivalentTo($cal2)); // true

    $cal3 = IntlCalendar::createInstance('Europe/Lisbon', 'en_US');
    var_dump($cal1->isEquivalentTo($cal3)); // false
    var_dump($cal1->getFirstDayOfWeek(),    // 2 (Monday)
    $cal3->getFirstDayOfWeek());            // 1 (Sunday)

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    int(2)
    int(1)

### Siehe auch

- IntlCalendar::equals() - Compare time of two IntlCalendar objects for equality

# IntlCalendar::isLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isLenient — Whether date/time interpretation is in lenient mode

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::isLenient(): bool

Prozeduraler Stil

function intlcal_is_lenient(IntlCalendar `$calendar`): bool

Returns whether the current date/time interpretations is lenient (the default). If that is case, some out of range values for fields will be accepted instead of raising an error.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

A bool representing whether the calendar is set to lenient mode.

### Beispiele

Beispiel #1 IntlCalendar::isLenient()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');
    ini_set('intl.use_exceptions', '1');

    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
    var_dump(IntlDateFormatter::formatObject($cal), // 01/07/2013, 00:00:00
    $cal->isLenient()); // true

    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // 02/08/2013, 00:00:00

    $cal->setLenient(false);
    var_dump($cal->isLenient()); // false
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 33);
    var_dump(IntlDateFormatter::formatObject($cal)); // error

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(20) "01/07/2013, 00:00:00"
    bool(true)
    string(20) "02/08/2013, 00:00:00"
    bool(false)

    Fatal error: Uncaught exception 'IntlException' with message 'datefmt_format_object: error obtaining instant from IntlCalendar' in /home/foobar/example.php:16
    Stack trace:
    #0 /home/foobar/example.php(16): IntlDateFormatter::formatObject(Object(IntlGregorianCalendar))
    #1 {main}
      thrown in /home/foobar/example.php on line 16

# IntlCalendar::isSet

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isSet — Whether a field is set

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::isSet(int `$field`): bool

Prozeduraler Stil

function intlcal_is_set(IntlCalendar `$calendar`, int `$field`): bool

Returns whether a field is set (as opposed to clear). Set fields take priority over unset fields and their default values when the date/time is being calculated. Fields set later take priority over fields set earlier.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

### Rückgabewerte

Assuming there are no argument errors, returns `true` if the field is set.

### Beispiele

See the example on IntlCalendar::clear().

### Siehe auch

- IntlCalendar::clear() - Clear a field or all fields
- IntlCalendar::set() - Set a time field or several common fields at once

# IntlCalendar::isWeekend

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isWeekend — Whether a certain date/time is in the weekend

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool

Prozeduraler Stil

function intlcal_is_weekend(IntlCalendar `$calendar`, ?float `$timestamp` = `null`): bool

Returns whether either the obejctʼs current time or the provided timestamp occur during a weekend in this objectʼs calendar system.

This function requires ICU 4.4 or later.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`timestamp`

  An optional timestamp representing the number of milliseconds since the epoch, excluding leap seconds. If `null`, this objectʼs current time is used instead.

### Rückgabewerte

A bool indicating whether the given or this objectʼs time occurs in a weekend.

Bei einem Fehler wird auch `false` zurückgegeben. Um Fehlerzustände zu erkennen, kann die Funktion intl_get_error_code() verwendet werden oder Intl so konfiguriert werden, dass es Exceptions auslöst.

### Beispiele

Beispiel #1 IntlCalendar::isWeekend()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');

    $cal = new IntlGregorianCalendar(NULL, 'en_US');
    $cal->set(2013, 6 /* July */, 7); // a Sunday

    var_dump($cal->isWeekend()); // true
    var_dump($cal->isWeekend(strtotime('2013-07-01 00:00:00'))); // false, Monday

    $cal = new IntlGregorianCalendar(NULL, 'ar_SA');
    $cal->set(2013, 6 /* July */, 7); // a Sunday
    var_dump($cal->isWeekend()); // false, Sunday not in weekend in this calendar

### Siehe auch

- IntlCalendar::getDayOfWeekType() - Tell whether a day is a weekday, weekend or a day that has a transition between the two
- IntlCalendar::getWeekendTransition() - Get time of the day at which weekend begins or ends

# IntlCalendar::roll

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::roll — Add value to field without carrying into more significant fields

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool

Prozeduraler Stil

function intlcal_roll(IntlCalendar `$calendar`, int `$field`, int|bool `$value`): bool

Adds a (signed) amount to a field. The difference with respect to IntlCalendar::add() is that when the field value overflows, it does not carry into more significant fields.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

`value`

  The (signed) amount to add to the field, `true` for rolling up (adding `1`), or `false` for rolling down (subtracting `1`).

### Rückgabewerte

Returns `true` on success or `false` on failure.

### Beispiele

Beispiel #1 IntlCalendar::roll()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = new IntlGregorianCalendar(2013, 5 /* June */, 30);

    $cal->add(IntlCalendar::FIELD_DAY_OF_MONTH, 1);
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/07/2013, 00:00:00"

    $cal->set(2013, 5 /* June */, 30);
    $cal->roll(IntlCalendar::FIELD_DAY_OF_MONTH, true); // roll up, same as rolling +1
    var_dump(IntlDateFormatter::formatObject($cal)); // "01/06/2013, 00:00:00"

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(20) "01/07/2013, 00:00:00"
    string(20) "01/06/2013, 00:00:00"

### Siehe auch

- IntlCalendar::add() - Add a (signed) amount of time to a field
- IntlCalendar::set() - Set a time field or several common fields at once

# IntlCalendar::set

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::set — Set a time field or several common fields at once

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true

Prozeduraler Stil

function intlcal_set(IntlCalendar `$cal`, int `$field`, int `$value`): true
function intlcal_set(
IntlCalendar `$cal`,
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): bool

Sets either a specific field to the given value, or sets at once several common fields. The range of values that are accepted depend on whether the calendar is using the lenient mode.

For fields that conflict, the fields that are set later have priority.

This method cannot be called with exactly four arguments.

### Parameter-Liste

`cal`

  Eine IntlCalendar-Instanz.

`field`

  One of the IntlCalendar date/time field constants. These are integer values between `0` and `IntlCalendar::FIELD_COUNT`.

`value`

  The new value of the given field.

`year`

  The new value for `IntlCalendar::FIELD_YEAR`.

`month`

  The new value for `IntlCalendar::FIELD_MONTH`. The month sequence is zero-based, i.e., January is represented by 0, February by 1, …, December is 11 and Undecember (if the calendar has it) is 12.

`dayOfMonth`

  The new value for `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  The new value for `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  The new value for `IntlCalendar::FIELD_MINUTE`.

`second`

  The new value for `IntlCalendar::FIELD_SECOND`.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Der Rückgabewert ist nun `true` vorher war es bool.
8.4.0 | This had been deprecated in favor of the methods IntlCalendar::setDate() and IntlCalendar::setDateTime().

### Beispiele

Beispiel #1 IntlCalendar::set()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'pt_PT');

    //Calls made later have priority
    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    var_dump(IntlDateFormatter::formatObject($cal));

    $cal = new IntlGregorianCalendar(2013, 6 /* July */, 1);
    $cal->set(IntlCalendar::FIELD_YEAR, 2012);
    $cal->set(IntlCalendar::FIELD_EXTENDED_YEAR, 2011);
    //the time has not been recalculated yet. If we clear the extended year,
    //the year set before will be used
    $cal->clear(IntlCalendar::FIELD_EXTENDED_YEAR);
    var_dump(IntlDateFormatter::formatObject($cal));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(20) "01/07/2011, 00:00:00"
    string(20) "01/07/2012, 00:00:00"

### Siehe auch

- IntlCalendar::get() - Get the value for a field
- IntlCalendar::add() - Add a (signed) amount of time to a field
- IntlCalendar::roll() - Add value to field without carrying into more significant fields

# IntlCalendar::setDate

(PHP 8 >= 8.3.0)

IntlCalendar::setDate — Set a date fields

### Beschreibung

public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void

Sets a date fields to the given value.

### Parameter-Liste

`year`

  The new value for `IntlCalendar::FIELD_YEAR`.

`month`

  The new value for `IntlCalendar::FIELD_MONTH`. The month sequence is zero-based, i.e., January is represented by 0, February by 1, …, December is 11 and Undecember (if the calendar has it) is 12.

`dayOfMonth`

  The new value for `IntlCalendar::FIELD_DAY_OF_MONTH`.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 IntlCalendar::setDate() example

    <?php
    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDate(2012, 1, 29);
    ?>

# IntlCalendar::setDateTime

(PHP 8 >= 8.3.0)

IntlCalendar::setDateTime — Set a date and time fields

### Beschreibung

public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void

Sets a date and time fields to the given value.

### Parameter-Liste

`year`

  The new value for `IntlCalendar::FIELD_YEAR`.

`month`

  The new value for `IntlCalendar::FIELD_MONTH`. The month sequence is zero-based, i.e., January is represented by 0, February by 1, …, December is 11 and Undecember (if the calendar has it) is 12.

`dayOfMonth`

  The new value for `IntlCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  The new value for `IntlCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  The new value for `IntlCalendar::FIELD_MINUTE`.

`second`

  The new value for `IntlCalendar::FIELD_SECOND`.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 IntlCalendar::setDateTime() example

    <?php
    $intlCal = IntlCalendar::createInstance('UTC');

    $intlCal->setDateTime(2012, 1, 29, 23, 58);
    ?>

# IntlCalendar::setFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setFirstDayOfWeek — Set the day on which the week is deemed to start

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true

Prozeduraler Stil

function intlcal_set_first_day_of_week(IntlCalendar `$calendar`, int `$dayOfWeek`): true

Defines the day of week deemed to start the week. This affects the behavior of fields that depend on the concept of week start and end such as `IntlCalendar::FIELD_WEEK_OF_YEAR` and `IntlCalendar::FIELD_YEAR_WOY`.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`dayOfWeek`

  One of the constants `IntlCalendar::DOW_SUNDAY`, `IntlCalendar::DOW_MONDAY`, …, `IntlCalendar::DOW_SATURDAY`.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Der Rückgabewert ist nun `true` vorher war es bool.

### Beispiele

Beispiel #1 IntlCalendar::setFirstDayOfWeek()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = IntlCalendar::createInstance();
    $cal->set(2013, 5 /* June */, 30); // A Sunday

    var_dump($cal->getFirstDayOfWeek()); // 2 (Monday)

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'local day of week: 'cc'
    week of month    : 'W'
    week of year     : 'ww
    EOD
    ), "\n";

    $cal->setFirstDayOfWeek(IntlCalendar::DOW_SUNDAY);

    echo IntlDateFormatter::formatObject($cal, <<<EOD
    'local day of week: 'cc'
    week of month    : 'W'
    week of year     : 'ww
    EOD
    ), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(2)
    local day of week: 7
    week of month    : 4
    week of year     : 26
    local day of week: 1
    week of month    : 5
    week of year     : 27

# IntlCalendar::setLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setLenient — Set whether date/time interpretation is to be lenient

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::setLenient(bool `$lenient`): true

Prozeduraler Stil

function intlcal_set_lenient(IntlCalendar `$calendar`, bool `$lenient`): true

Defines whether the calendar is ‘lenient mode’. In such a mode, some of out-of-bounds values for some fields are accepted, the behavior being similar to that of IntlCalendar::add() (i.e., the value wraps around, carrying into more significant fields each time). If the lenient mode is off, then such values will generate an error.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`lenient`

  Use `true` to activate the lenient mode; `false` otherwise.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Der Rückgabewert ist nun `true` vorher war es bool.

### Beispiele

See the example in IntlCalendar::isLenient().

# IntlCalendar::setMinimalDaysInFirstWeek

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

IntlCalendar::setMinimalDaysInFirstWeek — Set minimal number of days the first week in a year or month can have

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true

Prozeduraler Stil

function intlcal_set_minimal_days_in_first_week(IntlCalendar `$calendar`, int `$days`): true

Sets the smallest number of days the first week of a year or month must have in the new year or month. For instance, in the Gregorian calendar, if this value is 1, then the first week of the year will necessarily include January 1st, while if this value is 7, then the week with January 1st will be the first week of the year only if the day of the week for January 1st matches the day of the week returned by IntlCalendar::getFirstDayOfWeek(); otherwise it will be the previous yearʼs last week.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`days`

  The number of minimal days to set.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

ValueError if `days` is out of range (less than `1` or more than `7`).

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | A ValueError is now thrown on invalid input. Previously, `false` was returned.

# IntlCalendar::setRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setRepeatedWallTimeOption — Set behavior for handling repeating wall times at negative timezone offset transitions

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true

Prozeduraler Stil

function intlcal_set_repeated_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Sets the current strategy for dealing with wall times that are repeated whenever the clock is set back during dailight saving time end transitions. The default value is `IntlCalendar::WALLTIME_LAST` (take the post-DST instant). The other possible value is `IntlCalendar::WALLTIME_FIRST` (take the instant that occurs during DST).

This function requires ICU 4.9 or later.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`option`

  One of the constants `IntlCalendar::WALLTIME_FIRST` or `IntlCalendar::WALLTIME_LAST`.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Der Rückgabewert ist nun `true` vorher war es bool.

### Beispiele

See the example on IntlCalendar::getRepeatedWallTimeOption().

### Siehe auch

- intlCalendar::getRepeatedWallTimeOption() - Get behavior for handling repeating wall time
- intlCalendar::setSkippedWallTimeOption() - Set behavior for handling skipped wall times at positive timezone offset transitions
- intlCalendar::getSkippedWallTimeOption() - Get behavior for handling skipped wall time

# IntlCalendar::setSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setSkippedWallTimeOption — Set behavior for handling skipped wall times at positive timezone offset transitions

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true

Prozeduraler Stil

function intlcal_set_skipped_wall_time_option(IntlCalendar `$calendar`, int `$option`): true

Sets the current strategy for dealing with wall times that are skipped whenever the clock is forwarded during dailight saving time start transitions. The default value is `IntlCalendar::WALLTIME_LAST` (take it as being the same instant as the one when the wall time is one hour more). Alternative values are `IntlCalendar::WALLTIME_FIRST` (same instant as the one with a wall time of one hour less) and `IntlCalendar::WALLTIME_NEXT_VALID` (same instant as when DST begins).

This affects only the instant represented by the calendar (as reported by IntlCalendar::getTime()), the field values will not be rewritten accordingly.

The calendar must be lenient for this option to have any effect, otherwise attempting to set a non-existing time will cause an error.

This function requires ICU 4.9 or later.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`option`

  One of the constants `IntlCalendar::WALLTIME_FIRST`, `IntlCalendar::WALLTIME_LAST` or `IntlCalendar::WALLTIME_NEXT_VALID`.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | Der Rückgabewert ist nun `true` vorher war es bool.

### Beispiele

See the example on IntlCalendar::getSkippedWallTimeOption().

### Siehe auch

- intlCalendar::getSkippedWallTimeOption() - Get behavior for handling skipped wall time
- intlCalendar::setRepeatedWallTimeOption() - Set behavior for handling repeating wall times at negative timezone offset transitions
- intlCalendar::getRepeatedWallTimeOption() - Get behavior for handling repeating wall time

# IntlCalendar::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTime — Set the calendar time in milliseconds since the epoch

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::setTime(float `$timestamp`): bool

Prozeduraler Stil

function intlcal_set_time(IntlCalendar `$calendar`, float `$timestamp`): bool

Sets the instant represented by this object. The instant is represented by a float whose value should be an integer number of milliseconds since the epoch (1 Jan 1970 00:00:00.000 UTC), ignoring leap seconds. All the field values will be recalculated accordingly.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`timestamp`

  An instant represented by the number of number of milliseconds between such instant and the epoch, ignoring leap seconds.

### Rückgabewerte

Returns `true` on success and `false` on failure.

### Beispiele

Beispiel #1 IntlCalendar::setTime()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'fr_FR');

    $cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    /* In Europe/Lisbon, on 2013-10-27 at 0200, the clock goes back one hour and
       the timezone from UTC+01 to UTC+00 */

    $cal->setTime(strtotime('2013-10-27 00:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

    $cal->setTime(strtotime('2013-10-27 01:30:00 UTC') * 1000.);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    samedi 1 juin 2013 12:00:00 heure avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure normale d’Europe de l’Ouest

# IntlCalendar::setTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTimeZone — Set the timezone used by this calendar

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Prozeduraler Stil

function intlcal_set_time_zone(IntlCalendar `$calendar`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Defines a new timezone for this calendar. The time represented by the object is preserved to the detriment of the field values.

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

`timezone`

  The new timezone to be used by this calendar. It can be specified in the following ways:

  - `null`, in which case the default timezone will be used, as specified in the ini setting date.timezone or through the function date_default_timezone_set() and as returned by date_default_timezone_get().

  - An IntlTimeZone, which will be used directly.

  - A DateTimeZone. Its identifier will be extracted and an ICU timezone object will be created; the timezone will be backed by ICUʼs database, not PHPʼs.

  - A string, which should be a valid ICU timezone identifier. See IntlTimeZone::createTimeZoneIDEnumeration(). Raw offsets such as `"GMT+08:30"` are also accepted.

### Rückgabewerte

Returns `true` on success and `false` on failure.

### Beispiele

Beispiel #1 IntlCalendar::setTimeZone()

    <?php
    ini_set('date.timezone', 'Europe/Lisbon');
    ini_set('intl.default_locale', 'es_ES');

    $cal = new IntlGregorianCalendar(2013, 5 /* May */, 1, 12, 0, 0);

    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone(IntlTimeZone::getGMT());
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

    $cal->setTimeZone('GMT+03:33');
    echo IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL), "\n";
    echo "(instant {$cal->getTime()})\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    sábado, 1 de junio de 2013 12:00:00 Hora de verano de Europa occidental
    (instant 1370084400000)
    sábado, 1 de junio de 2013 11:00:00 GMT
    (instant 1370084400000)
    sábado, 1 de junio de 2013 14:33:00 GMT+03:33
    (instant 1370084400000)

# IntlCalendar::toDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::toDateTime — Convert an IntlCalendar into a DateTime object

### Beschreibung

Objektorientierter Stil

public function IntlCalendar::toDateTime(): DateTime|false

Prozeduraler Stil

function intlcal_to_date_time(IntlCalendar `$calendar`): DateTime|false

Create a DateTime object that represents the same instant (up to second precision, with a rounding error of less than 1 second) and has an analog timezone to this object (the difference being DateTimeʼs timezone will be backed by PHPʼs timezone while IntlCalendarʼs timezone is backed by ICUʼs).

### Parameter-Liste

`calendar`

  Eine IntlCalendar-Instanz.

### Rückgabewerte

A DateTime object with the same timezone as this object (though using PHPʼs database instead of ICUʼs) and the same time, except for the smaller precision (second precision instead of millisecond). Returns `false` on failure.

### Beispiele

Beispiel #1 IntlCalendar::toDateTime()

    <?php
    ini_set('date.timezone', 'UTC');
    ini_set('intl.default_locale', 'pt_PT');

    $cal = IntlCalendar::createInstance('Europe/Lisbon'); //current time

    $dt = $cal->toDateTime();
    print_r($dt);

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    DateTime Object
    (
        [date] => 2013-07-02 00:29:13
        [timezone_type] => 3
        [timezone] => Europe/Lisbon
    )

### Siehe auch

- IntlCalendar::fromDateTime() - Create an IntlCalendar from a DateTime object or string
- IntlCalendar::getTime() - Get time currently represented by the object
- IntlCalendar::createInstance() - Create a new IntlCalendar
- DateTime::__construct() - Liefert ein neues DateTime-Objekt

## Inhaltsverzeichnis

- IntlCalendar::add — Add a (signed) amount of time to a field
- IntlCalendar::after — Whether this objectʼs time is after that of the passed object
- IntlCalendar::before — Whether this objectʼs time is before that of the passed object
- IntlCalendar::clear — Clear a field or all fields
- IntlCalendar::__construct — Private constructor for disallowing instantiation
- IntlCalendar::createInstance — Create a new IntlCalendar
- IntlCalendar::equals — Compare time of two IntlCalendar objects for equality
- IntlCalendar::fieldDifference — Calculate difference between given time and this objectʼs time
- IntlCalendar::fromDateTime — Create an IntlCalendar from a DateTime object or string
- IntlCalendar::get — Get the value for a field
- IntlCalendar::getActualMaximum — The maximum value for a field, considering the objectʼs current time
- IntlCalendar::getActualMinimum — The minimum value for a field, considering the objectʼs current time
- IntlCalendar::getAvailableLocales — Get array of locales for which there is data
- IntlCalendar::getDayOfWeekType — Tell whether a day is a weekday, weekend or a day that has a transition between the two
- IntlCalendar::getErrorCode — Get last error code on the object
- IntlCalendar::getErrorMessage — Get last error message on the object
- IntlCalendar::getFirstDayOfWeek — Get the first day of the week for the calendarʼs locale
- IntlCalendar::getGreatestMinimum — Get the largest local minimum value for a field
- IntlCalendar::getKeywordValuesForLocale — Get set of locale keyword values
- IntlCalendar::getLeastMaximum — Get the smallest local maximum for a field
- IntlCalendar::getLocale — Get the locale associated with the object
- IntlCalendar::getMaximum — Get the global maximum value for a field
- IntlCalendar::getMinimalDaysInFirstWeek — Get minimal number of days the first week in a year or month can have
- IntlCalendar::getMinimum — Get the global minimum value for a field
- IntlCalendar::getNow — Get number representing the current time
- IntlCalendar::getRepeatedWallTimeOption — Get behavior for handling repeating wall time
- IntlCalendar::getSkippedWallTimeOption — Get behavior for handling skipped wall time
- IntlCalendar::getTime — Get time currently represented by the object
- IntlCalendar::getTimeZone — Get the objectʼs timezone
- IntlCalendar::getType — Get the calendar type
- IntlCalendar::getWeekendTransition — Get time of the day at which weekend begins or ends
- IntlCalendar::inDaylightTime — Whether the objectʼs time is in Daylight Savings Time
- IntlCalendar::isEquivalentTo — Whether another calendar is equal but for a different time
- IntlCalendar::isLenient — Whether date/time interpretation is in lenient mode
- IntlCalendar::isSet — Whether a field is set
- IntlCalendar::isWeekend — Whether a certain date/time is in the weekend
- IntlCalendar::roll — Add value to field without carrying into more significant fields
- IntlCalendar::set — Set a time field or several common fields at once
- IntlCalendar::setDate — Set a date fields
- IntlCalendar::setDateTime — Set a date and time fields
- IntlCalendar::setFirstDayOfWeek — Set the day on which the week is deemed to start
- IntlCalendar::setLenient — Set whether date/time interpretation is to be lenient
- IntlCalendar::setMinimalDaysInFirstWeek — Set minimal number of days the first week in a year or month can have
- IntlCalendar::setRepeatedWallTimeOption — Set behavior for handling repeating wall times at negative timezone offset transitions
- IntlCalendar::setSkippedWallTimeOption — Set behavior for handling skipped wall times at positive timezone offset transitions
- IntlCalendar::setTime — Set the calendar time in milliseconds since the epoch
- IntlCalendar::setTimeZone — Set the timezone used by this calendar
- IntlCalendar::toDateTime — Convert an IntlCalendar into a DateTime object

# The IntlGregorianCalendar class

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

## Klassenbeschreibung

class IntlGregorianCalendar extends IntlCalendar {
/* Geerbte Konstanten */
public const int IntlCalendar::FIELD_ERA;
public const int IntlCalendar::FIELD_YEAR;
public const int IntlCalendar::FIELD_MONTH;
public const int IntlCalendar::FIELD_WEEK_OF_YEAR;
public const int IntlCalendar::FIELD_WEEK_OF_MONTH;
public const int IntlCalendar::FIELD_DATE;
public const int IntlCalendar::FIELD_DAY_OF_YEAR;
public const int IntlCalendar::FIELD_DAY_OF_WEEK;
public const int IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH;
public const int IntlCalendar::FIELD_AM_PM;
public const int IntlCalendar::FIELD_HOUR;
public const int IntlCalendar::FIELD_HOUR_OF_DAY;
public const int IntlCalendar::FIELD_MINUTE;
public const int IntlCalendar::FIELD_SECOND;
public const int IntlCalendar::FIELD_MILLISECOND;
public const int IntlCalendar::FIELD_ZONE_OFFSET;
public const int IntlCalendar::FIELD_DST_OFFSET;
public const int IntlCalendar::FIELD_YEAR_WOY;
public const int IntlCalendar::FIELD_DOW_LOCAL;
public const int IntlCalendar::FIELD_EXTENDED_YEAR;
public const int IntlCalendar::FIELD_JULIAN_DAY;
public const int IntlCalendar::FIELD_MILLISECONDS_IN_DAY;
public const int IntlCalendar::FIELD_IS_LEAP_MONTH;
public const int IntlCalendar::FIELD_FIELD_COUNT;
public const int IntlCalendar::FIELD_DAY_OF_MONTH;
public const int IntlCalendar::DOW_SUNDAY;
public const int IntlCalendar::DOW_MONDAY;
public const int IntlCalendar::DOW_TUESDAY;
public const int IntlCalendar::DOW_WEDNESDAY;
public const int IntlCalendar::DOW_THURSDAY;
public const int IntlCalendar::DOW_FRIDAY;
public const int IntlCalendar::DOW_SATURDAY;
public const int IntlCalendar::DOW_TYPE_WEEKDAY;
public const int IntlCalendar::DOW_TYPE_WEEKEND;
public const int IntlCalendar::DOW_TYPE_WEEKEND_OFFSET;
public const int IntlCalendar::DOW_TYPE_WEEKEND_CEASE;
public const int IntlCalendar::WALLTIME_FIRST;
public const int IntlCalendar::WALLTIME_LAST;
public const int IntlCalendar::WALLTIME_NEXT_VALID;
/* Methoden */
public function __construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function __construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function __construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)
public static function createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static
public static function createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static
public function getGregorianChange(): float
public function isLeapYear(int `$year`): bool
public function setGregorianChange(float `$timestamp`): bool
/* Geerbte Methoden */
public function IntlCalendar::add(int `$field`, int `$value`): bool
public function IntlCalendar::after(IntlCalendar `$other`): bool
public function IntlCalendar::before(IntlCalendar `$other`): bool
public function IntlCalendar::clear(?int `$field` = `null`): true
public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::equals(IntlCalendar `$other`): bool
public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false
public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::get(int `$field`): int|false
public function IntlCalendar::getActualMaximum(int `$field`): int|false
public function IntlCalendar::getActualMinimum(int `$field`): int|false
public static function IntlCalendar::getAvailableLocales(): array
public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false
public function IntlCalendar::getErrorCode(): int|false
public function IntlCalendar::getErrorMessage(): string|false
public function IntlCalendar::getFirstDayOfWeek(): int|false
public function IntlCalendar::getGreatestMinimum(int `$field`): int|false
public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function IntlCalendar::getLeastMaximum(int `$field`): int|false
public function IntlCalendar::getLocale(int `$type`): string|false
public function IntlCalendar::getMaximum(int `$field`): int|false
public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false
public function IntlCalendar::getMinimum(int `$field`): int|false
public static function IntlCalendar::getNow(): float
public function IntlCalendar::getRepeatedWallTimeOption(): int
public function IntlCalendar::getSkippedWallTimeOption(): int
public function IntlCalendar::getTime(): float|false
public function IntlCalendar::getTimeZone(): IntlTimeZone|false
public function IntlCalendar::getType(): string
public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false
public function IntlCalendar::inDaylightTime(): bool
public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool
public function IntlCalendar::isLenient(): bool
public function IntlCalendar::isSet(int `$field`): bool
public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool
public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool
public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true
public function IntlCalendar::setLenient(bool `$lenient`): true
public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true
public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true
public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true
public function IntlCalendar::setTime(float `$timestamp`): bool
public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function IntlCalendar::toDateTime(): DateTime|false
}

# IntlGregorianCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::__construct — Create the Gregorian Calendar class

### Beschreibung

public function IntlGregorianCalendar::__construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function IntlGregorianCalendar::__construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function IntlGregorianCalendar::__construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`tz`

`locale`

`timeZoneOrYear`

`localeOrMonth`

`dayOfMonth`

`hour`

`minute`

`second`

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | This had been deprecated in favor of the methods IntlGregorianCalendar::createFromDate() and IntlGregorianCalendar::createFromDateTime().

# IntlGregorianCalendar::createFromDate

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDate — Create a new IntlGregorianCalendar instance from date

### Beschreibung

public static function IntlGregorianCalendar::createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static

Creates a new IntlGregorianCalendar instance from date.

### Parameter-Liste

`year`

  The new value for `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  The new value for `IntlGregorianCalendar::FIELD_MONTH`. The month sequence is zero-based, i.e., January is represented by 0, February by 1, …, December is 11 and Undecember (if the calendar has it) is 12.

`dayOfMonth`

  The new value for `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

### Rückgabewerte

Returns a new IntlGregorianCalendar instance.

### Beispiele

Beispiel #1 IntlGregorianCalendar::createFromDate() example

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDate(2023, 11, 23);
    var_dump($intlCalendar);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(0)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(0)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(0)
        ["is leap month"]=>
        int(0)
      }
    }

### Siehe auch

- IntlGregorianCalendar::createFromDateTime() - Create a new IntlGregorianCalendar instance from date and time

# IntlGregorianCalendar::createFromDateTime

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDateTime — Create a new IntlGregorianCalendar instance from date and time

### Beschreibung

public static function IntlGregorianCalendar::createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static

Creates a new IntlGregorianCalendar instance from date and time.

### Parameter-Liste

`year`

  The new value for `IntlGregorianCalendar::FIELD_YEAR`.

`month`

  The new value for `IntlGregorianCalendar::FIELD_MONTH`. The month sequence is zero-based, i.e., January is represented by 0, February by 1, …, December is 11 and Undecember (if the calendar has it) is 12.

`dayOfMonth`

  The new value for `IntlGregorianCalendar::FIELD_DAY_OF_MONTH`.

`hour`

  The new value for `IntlGregorianCalendar::FIELD_HOUR_OF_DAY`.

`minute`

  The new value for `IntlGregorianCalendar::FIELD_MINUTE`.

`second`

  The new value for `IntlGregorianCalendar::FIELD_SECOND`.

### Rückgabewerte

Returns a new IntlGregorianCalendar instance.

### Beispiele

Beispiel #1 IntlGregorianCalendar::createFromDateTime() example

    <?php

    $intlCalendar = IntlGregorianCalendar::createFromDateTime(2023, 11, 23, 12, 00);
    var_dump($intlCalendar);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(IntlGregorianCalendar)#1 (5) {
      ["valid"]=>
      bool(true)
      ["type"]=>
      string(9) "gregorian"
      ["timeZone"]=>
      array(4) {
        ["valid"]=>
        bool(true)
        ["id"]=>
        string(16) "Europe/Amsterdam"
        ["rawOffset"]=>
        int(3600000)
        ["currentOffset"]=>
        int(3600000)
      }
      ["locale"]=>
      string(11) "en_US_POSIX"
      ["fields"]=>
      array(23) {
        ["era"]=>
        int(1)
        ["year"]=>
        int(2023)
        ["month"]=>
        int(11)
        ["week of year"]=>
        int(51)
        ["week of month"]=>
        int(4)
        ["day of year"]=>
        int(357)
        ["day of month"]=>
        int(23)
        ["day of week"]=>
        int(7)
        ["day of week in month"]=>
        int(4)
        ["AM/PM"]=>
        int(1)
        ["hour"]=>
        int(0)
        ["hour of day"]=>
        int(12)
        ["minute"]=>
        int(0)
        ["second"]=>
        int(0)
        ["millisecond"]=>
        int(0)
        ["zone offset"]=>
        int(3600000)
        ["DST offset"]=>
        int(0)
        ["year for week of year"]=>
        int(2023)
        ["localized day of week"]=>
        int(7)
        ["extended year"]=>
        int(2023)
        ["julian day"]=>
        int(2460302)
        ["milliseconds in day"]=>
        int(43200000)
        ["is leap month"]=>
        int(0)
      }
    }

### Siehe auch

- IntlGregorianCalendar::createFromDate() - Create a new IntlGregorianCalendar instance from date

# IntlGregorianCalendar::getGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::getGregorianChange — Get the Gregorian Calendar change date

### Beschreibung

public function IntlGregorianCalendar::getGregorianChange(): float

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the change date.

# IntlGregorianCalendar::isLeapYear

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::isLeapYear — Determine if the given year is a leap year

### Beschreibung

public function IntlGregorianCalendar::isLeapYear(int `$year`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`year`

### Rückgabewerte

Returns `true` for leap years, `false` otherwise and on failure.

# IntlGregorianCalendar::setGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::setGregorianChange — Set the Gregorian Calendar the change date

### Beschreibung

public function IntlGregorianCalendar::setGregorianChange(float `$timestamp`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timestamp`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

## Inhaltsverzeichnis

- IntlGregorianCalendar::__construct — Create the Gregorian Calendar class
- IntlGregorianCalendar::createFromDate — Create a new IntlGregorianCalendar instance from date
- IntlGregorianCalendar::createFromDateTime — Create a new IntlGregorianCalendar instance from date and time
- IntlGregorianCalendar::getGregorianChange — Get the Gregorian Calendar change date
- IntlGregorianCalendar::isLeapYear — Determine if the given year is a leap year
- IntlGregorianCalendar::setGregorianChange — Set the Gregorian Calendar the change date

# The IntlTimeZone class

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Einführung

## Klassenbeschreibung

class IntlTimeZone {
/* Konstanten */
public const int DISPLAY_SHORT;
public const int DISPLAY_LONG;
public const int DISPLAY_SHORT_GENERIC;
public const int DISPLAY_LONG_GENERIC;
public const int DISPLAY_SHORT_GMT;
public const int DISPLAY_LONG_GMT;
public const int DISPLAY_SHORT_COMMONLY_USED;
public const int DISPLAY_GENERIC_LOCATION;
public const int TYPE_ANY;
public const int TYPE_CANONICAL;
public const int TYPE_CANONICAL_LOCATION;
/* Methoden */
private function __construct()
public static function countEquivalentIDs(string `$timezoneId`): int|false
public static function createDefault(): IntlTimeZone
public static function createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false
public static function createTimeZone(string `$timezoneId`): ?IntlTimeZone
public static function createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false
public static function fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone
public static function getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false
public function getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false
public function getDSTSavings(): int
public static function getEquivalentID(string `$timezoneId`, int `$offset`): string|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public static function getGMT(): IntlTimeZone
public static function getIanaID(string `$timezoneId`): string|false
public function getID(): string|false
public static function getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false
public function getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool
public function getRawOffset(): int
public static function getRegion(string `$timezoneId`): string|false
public static function getTZDataVersion(): string|false
public static function getUnknown(): IntlTimeZone
public static function getWindowsID(string `$timezoneId`): string|false
public function hasSameRules(IntlTimeZone `$other`): bool
public function toDateTimeZone(): DateTimeZone|false
public function useDaylightTime(): bool
}

## Vordefinierte Konstanten

`IntlTimeZone::DISPLAY_SHORT` int

`IntlTimeZone::DISPLAY_LONG` int

`IntlTimeZone::DISPLAY_SHORT_GENERIC` int

`IntlTimeZone::DISPLAY_LONG_GENERIC` int

`IntlTimeZone::DISPLAY_SHORT_GMT` int

`IntlTimeZone::DISPLAY_LONG_GMT` int

`IntlTimeZone::DISPLAY_SHORT_COMMONLY_USED` int

`IntlTimeZone::DISPLAY_GENERIC_LOCATION` int

`IntlTimeZone::TYPE_ANY` int

`IntlTimeZone::TYPE_CANONICAL` int

`IntlTimeZone::TYPE_CANONICAL_LOCATION` int

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | The class constants are now typed.

# IntlTimeZone::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::__construct — Private constructor to disallow direct instantiation

### Beschreibung

private function IntlTimeZone::__construct()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# IntlTimeZone::countEquivalentIDs

# intltz_count_equivalent_ids

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::countEquivalentIDs -- intltz_count_equivalent_ids — Get the number of IDs in the equivalency group that includes the given ID

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::countEquivalentIDs(string `$timezoneId`): int|false

Prozeduraler Stil:

function intltz_count_equivalent_ids(string `$timezoneId`): int|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timezoneId`

### Rückgabewerte

# IntlTimeZone::createDefault

# intltz_create_default

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createDefault -- intltz_create_default — Create a new copy of the default timezone for this host

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::createDefault(): IntlTimeZone

Prozeduraler Stil:

function intltz_create_default(): IntlTimeZone

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlTimeZone::createEnumeration

# intltz_create_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createEnumeration -- intltz_create_enumeration — Get an enumeration over time zone IDs associated with the given country or offset

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Prozeduraler Stil:

function intltz_create_enumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`countryOrRawOffset`

### Rückgabewerte

# IntlTimeZone::createTimeZone

# intltz_create_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::createTimeZone -- intltz_create_time_zone — Create a timezone object for the given ID

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::createTimeZone(string `$timezoneId`): ?IntlTimeZone

Prozeduraler Stil:

function intltz_create_time_zone(string `$timezoneId`): ?IntlTimeZone

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timezoneId`

### Rückgabewerte

# IntlTimeZone::createTimeZoneIDEnumeration

# intltz_create_time_zone_id_enumeration

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::createTimeZoneIDEnumeration -- intltz_create_time_zone_id_enumeration — Get an enumeration over system time zone IDs with the given filter conditions

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Prozeduraler Stil:

function intltz_create_time_zone_id_enumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`type`

`region`

`rawOffset`

### Rückgabewerte

Returns IntlIteratorBei einem Fehler wird `false` zurückgegeben..

# IntlTimeZone::fromDateTimeZone

# intltz_from_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::fromDateTimeZone -- intltz_from_date_time_zone — Create a timezone object from DateTimeZone

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone

Prozeduraler Stil:

function intltz_from_date_time_zone(DateTimeZone `$timezone`): ?IntlTimeZone

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timezone`

### Rückgabewerte

# IntlTimeZone::getCanonicalID

# intltz_get_canonical_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getCanonicalID -- intltz_get_canonical_id — Get the canonical system timezone ID or the normalized custom time zone ID for the given time zone ID

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Prozeduraler Stil:

function intltz_get_canonical_id(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timezoneId`

`isSystemId`

### Rückgabewerte

# IntlTimeZone::getDisplayName

# intltz_get_display_name

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDisplayName -- intltz_get_display_name — Get a name of this time zone suitable for presentation to the user

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false

Prozeduraler Stil:

function intltz_get_display_name(
IntlTimeZone `$timezone`,
bool `$dst` = `false`,
int `$style` = `IntlTimeZone::DISPLAY_LONG`,
?string `$locale` = `null`
): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`dst`

`style`

`locale`

### Rückgabewerte

# IntlTimeZone::getDSTSavings

# intltz_get_dst_savings

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getDSTSavings -- intltz_get_dst_savings — Get the amount of time to be added to local standard time to get local wall clock time

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::getDSTSavings(): int

Prozeduraler Stil:

function intltz_get_dst_savings(IntlTimeZone `$timezone`): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlTimeZone::getEquivalentID

# intltz_get_equivalent_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getEquivalentID -- intltz_get_equivalent_id — Get an ID in the equivalency group that includes the given ID

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::getEquivalentID(string `$timezoneId`, int `$offset`): string|false

Prozeduraler Stil:

function intltz_get_equivalent_id(string `$timezoneId`, int `$offset`): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timezoneId`

`offset`

### Rückgabewerte

# IntlTimeZone::getErrorCode

# intltz_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorCode -- intltz_get_error_code — Get last error code on the object

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::getErrorCode(): int|false

Prozeduraler Stil:

function intltz_get_error_code(IntlTimeZone `$timezone`): int|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlTimeZone::getErrorMessage

# intltz_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getErrorMessage -- intltz_get_error_message — Get last error message on the object

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::getErrorMessage(): string|false

Prozeduraler Stil:

function intltz_get_error_message(IntlTimeZone `$timezone`): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlTimeZone::getGMT

# intltz_get_gmt

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getGMT -- intltz_get_gmt — Create GMT (UTC) timezone

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::getGMT(): IntlTimeZone

Prozeduraler Stil:

function intltz_get_gmt(): IntlTimeZone

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlTimeZone::getIanaID

# intltz_get_iana_id

(PHP 8 >= 8.4.0)

IntlTimeZone::getIanaID -- intltz_get_iana_id — Übersetzt einen Zeitzonen-Bezeichner in sein IANA-Äquivalent

### Beschreibung

Objektorientierter Stil (Methode):

public static function IntlTimeZone::getIanaID(string `$timezoneId`): string|false

Prozeduraler Stil:

function intltz_get_iana_id(string `$timezoneId`): string|false

Übersetzt einen Zeitzonen-Bezeichner in sein IANA-Äquivalent. Zum Beispiel liefert `"GMT"` den Wert `"Etc/GMT"` und `"US/Eastern"` liefert `"America/New_York"`.

> Hinweis: Diese Funktion erfordert ICU Version >= 74.

### Parameter-Liste

`timezoneId`
  Der zu übersetzende Zeitzonen-Bezeichner.

### Rückgabewerte

Gibt den IANA-Zeitzonen-Bezeichner als String zurück oder `false` bei einem Fehler.

### Siehe auch

- intltz_get_id_for_windows_id() - Translate a Windows timezone into a system timezone
- intltz_get_windows_id() - Translate a system timezone into a Windows timezone
- intltz_create_time_zone() - Create a timezone object for the given ID

# IntlTimeZone::getID

# intltz_get_id

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getID -- intltz_get_id — Get timezone ID

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::getID(): string|false

Prozeduraler Stil:

function intltz_get_id(IntlTimeZone `$timezone`): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlTimeZone::getIDForWindowsID

# intltz_get_id_for_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getIDForWindowsID -- intltz_get_id_for_windows_id — Translate a Windows timezone into a system timezone

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false

Prozeduraler Stil:

function intltz_get_id_for_windows_id(string `$timezoneId`, ?string `$region` = `null`): string|false

Translates a Windows timezone (e.g. "Pacific Standard Time") into a system timezone (e.g. "America/Los_Angeles").

> Hinweis: This function requires ICU version ≥ 52.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timezoneId`

`region`

### Rückgabewerte

Returns the system timezoneBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `region` is now nullable.

### Siehe auch

- IntlTimeZone::getWindowsID() - Translate a system timezone into a Windows timezone

# IntlTimeZone::getOffset

# intltz_get_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getOffset -- intltz_get_offset — Get the time zone raw and GMT offset for the given moment in time

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Prozeduraler Stil:

function intltz_get_offset(
IntlTimeZone `$timezone`,
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timestamp`

`local`

`rawOffset`

`dstOffset`

### Rückgabewerte

# IntlTimeZone::getRawOffset

# intltz_get_raw_offset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getRawOffset -- intltz_get_raw_offset — Get the raw GMT offset (before taking daylight savings time into account

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::getRawOffset(): int

Prozeduraler Stil:

function intltz_get_raw_offset(IntlTimeZone `$timezone`): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlTimeZone::getRegion

# intltz_get_region

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getRegion -- intltz_get_region — Get the region code associated with the given system time zone ID

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::getRegion(string `$timezoneId`): string|false

Prozeduraler Stil:

function intltz_get_region(string `$timezoneId`): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timezoneId`

### Rückgabewerte

Return regionBei einem Fehler wird `false` zurückgegeben..

# IntlTimeZone::getTZDataVersion

# intltz_get_tz_data_version

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::getTZDataVersion -- intltz_get_tz_data_version — Get the timezone data version currently used by ICU

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::getTZDataVersion(): string|false

Prozeduraler Stil:

function intltz_get_tz_data_version(): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlTimeZone::getUnknown

# intltz_get_unknown

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getUnknown -- intltz_get_unknown — Get the "unknown" time zone

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::getUnknown(): IntlTimeZone

Prozeduraler Stil:

function intltz_get_unknown(): IntlTimeZone

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns IntlTimeZone or `null` on failure.

# IntlTimeZone::getWindowsID

# intltz_get_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getWindowsID -- intltz_get_windows_id — Translate a system timezone into a Windows timezone

### Beschreibung

Objektorientierter Stil (method):

public static function IntlTimeZone::getWindowsID(string `$timezoneId`): string|false

Prozeduraler Stil:

function intltz_get_windows_id(string `$timezoneId`): string|false

Translates a system timezone (e.g. "America/Los_Angeles") into a Windows timezone (e.g. "Pacific Standard Time").

> Hinweis: This function requires ICU version ≥ 52.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`timezoneId`

### Rückgabewerte

Returns the Windows timezoneBei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- IntlTimeZone::getIDForWindowsID() - Translate a Windows timezone into a system timezone

# IntlTimeZone::hasSameRules

# intltz_has_same_rules

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::hasSameRules -- intltz_has_same_rules — Check if this zone has the same rules and offset as another zone

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::hasSameRules(IntlTimeZone `$other`): bool

Prozeduraler Stil:

function intltz_has_same_rules(IntlTimeZone `$timezone`, IntlTimeZone `$other`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`other`

### Rückgabewerte

# IntlTimeZone::toDateTimeZone

# intltz_to_date_time_zone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::toDateTimeZone -- intltz_to_date_time_zone — Convert to DateTimeZone object

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::toDateTimeZone(): DateTimeZone|false

Prozeduraler Stil:

function intltz_to_date_time_zone(IntlTimeZone `$timezone`): DateTimeZone|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlTimeZone::useDaylightTime

# intltz_use_daylight_time

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::useDaylightTime -- intltz_use_daylight_time — Check if this time zone uses daylight savings time

### Beschreibung

Objektorientierter Stil (method):

public function IntlTimeZone::useDaylightTime(): bool

Prozeduraler Stil:

function intltz_use_daylight_time(IntlTimeZone `$timezone`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

## Inhaltsverzeichnis

- IntlTimeZone::__construct — Private constructor to disallow direct instantiation
- IntlTimeZone::countEquivalentIDs — Get the number of IDs in the equivalency group that includes the given ID
- IntlTimeZone::createDefault — Create a new copy of the default timezone for this host
- IntlTimeZone::createEnumeration — Get an enumeration over time zone IDs associated with the given country or offset
- IntlTimeZone::createTimeZone — Create a timezone object for the given ID
- IntlTimeZone::createTimeZoneIDEnumeration — Get an enumeration over system time zone IDs with the given filter conditions
- IntlTimeZone::fromDateTimeZone — Create a timezone object from DateTimeZone
- IntlTimeZone::getCanonicalID — Get the canonical system timezone ID or the normalized custom time zone ID for the given time zone ID
- IntlTimeZone::getDisplayName — Get a name of this time zone suitable for presentation to the user
- IntlTimeZone::getDSTSavings — Get the amount of time to be added to local standard time to get local wall clock time
- IntlTimeZone::getEquivalentID — Get an ID in the equivalency group that includes the given ID
- IntlTimeZone::getErrorCode — Get last error code on the object
- IntlTimeZone::getErrorMessage — Get last error message on the object
- IntlTimeZone::getGMT — Create GMT (UTC) timezone
- IntlTimeZone::getIanaID — Übersetzt einen Zeitzonen-Bezeichner in sein IANA-Äquivalent
- IntlTimeZone::getID — Get timezone ID
- IntlTimeZone::getIDForWindowsID — Translate a Windows timezone into a system timezone
- IntlTimeZone::getOffset — Get the time zone raw and GMT offset for the given moment in time
- IntlTimeZone::getRawOffset — Get the raw GMT offset (before taking daylight savings time into account
- IntlTimeZone::getRegion — Get the region code associated with the given system time zone ID
- IntlTimeZone::getTZDataVersion — Get the timezone data version currently used by ICU
- IntlTimeZone::getUnknown — Get the "unknown" time zone
- IntlTimeZone::getWindowsID — Translate a system timezone into a Windows timezone
- IntlTimeZone::hasSameRules — Check if this zone has the same rules and offset as another zone
- IntlTimeZone::toDateTimeZone — Convert to DateTimeZone object
- IntlTimeZone::useDaylightTime — Check if this time zone uses daylight savings time

# The IntlDateFormatter class

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

## Einführung

Date Formatter is a concrete class that enables locale-dependent formatting/parsing of dates using pattern strings and/or canned patterns.

This class represents the ICU date formatting functionality. It allows users to display dates in a localized format or to parse strings into PHP date values using pattern strings and/or canned patterns.

## Class synopsis

class IntlDateFormatter {
/* Konstanten */
public const int FULL;
public const int LONG;
public const int MEDIUM;
public const int SHORT;
public const int NONE;
public const int RELATIVE_FULL;
public const int RELATIVE_LONG;
public const int RELATIVE_MEDIUM;
public const int RELATIVE_SHORT;
public const int PATTERN;
public const int GREGORIAN;
public const int TRADITIONAL;
/* Methoden */
public function __construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)
public static function create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter
public function format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false
public static function formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false
public function getCalendar(): int|false
public function getDateType(): int|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getTimeType(): int|false
public function getTimeZoneId(): string|false
public function getCalendarObject(): IntlCalendar|false|null
public function getTimeZone(): IntlTimeZone|false
public function isLenient(): bool
public function localtime(string `$string`, int `&$offset` = `null`): array|false
public function parse(string `$string`, int `&$offset` = `null`): int|float|false
public function parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false
public function setCalendar(IntlCalendar|int|null `$calendar`): bool
public function setLenient(bool `$lenient`): void
public function setPattern(string `$pattern`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
}

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Added `IntlDateFormatter::PATTERN`.

## Siehe auch

- » ICU Date formatter

- » ICU Date formats

## Vordefinierte Konstanten

These constants are used to specify different formats in the constructor for DateType and TimeType.

`IntlDateFormatter::NONE` int
  Do not include this element
`IntlDateFormatter::FULL` int
  Completely specified style (Tuesday, April 12, 1952 AD or 3:30:42pm PST)
`IntlDateFormatter::LONG` int
  Long style (January 12, 1952 or 3:30:32pm)
`IntlDateFormatter::MEDIUM` int
  Medium style (Jan 12, 1952)
`IntlDateFormatter::SHORT` int
  Most abbreviated style, only essential data (12/13/52 or 3:30pm)
`IntlDateFormatter::RELATIVE_FULL` int
  The same as `IntlDateFormatter::FULL`, but yesterday, today, and tomorrow show as `yesterday`, `today`, and `tomorrow`, respectively. Available as of PHP 8.0.0, for `dateType` only.
`IntlDateFormatter::RELATIVE_LONG` int
  The same as `IntlDateFormatter::LONG`, but yesterday, today, and tomorrow show as `yesterday`, `today`, and `tomorrow`, respectively. Available as of PHP 8.0.0, for `dateType` only.
`IntlDateFormatter::RELATIVE_MEDIUM` int
  The same as `IntlDateFormatter::MEDIUM`, but yesterday, today, and tomorrow show as `yesterday`, `today`, and `tomorrow`, respectively. Available as of PHP 8.0.0, for `dateType` only.
`IntlDateFormatter::RELATIVE_SHORT` int
  The same as `IntlDateFormatter::SHORT`, but yesterday, today, and tomorrow show as `yesterday`, `today`, and `tomorrow`, respectively. Available as of PHP 8.0.0, for `dateType` only.
`IntlDateFormatter::PATTERN` int
  Uses the pattern given in `pattern`. Available as of PHP 8.4.0.

The following int constants are used to specify the calendar. These calendars are all based directly on the Gregorian calendar. Non-Gregorian calendars need to be specified in locale. Examples might include locale="hi@calendar=BUDDHIST".

`IntlDateFormatter::TRADITIONAL` int
  Non-Gregorian Calendar
`IntlDateFormatter::GREGORIAN` int
  Gregorian Calendar

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | The class constants are now typed.

# IntlDateFormatter::create

# datefmt_create

# IntlDateFormatter::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::create -- datefmt_create -- IntlDateFormatter::__construct — Create a date formatter

### Beschreibung

Objektorientierter Stil

public static function IntlDateFormatter::create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter

Objektorientierter Stil (constructor)

public function IntlDateFormatter::__construct(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
)

Prozeduraler Stil

function datefmt_create(
?string `$locale`,
int `$dateType` = `IntlDateFormatter::FULL`,
int `$timeType` = `IntlDateFormatter::FULL`,
IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`,
IntlCalendar|int|null `$calendar` = `null`,
?string `$pattern` = `null`
): ?IntlDateFormatter

Create a date formatter.

### Parameter-Liste

`locale`

  Locale to use when formatting or parsing or `null` to use the value specified in the ini setting intl.default_locale.

`dateType`

  Format of the date determined by one of the IntlDateFormatter constants. The default value is `IntlDateFormatter::FULL`.

`timeType`

  Format of the time determined by one of the IntlDateFormatter constants. The default value is `IntlDateFormatter::FULL`.

`timezone`

  Time zone ID. The default (and the one used if `null` is given) is the one returned by date_default_timezone_get() or, if applicable, that of the IntlCalendar object passed for the `calendar` parameter. This ID must be a valid identifier on ICUʼs database or an ID representing an explicit offset, such as `GMT-05:30`.

  This can also be an IntlTimeZone or a DateTimeZone object.

`calendar`

  Calendar to use for formatting or parsing. The default value is `null`, which corresponds to `IntlDateFormatter::GREGORIAN`. This can either be one of the IntlDateFormatter calendar constants or an IntlCalendar. Any IntlCalendar object passed will be clone; it will not be changed by the IntlDateFormatter. This will determine the calendar type used (gregorian, islamic, persian, etc.) and, if `null` is given for the `timezone` parameter, also the timezone used.

`pattern`

  Optional pattern to use when formatting or parsing. Possible patterns are documented at » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Rückgabewerte

The created IntlDateFormatter or `null` in case of failure.

### Fehler/Exceptions

A ValueError is thrown if `locale` is invalid.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | A ValueError is thrown if `locale` is invalid.
8.1.0 | Parameters `dateType` and `timeType` are now optional.

### Beispiele

Beispiel #1 datefmt_create() example

    <?php
    $fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles', IntlDateFormatter::GREGORIAN  );
    echo "First Formatted output is ".datefmt_format( $fmt , 0);
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "Second Formatted output is ".datefmt_format( $fmt , 0);

    $fmt = datefmt_create( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "First Formatted output with pattern is ".datefmt_format( $fmt , 0);
    $fmt = datefmt_create( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "Second Formatted output with pattern is ".datefmt_format( $fmt , 0);
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "First Formatted output is ".$fmt->format(0);
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
        'America/Los_Angeles',IntlDateFormatter::GREGORIAN  );
    echo "Second Formatted output is ".$fmt->format(0);

    $fmt = new IntlDateFormatter( "en_US" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
         'America/Los_Angeles',IntlDateFormatter::GREGORIAN  ,"MM/dd/yyyy");
    echo "First Formatted output with pattern is ".$fmt->format(0);
    $fmt = new IntlDateFormatter( "de-DE" ,IntlDateFormatter::FULL, IntlDateFormatter::FULL,
          'America/Los_Angeles',IntlDateFormatter::GREGORIAN , "MM/dd/yyyy");
    echo "Second Formatted output with pattern is ".$fmt->format(0);
    ?>

Beispiel #3 Example of invalid locale handling

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'invalid_locale',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'dunno',
            IntlDateFormatter::GREGORIAN,
        );
    } catch (\Error $e) {
        // ...
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
    Second Formatted output is Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
    First Formatted output with pattern is 12/31/1969
    Second Formatted output with pattern is 12/31/1969

### Siehe auch

- datefmt_format() - Format the date/time value as a string
- datefmt_parse() - Parse string to a timestamp value
- datefmt_get_error_code() - Get the error code from last operation
- datefmt_get_error_message() - Get the error text from the last operation

# IntlDateFormatter::format

# datefmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::format -- datefmt_format — Format the date/time value as a string

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Prozeduraler Stil

function datefmt_format(IntlDateFormatter `$formatter`, IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

Formats the time value as a string.

### Parameter-Liste

`formatter`

  The date formatter resource.

`datetime`

  Value to format. This may be a DateTimeInterface object, an IntlCalendar object, a numeric type representing a (possibly fractional) number of seconds since epoch or an array in the format output by localtime().

  If a DateTime or an IntlCalendar object is passed, its timezone is not considered. The object will be formatted using the formaterʼs configured timezone. If one wants to use the timezone of the object to be formatted, IntlDateFormatter::setTimeZone() must be called before with the objectʼs timezone. Alternatively, the static function IntlDateFormatter::formatObject() may be used instead.

### Rückgabewerte

The formatted string or, if an error occurred, `false`.

### Changelog

Version | Beschreibung
--- | ---
7.1.5 | Support for providing general DateTimeInterface objects to the `datetime` parameter was added. Formerly, only proper DateTime objects were supported.
PECL intl 3.0.0 | Support for providing IntlCalendar objects to the `datetime` parameter was added.

### Beispiele

Beispiel #1 datefmt_format() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'First Formatted output is ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Second Formatted output is ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'First Formatted output with pattern is ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo "Second Formatted output with pattern is " . datefmt_format($fmt, 0);
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'First Formatted output is ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Second Formatted output is ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'First Formatted output with pattern is ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Second Formatted output with pattern is ' . $fmt->format(0);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
    Second Formatted output is Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00
    First Formatted output with pattern is 12/31/1969
    Second Formatted output with pattern is 12/31/1969

Beispiel #3 With IntlCalendar object

    <?php
    $tz = reset(iterator_to_array(IntlTimeZone::createEnumeration('FR')));
    $formatter = IntlDateFormatter::create(
        'fr_FR',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        $tz,
        IntlDateFormatter::GREGORIAN
    );

    $cal = IntlCalendar::createInstance($tz, '@calendar=islamic-civil');
    $cal->set(IntlCalendar::FIELD_MONTH, 8); //9th month, Ramadan
    $cal->set(IntlCalendar::FIELD_DAY_OF_MONTH, 1); //1st day
    $cal->clear(IntlCalendar::FIELD_HOUR_OF_DAY);
    $cal->clear(IntlCalendar::FIELD_MINUTE);
    $cal->clear(IntlCalendar::FIELD_SECOND);
    $cal->clear(IntlCalendar::FIELD_MILLISECOND);

    echo "In this islamic year, Ramadan started/will start on:\n\t",
            $formatter->format($cal), "\n";

    //Itʼs the formatterʼs timezone that is used:
    $formatter->setTimeZone('Asia/Tokyo');
    echo "After changing timezone:\n\t",
            $formatter->format($cal), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    In this islamic year, Ramadan started/will start on:
        mardi 9 juillet 2013 19:00:00 heure avancée d’Europe centrale
    After changing timezone:
        mercredi 10 juillet 2013 02:00:00 heure normale du Japon

### Siehe auch

- datefmt_create() - Create a date formatter
- datefmt_parse() - Parse string to a timestamp value
- datefmt_get_error_code() - Get the error code from last operation
- datefmt_get_error_message() - Get the error text from the last operation
- datefmt_format_object() - Formats an object

# IntlDateFormatter::formatObject

# datefmt_format_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::formatObject -- datefmt_format_object — Formats an object

### Beschreibung

Objektorientierter Stil

public static function IntlDateFormatter::formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

Prozeduraler Stil

function datefmt_format_object(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

This function allows formatting an IntlCalendar or DateTime object without first explicitly creating a IntlDateFormatter object.

The temporary IntlDateFormatter that will be created will take the timezone from the passed in object. The timezone database bundled with PHP will not be used – ICU's will be used instead. The timezone identifier used in DateTime objects must therefore also exist in ICU's database.

### Parameter-Liste

`datetime`

  An object of type IntlCalendar or DateTime. The timezone information in the object will be used.

`format`

  How to format the date/time. This can either be an array with two elements (first the date style, then the time style, these being one of the constants `IntlDateFormatter::NONE`, `IntlDateFormatter::SHORT`, `IntlDateFormatter::MEDIUM`, `IntlDateFormatter::LONG`, `IntlDateFormatter::FULL`), an int with the value of one of these constants (in which case it will be used both for the time and the date) or a string with the format described in » the ICU documentation. If `null`, the default style will be used.

`locale`

  The locale to use, or `null` to use the default one.

### Rückgabewerte

A string with resultBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlDateFormatter::formatObject() examples

    <?php
    /* default timezone is irrelevant; timezone taken from the object */
    ini_set('date.timezone', 'UTC');
    /* default locale is taken from this ini setting */
    ini_set('intl.default_locale', 'fr_FR');

    $cal = IntlCalendar::fromDateTime("2013-06-06 17:05:06 Europe/Dublin");
    echo "default:\n\t",
            IntlDateFormatter::formatObject($cal),
            "\n";

    echo "long \$format (full):\n\t",
            IntlDateFormatter::formatObject($cal, IntlDateFormatter::FULL),
            "\n";

    echo "array \$format (none, full):\n\t",
            IntlDateFormatter::formatObject($cal, array(
                    IntlDateFormatter::NONE,
                    IntlDateFormatter::FULL)),
            "\n";

    echo "string \$format (d 'of' MMMM y):\n\t",
            IntlDateFormatter::formatObject($cal, "d 'of' MMMM y", 'en_US'),
            "\n";

    echo "with DateTime:\n\t",
            IntlDateFormatter::formatObject(
                    new DateTime("2013-09-09 09:09:09 Europe/Madrid"),
                    IntlDateFormatter::FULL,
                    'es_ES'),
            "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    default:
        6 juin 2013 17:05:06
    long $format (full):
        jeudi 6 juin 2013 17:05:06 heure d’été irlandaise
    array $format (none, full):
        17:05:06 heure d’été irlandaise
    string $format (d 'of' MMMM y):
        6 of June 2013
    with DateTime:
        lunes, 9 de septiembre de 2013 09:09:09 Hora de verano de Europa central

# IntlDateFormatter::getCalendar

# datefmt_get_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getCalendar -- datefmt_get_calendar — Get the calendar type used for the IntlDateFormatter

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getCalendar(): int|false

Prozeduraler Stil

function datefmt_get_calendar(IntlDateFormatter `$formatter`): int|false

### Parameter-Liste

`formatter`

  The formatter resource

### Rückgabewerte

The calendar type being used by the formatter. Either `IntlDateFormatter::TRADITIONAL` or `IntlDateFormatter::GREGORIAN`. Returns `false` on failure.

### Beispiele

Beispiel #1 datefmt_get_calendar() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'calendar of the formatter is : ' . datefmt_get_calendar($fmt);
    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'Now calendar of the formatter is : ' . datefmt_get_calendar($fmt);
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'calendar of the formatter is : ' . $fmt->getCalendar();
    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'Now calendar of the formatter is : ' . $fmt->getCalendar();

    ?>

Beispiel #3 Example of invalid locale handling

    <?php
    try {
        $fmt = new IntlDateFormatter(
            'invalid_locale',
            IntlDateFormatter::FULL,
            IntlDateFormatter::FULL,
            'dunno',
            IntlDateFormatter::GREGORIAN,
        );
        $cal = $fmt->getCalendar();
    } catch (\Error $e) {
        // ...
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    calendar of the formatter is : 1
    Now calendar of the formatter is : 0

### Siehe auch

- datefmt_get_calendar_object() - Get copy of formatterʼs calendar object
- datefmt_set_calendar() - Sets the calendar type used by the formatter
- datefmt_create() - Create a date formatter

# IntlDateFormatter::getDateType

# datefmt_get_datetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getDateType -- datefmt_get_datetype — Get the datetype used for the IntlDateFormatter

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getDateType(): int|false

Prozeduraler Stil

function datefmt_get_datetype(IntlDateFormatter `$formatter`): int|false

Returns date type used by the formatter.

### Parameter-Liste

`formatter`

  The formatter resource.

### Rückgabewerte

The current date type value of the formatter, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 datefmt_get_datetype() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'datetype of the formatter is : ' . datefmt_get_datetype($fmt);
    echo 'First Formatted output with datetype is ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Now datetype of the formatter is : ' . datefmt_get_datetype($fmt);
    echo 'Second Formatted output with datetype is ' . datefmt_format($fmt, 0);

    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'datetype of the formatter is : ' . $fmt->getDateType();
    echo 'First Formatted output is ' . $fmt->format(0);
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::SHORT,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Now datetype of the formatter is : ' . $fmt->getDateType();
    echo 'Second Formatted output is ' . $fmt->format(0);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    datetype of the formatter is : 0
    First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
    Now datetype of the formatter is : 2
    Second Formatted output is 12/31/69 4:00:00 PM PT

### Siehe auch

- datefmt_get_timetype() - Get the timetype used for the IntlDateFormatter
- datefmt_create() - Create a date formatter

# IntlDateFormatter::getErrorCode

# datefmt_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorCode -- datefmt_get_error_code — Get the error code from last operation

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getErrorCode(): int

Prozeduraler Stil

function datefmt_get_error_code(IntlDateFormatter `$formatter`): int

Returns the error code from the last formatting operation.

### Parameter-Liste

`formatter`

  The formatter resource.

### Rückgabewerte

The error code, one of UErrorCode values. Initial value is U_ZERO_ERROR.

### Beispiele

Beispiel #1 datefmt_get_error_code() example

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt, 0);

    printf(
        "ERROR: %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Beispiel #2 OO example

    <?php

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "ERROR: %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ERROR: U_ZERO_ERROR (0)

### Siehe auch

- datefmt_get_error_message() - Get the error text from the last operation
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure

# IntlDateFormatter::getErrorMessage

# datefmt_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getErrorMessage -- datefmt_get_error_message — Get the error text from the last operation

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getErrorMessage(): string

Prozeduraler Stil

function datefmt_get_error_message(IntlDateFormatter `$formatter`): string

Get the error text from the last operation.

### Parameter-Liste

`formatter`

  The formatter resource.

### Rückgabewerte

Description of the last error.

### Beispiele

Beispiel #1 datefmt_get_error_message() example

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = datefmt_format($fmt, 0);

    printf(
        "ERROR: %s (%d)\n",
        datefmt_get_error_message($fmt),
        datefmt_get_error_code($fmt)
    );
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $str = $fmt->format(0);

    printf(
        "ERROR: %s (%d)\n",
        $fmt->getErrorMessage(),
        $fmt->getErrorCode()
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ERROR: U_ZERO_ERROR (0)

### Siehe auch

- datefmt_get_error_code() - Get the error code from last operation
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure

# IntlDateFormatter::getLocale

# datefmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getLocale -- datefmt_get_locale — Get the locale used by formatter

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Prozeduraler Stil

function datefmt_get_locale(IntlDateFormatter `$formatter`, int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

Get locale used by the formatter.

### Parameter-Liste

`formatter`

  The formatter resource

`type`

  You can choose between valid and actual locale ( `Locale::VALID_LOCALE`, `Locale::ACTUAL_LOCALE`, respectively). The default is the actual locale.

### Rückgabewerte

The locale of this formatter, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 datefmt_get_locale() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'locale of the formatter is : ' . datefmt_get_locale($fmt);
    echo 'First Formatted output is ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'locale of the formatter is : ' . datefmt_get_locale($fmt);
    echo 'Second Formatted output is ' . datefmt_format($fmt, 0);

    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'locale of the formatter is : ' . $fmt->getLocale();
    echo 'First Formatted output is ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'locale of the formatter is : ' . $fmt->getLocale();
    echo 'Second Formatted output is ' . $fmt->format(0);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    locale of the formatter is : en
    First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
    locale of the formatter is : de
    Second Formatted output is Mittwoch, 31. Dezember 1969 16:00 Uhr GMT-08:00

### Siehe auch

- datefmt_create() - Create a date formatter

# IntlDateFormatter::getPattern

# datefmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getPattern -- datefmt_get_pattern — Get the pattern used for the IntlDateFormatter

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getPattern(): string|false

Prozeduraler Stil

function datefmt_get_pattern(IntlDateFormatter `$formatter`): string|false

Get pattern used by the formatter.

### Parameter-Liste

`formatter`

  The formatter resource.

### Rückgabewerte

The pattern string being used to format/parse, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 datefmt_get_pattern() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'pattern of the formatter is : ' . datefmt_get_pattern($fmt);
    echo 'First Formatted output with pattern is ' . datefmt_format($fmt, 0);
    datefmt_set_pattern($fmt,'yyyymmdd hh:mm:ss z');
    echo 'Now pattern of the formatter is : ' . datefmt_get_pattern($fmt);
    echo 'Second Formatted output with pattern is ' . datefmt_format($fmt, 0);

    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'pattern of the formatter is : ' . $fmt->getPattern();
    echo 'First Formatted output is ' . $fmt->format(0);
    $fmt->setPattern('yyyymmdd hh:mm:ss z');
    echo 'Now pattern of the formatter is : ' . $fmt->getPattern();
    echo 'Second Formatted output is ' . $fmt->format(0);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    pattern of the formatter is : MM/dd/yyyy
    First Formatted output is 12/31/1969
    Now pattern of the formatter is : yyyymmdd hh:mm:ss z
    Second Formatted output is 19690031 04:00:00 PST

### Siehe auch

- datefmt_set_pattern() - Set the pattern used for the IntlDateFormatter
- datefmt_create() - Create a date formatter

# IntlDateFormatter::getTimeType

# datefmt_get_timetype

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeType -- datefmt_get_timetype — Get the timetype used for the IntlDateFormatter

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getTimeType(): int|false

Prozeduraler Stil

function datefmt_get_timetype(IntlDateFormatter `$formatter`): int|false

Return time type used by the formatter.

### Parameter-Liste

`formatter`

  The formatter resource.

### Rückgabewerte

The current date type value of the formatter, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 datefmt_get_timetype() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'timetype of the formatter is : ' . datefmt_get_timetype($fmt);
    echo 'First Formatted output with timetype is ' . datefmt_format($fmt, 0);

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Now timetype of the formatter is : ' . datefmt_get_timetype($fmt);
    echo 'Second Formatted output with timetype is ' . datefmt_format($fmt, 0);

    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'timetype of the formatter is : ' . $fmt->getTimeType();
    echo 'First Formatted output is ' . $fmt->format(0);

    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::SHORT,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Now timetype of the formatter is : ' . $fmt->getTimeType();
    echo 'Second Formatted output is ' . $fmt->format(0);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    timetype of the formatter is : 0
    First Formatted output is Wednesday, December 31, 1969 4:00:00 PM PT
    Now timetype of the formatter is : 3
    Second Formatted output is Wednesday, December 31, 1969 4:00 PM

### Siehe auch

- datefmt_get_datetype() - Get the datetype used for the IntlDateFormatter
- datefmt_create() - Create a date formatter

# IntlDateFormatter::getTimeZoneId

# datefmt_get_timezone_id

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::getTimeZoneId -- datefmt_get_timezone_id — Get the timezone-id used for the IntlDateFormatter

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getTimeZoneId(): string|false

Prozeduraler Stil

function datefmt_get_timezone_id(IntlDateFormatter `$formatter`): string|false

Get the timezone-id used for the IntlDateFormatter.

### Parameter-Liste

`formatter`

  The formatter resource.

### Rückgabewerte

ID string for the time zone used by this formatter, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 datefmt_get_timezone_id() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'timezone_id of the formatter is: ' . datefmt_get_timezone_id($fmt) . "\n";
    datefmt_set_timezone($fmt, 'Europe/Madrid');
    echo 'Now timezone_id of the formatter is: ' . datefmt_get_timezone_id($fmt);

    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'timezone_id of the formatter is: ' . $fmt->getTimezoneId() . "\n";
    $fmt->setTimezone('Europe/Madrid');
    echo 'Now timezone_id of the formatter is: ' . $fmt->getTimezoneId();

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    timezone_id of the formatter is: America/Los_Angeles
    Now timezone_id of the formatter is: Europe/Madrid

### Siehe auch

- datefmt_set_timezone() - Sets formatterʼs timezone
- datefmt_create() - Create a date formatter

# IntlDateFormatter::getCalendarObject

# datefmt_get_calendar_object

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getCalendarObject -- datefmt_get_calendar_object — Get copy of formatterʼs calendar object

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getCalendarObject(): IntlCalendar|false|null

Prozeduraler Stil

function datefmt_get_calendar_object(IntlDateFormatter `$formatter`): IntlCalendar|false|null

Obtain a copy of the calendar object used internally by this formatter. This calendar will have a type (as in gregorian, japanese, buddhist, roc, persian, islamic, etc.) and a timezone that match the type and timezone used by the formatter. The date/time of the object is unspecified.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

A copy of the internal calendar object used by this formatter, or `null` if none has been set, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlDateFormatter::getCalendarObject() example

    <?php
    $formatter = IntlDateFormatter::create(
        "fr_FR@calendar=islamic",
        NULL,
        NULL,
        "GMT-01:00",
        IntlDateFormatter::TRADITIONAL
    );

    $cal = $formatter->getCalendarObject();

    var_dump(
        $cal->getType(),
        $cal->getTimeZone(),
        $cal->getLocale(Locale::VALID_LOCALE)
    );

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(7) "islamic"
    object(IntlTimeZone)#3 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(9) "GMT-01:00"
      ["rawOffset"]=>
      int(-3600000)
      ["currentOffset"]=>
      int(-3600000)
    }
    string(5) "fr_FR"

### Siehe auch

- IntlDateFormatter::getCalendar() - Get the calendar type used for the IntlDateFormatter
- IntlDateFormatter::setCalendar() - Sets the calendar type used by the formatter
- IntlCalendar

# IntlDateFormatter::getTimeZone

# datefmt_get_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getTimeZone -- datefmt_get_timezone — Get formatterʼs timezone

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::getTimeZone(): IntlTimeZone|false

Prozeduraler Stil

function datefmt_get_timezone(IntlDateFormatter `$formatter`): IntlTimeZone|false

Returns an IntlTimeZone object representing the timezone that will be used by this object to format dates and times. When formatting IntlCalendar and DateTime objects with this IntlDateFormatter, the timezone used will be the one returned by this method, not the one associated with the objects being formatted.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The associated IntlTimeZone objectBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlDateFormatter::getTimeZone() examples

    <?php

    $madrid = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Madrid');
    $lisbon = IntlDateFormatter::create(NULL, NULL, NULL, 'Europe/Lisbon');

    var_dump($madrid->getTimezone());
    echo $madrid->getTimezone()->getDisplayName(
            false, IntlTimeZone::DISPLAY_GENERIC_LOCATION, "en_US"), "\n";
    echo $lisbon->getTimeZone()->getId(), "\n";
    //The id can also be retrieved with ->getTimezoneId()
    echo $lisbon->getTimeZoneId(), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(IntlTimeZone)#4 (4) {
      ["valid"]=>
      bool(true)
      ["id"]=>
      string(13) "Europe/Madrid"
      ["rawOffset"]=>
      int(3600000)
      ["currentOffset"]=>
      int(7200000)
    }
    Spain Time
    Europe/Lisbon
    Europe/Lisbon

### Siehe auch

- IntlDateFormatter::getTimeZoneId() - Get the timezone-id used for the IntlDateFormatter
- IntlDateFormatter::setTimeZone() - Sets formatterʼs timezone
- IntlTimeZone

# IntlDateFormatter::isLenient

# datefmt_is_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::isLenient -- datefmt_is_lenient — Get the lenient used for the IntlDateFormatter

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::isLenient(): bool

Prozeduraler Stil

function datefmt_is_lenient(IntlDateFormatter `$formatter`): bool

Check if the parser is strict or lenient in interpreting inputs that do not match the pattern exactly.

### Parameter-Liste

`formatter`

  The formatter resource.

### Rückgabewerte

`true` if parser is lenient, `false` if parser is strict. By default the parser is lenient.

### Beispiele

Beispiel #1 datefmt_is_lenient() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/mm/yyyy'
    );
    echo 'lenient of the formatter is : ';
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\n Trying to do parse('35/13/1971').\nResult is : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg is : " . intl_get_error_message();
        echo "\nError_code is : " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt,false);
    echo 'Now lenient of the formatter is : ';
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\n Trying to do parse('35/13/1971').Result is : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg is : " . intl_get_error_message();
        echo "\nError_code is : " . intl_get_error_code();
    }

    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        "dd/mm/yyyy"
    );
    echo "lenient of the formatter is : ";
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    $fmt->parse('35/13/1971');
    echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0){
        echo "\nError_msg is : " . intl_get_error_message();
        echo "\nError_code is : " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo 'Now lenient of the formatter is : ';
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    $fmt->parse('35/13/1971');
    echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg is : " . intl_get_error_message();
        echo "\nError_code is : " . intl_get_error_code();
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    lenient of the formatter is : TRUE
    Trying to do parse('35/13/1971').
    Result is : -2147483
    Now lenient of the formatter is : FALSE
    Trying to do parse('35/13/1971').
    Result is :
    Error_msg is : Date parsing failed: U_PARSE_ERROR
    Error_code is : 9

### Siehe auch

- datefmt_set_lenient() - Set the leniency of the parser
- datefmt_create() - Create a date formatter

# IntlDateFormatter::localtime

# datefmt_localtime

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::localtime -- datefmt_localtime — Parse string to a field-based time value

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::localtime(string `$string`, int `&$offset` = `null`): array|false

Prozeduraler Stil

function datefmt_localtime(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): array|false

Converts string $value to a field-based time value ( an array of various fields), starting at $parse_pos and consuming as much of the input value as possible.

### Parameter-Liste

`formatter`

  The formatter resource

`string`

  string to convert to a time

`offset`

  Position at which to start the parsing in $value (zero-based). If no error occurs before $value is consumed, $parse_pos will contain -1 otherwise it will contain the position at which parsing ended . If $parse_pos > strlen($value), the parse fails immediately.

### Rückgabewerte

Localtime compatible array of integers : contains 24 hour clock value in tm_hour field, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 datefmt_localtime() example

    <?php

    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $arr = datefmt_localtime($fmt, 'Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);
    echo 'First parsed output is ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }

    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    $arr = $fmt->localtime('Wednesday, December 31, 1969 at 4:00:00 PM Pacific Standard Time', $offset);
    echo 'First parsed output is ';
    if ($arr) {
        foreach ($arr as $key => $value) {
            echo "$key : $value , ";
        }
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    First parsed output is tm_sec : 0 , tm_min : 0 , tm_hour : 16 , tm_year : 69 ,
    tm_mday : 31 , tm_wday : 3 , tm_yday : 365 , tm_mon : 11 , tm_isdst : 0 ,

### Siehe auch

- datefmt_create() - Create a date formatter
- datefmt_format() - Format the date/time value as a string
- datefmt_parse() - Parse string to a timestamp value
- datefmt_get_error_code() - Get the error code from last operation
- datefmt_get_error_message() - Get the error text from the last operation

# IntlDateFormatter::parse

# datefmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::parse -- datefmt_parse — Parse string to a timestamp value

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::parse(string `$string`, int `&$offset` = `null`): int|float|false

Prozeduraler Stil

function datefmt_parse(IntlDateFormatter `$formatter`, string `$string`, int `&$offset` = `null`): int|float|false

Converts `string` to an incremental time value, starting at `offset` and consuming as much of the input value as possible.

### Parameter-Liste

`formatter`

  The formatter resource

`string`

  string to convert to a time

`offset`

  Position at which to start the parsing in `string` (zero-based). If no error occurs before `string` is consumed, `offset` will contain -1 otherwise it will contain the position at which parsing ended (and the error occurred). This variable will contain the end position if the parse fails. If `offset` > `strlen($string)`, the parse fails immediately.

### Rückgabewerte

Timestamp of parsed value, or `false` if value cannot be parsed.

### Beispiele

Beispiel #1 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'First parsed output is ' . $fmt->parse('Wednesday, December 20, 1989 4:00:00 PM PT');
    $fmt = new IntlDateFormatter(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    ?>

Beispiel #2 datefmt_parse() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'First parsed output is ' . datefmt_parse($fmt, 'Wednesday, December 20, 1989 4:00:00 PM PT');
    $fmt = datefmt_create(
        'de-DE',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'Second parsed output is ' . datefmt_parse($fmt, 'Mittwoch, 20. Dezember 1989 16:00 Uhr GMT-08:00');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    First parsed output is 630201600
    Second parsed output is 630201600

### Siehe auch

- datefmt_create() - Create a date formatter
- datefmt_format() - Format the date/time value as a string
- datefmt_localtime() - Parse string to a field-based time value
- datefmt_get_error_code() - Get the error code from last operation
- datefmt_get_error_message() - Get the error text from the last operation

# IntlDateFormatter::parseToCalendar

(PHP 8 >= 8.4.0)

IntlDateFormatter::parseToCalendar — Parse a string into a timestamp, updating an open calendar

### Beschreibung

public function IntlDateFormatter::parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false

Converts `string` to an incremental time value, starting at `offset` and consuming as much of the input value as possible.

This method behaves like IntlDateFormatter::parse(), except that the time zone of the formatter is updated according to the time zone information contained in the parsed `string`.

### Parameter-Liste

`string`
  The string to convert to a time.
`offset`
  Position at which to start the parsing in `string` (zero-based). If no error occurs before `string` is consumed, `offset` will contain -1, otherwise it will contain the position at which parsing ended (and the error occurred). This variable will contain the end position if the parse fails. If `offset` > `strlen($string)`, the parse fails immediately.

### Rückgabewerte

Timestamp of parsed value, or `false` if value cannot be parsed.

### Beispiele

Beispiel #1 IntlDateFormatter::parseToCalendar() example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo $fmt->parseToCalendar('Wednesday, December 20, 1989 at 4:00:00 PM Pacific Standard Time');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    630201600

### Siehe auch

- IntlDateFormatter::parse() - Parse string to a timestamp value
- IntlDateFormatter::format() - Format the date/time value as a string
- IntlDateFormatter::getErrorCode() - Get the error code from last operation
- IntlDateFormatter::getErrorMessage() - Get the error text from the last operation

# IntlDateFormatter::setCalendar

# datefmt_set_calendar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setCalendar -- datefmt_set_calendar — Sets the calendar type used by the formatter

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::setCalendar(IntlCalendar|int|null `$calendar`): bool

Prozeduraler Stil

function datefmt_set_calendar(IntlDateFormatter `$formatter`, IntlCalendar|int|null `$calendar`): bool

Sets the calendar or calendar type used by the formatter.

### Parameter-Liste

`formatter`

  The formatter resource.

`calendar`

  This can either be: the calendar type to use (default is `IntlDateFormatter::GREGORIAN`, which is also used if `null` is specified) or an IntlCalendar object.

  Any IntlCalendar object passed in will be cloned; no modifications will be made to the argument object.

  The timezone of the formatter will only be kept if an IntlCalendar object is not passed, otherwise the new timezone will be that of the passed object.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
PECL intl 3.0.0 | It became possible to pass an IntlCalendar object.

### Beispiele

Beispiel #1 datefmt_set_calendar() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'calendar of the formatter is : ' . datefmt_get_calendar($fmt);
    datefmt_set_calendar($fmt, IntlDateFormatter::TRADITIONAL);
    echo 'Now calendar of the formatter is : ' . datefmt_get_calendar($fmt);
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo 'calendar of the formatter is : ' . $fmt->getCalendar();
    $fmt->setCalendar(IntlDateFormatter::TRADITIONAL);
    echo 'Now calendar of the formatter is : ' . $fmt->getCalendar();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    calendar of the formatter is : 1
    Now calendar of the formatter is : 0

Beispiel #3 Example with IntlCalendar argument

    <?php
    $time = strtotime("2013-03-03 00:00:00 UTC");
    $formatter = IntlDateFormatter::create("en_US", NULL, NULL, "Europe/Amsterdam");

    echo "before: ", $formatter->format($time), "\n";

    /* note that the calendar's locale is not used! */
    $formatter->setCalendar(IntlCalendar::createInstance(
                   "America/New_York", "pt_PT@calendar=islamic"));

    echo "after:  ", $formatter->format($time), "\n";

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    before: Sunday, March 3, 2013 at 1:00:00 AM Central European Standard Time
    after:  Saturday, Rabiʻ II 20, 1434 at 7:00:00 PM Eastern Standard Time

### Siehe auch

- datefmt_get_calendar() - Get the calendar type used for the IntlDateFormatter
- datefmt_get_calendar_object() - Get copy of formatterʼs calendar object
- datefmt_create() - Create a date formatter

# IntlDateFormatter::setLenient

# datefmt_set_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setLenient -- datefmt_set_lenient — Set the leniency of the parser

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::setLenient(bool `$lenient`): void

Prozeduraler Stil

function datefmt_set_lenient(IntlDateFormatter `$formatter`, bool `$lenient`): void

Define if the parser is strict or lenient in interpreting inputs that do not match the pattern exactly. Enabling lenient parsing allows the parser to accept otherwise flawed date or time patterns, parsing as much as possible to obtain a value. Extra space, unrecognized tokens, or invalid values ("February 30th") are not accepted.

### Parameter-Liste

`formatter`

  The formatter resource

`lenient`

  Sets whether the parser is lenient or not, default is `true` (lenient).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 datefmt_set_lenient() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'lenient of the formatter is : ';
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\n Trying to do parse('35/13/1971').\nResult is : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg is : " . intl_get_error_message();
        echo "\nError_code is : " . intl_get_error_code();
    }
    datefmt_set_lenient($fmt, false);
    echo "\nNow lenient of the formatter is : ";
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    datefmt_parse($fmt, '35/13/1971');
    echo "\nTrying to do parse('35/13/1971').\nResult is : " . datefmt_parse($fmt, '35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg is : ".intl_get_error_message();
        echo "\nError_code is : ".intl_get_error_code();
    }

    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'dd/MM/yyyy'
    );
    echo 'lenient of the formatter is : ';
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    $fmt->parse('35/13/1971');
    echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg is : " . intl_get_error_message();
        echo "\nError_code is : " . intl_get_error_code();
    }

    $fmt->setLenient(FALSE);
    echo "\nNow lenient of the formatter is : ";
    if ($fmt->isLenient()) {
        echo 'TRUE';
    } else {
        echo 'FALSE';
    }
    $fmt->parse('35/13/1971');
    echo "\n Trying to do parse('35/13/1971').\nResult is : " . $fmt->parse('35/13/1971');
    if (intl_get_error_code() != 0) {
        echo "\nError_msg is : " . intl_get_error_message();
        echo "\nError_code is : " . intl_get_error_code();
    }

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    lenient of the formatter is : TRUE
    Trying to do parse('35/13/1971').
    Result is : 66038400
    Now lenient of the formatter is : FALSE
    Trying to do parse('35/13/1971').
    Result is :
    Error_msg is : Date parsing failed: U_PARSE_ERROR
    Error_code is : 9

### Siehe auch

- datefmt_is_lenient() - Get the lenient used for the IntlDateFormatter
- datefmt_create() - Create a date formatter

# IntlDateFormatter::setPattern

# datefmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setPattern -- datefmt_set_pattern — Set the pattern used for the IntlDateFormatter

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::setPattern(string `$pattern`): bool

Prozeduraler Stil

function datefmt_set_pattern(IntlDateFormatter `$formatter`, string `$pattern`): bool

Set the pattern used for the IntlDateFormatter.

### Parameter-Liste

`formatter`

  The formatter resource.

`pattern`

  New pattern string to use. Possible patterns are documented at » https://unicode-org.github.io/icu/userguide/format_parse/datetime/.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. Bad formatstrings are usually the cause of the failure.

### Beispiele

Beispiel #1 datefmt_set_pattern() example

    <?php
    $fmt = datefmt_create(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Pattern of the formatter is : ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'First Formatted output with pattern is ', datefmt_format($fmt, 0), PHP_EOL;
    datefmt_set_pattern($fmt, 'yyyyMMdd hh:mm:ss z');
    echo 'Now pattern of the formatter is : ', datefmt_get_pattern($fmt), PHP_EOL;
    echo 'Second Formatted output with pattern is ', datefmt_format($fmt, 0), PHP_EOL;
    ?>

Beispiel #2 OO example

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN,
        'MM/dd/yyyy'
    );
    echo 'Pattern of the formatter is : ', $fmt->getPattern(), PHP_EOL;
    echo 'First Formatted output is ', $fmt->format(0), PHP_EOL;
    $fmt->setPattern('yyyyMMdd hh:mm:ss z');
    echo 'Now pattern of the formatter is : ', $fmt->getPattern(), PHP_EOL;
    echo 'Second Formatted output is ', $fmt->format(0), PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Pattern of the formatter is : MM/dd/yyyy
    First Formatted output is 12/31/1969
    Now pattern of the formatter is : yyyyMMdd hh:mm:ss z
    Second Formatted output is 19691231 04:00:00 PST

### Siehe auch

- datefmt_get_pattern() - Get the pattern used for the IntlDateFormatter
- datefmt_create() - Create a date formatter

# IntlDateFormatter::setTimeZone

# datefmt_set_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::setTimeZone -- datefmt_set_timezone — Sets formatterʼs timezone

### Beschreibung

Objektorientierter Stil

public function IntlDateFormatter::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Prozeduraler Stil

function datefmt_set_timezone(IntlDateFormatter `$formatter`, IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

Sets the timezone used for the IntlDateFormatter. object.

### Parameter-Liste

`formatter`

  The formatter resource.

`timezone`

  The timezone to use for this formatter. This can be specified in the following forms:

  - `null`, in which case the default timezone will be used, as specified in the ini setting date.timezone or through the function date_default_timezone_set() and as returned by date_default_timezone_get().

  - An IntlTimeZone, which will be used directly.

  - A DateTimeZone. Its identifier will be extracted and an ICU timezone object will be created; the timezone will be backed by ICUʼs database, not PHPʼs.

  - A string, which should be a valid ICU timezone identifier. See IntlTimeZone::createTimeZoneIDEnumeration(). Raw offsets such as `"GMT+08:30"` are also accepted.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | This function now returns `true` on success; previously it returns `null`.

### Beispiele

Beispiel #1 IntlDateFormatter::setTimeZone() examples

    <?php
    ini_set('date.timezone', 'Europe/Amsterdam');

    $formatter = IntlDateFormatter::create(NULL, NULL, NULL, "UTC");

    $formatter->setTimeZone(NULL);
    echo "NULL\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(IntlTimeZone::createTimeZone('Europe/Lisbon'));
    echo "IntlTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone(new DateTimeZone('Europe/Paris'));
    echo "DateTimeZone\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('Europe/Rome');
    echo "String\n    ", $formatter->getTimeZone()->getId(), "\n";

    $formatter->setTimeZone('GMT+00:30');
    print_r($formatter->getTimeZone());

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    NULL
        Europe/Amsterdam
    IntlTimeZone
        Europe/Lisbon
    DateTimeZone
        Europe/Paris
    String
        Europe/Rome
    IntlTimeZone Object
    (
        [valid] => 1
        [id] => GMT+00:30
        [rawOffset] => 1800000
        [currentOffset] => 1800000
    )

### Siehe auch

- IntlDateFormatter::getTimeZone() - Get formatterʼs timezone

## Inhaltsverzeichnis

- IntlDateFormatter::create — Create a date formatter
- IntlDateFormatter::format — Format the date/time value as a string
- IntlDateFormatter::formatObject — Formats an object
- IntlDateFormatter::getCalendar — Get the calendar type used for the IntlDateFormatter
- IntlDateFormatter::getDateType — Get the datetype used for the IntlDateFormatter
- IntlDateFormatter::getErrorCode — Get the error code from last operation
- IntlDateFormatter::getErrorMessage — Get the error text from the last operation
- IntlDateFormatter::getLocale — Get the locale used by formatter
- IntlDateFormatter::getPattern — Get the pattern used for the IntlDateFormatter
- IntlDateFormatter::getTimeType — Get the timetype used for the IntlDateFormatter
- IntlDateFormatter::getTimeZoneId — Get the timezone-id used for the IntlDateFormatter
- IntlDateFormatter::getCalendarObject — Get copy of formatterʼs calendar object
- IntlDateFormatter::getTimeZone — Get formatterʼs timezone
- IntlDateFormatter::isLenient — Get the lenient used for the IntlDateFormatter
- IntlDateFormatter::localtime — Parse string to a field-based time value
- IntlDateFormatter::parse — Parse string to a timestamp value
- IntlDateFormatter::parseToCalendar — Parse a string into a timestamp, updating an open calendar
- IntlDateFormatter::setCalendar — Sets the calendar type used by the formatter
- IntlDateFormatter::setLenient — Set the leniency of the parser
- IntlDateFormatter::setPattern — Set the pattern used for the IntlDateFormatter
- IntlDateFormatter::setTimeZone — Sets formatterʼs timezone

# The ResourceBundle class

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Einführung

Localized software products often require sets of data that are to be customized depending on current locale, e.g.: messages, labels, formatting patterns. ICU resource mechanism allows to define sets of resources that the application can load on locale basis, while accessing them in unified locale-independent fashion.

This class implements access to ICU resource data files. These files are binary data arrays which ICU uses to store the localized data.

ICU resource bundle can hold simple resources and complex resources. Complex resources are containers which can be either integer-indexed or string-indexed (just like PHP arrays). Simple resources can be of the following types: string, integer, binary data field or integer array.

ResourceBundle supports direct access to the data through array access pattern and iteration via foreach, as well as access via class methods. The result will be PHP value for simple resources and ResourceBundle object for complex ones. All resources are read-only.

## Klassenbeschreibung

class ResourceBundle implements IteratorAggregate, Countable {
/* Methoden */
public function __construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)
public function count(): int
public static function create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle
public function get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null
public function getErrorCode(): int
public function getErrorMessage(): string
public static function getLocales(string `$bundle`): array|false
}

## Changelog

Version | Beschreibung
--- | ---
8.0.0 | ResourceBundle implements IteratorAggregate now. Previously, Traversable was implemented instead.
7.4.0 | ResourceBundle implements Countable now.

## Siehe auch

- » ICU Resource Management
- » ICU Data

# ResourceBundle::count

# resourcebundle_count

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::count -- resourcebundle_count — Get number of elements in the bundle

### Beschreibung

Objektorientierter Stil

public function ResourceBundle::count(): int

Prozeduraler Stil

function resourcebundle_count(ResourceBundle `$bundle`): int

Get the number of elements in the bundle.

### Parameter-Liste

`bundle`

  ResourceBundle object.

### Rückgabewerte

Returns number of elements in the bundle.

### Beispiele

Beispiel #1 resourcebundle_count() example

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_count($r);
    ?>

Beispiel #2 OO example

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->count();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    42

### Siehe auch

- resourcebundle_get() - Get data from the bundle

# ResourceBundle::create

# resourcebundle_create

# ResourceBundle::__construct

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::create -- resourcebundle_create -- ResourceBundle::__construct — Create a resource bundle

### Beschreibung

Objektorientierter Stil (method)

public static function ResourceBundle::create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Prozeduraler Stil

function resourcebundle_create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

Objektorientierter Stil (constructor):

public function ResourceBundle::__construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)

Creates a resource bundle.

### Parameter-Liste

`locale`

  Locale for which the resources should be loaded (locale name, e.g. en_CA).

`bundle`

  The directory where the data is stored or the name of the .dat file.

`fallback`

  Whether locale should match exactly or fallback to parent locale is allowed.

### Rückgabewerte

Returns ResourceBundle object or `null` on error.

### Beispiele

Beispiel #1 resourcebundle_create() example

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

Beispiel #2 ResourceBundle::create() example

    <?php
    $r = ResourceBundle::create( 'es', "/usr/share/data/myapp");
    echo $r['teststring'];
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ¡Hola, mundo!

### Siehe auch

- resourcebundle_get() - Get data from the bundle

# ResourceBundle::get

# resourcebundle_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::get -- resourcebundle_get — Get data from the bundle

### Beschreibung

Objektorientierter Stil

public function ResourceBundle::get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Prozeduraler Stil

function resourcebundle_get(ResourceBundle `$bundle`, string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

Get the data from the bundle by index or string key.

### Parameter-Liste

`bundle`

  ResourceBundle object.

`index`

  Data index, must be string or integer.

`fallback`

  Whether locale should match exactly or fallback to parent locale is allowed.

### Rückgabewerte

Returns the data located at the index or `null` on error. Strings, integers and binary data strings are returned as corresponding PHP types, integer array is returned as PHP array. Complex types are returned as ResourceBundle object.

### Fehler/Exceptions

A TypeError is thrown if the offset type is invalid.

A ValueError is thrown if if `index` is a string and is empty or is a int and does not fit into a 32 bit integer type.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | A TypeError is thrown if the offset type is invalid. A ValueError is thrown if if `index` is a string and is empty or is a int and does not fit into a 32 bit integer type.

### Beispiele

Beispiel #1 resourcebundle_get() example

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo resourcebundle_get($r, 'somestring');
    ?>

Beispiel #2 OO example

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r->get('somestring');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ?Hola, mundo!

### Siehe auch

- resourcebundle_count() - Get number of elements in the bundle

# ResourceBundle::getErrorCode

# resourcebundle_get_error_code

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorCode -- resourcebundle_get_error_code — Get bundle's last error code

### Beschreibung

Objektorientierter Stil

public function ResourceBundle::getErrorCode(): int

Prozeduraler Stil

function resourcebundle_get_error_code(ResourceBundle `$bundle`): int

Get error code from the last function performed by the bundle object.

### Parameter-Liste

`bundle`

  ResourceBundle object.

### Rückgabewerte

Returns error code from last bundle object call.

### Beispiele

Beispiel #1 resourcebundle_get_error_code() example

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Bundle error");
    }
    ?>

Beispiel #2 OO example

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Bundle error");
    }
    ?>

### Siehe auch

- resourcebundle_get_error_message() - Get bundle's last error message
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure

# ResourceBundle::getErrorMessage

# resourcebundle_get_error_message

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getErrorMessage -- resourcebundle_get_error_message — Get bundle's last error message

### Beschreibung

Objektorientierter Stil

public function ResourceBundle::getErrorMessage(): string

Prozeduraler Stil

function resourcebundle_get_error_message(ResourceBundle `$bundle`): string

Get error message from the last function performed by the bundle object.

### Parameter-Liste

`bundle`

  ResourceBundle object.

### Rückgabewerte

Returns error message from last bundle object's call.

### Beispiele

Beispiel #1 resourcebundle_get_error_message() example

    <?php
    $r = resourcebundle_create( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(resourcebundle_get_error_code($r))) {
        report_error("Bundle error: ".resourcebundle_get_error_message($r));
    }
    ?>

Beispiel #2 OO example

    <?php
    $r = new ResourceBundle( 'es', "/usr/share/data/myapp");
    echo $r['somestring'];
    if(intl_is_failure(ResourceBundle::getErrorCode($r))) {
        report_error("Bundle error: ".ResourceBundle::getErrorMessage($r));
    }
    ?>

### Siehe auch

- resourcebundle_get_error_code() - Get bundle's last error code
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure

# ResourceBundle::getLocales

# resourcebundle_locales

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getLocales -- resourcebundle_locales — Get supported locales

### Beschreibung

Objektorientierter Stil

public static function ResourceBundle::getLocales(string `$bundle`): array|false

Prozeduraler Stil

function resourcebundle_locales(string `$bundle`): array|false

Get available locales from ResourceBundle name.

### Parameter-Liste

`bundle`

  Path of ResourceBundle for which to get available locales, or empty string for default locales list.

### Rückgabewerte

Returns the list of locales supported by the bundle, or `false` on failure.

### Beispiele

Beispiel #1 resourcebundle_locales() example

    <?php
    $bundle = "/user/share/data/myapp";
    echo join(PHP_EOL, resourcebundle_locales($bundle));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    es
    root

Beispiel #2 OO example

    <?php
    $bundle = "/usr/share/data/myapp";
    $r = new ResourceBundle( 'es', $bundle);
    echo join("\n", $r->getLocales($bundle));
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    es
    root

### Siehe auch

- resourcebundle_get() - Get data from the bundle

## Inhaltsverzeichnis

- ResourceBundle::count — Get number of elements in the bundle
- ResourceBundle::create — Create a resource bundle
- ResourceBundle::get — Get data from the bundle
- ResourceBundle::getErrorCode — Get bundle's last error code
- ResourceBundle::getErrorMessage — Get bundle's last error message
- ResourceBundle::getLocales — Get supported locales

# The Spoofchecker class

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Einführung

This class is provided because Unicode contains large number of characters and incorporates the varied writing systems of the world and their incorrect usage can expose programs or systems to possible security attacks using characters similarity.

Provided methods allow to check whether an individual string is likely an attempt at confusing the reader (`spoof detection`), such as "pаypаl" spelled with Cyrillic 'а' characters.

## Klassenbeschreibung

class Spoofchecker {
/* Konstanten */
public const int SINGLE_SCRIPT_CONFUSABLE;
public const int MIXED_SCRIPT_CONFUSABLE;
public const int WHOLE_SCRIPT_CONFUSABLE;
public const int ANY_CASE;
public const int SINGLE_SCRIPT;
public const int INVISIBLE;
public const int CHAR_LIMIT;
public const int ASCII;
public const int HIGHLY_RESTRICTIVE;
public const int MODERATELY_RESTRICTIVE;
public const int MINIMALLY_RESTRICTIVE;
public const int UNRESTRICTIVE;
public const int SINGLE_SCRIPT_RESTRICTIVE;
public const int MIXED_NUMBERS;
public const int HIDDEN_OVERLAY;
public const int IGNORE_SPACE;
public const int CASE_INSENSITIVE;
public const int ADD_CASE_MAPPINGS;
public const int SIMPLE_CASE_INSENSITIVE;
/* Methoden */
public function __construct()
public function areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool
public function isSuspicious(string `$string`, int `&$errorCode` = `null`): bool
public function setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void
public function setAllowedLocales(string `$locales`): void
public function setChecks(int `$checks`): void
public function setRestrictionLevel(int `$level`): void
}

## Vordefinierte Konstanten

`Spoofchecker::SINGLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::MIXED_SCRIPT_CONFUSABLE` int

`Spoofchecker::WHOLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::ANY_CASE` int

`Spoofchecker::SINGLE_SCRIPT` int

`Spoofchecker::INVISIBLE` int

`Spoofchecker::CHAR_LIMIT` int

`Spoofchecker::ASCII` int

`Spoofchecker::HIGHLY_RESTRICTIVE` int

`Spoofchecker::MODERATELY_RESTRICTIVE` int

`Spoofchecker::MINIMALLY_RESTRICTIVE` int

`Spoofchecker::UNRESTRICTIVE` int

`Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` int

`Spoofchecker::MIXED_NUMBERS` int

`Spoofchecker::HIDDEN_OVERLAY` int

`Spoofchecker::IGNORE_SPACE` int

`Spoofchecker::CASE_INSENSITIVE` int
  Enables case-insensitive matching
`Spoofchecker::ADD_CASE_MAPPINGS` int

  Adds all case mappings for each element in the set

`Spoofchecker::SIMPLE_CASE_INSENSITIVE` int
  Enables case-insensitive matching

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Added `Spoofchecker::IGNORE_SPACE`, `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS`, `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.
8.4.0 | The class constants are now typed.
7.3.0 | Class constants used by Spoofchecker::setRestrictionLevel() such as `Spoofchecker::ASCII`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE`, `Spoofchecker::UNRESTRICTIVE`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` has been added.

# Spoofchecker::areConfusable

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::areConfusable — Checks if given strings can be confused

### Beschreibung

public function Spoofchecker::areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool

Checks whether two given strings can easily be mistaken.

### Parameter-Liste

`string1`

  First string to check.

`string2`

  Second string to check.

`errorCode`

  This variable is set by-reference to Integer containing an error, if there was any.

### Rückgabewerte

Returns `true` if two given strings can be confused, `false` otherwise.

### Beispiele

Beispiel #1 Spoofchecker::areConfusable() example

    <?php
    $checker = new Spoofchecker();

    $checker->areConfusable('google.com', 'goog1e.com'); // true
    // Lower l can be confused with digit one

    $checker->areConfusable('google.com', 'g00g1e.com'); // false
    // Zero (0) cannot be easily confused with "o" letter

# Spoofchecker::__construct

(No version information available, might only be in Git)

Spoofchecker::__construct — Constructor

### Beschreibung

public function Spoofchecker::__construct()

Creates new instance of Spoofchecker.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

# Spoofchecker::isSuspicious

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::isSuspicious — Checks if a given text contains any suspicious characters

### Beschreibung

public function Spoofchecker::isSuspicious(string `$string`, int `&$errorCode` = `null`): bool

Checks if given string contains any suspicious characters like letters which are almost identical visually, but are Unicode characters from different sets.

### Parameter-Liste

`string`

  String to test.

`errorCode`

  This variable is set by-reference to Integer containing an error, if there was any.

### Rückgabewerte

Returns `true` if there are suspicious characters, `false` otherwise.

### Beispiele

Beispiel #1 Spoofchecker::isSuspicious() example

    <?php
    $checker = new Spoofchecker();

    $checker->isSuspicious('google.com'); // FALSE: only ASCII characters

    $checker->isSuspicious('Рaypal.com'); // TRUE
    // The first letter is from Cyrylic, not a regular latin "P"

# Spoofchecker::setAllowedChars

(PHP 8 >= 8.4.0)

Spoofchecker::setAllowedChars — Set the set of characters allowed when running checks

### Beschreibung

public function Spoofchecker::setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void

Restricts the characters that are considered acceptable by subsequent checks to the set described by `pattern`. Any character outside of this set causes Spoofchecker::isSuspicious() to report a result.

### Parameter-Liste

`pattern`
  A character set described as a `UnicodeSet` pattern, that is a regular-expression style character class. It must begin with `[` and end with `]`, for example `[a-z0-9]`.
`patternOptions`
  A bitmask controlling how `pattern` is interpreted. It must be `0`, or `Spoofchecker::IGNORE_SPACE` on its own or combined with exactly one of `Spoofchecker::CASE_INSENSITIVE`, `Spoofchecker::ADD_CASE_MAPPINGS`, or `Spoofchecker::SIMPLE_CASE_INSENSITIVE`.

### Rückgabewerte

No value is returned.

### Fehler/Exceptions

Throws a ValueError if `pattern` is not a valid character set pattern, or if `patternOptions` is not a valid combination of options.

### Beispiele

Beispiel #1 Spoofchecker::setAllowedChars() example

    <?php
    $checker = new Spoofchecker();
    $checker->setAllowedChars('[a-z0-9]');

    var_dump($checker->isSuspicious('hello'));
    var_dump($checker->isSuspicious('héllo'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)

### Siehe auch

- Spoofchecker::setAllowedLocales() - Locales to use when running checks
- Spoofchecker::isSuspicious() - Checks if a given text contains any suspicious characters

# Spoofchecker::setAllowedLocales

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setAllowedLocales — Locales to use when running checks

### Beschreibung

public function Spoofchecker::setAllowedLocales(string `$locales`): void

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`locales`

### Rückgabewerte

# Spoofchecker::setChecks

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setChecks — Set the checks to run

### Beschreibung

public function Spoofchecker::setChecks(int `$checks`): void

Sets the checks that will be performed by SpoofChecker::isSuspicious().

### Parameter-Liste

`checks`

  The checks that will be performed by SpoofChecker::isSuspicious(). A bitmask of `Spoofchecker::SINGLE_SCRIPT_CONFUSABLE`, `Spoofchecker::MIXED_SCRIPT_CONFUSABLE`, `Spoofchecker::WHOLE_SCRIPT_CONFUSABLE`, `Spoofchecker::ANY_CASE`, `Spoofchecker::SINGLE_SCRIPT`, `Spoofchecker::INVISIBLE`, or `Spoofchecker::CHAR_LIMIT`. Defaults to all checks as of ICU 58; prior to that version, `Spoofchecker::SINGLE_SCRIPT` was excluded.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# Spoofchecker::setRestrictionLevel

(PHP 7 >= 7.3.0, PHP 8)

Spoofchecker::setRestrictionLevel — Set the restriction level

### Beschreibung

public function Spoofchecker::setRestrictionLevel(int `$level`): void

Sets the restriction level of SpoofChecker::isSuspicious().

### Parameter-Liste

`level`

  The restriction level of SpoofChecker::isSuspicious(). One of `Spoofchecker::ASCII`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE`, or `Spoofchecker::UNRESTRICTIVE`. Defaults to `Spoofchecker::HIGHLY_RESTRICTIVE`.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

## Inhaltsverzeichnis

- Spoofchecker::areConfusable — Checks if given strings can be confused
- Spoofchecker::__construct — Constructor
- Spoofchecker::isSuspicious — Checks if a given text contains any suspicious characters
- Spoofchecker::setAllowedChars — Set the set of characters allowed when running checks
- Spoofchecker::setAllowedLocales — Locales to use when running checks
- Spoofchecker::setChecks — Set the checks to run
- Spoofchecker::setRestrictionLevel — Set the restriction level

# The Transliterator class

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

## Einführung

Transliterator provides transliteration of strings.

## Klassenbeschreibung

class Transliterator {
/* Konstanten */
public const int FORWARD;
public const int REVERSE;
/* Eigenschaften */
public readonly string $id;
/* Methoden */
final private function __construct()
public static function create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public static function createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public function createInverse(): ?Transliterator
public function getErrorCode(): int
public function getErrorMessage(): string
public static function listIDs(): array|false
public function transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false
}

## Eigenschaften

id

## Vordefinierte Konstanten

`Transliterator::FORWARD` int

`Transliterator::REVERSE` int

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | The class constants are now typed.
8.2.0 | The id property is now readonly.

# Transliterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::__construct — Private constructor to deny instantiation

### Beschreibung

final private function Transliterator::__construct()

This method should not be called. Its only purpose is to deny instantiation with the new operator.

Use the factory methods Transliterator::create() or Transliterator::createFromRules() instead.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- Transliterator::create() - Create a transliterator
- Transliterator::createFromRules() - Create transliterator from rules

# Transliterator::create

# transliterator_create

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::create -- transliterator_create — Create a transliterator

### Beschreibung

Objektorientierter Stil

public static function Transliterator::create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Prozeduraler Stil

function transliterator_create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Opens a Transliterator by ID.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`id`

  The ID. A list of all registered transliterator IDs can be retrieved by using Transliterator::listIDs().

`direction`

  The direction, defaults to Transliterator::FORWARD. May also be set to Transliterator::REVERSE.

### Rückgabewerte

Returns a Transliterator object on success, or `null` on failure.

### Siehe auch

- Transliterator::getErrorMessage() - Get last error message
- Transliterator::__construct() - Private constructor to deny instantiation

# Transliterator::createFromRules

# transliterator_create_from_rules

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createFromRules -- transliterator_create_from_rules — Create transliterator from rules

### Beschreibung

Objektorientierter Stil

public static function Transliterator::createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Prozeduraler Stil

function transliterator_create_from_rules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

Creates a Transliterator from rules.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`rules`

  The rules as defined in Transform Rules Syntax of UTS #35: Unicode LDML.

`direction`

  The direction, defaults to Transliterator::FORWARD. May also be set to Transliterator::REVERSE.

### Rückgabewerte

Returns a Transliterator object on success, or `null` on failure.

### Siehe auch

- Transliterator::getErrorMessage() - Get last error message
- Transliterator::create() - Create a transliterator

# Transliterator::createInverse

# transliterator_create_inverse

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::createInverse -- transliterator_create_inverse — Create an inverse transliterator

### Beschreibung

Objektorientierter Stil

public function Transliterator::createInverse(): ?Transliterator

Prozeduraler Stil

function transliterator_create_inverse(Transliterator `$transliterator`): ?Transliterator

Opens the inverse transliterator.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a Transliterator object on success, or `null` on failure

### Siehe auch

- Transliterator::getErrorMessage() - Get last error message
- Transliterator::create() - Create a transliterator

# Transliterator::getErrorCode

# transliterator_get_error_code

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorCode -- transliterator_get_error_code — Get last error code

### Beschreibung

Objektorientierter Stil

public function Transliterator::getErrorCode(): int

Prozeduraler Stil

function transliterator_get_error_code(Transliterator `$transliterator`): int

Gets the last error code for this transliterator.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`transliterator`

### Rückgabewerte

The error code on success, or `false` if none exists, or on failure.

### Siehe auch

- Transliterator::getErrorMessage() - Get last error message
- Transliterator::listIDs() - Get transliterator IDs

# Transliterator::getErrorMessage

# transliterator_get_error_message

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::getErrorMessage -- transliterator_get_error_message — Get last error message

### Beschreibung

Objektorientierter Stil

public function Transliterator::getErrorMessage(): string

Prozeduraler Stil

function transliterator_get_error_message(Transliterator `$transliterator`): string

Gets the last error message for this transliterator.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`transliterator`

### Rückgabewerte

The error message on success, or `false` if none exists, or on failure.

### Siehe auch

- Transliterator::getErrorCode() - Get last error code
- Transliterator::listIDs() - Get transliterator IDs

# Transliterator::listIDs

# transliterator_list_ids

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::listIDs -- transliterator_list_ids — Get transliterator IDs

### Beschreibung

Objektorientierter Stil

public static function Transliterator::listIDs(): array|false

Prozeduraler Stil

function transliterator_list_ids(): array|false

Returns an array with the registered transliterator IDs.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array of registered transliterator IDs on success, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Retrieving the registered transliterator IDs

    <?php
    print_r(Transliterator::listIDs());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => ASCII-Latin
        [1] => Accents-Any
        [2] => Amharic-Latin/BGN
        [3] => Any-Accents
        [4] => Any-Publishing
    ...
        [650] => Any-ps_Latn/BGN
        [651] => Any-tk/BGN
        [652] => Any-ch_FONIPA
        [653] => Any-cs_FONIPA
        [654] => Any-cy_FONIPA
    )

### Siehe auch

- Transliterator::getErrorMessage() - Get last error message
- Transliterator::transliterate() - Transliterate a string

# Transliterator::transliterate

# transliterator_transliterate

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::transliterate -- transliterator_transliterate — Transliterate a string

### Beschreibung

Objektorientierter Stil

public function Transliterator::transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false

Prozeduraler Stil

function transliterator_transliterate(
Transliterator|string `$transliterator`,
string `$string`,
int `$start` = 0,
int `$end` = -1
): string|false

Transforms a string or part thereof using an ICU transliterator.

### Parameter-Liste

`transliterator`

  In the procedural version, either a Transliterator or a string from which a Transliterator can be built.

`string`

  The string to be transformed.

`start`

  The start index (in UTF-16 code units) from which the string will start to be transformed, inclusive. Indexing starts at 0. The text before will be left as is.

`end`

  The end index (in UTF-16 code units) until which the string will be transformed, exclusive. Indexing starts at 0. The text after will be left as is.

### Rückgabewerte

The transformed string on success, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Converting escaped UTF-16 code units

    <?php
    $s = "\u304A\u65E9\u3046\u3054\u3056\u3044\u307E\u3059";
    echo transliterator_transliterate("Hex-Any/Java", $s), "\n";

    //now the reverse operation with a supplementary character
    $supplChar = html_entity_decode('&#x1D11E;');
    echo mb_strlen($supplChar, "UTF-8"), "\n";
    $encSupplChar = transliterator_transliterate("Any-Hex/Java", $supplChar);
    //echoes two encoded UTF-16 code units
    echo $encSupplChar, "\n";
    //and back
    echo transliterator_transliterate("Hex-Any/Java", $encSupplChar), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    お早うございます
    1
    \uD834\uDD1E
    𝄞

### Siehe auch

- Transliterator::getErrorMessage() - Get last error message
- Transliterator::__construct() - Private constructor to deny instantiation

## Inhaltsverzeichnis

- Transliterator::__construct — Private constructor to deny instantiation
- Transliterator::create — Create a transliterator
- Transliterator::createFromRules — Create transliterator from rules
- Transliterator::createInverse — Create an inverse transliterator
- Transliterator::getErrorCode — Get last error code
- Transliterator::getErrorMessage — Get last error message
- Transliterator::listIDs — Get transliterator IDs
- Transliterator::transliterate — Transliterate a string

# The IntlBreakIterator class

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

A “break iterator” is an ICU object that exposes methods for locating boundaries in text (e.g. word or sentence boundaries). The PHP IntlBreakIterator serves as the base class for all types of ICU break iterators. Where extra functionality is available, the intl extension may expose the ICU break iterator with suitable subclasses, such as IntlRuleBasedBreakIterator or IntlCodePointBreakIterator.

This class implements IteratorAggregate. Traversing an IntlBreakIterator yields non-negative integer values representing the successive locations of the text boundaries, expressed as UTF-8 code units (byte) counts, taken from the beginning of the text (which has the location `0`). The keys yielded by the iterator simply form the sequence of natural numbers `{0, 1, 2, …}`.

## Klassenbeschreibung

class IntlBreakIterator implements IteratorAggregate {
/* Konstanten */
public const int DONE;
public const int WORD_NONE;
public const int WORD_NONE_LIMIT;
public const int WORD_NUMBER;
public const int WORD_NUMBER_LIMIT;
public const int WORD_LETTER;
public const int WORD_LETTER_LIMIT;
public const int WORD_KANA;
public const int WORD_KANA_LIMIT;
public const int WORD_IDEO;
public const int WORD_IDEO_LIMIT;
public const int LINE_SOFT;
public const int LINE_SOFT_LIMIT;
public const int LINE_HARD;
public const int LINE_HARD_LIMIT;
public const int SENTENCE_TERM;
public const int SENTENCE_TERM_LIMIT;
public const int SENTENCE_SEP;
public const int SENTENCE_SEP_LIMIT;
/* Methoden */
private function __construct()
public static function createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createCodePointInstance(): IntlCodePointBreakIterator
public static function createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function current(): int
public function first(): int
public function following(int `$offset`): int
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type`): string|false
public function getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function getText(): ?string
public function isBoundary(int `$offset`): bool
public function last(): int
public function next(?int `$offset` = `null`): int
public function preceding(int `$offset`): int
public function previous(): int
public function setText(string `$text`): bool
}

## Vordefinierte Konstanten

`IntlBreakIterator::DONE` int

`IntlBreakIterator::WORD_NONE` int

`IntlBreakIterator::WORD_NONE_LIMIT` int

`IntlBreakIterator::WORD_NUMBER` int

`IntlBreakIterator::WORD_NUMBER_LIMIT` int

`IntlBreakIterator::WORD_LETTER` int

`IntlBreakIterator::WORD_LETTER_LIMIT` int

`IntlBreakIterator::WORD_KANA` int

`IntlBreakIterator::WORD_KANA_LIMIT` int

`IntlBreakIterator::WORD_IDEO` int

`IntlBreakIterator::WORD_IDEO_LIMIT` int

`IntlBreakIterator::LINE_SOFT` int

`IntlBreakIterator::LINE_SOFT_LIMIT` int

`IntlBreakIterator::LINE_HARD` int

`IntlBreakIterator::LINE_HARD_LIMIT` int

`IntlBreakIterator::SENTENCE_TERM` int

`IntlBreakIterator::SENTENCE_TERM_LIMIT` int

`IntlBreakIterator::SENTENCE_SEP` int

`IntlBreakIterator::SENTENCE_SEP_LIMIT` int

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | The class constants are now typed.
8.0.0 | IntlBreakIterator implements IteratorAggregate now. Previously, Traversable was implemented instead.

# IntlBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::__construct — Private constructor for disallowing instantiation

### Beschreibung

private function IntlBreakIterator::__construct()

IntlBreakIterator instances should be created by using one of the static factory methods.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Siehe auch

- IntlBreakIterator::createCharacterInstance() - Create break iterator for boundaries of combining character sequences
- IntlBreakIterator::createCodePointInstance() - Create break iterator for boundaries of code points
- IntlBreakIterator::createLineInstance() - Create break iterator for logically possible line breaks
- IntlBreakIterator::createSentenceInstance() - Create break iterator for sentence breaks
- IntlBreakIterator::createTitleInstance() - Create break iterator for title-casing breaks
- IntlBreakIterator::createWordInstance() - Create break iterator for word breaks

# IntlBreakIterator::createCharacterInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCharacterInstance — Create break iterator for boundaries of combining character sequences

### Beschreibung

public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`locale`

### Rückgabewerte

# IntlBreakIterator::createCodePointInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCodePointInstance — Create break iterator for boundaries of code points

### Beschreibung

public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlBreakIterator::createLineInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createLineInstance — Create break iterator for logically possible line breaks

### Beschreibung

public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`locale`

### Rückgabewerte

# IntlBreakIterator::createSentenceInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createSentenceInstance — Create break iterator for sentence breaks

### Beschreibung

public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`locale`

### Rückgabewerte

# IntlBreakIterator::createTitleInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createTitleInstance — Create break iterator for title-casing breaks

### Beschreibung

public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`locale`

### Rückgabewerte

# IntlBreakIterator::createWordInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createWordInstance — Create break iterator for word breaks

### Beschreibung

public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`locale`

### Rückgabewerte

# IntlBreakIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::current — Get index of current position

### Beschreibung

public function IntlBreakIterator::current(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlBreakIterator::first

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::first — Set position to the first character in the text

### Beschreibung

public function IntlBreakIterator::first(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlBreakIterator::following

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::following — Advance the iterator to the first boundary following specified offset

### Beschreibung

public function IntlBreakIterator::following(int `$offset`): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`offset`

### Rückgabewerte

# IntlBreakIterator::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorCode -- intl_get_error_code — Get last error code on the object

### Beschreibung

Objektorientierter Stil (method):

public function IntlBreakIterator::getErrorCode(): int

Prozeduraler Stil:

function intl_get_error_code(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlBreakIterator::getErrorMessage

# intl_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorMessage -- intl_get_error_message — Get last error message on the object

### Beschreibung

Objektorientierter Stil (method):

public function IntlBreakIterator::getErrorMessage(): string

Prozeduraler Stil:

function intl_get_error_message(): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlBreakIterator::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getLocale — Get the locale associated with the object

### Beschreibung

public function IntlBreakIterator::getLocale(int `$type`): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`type`

### Rückgabewerte

# IntlBreakIterator::getPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getPartsIterator — Create iterator for navigating fragments between boundaries

### Beschreibung

public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`type`

  Optional key type. Possible values are:

  - `IntlPartsIterator::KEY_SEQUENTIAL` - The default. Sequentially increasing integers used as key.
  - `IntlPartsIterator::KEY_LEFT` - Byte offset left of current part used as key.
  - `IntlPartsIterator::KEY_RIGHT` - Byte offset right of current part used as key.

### Rückgabewerte

# IntlBreakIterator::getText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getText — Get the text being scanned

### Beschreibung

public function IntlBreakIterator::getText(): ?string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlBreakIterator::isBoundary

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::isBoundary — Tell whether an offset is a boundaryʼs offset

### Beschreibung

public function IntlBreakIterator::isBoundary(int `$offset`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`offset`

### Rückgabewerte

# IntlBreakIterator::last

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::last — Set the iterator position to index beyond the last character

### Beschreibung

public function IntlBreakIterator::last(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlBreakIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::next — Advance the iterator the next boundary

### Beschreibung

public function IntlBreakIterator::next(?int `$offset` = `null`): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`offset`

### Rückgabewerte

# IntlBreakIterator::preceding

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::preceding — Set the iterator position to the first boundary before an offset

### Beschreibung

public function IntlBreakIterator::preceding(int `$offset`): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`offset`

### Rückgabewerte

# IntlBreakIterator::previous

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::previous — Set the iterator position to the boundary immediately before the current

### Beschreibung

public function IntlBreakIterator::previous(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlBreakIterator::setText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::setText — Set the text being scanned

### Beschreibung

public function IntlBreakIterator::setText(string `$text`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`text`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | This method now returns `false` on failure; previously it returns `null`.

## Inhaltsverzeichnis

- IntlBreakIterator::__construct — Private constructor for disallowing instantiation
- IntlBreakIterator::createCharacterInstance — Create break iterator for boundaries of combining character sequences
- IntlBreakIterator::createCodePointInstance — Create break iterator for boundaries of code points
- IntlBreakIterator::createLineInstance — Create break iterator for logically possible line breaks
- IntlBreakIterator::createSentenceInstance — Create break iterator for sentence breaks
- IntlBreakIterator::createTitleInstance — Create break iterator for title-casing breaks
- IntlBreakIterator::createWordInstance — Create break iterator for word breaks
- IntlBreakIterator::current — Get index of current position
- IntlBreakIterator::first — Set position to the first character in the text
- IntlBreakIterator::following — Advance the iterator to the first boundary following specified offset
- IntlBreakIterator::getErrorCode — Get last error code on the object
- IntlBreakIterator::getErrorMessage — Get last error message on the object
- IntlBreakIterator::getLocale — Get the locale associated with the object
- IntlBreakIterator::getPartsIterator — Create iterator for navigating fragments between boundaries
- IntlBreakIterator::getText — Get the text being scanned
- IntlBreakIterator::isBoundary — Tell whether an offset is a boundaryʼs offset
- IntlBreakIterator::last — Set the iterator position to index beyond the last character
- IntlBreakIterator::next — Advance the iterator the next boundary
- IntlBreakIterator::preceding — Set the iterator position to the first boundary before an offset
- IntlBreakIterator::previous — Set the iterator position to the boundary immediately before the current
- IntlBreakIterator::setText — Set the text being scanned

# The IntlRuleBasedBreakIterator class

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

A subclass of IntlBreakIterator that encapsulates ICU break iterators whose behavior is specified using a set of rules. This is the most common kind of break iterators.

These rules are described in the » ICU Boundary Analysis User Guide.

## Klassenbeschreibung

class IntlRuleBasedBreakIterator extends IntlBreakIterator {
/* Geerbte Konstanten */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Methoden */
public function __construct(string `$rules`, bool `$compiled` = `false`)
public function getBinaryRules(): string|false
public function getRules(): string|false
public function getRuleStatus(): int
public function getRuleStatusVec(): array|false
/* Geerbte Methoden */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlRuleBasedBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::__construct — Create iterator from ruleset

### Beschreibung

public function IntlRuleBasedBreakIterator::__construct(string `$rules`, bool `$compiled` = `false`)

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`rules`

`compiled`

### Rückgabewerte

# IntlRuleBasedBreakIterator::getBinaryRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getBinaryRules — Get the binary form of compiled rules

### Beschreibung

public function IntlRuleBasedBreakIterator::getBinaryRules(): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlRuleBasedBreakIterator::getRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRules — Get the rule set used to create this object

### Beschreibung

public function IntlRuleBasedBreakIterator::getRules(): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlRuleBasedBreakIterator::getRuleStatus

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatus — Get the largest status value from the break rules that determined the current break position

### Beschreibung

public function IntlRuleBasedBreakIterator::getRuleStatus(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlRuleBasedBreakIterator::getRuleStatusVec

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatusVec — Get the status values from the break rules that determined the current break position

### Beschreibung

public function IntlRuleBasedBreakIterator::getRuleStatusVec(): array|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

## Inhaltsverzeichnis

- IntlRuleBasedBreakIterator::__construct — Create iterator from ruleset
- IntlRuleBasedBreakIterator::getBinaryRules — Get the binary form of compiled rules
- IntlRuleBasedBreakIterator::getRules — Get the rule set used to create this object
- IntlRuleBasedBreakIterator::getRuleStatus — Get the largest status value from the break rules that determined the current break position
- IntlRuleBasedBreakIterator::getRuleStatusVec — Get the status values from the break rules that determined the current break position

# The IntlCodePointBreakIterator class

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

This break iterator identifies the boundaries between UTF-8 code points.

## Klassenbeschreibung

class IntlCodePointBreakIterator extends IntlBreakIterator {
/* Geerbte Konstanten */
public const int IntlBreakIterator::DONE;
public const int IntlBreakIterator::WORD_NONE;
public const int IntlBreakIterator::WORD_NONE_LIMIT;
public const int IntlBreakIterator::WORD_NUMBER;
public const int IntlBreakIterator::WORD_NUMBER_LIMIT;
public const int IntlBreakIterator::WORD_LETTER;
public const int IntlBreakIterator::WORD_LETTER_LIMIT;
public const int IntlBreakIterator::WORD_KANA;
public const int IntlBreakIterator::WORD_KANA_LIMIT;
public const int IntlBreakIterator::WORD_IDEO;
public const int IntlBreakIterator::WORD_IDEO_LIMIT;
public const int IntlBreakIterator::LINE_SOFT;
public const int IntlBreakIterator::LINE_SOFT_LIMIT;
public const int IntlBreakIterator::LINE_HARD;
public const int IntlBreakIterator::LINE_HARD_LIMIT;
public const int IntlBreakIterator::SENTENCE_TERM;
public const int IntlBreakIterator::SENTENCE_TERM_LIMIT;
public const int IntlBreakIterator::SENTENCE_SEP;
public const int IntlBreakIterator::SENTENCE_SEP_LIMIT;
/* Methoden */
public function getLastCodePoint(): int
/* Geerbte Methoden */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlCodePointBreakIterator::getLastCodePoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlCodePointBreakIterator::getLastCodePoint — Get last code point passed over after advancing or receding the iterator

### Beschreibung

public function IntlCodePointBreakIterator::getLastCodePoint(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

## Inhaltsverzeichnis

- IntlCodePointBreakIterator::getLastCodePoint — Get last code point passed over after advancing or receding the iterator

# The IntlDatePatternGenerator class

(PHP 8 >= 8.1.0)

## Einführung

Generates localized date and/or time format pattern strings suitable for use in IntlDateFormatter.

## Klassenbeschreibung

class IntlDatePatternGenerator {
/* Methoden */
public function __construct(?string `$locale` = `null`)
public static function create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function getBestPattern(string `$skeleton`): string|false
}

# IntlDatePatternGenerator::create

# IntlDatePatternGenerator::__construct

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::create -- IntlDatePatternGenerator::__construct — Creates a new IntlDatePatternGenerator instance

### Beschreibung

public static function IntlDatePatternGenerator::create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function IntlDatePatternGenerator::__construct(?string `$locale` = `null`)

Creates a new IntlDatePatternGenerator instance.

### Parameter-Liste

`locale`

  The locale. If `null` is passed, uses the ini setting intl.default_locale.

### Rückgabewerte

Returns an IntlDatePatternGenerator instance on success, or `null` on failure.

# IntlDatePatternGenerator::getBestPattern

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::getBestPattern — Bestimmt das am besten geeignete Datums-/Zeitformat

### Beschreibung

public function IntlDatePatternGenerator::getBestPattern(string `$skeleton`): string|false

Bestimmt, welches Datums-/Zeitformat für ein bestimmtes Gebietsschema am besten geeignet ist.

### Parameter-Liste

`skeleton`

  Das Grundgerüst.

### Rückgabewerte

Gibt im Erfolgsfall ein von IntlDateFormatter akzeptiertes ICU-Datums-/Zeitmuster zurück, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 IntlDatePatternGenerator::getBestPattern()-Beispiel

    <?php

    $skeleton = 'YYYYMMdd';
    $today = \DateTimeImmutable::createFromFormat('Y-m-d', '2021-04-24');

    $patternGenerator = new \IntlDatePatternGenerator('de_DE');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'de: ', \IntlDateFormatter::formatObject($today, $pattern, 'de_DE'), "\n";

    $patternGenerator = new \IntlDatePatternGenerator('en_US');
    $pattern = $patternGenerator->getBestPattern($skeleton);
    echo 'en: ', \IntlDateFormatter::formatObject($today, $pattern, 'en_US');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    de: 24.04.2021
    en: 04/24/2021

## Inhaltsverzeichnis

- IntlDatePatternGenerator::create — Creates a new IntlDatePatternGenerator instance
- IntlDatePatternGenerator::getBestPattern — Bestimmt das am besten geeignete Datums-/Zeitformat

# The IntlPartsIterator class

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

Objects of this class can be obtained from IntlBreakIterator objects. While the break iterators provide a sequence of boundary positions when iterated, IntlPartsIterator objects provide, as a convenience, the text fragments comprehended between two successive boundaries.

The keys may represent the offset of the left boundary, right boundary, or they may just the sequence of non-negative integers. See IntlBreakIterator::getPartsIterator().

## Klassenbeschreibung

class IntlPartsIterator extends IntlIterator {
/* Konstanten */
public const int KEY_SEQUENTIAL;
public const int KEY_LEFT;
public const int KEY_RIGHT;
/* Methoden */
public function getBreakIterator(): IntlBreakIterator
/* Geerbte Methoden */
public function IntlIterator::current(): mixed
public function IntlIterator::key(): mixed
public function IntlIterator::next(): void
public function IntlIterator::rewind(): void
public function IntlIterator::valid(): bool
}

## Vordefinierte Konstanten

`IntlPartsIterator::KEY_SEQUENTIAL` int

`IntlPartsIterator::KEY_LEFT` int

`IntlPartsIterator::KEY_RIGHT` int

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | The class constants are now typed.

# IntlPartsIterator::getBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlPartsIterator::getBreakIterator — Get IntlBreakIterator backing this parts iterator

### Beschreibung

public function IntlPartsIterator::getBreakIterator(): IntlBreakIterator

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

## Inhaltsverzeichnis

- IntlPartsIterator::getBreakIterator — Get IntlBreakIterator backing this parts iterator

# Die Klasse UConverter

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

## Einführung

## Klassenbeschreibung

class UConverter {
/* Konstanten */
public const int REASON_UNASSIGNED;
public const int REASON_ILLEGAL;
public const int REASON_IRREGULAR;
public const int REASON_RESET;
public const int REASON_CLOSE;
public const int REASON_CLONE;
public const int UNSUPPORTED_CONVERTER;
public const int SBCS;
public const int DBCS;
public const int MBCS;
public const int LATIN_1;
public const int UTF8;
public const int UTF16_BigEndian;
public const int UTF16_LittleEndian;
public const int UTF32_BigEndian;
public const int UTF32_LittleEndian;
public const int EBCDIC_STATEFUL;
public const int ISO_2022;
public const int LMBCS_1;
public const int LMBCS_2;
public const int LMBCS_3;
public const int LMBCS_4;
public const int LMBCS_5;
public const int LMBCS_6;
public const int LMBCS_8;
public const int LMBCS_11;
public const int LMBCS_16;
public const int LMBCS_17;
public const int LMBCS_18;
public const int LMBCS_19;
public const int LMBCS_LAST;
public const int HZ;
public const int SCSU;
public const int ISCII;
public const int US_ASCII;
public const int UTF7;
public const int BOCU1;
public const int UTF16;
public const int UTF32;
public const int CESU8;
public const int IMAP_MAILBOX;
/* Methoden */
public function __construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)
public function convert(string `$str`, bool `$reverse` = `false`): string|false
public function fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null
public static function getAliases(string `$name`): array|false|null
public static function getAvailable(): array
public function getDestinationEncoding(): string|false|null
public function getDestinationType(): int|false|null
public function getErrorCode(): int
public function getErrorMessage(): ?string
public function getSourceEncoding(): string|false|null
public function getSourceType(): int|false|null
public static function getStandards(): ?array
public function getSubstChars(): string|false|null
public static function reasonText(int `$reason`): string
public function setDestinationEncoding(string `$encoding`): bool
public function setSourceEncoding(string `$encoding`): bool
public function setSubstChars(string `$chars`): bool
public function toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null
public static function transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false
}

## Vordefinierte Konstanten

`UConverter::REASON_UNASSIGNED` int

`UConverter::REASON_ILLEGAL` int

`UConverter::REASON_IRREGULAR` int

`UConverter::REASON_RESET` int

`UConverter::REASON_CLOSE` int

`UConverter::REASON_CLONE` int

`UConverter::UNSUPPORTED_CONVERTER` int

`UConverter::SBCS` int

`UConverter::DBCS` int

`UConverter::MBCS` int

`UConverter::LATIN_1` int

`UConverter::UTF8` int

`UConverter::UTF16_BigEndian` int

`UConverter::UTF16_LittleEndian` int

`UConverter::UTF32_BigEndian` int

`UConverter::UTF32_LittleEndian` int

`UConverter::EBCDIC_STATEFUL` int

`UConverter::ISO_2022` int

`UConverter::LMBCS_1` int

`UConverter::LMBCS_2` int

`UConverter::LMBCS_3` int

`UConverter::LMBCS_4` int

`UConverter::LMBCS_5` int

`UConverter::LMBCS_6` int

`UConverter::LMBCS_8` int

`UConverter::LMBCS_11` int

`UConverter::LMBCS_16` int

`UConverter::LMBCS_17` int

`UConverter::LMBCS_18` int

`UConverter::LMBCS_19` int

`UConverter::LMBCS_LAST` int

`UConverter::HZ` int

`UConverter::SCSU` int

`UConverter::ISCII` int

`UConverter::US_ASCII` int

`UConverter::UTF7` int

`UConverter::BOCU1` int

`UConverter::UTF16` int

`UConverter::UTF32` int

`UConverter::CESU8` int

`UConverter::IMAP_MAILBOX` int

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Klassenkonstanten sind nun typisiert.

# UConverter::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::__construct — Create UConverter object

### Beschreibung

public function UConverter::__construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`destination_encoding`

`source_encoding`

### Rückgabewerte

# UConverter::convert

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::convert — Convert string from one charset to another

### Beschreibung

public function UConverter::convert(string `$str`, bool `$reverse` = `false`): string|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`str`

`reverse`

### Rückgabewerte

# UConverter::fromUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::fromUCallback — Default "from" callback function

### Beschreibung

public function UConverter::fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`reason`

`source`

`codePoint`

`error`

### Rückgabewerte

# UConverter::getAliases

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAliases — Get the aliases of the given name

### Beschreibung

public static function UConverter::getAliases(string `$name`): array|false|null

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`name`

### Rückgabewerte

# UConverter::getAvailable

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAvailable — Get the available canonical converter names

### Beschreibung

public static function UConverter::getAvailable(): array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# UConverter::getDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationEncoding — Get the destination encoding

### Beschreibung

public function UConverter::getDestinationEncoding(): string|false|null

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# UConverter::getDestinationType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationType — Get the destination converter type

### Beschreibung

public function UConverter::getDestinationType(): int|false|null

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# UConverter::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorCode -- intl_get_error_code — Get last error code on the object

### Beschreibung

public function UConverter::getErrorCode(): int

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# UConverter::getErrorMessage

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorMessage — Get last error message on the object

### Beschreibung

public function UConverter::getErrorMessage(): ?string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# UConverter::getSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceEncoding — Get the source encoding

### Beschreibung

public function UConverter::getSourceEncoding(): string|false|null

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# UConverter::getSourceType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceType — Get the source converter type

### Beschreibung

public function UConverter::getSourceType(): int|false|null

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# UConverter::getStandards

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getStandards — Get standards associated to converter names

### Beschreibung

public static function UConverter::getStandards(): ?array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# UConverter::getSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSubstChars — Get substitution chars

### Beschreibung

public function UConverter::getSubstChars(): string|false|null

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# UConverter::reasonText

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::reasonText — Get string representation of the callback reason

### Beschreibung

public static function UConverter::reasonText(int `$reason`): string

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`reason`

### Rückgabewerte

# UConverter::setDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setDestinationEncoding — Set the destination encoding

### Beschreibung

public function UConverter::setDestinationEncoding(string `$encoding`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`encoding`

### Rückgabewerte

# UConverter::setSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSourceEncoding — Set the source encoding

### Beschreibung

public function UConverter::setSourceEncoding(string `$encoding`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`encoding`

### Rückgabewerte

# UConverter::setSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSubstChars — Set the substitution chars

### Beschreibung

public function UConverter::setSubstChars(string `$chars`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`chars`

### Rückgabewerte

# UConverter::toUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::toUCallback — Default "to" callback function

### Beschreibung

public function UConverter::toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`reason`

`source`

`codeUnits`

`error`

### Rückgabewerte

# UConverter::transcode

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::transcode — Convert a string from one character encoding to another

### Beschreibung

public static function UConverter::transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false

Converts `str` from `fromEncoding` to `toEncoding`.

### Parameter-Liste

`str`

  The String to be converted.

`toEncoding`

  The desired encoding of the result.

`fromEncoding`

  The current encoding used to interpret `str`.

`options`

  An optional Array, which may contain the following keys:

  - `'to_subst'` - the substitution character to use in place of any character of `str` which cannot be encoded in `toEncoding`. If specified, it must represent a single character in the target encoding.

### Rückgabewerte

Returns the converted stringBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Converting from UTF-8 to UTF-16 and back

    <?php
    $utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoë' in UTF-8
    $utf16_string = UConverter::transcode($utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";

    $new_utf8_string = UConverter::transcode($utf16_string, 'UTF-8', 'UTF-16BE');
    echo bin2hex($new_utf8_string), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    005a006f00eb
    5a6fc3ab

Beispiel #2 Invalid characters in input

If the input string contains a sequence of bytes which is not valid in the encoding specified by `fromEncoding`, they are replaced by Unicode code point U+FFFD (Replacement Character) before converting to `toEncoding`.

    <?php
    $invalid_utf8_string = "\xC3"; // incomplete multi-byte UTF-8 sequence
    $utf16_string = UConverter::transcode($invalid_utf8_string, 'UTF-16BE', 'UTF-8');
    echo bin2hex($utf16_string), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    fffd

Beispiel #3 Characters which cannot be encoded

If the input string contains characters which cannot be represented in `toEncoding`, they are replaced with a single character. The default character to use depends on the encoding, and can be controlled using the `'to_subst'` option.

    <?php
    $utf8_string = "\xE2\x82\xAC"; // € (Euro Sign) does not exist in ISO 8859-1

    // Default replacement in ISO 8859-1 is "\x1A" (Substitute)
    $iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF-8');
    echo bin2hex($iso8859_1_string), "\n";

    // Specify a replacement of '?' ("\x3F") instead
    $iso8859_1_string = UConverter::transcode(
        $utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";

    // Since ISO 8859-1 cannot map U+FFFD, invalid input is also replaced by to_subst
    $invalid_utf8_string = "\xC3"; // incomplete multi-byte UTF-8 sequence
    $iso8859_1_string = UConverter::transcode(
        $invalid_utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
    );
    echo bin2hex($iso8859_1_string), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1a
    3f
    3f

### Siehe auch

- mb_convert_encoding() - Convert a string from one character encoding to another
- iconv() - Konvertiert eine Zeichenkette von einem Zeichensatz in einen anderen

## Inhaltsverzeichnis

- UConverter::__construct — Create UConverter object
- UConverter::convert — Convert string from one charset to another
- UConverter::fromUCallback — Default "from" callback function
- UConverter::getAliases — Get the aliases of the given name
- UConverter::getAvailable — Get the available canonical converter names
- UConverter::getDestinationEncoding — Get the destination encoding
- UConverter::getDestinationType — Get the destination converter type
- UConverter::getErrorCode — Get last error code on the object
- UConverter::getErrorMessage — Get last error message on the object
- UConverter::getSourceEncoding — Get the source encoding
- UConverter::getSourceType — Get the source converter type
- UConverter::getStandards — Get standards associated to converter names
- UConverter::getSubstChars — Get substitution chars
- UConverter::reasonText — Get string representation of the callback reason
- UConverter::setDestinationEncoding — Set the destination encoding
- UConverter::setSourceEncoding — Set the source encoding
- UConverter::setSubstChars — Set the substitution chars
- UConverter::toUCallback — Default "to" callback function
- UConverter::transcode — Convert a string from one character encoding to another

# Grapheme Funktionen

# grapheme_extract

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_extract — Function to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8

### Beschreibung

Prozeduraler Stil

function grapheme_extract(
string `$haystack`,
int `$size`,
int `$type` = `GRAPHEME_EXTR_COUNT`,
int `$offset` = 0,
int `&$next` = `null`
): string|false

Function to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8.

### Parameter-Liste

`haystack`

  String to search.

`size`

  Maximum number items - based on the `type` - to return.

`type`

  Defines the type of units referred to by the `size` parameter:

  - GRAPHEME_EXTR_COUNT (default) -`size` is the number of default grapheme clusters to extract.
  - GRAPHEME_EXTR_MAXBYTES -`size` is the maximum number of bytes returned.
  - GRAPHEME_EXTR_MAXCHARS - `size` is the maximum number of UTF-8 characters returned.
`offset`

  Starting position in `haystack` in bytes - if given, it must be zero or a positive value that is less than or equal to the length of `haystack` in bytes, or a negative value that counts from the end of `haystack`. If `offset` does not point to the first byte of a UTF-8 character, the start position is moved to the next character boundary.

`next`

  Reference to a value that will be set to the next starting position. When the call returns, this may point to the first byte position past the end of the string.

### Rückgabewerte

A string starting at offset `offset` and ending on a default grapheme cluster boundary that conforms to the `size` and `type` specified, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
7.1.0 | Support for negative `offset`s has been added.

### Beispiele

Beispiel #1 grapheme_extract() example

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print urlencode(grapheme_extract( $char_a_ring_nfd . $char_o_diaeresis_nfd, 1, GRAPHEME_EXTR_COUNT, 2));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    o%CC%88

### Siehe auch

- grapheme_substr() - Return part of a string
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_str_split

(PHP 8 >= 8.4.0)

grapheme_str_split — Split a string into an array

### Beschreibung

function grapheme_str_split(string `$string`, int `$length` = 1): array|false

This function will return an array of strings, it is a version of str_split() with support for grapheme cluster byte characters. If the `length` parameter is specified, the string is broken down into chunks of the specified length in grapheme clusters (not bytes).

### Parameter-Liste

`string`

  The string to split into grapheme clusters or chunks. `string` must be valid UTF-8.

`length`

  Each element of the returned array will be composed of `length` grapheme clusters.

### Rückgabewerte

grapheme_str_split() returns an array of strings, Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

If `length` is less than `1`, a ValueError will be thrown.

### Siehe auch

- str_split() - Konvertiert einen String in ein Array
- mb_str_split() - Given a multibyte string, return an array of its characters
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_stripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stripos — Find position (in grapheme units) of first occurrence of a case-insensitive string

### Beschreibung

Prozeduraler Stil

function grapheme_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Find position (in grapheme units) of first occurrence of a case-insensitive string

### Parameter-Liste

`haystack`

  The string to look in. Must be valid UTF-8.

`needle`

  The string to look for. Must be valid UTF-8.

`offset`

  The optional `offset` parameter allows you to specify where in `haystack` to start searching as an offset in grapheme units (not bytes or characters). If the offset is negative, it is treated relative to the end of the string. The position returned is still relative to the beginning of `haystack` regardless of the value of `offset`.

`locale`
  Locale to use.

### Rückgabewerte

Returns the position as an integer. If `needle` is not found, grapheme_stripos() will return `false`.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The optional parameter `locale` has been added.
7.1.0 | Support for negative `offset`s has been added.

### Beispiele

Beispiel #1 grapheme_stripos() example

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) normalization form "D"

    print grapheme_stripos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2

### Siehe auch

- grapheme_stristr() - Returns part of haystack string from the first occurrence of case-insensitive needle to the end of haystack
- grapheme_strpos() - Find position (in grapheme units) of first occurrence of a string
- grapheme_strripos() - Find position (in grapheme units) of last occurrence of a case-insensitive string
- grapheme_strrpos() - Find position (in grapheme units) of last occurrence of a string
- grapheme_strstr() - Returns part of haystack string from the first occurrence of needle to the end of haystack
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_stristr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stristr — Returns part of haystack string from the first occurrence of case-insensitive needle to the end of haystack

### Beschreibung

Prozeduraler Stil

function grapheme_stristr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

Returns part of `haystack` string starting from and including the first occurrence of case-insensitive needle to the end of `haystack`.

### Parameter-Liste

`haystack`

  The input string. Must be valid UTF-8.

`needle`

  The string to look for. Must be valid UTF-8.

`beforeNeedle`

  If `true`, grapheme_stristr() returns the part of the `haystack` before the first occurrence of the needle (excluding `needle`).

`locale`
  Locale to use.

### Rückgabewerte

Returns the portion of `haystack`, or `false` if `needle` is not found.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The optional parameter `locale` has been added.

### Beispiele

Beispiel #1 grapheme_stristr() example

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) normalization form "D"

    print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_O_diaeresis_nfd));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    o%CC%88a%CC%8A

### Siehe auch

- grapheme_stripos() - Find position (in grapheme units) of first occurrence of a case-insensitive string
- grapheme_strpos() - Find position (in grapheme units) of first occurrence of a string
- grapheme_strripos() - Find position (in grapheme units) of last occurrence of a case-insensitive string
- grapheme_strrpos() - Find position (in grapheme units) of last occurrence of a string
- grapheme_strstr() - Returns part of haystack string from the first occurrence of needle to the end of haystack
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strlen

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strlen — Get string length in grapheme units

### Beschreibung

Prozeduraler Stil

function grapheme_strlen(string `$string`): int|false|null

Get string length in grapheme units (not bytes or characters)

### Parameter-Liste

`string`

  The string being measured for length. It must be a valid UTF-8 string.

### Rückgabewerte

The length of the string on success, `null` or `false` on failure.

### Beispiele

Beispiel #1 grapheme_strlen() example

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    6

### Siehe auch

- » Unicode Text Segmentation: Grapheme Cluster Boundaries
- iconv_strlen() - Returns the character count of string
- mb_strlen() - Get string length
- strlen() - Ermitteln der String-Länge

# grapheme_strpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strpos — Find position (in grapheme units) of first occurrence of a string

### Beschreibung

Prozeduraler Stil

function grapheme_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Find position (in grapheme units) of first occurrence of a string

### Parameter-Liste

`haystack`

  The string to look in. Must be valid UTF-8.

`needle`

  The string to look for. Must be valid UTF-8.

`offset`

  The optional `offset` parameter allows you to specify where in `haystack` to start searching as an offset in grapheme units (not bytes or characters). If the offset is negative, it is treated relative to the end of the string. The position returned is still relative to the beginning of `haystack` regardless of the value of `offset`.

`locale`
  Locale to use.

### Rückgabewerte

Returns the position as an integer. If `needle` is not found, grapheme_strpos() will return `false`.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The optional parameter `locale` has been added.
7.1.0 | Support for negative `offset`s has been added.

### Beispiele

Beispiel #1 grapheme_strpos() example

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2

### Siehe auch

- grapheme_stripos() - Find position (in grapheme units) of first occurrence of a case-insensitive string
- grapheme_stristr() - Returns part of haystack string from the first occurrence of case-insensitive needle to the end of haystack
- grapheme_strripos() - Find position (in grapheme units) of last occurrence of a case-insensitive string
- grapheme_strrpos() - Find position (in grapheme units) of last occurrence of a string
- grapheme_strstr() - Returns part of haystack string from the first occurrence of needle to the end of haystack
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strripos — Find position (in grapheme units) of last occurrence of a case-insensitive string

### Beschreibung

Prozeduraler Stil

function grapheme_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Find position (in grapheme units) of last occurrence of a case-insensitive string

### Parameter-Liste

`haystack`

  The string to look in. Must be valid UTF-8.

`needle`

  The string to look for. Must be valid UTF-8.

`offset`

  The optional `offset` parameter allows you to specify where in `haystack` to start searching as an offset in grapheme units (not bytes or characters). The position returned is still relative to the beginning of `haystack` regardless of the value of `offset`.

`locale`
  Locale to use.

### Rückgabewerte

Returns the position as an integer. If `needle` is not found, grapheme_strripos() will return `false`.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The optional parameter `locale` has been added.

### Beispiele

Beispiel #1 grapheme_strripos() example

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"
    $char_O_diaeresis_nfd = "O\xCC\x88"; // 'LATIN CAPITAL LETTER O WITH DIAERESIS' (U+00D6) normalization form "D"

    print grapheme_strripos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_O_diaeresis_nfd);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2

### Siehe auch

- grapheme_stripos() - Find position (in grapheme units) of first occurrence of a case-insensitive string
- grapheme_stristr() - Returns part of haystack string from the first occurrence of case-insensitive needle to the end of haystack
- grapheme_strpos() - Find position (in grapheme units) of first occurrence of a string
- grapheme_strrpos() - Find position (in grapheme units) of last occurrence of a string
- grapheme_strstr() - Returns part of haystack string from the first occurrence of needle to the end of haystack
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strrpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strrpos — Find position (in grapheme units) of last occurrence of a string

### Beschreibung

Prozeduraler Stil

function grapheme_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

Find position (in grapheme units) of last occurrence of a string

### Parameter-Liste

`haystack`

  The string to look in. Must be valid UTF-8.

`needle`

  The string to look for. Must be valid UTF-8.

`offset`

  The optional `offset` parameter allows you to specify where in `haystack` to start searching as an offset in grapheme units (not bytes or characters). The position returned is still relative to the beginning of `haystack` regardless of the value of `offset`.

`locale`
  Locale to use.

### Rückgabewerte

Returns the position as an integer. If `needle` is not found, grapheme_strrpos() will return `false`.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The optional parameter `locale` has been added.

### Beispiele

Beispiel #1 grapheme_strrpos() example

    <?php
    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print grapheme_strrpos( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2

### Siehe auch

- grapheme_stripos() - Find position (in grapheme units) of first occurrence of a case-insensitive string
- grapheme_stristr() - Returns part of haystack string from the first occurrence of case-insensitive needle to the end of haystack
- grapheme_strpos() - Find position (in grapheme units) of first occurrence of a string
- grapheme_strripos() - Find position (in grapheme units) of last occurrence of a case-insensitive string
- grapheme_strstr() - Returns part of haystack string from the first occurrence of needle to the end of haystack
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_strstr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strstr — Returns part of haystack string from the first occurrence of needle to the end of haystack

### Beschreibung

Prozeduraler Stil

function grapheme_strstr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

Returns part of haystack string from the first occurrence of needle to the end of haystack (including the needle).

### Parameter-Liste

`haystack`

  The input string. Must be valid UTF-8.

`needle`

  The string to look for. Must be valid UTF-8.

`beforeNeedle`

  If `true`, grapheme_strstr() returns the part of the `haystack` before the first occurrence of the `needle` (excluding the `needle`).

`locale`
  Locale to use.

### Rückgabewerte

Returns the portion of `haystack`, or `false` if `needle` is not found.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The optional parameter `locale` has been added.

### Beispiele

Beispiel #1 grapheme_strstr() example

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print urlencode(grapheme_stristr( $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_a_ring_nfd, $char_o_diaeresis_nfd));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    o%CC%88a%CC%8A

### Siehe auch

- grapheme_stristr() - Returns part of haystack string from the first occurrence of case-insensitive needle to the end of haystack
- grapheme_stripos() - Find position (in grapheme units) of first occurrence of a case-insensitive string
- grapheme_strpos() - Find position (in grapheme units) of first occurrence of a string
- grapheme_strripos() - Find position (in grapheme units) of last occurrence of a case-insensitive string
- grapheme_strrpos() - Find position (in grapheme units) of last occurrence of a string
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_substr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_substr — Return part of a string

### Beschreibung

Prozeduraler Stil

function grapheme_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
string `$locale` = ""
): string|false

Return part of a string

### Parameter-Liste

`string`

  The input string. Must be valid UTF-8.

`offset`

  Start position in default grapheme units. If `offset` is non-negative, the returned string will start at the `offset`'th position in `string`, counting from zero. If `offset` is negative, the returned string will start at the `offset`'th grapheme unit from the end of string.

`length`

  Length in grapheme units. If `length` is given and is positive, the string returned will contain at most `length` grapheme units beginning from `offset` (depending on the length of string). If `length` is given and is negative, then that many grapheme units will be omitted from the end of string (after the start position has been calculated when `offset` is negative). If `offset` denotes a position beyond this truncation, an empty string will be returned.

`locale`
  Locale to use.

### Rückgabewerte

Returns the extracted part of `string`, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The optional parameter `locale` has been added.
8.0.0 | The function now consistently clamps out-of-bounds offsets to the string boundary. Previously, `false` was returned instead of the empty string in some cases.

### Beispiele

Beispiel #1 grapheme_substr() example

    <?php

    $char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
    $char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

    print urlencode(grapheme_substr( "ao" . $char_a_ring_nfd . "bc" . $char_o_diaeresis_nfd . "O", 2, -1 ));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    a%CC%8Abco%CC%88

### Siehe auch

- grapheme_extract() - Function to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

## Inhaltsverzeichnis

- grapheme_extract — Function to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8
- grapheme_str_split — Split a string into an array
- grapheme_stripos — Find position (in grapheme units) of first occurrence of a case-insensitive string
- grapheme_stristr — Returns part of haystack string from the first occurrence of case-insensitive needle to the end of haystack
- grapheme_strlen — Get string length in grapheme units
- grapheme_strpos — Find position (in grapheme units) of first occurrence of a string
- grapheme_strripos — Find position (in grapheme units) of last occurrence of a case-insensitive string
- grapheme_strrpos — Find position (in grapheme units) of last occurrence of a string
- grapheme_strstr — Returns part of haystack string from the first occurrence of needle to the end of haystack
- grapheme_substr — Return part of a string

# IDN Funktionen

# idn_to_ascii

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_ascii — Convert domain name to IDNA ASCII form

### Beschreibung

Prozeduraler Stil

function idn_to_ascii(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

This function converts a Unicode domain name to an IDNA ASCII-compatible format in lowercase.

### Parameter-Liste

`domain`

  The domain to convert, which must be UTF-8 encoded.

`flags`

  Conversion options - combination of IDNA_* constants (except IDNA_ERROR_* constants).

`variant`

  Either `INTL_IDNA_VARIANT_2003` (deprecated as of PHP 7.2.0) for IDNA 2003 or `INTL_IDNA_VARIANT_UTS46` (only available as of ICU 4.6) for UTS #46.

`idna_info`

  This parameter can be used only if `INTL_IDNA_VARIANT_UTS46` was used for `variant`. In that case, it will be filled with an array with the keys `'result'`, the possibly illegal result of the transformation, `'isTransitionalDifferent'`, a boolean indicating whether the usage of the transitional mechanisms of UTS #46 either has or would have changed the result and `'errors'`, which is an int representing a bitset of the error constants IDNA_ERROR_*.

### Rückgabewerte

The domain name encoded in ASCII-compatible form, Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Now throws a ValueError if the `domain` parameter is empty.
8.4.0 | Now throws a ValueError if the `variant` parameter is not `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | The default value of `variant` is now `INTL_IDNA_VARIANT_UTS46` instead of the deprecated `INTL_IDNA_VARIANT_2003`.
7.2.0 | `INTL_IDNA_VARIANT_2003` has been deprecated; use `INTL_IDNA_VARIANT_UTS46` instead.

### Beispiele

Beispiel #1 idn_to_ascii() example

    <?php

    echo idn_to_ascii('täst.de');

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    xn--tst-qla.de

Beispiel #2 All-ASCII domain names are just converted to lowercase

    <?php

    var_dump(idn_to_ascii('Example.com'));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(11) "example.com"

### Siehe auch

- idn_to_utf8() - Convert domain name from IDNA ASCII to Unicode

# idn_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.2, PECL idn >= 0.1)

idn_to_utf8 — Convert domain name from IDNA ASCII to Unicode

### Beschreibung

Prozeduraler Stil

function idn_to_utf8(
string `$domain`,
int `$flags` = `IDNA_DEFAULT`,
int `$variant` = `INTL_IDNA_VARIANT_UTS46`,
array `&$idna_info` = `null`
): string|false

This function converts a Unicode domain name from an IDNA ASCII-compatible format to plain Unicode, encoded in UTF-8.

### Parameter-Liste

`domain`

  Domain to convert in an IDNA ASCII-compatible format.

`flags`

  Conversion options - combination of IDNA_* constants (except IDNA_ERROR_* constants).

`variant`

  Either `INTL_IDNA_VARIANT_2003` (deprecated as of PHP 7.2.0) for IDNA 2003 or `INTL_IDNA_VARIANT_UTS46` (only available as of ICU 4.6) for UTS #46.

`idna_info`

  This parameter can be used only if `INTL_IDNA_VARIANT_UTS46` was used for `variant`. In that case, it will be filled with an array with the keys `'result'`, the possibly illegal result of the transformation, `'isTransitionalDifferent'`, a boolean indicating whether the usage of the transitional mechanisms of UTS #46 either has or would have changed the result and `'errors'`, which is an int representing a bitset of the error constants IDNA_ERROR_*.

### Rückgabewerte

The domain name in Unicode, encoded in UTF-8, Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Now throws a ValueError if the `domain` parameter is empty.
8.4.0 | Now throws a ValueError if the `variant` parameter is not `INTL_IDNA_VARIANT_UTS46`.
7.4.0 | The default value of `variant` is now `INTL_IDNA_VARIANT_UTS46` instead of the deprecated `INTL_IDNA_VARIANT_2003`.
7.2.0 | `INTL_IDNA_VARIANT_2003` has been deprecated; use `INTL_IDNA_VARIANT_UTS46` instead.

### Beispiele

Beispiel #1 idn_to_utf8() example

    <?php

    echo idn_to_utf8('xn--tst-qla.de');

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    täst.de

### Siehe auch

- idn_to_ascii() - Convert domain name to IDNA ASCII form

## Inhaltsverzeichnis

- idn_to_ascii — Convert domain name to IDNA ASCII form
- idn_to_utf8 — Convert domain name from IDNA ASCII to Unicode

# IntlChar

(PHP 7, PHP 8)

## Einführung

Die Klasse IntlChar bietet eine Reihe von nützlichen Methoden für den Zugriff auf Informationen über Unicode-Zeichen.

Die Methoden und Konstanten lehnen sich eng an die Namen und das Verhalten der zugrunde liegenden ICU-Bibliothek an.

## Klassenbeschreibung

class IntlChar {
/* Konstanten */
public const string UNICODE_VERSION;
public const int CODEPOINT_MIN;
public const int CODEPOINT_MAX;
public const float NO_NUMERIC_VALUE;
public const int PROPERTY_ALPHABETIC;
public const int PROPERTY_BINARY_START;
public const int PROPERTY_ASCII_HEX_DIGIT;
public const int PROPERTY_BIDI_CONTROL;
public const int PROPERTY_BIDI_MIRRORED;
public const int PROPERTY_DASH;
public const int PROPERTY_DEFAULT_IGNORABLE_CODE_POINT;
public const int PROPERTY_DEPRECATED;
public const int PROPERTY_DIACRITIC;
public const int PROPERTY_EXTENDER;
public const int PROPERTY_FULL_COMPOSITION_EXCLUSION;
public const int PROPERTY_GRAPHEME_BASE;
public const int PROPERTY_GRAPHEME_EXTEND;
public const int PROPERTY_GRAPHEME_LINK;
public const int PROPERTY_HEX_DIGIT;
public const int PROPERTY_HYPHEN;
public const int PROPERTY_ID_CONTINUE;
public const int PROPERTY_ID_START;
public const int PROPERTY_IDEOGRAPHIC;
public const int PROPERTY_IDS_BINARY_OPERATOR;
public const int PROPERTY_IDS_TRINARY_OPERATOR;
public const int PROPERTY_JOIN_CONTROL;
public const int PROPERTY_LOGICAL_ORDER_EXCEPTION;
public const int PROPERTY_LOWERCASE;
public const int PROPERTY_MATH;
public const int PROPERTY_NONCHARACTER_CODE_POINT;
public const int PROPERTY_QUOTATION_MARK;
public const int PROPERTY_RADICAL;
public const int PROPERTY_SOFT_DOTTED;
public const int PROPERTY_TERMINAL_PUNCTUATION;
public const int PROPERTY_UNIFIED_IDEOGRAPH;
public const int PROPERTY_UPPERCASE;
public const int PROPERTY_WHITE_SPACE;
public const int PROPERTY_XID_CONTINUE;
public const int PROPERTY_XID_START;
public const int PROPERTY_CASE_SENSITIVE;
public const int PROPERTY_S_TERM;
public const int PROPERTY_VARIATION_SELECTOR;
public const int PROPERTY_NFD_INERT;
public const int PROPERTY_NFKD_INERT;
public const int PROPERTY_NFC_INERT;
public const int PROPERTY_NFKC_INERT;
public const int PROPERTY_SEGMENT_STARTER;
public const int PROPERTY_PATTERN_SYNTAX;
public const int PROPERTY_PATTERN_WHITE_SPACE;
public const int PROPERTY_POSIX_ALNUM;
public const int PROPERTY_POSIX_BLANK;
public const int PROPERTY_POSIX_GRAPH;
public const int PROPERTY_POSIX_PRINT;
public const int PROPERTY_POSIX_XDIGIT;
public const int PROPERTY_CASED;
public const int PROPERTY_CASE_IGNORABLE;
public const int PROPERTY_CHANGES_WHEN_LOWERCASED;
public const int PROPERTY_CHANGES_WHEN_UPPERCASED;
public const int PROPERTY_CHANGES_WHEN_TITLECASED;
public const int PROPERTY_CHANGES_WHEN_CASEFOLDED;
public const int PROPERTY_CHANGES_WHEN_CASEMAPPED;
public const int PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED;
public const int PROPERTY_BINARY_LIMIT;
public const int PROPERTY_BIDI_CLASS;
public const int PROPERTY_INT_START;
public const int PROPERTY_BLOCK;
public const int PROPERTY_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_DECOMPOSITION_TYPE;
public const int PROPERTY_EAST_ASIAN_WIDTH;
public const int PROPERTY_GENERAL_CATEGORY;
public const int PROPERTY_JOINING_GROUP;
public const int PROPERTY_JOINING_TYPE;
public const int PROPERTY_LINE_BREAK;
public const int PROPERTY_NUMERIC_TYPE;
public const int PROPERTY_SCRIPT;
public const int PROPERTY_HANGUL_SYLLABLE_TYPE;
public const int PROPERTY_NFD_QUICK_CHECK;
public const int PROPERTY_NFKD_QUICK_CHECK;
public const int PROPERTY_NFC_QUICK_CHECK;
public const int PROPERTY_NFKC_QUICK_CHECK;
public const int PROPERTY_LEAD_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS;
public const int PROPERTY_GRAPHEME_CLUSTER_BREAK;
public const int PROPERTY_SENTENCE_BREAK;
public const int PROPERTY_WORD_BREAK;
public const int PROPERTY_BIDI_PAIRED_BRACKET_TYPE;
public const int PROPERTY_INT_LIMIT;
public const int PROPERTY_GENERAL_CATEGORY_MASK;
public const int PROPERTY_MASK_START;
public const int PROPERTY_MASK_LIMIT;
public const int PROPERTY_NUMERIC_VALUE;
public const int PROPERTY_DOUBLE_START;
public const int PROPERTY_DOUBLE_LIMIT;
public const int PROPERTY_AGE;
public const int PROPERTY_STRING_START;
public const int PROPERTY_BIDI_MIRRORING_GLYPH;
public const int PROPERTY_CASE_FOLDING;
public const int PROPERTY_ISO_COMMENT;
public const int PROPERTY_LOWERCASE_MAPPING;
public const int PROPERTY_NAME;
public const int PROPERTY_SIMPLE_CASE_FOLDING;
public const int PROPERTY_SIMPLE_LOWERCASE_MAPPING;
public const int PROPERTY_SIMPLE_TITLECASE_MAPPING;
public const int PROPERTY_SIMPLE_UPPERCASE_MAPPING;
public const int PROPERTY_TITLECASE_MAPPING;
public const int PROPERTY_UNICODE_1_NAME;
public const int PROPERTY_UPPERCASE_MAPPING;
public const int PROPERTY_BIDI_PAIRED_BRACKET;
public const int PROPERTY_STRING_LIMIT;
public const int PROPERTY_SCRIPT_EXTENSIONS;
public const int PROPERTY_OTHER_PROPERTY_START;
public const int PROPERTY_OTHER_PROPERTY_LIMIT;
public const int PROPERTY_INVALID_CODE;
public const int CHAR_CATEGORY_UNASSIGNED;
public const int CHAR_CATEGORY_GENERAL_OTHER_TYPES;
public const int CHAR_CATEGORY_UPPERCASE_LETTER;
public const int CHAR_CATEGORY_LOWERCASE_LETTER;
public const int CHAR_CATEGORY_TITLECASE_LETTER;
public const int CHAR_CATEGORY_MODIFIER_LETTER;
public const int CHAR_CATEGORY_OTHER_LETTER;
public const int CHAR_CATEGORY_NON_SPACING_MARK;
public const int CHAR_CATEGORY_ENCLOSING_MARK;
public const int CHAR_CATEGORY_COMBINING_SPACING_MARK;
public const int CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER;
public const int CHAR_CATEGORY_LETTER_NUMBER;
public const int CHAR_CATEGORY_OTHER_NUMBER;
public const int CHAR_CATEGORY_SPACE_SEPARATOR;
public const int CHAR_CATEGORY_LINE_SEPARATOR;
public const int CHAR_CATEGORY_PARAGRAPH_SEPARATOR;
public const int CHAR_CATEGORY_CONTROL_CHAR;
public const int CHAR_CATEGORY_FORMAT_CHAR;
public const int CHAR_CATEGORY_PRIVATE_USE_CHAR;
public const int CHAR_CATEGORY_SURROGATE;
public const int CHAR_CATEGORY_DASH_PUNCTUATION;
public const int CHAR_CATEGORY_START_PUNCTUATION;
public const int CHAR_CATEGORY_END_PUNCTUATION;
public const int CHAR_CATEGORY_CONNECTOR_PUNCTUATION;
public const int CHAR_CATEGORY_OTHER_PUNCTUATION;
public const int CHAR_CATEGORY_MATH_SYMBOL;
public const int CHAR_CATEGORY_CURRENCY_SYMBOL;
public const int CHAR_CATEGORY_MODIFIER_SYMBOL;
public const int CHAR_CATEGORY_OTHER_SYMBOL;
public const int CHAR_CATEGORY_INITIAL_PUNCTUATION;
public const int CHAR_CATEGORY_FINAL_PUNCTUATION;
public const int CHAR_CATEGORY_CHAR_CATEGORY_COUNT;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR;
public const int CHAR_DIRECTION_ARABIC_NUMBER;
public const int CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR;
public const int CHAR_DIRECTION_BLOCK_SEPARATOR;
public const int CHAR_DIRECTION_SEGMENT_SEPARATOR;
public const int CHAR_DIRECTION_WHITE_SPACE_NEUTRAL;
public const int CHAR_DIRECTION_OTHER_NEUTRAL;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT;
public const int CHAR_DIRECTION_DIR_NON_SPACING_MARK;
public const int CHAR_DIRECTION_BOUNDARY_NEUTRAL;
public const int CHAR_DIRECTION_FIRST_STRONG_ISOLATE;
public const int CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE;
public const int CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE;
public const int CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE;
public const int CHAR_DIRECTION_CHAR_DIRECTION_COUNT;
public const int BLOCK_CODE_NO_BLOCK;
public const int BLOCK_CODE_BASIC_LATIN;
public const int BLOCK_CODE_LATIN_1_SUPPLEMENT;
public const int BLOCK_CODE_LATIN_EXTENDED_A;
public const int BLOCK_CODE_LATIN_EXTENDED_B;
public const int BLOCK_CODE_IPA_EXTENSIONS;
public const int BLOCK_CODE_SPACING_MODIFIER_LETTERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS;
public const int BLOCK_CODE_GREEK;
public const int BLOCK_CODE_CYRILLIC;
public const int BLOCK_CODE_ARMENIAN;
public const int BLOCK_CODE_HEBREW;
public const int BLOCK_CODE_ARABIC;
public const int BLOCK_CODE_SYRIAC;
public const int BLOCK_CODE_THAANA;
public const int BLOCK_CODE_DEVANAGARI;
public const int BLOCK_CODE_BENGALI;
public const int BLOCK_CODE_GURMUKHI;
public const int BLOCK_CODE_GUJARATI;
public const int BLOCK_CODE_ORIYA;
public const int BLOCK_CODE_TAMIL;
public const int BLOCK_CODE_TELUGU;
public const int BLOCK_CODE_KANNADA;
public const int BLOCK_CODE_MALAYALAM;
public const int BLOCK_CODE_SINHALA;
public const int BLOCK_CODE_THAI;
public const int BLOCK_CODE_LAO;
public const int BLOCK_CODE_TIBETAN;
public const int BLOCK_CODE_MYANMAR;
public const int BLOCK_CODE_GEORGIAN;
public const int BLOCK_CODE_HANGUL_JAMO;
public const int BLOCK_CODE_ETHIOPIC;
public const int BLOCK_CODE_CHEROKEE;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS;
public const int BLOCK_CODE_OGHAM;
public const int BLOCK_CODE_RUNIC;
public const int BLOCK_CODE_KHMER;
public const int BLOCK_CODE_MONGOLIAN;
public const int BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL;
public const int BLOCK_CODE_GREEK_EXTENDED;
public const int BLOCK_CODE_GENERAL_PUNCTUATION;
public const int BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS;
public const int BLOCK_CODE_CURRENCY_SYMBOLS;
public const int BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS;
public const int BLOCK_CODE_LETTERLIKE_SYMBOLS;
public const int BLOCK_CODE_NUMBER_FORMS;
public const int BLOCK_CODE_ARROWS;
public const int BLOCK_CODE_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_MISCELLANEOUS_TECHNICAL;
public const int BLOCK_CODE_CONTROL_PICTURES;
public const int BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERICS;
public const int BLOCK_CODE_BOX_DRAWING;
public const int BLOCK_CODE_BLOCK_ELEMENTS;
public const int BLOCK_CODE_GEOMETRIC_SHAPES;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS;
public const int BLOCK_CODE_DINGBATS;
public const int BLOCK_CODE_BRAILLE_PATTERNS;
public const int BLOCK_CODE_CJK_RADICALS_SUPPLEMENT;
public const int BLOCK_CODE_KANGXI_RADICALS;
public const int BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS;
public const int BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION;
public const int BLOCK_CODE_HIRAGANA;
public const int BLOCK_CODE_KATAKANA;
public const int BLOCK_CODE_BOPOMOFO;
public const int BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO;
public const int BLOCK_CODE_KANBUN;
public const int BLOCK_CODE_BOPOMOFO_EXTENDED;
public const int BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS;
public const int BLOCK_CODE_CJK_COMPATIBILITY;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS;
public const int BLOCK_CODE_YI_SYLLABLES;
public const int BLOCK_CODE_YI_RADICALS;
public const int BLOCK_CODE_HANGUL_SYLLABLES;
public const int BLOCK_CODE_HIGH_SURROGATES;
public const int BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES;
public const int BLOCK_CODE_LOW_SURROGATES;
public const int BLOCK_CODE_PRIVATE_USE_AREA;
public const int BLOCK_CODE_PRIVATE_USE;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS;
public const int BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A;
public const int BLOCK_CODE_COMBINING_HALF_MARKS;
public const int BLOCK_CODE_CJK_COMPATIBILITY_FORMS;
public const int BLOCK_CODE_SMALL_FORM_VARIANTS;
public const int BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B;
public const int BLOCK_CODE_SPECIALS;
public const int BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS;
public const int BLOCK_CODE_OLD_ITALIC;
public const int BLOCK_CODE_GOTHIC;
public const int BLOCK_CODE_DESERET;
public const int BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MUSICAL_SYMBOLS;
public const int BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B;
public const int BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT;
public const int BLOCK_CODE_TAGS;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENT;
public const int BLOCK_CODE_CYRILLIC_SUPPLEMENTARY;
public const int BLOCK_CODE_TAGALOG;
public const int BLOCK_CODE_HANUNOO;
public const int BLOCK_CODE_BUHID;
public const int BLOCK_CODE_TAGBANWA;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_A;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_B;
public const int BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B;
public const int BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS;
public const int BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_VARIATION_SELECTORS;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A;
public const int BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B;
public const int BLOCK_CODE_LIMBU;
public const int BLOCK_CODE_TAI_LE;
public const int BLOCK_CODE_KHMER_SYMBOLS;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS;
public const int BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS;
public const int BLOCK_CODE_LINEAR_B_SYLLABARY;
public const int BLOCK_CODE_LINEAR_B_IDEOGRAMS;
public const int BLOCK_CODE_AEGEAN_NUMBERS;
public const int BLOCK_CODE_UGARITIC;
public const int BLOCK_CODE_SHAVIAN;
public const int BLOCK_CODE_OSMANYA;
public const int BLOCK_CODE_CYPRIOT_SYLLABARY;
public const int BLOCK_CODE_TAI_XUAN_JING_SYMBOLS;
public const int BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT;
public const int BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION;
public const int BLOCK_CODE_ANCIENT_GREEK_NUMBERS;
public const int BLOCK_CODE_ARABIC_SUPPLEMENT;
public const int BLOCK_CODE_BUGINESE;
public const int BLOCK_CODE_CJK_STROKES;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT;
public const int BLOCK_CODE_COPTIC;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED;
public const int BLOCK_CODE_ETHIOPIC_SUPPLEMENT;
public const int BLOCK_CODE_GEORGIAN_SUPPLEMENT;
public const int BLOCK_CODE_GLAGOLITIC;
public const int BLOCK_CODE_KHAROSHTHI;
public const int BLOCK_CODE_MODIFIER_TONE_LETTERS;
public const int BLOCK_CODE_NEW_TAI_LUE;
public const int BLOCK_CODE_OLD_PERSIAN;
public const int BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT;
public const int BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION;
public const int BLOCK_CODE_SYLOTI_NAGRI;
public const int BLOCK_CODE_TIFINAGH;
public const int BLOCK_CODE_VERTICAL_FORMS;
public const int BLOCK_CODE_NKO;
public const int BLOCK_CODE_BALINESE;
public const int BLOCK_CODE_LATIN_EXTENDED_C;
public const int BLOCK_CODE_LATIN_EXTENDED_D;
public const int BLOCK_CODE_PHAGS_PA;
public const int BLOCK_CODE_PHOENICIAN;
public const int BLOCK_CODE_CUNEIFORM;
public const int BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION;
public const int BLOCK_CODE_COUNTING_ROD_NUMERALS;
public const int BLOCK_CODE_SUNDANESE;
public const int BLOCK_CODE_LEPCHA;
public const int BLOCK_CODE_OL_CHIKI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_A;
public const int BLOCK_CODE_VAI;
public const int BLOCK_CODE_CYRILLIC_EXTENDED_B;
public const int BLOCK_CODE_SAURASHTRA;
public const int BLOCK_CODE_KAYAH_LI;
public const int BLOCK_CODE_REJANG;
public const int BLOCK_CODE_CHAM;
public const int BLOCK_CODE_ANCIENT_SYMBOLS;
public const int BLOCK_CODE_PHAISTOS_DISC;
public const int BLOCK_CODE_LYCIAN;
public const int BLOCK_CODE_CARIAN;
public const int BLOCK_CODE_LYDIAN;
public const int BLOCK_CODE_MAHJONG_TILES;
public const int BLOCK_CODE_DOMINO_TILES;
public const int BLOCK_CODE_SAMARITAN;
public const int BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED;
public const int BLOCK_CODE_TAI_THAM;
public const int BLOCK_CODE_VEDIC_EXTENSIONS;
public const int BLOCK_CODE_LISU;
public const int BLOCK_CODE_BAMUM;
public const int BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS;
public const int BLOCK_CODE_DEVANAGARI_EXTENDED;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_A;
public const int BLOCK_CODE_JAVANESE;
public const int BLOCK_CODE_MYANMAR_EXTENDED_A;
public const int BLOCK_CODE_TAI_VIET;
public const int BLOCK_CODE_MEETEI_MAYEK;
public const int BLOCK_CODE_HANGUL_JAMO_EXTENDED_B;
public const int BLOCK_CODE_IMPERIAL_ARAMAIC;
public const int BLOCK_CODE_OLD_SOUTH_ARABIAN;
public const int BLOCK_CODE_AVESTAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PARTHIAN;
public const int BLOCK_CODE_INSCRIPTIONAL_PAHLAVI;
public const int BLOCK_CODE_OLD_TURKIC;
public const int BLOCK_CODE_RUMI_NUMERAL_SYMBOLS;
public const int BLOCK_CODE_KAITHI;
public const int BLOCK_CODE_EGYPTIAN_HIEROGLYPHS;
public const int BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT;
public const int BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C;
public const int BLOCK_CODE_MANDAIC;
public const int BLOCK_CODE_BATAK;
public const int BLOCK_CODE_ETHIOPIC_EXTENDED_A;
public const int BLOCK_CODE_BRAHMI;
public const int BLOCK_CODE_BAMUM_SUPPLEMENT;
public const int BLOCK_CODE_KANA_SUPPLEMENT;
public const int BLOCK_CODE_PLAYING_CARDS;
public const int BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS;
public const int BLOCK_CODE_EMOTICONS;
public const int BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS;
public const int BLOCK_CODE_ALCHEMICAL_SYMBOLS;
public const int BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D;
public const int BLOCK_CODE_ARABIC_EXTENDED_A;
public const int BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS;
public const int BLOCK_CODE_CHAKMA;
public const int BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS;
public const int BLOCK_CODE_MEROITIC_CURSIVE;
public const int BLOCK_CODE_MEROITIC_HIEROGLYPHS;
public const int BLOCK_CODE_MIAO;
public const int BLOCK_CODE_SHARADA;
public const int BLOCK_CODE_SORA_SOMPENG;
public const int BLOCK_CODE_SUNDANESE_SUPPLEMENT;
public const int BLOCK_CODE_TAKRI;
public const int BLOCK_CODE_BASSA_VAH;
public const int BLOCK_CODE_CAUCASIAN_ALBANIAN;
public const int BLOCK_CODE_COPTIC_EPACT_NUMBERS;
public const int BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED;
public const int BLOCK_CODE_DUPLOYAN;
public const int BLOCK_CODE_ELBASAN;
public const int BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED;
public const int BLOCK_CODE_GRANTHA;
public const int BLOCK_CODE_KHOJKI;
public const int BLOCK_CODE_KHUDAWADI;
public const int BLOCK_CODE_LATIN_EXTENDED_E;
public const int BLOCK_CODE_LINEAR_A;
public const int BLOCK_CODE_MAHAJANI;
public const int BLOCK_CODE_MANICHAEAN;
public const int BLOCK_CODE_MENDE_KIKAKUI;
public const int BLOCK_CODE_MODI;
public const int BLOCK_CODE_MRO;
public const int BLOCK_CODE_MYANMAR_EXTENDED_B;
public const int BLOCK_CODE_NABATAEAN;
public const int BLOCK_CODE_OLD_NORTH_ARABIAN;
public const int BLOCK_CODE_OLD_PERMIC;
public const int BLOCK_CODE_ORNAMENTAL_DINGBATS;
public const int BLOCK_CODE_PAHAWH_HMONG;
public const int BLOCK_CODE_PALMYRENE;
public const int BLOCK_CODE_PAU_CIN_HAU;
public const int BLOCK_CODE_PSALTER_PAHLAVI;
public const int BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS;
public const int BLOCK_CODE_SIDDHAM;
public const int BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS;
public const int BLOCK_CODE_SUPPLEMENTAL_ARROWS_C;
public const int BLOCK_CODE_TIRHUTA;
public const int BLOCK_CODE_WARANG_CITI;
public const int BLOCK_CODE_COUNT;
public const int BLOCK_CODE_INVALID_CODE;
public const int BPT_NONE;
public const int BPT_OPEN;
public const int BPT_CLOSE;
public const int BPT_COUNT;
public const int EA_NEUTRAL;
public const int EA_AMBIGUOUS;
public const int EA_HALFWIDTH;
public const int EA_FULLWIDTH;
public const int EA_NARROW;
public const int EA_WIDE;
public const int EA_COUNT;
public const int UNICODE_CHAR_NAME;
public const int UNICODE_10_CHAR_NAME;
public const int EXTENDED_CHAR_NAME;
public const int CHAR_NAME_ALIAS;
public const int CHAR_NAME_CHOICE_COUNT;
public const int SHORT_PROPERTY_NAME;
public const int LONG_PROPERTY_NAME;
public const int PROPERTY_NAME_CHOICE_COUNT;
public const int DT_NONE;
public const int DT_CANONICAL;
public const int DT_COMPAT;
public const int DT_CIRCLE;
public const int DT_FINAL;
public const int DT_FONT;
public const int DT_FRACTION;
public const int DT_INITIAL;
public const int DT_ISOLATED;
public const int DT_MEDIAL;
public const int DT_NARROW;
public const int DT_NOBREAK;
public const int DT_SMALL;
public const int DT_SQUARE;
public const int DT_SUB;
public const int DT_SUPER;
public const int DT_VERTICAL;
public const int DT_WIDE;
public const int DT_COUNT;
public const int JT_NON_JOINING;
public const int JT_JOIN_CAUSING;
public const int JT_DUAL_JOINING;
public const int JT_LEFT_JOINING;
public const int JT_RIGHT_JOINING;
public const int JT_TRANSPARENT;
public const int JT_COUNT;
public const int JG_NO_JOINING_GROUP;
public const int JG_AIN;
public const int JG_ALAPH;
public const int JG_ALEF;
public const int JG_BEH;
public const int JG_BETH;
public const int JG_DAL;
public const int JG_DALATH_RISH;
public const int JG_E;
public const int JG_FEH;
public const int JG_FINAL_SEMKATH;
public const int JG_GAF;
public const int JG_GAMAL;
public const int JG_HAH;
public const int JG_TEH_MARBUTA_GOAL;
public const int JG_HAMZA_ON_HEH_GOAL;
public const int JG_HE;
public const int JG_HEH;
public const int JG_HEH_GOAL;
public const int JG_HETH;
public const int JG_KAF;
public const int JG_KAPH;
public const int JG_KNOTTED_HEH;
public const int JG_LAM;
public const int JG_LAMADH;
public const int JG_MEEM;
public const int JG_MIM;
public const int JG_NOON;
public const int JG_NUN;
public const int JG_PE;
public const int JG_QAF;
public const int JG_QAPH;
public const int JG_REH;
public const int JG_REVERSED_PE;
public const int JG_SAD;
public const int JG_SADHE;
public const int JG_SEEN;
public const int JG_SEMKATH;
public const int JG_SHIN;
public const int JG_SWASH_KAF;
public const int JG_SYRIAC_WAW;
public const int JG_TAH;
public const int JG_TAW;
public const int JG_TEH_MARBUTA;
public const int JG_TETH;
public const int JG_WAW;
public const int JG_YEH;
public const int JG_YEH_BARREE;
public const int JG_YEH_WITH_TAIL;
public const int JG_YUDH;
public const int JG_YUDH_HE;
public const int JG_ZAIN;
public const int JG_FE;
public const int JG_KHAPH;
public const int JG_ZHAIN;
public const int JG_BURUSHASKI_YEH_BARREE;
public const int JG_FARSI_YEH;
public const int JG_NYA;
public const int JG_ROHINGYA_YEH;
public const int JG_MANICHAEAN_ALEPH;
public const int JG_MANICHAEAN_AYIN;
public const int JG_MANICHAEAN_BETH;
public const int JG_MANICHAEAN_DALETH;
public const int JG_MANICHAEAN_DHAMEDH;
public const int JG_MANICHAEAN_FIVE;
public const int JG_MANICHAEAN_GIMEL;
public const int JG_MANICHAEAN_HETH;
public const int JG_MANICHAEAN_HUNDRED;
public const int JG_MANICHAEAN_KAPH;
public const int JG_MANICHAEAN_LAMEDH;
public const int JG_MANICHAEAN_MEM;
public const int JG_MANICHAEAN_NUN;
public const int JG_MANICHAEAN_ONE;
public const int JG_MANICHAEAN_PE;
public const int JG_MANICHAEAN_QOPH;
public const int JG_MANICHAEAN_RESH;
public const int JG_MANICHAEAN_SADHE;
public const int JG_MANICHAEAN_SAMEKH;
public const int JG_MANICHAEAN_TAW;
public const int JG_MANICHAEAN_TEN;
public const int JG_MANICHAEAN_TETH;
public const int JG_MANICHAEAN_THAMEDH;
public const int JG_MANICHAEAN_TWENTY;
public const int JG_MANICHAEAN_WAW;
public const int JG_MANICHAEAN_YODH;
public const int JG_MANICHAEAN_ZAYIN;
public const int JG_STRAIGHT_WAW;
public const int JG_COUNT;
public const int GCB_OTHER;
public const int GCB_CONTROL;
public const int GCB_CR;
public const int GCB_EXTEND;
public const int GCB_L;
public const int GCB_LF;
public const int GCB_LV;
public const int GCB_LVT;
public const int GCB_T;
public const int GCB_V;
public const int GCB_SPACING_MARK;
public const int GCB_PREPEND;
public const int GCB_REGIONAL_INDICATOR;
public const int GCB_COUNT;
public const int WB_OTHER;
public const int WB_ALETTER;
public const int WB_FORMAT;
public const int WB_KATAKANA;
public const int WB_MIDLETTER;
public const int WB_MIDNUM;
public const int WB_NUMERIC;
public const int WB_EXTENDNUMLET;
public const int WB_CR;
public const int WB_EXTEND;
public const int WB_LF;
public const int WB_MIDNUMLET;
public const int WB_NEWLINE;
public const int WB_REGIONAL_INDICATOR;
public const int WB_HEBREW_LETTER;
public const int WB_SINGLE_QUOTE;
public const int WB_DOUBLE_QUOTE;
public const int WB_COUNT;
public const int SB_OTHER;
public const int SB_ATERM;
public const int SB_CLOSE;
public const int SB_FORMAT;
public const int SB_LOWER;
public const int SB_NUMERIC;
public const int SB_OLETTER;
public const int SB_SEP;
public const int SB_SP;
public const int SB_STERM;
public const int SB_UPPER;
public const int SB_CR;
public const int SB_EXTEND;
public const int SB_LF;
public const int SB_SCONTINUE;
public const int SB_COUNT;
public const int LB_UNKNOWN;
public const int LB_AMBIGUOUS;
public const int LB_ALPHABETIC;
public const int LB_BREAK_BOTH;
public const int LB_BREAK_AFTER;
public const int LB_BREAK_BEFORE;
public const int LB_MANDATORY_BREAK;
public const int LB_CONTINGENT_BREAK;
public const int LB_CLOSE_PUNCTUATION;
public const int LB_COMBINING_MARK;
public const int LB_CARRIAGE_RETURN;
public const int LB_EXCLAMATION;
public const int LB_GLUE;
public const int LB_HYPHEN;
public const int LB_IDEOGRAPHIC;
public const int LB_INSEPARABLE;
public const int LB_INSEPERABLE;
public const int LB_INFIX_NUMERIC;
public const int LB_LINE_FEED;
public const int LB_NONSTARTER;
public const int LB_NUMERIC;
public const int LB_OPEN_PUNCTUATION;
public const int LB_POSTFIX_NUMERIC;
public const int LB_PREFIX_NUMERIC;
public const int LB_QUOTATION;
public const int LB_COMPLEX_CONTEXT;
public const int LB_SURROGATE;
public const int LB_SPACE;
public const int LB_BREAK_SYMBOLS;
public const int LB_ZWSPACE;
public const int LB_NEXT_LINE;
public const int LB_WORD_JOINER;
public const int LB_H2;
public const int LB_H3;
public const int LB_JL;
public const int LB_JT;
public const int LB_JV;
public const int LB_CLOSE_PARENTHESIS;
public const int LB_CONDITIONAL_JAPANESE_STARTER;
public const int LB_HEBREW_LETTER;
public const int LB_REGIONAL_INDICATOR;
public const int LB_COUNT;
public const int NT_NONE;
public const int NT_DECIMAL;
public const int NT_DIGIT;
public const int NT_NUMERIC;
public const int NT_COUNT;
public const int HST_NOT_APPLICABLE;
public const int HST_LEADING_JAMO;
public const int HST_VOWEL_JAMO;
public const int HST_TRAILING_JAMO;
public const int HST_LV_SYLLABLE;
public const int HST_LVT_SYLLABLE;
public const int HST_COUNT;
public const int FOLD_CASE_DEFAULT;
public const int FOLD_CASE_EXCLUDE_SPECIAL_I;
/* Methoden */
public static function charAge(int|string `$codepoint`): ?array
public static function charDigitValue(int|string `$codepoint`): ?int
public static function charDirection(int|string `$codepoint`): ?int
public static function charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int
public static function charMirror(int|string `$codepoint`): int|string|null
public static function charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string
public static function charType(int|string `$codepoint`): ?int
public static function chr(int|string `$codepoint`): ?string
public static function digit(int|string `$codepoint`, int `$base` = 10): int|false|null
public static function enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool
public static function enumCharTypes(callable `$callback`): void
public static function foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null
public static function forDigit(int `$digit`, int `$base` = 10): int
public static function getBidiPairedBracket(int|string `$codepoint`): int|string|null
public static function getBlockCode(int|string `$codepoint`): ?int
public static function getCombiningClass(int|string `$codepoint`): ?int
public static function getFC_NFKC_Closure(int|string `$codepoint`): string|false|null
public static function getIntPropertyMaxValue(int `$property`): int
public static function getIntPropertyMinValue(int `$property`): int
public static function getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int
public static function getNumericValue(int|string `$codepoint`): ?float
public static function getPropertyEnum(string `$alias`): int
public static function getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getPropertyValueEnum(int `$property`, string `$name`): int
public static function getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getUnicodeVersion(): array
public static function hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool
public static function isalnum(int|string `$codepoint`): ?bool
public static function isalpha(int|string `$codepoint`): ?bool
public static function isbase(int|string `$codepoint`): ?bool
public static function isblank(int|string `$codepoint`): ?bool
public static function iscntrl(int|string `$codepoint`): ?bool
public static function isdefined(int|string `$codepoint`): ?bool
public static function isdigit(int|string `$codepoint`): ?bool
public static function isgraph(int|string `$codepoint`): ?bool
public static function isIDIgnorable(int|string `$codepoint`): ?bool
public static function isIDPart(int|string `$codepoint`): ?bool
public static function isIDStart(int|string `$codepoint`): ?bool
public static function isISOControl(int|string `$codepoint`): ?bool
public static function isJavaIDPart(int|string `$codepoint`): ?bool
public static function isJavaIDStart(int|string `$codepoint`): ?bool
public static function isJavaSpaceChar(int|string `$codepoint`): ?bool
public static function islower(int|string `$codepoint`): ?bool
public static function isMirrored(int|string `$codepoint`): ?bool
public static function isprint(int|string `$codepoint`): ?bool
public static function ispunct(int|string `$codepoint`): ?bool
public static function isspace(int|string `$codepoint`): ?bool
public static function istitle(int|string `$codepoint`): ?bool
public static function isUAlphabetic(int|string `$codepoint`): ?bool
public static function isULowercase(int|string `$codepoint`): ?bool
public static function isupper(int|string `$codepoint`): ?bool
public static function isUUppercase(int|string `$codepoint`): ?bool
public static function isUWhiteSpace(int|string `$codepoint`): ?bool
public static function isWhitespace(int|string `$codepoint`): ?bool
public static function isxdigit(int|string `$codepoint`): ?bool
public static function ord(int|string `$character`): ?int
public static function tolower(int|string `$codepoint`): int|string|null
public static function totitle(int|string `$codepoint`): int|string|null
public static function toupper(int|string `$codepoint`): int|string|null
}

## Vordefinierte Konstanten

`IntlChar::UNICODE_VERSION` string

`IntlChar::CODEPOINT_MIN` int

`IntlChar::CODEPOINT_MAX` int

`IntlChar::NO_NUMERIC_VALUE` int

  Special value that is returned by IntlChar::getNumericValue() when no numeric value is defined for a code point.

`IntlChar::PROPERTY_ALPHABETIC` int

`IntlChar::PROPERTY_BINARY_START` int

`IntlChar::PROPERTY_ASCII_HEX_DIGIT` int

`IntlChar::PROPERTY_BIDI_CONTROL` int

`IntlChar::PROPERTY_BIDI_MIRRORED` int

`IntlChar::PROPERTY_DASH` int

`IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT` int

`IntlChar::PROPERTY_DEPRECATED` int

`IntlChar::PROPERTY_DIACRITIC` int

`IntlChar::PROPERTY_EXTENDER` int

`IntlChar::PROPERTY_FULL_COMPOSITION_EXCLUSION` int

`IntlChar::PROPERTY_GRAPHEME_BASE` int

`IntlChar::PROPERTY_GRAPHEME_EXTEND` int

`IntlChar::PROPERTY_GRAPHEME_LINK` int

`IntlChar::PROPERTY_HEX_DIGIT` int

`IntlChar::PROPERTY_HYPHEN` int

`IntlChar::PROPERTY_ID_CONTINUE` int

`IntlChar::PROPERTY_ID_START` int

`IntlChar::PROPERTY_IDEOGRAPHIC` int

`IntlChar::PROPERTY_IDS_BINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_TRINARY_OPERATOR` int

`IntlChar::PROPERTY_JOIN_CONTROL` int

`IntlChar::PROPERTY_LOGICAL_ORDER_EXCEPTION` int

`IntlChar::PROPERTY_LOWERCASE` int

`IntlChar::PROPERTY_MATH` int

`IntlChar::PROPERTY_NONCHARACTER_CODE_POINT` int

`IntlChar::PROPERTY_QUOTATION_MARK` int

`IntlChar::PROPERTY_RADICAL` int

`IntlChar::PROPERTY_SOFT_DOTTED` int

`IntlChar::PROPERTY_TERMINAL_PUNCTUATION` int

`IntlChar::PROPERTY_UNIFIED_IDEOGRAPH` int

`IntlChar::PROPERTY_UPPERCASE` int

`IntlChar::PROPERTY_WHITE_SPACE` int

`IntlChar::PROPERTY_XID_CONTINUE` int

`IntlChar::PROPERTY_XID_START` int

`IntlChar::PROPERTY_CASE_SENSITIVE` int

`IntlChar::PROPERTY_S_TERM` int

`IntlChar::PROPERTY_VARIATION_SELECTOR` int

`IntlChar::PROPERTY_NFD_INERT` int

`IntlChar::PROPERTY_NFKD_INERT` int

`IntlChar::PROPERTY_NFC_INERT` int

`IntlChar::PROPERTY_NFKC_INERT` int

`IntlChar::PROPERTY_SEGMENT_STARTER` int

`IntlChar::PROPERTY_PATTERN_SYNTAX` int

`IntlChar::PROPERTY_PATTERN_WHITE_SPACE` int

`IntlChar::PROPERTY_POSIX_ALNUM` int

`IntlChar::PROPERTY_POSIX_BLANK` int

`IntlChar::PROPERTY_POSIX_GRAPH` int

`IntlChar::PROPERTY_POSIX_PRINT` int

`IntlChar::PROPERTY_POSIX_XDIGIT` int

`IntlChar::PROPERTY_CASED` int

`IntlChar::PROPERTY_CASE_IGNORABLE` int

`IntlChar::PROPERTY_CHANGES_WHEN_LOWERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_UPPERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_TITLECASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEFOLDED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEMAPPED` int

`IntlChar::PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED` int

`IntlChar::PROPERTY_BINARY_LIMIT` int

`IntlChar::PROPERTY_BIDI_CLASS` int

`IntlChar::PROPERTY_INT_START` int

`IntlChar::PROPERTY_BLOCK` int

`IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_DECOMPOSITION_TYPE` int

`IntlChar::PROPERTY_EAST_ASIAN_WIDTH` int

`IntlChar::PROPERTY_GENERAL_CATEGORY` int

`IntlChar::PROPERTY_JOINING_GROUP` int

`IntlChar::PROPERTY_JOINING_TYPE` int

`IntlChar::PROPERTY_LINE_BREAK` int

`IntlChar::PROPERTY_NUMERIC_TYPE` int

`IntlChar::PROPERTY_SCRIPT` int

`IntlChar::PROPERTY_HANGUL_SYLLABLE_TYPE` int

`IntlChar::PROPERTY_NFD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFC_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKC_QUICK_CHECK` int

`IntlChar::PROPERTY_LEAD_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_GRAPHEME_CLUSTER_BREAK` int

`IntlChar::PROPERTY_SENTENCE_BREAK` int

`IntlChar::PROPERTY_WORD_BREAK` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE` int

`IntlChar::PROPERTY_INT_LIMIT` int

`IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` int

`IntlChar::PROPERTY_MASK_START` int

`IntlChar::PROPERTY_MASK_LIMIT` int

`IntlChar::PROPERTY_NUMERIC_VALUE` int

`IntlChar::PROPERTY_DOUBLE_START` int

`IntlChar::PROPERTY_DOUBLE_LIMIT` int

`IntlChar::PROPERTY_AGE` int

`IntlChar::PROPERTY_STRING_START` int

`IntlChar::PROPERTY_BIDI_MIRRORING_GLYPH` int

`IntlChar::PROPERTY_CASE_FOLDING` int

`IntlChar::PROPERTY_ISO_COMMENT` int

`IntlChar::PROPERTY_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_NAME` int

`IntlChar::PROPERTY_SIMPLE_CASE_FOLDING` int

`IntlChar::PROPERTY_SIMPLE_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_UNICODE_1_NAME` int

`IntlChar::PROPERTY_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET` int

`IntlChar::PROPERTY_STRING_LIMIT` int

`IntlChar::PROPERTY_SCRIPT_EXTENSIONS` int

`IntlChar::PROPERTY_OTHER_PROPERTY_START` int

`IntlChar::PROPERTY_OTHER_PROPERTY_LIMIT` int

`IntlChar::PROPERTY_INVALID_CODE` int

`IntlChar::CHAR_CATEGORY_UNASSIGNED` int

`IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES` int

`IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_TITLECASE_LETTER` int

`IntlChar::CHAR_CATEGORY_MODIFIER_LETTER` int

`IntlChar::CHAR_CATEGORY_OTHER_LETTER` int

`IntlChar::CHAR_CATEGORY_NON_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_ENCLOSING_MARK` int

`IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER` int

`IntlChar::CHAR_CATEGORY_LETTER_NUMBER` int

`IntlChar::CHAR_CATEGORY_OTHER_NUMBER` int

`IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_CONTROL_CHAR` int

`IntlChar::CHAR_CATEGORY_FORMAT_CHAR` int

`IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR` int

`IntlChar::CHAR_CATEGORY_SURROGATE` int

`IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_START_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_END_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_MATH_SYMBOL` int

`IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL` int

`IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_OTHER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR` int

`IntlChar::CHAR_DIRECTION_ARABIC_NUMBER` int

`IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT` int

`IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK` int

`IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE` int

`IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT` int

`IntlChar::BLOCK_CODE_NO_BLOCK` int

`IntlChar::BLOCK_CODE_BASIC_LATIN` int

`IntlChar::BLOCK_CODE_LATIN_1_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_A` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IPA_EXTENSIONS` int

`IntlChar::BLOCK_CODE_SPACING_MODIFIER_LETTERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS` int

`IntlChar::BLOCK_CODE_GREEK` int

`IntlChar::BLOCK_CODE_CYRILLIC` int

`IntlChar::BLOCK_CODE_ARMENIAN` int

`IntlChar::BLOCK_CODE_HEBREW` int

`IntlChar::BLOCK_CODE_ARABIC` int

`IntlChar::BLOCK_CODE_SYRIAC` int

`IntlChar::BLOCK_CODE_THAANA` int

`IntlChar::BLOCK_CODE_DEVANAGARI` int

`IntlChar::BLOCK_CODE_BENGALI` int

`IntlChar::BLOCK_CODE_GURMUKHI` int

`IntlChar::BLOCK_CODE_GUJARATI` int

`IntlChar::BLOCK_CODE_ORIYA` int

`IntlChar::BLOCK_CODE_TAMIL` int

`IntlChar::BLOCK_CODE_TELUGU` int

`IntlChar::BLOCK_CODE_KANNADA` int

`IntlChar::BLOCK_CODE_MALAYALAM` int

`IntlChar::BLOCK_CODE_SINHALA` int

`IntlChar::BLOCK_CODE_THAI` int

`IntlChar::BLOCK_CODE_LAO` int

`IntlChar::BLOCK_CODE_TIBETAN` int

`IntlChar::BLOCK_CODE_MYANMAR` int

`IntlChar::BLOCK_CODE_GEORGIAN` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO` int

`IntlChar::BLOCK_CODE_ETHIOPIC` int

`IntlChar::BLOCK_CODE_CHEROKEE` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS` int

`IntlChar::BLOCK_CODE_OGHAM` int

`IntlChar::BLOCK_CODE_RUNIC` int

`IntlChar::BLOCK_CODE_KHMER` int

`IntlChar::BLOCK_CODE_MONGOLIAN` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL` int

`IntlChar::BLOCK_CODE_GREEK_EXTENDED` int

`IntlChar::BLOCK_CODE_GENERAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS` int

`IntlChar::BLOCK_CODE_CURRENCY_SYMBOLS` int

`IntlChar::BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS` int

`IntlChar::BLOCK_CODE_LETTERLIKE_SYMBOLS` int

`IntlChar::BLOCK_CODE_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_ARROWS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_TECHNICAL` int

`IntlChar::BLOCK_CODE_CONTROL_PICTURES` int

`IntlChar::BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERICS` int

`IntlChar::BLOCK_CODE_BOX_DRAWING` int

`IntlChar::BLOCK_CODE_BLOCK_ELEMENTS` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS` int

`IntlChar::BLOCK_CODE_DINGBATS` int

`IntlChar::BLOCK_CODE_BRAILLE_PATTERNS` int

`IntlChar::BLOCK_CODE_CJK_RADICALS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANGXI_RADICALS` int

`IntlChar::BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS` int

`IntlChar::BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_HIRAGANA` int

`IntlChar::BLOCK_CODE_KATAKANA` int

`IntlChar::BLOCK_CODE_BOPOMOFO` int

`IntlChar::BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO` int

`IntlChar::BLOCK_CODE_KANBUN` int

`IntlChar::BLOCK_CODE_BOPOMOFO_EXTENDED` int

`IntlChar::BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_YI_SYLLABLES` int

`IntlChar::BLOCK_CODE_YI_RADICALS` int

`IntlChar::BLOCK_CODE_HANGUL_SYLLABLES` int

`IntlChar::BLOCK_CODE_HIGH_SURROGATES` int

`IntlChar::BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES` int

`IntlChar::BLOCK_CODE_LOW_SURROGATES` int

`IntlChar::BLOCK_CODE_PRIVATE_USE_AREA` int

`IntlChar::BLOCK_CODE_PRIVATE_USE` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A` int

`IntlChar::BLOCK_CODE_COMBINING_HALF_MARKS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_FORMS` int

`IntlChar::BLOCK_CODE_SMALL_FORM_VARIANTS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B` int

`IntlChar::BLOCK_CODE_SPECIALS` int

`IntlChar::BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS` int

`IntlChar::BLOCK_CODE_OLD_ITALIC` int

`IntlChar::BLOCK_CODE_GOTHIC` int

`IntlChar::BLOCK_CODE_DESERET` int

`IntlChar::BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_MUSICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_TAGS` int

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENTARY` int

`IntlChar::BLOCK_CODE_TAGALOG` int

`IntlChar::BLOCK_CODE_HANUNOO` int

`IntlChar::BLOCK_CODE_BUHID` int

`IntlChar::BLOCK_CODE_TAGBANWA` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_B` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS` int

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B` int

`IntlChar::BLOCK_CODE_LIMBU` int

`IntlChar::BLOCK_CODE_TAI_LE` int

`IntlChar::BLOCK_CODE_KHMER_SYMBOLS` int

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS` int

`IntlChar::BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS` int

`IntlChar::BLOCK_CODE_LINEAR_B_SYLLABARY` int

`IntlChar::BLOCK_CODE_LINEAR_B_IDEOGRAMS` int

`IntlChar::BLOCK_CODE_AEGEAN_NUMBERS` int

`IntlChar::BLOCK_CODE_UGARITIC` int

`IntlChar::BLOCK_CODE_SHAVIAN` int

`IntlChar::BLOCK_CODE_OSMANYA` int

`IntlChar::BLOCK_CODE_CYPRIOT_SYLLABARY` int

`IntlChar::BLOCK_CODE_TAI_XUAN_JING_SYMBOLS` int

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION` int

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_NUMBERS` int

`IntlChar::BLOCK_CODE_ARABIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_BUGINESE` int

`IntlChar::BLOCK_CODE_CJK_STROKES` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_COPTIC` int

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED` int

`IntlChar::BLOCK_CODE_ETHIOPIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_GEORGIAN_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_GLAGOLITIC` int

`IntlChar::BLOCK_CODE_KHAROSHTHI` int

`IntlChar::BLOCK_CODE_MODIFIER_TONE_LETTERS` int

`IntlChar::BLOCK_CODE_NEW_TAI_LUE` int

`IntlChar::BLOCK_CODE_OLD_PERSIAN` int

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SYLOTI_NAGRI` int

`IntlChar::BLOCK_CODE_TIFINAGH` int

`IntlChar::BLOCK_CODE_VERTICAL_FORMS` int

`IntlChar::BLOCK_CODE_NKO` int

`IntlChar::BLOCK_CODE_BALINESE` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_C` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_D` int

`IntlChar::BLOCK_CODE_PHAGS_PA` int

`IntlChar::BLOCK_CODE_PHOENICIAN` int

`IntlChar::BLOCK_CODE_CUNEIFORM` int

`IntlChar::BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_COUNTING_ROD_NUMERALS` int

`IntlChar::BLOCK_CODE_SUNDANESE` int

`IntlChar::BLOCK_CODE_LEPCHA` int

`IntlChar::BLOCK_CODE_OL_CHIKI` int

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_VAI` int

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_B` int

`IntlChar::BLOCK_CODE_SAURASHTRA` int

`IntlChar::BLOCK_CODE_KAYAH_LI` int

`IntlChar::BLOCK_CODE_REJANG` int

`IntlChar::BLOCK_CODE_CHAM` int

`IntlChar::BLOCK_CODE_ANCIENT_SYMBOLS` int

`IntlChar::BLOCK_CODE_PHAISTOS_DISC` int

`IntlChar::BLOCK_CODE_LYCIAN` int

`IntlChar::BLOCK_CODE_CARIAN` int

`IntlChar::BLOCK_CODE_LYDIAN` int

`IntlChar::BLOCK_CODE_MAHJONG_TILES` int

`IntlChar::BLOCK_CODE_DOMINO_TILES` int

`IntlChar::BLOCK_CODE_SAMARITAN` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED` int

`IntlChar::BLOCK_CODE_TAI_THAM` int

`IntlChar::BLOCK_CODE_VEDIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_LISU` int

`IntlChar::BLOCK_CODE_BAMUM` int

`IntlChar::BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_DEVANAGARI_EXTENDED` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_A` int

`IntlChar::BLOCK_CODE_JAVANESE` int

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_A` int

`IntlChar::BLOCK_CODE_TAI_VIET` int

`IntlChar::BLOCK_CODE_MEETEI_MAYEK` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IMPERIAL_ARAMAIC` int

`IntlChar::BLOCK_CODE_OLD_SOUTH_ARABIAN` int

`IntlChar::BLOCK_CODE_AVESTAN` int

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PARTHIAN` int

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PAHLAVI` int

`IntlChar::BLOCK_CODE_OLD_TURKIC` int

`IntlChar::BLOCK_CODE_RUMI_NUMERAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_KAITHI` int

`IntlChar::BLOCK_CODE_EGYPTIAN_HIEROGLYPHS` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C` int

`IntlChar::BLOCK_CODE_MANDAIC` int

`IntlChar::BLOCK_CODE_BATAK` int

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_BRAHMI` int

`IntlChar::BLOCK_CODE_BAMUM_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANA_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_PLAYING_CARDS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS` int

`IntlChar::BLOCK_CODE_EMOTICONS` int

`IntlChar::BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS` int

`IntlChar::BLOCK_CODE_ALCHEMICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D` int

`IntlChar::BLOCK_CODE_ARABIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS` int

`IntlChar::BLOCK_CODE_CHAKMA` int

`IntlChar::BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS` int

`IntlChar::BLOCK_CODE_MEROITIC_CURSIVE` int

`IntlChar::BLOCK_CODE_MEROITIC_HIEROGLYPHS` int

`IntlChar::BLOCK_CODE_MIAO` int

`IntlChar::BLOCK_CODE_SHARADA` int

`IntlChar::BLOCK_CODE_SORA_SOMPENG` int

`IntlChar::BLOCK_CODE_SUNDANESE_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_TAKRI` int

`IntlChar::BLOCK_CODE_BASSA_VAH` int

`IntlChar::BLOCK_CODE_CAUCASIAN_ALBANIAN` int

`IntlChar::BLOCK_CODE_COPTIC_EPACT_NUMBERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED` int

`IntlChar::BLOCK_CODE_DUPLOYAN` int

`IntlChar::BLOCK_CODE_ELBASAN` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED` int

`IntlChar::BLOCK_CODE_GRANTHA` int

`IntlChar::BLOCK_CODE_KHOJKI` int

`IntlChar::BLOCK_CODE_KHUDAWADI` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_E` int

`IntlChar::BLOCK_CODE_LINEAR_A` int

`IntlChar::BLOCK_CODE_MAHAJANI` int

`IntlChar::BLOCK_CODE_MANICHAEAN` int

`IntlChar::BLOCK_CODE_MENDE_KIKAKUI` int

`IntlChar::BLOCK_CODE_MODI` int

`IntlChar::BLOCK_CODE_MRO` int

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_B` int

`IntlChar::BLOCK_CODE_NABATAEAN` int

`IntlChar::BLOCK_CODE_OLD_NORTH_ARABIAN` int

`IntlChar::BLOCK_CODE_OLD_PERMIC` int

`IntlChar::BLOCK_CODE_ORNAMENTAL_DINGBATS` int

`IntlChar::BLOCK_CODE_PAHAWH_HMONG` int

`IntlChar::BLOCK_CODE_PALMYRENE` int

`IntlChar::BLOCK_CODE_PAU_CIN_HAU` int

`IntlChar::BLOCK_CODE_PSALTER_PAHLAVI` int

`IntlChar::BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS` int

`IntlChar::BLOCK_CODE_SIDDHAM` int

`IntlChar::BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_C` int

`IntlChar::BLOCK_CODE_TIRHUTA` int

`IntlChar::BLOCK_CODE_WARANG_CITI` int

`IntlChar::BLOCK_CODE_COUNT` int

`IntlChar::BLOCK_CODE_INVALID_CODE` int

`IntlChar::BPT_NONE` int

`IntlChar::BPT_OPEN` int

`IntlChar::BPT_CLOSE` int

`IntlChar::BPT_COUNT` int

`IntlChar::EA_NEUTRAL` int

`IntlChar::EA_AMBIGUOUS` int

`IntlChar::EA_HALFWIDTH` int

`IntlChar::EA_FULLWIDTH` int

`IntlChar::EA_NARROW` int

`IntlChar::EA_WIDE` int

`IntlChar::EA_COUNT` int

`IntlChar::UNICODE_CHAR_NAME` int

`IntlChar::UNICODE_10_CHAR_NAME` int

`IntlChar::EXTENDED_CHAR_NAME` int

`IntlChar::CHAR_NAME_ALIAS` int

`IntlChar::CHAR_NAME_CHOICE_COUNT` int

`IntlChar::SHORT_PROPERTY_NAME` int

`IntlChar::LONG_PROPERTY_NAME` int

`IntlChar::PROPERTY_NAME_CHOICE_COUNT` int

`IntlChar::DT_NONE` int

`IntlChar::DT_CANONICAL` int

`IntlChar::DT_COMPAT` int

`IntlChar::DT_CIRCLE` int

`IntlChar::DT_FINAL` int

`IntlChar::DT_FONT` int

`IntlChar::DT_FRACTION` int

`IntlChar::DT_INITIAL` int

`IntlChar::DT_ISOLATED` int

`IntlChar::DT_MEDIAL` int

`IntlChar::DT_NARROW` int

`IntlChar::DT_NOBREAK` int

`IntlChar::DT_SMALL` int

`IntlChar::DT_SQUARE` int

`IntlChar::DT_SUB` int

`IntlChar::DT_SUPER` int

`IntlChar::DT_VERTICAL` int

`IntlChar::DT_WIDE` int

`IntlChar::DT_COUNT` int

`IntlChar::JT_NON_JOINING` int

`IntlChar::JT_JOIN_CAUSING` int

`IntlChar::JT_DUAL_JOINING` int

`IntlChar::JT_LEFT_JOINING` int

`IntlChar::JT_RIGHT_JOINING` int

`IntlChar::JT_TRANSPARENT` int

`IntlChar::JT_COUNT` int

`IntlChar::JG_NO_JOINING_GROUP` int

`IntlChar::JG_AIN` int

`IntlChar::JG_ALAPH` int

`IntlChar::JG_ALEF` int

`IntlChar::JG_BEH` int

`IntlChar::JG_BETH` int

`IntlChar::JG_DAL` int

`IntlChar::JG_DALATH_RISH` int

`IntlChar::JG_E` int

`IntlChar::JG_FEH` int

`IntlChar::JG_FINAL_SEMKATH` int

`IntlChar::JG_GAF` int

`IntlChar::JG_GAMAL` int

`IntlChar::JG_HAH` int

`IntlChar::JG_TEH_MARBUTA_GOAL` int

`IntlChar::JG_HAMZA_ON_HEH_GOAL` int

`IntlChar::JG_HE` int

`IntlChar::JG_HEH` int

`IntlChar::JG_HEH_GOAL` int

`IntlChar::JG_HETH` int

`IntlChar::JG_KAF` int

`IntlChar::JG_KAPH` int

`IntlChar::JG_KNOTTED_HEH` int

`IntlChar::JG_LAM` int

`IntlChar::JG_LAMADH` int

`IntlChar::JG_MEEM` int

`IntlChar::JG_MIM` int

`IntlChar::JG_NOON` int

`IntlChar::JG_NUN` int

`IntlChar::JG_PE` int

`IntlChar::JG_QAF` int

`IntlChar::JG_QAPH` int

`IntlChar::JG_REH` int

`IntlChar::JG_REVERSED_PE` int

`IntlChar::JG_SAD` int

`IntlChar::JG_SADHE` int

`IntlChar::JG_SEEN` int

`IntlChar::JG_SEMKATH` int

`IntlChar::JG_SHIN` int

`IntlChar::JG_SWASH_KAF` int

`IntlChar::JG_SYRIAC_WAW` int

`IntlChar::JG_TAH` int

`IntlChar::JG_TAW` int

`IntlChar::JG_TEH_MARBUTA` int

`IntlChar::JG_TETH` int

`IntlChar::JG_WAW` int

`IntlChar::JG_YEH` int

`IntlChar::JG_YEH_BARREE` int

`IntlChar::JG_YEH_WITH_TAIL` int

`IntlChar::JG_YUDH` int

`IntlChar::JG_YUDH_HE` int

`IntlChar::JG_ZAIN` int

`IntlChar::JG_FE` int

`IntlChar::JG_KHAPH` int

`IntlChar::JG_ZHAIN` int

`IntlChar::JG_BURUSHASKI_YEH_BARREE` int

`IntlChar::JG_FARSI_YEH` int

`IntlChar::JG_NYA` int

`IntlChar::JG_ROHINGYA_YEH` int

`IntlChar::JG_MANICHAEAN_ALEPH` int

`IntlChar::JG_MANICHAEAN_AYIN` int

`IntlChar::JG_MANICHAEAN_BETH` int

`IntlChar::JG_MANICHAEAN_DALETH` int

`IntlChar::JG_MANICHAEAN_DHAMEDH` int

`IntlChar::JG_MANICHAEAN_FIVE` int

`IntlChar::JG_MANICHAEAN_GIMEL` int

`IntlChar::JG_MANICHAEAN_HETH` int

`IntlChar::JG_MANICHAEAN_HUNDRED` int

`IntlChar::JG_MANICHAEAN_KAPH` int

`IntlChar::JG_MANICHAEAN_LAMEDH` int

`IntlChar::JG_MANICHAEAN_MEM` int

`IntlChar::JG_MANICHAEAN_NUN` int

`IntlChar::JG_MANICHAEAN_ONE` int

`IntlChar::JG_MANICHAEAN_PE` int

`IntlChar::JG_MANICHAEAN_QOPH` int

`IntlChar::JG_MANICHAEAN_RESH` int

`IntlChar::JG_MANICHAEAN_SADHE` int

`IntlChar::JG_MANICHAEAN_SAMEKH` int

`IntlChar::JG_MANICHAEAN_TAW` int

`IntlChar::JG_MANICHAEAN_TEN` int

`IntlChar::JG_MANICHAEAN_TETH` int

`IntlChar::JG_MANICHAEAN_THAMEDH` int

`IntlChar::JG_MANICHAEAN_TWENTY` int

`IntlChar::JG_MANICHAEAN_WAW` int

`IntlChar::JG_MANICHAEAN_YODH` int

`IntlChar::JG_MANICHAEAN_ZAYIN` int

`IntlChar::JG_STRAIGHT_WAW` int

`IntlChar::JG_COUNT` int

`IntlChar::GCB_OTHER` int

`IntlChar::GCB_CONTROL` int

`IntlChar::GCB_CR` int

`IntlChar::GCB_EXTEND` int

`IntlChar::GCB_L` int

`IntlChar::GCB_LF` int

`IntlChar::GCB_LV` int

`IntlChar::GCB_LVT` int

`IntlChar::GCB_T` int

`IntlChar::GCB_V` int

`IntlChar::GCB_SPACING_MARK` int

`IntlChar::GCB_PREPEND` int

`IntlChar::GCB_REGIONAL_INDICATOR` int

`IntlChar::GCB_COUNT` int

`IntlChar::WB_OTHER` int

`IntlChar::WB_ALETTER` int

`IntlChar::WB_FORMAT` int

`IntlChar::WB_KATAKANA` int

`IntlChar::WB_MIDLETTER` int

`IntlChar::WB_MIDNUM` int

`IntlChar::WB_NUMERIC` int

`IntlChar::WB_EXTENDNUMLET` int

`IntlChar::WB_CR` int

`IntlChar::WB_EXTEND` int

`IntlChar::WB_LF` int

`IntlChar::WB_MIDNUMLET` int

`IntlChar::WB_NEWLINE` int

`IntlChar::WB_REGIONAL_INDICATOR` int

`IntlChar::WB_HEBREW_LETTER` int

`IntlChar::WB_SINGLE_QUOTE` int

`IntlChar::WB_DOUBLE_QUOTE` int

`IntlChar::WB_COUNT` int

`IntlChar::SB_OTHER` int

`IntlChar::SB_ATERM` int

`IntlChar::SB_CLOSE` int

`IntlChar::SB_FORMAT` int

`IntlChar::SB_LOWER` int

`IntlChar::SB_NUMERIC` int

`IntlChar::SB_OLETTER` int

`IntlChar::SB_SEP` int

`IntlChar::SB_SP` int

`IntlChar::SB_STERM` int

`IntlChar::SB_UPPER` int

`IntlChar::SB_CR` int

`IntlChar::SB_EXTEND` int

`IntlChar::SB_LF` int

`IntlChar::SB_SCONTINUE` int

`IntlChar::SB_COUNT` int

`IntlChar::LB_UNKNOWN` int

`IntlChar::LB_AMBIGUOUS` int

`IntlChar::LB_ALPHABETIC` int

`IntlChar::LB_BREAK_BOTH` int

`IntlChar::LB_BREAK_AFTER` int

`IntlChar::LB_BREAK_BEFORE` int

`IntlChar::LB_MANDATORY_BREAK` int

`IntlChar::LB_CONTINGENT_BREAK` int

`IntlChar::LB_CLOSE_PUNCTUATION` int

`IntlChar::LB_COMBINING_MARK` int

`IntlChar::LB_CARRIAGE_RETURN` int

`IntlChar::LB_EXCLAMATION` int

`IntlChar::LB_GLUE` int

`IntlChar::LB_HYPHEN` int

`IntlChar::LB_IDEOGRAPHIC` int

`IntlChar::LB_INSEPARABLE` int

`IntlChar::LB_INSEPERABLE` int

`IntlChar::LB_INFIX_NUMERIC` int

`IntlChar::LB_LINE_FEED` int

`IntlChar::LB_NONSTARTER` int

`IntlChar::LB_NUMERIC` int

`IntlChar::LB_OPEN_PUNCTUATION` int

`IntlChar::LB_POSTFIX_NUMERIC` int

`IntlChar::LB_PREFIX_NUMERIC` int

`IntlChar::LB_QUOTATION` int

`IntlChar::LB_COMPLEX_CONTEXT` int

`IntlChar::LB_SURROGATE` int

`IntlChar::LB_SPACE` int

`IntlChar::LB_BREAK_SYMBOLS` int

`IntlChar::LB_ZWSPACE` int

`IntlChar::LB_NEXT_LINE` int

`IntlChar::LB_WORD_JOINER` int

`IntlChar::LB_H2` int

`IntlChar::LB_H3` int

`IntlChar::LB_JL` int

`IntlChar::LB_JT` int

`IntlChar::LB_JV` int

`IntlChar::LB_CLOSE_PARENTHESIS` int

`IntlChar::LB_CONDITIONAL_JAPANESE_STARTER` int

`IntlChar::LB_HEBREW_LETTER` int

`IntlChar::LB_REGIONAL_INDICATOR` int

`IntlChar::LB_COUNT` int

`IntlChar::NT_NONE` int

`IntlChar::NT_DECIMAL` int

`IntlChar::NT_DIGIT` int

`IntlChar::NT_NUMERIC` int

`IntlChar::NT_COUNT` int

`IntlChar::HST_NOT_APPLICABLE` int

`IntlChar::HST_LEADING_JAMO` int

`IntlChar::HST_VOWEL_JAMO` int

`IntlChar::HST_TRAILING_JAMO` int

`IntlChar::HST_LV_SYLLABLE` int

`IntlChar::HST_LVT_SYLLABLE` int

`IntlChar::HST_COUNT` int

`IntlChar::FOLD_CASE_DEFAULT` int

`IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I` int

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Klassenkonstanten sind nun typisiert.
7.0.6 | Die Konstante `IntlChar::NO_NUMERIC_VALUE` wurde hinzugefügt.

# IntlChar::charAge

(PHP 7, PHP 8)

IntlChar::charAge — Get the "age" of the code point

### Beschreibung

public static function IntlChar::charAge(int|string `$codepoint`): ?array

Gets the "age" of the code point.

The "age" is the Unicode version when the code point was first designated (as a non-character or for Private Use) or assigned a character. This can be useful to avoid emitting code points to receiving processes that do not accept newer characters.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

The Unicode version number, as an array. For example, version 1.3.31.2 would be represented as `[1, 3, 31, 2]`. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::charage("\u{2603}"));
    var_dump(IntlChar::charage("\u{1F576}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      [0]=>
      int(1)
      [1]=>
      int(1)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }
    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Siehe auch

- IntlChar::getUnicodeVersion() - Get the Unicode version
- IntlChar::getIntPropertyMinValue() - Get the min value for a Unicode property
- IntlChar::getIntPropertyValue() - Get the value for a Unicode property for a code point

# IntlChar::charDigitValue

(PHP 7, PHP 8)

IntlChar::charDigitValue — Get the decimal digit value of a decimal digit character

### Beschreibung

public static function IntlChar::charDigitValue(int|string `$codepoint`): ?int

Returns the decimal digit value of a decimal digit character.

Such characters have the general category "Nd" (decimal digit numbers) and a Numeric_Type of Decimal.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

The decimal digit value of `codepoint`, or `-1` if it is not a decimal digit character. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::charDigitValue("1"));
    var_dump(IntlChar::charDigitValue("\u{0662}"));
    var_dump(IntlChar::charDigitValue("\u{0E53}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)
    int(2)
    int(3)

### Siehe auch

- IntlChar::getNumericValue() - Get the numeric value for a Unicode code point

# IntlChar::charDirection

(PHP 7, PHP 8)

IntlChar::charDirection — Get bidirectional category value for a code point

### Beschreibung

public static function IntlChar::charDirection(int|string `$codepoint`): ?int

Returns the bidirectional category value for the code point, which is used in the » Unicode bidirectional algorithm (UAX #9).

> Hinweis:

> Some unassigned code points have bidi values of R or AL because they are in blocks that are reserved for Right-To-Left scripts.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

The bidirectional category value; one of the following constants:

- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR`
- `IntlChar::CHAR_DIRECTION_ARABIC_NUMBER`
- `IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR`
- `IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT`
- `IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK`
- `IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL`
- `IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE`
- `IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE`
- `IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE`
- `IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT`

Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::charDirection("A") === IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT);
    var_dump(IntlChar::charDirection("\u{05E9}") === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::charDirection("+") === IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR);
    var_dump(IntlChar::charDirection(".") === IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::charFromName

(PHP 7, PHP 8)

IntlChar::charFromName — Find Unicode character by name and return its code point value

### Beschreibung

public static function IntlChar::charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int

Finds a Unicode character by its name and returns its code point value.

The name is matched exactly and completely. If the name does not correspond to a code point, `null` is returned.

A Unicode 1.0 name is matched only if it differs from the modern name. Unicode names are all uppercase. Extended names are lowercase followed by an uppercase hexadecimal number, and within angle brackets.

### Parameter-Liste

`name`

  Full name of the Unicode character.

`type`

  Which set of names to use for the lookup. Can be any of these constants:

  - `IntlChar::UNICODE_CHAR_NAME` (default)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Rückgabewerte

The Unicode value of the code point with the given name (as an int), or `null` if there is no such code point.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::charFromName("LATIN CAPITAL LETTER A"));
    var_dump(IntlChar::charFromName("SNOWMAN"));
    var_dump(IntlChar::charFromName("RECYCLING SYMBOL FOR TYPE-1 PLASTICS"));
    var_dump(IntlChar::charFromName("A RANDOM STRING WHICH DOESN'T CORRESPOND TO ANY UNICODE CHARACTER"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(65)
    int(9731)
    int(9843)
    NULL

### Siehe auch

- IntlChar::charName() - Retrieve the name of a Unicode character
- IntlChar::enumCharNames() - Enumerate all assigned Unicode characters within a range

# IntlChar::charMirror

(PHP 7, PHP 8)

IntlChar::charMirror — Get the "mirror-image" character for a code point

### Beschreibung

public static function IntlChar::charMirror(int|string `$codepoint`): int|string|null

Maps the specified character to a "mirror-image" character.

For characters with the Bidi_Mirrored property, implementations sometimes need a "poor man's" mapping to another Unicode character (code point) such that the default glyph may serve as the mirror-image of the default glyph of the specified character. This is useful for text conversion to and from codepages with visual order, and for displays without glyph selection capabilities.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns another Unicode code point that may serve as a mirror-image substitute, or `codepoint` itself if there is no such mapping or `codepoint` does not have the Bidi_Mirrored property.

Der Rückgabetyp ist int, außer der Codepoint wurde als UTF-8-String übergeben, in welchem Fall ein String zurückgegeben wird. Bei einem Fehler wird `null` zurückgegeben.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::charMirror("A"));
    var_dump(IntlChar::charMirror("<"));
    var_dump(IntlChar::charMirror("("));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "A"
    string(1) ">"
    string(2) ")"

### Siehe auch

- IntlChar::isMirrored() - Check if code point has the Bidi_Mirrored property
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::charName

(PHP 7, PHP 8)

IntlChar::charName — Retrieve the name of a Unicode character

### Beschreibung

public static function IntlChar::charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string

Retrieves the name of a Unicode character.

Depending on `type`, the resulting character name is the "modern" name or the name that was defined in Unicode version 1.0. The name contains only "invariant" characters like A-Z, 0-9, space, and '-'. Unicode 1.0 names are only retrieved if they are different from the modern names and if ICU contains the data for them.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

`type`

  Which set of names to use for the lookup. Can be any of these constants:

  - `IntlChar::UNICODE_CHAR_NAME` (default)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Rückgabewerte

The corresponding name, or an empty string if there is no name for this character, or `null` if there is no such code point.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::charName("."));
    var_dump(IntlChar::charName(".", IntlChar::UNICODE_CHAR_NAME));
    var_dump(IntlChar::charName("\u{2603}"));
    var_dump(IntlChar::charName("\u{0000}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(9) "FULL STOP"
    string(9) "FULL STOP"
    string(7) "SNOWMAN"
    string(0) ""

### Siehe auch

- IntlChar::charFromName() - Find Unicode character by name and return its code point value
- IntlChar::enumCharNames() - Enumerate all assigned Unicode characters within a range

# IntlChar::charType

(PHP 7, PHP 8)

IntlChar::charType — Get the general category value for a code point

### Beschreibung

public static function IntlChar::charType(int|string `$codepoint`): ?int

Returns the general category value for the code point.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns the general category type, which may be one of the following constants:

- `IntlChar::CHAR_CATEGORY_UNASSIGNED`
- `IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES`
- `IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER`
- `IntlChar::CHAR_CATEGORY_TITLECASE_LETTER`
- `IntlChar::CHAR_CATEGORY_MODIFIER_LETTER`
- `IntlChar::CHAR_CATEGORY_OTHER_LETTER`
- `IntlChar::CHAR_CATEGORY_NON_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_ENCLOSING_MARK`
- `IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK`
- `IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER`
- `IntlChar::CHAR_CATEGORY_LETTER_NUMBER`
- `IntlChar::CHAR_CATEGORY_OTHER_NUMBER`
- `IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR`
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR`
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR`
- `IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR`
- `IntlChar::CHAR_CATEGORY_SURROGATE`
- `IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_START_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_END_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_MATH_SYMBOL`
- `IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL`
- `IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_OTHER_SYMBOL`
- `IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION`
- `IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT`

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::charType("A") === IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER);
    var_dump(IntlChar::charType(".") === IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION);
    var_dump(IntlChar::charType("\t") === IntlChar::CHAR_CATEGORY_CONTROL_CHAR);
    var_dump(IntlChar::charType("\u{2603}") === IntlChar::CHAR_CATEGORY_OTHER_SYMBOL);
    var_dump(IntlChar::charType("multiple chars") === null);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::chr

(PHP 7, PHP 8)

IntlChar::chr — Return Unicode character by code point value

### Beschreibung

public static function IntlChar::chr(int|string `$codepoint`): ?string

Returns a string containing the character specified by the Unicode code point value.

This method complements IntlChar::ord().

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

A string containing the single character specified by the Unicode code point value, or `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    $values = ["A", 63, 123, 9731];
    foreach ($values as $value) {
        var_dump(IntlChar::chr($value));
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "A"
    string(1) "?"
    string(1) "{"
    string(3) "☃"

### Siehe auch

- IntlChar::ord() - Return Unicode code point value of character
- mb_chr() - Return character by Unicode code point value
- chr() - Erzeugt eine Ein-Byte-Zeichenkette aus einer Zahl

# IntlChar::digit

(PHP 7, PHP 8)

IntlChar::digit — Get the decimal digit value of a code point for a given radix

### Beschreibung

public static function IntlChar::digit(int|string `$codepoint`, int `$base` = 10): int|false|null

Returns the decimal digit value of the code point in the specified radix.

If the radix is not in the range `2 <= radix <= 36` or if the value of `codepoint` is not a valid digit in the specified radix, `false` is returned. A character is a valid digit if at least one of the following is true:

- The character has a decimal digit value. Such characters have the general category "Nd" (decimal digit numbers) and a Numeric_Type of "Decimal". In this case the value is the character's decimal digit value.
- The character is one of the uppercase Latin letters `'A'` through `'Z'`. In this case the value is `codepoint - 'A' + 10`.
- The character is one of the lowercase Latin letters `'a'` through `'z'`. In this case the value is `codepoint - 'a' + 10`.
- Latin letters from both the ASCII range (`0061..007A`, `0041..005A`) as well as from the Fullwidth ASCII range (`FF41..FF5A`, `FF21..FF3A`) are recognized.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

`base`

  The radix (defaults to `10`).

### Rückgabewerte

Returns the numeric value represented by the character in the specified radix, or `false` if there is no value or if the value exceeds the radix. Returns `null` on failure.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php

    var_dump(IntlChar::digit("0"));
    var_dump(IntlChar::digit("3"));

    var_dump(IntlChar::digit("A", 16));
    var_dump(IntlChar::digit("A"));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    int(3)
    int(10)
    bool(false)

### Siehe auch

- IntlChar::forDigit() - Get character representation for a given digit and radix
- IntlChar::charDigitValue() - Get the decimal digit value of a decimal digit character
- IntlChar::isdigit() - Check if code point is a digit character
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::enumCharNames

(PHP 7, PHP 8)

IntlChar::enumCharNames — Enumerate all assigned Unicode characters within a range

### Beschreibung

public static function IntlChar::enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool

Enumerate all assigned Unicode characters between the start and limit code points (start inclusive, limit exclusive) and call a function for each, passing the code point value and the character name.

For Unicode 1.0 names, only those are enumerated that differ from the modern names.

### Parameter-Liste

`start`

  The first code point in the enumeration range.

`end`

  One more than the last code point in the enumeration range (the first one after the range).

`callback`

  The function that is to be called for each character name. The following three arguments will be passed into it:

  - int `$codepoint` - The numeric code point value
  - int `$nameChoice` - The same value as the `type` parameter below
  - string `$name` - The name of the character
`type`

  Selector for which kind of names to enumerate. Can be any of these constants:

  - `IntlChar::UNICODE_CHAR_NAME` (default)
  - `IntlChar::UNICODE_10_CHAR_NAME`
  - `IntlChar::EXTENDED_CHAR_NAME`
  - `IntlChar::CHAR_NAME_ALIAS`
  - `IntlChar::CHAR_NAME_CHOICE_COUNT`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | This method now returns `false` on failure; previously it returns `null`.

### Beispiele

Beispiel #1 Enumerating over a sample range of code points

    <?php
    IntlChar::enumCharNames(0x2600, 0x2610, function($codepoint, $nameChoice, $name) {
        printf("U+%04x %s\n", $codepoint, $name);
    });
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    U+2600 BLACK SUN WITH RAYS
    U+2601 CLOUD
    U+2602 UMBRELLA
    U+2603 SNOWMAN
    U+2604 COMET
    U+2605 BLACK STAR
    U+2606 WHITE STAR
    U+2607 LIGHTNING
    U+2608 THUNDERSTORM
    U+2609 SUN
    U+260a ASCENDING NODE
    U+260b DESCENDING NODE
    U+260c CONJUNCTION
    U+260d OPPOSITION
    U+260e BLACK TELEPHONE
    U+260f WHITE TELEPHONE

### Siehe auch

- IntlChar::charName() - Retrieve the name of a Unicode character
- IntlChar::charFromName() - Find Unicode character by name and return its code point value

# IntlChar::enumCharTypes

(PHP 7, PHP 8)

IntlChar::enumCharTypes — Enumerate all code points with their Unicode general categories

### Beschreibung

public static function IntlChar::enumCharTypes(callable `$callback`): void

Enumerates efficiently all code points with their Unicode general categories. This is useful for building data structures, for enumerating all assigned code points, etc.

For each contiguous range of code points with a given general category ("character type"), the `callback` function is called. Adjacent ranges have different types. The Unicode Standard guarantees that the numeric value of the type is 0..31.

### Parameter-Liste

`callback`

  The function that is to be called for each contiguous range of code points with the same general category. The following three arguments will be passed into it:

  - int `$start` - The starting code point of the range
  - int `$end` - The ending code point of the range
  - int `$name` - The category type (one of the `IntlChar::CHAR_CATEGORY_*` constants)

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 Enumerating over a sample range of code points

    <?php
    IntlChar::enumCharTypes(function($start, $end, $type) {
        printf("U+%04x through U+%04x are in category %d\n", $start, $end, $type);
    });
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    U+0000 through U+0020 are in category 15
    U+0020 through U+0021 are in category 12
    U+0021 through U+0024 are in category 23
    U+0024 through U+0025 are in category 25
    U+0025 through U+0028 are in category 23
    U+0028 through U+0029 are in category 20
    U+0029 through U+002a are in category 21
    U+002a through U+002b are in category 23
    U+002b through U+002c are in category 24
    U+002c through U+002d are in category 23
    U+002d through U+002e are in category 19
    U+002e through U+0030 are in category 23
    U+0030 through U+003a are in category 9
    ...

# IntlChar::foldCase

(PHP 7, PHP 8)

IntlChar::foldCase — Perform case folding on a code point

### Beschreibung

public static function IntlChar::foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null

The given character is mapped to its case folding equivalent; if the character has no case folding equivalent, the character itself is returned.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

`options`

  Either `IntlChar::FOLD_CASE_DEFAULT` (default) or `IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I`.

### Rückgabewerte

Returns the Simple_Case_Folding of the code point, if any; otherwise the code point itself on success, or `null` on failure.

# IntlChar::forDigit

(PHP 7, PHP 8)

IntlChar::forDigit — Get character representation for a given digit and radix

### Beschreibung

public static function IntlChar::forDigit(int `$digit`, int `$base` = 10): int

Determines the character representation for a specific digit in the specified radix.

If the value of radix is not a valid radix, or the value of digit is not a valid digit in the specified radix, the null character (`U+0000`) is returned.

The radix argument is valid if it is greater than or equal to `2` and less than or equal to `36`. The digit argument is valid if `0 <= digit < radix`.

If the digit is less than `10`, then '0' + digit is returned. Otherwise, the value 'a' + digit - 10 is returned.

### Parameter-Liste

`digit`

  The number to convert to a character.

`base`

  The radix (defaults to `10`).

### Rückgabewerte

The character representation (as a int) of the specified digit in the specified radix.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::forDigit(0));
    var_dump(IntlChar::forDigit(3));
    var_dump(IntlChar::forDigit(3, 10));
    var_dump(IntlChar::forDigit(10));
    var_dump(IntlChar::forDigit(10, 16));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(48)
    int(51)
    int(51)
    int(0)
    int(97)

### Siehe auch

- IntlChar::digit() - Get the decimal digit value of a code point for a given radix
- IntlChar::charDigitValue() - Get the decimal digit value of a decimal digit character
- IntlChar::isdigit() - Check if code point is a digit character
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::getBidiPairedBracket

(PHP 7, PHP 8)

IntlChar::getBidiPairedBracket — Get the paired bracket character for a code point

### Beschreibung

public static function IntlChar::getBidiPairedBracket(int|string `$codepoint`): int|string|null

Maps the specified character to its paired bracket character.

For `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE !== IntlChar::BPT_NONE`, this is the same as IntlChar::charMirror(). Otherwise `codepoint` itself is returned.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns the paired bracket code point, or `codepoint` itself if there is no such mapping. Returns `null` on failure.

Der Rückgabetyp ist int, außer der Codepoint wurde als UTF-8-String übergeben, in welchem Fall ein String zurückgegeben wird. Bei einem Fehler wird `null` zurückgegeben.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::getBidiPairedBracket(91));
    var_dump(IntlChar::getBidiPairedBracket('['));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(93)
    string(1) "]"

### Anmerkungen

> Hinweis:

> This method is available as of ICU version 52.

### Siehe auch

- IntlChar::charMirror() - Get the "mirror-image" character for a code point
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET`
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE`

# IntlChar::getBlockCode

(PHP 7, PHP 8)

IntlChar::getBlockCode — Get the Unicode allocation block containing a code point

### Beschreibung

public static function IntlChar::getBlockCode(int|string `$codepoint`): ?int

Returns the Unicode allocation block that contains the character.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns the block value for `codepoint`. See the `IntlChar::BLOCK_CODE_*` constants for possible return values. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::getBlockCode("A") === IntlChar::BLOCK_CODE_BASIC_LATIN);
    var_dump(IntlChar::getBlockCode("Φ") === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getBlockCode("\u{2603}") === IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(true)

# IntlChar::getCombiningClass

(PHP 7, PHP 8)

IntlChar::getCombiningClass — Get the combining class of a code point

### Beschreibung

public static function IntlChar::getCombiningClass(int|string `$codepoint`): ?int

Returns the combining class of the code point.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns the combining class of the character. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::getCombiningClass("A"));
    var_dump(IntlChar::getCombiningClass("\u{0334}"));
    var_dump(IntlChar::getCombiningClass("\u{0358}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    int(1)
    int(232)

# IntlChar::getFC_NFKC_Closure

(PHP 7, PHP 8)

IntlChar::getFC_NFKC_Closure — Get the FC_NFKC_Closure property for a code point

### Beschreibung

public static function IntlChar::getFC_NFKC_Closure(int|string `$codepoint`): string|false|null

Gets the FC_NFKC_Closure property string for a character.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns the FC_NFKC_Closure property string for the `codepoint`, or an empty string if there is none. Returns `null` or `false` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::getFC_NFKC_Closure("\u{2121}"));
    var_dump(IntlChar::getFC_NFKC_Closure("\u{1D2D}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(3) "tel"
    string(2) "æ"

# IntlChar::getIntPropertyMaxValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMaxValue — Get the max value for a Unicode property

### Beschreibung

public static function IntlChar::getIntPropertyMaxValue(int `$property`): int

Gets the maximum value for an enumerated/integer/binary Unicode property.

### Parameter-Liste

`property`

  Die Unicode-Eigenschaft, die gesucht werden soll (siehe die `IntlChar::PROPERTY_*`-Konstanten).

### Rückgabewerte

The maximum value returned by IntlChar::getIntPropertyValue() for a Unicode property. `<=0` if the property selector is out of range.

### Beispiele

Beispiel #1 Testen unterschiedlicher Eigenschaften

    <?php
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMaxValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMaxValue(999999999)); // Some made-up value
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(22)
    int(166)
    int(1)
    int(-1)

### Siehe auch

- IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
- IntlChar::getIntPropertyMinValue() - Get the min value for a Unicode property
- IntlChar::getIntPropertyValue() - Get the value for a Unicode property for a code point
- IntlChar::getUnicodeVersion() - Get the Unicode version

# IntlChar::getIntPropertyMinValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMinValue — Get the min value for a Unicode property

### Beschreibung

public static function IntlChar::getIntPropertyMinValue(int `$property`): int

Gets the minimum value for an enumerated/integer/binary Unicode property.

### Parameter-Liste

`property`

  Die Unicode-Eigenschaft, die gesucht werden soll (siehe die `IntlChar::PROPERTY_*`-Konstanten).

### Rückgabewerte

The minimum value returned by IntlChar::getIntPropertyValue() for a Unicode property. `0` if the property selector is out of range.

### Beispiele

Beispiel #1 Testen unterschiedlicher Eigenschaften

    <?php
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_SCRIPT));
    var_dump(IntlChar::getIntPropertyMinValue(IntlChar::PROPERTY_IDEOGRAPHIC));
    var_dump(IntlChar::getIntPropertyMinValue(999999999)); // Some made-up value
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    int(0)
    int(0)
    int(0)

### Siehe auch

- IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
- IntlChar::getIntPropertyMaxValue() - Get the max value for a Unicode property
- IntlChar::getIntPropertyValue() - Get the value for a Unicode property for a code point
- IntlChar::getUnicodeVersion() - Get the Unicode version

# IntlChar::getIntPropertyValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyValue — Get the value for a Unicode property for a code point

### Beschreibung

public static function IntlChar::getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int

Gets the property value for an enumerated or integer Unicode property for a code point. Also returns binary and mask property values.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

`property`

  Die Unicode-Eigenschaft, die gesucht werden soll (siehe die `IntlChar::PROPERTY_*`-Konstanten).

### Rückgabewerte

Returns the numeric value that is directly the property value or, for enumerated properties, corresponds to the numeric value of the enumerated constant of the respective property value enumeration type. Returns `null` on failure.

Returns `0` or `1` (for `false`/`true`) for binary Unicode properties.

Returns a bit-mask for mask properties.

Returns `0` if `property` is out of bounds or if the Unicode version does not have data for the property at all, or not for this code point.

### Beispiele

Beispiel #1 Testen unterschiedlicher Eigenschaften

    <?php
    var_dump(IntlChar::getIntPropertyValue("A", IntlChar::PROPERTY_ALPHABETIC) === 1);
    var_dump(IntlChar::getIntPropertyValue("[", IntlChar::PROPERTY_BIDI_MIRRORED) === 1);
    var_dump(IntlChar::getIntPropertyValue("Φ", IntlChar::PROPERTY_BLOCK) === IntlChar::BLOCK_CODE_GREEK);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(true)

### Siehe auch

- IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
- IntlChar::getIntPropertyMinValue() - Get the min value for a Unicode property
- IntlChar::getIntPropertyMaxValue() - Get the max value for a Unicode property
- IntlChar::getUnicodeVersion() - Get the Unicode version

# IntlChar::getNumericValue

(PHP 7, PHP 8)

IntlChar::getNumericValue — Get the numeric value for a Unicode code point

### Beschreibung

public static function IntlChar::getNumericValue(int|string `$codepoint`): ?float

Gets the numeric value for a Unicode code point as defined in the Unicode Character Database.

For characters without any numeric values in the Unicode Character Database, this function will return `IntlChar::NO_NUMERIC_VALUE`.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Numeric value of `codepoint`, or `IntlChar::NO_NUMERIC_VALUE` if none is defined. This constant was added in PHP 7.0.6, prior to this version the literal value (float)`-123456789` may be used instead. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::getNumericValue("4"));
    var_dump(IntlChar::getNumericValue("x"));
    var_dump(IntlChar::getNumericValue("\u{216C}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(4)
    float(-123456789)
    float(50)

# IntlChar::getPropertyEnum

(PHP 7, PHP 8)

IntlChar::getPropertyEnum — Get the property constant value for a given property name

### Beschreibung

public static function IntlChar::getPropertyEnum(string `$alias`): int

Returns the property constant value for a given property name, as specified in the Unicode database file PropertyAliases.txt. Short, long, and any other variants are recognized.

In addition, this function maps the synthetic names "gcm" / "General_Category_Mask" to the property `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`. These names are not in PropertyAliases.txt.

This function complements IntlChar::getPropertyName().

### Parameter-Liste

`alias`

  The property name to be matched. The name is compared using "loose matching" as described in PropertyAliases.txt.

### Rückgabewerte

Returns an `IntlChar::PROPERTY_` constant value, or `IntlChar::PROPERTY_INVALID_CODE` if the given name does not match any property.

### Beispiele

Beispiel #1 Testen unterschiedlicher Eigenschaften

    <?php
    var_dump(IntlChar::getPropertyEnum('Bidi_Class') === IntlChar::PROPERTY_BIDI_CLASS);
    var_dump(IntlChar::getPropertyEnum('script') === IntlChar::PROPERTY_SCRIPT);
    var_dump(IntlChar::getPropertyEnum('IDEOGRAPHIC') === IntlChar::PROPERTY_IDEOGRAPHIC);
    var_dump(IntlChar::getPropertyEnum('Some made-up string') === IntlChar::PROPERTY_INVALID_CODE);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Siehe auch

- IntlChar::getPropertyName() - Get the Unicode name for a property

# IntlChar::getPropertyName

(PHP 7, PHP 8)

IntlChar::getPropertyName — Get the Unicode name for a property

### Beschreibung

public static function IntlChar::getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Returns the Unicode name for a given property, as given in the Unicode database file PropertyAliases.txt.

In addition, this function maps the property `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` to the synthetic names "gcm" / "General_Category_Mask". These names are not in PropertyAliases.txt.

This function complements IntlChar::getPropertyEnum().

### Parameter-Liste

`property`

  Die Unicode-Eigenschaft, die gesucht werden soll (siehe die `IntlChar::PROPERTY_*`-Konstanten).

  `IntlChar::PROPERTY_INVALID_CODE` should not be used. Also, if `property` is out of range, `false` is returned.

`type`

  Selector for which name to get. If out of range, `false` is returned.

  All properties have a long name. Most have a short name, but some do not. Unicode allows for additional names; if present these will be returned by adding 1, 2, etc. to `IntlChar::LONG_PROPERTY_NAME`.

### Rückgabewerte

Returns the name, or `false` if either the `property` or the `type` is out of range.

If a given `type` returns `false`, then all larger values of `type` will return `false`, with one exception: if `false` is returned for `IntlChar::SHORT_PROPERTY_NAME`, then `IntlChar::LONG_PROPERTY_NAME` (and higher) may still return a non-`false` value.

### Beispiele

Beispiel #1 Testen unterschiedlicher Eigenschaften

    <?php
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyName(IntlChar::PROPERTY_BIDI_CLASS, IntlChar::LONG_PROPERTY_NAME + 1));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(10) "Bidi_Class"
    string(2) "bc"
    string(10) "Bidi_Class"
    bool(false)

### Siehe auch

- IntlChar::getPropertyEnum() - Get the property constant value for a given property name

# IntlChar::getPropertyValueEnum

(PHP 7, PHP 8)

IntlChar::getPropertyValueEnum — Get the property value for a given value name

### Beschreibung

public static function IntlChar::getPropertyValueEnum(int `$property`, string `$name`): int

Returns the property value integer for a given value name, as specified in the Unicode database file PropertyValueAliases.txt. Short, long, and any other variants are recognized.

> Hinweis:

> Some of the names in PropertyValueAliases.txt will only be recognized with `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`, not `IntlChar::PROPERTY_GENERAL_CATEGORY`. These include:

> - "C" / "Other"
> - "L" / "Letter"
> - "LC" / "Cased_Letter"
> - "M" / "Mark"
> - "N" / "Number"
> - "P" / "Punctuation"
> - "S" / "Symbol"
> - "Z" / "Separator"

### Parameter-Liste

`property`

  Die Unicode-Eigenschaft, die gesucht werden soll (siehe die `IntlChar::PROPERTY_*`-Konstanten).

  If out of range, or this method doesn't work with the given value, `IntlChar::PROPERTY_INVALID_CODE` is returned.

`name`

  The value name to be matched. The name is compared using "loose matching" as described in PropertyValueAliases.txt.

### Rückgabewerte

Returns the corresponding value integer, or `IntlChar::PROPERTY_INVALID_CODE` if the given name does not match any value of the given property, or if the property is invalid.

### Beispiele

Beispiel #1 Testen unterschiedlicher Eigenschaften

    <?php
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BLOCK, 'greek') === IntlChar::BLOCK_CODE_GREEK);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'RIGHT_TO_LEFT') === IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT);
    var_dump(IntlChar::getPropertyValueEnum(IntlChar::PROPERTY_BIDI_CLASS, 'some made-up string') === IntlChar::PROPERTY_INVALID_CODE);
    var_dump(IntlChar::getPropertyValueEnum(123456789, 'RIGHT_TO_LEFT') === IntlChar::PROPERTY_INVALID_CODE);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(true)
    bool(true)

# IntlChar::getPropertyValueName

(PHP 7, PHP 8)

IntlChar::getPropertyValueName — Get the Unicode name for a property value

### Beschreibung

public static function IntlChar::getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false

Returns the Unicode name for a given property value, as given in the Unicode database file PropertyValueAliases.txt.

> Hinweis:

> Some of the names in PropertyValueAliases.txt can only be retrieved using `IntlChar::PROPERTY_GENERAL_CATEGORY_MASK`, not `IntlChar::PROPERTY_GENERAL_CATEGORY`. These include:

> - "C" / "Other"
> - "L" / "Letter"
> - "LC" / "Cased_Letter"
> - "M" / "Mark"
> - "N" / "Number"
> - "P" / "Punctuation"
> - "S" / "Symbol"
> - "Z" / "Separator"

### Parameter-Liste

`property`

  Die Unicode-Eigenschaft, die gesucht werden soll (siehe die `IntlChar::PROPERTY_*`-Konstanten).

  If out of range, or this method doesn't work with the given value, `false` is returned.

`value`

  Selector for a value for the given property. If out of range, `false` is returned.

  In general, valid values range from `0` up to some maximum. There are a couple exceptions:

  - `IntlChar::PROPERTY_BLOCK` values begin at the non-zero value `IntlChar::BLOCK_CODE_BASIC_LATIN`
  - `IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` values are not contiguous and range from 0..240.
`type`

  Selector for which name to get. If out of range, `false` is returned.

  All values have a long name. Most have a short name, but some do not. Unicode allows for additional names; if present these will be returned by adding 1, 2, etc. to `IntlChar::LONG_PROPERTY_NAME`.

### Rückgabewerte

Returns the name, or `false` if either the `property` or the `type` is out of range. Returns `null` on failure.

If a given `type` returns `false`, then all larger values of `type` will return `false`, with one exception: if `false` is returned for `IntlChar::SHORT_PROPERTY_NAME`, then `IntlChar::LONG_PROPERTY_NAME` (and higher) may still return a non-`false` value.

### Beispiele

Beispiel #1 Testen unterschiedlicher Eigenschaften

    <?php
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::SHORT_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME));
    var_dump(IntlChar::getPropertyValueName(IntlChar::PROPERTY_BLOCK, IntlChar::BLOCK_CODE_GREEK, IntlChar::LONG_PROPERTY_NAME + 1));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(16) "Greek_And_Coptic"
    string(5) "Greek"
    string(16) "Greek_And_Coptic"
    bool(false)

# IntlChar::getUnicodeVersion

(PHP 7, PHP 8)

IntlChar::getUnicodeVersion — Get the Unicode version

### Beschreibung

public static function IntlChar::getUnicodeVersion(): array

Gets the Unicode version information.

The version array is filled in with the version information for the Unicode standard that is currently used by ICU. For example, Unicode version 3.1.1 is represented as an array with the values `[3, 1, 1, 0]`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array containing the Unicode version number.

### Beispiele

Beispiel #1 Testen unterschiedlicher Eigenschaften

    <?php
    var_dump(IntlChar::getUnicodeVersion());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      [0]=>
      int(7)
      [1]=>
      int(0)
      [2]=>
      int(0)
      [3]=>
      int(0)
    }

### Siehe auch

- IntlChar::charAge() - Get the "age" of the code point

# IntlChar::hasBinaryProperty

(PHP 7, PHP 8)

IntlChar::hasBinaryProperty — Check a binary Unicode property for a code point

### Beschreibung

public static function IntlChar::hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool

Checks a binary Unicode property for a code point.

Unicode, especially in version 3.2, defines many more properties than the original set in UnicodeData.txt.

The properties APIs are intended to reflect Unicode properties as defined in the Unicode Character Database (UCD) and Unicode Technical Reports (UTR). For details about the properties see » http://www.unicode.org/ucd/. For names of Unicode properties see the UCD file PropertyAliases.txt.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

`property`

  Die Unicode-Eigenschaft, die gesucht werden soll (siehe die `IntlChar::PROPERTY_*`-Konstanten).

### Rückgabewerte

Returns `true` or `false` according to the binary Unicode property value for `codepoint`. Also `false` if `property` is out of bounds or if the Unicode version does not have data for the property at all, or not for this code point. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Eigenschaften

    <?php
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("A", IntlChar::PROPERTY_BIDI_MIRRORED));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_ALPHABETIC));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_CASE_SENSITIVE));
    var_dump(IntlChar::hasBinaryProperty("[", IntlChar::PROPERTY_BIDI_MIRRORED));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)
    bool(false)
    bool(false)
    bool(true)

### Siehe auch

- IntlChar::getIntPropertyValue() - Get the value for a Unicode property for a code point
- IntlChar::getUnicodeVersion() - Get the Unicode version

# IntlChar::isalnum

(PHP 7, PHP 8)

IntlChar::isalnum — Check if code point is an alphanumeric character

### Beschreibung

public static function IntlChar::isalnum(int|string `$codepoint`): ?bool

Determines whether the specified code point is an alphanumeric character (letter or digit). `true` for characters with general categories "L" (letters) and "Nd" (decimal digit numbers).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is an alphanumeric character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isalnum("A"));
    var_dump(IntlChar::isalnum("1"));
    var_dump(IntlChar::isalnum("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)

### Siehe auch

- IntlChar::isalpha() - Check if code point is a letter character
- IntlChar::isdigit() - Check if code point is a digit character
- ctype_alnum() - Prüft auf alphanumerische Zeichen

# IntlChar::isalpha

(PHP 7, PHP 8)

IntlChar::isalpha — Check if code point is a letter character

### Beschreibung

public static function IntlChar::isalpha(int|string `$codepoint`): ?bool

Determines whether the specified code point is a letter character. `true` for general categories "L" (letters).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a letter character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isalpha("A"));
    var_dump(IntlChar::isalpha("1"));
    var_dump(IntlChar::isalpha("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::isalnum() - Check if code point is an alphanumeric character
- IntlChar::isdigit() - Check if code point is a digit character
- ctype_alpha() - Prüft auf Buchstabe(n)

# IntlChar::isbase

(PHP 7, PHP 8)

IntlChar::isbase — Check if code point is a base character

### Beschreibung

public static function IntlChar::isbase(int|string `$codepoint`): ?bool

Determines whether the specified code point is a base character. `true` for general categories "L" (letters), "N" (numbers), "Mc" (spacing combining marks), and "Me" (enclosing marks).

> Hinweis:

> This is different from the Unicode definition in chapter 3.5, conformance clause D13, which defines base characters to be all characters (not Cn) that do not graphically combine with preceding characters (M) and that are neither control (Cc) or format (Cf) characters.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a base character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isbase("A"));
    var_dump(IntlChar::isbase("1"));
    var_dump(IntlChar::isbase("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)

### Siehe auch

- IntlChar::isalpha() - Check if code point is a letter character
- IntlChar::isdigit() - Check if code point is a digit character

# IntlChar::isblank

(PHP 7, PHP 8)

IntlChar::isblank — Check if code point is a "blank" or "horizontal space" character

### Beschreibung

public static function IntlChar::isblank(int|string `$codepoint`): ?bool

Determines whether the specified code point is a "blank" or "horizontal space", a character that visibly separates words on a line.

The following are equivalent definitions:

- `true` for Unicode White_Space characters except for "vertical space controls" where "vertical space controls" are the following characters: U+000A (LF) U+000B (VT) U+000C (FF) U+000D (CR) U+0085 (NEL) U+2028 (LS) U+2029 (PS)
- `true` for U+0009 (TAB) and characters with general category "Zs" (space separators) except Zero Width Space (ZWSP, U+200B).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is either a "blank" or "horizontal space" character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isblank("A"));
    var_dump(IntlChar::isblank(" "));
    var_dump(IntlChar::isblank("\t"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(true)

### Siehe auch

- IntlChar::isspace() - Check if code point is a space character
- IntlChar::isJavaSpaceChar() - Check if code point is a space character according to Java
- IntlChar::isUWhiteSpace() - Check if code point has the White_Space Unicode property
- IntlChar::isWhitespace() - Check if code point is a whitespace character according to ICU

# IntlChar::iscntrl

(PHP 7, PHP 8)

IntlChar::iscntrl — Check if code point is a control character

### Beschreibung

public static function IntlChar::iscntrl(int|string `$codepoint`): ?bool

Determines whether the specified code point is a control character.

A control character is one of the following:

- ISO 8-bit control character (U+0000..U+001f and U+007f..U+009f)
- `IntlChar::CHAR_CATEGORY_CONTROL_CHAR` (Cc)
- `IntlChar::CHAR_CATEGORY_FORMAT_CHAR` (Cf)
- `IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` (Zl)
- `IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` (Zp)

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a control character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::iscntrl("A"));
    var_dump(IntlChar::iscntrl(" "));
    var_dump(IntlChar::iscntrl("\n"));
    var_dump(IntlChar::iscntrl("\u{200e}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(false)
    bool(true)
    bool(true)

### Siehe auch

- IntlChar::isprint() - Check if code point is a printable character
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_cntrl() - Prüft auf Steuerzeichen

# IntlChar::isdefined

(PHP 7, PHP 8)

IntlChar::isdefined — Check whether the code point is defined

### Beschreibung

public static function IntlChar::isdefined(int|string `$codepoint`): ?bool

Determines whether the specified code point is "defined", which usually means that it is assigned a character.

`true` for general categories other than "Cn" (other, not assigned).

> Hinweis:

> Note that non-character code points (e.g., U+FDD0) are not "defined" (they are Cn), but surrogate code points are "defined" (Cs).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a defined character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isdefined("A"));
    var_dump(IntlChar::isdefined(" "));
    var_dump(IntlChar::isdefined("\u{FDD0}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)

### Siehe auch

- IntlChar::isdigit() - Check if code point is a digit character
- IntlChar::isalpha() - Check if code point is a letter character
- IntlChar::isalnum() - Check if code point is an alphanumeric character
- IntlChar::isupper() - Check if code point has the general category "Lu" (uppercase letter)
- IntlChar::islower() - Check if code point is a lowercase letter
- IntlChar::istitle() - Check if code point is a titlecase letter

# IntlChar::isdigit

(PHP 7, PHP 8)

IntlChar::isdigit — Check if code point is a digit character

### Beschreibung

public static function IntlChar::isdigit(int|string `$codepoint`): ?bool

Determines whether the specified code point is a digit character.

`true` for characters with general category "Nd" (decimal digit numbers). Beginning with Unicode 4, this is the same as testing for the Numeric_Type of Decimal.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a digit character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isdigit("A"));
    var_dump(IntlChar::isdigit("1"));
    var_dump(IntlChar::isdigit("\t"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(false)

### Siehe auch

- IntlChar::isalpha() - Check if code point is a letter character
- IntlChar::isalnum() - Check if code point is an alphanumeric character
- IntlChar::isxdigit() - Check if code point is a hexadecimal digit
- ctype_digit() - Prüft auf Ziffern

# IntlChar::isgraph

(PHP 7, PHP 8)

IntlChar::isgraph — Check if code point is a graphic character

### Beschreibung

public static function IntlChar::isgraph(int|string `$codepoint`): ?bool

Determines whether the specified code point is a "graphic" character (printable, excluding spaces).

`true` for all characters except those with general categories "Cc" (control codes), "Cf" (format controls), "Cs" (surrogates), "Cn" (unassigned), and "Z" (separators).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a "graphic" character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isgraph("A"));
    var_dump(IntlChar::isgraph("1"));
    var_dump(IntlChar::isgraph("\u{2603}"));
    var_dump(IntlChar::isgraph("\n"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Siehe auch

- ctype_graph() - Prüft auf druckbare Zeichen (außer Leerzeichen)

# IntlChar::isIDIgnorable

(PHP 7, PHP 8)

IntlChar::isIDIgnorable — Check if code point is an ignorable character

### Beschreibung

public static function IntlChar::isIDIgnorable(int|string `$codepoint`): ?bool

Determines if the specified character should be regarded as an ignorable character in an identifier.

`true` for characters with general category "Cf" (format controls) as well as non-whitespace ISO controls (U+0000..U+0008, U+000E..U+001B, U+007F..U+009F).

> Hinweis:

> Note that Unicode just recommends to ignore Cf (format controls).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is ignorable in identifiers, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isIDIgnorable("A"));
    var_dump(IntlChar::isIDIgnorable(" "));
    var_dump(IntlChar::isIDIgnorable("\u{007F}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(false)
    bool(true)

### Siehe auch

- IntlChar::isIDStart() - Check if code point is permissible as the first character in an identifier
- IntlChar::isIDPart() - Check if code point is permissible in an identifier
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`

# IntlChar::isIDPart

(PHP 7, PHP 8)

IntlChar::isIDPart — Check if code point is permissible in an identifier

### Beschreibung

public static function IntlChar::isIDPart(int|string `$codepoint`): ?bool

Determines if the specified character is permissible in an identifier.

`true` for characters with general categories "L" (letters), "Nl" (letter numbers), "Nd" (decimal digits), "Mc" and "Mn" (combining marks), "Pc" (connecting punctuation), and u_isIDIgnorable(c).

> Hinweis:

> This is almost the same as Unicode's ID_Continue (`IntlChar::PROPERTY_ID_CONTINUE`) except that Unicode recommends to ignore Cf which is less than IntlChar::isIDIgnorable().

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is the code point may occur in an identifier, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isIDPart("A"));
    var_dump(IntlChar::isIDPart("$"));
    var_dump(IntlChar::isIDPart("\n"));
    var_dump(IntlChar::isIDPart("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::isIDIgnorable() - Check if code point is an ignorable character
- IntlChar::isIDStart() - Check if code point is permissible as the first character in an identifier
- `IntlChar::PROPERTY_ID_CONTINUE`

# IntlChar::isIDStart

(PHP 7, PHP 8)

IntlChar::isIDStart — Check if code point is permissible as the first character in an identifier

### Beschreibung

public static function IntlChar::isIDStart(int|string `$codepoint`): ?bool

Determines if the specified character is permissible as the first character in an identifier according to Unicode (The Unicode Standard, Version 3.0, chapter 5.16 Identifiers).

`true` for characters with general categories "L" (letters) and "Nl" (letter numbers).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` may start an identifier, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isIDStart("A"));
    var_dump(IntlChar::isIDStart("$"));
    var_dump(IntlChar::isIDStart("\n"));
    var_dump(IntlChar::isIDStart("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::isalpha() - Check if code point is a letter character
- IntlChar::isIDPart() - Check if code point is permissible in an identifier
- `IntlChar::PROPERTY_ID_START`

# IntlChar::isISOControl

(PHP 7, PHP 8)

IntlChar::isISOControl — Check if code point is an ISO control code

### Beschreibung

public static function IntlChar::isISOControl(int|string `$codepoint`): ?bool

Determines whether the specified code point is an ISO control code.

`true` for U+0000..U+001f and U+007f..U+009f (general category "Cc").

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is an ISO control code, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isISOControl(" "));
    var_dump(IntlChar::isISOControl("\n"));
    var_dump(IntlChar::isISOControl("\u{200e}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(false)

### Siehe auch

- IntlChar::iscntrl() - Check if code point is a control character

# IntlChar::isJavaIDPart

(PHP 7, PHP 8)

IntlChar::isJavaIDPart — Check if code point is permissible in a Java identifier

### Beschreibung

public static function IntlChar::isJavaIDPart(int|string `$codepoint`): ?bool

Determines if the specified character is permissible in a Java identifier.

In addition to IntlChar::isIDPart(), `true` for characters with general category "Sc" (currency symbols).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` may occur in a Java identifier, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isJavaIDPart("A"));
    var_dump(IntlChar::isJavaIDPart("$"));
    var_dump(IntlChar::isJavaIDPart("\n"));
    var_dump(IntlChar::isJavaIDPart("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::isIDIgnorable() - Check if code point is an ignorable character
- IntlChar::isIDPart() - Check if code point is permissible in an identifier
- IntlChar::isJavaIDStart() - Check if code point is permissible as the first character in a Java identifier
- IntlChar::isalpha() - Check if code point is a letter character
- IntlChar::isdigit() - Check if code point is a digit character

# IntlChar::isJavaIDStart

(PHP 7, PHP 8)

IntlChar::isJavaIDStart — Check if code point is permissible as the first character in a Java identifier

### Beschreibung

public static function IntlChar::isJavaIDStart(int|string `$codepoint`): ?bool

Determines if the specified character is permissible as the start of a Java identifier.

In addition to IntlChar::isIDStart(), `true` for characters with general categories "Sc" (currency symbols) and "Pc" (connecting punctuation).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` may start a Java identifier, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isJavaIDStart("A"));
    var_dump(IntlChar::isJavaIDStart("$"));
    var_dump(IntlChar::isJavaIDStart("\n"));
    var_dump(IntlChar::isJavaIDStart("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::isIDStart() - Check if code point is permissible as the first character in an identifier
- IntlChar::isJavaIDPart() - Check if code point is permissible in a Java identifier
- IntlChar::isalpha() - Check if code point is a letter character

# IntlChar::isJavaSpaceChar

(PHP 7, PHP 8)

IntlChar::isJavaSpaceChar — Check if code point is a space character according to Java

### Beschreibung

public static function IntlChar::isJavaSpaceChar(int|string `$codepoint`): ?bool

Determine if the specified code point is a space character according to Java.

`true` for characters with general categories "Z" (separators), which does not include control codes (e.g., TAB or Line Feed).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a space character according to Java, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isJavaSpaceChar("A"));
    var_dump(IntlChar::isJavaSpaceChar(" "));
    var_dump(IntlChar::isJavaSpaceChar("\n"));
    var_dump(IntlChar::isJavaSpaceChar("\t"));
    var_dump(IntlChar::isJavaSpaceChar("\u{00A0}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(false)
    bool(false)
    bool(true)

### Siehe auch

- IntlChar::isspace() - Check if code point is a space character
- IntlChar::isWhitespace() - Check if code point is a whitespace character according to ICU
- IntlChar::isUWhiteSpace() - Check if code point has the White_Space Unicode property

# IntlChar::islower

(PHP 7, PHP 8)

IntlChar::islower — Check if code point is a lowercase letter

### Beschreibung

public static function IntlChar::islower(int|string `$codepoint`): ?bool

Determines whether the specified code point has the general category "Ll" (lowercase letter).

> Hinweis:

> This misses some characters that are also lowercase but have a different general category value. In order to include those, use IntlChar::isULowercase().

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is an Ll lowercase letter, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::islower("A"));
    var_dump(IntlChar::islower("a"));
    var_dump(IntlChar::islower("Φ"));
    var_dump(IntlChar::islower("φ"));
    var_dump(IntlChar::islower("1"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Siehe auch

- IntlChar::isupper() - Check if code point has the general category "Lu" (uppercase letter)
- IntlChar::istitle() - Check if code point is a titlecase letter
- IntlChar::tolower() - Make Unicode character lowercase
- IntlChar::toupper() - Make Unicode character uppercase
- `IntlChar::PROPERTY_LOWERCASE`
- ctype_lower() - Prüft auf Kleinbuchstaben

# IntlChar::isMirrored

(PHP 7, PHP 8)

IntlChar::isMirrored — Check if code point has the Bidi_Mirrored property

### Beschreibung

public static function IntlChar::isMirrored(int|string `$codepoint`): ?bool

Determines whether the code point has the Bidi_Mirrored property.

This property is set for characters that are commonly used in Right-To-Left contexts and need to be displayed with a "mirrored" glyph.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` has the Bidi_Mirrored property, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isMirrored("A"));
    var_dump(IntlChar::isMirrored("<"));
    var_dump(IntlChar::isMirrored("("));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(true)

### Siehe auch

- IntlChar::charMirror() - Get the "mirror-image" character for a code point
- `IntlChar::PROPERTY_BIDI_MIRRORED`

# IntlChar::isprint

(PHP 7, PHP 8)

IntlChar::isprint — Check if code point is a printable character

### Beschreibung

public static function IntlChar::isprint(int|string `$codepoint`): ?bool

Determines whether the specified code point is a printable character.

`true` for general categories other than "C" (controls).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a printable character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isprint("A"));
    var_dump(IntlChar::isprint(" "));
    var_dump(IntlChar::isprint("\n"));
    var_dump(IntlChar::isprint("\u{200e}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::iscntrl() - Check if code point is a control character
- `IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT`
- ctype_print() - Prüft auf druckbare Zeichen

# IntlChar::ispunct

(PHP 7, PHP 8)

IntlChar::ispunct — Check if code point is punctuation character

### Beschreibung

public static function IntlChar::ispunct(int|string `$codepoint`): ?bool

Determines whether the specified code point is a punctuation character.

`true` for characters with general categories "P" (punctuation).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a punctuation character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::ispunct("."));
    var_dump(IntlChar::ispunct(","));
    var_dump(IntlChar::ispunct("\n"));
    var_dump(IntlChar::ispunct("$"));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)
    bool(false)

### Siehe auch

- ctype_punct() - Prüft auf Sonderzeichen, d. h. auf druckbare Zeichen die weder Buchstaben noch Ziffern noch Leerzeichen sind.

# IntlChar::isspace

(PHP 7, PHP 8)

IntlChar::isspace — Check if code point is a space character

### Beschreibung

public static function IntlChar::isspace(int|string `$codepoint`): ?bool

Determines if the specified character is a space character or not.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a space character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isspace("A"));
    var_dump(IntlChar::isspace(" "));
    var_dump(IntlChar::isspace("\n"));
    var_dump(IntlChar::isspace("\t"));
    var_dump(IntlChar::isspace("\u{00A0}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Siehe auch

- IntlChar::isJavaSpaceChar() - Check if code point is a space character according to Java
- IntlChar::isWhitespace() - Check if code point is a whitespace character according to ICU
- IntlChar::isUWhiteSpace() - Check if code point has the White_Space Unicode property
- ctype_space() - Prüft auf Leerzeichen

# IntlChar::istitle

(PHP 7, PHP 8)

IntlChar::istitle — Check if code point is a titlecase letter

### Beschreibung

public static function IntlChar::istitle(int|string `$codepoint`): ?bool

Determines whether the specified code point is a titlecase letter.

`true` for general category "Lt" (titlecase letter).

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a titlecase letter, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    // Latin Capital Letter Dz with Caron U+01C4
    var_dump(IntlChar::istitle("Ǆ"));
    // Latin Capital Letter D with Small Letter Z with Caron U+01C5
    var_dump(IntlChar::istitle("ǅ"));
    // Latin Small Letter Dz with Caron U+01C6
    var_dump(IntlChar::istitle("ǆ"));

    // Greek Capital Letter Alpha with Prosgegrammeni U+1FBC
    var_dump(IntlChar::istitle("ᾼ"));
    // Greek Small Letter Alpha with Ypogegrammeni U+1FB3
    var_dump(IntlChar::istitle("ᾳ"));
    // Greek Capital Letter Alpha U+0391
    var_dump(IntlChar::istitle("Α"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::isupper() - Check if code point has the general category "Lu" (uppercase letter)
- IntlChar::islower() - Check if code point is a lowercase letter
- IntlChar::totitle() - Make Unicode character titlecase

# IntlChar::isUAlphabetic

(PHP 7, PHP 8)

IntlChar::isUAlphabetic — Check if code point has the Alphabetic Unicode property

### Beschreibung

public static function IntlChar::isUAlphabetic(int|string `$codepoint`): ?bool

Check if a code point has the Alphabetic Unicode property.

This is the same as `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_ALPHABETIC)`

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` has the Alphabetic Unicode property, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isUAlphabetic("A"));
    var_dump(IntlChar::isUAlphabetic("1"));
    var_dump(IntlChar::isUAlphabetic("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::isalpha() - Check if code point is a letter character
- IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
- `IntlChar::PROPERTY_ALPHABETIC`

# IntlChar::isULowercase

(PHP 7, PHP 8)

IntlChar::isULowercase — Check if code point has the Lowercase Unicode property

### Beschreibung

public static function IntlChar::isULowercase(int|string `$codepoint`): ?bool

Check if a code point has the Lowercase Unicode property.

This is the same as `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_LOWERCASE)`

> Hinweis:

> This is different than IntlChar::islower() and will return `true` for more characters.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` has the Lowercase Unicode property, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isULowercase("A"));
    var_dump(IntlChar::isULowercase("a"));
    var_dump(IntlChar::isULowercase("Φ"));
    var_dump(IntlChar::isULowercase("φ"));
    var_dump(IntlChar::isULowercase("1"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(false)
    bool(true)
    bool(false)

### Siehe auch

- IntlChar::islower() - Check if code point is a lowercase letter
- IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
- `IntlChar::PROPERTY_LOWERCASE`

# IntlChar::isupper

(PHP 7, PHP 8)

IntlChar::isupper — Check if code point has the general category "Lu" (uppercase letter)

### Beschreibung

public static function IntlChar::isupper(int|string `$codepoint`): ?bool

Determines whether the specified code point has the general category "Lu" (uppercase letter).

> Hinweis:

> This misses some characters that are also uppercase but have a different general category value. In order to include those, use IntlChar::isUUppercase().

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is an Lu uppercase letter, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isupper("A"));
    var_dump(IntlChar::isupper("a"));
    var_dump(IntlChar::isupper("Φ"));
    var_dump(IntlChar::isupper("φ"));
    var_dump(IntlChar::isupper("1"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::islower() - Check if code point is a lowercase letter
- IntlChar::istitle() - Check if code point is a titlecase letter
- IntlChar::tolower() - Make Unicode character lowercase
- IntlChar::toupper() - Make Unicode character uppercase
- `IntlChar::PROPERTY_UPPERCASE`
- ctype_upper() - Prüft auf Großbuchstaben

# IntlChar::isUUppercase

(PHP 7, PHP 8)

IntlChar::isUUppercase — Check if code point has the Uppercase Unicode property

### Beschreibung

public static function IntlChar::isUUppercase(int|string `$codepoint`): ?bool

Check if a code point has the Uppercase Unicode property.

This is the same as `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_UPPERCASE)`

> Hinweis:

> This is different than IntlChar::isupper() and will return `true` for more characters.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` has the Uppercase Unicode property, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isUUppercase("A"));
    var_dump(IntlChar::isUUppercase("a"));
    var_dump(IntlChar::isUUppercase("Φ"));
    var_dump(IntlChar::isUUppercase("φ"));
    var_dump(IntlChar::isUUppercase("1"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    bool(true)
    bool(false)
    bool(false)

### Siehe auch

- IntlChar::isupper() - Check if code point has the general category "Lu" (uppercase letter)
- IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
- `IntlChar::PROPERTY_UPPERCASE`

# IntlChar::isUWhiteSpace

(PHP 7, PHP 8)

IntlChar::isUWhiteSpace — Check if code point has the White_Space Unicode property

### Beschreibung

public static function IntlChar::isUWhiteSpace(int|string `$codepoint`): ?bool

Check if a code point has the White_Space Unicode property.

This is the same as `IntlChar::hasBinaryProperty($codepoint, IntlChar::PROPERTY_WHITE_SPACE)`

> Hinweis:

> This is different from both IntlChar::isspace() and IntlChar::isWhitespace().

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` has the White_Space Unicode property, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isUWhiteSpace("A"));
    var_dump(IntlChar::isUWhiteSpace(" "));
    var_dump(IntlChar::isUWhiteSpace("\n"));
    var_dump(IntlChar::isUWhiteSpace("\t"));
    var_dump(IntlChar::isUWhiteSpace("\u{00A0}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(true)

### Siehe auch

- IntlChar::isspace() - Check if code point is a space character
- IntlChar::isWhitespace() - Check if code point is a whitespace character according to ICU
- IntlChar::isJavaSpaceChar() - Check if code point is a space character according to Java
- IntlChar::hasBinaryProperty() - Check a binary Unicode property for a code point
- `IntlChar::PROPERTY_WHITE_SPACE`

# IntlChar::isWhitespace

(PHP 7, PHP 8)

IntlChar::isWhitespace — Check if code point is a whitespace character according to ICU

### Beschreibung

public static function IntlChar::isWhitespace(int|string `$codepoint`): ?bool

Determines if the specified code point is a whitespace character according to ICU.

A character is considered to be a ICU whitespace character if and only if it satisfies one of the following criteria:

- It is a Unicode Separator character (categories "Z" = "Zs" or "Zl" or "Zp"), but is not also a non-breaking space (U+00A0 NBSP or U+2007 Figure Space or U+202F Narrow NBSP).
- It is U+0009 HORIZONTAL TABULATION.
- It is U+000A LINE FEED.
- It is U+000B VERTICAL TABULATION.
- It is U+000C FORM FEED.
- It is U+000D CARRIAGE RETURN.
- It is U+001C FILE SEPARATOR.
- It is U+001D GROUP SEPARATOR.
- It is U+001E RECORD SEPARATOR.
- It is U+001F UNIT SEPARATOR.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a whitespace character according to ICU, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::iswhitespace("A"));
    var_dump(IntlChar::iswhitespace(" "));
    var_dump(IntlChar::iswhitespace("\n"));
    var_dump(IntlChar::iswhitespace("\t"));
    var_dump(IntlChar::iswhitespace("\u{00A0}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)
    bool(true)
    bool(true)
    bool(false)

### Siehe auch

- IntlChar::isspace() - Check if code point is a space character
- IntlChar::isJavaSpaceChar() - Check if code point is a space character according to Java
- IntlChar::isUWhiteSpace() - Check if code point has the White_Space Unicode property

# IntlChar::isxdigit

(PHP 7, PHP 8)

IntlChar::isxdigit — Check if code point is a hexadecimal digit

### Beschreibung

public static function IntlChar::isxdigit(int|string `$codepoint`): ?bool

Determines whether the specified code point is a hexadecimal digit.

`true` for characters with general category "Nd" (decimal digit numbers) as well as Latin letters a-f and A-F in both ASCII and Fullwidth ASCII. (That is, for letters with code points 0041..0046, 0061..0066, FF21..FF26, FF41..FF46.)

This is equivalent to `IntlChar::digit($codepoint, 16) >= 0`.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns `true` if `codepoint` is a hexadecimal character, `false` if not. Returns `null` on failure.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::isxdigit("A"));
    var_dump(IntlChar::isxdigit("1"));
    var_dump(IntlChar::isxdigit("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(true)
    bool(false)

### Anmerkungen

> Hinweis:

> In order to narrow the definition of hexadecimal digits to only ASCII characters use:

>     <?php
>     $isASCIIHexadecimal = IntlChar::ord($codepoint) <= 0x7F && IntlChar::isxdigit($codepoint);
>     ?>

### Siehe auch

- IntlChar::isdigit() - Check if code point is a digit character
- ctype_xdigit() - Prüft auf Zeichen, die eine Hexadezimalziffer darstellen

# IntlChar::ord

(PHP 7, PHP 8)

IntlChar::ord — Return Unicode code point value of character

### Beschreibung

public static function IntlChar::ord(int|string `$character`): ?int

Returns the Unicode code point value of the given character.

This function complements IntlChar::chr().

### Parameter-Liste

`character`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns the Unicode code point value as an integer.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::ord("A"));
    var_dump(IntlChar::ord(" "));
    var_dump(IntlChar::ord("\u{2603}"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(65)
    int(32)
    int(9731)

### Siehe auch

- IntlChar::chr() - Return Unicode character by code point value
- mb_ord() - Get Unicode code point of character
- ord() - Konvertiert das erste Byte einer Zeichenkette in einen Wert zwischen 0 und 255

# IntlChar::tolower

(PHP 7, PHP 8)

IntlChar::tolower — Make Unicode character lowercase

### Beschreibung

public static function IntlChar::tolower(int|string `$codepoint`): int|string|null

The given character is mapped to its lowercase equivalent. If the character has no lowercase equivalent, the original character itself is returned.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns the Simple_Lowercase_Mapping of the code point, if any; otherwise the code point itself. Returns `null` on failure.

Der Rückgabetyp ist int, außer der Codepoint wurde als UTF-8-String übergeben, in welchem Fall ein String zurückgegeben wird. Bei einem Fehler wird `null` zurückgegeben.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::tolower("A"));
    var_dump(IntlChar::tolower("a"));
    var_dump(IntlChar::tolower("Φ"));
    var_dump(IntlChar::tolower("φ"));
    var_dump(IntlChar::tolower("1"));
    var_dump(IntlChar::tolower(ord("A")));
    var_dump(IntlChar::tolower(ord("a")));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "a"
    string(1) "a"
    string(2) "φ"
    string(2) "φ"
    string(1) "1"
    int(97)
    int(97)

### Siehe auch

- IntlChar::totitle() - Make Unicode character titlecase
- IntlChar::toupper() - Make Unicode character uppercase
- mb_strtolower() - Make a string lowercase

# IntlChar::totitle

(PHP 7, PHP 8)

IntlChar::totitle — Make Unicode character titlecase

### Beschreibung

public static function IntlChar::totitle(int|string `$codepoint`): int|string|null

The given character is mapped to its titlecase equivalent. If the character has no titlecase equivalent, the original character itself is returned.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns the Simple_Titlecase_Mapping of the code point, if any; otherwise the code point itself. Returns `null` on failure.

Der Rückgabetyp ist int, außer der Codepoint wurde als UTF-8-String übergeben, in welchem Fall ein String zurückgegeben wird. Bei einem Fehler wird `null` zurückgegeben.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::totitle("Ǆ"));
    var_dump(IntlChar::totitle("ǆ"));
    var_dump(IntlChar::totitle("Φ"));
    var_dump(IntlChar::totitle("φ"));
    var_dump(IntlChar::totitle("1"));
    var_dump(IntlChar::totitle("ᾳ"));
    var_dump(IntlChar::totitle(ord("A")));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "ǅ"
    string(1) "ǅ"
    string(2) "Φ"
    string(2) "φ"
    string(1) "1"
    string(1) "ᾼ"
    int(65)

### Siehe auch

- IntlChar::tolower() - Make Unicode character lowercase
- IntlChar::toupper() - Make Unicode character uppercase
- IntlChar::istitle() - Check if code point is a titlecase letter
- mb_convert_case() - Perform case folding on a string

# IntlChar::toupper

(PHP 7, PHP 8)

IntlChar::toupper — Make Unicode character uppercase

### Beschreibung

public static function IntlChar::toupper(int|string `$codepoint`): int|string|null

The given character is mapped to its uppercase equivalent. If the character has no uppercase equivalent, the character itself is returned.

### Parameter-Liste

`codepoint`

  Ein Wert vom Typ int, der einen Codepoint darstellt (z. B. `0x2603` für U+2603 SNOWMAN) oder ein als UTF-8-String kodiertes Zeichen (z. B. `"\u{2603}"`)

### Rückgabewerte

Returns the Simple_Uppercase_Mapping of the code point, if any; otherwise the code point itself.

Der Rückgabetyp ist int, außer der Codepoint wurde als UTF-8-String übergeben, in welchem Fall ein String zurückgegeben wird. Bei einem Fehler wird `null` zurückgegeben.

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    var_dump(IntlChar::toupper("A"));
    var_dump(IntlChar::toupper("a"));
    var_dump(IntlChar::toupper("Φ"));
    var_dump(IntlChar::toupper("φ"));
    var_dump(IntlChar::toupper("1"));
    var_dump(IntlChar::toupper(ord("A")));
    var_dump(IntlChar::toupper(ord("a")));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "A"
    string(1) "A"
    string(2) "Φ"
    string(2) "Φ"
    string(1) "1"
    int(65)
    int(65)

### Siehe auch

- IntlChar::tolower() - Make Unicode character lowercase
- IntlChar::totitle() - Make Unicode character titlecase
- mb_strtoupper() - Make a string uppercase

## Inhaltsverzeichnis

- IntlChar::charAge — Get the "age" of the code point
- IntlChar::charDigitValue — Get the decimal digit value of a decimal digit character
- IntlChar::charDirection — Get bidirectional category value for a code point
- IntlChar::charFromName — Find Unicode character by name and return its code point value
- IntlChar::charMirror — Get the "mirror-image" character for a code point
- IntlChar::charName — Retrieve the name of a Unicode character
- IntlChar::charType — Get the general category value for a code point
- IntlChar::chr — Return Unicode character by code point value
- IntlChar::digit — Get the decimal digit value of a code point for a given radix
- IntlChar::enumCharNames — Enumerate all assigned Unicode characters within a range
- IntlChar::enumCharTypes — Enumerate all code points with their Unicode general categories
- IntlChar::foldCase — Perform case folding on a code point
- IntlChar::forDigit — Get character representation for a given digit and radix
- IntlChar::getBidiPairedBracket — Get the paired bracket character for a code point
- IntlChar::getBlockCode — Get the Unicode allocation block containing a code point
- IntlChar::getCombiningClass — Get the combining class of a code point
- IntlChar::getFC_NFKC_Closure — Get the FC_NFKC_Closure property for a code point
- IntlChar::getIntPropertyMaxValue — Get the max value for a Unicode property
- IntlChar::getIntPropertyMinValue — Get the min value for a Unicode property
- IntlChar::getIntPropertyValue — Get the value for a Unicode property for a code point
- IntlChar::getNumericValue — Get the numeric value for a Unicode code point
- IntlChar::getPropertyEnum — Get the property constant value for a given property name
- IntlChar::getPropertyName — Get the Unicode name for a property
- IntlChar::getPropertyValueEnum — Get the property value for a given value name
- IntlChar::getPropertyValueName — Get the Unicode name for a property value
- IntlChar::getUnicodeVersion — Get the Unicode version
- IntlChar::hasBinaryProperty — Check a binary Unicode property for a code point
- IntlChar::isalnum — Check if code point is an alphanumeric character
- IntlChar::isalpha — Check if code point is a letter character
- IntlChar::isbase — Check if code point is a base character
- IntlChar::isblank — Check if code point is a "blank" or "horizontal space" character
- IntlChar::iscntrl — Check if code point is a control character
- IntlChar::isdefined — Check whether the code point is defined
- IntlChar::isdigit — Check if code point is a digit character
- IntlChar::isgraph — Check if code point is a graphic character
- IntlChar::isIDIgnorable — Check if code point is an ignorable character
- IntlChar::isIDPart — Check if code point is permissible in an identifier
- IntlChar::isIDStart — Check if code point is permissible as the first character in an identifier
- IntlChar::isISOControl — Check if code point is an ISO control code
- IntlChar::isJavaIDPart — Check if code point is permissible in a Java identifier
- IntlChar::isJavaIDStart — Check if code point is permissible as the first character in a Java identifier
- IntlChar::isJavaSpaceChar — Check if code point is a space character according to Java
- IntlChar::islower — Check if code point is a lowercase letter
- IntlChar::isMirrored — Check if code point has the Bidi_Mirrored property
- IntlChar::isprint — Check if code point is a printable character
- IntlChar::ispunct — Check if code point is punctuation character
- IntlChar::isspace — Check if code point is a space character
- IntlChar::istitle — Check if code point is a titlecase letter
- IntlChar::isUAlphabetic — Check if code point has the Alphabetic Unicode property
- IntlChar::isULowercase — Check if code point has the Lowercase Unicode property
- IntlChar::isupper — Check if code point has the general category "Lu" (uppercase letter)
- IntlChar::isUUppercase — Check if code point has the Uppercase Unicode property
- IntlChar::isUWhiteSpace — Check if code point has the White_Space Unicode property
- IntlChar::isWhitespace — Check if code point is a whitespace character according to ICU
- IntlChar::isxdigit — Check if code point is a hexadecimal digit
- IntlChar::ord — Return Unicode code point value of character
- IntlChar::tolower — Make Unicode character lowercase
- IntlChar::totitle — Make Unicode character titlecase
- IntlChar::toupper — Make Unicode character uppercase

# Exception class for intl errors

(PHP 5 > 5.5.0, PHP 7, PHP 8, PECL intl > 3.0.0a1)

## Einführung

This class is used for generating exceptions when errors occur inside intl functions. Such exceptions are only generated when intl.use_exceptions is enabled.

## Klassenbeschreibung

class IntlException extends Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Geerbte Methoden */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The IntlIterator class

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## Einführung

This class represents iterator objects throughout the intl extension whenever the iterator cannot be identified with any other object provided by the extension. The distinct iterator object used internally by the `foreach` construct can only be obtained (in the relevant part here) from objects, so objects of this class serve the purpose of providing the hook through which this internal object can be obtained. As a convenience, this class also implements the Iterator interface, allowing the collection of values to be navigated using the methods defined in that interface. Both these methods and the internal iterator objects provided to `foreach` are backed by the same state (e.g. the position of the iterator and its current value).

Subclasses may provide richer functionality.

## Klassenbeschreibung

class IntlIterator implements Iterator {
/* Methoden */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# IntlIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::current — Get the current element

### Beschreibung

public function IntlIterator::current(): mixed

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlIterator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::key — Get the current key

### Beschreibung

public function IntlIterator::key(): mixed

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::next — Move forward to the next element

### Beschreibung

public function IntlIterator::next(): void

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlIterator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::rewind — Rewind the iterator to the first element

### Beschreibung

public function IntlIterator::rewind(): void

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# IntlIterator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::valid — Check if current position is valid

### Beschreibung

public function IntlIterator::valid(): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

## Inhaltsverzeichnis

- IntlIterator::current — Get the current element
- IntlIterator::key — Get the current key
- IntlIterator::next — Move forward to the next element
- IntlIterator::rewind — Rewind the iterator to the first element
- IntlIterator::valid — Check if current position is valid

# intl Funktionen

# intl_error_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_error_name — Get symbolic name for a given error code

### Beschreibung

function intl_error_name(int `$errorCode`): string

Return ICU error code name.

### Parameter-Liste

`errorCode`

  ICU error code.

### Rückgabewerte

The returned string will be the same as the name of the error code constant.

### Beispiele

Beispiel #1 intl_error_name() example

    <?php
    $coll     = collator_create( 'en_RU' );
    $err_code = collator_get_error_code( $coll );

    printf( "Symbolic name for %d is %s\n.", $err_code, intl_error_name( $err_code ) );
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Symbolic name for -128 is U_USING_FALLBACK_WARNING.

### Siehe auch

- intl_is_failure() - Check whether the given error code indicates failure
- intl_get_error_code() - Get the last error code
- intl_get_error_message() - Get description of the last error

# intl_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_code — Get the last error code

### Beschreibung

function intl_get_error_code(): int

Useful to handle errors occurred in static methods when there's no object to get error code from.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Error code returned by the last API function call.

### Beispiele

Beispiel #1 intl_get_error_code() example

    <?php
    $coll = collator_create( '<bad_param>' );
    if( !$coll ) {
        handle_error( intl_get_error_code() );
    }
    ?>

### Siehe auch

- intl_is_failure() - Check whether the given error code indicates failure
- intl_error_name() - Get symbolic name for a given error code
- intl_get_error_message() - Get description of the last error
- collator_get_error_code() - Get collator's last error code
- numfmt_get_error_code() - Get formatter's last error code

# intl_get_error_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_message — Get description of the last error

### Beschreibung

function intl_get_error_message(): string

Get error message from last internationalization function called.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Description of an error occurred in the last API function call.

### Beispiele

Beispiel #1 intl_get_error_message() example

    <?php
    if( Collator::getAvailableLocales() === false ) {
        show_error( intl_get_error_message() );
    }
    ?>

### Siehe auch

- intl_error_name() - Get symbolic name for a given error code
- intl_get_error_code() - Get the last error code
- intl_is_failure() - Check whether the given error code indicates failure
- collator_get_error_message() - Get text for collator's last error code
- numfmt_get_error_message() - Get formatter's last error message

# intl_is_failure

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_is_failure — Check whether the given error code indicates failure

### Beschreibung

function intl_is_failure(int `$errorCode`): bool

### Parameter-Liste

`errorCode`

  is a value that returned by functions: intl_get_error_code(), collator_get_error_code() .

### Rückgabewerte

`true` if it the code indicates some failure, and `false` in case of success or a warning.

### Beispiele

Beispiel #1 intl_is_failure() example

    <?php
    function check( $err_code )
    {
        var_export( intl_is_failure( $err_code ) );
        echo "\n";
    }

    check( U_ZERO_ERROR );
    check( U_USING_FALLBACK_WARNING );
    check( U_ILLEGAL_ARGUMENT_ERROR );
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    false
    false
    true

### Siehe auch

- intl_get_error_code() - Get the last error code
- collator_get_error_code() - Get collator's last error code
- Collator-getErrorCode()

## Inhaltsverzeichnis

- intl_error_name — Get symbolic name for a given error code
- intl_get_error_code — Get the last error code
- intl_get_error_message — Get description of the last error
- intl_is_failure — Check whether the given error code indicates failure

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Beispiele
  - Basic usage of this extension
- Collator — The Collator class
  - Collator::asort — Sort array maintaining index association
  - Collator::compare — Compare two Unicode strings
  - Collator::__construct — Create a collator
  - Collator::create — Create a collator
  - Collator::getAttribute — Get collation attribute value
  - Collator::getErrorCode — Get collator's last error code
  - Collator::getErrorMessage — Get text for collator's last error code
  - Collator::getLocale — Get the locale name of the collator
  - Collator::getSortKey — Get sorting key for a string
  - Collator::getStrength — Get current collation strength
  - Collator::setAttribute — Set collation attribute
  - Collator::setStrength — Set collation strength
  - Collator::sort — Sort array using specified collator
  - Collator::sortWithSortKeys — Sort array using specified collator and sort keys
- NumberFormatter — The NumberFormatter class
  - NumberFormatter::create — Create a number formatter
  - NumberFormatter::format — Format a number
  - NumberFormatter::formatCurrency — Format a currency value
  - NumberFormatter::getAttribute — Get an attribute
  - NumberFormatter::getErrorCode — Get formatter's last error code
  - NumberFormatter::getErrorMessage — Get formatter's last error message
  - NumberFormatter::getLocale — Get formatter locale
  - NumberFormatter::getPattern — Get formatter pattern
  - NumberFormatter::getSymbol — Get a symbol value
  - NumberFormatter::getTextAttribute — Get a text attribute
  - NumberFormatter::parse — Parse a number
  - NumberFormatter::parseCurrency — Parse a currency number
  - NumberFormatter::setAttribute — Set an attribute
  - NumberFormatter::setPattern — Set formatter pattern
  - NumberFormatter::setSymbol — Set a symbol value
  - NumberFormatter::setTextAttribute — Set a text attribute
- Locale — The Locale class
  - Locale::acceptFromHttp — Tries to find out best available locale based on HTTP "Accept-Language" header
  - Locale::canonicalize — Canonicalize the locale string
  - Locale::composeLocale — Returns a correctly ordered and delimited locale ID
  - Locale::filterMatches — Checks if a language tag filter matches with locale
  - Locale::getAllVariants — Gets the variants for the input locale
  - Locale::getDefault — Gets the default locale value from the INTL global 'default_locale'
  - Locale::getDisplayLanguage — Returns an appropriately localized display name for language of the inputlocale
  - Locale::getDisplayName — Returns an appropriately localized display name for the input locale
  - Locale::getDisplayRegion — Returns an appropriately localized display name for region of the input locale
  - Locale::getDisplayScript — Returns an appropriately localized display name for script of the input locale
  - Locale::getDisplayVariant — Returns an appropriately localized display name for variants of the input locale
  - Locale::getKeywords — Gets the keywords for the input locale
  - Locale::getPrimaryLanguage — Gets the primary language for the input locale
  - Locale::getRegion — Gets the region for the input locale
  - Locale::getScript — Gets the script for the input locale
  - Locale::isRightToLeft — Check whether a locale uses a right-to-left writing system
  - Locale::lookup — Searches the language tag list for the best match to the language
  - Locale::parseLocale — Returns a key-value array of locale ID subtag elements
  - Locale::setDefault — Sets the default runtime locale
- Normalizer — The Normalizer class
  - Normalizer::getRawDecomposition — Gets the Decomposition_Mapping property for the given UTF-8 encoded code point
  - Normalizer::isNormalized — Checks if the provided string is already in the specified normalization form
  - Normalizer::normalize — Normalizes the input provided and returns the normalized string
- MessageFormatter — The MessageFormatter class
  - MessageFormatter::create — Constructs a new Message Formatter
  - MessageFormatter::format — Format the message
  - MessageFormatter::formatMessage — Quick format message
  - MessageFormatter::getErrorCode — Get the error code from last operation
  - MessageFormatter::getErrorMessage — Get the error text from the last operation
  - MessageFormatter::getLocale — Get the locale for which the formatter was created
  - MessageFormatter::getPattern — Get the pattern used by the formatter
  - MessageFormatter::parse — Parse input string according to pattern
  - MessageFormatter::parseMessage — Quick parse input string
  - MessageFormatter::setPattern — Set the pattern used by the formatter
- IntlCalendar — The IntlCalendar class
  - IntlCalendar::add — Add a (signed) amount of time to a field
  - IntlCalendar::after — Whether this objectʼs time is after that of the passed object
  - IntlCalendar::before — Whether this objectʼs time is before that of the passed object
  - IntlCalendar::clear — Clear a field or all fields
  - IntlCalendar::__construct — Private constructor for disallowing instantiation
  - IntlCalendar::createInstance — Create a new IntlCalendar
  - IntlCalendar::equals — Compare time of two IntlCalendar objects for equality
  - IntlCalendar::fieldDifference — Calculate difference between given time and this objectʼs time
  - IntlCalendar::fromDateTime — Create an IntlCalendar from a DateTime object or string
  - IntlCalendar::get — Get the value for a field
  - IntlCalendar::getActualMaximum — The maximum value for a field, considering the objectʼs current time
  - IntlCalendar::getActualMinimum — The minimum value for a field, considering the objectʼs current time
  - IntlCalendar::getAvailableLocales — Get array of locales for which there is data
  - IntlCalendar::getDayOfWeekType — Tell whether a day is a weekday, weekend or a day that has a transition between the two
  - IntlCalendar::getErrorCode — Get last error code on the object
  - IntlCalendar::getErrorMessage — Get last error message on the object
  - IntlCalendar::getFirstDayOfWeek — Get the first day of the week for the calendarʼs locale
  - IntlCalendar::getGreatestMinimum — Get the largest local minimum value for a field
  - IntlCalendar::getKeywordValuesForLocale — Get set of locale keyword values
  - IntlCalendar::getLeastMaximum — Get the smallest local maximum for a field
  - IntlCalendar::getLocale — Get the locale associated with the object
  - IntlCalendar::getMaximum — Get the global maximum value for a field
  - IntlCalendar::getMinimalDaysInFirstWeek — Get minimal number of days the first week in a year or month can have
  - IntlCalendar::getMinimum — Get the global minimum value for a field
  - IntlCalendar::getNow — Get number representing the current time
  - IntlCalendar::getRepeatedWallTimeOption — Get behavior for handling repeating wall time
  - IntlCalendar::getSkippedWallTimeOption — Get behavior for handling skipped wall time
  - IntlCalendar::getTime — Get time currently represented by the object
  - IntlCalendar::getTimeZone — Get the objectʼs timezone
  - IntlCalendar::getType — Get the calendar type
  - IntlCalendar::getWeekendTransition — Get time of the day at which weekend begins or ends
  - IntlCalendar::inDaylightTime — Whether the objectʼs time is in Daylight Savings Time
  - IntlCalendar::isEquivalentTo — Whether another calendar is equal but for a different time
  - IntlCalendar::isLenient — Whether date/time interpretation is in lenient mode
  - IntlCalendar::isSet — Whether a field is set
  - IntlCalendar::isWeekend — Whether a certain date/time is in the weekend
  - IntlCalendar::roll — Add value to field without carrying into more significant fields
  - IntlCalendar::set — Set a time field or several common fields at once
  - IntlCalendar::setDate — Set a date fields
  - IntlCalendar::setDateTime — Set a date and time fields
  - IntlCalendar::setFirstDayOfWeek — Set the day on which the week is deemed to start
  - IntlCalendar::setLenient — Set whether date/time interpretation is to be lenient
  - IntlCalendar::setMinimalDaysInFirstWeek — Set minimal number of days the first week in a year or month can have
  - IntlCalendar::setRepeatedWallTimeOption — Set behavior for handling repeating wall times at negative timezone offset transitions
  - IntlCalendar::setSkippedWallTimeOption — Set behavior for handling skipped wall times at positive timezone offset transitions
  - IntlCalendar::setTime — Set the calendar time in milliseconds since the epoch
  - IntlCalendar::setTimeZone — Set the timezone used by this calendar
  - IntlCalendar::toDateTime — Convert an IntlCalendar into a DateTime object
- IntlGregorianCalendar — The IntlGregorianCalendar class
  - IntlGregorianCalendar::__construct — Create the Gregorian Calendar class
  - IntlGregorianCalendar::createFromDate — Create a new IntlGregorianCalendar instance from date
  - IntlGregorianCalendar::createFromDateTime — Create a new IntlGregorianCalendar instance from date and time
  - IntlGregorianCalendar::getGregorianChange — Get the Gregorian Calendar change date
  - IntlGregorianCalendar::isLeapYear — Determine if the given year is a leap year
  - IntlGregorianCalendar::setGregorianChange — Set the Gregorian Calendar the change date
- IntlTimeZone — The IntlTimeZone class
  - IntlTimeZone::__construct — Private constructor to disallow direct instantiation
  - IntlTimeZone::countEquivalentIDs — Get the number of IDs in the equivalency group that includes the given ID
  - IntlTimeZone::createDefault — Create a new copy of the default timezone for this host
  - IntlTimeZone::createEnumeration — Get an enumeration over time zone IDs associated with the given country or offset
  - IntlTimeZone::createTimeZone — Create a timezone object for the given ID
  - IntlTimeZone::createTimeZoneIDEnumeration — Get an enumeration over system time zone IDs with the given filter conditions
  - IntlTimeZone::fromDateTimeZone — Create a timezone object from DateTimeZone
  - IntlTimeZone::getCanonicalID — Get the canonical system timezone ID or the normalized custom time zone ID for the given time zone ID
  - IntlTimeZone::getDisplayName — Get a name of this time zone suitable for presentation to the user
  - IntlTimeZone::getDSTSavings — Get the amount of time to be added to local standard time to get local wall clock time
  - IntlTimeZone::getEquivalentID — Get an ID in the equivalency group that includes the given ID
  - IntlTimeZone::getErrorCode — Get last error code on the object
  - IntlTimeZone::getErrorMessage — Get last error message on the object
  - IntlTimeZone::getGMT — Create GMT (UTC) timezone
  - IntlTimeZone::getIanaID — Übersetzt einen Zeitzonen-Bezeichner in sein IANA-Äquivalent
  - IntlTimeZone::getID — Get timezone ID
  - IntlTimeZone::getIDForWindowsID — Translate a Windows timezone into a system timezone
  - IntlTimeZone::getOffset — Get the time zone raw and GMT offset for the given moment in time
  - IntlTimeZone::getRawOffset — Get the raw GMT offset (before taking daylight savings time into account
  - IntlTimeZone::getRegion — Get the region code associated with the given system time zone ID
  - IntlTimeZone::getTZDataVersion — Get the timezone data version currently used by ICU
  - IntlTimeZone::getUnknown — Get the "unknown" time zone
  - IntlTimeZone::getWindowsID — Translate a system timezone into a Windows timezone
  - IntlTimeZone::hasSameRules — Check if this zone has the same rules and offset as another zone
  - IntlTimeZone::toDateTimeZone — Convert to DateTimeZone object
  - IntlTimeZone::useDaylightTime — Check if this time zone uses daylight savings time
- IntlDateFormatter — The IntlDateFormatter class
  - IntlDateFormatter::create — Create a date formatter
  - IntlDateFormatter::format — Format the date/time value as a string
  - IntlDateFormatter::formatObject — Formats an object
  - IntlDateFormatter::getCalendar — Get the calendar type used for the IntlDateFormatter
  - IntlDateFormatter::getDateType — Get the datetype used for the IntlDateFormatter
  - IntlDateFormatter::getErrorCode — Get the error code from last operation
  - IntlDateFormatter::getErrorMessage — Get the error text from the last operation
  - IntlDateFormatter::getLocale — Get the locale used by formatter
  - IntlDateFormatter::getPattern — Get the pattern used for the IntlDateFormatter
  - IntlDateFormatter::getTimeType — Get the timetype used for the IntlDateFormatter
  - IntlDateFormatter::getTimeZoneId — Get the timezone-id used for the IntlDateFormatter
  - IntlDateFormatter::getCalendarObject — Get copy of formatterʼs calendar object
  - IntlDateFormatter::getTimeZone — Get formatterʼs timezone
  - IntlDateFormatter::isLenient — Get the lenient used for the IntlDateFormatter
  - IntlDateFormatter::localtime — Parse string to a field-based time value
  - IntlDateFormatter::parse — Parse string to a timestamp value
  - IntlDateFormatter::parseToCalendar — Parse a string into a timestamp, updating an open calendar
  - IntlDateFormatter::setCalendar — Sets the calendar type used by the formatter
  - IntlDateFormatter::setLenient — Set the leniency of the parser
  - IntlDateFormatter::setPattern — Set the pattern used for the IntlDateFormatter
  - IntlDateFormatter::setTimeZone — Sets formatterʼs timezone
- ResourceBundle — The ResourceBundle class
  - ResourceBundle::count — Get number of elements in the bundle
  - ResourceBundle::create — Create a resource bundle
  - ResourceBundle::get — Get data from the bundle
  - ResourceBundle::getErrorCode — Get bundle's last error code
  - ResourceBundle::getErrorMessage — Get bundle's last error message
  - ResourceBundle::getLocales — Get supported locales
- Spoofchecker — The Spoofchecker class
  - Spoofchecker::areConfusable — Checks if given strings can be confused
  - Spoofchecker::__construct — Constructor
  - Spoofchecker::isSuspicious — Checks if a given text contains any suspicious characters
  - Spoofchecker::setAllowedChars — Set the set of characters allowed when running checks
  - Spoofchecker::setAllowedLocales — Locales to use when running checks
  - Spoofchecker::setChecks — Set the checks to run
  - Spoofchecker::setRestrictionLevel — Set the restriction level
- Transliterator — The Transliterator class
  - Transliterator::__construct — Private constructor to deny instantiation
  - Transliterator::create — Create a transliterator
  - Transliterator::createFromRules — Create transliterator from rules
  - Transliterator::createInverse — Create an inverse transliterator
  - Transliterator::getErrorCode — Get last error code
  - Transliterator::getErrorMessage — Get last error message
  - Transliterator::listIDs — Get transliterator IDs
  - Transliterator::transliterate — Transliterate a string
- IntlBreakIterator — The IntlBreakIterator class
  - IntlBreakIterator::__construct — Private constructor for disallowing instantiation
  - IntlBreakIterator::createCharacterInstance — Create break iterator for boundaries of combining character sequences
  - IntlBreakIterator::createCodePointInstance — Create break iterator for boundaries of code points
  - IntlBreakIterator::createLineInstance — Create break iterator for logically possible line breaks
  - IntlBreakIterator::createSentenceInstance — Create break iterator for sentence breaks
  - IntlBreakIterator::createTitleInstance — Create break iterator for title-casing breaks
  - IntlBreakIterator::createWordInstance — Create break iterator for word breaks
  - IntlBreakIterator::current — Get index of current position
  - IntlBreakIterator::first — Set position to the first character in the text
  - IntlBreakIterator::following — Advance the iterator to the first boundary following specified offset
  - IntlBreakIterator::getErrorCode — Get last error code on the object
  - IntlBreakIterator::getErrorMessage — Get last error message on the object
  - IntlBreakIterator::getLocale — Get the locale associated with the object
  - IntlBreakIterator::getPartsIterator — Create iterator for navigating fragments between boundaries
  - IntlBreakIterator::getText — Get the text being scanned
  - IntlBreakIterator::isBoundary — Tell whether an offset is a boundaryʼs offset
  - IntlBreakIterator::last — Set the iterator position to index beyond the last character
  - IntlBreakIterator::next — Advance the iterator the next boundary
  - IntlBreakIterator::preceding — Set the iterator position to the first boundary before an offset
  - IntlBreakIterator::previous — Set the iterator position to the boundary immediately before the current
  - IntlBreakIterator::setText — Set the text being scanned
- IntlRuleBasedBreakIterator — The IntlRuleBasedBreakIterator class
  - IntlRuleBasedBreakIterator::__construct — Create iterator from ruleset
  - IntlRuleBasedBreakIterator::getBinaryRules — Get the binary form of compiled rules
  - IntlRuleBasedBreakIterator::getRules — Get the rule set used to create this object
  - IntlRuleBasedBreakIterator::getRuleStatus — Get the largest status value from the break rules that determined the current break position
  - IntlRuleBasedBreakIterator::getRuleStatusVec — Get the status values from the break rules that determined the current break position
- IntlCodePointBreakIterator — The IntlCodePointBreakIterator class
  - IntlCodePointBreakIterator::getLastCodePoint — Get last code point passed over after advancing or receding the iterator
- IntlDatePatternGenerator — The IntlDatePatternGenerator class
  - IntlDatePatternGenerator::create — Creates a new IntlDatePatternGenerator instance
  - IntlDatePatternGenerator::getBestPattern — Bestimmt das am besten geeignete Datums-/Zeitformat
- IntlPartsIterator — The IntlPartsIterator class
  - IntlPartsIterator::getBreakIterator — Get IntlBreakIterator backing this parts iterator
- UConverter — Die Klasse UConverter
  - UConverter::__construct — Create UConverter object
  - UConverter::convert — Convert string from one charset to another
  - UConverter::fromUCallback — Default "from" callback function
  - UConverter::getAliases — Get the aliases of the given name
  - UConverter::getAvailable — Get the available canonical converter names
  - UConverter::getDestinationEncoding — Get the destination encoding
  - UConverter::getDestinationType — Get the destination converter type
  - UConverter::getErrorCode — Get last error code on the object
  - UConverter::getErrorMessage — Get last error message on the object
  - UConverter::getSourceEncoding — Get the source encoding
  - UConverter::getSourceType — Get the source converter type
  - UConverter::getStandards — Get standards associated to converter names
  - UConverter::getSubstChars — Get substitution chars
  - UConverter::reasonText — Get string representation of the callback reason
  - UConverter::setDestinationEncoding — Set the destination encoding
  - UConverter::setSourceEncoding — Set the source encoding
  - UConverter::setSubstChars — Set the substitution chars
  - UConverter::toUCallback — Default "to" callback function
  - UConverter::transcode — Convert a string from one character encoding to another
- Grapheme Funktionen
  - grapheme_extract — Function to extract a sequence of default grapheme clusters from a text buffer, which must be encoded in UTF-8
  - grapheme_str_split — Split a string into an array
  - grapheme_stripos — Find position (in grapheme units) of first occurrence of a case-insensitive string
  - grapheme_stristr — Returns part of haystack string from the first occurrence of case-insensitive needle to the end of haystack
  - grapheme_strlen — Get string length in grapheme units
  - grapheme_strpos — Find position (in grapheme units) of first occurrence of a string
  - grapheme_strripos — Find position (in grapheme units) of last occurrence of a case-insensitive string
  - grapheme_strrpos — Find position (in grapheme units) of last occurrence of a string
  - grapheme_strstr — Returns part of haystack string from the first occurrence of needle to the end of haystack
  - grapheme_substr — Return part of a string
- IDN Funktionen
  - idn_to_ascii — Convert domain name to IDNA ASCII form
  - idn_to_utf8 — Convert domain name from IDNA ASCII to Unicode
- IntlChar
  - IntlChar::charAge — Get the "age" of the code point
  - IntlChar::charDigitValue — Get the decimal digit value of a decimal digit character
  - IntlChar::charDirection — Get bidirectional category value for a code point
  - IntlChar::charFromName — Find Unicode character by name and return its code point value
  - IntlChar::charMirror — Get the "mirror-image" character for a code point
  - IntlChar::charName — Retrieve the name of a Unicode character
  - IntlChar::charType — Get the general category value for a code point
  - IntlChar::chr — Return Unicode character by code point value
  - IntlChar::digit — Get the decimal digit value of a code point for a given radix
  - IntlChar::enumCharNames — Enumerate all assigned Unicode characters within a range
  - IntlChar::enumCharTypes — Enumerate all code points with their Unicode general categories
  - IntlChar::foldCase — Perform case folding on a code point
  - IntlChar::forDigit — Get character representation for a given digit and radix
  - IntlChar::getBidiPairedBracket — Get the paired bracket character for a code point
  - IntlChar::getBlockCode — Get the Unicode allocation block containing a code point
  - IntlChar::getCombiningClass — Get the combining class of a code point
  - IntlChar::getFC_NFKC_Closure — Get the FC_NFKC_Closure property for a code point
  - IntlChar::getIntPropertyMaxValue — Get the max value for a Unicode property
  - IntlChar::getIntPropertyMinValue — Get the min value for a Unicode property
  - IntlChar::getIntPropertyValue — Get the value for a Unicode property for a code point
  - IntlChar::getNumericValue — Get the numeric value for a Unicode code point
  - IntlChar::getPropertyEnum — Get the property constant value for a given property name
  - IntlChar::getPropertyName — Get the Unicode name for a property
  - IntlChar::getPropertyValueEnum — Get the property value for a given value name
  - IntlChar::getPropertyValueName — Get the Unicode name for a property value
  - IntlChar::getUnicodeVersion — Get the Unicode version
  - IntlChar::hasBinaryProperty — Check a binary Unicode property for a code point
  - IntlChar::isalnum — Check if code point is an alphanumeric character
  - IntlChar::isalpha — Check if code point is a letter character
  - IntlChar::isbase — Check if code point is a base character
  - IntlChar::isblank — Check if code point is a "blank" or "horizontal space" character
  - IntlChar::iscntrl — Check if code point is a control character
  - IntlChar::isdefined — Check whether the code point is defined
  - IntlChar::isdigit — Check if code point is a digit character
  - IntlChar::isgraph — Check if code point is a graphic character
  - IntlChar::isIDIgnorable — Check if code point is an ignorable character
  - IntlChar::isIDPart — Check if code point is permissible in an identifier
  - IntlChar::isIDStart — Check if code point is permissible as the first character in an identifier
  - IntlChar::isISOControl — Check if code point is an ISO control code
  - IntlChar::isJavaIDPart — Check if code point is permissible in a Java identifier
  - IntlChar::isJavaIDStart — Check if code point is permissible as the first character in a Java identifier
  - IntlChar::isJavaSpaceChar — Check if code point is a space character according to Java
  - IntlChar::islower — Check if code point is a lowercase letter
  - IntlChar::isMirrored — Check if code point has the Bidi_Mirrored property
  - IntlChar::isprint — Check if code point is a printable character
  - IntlChar::ispunct — Check if code point is punctuation character
  - IntlChar::isspace — Check if code point is a space character
  - IntlChar::istitle — Check if code point is a titlecase letter
  - IntlChar::isUAlphabetic — Check if code point has the Alphabetic Unicode property
  - IntlChar::isULowercase — Check if code point has the Lowercase Unicode property
  - IntlChar::isupper — Check if code point has the general category "Lu" (uppercase letter)
  - IntlChar::isUUppercase — Check if code point has the Uppercase Unicode property
  - IntlChar::isUWhiteSpace — Check if code point has the White_Space Unicode property
  - IntlChar::isWhitespace — Check if code point is a whitespace character according to ICU
  - IntlChar::isxdigit — Check if code point is a hexadecimal digit
  - IntlChar::ord — Return Unicode code point value of character
  - IntlChar::tolower — Make Unicode character lowercase
  - IntlChar::totitle — Make Unicode character titlecase
  - IntlChar::toupper — Make Unicode character uppercase
- IntlException — Exception class for intl errors
- IntlIterator — The IntlIterator class
  - IntlIterator::current — Get the current element
  - IntlIterator::key — Get the current key
  - IntlIterator::next — Move forward to the next element
  - IntlIterator::rewind — Rewind the iterator to the first element
  - IntlIterator::valid — Check if current position is valid
- intl Funktionen
  - intl_error_name — Get symbolic name for a given error code
  - intl_get_error_code — Get the last error code
  - intl_get_error_message — Get description of the last error
  - intl_is_failure — Check whether the given error code indicates failure

# Multibyte String

# Einführung

While there are many languages in which every necessary character can be represented by a one-to-one mapping to an 8-bit value, there are also several languages which require so many characters for written communication that they cannot be contained within the range a mere byte can code (A byte is made up of eight bits. Each bit can contain only two distinct values, one or zero. Because of this, a byte can only represent 256 unique values (two to the power of eight)). Multibyte character encoding schemes were developed to express more than 256 characters in the regular bytewise coding system.

When you manipulate (trim, split, splice, etc.) strings encoded in a multibyte encoding, you need to use special functions since two or more consecutive bytes may represent a single character in such encoding schemes. Otherwise, if you apply a non-multibyte-aware string function to the string, it probably fails to detect the beginning or ending of the multibyte character and ends up with a corrupted garbage string that most likely loses its original meaning.

`mbstring` provides multibyte specific string functions that help you deal with multibyte encodings in PHP. In addition to that, `mbstring` handles character encoding conversion between the possible encoding pairs. `mbstring` is designed to handle Unicode-based encodings such as UTF-8 and UCS-2 and many single-byte encodings for convenience (listed in Supported Character Encodings).

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Laufzeit-Konfiguration

## Installation

`mbstring` is a non-default extension. This means it is not enabled by default. You must explicitly enable the module with the `configure` option. See the Install section for details.

The following configure options are related to the `mbstring` module.

- --enable-mbstring: Enable `mbstring` functions. This option is required to use `mbstring` functions.

  libmbfl is necessary for `mbstring`. libmbfl is bundled with `mbstring`. Prior to PHP 7.3.0, if libmbfl is already installed on the system, --with-libmbfl[=DIR] can be specified to use the installed library.

- --disable-mbregex: Disable regular expression functions with multibyte character support.

  Oniguruma is necessary for the regular expression functions with multibyte character support. As of PHP 7.4.0, pkg-config is used to detect the libonig library. Prior to PHP 7.4.0, Oniguruma was bundled with `mbstring`, but it was possible to build against an already installed libonig by passing --with-onig[=DIR].

  It is possible to disable the multibyte regex backtrack check by specifying --disable-mbregex-backtrack.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

mbstring configuration options
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
mbstring.language | "neutral" | `INI_ALL` |
mbstring.detect_order | NULL | `INI_ALL` |
mbstring.http_input | "pass" | `INI_ALL` | Deprecated
mbstring.http_output | "pass" | `INI_ALL` | Deprecated
mbstring.internal_encoding | NULL | `INI_ALL` | Deprecated
mbstring.substitute_character | NULL | `INI_ALL` |
mbstring.func_overload | "0" | `INI_SYSTEM` | Deprecated as of PHP 7.2.0; removed as of PHP 8.0.0.
mbstring.encoding_translation | "0" | `INI_PERDIR` |
mbstring.http_output_conv_mimetypes | "^(text/|application/xhtml\+xml)" | `INI_ALL` |
mbstring.strict_detection | "0" | `INI_ALL` |
mbstring.regex_retry_limit | "1000000" | `INI_ALL` | Available as of PHP 7.4.0.
mbstring.regex_stack_limit | "100000" | `INI_ALL` | Available as of PHP 7.3.5.

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`mbstring.language` string

  The default national language setting (NLS) used in mbstring. Note that this option automagically defines `mbstring.internal_encoding` and `mbstring.internal_encoding` should be placed after `mbstring.language` in php.ini

`mbstring.encoding_translation` bool

  Enables the transparent character encoding filter for the incoming HTTP queries, which performs detection and conversion of the input encoding to the internal character encoding.

`mbstring.internal_encoding` string
  Warnung

  Dieses veraltete Feature wird in der Zukunft sicherlich entfernt.

  Defines the default internal character encoding.

  Users should leave this empty and set `default_charset` instead.

`mbstring.http_input` string
  Warnung

  Dieses veraltete Feature wird in der Zukunft sicherlich entfernt.

  Defines the default HTTP input character encoding.

  Users should leave this empty and set `default_charset` instead.

`mbstring.http_output` string
  Warnung

  Dieses veraltete Feature wird in der Zukunft sicherlich entfernt.

  Defines the default HTTP output character encoding (output will be converted from the internal encoding to the HTTP output encoding upon output).

  Users should leave this empty and set `default_charset` instead.

`mbstring.detect_order` string

  Defines default character code detection order. See also mb_detect_order().

`mbstring.substitute_character` string

  Defines character to substitute for invalid character encoding. See mb_substitute_character() for supported values.

`mbstring.func_overload` string
  Warnung

  Dieses Feature ist seit PHP 7.2.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieses Features wird dringend abgeraten.

  Overloads a set of single byte functions by the mbstring counterparts. See Function overloading for more information.

  This setting can only be changed from the php.ini file.

`mbstring.http_output_conv_mimetypes` string

`mbstring.strict_detection` bool

  Enables strict encoding detection. See mb_detect_encoding() for a description and examples.

`mbstring.regex_retry_limit` int

  Limits the amount of backtracking that may be performed during one mbregex match.

  This setting only takes effect when linking against oniguruma >= 6.8.0.

`mbstring.regex_stack_limit` int

  Limits the stack depth of mbstring regular expressions.

According to the » HTML 4.01 specification, Web browsers are allowed to encode a form being submitted with a character encoding different from the one used for the page. See mb_http_input() to detect character encoding used by browsers.

Although popular browsers are capable of giving a reasonably accurate guess to the character encoding of a given HTML document, it would be better to set the `charset` parameter in the `Content-Type` HTTP header to the appropriate value by header() or default_charset ini setting.

Beispiel #1 php.ini setting examples

    ; Set default language
    mbstring.language        = Neutral; Set default language to Neutral(UTF-8) (default)
    mbstring.language        = English; Set default language to English
    mbstring.language        = Japanese; Set default language to Japanese

    ;; Set default internal encoding
    ;; Note: Make sure to use character encoding works with PHP
    mbstring.internal_encoding    = UTF-8  ; Set internal encoding to UTF-8

    ;; HTTP input encoding translation is enabled.
    mbstring.encoding_translation = On

    ;; Set default HTTP input character encoding
    ;; Note: Script cannot change http_input setting.
    mbstring.http_input           = pass    ; No conversion.
    mbstring.http_input           = auto    ; Set HTTP input to auto
                                    ; "auto" is expanded according to mbstring.language
    mbstring.http_input           = SJIS    ; Set HTTP input to SJIS
    mbstring.http_input           = UTF-8,SJIS,EUC-JP ; Specify order

    ;; Set default HTTP output character encoding
    mbstring.http_output          = pass    ; No conversion
    mbstring.http_output          = UTF-8   ; Set HTTP output encoding to UTF-8

    ;; Set default character encoding detection order
    mbstring.detect_order         = auto    ; Set detect order to auto
    mbstring.detect_order         = ASCII,JIS,UTF-8,SJIS,EUC-JP ; Specify order

    ;; Set default substitute character
    mbstring.substitute_character = 12307   ; Specify Unicode value
    mbstring.substitute_character = none    ; Do not print character
    mbstring.substitute_character = long    ; Long Example: U+3000,JIS+7E7E

Beispiel #2 php.ini setting for `EUC-JP` users

    ;; Disable Output Buffering
    output_buffering      = Off

    ;; Set HTTP header charset
    default_charset       = EUC-JP

    ;; Set default language to Japanese
    mbstring.language = Japanese

    ;; HTTP input encoding translation is enabled.
    mbstring.encoding_translation = On

    ;; Set HTTP input encoding conversion to auto
    mbstring.http_input   = auto

    ;; Convert HTTP output to EUC-JP
    mbstring.http_output  = EUC-JP

    ;; Set internal encoding to EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; Do not print invalid characters
    mbstring.substitute_character = none

Beispiel #3 php.ini setting for `SJIS` users

    ;; Enable Output Buffering
    output_buffering     = On

    ;; Set mb_output_handler to enable output conversion
    output_handler       = mb_output_handler

    ;; Set HTTP header charset
    default_charset      = Shift_JIS

    ;; Set default language to Japanese
    mbstring.language = Japanese

    ;; Set http input encoding conversion to auto
    mbstring.http_input  = auto

    ;; Convert to SJIS
    mbstring.http_output = SJIS

    ;; Set internal encoding to EUC-JP
    mbstring.internal_encoding = EUC-JP

    ;; Do not print invalid characters
    mbstring.substitute_character = none

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`MB_OVERLOAD_MAIL` (int)
  Removed as of PHP 8.0.0.
`MB_OVERLOAD_STRING` (int)
  Removed as of PHP 8.0.0.
`MB_OVERLOAD_REGEX` (int)
  Removed as of PHP 8.0.0.
`MB_CASE_UPPER` (int)
  Performs a full upper-case folding. This may change the length of the string. This is the mode used by mb_strtoupper().
`MB_CASE_LOWER` (int)
  Performs a full lower-case folding. This may change the length of the string. This is the mode used by mb_strtolower().
`MB_CASE_TITLE` (int)
  Performs a full title-case conversion based on the Cased and CaseIgnorable derived Unicode properties. In particular this improves handling of quotes and apostrophes. This may change the length of the string.
`MB_CASE_FOLD` (int)
  Performs a full case fold conversion which removes case distinctions present in the string. This is used for caseless matching. This may change the length of the string. Available since PHP 7.3.
`MB_CASE_LOWER_SIMPLE` (int)
  Performs a simple lower-case fold conversion. This does not change the length of the string. Available as of PHP 7.3.
`MB_CASE_UPPER_SIMPLE` (int)
  Performs simple upper-case fold conversion. This does not change the length of the string. Available as of PHP 7.3.
`MB_CASE_TITLE_SIMPLE` (int)
  Performs simple title-case fold conversion. This does not change the length of the string. Available as of PHP 7.3.
`MB_CASE_FOLD_SIMPLE` (int)
  Performs a simple case fold conversion which removes case distinctions present in the string. This is used for caseless matching. This does not change the length of the string. Used by case-insensitive operations internally by the MBString extension. Available as of PHP 7.3.
`MB_ONIGURUMA_VERSION` (string)
  The Oniguruma version, e.g. `6.9.4`. Available as of PHP 7.4.

# Summaries of supported encodings

Summaries of supported encodings
Name in the IANA character set registry | Underlying character set | Description | Additional note
--- | --- | --- | ---
ISO-10646-UCS-4 | ISO 10646 | The Universal Character Set with 31-bit code space, standardized as UCS-4 by ISO/IEC 10646. It is kept synchronized with the latest version of the Unicode code map. | If this name is used in the encoding conversion facility, the converter attempts to identify by the preceding BOM (byte order mark)in which endian the subsequent bytes are represented.
ISO-10646-UCS-4 | UCS-4 | See above. | In contrast to `UCS-4`, strings are always assumed to be in big endian form.
ISO-10646-UCS-4 | UCS-4 | See above. | In contrast to `UCS-4`, strings are always assumed to be in little endian form.
ISO-10646-UCS-2 | UCS-2 | The Universal Character Set with 16-bit code space, standardized as UCS-2 by ISO/IEC 10646. It is kept synchronized with the latest version of the unicode code map. | If this name is used in the encoding conversion facility, the converter attempts to identify by the preceding BOM (byte order mark)in which endian the subsequent bytes are represented.
ISO-10646-UCS-2 | UCS-2 | See above. | In contrast to `UCS-2`, strings are always assumed to be in big endian form.
ISO-10646-UCS-2 | UCS-2 | See above. | In contrast to `UCS-2`, strings are always assumed to be in little endian form.
UTF-32 | Unicode | Unicode Transformation Format of 32-bit unit width, whose encoding space refers to the Unicode's codeset standard. This encoding scheme wasn't identical to UCS-4 because the code space of Unicode were limited to a 21-bit value. | If this name is used in the encoding conversion facility, the converter attempts to identify by the preceding BOM (byte order mark)in which endian the subsequent bytes are represented.
UTF-32BE | Unicode | See above | In contrast to `UTF-32`, strings are always assumed to be in big endian form.
UTF-32LE | Unicode | See above | In contrast to `UTF-32`, strings are always assumed to be in little endian form.
UTF-16 | Unicode | Unicode Transformation Format of 16-bit unit width. It's worth a note that UTF-16 is no longer the same specification as UCS-2 because the surrogate mechanism has been introduced since Unicode 2.0 and UTF-16 now refers to a 21-bit code space. | If this name is used in the encoding conversion facility, the converter attempts to identify by the preceding BOM (byte order mark)in which endian the subsequent bytes are represented.
UTF-16BE | Unicode | See above. | In contrast to `UTF-16`, strings are always assumed to be in big endian form.
UTF-16LE | Unicode | See above. | In contrast to `UTF-16`, strings are always assumed to be in little endian form.
UTF-8 | Unicode / UCS | Unicode Transformation Format of 8-bit unit width. | none
UTF-7 | Unicode | A mail-safe transformation format of Unicode, specified in » RFC2152. | none
(none) | Unicode | A variant of UTF-7 which is specialized for use in the » IMAP protocol. | none
US-ASCII (preferred MIME name) / iso-ir-6 / ANSI_X3.4-1986 / ISO_646.irv:1991 / ASCII / ISO646-US / us / IBM367 / CP367 / csASCII | ASCII / ISO 646 | American Standard Code for Information Interchange is a commonly-used 7-bit encoding. Also standardized as an international standard, ISO 646. | (none)
EUC-JP (preferred MIME name) / Extended_UNIX_Code_Packed_Format_for_Japanese / csEUCPkdFmtJapanese | Compound of US-ASCII / JIS X0201:1997 (hankaku kana part) / JIS X0208:1990 / JIS X0212:1990 | As you see the name is derived from an abbreviation of Extended UNIX Code Packed Format for Japanese, this encoding is mostly used on UNIX or alike platforms. The original encoding scheme, Extended UNIX Code, is designed on the basis of ISO 2022. | The character set referred to by EUC-JP is different to IBM932 / CP932, which are used by OS/2® and Microsoft® Windows®. For information interchange with those platforms, use EUCJP-WIN instead.
Shift_JIS (preferred MIME name) / MS_Kanji / csShift_JIS | Compound of JIS X0201:1997 / JIS X0208:1997 | Shift_JIS was developed in early 80's, at the time personal Japanese word processors were brought into the market, in order to maintain compatibilities with the legacy encoding scheme JIS X 0201:1976. According to the IANA definition the codeset of Shift_JIS is slightly different to IBM932 / CP932. However, the names "SJIS" / "Shift_JIS" are often wrongly used to refer to these codesets. | For the CP932 codemap, use SJIS-WIN instead.
(none) | Compound of JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions | While this "encoding" uses the same encoding scheme as EUC-JP, the underlying character set is different. That is, some code points map to different characters than EUC-JP. | none
Windows-31J / csWindows31J | Compound of JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions | While this "encoding" uses the same encoding scheme as Shift_JIS, the underlying character set is different. That means some code points map to different characters than Shift_JIS. | (none)
ISO-2022-JP (preferred MIME name) / csISO2022JP | US-ASCII / JIS X0201:1976 / JIS X0208:1978 / JIS X0208:1983 | » RFC1468 | (none)
JIS |  |  |
ISO-8859-1 |  |  |
ISO-8859-2 |  |  |
ISO-8859-3 |  |  |
ISO-8859-4 |  |  |
ISO-8859-5 |  |  |
ISO-8859-6 |  |  |
ISO-8859-7 |  |  |
ISO-8859-8 |  |  |
ISO-8859-9 |  |  |
ISO-8859-10 |  |  |
ISO-8859-13 |  |  |
ISO-8859-14 |  |  |
ISO-8859-15 |  |  |
ISO-8859-16 |  |  |
byte2be |  |  |
byte2le |  |  |
byte4be |  |  |
byte4le |  |  |
BASE64 |  |  |
HTML-ENTITIES |  |  |
7bit |  |  |
8bit |  |  |
EUC-CN |  |  |
CP936 |  |  |
HZ |  |  |
EUC-TW |  |  |
CP950 |  |  |
BIG-5 |  |  |
EUC-KR |  |  |
UHC (CP949) |  |  |
ISO-2022-KR |  |  |
Windows-1251 (CP1251) |  |  |
Windows-1252 (CP1252) |  |  |
CP866 (IBM866) |  |  |
KOI8-R |  |  |
KOI8-U |  |  |

# Basics of Japanese multi-byte encodings

Japanese characters can only be represented by multibyte encodings, and multiple encoding standards are used depending on platform and text purpose. To make matters worse, these encoding standards differ slightly from one another. In order to create a web application which would be usable in a Japanese environment, a developer has to keep these complexities in mind to ensure that the proper character encodings are used.

- Storage for a character can be up to six bytes
- Most Japanese multibyte characters appear twice as wide as single-byte characters. These characters are called "zen-kaku" in Japanese, which means "full width". Other, narrower, characters are called "han-kaku", which means "half width". The graphical properties of the characters, however, depends upon the type faces used to display them.
- Some character encodings use shift(escape) sequences defined in ISO-2022 to switch the code map of the specific code area (`00h` to `7fh`).
- ISO-2022-JP should be used in SMTP/NNTP, and headers and entities should be reencoded as per RFC requirements. Although those are not requisites, it's still a good idea because several popular user agents cannot recognize any other encoding methods.
- Web pages created for mobile phone services such as » i-mode or » EZweb are supposed to use Shift_JIS.
- Emoji used for mobile phone service such as » i-mode or » EZweb are supported.

# HTTP Input and Output

HTTP input/output character encoding conversion may convert binary data also. Users are supposed to control character encoding conversion if binary data is used for HTTP input/output.

> Hinweis:

> If `enctype` for HTML form is set to `multipart/form-data` and `mbstring.encoding_translation` is set to On in php.ini the POST'ed variables and the names of uploaded files will be converted to the internal character encoding as well. However, the conversion isn't applied to the query keys.

- HTTP Input

  There is no way to control HTTP input character conversion from a PHP script. To disable HTTP input character conversion, it has to be done in php.ini.

  Beispiel #1 Disable HTTP input conversion in php.ini

      ;; Disable HTTP Input conversion
      mbstring.http_input = pass
      ;; Disable HTTP Input conversion
      mbstring.encoding_translation = Off

  When using PHP as an Apache module, it is possible to override those settings in each Virtual Host directive in httpd.conf or per directory with .htaccess. Refer to the Configuration section and Apache Manual for details.

- HTTP Output

  There are several ways to enable output character encoding conversion. One is using php.ini, another is using ob_start() with mb_output_handler() as the `ob_start` callback function.

Beispiel #2 php.ini setting example

    ;; Enable output character encoding conversion for all PHP pages

    ;; Enable Output Buffering
    output_buffering    = On

    ;; Set mb_output_handler to enable output conversion
    output_handler      = mb_output_handler

Beispiel #3 Script example

    <?php

    // Enable output character encoding conversion only for this page

    // Set HTTP output character encoding to SJIS
    mb_http_output('SJIS');

    // Start buffering and specify "mb_output_handler" as
    // callback function
    ob_start('mb_output_handler');

    ?>

# Supported Character Encodings

Currently the following character encodings are supported by the `mbstring` module. Any of those Character encodings can be specified in the `encoding` parameter of `mbstring` functions.

The following character encodings are supported in this PHP extension:

- UCS-4*
- UCS-4BE
- UCS-4LE*
- UCS-2
- UCS-2BE
- UCS-2LE
- UTF-32*
- UTF-32BE*
- UTF-32LE*
- UTF-16*
- UTF-16BE*
- UTF-16LE*
- UTF-7
- UTF7-IMAP
- UTF-8*
- ASCII*
- EUC-JP*
- SJIS*
- eucJP-win*
- SJIS-win*
- ISO-2022-JP
- ISO-2022-JP-MS
- CP932
- CP51932
- SJIS-mac (alias: MacJapanese)
- SJIS-Mobile#DOCOMO (alias: SJIS-DOCOMO)
- SJIS-Mobile#KDDI (alias: SJIS-KDDI)
- SJIS-Mobile#SOFTBANK (alias: SJIS-SOFTBANK)
- UTF-8-Mobile#DOCOMO (alias: UTF-8-DOCOMO)
- UTF-8-Mobile#KDDI-A
- UTF-8-Mobile#KDDI-B (alias: UTF-8-KDDI)
- UTF-8-Mobile#SOFTBANK (alias: UTF-8-SOFTBANK)
- ISO-2022-JP-MOBILE#KDDI (alias: ISO-2022-JP-KDDI)
- JIS
- JIS-ms
- CP50220
- CP50220raw
- CP50221
- CP50222
- ISO-8859-1*
- ISO-8859-2*
- ISO-8859-3*
- ISO-8859-4*
- ISO-8859-5*
- ISO-8859-6*
- ISO-8859-7*
- ISO-8859-8*
- ISO-8859-9*
- ISO-8859-10*
- ISO-8859-13*
- ISO-8859-14*
- ISO-8859-15*
- ISO-8859-16*
- byte2be
- byte2le
- byte4be
- byte4le
- BASE64
- HTML-ENTITIES (alias: HTML)
- 7bit
- 8bit
- EUC-CN*
- CP936
- GB18030
- HZ
- EUC-TW*
- CP950
- BIG-5*
- EUC-KR*
- UHC (alias: CP949)
- ISO-2022-KR
- Windows-1251 (alias: CP1251)
- Windows-1252 (alias: CP1252)
- CP866 (alias: IBM866)
- KOI8-R*
- KOI8-U*
- ArmSCII-8 (alias: ArmSCII8)

* denotes encodings usable also in regular expressions.

Any php.ini entry which accepts an encoding name can also use the values "`auto`" and "`pass`". `mbstring` functions which accept an encoding name can also use the value "`auto`".

If "`pass`" is set, no character encoding conversion is performed.

If "`auto`" is set, it is expanded to the list of encodings defined per the NLS. For instance, if the NLS is set to `Japanese`, the value is assumed to be "`ASCII,JIS,UTF-8,EUC-JP,SJIS`".

See also mb_detect_order()

# Function Overloading Feature

Warnung

Dieses Feature ist seit PHP 7.2.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieses Features wird dringend abgeraten.

You might often find it difficult to get an existing PHP application to work in a given multibyte environment. This happens because most PHP applications out there are written with the standard string functions such as substr(), which are known to not properly handle multibyte-encoded strings.

mbstring supports a 'function overloading' feature which enables you to add multibyte awareness to such an application without code modification by overloading multibyte counterparts on the standard string functions. For example, mb_substr() is called instead of substr() if function overloading is enabled. This feature makes it easy to port applications that only support single-byte encodings to a multibyte environment in many cases.

To use function overloading, set `mbstring.func_overload` in php.ini to a positive value that represents a combination of bitmasks specifying the categories of functions to be overloaded. It should be set to 1 to overload the mail() function. 2 for string functions, 4 for regular expression functions. For example, if it is set to 7, mail, strings and regular expression functions will be overloaded. The list of overloaded functions are shown below.

Functions to be overloaded
value of mbstring.func_overload | original function | overloaded function
--- | --- | ---
1 | mail() | mb_send_mail()
2 | strlen() | mb_strlen()
2 | strpos() | mb_strpos()
2 | strrpos() | mb_strrpos()
2 | substr() | mb_substr()
2 | strtolower() | mb_strtolower()
2 | strtoupper() | mb_strtoupper()
2 | stripos() | mb_stripos()
2 | strripos() | mb_strripos()
2 | strstr() | mb_strstr()
2 | stristr() | mb_stristr()
2 | strrchr() | mb_strrchr()
2 | substr_count() | mb_substr_count()

> Hinweis:

> It is not recommended to use the function overloading option in the per-directory context, because it's not confirmed yet to be stable enough in a production environment and may lead to undefined behaviour.

# PHP Character Encoding Requirements

Encodings of the following types are safely used with PHP.

- A singlebyte encoding,

  - which has ASCII-compatible (ISO646 compatible) mappings for the characters in range of `00h` to `7fh`.

- A multibyte encoding,

  - which has ASCII-compatible mappings for the characters in range of `00h` to `7fh`.
  - which don't use ISO2022 escape sequences.
  - which don't use a value from `00h` to `7fh` in any of the compounded bytes that represents a single character.

These are examples of character encodings that are unlikely to work with PHP.

    JIS, SJIS, ISO-2022-JP, BIG-5

Although PHP scripts written in any of those encodings might not work, especially in the case where encoded strings appear as identifiers or literals in the script, you can almost avoid using these encodings by setting up the `mbstring`'s transparent encoding filter function for incoming HTTP queries.

> Hinweis:

> It's highly discouraged to use SJIS, BIG5, CP936, CP949 and GB18030 for the internal encoding unless you are familiar with the parser, the scanner and the character encoding.

> Hinweis:

> If you are connecting to a database with PHP, it is recommended that you use the same character encoding for both the database and the `internal encoding` for ease of use and better performance.

> If you are using PostgreSQL, the character encoding used in the database and the one used in PHP may differ as it supports automatic character set conversion between the backend and the frontend.

# Multibyte String Funktionen

# References

Multibyte character encoding schemes and their related issues are fairly complicated, and are beyond the scope of this documentation. Please refer to the following URLs and other resources for further information regarding these topics.

- Unicode materials

  » http://www.unicode.org/

- Japanese/Korean/Chinese character information

  » https://resources.oreilly.com/examples/9781565922242/blob/master/doc/cjk.inf

# mb_check_encoding

(PHP 4 >= 4.4.3, PHP 5 >= 5.1.3, PHP 7, PHP 8)

mb_check_encoding — Check if strings are valid for the specified encoding

### Beschreibung

function mb_check_encoding(array|string|null `$value` = `null`, ?string `$encoding` = `null`): bool

Checks if the specified byte stream is valid for the specified encoding. If `value` is of type Array, all keys and values are validated recursively. It is useful to prevent so-called "Invalid Encoding Attack".

### Parameter-Liste

`value`

  The byte stream or Array to check. If it is omitted, this function checks all the input from the beginning of the request.

  Warnung

  As of PHP 8.1.0, omitting this parameter or passing `null` is deprecated.

`encoding`

  The expected encoding.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Calling this function with `null` as `value` or without argument is deprecated.
8.0.0 | `value` and `encoding` are nullable now.
7.2.0 | This function now also accepts an Array as `value`. Formerly, only Strings have been supported.

# mb_chr

(PHP 7 >= 7.2.0, PHP 8)

mb_chr — Return character by Unicode code point value

### Beschreibung

function mb_chr(int `$codepoint`, ?string `$encoding` = `null`): string|false

Returns a string containing the character specified by the Unicode code point value, encoded in the specified encoding.

This function complements mb_ord().

### Parameter-Liste

`codepoint`

  A Unicode codepoint value, e.g. `128024` for U+1F418 ELEPHANT

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

A string containing the requested character, if it can be represented in the specified encoding Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 Testen unterschiedlicher Codepoints

    <?php
    $values = [65, 63, 0x20AC, 128024];
    foreach ($values as $value) {
        var_dump(mb_chr($value, 'UTF-8'));
        var_dump(mb_chr($value, 'ISO-8859-1'));
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "A"
    string(1) "A"
    string(1) "?"
    string(1) "?"
    string(3) "€"
    bool(false)
    string(4) "🐘"
    bool(false)

### Siehe auch

- mb_internal_encoding() - Set/Get internal character encoding
- mb_ord() - Get Unicode code point of character
- IntlChar::ord() - Return Unicode code point value of character
- chr() - Erzeugt eine Ein-Byte-Zeichenkette aus einer Zahl

# mb_convert_case

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_convert_case — Perform case folding on a string

### Beschreibung

function mb_convert_case(string `$string`, int `$mode`, ?string `$encoding` = `null`): string

Performs case folding on a string, converted in the way specified by `mode`.

### Parameter-Liste

`string`

  The string being converted.

`mode`

  The mode of the conversion. It can be one of `MB_CASE_UPPER`, `MB_CASE_LOWER`, `MB_CASE_TITLE`, `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE`, `MB_CASE_FOLD_SIMPLE`.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

A case folded version of `string` converted in the way specified by `mode`.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Implemented conditional casing rules for the Greek letter sigma which only apply to `MB_CASE_LOWER` and `MB_CASE_TITLE` modes, not to `MB_CASE_LOWER_SIMPLE` and `MB_CASE_TITLE_SIMPLE`.
7.3.0 | Added support for `MB_CASE_FOLD`, `MB_CASE_UPPER_SIMPLE`, `MB_CASE_LOWER_SIMPLE`, `MB_CASE_TITLE_SIMPLE`, and `MB_CASE_FOLD_SIMPLE` as `mode`.

### Beispiele

Beispiel #1 mb_convert_case() example

    <?php
    $str = "mary had a Little lamb and she loved it so";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

Beispiel #2 mb_convert_case() example with non-Latin UTF-8 text

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

### Anmerkungen

By contrast to the standard case folding functions such as strtolower() and strtoupper(), case folding is performed on the basis of the Unicode character properties. Thus the behaviour of this function is not affected by locale settings and it can convert any characters that have 'alphabetic' property, such a-umlaut (ä).

For more information about the Unicode properties, please see » http://www.unicode.org/reports/tr21/.

### Siehe auch

- mb_strtolower() - Make a string lowercase
- mb_strtoupper() - Make a string uppercase
- strtolower() - Setzt einen String in Kleinbuchstaben um
- strtoupper() - Wandelt alle Zeichen eines Strings in Großbuchstaben um
- ucfirst() - Verwandelt das erste Zeichen eines Strings in einen Großbuchstaben
- ucwords() - Wandelt jeden ersten Buchstaben eines Wortes innerhalb eines Strings in einen Großbuchstaben um

# mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_encoding — Convert a string from one character encoding to another

### Beschreibung

function mb_convert_encoding(array|string `$string`, string `$to_encoding`, array|string|null `$from_encoding` = `null`): array|string|false

Converts `string` from `from_encoding`, or the current internal encoding, to `to_encoding`. If `string` is an Array, all its String values will be converted recursively.

### Parameter-Liste

`string`

  The String or Array to be converted.

`to_encoding`

  The desired encoding of the result.

`from_encoding`

  The current encoding used to interpret `string`. Multiple encodings may be specified as an Array or comma separated list, in which case the correct encoding will be guessed using the same algorithm as mb_detect_encoding().

  If `from_encoding` is omitted or `null`, the mbstring.internal_encoding setting will be used if set, otherwise the default_charset setting.

  See supported encodings for valid values of `to_encoding` and `from_encoding`.

### Rückgabewerte

The encoded String or Array on success, Bei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

As of PHP 8.0.0, a ValueError is thrown if the value of `to_encoding` or `from_encoding` is an invalid encoding. Prior to PHP 8.0.0, a `E_WARNING` was emitted instead.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | mb_convert_encoding() will no longer return the following non text encodings: `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` and `"8 bit"`.
8.0.0 | mb_convert_encoding() will now throw a ValueError when `to_encoding` is passed an invalid encoding.
8.0.0 | mb_convert_encoding() will now throw a ValueError when `from_encoding` is passed an invalid encoding.
8.0.0 | `from_encoding` is nullable now.
7.2.0 | This function now also accepts an Array as `string`. Formerly, only Strings have been supported.

### Beispiele

Beispiel #1 mb_convert_encoding() example

    <?php
    /* Convert internal character encoding to SJIS */
    $str = mb_convert_encoding($str, "SJIS");

    /* Convert EUC-JP to UTF-7 */
    $str = mb_convert_encoding($str, "UTF-7", "EUC-JP");

    /* Auto detect encoding from JIS, eucjp-win, sjis-win, then convert str to UCS-2LE */
    $str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win");

    /* If mbstring.language is "Japanese", "auto" is expanded to "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
    $str = mb_convert_encoding($str, "EUC-JP", "auto");
    ?>

### Siehe auch

- mb_detect_order() - Set/Get character encoding detection order
- UConverter::transcode() - Convert a string from one character encoding to another
- iconv() - Konvertiert eine Zeichenkette von einem Zeichensatz in einen anderen

# mb_convert_kana

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_kana — Convert "kana" one from another ("zen-kaku", "han-kaku" and more)

### Beschreibung

function mb_convert_kana(string `$string`, string `$mode` = "KV", ?string `$encoding` = `null`): string

Performs a "han-kaku" - "zen-kaku" conversion for string `string`. This function is only useful for Japanese.

### Parameter-Liste

`string`

  The string being converted.

`mode`

  The conversion option.

  Specify with a combination of following options.

  Applicable Conversion Options
  Option | Meaning
  --- | ---
  `r` | Convert "zen-kaku" alphabets to "han-kaku"
  `R` | Convert "han-kaku" alphabets to "zen-kaku"
  `n` | Convert "zen-kaku" numbers to "han-kaku"
  `N` | Convert "han-kaku" numbers to "zen-kaku"
  `a` | Convert "zen-kaku" alphabets and numbers to "han-kaku"
  `A` | Convert "han-kaku" alphabets and numbers to "zen-kaku" (Characters included in "a", "A" options are U+0021 - U+007E excluding U+0022, U+0027, U+005C, U+007E)
  `s` | Convert "zen-kaku" space to "han-kaku" (U+3000 -> U+0020)
  `S` | Convert "han-kaku" space to "zen-kaku" (U+0020 -> U+3000)
  `k` | Convert "zen-kaku kata-kana" to "han-kaku kata-kana"
  `K` | Convert "han-kaku kata-kana" to "zen-kaku kata-kana"
  `h` | Convert "zen-kaku hira-gana" to "han-kaku kata-kana"
  `H` | Convert "han-kaku kata-kana" to "zen-kaku hira-gana"
  `c` | Convert "zen-kaku kata-kana" to "zen-kaku hira-gana"
  `C` | Convert "zen-kaku hira-gana" to "zen-kaku kata-kana"
  `V` | Collapse voiced sound notation and convert them into a character. Use with "K","H"

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

The converted string.

### Fehler/Exceptions

Throws a ValueError if the combination of different `mode`s is invalid. For example `"sS"`.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | A ValueError is now thrown if the combination of different `mode`s is invalid.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 mb_convert_kana() example

    <?php
    /* Convert all "han-kaku" "kata-kana" to "zen-kaku" "hira-gana" */
    echo mb_convert_kana('ﾔﾏﾀﾞ ﾊﾅｺ', "HV") . "\n";

    /* Convert "han-kaku" "kata-kana" to "zen-kaku" "kata-kana"
       and "zen-kaku" alphanumeric to "han-kaku" */
    echo mb_convert_kana('ｺｳｻﾞﾊﾞﾝｺﾞｳ ０１２３４５６', "KVa") . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    やまだ はなこ
    コウザバンゴウ 0123456

# mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_variables — Convert character code in variable(s)

### Beschreibung

function mb_convert_variables(
string `$to_encoding`,
array|string `$from_encoding`,
mixed `&$var`,
mixed `&...$vars`
): string|false

Converts character encoding of variables `var` and `vars` in encoding `from_encoding` to encoding `to_encoding`.

mb_convert_variables() join strings in Array or Object to detect encoding, since encoding detection tends to fail for short strings. Therefore, it is impossible to mix encoding in single array or object.

### Parameter-Liste

`to_encoding`

  The encoding that the string is being converted to.

`from_encoding`

  `from_encoding` is specified as an array or comma separated string, it tries to detect encoding from `from-coding`. When `from_encoding` is omitted, `detect_order` is used.

`var`

  `var` is the reference to the variable being converted. String, Array and Object are accepted. mb_convert_variables() assumes all parameters have the same encoding.

`vars`

  Additional `var`s.

### Rückgabewerte

The character encoding before conversion for success, or `false` for failure.

### Beispiele

Beispiel #1 mb_convert_variables() example

    <?php
    /* Convert variables $post1, $post2 to internal encoding */
    $interenc = mb_internal_encoding();
    $inputenc = mb_convert_variables($interenc, "ASCII,UTF-8,SJIS-win", $post1, $post2);
    ?>

# mb_decode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_mimeheader — Decode string in MIME header field

### Beschreibung

function mb_decode_mimeheader(string `$string`): string

Decodes encoded-word string `string` in MIME header.

### Parameter-Liste

`string`

  The string being decoded.

### Rückgabewerte

The decoded string in internal character encoding.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Underscores are converted to spaces as specified by » RFC 2047.

### Siehe auch

- mb_encode_mimeheader() - Encode string for MIME header

# mb_decode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_numericentity — Decode HTML numeric string reference to character

### Beschreibung

function mb_decode_numericentity(string `$string`, array `$map`, ?string `$encoding` = `null`): string

Convert numeric string reference of string `string` in a specified block to character.

### Parameter-Liste

`string`

  The string being decoded.

`map`

  `map` is an array that specifies the code area to convert.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

The converted string.

### Fehler/Exceptions

Throws a ValueError if `map` is not a list of Integers.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | mb_decode_numericentity() now throws a ValueError if `map` is not a list of Integers.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 `map` example

    <?php
    $convmap = array (
       int start_code1, int end_code1, int offset1, int mask1,
       int start_code2, int end_code2, int offset2, int mask2,
       // ........
       int start_codeN, int end_codeN, int offsetN, int maskN );
    // Specify Unicode value for start_codeN and end_codeN
    // Add offsetN to value and take bit-wise 'AND' with maskN,
    // then convert value to numeric string reference.
    ?>

Beispiel #2 `map` example escapes JavaScript string

    <?php
    function escape_javascript_string($str) {
      $map = [
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,0,0, // 49
              0,0,0,0,0,0,0,0,1,1,
              1,1,1,1,1,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,1,1,1,1,1,1,0,0,0, // 99
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,0,0,0,0,0,0,0,
              0,0,0,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 149
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 199
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1,
              1,1,1,1,1,1,1,1,1,1, // 249
              1,1,1,1,1,1,1, // 255
              ];
      // Char encoding is UTF-8
      $mblen = mb_strlen($str, 'UTF-8');
      $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
      for ($i=0, $encoded=''; $i < $mblen; $i++) {
          $u = substr($utf32, $i*8, 8);
          $v = base_convert($u, 16, 10);
          if ($v < 256 && $map[$v]) {
            $encoded .= '\\x'.substr($u, 6,2);
          } else if ($v == 2028) {
            $encoded .= '\\u2028';
          } else if ($v == 2029) {
            $encoded .= '\\u2029';
          } else {
            $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
          }
       }
       return $encoded;
    }

    // Test data
    $convmap = [ 0x0, 0xffff, 0, 0xffff ];
    $msg = '';
    for ($i=0; $i < 1000; $i++) {
      // chr() cannot generate correct UTF-8 data larger value than 128, use mb_decode_numericentity().
      $msg .= mb_decode_numericentity('&#'.$i.';', $convmap, 'UTF-8');
    }

    // var_dump($msg);
    var_dump(escape_javascript_string($msg));

### Siehe auch

- mb_encode_numericentity() - Encode character to HTML numeric string reference

# mb_detect_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_encoding — Detect character encoding

### Beschreibung

function mb_detect_encoding(string `$string`, array|string|null `$encodings` = `null`, bool `$strict` = `false`): string|false

Detects the most likely character encoding for string `string` from a list of candidates.

As of PHP 8.1 this function uses heuristics to detect which of the valid text encodings in the specified list is most likely to be correct and may not be in order of `encodings` provided.

Automatic detection of the intended character encoding can never be entirely reliable; without some additional information, it is similar to decoding an encrypted string without the key. It is always preferable to use an indication of character encoding stored or transmitted with the data, such as a "Content-Type" HTTP header.

This function is most useful with multibyte encodings, where not all sequences of bytes form a valid string. If the input string contains such a sequence, that encoding will be rejected.

Warnung

# The result is not accurate

The name of this function is misleading, it performs "guessing" rather than "detection".

The guesses are far from accurate, and therefore you cannot use this function to accurately detect the correct character encoding.

### Parameter-Liste

`string`

  The string being inspected.

`encodings`

  A list of character encodings to try. The list may be specified as an array of strings, or a single string separated by commas.

  If `encodings` is omitted or `null`, the current detect_order (set with the mbstring.detect_order configuration option, or mb_detect_order() function) will be used.

`strict`

  Controls the behaviour when `string` is not valid in any of the listed `encodings`. If `strict` is set to `false`, the closest matching encoding will be returned; if `strict` is set to `true`, `false` will be returned.

  The default value for `strict` can be set with the mbstring.strict_detection configuration option.

### Rückgabewerte

The detected character encoding, or `false` if the string is not valid in any of the listed encodings.

### Changelog

Version | Beschreibung
--- | ---
8.2.0 | mb_detect_encoding() will no longer return the following non text encodings: `"Base64"`, `"QPrint"`, `"UUencode"`, `"HTML entities"`, `"7 bit"` and `"8 bit"`.

### Beispiele

Beispiel #1 mb_detect_encoding() example

    <?php

    $str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";

    // Detect character encoding with current detect_order
    var_dump(mb_detect_encoding($str));

    // "auto" is expanded according to mbstring.language
    var_dump(mb_detect_encoding($str, "auto"));

    // Specify "encodings" parameter by list separated by comma
    var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));

    // Use array to specify "encodings" parameter
    $encodings = [
      "ASCII",
      "JIS",
      "EUC-JP"
    ];
    var_dump(mb_detect_encoding($str, $encodings));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(5) "ASCII"
    string(5) "ASCII"
    string(8) "SJIS-win"
    string(5) "ASCII"

Beispiel #2 Effect of `strict` parameter

    <?php
    // 'áéóú' encoded in ISO-8859-1
    $str = "\xE1\xE9\xF3\xFA";

    // The string is not valid ASCII or UTF-8, but UTF-8 is considered a closer match
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8'], true));

    // If a valid encoding is found, the strict parameter does not change the result
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], false));
    var_dump(mb_detect_encoding($str, ['ASCII', 'UTF-8', 'ISO-8859-1'], true));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(5) "UTF-8"
    bool(false)
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"

In some cases, the same sequence of bytes may form a valid string in multiple character encodings, and it is impossible to know which interpretation was intended. For instance, among many others, the byte sequence "\xC4\xA2" could be:

- "Ä¢" (U+00C4 LATIN CAPITAL LETTER A WITH DIAERESIS followed by U+00A2 CENT SIGN) encoded in any of ISO-8859-1, ISO-8859-15, or Windows-1252
- "ФЂ" (U+0424 CYRILLIC CAPITAL LETTER EF followed by U+0402 CYRILLIC CAPITAL LETTER DJE) encoded in ISO-8859-5
- "Ģ" (U+0122 LATIN CAPITAL LETTER G WITH CEDILLA) encoded in UTF-8

Beispiel #3 Effect of order when multiple encodings match

    <?php
    $str = "\xC4\xA2";

    // The string is valid in all three encodings, but the first one listed may not always be the one returned
    var_dump(mb_detect_encoding($str, ['UTF-8']));
    var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5'])); // as of php8.1 this returns ISO-8859-1 instead of UTF-8
    var_dump(mb_detect_encoding($str, ['ISO-8859-1', 'ISO-8859-5', 'UTF-8']));
    var_dump(mb_detect_encoding($str, ['ISO-8859-5', 'UTF-8', 'ISO-8859-1']));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(5) "UTF-8"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-1"
    string(10) "ISO-8859-5"

### Siehe auch

- mb_detect_order() - Set/Get character encoding detection order

# mb_detect_order

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_order — Set/Get character encoding detection order

### Beschreibung

function mb_detect_order(array|string|null `$encoding` = `null`): array|bool

Sets the automatic character encoding detection order to `encoding`.

### Parameter-Liste

`encoding`

  `encoding` is an array or comma separated list of character encoding. See supported encodings.

  If `encoding` is omitted or `null`, it returns the current character encoding detection order as array.

  This setting affects mb_detect_encoding() and mb_send_mail().

  `mbstring` currently implements the following encoding detection filters. If there is an invalid byte sequence for the following encodings, encoding detection will fail.

  `UTF-8`, `UTF-7`, `ASCII`, `EUC-JP`,`SJIS`, `eucJP-win`, `SJIS-win`, `JIS`, `ISO-2022-JP`

  For `ISO-8859-*`, `mbstring` always detects as `ISO-8859-*`.

  For `UTF-16`, `UTF-32`, `UCS2` and `UCS4`, encoding detection will fail always.

### Rückgabewerte

When setting the encoding detection order, `true` is returned on success or `false` on failure.

When getting the encoding detection order, an ordered array of the encodings is returned.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 mb_detect_order() examples

    <?php
    /* Set detection order by enumerated list */
    mb_detect_order("eucjp-win,sjis-win,UTF-8");

    /* Set detection order by array */
    $ary[] = "ASCII";
    $ary[] = "JIS";
    $ary[] = "EUC-JP";
    mb_detect_order($ary);

    /* Display current detection order */
    echo implode(", ", mb_detect_order());
    ?>

Beispiel #2 Example showing useless detect orders

    ; Always detect as ISO-8859-1
    detect_order = ISO-8859-1, UTF-8

    ; Always detect as UTF-8, since ASCII/UTF-7 values are
    ; valid for UTF-8
    detect_order = UTF-8, ASCII, UTF-7

### Siehe auch

- mb_internal_encoding() - Set/Get internal character encoding
- mb_http_input() - Detect HTTP input character encoding
- mb_http_output() - Set/Get HTTP output character encoding
- mb_send_mail() - Send encoded mail

# mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_mimeheader — Encode string for MIME header

### Beschreibung

function mb_encode_mimeheader(
string `$string`,
?string `$charset` = `null`,
?string `$transfer_encoding` = `null`,
string `$newline` = "\r\n",
int `$indent` = 0
): string

Encodes a given string `string` by the MIME header encoding scheme.

### Parameter-Liste

`string`

  The string being encoded. Its encoding should be same as mb_internal_encoding().

`charset`

  `charset` specifies the name of the character set in which `string` is represented in. The default value is determined by the current NLS setting (`mbstring.language`).

`transfer_encoding`

  `transfer_encoding` specifies the scheme of MIME encoding. It should be either `"B"` (Base64) or `"Q"` (Quoted-Printable). Falls back to `"B"` if not given.

`newline`

  `newline` specifies the EOL (end-of-line) marker with which mb_encode_mimeheader() performs line-folding (a » RFC term, the act of breaking a line longer than a certain length into multiple lines. The length is currently hard-coded to 74 characters). Falls back to `"\r\n"` (CRLF) if not given.

`indent`

  Indentation of the first line (number of characters in the header before `string`).

### Rückgabewerte

A converted version of the string represented in ASCII.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | `NUL` (0) bytes are no longer dropped when encoded using Quoted-Printable encoding, but encoded as `=00`.
8.0.0 | `charset` and `transfer_encoding` are nullable now.

### Beispiele

Beispiel #1 mb_encode_mimeheader() example

    <?php
    $name = "太郎"; // kanji
    $mbox = "kru";
    $doma = "gtinn.mon";
    $addr = '"' . addcslashes(mb_encode_mimeheader($name, "UTF-7", "Q"), '"') . '" <' . $mbox . "@" . $doma . ">";
    echo $addr;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    "=?UTF-7?Q?+WSqQzg-?=" <kru@gtinn.mon>

### Anmerkungen

> Hinweis:

> This function isn't designed to break lines at higher-level contextual break points (word boundaries, etc.). This behaviour may clutter up the original string with unexpected spaces.

### Siehe auch

- mb_decode_mimeheader() - Decode string in MIME header field

# mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_numericentity — Encode character to HTML numeric string reference

### Beschreibung

function mb_encode_numericentity(
string `$string`,
array `$map`,
?string `$encoding` = `null`,
bool `$hex` = `false`
): string

Converts specified character codes in string `string` from character code to HTML numeric character reference.

### Parameter-Liste

`string`

  The string being encoded.

`map`

  `map` is array specifies code area to convert.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

`hex`

  Whether the returned entity reference should be in hexadecimal notation (otherwise it is in decimal notation).

### Rückgabewerte

The converted string.

### Fehler/Exceptions

Throws a ValueError if `map` is not a list of Integers.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | mb_encode_numericentity() now throws a ValueError if `map` is not a list of Integers.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 `map` example

    <?php
    $convmap = array (
     int start_code1, int end_code1, int offset1, int mask1,
     int start_code2, int end_code2, int offset2, int mask2,
     ........
     int start_codeN, int end_codeN, int offsetN, int maskN );
    // Specify Unicode value for start_codeN and end_codeN
    // Add offsetN to value and take bit-wise 'AND' with maskN, then
    // it converts value to numeric string reference.
    ?>

Beispiel #2 mb_encode_numericentity() example

    <?php

    $str = "aAæÆあア𩸽";

    /* Convert all UTF8 characters up to 4 bytes to HTML numeric character reference */
    $convmap = [0, 0x1FFFFF, 0, 0x10FFFF];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));

    /* Converts only 2-byte and 4-byte UTF8 characters to HTML numeric character reference */
    $convmap = [
        0x80, 0x7FF, 0, 0x10FFFF,
        0x10000, 0x1FFFFF, 0, 0x10FFFF,
    ];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(46) "&#97;&#65;&#230;&#198;&#12354;&#12450;&#40509;"
    string(28) "aA&#230;&#198;あア&#40509;"

### Siehe auch

- mb_decode_numericentity() - Decode HTML numeric string reference to character

# mb_encoding_aliases

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mb_encoding_aliases — Get aliases of a known encoding type

### Beschreibung

function mb_encoding_aliases(string `$encoding`): array

Returns an array of aliases for a known `encoding` type.

### Parameter-Liste

`encoding`

  The encoding type being checked, for aliases.

### Rückgabewerte

Returns a numerically indexed array of encoding aliases.

### Fehler/Exceptions

Throws a ValueError if `encoding` is unknown.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | If the `encoding` is unknown, a ValueError is now thrown; previously an `E_WARNING` was emitted, and the function returned `false`.

### Beispiele

Beispiel #1 mb_encoding_aliases() example

    <?php
    $encoding        = 'ASCII';
    $known_encodings = mb_list_encodings();

    if (in_array($encoding, $known_encodings)) {

        $aliases = mb_encoding_aliases($encoding);
        print_r($aliases);

    } else {

        echo "Unknown ($encoding) encoding.\n";

    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => ANSI_X3.4-1968
        [1] => iso-ir-6
        [2] => ANSI_X3.4-1986
        [3] => ISO_646.irv:1991
        [4] => US-ASCII
        [5] => ISO646-US
        [6] => us
        [7] => IBM367
        [8] => cp367
        [9] => csASCII
    )

### Siehe auch

- mb_list_encodings() - Returns an array of all supported encodings

# mb_ereg

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg — Regular expression match with multibyte support

### Beschreibung

function mb_ereg(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Executes the regular expression match with multibyte support.

### Parameter-Liste

`pattern`

  The search pattern.

`string`

  The search string.

`matches`

  If matches are found for parenthesized substrings of `pattern` and the function is called with the third argument `matches`, the matches will be stored in the elements of the array `matches`. If no matches are found, `matches` is set to an empty array.

  $matches[1] will contain the substring which starts at the first left parenthesis; $matches[2] will contain the substring starting at the second, and so on. $matches[0] will contain a copy of the complete string matched.

### Rückgabewerte

Returns whether `pattern` matches `string`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | This function returns `true` on success now. Previously, it returned the byte length of the matched string if a match for `pattern` was found in `string` and `matches` was passed. If the optional parameter `matches` was not passed or the length of the matched string was `0`, this function returned `1`.
7.1.0 | mb_ereg() will now set `matches` to an empty array, if nothing matched. Formerly, `matches` was not modified in that case.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_eregi() - Regular expression match ignoring case with multibyte support

# mb_ereg_match

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_match — Regular expression match for multibyte string

### Beschreibung

function mb_ereg_match(string `$pattern`, string `$string`, ?string `$options` = `null`): bool

A regular expression match for a multibyte string

> Hinweis: `pattern` is only matched at the beginning of `string`.

### Parameter-Liste

`pattern`

  The regular expression pattern.

`string`

  The string being evaluated.

`options`

  The search option. See mb_regex_set_options() for explanation.

### Rückgabewerte

Returns `true` if `string` matches the regular expression `pattern`, `false` if not.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `options` is nullable now.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg() - Regular expression match with multibyte support

# mb_ereg_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_replace — Replace regular expression with multibyte support

### Beschreibung

function mb_ereg_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Scans `string` for matches to `pattern`, then replaces the matched text with `replacement`

### Parameter-Liste

`pattern`

  The regular expression pattern.

  Multibyte characters may be used in `pattern`.

`replacement`

  The replacement text.

`string`

  The string being checked.

`options`
  The search option. See mb_regex_set_options() for explanation.

### Rückgabewerte

The resultant string on success, or `false` on error. If `string` is not valid for the current encoding, `null` is returned.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `options` is nullable now.
7.1.0 | The function checks whether `string` is valid for the current encoding.
7.1.0 | The `e` modifier has been deprecated.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

Warnung

Der Modifikator `e` sollte niemals verwendet werden, wenn mit Eingaben gearbeitet wird, die als nicht vertrauenswürdig gelten. Es erfolgt keine automatische Maskierung wie sie von der Funktion preg_replace() bekannt ist. Wenn dies nicht beachtet wird, führt es in der Anwendung höchstwahrscheinlich zu Sicherheitslücken bezüglich der Ausführung von entferntem Code.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_eregi_replace() - Replace regular expression with multibyte support ignoring case

# mb_ereg_replace_callback

(PHP 5 >= 5.4.1, PHP 7, PHP 8)

mb_ereg_replace_callback — Perform a regular expression search and replace with multibyte support using a callback

### Beschreibung

function mb_ereg_replace_callback(
string `$pattern`,
callable `$callback`,
string `$string`,
?string `$options` = `null`
): string|false|null

Scans `string` for matches to `pattern`, then replaces the matched text with the output of `callback` function.

The behavior of this function is almost identical to mb_ereg_replace(), except for the fact that instead of `replacement` parameter, one should specify a `callback`.

### Parameter-Liste

`pattern`

  The regular expression pattern.

  Multibyte characters may be used in `pattern`.

`callback`

  A callback that will be called and passed an array of matched elements in the `string` string. The callback should return the replacement string.

  You'll often need the `callback` function for a mb_ereg_replace_callback() in just one place. In this case you can use an anonymous function to declare the callback within the call to mb_ereg_replace_callback(). By doing it this way you have all information for the call in one place and do not clutter the function namespace with a callback function's name not used anywhere else.

`string`

  The string being checked.

`options`

  The search option. See mb_regex_set_options() for explanation.

### Rückgabewerte

The resultant string on success, or `false` on error. If `string` is not valid for the current encoding, `null` is returned.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `options` is nullable now.
7.1.0 | The function checks whether `string` is valid for the current encoding.

### Beispiele

Beispiel #1 mb_ereg_replace_callback() example

    <?php
    // this text was used in 2002
    // we want to get this up to date for 2003
    $text = "April fools day is 04/01/2002\n";
    $text.= "Last christmas was 12/24/2001\n";
    // the callback function
    function next_year($matches)
    {
      // as usual: $matches[0] is the complete match
      // $matches[1] the match for the first subpattern
      // enclosed in '(...)' and so on
      return $matches[1].($matches[2]+1);
    }
    echo mb_ereg_replace_callback(
                "(\d{2}/\d{2}/)(\d{4})",
                "next_year",
                $text);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    April fools day is 04/01/2003
    Last christmas was 12/24/2002

Beispiel #2 mb_ereg_replace_callback() using anonymous function

    <?php
    // this text was used in 2002
    // we want to get this up to date for 2003
    $text = "April fools day is 04/01/2002\n";
    $text.= "Last christmas was 12/24/2001\n";

    echo mb_ereg_replace_callback(
                "(\d{2}/\d{2}/)(\d{4})",
                function ($matches) {
                   return $matches[1].($matches[2]+1);
                },
                $text);
    ?>

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg_replace() - Replace regular expression with multibyte support
- Anonymous functions

# mb_ereg_search

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search — Multibyte regular expression match for predefined multibyte string

### Beschreibung

function mb_ereg_search(?string `$pattern` = `null`, ?string `$options` = `null`): bool

Performs a multibyte regular expression match for a predefined multibyte string.

### Parameter-Liste

`pattern`

  The search pattern.

`options`

  The search option. See mb_regex_set_options() for explanation.

### Rückgabewerte

mb_ereg_search() returns `true` if the multibyte string matches with the regular expression, or `false` otherwise. The string for matching is set by mb_ereg_search_init(). If `pattern` is not specified, the previous one is used.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `pattern` and `options` are nullable now.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg_search_init() - Setup string and regular expression for a multibyte regular expression match

# mb_ereg_search_getpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getpos — Returns start point for next regular expression match

### Beschreibung

function mb_ereg_search_getpos(): int

Returns the start point for the next regular expression match.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

mb_ereg_search_getpos() returns the point to start regular expression match for mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). The position is represented by bytes from the head of string.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg_search_setpos() - Set start point of next regular expression match

# mb_ereg_search_getregs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getregs — Retrieve the result from the last multibyte regular expression match

### Beschreibung

function mb_ereg_search_getregs(): array|false

Retrieve the result from the last multibyte regular expression match

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array including the sub-string of matched part by last mb_ereg_search(), mb_ereg_search_pos(), mb_ereg_search_regs(). If there are some matches, the first element will have the matched sub-string, the second element will have the first part grouped with brackets, the third element will have the second part grouped with brackets, and so on. It returns `false` on error.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg_search_init() - Setup string and regular expression for a multibyte regular expression match

# mb_ereg_search_init

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_init — Setup string and regular expression for a multibyte regular expression match

### Beschreibung

function mb_ereg_search_init(string `$string`, ?string `$pattern` = `null`, ?string `$options` = `null`): bool

mb_ereg_search_init() sets `string` and `pattern` for a multibyte regular expression. These values are used for mb_ereg_search(), mb_ereg_search_pos(), and mb_ereg_search_regs().

### Parameter-Liste

`string`

  The search string.

`pattern`

  The search pattern.

`options`

  The search option. See mb_regex_set_options() for explanation.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `pattern` and `options` are nullable now.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg_search_regs() - Returns the matched part of a multibyte regular expression

# mb_ereg_search_pos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_pos — Returns position and length of a matched part of the multibyte regular expression for a predefined multibyte string

### Beschreibung

function mb_ereg_search_pos(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Returns position and length of a matched part of the multibyte regular expression for a predefined multibyte string

The string for match is specified by mb_ereg_search_init(). If it is not specified, the previous one will be used.

### Parameter-Liste

`pattern`

  The search pattern.

`options`

  The search option. See mb_regex_set_options() for explanation.

### Rückgabewerte

An array containing two elements. The first element is the offset, in bytes, where the match begins relative to the start of the search string, and the second element is the length in bytes of the match.

If an error occurs, `false` is returned.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `pattern` and `options` are nullable now.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg_search_init() - Setup string and regular expression for a multibyte regular expression match

# mb_ereg_search_regs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_regs — Returns the matched part of a multibyte regular expression

### Beschreibung

function mb_ereg_search_regs(?string `$pattern` = `null`, ?string `$options` = `null`): array|false

Returns the matched part of a multibyte regular expression.

### Parameter-Liste

`pattern`

  The search pattern.

`options`

  The search option. See mb_regex_set_options() for explanation.

### Rückgabewerte

mb_ereg_search_regs() executes the multibyte regular expression match, and if there are some matched part, it returns an array including substring of matched part as first element, the first grouped part with brackets as second element, the second grouped part as third element, and so on. It returns `false` on error.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `pattern` and `options` are nullable now.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg_search_init() - Setup string and regular expression for a multibyte regular expression match

# mb_ereg_search_setpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_setpos — Set start point of next regular expression match

### Beschreibung

function mb_ereg_search_setpos(int `$offset`): bool

mb_ereg_search_setpos() sets the starting point of a match for mb_ereg_search().

### Parameter-Liste

`offset`

  The position to set. If it is negative, it counts from the end of the string.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
7.1.0 | Support for negative `offset`s has been added.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg_search_init() - Setup string and regular expression for a multibyte regular expression match

# mb_eregi

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi — Regular expression match ignoring case with multibyte support

### Beschreibung

function mb_eregi(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

Executes the case insensitive regular expression match with multibyte support.

### Parameter-Liste

`pattern`

  The regular expression pattern.

`string`

  The string being searched.

`matches`

  If matches are found for parenthesized substrings of `pattern` and the function is called with the third argument `matches`, the matches will be stored in the elements of the array `matches`. If no matches are found, `matches` is set to an empty array.

  $matches[1] will contain the substring which starts at the first left parenthesis; $matches[2] will contain the substring starting at the second, and so on. $matches[0] will contain a copy of the complete string matched.

### Rückgabewerte

Returns whether `pattern` matches `string`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | This function returns `true` on success now. Previously, it returned the byte length of the matched string if a match for `pattern` was found in `string` and `matches` was passed. If the optional parameter `matches` was not passed or the length of the matched string was `0`, this function returned `1`.
7.1.0 | mb_eregi() will now set `matches` to an empty array, if nothing matched. Formerly, `matches` was not modified in that case.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg() - Regular expression match with multibyte support

# mb_eregi_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi_replace — Replace regular expression with multibyte support ignoring case

### Beschreibung

function mb_eregi_replace(
string `$pattern`,
string `$replacement`,
string `$string`,
?string `$options` = `null`
): string|false|null

Scans `string` for matches to `pattern`, then replaces the matched text with `replacement`.

### Parameter-Liste

`pattern`

  The regular expression pattern. Multibyte characters may be used. The case will be ignored.

`replacement`

  The replacement text.

`string`

  The searched string.

`options`
  The search option. See mb_regex_set_options() for explanation.

### Rückgabewerte

The resultant string or `false` on error. If `string` is not valid for the current encoding, `null` is returned.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `options` is nullable now.
7.1.0 | The function checks whether `string` is valid for the current encoding.
7.1.0 | The `e` modifier has been deprecated.

### Anmerkungen

> Hinweis:

> Die interne Kodierung oder die mit mb_regex_encoding() festgelegte Zeichenkodierung wird als Zeichenkodierung für diese Funktion genutzt.

Warnung

Der Modifikator `e` sollte niemals verwendet werden, wenn mit Eingaben gearbeitet wird, die als nicht vertrauenswürdig gelten. Es erfolgt keine automatische Maskierung wie sie von der Funktion preg_replace() bekannt ist. Wenn dies nicht beachtet wird, führt es in der Anwendung höchstwahrscheinlich zu Sicherheitslücken bezüglich der Ausführung von entferntem Code.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg_replace() - Replace regular expression with multibyte support

# mb_get_info

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_get_info — Get internal settings of mbstring

### Beschreibung

function mb_get_info(string `$type` = "all"): array|string|int|false|null

mb_get_info() returns the internal setting parameters of mbstring.

### Parameter-Liste

`type`

  If `type` is not specified or is specified as `"all"`, `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` and `"strict_detection"` will be returned.

  If `type` is specified as `"internal_encoding"`, `"http_input"`, `"http_output"`, `"http_output_conv_mimetypes"`, `"mail_charset"`, `"mail_header_encoding"`, `"mail_body_encoding"`, `"illegal_chars"`, `"encoding_translation"`, `"language"`, `"detect_order"`, `"substitute_character"` or `"strict_detection"` the specified setting parameter will be returned.

### Rückgabewerte

An array of type information if `type` is not specified, otherwise a specific `type`, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | The `type`s `"func_overload"` and `"func_overload_list"` are no longer supported.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_http_output() - Set/Get HTTP output character encoding

# mb_http_input

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_input — Detect HTTP input character encoding

### Beschreibung

function mb_http_input(?string `$type` = `null`): array|string|false

Detects the HTTP input character encoding.

### Parameter-Liste

`type`

  Input string specifies the input type. `"G"` for GET, `"P"` for POST, `"C"` for COOKIE, `"S"` for string, `"L"` for list, and `"I"` for the whole list (will return array). If type is omitted, it returns the last input type processed.

### Rückgabewerte

The character encoding name, as per the `type`, or an array of character encoding names, if `type` is `"I"`. If mb_http_input() does not process specified HTTP input, it returns `false`.

### Fehler/Exceptions

Throws a ValueError if `type` is invalid.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | mb_http_input() now throws a ValueError if `type` is invalid.
8.0.0 | `type` is nullable now.

### Siehe auch

- mb_internal_encoding() - Set/Get internal character encoding
- mb_http_output() - Set/Get HTTP output character encoding
- mb_detect_order() - Set/Get character encoding detection order

# mb_http_output

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_output — Set/Get HTTP output character encoding

### Beschreibung

function mb_http_output(?string `$encoding` = `null`): string|bool

Set/Get the HTTP output character encoding. Output after this function is called will be converted from the set internal encoding to `encoding`.

### Parameter-Liste

`encoding`

  If `encoding` is set, mb_http_output() sets the HTTP output character encoding to `encoding`.

  If `encoding` is omitted, mb_http_output() returns the current HTTP output character encoding.

### Rückgabewerte

If `encoding` is omitted, mb_http_output() returns the current HTTP output character encoding. Otherwise, Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Throws a ValueError if `encoding` contains null bytes.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | mb_http_output() now throws a ValueError if `encoding` contains null bytes.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- mb_internal_encoding() - Set/Get internal character encoding
- mb_http_input() - Detect HTTP input character encoding
- mb_detect_order() - Set/Get character encoding detection order

# mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_internal_encoding — Set/Get internal character encoding

### Beschreibung

function mb_internal_encoding(?string `$encoding` = `null`): string|bool

Set/Get the internal character encoding

### Parameter-Liste

`encoding`

  `encoding` is the character encoding name used for the HTTP input character encoding conversion, HTTP output character encoding conversion, and the default character encoding for string functions defined by the mbstring module. You should notice that the internal encoding is totally different from the one for multibyte regex.

### Rückgabewerte

If `encoding` is set, then Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. In this case, the character encoding for multibyte regex is NOT changed. If `encoding` is omitted, then the current character encoding name is returned.

### Fehler/Exceptions

As of PHP 8.0.0, a ValueError is thrown if the value of `encoding` is an invalid encoding. Prior to PHP 8.0.0, a `E_WARNING` was emitted instead.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).
8.0.0 | Now throws a ValueError if `encoding` is an invalid encoding. Previously a `E_WARNING` was emitted instead.

### Beispiele

Beispiel #1 mb_internal_encoding() example

    <?php
    /* Set internal character encoding to UTF-8 */
    mb_internal_encoding("UTF-8");

    /* Display current internal character encoding */
    echo mb_internal_encoding();
    ?>

### Siehe auch

- mb_http_input() - Detect HTTP input character encoding
- mb_http_output() - Set/Get HTTP output character encoding
- mb_detect_order() - Set/Get character encoding detection order
- mb_regex_encoding() - Set/Get character encoding for multibyte regex

# mb_language

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_language — Set/Get current language

### Beschreibung

function mb_language(?string `$language` = `null`): string|bool

Set/Get the current language.

### Parameter-Liste

`language`

  Used for encoding e-mail messages. The valid languages are listed in the following table. mb_send_mail() uses this setting to encode e-mail.

  Language | Charset | Encoding | Alias
  --- | --- | --- | ---
  German/de | ISO-8859-15 | Quoted-Printable | Deutsch
  English/en | ISO-8859-1 | Quoted-Printable |
  Armenian/hy | ArmSCII-8 | Quoted-Printable |
  Japanese/ja | ISO-2022-JP | BASE64 |
  Korean/ko | ISO-2022-KR | BASE64 |
  neutral | UTF-8 | BASE64 |
  Russian/ru | KOI8-R | Quoted-Printable |
  Turkish/tr | ISO-8859-9 | Quoted-Printable |
  Ukrainian/ua | KOI8-U | Quoted-Printable |
  uni | UTF-8 | BASE64 | universal
  Simplified Chinese/zh-cn | HZ | BASE64 |
  Traditional Chinese/zh-tw | BIG-5 | BASE64 |

### Rückgabewerte

If `language` is set and `language` is valid, it returns `true`. Otherwise, it returns `false`. When `language` is omitted or `null`, it returns the language name as a string.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `language` is nullable now.

### Siehe auch

- mb_send_mail() - Send encoded mail

# mb_lcfirst

(PHP 8 >= 8.4.0)

mb_lcfirst — Make a string's first character lowercase

### Beschreibung

function mb_lcfirst(string `$string`, ?string `$encoding` = `null`): string

Performs a multi-byte safe lcfirst() operation, and returns a string with the first character of `string` lowercased.

### Parameter-Liste

`string`
  The input string.
`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the resulting string.

### Siehe auch

- mb_ucfirst() - Make a string's first character uppercase
- lcfirst() - Wandelt den ersten Buchstaben eines Strings in einen Kleinbuchstaben um

# mb_list_encodings

(PHP 5, PHP 7, PHP 8)

mb_list_encodings — Returns an array of all supported encodings

### Beschreibung

function mb_list_encodings(): array

Returns an array containing all supported encodings.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a numerically indexed array.

### Fehler/Exceptions

This function does not emit any errors.

### Beispiele

Beispiel #1 mb_list_encodings() example

    <?php

    print_r(mb_list_encodings());

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => pass
        [1] => auto
        [2] => wchar
        [3] => byte2be
        [4] => byte2le
        [5] => byte4be
        [6] => byte4le
        [7] => BASE64
        [8] => UUENCODE
        [9] => HTML-ENTITIES
        [10] => Quoted-Printable
        [11] => 7bit
        [12] => 8bit
        [13] => UCS-4
        [14] => UCS-4BE
        [15] => UCS-4LE
        [16] => UCS-2
        [17] => UCS-2BE
        [18] => UCS-2LE
        [19] => UTF-32
        [20] => UTF-32BE
        [21] => UTF-32LE
        [22] => UTF-16
        [23] => UTF-16BE
        [24] => UTF-16LE
        [25] => UTF-8
        [26] => UTF-7
        [27] => UTF7-IMAP
        [28] => ASCII
        [29] => EUC-JP
        [30] => SJIS
        [31] => eucJP-win
        [32] => SJIS-win
        [33] => JIS
        [34] => ISO-2022-JP
        [35] => Windows-1252
        [36] => ISO-8859-1
        [37] => ISO-8859-2
        [38] => ISO-8859-3
        [39] => ISO-8859-4
        [40] => ISO-8859-5
        [41] => ISO-8859-6
        [42] => ISO-8859-7
        [43] => ISO-8859-8
        [44] => ISO-8859-9
        [45] => ISO-8859-10
        [46] => ISO-8859-13
        [47] => ISO-8859-14
        [48] => ISO-8859-15
        [49] => EUC-CN
        [50] => CP936
        [51] => HZ
        [52] => EUC-TW
        [53] => BIG-5
        [54] => EUC-KR
        [55] => UHC
        [56] => ISO-2022-KR
        [57] => Windows-1251
        [58] => CP866
        [59] => KOI8-R
    )

### Siehe auch

- mb_encoding_aliases() - Get aliases of a known encoding type

# mb_ltrim

(PHP 8 >= 8.4.0)

mb_ltrim — Strip whitespace (or other characters) from the beginning of a string

### Beschreibung

function mb_ltrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Performs a multi-byte safe ltrim() operation. Strip whitespace (or other characters) from the beginning of a string.

Without the second parameter, mb_ltrim() will strip these characters:

- `" "` (Unicode U+0020), ein gewöhliches Leerzeichen.
- `"\t"` (Unicode U+0009), ein Tabulatorzeichen.
- `"\n"` (Unicode U+000A), eine neue Zeile (Zeilenvorschub, Line Feed).
- `"\r"` (Unicode U+000D), ein Wagenrücklauf (Carriage Return)
- `"\0"` (Unicode U+0000), das NUL-Byte.
- `"\v"` (Unicode U+000B), ein vertikales Tabulatorzeichen.
- `"\f"` (Unicode U+000C), eine neue Zeile (Seitenvorschub, Form Feed).
- `"\u00A0"` (Unicode U+00A0), ein geschütztes Leerzeichen (NO-BREAK SPACE).
- `"\u1680"` (Unicode U+1680), ein Ogam-Leerzeichen.
- `"\u2000"` (Unicode U+2000), ein Halbgeviert-Abstand (EN QUAD).
- `"\u2001"` (Unicode U+2001), ein Geviert-Abstand (EM QUAD).
- `"\u2002"` (Unicode U+2002), ein Halbgeviert-Leerzeichen (EN SPACE).
- `"\u2003"` (Unicode U+2003), ein Geviert-Leerzeichen (EM SPACE).
- `"\u2004"` (Unicode U+2004), ein Drittelgeviert-Leerzeichen (THREE-PER-EM SPACE).
- `"\u2005"` (Unicode U+2005), ein Viertelgeviert-Leerzeichen (FOUR-PER-EM SPACE).
- `"\u2006"` (Unicode U+2006), ein Sechstelgeviert-Leerzeichen (SIX-PER-EM SPACE).
- `"\u2007"` (Unicode U+2007), ein ziffernbreites Leerzeichen (FIGURE SPACE).
- `"\u2008"` (Unicode U+2008), ein punktbreites Leerzeichen (PUNCTUATION SPACE).
- `"\u2009"` (Unicode U+2009), ein Schmales Leerzeichen (THIN SPACE).
- `"\u200A"` (Unicode U+200A), ein Haarspatium (HAIR SPACE).
- `"\u2028"` (Unicode U+2028), ein Zeilentrenner (LINE SEPARATOR).
- `"\u2029"` (Unicode U+2029), ein Absatztrenner (PARAGRAPH SEPARATOR).
- `"\u202F"` (Unicode U+202F), ein schmales geschütztes Leerzeichen (NARROW NO-BREAK SPACE).
- `"\u205F"` (Unicode U+205F), ein mittleres mathematisches Leerzeichen (MEDIUM MATHEMATICAL SPACE).
- `"\u3000"` (Unicode U+3000), ein ideographisches Leerzeichen (IDEOGRAPHIC SPACE).
- `"\u0085"` (Unicode U+0085), nächste Zeile (NEXT LINE, NEL).
- `"\u180E"` (Unicode U+180E), ein mongolisches Vokaltrennungszeichen (MONGOLIAN VOWEL SEPARATOR).

### Parameter-Liste

`string`
  The input string.
`characters`
  Optional können die zu entfernenden Zeichen auch mit dem Parameter `characters` angegeben werden. Dazu werden einfach alle Zeichen aufgelistet, die entfernt werden sollen.
`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

This function returns a string with whitespace stripped from the beginning of `string`.

### Siehe auch

- mb_trim() - Strip whitespace (or other characters) from the beginning and end of a string
- mb_rtrim() - Strip whitespace (or other characters) from the end of a string
- ltrim() - Entfernt Leerraum (oder andere Zeichen) vom Anfang eines Strings

# mb_ord

(PHP 7 >= 7.2.0, PHP 8)

mb_ord — Get Unicode code point of character

### Beschreibung

function mb_ord(string `$string`, ?string `$encoding` = `null`): int|false

Returns the Unicode code point value of the given character.

This function complements mb_chr().

### Parameter-Liste

`string`

  A string

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

The Unicode code point for the first character of `string` Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 A basic mb_ord() example

    <?php
    var_dump(mb_ord("A", "UTF-8"));
    var_dump(mb_ord("🐘", "UTF-8"));
    var_dump(mb_ord("\x80", "ISO-8859-1"));
    var_dump(mb_ord("\x80", "Windows-1252"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

int(65)
int(128024)
int(128)
int(8364)

### Siehe auch

- mb_internal_encoding() - Set/Get internal character encoding
- mb_chr() - Return character by Unicode code point value
- IntlChar::ord() - Return Unicode code point value of character
- ord() - Konvertiert das erste Byte einer Zeichenkette in einen Wert zwischen 0 und 255

# mb_output_handler

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_output_handler — Callback function converts character encoding in output buffer

### Beschreibung

function mb_output_handler(string `$string`, int `$status`): string

mb_output_handler() is ob_start() callback function. mb_output_handler() converts characters in the output buffer from internal character encoding to HTTP output character encoding.

### Parameter-Liste

`string`

  The contents of the output buffer.

`status`

  The status of the output buffer.

### Rückgabewerte

The converted string.

### Beispiele

Beispiel #1 mb_output_handler() example

    <?php
    mb_http_output("UTF-8");
    ob_start("mb_output_handler");
    ?>

### Anmerkungen

> Hinweis:

> If you want to output binary data, such as an image, a Content-Type: header must be set using header() before any binary data is sent to the client (e.g. header("Content-Type: image/png")). If Content-Type: header is sent, output character encoding conversion will not be performed.

> Note that if 'Content-Type: text/*' is sent, the content body is regarded as text; conversion will take place.

### Siehe auch

- ob_start() - Ausgabepufferung aktivieren

# mb_parse_str

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_parse_str — Parse GET/POST/COOKIE data and set global variable

### Beschreibung

function mb_parse_str(string `$string`, array `&$result`): bool

Parses GET/POST/COOKIE data and sets global variables. Since PHP does not provide raw POST/COOKIE data, it can only be used for GET data for now. It parses URL encoded data, detects encoding, converts coding to internal encoding and set values to the `result` array or global variables.

### Parameter-Liste

`string`

  The URL encoded data.

`result`

  An array containing decoded and character encoded converted values.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | The second parameter was no longer optional.
7.2.0 | Calling mb_parse_str() without the second parameter was deprecated.

### Siehe auch

- mb_detect_order() - Set/Get character encoding detection order
- mb_internal_encoding() - Set/Get internal character encoding

# mb_preferred_mime_name

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_preferred_mime_name — Get MIME charset string

### Beschreibung

function mb_preferred_mime_name(string `$encoding`): string|false

Get a MIME charset string for a specific encoding.

### Parameter-Liste

`encoding`

  The encoding being checked.

### Rückgabewerte

The MIME `charset` string for character encoding `encoding`, or `false` if no charset is preferred for the given `encoding`.

### Beispiele

Beispiel #1 mb_preferred_mime_name() example

    <?php
    $outputenc = "sjis-win";
    mb_http_output($outputenc);
    ob_start("mb_output_handler");
    header("Content-Type: text/html; charset=" . mb_preferred_mime_name($outputenc));
    ?>

# mb_regex_encoding

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_regex_encoding — Set/Get character encoding for multibyte regex

### Beschreibung

function mb_regex_encoding(?string `$encoding` = `null`): string|bool

Set/Get character encoding for a multibyte regex.

### Parameter-Liste

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

If `encoding` is set, then Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben. In this case, the internal character encoding is NOT changed. If `encoding` is omitted, then the current character encoding name for a multibyte regex is returned.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- mb_internal_encoding() - Set/Get internal character encoding
- mb_ereg() - Regular expression match with multibyte support

# mb_regex_set_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_regex_set_options — Set/Get the default options for mbregex functions

### Beschreibung

function mb_regex_set_options(?string `$options` = `null`): string

Sets the default options described by `options` for multibyte regex functions.

### Parameter-Liste

`options`

  The options to set. This is a string where each character is an option. To set a mode, the mode character must be the last one set, however there can only be set one mode but multiple options.

  Regex options
  Option | Meaning | Changelog
  --- | --- | ---
  i | Ambiguity match on |
  x | Enables extended pattern form |
  m | `'.'` matches with newlines |
  s | `'^'` -> `'\A'`, `'$'` -> `'\Z'` |
  p | Same as both the `m` and `s` options |
  l | Finds longest matches |
  n | Ignores empty matches |
  e | eval() resulting code | Deprecated as of PHP 7.1.0 and removed as of PHP 8.0.0

  > Hinweis:

  > The `"e"` option has no effect when set through mb_regex_set_options(). Use it with mb_ereg_replace() or mb_eregi_replace().

  Regex syntax modes (only one may be set)
  Mode | Meaning
  --- | ---
  j | Java (Sun java.util.regex)
  u | GNU regex
  g | grep
  c | Emacs
  r | Ruby
  z | Perl
  b | POSIX Basic regex
  d | POSIX Extended regex

### Rückgabewerte

The previous options. If `options` is omitted or `null`, it returns the string that describes the current options.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | If the parameter `options` is given and not `null`, the previous options are returned. Formerly, the current options have been returned.
8.0.0 | `options` is nullable now.
8.0.0 | The `"e"` option now throws a ValueError.
7.1.0 | The `"e"` option now emits an `E_DEPRECATED`.

### Siehe auch

- mb_split() - Split multibyte string using regular expression
- mb_ereg() - Regular expression match with multibyte support
- mb_eregi() - Regular expression match ignoring case with multibyte support

# mb_rtrim

(PHP 8 >= 8.4.0)

mb_rtrim — Strip whitespace (or other characters) from the end of a string

### Beschreibung

function mb_rtrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Performs a multi-byte safe rtrim() operation, and returns a string with whitespace (or other characters) stripped from the end of `string`.

Without the second parameter, mb_rtrim() will strip these characters:

- `" "` (Unicode U+0020), ein gewöhliches Leerzeichen.
- `"\t"` (Unicode U+0009), ein Tabulatorzeichen.
- `"\n"` (Unicode U+000A), eine neue Zeile (Zeilenvorschub, Line Feed).
- `"\r"` (Unicode U+000D), ein Wagenrücklauf (Carriage Return)
- `"\0"` (Unicode U+0000), das NUL-Byte.
- `"\v"` (Unicode U+000B), ein vertikales Tabulatorzeichen.
- `"\f"` (Unicode U+000C), eine neue Zeile (Seitenvorschub, Form Feed).
- `"\u00A0"` (Unicode U+00A0), ein geschütztes Leerzeichen (NO-BREAK SPACE).
- `"\u1680"` (Unicode U+1680), ein Ogam-Leerzeichen.
- `"\u2000"` (Unicode U+2000), ein Halbgeviert-Abstand (EN QUAD).
- `"\u2001"` (Unicode U+2001), ein Geviert-Abstand (EM QUAD).
- `"\u2002"` (Unicode U+2002), ein Halbgeviert-Leerzeichen (EN SPACE).
- `"\u2003"` (Unicode U+2003), ein Geviert-Leerzeichen (EM SPACE).
- `"\u2004"` (Unicode U+2004), ein Drittelgeviert-Leerzeichen (THREE-PER-EM SPACE).
- `"\u2005"` (Unicode U+2005), ein Viertelgeviert-Leerzeichen (FOUR-PER-EM SPACE).
- `"\u2006"` (Unicode U+2006), ein Sechstelgeviert-Leerzeichen (SIX-PER-EM SPACE).
- `"\u2007"` (Unicode U+2007), ein ziffernbreites Leerzeichen (FIGURE SPACE).
- `"\u2008"` (Unicode U+2008), ein punktbreites Leerzeichen (PUNCTUATION SPACE).
- `"\u2009"` (Unicode U+2009), ein Schmales Leerzeichen (THIN SPACE).
- `"\u200A"` (Unicode U+200A), ein Haarspatium (HAIR SPACE).
- `"\u2028"` (Unicode U+2028), ein Zeilentrenner (LINE SEPARATOR).
- `"\u2029"` (Unicode U+2029), ein Absatztrenner (PARAGRAPH SEPARATOR).
- `"\u202F"` (Unicode U+202F), ein schmales geschütztes Leerzeichen (NARROW NO-BREAK SPACE).
- `"\u205F"` (Unicode U+205F), ein mittleres mathematisches Leerzeichen (MEDIUM MATHEMATICAL SPACE).
- `"\u3000"` (Unicode U+3000), ein ideographisches Leerzeichen (IDEOGRAPHIC SPACE).
- `"\u0085"` (Unicode U+0085), nächste Zeile (NEXT LINE, NEL).
- `"\u180E"` (Unicode U+180E), ein mongolisches Vokaltrennungszeichen (MONGOLIAN VOWEL SEPARATOR).

### Parameter-Liste

`string`
  The input string.
`characters`
  Optional können die zu entfernenden Zeichen auch mit dem Parameter `characters` angegeben werden. Dazu werden einfach alle Zeichen aufgelistet, die entfernt werden sollen.
`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the modified string.

### Siehe auch

- mb_trim() - Strip whitespace (or other characters) from the beginning and end of a string
- mb_ltrim() - Strip whitespace (or other characters) from the beginning of a string
- rtrim() - Entfernt Leerraum (oder andere Zeichen) vom Ende eines Strings

# mb_scrub

(PHP 7 >= 7.2.0, PHP 8)

mb_scrub — Replace ill-formed byte sequences with the substitute character

### Beschreibung

function mb_scrub(string `$string`, ?string `$encoding` = `null`): string

Perform a character set conversion from the specified encoding, or the default encoding if no encoding was specified, to the same encoding. This has the effect of replacing any invalid byte sequences with the substitute character.

### Parameter-Liste

`string`

  The input string.

`encoding`

  The encoding used to interpret `string`. If it is omitted or `null`, the mbstring.internal_encoding setting will be used if set, otherwise the default_charset setting will be used.

### Rückgabewerte

The String result with invalid byte sequences replaced.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

# mb_send_mail

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_send_mail — Send encoded mail

### Beschreibung

function mb_send_mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
?string `$additional_params` = `null`
): bool

Sends email. Headers and messages are converted and encoded according to the mb_language() setting. It's a wrapper function for mail(), so see also mail() for details.

### Parameter-Liste

`to`

  The mail addresses being sent to. Multiple recipients may be specified by putting a comma between each address in `to`. This parameter is not automatically encoded.

`subject`

  The subject of the mail.

`message`

  The message of the mail.

`additional_headers` (optional)

  String or array to be inserted at the end of the email header.

  This is typically used to add extra headers (From, Cc, and Bcc). Multiple extra headers should be separated with a CRLF (\r\n). Validate parameter not to be injected unwanted headers by attackers.

  If an array is passed, its keys are the header names and its values are the respective header values.

  > Hinweis:

  > When sending mail, the mail must contain a `From` header. This can be set with the `additional_headers` parameter, or a default can be set in php.ini.

  > Failing to do this will result in an error message similar to `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing`. The `From` header sets also `Return-Path` under Windows.

  > Hinweis:

  > If messages are not received, try using a LF (\n) only. Some Unix mail transfer agents (most notably » qmail) replace LF by CRLF automatically (which leads to doubling CR if CRLF is used). This should be a last resort, as it does not comply with » RFC 2822.

`additional_params`

  `additional_params` is a MTA command line parameter. It is useful when setting the correct Return-Path header when using sendmail.

  This parameter is escaped by escapeshellcmd() internally to prevent command execution. escapeshellcmd() prevents command execution, but allows to add additional parameters. For security reason, this parameter should be validated.

  Since escapeshellcmd() is applied automatically, some characters that are allowed as email addresses by internet RFCs cannot be used. Programs that are required to use these characters mail() cannot be used.

  The user that the webserver runs as should be added as a trusted user to the sendmail configuration to prevent a 'X-Warning' header from being added to the message when the envelope sender (-f) is set using this method. For sendmail users, this file is /etc/mail/trusted-users.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `additional_params` is nullable now.
7.2.0 | The `additional_headers` parameter now also accepts an array.

### Siehe auch

- mail() - Sendet eine E-Mail
- mb_encode_mimeheader() - Encode string for MIME header
- mb_language() - Set/Get current language

# mb_split

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_split — Split multibyte string using regular expression

### Beschreibung

function mb_split(string `$pattern`, string `$string`, int `$limit` = -1): array|false

Split a multibyte `string` using regular expression `pattern` and returns the result as an array.

### Parameter-Liste

`pattern`

  The regular expression pattern.

`string`

  The string being split.

`limit`
  If optional parameter `limit` is specified, it will be split in `limit` elements as maximum.

### Rückgabewerte

The result as an array, Bei einem Fehler wird `false` zurückgegeben..

### Anmerkungen

> Hinweis:

> Die durch mb_regex_encoding() angegebene Zeichenkodierung wird von dieser Funktion als die Standardkodierung verwendet.

### Siehe auch

- mb_regex_encoding() - Set/Get character encoding for multibyte regex
- mb_ereg() - Regular expression match with multibyte support
- explode() - Teilt eine Zeichenkette anhand einer Zeichenkette

# mb_str_pad

(PHP 8 >= PHP 8.3.0)

mb_str_pad — Pad a multibyte string to a certain length with another multibyte string

### Beschreibung

function mb_str_pad(
string `$string`,
int `$length`,
string `$pad_string` = " ",
int `$pad_type` = `STR_PAD_RIGHT`,
?string `$encoding` = `null`
): string

This function returns the `string` padded on the left, the right, or both sides to the specified padding length, where the length is measured in Unicode codepoints. If the optional argument `pad_string` is not supplied, the `string` is padded with spaces, otherwise it is padded with characters from `pad_string` up to the limit.

### Parameter-Liste

`string`

  The input string.

`length`

  If the value of `length` is negative, less than, or equal to the length of the input string, no padding takes place, and `string` will be returned.

`pad_string`

  > Hinweis:

  > The `pad_string` may be truncated if the required number of padding characters can't be evenly divided by the `pad_string`'s length.

`pad_type`

  Optional argument `pad_type` can be `STR_PAD_RIGHT`, `STR_PAD_LEFT`, or `STR_PAD_BOTH`. By default `STR_PAD_RIGHT`.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the padded string.

### Beispiele

Beispiel #1 mb_str_pad() example

    <?php
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_RIGHT)); // string(18) "▶▶❤❓❇❤"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_LEFT));  // string(18) "❤❓❇❤▶▶"
    var_dump(mb_str_pad('▶▶', 6, '❤❓❇', STR_PAD_BOTH));  // string(18) "❤❓▶▶❤❓"

    var_dump(mb_str_pad("🎉", 3, "祝", STR_PAD_LEFT));   // string(10) "祝祝🎉"
    ?>

# mb_str_split

(PHP 7 >= 7.4.0, PHP 8)

mb_str_split — Given a multibyte string, return an array of its characters

### Beschreibung

function mb_str_split(string `$string`, int `$length` = 1, ?string `$encoding` = `null`): array

This function will return an array of strings, it is a version of str_split() with support for encodings of variable character size as well as fixed-size encodings of 1,2 or 4 byte characters. If the `length` parameter is specified, the string is broken down into chunks of the specified length in characters (not bytes). The `encoding` parameter can be optionally specified and it is good practice to do so.

### Parameter-Liste

`string`

  The String to split into characters or chunks.

`length`

  If specified, each element of the returned array will be composed of multiple characters instead of a single character.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

  A string specifying one of the supported encodings.

### Rückgabewerte

mb_str_split() returns an array of strings.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).
8.0.0 | This function no longer returns `false` on failure.

### Siehe auch

- str_split() - Konvertiert einen String in ein Array
- grapheme_str_split() - Split a string into an array
- explode() - Teilt eine Zeichenkette anhand einer Zeichenkette

# mb_strcut

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strcut — Get part of string

### Beschreibung

function mb_strcut(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

mb_strcut() extracts a substring from a string similarly to mb_substr(), but operates on bytes instead of characters. If the cut position happens to be between two bytes of a multi-byte character, the cut is performed starting from the first byte of that character. This is also the difference to the substr() function, which would simply cut the string between the bytes and thus result in a malformed byte sequence.

### Parameter-Liste

`string`

  The string being cut.

`start`

  If `start` is non-negative, the returned string will start at the `start`'th byte position in `string`, counting from zero. For instance, in the string '`abcdef`', the byte at position `0` is '`a`', the byte at position `2` is '`c`', and so forth.

  If `start` is negative, the returned string will start at the `start`'th byte counting back from the end of `string`. However, if the magnitude of a negative `start` is greater than the length of the string, the returned portion will start from the beginning of `string`.

`length`

  Length in bytes. If omitted or `NULL` is passed, extract all bytes to the end of the string.

  If `length` is negative, the returned string will end at the `length`'th byte counting back from the end of `string`. However, if the magnitude of a negative `length` is greater than the number of characters after the `start` position, an empty string will be returned.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

mb_strcut() returns the portion of `string` specified by the `start` and `length` parameters.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | The behavior is more consistent now on invalid `UTF-8` and `UTF-16` strings.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- mb_substr() - Get part of string
- mb_internal_encoding() - Set/Get internal character encoding

# mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strimwidth — Get truncated string with specified width

### Beschreibung

function mb_strimwidth(
string `$string`,
int `$start`,
int `$width`,
string `$trim_marker` = "",
?string `$encoding` = `null`
): string

Truncates string `string` to specified `width`, where halfwidth characters count as `1`, and fullwidth characters count as `2`. See » http://www.unicode.org/reports/tr11/ for details regarding East Asian character widths.

### Parameter-Liste

`string`

  The string being decoded.

`start`

  The start position offset. Number of characters from the beginning of string (first character is 0), or if start is negative, number of characters from the end of the string.

`width`

  The width of the desired trim. If negative width is specified, count from the end of the string.

  > Hinweis:

  > Passing negative width is deprecated as of PHP 8.3.0.

`trim_marker`

  A string that is added to the end of string when string is truncated.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

The truncated string. If `trim_marker` is set, `trim_marker` replaces the last chars to match the `width`.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Passing a negative `width` to mb_strimwidth() is now deprecated.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).
7.1.0 | Support for negative `start`s and `width`s has been added.

### Beispiele

Beispiel #1 mb_strimwidth() example

    <?php
    echo mb_strimwidth("Hello World", 0, 10, "...");
    // output: "Hello W..."
    ?>

### Siehe auch

- mb_strwidth() - Return width of string
- mb_internal_encoding() - Set/Get internal character encoding

# mb_stripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stripos — Finds position of first occurrence of a string within another, case insensitive

### Beschreibung

function mb_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_stripos() returns the numeric position of the first occurrence of `needle` in the `haystack` string. Unlike mb_strpos(), mb_stripos() is case-insensitive. If `needle` is not found, it returns `false`.

### Parameter-Liste

`haystack`

  The string from which to get the position of the first occurrence of `needle`

`needle`

  The string to find in `haystack`

`offset`

  The position in `haystack` to start searching. A negative offset counts from the end of the string.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Return the numeric position of the first occurrence of `needle` in the `haystack` string, or `false` if `needle` is not found.

### Fehler/Exceptions

- If `offset` is greater than the length of `haystack`, a ValueError will be thrown.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `needle` akzeptiert nun eine leere Zeichenkette.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).
7.1.0 | Support for negative `offset`s has been added.

### Siehe auch

- stripos() - Findet das erste Vorkommen eines Teilstrings in einem String, unabhängig von Groß- und Kleinschreibung
- strpos() - Sucht die Position des ersten Vorkommens des Suchstrings in einem String
- mb_strpos() - Find position of first occurrence of string in a string

# mb_stristr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stristr — Finds first occurrence of a string within another, case insensitive

### Beschreibung

function mb_stristr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_stristr() finds the first occurrence of `needle` in `haystack` and returns the portion of `haystack`. Unlike mb_strstr(), mb_stristr() is case-insensitive. If `needle` is not found, it returns `false`.

### Parameter-Liste

`haystack`

  The string from which to get the first occurrence of `needle`

`needle`

  The string to find in `haystack`

`before_needle`
  Determines which portion of `haystack` this function returns. If set to `true`, it returns all of `haystack` from the beginning to the first occurrence of `needle` (excluding needle). If set to `false`, it returns all of `haystack` from the first occurrence of `needle` to the end (including needle).
`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the portion of `haystack`, or `false` if `needle` is not found.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `needle` akzeptiert nun eine leere Zeichenkette.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- stristr() - Wie strstr, aber unabhängig von Groß- bzw. Kleinschreibung
- strstr() - Findet das erste Vorkommen eines Strings
- mb_strstr() - Finds first occurrence of a string within another

# mb_strlen

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strlen — Get string length

### Beschreibung

function mb_strlen(string `$string`, ?string `$encoding` = `null`): int

Gets the length of a string.

### Parameter-Liste

`string`

  The string being checked for length.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the number of characters in string `string` having character encoding `encoding`. A multi-byte character is counted as 1.

### Fehler/Exceptions

If the encoding is unknown, an error of level `E_WARNING` is generated.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- mb_internal_encoding() - Set/Get internal character encoding
- grapheme_strlen() - Get string length in grapheme units
- iconv_strlen() - Returns the character count of string
- strlen() - Ermitteln der String-Länge

# mb_strpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strpos — Find position of first occurrence of string in a string

### Beschreibung

function mb_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Finds position of the first occurrence of `needle` in the `haystack` string.

Performs a multi-byte safe strpos() operation based on number of characters. The first character's position is 0, the second character position is 1, and so on.

### Parameter-Liste

`haystack`

  The string from which to get the position of the first occurrence of `needle`.

`needle`

  The string to find in `haystack`. In contrast with strpos(), numeric values are not applied as the ordinal value of a character.

`offset`

  The search offset. If it is not specified, 0 is used. A negative offset counts from the end of the string.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the numeric position of the first occurrence of `needle` in the `haystack` string. If `needle` is not found, it returns `false`.

### Fehler/Exceptions

- If `offset` is greater than the length of `haystack`, a ValueError will be thrown.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `needle` akzeptiert nun eine leere Zeichenkette.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).
7.1.0 | Support for negative `offset`s has been added.

### Siehe auch

- mb_internal_encoding() - Set/Get internal character encoding
- strpos() - Sucht die Position des ersten Vorkommens des Suchstrings in einem String

# mb_strrchr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrchr — Finds the last occurrence of a character in a string within another

### Beschreibung

function mb_strrchr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrchr() finds the last occurrence of `needle` in `haystack` and returns the portion of `haystack`. If `needle` is not found, it returns `false`.

### Parameter-Liste

`haystack`

  The string from which to get the last occurrence of `needle`.

`needle`

  The string to find in `haystack`.

`before_needle`

  Determines which portion of `haystack` this function returns. If set to `true`, it returns all of `haystack` from the beginning to the last occurrence of `needle`. If set to `false`, it returns all of `haystack` from the last occurrence of `needle` to the end.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the portion of `haystack`. or `false` if `needle` is not found.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `needle` akzeptiert nun eine leere Zeichenkette.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- strrchr() - Sucht das letzte Vorkommen eines Zeichens in einem String
- mb_strstr() - Finds first occurrence of a string within another
- mb_strrichr() - Finds the last occurrence of a character in a string within another, case insensitive

# mb_strrichr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrichr — Finds the last occurrence of a character in a string within another, case insensitive

### Beschreibung

function mb_strrichr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strrichr() finds the last occurrence of `needle` in `haystack` and returns the portion of `haystack`. Unlike mb_strrchr(), mb_strrichr() is case-insensitive. If `needle` is not found, it returns `false`.

### Parameter-Liste

`haystack`

  The string from which to get the last occurrence of `needle`.

`needle`

  The string to find in `haystack`.

`before_needle`
  Determines which portion of `haystack` this function returns. If set to `true`, it returns all of `haystack` from the beginning to the last occurrence of `needle`. If set to `false`, it returns all of `haystack` from the last occurrence of `needle` to the end.
`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the portion of `haystack`. or `false` if `needle` is not found.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `needle` akzeptiert nun eine leere Zeichenkette.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- mb_stristr() - Finds first occurrence of a string within another, case insensitive
- mb_strrchr() - Finds the last occurrence of a character in a string within another

# mb_strripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strripos — Finds position of last occurrence of a string within another, case insensitive

### Beschreibung

function mb_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

mb_strripos() performs multi-byte safe strripos() operation based on number of characters. `needle` position is counted from the beginning of `haystack`. First character's position is 0. Second character position is 1. Unlike mb_strrpos(), mb_strripos() is case-insensitive.

### Parameter-Liste

`haystack`

  The string from which to get the position of the last occurrence of `needle`.

`needle`

  The string to find in `haystack`.

`offset`

  May be specified to begin searching an arbitrary number of characters into the `haystack`. Negative values will stop searching at an arbitrary point prior to the end of the `haystack`.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Return the numeric position of the last occurrence of `needle` in the `haystack` string, or `false` if `needle` is not found.

### Fehler/Exceptions

- If `offset` is greater than the length of `haystack`, a ValueError will be thrown.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `needle` akzeptiert nun eine leere Zeichenkette.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- strripos() - Findet das letzte Vorkommen der gesuchten Zeichenkette in einem String, unabhängig von Groß- und Kleinschreibung
- strrpos() - Findet die Position des letzten Vorkommens eines Teilstrings innerhalb einer Zeichenkette
- mb_strrpos() - Find position of last occurrence of a string in a string

# mb_strrpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strrpos — Find position of last occurrence of a string in a string

### Beschreibung

function mb_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

Performs a multibyte safe strrpos() operation based on the number of characters. `needle` position is counted from the beginning of `haystack`. First character's position is 0. Second character position is 1.

### Parameter-Liste

`haystack`

  The string being checked, for the last occurrence of `needle`

`needle`

  The string to find in `haystack`.

`offset`
  May be specified to begin searching an arbitrary number of characters into the `haystack`. Negative values will stop searching at an arbitrary point prior to the end of the `haystack`.
`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the numeric position of the last occurrence of `needle` in the `haystack` string. If `needle` is not found, it returns `false`.

### Fehler/Exceptions

- If `offset` is greater than the length of `haystack`, a ValueError will be thrown.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `needle` akzeptiert nun eine leere Zeichenkette.
8.0.0 | Passing the `encoding` as the third argument instead of an `offset` has been removed.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- mb_strpos() - Find position of first occurrence of string in a string
- mb_internal_encoding() - Set/Get internal character encoding
- strrpos() - Findet die Position des letzten Vorkommens eines Teilstrings innerhalb einer Zeichenkette

# mb_strstr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strstr — Finds first occurrence of a string within another

### Beschreibung

function mb_strstr(
string `$haystack`,
string `$needle`,
bool `$before_needle` = `false`,
?string `$encoding` = `null`
): string|false

mb_strstr() finds the first occurrence of `needle` in `haystack` and returns the portion of `haystack`. If `needle` is not found, it returns `false`.

### Parameter-Liste

`haystack`

  The string from which to get the first occurrence of `needle`

`needle`

  The string to find in `haystack`

`before_needle`
  Determines which portion of `haystack` this function returns. If set to `true`, it returns all of `haystack` from the beginning to the first occurrence of `needle` (excluding needle). If set to `false`, it returns all of `haystack` from the first occurrence of `needle` to the end (including needle).
`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

Returns the portion of `haystack`, or `false` if `needle` is not found.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `needle` akzeptiert nun eine leere Zeichenkette.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- stristr() - Wie strstr, aber unabhängig von Groß- bzw. Kleinschreibung
- strstr() - Findet das erste Vorkommen eines Strings
- mb_stristr() - Finds first occurrence of a string within another, case insensitive

# mb_strtolower

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtolower — Make a string lowercase

### Beschreibung

function mb_strtolower(string `$string`, ?string `$encoding` = `null`): string

Returns `string` with all alphabetic characters converted to lowercase.

### Parameter-Liste

`string`

  The string being lowercased.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

`string` with all alphabetic characters converted to lowercase.

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | Implemented conditional casing rules for the Greek letter sigma.

### Beispiele

Beispiel #1 mb_strtolower() example

    <?php
    $str = "Mary Had A Little Lamb and She LOVED It So";
    $str = mb_strtolower($str);
    echo $str; // Prints mary had a little lamb and she loved it so
    ?>

Beispiel #2 mb_strtolower() example with non-Latin UTF-8 text

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtolower($str, 'UTF-8');
    echo $str; // Prints τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός
    ?>

### Anmerkungen

By contrast to strtolower(), 'alphabetic' is determined by the Unicode character properties. Thus the behaviour of this function is not affected by locale settings and it can convert any characters that have 'alphabetic' property, such as a-umlaut (ä).

For more information about the Unicode properties, please see » http://www.unicode.org/reports/tr21/.

### Siehe auch

- mb_strtoupper() - Make a string uppercase
- mb_convert_case() - Perform case folding on a string
- strtolower() - Setzt einen String in Kleinbuchstaben um

# mb_strtoupper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtoupper — Make a string uppercase

### Beschreibung

function mb_strtoupper(string `$string`, ?string `$encoding` = `null`): string

Returns `string` with all alphabetic characters converted to uppercase.

### Parameter-Liste

`string`

  The string being uppercased.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

`string` with all alphabetic characters converted to uppercase.

### Beispiele

Beispiel #1 mb_strtoupper() example

    <?php
    $str = "Mary Had A Little Lamb and She LOVED It So";
    $str = mb_strtoupper($str);
    echo $str; // Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO
    ?>

Beispiel #2 mb_strtoupper() example with non-Latin UTF-8 text

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_strtoupper($str, 'UTF-8');
    echo $str; // Prints ΤΆΧΙΣΤΗ ΑΛΏΠΗΞ ΒΑΦΉΣ ΨΗΜΈΝΗ ΓΗ, ΔΡΑΣΚΕΛΊΖΕΙ ΥΠΈΡ ΝΩΘΡΟΎ ΚΥΝΌΣ
    ?>

### Anmerkungen

By contrast to strtoupper(), 'alphabetic' is determined by the Unicode character properties. Thus the behaviour of this function is not affected by locale settings and it can convert any characters that have 'alphabetic' property, such as a-umlaut (ä).

For more information about the Unicode properties, please see » http://www.unicode.org/reports/tr21/.

### Siehe auch

- mb_strtolower() - Make a string lowercase
- mb_convert_case() - Perform case folding on a string
- strtoupper() - Wandelt alle Zeichen eines Strings in Großbuchstaben um

# mb_strwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strwidth — Return width of string

### Beschreibung

function mb_strwidth(string `$string`, ?string `$encoding` = `null`): int

Returns the width of string `string`, where halfwidth characters count as `1`, and fullwidth characters count as `2`. See » http://www.unicode.org/reports/tr11/ for details regarding East Asian character widths.

The fullwidth characters are: `U+1100`-`U+115F`, `U+11A3`-`U+11A7`, `U+11FA`-`U+11FF`, `U+2329`-`U+232A`, `U+2E80`-`U+2E99`, `U+2E9B`-`U+2EF3`, `U+2F00`-`U+2FD5`, `U+2FF0`-`U+2FFB`, `U+3000`-`U+303E`, `U+3041`-`U+3096`, `U+3099`-`U+30FF`, `U+3105`-`U+312D`, `U+3131`-`U+318E`, `U+3190`-`U+31BA`, `U+31C0`-`U+31E3`, `U+31F0`-`U+321E`, `U+3220`-`U+3247`, `U+3250`-`U+32FE`, `U+3300`-`U+4DBF`, `U+4E00`-`U+A48C`, `U+A490`-`U+A4C6`, `U+A960`-`U+A97C`, `U+AC00`-`U+D7A3`, `U+D7B0`-`U+D7C6`, `U+D7CB`-`U+D7FB`, `U+F900`-`U+FAFF`, `U+FE10`-`U+FE19`, `U+FE30`-`U+FE52`, `U+FE54`-`U+FE66`, `U+FE68`-`U+FE6B`, `U+FF01`-`U+FF60`, `U+FFE0`-`U+FFE6`, `U+1B000`-`U+1B001`, `U+1F200`-`U+1F202`, `U+1F210`-`U+1F23A`, `U+1F240`-`U+1F248`, `U+1F250`-`U+1F251`, `U+20000`-`U+2FFFD`, `U+30000`-`U+3FFFD`. All other characters are halfwidth characters.

### Parameter-Liste

`string`

  The string being decoded.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

The width of string `string`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 mb_strwidth() example

    <?php
    var_dump(
        mb_strwidth('a'),       // LATIN SMALL LETTER A
        mb_strwidth("\u{ff41}") // FULLWIDTH LATIN SMALL LETTER A
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)
    int(2)

### Siehe auch

- mb_strimwidth() - Get truncated string with specified width
- mb_internal_encoding() - Set/Get internal character encoding

# mb_substitute_character

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substitute_character — Set/Get substitution character

### Beschreibung

function mb_substitute_character(string|int|null `$substitute_character` = `null`): string|int|bool

Specifies a substitution character when input character encoding is invalid or character code does not exist in output character encoding. Invalid characters may be substituted `"none"` (no output), string or int value (Unicode character code value).

This setting affects mb_convert_encoding(), mb_convert_variables(), mb_output_handler(), mb_scrub(), and mb_send_mail().

### Parameter-Liste

`substitute_character`

  Specify the Unicode value as an int, or as one of the following strings:

  - `"none"`: no output
  - `"long"`: Output character code value (Example: `U+3000`, `JIS+7E7E`)
  - `"entity"`: Output character entity (Example: `&#x200;`)

### Rückgabewerte

If `substitute_character` is set, it returns `true` for success, otherwise returns `false`. If `substitute_character` is not set, it returns the current setting.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Passing an empty string to `substitute_character` is no longer supported; `"none"` should be passed instead.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 mb_substitute_character() example

    <?php
    /* Set with Unicode U+3013 (GETA MARK) */
    mb_substitute_character(0x3013);

    /* Set hex format */
    mb_substitute_character("long");

    /* Display current setting */
    echo mb_substitute_character();
    ?>

# mb_substr

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substr — Get part of string

### Beschreibung

function mb_substr(
string `$string`,
int `$start`,
?int `$length` = `null`,
?string `$encoding` = `null`
): string

Performs a multi-byte safe substr() operation based on number of characters. Position is counted from the beginning of `string`. First character's position is 0. Second character position is 1, and so on.

### Parameter-Liste

`string`

  The string to extract the substring from.

`start`

  If `start` is non-negative, the returned string will start at the `start`'th position in `string`, counting from zero. For instance, in the string '`abcdef`', the character at position `0` is '`a`', the character at position `2` is '`c`', and so forth.

  If `start` is negative, the returned string will start at the `start`'th character from the end of `string`.

`length`

  Maximum number of characters to use from `string`. If omitted or `NULL` is passed, extract all characters to the end of the string.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

mb_substr() returns the portion of `string` specified by the `start` and `length` parameters.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | On invalid strings (those with encoding errors), character indices are now interpreted in the same manner as most other mbstring functions. This means that character indices returned by mb_strpos() can be passed directly.
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Siehe auch

- mb_strcut() - Get part of string
- mb_internal_encoding() - Set/Get internal character encoding

# mb_substr_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_substr_count — Count the number of substring occurrences

### Beschreibung

function mb_substr_count(string `$haystack`, string `$needle`, ?string `$encoding` = `null`): int

Counts the number of times the `needle` substring occurs in the `haystack` string.

### Parameter-Liste

`haystack`

  The string being checked.

`needle`

  The string being found.

`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

The number of times the `needle` substring occurs in the `haystack` string.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `encoding` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 mb_substr_count() example

    <?php
    echo mb_substr_count("This is a test", "is"); // prints out 2
    ?>

### Siehe auch

- mb_strpos() - Find position of first occurrence of string in a string
- mb_substr() - Get part of string
- substr_count() - Ermittelt, wie oft eine Zeichenkette in einem String vorkommt

# mb_trim

(PHP 8 >= 8.4.0)

mb_trim — Strip whitespace (or other characters) from the beginning and end of a string

### Beschreibung

function mb_trim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

Performs a multi-byte safe trim() operation, and returns a string with whitespace stripped from the beginning and end of `string`. Without the second parameter, mb_trim() will strip these characters:

- `" "` (Unicode U+0020), ein gewöhliches Leerzeichen.
- `"\t"` (Unicode U+0009), ein Tabulatorzeichen.
- `"\n"` (Unicode U+000A), eine neue Zeile (Zeilenvorschub, Line Feed).
- `"\r"` (Unicode U+000D), ein Wagenrücklauf (Carriage Return)
- `"\0"` (Unicode U+0000), das NUL-Byte.
- `"\v"` (Unicode U+000B), ein vertikales Tabulatorzeichen.
- `"\f"` (Unicode U+000C), eine neue Zeile (Seitenvorschub, Form Feed).
- `"\u00A0"` (Unicode U+00A0), ein geschütztes Leerzeichen (NO-BREAK SPACE).
- `"\u1680"` (Unicode U+1680), ein Ogam-Leerzeichen.
- `"\u2000"` (Unicode U+2000), ein Halbgeviert-Abstand (EN QUAD).
- `"\u2001"` (Unicode U+2001), ein Geviert-Abstand (EM QUAD).
- `"\u2002"` (Unicode U+2002), ein Halbgeviert-Leerzeichen (EN SPACE).
- `"\u2003"` (Unicode U+2003), ein Geviert-Leerzeichen (EM SPACE).
- `"\u2004"` (Unicode U+2004), ein Drittelgeviert-Leerzeichen (THREE-PER-EM SPACE).
- `"\u2005"` (Unicode U+2005), ein Viertelgeviert-Leerzeichen (FOUR-PER-EM SPACE).
- `"\u2006"` (Unicode U+2006), ein Sechstelgeviert-Leerzeichen (SIX-PER-EM SPACE).
- `"\u2007"` (Unicode U+2007), ein ziffernbreites Leerzeichen (FIGURE SPACE).
- `"\u2008"` (Unicode U+2008), ein punktbreites Leerzeichen (PUNCTUATION SPACE).
- `"\u2009"` (Unicode U+2009), ein Schmales Leerzeichen (THIN SPACE).
- `"\u200A"` (Unicode U+200A), ein Haarspatium (HAIR SPACE).
- `"\u2028"` (Unicode U+2028), ein Zeilentrenner (LINE SEPARATOR).
- `"\u2029"` (Unicode U+2029), ein Absatztrenner (PARAGRAPH SEPARATOR).
- `"\u202F"` (Unicode U+202F), ein schmales geschütztes Leerzeichen (NARROW NO-BREAK SPACE).
- `"\u205F"` (Unicode U+205F), ein mittleres mathematisches Leerzeichen (MEDIUM MATHEMATICAL SPACE).
- `"\u3000"` (Unicode U+3000), ein ideographisches Leerzeichen (IDEOGRAPHIC SPACE).
- `"\u0085"` (Unicode U+0085), nächste Zeile (NEXT LINE, NEL).
- `"\u180E"` (Unicode U+180E), ein mongolisches Vokaltrennungszeichen (MONGOLIAN VOWEL SEPARATOR).

### Parameter-Liste

`string`
  The string that will be trimmed.
`characters`
  Optional können die zu entfernenden Zeichen auch mit dem Parameter `characters` angegeben werden. Dazu werden einfach alle Zeichen aufgelistet, die entfernt werden sollen.
`encoding`

  Der Parameter `encoding` legt die Zeichenkodierung fest. Wird er nicht übergeben, so wird die interne Zeichenkodierung genutzt.

### Rückgabewerte

The trimmed string.

### Siehe auch

- mb_ltrim() - Strip whitespace (or other characters) from the beginning of a string
- mb_rtrim() - Strip whitespace (or other characters) from the end of a string
- trim() - Entfernt Whitespaces (oder andere Zeichen) am Anfang und Ende eines Strings

# mb_ucfirst

(PHP 8 >= 8.4.0)

mb_ucfirst — Make a string's first character uppercase

### Beschreibung

function mb_ucfirst(string `$string`, ?string `$encoding` = `null`): string

Performs a multi-byte safe ucfirst() operation, and returns a string with the first character of `string` title-cased.

### Parameter-Liste

`string`
  The input string.
`encoding`
  The string encoding.

### Rückgabewerte

Returns the resulting string.

### Anmerkungen

> Hinweis:

> By contrast to the standard case folding functions such as strtolower() and strtoupper(), case folding is performed on the basis of the Unicode character properties. Thus the behaviour of this function is not affected by locale settings and it can convert any characters that have 'alphabetic' property, such a-umlaut (ä).

For more information about the Unicode properties, please see » http://www.unicode.org/reports/tr21/.

### Siehe auch

- mb_lcfirst() - Make a string's first character lowercase
- mb_convert_case() - Perform case folding on a string
- ucfirst() - Verwandelt das erste Zeichen eines Strings in einen Großbuchstaben

## Inhaltsverzeichnis

- mb_check_encoding — Check if strings are valid for the specified encoding
- mb_chr — Return character by Unicode code point value
- mb_convert_case — Perform case folding on a string
- mb_convert_encoding — Convert a string from one character encoding to another
- mb_convert_kana — Convert "kana" one from another ("zen-kaku", "han-kaku" and more)
- mb_convert_variables — Convert character code in variable(s)
- mb_decode_mimeheader — Decode string in MIME header field
- mb_decode_numericentity — Decode HTML numeric string reference to character
- mb_detect_encoding — Detect character encoding
- mb_detect_order — Set/Get character encoding detection order
- mb_encode_mimeheader — Encode string for MIME header
- mb_encode_numericentity — Encode character to HTML numeric string reference
- mb_encoding_aliases — Get aliases of a known encoding type
- mb_ereg — Regular expression match with multibyte support
- mb_ereg_match — Regular expression match for multibyte string
- mb_ereg_replace — Replace regular expression with multibyte support
- mb_ereg_replace_callback — Perform a regular expression search and replace with multibyte support using a callback
- mb_ereg_search — Multibyte regular expression match for predefined multibyte string
- mb_ereg_search_getpos — Returns start point for next regular expression match
- mb_ereg_search_getregs — Retrieve the result from the last multibyte regular expression match
- mb_ereg_search_init — Setup string and regular expression for a multibyte regular expression match
- mb_ereg_search_pos — Returns position and length of a matched part of the multibyte regular expression for a predefined multibyte string
- mb_ereg_search_regs — Returns the matched part of a multibyte regular expression
- mb_ereg_search_setpos — Set start point of next regular expression match
- mb_eregi — Regular expression match ignoring case with multibyte support
- mb_eregi_replace — Replace regular expression with multibyte support ignoring case
- mb_get_info — Get internal settings of mbstring
- mb_http_input — Detect HTTP input character encoding
- mb_http_output — Set/Get HTTP output character encoding
- mb_internal_encoding — Set/Get internal character encoding
- mb_language — Set/Get current language
- mb_lcfirst — Make a string's first character lowercase
- mb_list_encodings — Returns an array of all supported encodings
- mb_ltrim — Strip whitespace (or other characters) from the beginning of a string
- mb_ord — Get Unicode code point of character
- mb_output_handler — Callback function converts character encoding in output buffer
- mb_parse_str — Parse GET/POST/COOKIE data and set global variable
- mb_preferred_mime_name — Get MIME charset string
- mb_regex_encoding — Set/Get character encoding for multibyte regex
- mb_regex_set_options — Set/Get the default options for mbregex functions
- mb_rtrim — Strip whitespace (or other characters) from the end of a string
- mb_scrub — Replace ill-formed byte sequences with the substitute character
- mb_send_mail — Send encoded mail
- mb_split — Split multibyte string using regular expression
- mb_str_pad — Pad a multibyte string to a certain length with another multibyte string
- mb_str_split — Given a multibyte string, return an array of its characters
- mb_strcut — Get part of string
- mb_strimwidth — Get truncated string with specified width
- mb_stripos — Finds position of first occurrence of a string within another, case insensitive
- mb_stristr — Finds first occurrence of a string within another, case insensitive
- mb_strlen — Get string length
- mb_strpos — Find position of first occurrence of string in a string
- mb_strrchr — Finds the last occurrence of a character in a string within another
- mb_strrichr — Finds the last occurrence of a character in a string within another, case insensitive
- mb_strripos — Finds position of last occurrence of a string within another, case insensitive
- mb_strrpos — Find position of last occurrence of a string in a string
- mb_strstr — Finds first occurrence of a string within another
- mb_strtolower — Make a string lowercase
- mb_strtoupper — Make a string uppercase
- mb_strwidth — Return width of string
- mb_substitute_character — Set/Get substitution character
- mb_substr — Get part of string
- mb_substr_count — Count the number of substring occurrences
- mb_trim — Strip whitespace (or other characters) from the beginning and end of a string
- mb_ucfirst — Make a string's first character uppercase

- Installation/Konfiguration
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Summaries of supported encodings
- Basics of Japanese multi-byte encodings
- HTTP Input and Output
- Supported Character Encodings
- Function Overloading Feature
- PHP Character Encoding Requirements
- Multibyte String Funktionen
  - mb_check_encoding — Check if strings are valid for the specified encoding
  - mb_chr — Return character by Unicode code point value
  - mb_convert_case — Perform case folding on a string
  - mb_convert_encoding — Convert a string from one character encoding to another
  - mb_convert_kana — Convert "kana" one from another ("zen-kaku", "han-kaku" and more)
  - mb_convert_variables — Convert character code in variable(s)
  - mb_decode_mimeheader — Decode string in MIME header field
  - mb_decode_numericentity — Decode HTML numeric string reference to character
  - mb_detect_encoding — Detect character encoding
  - mb_detect_order — Set/Get character encoding detection order
  - mb_encode_mimeheader — Encode string for MIME header
  - mb_encode_numericentity — Encode character to HTML numeric string reference
  - mb_encoding_aliases — Get aliases of a known encoding type
  - mb_ereg — Regular expression match with multibyte support
  - mb_ereg_match — Regular expression match for multibyte string
  - mb_ereg_replace — Replace regular expression with multibyte support
  - mb_ereg_replace_callback — Perform a regular expression search and replace with multibyte support using a callback
  - mb_ereg_search — Multibyte regular expression match for predefined multibyte string
  - mb_ereg_search_getpos — Returns start point for next regular expression match
  - mb_ereg_search_getregs — Retrieve the result from the last multibyte regular expression match
  - mb_ereg_search_init — Setup string and regular expression for a multibyte regular expression match
  - mb_ereg_search_pos — Returns position and length of a matched part of the multibyte regular expression for a predefined multibyte string
  - mb_ereg_search_regs — Returns the matched part of a multibyte regular expression
  - mb_ereg_search_setpos — Set start point of next regular expression match
  - mb_eregi — Regular expression match ignoring case with multibyte support
  - mb_eregi_replace — Replace regular expression with multibyte support ignoring case
  - mb_get_info — Get internal settings of mbstring
  - mb_http_input — Detect HTTP input character encoding
  - mb_http_output — Set/Get HTTP output character encoding
  - mb_internal_encoding — Set/Get internal character encoding
  - mb_language — Set/Get current language
  - mb_lcfirst — Make a string's first character lowercase
  - mb_list_encodings — Returns an array of all supported encodings
  - mb_ltrim — Strip whitespace (or other characters) from the beginning of a string
  - mb_ord — Get Unicode code point of character
  - mb_output_handler — Callback function converts character encoding in output buffer
  - mb_parse_str — Parse GET/POST/COOKIE data and set global variable
  - mb_preferred_mime_name — Get MIME charset string
  - mb_regex_encoding — Set/Get character encoding for multibyte regex
  - mb_regex_set_options — Set/Get the default options for mbregex functions
  - mb_rtrim — Strip whitespace (or other characters) from the end of a string
  - mb_scrub — Replace ill-formed byte sequences with the substitute character
  - mb_send_mail — Send encoded mail
  - mb_split — Split multibyte string using regular expression
  - mb_str_pad — Pad a multibyte string to a certain length with another multibyte string
  - mb_str_split — Given a multibyte string, return an array of its characters
  - mb_strcut — Get part of string
  - mb_strimwidth — Get truncated string with specified width
  - mb_stripos — Finds position of first occurrence of a string within another, case insensitive
  - mb_stristr — Finds first occurrence of a string within another, case insensitive
  - mb_strlen — Get string length
  - mb_strpos — Find position of first occurrence of string in a string
  - mb_strrchr — Finds the last occurrence of a character in a string within another
  - mb_strrichr — Finds the last occurrence of a character in a string within another, case insensitive
  - mb_strripos — Finds position of last occurrence of a string within another, case insensitive
  - mb_strrpos — Find position of last occurrence of a string in a string
  - mb_strstr — Finds first occurrence of a string within another
  - mb_strtolower — Make a string lowercase
  - mb_strtoupper — Make a string uppercase
  - mb_strwidth — Return width of string
  - mb_substitute_character — Set/Get substitution character
  - mb_substr — Get part of string
  - mb_substr_count — Count the number of substring occurrences
  - mb_trim — Strip whitespace (or other characters) from the beginning and end of a string
  - mb_ucfirst — Make a string's first character uppercase

# Pspell

# Einführung

Warnung

Diese Erweiterung ist seit PHP 8.4.0 DEPRECATED (veraltet) und UNBUNDLED (nicht mehr eingebunden).

Diese Funktionen ermöglichen Ihnen, die Rechtschreibung eines Wortes zu prüfen und bieten Änderungsvorschläge an.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Ressource-Typen

## Anforderungen

Um PHP mit pspell-Unterstützung zu kompilieren, wird die aspell-Bibliothek benötigt, die unter » http://aspell.net/ zur Verfügung steht.

## Installation

## PHP 8.4

Diese Erweiterung wurde ins » PECL-Repositorium verschoben und ist nicht mehr Teil von PHP ab PHP 8.4.0

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/pspell.

## PHP < 8.4

Um diese Erweiterung zu aktivieren, muss PHP mit der Option --with-pspell[=dir] übersetzt werden.

> Hinweis: Anmerkung für Win32-Benutzer

> Diese Erweiterung benötigt DLL-Dateien. die für Windows verfügbar seien müssen. Der FAQ-Eintrag " Wie füge ich unter Windows PATH mein PHP-Verzeichnis hinzu?" gibt hierzu weitere Informationen. Obwohl ein einfaches Kopieren der DLL-Dateien vom PHP-Verzeichnis in den Windows-Systemordner auch funktioniert (weil der Systemordner immer im PATH enthalten ist), ist dieses Vorgehen nicht empfehlenswert. Diese Erweiterung benötigt die folgenden Dateien im PATH: aspell-15.dll aus dem Verzeichnis bin der aspell-Installation.

> Die Ünterstützung von Win32 benötigt aspell ab Version 0.50.

## Ressource-Typen

Vor PHP 8.1.0 gab es zwei Ressourcentypen, die in dieser Erweiterung verwendet wurden. Der erste ist die Kennung des Wörterbuch-Links, der zweite ist eine Ressource, die die Pspell-Konfiguration enthält.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`PSPELL_FAST` (int)
`PSPELL_NORMAL` (int)
`PSPELL_BAD_SPELLERS` (int)
`PSPELL_RUN_TOGETHER` (int)

# Pspell Funktionen

# pspell_add_to_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_personal — Fügt der persönlichen Wortliste ein Wort hinzu

### Beschreibung

function pspell_add_to_personal(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_personal() fügt der persönlichen Wortliste ein Wort hinzu. Falls pspell_new_config() mit pspell_config_personal() verwendet wurde, um das Wörterbuch zu öffnen, kann die Wortliste später mit pspell_save_wordlist() gespeichert werden.

### Parameter-Liste

`dictionary`

  Eine PSpell\Dictionary-Instanz.

`word`

  Das hinzugefügte Wort.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `dictionary` erwartet nun eine PSpell\Dictionary-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_add_to_personal()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion funktioniert nur mit pspell .11.2 und aspell .32.5 oder höher.

# pspell_add_to_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_session — Fügt der Wortliste der aktuellen Sitzung ein Wort hinzu

### Beschreibung

function pspell_add_to_session(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_add_to_session() fügt der Wortliste, die zur aktuellen Sitzung gehört, ein Wort hinzu. Diese Funktion ist der Funktion pspell_add_to_personal() sehr ähnlich.

### Parameter-Liste

`dictionary`

  Eine PSpell\Dictionary-Instanz.

`word`

  Das hinzugefügte Wort

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `dictionary` erwartet nun eine PSpell\Dictionary-Instanz; vorher wurde eine Ressource erwartet.

# pspell_check

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_check — Überprüft ein Wort

### Beschreibung

function pspell_check(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_check() überprüft die Schreibweise eines Wortes.

### Parameter-Liste

`dictionary`

  Eine PSpell\Dictionary-Instanz.

`word`

  Das zu überprüfende Wort.

### Rückgabewerte

Gibt `true` zurück, wenn die Schreibweise korrekt ist, oder `false`, wenn nicht.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `dictionary` erwartet nun eine PSpell\Dictionary-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_check()-Beispiel

    <?php
    $pspell = pspell_new("de");

    if (pspell_check($pspell, "Testt")) {
        echo "Das ist eine gültige Schreibweise";
    } else {
        echo "Sorry, falsche Schreibweise";
    }
    ?>

# pspell_clear_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_clear_session — Löscht die aktuelle Sitzung

### Beschreibung

function pspell_clear_session(PSpell\Dictionary `$dictionary`): bool

pspell_clear_session() löscht die aktuelle Sitzung. Die aktuelle Wortliste wird geleert und wenn zum Beispiel versucht wird, sie mit pspell_save_wordlist() zu speichern, passiert gar nichts.

### Parameter-Liste

`dictionary`

  Eine PSpell\Dictionary-Instanz.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `dictionary` erwartet nun eine PSpell\Dictionary-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_add_to_personal()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_clear_session($pspell);
    pspell_save_wordlist($pspell);    //"Vlad" wird nicht gespeichert
    ?>

# pspell_config_create

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_create — Erzeugt eine Konfiguration zum Öffnen eines Wörterbuchs

### Beschreibung

function pspell_config_create(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = ""
): PSpell\Config

Erzeugt eine Konfiguration zum Öffnen eines Wörterbuchs.

pspell_config_create() hat eine sehr ähnliche Syntax wie pspell_new(). Wenn pspell_config_create() direkt gefolgt von pspell_new_config() verwendet wird, hat das in der Tat genau das gleiche Ergebnis. Allerdings können nach dem Erzeugen einer neuen Konfiguration die pspell_config_*()-Funktionen verwendet werden, bevor pspell_new_config() aufgerufen wird, um von einer erweiterten Funktionalität zu profitieren.

Weitere Informationen und Beispiele sind im Online-Handbuch der pspell-Webseite zu finden: » http://aspell.net/.

### Parameter-Liste

`language`

  Der Sprachencode, der aus dem zweibuchstabigen ISO-639-Sprachencode und, nach einem Binde- oder Unterstrich, einem optionalen zweibuchstabigen ISO-3166-Ländercode besteht.

`spelling`

  Die angeforderte Schreibweise für Sprachen mit mehr als einer Schreibweise, wie zum Beispiel Englisch. Bekannte Werte sind 'american', 'british' und 'canadian'.

`jargon`

  Enthält zusätzliche Informationen, um zwischen zwei Wortlisten mit derselben Sprache und denselben Parametern für die Schreibweise zu unterscheiden.

`encoding`

  Die Kodierung, in der die Wörter voraussichtlich sind. Gültige Werte sind 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16' und 'machine unsigned 32'. Dieser Parameter ist weitgehend ungetestet, weshalb bei dessen Verwendung Vorsicht geboten ist.

### Rückgabewerte

Gibt eine PSpell\Config-Instanz zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PSpell\Config-Instanz zurück; vorher wurde ein Ressource zurückgegeben.

### Beispiele

Beispiel #1 pspell_config_create()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_personal($pspell_config, "de");
    ?>

# pspell_config_data_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_data_dir — Ort der Dateien mit den Daten für die Sprachen

### Beschreibung

function pspell_config_data_dir(PSpell\Config `$config`, string `$directory`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `config` erwartet nun eine PSpell\Config-Instanz; vorher wurde eine Ressource erwartet.

# pspell_config_dict_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_dict_dir — Ort der Haupt-Wortliste

### Beschreibung

function pspell_config_dict_dir(PSpell\Config `$config`, string `$directory`): bool

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `config` erwartet nun eine PSpell\Config-Instanz; vorher wurde eine Ressource erwartet.

# pspell_config_ignore

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_ignore — Ignoriert Wörter mit weniger als N Buchstaben

### Beschreibung

function pspell_config_ignore(PSpell\Config `$config`, int `$min_length`): bool

pspell_config_ignore() sollte auf die Konfiguration angewendet werden, bevor pspell_new_config() aufgerufen wird. Diese Funktion erlaubt der Rechtschreibprüfung, kurze Wörter zu überspringen.

### Parameter-Liste

`config`

  Eine PSpell\Config-Instanz.

`min_length`

  Wörter mit weniger als `min_length` Buchstaben werden übersprungen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `config` erwartet nun eine PSpell\Config-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_config_ignore()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_ignore($pspell_config, 5);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "abcd");    // produziert keinen Fehler
    ?>

# pspell_config_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_mode — Ändert den Modus für die Anzahl gelieferter Vorschläge

### Beschreibung

function pspell_config_mode(PSpell\Config `$config`, int `$mode`): bool

pspell_config_mode() sollte auf die Konfiguration angewendet werden, bevor pspell_new_config() aufgerufen wird. Diese Funktion bestimmt, wie viele Vorschläge von pspell_suggest() zurückgegeben werden.

### Parameter-Liste

`config`

  Eine PSpell\Config-Instanz.

`mode`

  Der Modus, in dem die Rechtschreibprüfung arbeitet. Es stehen mehrere Modi zur Verfügung:

  - `PSPELL_FAST` - Schneller Modus (geringste Anzahl Vorschläge)
  - `PSPELL_NORMAL` - Normaler Modus (mehr Vorschläge)
  - `PSPELL_BAD_SPELLERS` - Langsamer Modus (viele Vorschläge)

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `config` erwartet nun eine PSpell\Config-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_config_mode()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_mode($pspell_config, PSPELL_FAST);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "dieSpinne");
    ?>

# pspell_config_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_personal — Legt die Datei fest, die die persönliche Wortliste enthält

### Beschreibung

function pspell_config_personal(PSpell\Config `$config`, string `$filename`): bool

Legt die Datei fest, die die persönliche Wortliste enthält. Die persönliche Wortliste wird geladen und nach dem Aufruf von pspell_new_config() zusätzlich zur standardmäßigen verwendet. Diese Datei ist auch der Ort, an dem pspell_save_wordlist() die persönliche Wortliste speichert.

pspell_config_personal() sollte auf die Konfiguration angewendet werden, bevor pspell_new_config() aufgerufen wird.

### Parameter-Liste

`config`

  Eine PSpell\Config-Instanz.

`filename`

  Die persönliche Wortliste. Falls die Datei nicht existiert, wird sie angelegt. Die Datei sollte für denjenigen, unter dem PHP läuft (z. B. nobody), eine Schreibberechtigung haben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `config` erwartet nun eine PSpell\Config-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_config_personal()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "dieSpinne");
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion funktioniert nur mit pspell .11.2 und aspell .32.5 oder höher.

# pspell_config_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_repl — Legt die Datei fest, welche die Ersetzungspaare enthält

### Beschreibung

function pspell_config_repl(PSpell\Config `$config`, string `$filename`): bool

Legt die Datei fest, welche die Ersetzungspaare enthält.

Die Ersetzungspaare verbessern die Qualität der Rechtschreibprüfung. Wenn ein Wort falsch geschrieben und in der Wortliste kein passender Vorschlag gefunden wurde, kann pspell_store_replacement() zum Speichern eines Ersetzungspaares verwendet werden und dann pspell_save_wordlist() zum Speichern der Wortliste zusammen mit den Ersetzungspaaren.

pspell_config_repl() sollte auf die Konfiguration angewendet werden, bevor pspell_new_config() aufgerufen wird.

### Parameter-Liste

`config`

  Eine PSpell\Config-Instanz.

`filename`

  Die Datei sollte für denjenigen, unter dem PHP läuft (z. B. nobody), eine Schreibberechtigung haben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `config` erwartet nun eine PSpell\Config-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_config_repl()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "dieSpinne");
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion funktioniert nur mit pspell .11.2 und aspell .32.5 oder höher.

# pspell_config_runtogether

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_runtogether — Betrachtet zusammengesetzte Wörter als gültige Verbindungen

### Beschreibung

function pspell_config_runtogether(PSpell\Config `$config`, bool `$allow`): bool

Diese Funktion bestimmt, ob zusammengesetzte Wörter als erlaubte Verbindungen betrachtet werden. Das heißt, "dieSpinne" wäre dann eine erlaubte Verbindung, obwohl ein Leerzeichen zwischen den beiden Wörtern sein müsste. Eine Änderung dieser Einstellung wirkt sich nur auf das Ergebnis aus, das von pspell_check() zurückgegeben wird; pspell_suggest() liefert weiterhin Änderungsvorschläge.

pspell_config_runtogether() sollte auf die Konfiguration angewendet werden, bevor pspell_new_config() aufgerufen wird.

### Parameter-Liste

`config`

  Eine PSpell\Config-Instanz.

`allow`

  `true`, falls zusammengesetzte Wörter als gültige Verbindungen betrachtet werden sollen, andernfalls `false`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `config` erwartet nun eine PSpell\Config-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_config_runtogether()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_runtogether($pspell_config, true);
    $pspell = pspell_new_config($pspell_config);
    pspell_check($pspell, "dieSpinne");
    ?>

# pspell_config_save_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_save_repl — Bestimmt, ob Ersetzungspaare zusammen mit der Wortliste gespeichert werden

### Beschreibung

function pspell_config_save_repl(PSpell\Config `$config`, bool `$save`): bool

Die Funktion pspell_config_save_repl() bestimmt, ob pspell_save_wordlist() Ersetzungspaare zusammen mit der Wortliste speichert. Normalerweise wird sie nicht benötigt, denn wenn die Funktion pspell_config_repl() verwendet wird, werden die Ersetzungspaare sowieso durch pspell_save_wordlist() gespeichert, und wenn sie nicht verwendet wird, werden die Ersetzungspaare nicht gespeichert.

pspell_config_save_repl() sollte auf die Konfiguration angewendet werden, bevor pspell_new_config() aufgerufen wird.

### Parameter-Liste

`config`

  Eine PSpell\Config-Instanz.

`save`

  `true`, falls Ersetzungspaare gespeichert werden sollen, andernfalls `false`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `config` erwartet nun eine PSpell\Config-Instanz; vorher wurde eine Ressource erwartet.

### Anmerkungen

> Hinweis:

> Diese Funktion funktioniert nur mit pspell .11.2 und aspell .32.5 oder höher.

# pspell_new

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new — Lädt ein neues Wörterbuch

### Beschreibung

function pspell_new(
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new() öffnet ein neues Wörterbuch und gibt eine PSpell\Dictionary-Instanz für die Verwendung in anderen pspell-Funktionen zurück.

Weitere Informationen und Beispiele sind im Online-Handbuch der pspell-Webseite zu finden: » http://aspell.net/.

### Parameter-Liste

`language`

  Der Sprachencode, der aus dem zweibuchstabigen ISO-639-Sprachencode und, nach einem Binde- oder Unterstrich, einem optionalen zweibuchstabigen ISO-3166-Ländercode besteht.

`spelling`

  Die angeforderte Schreibweise für Sprachen mit mehr als einer Schreibweise, wie zum Beispiel Englisch. Bekannte Werte sind 'american', 'british' und 'canadian'.

`jargon`

  Enthält zusätzliche Informationen, um zwischen zwei Wortlisten mit derselben Sprache und denselben Parametern für die Schreibweise zu unterscheiden.

`encoding`

  Die Kodierung, in der die Wörter voraussichtlich sind. Gültige Werte sind 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16' und 'machine unsigned 32'. Dieser Parameter ist weitgehend ungetestet, weshalb bei dessen Verwendung Vorsicht geboten ist.

`mode`

  Der Modus, in dem die Rechtschreibprüfung arbeitet. Es stehen mehrere Modi zur Verfügung:

  - `PSPELL_FAST` - Schneller Modus (geringste Anzahl Vorschläge)
  - `PSPELL_NORMAL` - Normaler Modus (mehr Vorschläge)
  - `PSPELL_BAD_SPELLERS` - Langsamer Modus (viele Vorschläge)
  - `PSPELL_RUN_TOGETHER` - Betrachtet zusammengesetzte Wörter als erlaubte Verbindungen. Das heißt, "dieSpinne" wäre dann eine erlaubte Verbindung, obwohl ein Leerzeichen zwischen den beiden Wörtern sein müsste. Eine Änderung dieser Einstellung wirkt sich nur auf das Ergebnis aus, das von pspell_check() zurückgegeben wird; pspell_suggest() liefert weiterhin Änderungsvorschläge.
  `mode` ist eine Bitmaske, die sich aus verschiedenden der oben aufgelisteten Konstanten zusammensetzt. `PSPELL_FAST`, `PSPELL_NORMAL` und `PSPELL_BAD_SPELLERS` schließen sich allerdings gegenseitig aus, weshalb nur eine davon ausgewählt werden sollte.

### Rückgabewerte

Gibt bei Erfolg eine PSpell\Dictionary-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PSpell\Dictionary-Instanz zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 pspell_new()-Beispiel

    <?php
    $pspell = pspell_new("de", "", "", "",
                         (PSPELL_FAST|PSPELL_RUN_TOGETHER));
    ?>

# pspell_new_config

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_config — Lädt ein neues Wörterbuch mit den Einstellungen einer angegebenen Konfiguration

### Beschreibung

function pspell_new_config(PSpell\Config `$config`): PSpell\Dictionary|false

pspell_new_config() öffnet ein neues Wörterbuch, das mittels pspell_config_create() erzeugt und mit den pspell_config_*()-Funktionen geändert wurde, mit den Einstellungen aus `config`. Diese Methode bietet die größte Flexibilität und hat die ganze Funktionalität, die pspell_new() und pspell_new_personal() bieten.

### Parameter-Liste

`config`

  `config` ist der Parameter, der von pspell_config_create() beim Erzeugen der Konfiguration zurückgegeben wird.

### Rückgabewerte

Gibt bei Erfolg eine PSpell\Dictionary-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `config` erwartet nun eine PSpell\Config-Instanz; vorher wurde eine Ressource erwartet.
8.1.0 | Gibt nun eine PSpell\Dictionary-Instanz zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 pspell_new_config()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);
    ?>

# pspell_new_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_personal — Lädt ein neues Wörterbuch mit persönlicher Wortliste

### Beschreibung

function pspell_new_personal(
string `$filename`,
string `$language`,
string `$spelling` = "",
string `$jargon` = "",
string `$encoding` = "",
int `$mode` = 0
): PSpell\Dictionary|false

pspell_new_personal() öffnet ein neues Wörterbuch mit einer persönlichen Wortliste. Die Wortliste kann bei Bedarf mit pspell_save_wordlist() geändert und gespeichert werden. Die Ersetzungspaare werden jedoch nicht gespeichert. Um diese zu speichern, müssen Sie mittels pspell_config_create() eine Konfiguration erzeugen, die persönliche Wortliste mit pspell_config_personal() setzen, die Datei für die Ersetzen-Paare mit pspell_config_repl() setzen und mit pspell_new_config() ein neues Wörterbuch öffnen.

Weitere Informationen und Beispiele sind im Online-Handbuch der pspell-Webseite zu finden: » http://aspell.net/.

### Parameter-Liste

`filename`

  Die Datei, in der Wörter, die zur persönlichen Wortliste hinzugefügt wurden, gespeichert werden. Dieser Parameter sollte als absoluter Dateiname mit '/' beginnend angegeben werden, weil er andernfalls relativ zu $HOME wäre, was auf den meisten Systemen '/root' ist und es vermutlich nicht das ist, was Sie wollen.

`language`

  Der Sprachencode, der aus dem zweibuchstabigen ISO-639-Sprachencode und, nach einem Binde- oder Unterstrich, einem optionalen zweibuchstabigen ISO-3166-Ländercode besteht.

`spelling`

  Die angeforderte Schreibweise für Sprachen mit mehr als einer Schreibweise, wie zum Beispiel Englisch. Bekannte Werte sind 'american', 'british' und 'canadian'.

`jargon`

  Enthält zusätzliche Informationen, um zwischen zwei Wortlisten mit derselben Sprache und denselben Parametern für die Schreibweise zu unterscheiden.

`encoding`

  Die Kodierung, in der die Wörter voraussichtlich sind. Gültige Werte sind `utf-8`, `iso8859-*`, `koi8-r`, `viscii`, `cp1252`, `machine unsigned 16` und `machine unsigned 32`.

`mode`

  Der Modus, in dem die Rechtschreibprüfung arbeitet. Es stehen mehrere Modi zur Verfügung:

  - `PSPELL_FAST` - Schneller Modus (geringste Anzahl Vorschläge)
  - `PSPELL_NORMAL` - Normaler Modus (mehr Vorschläge)
  - `PSPELL_BAD_SPELLERS` - Langsamer Modus (viele Vorschläge)
  - `PSPELL_RUN_TOGETHER` - Betrachtet zusammengesetzte Wörter als erlaubte Verbindungen. Das heißt, "dieSpinne" wäre dann eine erlaubte Verbindung, obwohl ein Leerzeichen zwischen den beiden Wörtern sein müsste. Eine Änderung dieser Einstellung wirkt sich nur auf das Ergebnis aus, das von pspell_check() zurückgegeben wird; pspell_suggest() liefert weiterhin Änderungsvorschläge.
  `mode` ist eine Bitmaske, die sich aus verschiedenden der oben aufgelisteten Konstanten zusammensetzt. `PSPELL_FAST`, `PSPELL_NORMAL` und `PSPELL_BAD_SPELLERS` schließen sich allerdings gegenseitig aus, weshalb nur eine davon ausgewählt werden sollte.

### Rückgabewerte

Gibt bei Erfolg eine PSpell\Dictionary-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine PSpell\Dictionary-Instanz zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 pspell_new_personal()-Beispiel

    <?php
    $pspell = pspell_new_personal ("/var/dictionaries/custom.pws",
            "de", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER);
    ?>

# pspell_save_wordlist

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_save_wordlist — Speichert die persönliche Wortliste in einer Datei

### Beschreibung

function pspell_save_wordlist(PSpell\Dictionary `$dictionary`): bool

pspell_save_wordlist() speichert die persönliche Wortliste der aktuellen Sitzung. Die Stelle der zu speichernden Dateien muss mit pspell_config_personal() und (optional) pspell_config_repl() bestimmt werden.

### Parameter-Liste

`dictionary`

  Eine PSpell\Dictionary-Instanz.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `dictionary` erwartet nun eine PSpell\Dictionary-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_add_to_personal()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_personal($pspell_config, "/tmp/dicts/newdict");
    $pspell = pspell_new_config($pspell_config);

    pspell_add_to_personal($pspell, "Vlad");
    pspell_save_wordlist($pspell);
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion funktioniert nur mit pspell .11.2 und aspell .32.5 oder höher.

# pspell_store_replacement

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_store_replacement — Speichert das Ersetzungspaar für ein Wort

### Beschreibung

function pspell_store_replacement(PSpell\Dictionary `$dictionary`, string `$misspelled`, string `$correct`): bool

pspell_store_replacement() speichert das Ersetzungspaar für ein Wort, damit dieses Ersetzungspaar später von pspell_suggest() zurückgegeben werden kann. Um von dieser Funktion profitieren zu können, muss pspell_new_personal() zum Öffnen des Wörterbuchs verwendet werden. Um das Ersetzungspaar dauerhaft zu speichern, müssen pspell_config_personal() und pspell_config_repl() verwendet werden, um den Pfad zu setzen, unter dem die selbst erstellten Wortlisten gespeichert werden sollen und dann pspell_save_wordlist(), damit die Änderungen auf die Festplatte geschrieben werden.

### Parameter-Liste

`dictionary`

  Eine PSpell\Dictionary-Instanz.

`misspelled`

  Das falsch geschriebene Wort

`correct`

  Die richtige Schreibweise für `misspelled`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `dictionary` erwartet nun eine PSpell\Dictionary-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_store_replacement()-Beispiel

    <?php
    $pspell_config = pspell_config_create("de");
    pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws");
    pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl");
    $pspell = pspell_new_config($pspell_config);

    pspell_store_replacement($pspell, $falsch, $richtig);
    pspell_save_wordlist($pspell);
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion funktioniert nur mit pspell .11.2 und aspell .32.5 oder höher.

# pspell_suggest

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_suggest — Macht Vorschläge für die Schreibweise eines Wortes

### Beschreibung

function pspell_suggest(PSpell\Dictionary `$dictionary`, string `$word`): array|false

pspell_suggest() gibt ein Array möglicher Schreibweisen für das angegebene Wort zurück.

### Parameter-Liste

`dictionary`

  Eine PSpell\Dictionary-Instanz.

`word`

  Das zu überprüfende Wort.

### Rückgabewerte

Gibt ein Array möglicher Schreibweisen zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `dictionary` erwartet nun eine PSpell\Dictionary-Instanz; vorher wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 pspell_suggest()-Beispiel

    <?php
    $pspell = pspell_new("de");

    if (!pspell_check($pspell, "Testt")) {
        $vorschlaege = pspell_suggest($pspell, "Testt");

        foreach ($vorschlaege as $vorschlag) {
            echo "Mögliche Schreibweise: $vorschlag<br />";
        }
    }
    ?>

## Inhaltsverzeichnis

- pspell_add_to_personal — Fügt der persönlichen Wortliste ein Wort hinzu
- pspell_add_to_session — Fügt der Wortliste der aktuellen Sitzung ein Wort hinzu
- pspell_check — Überprüft ein Wort
- pspell_clear_session — Löscht die aktuelle Sitzung
- pspell_config_create — Erzeugt eine Konfiguration zum Öffnen eines Wörterbuchs
- pspell_config_data_dir — Ort der Dateien mit den Daten für die Sprachen
- pspell_config_dict_dir — Ort der Haupt-Wortliste
- pspell_config_ignore — Ignoriert Wörter mit weniger als N Buchstaben
- pspell_config_mode — Ändert den Modus für die Anzahl gelieferter Vorschläge
- pspell_config_personal — Legt die Datei fest, die die persönliche Wortliste enthält
- pspell_config_repl — Legt die Datei fest, welche die Ersetzungspaare enthält
- pspell_config_runtogether — Betrachtet zusammengesetzte Wörter als gültige Verbindungen
- pspell_config_save_repl — Bestimmt, ob Ersetzungspaare zusammen mit der Wortliste gespeichert werden
- pspell_new — Lädt ein neues Wörterbuch
- pspell_new_config — Lädt ein neues Wörterbuch mit den Einstellungen einer angegebenen Konfiguration
- pspell_new_personal — Lädt ein neues Wörterbuch mit persönlicher Wortliste
- pspell_save_wordlist — Speichert die persönliche Wortliste in einer Datei
- pspell_store_replacement — Speichert das Ersetzungspaar für ein Wort
- pspell_suggest — Macht Vorschläge für die Schreibweise eines Wortes

# The PSpell\Dictionary class

(PHP 8 >= 8.1.0)

## Einführung

A fully opaque class which replaces a `pspell` resource as of PHP 8.1.0.

## Klassenbeschreibung

final class PSpell\Dictionary {
}

# The PSpell\Config class

(PHP 8 >= 8.1.0)

## Einführung

A fully opaque class which replaces a `pspell config` resource as of PHP 8.1.0.

## Klassenbeschreibung

final class PSpell\Config {
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- Pspell Funktionen
  - pspell_add_to_personal — Fügt der persönlichen Wortliste ein Wort hinzu
  - pspell_add_to_session — Fügt der Wortliste der aktuellen Sitzung ein Wort hinzu
  - pspell_check — Überprüft ein Wort
  - pspell_clear_session — Löscht die aktuelle Sitzung
  - pspell_config_create — Erzeugt eine Konfiguration zum Öffnen eines Wörterbuchs
  - pspell_config_data_dir — Ort der Dateien mit den Daten für die Sprachen
  - pspell_config_dict_dir — Ort der Haupt-Wortliste
  - pspell_config_ignore — Ignoriert Wörter mit weniger als N Buchstaben
  - pspell_config_mode — Ändert den Modus für die Anzahl gelieferter Vorschläge
  - pspell_config_personal — Legt die Datei fest, die die persönliche Wortliste enthält
  - pspell_config_repl — Legt die Datei fest, welche die Ersetzungspaare enthält
  - pspell_config_runtogether — Betrachtet zusammengesetzte Wörter als gültige Verbindungen
  - pspell_config_save_repl — Bestimmt, ob Ersetzungspaare zusammen mit der Wortliste gespeichert werden
  - pspell_new — Lädt ein neues Wörterbuch
  - pspell_new_config — Lädt ein neues Wörterbuch mit den Einstellungen einer angegebenen Konfiguration
  - pspell_new_personal — Lädt ein neues Wörterbuch mit persönlicher Wortliste
  - pspell_save_wordlist — Speichert die persönliche Wortliste in einer Datei
  - pspell_store_replacement — Speichert das Ersetzungspaar für ein Wort
  - pspell_suggest — Macht Vorschläge für die Schreibweise eines Wortes
- PSpell\Dictionary — The PSpell\Dictionary class
- PSpell\Config — The PSpell\Config class

# GNU Recode

# Einführung

Warnung

Diese Erweiterung wird nicht mehr gepflegt.

Das Modul enthält ein Interface zur GNU Recode-Bibliothek. Die GNU Recode-Bibliothek konvertiert Dateien zwischen unterschiedlichen Zeichensätzen und Encodings. Wenn diese nicht exakt bestimmt werden können, kann es sein, dass die "fehlerhaften" Zeichen entfernt werden und eine Fallback-Ersetzung vorgenommen wird. Die Bibliothek erkennt und verarbeitet etwa 150 unterschiedliche Zeichensätze und ist dafür ausgelegt, Dateien zwischen jeder der damit möglichen Kombinationen zu konvertieren. Die meisten » RFC 1345-Zeichensätze werden unterstützt.

> Hinweis: Diese Erweiterung ist von PHP 7.4.0 an entbündelt und nach » PECL verschoben. Es ist zu erwägen statt dessen die Erweiterung Multibyte String oder iconv zu verwenden.

> Hinweis: Diese Erweiterung steht auf Windows-Plattformen nicht zur Verfügung.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

Sie müssen GNU Recode 3.5 oder höher auf Ihrem System installiert haben. Das Paket können Sie von » http://directory.fsf.org/All_GNU_Packages/recode.html herunterladen.

Warnung

Die Recode Library 3.6 fügt an unter bestimmten Umständen an konvertierte Strings seltsame Zeichen an. Daher ist es sicherer, Recode v3.5 oder eine der verfügbaren Alternativen wie die iconv- oder mbstring-Extension zu verwenden.

## Installation

## PHP 7.4

Diese Erweiterung wurde ins » PECL-Repositorium verschoben und ist nicht mehr Teil von PHP ab PHP 7.4.0

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/recode.

## PHP < 7.4

Um die von diesem Modul definierten Funktionen nutzbar zu machen, müssen Sie Ihr PHP mit der Option --with-recode[=DIR] kompilieren.

Warnung

Abstürze und Startprobleme von PHP können auftreten, wenn die Recode-Extension nach einer der beiden Extensions mysql oder imap geladen wird. Wenn die Recode-Extension vor den genannten anderen geladen wird, tritt das Problem nicht auf. Das Problem resultiert aus dem technischen Grund, dass die C-Clientlibrary, die von Imap und Recode genutzt wird, jeweils ihre eigenen `hach_lookup()`-Funktionalitäten mitbringt. Der Konflikt mit der MySQL-Extension entsteht durch unterschiedliche `hash_insert`-Funktionalitäten.

Warnung

Die Erweiterungen IMAP, recode und YAZ können nicht zusammen verwendet werden. Diese Tatsache liegt darin begründet, dass alle diese Erweiterungen die gleichen internen Symbole benutzen. Hinweis: Yaz 2.0 und höher hat dieses Problem nicht.

# Recode-Funktionen

# recode

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode — Alias von recode_string()

### Beschreibung

Diese Funktion ist ein Alias für: recode_string().

# recode_file

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_file — Umkodierung von Dateien entsprechend der Recode-Anweisung

### Beschreibung

function recode_file(string `$request`, resource `$input`, resource `$output`): bool

Umkodierung der Datei, die durch den Dateizeiger `input` referenziert wird, in die Datei `output`, entsprechend der Recode-Anweisung `request`.

### Parameter-Liste

`request`
  Der gewünschte Recode-Requesttyp.
`input`
  Ein lokaler Dateizeiger vom Typ resource für den `input`-Parameter.
`output`
  Ein lokaler Dateizeiger vom Typ resource für den `output`-Parameter.

### Rückgabewerte

Gibt `false` zurück, wenn es nicht möglich ist, die Anweisung durchzuführen, andernfalls `true`.

### Beispiele

Beispiel #1 Einfaches recode_file()-Beispiel

    <?php
    $input = fopen('input.txt', 'r');
    $output = fopen('output.txt', 'w');
    recode_file("us..flat", $input, $output);
    ?>

### Anmerkungen

Die Funktion verarbeitet derzeit keine Dateizeiger, die auf entfernte Dateien zeigen (URLs). Beide Dateizeiger müssen auf lokale Dateien zeigen.

### Siehe auch

- fopen() - Öffnet eine Datei oder URL

# recode_string

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_string — Kodiert einen String entsprechend einer Recode-Anweisung um

### Beschreibung

function recode_string(string `$request`, string `$string`): string

Der Parameter `string` wird entsprechend der Recode-Anweisung `request` umgewandelt.

### Parameter-Liste

`request`
  Der gewünschte Recode-Anweisungstyp
`string`
  Der umzukodierende String

### Rückgabewerte

Gibt den umkodierten String zurück oder `false`, wenn es nicht möglich ist, die Recode-Anweisung auszuführen.

### Beispiele

Beispiel #1 Einfaches recode_string()-Beispiel:

    <?php
    echo recode_string("us..flat", "Der folgende Buchstabe hat ein diakritisches Zeichen: á");
    ?>

### Anmerkungen

Eine einfache Recode-Anweisung könnte "lat1..iso646-de" sein.

### Siehe auch

- Detaillierte Anweisungen zur Gestaltung der Recode-Anfrage sind in der Dokumentation des installierten GNU Recode zu finden.
- mb_convert_encoding() - Convert a string from one character encoding to another
- UConverter::transcode() - Convert a string from one character encoding to another
- iconv() - Konvertiert eine Zeichenkette von einem Zeichensatz in einen anderen

## Inhaltsverzeichnis

- recode — Alias von recode_string
- recode_file — Umkodierung von Dateien entsprechend der Recode-Anweisung
- recode_string — Kodiert einen String entsprechend einer Recode-Anweisung um

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Recode-Funktionen
  - recode — Alias von recode_string
  - recode_file — Umkodierung von Dateien entsprechend der Recode-Anweisung
  - recode_string — Kodiert einen String entsprechend einer Recode-Anweisung um

- Enchant — Enchant spelling library
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Enchant Funktionen
  - EnchantBroker — The EnchantBroker class
  - EnchantDictionary — The EnchantDictionary class
- Gender — Geschlecht aus Vornamen ermitteln
  - Installation/Konfiguration
  - Beispiele
  - Gender\Gender — The Gender\Gender class
- Gettext
  - Installation/Konfiguration
  - Gettext-Funktionen
- iconv
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - iconv Funktionen
- intl — Internationalization Functions
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Collator — The Collator class
  - NumberFormatter — The NumberFormatter class
  - Locale — The Locale class
  - Normalizer — The Normalizer class
  - MessageFormatter — The MessageFormatter class
  - IntlCalendar — The IntlCalendar class
  - IntlGregorianCalendar — The IntlGregorianCalendar class
  - IntlTimeZone — The IntlTimeZone class
  - IntlDateFormatter — The IntlDateFormatter class
  - ResourceBundle — The ResourceBundle class
  - Spoofchecker — The Spoofchecker class
  - Transliterator — The Transliterator class
  - IntlBreakIterator — The IntlBreakIterator class
  - IntlRuleBasedBreakIterator — The IntlRuleBasedBreakIterator class
  - IntlCodePointBreakIterator — The IntlCodePointBreakIterator class
  - IntlDatePatternGenerator — The IntlDatePatternGenerator class
  - IntlPartsIterator — The IntlPartsIterator class
  - UConverter — Die Klasse UConverter
  - Grapheme Funktionen
  - IDN Funktionen
  - IntlChar
  - IntlException — Exception class for intl errors
  - IntlIterator — The IntlIterator class
  - intl Funktionen
- Multibyte String
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Summaries of supported encodings
  - Basics of Japanese multi-byte encodings
  - HTTP Input and Output
  - Supported Character Encodings
  - Function Overloading Feature
  - PHP Character Encoding Requirements
  - Multibyte String Funktionen
- Pspell
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Pspell Funktionen
  - PSpell\Dictionary — The PSpell\Dictionary class
  - PSpell\Config — The PSpell\Config class
- Recode — GNU Recode
  - Installation/Konfiguration
  - Recode-Funktionen

# Bildverarbeitung und -generierung

# Exchangable Image Information (EXIF)

# Einführung

Die Exif-Erweiterung ermöglicht es mit Metadaten von Bildern zu arbeiten, z. B. kann man die Exif-Funktionen nutzen, um die Metadaten von Bildern auszulesen, die mit Digitalkameras gemacht wurden, indem man die Header ausliest. Diese finden sich üblicherweise in JPEG und TIFF Bildern.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

PHP muss mit `--enable-exif` kompiliert werden. Um Multibyte-Unterstützung in EXIF-Tags zu aktivieren, muss die Erweiterung mbstring durch Kompilieren von PHP mit `--enable-mbstring` aktiviert sein. PHP braucht keine weiteren Bibliotheken für das Exif-Modul.

## Installation

Um PHP mit Exif-Unterstützung nutzen zu können, muss man PHP mit der Option --enable-exif kompilieren.

Windows-Nutzer müssen die DLLs php_mbstring.dll und php_exif.dll in der php.ini aktivieren. Die php_mbstring.dll muss vor der php_exif.dll geladen werden. Die php.ini muss entsprechend angepasst werden.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Exif unterstützt eine automatische Konvertierung von Unicode- und JIS-kodierten Zeichen von Nutzerkommentaren, wenn das Modul mbstring verfügbar ist. Dies wird gemacht, indem zuerst die spezifizierten Kommentare dekodiert werden. Das Ergebnis ist dann mit einem Zeichensatz kodiert, der mit der `HTTP`-Ausgabe übereinstimmen sollte.

Exif-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
exif.encode_unicode | "ISO-8859-15" | `INI_ALL` |
exif.decode_unicode_motorola | "UCS-2BE" | `INI_ALL` |
exif.decode_unicode_intel | "UCS-2LE" | `INI_ALL` |
exif.encode_jis | "" | `INI_ALL` |
exif.decode_jis_motorola | "JIS" | `INI_ALL` |
exif.decode_jis_intel | "JIS" | `INI_ALL` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`exif.encode_unicode` string
  `exif.encode_unicode` definiert den Zeichensatz für UNICODE-Nutzerkommentare. Der Standardwert ist ISO-8859-15, welcher für die meisten nicht-asiatischen Länder funktionieren sollte. Der Wert darf leer sein oder muss eine Kodierung enthalten, die von mbstring unterstützt wird. Ist der Wert leer, wird die aktuelle, interne Kodierung von mbstring genutzt.
`exif.decode_unicode_motorola` string
  `exif.decode_unicode_motorola` definiert den internen Zeichensatz des Bildes für Unicode-kodierte Nutzerkommentare, sollte das Bild in der Motorola-Bytefolge (big-endian) sein. Dieser Wert darf nicht leer sein, sondern kann mit einer Liste von Kodierungen gefüllt werden, die von mbstring unterstützt werden. Der Standard ist UCS-2BE.
`exif.decode_unicode_intel` string
  `exif.decode_unicode_intel` definiert den internen Zeichensatz des Bildes für Unicode-kodierte Nutzerkommentare, sollte das Bild in der Intel-Bytefolge (little-endian) sein. Dieser Wert darf nicht leer sein, sondern kann mit einer Liste von Kodierungen gefüllt werden, die von mbstring unterstützt werden. Der Standard ist UCS-2LE.
`exif.encode_jis` string
  `exif.encode_jis` definiert den Zeichensatz, mit dem JIS-Nutzerkommentare behandelt werden. Der Standard ist leer und zwingt die Funktionen dazu, die aktuelle interne Kodierung von mbstring zu nutzen.
`exif.decode_jis_motorola` string
  `exif.decode_jis_motorola` definiert den internen Zeichensatz des Bildes für JIS-kodierte Nutzerkommentare, sollte das Bild in der Motorola-Bytefolge (big-endian) sein. Dieser Wert darf nicht leer sein, sondern kann mit einer Liste von Kodierungen gefüllt werden, die von mbstring unterstützt werden. Der Standard ist JIS.
`exif.decode_jis_intel` string
  `exif.decode_jis_intel` definiert den internen Zeichensatz des Bildes für JIS-kodierte Nutzerkommentare, sollte das Bild in der Intel-Bytefolge (little-endian) sein. Dieser Wert darf nicht leer sein, sondern kann mit einer Liste von Kodierungen gefüllt werden, die von mbstring unterstützt werden. Der Standard ist JIS.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`EXIF_USE_MBSTRING` (int)
  Diese Konstante hat den Wert `1`, wenn mbstring aktiviert ist; anderfalls ist ihr Wert `0`.

exif_imagetype() listet einige eingebaute Konstanten auf.

# Exif-Funktionen

# exif_imagetype

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

exif_imagetype — Ermittelt den Bildtyp

### Beschreibung

function exif_imagetype(string `$filename`): int|false

exif_imagetype() liest die ersten Bytes eines Bildes aus und überprüft dessen Signatur.

exif_imagetype() kann benutzt werden, um Aufrufe anderer exif-Funktionen bei nicht unterstützten Dateitypen zu vermeiden. Es kann in Verbindung mit $_SERVER['HTTP_ACCEPT'] auch dazu verwendet werden, zu überprüfen, ob der Betrachter ein bestimmtes Bild in seinem Browser angezeigt bekommt oder nicht.

### Parameter-Liste

`filename`
  Das zu überprüfende Bild.

### Rückgabewerte

Bei einer korrekten Signatur wird die entsprechende Konstante als Wert zurückgegeben, andernfalls `false`. Der Rückgabewert ist derselbe, der auch von getimagesize() als Index 2 zurückgegeben wird, aber exif_imagetype() ist deutlich schneller.

Die folgenden Konstanten sind definiert und repräsentieren die möglichen Rückgabewerte von exif_imagetype():

Konstanten für Bildtypen
Wert | Konstante
--- | ---
1 | `IMAGETYPE_GIF`
2 | `IMAGETYPE_JPEG`
3 | `IMAGETYPE_PNG`
4 | `IMAGETYPE_SWF`
5 | `IMAGETYPE_PSD`
6 | `IMAGETYPE_BMP`
7 | `IMAGETYPE_TIFF_II` (Intel-Bytefolge)
8 | `IMAGETYPE_TIFF_MM` (Motorola-Bytefolge)
9 | `IMAGETYPE_JPC`
10 | `IMAGETYPE_JP2`
11 | `IMAGETYPE_JPX`
12 | `IMAGETYPE_JB2`
13 | `IMAGETYPE_SWC`
14 | `IMAGETYPE_IFF`
15 | `IMAGETYPE_WBMP`
16 | `IMAGETYPE_XBM`
17 | `IMAGETYPE_ICO`
18 | `IMAGETYPE_WEBP`
19 | `IMAGETYPE_AVIF`

> Hinweis: exif_imagetype() löst einen Fehler vom Typ `E_NOTICE` aus und gibt `false` zurück, wenn die Funktion nicht genügend Bytes aus der Datei lesen konnte, um den Bildtyp zu bestimmen.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Unterstützung für AVIF hinzugefügt.
7.1.0 | Unterstützung für WebP hinzugefügt.

### Beispiele

Beispiel #1 exif_imagetype()-Beispiel

    <?php
    if (exif_imagetype('image.gif') != IMAGETYPE_GIF) {
        echo 'Das Bild ist kein gif';
    }
    ?>

### Siehe auch

- image_type_to_mime_type() - Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- getimagesize() - Liefert die Größe einer Grafik

# exif_read_data

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_read_data — Liest die EXIF-Header einer Bilddatei aus

### Beschreibung

function exif_read_data(
resource|string `$file`,
?string `$required_sections` = `null`,
bool `$as_arrays` = `false`,
bool `$read_thumbnail` = `false`
): array|false

exif_read_data() liest die EXIF-Header aus einer Bilddatei aus. Auf diese Weise können die Metadaten ausgelesen werden, die mit Digitalkameras erzeugt wurden.

EXIF-Header kommen normalerweise bei JPEG/TIFF-Bildern vor, die von Digitalkameras gemacht wurden. Leider hat jeder Kamerahersteller eine andere Vorstellung davon, wie man die Bilder beschreibt, sodass man sich nicht darauf verlassen kann, das ein bestimmter Exif-Header vorhanden ist.

`Height` und `Width` werden genauso wie getimagesize() berechnet. Diese Werte dürfen also nicht Teil von irgendwelchen Headern sein, die zurückgegeben werden. Ferner ist `html` ein Höhen/Breiten-Textstring für den Gebrauch in normalem HTML.

Wenn ein Exif-Header einen Copyrightvermerk beinhaltet, kann dieser selbst aus zwei Werten bestehen. Da die Lösung im Exif-2.10 -Standard nicht konsistent ist, liefert der `COMPUTED`-Bereich die beiden Einträge `Copyright.Photographer` und `Copyright.Editor`, während die `IFD`-Bereiche aus einem Byte-Array besteht, in dem die beiden Werte durch ein NULL-Zeichen getrennt sind. Wenn der Datentyp falsch ist, ist nur der erste Eintrag vorhanden (normales Verhalten von Exif). `COMPUTED` beinhaltet auch einen `Copyright`-Eintrag. Dieser entspricht entweder dem originalen Copyright-String oder er besteht aus einer kommaseparierten Liste von Foto- und Herausgeber-Copyright.

Der Tag `UserComment` hat das gleiche Problem, wie das Copyright-Tag. Er kann zwei Werte speichern. Als erstes die verwendete Kodierung und als zweites den Wert selbst. Wenn dem so ist, enthält der `IFD`-Bereich nur die Kodierung oder ein Byte-Array. Der `COMPUTED`-Bereich speichert beide in den Einträgen `UserCommentEncoding` und `UserComment`. Der Eintrag `UserComment` ist in beiden Fällen verfügbar. Er sollte also dem Eintrag im `IFD0`-Bereich vorgezogen werden.

exif_read_data() validiert auch EXIF-Datentags entsprechend der EXIF-Spezifikationen (» http://exif.org/Exif2-2.PDF, Seite 20).

### Parameter-Liste

`file`
  Der Ort der Bilddatei. Dies kann entweder der Pfad der Datei (Stream-Wrapper werden wie üblich ebenso unterstützt) oder eine Stream-Ressource sein.
`required_sections`

  Ist eine kommaseparierte Liste von Bereichen, die in der Datei vorhanden sein müssen, um das Rückgabe-Array zu erzeugen. Wenn keiner der geforderten Bereiche gefunden werden kann, wird `false` zurückgegeben.

  FILE | FileName, FileSize, FileDateTime, SectionsFound
  COMPUTED | html, Width, Height, IsColor und andere, wenn vorhanden. Height und Width werden genauso wie getimagesize() berechnet. Diese Werte dürfen also nicht Teil von irgendwelchen Headern sein, die zurückgegeben werden. Ferner ist `html` ein Höhen/Breiten-Textstring für den Gebrauch in normalem HTML.
  ANY_TAG | Jegliche Informationen, die ein Tag besitzen, z. B. `IFD0`, `EXIF`, ...
  IFD0 | Alle IFD0-Daten mit Tag. In normalen Bilddateien beinhalten diese die Bildgröße usw.
  THUMBNAIL | Wenn eine Datei ein zweites `IFD` enthält, wird angenommen, dass sie ein Miniaturbild enthält. Alle Informationen mit Tags über das eingebettete Miniaturbild werden in diesem Bereich gespeichert.
  COMMENT | Kommentarheader des JPEG-Bildes.
  EXIF | Der EXIF-Bereich ist ein Unterbereich von `IFD0`. Er enthält detailliertere Information über das Bild. Die meisten dieser Einträge beziehen sich auf die Digitalkamera.

`as_arrays`
  Definiert ob jeder Bereich ein Array wird oder nicht. Die `required_sections` `COMPUTED`, `THUMBNAIL` und `COMMENT` werden immer zu Arrays, da die Namen der Werte mit denen anderer Bereiche kollidieren können.
`read_thumbnail`
  Bei `true` wird das Miniaturbild ausgelesen, ansonsten nur die Daten der Tags.

### Rückgabewerte

Gibt ein assoziatives Array zurück, bei dem der Arrayindex den Headernamen entspricht und der Arraywert die Werte enthält, die mit diesen Headern in Verbindung stehen. Wenn keine Daten zurückgegeben werden können, gibt exif_read_data() `false` zurück.

### Fehler/Exceptions

Fehler der Stufe `E_WARNING` und/oder `E_NOTICE` können bei nicht unterstützten Tags oder anderen potentiellen Fehlerbedingungen ausgelöst werden, aber die Funktion versucht trotzdem, alle verständlichen Informationen zu lesen.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `required_sections` ist jetzt nullable (akzeptiert den `null`-Wert).
7.2.0 | Der Parameter `file` unterstützt jetzt sowohl lokale Dateien als auch Stream-Ressourcen.
7.2.0 | Unterstützung für folgende EXIF-Formate wurde hinzugefügt: Samsung DJI Panasonic Sony Pentax Minolta Sigma/Foveon AGFA Kyocera Ricoh Epson

### Beispiele

Beispiel #1 exif_read_data()-Beispiel

    <?php
    echo "test1.jpg:<br />\n";
    $exif = exif_read_data('tests/test1.jpg', 'IFD0');
    echo $exif===false ? "Keine Headerdaten gefunden.<br />\n" : "Bild beinhaltet Header<br />\n";

    $exif = exif_read_data('tests/test2.jpg', 0, true);
    echo "test2.jpg:<br />\n";
    foreach ($exif as $key => $section) {
        foreach ($section as $name => $val) {
            echo "$key.$name: $val<br />\n";
        }
    }
    ?>

Der erste Aufruf schlägt fehl, da das Bild keine Headerinformationen enthält.

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    test1.jpg:
    Keine Headerdaten gefunden.
    test2.jpg:
    FILE.FileName: test2.jpg
    FILE.FileDateTime: 1017666176
    FILE.FileSize: 1240
    FILE.FileType: 2
    FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT
    COMPUTED.html: width="1" height="1"
    COMPUTED.Height: 1
    COMPUTED.Width: 1
    COMPUTED.IsColor: 1
    COMPUTED.ByteOrderMotorola: 1
    COMPUTED.UserComment: Exif test image.
    COMPUTED.UserCommentEncoding: ASCII
    COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger.
    COMPUTED.Copyright.Photographer: Photo (c) M.Boerger
    COMPUTED.Copyright.Editor: Edited by M.Boerger.
    IFD0.Copyright: Photo (c) M.Boerger
    IFD0.UserComment: ASCII
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.JPEGInterchangeFormatLength: 523
    COMMENT.0: Comment #1.
    COMMENT.1: Comment #2.
    COMMENT.2: Comment #3end
    THUMBNAIL.JPEGInterchangeFormat: 134
    THUMBNAIL.Thumbnail.Height: 1
    THUMBNAIL.Thumbnail.Height: 1

Beispiel #2 exif_read_data() mit Streams; verfügbar von PHP 7.2.0 an

    <?php
    // Öffne die Datei im Binärmodus
    $fp = fopen('/path/to/image.jpg', 'rb');

    if (!$fp) {
        echo 'Fehler: Konnte das Bild nicht fürs Lesen öffnen';
        exit;
    }

    // Versuche die Exif-Header zu lesen
    $headers = exif_read_data($fp);

    if (!$headers) {
        echo 'Fehler: Konnte die Exif-Header nicht lesen';
        exit;
    }

    // Gib die 'COMPUTED'-Header aus
    echo 'EXIF Header:' . PHP_EOL;

    foreach ($headers['COMPUTED'] as $header => $value) {
        printf(' %s => %s%s', $header, $value, PHP_EOL);
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    EXIF Header:
     Height => 576
     Width => 1024
     IsColor => 1
     ByteOrderMotorola => 0
     ApertureFNumber => f/5.6
     UserComment =>
     UserCommentEncoding => UNDEFINED
     Copyright => Denis
     Thumbnail.FileType => 2
     Thumbnail.MimeType => image/jpeg

### Anmerkungen

> Hinweis: Ist mbstring aktiviert, wird exif versuchen den Unicode zu verarbeiten, und einen Zeichensatz gemäß exif.decode_unicode_motorola und exif.decode_unicode_intel zu wählen. Die exif-Erweiterung versucht nicht, die Kodierung selbst zu ermitteln, so dass es die Aufgabe des Benutzers ist, die gewünschte Kodierung durch Setzen einer der beiden ini-Direktiven anzugeben, bevor exif_read_data() aufgerufen wird.

> Hinweis: Wird der Parameter `file` verwendet, um einen Stream an diese Funktion zu übergeben, dann muss der Stream suchbar sein. Es ist zu beachten, dass die Position des Dateizeigers nach dem Aufruf dieser Funktion unverändert ist.

### Siehe auch

- exif_thumbnail() - Liest das eingebettete Miniaturbild eines Bildes aus
- getimagesize() - Liefert die Größe einer Grafik
- Unterstützte Protokolle und Wrapper

# exif_tagname

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_tagname — Gibt den Header-Namen für einen Index zurück

### Beschreibung

function exif_tagname(int `$index`): string|false

### Parameter-Liste

`index`
  Die Tag-ID für welche ein Tag-Name nachgeschlagen wird.

### Rückgabewerte

Gibt den Header-Namen oder `false` zurück, wenn der `index` keine definierte EXIF-Tag-ID ist.

### Beispiele

Beispiel #1 exif_tagname() Beispiel

    <?php
    echo "256: ".exif_tagname(256).PHP_EOL;
    echo "257: ".exif_tagname(257).PHP_EOL;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    256: ImageWidth
    257: ImageLength

### Siehe auch

- exif_imagetype() - Ermittelt den Bildtyp
- » EXIF Spezifikation
- » EXIF Tags

# exif_thumbnail

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_thumbnail — Liest das eingebettete Miniaturbild eines Bildes aus

### Beschreibung

function exif_thumbnail(
resource|string `$file`,
int `&$width` = `null`,
int `&$height` = `null`,
int `&$image_type` = `null`
): string|false

exif_thumbnail() liest das eingebettete Miniaturbild eines Bildes aus.

Wenn man das Miniaturbild mit dieser Funktion ausliefern möchte, sollte man den Mimetype mit Hilfe der Funktion header() mitschicken.

Es kann passieren, dass exif_thumbnail() das Bild nicht erzeugen, aber dessen Größe bestimmen kann. In diesem Fall, ist der Rückgabewert `false`, obwohl `width` und `height` gesetzt sind.

### Parameter-Liste

`file`
  Der Ort der Bilddatei. Dies kann entweder ein Dateipfad oder eine Stream-Ressource sein.
`width`
  Die Breite des gelieferten Miniaturbildes als Rückgabewert.
`height`
  Die Höhe des gelieferten Miniaturbildes als Rückgabewert.
`image_type`
  Der Bildtyp des gelieferten Miniaturbildes als Rückgabewert. Dieser ist entweder TIFF oder JPEG.

### Rückgabewerte

Gibt das eingebettete Miniaturbild zurück oder `false`, wenn das Bild kein Miniaturbild enthält.

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | Der Parameter `file` unterstützt jetzt sowohl lokale Dateien als auch Stream-Ressourcen.

### Beispiele

Beispiel #1 exif_thumbnail()-Beispiel

    <?php
    $image = exif_thumbnail('/Pfad/zum/Bild.jpg', $width, $height, $type);
    if ($image!==false) {
        header('Content-type: ' .image_type_to_mime_type($type));
        echo $image;
        exit;
    } else {
        // kein Miniaturbild vorhanden. Fehler wird hier verarbeitet
        echo 'Kein Miniaturbild verfügbar';
    }
    ?>

### Anmerkungen

> Hinweis: Wird `file` verwendet, um einen Stream an diese Funktion zu übergeben, dann muss der Stream durchsuchbar sein. Es ist zu beachten, dass sich die Position des Dateizeigers nicht ändert, nachdem diese Funktion aufgerufen wurde.

### Siehe auch

- exif_read_data() - Liest die EXIF-Header einer Bilddatei aus
- image_type_to_mime_type() - Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype

# read_exif_data

(PHP 4 >= 4.0.1, PHP 5, PHP 7)

read_exif_data — Alias von exif_read_data()

Warnung

Dieser Alias ist seit PHP 7.2.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT.

### Beschreibung

Diese Funktion ist ein Alias für: exif_read_data().

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | Dieser Funktionsalias wurde missbilligt.

## Inhaltsverzeichnis

- exif_imagetype — Ermittelt den Bildtyp
- exif_read_data — Liest die EXIF-Header einer Bilddatei aus
- exif_tagname — Gibt den Header-Namen für einen Index zurück
- exif_thumbnail — Liest das eingebettete Miniaturbild eines Bildes aus
- read_exif_data — Alias von exif_read_data

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Exif-Funktionen
  - exif_imagetype — Ermittelt den Bildtyp
  - exif_read_data — Liest die EXIF-Header einer Bilddatei aus
  - exif_tagname — Gibt den Header-Namen für einen Index zurück
  - exif_thumbnail — Liest das eingebettete Miniaturbild eines Bildes aus
  - read_exif_data — Alias von exif_read_data

# Bildbearbeitung und GD

# Einführung

Mit PHP können Sie nicht nur HTML ausgeben, sondern auch Grafiken in vielen Formaten wie GIF, PNG, JPEG, WBMP und XPM erzeugen und/oder manipulieren. Noch besser, Sie können Grafiken mit PHP direkt als Datenstrom ausgeben. Damit das funktioniert, müssen Sie PHP mit der GD-Bibliothek zur Grafikbearbeitung kompilieren. GD und PHP benötigen, je nachdem mit welchen Grafikformaten Sie arbeiten wollen, zusätzliche Bibliotheken.

Sie können die Grafikfunktionen in PHP auch verwenden, um die Größe von JPEG-, GIF-, PNG-, SWF-, TIFF- und JPEG2000-Grafiken zu bestimmen.

Mittels der exif-Erweiterung können Sie die in den Headern von JPEG- und TIFF-Grafiken enthaltenen Informationen verarbeiten. Auf diese Weise können von Digitalkameras erstellte Metadaten verarbeitet werden. Die Exif-Funktionen benötigen die GD-Bibliothek nicht.

> Hinweis: Im Abschnitt über die Anforderungen können Sie nachlesen, wie Sie die Möglichkeiten der Bildbearbeitung zum Lesen, Schreiben und Manipulieren von Bildern erweitern können. Um Metadaten von Bildern auszulesen, die mit einer Digitalkamera aufgenommen wurden, wird die bereits erwähnte exif-Erweiterung benötigt.

> Hinweis: Für die Funktion getimagesize() wird die GD-Bibliothek nicht benötigt.

Achtung

Während die gebündelte Version der GD-Bibliothek den Zend-Speichermanager zur Allokation von Speicher verwendet, tun dies die Systemversionen nicht, sodass memory_limit ignoriert wird.

GD unterstützt viele Formate. Nachfolgend eine Liste aller von GD unterstützten Formaten und Hinweise zu Verfügbarkeit und Lese-/Schreibunterstützung.

Von GD unterstützte Formate
Format | Lesen | Schreiben | Anmerkungen
--- | --- | --- | ---
JPEG | `true` | `true` |
PNG | `true` | `true` |
GIF | `true` | `true` |
XBM | `true` | `true` |
XPM | `true` | `false` |
WBMP | `true` | `true` |
WebP | `true` | `true` |
BMP | `true` | `true` | Verfügbar seit PHP 7.2.0

Obwohl die meisten Formate in der obigen Tabelle sowohl zum Lesen als auch zum Schreiben verfügbar sind, bedeutet dies nicht, dass die Unterstützung in PHP einkompiliert ist. Welche Formate dies sind und wie PHP mit Unterstützung für diese kompiliert werden kann, zeigt die Funktion gd_info(). Weitere Informationen zu diesem Thema sind im Kapitel Installation zu finden.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

Mit der GD-Bibliothek (verfügbar unter » http://www.libgd.org/) können Sie auch Grafiken erzeugen und manipulieren.

Die mittels dieser Funktionen veränderbaren Grafik-Formate hängen davon ab, welche Version von GD Sie installieren und welche zusätzlichen Bibliotheken GD benötigt, um mit diesen Formaten umgehen zu können.

> Hinweis: libgd-2.1.0 oder höher wird benötigt. Alternativ kann die gebündelte GD-Bibliothek verwendet werden, die mit PHP ausgeliefert wird.

> Hinweis: Die GD-Bibliothek benötigt zlib >= 1.2.0.4.

Sie können GD erweitern, um mehr Grafikformate zu verwenden.

Unterstützte Grafikformate
Grafikformat | Download der benötigten Bibliothek | Anmerkungen
--- | --- | ---
`gif` |  |
`avif` |  |
`jpeg` | » http://www.ijg.org/ | Wenn Sie die jpeg-Bibliothek übersetzen (vor dem Übersetzen von PHP), müssen Sie die Option --enable-shared im configure-Schritt verwenden. Wenn Sie dies nicht tun, werden Sie beim configure-Schritt der PHP-Übersetzung den Fehler `libjpeg.(a|so) not found` erhalten.
`png` | » http://www.libpng.org/pub/png/libpng.html |
`xpm` | » http://www.ibiblio.org/pub/Linux/libs/X/!INDEX.html | Wenn Ihr System über eine installierte X-Umgebung verfügt, ist diese Bibliothek wahrscheinlich bereits vorhanden.
`webp` |  |

Sie können GD erweitern, um unterschiedliche Schriften zu verwenden. Die » Freetype 2-Bibliothek wird unterstützt.

## Installation

To enable GD-support configure PHP --with-gd[=DIR], where DIR is the GD base install directory. To use the recommended bundled version of the GD library, use the configure option --with-gd. GD library requires libpng and libjpeg to compile. As of PHP 7.4.0, --with-gd becomes --enable-gd (whether to enable the extension at all) and --with-external-gd (to opt into using an external libgd, rather than the bundled one).

In Windows, you'll include the GD DLL php_gd.dll as an extension in php.ini. Prior to PHP 8.0.0, the DLL was named php_gd2.dll.

Enhance the capabilities of GD to handle more image formats by specifying the `--with-XXXX` configure switch to your PHP configure line.

Supported image formats
Image Format | Configure Switch
--- | ---
`avif` | To enable support for avif add --with-avif. Available as of PHP 8.1.0.
`jpeg` | To enable support for jpeg add --with-jpeg-dir=DIR. Jpeg 6b, 7 or 8 are supported. As of PHP 7.4.0, use --with-jpeg instead.
`png` | To enable support for png add --with-png-dir=DIR. Note, libpng requires the zlib library, therefore add --with-zlib-dir[=DIR] to your configure line. As of PHP 7.4.0, --with-png-dir and --with-zlib-dir have been removed. libpng and zlib are required.
`xpm` | To enable support for xpm add --with-xpm-dir=DIR. If configure is not able to find the required libraries, you may add the path to your X11 libraries. As of PHP 7.4.0, use --with-xpm instead.
`webp` | To enable support for webp add --with-webp-dir=DIR. As of PHP 7.4.0, use --with-webp instead.

> Hinweis: When compiling PHP with libpng, you must use the same version that was linked with the GD library.

Enhance the capabilities of GD to deal with different fonts by specifying the `--with-XXXX` configure switch to your PHP configure line.

Supported font libraries
Font library | Configure Switch
--- | ---
`FreeType 2` | To enable support for FreeType 2 add --with-freetype-dir=DIR. As of PHP 7.4.0 use --with-freetype instead, which relies on pkg-config.
`Native TrueType string function` | To enable support for native TrueType string function add --enable-gd-native-ttf. (This option has no effect and has been removed as of PHP 7.2.0.)

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Image-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
gd.jpeg_ignore_warning | "1" | `INI_ALL` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`gd.jpeg_ignore_warning` bool

  Ignoriert Warnungen (aber keine Fehler), die von libjpeg(-turbo) gemeldet werden.

Changelog für `gd.jpeg_ignore_warning`
Version | Beschreibung
--- | ---
7.1.0 | Der Standard-Wert von gd.jpeg_ignore_warning wurde von 0 zu 1 geändert.

Siehe auch die exif-Konfigurationsanweisungen.

Warnung

Die Image-Funktionen sind sehr ressourcenintensiv. Stellen Sie sicher, dass Sie memory_limit hoch genug setzen, falls Sie die gebündelte Version der GD-Bibliothek verwenden.

## Ressource-Typen

Diese Erweiterung definiert die folgenden Ressourcen-Typen:

Liste von Ressourcen-Typen in GD
Name | Beschreibung | Bemerkungen
--- | --- | ---
`gd` | Bild-Ressource, verwendet von Funktionen wie imagecreatefrompng() | Vor PHP 8.0.0
`gd font` | Schriftarten-Ressource, die intern von imageloadfont() erzeugt wird | Vor PHP 8.1.0

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`GD_VERSION` (string)
  The GD version PHP was compiled against.
`GD_MAJOR_VERSION` (int)
  The GD major version PHP was compiled against.
`GD_MINOR_VERSION` (int)
  The GD minor version PHP was compiled against.
`GD_RELEASE_VERSION` (int)
  The GD release version PHP was compiled against.
`GD_EXTRA_VERSION` (string)
  The GD "extra" version (beta/rc..) PHP was compiled against.
`GD_BUNDLED` (int)
  When the bundled version of GD is used this is 1 otherwise its set to 0.
`IMG_AVIF` (int)
  Wird als Rückgabewert von imagetypes() verwendet (Available as of PHP 8.1.0)
`IMG_BMP` (int)
  Wird als Rückgabewert von imagetypes() verwendet
`IMG_GIF` (int)
  Wird als Rückgabewert von imagetypes() verwendet
`IMG_JPG` (int)
  Wird als Rückgabewert von imagetypes() verwendet
`IMG_JPEG` (int)
  Wird als Rückgabewert von imagetypes() verwendet

  > Hinweis:

  > This constant has the same value as `IMG_JPG`

`IMG_PNG` (int)
  Wird als Rückgabewert von imagetypes() verwendet
`IMG_TGA` (int)
  Wird als Rückgabewert von imagetypes() verwendet (Available as of PHP 7.4.0)
`IMG_WBMP` (int)
  Wird als Rückgabewert von imagetypes() verwendet
`IMG_XPM` (int)
  Wird als Rückgabewert von imagetypes() verwendet
`IMG_WEBP` (int)
  Wird als Rückgabewert von imagetypes() verwendet (Available as of PHP 7.0.10)
`IMG_WEBP_LOSSLESS` (int)
  (Available as of PHP 8.1.0)
`IMG_COLOR_TILED` (int)
  Eine spezielle Farboption, die anstelle einer Farbe verwendet werden kann, die mit imagecolorallocate() oder imagecolorallocatealpha() zugewiesen wird.
`IMG_COLOR_STYLED` (int)
  Eine spezielle Farboption, die anstelle einer Farbe verwendet werden kann, die mit imagecolorallocate() oder imagecolorallocatealpha() zugewiesen wird.
`IMG_COLOR_BRUSHED` (int)
  Eine spezielle Farboption, die anstelle einer Farbe verwendet werden kann, die mit imagecolorallocate() oder imagecolorallocatealpha() zugewiesen wird.
`IMG_COLOR_STYLEDBRUSHED` (int)
  Eine spezielle Farboption, die anstelle einer Farbe verwendet werden kann, die mit imagecolorallocate() oder imagecolorallocatealpha() zugewiesen wird.
`IMG_COLOR_TRANSPARENT` (int)
  Eine spezielle Farboption, die anstelle einer Farbe verwendet werden kann, die mit imagecolorallocate() oder imagecolorallocatealpha() zugewiesen wird.
`IMG_AFFINE_TRANSLATE` (int)
  Eine Konstante vom Typ affine Transformation, die von der Funktion imageaffinematrixget() verwendet wird.
`IMG_AFFINE_SCALE` (int)
  Eine Konstante vom Typ affine Transformation, die von der Funktion imageaffinematrixget() verwendet wird.
`IMG_AFFINE_ROTATE` (int)
  Eine Konstante vom Typ affine Transformation, die von der Funktion imageaffinematrixget() verwendet wird.
`IMG_AFFINE_SHEAR_HORIZONTAL` (int)
  Eine Konstante vom Typ affine Transformation, die von der Funktion imageaffinematrixget() verwendet wird.
`IMG_AFFINE_SHEAR_VERTICAL` (int)
  Eine Konstante vom Typ affine Transformation, die von der Funktion imageaffinematrixget() verwendet wird.
`IMG_ARC_ROUNDED` (int)
  Eine Stilkonstante, die von der Funktion imagefilledarc() verwendet wird.

  > Hinweis:

  > This constant has the same value as `IMG_ARC_PIE`

`IMG_ARC_PIE` (int)
  Eine Stilkonstante, die von der Funktion imagefilledarc() verwendet wird.
`IMG_ARC_CHORD` (int)
  Eine Stilkonstante, die von der Funktion imagefilledarc() verwendet wird.
`IMG_ARC_NOFILL` (int)
  Eine Stilkonstante, die von der Funktion imagefilledarc() verwendet wird.
`IMG_ARC_EDGED` (int)
  Eine Stilkonstante, die von der Funktion imagefilledarc() verwendet wird.
`IMG_GD2_RAW` (int)
  Eine Typkonstante, die von der Funktion imagegd2() verwendet wird.
`IMG_GD2_COMPRESSED` (int)
  Eine Typkonstante, die von der Funktion imagegd2() verwendet wird.
`IMG_EFFECT_REPLACE` (int)
  Ein Alpha-Blending-Effekt, der von der Funktion imagelayereffect() verwendet wird.
`IMG_EFFECT_ALPHABLEND` (int)
  Ein Alpha-Blending-Effekt, der von der Funktion imagelayereffect() verwendet wird.
`IMG_EFFECT_NORMAL` (int)
  Ein Alpha-Blending-Effekt, der von der Funktion imagelayereffect() verwendet wird.
`IMG_EFFECT_OVERLAY` (int)
  Ein Alpha-Blending-Effekt, der von der Funktion imagelayereffect() verwendet wird.
`IMG_EFFECT_MULTIPLY` (int)
  Ein Alpha-Blending-Effekt, der von der Funktion imagelayereffect() verwendet wird.
`IMG_FILTER_NEGATE` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_GRAYSCALE` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_BRIGHTNESS` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_CONTRAST` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_COLORIZE` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_EDGEDETECT` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_GAUSSIAN_BLUR` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_SELECTIVE_BLUR` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_EMBOSS` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_MEAN_REMOVAL` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_SMOOTH` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_PIXELATE` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird.
`IMG_FILTER_SCATTER` (int)
  Ein spezieller GD-Filter, der von der Funktion imagefilter() verwendet wird. (Available as of PHP 7.4.0)
`IMAGETYPE_GIF` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_JPEG` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_JPEG2000` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_PNG` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_SWF` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_PSD` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_BMP` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_WBMP` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_XBM` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_TIFF_II` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_TIFF_MM` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_IFF` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_JB2` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_JPC` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_JP2` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_JPX` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_SWC` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_ICO` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_WEBP` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird. (Available as of PHP 7.1.0)
`IMAGETYPE_AVIF` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird. (Available as of PHP 8.1.0)
`IMAGETYPE_HEIF` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird. (Available as of PHP 8.5.0)
`IMAGETYPE_UNKNOWN` (int)
  Eine Bildtyp-Konstante, die von den Funktionen image_type_to_mime_type() und image_type_to_extension() verwendet wird.
`IMAGETYPE_COUNT` (int)
  The number of image type constants (including the "unknown" type) supported by the image_type_to_mime_type() and image_type_to_extension() functions
`PNG_NO_FILTER` (int)
  Ein spezieller PNG-Filter, der von der Funktion imagepng() verwendet wird.
`PNG_FILTER_NONE` (int)
  Ein spezieller PNG-Filter, der von der Funktion imagepng() verwendet wird.
`PNG_FILTER_SUB` (int)
  Ein spezieller PNG-Filter, der von der Funktion imagepng() verwendet wird.
`PNG_FILTER_UP` (int)
  Ein spezieller PNG-Filter, der von der Funktion imagepng() verwendet wird.
`PNG_FILTER_AVG` (int)
  Ein spezieller PNG-Filter, der von der Funktion imagepng() verwendet wird.
`PNG_FILTER_PAETH` (int)
  Ein spezieller PNG-Filter, der von der Funktion imagepng() verwendet wird.
`PNG_ALL_FILTERS` (int)
  Ein spezieller PNG-Filter, der von der Funktion imagepng() verwendet wird.
`IMG_FLIP_VERTICAL` (int)
  Wird zusammen mit imageflip() verwendet.
`IMG_FLIP_HORIZONTAL` (int)
  Wird zusammen mit imageflip() verwendet.
`IMG_FLIP_BOTH` (int)
  Wird zusammen mit imageflip() verwendet.
`IMG_BELL` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_BESSEL` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_BILINEAR_FIXED` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_BICUBIC` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_BICUBIC_FIXED` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_BLACKMAN` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_BOX` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_BSPLINE` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_CATMULLROM` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_GAUSSIAN` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_GENERALIZED_CUBIC` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_HERMITE` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_HAMMING` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_HANNING` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_MITCHELL` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_POWER` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_QUADRATIC` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_SINC` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_NEAREST_NEIGHBOUR` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_WEIGHTED4` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_TRIANGLE` (int)
  Wird zusammen mit imagesetinterpolation() verwendet.
`IMG_CROP_BLACK` (int)
  Crops out a black background.
`IMG_CROP_DEFAULT` (int)
  Same as `IMG_CROP_TRANSPARENT`. Before PHP 7.4.0, the bundled libgd fell back to `IMG_CROP_SIDES`, if the image had no transparent color.
`IMG_CROP_SIDES` (int)
  Uses the 4 corners of the image to attempt to detect the background to crop.
`IMG_CROP_THRESHOLD` (int)
  Crops an image using the given `threshold` and `color`.
`IMG_CROP_TRANSPARENT` (int)
  Crops out a transparent background.
`IMG_CROP_WHITE` (int)
  Crops out a white background.

# Beispiele

## Inhaltsverzeichnis

- PNG erzeugen mit PHP
- Wasserzeichen mit Hilfe von Alpha-Kanälen zufügen
- Erstellen eines transparenten Wasserzeichens mit imagecopymerge

## PNG erzeugen mit PHP

Beispiel #1 PNG erzeugen mit PHP

    <?php

    header("Content-type: image/png");
    $string = $_GET['text'];
    $im     = imagecreatefrompng("images/button1.png");
    $orange = imagecolorallocate($im, 220, 210, 60);
    $px     = (imagesx($im) - 7.5 * strlen($string)) / 2;
    imagestring($im, 3, $px, 9, $string, $orange);
    imagepng($im);

    ?>

Dieses Beispiel würde von einer Seite über einen Link wie `<img src="button.php?text=text">` aufgerufen. Das oben aufgezeigte Beispielskript button.php nimmt den Text `"text"` entgegen und legt diesen über ein vorhandenes Bild, in diesem Fall `"images/button1.png"` und gibt die resultierende Grafik aus. Diese Vorgehensweise ist sehr zweckmäßig, wenn Sie vermeiden wollen, dass Sie immer wieder neue Button-Grafiken erstellen müssen, falls Sie die Beschriftung eines Buttons ändern wollen. Mit der vorgestellten Methode werden Ihre Buttons, samt Beschriftung, dynamisch generiert.

## Wasserzeichen mit Hilfe von Alpha-Kanälen zufügen

Beispiel #1 Wasserzeichen mit Hilfe von Alpha-Kanälen zufügen

    <?php
    // Wasserzeichen und Foto laden
    $stamp = imagecreatefrompng('stamp.png');
    $im = imagecreatefromjpeg('photo.jpeg');

    // Ränder für Wasserzeichen festlegen, dessen Höhe und Breite bestimmen
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Wasserzeichen auf das Foto kopieren, die Position berechnet sich dabei aus
    // den Rändern und der Bildbreite
    imagecopy($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp));

    // Ausgeben
    header('Content-type: image/png');
    imagepng($im);
    ?>

Dieses Beispiel zeigt eine übliche Vorgehensweise um ein Wasserzeichen auf Fotos oder urheberrechtlich geschützten Bildern anzubringen. Beachten Sie, daß die Wasserzeichen-Grafik einen Alphakanal enthält. Dieser wird beim Kopiervorgang beibehalten.

## Erstellen eines transparenten Wasserzeichens mit imagecopymerge()

Beispiel #1 Erstellen eines transparenten Wasserzeichens mit imagecopymerge()

    <?php
    // Foto laden
    $im = imagecreatefromjpeg('photo.jpeg');

    // wir erstellen ein Wasserzeichen mit GD
    $stamp = imagecreatetruecolor(100, 70);
    imagefilledrectangle($stamp, 0, 0, 99, 69, 0x0000FF);
    imagefilledrectangle($stamp, 9, 9, 90, 60, 0xFFFFFF);
    imagestring($stamp, 5, 20, 20, 'libGD', 0x0000FF);
    imagestring($stamp, 3, 20, 40, '(c) 2007-9', 0x0000FF);

    // Ränder setzen, Dimensionen ermitteln
    $marge_right = 10;
    $marge_bottom = 10;
    $sx = imagesx($stamp);
    $sy = imagesy($stamp);

    // Wasserzeichen mit einer Transparenz von 50% über das Foto legen
    imagecopymerge($im, $stamp, imagesx($im) - $sx - $marge_right, imagesy($im) - $sy - $marge_bottom, 0, 0, imagesx($stamp), imagesy($stamp), 50);

    // Bild in einer Datei speichern
    imagepng($im, 'photo_stamp.png');

    ?>

Dieses Beispiel nutzt imagecopymerge() um das Wasserzeichen über das Original-Bild zu legen. Dabei können wir die Transparenz des Wasserzeichens frei bestimmen - im Beispiel werden 50% gesetzt. In der Praxis wäre dies ein sinnvolles Vorgehen zum Urheberschutz, da halbtransparente Wasserzeichen schwierig zu entfernen sind, dem Betrachter aber trotzdem erlauben das Bild zu sehen.

# GD- und Image-Funktionen

# gd_info

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

gd_info — Liefert Informationen über die aktuell verwendete GD-Bibliothek

### Beschreibung

function gd_info(): array

Ermittelt Informationen über die Version und die Funktionen der installierten GD-Bibliothek.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein assoziatives Array zurück.

Elemente des von gd_info() zurückgegebenen Arrays
Attribut | Bedeutung
--- | ---
GD Version | string-Wert, der die installierte `libgd`-Version beschreibt.
FreeType Support | bool-Wert. `true`, wenn FreeType-Unterstützung installiert ist.
FreeType Linkage | string-Wert, der beschreibt, wie FreeType verknüpft wurde. Erwartete Inhalte: 'with freetype', 'with TTF library', und 'with unknown library'. Dieses Element wird nur definiert, wenn `FreeType-Support` als `true` beurteilt wurde.
GIF Read Support | bool-Wert. `true`, wenn Leseunterstützung für `GIF`-Bilder eingebunden ist.
GIF Create Support | bool-Wert. `true`, wenn Unterstützung für das Erstellen von `GIF`-Bildern eingebunden ist.
JPEG Support | bool-Wert. `true`, wenn `JPEG`-Unterstützung eingebunden ist.
PNG Support | bool-Wert. `true`, wenn `PNG`-Unterstützung eingebunden ist.
WBMP Support | bool-Wert. `true`, wenn `WBMP`-Unterstützung eingebunden ist.
XBM Support | bool-Wert. `true`, wenn `XBM`-Unterstützung eingebunden ist.
WebP Support | bool-Wert. `true`, wenn `WebP`-Unterstützung eingebunden ist.
AVIF Support | bool value. `true`, wenn `AVIF`-Unterstützung eingebunden ist. Verfügbar seit PHP 8.1.0.

### Beispiele

Beispiel #1 Verwendung von gd_info()

    <?php
    var_dump(gd_info());
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(10) {
      ["GD Version"]=>
      string(24) "bundled (2.1.0 compatible)"
      ["FreeType Support"]=>
      bool(false)
      ["GIF Read Support"]=>
      bool(true)
      ["GIF Create Support"]=>
      bool(false)
      ["JPEG Support"]=>
      bool(false)
      ["PNG Support"]=>
      bool(true)
      ["WBMP Support"]=>
      bool(true)
      ["XBM Support"]=>
      bool(false)
      ["WebP Support"]=>
      bool(false)
      ["AVIF Support"]=>
      bool(false)
    }

### Siehe auch

- imagepng() - Ausgabe eines Bildes im Browser oder als Datei im PNG-Format
- imagejpeg() - Gibt das Bild im Browser oder einer Datei aus.
- imagegif() - Gibt das Bild im Browser oder einer Datei aus.
- imagewbmp() - Gibt das Bild im Browser oder einer Datei aus.
- imagewebp() - Output a WebP image to browser or file
- imageavif() - Gibt das Bild im Browser oder einer Datei aus.
- imagetypes() - Liefert die von der verwendeten PHP-Version unterstützten Grafikformate

# getimagesize

(PHP 4, PHP 5, PHP 7, PHP 8)

getimagesize — Liefert die Größe einer Grafik

### Beschreibung

function getimagesize(string `$filename`, array `&$image_info` = `null`): array|false

Die Funktion getimagesize() ermittelt die Größe der übergebenen Grafik, sofern das Format unterstützt wird, und gibt die Abmessungen zusammen mit dem Dateityp und einer Zeichenkette aus `Breite` und `Höhe` zurück, die innerhalb eines regulären HTML-`IMG`-Tags verwendet werden kann. Außerdem wird der entsprechende HTTP-Content-Type zurückgegeben.

getimagesize() kann im Parameter `image_info` weitere Informationen liefern.

Achtung

Diese Funktion erwartet, dass `filename` eine gültige Bilddatei ist. Wird eine Datei angegeben, die kein Bild enthält, kann sie fälschlicherweise als Bild erkannt werden und die Funktion wird erfolgreich ausgeführt, aber das Array kann unsinnige Werte enthalten.

getimagesize() sollte nicht verwendet werden, um zu überprüfen, ob eine gegebene Datei ein Bild enthält. Stattdessen sollte eine für diesen Zweck entwickelte Lösung wie die Erweiterung Fileinfo verwendet werden.

> Hinweis: Beachten Sie, dass JPC und JP2 aus Komponenten mit verschiedener Farbtiefe bestehen können. In diesem Fall entspricht der Wert für "bits" dem höchsten gefundenen Wert. Des Weiteren können JP2-Dateien mehrere JPEG-2000-Codestreams enthalten. In diesem Fall gibt getimagesize() die Werte des ersten gefundenen Codestreams zurück.

> Hinweis: Informationen über Icons werden für das Icon mit der höchsten Bitrate ermittelt.

> Hinweis: GIF-Bilder bestehen aus einem oder mehreren Frames, wobei jeder Frame nur einen Teil des Bildes belegen kann. Die Größe des Bildes, die von getimagesize() gemeldet wird, ist die Gesamtgröße (ermittelt aus dem Logical Screen Descriptor).

### Parameter-Liste

`filename`

  Die zu überprüfende Datei. Dabei kann es sich um eine lokale Datei oder, eine entsprechende Konfiguration vorausgesetzt, um eine entfernte Datei handeln, die über einen der unterstützten Streams gelesen wird.

`image_info`

  Dieser optionale Parameter erlaubt es, erweiterte Informationen aus der Datei zu ermitteln. Aktuell werden die verschiedenen JPG-APP-Markierungen als assoziatives Array zurückgegeben. Diese Markierungen werden von einigen Programmen verwendet um, Textinformationen in Grafiken zu speichern. Gebräuchlich ist die Einbettung von » IPTC-Informationen in die APP13-Markierung. Sie können iptcparse() verwenden, um die binäre APP13-Markierung in ein lesbares Format zu übertragen.

  > Hinweis:

  > Der Parameter `image_info` unterstützt nur JFIF-Dateien.

### Rückgabewerte

Gibt ein Array mit bis zu sieben Elementen zurück. Nicht alle Bildtypen enthalten die Elemente `channels` und `bits`.

Index 0 und 1 enthalten die Breite bzw. die Höhe des Bildes.

> Hinweis:

> Einige Formate enthalten keine oder mehrere Grafiken. In diesen Fällen ist getimagesize() möglicherweise nicht in der Lage, die Abmessungen zu ermitteln; der Rückgabewert für Breite und Höhe ist in diesen Fällen 0.

> Hinweis: Die Funktion getimagesize() berücksichtigt die Metadaten des Bildes nicht. Wenn z. B. das Exif-Flag `Orientation` auf einen Wert gesetzt ist, der das Bild um 90 oder 270 Grad dreht, werden die Indizes 0 und 1 vertauscht, d. h. sie enthalten die Höhe bzw. Breite.

Index 2 ist eine der `IMAGETYPE_*`-Konstanten, die den Typ der Grafik angeben.

Index 3 ist eine Zeichenkette mit dem Attributen Breite und Höhe in der Form `height="yyy" width="xxx"` zur Verwendung in einem IMG-Tag.

`mime` entspricht dem MIME-Typ der Grafik. Diese Information kann zur Auslieferung von Grafiken mit dem entsprechenden HTTP-`Content-type`-Header dienen.

Beispiel #1 getimagesize() und MIME-Typ

    <?php
    $size = getimagesize($filename);
    $fp = fopen($filename, "rb");
    if ($size && $fp) {
        header("Content-type: {$size['mime']}");
        fpassthru($fp);
        exit;
    } else {
        // Fehler
    }
    ?>

`channels` hat für RGB-Grafiken den Wert 3, für CMYK den Wert 4.

`bits` entspricht der Anzahl der Bits pro Farbe.

Für einige Bildformate kann die Angebe von `channels` und `bits` irreführend sein. Beispielsweise nutzt GIF immer drei Kanäle pro Pixel, aber die Anzahl der Bits pro Pixel kann für ein animiertes GIF mit einer globalen Farbtabelle nicht errechnet werden.

Gibt im Falle eines Fehlers `false` zurück.

### Fehler/Exceptions

Wenn ein Zugriff auf die mit `filename` angegebene Grafik nicht möglich ist, wird getimagesize() einen Fehler der Stufe `E_WARNING` generieren. Bei einem Lesefehler wird getimagesize() einen Fehler der Stufe `E_NOTICE` hervorrufen.

Ab PHP 8.0.0 wird eine ValueError-Ausnahme ausgelöst, wenn `filename` leer ist.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Eine ValueError-Ausnahme wird nun ausgelöst, wenn `filename` leer ist; vorher wurde ein`E_WARNING` ausgegeben und die Funktion gab `false` zurück.
8.2.0 | Gibt nun die tatsächlichen Abmessungen, Bits und Kanäle von AVIF-Bildern zurück; zuvor wurden die Abmessungen als `0x0` zurückgegeben, und Bits und Kanäle wurden überhaupt nicht zurückgegeben.
7.1.0 | Unterstützung für WebP hinzugefügt.

### Beispiele

Beispiel #2 getimagesize()-Beispiel

    <?php
    list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
    echo "<img src=\"img/flag.jpg\" $attr alt=\"getimagesize() example\" />";
    ?>

Beispiel #3 getimagesize (URL)

    <?php
    $size = getimagesize("http://www.example.com/gifs/logo.gif");

    // Wenn der Dateiname ein Leerzeichen enthält, muss es korrekt kodiert werden.
    $size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

    ?>

Beispiel #4 getimagesize() mit Rückgabe von IPTC

    <?php
    $size = getimagesize("testimg.jpg", $info);
    if (isset($info["APP13"])) {
        $iptc = iptcparse($info["APP13"]);
        var_dump($iptc);
    }
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion benötigt die GD-Bibliothek nicht.

### Siehe auch

- image_type_to_mime_type() - Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- exif_imagetype() - Ermittelt den Bildtyp
- exif_read_data() - Liest die EXIF-Header einer Bilddatei aus
- exif_thumbnail() - Liest das eingebettete Miniaturbild eines Bildes aus
- imagesx() - Ermittelt die Breite eines Bildes
- imagesy() - Ermittelt die Höhe eines Bildes

# getimagesizefromstring

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

getimagesizefromstring — Liefert die Größe einer Grafik aus einer Zeichenkette

### Beschreibung

function getimagesizefromstring(string `$string`, array `&$image_info` = `null`): array|false

Identisch zu getimagesize(), außer dass getimagesizefromstring() als ersten Übergabeparameter eine Zeichenkette statt eines Dateinamens akzeptiert.

In der Dokumentation zu getimagesize() sind die Details zur Funktionsweise dieser Funktion zu finden.

### Parameter-Liste

`string`

  Die Bilddaten als Zeichenkette.

`image_info`

  Siehe getimagesize().

### Rückgabewerte

Siehe getimagesize().

### Beispiele

Beispiel #1 getimagesizefromstring()-Beispiel

    <?php
    $img = '/path/to/test.png';

    // als Datei öffnen
    $size_info1 = getimagesize($img);

    // oder als Zeichenkette öffnen
    $data       = file_get_contents($img);
    $size_info2 = getimagesizefromstring($data);
    ?>

### Siehe auch

- getimagesize() - Liefert die Größe einer Grafik

# image_type_to_extension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

image_type_to_extension — Get file extension for image type

### Beschreibung

function image_type_to_extension(int `$image_type`, bool `$include_dot` = `true`): string|false

Returns the extension for the given `IMAGETYPE_*` constant.

### Parameter-Liste

`image_type`

  One of the `IMAGETYPE_*` constant.

`include_dot`

  Whether to prepend a dot to the extension or not. Default to `true`.

### Rückgabewerte

A string with the extension corresponding to the given image type, Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 image_type_to_extension() example

    <?php
    // Create image instance
    $im = imagecreatetruecolor(100, 100);

    // Save image
    imagepng($im, './test' . image_type_to_extension(IMAGETYPE_PNG));
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion benötigt die GD-Bibliothek nicht.

# image_type_to_mime_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

image_type_to_mime_type — Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype

### Beschreibung

function image_type_to_mime_type(int `$image_type`): string

The image_type_to_mime_type() function will determine the Mime-Type for an IMAGETYPE constant.

### Parameter-Liste

`image_type`

  One of the `IMAGETYPE_*` constants.

### Rückgabewerte

The returned values are as follows

Returned values Constants
`image_type` | Returned value
--- | ---
`IMAGETYPE_GIF` | `image/gif`
`IMAGETYPE_JPEG` | `image/jpeg`
`IMAGETYPE_PNG` | `image/png`
`IMAGETYPE_SWF` | `application/x-shockwave-flash`
`IMAGETYPE_PSD` | `image/psd`
`IMAGETYPE_BMP` | `image/bmp`
`IMAGETYPE_TIFF_II` (intel byte order) | `image/tiff`
`IMAGETYPE_TIFF_MM` (motorola byte order) | `image/tiff`
`IMAGETYPE_JPC` | `application/octet-stream`
`IMAGETYPE_JP2` | `image/jp2`
`IMAGETYPE_JPX` | `application/octet-stream`
`IMAGETYPE_JB2` | `application/octet-stream`
`IMAGETYPE_SWC` | `application/x-shockwave-flash`
`IMAGETYPE_IFF` | `image/iff`
`IMAGETYPE_WBMP` | `image/vnd.wap.wbmp`
`IMAGETYPE_XBM` | `image/xbm`
`IMAGETYPE_ICO` | `image/vnd.microsoft.icon`
`IMAGETYPE_WEBP` | `image/webp`
`IMAGETYPE_AVIF` | `image/avif`
`IMAGETYPE_HEIF` | `image/heif`

### Beispiele

Beispiel #1 image_type_to_mime_type() example

    <?php
    header("Content-type: " . image_type_to_mime_type(IMAGETYPE_PNG));
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion benötigt die GD-Bibliothek nicht.

### Siehe auch

- getimagesize() - Liefert die Größe einer Grafik
- exif_imagetype() - Ermittelt den Bildtyp
- exif_read_data() - Liest die EXIF-Header einer Bilddatei aus
- exif_thumbnail() - Liest das eingebettete Miniaturbild eines Bildes aus

# image2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

image2wbmp — Gibt das Bild im Browser oder einer Datei aus.

Warnung

Diese Funktion ist seit PHP 7.3.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function image2wbmp(resource `$image`, string `$filename` = ?, int `$foreground` = ?): bool

image2wbmp() outputs or save a WBMP version of the given `image`.

### Parameter-Liste

`image`

  An image resource, returned by one of the image creation functions, such as imagecreatetruecolor().

`filename`

  Path to the saved file. If not given, the raw image stream will be output directly.

`foreground`

  You can set the foreground color with this parameter by setting an identifier obtained from imagecolorallocate(). The default foreground color is black.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Beispiele

Beispiel #1 image2wbmp() example

    <?php
    $file = 'php.png';
    $image = imagecreatefrompng($file);

    header('Content-Type: ' . image_type_to_mime_type(IMAGETYPE_WBMP));
    image2wbmp($image); // output the stream directly
    ?>

### Siehe auch

- imagewbmp() - Gibt das Bild im Browser oder einer Datei aus.

# imageaffine

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffine — Return an image containing the affine transformed src image, using an optional clipping area

### Beschreibung

function imageaffine(GdImage `$image`, array `$affine`, ?array `$clip` = `null`): GdImage|false

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`affine`

  Array with keys 0 to 5.

`clip`

  Array with keys "x", "y", "width" and "height"; or `null`.

### Rückgabewerte

Return affined image object on successBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `clip` is now nullable.
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

# imageaffinematrixconcat

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixconcat — Concatenate two affine transformation matrices

### Beschreibung

function imageaffinematrixconcat(array `$matrix1`, array `$matrix2`): array|false

Returns the concatenation of two affine transformation matrices, what is useful if multiple transformations should be applied to the same image in one go.

### Parameter-Liste

`matrix1`

  An affine transformation matrix (an array with keys `0` to `5` and float values).

`matrix2`

  An affine transformation matrix (an array with keys `0` to `5` and float values).

### Rückgabewerte

An affine transformation matrix (an array with keys `0` to `5` and float values) Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 imageaffinematrixconcat() example

    <?php
    $m1 = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    $m2 = imageaffinematrixget(IMG_AFFINE_SCALE, array('x' => 4, 'y' => 5));
    $matrix = imageaffinematrixconcat($m1, $m2);
    print_r($matrix);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => 4
        [1] => 0
        [2] => 0
        [3] => 5
        [4] => 8
        [5] => 15
    )

### Siehe auch

- imageaffine() - Return an image containing the affine transformed src image, using an optional clipping area
- imageaffinematrixget() - Get an affine transformation matrix

# imageaffinematrixget

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixget — Get an affine transformation matrix

### Beschreibung

function imageaffinematrixget(int `$type`, array|float `$options`): array|false

Returns an affine transformation matrix.

### Parameter-Liste

`type`

  One of the `IMG_AFFINE_*` constants.

`options`

  If `type` is `IMG_AFFINE_TRANSLATE` or `IMG_AFFINE_SCALE`, `options` has to be an array with keys `x` and `y`, both having float values.

  If `type` is `IMG_AFFINE_ROTATE`, `IMG_AFFINE_SHEAR_HORIZONTAL` or `IMG_AFFINE_SHEAR_VERTICAL`, `options` has to be a float specifying the angle.

### Rückgabewerte

An affine transformation matrix (an array with keys `0` to `5` and float values) Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 imageaffinematrixget() example

    <?php
    $matrix = imageaffinematrixget(IMG_AFFINE_TRANSLATE, array('x' => 2, 'y' => 3));
    print_r($matrix);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => 1
        [1] => 0
        [2] => 0
        [3] => 1
        [4] => 2
        [5] => 3
    )

### Siehe auch

- imageaffine() - Return an image containing the affine transformed src image, using an optional clipping area
- imageaffinematrixconcat() - Concatenate two affine transformation matrices

# imagealphablending

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagealphablending — Set the blending mode for an image

### Beschreibung

function imagealphablending(GdImage `$image`, bool `$enable`): true

imagealphablending() allows for two different modes of drawing on truecolor images. In blending mode, the alpha channel component of the color supplied to all drawing function, such as imagesetpixel() determines how much of the underlying color should be allowed to shine through. As a result, gd automatically blends the existing color at that point with the drawing color, and stores the result in the image. The resulting pixel is opaque. In non-blending mode, the drawing color is copied literally with its alpha channel information, replacing the destination pixel. Blending mode is not available when drawing on palette images.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`enable`

  Whether to enable the blending mode or not. On true color images the default value is `true` otherwise the default value is `false`

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagealphablending() usage example

    <?php
    // Create image
    $im = imagecreatetruecolor(100, 100);

    // Set alphablending to on
    imagealphablending($im, true);

    // Draw a square
    imagefilledrectangle($im, 30, 30, 70, 70, imagecolorallocate($im, 255, 0, 0));

    // Output
    header('Content-Type: image/png');

    imagepng($im);
    ?>

# imageantialias

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageantialias — Should antialias functions be used or not

### Beschreibung

function imageantialias(GdImage `$image`, bool `$enable`): true

Activate the fast drawing antialiased methods for lines and wired polygons. It does not support alpha components. It works using a direct blend operation. It works only with truecolor images.

Thickness and styled are not supported.

Using antialiased primitives with transparent background color can end with some unexpected results. The blend method uses the background color as any other colors. The lack of alpha component support does not allow an alpha based antialiasing method.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`enable`

  Whether to enable antialiasing or not.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
7.2.0 | imageantialias() is now generally available. Formerly it was only available if PHP was compiled with the bundled version of the GD library.

### Beispiele

Beispiel #1 A comparison of two lines, one with anti-aliasing switched on

    <?php
    // Setup an anti-aliased image and a normal image
    $aa = imagecreatetruecolor(400, 100);
    $normal = imagecreatetruecolor(200, 100);

    // Switch antialiasing on for one image
    imageantialias($aa, true);

    // Allocate colors
    $red = imagecolorallocate($normal, 255, 0, 0);
    $red_aa = imagecolorallocate($aa, 255, 0, 0);

    // Draw two lines, one with AA enabled
    imageline($normal, 0, 0, 200, 100, $red);
    imageline($aa, 0, 0, 200, 100, $red_aa);

    // Merge the two images side by side for output (AA: left, Normal: Right)
    imagecopymerge($aa, $normal, 200, 0, 0, 0, 200, 100, 100);

    // Output image
    header('Content-type: image/png');

    imagepng($aa);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagecreatetruecolor() - Create a new true color image

# imagearc

(PHP 4, PHP 5, PHP 7, PHP 8)

imagearc — Zeichnet einen Bogen

### Beschreibung

function imagearc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`
): true

imagearc() zeichnet einen Kreisbogen um den angegebenen Mittelpunkt

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`center_x`

  x-Koordinate des Mittelpunkts

`center_y`

  y-Koordinate des Mittelpunkts

`width`

  Die Breite der Ellipse

`height`

  Die Höhe der Ellipse

`start_angle`

  Der Startwinkel des Bogens, in Grad.

`end_angle`

  Der Endwinkel des Bogens, in Grad. 0° liegt in der Drei-Uhr-Position und der Bogen wird im Uhrzeigersinn gezeichnet.

`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Zeichnen eines Kreises mittels imagearc()

    <?php

    // eine 200*200-Grafik erstellen
    $img = imagecreatetruecolor(200, 200);

    // Farben vorbereiten
    $white = imagecolorallocate($img, 255, 255, 255);
    $red   = imagecolorallocate($img, 255,   0,   0);
    $green = imagecolorallocate($img,   0, 255,   0);
    $blue  = imagecolorallocate($img,   0,   0, 255);

    // Kopf
    imagearc($img, 100, 100, 200, 200,  0, 360, $white);
    // Mund
    imagearc($img, 100, 100, 150, 150, 25, 155, $red);
    // Augen
    imagearc($img,  60,  75,  50,  50,  0, 360, $green);
    imagearc($img, 140,  75,  50,  50,  0, 360, $blue);

    // Ausgabe im Browser
    header("Content-type: image/png");
    imagepng($img);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagefilledarc() - Draw a partial arc and fill it
- imageellipse() - Draw an ellipse
- imagefilledellipse() - Draw a filled ellipse

# imageavif

(PHP 8 >= 8.1.0)

imageavif — Gibt das Bild im Browser oder einer Datei aus.

### Beschreibung

function imageavif(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$speed` = -1
): bool

Outputs or saves a AVIF Raster image from the given `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`file`

  Der Pfad oder eine offene Stream-Ressource (die nach der Beendigung dieser Funktion automatisch geschlossen wird), in dem bzw. der die Datei gespeichert werden soll. Falls nicht gesetzt oder `null`, wird der rohe Bilddatenstrom direkt ausgegeben.

`quality`

  `quality` is optional, and ranges from 0 (worst quality, smaller file) to 100 (best quality, larger file). If `-1` is provided, the default value `52` is used.

`speed`

  `speed` is optional, and ranges from 0 (slow, smaller file) to 10 (fast, larger file). If `-1` is provided, the default value `6` is used.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Fehler/Exceptions

Throws a ValueError if `quality` or `speed` is invalid.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Now throws a ValueError if `quality` or `speed` is invalid.

### Siehe auch

- imagepng() - Ausgabe eines Bildes im Browser oder als Datei im PNG-Format
- imagewbmp() - Gibt das Bild im Browser oder einer Datei aus.
- imagejpeg() - Gibt das Bild im Browser oder einer Datei aus.
- imagetypes() - Liefert die von der verwendeten PHP-Version unterstützten Grafikformate

# imagebmp

(PHP 7 >= 7.2.0, PHP 8)

imagebmp — Output a BMP image to browser or file

### Beschreibung

function imagebmp(GdImage `$image`, resource|string|null `$file` = `null`, bool `$compressed` = `true`): bool

Outputs or saves a BMP version of the given `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`file`

  Der Pfad oder eine offene Stream-Ressource (die nach der Beendigung dieser Funktion automatisch geschlossen wird), in dem bzw. der die Datei gespeichert werden soll. Falls nicht gesetzt oder `null`, wird der rohe Bilddatenstrom direkt ausgegeben.

  > Hinweis:

  > `null` is invalid if the `compressed` arguments is not used.

`compressed`

  Whether the BMP should be compressed with run-length encoding (RLE), or not.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
8.0.0 | The type of `compressed` is Boolean now; formerly it was Integer.

### Beispiele

Beispiel #1 Saving a BMP file

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'BMP with PHP', $text_color);

    // Save the image
    imagebmp($im, 'php.bmp');
    ?>

# imagechar

(PHP 4, PHP 5, PHP 7, PHP 8)

imagechar — Zeichnet ein horizontal ausgerichtetes Zeichen

### Beschreibung

function imagechar(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

imagechar() zeichnet das erste in `char` enthaltene Zeichen in der mit `image` angegebenen Grafik dar. Das Zeichen wird mit seiner linken oberen Ecke in `x`, `y` positioniert (die linke obere Ecke der Grafik hat die Koordinaten 0,0), die Darstellung erfolgt in der Farbe `color`

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`font`

  Kann bei eingebauten Schriftarten in Latin2-Kodierung 1, 2, 3, 4 oder 5 sein (wobei größere Zahlen größeren Schriftarten entsprechen) oder eine GdFont-Instanz, die von imageloadfont() zurückgegeben wurde.

`x`

  x-Koordinate des Startpunkts

`y`

  y-Koordinate des Startpunkts

`char`

  Das darzustellende Zeichen

`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `font` akzeptiert jetzt sowohl eine GdFont-Instanz als auch ein Integer; vorher wurde nur Integer akzeptiert.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagechar()-Beispiel

    <?php

    $im = imagecreate(100, 100);

    $string = 'PHP';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // schreibe ein schwarzes "P" in die linke obere Ecke
    imagechar($im, 1, 0, 0, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagecharup() - Zeichnet ein vertikal ausgerichtetes Zeichen
- imageloadfont() - Lädt eine neue Schriftart

# imagecharup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecharup — Zeichnet ein vertikal ausgerichtetes Zeichen

### Beschreibung

function imagecharup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

Zeichnet den Buchstaben `char` vertikal an der angegebenen Koordinate auf dem angegebenen `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`font`

  Kann bei eingebauten Schriftarten in Latin2-Kodierung 1, 2, 3, 4 oder 5 sein (wobei größere Zahlen größeren Schriftarten entsprechen) oder eine GdFont-Instanz, die von imageloadfont() zurückgegeben wurde.

`x`

  x-Koordinate des Anfangs.

`y`

  y-Koordinate des Anfangs.

`char`

  Der zu zeichnende Buchstabe.

`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `font` akzeptiert jetzt sowohl eine GdFont-Instanz als auch ein Integer; vorher wurde nur Integer akzeptiert.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagecharup()-Beispiel

    <?php

    $im = imagecreate(100, 100);

    $string = 'N wird aussehen wie ein Z';

    $bg = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // druckt ein schwarzes "Z" auf weißem Hintergrund
    imagecharup($im, 3, 10, 10, $string, $black);

    header('Content-type: image/png');
    imagepng($im);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagechar() - Zeichnet ein horizontal ausgerichtetes Zeichen
- imageloadfont() - Lädt eine neue Schriftart

# imagecolorallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorallocate — Alloziert eine Farbe für eine Grafik

### Beschreibung

function imagecolorallocate(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int|false

Gibt einen Farb-Kennzeichner zurück, der die aus den gegebenen RGB-Komponenten bestehende Farbe darstellt.

imagecolorallocate() muss aufgerufen werden, um jede Farbe zu erzeugen, die in dem durch `image` angegebenen Bild verwendet werden soll.

> Hinweis:

> Der erste Aufruf von imagecolorallocate() bestimmt die Hintergrundfarbe von palettenbasierten Bilder – also Bildern, die durch imagecreate() erzeugt wurden.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

Diese Parameter sind Ganzzahlen zwischen 0 und 255 oder Hexadezimalzahlen zwischen 0x00 und 0xFF.

### Rückgabewerte

Ein Farb-Kennzeichner oder `false`, falls die Farbe nicht alloziert werden konnte.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagecolorallocate()-Beispiel

    <?php

    $im = imagecreate(100, 100);

    // färbt den Hintergrund rot
    $background = imagecolorallocate($im, 255, 0, 0);

    // alloziert weitere Farben
    $white = imagecolorallocate($im, 255, 255, 255);
    $black = imagecolorallocate($im, 0, 0, 0);

    // hexadezimale Schreibweise
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    ?>

### Siehe auch

- imagecolorallocatealpha() - Allocate a color for an image
- imagecolordeallocate() - Löscht eine Farbdefinition

# imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagecolorallocatealpha — Allocate a color for an image

### Beschreibung

function imagecolorallocatealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int|false

imagecolorallocatealpha() behaves identically to imagecolorallocate() with the addition of the transparency parameter `alpha`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

`alpha`

  A value between `0` and `127`. `0` indicates completely opaque while `127` indicates completely transparent.

The `red`, `green` and `blue` parameters are integers between 0 and 255 or hexadecimals between 0x00 and 0xFF.

### Rückgabewerte

A color identifier or `false` if the allocation failed.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Example of using imagecolorallocatealpha()

    <?php
    $size = 300;
    $image=imagecreatetruecolor($size, $size);

    // something to get a white background with black border
    $back = imagecolorallocate($image, 255, 255, 255);
    $border = imagecolorallocate($image, 0, 0, 0);
    imagefilledrectangle($image, 0, 0, $size - 1, $size - 1, $back);
    imagerectangle($image, 0, 0, $size - 1, $size - 1, $border);

    $yellow_x = 100;
    $yellow_y = 75;
    $red_x    = 120;
    $red_y    = 165;
    $blue_x   = 187;
    $blue_y   = 125;
    $radius   = 150;

    // allocate colors with alpha values
    $yellow = imagecolorallocatealpha($image, 255, 255, 0, 75);
    $red    = imagecolorallocatealpha($image, 255, 0, 0, 75);
    $blue   = imagecolorallocatealpha($image, 0, 0, 255, 75);

    // drawing 3 overlapped circle
    imagefilledellipse($image, $yellow_x, $yellow_y, $radius, $radius, $yellow);
    imagefilledellipse($image, $red_x, $red_y, $radius, $radius, $red);
    imagefilledellipse($image, $blue_x, $blue_y, $radius, $radius, $blue);

    // don't forget to output a correct header!
    header('Content-Type: image/png');

    // and finally, output the result
    imagepng($image);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Beispiel #2 Convert typical alpha values for use with imagecolorallocatealpha()

Usually alpha values of `0` designate fully transparent pixels, and the alpha channel has 8 bits. To convert such alpha values to be compatible with imagecolorallocatealpha(), some simple arithmetic is sufficient:

    <?php
    $alpha8 = 0; // fully transparent
    var_dump(127 - ($alpha8 >> 1));
    $alpha8 = 255; // fully opaque
    var_dump(127 - ($alpha8 >> 1));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(127)
    int(0)

### Siehe auch

- imagecolorallocate() - Alloziert eine Farbe für eine Grafik
- imagecolordeallocate() - Löscht eine Farbdefinition

# imagecolorat

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorat — Liefert den Farbwert eines Bildpunktes

### Beschreibung

function imagecolorat(GdImage `$image`, int `$x`, int `$y`): int|false

Gibt den Farbindex des Pixels zurück, das sich an den angegebenen Koordinaten im Bild befindet, das durch `image` angegeben wurde.

Handelt es sich bei dem Bild um ein Echtfarben-Bild, gibt diese Funktion den RGB-Wert dieses Pixels als Integer zurück. Bitverschiebung und Maskierung kann verwendet werden, um auf die individuellen roten, grünen und blauen Komponentenwerte zuzugreifen.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`x`

  x-Kooordinate des Punkts.

`y`

  y-Koordinate des Punkts.

### Rückgabewerte

Gibt den Farbindex zurück. Bei einem Fehler wird `false` zurückgegeben.

Warnung

Diese Funktion kann sowohl das boolsche `false` zurückliefern, als auch einen nicht-boolschen Wert, welcher zu `false` ausgewertet wird. Weitere Informationen entnehmen Sie bitte dem Abschnitt über die boolschen Typen. Benutzen Sie deshalb den === Operator, um den Rückgabewert dieser Funktion zu überprüfen.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Zurgriff auf individuelle RGB-Werte

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);
    $r = ($rgb >> 16) & 0xFF;
    $g = ($rgb >> 8) & 0xFF;
    $b = $rgb & 0xFF;

    var_dump($r, $g, $b);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    int(119)
    int(123)
    int(180)

Beispiel #2 Menschenlesbare RGB-Werte unter Verwendung von imagecolorsforindex()

    <?php
    $im = imagecreatefrompng("php.png");
    $rgb = imagecolorat($im, 10, 15);

    $colors = imagecolorsforindex($im, $rgb);

    var_dump($colors);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    array(4) {
      ["red"]=>
      int(119)
      ["green"]=>
      int(123)
      ["blue"]=>
      int(180)
      ["alpha"]=>
      int(127)
    }

### Siehe auch

- imagecolorset() - Setzt die Farbe für den angegebenen Paletten-Index
- imagecolorsforindex() - Ermittelt die Farbwerte eines Palettenindex
- imagesetpixel() - Setzt ein einzelnes Pixel

# imagecolorclosest

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorclosest — Ermittelt den Index der Farbe, die der angegebenen Farbe am nächsten kommt

### Beschreibung

function imagecolorclosest(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Gibt den Index der Farbwert-Palette des Bildes zurück, der dem angegebenen RGB-Wert am nächsten kommt.

Die "Entfernung" zwischen der angeforderten Farbe und jedem Farb-Paletten-Wert wird berechnet, als ob die angegebenen RGB-Werte Punkte in einem dreidimensionalen Raum darstellen würden.

Wenn das Bild aus einer Datei erzeugt wurde, so werden nur die Farben aufgelöst, die im Bild verwendet werden. Farben, die nur in der Farbpalette enthalten sind, werden nicht aufgelöst.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

Die Farbparameter sind Ganzzahlen zwischen 0 und 255 oder Hexadezimalzahlen zwischen 0x00 und 0xFF.

### Rückgabewerte

Gibt den Index der Farbe in der Palette des Bildes zurück, die am nächsten an der angegebenen liegt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Suche nach einem Satz von Farben in einem Bild

    <?php
    // Konvertiere zunächst ein Bild in ein palettenbasiertes Bild
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Gesuchte Farben (RGB)
    $colors = array(
        array(254, 145, 154),
        array(153, 145, 188),
        array(153, 90, 145),
        array(255, 137, 92)
    );

    // Durchlaufe die gesuchten Farben und finde die nächstgelegene Farbe in der Palette.
    // Gib die Suchnummer, die gesuchten und die gefundenen RGB-Farben zurück.
    foreach($colors as $id => $rgb)
    {
        $result = imagecolorclosest($im, $rgb[0], $rgb[1], $rgb[2]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']})";

        echo "#$id: Gesuchte Farbe ($rgb[0], $rgb[1], $rgb[2]); Nächstgelegene Farbe: $result.\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    #0: Gesuchte Farbe (254, 145, 154); Nächstgelegene Farbe: (252, 150, 148).
    #1: Gesuchte Farbe (153, 145, 188); Nächstgelegene Farbe: (148, 150, 196).
    #2: Gesuchte Farbe (153, 90, 145); Nächstgelegene Farbe: (148, 90, 156).
    #3: Gesuchte Farbe (255, 137, 92); Nächstgelegene Farbe: (252, 150, 92).

### Siehe auch

- imagecolorexact() - Ermittelt den Index-Wert der angegebenen Farbe
- imagecolorclosestalpha() - Get the index of the closest color to the specified color + alpha
- imagecolorclosesthwb() - Get the index of the color which has the hue, white and blackness

# imagecolorclosestalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorclosestalpha — Get the index of the closest color to the specified color + alpha

### Beschreibung

function imagecolorclosestalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Returns the index of the color in the palette of the image which is "closest" to the specified RGB value and `alpha` level.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

`alpha`

  A value between `0` and `127`. `0` indicates completely opaque while `127` indicates completely transparent.

The colors parameters are integers between 0 and 255 or hexadecimals between 0x00 and 0xFF.

### Rückgabewerte

Returns the index of the closest color in the palette.

### Beispiele

Beispiel #1 Search for a set of colors in an image

    <?php
    // Start with an image and convert it to a palette-based image
    $im = imagecreatefrompng('figures/imagecolorclosest.png');
    imagetruecolortopalette($im, false, 255);

    // Search colors (RGB)
    $colors = array(
        array(254, 145, 154, 50),
        array(153, 145, 188, 127),
        array(153, 90, 145, 0),
        array(255, 137, 92, 84)
    );

    // Loop through each search and find the closest color in the palette.
    // Return the search number, the search RGB and the converted RGB match
    foreach($colors as $id => $rgb)
    {
        $result = imagecolorclosestalpha($im, $rgb[0], $rgb[1], $rgb[2], $rgb[3]);
        $result = imagecolorsforindex($im, $result);
        $result = "({$result['red']}, {$result['green']}, {$result['blue']}, {$result['alpha']})";

        echo "#$id: Search ($rgb[0], $rgb[1], $rgb[2], $rgb[3]); Closest match: $result.\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    #0: Search (254, 145, 154, 50); Closest match: (252, 150, 148, 0).
    #1: Search (153, 145, 188, 127); Closest match: (148, 150, 196, 0).
    #2: Search (153, 90, 145, 0); Closest match: (148, 90, 156, 0).
    #3: Search (255, 137, 92, 84); Closest match: (252, 150, 92, 0).

### Siehe auch

- imagecolorexactalpha() - Get the index of the specified color + alpha
- imagecolorclosest() - Ermittelt den Index der Farbe, die der angegebenen Farbe am nächsten kommt
- imagecolorclosesthwb() - Get the index of the color which has the hue, white and blackness

# imagecolorclosesthwb

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecolorclosesthwb — Get the index of the color which has the hue, white and blackness

### Beschreibung

function imagecolorclosesthwb(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Get the index of the color which has the hue, white and blackness nearest the given color.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

### Rückgabewerte

Returns an integer with the index of the color which has the hue, white and blackness nearest the given color.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Example of using imagecolorclosesthwb()

    <?php
    $im = imagecreatefromgif('php.gif');

    echo 'HWB: ' . imagecolorclosesthwb($im, 116, 115, 152);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    HWB: 33

### Siehe auch

- imagecolorclosest() - Ermittelt den Index der Farbe, die der angegebenen Farbe am nächsten kommt

# imagecolordeallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolordeallocate — Löscht eine Farbdefinition

### Beschreibung

function imagecolordeallocate(GdImage `$image`, int `$color`): true

Löscht eine zuvor mit imagecolorallocate() oder imagecolorallocatealpha() allozierte Farbe.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`color`

  Der Farbkennzeichner.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Verwendung von imagecolordeallocate()

    <?php
    $white = imagecolorallocate($im, 255, 255, 255);
    imagecolordeallocate($im, $white);
    ?>

### Siehe auch

- imagecolorallocate() - Alloziert eine Farbe für eine Grafik
- imagecolorallocatealpha() - Allocate a color for an image

# imagecolorexact

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorexact — Ermittelt den Index-Wert der angegebenen Farbe

### Beschreibung

function imagecolorexact(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Gibt den Index der angegebenen Farbe in der Farb-Palette des Bildes zurück.

Wenn das Bild aus einer Datei erzeugt wurde, so werden nur die Farben aufgelöst, die im Bild verwendet werden. Farben, die nur in der Farbpalette enthalten sind, werden nicht aufgelöst.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

### Rückgabewerte

Gibt den Paletten-Index der angegeben Farbe zurück, oder -1, falls die Farbe nicht existiert.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Ermittle Farben des GD-Logos

    <?php
    // Lade ein Bild
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = Array();
    $colors[] = imagecolorexact($im, 255, 0, 0);
    $colors[] = imagecolorexact($im, 0, 0, 0);
    $colors[] = imagecolorexact($im, 255, 255, 255);
    $colors[] = imagecolorexact($im, 100, 255, 52);

    print_r($colors);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 16711680
        [1] => 0
        [2] => 16777215
        [3] => 6618932
    )

### Siehe auch

- imagecolorclosest() - Ermittelt den Index der Farbe, die der angegebenen Farbe am nächsten kommt

# imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorexactalpha — Get the index of the specified color + alpha

### Beschreibung

function imagecolorexactalpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

Returns the index of the specified color+alpha in the palette of the image.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

`alpha`

  A value between `0` and `127`. `0` indicates completely opaque while `127` indicates completely transparent.

The colors parameters are integers between 0 and 255 or hexadecimals between 0x00 and 0xFF.

### Rückgabewerte

Returns the index of the specified color+alpha in the palette of the image, or -1 if the color does not exist in the image's palette.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Get colors from the GD logo

    <?php

    // Setup an image
    $im = imagecreatefrompng('./gdlogo.png');

    $colors   = Array();
    $colors[] = imagecolorexactalpha($im, 255, 0, 0, 0);
    $colors[] = imagecolorexactalpha($im, 0, 0, 0, 127);
    $colors[] = imagecolorexactalpha($im, 255, 255, 255, 55);
    $colors[] = imagecolorexactalpha($im, 100, 255, 52, 20);

    print_r($colors);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 16711680
        [1] => 2130706432
        [2] => 939524095
        [3] => 342163252
    )

### Siehe auch

- imagecolorclosestalpha() - Get the index of the closest color to the specified color + alpha

# imagecolormatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagecolormatch — Makes the colors of the palette version of an image more closely match the true color version

### Beschreibung

function imagecolormatch(GdImage `$image1`, GdImage `$image2`): true

Makes the colors of the palette version of an image more closely match the true color version.

### Parameter-Liste

`image1`

  A truecolor image object.

`image2`

  A palette image object pointing to an image that has the same size as `image1`.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image1` and `image2` expect GdImage instances now; previously, resources were expected.

### Beispiele

Beispiel #1 imagecolormatch() example

    <?php
    // Setup the true color and palette images
    $im1 = imagecreatefrompng('./gdlogo.png');
    $im2 = imagecreate(imagesx($im1), imagesy($im1));

    // Add some colors to $im2
    $colors   = Array();
    $colors[] = imagecolorallocate($im2, 255, 36, 74);
    $colors[] = imagecolorallocate($im2, 40, 0, 240);
    $colors[] = imagecolorallocate($im2, 82, 100, 255);
    $colors[] = imagecolorallocate($im2, 84, 63, 44);

    // Match these colors with the true color image
    imagecolormatch($im1, $im2);
    ?>

### Siehe auch

- imagecreatetruecolor() - Create a new true color image

# imagecolorresolve

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorresolve — Ermittelt den Index-Wert der angegebenen Farbe oder die nächstmögliche Alternative dazu

### Beschreibung

function imagecolorresolve(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`
): int

Diese Funktion gibt garantiert einen Farbindex für die angegebenen Farbe zurück, entweder den exakten oder den nächstmöglichen Wert.

Wenn das Bild aus einer Datei erzeugt wurde, so werden nur die Farben aufgelöst, die im Bild verwendet werden. Farben, die nur in der Farbpalette enthalten sind, werden nicht aufgelöst.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

### Rückgabewerte

Gibt einen Farbindex zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Verwendung von imagecoloresolve(), um Farben aus einem Bild auszulesen

    <?php
    // Lade ein Bild
    $im = imagecreatefromgif('phplogo.gif');

    // Ermittle die nächstgelegenen Farben des Bildes
    $colors = array();
    $colors[] = imagecolorresolve($im, 255, 255, 255);
    $colors[] = imagecolorresolve($im, 0, 0, 200);

    // Output
    print_r($colors);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 89
        [1] => 85
    )

### Siehe auch

- imagecolorclosest() - Ermittelt den Index der Farbe, die der angegebenen Farbe am nächsten kommt

# imagecolorresolvealpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorresolvealpha — Get the index of the specified color + alpha or its closest possible alternative

### Beschreibung

function imagecolorresolvealpha(
GdImage `$image`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha`
): int

This function is guaranteed to return a color index for a requested color, either the exact color or the closest possible alternative.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

`alpha`

  A value between `0` and `127`. `0` indicates completely opaque while `127` indicates completely transparent.

The colors parameters are integers between 0 and 255 or hexadecimals between 0x00 and 0xFF.

### Rückgabewerte

Returns a color index.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Using imagecoloresolvealpha() to get colors from an image

    <?php
    // Load an image
    $im = imagecreatefromgif('phplogo.gif');

    // Get closest colors from the image
    $colors = array();
    $colors[] = imagecolorresolvealpha($im, 255, 255, 255, 0);
    $colors[] = imagecolorresolvealpha($im, 0, 0, 200, 127);

    // Output
    print_r($colors);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 89
        [1] => 85
    )

### Siehe auch

- imagecolorclosestalpha() - Get the index of the closest color to the specified color + alpha

# imagecolorset

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorset — Setzt die Farbe für den angegebenen Paletten-Index

### Beschreibung

function imagecolorset(
GdImage `$image`,
int `$color`,
int `$red`,
int `$green`,
int `$blue`,
int `$alpha` = 0
): ?false

Hierdurch wird der Farbwert der Palette auf die angegebene Farbe gesetzt. Dies ist nützlich bei Aktionen wie "Fülle Farbe X mit Farbe Y" (Flood-Fill-Effekt), ohne den sonst notwendigen Aufwand für solche Aktionen betreiben zu müssen.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`color`

  Ein Index der Palette.

`red`

  Wert der Rotkomponente.

`green`

  Wert der Grünkomponente.

`blue`

  Wert der Blaukomponente.

`alpha`

  Wert der Alpha-Komponente.

### Rückgabewerte

Die Funktion gibt bei Erfolg `null` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagecolorset()-Beispiel

    <?php
    // Erzeuge ein 300x100 Bild
    $im = imagecreate(300, 100);

    // Setze den Hintergrund auf Rot
    imagecolorallocate($im, 255, 0, 0);

    // Ermittle den Farbindex des Hintergrunds
    $bg = imagecolorat($im, 0, 0);

    // Setze den Hintergrund auf Blau
    imagecolorset($im, $bg, 0, 0, 255);

    // Gib das Bild an den Browser aus
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Siehe auch

- imagecolorat() - Liefert den Farbwert eines Bildpunktes

# imagecolorsforindex

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorsforindex — Ermittelt die Farbwerte eines Palettenindex

### Beschreibung

function imagecolorsforindex(GdImage `$image`, int `$color`): array

Gibt die Farbwerte eines Palettenindex zurück.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`color`

  Der Palettenindex.

### Rückgabewerte

Gibt ein assoziatives Array mit den Schlüsseln red, green, blue und alpha zurück, das die entsprechenden Werte für den angegebenen Palettenindex enthält.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
8.0.0 | imagecolorsforindex() löst jetzt eine ValueError Ausnahme aus, wenn `color` außerhalb des Bereichs liegt; zuvor wurde stattdessen `false` zurückgegeben.

### Beispiele

Beispiel #1 imagecolorsforindex()-Beispiel

    <?php

    // Erzeuge ein Bild
    $im = imagecreatefrompng('nexen.png');

    // Ermittle eine Farbe
    $start_x = 40;
    $start_y = 50;
    $color_index = imagecolorat($im, $start_x, $start_y);

    // Bringe es in menschenlesbare Form
    $color_tran = imagecolorsforindex($im, $color_index);

    // Was ist es?
    print_r($color_tran);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
       [red] => 226
       [green] => 222
       [blue] => 252
       [alpha] => 0
    )

### Siehe auch

- imagecolorat() - Liefert den Farbwert eines Bildpunktes
- imagecolorexact() - Ermittelt den Index-Wert der angegebenen Farbe

# imagecolorstotal

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorstotal — Ermittelt die Anzahl der Farben in der Palette eines Bildes

### Beschreibung

function imagecolorstotal(GdImage `$image`): int

Gibt die Anzahl der Farben in der Palette eines Bildes zurück.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

### Rückgabewerte

Gibt die Anzahl der Farben in der Palette des angegebenen Bildes oder 0 für Echtfarbbilder zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Ermitteln der Gesamtanzahl von Farben in einem Bild unter Verwendung von imagecolorstotal()

    <?php
    // Erzeuge ein Bild
    $im = imagecreatefromgif('php.gif');

    echo 'Zahl der Farben im Bild: ' . imagecolorstotal($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Zahl der Farben im Bild: 128

### Siehe auch

- imagecolorat() - Liefert den Farbwert eines Bildpunktes
- imagecolorsforindex() - Ermittelt die Farbwerte eines Palettenindex
- imageistruecolor() - Finds whether an image is a truecolor image

# imagecolortransparent

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolortransparent — Definiert eine Farbe als transparent

### Beschreibung

function imagecolortransparent(GdImage `$image`, ?int `$color` = `null`): int

Liest oder setzt die transparente Farbe des angegebenen Bildes `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt die Kennung der neuen transparenten Farbe zurück (oder der aktuellen, falls keine Farbe angegeben wurde). Falls `color` `null` ist und das Bild keine transparente Farbe hat, ist die zurückgegebene Kennung `-1`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
8.0.0 | `color` ist jetzt nullbar.

### Beispiele

Beispiel #1 imagecolortransparent()-Beispiel

    <?php
    // Erzeuge ein 55x30-Bild
    $im = imagecreatetruecolor(55, 30);
    $red = imagecolorallocate($im, 255, 0, 0);
    $black = imagecolorallocate($im, 0, 0, 0);

    // Mache den Hintergrund transparent
    imagecolortransparent($im, $black);

    // Zeichne ein rotes Rechteck
    imagefilledrectangle($im, 4, 4, 50, 25, $red);

    // Speichere das Bild
    imagepng($im, './imagecolortransparent.png');
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Anmerkungen

> Hinweis: Die Transparenz wird nur mit imagecopymerge() und Echtfarbbildern kopiert, nicht mit imagecopy() oder Palettenbildern.

> Hinweis:

> Die transparente Farbe ist eine Eigenschaft des Bildes, nicht der Farbe. Sobald eine Farbe als transparente Farbe definiert wurde, sind alle Bereiche eines Bildes mit dieser Farbe, die zuvor gezeichnet wurden, transparent.

# imageconvolution

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

imageconvolution — Apply a 3x3 convolution matrix, using coefficient and offset

### Beschreibung

function imageconvolution(
GdImage `$image`,
array `$matrix`,
float `$divisor`,
float `$offset`
): bool

Applies a convolution matrix on the image, using the given coefficient and offset.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`matrix`

  A 3x3 matrix: an array of three arrays of three floats.

`divisor`

  The divisor of the result of the convolution, used for normalization.

`offset`

  Color offset.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Embossing the PHP.net logo

    <?php
    $image = imagecreatefromgif('http://www.php.net/images/php.gif');

    $emboss = array(array(2, 0, 0), array(0, -1, 0), array(0, 0, -1));
    imageconvolution($image, $emboss, 1, 127);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Beispiel #2 Gaussian blur

    <?php
    $image = imagecreatetruecolor(180,40);

    // Writes the text and apply a gaussian blur on the image
    imagestring($image, 5, 10, 8, 'Gaussian Blur Text', 0x00ff00);
    $gaussian = array(array(1.0, 2.0, 1.0), array(2.0, 4.0, 2.0), array(1.0, 2.0, 1.0));
    imageconvolution($image, $gaussian, 16, 0);

    // Rewrites the text for comparison
    imagestring($image, 5, 10, 18, 'Gaussian Blur Text', 0x00ff00);

    header('Content-Type: image/png');
    imagepng($image, null, 9);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

### Siehe auch

- imagefilter() - Applies a filter to an image

# imagecopy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopy — Kopiert einen Bildausschnitt

### Beschreibung

function imagecopy(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`
): true

Kopiert einen Teil des Quellbildes `src_image` nach `dst_image`. Der zu kopierende Teil wird über die x/y-Koordinaten `src_x` und `src_y` angegeben. Die Breite wird in `src_width` und die Höhe in `src_height` angegeben. Der Ausschnitt wird an die x/y-Koordinaten `dst_x` und `dst_y` kopiert.

### Parameter-Liste

`dst_image`

  Ressource des Zielbildes.

`src_image`

  Ressource des Quellbildes.

`dst_x`

  x-Koordinate des Zielpunkts.

`dst_y`

  y-Koordinate des Zielpunkts.

`src_x`

  x-Koordinate des Quellpunkts.

`src_y`

  y-Koordinate des Quellpunkts.

`src_width`

  Breite der Quelle.

`src_height`

  Höhe der Quelle.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `dst_image` und `src_image` erwarten jetzt GdImage-Instanzen; zuvor wurde eine Ressource erwartet.

### Beispiele

Beispiel #1 Beschneiden des PHP.net-Logos

    <?php
    // Erzeuge die Bilder
    $src = imagecreatefromgif('php.gif');
    $dest = imagecreatetruecolor(80, 40);

    // Kopiere
    imagecopy($dest, $src, 0, 0, 20, 13, 80, 40);

    // Ausgabe
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagecrop() - Crop an image to the given rectangle

# imagecopymerge

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecopymerge — Copy and merge part of an image

### Beschreibung

function imagecopymerge(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

Copy a part of `src_image` onto `dst_image` starting at the x,y coordinates `src_x`, `src_y` with a width of `src_width` and a height of `src_height`. The portion defined will be copied onto the x,y coordinates, `dst_x` and `dst_y`.

### Parameter-Liste

`dst_image`

  Ressource des Zielbildes.

`src_image`

  Ressource des Quellbildes.

`dst_x`

  x-coordinate of destination point.

`dst_y`

  y-coordinate of destination point.

`src_x`

  x-coordinate of source point.

`src_y`

  y-coordinate of source point.

`src_width`

  Breite der Quelle.

`src_height`

  Höhe der Quelle.

`pct`
  The two images will be merged according to `pct` which can range from 0 to 100. When `pct` = 0, no action is taken, when 100 this function behaves identically to imagecopy() for palette images, except for ignoring alpha components, while it implements alpha transparency for true colour images.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `dst_image` and `src_image` expect GdImage instances now; previously, resources were expected.

### Beispiele

Beispiel #1 Merging two copies of the PHP.net logo with 75% transparency

    <?php
    // Create image instances
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Copy and merge
    imagecopymerge($dest, $src, 10, 10, 0, 0, 100, 47, 75);

    // Output
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopymergegray — Copy and merge part of an image with gray scale

### Beschreibung

function imagecopymergegray(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$src_width`,
int `$src_height`,
int `$pct`
): true

imagecopymergegray() copy a part of `src_image` onto `dst_image` starting at the x,y coordinates `src_x`, `src_y` with a width of `src_width` and a height of `src_height`. The portion defined will be copied onto the x,y coordinates, `dst_x` and `dst_y`.

This function is identical to imagecopymerge() except that when merging it preserves the hue of the source by converting the destination pixels to gray scale before the copy operation.

### Parameter-Liste

`dst_image`

  Ressource des Zielbildes.

`src_image`

  Ressource des Quellbildes.

`dst_x`

  x-coordinate of destination point.

`dst_y`

  y-coordinate of destination point.

`src_x`

  x-coordinate of source point.

`src_y`

  y-coordinate of source point.

`src_width`

  Breite der Quelle.

`src_height`

  Höhe der Quelle.

`pct`
  The `src_image` will be changed to grayscale according to `pct` where 0 is fully grayscale and 100 is unchanged. When `pct` = 100 this function behaves identically to imagecopy() for palette images, except for ignoring alpha components, while it implements alpha transparency for true colour images.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `dst_image` and `src_image` expect GdImage instances now; previously, resources were expected.

### Beispiele

Beispiel #1 imagecopymergegray() usage

    <?php
    // Create image instances
    $dest = imagecreatefromgif('php.gif');
    $src = imagecreatefromgif('php.gif');

    // Copy and merge - Gray = 20%
    imagecopymergegray($dest, $src, 10, 10, 0, 0, 100, 47, 20);

    // Output
    header('Content-Type: image/gif');
    imagegif($dest);
    ?>

# imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopyresampled — Copy and resize part of an image with resampling

### Beschreibung

function imagecopyresampled(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

imagecopyresampled() copies a rectangular portion of one image to another image, smoothly interpolating pixel values so that, in particular, reducing the size of an image still retains a great deal of clarity.

In other words, imagecopyresampled() will take a rectangular area from `src_image` of width `src_width` and height `src_height` at position (`src_x`,`src_y`) and place it in a rectangular area of `dst_image` of width `dst_width` and height `dst_height` at position (`dst_x`,`dst_y`).

If the source and destination coordinates and width and heights differ, appropriate stretching or shrinking of the image fragment will be performed. The coordinates refer to the upper left corner. This function can be used to copy regions within the same image (if `dst_image` is the same as `src_image`) but if the regions overlap the results will be unpredictable.

### Parameter-Liste

`dst_image`

  Ressource des Zielbildes.

`src_image`

  Ressource des Quellbildes.

`dst_x`

  x-coordinate of destination point.

`dst_y`

  y-coordinate of destination point.

`src_x`

  x-coordinate of source point.

`src_y`

  y-coordinate of source point.

`dst_width`

  Destination width.

`dst_height`

  Destination height.

`src_width`

  Breite der Quelle.

`src_height`

  Höhe der Quelle.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | The return type is `true` now; previously, it was bool.
8.0.0 | `dst_image` and `src_image` expect GdImage instances now; previously, resources were expected.

### Beispiele

Beispiel #1 Simple example

This example will resample an image to half its original size.

    <?php
    // The file
    $filename = 'test.jpg';
    $percent = 0.5;

    // Content type
    header('Content-Type: image/jpeg');

    // Get new dimensions
    list($width, $height) = getimagesize($filename);
    $new_width = $width * $percent;
    $new_height = $height * $percent;

    // Resample
    $image_p = imagecreatetruecolor($new_width, $new_height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $new_width, $new_height, $width, $height);

    // Output
    imagejpeg($image_p, null, 100);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Beispiel #2 Resampling an image proportionally

This example will display an image with the maximum width, or height, of 200 pixels.

    <?php
    // The file
    $filename = 'test.jpg';

    // Set a maximum height and width
    $width = 200;
    $height = 200;

    // Content type
    header('Content-Type: image/jpeg');

    // Get new dimensions
    list($width_orig, $height_orig) = getimagesize($filename);

    $ratio_orig = $width_orig/$height_orig;

    if ($width/$height > $ratio_orig) {
       $width = $height*$ratio_orig;
    } else {
       $height = $width/$ratio_orig;
    }

    // Resample
    $image_p = imagecreatetruecolor($width, $height);
    $image = imagecreatefromjpeg($filename);
    imagecopyresampled($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig);

    // Output
    imagejpeg($image_p, null, 100);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Anmerkungen

> Hinweis:

> There is a problem due to palette image limitations (255+1 colors). Resampling or filtering an image commonly needs more colors than 255, a kind of approximation is used to calculate the new resampled pixel and its color. With a palette image we try to allocate a new color, if that failed, we choose the closest (in theory) computed color. This is not always the closest visual color. That may produce a weird result, like blank (or visually blank) images. To skip this problem, please use a truecolor image as a destination image, such as one created by imagecreatetruecolor().

### Siehe auch

- imagecopyresized() - Kopieren und Ändern der Größe eines Bild-Teiles
- imagescale() - Scale an image using the given new width and height
- imagecrop() - Crop an image to the given rectangle

# imagecopyresized

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopyresized — Kopieren und Ändern der Größe eines Bild-Teiles

### Beschreibung

function imagecopyresized(
GdImage `$dst_image`,
GdImage `$src_image`,
int `$dst_x`,
int `$dst_y`,
int `$src_x`,
int `$src_y`,
int `$dst_width`,
int `$dst_height`,
int `$src_width`,
int `$src_height`
): true

imagecopyresized() kopiert einen rechteckigen Ausschnitt eines Bildes in ein anderes Bild. `dst_image` gibt das Zielbild, `src_image` gibt die Bildquelle an.

Mit anderen Worten, imagecopyresized() nimmt einen rechteckigen Ausschnitt von `src_image` der Breite `src_width` and Höhe `src_height` von Position (`src_x`,`src_y`) und platziert diesen in einem rechteckigen Bereich in `dst_image` mit der Breite `dst_width` and Höhe `dst_height` an der Position (`dst_x`,`dst_y`).

Unterscheiden sich die Angaben der Quelle und des Ziels bezogen auf die Koordinaten, Höhe oder Breite, wird das Teilbild entsprechend gedehnt oder geschrumpft. Die Koordinaten beziehen sich auf die linke obere Ecke. Sie können hiermit auch Teilbilder innerhalb ein- und desselben Bildes kopieren, sofern `dst_image` und `src_image` gleich sind. Falls sich dabei aber die kopierten Teile überlappen, führt das zu unvorhersehbaren Ergebnissen.

### Parameter-Liste

`dst_image`

  Ressource des Zielbildes.

`src_image`

  Ressource des Quellbildes.

`dst_x`

  x-Koordinate des Zielrechtecks.

`dst_y`

  y-Koordinate des Zielrechtecks.

`src_x`

  x-Koordinate des Quellrechtecks.

`src_y`

  y-Koordinate des Quellrechtecks.

`dst_width`

  Breite des Zielrechtecks.

`dst_height`

  Höhe des Zielrechtecks.

`src_width`

  Breite der Quelle.

`src_height`

  Höhe der Quelle.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `dst_image` und `src_image` erwarten jetzt GdImage-Instanzen; zuvor wurde eine resource erwartet.

### Beispiele

Beispiel #1 Ein Bild skalieren

Dieses Beispiel zeigt ein Bild in halber Größe an.

    <?php
    // Datei und Faktor der Größenänderung
    $filename = 'test.jpg';
    $percent = 0.5;

    // Typ der Ausgabe
    header('Content-Type: image/jpeg');

    // Neue Größe berechnen
    list($width, $height) = getimagesize($filename);
    $newwidth = $width * $percent;
    $newheight = $height * $percent;

    // Bild laden
    $thumb = imagecreatetruecolor($newwidth, $newheight);
    $source = imagecreatefromjpeg($filename);

    // Skalieren
    imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height);

    // Ausgabe
    imagejpeg($thumb);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Das Bild wird in halber Größe ausgegeben, allerdings könnten mit Hilfe der Funktion imagecopyresampled() Ergebnisse besserer Qualität erzielt werden.

### Anmerkungen

> Hinweis:

> Es gibt ein Problem bei Verwendung von limitierten Farbpaletten (255+1 Farben). Resampling und Filterung von Bildern benötigt in der Regel mehr als 255 Farben und eine Art der Annäherung wird zur Berechnung des neu resampleten Pixels und dessen Farbwertes verwendet. Bei einem palettenbasierten Bild wird zuerst versucht eine neue Farbe zu allokieren, wenn dies fehlschlägt wird der theoretisch nächst gelegene Farbwert aus der Palette verwendet. Dies ist aber nicht immer der Wert der farblich am nächsten ist. Dies kann zu eigenartigen Ergebnissen wie leeren (oder scheinbar leeren) Bildern führen. Um dieses Problem zu vermeiden, sollte ein Truecolor-Bild als Zielbild verwendet werden, welches z. B. mit der Funktion imagecreatetruecolor() erstellt werden kann.

### Siehe auch

- imagecopyresampled() - Copy and resize part of an image with resampling
- imagescale() - Scale an image using the given new width and height
- imagecrop() - Crop an image to the given rectangle

# imagecreate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreate — Erzeugt ein neues Palettenbild

### Beschreibung

function imagecreate(int `$width`, int `$height`): GdImage|false

imagecreate() gibt den Bezeichner für ein Bild zurück, der ein leeres Bild mit der angegebenen Größe repräsentiert.

Im Allgemeinen wird empfohlen, die Funktion imagecreatetruecolor() anstelle von imagecreate() zu verwenden, sodass die Bildverarbeitung mit der bestmöglichen Qualität erfolgt. Sollen Palettenbilder ausgegeben werden, dann sollte imagetruecolortopalette() unmittelbar vor dem Speichern des Bildes mit imagepng() oder imagegif() aufgerufen werden.

### Parameter-Liste

`width`

  Die Breite des Bildes.

`height`

  Die Höhe des Bildes.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Bei Erfolg gibt diese Funktion jetzt eine GDImage-Instanz zurück; zuvor wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 Erzeugen eines neuen GD-Bild-Streams und Ausgabe des Bildes

    <?php
    header("Content-Type: image/png");
    $im = @imagecreate(110, 20)
        or die("Kann keinen neuen GD-Bild-Stream erzeugen");
    $background_color = imagecolorallocate($im, 0, 0, 0);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5, "Ein Test-String", $text_color);
    imagepng($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagecreatetruecolor() - Create a new true color image

# imagecreatefromavif

(PHP 8 >= 8.1.0)

imagecreatefromavif — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefromavif(string `$filename`): GdImage|false

imagecreatefromavif() returns an image object representing the image obtained from the given filename.

### Parameter-Liste

`filename`

  Path to the AVIF raster image.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

# imagecreatefrombmp

(PHP 7 >= 7.2.0, PHP 8)

imagecreatefrombmp — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefrombmp(string `$filename`): GdImage|false

imagecreatefrombmp() returns an image identifier representing the image obtained from the given filename.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Path to the BMP image.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 Convert an BMP image to a PNG image using imagecreatefrombmp()

    <?php
    // Load the BMP file
    $im = imagecreatefrombmp('./example.bmp');

    // Convert it to a PNG file with default settings
    imagepng($im, './example.png');
    ?>

# imagecreatefromgd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd — Create a new image from GD file or URL

### Beschreibung

function imagecreatefromgd(string `$filename`): GdImage|false

Create a new image from GD file or URL.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Path to the GD file.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 imagecreatefromgd() example

    <?php
    // Load the gd image
    $im = @imagecreatefromgd('./test.gd');

    // Test if the image was loaded
    if(!$im)
    {
         die('Unable to load gd image!');
    }

    // Do image operations here

    // Save the image
    imagegd($im, './test_updated.gd');
    ?>

### Anmerkungen

Warnung

Die Bildformate GD und GD2 sind proprietäre Bildformate von libgd. Sie sind als veraltet anzusehen, und sollten nur zu Entwicklungs- und Testzwecken verwendet werden.

# imagecreatefromgd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2 — Create a new image from GD2 file or URL

### Beschreibung

function imagecreatefromgd2(string `$filename`): GdImage|false

Create a new image from GD2 file or URL.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Path to the GD2 image.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 imagecreatefromgd2() example

    <?php
    // Load the gd2 image
    $im = imagecreatefromgd2('./test.gd2');

    // Apply an effect on the image, in this
    // case negate the image
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_NEGATE);
    }

    // Save the image
    imagegd2($im, './test_updated.gd2');
    ?>

### Anmerkungen

Warnung

Die Bildformate GD und GD2 sind proprietäre Bildformate von libgd. Sie sind als veraltet anzusehen, und sollten nur zu Entwicklungs- und Testzwecken verwendet werden.

# imagecreatefromgd2part

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2part — Create a new image from a given part of GD2 file or URL

### Beschreibung

function imagecreatefromgd2part(
string `$filename`,
int `$x`,
int `$y`,
int `$width`,
int `$height`
): GdImage|false

Create a new image from a given part of GD2 file or URL.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Path to the GD2 image.

`x`

  x-coordinate of source point.

`y`

  y-coordinate of source point.

`width`

  Breite der Quelle.

`height`

  Höhe der Quelle.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 imagecreatefromgd2part() example

    <?php
    // For this example we need the image size before
    $image = getimagesize('./test.gd2');

    // Create the image instance now we got the image
    // sizes
    $im = imagecreatefromgd2part('./test.gd2', 4, 4, ($image[0] / 2) - 6, ($image[1] / 2) - 6);

    // Do an image operation, in this case we emboss the image
    if(function_exists('imagefilter'))
    {
        imagefilter($im, IMG_FILTER_EMBOSS);
    }

    // Save optimized image
    imagegd2($im, './test_emboss.gd2');
    ?>

### Anmerkungen

Warnung

Die Bildformate GD und GD2 sind proprietäre Bildformate von libgd. Sie sind als veraltet anzusehen, und sollten nur zu Entwicklungs- und Testzwecken verwendet werden.

# imagecreatefromgif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromgif — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefromgif(string `$filename`): GdImage|false

imagecreatefromgif() gibt den Bezeichner auf ein Bild zurück, der das aus der angegebenen Datei eingelesene Bild darstellt.

Achtung

Werden GIF-Dateien in den Speicher geladen, wird nur der erste Frame im Bildobjekt zurückgegeben. Die Größe des Bildes ist nicht notwendigerweise diejenige, die von getimagesize() gemeldet wird.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Pfad zum GIF-Bild.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Bei Erfolg gibt diese Funktion jetzt eine GDImage-Instanz zurück; zuvor wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 Beispiel zur Behandlung von Fehlern beim Einlesen eines GIFs

    <?php
    function LoadGif($imgname) {
        /* Versuche Datei zu öffnen */
        $im = @imagecreatefromgif($imgname);

        /* Wenn Öffnen fehlgeschlagen ist */
        if (!$im) {
            /* Erzeuge ein leeres Bild */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Gebe eine Fehlermeldung im Bild aus */
            imagestring($im, 1, 5, 5, 'Fehler beim Öffnen von ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/gif');

    $img = LoadGif('bogus.image');

    imagegif($img);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imagecreatefromjpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromjpeg — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefromjpeg(string `$filename`): GdImage|false

imagecreatefromjpeg() gibt einen Bezeichner für das Bild zurück, das aus der angegebenen Datei eingelesen wurde.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Pfad des JPEG-Bilds.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Bei Erfolg gibt diese Funktion jetzt eine GDImage-Instanz zurück; zuvor wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 Beispiel für Fehlerbehandlung beim Laden eines JPEG

    <?php
    function LoadJpeg($imgname)
    {
        /* Versuche zu öffnen */
        $im = @imagecreatefromjpeg($imgname);

        /* Prüfe, ob das fehlschlug */
        if(!$im)
        {
            /* Erzeuge ein schwarzes Bild */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Gib eine Fehlermeldung aus */
            imagestring($im, 1, 5, 5, 'Fehler beim Laden von ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/jpeg');

    $img = LoadJpeg('bogus.image');

    imagejpeg($img);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imagecreatefrompng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefrompng — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefrompng(string `$filename`): GdImage|false

imagecreatefrompng() gibt einen Bezeichner für das Bild zurück, das aus der angegebenen Datei eingelesen wurde.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Pfad des PNG-Bilds.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Bei Erfolg gibt diese Funktion jetzt eine GDImage-Instanz zurück; zuvor wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 Beispiel für Fehlerbehandlung beim Laden eines PNG

    <?php
    function LoadPNG($imgname)
    {
        /* Versuche zu öffnen */
        $im = @imagecreatefrompng($imgname);

        /* Prüfe, ob das fehlschlug */
        if(!$im)
        {
            /* Erzeuge ein schwarzes Bild */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Gib eine Fehlermeldung aus */
            imagestring($im, 1, 5, 5, 'Fehler beim Laden von ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/png');

    $img = LoadPNG('bogus.image');

    imagepng($img);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

imagecreatefromstring — Create a new image from the image stream in the string

### Beschreibung

function imagecreatefromstring(string `$data`): GdImage|false

imagecreatefromstring() returns an image identifier representing the image obtained from the given `data`. These types will be automatically detected if your build of PHP supports them: JPEG, PNG, GIF, BMP, WBMP, GD2, WEBP and AVIF.

### Parameter-Liste

`data`

  A string containing the image data.

### Rückgabewerte

An image object will be returned on success. `false` is returned if the image type is unsupported, the data is not in a recognised format, or the image is corrupt and cannot be loaded.

### Fehler/Exceptions

imagecreatefromstring() raises an E_WARNING level error, if the data is not in a recognized format.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.
7.3.0 | WEBP is supported now (if supported by the libgd in use).

### Beispiele

Beispiel #1 imagecreatefromstring() example

    <?php
    $data = 'iVBORw0KGgoAAAANSUhEUgAAABwAAAASCAMAAAB/2U7WAAAABl'
           . 'BMVEUAAAD///+l2Z/dAAAASUlEQVR4XqWQUQoAIAxC2/0vXZDr'
           . 'EX4IJTRkb7lobNUStXsB0jIXIAMSsQnWlsV+wULF4Avk9fLq2r'
           . '8a5HSE35Q3eO2XP1A1wQkZSgETvDtKdQAAAABJRU5ErkJggg==';
    $data = base64_decode($data);

    $im = imagecreatefromstring($data);
    if ($im !== false) {
        header('Content-Type: image/png');
        imagepng($im);
    }
    else {
        echo 'An error occurred.';
    }
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagecreatefromjpeg() - Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefrompng() - Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefromgif() - Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatetruecolor() - Create a new true color image

# imagecreatefromtga

(PHP 7 >= 7.4.0, PHP 8)

imagecreatefromtga — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefromtga(string `$filename`): GdImage|false

imagecreatefromtga() returns an image object representing the image obtained from the given filename.

### Parameter-Liste

`filename`

  Path to the Truevision TGA image.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a Ressource was returned.

# imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromwbmp — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefromwbmp(string `$filename`): GdImage|false

imagecreatefromwbmp() returns an image identifier representing the image obtained from the given filename.

> Hinweis: WBMP images are Wireless Bitmaps, not Windows Bitmaps. The latter can be loaded with imagecreatefrombmp().

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Path to the WBMP image.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 Example to handle an error during loading of a WBMP

    <?php
    function LoadWBMP($imgname)
    {
        /* Attempt to open */
        $im = @imagecreatefromwbmp($imgname);

        /* See if it failed */
        if(!$im)
        {
            /* Create a blank image */
            $im  = imagecreatetruecolor(150, 30);
            $bgc = imagecolorallocate($im, 255, 255, 255);
            $tc  = imagecolorallocate($im, 0, 0, 0);

            imagefilledrectangle($im, 0, 0, 150, 30, $bgc);

            /* Output an error message */
            imagestring($im, 1, 5, 5, 'Error loading ' . $imgname, $tc);
        }

        return $im;
    }

    header('Content-Type: image/vnd.wap.wbmp');

    $img = LoadWBMP('bogus.image');

    imagewbmp($img);
    ?>

# imagecreatefromwebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagecreatefromwebp — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefromwebp(string `$filename`): GdImage|false

imagecreatefromwebp() returns an image identifier representing the image obtained from the given filename. Note that animated WebP files cannot be read.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Path to the WebP image.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 Convert an WebP image to a jpeg image using imagecreatefromwebp()

    <?php
    // Load the WebP file
    $im = imagecreatefromwebp('./example.webp');

    // Convert it to a jpeg file with 100% quality
    imagejpeg($im, './example.jpeg', 100);
    ?>

# imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxbm — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefromxbm(string `$filename`): GdImage|false

imagecreatefromxbm() returns an image identifier representing the image obtained from the given filename.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Path to the XBM image.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 Convert an XBM image to a png image using imagecreatefromxbm()

    <?php
    // Load the xbm file
    $xbm = imagecreatefromxbm('./example.xbm');

    // Convert it to a png file
    imagepng($xbm, './example.png');
    ?>

# imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxpm — Erzeugt ein neues Bild aus einer Datei oder URL

### Beschreibung

function imagecreatefromxpm(string `$filename`): GdImage|false

imagecreatefromxpm() returns an image identifier representing the image obtained from the given filename.

Tipp

Wenn fopen wrappers aktiviert ist, kann mit dieser Funktion eine URL als Dateiname verwendet werden. Mehr Details dazu, wie der Dateiname angeben werden muss, sind bei fopen() zu finden. Eine Liste der unterstützten URL-Protokolle, die Fähigkeiten der verschiedenen Wrapper, Hinweise zu deren Verwendung und Informationen zu den eventuell vorhandenen vordefinierten Variablen sind unter Unterstützte Protokolle und Wrapper zu finden.

### Parameter-Liste

`filename`

  Path to the XPM image.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 Creating an image instance using imagecreatefromxpm()

    <?php
    // Check for XPM support
    if(!(imagetypes() & IMG_XPM))
    {
        die('Support for xpm was not found!');
    }

    // Create the image instance
    $xpm = imagecreatefromxpm('./example.xpm');

    // Do image operations here

    // PHP has no support for writing xpm images
    // so in this case we save the image as a
    // jpeg file with 100% quality
    imagejpeg($xpm, './example.jpg', 100);
    ?>

# imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecreatetruecolor — Create a new true color image

### Beschreibung

function imagecreatetruecolor(int `$width`, int `$height`): GdImage|false

imagecreatetruecolor() returns an image object representing a black image of the specified size.

### Parameter-Liste

`width`

  Image width.

`height`

  Image height.

### Rückgabewerte

Gibt im Erfolgsfall eine Bildobjekt zurück, im Fehlerfall `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 Creating a new GD image stream and outputting an image.

    <?php
    header ('Content-Type: image/png');
    $im = @imagecreatetruecolor(120, 20)
          or die('Cannot Initialize new GD image stream');
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);
    imagepng($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagecreate() - Erzeugt ein neues Palettenbild

# imagecrop

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecrop — Crop an image to the given rectangle

### Beschreibung

function imagecrop(GdImage `$image`, array `$rectangle`): GdImage|false

Crops an image to the given rectangular area and returns the resulting image. The given `image` is not modified.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`rectangle`

  The cropping rectangle as array with keys `x`, `y`, `width` and `height`.

### Rückgabewerte

Return cropped image object on successBei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 imagecrop() example

This example shows how to crop an image to a square area.

    <?php
    $im = imagecreatefrompng('example.png');
    $size = min(imagesx($im), imagesy($im));
    $im2 = imagecrop($im, ['x' => 0, 'y' => 0, 'width' => $size, 'height' => $size]);
    if ($im2 !== FALSE) {
        imagepng($im2, 'example-cropped.png');
    }
    ?>

### Siehe auch

- imagecropauto() - Crop an image automatically using one of the available modes

# imagecropauto

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecropauto — Crop an image automatically using one of the available modes

### Beschreibung

function imagecropauto(
GdImage `$image`,
int `$mode` = `IMG_CROP_DEFAULT`,
float `$threshold` = 0.5,
int `$color` = -1
): GdImage|false

Automatically crops an image according to the given `mode`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`mode`

  One of the following constants:

  `IMG_CROP_DEFAULT`
    Same as `IMG_CROP_TRANSPARENT`. Before PHP 7.4.0, the bundled libgd fell back to `IMG_CROP_SIDES`, if the image had no transparent color.
  `IMG_CROP_TRANSPARENT`
    Crops out a transparent background.
  `IMG_CROP_BLACK`
    Crops out a black background.
  `IMG_CROP_WHITE`
    Crops out a white background.
  `IMG_CROP_SIDES`
    Uses the 4 corners of the image to attempt to detect the background to crop.
  `IMG_CROP_THRESHOLD`
    Crops an image using the given `threshold` and `color`.
`threshold`

  Specifies the tolerance in percent to be used while comparing the image color and the color to crop. The method used to calculate the color difference is based on the color distance in the RGB(a) cube.

  Used only in `IMG_CROP_THRESHOLD` mode.

  > Hinweis: Before PHP 7.4.0, the bundled libgd used a somewhat different algorithm, so the same `threshold` yielded different results for system and bundled libgd.

`color`

  Either an RGB color value or a palette index.

  Used only in `IMG_CROP_THRESHOLD` mode.

### Rückgabewerte

Returns a cropped image object on successBei einem Fehler wird `false` zurückgegeben.. `false` is also returned if the whole image was cropped.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.
7.4.0 | The behavior of imagecropauto() in the bundled libgd has been synced with that of system libgd: `IMG_CROP_DEFAULT` no longer falls back to `IMG_CROP_SIDES` and threshold-cropping now uses the same algorithm as system libgd.
7.4.0 | The default value of `mode` has been changed to `IMG_CROP_AUTO`. Formerly, the default value has been `-1` which corresponds to `IMG_CROP_DEFAULT`, but passing `-1` is now deprecated.

### Beispiele

Beispiel #1 Proper handling of auto-cropping

As noted in the return value section, imagecropauto() returns `false` if the whole image was cropped. In this example we have an image object `$im` which should be automatically cropped only if there is something to crop; otherwise we want to proceed with the original image.

    <?php
    $cropped = imagecropauto($im, IMG_CROP_DEFAULT);
    if ($cropped !== false) { // in case a new image object was returned
        $im = $cropped;       // assign the cropped image to $im
    }
    ?>

### Siehe auch

- imagecrop() - Crop an image to the given rectangle

# imagedashedline

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedashedline — Zeichnet eine gestrichelte Linie

### Beschreibung

function imagedashedline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Diese Funktion ist veraltet. Stattdessen sollte eine Kombination von imagesetstyle() und imageline() verwendet werden. 0,0 ist die obere linke Ecke des Bildes.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`x1`

  x-Koordinate des ersten Punktes.

`y1`

  y-Koordinate des ersten Punktes.

`x2`

  x-Koordinate des zweiten Punktes.

`y2`

  y-Koordinate des zweiten Punktes.

`color`

  Die Füllfarbe. Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagedashedline()-Beispiel

    <?php
    // Erzeuge ein 100x100-Bild
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Zeichne die vertikale gestrichelte Linie
    imagedashedline($im, 50, 25, 50, 75, $white);

    // Speichere das Bild
    imagepng($im, './dashedline.png');
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Beispiel #2 Alternative zu imagedashedline()

    <?php
    // Erzeuge ein 100x100-Bild
    $im = imagecreatetruecolor(100, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);

    // Definiere den gewünschten Stil: die ersten 4 Pixel sind weiß und die
    // nächsten 4 sind transparent. Dies erzeugt den Effekt einer gestrichelten Linie
    $style = Array(
                    $white,
                    $white,
                    $white,
                    $white,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT,
                    IMG_COLOR_TRANSPARENT
                    );

    imagesetstyle($im, $style);

    // Zeichne die vertikale gestrichelte Linie
    imageline($im, 50, 25, 50, 75, IMG_COLOR_STYLED);

    // Speichere das Bild
    imagepng($im, './imageline.png');
    ?>

### Siehe auch

- imagesetstyle() - Set the style for line drawing
- imageline() - Zeichnet eine Linie

# imagedestroy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedestroy — Löscht ein Bild

Warnung

Diese Funktion ist seit PHP 8.5.0 als DEPRECATED (veraltet) markiert. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

#[\Deprecated]
function imagedestroy(GdImage `$image`): true

> Hinweis:

> Diese Funktion hat keine Auswirkung. Vor PHP 8.0.0 wurde sie verwendet, um die Ressource zu schließen.

Vor PHP 8.0.0 gibt imagedestroy() den durch die `image`-Ressource belegten Speicher wieder frei. Seit PHP 8.0.0 verwendet die GD-Erweiterung Objekte anstelle von Ressourcen, und Objekte können nicht explizit geschlossen werden.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.5.0 | Diese Funktion wurde als veraltet eingestuft.
8.0.0 | Diese Funktion ist jetzt ein NOP.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Verwendung von imagedestroy() vor PHP 8.0.0

    <?php
    // erzeuge ein 100 x 100 Bild
    $im = imagecreatetruecolor(100, 100);

    // verändere oder speichere das Bild

    // gibt den durch das Bild belegten Speicher frei
    imagedestroy($im);
    ?>

# imageellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imageellipse — Draw an ellipse

### Beschreibung

function imageellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Draws an ellipse centered at the specified coordinates.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`center_x`

  x-coordinate of the center.

`center_y`

  y-coordinate of the center.

`width`

  The ellipse width.

`height`

  The ellipse height.

`color`

  The color of the ellipse. Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imageellipse() example

    <?php

    // Create a blank image.
    $image = imagecreatetruecolor(400, 300);

    // Select the background color.
    $bg = imagecolorallocate($image, 0, 0, 0);

    // Fill the background with the color selected above.
    imagefill($image, 0, 0, $bg);

    // Choose a color for the ellipse.
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // Draw the ellipse.
    imageellipse($image, 200, 150, 300, 200, $col_ellipse);

    // Output the image.
    header("Content-type: image/png");
    imagepng($image);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Anmerkungen

> Hinweis:

> imageellipse() ignores imagesetthickness().

### Siehe auch

- imagefilledellipse() - Draw a filled ellipse
- imagearc() - Zeichnet einen Bogen

# imagefill

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefill — Flutfüllung

### Beschreibung

function imagefill(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

Führt eine Flutfüllung beginnend an der angegebenen Koordinate (oben links ist 0,0) mit der angegebenen Farbe `color` im Bild `image` durch.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`x`

  x-Koordinate des Anfangspunkts.

`y`

  y-Koordinate des Anfangspunkts.

`color`

  Die Füllfarbe. Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagefill()-Beispiel

    <?php

    $im = imagecreatetruecolor(100, 100);

    // Färbt den Hintergrund rot
    $red = imagecolorallocate($im, 255, 0, 0);
    imagefill($im, 0, 0, $red);

    header('Content-type: image/png');
    imagepng($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagecolorallocate() - Alloziert eine Farbe für eine Grafik

# imagefilledarc

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledarc — Draw a partial arc and fill it

### Beschreibung

function imagefilledarc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`,
int `$style`
): true

Draws a partial arc centered at the specified coordinate in the given `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`center_x`

  x-coordinate of the center.

`center_y`

  y-coordinate of the center.

`width`

  The arc width.

`height`

  The arc height.

`start_angle`

  The arc start angle, in degrees.

`end_angle`

  The arc end angle, in degrees. 0° is located at the three-o'clock position, and the arc is drawn clockwise.

`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

`style`

  A bitwise OR of the following possibilities:

  1. `IMG_ARC_PIE`
  2. `IMG_ARC_CHORD`
  3. `IMG_ARC_NOFILL`
  4. `IMG_ARC_EDGED`
  `IMG_ARC_PIE` and `IMG_ARC_CHORD` are mutually exclusive; `IMG_ARC_CHORD` just connects the starting and ending angles with a straight line, while `IMG_ARC_PIE` produces a rounded edge. `IMG_ARC_NOFILL` indicates that the arc or chord should be outlined, not filled. `IMG_ARC_EDGED`, used together with `IMG_ARC_NOFILL`, indicates that the beginning and ending angles should be connected to the center - this is a good way to outline (rather than fill) a 'pie slice'.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Creating a 3D looking pie

    <?php

    // create image
    $image = imagecreatetruecolor(100, 100);

    // allocate some colors
    $white    = imagecolorallocate($image, 0xFF, 0xFF, 0xFF);
    $gray     = imagecolorallocate($image, 0xC0, 0xC0, 0xC0);
    $darkgray = imagecolorallocate($image, 0x90, 0x90, 0x90);
    $navy     = imagecolorallocate($image, 0x00, 0x00, 0x80);
    $darknavy = imagecolorallocate($image, 0x00, 0x00, 0x50);
    $red      = imagecolorallocate($image, 0xFF, 0x00, 0x00);
    $darkred  = imagecolorallocate($image, 0x90, 0x00, 0x00);

    // make the 3D effect
    for ($i = 60; $i > 50; $i--) {
       imagefilledarc($image, 50, $i, 100, 50, 0, 45, $darknavy, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 45, 75 , $darkgray, IMG_ARC_PIE);
       imagefilledarc($image, 50, $i, 100, 50, 75, 360 , $darkred, IMG_ARC_PIE);
    }

    imagefilledarc($image, 50, 50, 100, 50, 0, 45, $navy, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 45, 75 , $gray, IMG_ARC_PIE);
    imagefilledarc($image, 50, 50, 100, 50, 75, 360 , $red, IMG_ARC_PIE);

    // flush image
    header('Content-type: image/png');
    imagepng($image);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledellipse — Draw a filled ellipse

### Beschreibung

function imagefilledellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

Draws an ellipse centered at the specified coordinate on the given `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`center_x`

  x-coordinate of the center.

`center_y`

  y-coordinate of the center.

`width`

  The ellipse width.

`height`

  The ellipse height.

`color`

  The fill color. Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagefilledellipse() example

    <?php

    // create a blank image
    $image = imagecreatetruecolor(400, 300);

    // fill the background color
    $bg = imagecolorallocate($image, 0, 0, 0);

    // choose a color for the ellipse
    $col_ellipse = imagecolorallocate($image, 255, 255, 255);

    // draw the white ellipse
    imagefilledellipse($image, 200, 150, 300, 200, $col_ellipse);

    // output the picture
    header("Content-type: image/png");
    imagepng($image);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Anmerkungen

> Hinweis:

> imagefilledellipse() ignores imagesetthickness().

### Siehe auch

- imageellipse() - Draw an ellipse
- imagefilledarc() - Draw a partial arc and fill it

# imagefilledpolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledpolygon — Zeichnet ein gefülltes Polygon

### Beschreibung

Signatur seit PHP 8.0.0 (keine Unterstützung für benannte Argumente)

function imagefilledpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Alternative Signatur (seit PHP 8.1.0 veraltet)

function imagefilledpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagefilledpolygon() erzeugt ein gefülltes Polygon im Bild, das durch `image` angegeben wurde.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`points`

  Ein Array, das die `x`- und `y`-Koordinaten der aufeinanderfolgenden Polygon-Eckpunkte enthält.

`num_points`

  Die Anzahl der Eckpunkte, die mindestens 3 sein muss.

  Wenn dieser Parameter gemäß der zweiten Signatur weggelassen wird, muss `points` eine gerade Anzahl von Elementen haben, und `num_points` wird angenommen als `count($punkte)/2`.
`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `num_points` ist veraltet und sollte nicht mehr verwendet werden.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagefilledpolygon()-Beispiel

    <?php
    // Initialisiere das Array der Polygon-Punkte
    $values = array(
                40,  50,  // Punkt 1 (x, y)
                20,  240, // Punkt 2 (x, y)
                60,  60,  // Punkt 3 (x, y)
                240, 20,  // Punkt 4 (x, y)
                50,  40,  // Punkt 5 (x, y)
                10,  10   // Punkt 6 (x, y)
                );

    // Erzeuge das Bild
    $image = imagecreatetruecolor(250, 250);

    // Weise Farben zu
    $bg   = imagecolorallocate($image, 0, 0, 0);
    $blue = imagecolorallocate($image, 0, 0, 255);

    // Fülle den Hintergrund
    imagefilledrectangle($image, 0, 0, 249, 249, $bg);

    // Zeichne ein Polygon
    imagefilledpolygon($image, $values, $blue);

    // Gib das Bild aus
    header('Content-type: image/png');
    imagepng($image);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagepolygon() - Zeichnet ein Polygon

# imagefilledrectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledrectangle — Zeichnet ein gefülltes Rechteck

### Beschreibung

function imagefilledrectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Erzeugt ein mit der Farbe `color` gefülltes Rechteck im angegebenen `image`, das sich von Punkt 1 bis zu Punkt 2 erstreckt. 0,0 ist die obere linke Ecke des Bildes.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`x1`

  x-Koordinate von Punkt 1.

`y1`

  y-Koordinate von Punkt 1.

`x2`

  x-Koordinate von Punkt 2.

`y2`

  y-Koordinate von Punkt 2.

`color`

  Die Füllfarbe. Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Beispiel für die Verwendung von imagefilledrectangle()

    <?php
    // Erzeuge ein 55x30-Bild
    $im = imagecreatetruecolor(55, 30);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Zeichne ein weißes Rechteck
    imagefilledrectangle($im, 4, 4, 50, 25, $white);

    // Speichere das Bild
    imagepng($im, './imagefilledrectangle.png');
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imagefilltoborder

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilltoborder — Füllt einen Bereich mit einer bestimmten Farbe

### Beschreibung

function imagefilltoborder(
GdImage `$image`,
int `$x`,
int `$y`,
int `$border_color`,
int `$color`
): true

imagefilltoborder() füllt den gesamten Bereich, dessen Grenze durch die Farbe in `border_color` definiert wird. Der Startpunkt wird durch `x` und `y` angegeben (oben links ist 0, 0). Der Bereich wird mit der Farbe `color` gefüllt.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`x`

  x-Koordinate des Anfangspunkts.

`y`

  y-Koordinate des Anfangspunkts.

`border_color`

  Die Grenzfarbe. Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

`color`

  Die Füllfarbe. Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Füllen einer Ellipse mit einer Farbe

    <?php
    // Erzeuge die Bildressource; definiere den Hintergrund als weiß
    $im = imagecreatetruecolor(100, 100);
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 255, 255, 255));

    // Zeichne eine auszufüllende Ellipse mit einem schwarzen Rand
    imageellipse($im, 50, 50, 50, 50, imagecolorallocate($im, 0, 0, 0));

    // Definiere die Rand- und Füllfarbe
    $border = imagecolorallocate($im, 0, 0, 0);
    $fill = imagecolorallocate($im, 255, 0, 0);

    // Fülle die Auswahl
    imagefilltoborder($im, 50, 50, $border, $fill);

    // Ausgabe
    header('Content-type: image/png');
    imagepng($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Anmerkungen

Der Algorithmus merkt sich nicht explizit, welche Pixel bereits gesetzt wurden, sondern schließt dies aus der Farbe des Pixels, so dass er nicht zwischen frisch gesetzten Pixeln und bereits gesetzten Pixeln unterscheiden kann. Das bedeutet, dass die Wahl einer beliebigen Füllfarbe, die bereits im Bild verwendet wird, zu unerwünschten Ergebnissen führen kann.

# imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — Applies a filter to an image

### Beschreibung

function imagefilter(GdImage `$image`, int `$filter`, array|int|float|bool `...$args`): bool

imagefilter() applies the given filter `filter` on the `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`filter`

  `filter` can be one of the following:

  - `IMG_FILTER_NEGATE`: Reverses all colors of the image.
  - `IMG_FILTER_GRAYSCALE`: Converts the image into grayscale by changing the red, green and blue components to their weighted sum using the same coefficients as the REC.601 luma (Y') calculation. The alpha components are retained. For palette images the result may differ due to palette limitations.
  - `IMG_FILTER_BRIGHTNESS`: Changes the brightness of the image. Use `args` to set the level of brightness. The range for the brightness is -255 to 255.
  - `IMG_FILTER_CONTRAST`: Changes the contrast of the image. Use `args` to set the level of contrast.
  - `IMG_FILTER_COLORIZE`: Like `IMG_FILTER_GRAYSCALE`, except you can specify the color. Use `args`, `arg2` and `arg3` in the form of `red`, `green`, `blue` and `arg4` for the `alpha` channel. The range for each color is 0 to 255.
  - `IMG_FILTER_EDGEDETECT`: Uses edge detection to highlight the edges in the image.
  - `IMG_FILTER_EMBOSS`: Embosses the image.
  - `IMG_FILTER_GAUSSIAN_BLUR`: Blurs the image using the Gaussian method.
  - `IMG_FILTER_SELECTIVE_BLUR`: Blurs the image.
  - `IMG_FILTER_MEAN_REMOVAL`: Uses mean removal to achieve a "sketchy" effect.
  - `IMG_FILTER_SMOOTH`: Makes the image smoother. Use `args` to set the level of smoothness.
  - `IMG_FILTER_PIXELATE`: Applies pixelation effect to the image, use `args` to set the block size and `arg2` to set the pixelation effect mode.
  - `IMG_FILTER_SCATTER`: Applies scatter effect to the image, use `args` and `arg2` to define the effect strength and additionally `arg3` to only apply the on select pixel colors.
`args`

  - `IMG_FILTER_BRIGHTNESS`: Brightness level.
  - `IMG_FILTER_CONTRAST`: Contrast level.
  - `IMG_FILTER_COLORIZE`: Wert der Rotkomponente.
  - `IMG_FILTER_SMOOTH`: Smoothness level.
  - `IMG_FILTER_PIXELATE`: Block size in pixels.
  - `IMG_FILTER_SCATTER`: Effect subtraction level. This must not be higher or equal to the addition level set with `arg2`.
`arg2`

  - `IMG_FILTER_COLORIZE`: Wert der Grünkomponente.
  - `IMG_FILTER_PIXELATE`: Whether to use advanced pixelation effect or not (defaults to `false`).
  - `IMG_FILTER_SCATTER`: Effect addition level.
`arg3`

  - `IMG_FILTER_COLORIZE`: Wert der Blaukomponente.
  - `IMG_FILTER_SCATTER`: Optional array indexed color values to apply effect at.
`arg4`

  - `IMG_FILTER_COLORIZE`: Alpha channel, A value between 0 and 127. 0 indicates completely opaque while 127 indicates completely transparent.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Throws a ValueError if `sub` or `plus` would cause over-/underflow with the `IMG_FILTER_SCATTER` `filter`.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Now throws a ValueError if `sub` or `plus` would cause over-/underflow with the `IMG_FILTER_SCATTER` `filter`.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
7.4.0 | Scatter support (`IMG_FILTER_SCATTER`) was added.

### Beispiele

Beispiel #1 imagefilter() grayscale example

    <?php
    $im = imagecreatefrompng('dave.png');

    if($im && imagefilter($im, IMG_FILTER_GRAYSCALE))
    {
        echo 'Image converted to grayscale.';

        imagepng($im, 'dave.png');
    }
    else
    {
        echo 'Conversion to grayscale failed.';
    }
    ?>

Beispiel #2 imagefilter() brightness example

    <?php
    $im = imagecreatefrompng('sean.png');

    if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
    {
        echo 'Image brightness changed.';

        imagepng($im, 'sean.png');
    }
    else
    {
        echo 'Image brightness change failed.';
    }
    ?>

Beispiel #3 imagefilter() colorize example

    <?php
    $im = imagecreatefrompng('philip.png');

    /* R, G, B, so 0, 255, 0 is green */
    if($im && imagefilter($im, IMG_FILTER_COLORIZE, 0, 255, 0))
    {
        echo 'Image successfully shaded green.';

        imagepng($im, 'philip.png');
    }
    else
    {
        echo 'Green shading failed.';
    }
    ?>

Beispiel #4 imagefilter() negate example

    <?php
    // Define our negate function so its portable for
    // php versions without imagefilter()
    function negate($im)
    {
        if(function_exists('imagefilter'))
        {
            return imagefilter($im, IMG_FILTER_NEGATE);
        }

        for($x = 0; $x < imagesx($im); ++$x)
        {
            for($y = 0; $y < imagesy($im); ++$y)
            {
                $index = imagecolorat($im, $x, $y);
                $rgb = imagecolorsforindex($index);
                $color = imagecolorallocate($im, 255 - $rgb['red'], 255 - $rgb['green'], 255 - $rgb['blue']);

                imagesetpixel($im, $x, $y, $color);
            }
        }

        return(true);
    }

    $im = imagecreatefromjpeg('kalle.jpg');

    if($im && negate($im))
    {
        echo 'Image successfully converted to negative colors.';

        imagejpeg($im, 'kalle.jpg', 100);
    }
    else
    {
        echo 'Converting to negative colors failed.';
    }
    ?>

Beispiel #5 imagefilter() pixelate example

    <?php
    // Load the PHP logo, we need to create two instances
    // to show the differences
    $logo1 = imagecreatefrompng('./php.png');
    $logo2 = imagecreatefrompng('./php.png');

    // Create the image instance we want to show the
    // differences on
    $output = imagecreatetruecolor(imagesx($logo1) * 2, imagesy($logo1));

    // Apply pixelation to each instance, with a block
    // size of 3
    imagefilter($logo1, IMG_FILTER_PIXELATE, 3);
    imagefilter($logo2, IMG_FILTER_PIXELATE, 3, true);

    // Merge the differences onto the output image
    imagecopy($output, $logo1, 0, 0, 0, 0, imagesx($logo1) - 1, imagesy($logo1) - 1);
    imagecopy($output, $logo2, imagesx($logo2), 0, 0, 0, imagesx($logo2) - 1, imagesy($logo2) - 1);

    // Output the differences
    header('Content-Type: image/png');
    imagepng($output);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Beispiel #6 imagefilter() scatter example

    <?php
    // Load the image
    $logo = imagecreatefrompng('./php.png');

    // Apply a very soft scatter effect to the image
    imagefilter($logo, IMG_FILTER_SCATTER, 3, 5);

    // Output the image with the scatter effect
    header('Content-Type: image/png');
    imagepng($logo);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Anmerkungen

> Hinweis: The result of `IMG_FILTER_SCATTER` is always random.

### Siehe auch

- imageconvolution() - Apply a 3x3 convolution matrix, using coefficient and offset

# imageflip

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageflip — Flips an image using a given mode

### Beschreibung

function imageflip(GdImage `$image`, int `$mode`): true

Flips the `image` image using the given `mode`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`mode`

  Flip mode, this can be one of the `IMG_FLIP_*` constants:

  Constant | Meaning
  --- | ---
  `IMG_FLIP_HORIZONTAL` | Flips the image horizontally.
  `IMG_FLIP_VERTICAL` | Flips the image vertically.
  `IMG_FLIP_BOTH` | Flips the image both horizontally and vertically.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Flips an image vertically

This example uses the `IMG_FLIP_VERTICAL` constant.

    <?php
    // File
    $filename = 'phplogo.png';

    // Content type
    header('Content-type: image/png');

    // Load
    $im = imagecreatefrompng($filename);

    // Flip it vertically
    imageflip($im, IMG_FLIP_VERTICAL);

    // Output
    imagejpeg($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Beispiel #2 Flips the image horizontally

This example uses the `IMG_FLIP_HORIZONTAL` constant.

    <?php
    // File
    $filename = 'phplogo.png';

    // Content type
    header('Content-type: image/png');

    // Load
    $im = imagecreatefrompng($filename);

    // Flip it horizontally
    imageflip($im, IMG_FLIP_HORIZONTAL);

    // Output
    imagejpeg($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imagefontheight

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontheight — Ermittelt die Höhe einer Schriftart

### Beschreibung

function imagefontheight(GdFont|int `$font`): int

Gibt die Höhe eines Zeichens (in Pixel) in der angegebenen Schriftart zurück.

### Parameter-Liste

`font`

  Kann bei eingebauten Schriftarten in Latin2-Kodierung 1, 2, 3, 4 oder 5 sein (wobei größere Zahlen größeren Schriftarten entsprechen) oder eine GdFont-Instanz, die von imageloadfont() zurückgegeben wurde.

### Rückgabewerte

Gibt die Höhe der Schriftart in Pixel zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `font` akzeptiert jetzt sowohl eine GdFont-Instanz als auch ein Integer; vorher wurde nur Integer akzeptiert.

### Beispiele

Beispiel #1 Verwendung von imagefontheight() mit integrierten Schriftarten

    <?php
    echo 'Höhe der Schriftart: ' . imagefontheight(4);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Höhe der Schriftart: 16

Beispiel #2 Verwendung von imagefontheight() mit imageloadfont()

    <?php
    // Lade eine .gdf-Schriftart
    $font = imageloadfont('anonymous.gdf');

    echo 'Höhe der Schriftart: ' . imagefontheight($font);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Höhe der Schriftart: 43

### Siehe auch

- imagefontwidth() - Ermittelt die Breite einer Schriftart
- imageloadfont() - Lädt eine neue Schriftart

# imagefontwidth

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontwidth — Ermittelt die Breite einer Schriftart

### Beschreibung

function imagefontwidth(GdFont|int `$font`): int

Gibt die Breite eines Zeichens (in Pixel) in der angegebenen Schriftart zurück.

### Parameter-Liste

`font`

  Kann bei eingebauten Schriftarten in Latin2-Kodierung 1, 2, 3, 4 oder 5 sein (wobei größere Zahlen größeren Schriftarten entsprechen) oder eine GdFont-Instanz, die von imageloadfont() zurückgegeben wurde.

### Rückgabewerte

Gibt die Breite der Schriftart in Pixel zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `font` akzeptiert jetzt sowohl eine GdFont-Instanz als auch ein Integer; vorher wurde nur Integer akzeptiert.

### Beispiele

Beispiel #1 Verwendung von imagefontwidth() mit integrierten Schriftarten

    <?php
    echo 'Breite der Schriftart: ' . imagefontwidth(4);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Breite der Schriftart: 8

Beispiel #2 Verwendung von imagefontwidth() mit imageloadfont()

    <?php
    // Lade eine .gdf Schriftart
    $font = imageloadfont('anonymous.gdf');

    echo 'Breite der Schriftart: ' . imagefontwidth($font);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Breite der Schriftart: 23

### Siehe auch

- imagefontheight() - Ermittelt die Höhe einer Schriftart
- imageloadfont() - Lädt eine neue Schriftart

# imageftbbox

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imageftbbox — Give the bounding box of a text using fonts via freetype2

### Beschreibung

function imageftbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

This function calculates and returns the bounding box in pixels for a FreeType text.

> Hinweis:

> Prior to PHP 8.0.0, imageftbbox() was an extended variant of imagettfbbox() which additionally supported the `options`. As of PHP 8.0.0, imagettfbbox() is an alias of imageftbbox().

### Parameter-Liste

`size`

  Die Schriftgröße in Punkten.

`angle`

  Angle in degrees in which `string` will be measured.

`font_filename`

  The name of the TrueType font file (can be a URL). Depending on which version of the GD library that PHP is using, it may attempt to search for files that do not begin with a leading '/' by appending '.ttf' to the filename and searching along a library-defined font path.

`string`

  The string to be measured.

`options`

  Possible array indexes for `options`
  Key | Type | Meaning
  --- | --- | ---
  `linespacing` | float | Defines drawing linespacing

### Rückgabewerte

imageftbbox() returns an array with 8 elements representing four points making the bounding box of the text:

0 | lower left corner, X position
1 | lower left corner, Y position
2 | lower right corner, X position
3 | lower right corner, Y position
4 | upper right corner, X position
5 | upper right corner, Y position
6 | upper left corner, X position
7 | upper left corner, Y position

The points are relative to the text regardless of the `angle`, so "upper left" means in the top left-hand corner seeing the text horizontally.

On failure, `false` is returned.

### Beispiele

Beispiel #1 imageftbbox() example

    <?php
    // Create a 300x150 image
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Set the background to be white
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Path to our font file
    $font = './arial.ttf';

    // First we create our bounding box
    $bbox = imageftbbox(10, 0, $font, 'The PHP Documentation Group');

    // This is our coordinates for X and Y
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 5;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    imagefttext($im, 10, 0, $x, $y, $black, $font, 'The PHP Documentation Group');

    // Output to browser
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Anmerkungen

> Hinweis: Diese Funktion ist nur verfügbar wenn PHP mit Freetype unterstützung (--with-freetype-dir=DIR) kompiliert wurde

### Siehe auch

- imagefttext() - Write text to the image using fonts using FreeType 2
- imagettfbbox() - Ermittelt das umgebende Rechteck eines Textes, der eine TrueType-Schriftart verwendet

# imagefttext

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagefttext — Write text to the image using fonts using FreeType 2

### Beschreibung

function imagefttext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

> Hinweis:

> Prior to PHP 8.0.0, imagefttext() was an extended variant of imagettftext() which additionally supported the `options`. As of PHP 8.0.0, imagettftext() is an alias of imagefttext().

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`size`

  The font size to use in points.

`angle`

  The angle in degrees, with 0 degrees being left-to-right reading text. Higher values represent a counter-clockwise rotation. For example, a value of 90 would result in bottom-to-top reading text.

`x`

  The coordinates given by `x` and `y` will define the basepoint of the first character (roughly the lower-left corner of the character). This is different from the imagestring(), where `x` and `y` define the upper-left corner of the first character. For example, "top left" is 0, 0.

`y`

  The y-ordinate. This sets the position of the fonts baseline, not the very bottom of the character.

`color`

  The index of the desired color for the text, see imagecolorexact().

`font_filename`

  The path to the TrueType font you wish to use.

  Depending on which version of the GD library PHP is using, when `font_filename` does not begin with a leading `/` then `.ttf` will be appended to the filename and the library will attempt to search for that filename along a library-defined font path.

  In many cases where a font resides in the same directory as the script using it the following trick will alleviate any include problems.

      <?php
      // Set the environment variable for GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Name the font to be used (note the lack of the .ttf extension)
      $font = 'SomeFont';
      ?>

`text`

  Text to be inserted into image.

`options`

  Possible array indexes for `options`
  Key | Type | Meaning
  --- | --- | ---
  `linespacing` | float | Defines drawing linespacing

### Rückgabewerte

This function returns an array defining the four points of the box, starting in the lower left and moving counter-clockwise:

0 | lower left x-coordinate
1 | lower left y-coordinate
2 | lower right x-coordinate
3 | lower right y-coordinate
4 | upper right x-coordinate
5 | upper right y-coordinate
6 | upper left x-coordinate
7 | upper left y-coordinate

On failure, `false` is returned.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagefttext() example

    <?php
    // Create a 300x100 image
    $im = imagecreatetruecolor(300, 100);
    $red = imagecolorallocate($im, 0xFF, 0x00, 0x00);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Make the background red
    imagefilledrectangle($im, 0, 0, 299, 99, $red);

    // Path to our ttf font file
    $font_file = './arial.ttf';

    // Draw the text 'PHP Manual' using font size 13
    imagefttext($im, 13, 0, 105, 55, $black, $font_file, 'PHP Manual');

    // Output image to the browser
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Anmerkungen

> Hinweis: Diese Funktion ist nur verfügbar wenn PHP mit Freetype unterstützung (--with-freetype-dir=DIR) kompiliert wurde

### Siehe auch

- imageftbbox() - Give the bounding box of a text using fonts via freetype2
- imagettftext() - Schreibt Text mit TrueType-Schriftarten ins Bild

# imagegammacorrect

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegammacorrect — Wendet eine Gamma-Korrektur auf ein GD-Bild an

### Beschreibung

function imagegammacorrect(GdImage `$image`, float `$input_gamma`, float `$output_gamma`): true

Wendet eine Gamma-Korrektur auf das angegebene `image` an, wobei Eingangs- und Ausgangsgamma angegeben werden.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`input_gamma`

  Das Eingangsgamma.

`output_gamma`

  Das Ausgangsgamma.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Die Verwendung von imagegammacorrect()

    <?php
    // Erzeuge ein Bild
    $im = imagecreatefromgif('php.gif');

    // Korrigiere Gamma, Ausgangsgamma = 1.537
    imagegammacorrect($im, 1.0, 1.537);

    // Speichere Bild
    imagegif($im, './php_gamma_corrected.gif');
    ?>

# imagegd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd — Output GD image to browser or file

### Beschreibung

function imagegd(GdImage `$image`, ?string `$file` = `null`): bool

Outputs or saves the given `image` in GD format.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`file`

  Der Pfad oder eine offene Stream-Ressource (die nach der Beendigung dieser Funktion automatisch geschlossen wird), in dem bzw. der die Datei gespeichert werden soll. Falls nicht gesetzt oder `null`, wird der rohe Bilddatenstrom direkt ausgegeben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.3 | `file` is now nullable.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
7.2.0 | imagegd() now allows to output truecolor images. Formerly, these have been implicitly converted to palette.

### Beispiele

Beispiel #1 Outputting a GD image

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Output the image
    imagegd($im);
    ?>

Beispiel #2 Saving a GD image

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Save the gd image
    // The file format for GD images is .gd, see http://www.libgd.org/GdFileFormats
    imagegd($im, 'simple.gd');
    ?>

### Anmerkungen

> Hinweis:

> The GD format is commonly used to allow fast loading of parts of images. Note that the GD format is only usable in GD-compatible applications.

Warnung

Die Bildformate GD und GD2 sind proprietäre Bildformate von libgd. Sie sind als veraltet anzusehen, und sollten nur zu Entwicklungs- und Testzwecken verwendet werden.

### Siehe auch

- imagegd2() - Output GD2 image to browser or file

# imagegd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd2 — Output GD2 image to browser or file

### Beschreibung

function imagegd2(
GdImage `$image`,
?string `$file` = `null`,
int `$chunk_size` = 128,
int `$mode` = `IMG_GD2_RAW`
): bool

Outputs or saves the given `image` in GD2 format.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`file`

  Der Pfad oder eine offene Stream-Ressource (die nach der Beendigung dieser Funktion automatisch geschlossen wird), in dem bzw. der die Datei gespeichert werden soll. Falls nicht gesetzt oder `null`, wird der rohe Bilddatenstrom direkt ausgegeben.

`chunk_size`

  Chunk size.

`mode`

  Either `IMG_GD2_RAW` or `IMG_GD2_COMPRESSED`. Default is `IMG_GD2_RAW`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.3 | `file` is now nullable.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Outputting a GD2 image

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Output the image
    imagegd2($im);
    ?>

Beispiel #2 Saving a GD2 image

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  "A Simple Text String", $text_color);

    // Save the gd2 image
    // The file format for GD2 images is .gd2, see http://www.libgd.org/GdFileFormats
    imagegd2($im, 'simple.gd2');
    ?>

### Anmerkungen

> Hinweis:

> The GD2 format is commonly used to allow fast loading of parts of images. Note that the GD2 format is only usable in GD2-compatible applications.

Warnung

Die Bildformate GD und GD2 sind proprietäre Bildformate von libgd. Sie sind als veraltet anzusehen, und sollten nur zu Entwicklungs- und Testzwecken verwendet werden.

### Siehe auch

- imagegd() - Output GD image to browser or file

# imagegetclip

(PHP 7 >= 7.2.0, PHP 8)

imagegetclip — Get the clipping rectangle

### Beschreibung

function imagegetclip(GdImage `$image`): array

imagegetclip() retrieves the current clipping rectangle, i.e. the area beyond which no pixels will be drawn.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

### Rückgabewerte

The function returns an indexed array with the coordinates of the clipping rectangle which has the following entries:

- x-coordinate of the upper left corner
- y-coordinate of the upper left corner
- x-coordinate of the lower right corner
- y-coordinate of the lower right corner

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagegetclip() example

Setting and retrieving the clipping rectangle.

    <?php
    $im = imagecreate(100, 100);
    imagesetclip($im, 10,10, 89,89);
    print_r(imagegetclip($im));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => 10
        [1] => 10
        [2] => 89
        [3] => 89
    )

### Siehe auch

- imagesetclip() - Set the clipping rectangle

# imagegetinterpolation

(PHP 8)

imagegetinterpolation — Get the interpolation method

### Beschreibung

function imagegetinterpolation(GdImage `$image`): int

Gets the currently set interpolation method of the `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

### Rückgabewerte

Returns the interpolation method.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Siehe auch

- imagesetinterpolation() - Set the interpolation method

# imagegif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegif — Gibt das Bild im Browser oder einer Datei aus.

### Beschreibung

function imagegif(GdImage `$image`, resource|string|null `$file` = `null`): bool

imagegif() erzeugt aus dem übergebenen `image` eine GIF-Datei in `file`. Der Inhalt des Parameters `image` ist der Rückgabewert der Funktionen imagecreate() oder `imagecreatefrom*`.

Das Bildformat ist GIF87a, es sei denn, das Bild wurde mittels imagecolortransparent() transparent gemacht. In diesem Fall ist das Bildformat GIF89a.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`file`

  Der Pfad oder eine offene Stream-Ressource (die nach der Beendigung dieser Funktion automatisch geschlossen wird), in dem bzw. der die Datei gespeichert werden soll. Falls nicht gesetzt oder `null`, wird der rohe Bilddatenstrom direkt ausgegeben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Ein Bild mittels imagegif() ausgeben

    <?php
    // Erzeugt ein neues Bild
    $im = imagecreatetruecolor(100, 100);

    // Den Hintergrund weiß machen
    imagefilledrectangle($im, 0, 0, 99, 99, 0xFFFFFF);

    // Einen Text im Bild ausgeben
    imagestring($im, 3, 40, 20, 'GD Library', 0xFFBA00);

    // Das Bild an den Browser ausgeben
    header('Content-Type: image/gif');

    imagegif($im);
    ?>

Beispiel #2 Eine PNG-Datei mit imagegif() in GIF konvertieren

    <?php

    // Die PNG-Datei laden
    $png = imagecreatefrompng('./php.png');

    // Die Datei im GIF-Format speichern
    imagegif($png, './php.gif');

    // Wir sind fertig
    echo 'Die PNG-Datei wurde erfolgreich nach GIF konvertiert!';
    ?>

### Anmerkungen

> Hinweis:

> Der folgende Codeauszug erlaubt es Ihnen, besser portierbare PHP-Anwendungen zu schreiben, indem die von GD unterstützten Bildformate automatisch erkannt werden. Ersetzen Sie den Abschnitt `header ("Content-Type: image/gif"); imagegif ($im);` durch diesen flexibleren Code:

>     <?php
>     // Ein neues Bild erzeugen
>     $im = imagecreatetruecolor(100, 100);

>     // Hier wird das Bild bearbeitet

>     // Ausgabebehandlung
>     if(function_exists('imagegif'))
>     {
>         // Für GIF
>         header('Content-Type: image/gif');

>         imagegif($im);
>     }
>     elseif(function_exists('imagejpeg'))
>     {
>         // Für JPEG
>         header('Content-Type: image/jpeg');

>         imagejpeg($im, NULL, 100);
>     }
>     elseif(function_exists('imagepng'))
>     {
>         // Für PNG
>         header('Content-Type: image/png');

>         imagepng($im);
>     }
>     elseif(function_exists('imagewbmp'))
>     {
>         // Für WBMP
>         header('Content-Type: image/vnd.wap.wbmp');

>         imagewbmp($im);
>     }
>     else
>     {
>         die('Auf diesem Server gibt es keine unterstützten Bildformate');
>     }
>     ?>

> Hinweis:

> Die Funktion imagetypes() kann verwendet werden, um die Unterstützung für verschiedene Bildformate zu überprüfen:

>     <?php
>     if(imagetypes() & IMG_GIF)
>     {
>         header('Content-Type: image/gif');
>         imagegif($im);
>     }
>     elseif(imagetypes() & IMG_JPG)
>     {
>         /* ... etc. */
>     }
>     ?>

### Siehe auch

- imagepng() - Ausgabe eines Bildes im Browser oder als Datei im PNG-Format
- imagewbmp() - Gibt das Bild im Browser oder einer Datei aus.
- imagejpeg() - Gibt das Bild im Browser oder einer Datei aus.
- imagetypes() - Liefert die von der verwendeten PHP-Version unterstützten Grafikformate

# imagegrabscreen

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabscreen — Captures the whole screen

### Beschreibung

function imagegrabscreen(): GdImage|false

Grabs a screenshot of the whole screen.

> Hinweis:

> This function is only available on Windows.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an image object on success, `false` on failure.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.

### Beispiele

Beispiel #1 imagegrabscreen() example

This example demonstrates how to take a screenshot of the current screen and save it as a png image.

    <?php
    $im = imagegrabscreen();
    imagepng($im, "myscreenshot.png");
    ?>

### Siehe auch

- imagegrabwindow() - Captures a window

# imagegrabwindow

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabwindow — Captures a window

### Beschreibung

function imagegrabwindow(int `$handle`, bool `$client_area` = `false`): GdImage|false

Grabs a window or its client area using a windows handle (HWND property in COM instance)

> Hinweis:

> This function is only available on Windows.

### Parameter-Liste

`handle`

  The HWND window ID.

`client_area`

  Include the client area of the application window.

### Rückgabewerte

Returns an image object on success, `false` on failure.

### Fehler/Exceptions

E_NOTICE is issued if `handle` is invalid window handle. E_WARNING is issued if the Windows API is too old.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.
8.0.0 | `client_area` expects a bool now; previously it expected an int.

### Beispiele

Beispiel #1 imagegrabwindow() example

Capture a window (IE for example)

    <?php
    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $im = imagegrabwindow($handle);
    $browser->Quit();
    imagepng($im, "iesnap.png");
    ?>

Capture a window (IE for example) but with its content

    <?php
    $browser = new COM("InternetExplorer.Application");
    $handle = $browser->HWND;
    $browser->Visible = true;
    $browser->Navigate("http://www.libgd.org");

    /* Still working? */
    while ($browser->Busy) {
        com_message_pump(4000);
    }
    $im = imagegrabwindow($handle, 0);
    $browser->Quit();
    imagepng($im, "iesnap.png");
    ?>

### Siehe auch

- imagegrabscreen() - Captures the whole screen

# imageinterlace

(PHP 4, PHP 5, PHP 7, PHP 8)

imageinterlace — Aktiviert oder Deaktiviert Interlacing

### Beschreibung

function imageinterlace(GdImage `$image`, ?bool `$enable` = `null`): bool

imageInterlace() schaltet das Interlace-Bit an oder aus.

Ist das Interlace-Bit gesetzt, und das Bild wird als JPEG-Bild verwendet, dann wird das Bild als progressives JPEG erzeugt.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`enable`

  Falls `true`, wird das Bild im Interlace-Verfahren erstellt, falls `false` wird das Interlace-Bit ausgeschaltet. Die Übergabe von `null` führt dazu, dass das Interlacing nicht geändert wird.

### Rückgabewerte

Gibt `true` zurück, wenn das Interlace-Bit des Bildes gesetzt ist, anderfalls `false`.

### Changelog

Version | Beschreibung
--- | ---
8.0.5 | imageinterlace() gibt nun einen bool-Wert zurück; vorher wurde ein int zurückgegeben (ungleich Null für interlaced Bilder, Null andernfalls)
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
8.0.0 | `enable` erwartet nun einen bool-Wert; vorher wurde ein int erwarten.

### Beispiele

Beispiel #1 Aktiviere Interlacing unter Verendung von imageinterlace()

    <?php
    // Erzeuge ein Bild
    $im = imagecreatefromgif('php.gif');

    // Aktiviere Interlacing
    imageinterlace($im, true);

    // Speichere das Bild interlaced
    imagegif($im, './php_interlaced.gif');
    ?>

# imageistruecolor

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageistruecolor — Finds whether an image is a truecolor image

### Beschreibung

function imageistruecolor(GdImage `$image`): bool

imageistruecolor() finds whether the image `image` is a truecolor image.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

### Rückgabewerte

Returns `true` if the `image` is truecolor, `false` otherwise.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Simple detection of true color image instances using imageistruecolor()

    <?php
    // $im is an image instance

    // Check if image is a true color image or not
    if(!imageistruecolor($im))
    {
        // Create a new true color image instance
        $tc = imagecreatetruecolor(imagesx($im), imagesy($im));

        // Copy over the pixels
        imagecopy($tc, $im, 0, 0, 0, 0, imagesx($im), imagesy($im));

        $im = $tc;
        $tc = NULL;

        // OR use imagepalettetotruecolor()
    }

    // Continue working with image instance
    ?>

### Siehe auch

- imagecreatetruecolor() - Create a new true color image
- imagepalettetotruecolor() - Converts a palette based image to true color

# imagejpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagejpeg — Gibt das Bild im Browser oder einer Datei aus.

### Beschreibung

function imagejpeg(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

imagejpeg() erzeugt eine JPEG-Datei aus dem übergebenen `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`file`

  Der Pfad oder eine offene Stream-Ressource (die nach der Beendigung dieser Funktion automatisch geschlossen wird), in dem bzw. der die Datei gespeichert werden soll. Falls nicht gesetzt oder `null`, wird der rohe Bilddatenstrom direkt ausgegeben.

`quality`

  `quality` ist optional und es kann ein Wert zwischen 0 (schlechteste Qualität, kleine Datei) und 100 (beste Qualität, größte Datei) übergeben werden. Der Standardwert (`-1`) verwendet den standardmäßigen IJG-Qualitätswert (ungefähr 75).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Fehler/Exceptions

Wenn `quality` ungültig ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Wirft nun einen ValueError, wenn `quality` ungültig ist.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Ein Bild an den Browser ausgeben

    <?php
    // Erzeut ein leeres Bild und fügt ein wenig Text hinzu
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Die Content-Type-Kopfzeile senden, in diesem Fall image/jpeg
    header('Content-Type: image/jpeg');

    // Das Bild ausgeben
    imagejpeg($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Beispiel #2 Ein Bild in eine Datei speichern

    <?php
    // Erzeugt ein leeres Bild und fügt ein wenig Text hinzu
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Das Bild als 'simpletext.jpg' speichern
    imagejpeg($im, 'simpletext.jpg');
    ?>

Beispiel #3 Das Bild mit 75% Qualität an den Browser ausgeben

    <?php
    // Erzeugt ein leeres Bild und fügt ein wenig Text hinzu
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Die Content-Type-Kopfzeile senden, in diesem Fall image/jpeg
    header('Content-Type: image/jpeg');

    // Der Dateiname wird übergangen, indem NULL verwendet wird
    // dann wird die Qualität auf 75% gesetzt
    imagejpeg($im, NULL, 75);
    ?>

### Anmerkungen

> Hinweis:

> Falls Progessive JPEGs ausgegeben werden sollen, so muss Interlacing mittels imageinterlace() eingeschaltet werden.

### Siehe auch

- imagepng() - Ausgabe eines Bildes im Browser oder als Datei im PNG-Format
- imagegif() - Gibt das Bild im Browser oder einer Datei aus.
- imagewbmp() - Gibt das Bild im Browser oder einer Datei aus.
- imageinterlace() - Aktiviert oder Deaktiviert Interlacing
- imagetypes() - Liefert die von der verwendeten PHP-Version unterstützten Grafikformate

# imagelayereffect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagelayereffect — Set the alpha blending flag to use layering effects

### Beschreibung

function imagelayereffect(GdImage `$image`, int `$effect`): true

Set the alpha blending flag to use layering effects.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`effect`

  One of the following constants:

  `IMG_EFFECT_REPLACE`
    Use pixel replacement (equivalent of passing `true` to imagealphablending())
  `IMG_EFFECT_ALPHABLEND`
    Use normal pixel blending (equivalent of passing `false` to imagealphablending())
  `IMG_EFFECT_NORMAL`
    Same as `IMG_EFFECT_ALPHABLEND`.
  `IMG_EFFECT_OVERLAY`
    Overlay has the effect that black background pixels will remain black, white background pixels will remain white, but grey background pixels will take the colour of the foreground pixel.
  `IMG_EFFECT_MULTIPLY`
    Overlays with a multiply effect.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
7.2.0 | Added `IMG_EFFECT_MULTIPLY` (requires system libgd >= 2.1.1 or the bundled libgd).

### Beispiele

Beispiel #1 imagelayereffect() example

    <?php
    // Setup an image
    $im = imagecreatetruecolor(100, 100);

    // Set a background
    imagefilledrectangle($im, 0, 0, 100, 100, imagecolorallocate($im, 220, 220, 220));

    // Apply the overlay alpha blending flag
    imagelayereffect($im, IMG_EFFECT_OVERLAY);

    // Draw two grey ellipses
    imagefilledellipse($im, 50, 50, 40, 40, imagecolorallocate($im, 100, 255, 100));
    imagefilledellipse($im, 50, 50, 50, 80, imagecolorallocate($im, 100, 100, 255));
    imagefilledellipse($im, 50, 50, 80, 50, imagecolorallocate($im, 255, 100, 100));

    // Output
    header('Content-type: image/png');

    imagepng($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imageline

(PHP 4, PHP 5, PHP 7, PHP 8)

imageline — Zeichnet eine Linie

### Beschreibung

function imageline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

Zeichnet eine Linie zwischen den beiden gegebenen Punkten.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`x1`

  x-Koordinate des ersten Punkts.

`y1`

  y-Koordinate des ersten Punkts.

`x2`

  x-Koordinate des zweiten Punkts.

`y2`

  y-Koordinate des zweiten Punkts.

`color`

  Die Linienfarbe. Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Zeichnen einer dicken Linie

    <?php

    function imagelinethick($image, $x1, $y1, $x2, $y2, $color, $thick = 1)
    {
        /* so funktioniert es nur bei orthogonale Linien gut
        imagesetthickness($image, $thick);
        return imageline($image, $x1, $y1, $x2, $y2, $color);
        */
        if ($thick == 1) {
            return imageline($image, $x1, $y1, $x2, $y2, $color);
        }
        $t = $thick / 2 - 0.5;
        if ($x1 == $x2 || $y1 == $y2) {
            return imagefilledrectangle($image, round(min($x1, $x2) - $t), round(min($y1, $y2) - $t), round(max($x1, $x2) + $t), round(max($y1, $y2) + $t), $color);
        }
        $k = ($y2 - $y1) / ($x2 - $x1); //y = kx + q
        $a = $t / sqrt(1 + pow($k, 2));
        $points = array(
            round($x1 - (1+$k)*$a), round($y1 + (1-$k)*$a),
            round($x1 - (1-$k)*$a), round($y1 - (1+$k)*$a),
            round($x2 + (1+$k)*$a), round($y2 - (1-$k)*$a),
            round($x2 + (1-$k)*$a), round($y2 + (1+$k)*$a),
        );
        imagefilledpolygon($image, $points, 4, $color);
        return imagepolygon($image, $points, 4, $color);
    }

    ?>

### Siehe auch

- imagecreatetruecolor() - Create a new true color image
- imagecolorallocate() - Alloziert eine Farbe für eine Grafik

# imageloadfont

(PHP 4, PHP 5, PHP 7, PHP 8)

imageloadfont — Lädt eine neue Schriftart

### Beschreibung

function imageloadfont(string `$filename`): GdFont|false

ImageLoadFont() lädt eine benutzerdefinierte Bitmap-Schriftart und gibt deren Kennung zurück.

### Parameter-Liste

`filename`

  Das Schriftart-Dateiformat ist zurzeit ein architekturabhängiges, binäres Format. Das bedeutet, dass Schriftart-Dateien immer auf derselben Architektur erzeugt werden müssen, auf dem diese verwendet werden sollen.

  Scrhiftart-Dateiformat
  Byte-Position | C Daten-Typ | Beschreibung
  --- | --- | ---
  Byte 0-3 | int | Anzahl der Zeichen der Schriftart
  Byte 4-7 | int | Wert des ersten Zeichens der Schriftart (meist 32 für Leerzeichen)
  Byte 8-11 | int | Pixel-Breite jedes Zeichens
  Byte 12-15 | int | Pixel-Höhe jedes Zeichens
  Byte 16- | char | Zeichen-Daten als Array, ein Byte je Pixel für jedes Zeichen; in der Summe also insgesamt (Anzahl Zeichen * Breite * Höhe) Byte.

### Rückgabewerte

Gibt eine GdFont-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt nun eine GdFont-Instanz zurück; vorher wurde ein Integer zurückgegeben.

### Beispiele

Beispiel #1 imageloadfont()-Beispiel

    <?php
    // Erzeuge ein neues Bild
    $im = imagecreatetruecolor(50, 20);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Färbe den Hintergrund weiß
    imagefilledrectangle($im, 0, 0, 49, 19, $white);

    // Lade die GD-Schriftart und schreibe 'Hallo'
    $font = imageloadfont('./04b.gdf');
    imagestring($im, $font, 0, 0, 'Hallo', $black);

    // Ausgabe an Browser
    header('Content-type: image/png');

    imagepng($im);
    ?>

### Siehe auch

- imagefontwidth() - Ermittelt die Breite einer Schriftart
- imagefontheight() - Ermittelt die Höhe einer Schriftart
- imagestring() - Zeichnet einen horizontalen String

# imageopenpolygon

(PHP 7 >= 7.2.0, PHP 8)

imageopenpolygon — Draws an open polygon

### Beschreibung

Signature as of PHP 8.0.0 (not supported with named arguments)

function imageopenpolygon(GdImage `$image`, array `$points`, int `$color`): bool

Alternative signature (deprecated as of PHP 8.1.0)

function imageopenpolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imageopenpolygon() draws an open polygon on the given `image`. Contrary to imagepolygon(), no line is drawn between the last and the first point.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`points`

  An array containing the polygon's vertices, e.g.:

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Total number of points (vertices), which must be at least 3.

  If this parameter is omitted as per the second signature, `points` must have an even number of elements, and `num_points` is assumed to be `count($points)/2`.
`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | The parameter `num_points` has been deprecated.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imageopenpolygon() example

    <?php
    // Create a blank image
    $image = imagecreatetruecolor(400, 300);

    // Allocate a color for the polygon
    $col_poly = imagecolorallocate($image, 255, 255, 255);

    // Draw the polygon
    imageopenpolygon($image, array(
            0,   0,
            100, 200,
            300, 200
        ),
        $col_poly);

    // Output the picture to the browser
    header('Content-type: image/png');

    imagepng($image);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagepolygon() - Zeichnet ein Polygon

# imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagepalettecopy — Copy the palette from one image to another

### Beschreibung

function imagepalettecopy(GdImage `$dst`, GdImage `$src`): void

imagepalettecopy() copies the palette from the `src` image to the `dst` image.

### Parameter-Liste

`dst`

  The destination image object.

`src`

  The source image object.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `dst` and `src` expect GdImage instances now; previously, resources were expected.

### Beispiele

Beispiel #1 imagepalettecopy() example

    <?php
    // Create two palette images
    $palette1 = imagecreate(100, 100);
    $palette2 = imagecreate(100, 100);

    // Allocate the background to be
    // green in the first palette image
    $green = imagecolorallocate($palette1, 0, 255, 0);

    // Copy the palette from image 1 to image 2
    imagepalettecopy($palette2, $palette1);

    // Since the palette is now copied we can use the
    // green color allocated to image 1 without using
    // imagecolorallocate() twice
    imagefilledrectangle($palette2, 0, 0, 99, 99, $green);

    // Output image to the browser
    header('Content-type: image/png');

    imagepng($palette2);
    ?>

# imagepalettetotruecolor

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagepalettetotruecolor — Converts a palette based image to true color

### Beschreibung

function imagepalettetotruecolor(GdImage `$image`): bool

Converts a palette based image, created by functions like imagecreate() to a true color image, like imagecreatetruecolor().

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

### Rückgabewerte

Returns `true` if the conversion was complete, or if the source image already is a true color image, otherwise `false` is returned.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Converts any image object to true color

    <?php
    // Backwards compatibility
    if(!function_exists('imagepalettetotruecolor'))
    {
        function imagepalettetotruecolor(&$src)
        {
            if(imageistruecolor($src))
            {
                return(true);
            }

            $dst = imagecreatetruecolor(imagesx($src), imagesy($src));

            imagecopy($dst, $src, 0, 0, 0, 0, imagesx($src), imagesy($src));

            $src = $dst;

            return(true);
        }
    }

    // Helper closure
    $typeof = function() use($im)
    {
        echo 'typeof($im) = ' . (imageistruecolor($im) ? 'true color' : 'palette'), PHP_EOL;
    };

    // Create a palette based image
    $im = imagecreate(100, 100);
    $typeof();

    // Convert it to true color
    imagepalettetotruecolor($im);
    $typeof();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    typeof($im) = palette
    typeof($im) = true color

### Siehe auch

- imagecreatetruecolor() - Create a new true color image
- imageistruecolor() - Finds whether an image is a truecolor image

# imagepng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepng — Ausgabe eines Bildes im Browser oder als Datei im PNG-Format

### Beschreibung

function imagepng(
GdImage `$image`,
resource|string|null `$file` = `null`,
int `$quality` = -1,
int `$filters` = -1
): bool

Erzeugt eine PNG-Datei aus dem übergebenen `image` oder gibt diese direkt aus.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`file`

  Der Pfad oder eine offene Stream-Ressource (die nach der Beendigung dieser Funktion automatisch geschlossen wird), in dem bzw. der die Datei gespeichert werden soll. Falls nicht gesetzt oder `null`, wird der rohe Bilddatenstrom direkt ausgegeben.

  > Hinweis:

  > `null` ist ungültig, wenn die Parameter `quality` und `filters` nicht übergeben werden.

`quality`

  Kompressionsstufe: Von 0 (keine Kompression) bis 9. Die Voreinstellung (`-1`) verwendet die voreingestellte zlib-Komprimierung. Weitere Informationen sind dem » zlib Handbuch zu entnehmen.

`filters`

  Erlaubt einer Verkleinerung der PNG-Dateigröße. Dies ist ein Bitfeld, welches beliebig aus den `PNG_FILTER_*`-Konstanten zusammengesetzt werden kann. `PNG_NO_FILTER` oder `PNG_ALL_FILTERS` können verwendet werden, um entweder alle Filter aus- oder einzuschalten. Der Vorgabewert (`-1`) deaktiviert die Filterung.

  Achtung

  Der Parameter `filters` wird von der System-libgd ignoriert.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Fehler/Exceptions

Wenn `quality` ungültig ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Wirft nun einen ValueError, wenn `quality` ungültig ist.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

    <?php
    $im = imagecreatefrompng("test.png");

    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Siehe auch

- imagegif() - Gibt das Bild im Browser oder einer Datei aus.
- imagewbmp() - Gibt das Bild im Browser oder einer Datei aus.
- imagejpeg() - Gibt das Bild im Browser oder einer Datei aus.
- imagetypes() - Liefert die von der verwendeten PHP-Version unterstützten Grafikformate
- imagesavealpha() - Ob beim Speichern von Bildern vollständige Alphakanal-Information erhalten wird

# imagepolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepolygon — Zeichnet ein Polygon

### Beschreibung

Signatur seit PHP 8.0.0 (keine Unterstützung für benannte Argumente)

function imagepolygon(GdImage `$image`, array `$points`, int `$color`): bool

Alternative Signatur (seit PHP 8.1.0 veraltet)

function imagepolygon(
GdImage `$image`,
array `$points`,
int `$num_points`,
int `$color`
): bool

imagepolygon() erzeugt ein Polygon im angegebenen `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`points`

  Ein Array, das die Eckpunkte des Polygons enthält, z. B.:

  points[0] | = x0
  points[1] | = y0
  points[2] | = x1
  points[3] | = y1

`num_points`

  Die Anzahl der Eckpunkte, die mindestens 3 sein muss.

  Wenn dieser Parameter gemäß der zweiten Signatur weggelassen wird, muss `points` eine gerade Anzahl von Elementen haben, und `num_points` wird angenommen als `count($punkte)/2`.
`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `num_points` ist veraltet und sollte nicht mehr verwendet werden.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagepolygon()-Beispiel

    <?php
    // Ein leeres Bild erstellen
    $bild = imagecreatetruecolor(400, 300);

    // Dem Polygon eine Farbe zuweisen
    $farbe_poly = imagecolorallocate($bild, 255, 255, 255);

    // Das Polygon zeichnen
    imagepolygon($bild, array(
            0,   0,
            100, 200,
            300, 200
        ),
        $farbe_poly);

    // Das Bild an den Browser ausgeben
    header('Content-type: image/png');

    imagepng($bild);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagefilledpolygon() - Zeichnet ein gefülltes Polygon
- imageopenpolygon() - Draws an open polygon
- imagecreate() - Erzeugt ein neues Palettenbild
- imagecreatetruecolor() - Create a new true color image

# imagerectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagerectangle — Zeichnet ein Rechteck

### Beschreibung

function imagerectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

imagerectangle() erzeugt ein Rechteck mit den angegebenen Koordinaten. 0,0 ist die obere linke Ecke des Bildes.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`x1`

  Obere linke x-Koordinate.

`y1`

  Obere linke y-Koordinate.

`x2`

  Untere rechte x-Koordinate.

`y2`

  Untere rechte y-Koordinate.

`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Einfaches imagerectangle()-Beispiel

    <?php
    // Erzeuge ein 200x200-Bild
    $canvas = imagecreatetruecolor(200, 200);

    // Alloziere Farben
    $pink = imagecolorallocate($canvas, 255, 105, 180);
    $white = imagecolorallocate($canvas, 255, 255, 255);
    $green = imagecolorallocate($canvas, 132, 135, 28);

    // Zeichne drei Rechtecke mit unterschiedlicher Farbe
    imagerectangle($canvas, 50, 50, 150, 150, $pink);
    imagerectangle($canvas, 45, 60, 120, 100, $white);
    imagerectangle($canvas, 100, 120, 75, 160, $green);

    // Ausgabe
    header('Content-Type: image/jpeg');
    imagejpeg($canvas);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imageresolution

(PHP 7 >= 7.2.0, PHP 8)

imageresolution — Get or set the resolution of the image

### Beschreibung

function imageresolution(GdImage `$image`, ?int `$resolution_x` = `null`, ?int `$resolution_y` = `null`): array|true

imageresolution() allows to set and get the resolution of an image in DPI (dots per inch). If the optional parameters are `null`, the current resolution is returned as an indexed array. If only `resolution_x` is not `null`, the horizontal and vertical resolution are set to this value. If none of the optional parameters are `null`, the horizontal and vertical resolution are set to these values, respectively.

The resolution is only used as meta information when images are read from and written to formats supporting this kind of information (currently PNG and JPEG). It does not affect any drawing operations. The default resolution for new images is 96 DPI.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`resolution_x`

  The horizontal resolution in DPI.

`resolution_y`

  The vertical resolution in DPI.

### Rückgabewerte

When used as getter, it returns an indexed array of the horizontal and vertical resolution on success. When used as setter, it always returns `true`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `resolution_x` and `resolution_y` are now nullable.

### Beispiele

Beispiel #1 Setting and getting the resolution of an image

    <?php
    $im = imagecreatetruecolor(100, 100);
    imageresolution($im, 200);
    print_r(imageresolution($im));
    imageresolution($im, 300, 72);
    print_r(imageresolution($im));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => 200
        [1] => 200
    )
    Array
    (
        [0] => 300
        [1] => 72
    )

# imagerotate

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagerotate — Rotate an image with a given angle

### Beschreibung

function imagerotate(GdImage `$image`, float `$angle`, int `$background_color`): GdImage|false

Rotates the `image` image using the given `angle` in degrees.

The center of rotation is the center of the image, and the rotated image may have different dimensions than the original image.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`angle`

  Rotation angle, in degrees. The rotation angle is interpreted as the number of degrees to rotate the image anticlockwise.

`background_color`

  Specifies the color of the uncovered zone after the rotation

### Rückgabewerte

Returns an image object for the rotated image, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.3.0 | The unused `ignore_transparent` has been completely removed.
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
8.0.0 | The unused `ignore_transparent` expects a bool now; previously it expected an int.

### Beispiele

Beispiel #1 Rotate an image 180 degrees

This example rotates an image 180 degrees - upside down.

    <?php
    // File and rotation
    $filename = 'test.jpg';
    $degrees = 180;

    // Content type
    header('Content-type: image/jpeg');

    // Load
    $source = imagecreatefromjpeg($filename);

    // Rotate
    $rotate = imagerotate($source, $degrees, 0);

    // Output
    imagejpeg($rotate);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Anmerkungen

> Hinweis:

> Diese Funktion wird von der mittels imagesetinterpolation() eingestellten Interpolationsmethode beeinflusst.

### Siehe auch

- imagesetinterpolation() - Set the interpolation method

# imagesavealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagesavealpha — Ob beim Speichern von Bildern vollständige Alphakanal-Information erhalten wird

### Beschreibung

function imagesavealpha(GdImage `$image`, bool `$enable`): true

imagesavealpha() setzt das Flag, das bestimmt, ob beim Speichern von Bildern vollständige Alphakanal-Information (im Gegensatz zu Einfarb-Transparenz) erhalten wird. Dies wird nur von Bildformaten mit vollständiger Alphakanal-Information unterstützt, d. h. `PNG`, `WebP` und `AVIF`.

> Hinweis: imagesavealpha() ist nur für `PNG`-Bilder sinnvoll, da bei `WebP` und `AVIF` immer der volle Alphakanal gespeichert wird. Es wird empfohlen, sich nicht auf dieses Verhalten zu verlassen, da es sich in Zukunft ändern kann. Daher sollte diese Funktion bei `WebP`- und `AVIF`-Bildern auch mit Bedacht aufgerufen werden.

Alphablending muss deaktiviert sein (`imagealphablending($im, false)`), um den Alphakanal überhaupt zu erhalten.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`enable`

  Ob der Alphakanal gespeichert werden soll, oder nicht. Die Voreinstellung ist `false`.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Grundlegende Verwendung imagesavealpha()-Verwendung

    <?php
    // Lade ein PNG-Bild mit Alphakanal
    $png = imagecreatefrompng('./alphachannel_example.png');

    // Deaktiviere das Alphablending
    imagealphablending($png, false);

    // Führe die gewünschten Operationen durch

    // Setze das Alphakanal-Flag
    imagesavealpha($png, true);

    // Gibt das Bild zum Browser aus
    header('Content-Type: image/png');

    imagepng($png);
    ?>

### Siehe auch

- imagealphablending() - Set the blending mode for an image

# imagescale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagescale — Scale an image using the given new width and height

### Beschreibung

function imagescale(
GdImage `$image`,
int `$width`,
int `$height` = -1,
int `$mode` = `IMG_BILINEAR_FIXED`
): GdImage|false

imagescale() scales an image using the given interpolation algorithm.

> Hinweis:

> Unlike many of other image functions, imagescale() does not modify the passed `image`; instead, a new image is returned.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`width`

  The width to scale the image to.

`height`

  The height to scale the image to. If omitted or negative, the aspect ratio will be preserved.

`mode`

  One of `IMG_NEAREST_NEIGHBOUR`, `IMG_BILINEAR_FIXED`, `IMG_BICUBIC`, `IMG_BICUBIC_FIXED` or anything else (will use two pass).

  > Hinweis: `IMG_WEIGHTED4` is not yet supported.

### Rückgabewerte

Return the scaled image object on successBei einem Fehler wird `false` zurückgegeben..

### Fehler/Exceptions

Throws a ValueError if `width` or `height` would cause over-/underflow.

Throws a ValueError if `mode` is invalid.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Now throws a ValueError if `width` or `height` would cause over-/underflow.
8.4.0 | Now throws a ValueError if `mode` is invalid.
8.0.0 | On success, this function returns a GDImage instance now; previously, a resource was returned.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Siehe auch

- imagecopyresized() - Kopieren und Ändern der Größe eines Bild-Teiles
- imagecopyresampled() - Copy and resize part of an image with resampling

# imagesetbrush

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetbrush — Set the brush image for line drawing

### Beschreibung

function imagesetbrush(GdImage `$image`, GdImage `$brush`): true

imagesetbrush() sets the brush image to be used by all line drawing functions (such as imageline() and imagepolygon()) when drawing with the special colors `IMG_COLOR_BRUSHED` or `IMG_COLOR_STYLEDBRUSHED`.

Achtung

You need not take special action when you are finished with a brush, but if you destroy the brush image (or let PHP destroy it), you must not use the `IMG_COLOR_BRUSHED` or `IMG_COLOR_STYLEDBRUSHED` colors until you have set a new brush image!

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`brush`

  An image object.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` and `brush` expect GdImage instances now; previously, resources were expected.

### Beispiele

Beispiel #1 imagesetbrush() example

    <?php

    // Load a mini php logo
    $php = imagecreatefrompng('./php.png');

    // Create the main image, 100x100
    $im = imagecreatetruecolor(100, 100);

    // Fill the background with white
    $white = imagecolorallocate($im, 255, 255, 255);
    imagefilledrectangle($im, 0, 0, 99, 99, $white);

    // Set the brush
    imagesetbrush($im, $php);

    // Draw a couple of brushes, each overlaying each
    imageline($im, 50, 50, 50, 60, IMG_COLOR_BRUSHED);

    // Output image to the browser
    header('Content-type: image/png');

    imagepng($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imagesetclip

(PHP 7 >= 7.2.0, PHP 8)

imagesetclip — Set the clipping rectangle

### Beschreibung

function imagesetclip(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`
): true

imagesetclip() sets the current clipping rectangle, i.e. the area beyond which no pixels will be drawn.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`x1`

  The x-coordinate of the upper left corner.

`y1`

  The y-coordinate of the upper left corner.

`x2`

  The x-coordinate of the lower right corner.

`y2`

  The y-coordinate of the lower right corner.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Siehe auch

- imagegetclip() - Get the clipping rectangle

# imagesetinterpolation

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagesetinterpolation — Set the interpolation method

### Beschreibung

function imagesetinterpolation(GdImage `$image`, int `$method` = `IMG_BILINEAR_FIXED`): bool

Sets the interpolation method, setting an interpolation method affects the rendering of various functions in GD, such as the imagerotate() function.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`method`

  The interpolation method, which can be one of the following:

  - `IMG_BELL`: Bell filter.
  - `IMG_BESSEL`: Bessel filter.
  - `IMG_BICUBIC`: Bicubic interpolation.
  - `IMG_BICUBIC_FIXED`: Fixed point implementation of the bicubic interpolation.
  - `IMG_BILINEAR_FIXED`: Fixed point implementation of the bilinear interpolation (`default (also on image creation)`).
  - `IMG_BLACKMAN`: Blackman window function.
  - `IMG_BOX`: Box blur filter.
  - `IMG_BSPLINE`: Spline interpolation.
  - `IMG_CATMULLROM`: Cubic Hermite spline interpolation.
  - `IMG_GAUSSIAN`: Gaussian function.
  - `IMG_GENERALIZED_CUBIC`: Generalized cubic spline fractal interpolation.
  - `IMG_HERMITE`: Hermite interpolation.
  - `IMG_HAMMING`: Hamming filter.
  - `IMG_HANNING`: Hanning filter.
  - `IMG_MITCHELL`: Mitchell filter.
  - `IMG_POWER`: Power interpolation.
  - `IMG_QUADRATIC`: Inverse quadratic interpolation.
  - `IMG_SINC`: Sinc function.
  - `IMG_NEAREST_NEIGHBOUR`: Nearest neighbour interpolation.
  - `IMG_WEIGHTED4`: Weighting filter.
  - `IMG_TRIANGLE`: Triangle interpolation.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagesetinterpolation() example

    <?php
    // Load an image
    $im = imagecreate(500, 500);

    // By default interpolation is IMG_BILINEAR_FIXED, switch
    // to use the 'Mitchell' filter:
    imagesetinterpolation($im, IMG_MITCHELL);

    // Continue to work with $im ...
    ?>

### Anmerkungen

Changing the interpolation method affects the following functions when rendering:

- imageaffine()
- imagerotate()

### Siehe auch

- imagegetinterpolation() - Get the interpolation method

# imagesetpixel

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesetpixel — Setzt ein einzelnes Pixel

### Beschreibung

function imagesetpixel(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

imagesetpixel() zeichnet ein Pixel an der angegebenen Koordinate.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`x`

  x-Koordinate

`y`

  y-Koordinate

`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagesetpixel()-Beispiel

Eine zufällige Zeichnung, die mit einem normalen Bild endet.

    <?php

    $x = 200;
    $y = 200;

    $gd = imagecreatetruecolor($x, $y);

    $corners[0] = array('x' => 100, 'y' =>  10);
    $corners[1] = array('x' =>   0, 'y' => 190);
    $corners[2] = array('x' => 200, 'y' => 190);

    $red = imagecolorallocate($gd, 255, 0, 0);

    for ($i = 0; $i < 100000; $i++) {
      imagesetpixel($gd, round($x), round($y), $red);
      $a = rand(0, 2);
      $x = ($x + $corners[$a]['x']) / 2;
      $y = ($y + $corners[$a]['y']) / 2;
    }

    header('Content-Type: image/png');
    imagepng($gd);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagecreatetruecolor() - Create a new true color image
- imagecolorallocate() - Alloziert eine Farbe für eine Grafik
- imagecolorat() - Liefert den Farbwert eines Bildpunktes

# imagesetstyle

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetstyle — Set the style for line drawing

### Beschreibung

function imagesetstyle(GdImage `$image`, array `$style`): bool

imagesetstyle() sets the style to be used by all line drawing functions (such as imageline() and imagepolygon()) when drawing with the special color `IMG_COLOR_STYLED` or lines of images with color `IMG_COLOR_STYLEDBRUSHED`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`style`

  An array of pixel colors. You can use the `IMG_COLOR_TRANSPARENT` constant to add a transparent pixel. Note that `style` must not be an empty array.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Following example script draws a dashed line from upper left to lower right corner of the canvas:

Beispiel #1 imagesetstyle() example

    <?php
    header("Content-type: image/jpeg");
    $im  = imagecreatetruecolor(100, 100);
    $w   = imagecolorallocate($im, 255, 255, 255);
    $red = imagecolorallocate($im, 255, 0, 0);

    /* Draw a dashed line, 5 red pixels, 5 white pixels */
    $style = array($red, $red, $red, $red, $red, $w, $w, $w, $w, $w);
    imagesetstyle($im, $style);
    imageline($im, 0, 0, 100, 100, IMG_COLOR_STYLED);

    /* Draw a line of happy faces using imagesetbrush() with imagesetstyle */
    $style = array($w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $red);
    imagesetstyle($im, $style);

    $brush = imagecreatefrompng("http://www.libpng.org/pub/png/images/smile.happy.png");
    $w2 = imagecolorallocate($brush, 255, 255, 255);
    imagecolortransparent($brush, $w2);
    imagesetbrush($im, $brush);
    imageline($im, 100, 0, 0, 100, IMG_COLOR_STYLEDBRUSHED);

    imagejpeg($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagesetbrush() - Set the brush image for line drawing
- imageline() - Zeichnet eine Linie

# imagesetthickness

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetthickness — Set the thickness for line drawing

### Beschreibung

function imagesetthickness(GdImage `$image`, int `$thickness`): true

imagesetthickness() sets the thickness of the lines drawn when drawing rectangles, polygons, arcs etc. to `thickness` pixels.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`thickness`

  Thickness, in pixels.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagesetthickness() example

    <?php

    // Create a 200x100 image
    $im = imagecreatetruecolor(200, 100);
    $white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    $black = imagecolorallocate($im, 0x00, 0x00, 0x00);

    // Set the background to be white
    imagefilledrectangle($im, 0, 0, 199, 99, $white);

    // Set the line thickness to 5
    imagesetthickness($im, 5);

    // Draw the rectangle
    imagerectangle($im, 14, 14, 185, 85, $black);

    // Output image to the browser
    header('Content-Type: image/png');

    imagepng($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imagesettile

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesettile — Set the tile image for filling

### Beschreibung

function imagesettile(GdImage `$image`, GdImage `$tile`): true

imagesettile() sets the tile image to be used by all region filling functions (such as imagefill() and imagefilledpolygon()) when filling with the special color `IMG_COLOR_TILED`.

A tile is an image used to fill an area with a repeated pattern. Any GD image can be used as a tile, and by setting the transparent color index of the tile image with imagecolortransparent(), a tile allows certain parts of the underlying area to shine through can be created.

Achtung

You need not take special action when you are finished with a tile, but if you destroy the tile image (or let PHP destroy it), you must not use the `IMG_COLOR_TILED` color until you have set a new tile image!

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`tile`

  The image object to be used as a tile.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` and `tile` expect GdImage instances now; previously, resources were expected.

### Beispiele

Beispiel #1 imagesettile() example

    <?php
    // Load an external image
    $zend = imagecreatefromgif('./zend.gif');

    // Create a 200x200 image
    $im = imagecreatetruecolor(200, 200);

    // Set the tile
    imagesettile($im, $zend);

    // Make the image repeat
    imagefilledrectangle($im, 0, 0, 199, 199, IMG_COLOR_TILED);

    // Output image to the browser
    header('Content-Type: image/png');

    imagepng($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# imagestring

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestring — Zeichnet einen horizontalen String

### Beschreibung

function imagestring(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Zeichnet einen `string` an den angegebenen Koordinaten.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`font`

  Kann bei eingebauten Schriftarten in Latin2-Kodierung 1, 2, 3, 4 oder 5 sein (wobei größere Zahlen größeren Schriftarten entsprechen) oder eine GdFont-Instanz, die von imageloadfont() zurückgegeben wurde.

`x`

  Die x-Koordinate der oberen linke Ecke.

`y`

  Die y-Koordinate der oberen linken Ecke.

`string`

  Die zu schreibende Zeichenkette.

`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `font` akzeptiert jetzt sowohl eine GdFont-Instanz als auch ein Integer; vorher wurde nur Integer akzeptiert.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagestring()-Beispiel

    <?php
    // Erzeuge ein 100*30 Bild
    $im = imagecreate(100, 30);

    // Weißer Hintergrund und blauer Text
    $bg = imagecolorallocate($im, 255, 255, 255);
    $textfarbe = imagecolorallocate($im, 0, 0, 255);

    // Schreibe die Zeichenkette oben links
    imagestring($im, 5, 0, 0, 'Hello world!', $textfarbe);

    // Gib das Bild aus
    header('Content-type: image/png');

    imagepng($im);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagestringup() - Zeichnet einen vertikalen String
- imageloadfont() - Lädt eine neue Schriftart
- imagettftext() - Schreibt Text mit TrueType-Schriftarten ins Bild

# imagestringup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestringup — Zeichnet einen vertikalen String

### Beschreibung

function imagestringup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

Zeichnet einen `string` vertikal an den angegebenen Koordinaten.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`font`

  Kann bei eingebauten Schriftarten in Latin2-Kodierung 1, 2, 3, 4 oder 5 sein (wobei größere Zahlen größeren Schriftarten entsprechen) oder eine GdFont-Instanz, die von imageloadfont() zurückgegeben wurde.

`x`

  Die x-Koordinate der unteren linken Ecke.

`y`

  Die y-Koordinate der unteren linken Ecke.

`string`

  Die zu schreibende Zeichenkette.

`color`

  Eine Farbkennung, die mit imagecolorallocate() erzeugt wurde.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `font` akzeptiert jetzt sowohl eine GdFont-Instanz als auch ein Integer; vorher wurde nur Integer akzeptiert.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 imagestringup()-Beispiel

    <?php
    // Erzeuge ein 100*100 Bild
    $im = imagecreatetruecolor(100, 100);

    // Schreibe den Text
    $textfarbe = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
    imagestringup($im, 3, 40, 80, 'gd library', $textfarbe);

    // Speichere das Bild
    imagepng($im, './stringup.png');
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- imagestring() - Zeichnet einen horizontalen String
- imageloadfont() - Lädt eine neue Schriftart

# imagesx

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesx — Ermittelt die Breite eines Bildes

### Beschreibung

function imagesx(GdImage `$image`): int

Gibt die Breite des angegebenen `image`-Objekts zurück.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

### Rückgabewerte

Gibt die Breite des Bildes `image` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Verwenden von imagesx()

    <?php

    // Erzeuge ein 300*200-Bild
    $img = imagecreatetruecolor(300, 200);

    echo imagesx($img); // 300

    ?>

### Siehe auch

- imagecreatetruecolor() - Create a new true color image
- getimagesize() - Liefert die Größe einer Grafik
- imagesy() - Ermittelt die Höhe eines Bildes

# imagesy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesy — Ermittelt die Höhe eines Bildes

### Beschreibung

function imagesy(GdImage `$image`): int

Gibt die Höhe des angegebenen `image`-Objekts zurück.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

### Rückgabewerte

Gibt die Höhe des Bildes `image` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Verwenden von imagesy()

    <?php

    // Erzeuge ein 300*200-Bild
    $img = imagecreatetruecolor(300, 200);

    echo imagesy($img); // 200

    ?>

### Siehe auch

- imagecreatetruecolor() - Create a new true color image
- getimagesize() - Liefert die Größe einer Grafik
- imagesx() - Ermittelt die Breite eines Bildes

# imagetruecolortopalette

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagetruecolortopalette — Convert a true color image to a palette image

### Beschreibung

function imagetruecolortopalette(GdImage `$image`, bool `$dither`, int `$num_colors`): bool

imagetruecolortopalette() converts a truecolor image to a palette image. The code for this function was originally drawn from the Independent JPEG Group library code, which is excellent. The code has been modified to preserve as much alpha channel information as possible in the resulting palette, in addition to preserving colors as well as possible. This does not work as well as might be hoped. It is usually best to simply produce a truecolor output image instead, which guarantees the highest output quality.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`dither`

  Indicates if the image should be dithered - if it is `true` then dithering will be used which will result in a more speckled image but with better color approximation.

`num_colors`

  Sets the maximum number of colors that should be retained in the palette.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Converting a true color image to a palette-based image

    <?php
    // Create a new true color image
    $im = imagecreatetruecolor(100, 100);

    // Convert to palette-based with no dithering and 255 colors
    imagetruecolortopalette($im, false, 255);

    // Save the image
    imagepng($im, './paletteimage.png');
    ?>

# imagettfbbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettfbbox — Ermittelt das umgebende Rechteck eines Textes, der eine TrueType-Schriftart verwendet

### Beschreibung

function imagettfbbox(
float `$size`,
float `$angle`,
string `$font_filename`,
string `$string`,
array `$options` = []
): array|false

Diese Funktion berechnet den Begrenzungsrahmen (Bounding Box) eines TrueType-Textes in Pixeln und gibt ihn zurück.

> Hinweis:

> Vor PHP 8.0.0 war imageftbbox() eine erweiterte Variante von imagettfbbox(), die zusätzlich den Parameter `extrainfo` unterstützte. Ab PHP 8.0.0 ist imagettfbbox() ein Alias von imageftbbox().

### Parameter-Liste

`size`

  Die Schriftgröße in Punkten.

`angle`

  Der Winkel in Grad, in dem `string` vermessen wird.

`fontfile`

  Der Pfad zu der TrueType-Schriftart, die verwendet werden soll.

  Der Pfad zu der TrueType-Schriftart, die verwendet werden soll. Abhängig davon, welche Version der GD-Bibliothek PHP verwendet, wird, wenn `fontfile` nicht mit einem vorangestellten `/` beginnt, `.ttf` an den Dateinamen angehängt und die Bibliothek versucht, diesen Dateinamen entlang eines von der Bibliothek definierten Schriftarten-Pfades zu suchen.

  Bei der Verwendung von Versionen der GD-Bibliothek, die älter als 2.0.18 sind, wurde ein `space`-Zeichen, anstelle eines Semikolons als Pfad-Trennzeichen für verschiedene Schriftdateien verwendet. Die unbeabsichtigte Verwendung dieser Eigenschaft führt zu einer Warnmeldung: `Warnung: Schriftart konnte nicht gefunden/geöffnet werden`. Für diese betroffenen Versionen besteht die einzige Lösung darin, die Schriftart in einen Pfad zu verschieben, der keine Leerzeichen enthält.

  In vielen Fällen, in denen sich eine Schriftart im selben Verzeichnis befindet wie das Skript, das sie verwendet, kann der folgende Trick die Probleme beim Einbinden lösen.

      <?php
      // Setzten der Umgebungsvariablen für GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Benennen der zu verwendenden Schriftart
      // (zu beachten ist das Fehlen der Erweiterung .ttf)
      $font = 'IrgendeineSchriftart';
      ?>

  > Hinweis:

  > Zu beachten ist, dass open_basedir nicht für `fontfile` gilt.

`string`

  Die zu vermessende Zeichenkette.

`options`

  Wie bei imagettftext().

### Rückgabewerte

imagettfbbox() gibt im Erfolgsfall ein Array mit 8 Elementen zurück, die die vier Punkte des umgebenden Rechtecks des Texts repräsentieren, und `false` im Fehlerfall.

Schlüssel | Wert
--- | ---
0 | untere linke Ecke, x-Koordinate
1 | untere linke Ecke, y-Koordinate
2 | untere rechte Ecke, x-Koordinate
3 | untere rechte Ecke, y-Koordinate
4 | obere rechte Ecke, x-Koordinate
5 | obere rechte Ecke, y-Koordinate
6 | obere linke Ecke, x-Koordinate
7 | obere linke Ecke, y-Koordinate

Die Punkte sind relativ zum Text, unabhängig von `angle`, sodass "obere linke Ecke" bedeutet "in der oberen linken Ecke, wenn der Text horizontal gesehen wird".

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Die `options` wurden hinzugefügt.

### Beispiele

Beispiel #1 imagettfbbox()-Beispiel

    <?php
    // Erzeuge ein 300x150-Bild
    $im = imagecreatetruecolor(300, 150);
    $black = imagecolorallocate($im, 0, 0, 0);
    $white = imagecolorallocate($im, 255, 255, 255);

    // Weißer Hintergrund
    imagefilledrectangle($im, 0, 0, 299, 299, $white);

    // Pfad der Schriftartdatei
    $font = './arial.ttf';

    // Zunächst ermitteln wir das umgebende Rechteck für den ersten Text
    $bbox = imagettfbbox(10, 45, $font, 'Powered by PHP ' . phpversion());

    // Dies sind die x- und y-Koordinaten
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) - 25;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Schreibe
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'Powered by PHP ' . phpversion());

    // Ermittle das umgebende Rechteck für den zweiten Text
    $bbox = imagettfbbox(10, 45, $font, 'and Zend Engine ' . zend_version());

    // Berechne die Koordinaten, sodass es neben dem ersten Text ist
    $x = $bbox[0] + (imagesx($im) / 2) - ($bbox[4] / 2) + 10;
    $y = $bbox[1] + (imagesy($im) / 2) - ($bbox[5] / 2) - 5;

    // Schreibe
    imagettftext($im, 10, 45, $x, $y, $black, $font, 'and Zend Engine ' . zend_version());

    // Ausgabe an den Browser
    header('Content-Type: image/png');

    imagepng($im);
    ?>

### Anmerkungen

> Hinweis: Diese Funktion ist nur verfügbar wenn PHP mit Freetype unterstützung (--with-freetype-dir=DIR) kompiliert wurde

### Siehe auch

- imagettftext() - Schreibt Text mit TrueType-Schriftarten ins Bild
- imageftbbox() - Give the bounding box of a text using fonts via freetype2

# imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext — Schreibt Text mit TrueType-Schriftarten ins Bild

### Beschreibung

function imagettftext(
GdImage `$image`,
float `$size`,
float `$angle`,
int `$x`,
int `$y`,
int `$color`,
string `$font_filename`,
string `$text`,
array `$options` = []
): array|false

Schreibt den angegebenen `text` ins Bild unter Verwendung von True-Type-Schriftarten.

> Hinweis:

> Vor PHP 8.0.0 war imagefttext() eine erweiterte Variante von imagettftext(), die zusätzlich den Parameter `extrainfo` unterstützte. Ab PHP 8.0.0 ist imagettftext() ein Alias von imagefttext().

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`size`

  Die Schriftgröße in Punkten.

`angle`

  Der Winkel in Grad, wobei 0 Grad einen von links nach rechts zu lesenden Text ergibt. Höhere Werte bewirken eine Drehung gegen den Uhrzeigersinn. Ein Wert von 90 ergibt zum Beispiel einen von unten nach oben zu lesendem Text.

`x`

  Die per `x` und `y` angegebenen Koordinaten definieren den Startpunkt des ersten Zeichens (in etwa die linke untere Ecke). Das ist anders als bei der Funktion imagestring(), bei der `x` und `y` die obere rechte Ecke des ersten Zeichens darstellen. Zum Beispiel ist oben links 0, 0.

`y`

  Die y-Koordinate. Diese legt die Position der Grundlinie der Schriftart fest, nicht den untersten Rand des Zeichens.

`color`

  Der Farbindex. Die Verwendung des negativen Indexwerts schaltet das Antialiasing ab. Siehe imagecolorallocate().

`fontfile`

  Der Pfad zu der TrueType-Schriftart, die verwendet werden soll.

  Der Pfad zu der TrueType-Schriftart, die verwendet werden soll. Abhängig davon, welche Version der GD-Bibliothek PHP verwendet, wird, wenn `fontfile` nicht mit einem vorangestellten `/` beginnt, `.ttf` an den Dateinamen angehängt und die Bibliothek versucht, diesen Dateinamen entlang eines von der Bibliothek definierten Schriftarten-Pfades zu suchen.

  Bei der Verwendung von Versionen der GD-Bibliothek, die älter als 2.0.18 sind, wurde ein `space`-Zeichen, anstelle eines Semikolons als Pfad-Trennzeichen für verschiedene Schriftdateien verwendet. Die unbeabsichtigte Verwendung dieser Eigenschaft führt zu einer Warnmeldung: `Warnung: Schriftart konnte nicht gefunden/geöffnet werden`. Für diese betroffenen Versionen besteht die einzige Lösung darin, die Schriftart in einen Pfad zu verschieben, der keine Leerzeichen enthält.

  In vielen Fällen, in denen sich eine Schriftart im selben Verzeichnis befindet wie das Skript, das sie verwendet, kann der folgende Trick die Probleme beim Einbinden lösen.

      <?php
      // Setzten der Umgebungsvariablen für GD
      putenv('GDFONTPATH=' . realpath('.'));

      // Benennen der zu verwendenden Schriftart
      // (zu beachten ist das Fehlen der Erweiterung .ttf)
      $font = 'IrgendeineSchriftart';
      ?>

  > Hinweis:

  > Zu beachten ist, dass open_basedir nicht für `fontfile` gilt.

`text`

  Die UTF8-kodierte Text-Zeichenkette.

  Kann dezimale numerische Zeichen-Entity-Referenzen (in der Form `&#8364;`) enthalten, um Zeichen außerhalb des ASCII-Bereichs zu referenzieren. Das hexadizimale Format (wie `&#xA9;`) wird ebenfalls unterstützt. UTF-8-kodierte Zeichenketten können direkt übergeben werden.

  Benannte Zeichen-Entity-Referenzen wie `&copy;` werden nicht unterstützt. um diese Zeichen-Entity-Referenzen nach UTF-8 zu konvertieren, kann html_entity_decode() verwendet werden.

  Wenn ein Zeichen in der Zeichenkette verwendet wird, das von der Schriftart nicht untersützt wird, wird es durch ein hohles Rechteck ersetzt.

`options`

  Ein Array mit dem Schlüssel `linespacing`, der einen float-Wert enthält.

### Rückgabewerte

Gibt ein Array mit 8 Elementen zurück, die die vier Punkte des umgebenden Rechtecks des Textes repräsentieren. Die Reihenfolge der Punkte ist unten links, unten rechts, oben rechts und oben links. Die Punkte sind relativ zum Text, unabhängig vom Winkel, sodass "obere linke Ecke" bedeutet "in der oberen linken Ecke, wenn der Text horizontal gesehen wird". Im Fehlerfall wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Die `options` wurden hinzugefügt.

### Beispiele

Beispiel #1 imagettftext()-Beispiel

Dieses Beispielskript erzeugt ein weißes 400x30 Pixel großes PNG mit dem Text "Testing..." in schwarz (mit grauem Schatten) in der Schriftart Arial.

    <?php

    // Setze den Content-Type
    header('Content-Type: image/png');

    // Erzeuge das Bild
    $im = imagecreatetruecolor(400, 30);

    // Erzeuge einige Farben
    $white = imagecolorallocate($im, 255, 255, 255);
    $grey = imagecolorallocate($im, 128, 128, 128);
    $black = imagecolorallocate($im, 0, 0, 0);
    imagefilledrectangle($im, 0, 0, 399, 29, $white);

    // Der zu zeichnende Text
    $text = 'Testing...';

    // Bei Bedarf ist der Pfad anzupassen
    $font = 'arial.ttf';

    // Füge etwas Schatten zum Text hinzu
    imagettftext($im, 20, 0, 11, 21, $grey, $font, $text);

    // Füge den Text hinzu
    imagettftext($im, 20, 0, 10, 20, $black, $font, $text);

    // Die Verwendung von imagepng() ergibt eine bessere Textqualität als imagejpeg()
    imagepng($im);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Anmerkungen

> Hinweis: Diese Funktion ist nur verfügbar wenn PHP mit Freetype unterstützung (--with-freetype-dir=DIR) kompiliert wurde

### Siehe auch

- imagettfbbox() - Ermittelt das umgebende Rechteck eines Textes, der eine TrueType-Schriftart verwendet
- imagefttext() - Write text to the image using fonts using FreeType 2
- imagestring() - Zeichnet einen horizontalen String

# imagetypes

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

imagetypes — Liefert die von der verwendeten PHP-Version unterstützten Grafikformate

### Beschreibung

function imagetypes(): int

Gibt die Grafikformate zurück, die von der aktuell verwendeten PHP-Installation unterstützt werden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Bitfeld zurück, das den von der verlinkten GD-Version unterstützten Grafikformaten entspricht. Die folgenden Bits werden zurückgegeben: `IMG_AVIF` | `IMG_BMP` | `IMG_GIF` | `IMG_JPG` | `IMG_PNG` | `IMG_WBMP` | `IMG_XPM` | `IMG_WEBP`.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | `IMG_AVIF` wurde hinzugefügt.
7.2.0 | `IMG_BMP` wurde hinzugefügt.
7.0.10 | `IMG_WEBP` wurde hinzugefügt.

### Beispiele

Beispiel #1 Prüfe PNG-Unterstützung

    <?php
    if (imagetypes() & IMG_PNG) {
        echo "PNG wird unterstützt";
    }
    ?>

### Siehe auch

- gd_info() - Liefert Informationen über die aktuell verwendete GD-Bibliothek

# imagewbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagewbmp — Gibt das Bild im Browser oder einer Datei aus.

### Beschreibung

function imagewbmp(GdImage `$image`, resource|string|null `$file` = `null`, ?int `$foreground_color` = `null`): bool

imagewbmp() outputs or save a WBMP version of the given `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`file`

  Der Pfad oder eine offene Stream-Ressource (die nach der Beendigung dieser Funktion automatisch geschlossen wird), in dem bzw. der die Datei gespeichert werden soll. Falls nicht gesetzt oder `null`, wird der rohe Bilddatenstrom direkt ausgegeben.

`foreground_color`

  You can set the foreground color with this parameter by setting an identifier obtained from imagecolorallocate(). The default foreground color is black.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
8.0.0 | `foreground_color` is nullable now.

### Beispiele

Beispiel #1 Outputting a WBMP image

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Set the content type header - in this case image/vnd.wap.wbmp
    // Hint: see image_type_to_mime_type() for content-types
    header('Content-Type: image/vnd.wap.wbmp');

    // Output the image
    imagewbmp($im);
    ?>

Beispiel #2 Saving the WBMP image

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Save the image
    imagewbmp($im, 'simpletext.wbmp');
    ?>

Beispiel #3 Outputting the image with a different foreground

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Set the content type header - in this case image/vnd.wap.wbmp
    // Hint: see image_type_to_mime_type() for content-types
    header('Content-Type: image/vnd.wap.wbmp');

    // Set a replacement foreground color
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    imagewbmp($im, NULL, $foreground_color);
    ?>

### Siehe auch

- image2wbmp() - Gibt das Bild im Browser oder einer Datei aus.
- imagepng() - Ausgabe eines Bildes im Browser oder als Datei im PNG-Format
- imagegif() - Gibt das Bild im Browser oder einer Datei aus.
- imagejpeg() - Gibt das Bild im Browser oder einer Datei aus.
- imagetypes() - Liefert die von der verwendeten PHP-Version unterstützten Grafikformate

# imagewebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagewebp — Output a WebP image to browser or file

### Beschreibung

function imagewebp(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

Outputs or saves a WebP version of the given `image`.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`file`

  Der Pfad oder eine offene Stream-Ressource (die nach der Beendigung dieser Funktion automatisch geschlossen wird), in dem bzw. der die Datei gespeichert werden soll. Falls nicht gesetzt oder `null`, wird der rohe Bilddatenstrom direkt ausgegeben.

`quality`

  `quality` ranges from 0 (worst quality, smaller file) to 100 (best quality, biggest file). If `-1` is provided, the default value `80` is used.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Fehler/Exceptions

Throws a ValueError if `quality` is invalid.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Now throws a ValueError if `quality` is invalid.
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.

### Beispiele

Beispiel #1 Saving an WebP file

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);

    imagestring($im, 1, 5, 5,  'WebP with PHP', $text_color);

    // Save the image
    imagewebp($im, 'php.webp');
    ?>

# imagexbm

(PHP 5, PHP 7, PHP 8)

imagexbm — Output an XBM image to browser or file

### Beschreibung

function imagexbm(GdImage `$image`, ?string `$filename`, ?int `$foreground_color` = `null`): bool

Outputs or save an XBM version of the given `image`.

> Hinweis: imagexbm() doesn't apply any padding, so the image width has to be a multiple of 8. This restriction does no longer apply as of PHP 7.0.9.

### Parameter-Liste

`image`

  Ein GdImage-Objekt, das von einer der Funktionen zur Bilderzeugung, z. B. imagecreatetruecolor(), zurückgegeben wurde.

`filename`

  The path to save the file to, given as String. If `null`, the raw image stream will be output directly.

  The `filename` (without the .xbm extension) is also used for the C identifiers of the XBM, whereby non alphanumeric characters of the current locale are substituted by underscores. If `filename` is set to `null`, `image` is used to build the C identifiers.

`foreground_color`

  You can set the foreground color with this parameter by setting an identifier obtained from imagecolorallocate(). The default foreground color is black. All other colors are treated as background.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `image` erwartet nun eine GdImage-Instanz; vorher wurde eine gültige `gd`-Ressource erwartet.
8.0.0 | `foreground_color` is now nullable.
8.0.0 | The fourth parameter, which was unused, has been removed.

### Beispiele

Beispiel #1 Saving an XBM file

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Save the image
    imagexbm($im, 'simpletext.xbm');
    ?>

Beispiel #2 Saving an XBM file with a different foreground color

    <?php
    // Create a blank image and add some text
    $im = imagecreatetruecolor(120, 20);
    $text_color = imagecolorallocate($im, 233, 14, 91);
    imagestring($im, 1, 5, 5,  'A Simple Text String', $text_color);

    // Set a replacement foreground color
    $foreground_color = imagecolorallocate($im, 255, 0, 0);

    // Save the image
    imagexbm($im, NULL, $foreground_color);
    ?>

# iptcembed

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcembed — Embeds binary IPTC data into a JPEG image

### Beschreibung

function iptcembed(string `$iptc_data`, string `$filename`, int `$spool` = 0): string|bool

Embeds binary IPTC data into a JPEG image.

### Parameter-Liste

`iptc_data`

  The data to be written.

`filename`

  Path to the JPEG image.

`spool`

  Spool flag. If the spool flag is less than 2 then the JPEG will be returned as a string. Otherwise the JPEG will be printed to STDOUT.

### Rückgabewerte

If `spool` is less than 2, the JPEG will be returned, Bei einem Fehler wird `false` zurückgegeben.. Otherwise returns `true` on success Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Embedding IPTC data into a JPEG

    <?php

    // iptc_make_tag() function by Thies C. Arntzen
    function iptc_make_tag($rec, $data, $value)
    {
        $length = strlen($value);
        $retval = chr(0x1C) . chr($rec) . chr($data);

        if($length < 0x8000)
        {
            $retval .= chr($length >> 8) .  chr($length & 0xFF);
        }
        else
        {
            $retval .= chr(0x80) .
                       chr(0x04) .
                       chr(($length >> 24) & 0xFF) .
                       chr(($length >> 16) & 0xFF) .
                       chr(($length >> 8) & 0xFF) .
                       chr($length & 0xFF);
        }

        return $retval . $value;
    }

    // Path to jpeg file
    $path = './phplogo.jpg';

    // Set the IPTC tags
    $iptc = array(
        '2#120' => 'Test image',
        '2#116' => 'Copyright 2008-2009, The PHP Group'
    );

    // Convert the IPTC tags into binary code
    $data = '';

    foreach($iptc as $tag => $string)
    {
        $tag = substr($tag, 2);
        $data .= iptc_make_tag(2, $tag, $string);
    }

    // Embed the IPTC data
    $content = iptcembed($data, $path);

    // Write the new image data out to the file.
    $fp = fopen($path, "wb");
    fwrite($fp, $content);
    fclose($fp);
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion benötigt die GD-Bibliothek nicht.

# iptcparse

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcparse — Parse a binary IPTC block into single tags

### Beschreibung

function iptcparse(string `$iptc_block`): array|false

Parses an » IPTC block into its single tags.

### Parameter-Liste

`iptc_block`

  A binary IPTC block.

### Rückgabewerte

Returns an array using the tagmarker as an index and the value as the value. It returns `false` on error or if no IPTC data was found.

### Beispiele

Beispiel #1 iptcparse() used together with getimagesize()

    <?php
    $size = getimagesize('./test.jpg', $info);
    if(isset($info['APP13']))
    {
        $iptc = iptcparse($info['APP13']);
        var_dump($iptc);
    }
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion benötigt die GD-Bibliothek nicht.

# jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

jpeg2wbmp — Konvertiert eine JPEG-Bilddatei in eine WBMP-Bilddatei

Warnung

Diese Funktion ist seit PHP 7.2.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function jpeg2wbmp(
string `$jpegname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Konvertiert eine JPEG-Datei in eine WBMP-Datei.

### Parameter-Liste

`jpegname`

  Pfad zur JPEG-Datei.

`wbmpname`

  Pfad zur WBMP-Datei.

`dest_height`

  Höhe des Zielbildes.

`dest_width`

  Breite des Zielbildes.

`threshold`

  Schwellenwert, zwischen 0 und 8 (inklusive).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Beispiele

Beispiel #1 jpeg2wbmp()-Beispiel

    <?php
    // Pfad zur JPEG-Datei
    $path = './test.jpg';

    // Ermitteln der Bildgröße
    $image = getimagesize($path);

    // Bild konvertieren
    jpeg2wbmp($path, './test.wbmp', $image[1], $image[0], 5);
    ?>

### Siehe auch

- png2wbmp() - Convert PNG image file to WBMP image file

# png2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

png2wbmp — Convert PNG image file to WBMP image file

Warnung

Diese Funktion ist seit PHP 7.2.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function png2wbmp(
string `$pngname`,
string `$wbmpname`,
int `$dest_height`,
int `$dest_width`,
int `$threshold`
): bool

Converts a PNG file into a WBMP file.

### Parameter-Liste

`pngname`

  Path to PNG file.

`wbmpname`

  Path to destination WBMP file.

`dest_height`

  Destination image height.

`dest_width`

  Destination image width.

`threshold`

  Threshold value, between 0 and 8 (inclusive).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

Achtung

Wenn libgd das Bild nicht ausgeben kann, gibt diese Funktion `true` zurück.

### Beispiele

Beispiel #1 png2wbmp() example

    <?php
    // Path to the target png
    $path = './test.png';

    // Get the image sizes
    $image = getimagesize($path);

    // Convert image
    png2wbmp($path, './test.wbmp', $image[1], $image[0], 7);
    ?>

### Siehe auch

- jpeg2wbmp() - Konvertiert eine JPEG-Bilddatei in eine WBMP-Bilddatei

## Inhaltsverzeichnis

- gd_info — Liefert Informationen über die aktuell verwendete GD-Bibliothek
- getimagesize — Liefert die Größe einer Grafik
- getimagesizefromstring — Liefert die Größe einer Grafik aus einer Zeichenkette
- image_type_to_extension — Get file extension for image type
- image_type_to_mime_type — Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
- image2wbmp — Gibt das Bild im Browser oder einer Datei aus.
- imageaffine — Return an image containing the affine transformed src image, using an optional clipping area
- imageaffinematrixconcat — Concatenate two affine transformation matrices
- imageaffinematrixget — Get an affine transformation matrix
- imagealphablending — Set the blending mode for an image
- imageantialias — Should antialias functions be used or not
- imagearc — Zeichnet einen Bogen
- imageavif — Gibt das Bild im Browser oder einer Datei aus.
- imagebmp — Output a BMP image to browser or file
- imagechar — Zeichnet ein horizontal ausgerichtetes Zeichen
- imagecharup — Zeichnet ein vertikal ausgerichtetes Zeichen
- imagecolorallocate — Alloziert eine Farbe für eine Grafik
- imagecolorallocatealpha — Allocate a color for an image
- imagecolorat — Liefert den Farbwert eines Bildpunktes
- imagecolorclosest — Ermittelt den Index der Farbe, die der angegebenen Farbe am nächsten kommt
- imagecolorclosestalpha — Get the index of the closest color to the specified color + alpha
- imagecolorclosesthwb — Get the index of the color which has the hue, white and blackness
- imagecolordeallocate — Löscht eine Farbdefinition
- imagecolorexact — Ermittelt den Index-Wert der angegebenen Farbe
- imagecolorexactalpha — Get the index of the specified color + alpha
- imagecolormatch — Makes the colors of the palette version of an image more closely match the true color version
- imagecolorresolve — Ermittelt den Index-Wert der angegebenen Farbe oder die nächstmögliche Alternative dazu
- imagecolorresolvealpha — Get the index of the specified color + alpha or its closest possible alternative
- imagecolorset — Setzt die Farbe für den angegebenen Paletten-Index
- imagecolorsforindex — Ermittelt die Farbwerte eines Palettenindex
- imagecolorstotal — Ermittelt die Anzahl der Farben in der Palette eines Bildes
- imagecolortransparent — Definiert eine Farbe als transparent
- imageconvolution — Apply a 3x3 convolution matrix, using coefficient and offset
- imagecopy — Kopiert einen Bildausschnitt
- imagecopymerge — Copy and merge part of an image
- imagecopymergegray — Copy and merge part of an image with gray scale
- imagecopyresampled — Copy and resize part of an image with resampling
- imagecopyresized — Kopieren und Ändern der Größe eines Bild-Teiles
- imagecreate — Erzeugt ein neues Palettenbild
- imagecreatefromavif — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefrombmp — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefromgd — Create a new image from GD file or URL
- imagecreatefromgd2 — Create a new image from GD2 file or URL
- imagecreatefromgd2part — Create a new image from a given part of GD2 file or URL
- imagecreatefromgif — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefromjpeg — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefrompng — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefromstring — Create a new image from the image stream in the string
- imagecreatefromtga — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefromwbmp — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefromwebp — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefromxbm — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatefromxpm — Erzeugt ein neues Bild aus einer Datei oder URL
- imagecreatetruecolor — Create a new true color image
- imagecrop — Crop an image to the given rectangle
- imagecropauto — Crop an image automatically using one of the available modes
- imagedashedline — Zeichnet eine gestrichelte Linie
- imagedestroy — Löscht ein Bild
- imageellipse — Draw an ellipse
- imagefill — Flutfüllung
- imagefilledarc — Draw a partial arc and fill it
- imagefilledellipse — Draw a filled ellipse
- imagefilledpolygon — Zeichnet ein gefülltes Polygon
- imagefilledrectangle — Zeichnet ein gefülltes Rechteck
- imagefilltoborder — Füllt einen Bereich mit einer bestimmten Farbe
- imagefilter — Applies a filter to an image
- imageflip — Flips an image using a given mode
- imagefontheight — Ermittelt die Höhe einer Schriftart
- imagefontwidth — Ermittelt die Breite einer Schriftart
- imageftbbox — Give the bounding box of a text using fonts via freetype2
- imagefttext — Write text to the image using fonts using FreeType 2
- imagegammacorrect — Wendet eine Gamma-Korrektur auf ein GD-Bild an
- imagegd — Output GD image to browser or file
- imagegd2 — Output GD2 image to browser or file
- imagegetclip — Get the clipping rectangle
- imagegetinterpolation — Get the interpolation method
- imagegif — Gibt das Bild im Browser oder einer Datei aus.
- imagegrabscreen — Captures the whole screen
- imagegrabwindow — Captures a window
- imageinterlace — Aktiviert oder Deaktiviert Interlacing
- imageistruecolor — Finds whether an image is a truecolor image
- imagejpeg — Gibt das Bild im Browser oder einer Datei aus.
- imagelayereffect — Set the alpha blending flag to use layering effects
- imageline — Zeichnet eine Linie
- imageloadfont — Lädt eine neue Schriftart
- imageopenpolygon — Draws an open polygon
- imagepalettecopy — Copy the palette from one image to another
- imagepalettetotruecolor — Converts a palette based image to true color
- imagepng — Ausgabe eines Bildes im Browser oder als Datei im PNG-Format
- imagepolygon — Zeichnet ein Polygon
- imagerectangle — Zeichnet ein Rechteck
- imageresolution — Get or set the resolution of the image
- imagerotate — Rotate an image with a given angle
- imagesavealpha — Ob beim Speichern von Bildern vollständige Alphakanal-Information erhalten wird
- imagescale — Scale an image using the given new width and height
- imagesetbrush — Set the brush image for line drawing
- imagesetclip — Set the clipping rectangle
- imagesetinterpolation — Set the interpolation method
- imagesetpixel — Setzt ein einzelnes Pixel
- imagesetstyle — Set the style for line drawing
- imagesetthickness — Set the thickness for line drawing
- imagesettile — Set the tile image for filling
- imagestring — Zeichnet einen horizontalen String
- imagestringup — Zeichnet einen vertikalen String
- imagesx — Ermittelt die Breite eines Bildes
- imagesy — Ermittelt die Höhe eines Bildes
- imagetruecolortopalette — Convert a true color image to a palette image
- imagettfbbox — Ermittelt das umgebende Rechteck eines Textes, der eine TrueType-Schriftart verwendet
- imagettftext — Schreibt Text mit TrueType-Schriftarten ins Bild
- imagetypes — Liefert die von der verwendeten PHP-Version unterstützten Grafikformate
- imagewbmp — Gibt das Bild im Browser oder einer Datei aus.
- imagewebp — Output a WebP image to browser or file
- imagexbm — Output an XBM image to browser or file
- iptcembed — Embeds binary IPTC data into a JPEG image
- iptcparse — Parse a binary IPTC block into single tags
- jpeg2wbmp — Konvertiert eine JPEG-Bilddatei in eine WBMP-Bilddatei
- png2wbmp — Convert PNG image file to WBMP image file

# The GdImage class

(PHP 8)

## Einführung

A fully opaque class which replaces `gd` resources as of PHP 8.0.0.

## Klassenbeschreibung

final class GdImage {
}

# The GdFont class

(PHP 8 >= 8.1.0)

## Einführung

A fully opaque class which replaces `gd font` resources as of PHP 8.1.0.

## Klassenbeschreibung

final class GdFont {
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Beispiele
  - PNG erzeugen mit PHP
  - Wasserzeichen mit Hilfe von Alpha-Kanälen zufügen
  - Erstellen eines transparenten Wasserzeichens mit imagecopymerge
- GD- und Image-Funktionen
  - gd_info — Liefert Informationen über die aktuell verwendete GD-Bibliothek
  - getimagesize — Liefert die Größe einer Grafik
  - getimagesizefromstring — Liefert die Größe einer Grafik aus einer Zeichenkette
  - image_type_to_extension — Get file extension for image type
  - image_type_to_mime_type — Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
  - image2wbmp — Gibt das Bild im Browser oder einer Datei aus.
  - imageaffine — Return an image containing the affine transformed src image, using an optional clipping area
  - imageaffinematrixconcat — Concatenate two affine transformation matrices
  - imageaffinematrixget — Get an affine transformation matrix
  - imagealphablending — Set the blending mode for an image
  - imageantialias — Should antialias functions be used or not
  - imagearc — Zeichnet einen Bogen
  - imageavif — Gibt das Bild im Browser oder einer Datei aus.
  - imagebmp — Output a BMP image to browser or file
  - imagechar — Zeichnet ein horizontal ausgerichtetes Zeichen
  - imagecharup — Zeichnet ein vertikal ausgerichtetes Zeichen
  - imagecolorallocate — Alloziert eine Farbe für eine Grafik
  - imagecolorallocatealpha — Allocate a color for an image
  - imagecolorat — Liefert den Farbwert eines Bildpunktes
  - imagecolorclosest — Ermittelt den Index der Farbe, die der angegebenen Farbe am nächsten kommt
  - imagecolorclosestalpha — Get the index of the closest color to the specified color + alpha
  - imagecolorclosesthwb — Get the index of the color which has the hue, white and blackness
  - imagecolordeallocate — Löscht eine Farbdefinition
  - imagecolorexact — Ermittelt den Index-Wert der angegebenen Farbe
  - imagecolorexactalpha — Get the index of the specified color + alpha
  - imagecolormatch — Makes the colors of the palette version of an image more closely match the true color version
  - imagecolorresolve — Ermittelt den Index-Wert der angegebenen Farbe oder die nächstmögliche Alternative dazu
  - imagecolorresolvealpha — Get the index of the specified color + alpha or its closest possible alternative
  - imagecolorset — Setzt die Farbe für den angegebenen Paletten-Index
  - imagecolorsforindex — Ermittelt die Farbwerte eines Palettenindex
  - imagecolorstotal — Ermittelt die Anzahl der Farben in der Palette eines Bildes
  - imagecolortransparent — Definiert eine Farbe als transparent
  - imageconvolution — Apply a 3x3 convolution matrix, using coefficient and offset
  - imagecopy — Kopiert einen Bildausschnitt
  - imagecopymerge — Copy and merge part of an image
  - imagecopymergegray — Copy and merge part of an image with gray scale
  - imagecopyresampled — Copy and resize part of an image with resampling
  - imagecopyresized — Kopieren und Ändern der Größe eines Bild-Teiles
  - imagecreate — Erzeugt ein neues Palettenbild
  - imagecreatefromavif — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatefrombmp — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatefromgd — Create a new image from GD file or URL
  - imagecreatefromgd2 — Create a new image from GD2 file or URL
  - imagecreatefromgd2part — Create a new image from a given part of GD2 file or URL
  - imagecreatefromgif — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatefromjpeg — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatefrompng — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatefromstring — Create a new image from the image stream in the string
  - imagecreatefromtga — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatefromwbmp — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatefromwebp — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatefromxbm — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatefromxpm — Erzeugt ein neues Bild aus einer Datei oder URL
  - imagecreatetruecolor — Create a new true color image
  - imagecrop — Crop an image to the given rectangle
  - imagecropauto — Crop an image automatically using one of the available modes
  - imagedashedline — Zeichnet eine gestrichelte Linie
  - imagedestroy — Löscht ein Bild
  - imageellipse — Draw an ellipse
  - imagefill — Flutfüllung
  - imagefilledarc — Draw a partial arc and fill it
  - imagefilledellipse — Draw a filled ellipse
  - imagefilledpolygon — Zeichnet ein gefülltes Polygon
  - imagefilledrectangle — Zeichnet ein gefülltes Rechteck
  - imagefilltoborder — Füllt einen Bereich mit einer bestimmten Farbe
  - imagefilter — Applies a filter to an image
  - imageflip — Flips an image using a given mode
  - imagefontheight — Ermittelt die Höhe einer Schriftart
  - imagefontwidth — Ermittelt die Breite einer Schriftart
  - imageftbbox — Give the bounding box of a text using fonts via freetype2
  - imagefttext — Write text to the image using fonts using FreeType 2
  - imagegammacorrect — Wendet eine Gamma-Korrektur auf ein GD-Bild an
  - imagegd — Output GD image to browser or file
  - imagegd2 — Output GD2 image to browser or file
  - imagegetclip — Get the clipping rectangle
  - imagegetinterpolation — Get the interpolation method
  - imagegif — Gibt das Bild im Browser oder einer Datei aus.
  - imagegrabscreen — Captures the whole screen
  - imagegrabwindow — Captures a window
  - imageinterlace — Aktiviert oder Deaktiviert Interlacing
  - imageistruecolor — Finds whether an image is a truecolor image
  - imagejpeg — Gibt das Bild im Browser oder einer Datei aus.
  - imagelayereffect — Set the alpha blending flag to use layering effects
  - imageline — Zeichnet eine Linie
  - imageloadfont — Lädt eine neue Schriftart
  - imageopenpolygon — Draws an open polygon
  - imagepalettecopy — Copy the palette from one image to another
  - imagepalettetotruecolor — Converts a palette based image to true color
  - imagepng — Ausgabe eines Bildes im Browser oder als Datei im PNG-Format
  - imagepolygon — Zeichnet ein Polygon
  - imagerectangle — Zeichnet ein Rechteck
  - imageresolution — Get or set the resolution of the image
  - imagerotate — Rotate an image with a given angle
  - imagesavealpha — Ob beim Speichern von Bildern vollständige Alphakanal-Information erhalten wird
  - imagescale — Scale an image using the given new width and height
  - imagesetbrush — Set the brush image for line drawing
  - imagesetclip — Set the clipping rectangle
  - imagesetinterpolation — Set the interpolation method
  - imagesetpixel — Setzt ein einzelnes Pixel
  - imagesetstyle — Set the style for line drawing
  - imagesetthickness — Set the thickness for line drawing
  - imagesettile — Set the tile image for filling
  - imagestring — Zeichnet einen horizontalen String
  - imagestringup — Zeichnet einen vertikalen String
  - imagesx — Ermittelt die Breite eines Bildes
  - imagesy — Ermittelt die Höhe eines Bildes
  - imagetruecolortopalette — Convert a true color image to a palette image
  - imagettfbbox — Ermittelt das umgebende Rechteck eines Textes, der eine TrueType-Schriftart verwendet
  - imagettftext — Schreibt Text mit TrueType-Schriftarten ins Bild
  - imagetypes — Liefert die von der verwendeten PHP-Version unterstützten Grafikformate
  - imagewbmp — Gibt das Bild im Browser oder einer Datei aus.
  - imagewebp — Output a WebP image to browser or file
  - imagexbm — Output an XBM image to browser or file
  - iptcembed — Embeds binary IPTC data into a JPEG image
  - iptcparse — Parse a binary IPTC block into single tags
  - jpeg2wbmp — Konvertiert eine JPEG-Bilddatei in eine WBMP-Bilddatei
  - png2wbmp — Convert PNG image file to WBMP image file
- GdImage — The GdImage class
- GdFont — The GdFont class

# Gmagick

# Einführung

Warnung

Diese Erweiterung ist EXPERIMENTELL. Das Verhalten dieser Erweiterung, einschließlich der Funktionsnamen, und alles Andere, was hier dokumentiert ist, kann sich in zukünftigen PHP-Versionen ohne Ankündigung ändern. Seien Sie gewarnt und verwenden Sie diese Erweiterung auf eigenes Risiko.

Gmagick is a php extension to create, modify and obtain meta information of images using the GraphicsMagick API.

GraphicsMagick prides itself as the swiss army knife of image processing. It works with over 88 major formats including important formats like DPX, GIF, JPEG, JPEG-2000, PNG, PDF, PNM, and TIFF.

Gmagick consists of a main Gmagick class, a GmagickDraw class which is in effect a drawing wand and a GmagickPixel class of which instances represent a single pixel of an image (color, opacity).

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

This extension works best with GraphicsMagick version 1.4+. Gmagick should work with earlier versions up to GraphicsMagick 1.2.6 but some features and formats are not supported for these versions. Windows version of GraphicsMagick is available from the GraphicsMagick website. To read about the difference between ImageMagick and GraphicsMagick, check the » FAQ.

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/gmagick.

> Hinweis: The official name of this extension is gmagick.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

Colortype constants
`Gmagick::COLOR_BLACK` (int)
  Black
`Gmagick::COLOR_BLUE` (int)
  Blue
`Gmagick::COLOR_CYAN` (int)
  Cyan
`Gmagick::COLOR_GREEN` (int)
  Green
`Gmagick::COLOR_RED` (int)
  Red
`Gmagick::COLOR_YELLOW` (int)
  Yellow
`Gmagick::COLOR_MAGENTA` (int)
  Magenta
`Gmagick::COLOR_OPACITY` (int)
  Opacity
`Gmagick::COLOR_ALPHA` (int)
  Alpha
`Gmagick::COLOR_FUZZ` (int)
  Fuzz

Composite Operator Constants
`Gmagick::COMPOSITE_DEFAULT` (int)
  The default composite operator
`Gmagick::COMPOSITE_UNDEFINED` (int)
  Undefined composite operator
`Gmagick::COMPOSITE_NO` (int)
  No composite operator defined
`Gmagick::COMPOSITE_ADD` (int)
  The result of image + image
`Gmagick::COMPOSITE_ATOP` (int)
  The result is the same shape as image, with composite image obscuring image where the image shapes overlap
`Gmagick::COMPOSITE_BLEND` (int)
  Blends the image
`Gmagick::COMPOSITE_BUMPMAP` (int)
  The same as COMPOSITE_MULTIPLY, except the source is converted to grayscale first.
`Gmagick::COMPOSITE_CLEAR` (int)
  Makes the target image transparent
`Gmagick::COMPOSITE_COLORBURN` (int)
  Darkens the destination image to reflect the source image
`Gmagick::COMPOSITE_COLORDODGE` (int)
  Brightens the destination image to reflect the source image
`Gmagick::COMPOSITE_COLORIZE` (int)
  Colorizes the target image using the composite image
`Gmagick::COMPOSITE_COPYBLACK` (int)
  Copies black from the source to target
`Gmagick::COMPOSITE_COPYBLUE` (int)
  Copies blue from the source to target
`Gmagick::COMPOSITE_COPY` (int)
  Copies the source image on the target image
`Gmagick::COMPOSITE_COPYCYAN` (int)
  Copies cyan from the source to target
`Gmagick::COMPOSITE_COPYGREEN` (int)
  Copies green from the source to target
`Gmagick::COMPOSITE_COPYMAGENTA` (int)
  Copies magenta from the source to target
`Gmagick::COMPOSITE_COPYOPACITY` (int)
  Copies opacity from the source to target
`Gmagick::COMPOSITE_COPYRED` (int)
  Copies red from the source to target
`Gmagick::COMPOSITE_COPYYELLOW` (int)
  Copies yellow from the source to target
`Gmagick::COMPOSITE_DARKEN` (int)
  Darkens the target image
`Gmagick::COMPOSITE_DSTATOP` (int)
  The part of the destination lying inside of the source is composited over the source and replaces the destination
`Gmagick::COMPOSITE_DST` (int)
  The target is left untouched
`Gmagick::COMPOSITE_DSTIN` (int)
  The parts inside the source replace the target
`Gmagick::COMPOSITE_DSTOUT` (int)
  The parts outside the source replace the target
`Gmagick::COMPOSITE_DSTOVER` (int)
  Target replaces the source
`Gmagick::COMPOSITE_DIFFERENCE` (int)
  Subtracts the darker of the two constituent colors from the lighter
`Gmagick::COMPOSITE_DISPLACE` (int)
  Shifts target image pixels as defined by the source
`Gmagick::COMPOSITE_DISSOLVE` (int)
  Dissolves the source in to the target
`Gmagick::COMPOSITE_EXCLUSION` (int)
  Produces an effect similar to that of Gmagick::COMPOSITE_DIFFERENCE, but appears as lower contrast
`Gmagick::COMPOSITE_HARDLIGHT` (int)
  Multiplies or screens the colors, dependent on the source color value
`Gmagick::COMPOSITE_HUE` (int)
  Modifies the hue of the target as defined by source
`Gmagick::COMPOSITE_IN` (int)
  Composites source into the target
`Gmagick::COMPOSITE_LIGHTEN` (int)
  Lightens the target as defined by source
`Gmagick::COMPOSITE_LUMINIZE` (int)
  Luminizes the target as defined by source
`Gmagick::COMPOSITE_MINUS` (int)
  Subtracts the source from the target
`Gmagick::COMPOSITE_MODULATE` (int)
  Modulates the target brightness, saturation and hue as defined by source
`Gmagick::COMPOSITE_MULTIPLY` (int)
  Multiplies the target to the source
`Gmagick::COMPOSITE_OUT` (int)
  Composites outer parts of the source on the target
`Gmagick::COMPOSITE_OVER` (int)
  Composites source over the target
`Gmagick::COMPOSITE_OVERLAY` (int)
  Overlays the source on the target
`Gmagick::COMPOSITE_PLUS` (int)
  Adds the source to the target
`Gmagick::COMPOSITE_REPLACE` (int)
  Replaces the target with the source
`Gmagick::COMPOSITE_SATURATE` (int)
  Saturates the target as defined by the source
`Gmagick::COMPOSITE_SCREEN` (int)
  The source and destination are complemented and then multiplied and then replace the destination
`Gmagick::COMPOSITE_SOFTLIGHT` (int)
  Darkens or lightens the colors, dependent on the source
`Gmagick::COMPOSITE_SRCATOP` (int)
  The part of the source lying inside of the destination is composited onto the destination
`Gmagick::COMPOSITE_SRC` (int)
  The source is copied to the destination
`Gmagick::COMPOSITE_SRCIN` (int)
  The part of the source lying inside of the destination replaces the destination
`Gmagick::COMPOSITE_SRCOUT` (int)
  The part of the source lying outside of the destination replaces the destination
`Gmagick::COMPOSITE_SRCOVER` (int)
  The source replaces the destination
`Gmagick::COMPOSITE_SUBTRACT` (int)
  Subtract the colors in the source image from the destination image
`Gmagick::COMPOSITE_THRESHOLD` (int)
  The source is composited on the target as defined by source threshold
`Gmagick::COMPOSITE_XOR` (int)
  The part of the source that lies outside of the destination is combined with the part of the destination that lies outside of the source

Montage Mode constants
`Gmagick::MONTAGEMODE_FRAME` (int)
`Gmagick::MONTAGEMODE_UNFRAME` (int)
`Gmagick::MONTAGEMODE_CONCATENATE` (int)

Style constants
`Gmagick::STYLE_NORMAL` (int)
`Gmagick::STYLE_ITALIC` (int)
`Gmagick::STYLE_OBLIQUE` (int)
`Gmagick::STYLE_ANY` (int)

Filter constants
`Gmagick::FILTER_UNDEFINED` (int)
`Gmagick::FILTER_POINT` (int)
`Gmagick::FILTER_BOX` (int)
`Gmagick::FILTER_TRIANGLE` (int)
`Gmagick::FILTER_HERMITE` (int)
`Gmagick::FILTER_HANNING` (int)
`Gmagick::FILTER_HAMMING` (int)
`Gmagick::FILTER_BLACKMAN` (int)
`Gmagick::FILTER_GAUSSIAN` (int)
`Gmagick::FILTER_QUADRATIC` (int)
`Gmagick::FILTER_CUBIC` (int)
`Gmagick::FILTER_CATROM` (int)
`Gmagick::FILTER_MITCHELL` (int)
`Gmagick::FILTER_LANCZOS` (int)
`Gmagick::FILTER_BESSEL` (int)
`Gmagick::FILTER_SINC` (int)

Image type constants
`Gmagick::IMGTYPE_UNDEFINED` (int)
`Gmagick::IMGTYPE_BILEVEL` (int)
`Gmagick::IMGTYPE_GRAYSCALE` (int)
`Gmagick::IMGTYPE_GRAYSCALEMATTE` (int)
`Gmagick::IMGTYPE_PALETTE` (int)
`Gmagick::IMGTYPE_PALETTEMATTE` (int)
`Gmagick::IMGTYPE_TRUECOLOR` (int)
`Gmagick::IMGTYPE_TRUECOLORMATTE` (int)
`Gmagick::IMGTYPE_COLORSEPARATION` (int)
`Gmagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`Gmagick::IMGTYPE_OPTIMIZE` (int)

Resolution constants
`Gmagick::RESOLUTION_UNDEFINED` (int)
`Gmagick::RESOLUTION_PIXELSPERINCH` (int)
`Gmagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

Compression constants
`Gmagick::COMPRESSION_UNDEFINED` (int)
`Gmagick::COMPRESSION_NO` (int)
`Gmagick::COMPRESSION_BZIP` (int)
`Gmagick::COMPRESSION_FAX` (int)
`Gmagick::COMPRESSION_GROUP4` (int)
`Gmagick::COMPRESSION_JPEG` (int)
`Gmagick::COMPRESSION_JPEG2000` (int)
`Gmagick::COMPRESSION_LOSSLESSJPEG` (int)
`Gmagick::COMPRESSION_LZW` (int)
`Gmagick::COMPRESSION_RLE` (int)
`Gmagick::COMPRESSION_ZIP` (int)

Paint constants
`Gmagick::PAINT_POINT` (int)
`Gmagick::PAINT_REPLACE` (int)
`Gmagick::PAINT_FLOODFILL` (int)
`Gmagick::PAINT_FILLTOBORDER` (int)
`Gmagick::PAINT_RESET` (int)

Gravity constants
`Gmagick::GRAVITY_NORTHWEST` (int)
`Gmagick::GRAVITY_NORTH` (int)
`Gmagick::GRAVITY_NORTHEAST` (int)
`Gmagick::GRAVITY_WEST` (int)
`Gmagick::GRAVITY_CENTER` (int)
`Gmagick::GRAVITY_EAST` (int)
`Gmagick::GRAVITY_SOUTHWEST` (int)
`Gmagick::GRAVITY_SOUTH` (int)
`Gmagick::GRAVITY_SOUTHEAST` (int)

Stretch constants
`Gmagick::STRETCH_NORMAL` (int)
`Gmagick::STRETCH_ULTRACONDENSED` (int)
`Gmagick::STRETCH_CONDENSED` (int)
`Gmagick::STRETCH_SEMICONDENSED` (int)
`Gmagick::STRETCH_SEMIEXPANDED` (int)
`Gmagick::STRETCH_EXPANDED` (int)
`Gmagick::STRETCH_EXTRAEXPANDED` (int)
`Gmagick::STRETCH_ULTRAEXPANDED` (int)
`Gmagick::STRETCH_ANY` (int)

Align constants
`Gmagick::ALIGN_UNDEFINED` (int)
`Gmagick::ALIGN_LEFT` (int)
`Gmagick::ALIGN_CENTER` (int)
`Gmagick::ALIGN_RIGHT` (int)

Decoration constants
`Gmagick::DECORATION_NO` (int)
`Gmagick::DECORATION_UNDERLINE` (int)
`Gmagick::DECORATION_OVERLINE` (int)
`Gmagick::DECORATION_LINETROUGH` (int)

Noise constants
`Gmagick::NOISE_UNIFORM` (int)
`Gmagick::NOISE_GAUSSIAN` (int)
`Gmagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`Gmagick::NOISE_IMPULSE` (int)
`Gmagick::NOISE_LAPLACIAN` (int)
`Gmagick::NOISE_POISSON` (int)

Channel constants
`Gmagick::CHANNEL_UNDEFINED` (int)
`Gmagick::CHANNEL_RED` (int)
`Gmagick::CHANNEL_GRAY` (int)
`Gmagick::CHANNEL_CYAN` (int)
`Gmagick::CHANNEL_GREEN` (int)
`Gmagick::CHANNEL_MAGENTA` (int)
`Gmagick::CHANNEL_BLUE` (int)
`Gmagick::CHANNEL_YELLOW` (int)
`Gmagick::CHANNEL_ALPHA` (int)
`Gmagick::CHANNEL_OPACITY` (int)
`Gmagick::CHANNEL_MATTE` (int)
`Gmagick::CHANNEL_BLACK` (int)
`Gmagick::CHANNEL_INDEX` (int)
`Gmagick::CHANNEL_ALL` (int)

Metric constants
`Gmagick::METRIC_UNDEFINED` (int)
`Gmagick::METRIC_MEANABSOLUTEERROR` (int)
`Gmagick::METRIC_MEANSQUAREERROR` (int)
`Gmagick::METRIC_PEAKABSOLUTEERROR` (int)
`Gmagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`Gmagick::METRIC_ROOTMEANSQUAREDERROR` (int)

Pixel constants
`Gmagick::PIXEL_CHAR` (int)
`Gmagick::PIXEL_DOUBLE` (int)
`Gmagick::PIXEL_FLOAT` (int)
`Gmagick::PIXEL_INTEGER` (int)
`Gmagick::PIXEL_LONG` (int)
`Gmagick::PIXEL_QUANTUM` (int)
`Gmagick::PIXEL_SHORT` (int)

Colorspace constants
`Gmagick::COLORSPACE_UNDEFINED` (int)
`Gmagick::COLORSPACE_RGB` (int)
`Gmagick::COLORSPACE_GRAY` (int)
`Gmagick::COLORSPACE_TRANSPARENT` (int)
`Gmagick::COLORSPACE_OHTA` (int)
`Gmagick::COLORSPACE_LAB` (int)
`Gmagick::COLORSPACE_XYZ` (int)
`Gmagick::COLORSPACE_YCBCR` (int)
`Gmagick::COLORSPACE_YCC` (int)
`Gmagick::COLORSPACE_YIQ` (int)
`Gmagick::COLORSPACE_YPBPR` (int)
`Gmagick::COLORSPACE_YUV` (int)
`Gmagick::COLORSPACE_CMYK` (int)
`Gmagick::COLORSPACE_SRGB` (int)
`Gmagick::COLORSPACE_HSB` (int)
`Gmagick::COLORSPACE_HSL` (int)
`Gmagick::COLORSPACE_HWB` (int)
`Gmagick::COLORSPACE_REC601LUMA` (int)
`Gmagick::COLORSPACE_REC709LUMA` (int)
`Gmagick::COLORSPACE_LOG` (int)

Virtual Pixel Method constants
`Gmagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`Gmagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`Gmagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`Gmagick::VIRTUALPIXELMETHOD_EDGE` (int)
`Gmagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`Gmagick::VIRTUALPIXELMETHOD_TILE` (int)
`Gmagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)

Preview constants
`Gmagick::PREVIEW_UNDEFINED` (int)
`Gmagick::PREVIEW_ROTATE` (int)
`Gmagick::PREVIEW_SHEAR` (int)
`Gmagick::PREVIEW_ROLL` (int)
`Gmagick::PREVIEW_HUE` (int)
`Gmagick::PREVIEW_SATURATION` (int)
`Gmagick::PREVIEW_BRIGHTNESS` (int)
`Gmagick::PREVIEW_GAMMA` (int)
`Gmagick::PREVIEW_SPIFF` (int)
`Gmagick::PREVIEW_DULL` (int)
`Gmagick::PREVIEW_GRAYSCALE` (int)
`Gmagick::PREVIEW_QUANTIZE` (int)
`Gmagick::PREVIEW_DESPECKLE` (int)
`Gmagick::PREVIEW_REDUCENOISE` (int)
`Gmagick::PREVIEW_ADDNOISE` (int)
`Gmagick::PREVIEW_SHARPEN` (int)
`Gmagick::PREVIEW_BLUR` (int)
`Gmagick::PREVIEW_THRESHOLD` (int)
`Gmagick::PREVIEW_EDGEDETECT` (int)
`Gmagick::PREVIEW_SPREAD` (int)
`Gmagick::PREVIEW_SOLARIZE` (int)
`Gmagick::PREVIEW_SHADE` (int)
`Gmagick::PREVIEW_RAISE` (int)
`Gmagick::PREVIEW_SEGMENT` (int)
`Gmagick::PREVIEW_SWIRL` (int)
`Gmagick::PREVIEW_IMPLODE` (int)
`Gmagick::PREVIEW_WAVE` (int)
`Gmagick::PREVIEW_OILPAINT` (int)
`Gmagick::PREVIEW_CHARCOALDRAWING` (int)
`Gmagick::PREVIEW_JPEG` (int)

Rendering Intent constants
`Gmagick::RENDERINGINTENT_UNDEFINED` (int)
`Gmagick::RENDERINGINTENT_SATURATION` (int)
`Gmagick::RENDERINGINTENT_PERCEPTUAL` (int)
`Gmagick::RENDERINGINTENT_ABSOLUTE` (int)
`Gmagick::RENDERINGINTENT_RELATIVE` (int)

Fillrule constants
`Gmagick::FILLRULE_UNDEFINED` (int)
`Gmagick::FILLRULE_EVENODD` (int)
`Gmagick::FILLRULE_NONZERO` (int)

Pathunit constants
`Gmagick::PATHUNITS_UNDEFINED` (int)
`Gmagick::PATHUNITS_USERSPACE` (int)
`Gmagick::PATHUNITS_USERSPACEONUSE` (int)
`Gmagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

Linecap constants
`Gmagick::LINECAP_UNDEFINED` (int)
`Gmagick::LINECAP_BUTT` (int)
`Gmagick::LINECAP_ROUND` (int)
`Gmagick::LINECAP_SQUARE` (int)

Line Join constants
`Gmagick::LINEJOIN_UNDEFINED` (int)
`Gmagick::LINEJOIN_MITER` (int)
`Gmagick::LINEJOIN_ROUND` (int)
`Gmagick::LINEJOIN_BEVEL` (int)

Resourcetype constants
`Gmagick::RESOURCETYPE_UNDEFINED` (int)
`Gmagick::RESOURCETYPE_AREA` (int)
`Gmagick::RESOURCETYPE_DISK` (int)
`Gmagick::RESOURCETYPE_FILE` (int)
`Gmagick::RESOURCETYPE_MAP` (int)
`Gmagick::RESOURCETYPE_MEMORY` (int)

Orientation constants
`Gmagick::ORIENTATION_UNDEFINED` (int)
`Gmagick::ORIENTATION_TOPLEFT` (int)
`Gmagick::ORIENTATION_TOPRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMRIGHT` (int)
`Gmagick::ORIENTATION_BOTTOMLEFT` (int)
`Gmagick::ORIENTATION_LEFTTOP` (int)
`Gmagick::ORIENTATION_RIGHTTOP` (int)
`Gmagick::ORIENTATION_RIGHTBOTTOM` (int)
`Gmagick::ORIENTATION_LEFTBOTTOM` (int)

Interlace constants
`Gmagick::INTERLACE_UNDEFINED` (int)
`Gmagick::INTERLACE_NO` (int)
`Gmagick::INTERLACE_NONE` (int)
`Gmagick::INTERLACE_LINE` (int)
`Gmagick::INTERLACE_PLANE` (int)
`Gmagick::INTERLACE_PARTITION` (int)

# Beispiele

The following shows some common Gmagick image operations.

Beispiel #1 Gmagick Example

    <?php
    //Instantiate a new Gmagick object
    $image = new Gmagick('example.jpg');

    //Make thumbnail from image loaded. 0 for either axes preserves aspect ratio
    $image->thumbnailimage(100, 0);

    //Create a border around the image, then simulate how the image will look like as an oil painting
    //Notice the chaining of mutator methods which is supported in gmagick
    $image->borderimage("yellow", 8, 8)->oilpaintimage(0.3);

    //Write the current image at the current state to a file
    $image->write('example_thumbnail.jpg');
    ?>

# The Gmagick class

(PECL gmagick >= Unknown)

## Einführung

## Klassenbeschreibung

class Gmagick {
/* Methoden */
public function __construct(string `$filename` = ?)
public function addimage(Gmagick `$source`): Gmagick
public function addnoiseimage(int `$noise_type`): Gmagick
public function annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick
public function blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick
public function borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick
public function charcoalimage(float `$radius`, float `$sigma`): Gmagick
public function chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick
public function clear(): Gmagick
public function commentimage(string `$comment`): Gmagick
public function compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick
public function cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick
public function cropthumbnailimage(int `$width`, int `$height`): Gmagick
public function current(): Gmagick
public function cyclecolormapimage(int `$displace`): Gmagick
public function deconstructimages(): Gmagick
public function despeckleimage(): Gmagick
public function destroy(): bool
public function drawimage(GmagickDraw `$GmagickDraw`): Gmagick
public function edgeimage(float `$radius`): Gmagick
public function embossimage(float `$radius`, float `$sigma`): Gmagick
public function enhanceimage(): Gmagick
public function equalizeimage(): Gmagick
public function flipimage(): Gmagick
public function flopimage(): Gmagick
public function frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick
public function gammaimage(float `$gamma`): Gmagick
public function getcopyright(): string
public function getfilename(): string
public function getimagebackgroundcolor(): GmagickPixel
public function getimageblueprimary(): array
public function getimagebordercolor(): GmagickPixel
public function getimagechanneldepth(int `$channel_type`): int
public function getimagecolors(): int
public function getimagecolorspace(): int
public function getimagecompose(): int
public function getimagedelay(): int
public function getimagedepth(): int
public function getimagedispose(): int
public function getimageextrema(): array
public function getimagefilename(): string
public function getimageformat(): string
public function getimagegamma(): float
public function getimagegreenprimary(): array
public function getimageheight(): int
public function getimagehistogram(): array
public function getimageindex(): int
public function getimageinterlacescheme(): int
public function getimageiterations(): int
public function getimagematte(): int
public function getimagemattecolor(): GmagickPixel
public function getimageprofile(string `$name`): string
public function getimageredprimary(): array
public function getimagerenderingintent(): int
public function getimageresolution(): array
public function getimagescene(): int
public function getimagesignature(): string
public function getimagetype(): int
public function getimageunits(): int
public function getimagewhitepoint(): array
public function getimagewidth(): int
public function getpackagename(): string
public function getquantumdepth(): array
public function getreleasedate(): string
public function getsamplingfactors(): array
public function getsize(): array
public function getversion(): array
public function hasnextimage(): mixed
public function haspreviousimage(): mixed
public function implodeimage(float `$radius`): mixed
public function labelimage(string `$label`): mixed
public function levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed
public function magnifyimage(): mixed
public function mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick
public function medianfilterimage(float `$radius`): void
public function minifyimage(): Gmagick
public function modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick
public function motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick
public function newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick
public function nextimage(): bool
public function normalizeimage(int `$channel` = ?): Gmagick
public function oilpaintimage( float `$radius` ): Gmagick
public function previousimage(): bool
public function profileimage(string `$name`, string `$profile`): Gmagick
public function quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function queryfontmetrics(GmagickDraw `$draw`, string `$text`): array
public function queryfonts(string `$pattern` = "*"): array
public function queryformats(string `$pattern` = "*"): array
public function radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick
public function raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick
public function read(string `$filename`): Gmagick
public function readimage(string `$filename`): Gmagick
public function readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick
public function readimagefile(resource `$fp`, string `$filename` = ?): Gmagick
public function reducenoiseimage(float `$radius`): Gmagick
public function removeimage(): Gmagick
public function removeimageprofile(string `$name`): string
public function resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick
public function resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick
public function rollimage(int `$x`, int `$y`): Gmagick
public function rotateimage(mixed `$color`, float `$degrees`): Gmagick
public function scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function separateimagechannel(int `$channel`): Gmagick
function setCompressionQuality( int `$quality` ): Gmagick
public function setfilename(string `$filename`): Gmagick
public function setimagebackgroundcolor(GmagickPixel `$color`): Gmagick
public function setimageblueprimary(float `$x`, float `$y`): Gmagick
public function setimagebordercolor(GmagickPixel `$color`): Gmagick
public function setimagechanneldepth(int `$channel`, int `$depth`): Gmagick
public function setimagecolorspace(int `$colorspace`): Gmagick
public function setimagecompose(int `$composite`): Gmagick
public function setimagedelay(int `$delay`): Gmagick
public function setimagedepth(int `$depth`): Gmagick
public function setimagedispose(int `$disposeType`): Gmagick
public function setimagefilename(string `$filename`): Gmagick
public function setimageformat(string `$imageFormat`): Gmagick
public function setimagegamma(float `$gamma`): Gmagick
public function setimagegreenprimary(float `$x`, float `$y`): Gmagick
public function setimageindex(int `$index`): Gmagick
public function setimageinterlacescheme(int `$interlace`): Gmagick
public function setimageiterations(int `$iterations`): Gmagick
public function setimageprofile(string `$name`, string `$profile`): Gmagick
public function setimageredprimary(float `$x`, float `$y`): Gmagick
public function setimagerenderingintent(int `$rendering_intent`): Gmagick
public function setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick
public function setimagescene(int `$scene`): Gmagick
public function setimagetype(int `$imgType`): Gmagick
public function setimageunits(int `$resolution`): Gmagick
public function setimagewhitepoint(float `$x`, float `$y`): Gmagick
public function setsamplingfactors(array `$factors`): Gmagick
public function setsize(int `$columns`, int `$rows`): Gmagick
public function shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick
public function solarizeimage(int `$threshold`): Gmagick
public function spreadimage(float `$radius`): Gmagick
public function stripimage(): Gmagick
public function swirlimage(float `$degrees`): Gmagick
public function thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function trimimage(float `$fuzz`): Gmagick
public function writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick
}

# Gmagick::addimage

(PECL gmagick >= Unknown)

Gmagick::addimage — Adds new image to Gmagick object image list

### Beschreibung

public function Gmagick::addimage(Gmagick `$source`): Gmagick

Adds new image to Gmagick object from the current position of the source object. After the operation iterator position is moved at the end of the list.

### Parameter-Liste

`source`
  The source Gmagick object

### Rückgabewerte

The Gmagick object with image added

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::addnoiseimage

(PECL gmagick >= Unknown)

Gmagick::addnoiseimage — Adds random noise to the image

### Beschreibung

public function Gmagick::addnoiseimage(int `$noise_type`): Gmagick

Adds random noise to the image.

### Parameter-Liste

`noise_type`
  The type of the noise. Refer to this list of noise constants.

### Rückgabewerte

The Gmagick object with noise added.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::annotateimage

(PECL gmagick >= Unknown)

Gmagick::annotateimage — Annotates an image with text

### Beschreibung

public function Gmagick::annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick

Annotates an image with text.

### Parameter-Liste

`GmagickDraw`
  The GmagickDraw object that contains settings for drawing the text.
`x`
  Horizontal offset in pixels to the left of text.
`y`
  Vertical offset in pixels to the baseline of text.
`angle`
  The angle at which to write the text.
`text`
  The string to draw.

### Rückgabewerte

The Gmagick object with annotation made.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::blurimage

(PECL gmagick >= Unknown)

Gmagick::blurimage — Adds blur filter to image

### Beschreibung

public function Gmagick::blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick

Adds blur filter to image.

### Parameter-Liste

`radius`
  Blur radius
`sigma`
  Standard deviation

### Rückgabewerte

The blurred Gmagick object

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::borderimage

(PECL gmagick >= Unknown)

Gmagick::borderimage — Surrounds the image with a border

### Beschreibung

public function Gmagick::borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick

Surrounds the image with a border of the color defined by the bordercolor GmagickPixel object or a color string.

### Parameter-Liste

`color`
  GmagickPixel object or a string containing the border color.
`width`
  Border width.
`height`
  Border height.

### Rückgabewerte

The Gmagick object with border defined.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::charcoalimage

(PECL gmagick >= Unknown)

Gmagick::charcoalimage — Simulates a charcoal drawing

### Beschreibung

public function Gmagick::charcoalimage(float `$radius`, float `$sigma`): Gmagick

Simulates a charcoal drawing.

### Parameter-Liste

`radius`
  The radius of the Gaussian, in pixels, not counting the center pixel.
`sigma`
  The standard deviation of the Gaussian, in pixels.

### Rückgabewerte

The Gmagick object with charcoal simulation.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::chopimage

(PECL gmagick >= Unknown)

Gmagick::chopimage — Removes a region of an image and trims

### Beschreibung

public function Gmagick::chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick

Removes a region of an image and collapses the image to occupy the removed portion.

### Parameter-Liste

`width`
  Width of the chopped area.
`height`
  Height of the chopped area.
`x`
  X origo of the chopped area.
`y`
  Y origo of the chopped area.

### Rückgabewerte

The chopped Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::clear

(PECL gmagick >= Unknown)

Gmagick::clear — Clears all resources associated to Gmagick object

### Beschreibung

public function Gmagick::clear(): Gmagick

Clears all resources associated to Gmagick object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The cleared Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::commentimage

(PECL gmagick >= Unknown)

Gmagick::commentimage — Adds a comment to your image

### Beschreibung

public function Gmagick::commentimage(string `$comment`): Gmagick

Adds a comment to your image.

### Parameter-Liste

`comment`
  The comment to add.

### Rückgabewerte

The Gmagick object with comment added.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::compositeimage

(PECL gmagick >= Unknown)

Gmagick::compositeimage — Composite one image onto another

### Beschreibung

public function Gmagick::compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick

Composite one image onto another at the specified offset.

### Parameter-Liste

`source`
  Gmagick object which holds the composite image.
`COMPOSE`
  Composite operator.
`x`
  The column offset of the composited image.
`y`
  The row offset of the composited image.

### Rückgabewerte

The Gmagick object with compositions.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::__construct

(PECL gmagick >= Unknown)

Gmagick::__construct — The Gmagick constructor

### Beschreibung

public function Gmagick::__construct(string `$filename` = ?)

The Gmagick constructor.

### Parameter-Liste

`filename`
  The path to an image to load or array of paths.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::cropimage

(PECL gmagick >= Unknown)

Gmagick::cropimage — Extracts a region of the image

### Beschreibung

public function Gmagick::cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick

Extracts a region of the image.

### Parameter-Liste

`width`
  The width of the crop.
`height`
  The height of the crop.
`x`
  The X coordinate of the cropped region's top left corner.
`y`
  The Y coordinate of the cropped region's top left corner.

### Rückgabewerte

The cropped Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::cropthumbnailimage

(PECL gmagick >= Unknown)

Gmagick::cropthumbnailimage — Creates a crop thumbnail

### Beschreibung

public function Gmagick::cropthumbnailimage(int `$width`, int `$height`): Gmagick

Creates a fixed size thumbnail by first scaling the image down and cropping a specified area from the center.

### Parameter-Liste

`width`
  The width of the thumbnail.
`height`
  The Height of the thumbnail.

### Rückgabewerte

The cropped Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::current

(PECL gmagick >= Unknown)

Gmagick::current — The current purpose

### Beschreibung

public function Gmagick::current(): Gmagick

Returns reference to the current gmagick object with image pointer at the correct sequence.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns self on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::cyclecolormapimage

(PECL gmagick >= Unknown)

Gmagick::cyclecolormapimage — Displaces an image's colormap

### Beschreibung

public function Gmagick::cyclecolormapimage(int `$displace`): Gmagick

Displaces an image's colormap by a given number of positions. If you cycle the colormap a number of times you can produce a psychedelic effect.

### Parameter-Liste

`displace`
  The amount to displace the colormap.

### Rückgabewerte

Returns self on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::deconstructimages

(PECL gmagick >= Unknown)

Gmagick::deconstructimages — Returns certain pixel differences between images

### Beschreibung

public function Gmagick::deconstructimages(): Gmagick

Compares each image with the next in a sequence and returns the maximum bounding region of any pixel differences it discovers.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a new Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::despeckleimage

(PECL gmagick >= Unknown)

Gmagick::despeckleimage — The despeckleimage purpose

### Beschreibung

public function Gmagick::despeckleimage(): Gmagick

Reduces the speckle noise in an image while preserving the edges of the original image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The despeckled Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

### Beispiele

Beispiel #1 Gmagick::despeckleimage() example

    <?php
    /* ... */
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    ...

# Gmagick::destroy

(PECL gmagick >= Unknown)

Gmagick::destroy — The destroy purpose

### Beschreibung

public function Gmagick::destroy(): bool

Destroys the Gmagick object and frees all resources associated with it

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::drawimage

(PECL gmagick >= Unknown)

Gmagick::drawimage — Renders the GmagickDraw object on the current image

### Beschreibung

public function Gmagick::drawimage(GmagickDraw `$GmagickDraw`): Gmagick

Renders the GmagickDraw object on the current image.

### Parameter-Liste

`GmagickDraw`
  The drawing operations to render on the image.

### Rückgabewerte

The drawn Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::edgeimage

(PECL gmagick >= Unknown)

Gmagick::edgeimage — Enhance edges within the image

### Beschreibung

public function Gmagick::edgeimage(float `$radius`): Gmagick

Enhance edges within the image with a convolution filter of the given radius. Use radius 0 and it will be auto-selected.

### Parameter-Liste

`radius`
  The radius of the operation.

### Rückgabewerte

The Gmagick object with edges enhanced.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::embossimage

(PECL gmagick >= Unknown)

Gmagick::embossimage — Returns a grayscale image with a three-dimensional effect

### Beschreibung

public function Gmagick::embossimage(float `$radius`, float `$sigma`): Gmagick

Returns a grayscale image with a three-dimensional effect. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and it will choose a suitable radius for you.

### Parameter-Liste

`radius`
  The radius of the effect.
`sigma`
  The sigma of the effect.

### Rückgabewerte

The embossed Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::enhanceimage

(PECL gmagick >= Unknown)

Gmagick::enhanceimage — Improves the quality of a noisy image

### Beschreibung

public function Gmagick::enhanceimage(): Gmagick

Applies a digital filter that improves the quality of a noisy image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The enhanced Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::equalizeimage

(PECL gmagick >= Unknown)

Gmagick::equalizeimage — Equalizes the image histogram

### Beschreibung

public function Gmagick::equalizeimage(): Gmagick

Equalizes the image histogram.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The equalized Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::flipimage

(PECL gmagick >= Unknown)

Gmagick::flipimage — Creates a vertical mirror image

### Beschreibung

public function Gmagick::flipimage(): Gmagick

Creates a vertical mirror image by reflecting the pixels around the central x-axis.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The flipped Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

### Siehe auch

- Gmagick::flopimage() - Creates a horizontal mirror image

# Gmagick::flopimage

(PECL gmagick >= Unknown)

Gmagick::flopimage — Creates a horizontal mirror image

### Beschreibung

public function Gmagick::flopimage(): Gmagick

Creates a horizontal mirror image by reflecting the pixels around the central y-axis.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The flopped Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

### Siehe auch

- Gmagick::flipimage() - Creates a vertical mirror image

# Gmagick::frameimage

(PECL gmagick >= Unknown)

Gmagick::frameimage — Adds a simulated three-dimensional border

### Beschreibung

public function Gmagick::frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick

Adds a simulated three-dimensional border around the image. The width and height specify the border width of the vertical and horizontal sides of the frame. The inner and outer bevels indicate the width of the inner and outer shadows of the frame.

### Parameter-Liste

`color`
  GmagickPixel object or a float representing the matte color.
`width`
  The width of the border.
`height`
  The height of the border.
`inner_bevel`
  The inner bevel width.
`outer_bevel`
  The outer bevel width.

### Rückgabewerte

The framed Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::gammaimage

(PECL gmagick >= Unknown)

Gmagick::gammaimage — Gamma-corrects an image

### Beschreibung

public function Gmagick::gammaimage(float `$gamma`): Gmagick

Gamma-corrects an image. The same image viewed on different devices will have perceptual differences in the way the image's intensities are represented on the screen. Specify individual gamma levels for the red, green, and blue channels, or adjust all three with the gamma parameter. Values typically range from 0.8 to 2.3.

### Parameter-Liste

`gamma`
  The amount of gamma-correction.

### Rückgabewerte

The gamma corrected Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getcopyright

(PECL gmagick >= Unknown)

Gmagick::getcopyright — Returns the GraphicsMagick API copyright as a string

### Beschreibung

public function Gmagick::getcopyright(): string

Returns the GraphicsMagick API copyright as a string.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the copyright notice of GraphicsMagick and Magickwand C API.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getfilename

(PECL gmagick >= Unknown)

Gmagick::getfilename — The filename associated with an image sequence

### Beschreibung

public function Gmagick::getfilename(): string

Returns the filename associated with an image sequence.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::getimagebackgroundcolor — Returns the image background color

### Beschreibung

public function Gmagick::getimagebackgroundcolor(): GmagickPixel

Returns the image background color.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an GmagickPixel set to the background color of the image.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::getimageblueprimary — Returns the chromaticy blue primary point

### Beschreibung

public function Gmagick::getimageblueprimary(): array

Returns the chromaticity blue primary point for the image.

### Parameter-Liste

`x`
  The chromaticity blue primary x-point.
`y`
  The chromaticity blue primary y-point.

### Rückgabewerte

Array consisting of "x" and "y" coordinates of point.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::getimagebordercolor — Returns the image border color

### Beschreibung

public function Gmagick::getimagebordercolor(): GmagickPixel

Returns the image border color.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

GmagickPixel object representing the color of the border.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::getimagechanneldepth — Gets the depth for a particular image channel

### Beschreibung

public function Gmagick::getimagechanneldepth(int `$channel_type`): int

Gets the depth for a particular image channel.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Depth of image channel

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagecolors

(PECL gmagick >= Unknown)

Gmagick::getimagecolors — Returns the color of the specified colormap index

### Beschreibung

public function Gmagick::getimagecolors(): int

Returns the color of the specified colormap index.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The number of colors in image.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::getimagecolorspace — Gets the image colorspace

### Beschreibung

public function Gmagick::getimagecolorspace(): int

Gets the image colorspace.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Colorspace

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagecompose

(PECL gmagick >= Unknown)

Gmagick::getimagecompose — Returns the composite operator associated with the image

### Beschreibung

public function Gmagick::getimagecompose(): int

Returns the composite operator associated with the image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the composite operator associated with the image.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagedelay

(PECL gmagick >= Unknown)

Gmagick::getimagedelay — Gets the image delay

### Beschreibung

public function Gmagick::getimagedelay(): int

Gets the image delay

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the composite operator associated with the image.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagedepth

(PECL gmagick >= Unknown)

Gmagick::getimagedepth — Gets the depth of the image

### Beschreibung

public function Gmagick::getimagedepth(): int

Gets the depth of the image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Image depth

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagedispose

(PECL gmagick >= Unknown)

Gmagick::getimagedispose — Gets the image disposal method

### Beschreibung

public function Gmagick::getimagedispose(): int

Gets the image disposal method

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the dispose method on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageextrema

(PECL gmagick >= Unknown)

Gmagick::getimageextrema — Gets the extrema for the image

### Beschreibung

public function Gmagick::getimageextrema(): array

Returns an associative array with the keys "min" and "max". Wirft bei einem Fehler eine GmagickException.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an associative array with the keys "min" and "max".

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagefilename

(PECL gmagick >= Unknown)

Gmagick::getimagefilename — Returns the filename of a particular image in a sequence

### Beschreibung

public function Gmagick::getimagefilename(): string

Returns the filename of a particular image in a sequence

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string with the filename of the image

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageformat

(PECL gmagick >= Unknown)

Gmagick::getimageformat — Returns the format of a particular image in a sequence

### Beschreibung

public function Gmagick::getimageformat(): string

Returns the format of a particular image in a sequence.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the image format on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagegamma

(PECL gmagick >= Unknown)

Gmagick::getimagegamma — Gets the image gamma

### Beschreibung

public function Gmagick::getimagegamma(): float

Gets the image gamma

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image gamma on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::getimagegreenprimary — Returns the chromaticy green primary point

### Beschreibung

public function Gmagick::getimagegreenprimary(): array

Returns the chromaticity green primary point. Returns an array with the keys "x" and "y".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array with the keys "x" and "y" on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageheight

(PECL gmagick >= Unknown)

Gmagick::getimageheight — Returns the image height

### Beschreibung

public function Gmagick::getimageheight(): int

Returns the image height

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image height in pixels.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagehistogram

(PECL gmagick >= Unknown)

Gmagick::getimagehistogram — Gets the image histogram

### Beschreibung

public function Gmagick::getimagehistogram(): array

Returns the image histogram as an array of GmagickPixel objects. Throw an GmagickException on error.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image histogram as an array of GmagickPixel objects.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageindex

(PECL gmagick >= Unknown)

Gmagick::getimageindex — Gets the index of the current active image

### Beschreibung

public function Gmagick::getimageindex(): int

Returns the index of the current active image within the Gmagick object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Index of current active image.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::getimageinterlacescheme — Gets the image interlace scheme

### Beschreibung

public function Gmagick::getimageinterlacescheme(): int

Gets the image interlace scheme.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the interlace scheme as an integer on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageiterations

(PECL gmagick >= Unknown)

Gmagick::getimageiterations — Gets the image iterations

### Beschreibung

public function Gmagick::getimageiterations(): int

Gets the image iterations.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image iterations as an integer.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagematte

(PECL gmagick >= Unknown)

Gmagick::getimagematte — Check if the image has a matte channel

### Beschreibung

public function Gmagick::getimagematte(): int

Returns `true` if the image has a matte channel, otherwise `false`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the image has a matte channel, otherwise `false`.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagemattecolor

(PECL gmagick >= Unknown)

Gmagick::getimagemattecolor — Returns the image matte color

### Beschreibung

public function Gmagick::getimagemattecolor(): GmagickPixel

Returns GmagickPixel object on success. Throw an GmagickException on error.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns GmagickPixel object on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageprofile

(PECL gmagick >= Unknown)

Gmagick::getimageprofile — Returns the named image profile

### Beschreibung

public function Gmagick::getimageprofile(string `$name`): string

Returns the named image profile.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the image profile.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageredprimary

(PECL gmagick >= Unknown)

Gmagick::getimageredprimary — Returns the chromaticity red primary point

### Beschreibung

public function Gmagick::getimageredprimary(): array

Returns the chromaticity red primary point as an array with the keys "x" and "y".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the chromaticity red primary point as an array with the keys "x" and "y".

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::getimagerenderingintent — Gets the image rendering intent

### Beschreibung

public function Gmagick::getimagerenderingintent(): int

Gets the image rendering intent

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Extracts a region of the image and returns it as a new wand

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageresolution

(PECL gmagick >= Unknown)

Gmagick::getimageresolution — Gets the image X and Y resolution

### Beschreibung

public function Gmagick::getimageresolution(): array

Returns the resolution as an array.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the resolution as an array.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagescene

(PECL gmagick >= Unknown)

Gmagick::getimagescene — Gets the image scene

### Beschreibung

public function Gmagick::getimagescene(): int

Gets the image scene.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image scene.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagesignature

(PECL gmagick >= Unknown)

Gmagick::getimagesignature — Generates an SHA-256 message digest

### Beschreibung

public function Gmagick::getimagesignature(): string

Generates an SHA-256 message digest for the image pixel stream.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the SHA-256 hash of the file.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagetype

(PECL gmagick >= Unknown)

Gmagick::getimagetype — Gets the potential image type

### Beschreibung

public function Gmagick::getimagetype(): int

Gets the potential image type.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the potential image type.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimageunits

(PECL gmagick >= Unknown)

Gmagick::getimageunits — Gets the image units of resolution

### Beschreibung

public function Gmagick::getimageunits(): int

Gets the image units of resolution.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image units of resolution.

# Gmagick::getimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::getimagewhitepoint — Returns the chromaticity white point

### Beschreibung

public function Gmagick::getimagewhitepoint(): array

Returns the chromaticity white point as an associative array with the keys "x" and "y".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the chromaticity white point as an associative array with the keys "x" and "y".

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getimagewidth

(PECL gmagick >= Unknown)

Gmagick::getimagewidth — Returns the width of the image

### Beschreibung

public function Gmagick::getimagewidth(): int

Returns the width of the image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image width.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getpackagename

(PECL gmagick >= Unknown)

Gmagick::getpackagename — Returns the GraphicsMagick package name

### Beschreibung

public function Gmagick::getpackagename(): string

Returns the GraphicsMagick package name.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the GraphicsMagick package name as a string.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getquantumdepth

(PECL gmagick >= Unknown)

Gmagick::getquantumdepth — Returns the Gmagick quantum depth as a string

### Beschreibung

public function Gmagick::getquantumdepth(): array

Returns the Gmagick quantum depth as a string.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the Gmagick quantum depth as a string.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getreleasedate

(PECL gmagick >= Unknown)

Gmagick::getreleasedate — Returns the GraphicsMagick release date as a string

### Beschreibung

public function Gmagick::getreleasedate(): string

Returns the GraphicsMagick release date as a string.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the GraphicsMagick release date as a string.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::getsamplingfactors — Gets the horizontal and vertical sampling factor

### Beschreibung

public function Gmagick::getsamplingfactors(): array

Gets the horizontal and vertical sampling factor.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an associative array with the horizontal and vertical sampling factors of the image.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getsize

(PECL gmagick >= Unknown)

Gmagick::getsize — Returns the size associated with the Gmagick object

### Beschreibung

public function Gmagick::getsize(): array

Returns the size associated with the Gmagick object as an array with the keys "columns" and "rows".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the size associated with the Gmagick object as an array with the keys "columns" and "rows".

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::getversion

(PECL gmagick >= Unknown)

Gmagick::getversion — Returns the GraphicsMagick API version

### Beschreibung

public function Gmagick::getversion(): array

Returns the GraphicsMagick API version as a string and as a number.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the GraphicsMagick API version as a string and as a number.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::hasnextimage

(PECL gmagick >= Unknown)

Gmagick::hasnextimage — Checks if the object has more images

### Beschreibung

public function Gmagick::hasnextimage(): mixed

Returns `true` if the object has more images when traversing the list in the forward direction.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the object has more images when traversing the list in the forward direction, returns `false` if there are none.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::haspreviousimage

(PECL gmagick >= Unknown)

Gmagick::haspreviousimage — Checks if the object has a previous image

### Beschreibung

public function Gmagick::haspreviousimage(): mixed

Returns `true` if the object has more images when traversing the list in the reverse direction.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the object has more images when traversing the list in the reverse direction, returns `false` if there are none.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::implodeimage

(PECL gmagick >= Unknown)

Gmagick::implodeimage — Creates a new image as a copy

### Beschreibung

public function Gmagick::implodeimage(float `$radius`): mixed

Creates a new image that is a copy of an existing one with the image pixels "imploded" by the specified percentage.

### Parameter-Liste

`radius`
  The radius of the implode.

### Rückgabewerte

Returns imploded Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::labelimage

(PECL gmagick >= Unknown)

Gmagick::labelimage — Adds a label to an image

### Beschreibung

public function Gmagick::labelimage(string `$label`): mixed

Adds a label to an image.

### Parameter-Liste

`label`
  The label to add

### Rückgabewerte

Gmagick with label.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::levelimage

(PECL gmagick >= Unknown)

Gmagick::levelimage — Adjusts the levels of an image

### Beschreibung

public function Gmagick::levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed

Adjusts the levels of an image by scaling the colors falling between specified white and black points to the full available quantum range. The parameters provided represent the black, mid, and white points. The black point specifies the darkest color in the image. Colors darker than the black point are set to zero. Mid point specifies a gamma correction to apply to the image. White point specifies the lightest color in the image. Colors brighter than the white point are set to the maximum quantum value.

### Parameter-Liste

`blackPoint`
  The image black point.
`gamma`
  The gamma value.
`whitePoint`
  The image white point.
`channel`
  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Gmagick object with image leveled.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::magnifyimage

(PECL gmagick >= Unknown)

Gmagick::magnifyimage — Scales an image proportionally 2x

### Beschreibung

public function Gmagick::magnifyimage(): mixed

Conveniently scales an image proportionally to twice its original size.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Magnified Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::mapimage

(PECL gmagick >= Unknown)

Gmagick::mapimage — Replaces the colors of an image with the closest color from a reference image

### Beschreibung

public function Gmagick::mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick

Replaces the colors of an image with the closest color from a reference image.

### Parameter-Liste

`gmagick`
  The reference image.
`dither`
  Set this integer value to something other than zero to dither the mapped image.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::medianfilterimage

(PECL gmagick >= Unknown)

Gmagick::medianfilterimage — Applies a digital filter

### Beschreibung

public function Gmagick::medianfilterimage(float `$radius`): void

Applies a digital filter that improves the quality of a noisy image. Each pixel is replaced by the median in a set of neighboring pixels as defined by radius.

### Parameter-Liste

`radius`
  The radius of the pixel neighborhood.

### Rückgabewerte

Gmagick object with median filter applied.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::minifyimage

(PECL gmagick >= Unknown)

Gmagick::minifyimage — Scales an image proportionally to half its size

### Beschreibung

public function Gmagick::minifyimage(): Gmagick

A convenient method that scales an image proportionally to one-half its original size.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::modulateimage

(PECL gmagick >= Unknown)

Gmagick::modulateimage — Control the brightness, saturation, and hue

### Beschreibung

public function Gmagick::modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick

Lets you control the brightness, saturation, and hue of an image. Hue is the percentage of absolute rotation from the current position. For example 50 results in a counter-clockwise rotation of 90 degrees, 150 results in a clockwise rotation of 90 degrees, with 0 and 200 both resulting in a rotation of 180 degrees.

### Parameter-Liste

`brightness`
  The percent change in brighness (-100 thru +100).
`saturation`
  The percent change in saturation (-100 thru +100)
`hue`
  The percent change in hue (-100 thru +100)

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::motionblurimage

(PECL gmagick >= Unknown)

Gmagick::motionblurimage — Simulates motion blur

### Beschreibung

public function Gmagick::motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick

Simulates motion blur. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and Gmagick::motionblurimage() selects a suitable radius for you. Angle gives the angle of the blurring motion.

### Parameter-Liste

`radius`
  The radius of the Gaussian, in pixels, not counting the center pixel.
`sigma`
  The standard deviation of the Gaussian, in pixels.
`angle`
  Apply the effect along this angle.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::newimage

(PECL gmagick >= Unknown)

Gmagick::newimage — Creates a new image

### Beschreibung

public function Gmagick::newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick

Creates a new image with the specified background color.

### Parameter-Liste

`width`
  Width of the new image.
`height`
  Height of the new image.
`background`
  The background color used for this image (as float).
`format`
  Image format.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::nextimage

(PECL gmagick >= Unknown)

Gmagick::nextimage — Moves to the next image

### Beschreibung

public function Gmagick::nextimage(): bool

Associates the next image in the image list with an Gmagick object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::normalizeimage

(PECL gmagick >= Unknown)

Gmagick::normalizeimage — Enhances the contrast of a color image

### Beschreibung

public function Gmagick::normalizeimage(int `$channel` = ?): Gmagick

Enhances the contrast of a color image by adjusting the pixels color to span the entire range of colors available.

### Parameter-Liste

`channel`
  Identify which channel to normalize.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::oilpaintimage

(PECL gmagick >= Unknown)

Gmagick::oilpaintimage — Simulates an oil painting

### Beschreibung

public function Gmagick::oilpaintimage( float `$radius` ): Gmagick

Applies a special effect filter that simulates an oil painting. Each pixel is replaced by the most frequent color occurring in a circular region defined by radius.

### Parameter-Liste

`radius`
  The radius of the circular neighborhood.

### Rückgabewerte

The Gmagick object on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::previousimage

(PECL gmagick >= Unknown)

Gmagick::previousimage — Move to the previous image in the object

### Beschreibung

public function Gmagick::previousimage(): bool

Associates the previous image in an image list with the Gmagick object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::profileimage

(PECL gmagick >= Unknown)

Gmagick::profileimage — Adds or removes a profile from an image

### Beschreibung

public function Gmagick::profileimage(string `$name`, string `$profile`): Gmagick

Adds or removes a ICC, IPTC, or generic profile from an image. If the profile is `null`, it is removed from the image otherwise added. Use a name of `*` and a profile of `null` to remove all profiles from the image.

### Parameter-Liste

`name`
  Name of profile to add or remove: ICC, IPTC, or generic profile.
`profile`
  The profile.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::quantizeimage

(PECL gmagick >= Unknown)

Gmagick::quantizeimage — Analyzes the colors within a reference image

### Beschreibung

public function Gmagick::quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Analyzes the colors within a reference image and chooses a fixed number of colors to represent the image. The goal of the algorithm is to minimize the color difference between the input and output image while minimizing the processing time.

### Parameter-Liste

`numColors`
  The number of colors.
`colorspace`
  Perform color reduction in this colorspace, typically RGBColorspace.
`treeDepth`
  Normally, this integer value is zero or one. A zero or one tells Quantize to choose a optimal tree depth of Log4(number_colors).% A tree of this depth generally allows the best representation of the reference image with the least amount of memory and the fastest computational speed. In some cases, such as an image with low color dispersion (a few number of colors), a value other than Log4(number_colors) is required. To expand the color tree completely, use a value of 8.
`dither`
  A value other than zero distributes the difference between an original image and the corresponding color reduced algorithm to neighboring pixels along a Hilbert curve.
`measureError`
  A value other than zero measures the difference between the original and quantized images. This difference is the total quantization error. The error is computed by summing over all pixels in an image the distance squared in RGB space between each reference pixel value and its quantized value.

### Rückgabewerte

The Gmagick object on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::quantizeimages

(PECL gmagick >= Unknown)

Gmagick::quantizeimages — The quantizeimages purpose

### Beschreibung

public function Gmagick::quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick

Analyzes the colors within a sequence of images and chooses a fixed number of colors to represent the image. The goal of the algorithm is to minimize the color difference between the input and output image while minimizing the processing time.

### Parameter-Liste

`numColors`
  The number of colors.
`colorspace`
  Perform color reduction in this colorspace, typically RGBColorspace.
`treeDepth`
  Normally, this integer value is zero or one. A zero or one tells Quantize to choose a optimal tree depth of Log4(number_colors).% A tree of this depth generally allows the best representation of the reference image with the least amount of memory and the fastest computational speed. In some cases, such as an image with low color dispersion (a few number of colors), a value other than Log4(number_colors) is required. To expand the color tree completely, use a value of 8.
`dither`
  A value other than zero distributes the difference between an original image and the corresponding color reduced algorithm to neighboring pixels along a Hilbert curve.
`measureError`
  A value other than zero measures the difference between the original and quantized images. This difference is the total quantization error. The error is computed by summing over all pixels in an image the distance squared in RGB space between each reference pixel value and its quantized value.

### Rückgabewerte

The Gmagick object on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::queryfontmetrics

(PECL gmagick >= Unknown)

Gmagick::queryfontmetrics — Returns an array representing the font metrics

### Beschreibung

public function Gmagick::queryfontmetrics(GmagickDraw `$draw`, string `$text`): array

MagickQueryFontMetrics() returns an array representing the font metrics.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The Gmagick object on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::queryfonts

(PECL gmagick >= Unknown)

Gmagick::queryfonts — Returns the configured fonts

### Beschreibung

public function Gmagick::queryfonts(string `$pattern` = "*"): array

Returns fonts supported by Gmagick.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The Gmagick object on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::queryformats

(PECL gmagick >= Unknown)

Gmagick::queryformats — Returns formats supported by Gmagick

### Beschreibung

public function Gmagick::queryformats(string `$pattern` = "*"): array

Returns formats supported by Gmagick.

### Parameter-Liste

`pattern`
  Specifies a string containing a pattern.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::radialblurimage

(PECL gmagick >= Unknown)

Gmagick::radialblurimage — Radial blurs an image

### Beschreibung

public function Gmagick::radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick

Radial blurs an image.

### Parameter-Liste

`angle`
  The angle of the blur in degrees.
`channel`
  Related channel.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::raiseimage

(PECL gmagick >= Unknown)

Gmagick::raiseimage — Creates a simulated 3d button-like effect

### Beschreibung

public function Gmagick::raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick

Creates a simulated three-dimensional button-like effect by lightening and darkening the edges of the image. Members width and height of raise_info define the width of the vertical and horizontal edge of the effect.

### Parameter-Liste

`width`
  Width of the area to raise.
`height`
  Height of the area to raise.
`x`
  X coordinate.
`y`
  Y coordinate.
`raise`
  A value other than zero creates a 3-D raise effect, otherwise it has a lowered effect.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::read

(PECL gmagick >= Unknown)

Gmagick::read — Reads image from filename

### Beschreibung

public function Gmagick::read(string `$filename`): Gmagick

Reads image from filename.

### Parameter-Liste

`filename`
  The image filename.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::readimage

(PECL gmagick >= Unknown)

Gmagick::readimage — Reads image from filename

### Beschreibung

public function Gmagick::readimage(string `$filename`): Gmagick

Reads image from filename.

### Parameter-Liste

`filename`
  The image filename.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::readimageblob

(PECL gmagick >= Unknown)

Gmagick::readimageblob — Reads image from a binary string

### Beschreibung

public function Gmagick::readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick

Reads image from a binary string.

### Parameter-Liste

`imageContents`
  Content of image.
`filename`
  The image filename.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::readimagefile

(PECL gmagick >= Unknown)

Gmagick::readimagefile — The readimagefile purpose

### Beschreibung

public function Gmagick::readimagefile(resource `$fp`, string `$filename` = ?): Gmagick

Reads an image or image sequence from an open file descriptor.

### Parameter-Liste

`fp`
  The file descriptor.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::reducenoiseimage

(PECL gmagick >= Unknown)

Gmagick::reducenoiseimage — Smooths the contours of an image

### Beschreibung

public function Gmagick::reducenoiseimage(float `$radius`): Gmagick

Smooths the contours of an image while still preserving edge information. The algorithm works by replacing each pixel with its neighbor closest in value. A neighbor is defined by radius. Use a radius of 0 and Gmagick::reducenoiseimage() selects a suitable radius for you.

### Parameter-Liste

`radius`
  The radius of the pixel neighborhood.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::removeimage

(PECL gmagick >= Unknown)

Gmagick::removeimage — Removes an image from the image list

### Beschreibung

public function Gmagick::removeimage(): Gmagick

Removes an image from the image list.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::removeimageprofile

(PECL gmagick >= Unknown)

Gmagick::removeimageprofile — Removes the named image profile and returns it

### Beschreibung

public function Gmagick::removeimageprofile(string `$name`): string

Removes the named image profile and returns it.

### Parameter-Liste

`name`
  Name of profile to return: ICC, IPTC, or generic profile.

### Rückgabewerte

The named profile.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::resampleimage

(PECL gmagick >= Unknown)

Gmagick::resampleimage — Resample image to desired resolution

### Beschreibung

public function Gmagick::resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick

Resample image to desired resolution.

### Parameter-Liste

`xResolution`
  The new image x resolution.
`yResolution`
  The new image y resolution.
`filter`
  Image filter to use.
`blur`
  The blur factor where larger than 1 is blurry, smaller than 1 is sharp.

### Rückgabewerte

The Gmagick object on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::resizeimage

(PECL gmagick >= Unknown)

Gmagick::resizeimage — Scales an image

### Beschreibung

public function Gmagick::resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick

Scales an image to the desired dimensions with a filter.

### Parameter-Liste

`width`
  The number of columns in the scaled image.
`height`
  The number of rows in the scaled image.
`filter`
  Image filter to use.
`blur`
  The blur factor where larger than 1 is blurry, lesser than 1 is sharp.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::rollimage

(PECL gmagick >= Unknown)

Gmagick::rollimage — Offsets an image

### Beschreibung

public function Gmagick::rollimage(int `$x`, int `$y`): Gmagick

Offsets an image as defined by x and y.

### Parameter-Liste

`x`
  The x offset.
`y`
  The y offset.

### Rückgabewerte

The Gmagick object on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::rotateimage

(PECL gmagick >= Unknown)

Gmagick::rotateimage — Rotates an image

### Beschreibung

public function Gmagick::rotateimage(mixed `$color`, float `$degrees`): Gmagick

Rotates an image the specified number of degrees. Empty triangles left over from rotating the image are filled with the background color.

### Parameter-Liste

`color`
  The background pixel.
`degrees`
  The number of degrees to rotate the image.

### Rückgabewerte

The Gmagick object on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::scaleimage

(PECL gmagick >= Unknown)

Gmagick::scaleimage — Scales the size of an image

### Beschreibung

public function Gmagick::scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Scales the size of an image to the given dimensions. The other parameter will be calculated if 0 is passed as either param.

### Parameter-Liste

`width`
  The number of columns in the scaled image.
`height`
  The number of rows in the scaled image.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::separateimagechannel

(PECL gmagick >= Unknown)

Gmagick::separateimagechannel — Separates a channel from the image

### Beschreibung

public function Gmagick::separateimagechannel(int `$channel`): Gmagick

Separates a channel from the image and returns a grayscale image. A channel is a particular color component of each pixel in the image.

### Parameter-Liste

`channel`
  One of the Channel constant (`Gmagick::CHANNEL_*`).

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setCompressionQuality

(No version information available, might only be in Git)

Gmagick::setCompressionQuality — Sets the object's default compression quality

### Beschreibung

function Gmagick::setCompressionQuality( int `$quality` ): Gmagick

Sets the object's default compression quality.

### Parameter-Liste

`quality`
  The GraphicsMagick default value is 75.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

### Beispiele

Beispiel #1 Gmagick::setCompressionQuality()

    <?php
    $gm = new Gmagick();
    $gm->read("magick:rose");
    $gm->setCompressionQuality(2);
    ?>

# Gmagick::setfilename

(PECL gmagick >= Unknown)

Gmagick::setfilename — Sets the filename before you read or write the image

### Beschreibung

public function Gmagick::setfilename(string `$filename`): Gmagick

Sets the filename before you read or write an image file.

### Parameter-Liste

`filename`
  The image filename.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::setimagebackgroundcolor — Sets the image background color

### Beschreibung

public function Gmagick::setimagebackgroundcolor(GmagickPixel `$color`): Gmagick

Sets the image background color.

### Parameter-Liste

`color`
  The background pixel wand.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::setimageblueprimary — Sets the image chromaticity blue primary point

### Beschreibung

public function Gmagick::setimageblueprimary(float `$x`, float `$y`): Gmagick

Sets the image chromaticity blue primary point.

### Parameter-Liste

`x`
  The blue primary x-point.
`y`
  The blue primary y-point.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::setimagebordercolor — Sets the image border color

### Beschreibung

public function Gmagick::setimagebordercolor(GmagickPixel `$color`): Gmagick

Sets the image border color.

### Parameter-Liste

`color`
  The border pixel wand.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::setimagechanneldepth — Sets the depth of a particular image channel

### Beschreibung

public function Gmagick::setimagechanneldepth(int `$channel`, int `$depth`): Gmagick

Sets the depth of a particular image channel.

### Parameter-Liste

`channel`
  One of the Channel constant (`Gmagick::CHANNEL_*`).
`depth`
  The image depth in bits.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::setimagecolorspace — Sets the image colorspace

### Beschreibung

public function Gmagick::setimagecolorspace(int `$colorspace`): Gmagick

Sets the image colorspace.

### Parameter-Liste

`colorspace`
  One of the Colorspace constant (`Gmagick::COLORSPACE_*`).

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagecompose

(PECL gmagick >= Unknown)

Gmagick::setimagecompose — Sets the image composite operator

### Beschreibung

public function Gmagick::setimagecompose(int `$composite`): Gmagick

Sets the image composite operator.

### Parameter-Liste

`composite`
  The image composite operator.

### Rückgabewerte

The Gmagick object on success

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagedelay

(PECL gmagick >= Unknown)

Gmagick::setimagedelay — Sets the image delay

### Beschreibung

public function Gmagick::setimagedelay(int `$delay`): Gmagick

Sets the image delay.

### Parameter-Liste

`delay`
  The image delay in 1/100th of a second.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagedepth

(PECL gmagick >= Unknown)

Gmagick::setimagedepth — Sets the image depth

### Beschreibung

public function Gmagick::setimagedepth(int `$depth`): Gmagick

Sets the image depth.

### Parameter-Liste

`depth`
  The image depth in bits: 8, 16, or 32.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagedispose

(PECL gmagick >= Unknown)

Gmagick::setimagedispose — Sets the image disposal method

### Beschreibung

public function Gmagick::setimagedispose(int `$disposeType`): Gmagick

Sets the image disposal method.

### Parameter-Liste

`disposeType`
  The image disposal type.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagefilename

(PECL gmagick >= Unknown)

Gmagick::setimagefilename — Sets the filename of a particular image in a sequence

### Beschreibung

public function Gmagick::setimagefilename(string `$filename`): Gmagick

Sets the filename of a particular image in a sequence.

### Parameter-Liste

`filename`
  The image filename.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimageformat

(PECL gmagick >= Unknown)

Gmagick::setimageformat — Sets the format of a particular image

### Beschreibung

public function Gmagick::setimageformat(string `$imageFormat`): Gmagick

Sets the format of a particular image in a sequence.

### Parameter-Liste

`imageFormat`
  The image format.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagegamma

(PECL gmagick >= Unknown)

Gmagick::setimagegamma — Sets the image gamma

### Beschreibung

public function Gmagick::setimagegamma(float `$gamma`): Gmagick

Sets the image gamma.

### Parameter-Liste

`gamma`
  The image gamma.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::setimagegreenprimary — Sets the image chromaticity green primary point

### Beschreibung

public function Gmagick::setimagegreenprimary(float `$x`, float `$y`): Gmagick

Sets the image chromaticity green primary point.

### Parameter-Liste

`x`
  The chromaticity green primary x-point.
`y`
  The chromaticity green primary y-point.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimageindex

(PECL gmagick >= Unknown)

Gmagick::setimageindex — Set the iterator to the position in the image list specified with the index parameter

### Beschreibung

public function Gmagick::setimageindex(int `$index`): Gmagick

Set the iterator to the position in the image list specified with the index parameter.

### Parameter-Liste

`index`
  The scene number.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::setimageinterlacescheme — Sets the interlace scheme of the image

### Beschreibung

public function Gmagick::setimageinterlacescheme(int `$interlace`): Gmagick

Sets the interlace scheme of the image.

### Parameter-Liste

`interlace`
  One of the Interlace constant (`Gmagick::INTERLACE_*`).

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimageiterations

(PECL gmagick >= Unknown)

Gmagick::setimageiterations — Sets the image iterations

### Beschreibung

public function Gmagick::setimageiterations(int `$iterations`): Gmagick

Sets the image iterations.

### Parameter-Liste

`iterations`
  The image delay in 1/100th of a second.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimageprofile

(PECL gmagick >= Unknown)

Gmagick::setimageprofile — Adds a named profile to the Gmagick object

### Beschreibung

public function Gmagick::setimageprofile(string `$name`, string `$profile`): Gmagick

Adds a named profile to the Gmagick object. If a profile with the same name already exists, it is replaced. This method differs from the Gmagick::profileimage() method in that it does not apply any CMS color profiles.

### Parameter-Liste

`name`
  Name of profile to add or remove: ICC, IPTC, or generic profile.
`profile`
  The profile.

### Rückgabewerte

The Gmagick object on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimageredprimary

(PECL gmagick >= Unknown)

Gmagick::setimageredprimary — Sets the image chromaticity red primary point

### Beschreibung

public function Gmagick::setimageredprimary(float `$x`, float `$y`): Gmagick

Sets the image chromaticity red primary point.

### Parameter-Liste

`x`
  The red primary x-point.
`y`
  The red primary y-point.

### Rückgabewerte

The Gmagick object on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::setimagerenderingintent — Sets the image rendering intent

### Beschreibung

public function Gmagick::setimagerenderingintent(int `$rendering_intent`): Gmagick

Sets the image rendering intent.

### Parameter-Liste

`rendering_intent`
  One of the Rendering Intent constant (`Gmagick::RENDERINGINTENT_*`).

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimageresolution

(PECL gmagick >= Unknown)

Gmagick::setimageresolution — Sets the image resolution

### Beschreibung

public function Gmagick::setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick

Sets the image resolution.

### Parameter-Liste

`xResolution`
  The image x resolution.
`yResolution`
  The image y resolution.

### Rückgabewerte

The Gmagick object on success.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagescene

(PECL gmagick >= Unknown)

Gmagick::setimagescene — Sets the image scene

### Beschreibung

public function Gmagick::setimagescene(int `$scene`): Gmagick

Sets the image scene.

### Parameter-Liste

`scene`
  The image scene number.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagetype

(PECL gmagick >= Unknown)

Gmagick::setimagetype — Sets the image type

### Beschreibung

public function Gmagick::setimagetype(int `$imgType`): Gmagick

Sets the image type.

### Parameter-Liste

`imgType`
  One of the Image type constant (`Gmagick::IMGTYPE_*`).

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimageunits

(PECL gmagick >= Unknown)

Gmagick::setimageunits — Sets the image units of resolution

### Beschreibung

public function Gmagick::setimageunits(int `$resolution`): Gmagick

Sets the image units of resolution.

### Parameter-Liste

`resolution`
  One of the Resolution constant (`Gmagick::RESOLUTION_*`).

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::setimagewhitepoint — Sets the image chromaticity white point

### Beschreibung

public function Gmagick::setimagewhitepoint(float `$x`, float `$y`): Gmagick

Sets the image chromaticity white point.

### Parameter-Liste

`x`
  The white x-point.
`y`
  The white y-point.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::setsamplingfactors — Sets the image sampling factors

### Beschreibung

public function Gmagick::setsamplingfactors(array `$factors`): Gmagick

Sets the image sampling factors.

### Parameter-Liste

`factors`
  An array of floats representing the sampling factor for each color component (in RGB order).

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::setsize

(PECL gmagick >= Unknown)

Gmagick::setsize — Sets the size of the Gmagick object

### Beschreibung

public function Gmagick::setsize(int `$columns`, int `$rows`): Gmagick

Sets the size of the Gmagick object. Set it before you read a raw image format such as `Gmagick::COLORSPACE_RGB`, `Gmagick::COLORSPACE_GRAY`, or `Gmagick::COLORSPACE_CMYK`.

### Parameter-Liste

`columns`
  The width in pixels.
`rows`
  The height in pixels.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::shearimage

(PECL gmagick >= Unknown)

Gmagick::shearimage — Creating a parallelogram

### Beschreibung

public function Gmagick::shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick

Slides one edge of an image along the X or Y axis, creating a parallelogram. An X direction shear slides an edge along the X axis, while a Y direction shear slides an edge along the Y axis. The amount of the shear is controlled by a shear angle. For X direction shears, x_shear is measured relative to the Y axis, and similarly, for Y direction shears y_shear is measured relative to the X axis. Empty triangles left over from shearing the image are filled with the background color.

### Parameter-Liste

`color`
  The background pixel wand.
`xShear`
  The number of degrees to shear the image.
`yShear`
  The number of degrees to shear the image.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::solarizeimage

(PECL gmagick >= Unknown)

Gmagick::solarizeimage — Applies a solarizing effect to the image

### Beschreibung

public function Gmagick::solarizeimage(int `$threshold`): Gmagick

Applies a special effect to the image, similar to the effect achieved in a photo darkroom by selectively exposing areas of photo sensitive paper to light. Threshold ranges from 0 to QuantumRange and is a measure of the extent of the solarization.

### Parameter-Liste

`threshold`
  Define the extent of the solarization.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::spreadimage

(PECL gmagick >= Unknown)

Gmagick::spreadimage — Randomly displaces each pixel in a block

### Beschreibung

public function Gmagick::spreadimage(float `$radius`): Gmagick

Special effects method that randomly displaces each pixel in a block defined by the radius parameter.

### Parameter-Liste

`radius`
  Choose a random pixel in a neighborhood of this extent.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::stripimage

(PECL gmagick >= Unknown)

Gmagick::stripimage — Strips an image of all profiles and comments

### Beschreibung

public function Gmagick::stripimage(): Gmagick

Strips an image of all profiles and comments.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::swirlimage

(PECL gmagick >= Unknown)

Gmagick::swirlimage — Swirls the pixels about the center of the image

### Beschreibung

public function Gmagick::swirlimage(float `$degrees`): Gmagick

Swirls the pixels about the center of the image, where degrees indicates the sweep of the arc through which each pixel is moved. You get a more dramatic effect as the degrees move from 1 to 360.

### Parameter-Liste

`degrees`
  Define the tightness of the swirling effect.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::thumbnailimage

(PECL gmagick >= Unknown)

Gmagick::thumbnailimage — Changes the size of an image

### Beschreibung

public function Gmagick::thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

Changes the size of an image to the given dimensions and removes any associated profiles. The goal is to produce small low cost thumbnail images suited for display on the Web. If `true` is given as a third parameter then columns and rows parameters are used as maximums for each side. Both sides will be scaled down until the match or are smaller than the parameter given for the side.

### Parameter-Liste

`width`
  Image width.
`height`
  Image height.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::trimimage

(PECL gmagick >= Unknown)

Gmagick::trimimage — Remove edges from the image

### Beschreibung

public function Gmagick::trimimage(float `$fuzz`): Gmagick

Remove edges that are the background color from the image.

### Parameter-Liste

`fuzz`
  By default target must match a particular pixel color exactly. However, in many cases two colors may differ by a small amount. The fuzz member of image defines how much tolerance is acceptable to consider two colors as the same. This parameter represents the variation on the quantum range.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

# Gmagick::write

(PECL gmagick >= Unknown)

Gmagick::write — Alias von Gmagick::writeimage()

### Beschreibung

Diese Methode ist ein Alias für: Gmagick::writeimage().

# Gmagick::writeimage

(PECL gmagick >= Unknown)

Gmagick::writeimage — Writes an image to the specified filename

### Beschreibung

public function Gmagick::writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick

Writes an image to the specified filename. If the filename parameter is `null`, the image is written to the filename set by Gmagick::readimage() or Gmagick::setimagefilename().

### Parameter-Liste

`filename`
  The image filename.

### Rückgabewerte

The Gmagick object.

### Fehler/Exceptions

Wirft bei einem Fehler eine GmagickException.

## Inhaltsverzeichnis

- Gmagick::addimage — Adds new image to Gmagick object image list
- Gmagick::addnoiseimage — Adds random noise to the image
- Gmagick::annotateimage — Annotates an image with text
- Gmagick::blurimage — Adds blur filter to image
- Gmagick::borderimage — Surrounds the image with a border
- Gmagick::charcoalimage — Simulates a charcoal drawing
- Gmagick::chopimage — Removes a region of an image and trims
- Gmagick::clear — Clears all resources associated to Gmagick object
- Gmagick::commentimage — Adds a comment to your image
- Gmagick::compositeimage — Composite one image onto another
- Gmagick::__construct — The Gmagick constructor
- Gmagick::cropimage — Extracts a region of the image
- Gmagick::cropthumbnailimage — Creates a crop thumbnail
- Gmagick::current — The current purpose
- Gmagick::cyclecolormapimage — Displaces an image's colormap
- Gmagick::deconstructimages — Returns certain pixel differences between images
- Gmagick::despeckleimage — The despeckleimage purpose
- Gmagick::destroy — The destroy purpose
- Gmagick::drawimage — Renders the GmagickDraw object on the current image
- Gmagick::edgeimage — Enhance edges within the image
- Gmagick::embossimage — Returns a grayscale image with a three-dimensional effect
- Gmagick::enhanceimage — Improves the quality of a noisy image
- Gmagick::equalizeimage — Equalizes the image histogram
- Gmagick::flipimage — Creates a vertical mirror image
- Gmagick::flopimage — Creates a horizontal mirror image
- Gmagick::frameimage — Adds a simulated three-dimensional border
- Gmagick::gammaimage — Gamma-corrects an image
- Gmagick::getcopyright — Returns the GraphicsMagick API copyright as a string
- Gmagick::getfilename — The filename associated with an image sequence
- Gmagick::getimagebackgroundcolor — Returns the image background color
- Gmagick::getimageblueprimary — Returns the chromaticy blue primary point
- Gmagick::getimagebordercolor — Returns the image border color
- Gmagick::getimagechanneldepth — Gets the depth for a particular image channel
- Gmagick::getimagecolors — Returns the color of the specified colormap index
- Gmagick::getimagecolorspace — Gets the image colorspace
- Gmagick::getimagecompose — Returns the composite operator associated with the image
- Gmagick::getimagedelay — Gets the image delay
- Gmagick::getimagedepth — Gets the depth of the image
- Gmagick::getimagedispose — Gets the image disposal method
- Gmagick::getimageextrema — Gets the extrema for the image
- Gmagick::getimagefilename — Returns the filename of a particular image in a sequence
- Gmagick::getimageformat — Returns the format of a particular image in a sequence
- Gmagick::getimagegamma — Gets the image gamma
- Gmagick::getimagegreenprimary — Returns the chromaticy green primary point
- Gmagick::getimageheight — Returns the image height
- Gmagick::getimagehistogram — Gets the image histogram
- Gmagick::getimageindex — Gets the index of the current active image
- Gmagick::getimageinterlacescheme — Gets the image interlace scheme
- Gmagick::getimageiterations — Gets the image iterations
- Gmagick::getimagematte — Check if the image has a matte channel
- Gmagick::getimagemattecolor — Returns the image matte color
- Gmagick::getimageprofile — Returns the named image profile
- Gmagick::getimageredprimary — Returns the chromaticity red primary point
- Gmagick::getimagerenderingintent — Gets the image rendering intent
- Gmagick::getimageresolution — Gets the image X and Y resolution
- Gmagick::getimagescene — Gets the image scene
- Gmagick::getimagesignature — Generates an SHA-256 message digest
- Gmagick::getimagetype — Gets the potential image type
- Gmagick::getimageunits — Gets the image units of resolution
- Gmagick::getimagewhitepoint — Returns the chromaticity white point
- Gmagick::getimagewidth — Returns the width of the image
- Gmagick::getpackagename — Returns the GraphicsMagick package name
- Gmagick::getquantumdepth — Returns the Gmagick quantum depth as a string
- Gmagick::getreleasedate — Returns the GraphicsMagick release date as a string
- Gmagick::getsamplingfactors — Gets the horizontal and vertical sampling factor
- Gmagick::getsize — Returns the size associated with the Gmagick object
- Gmagick::getversion — Returns the GraphicsMagick API version
- Gmagick::hasnextimage — Checks if the object has more images
- Gmagick::haspreviousimage — Checks if the object has a previous image
- Gmagick::implodeimage — Creates a new image as a copy
- Gmagick::labelimage — Adds a label to an image
- Gmagick::levelimage — Adjusts the levels of an image
- Gmagick::magnifyimage — Scales an image proportionally 2x
- Gmagick::mapimage — Replaces the colors of an image with the closest color from a reference image
- Gmagick::medianfilterimage — Applies a digital filter
- Gmagick::minifyimage — Scales an image proportionally to half its size
- Gmagick::modulateimage — Control the brightness, saturation, and hue
- Gmagick::motionblurimage — Simulates motion blur
- Gmagick::newimage — Creates a new image
- Gmagick::nextimage — Moves to the next image
- Gmagick::normalizeimage — Enhances the contrast of a color image
- Gmagick::oilpaintimage — Simulates an oil painting
- Gmagick::previousimage — Move to the previous image in the object
- Gmagick::profileimage — Adds or removes a profile from an image
- Gmagick::quantizeimage — Analyzes the colors within a reference image
- Gmagick::quantizeimages — The quantizeimages purpose
- Gmagick::queryfontmetrics — Returns an array representing the font metrics
- Gmagick::queryfonts — Returns the configured fonts
- Gmagick::queryformats — Returns formats supported by Gmagick
- Gmagick::radialblurimage — Radial blurs an image
- Gmagick::raiseimage — Creates a simulated 3d button-like effect
- Gmagick::read — Reads image from filename
- Gmagick::readimage — Reads image from filename
- Gmagick::readimageblob — Reads image from a binary string
- Gmagick::readimagefile — The readimagefile purpose
- Gmagick::reducenoiseimage — Smooths the contours of an image
- Gmagick::removeimage — Removes an image from the image list
- Gmagick::removeimageprofile — Removes the named image profile and returns it
- Gmagick::resampleimage — Resample image to desired resolution
- Gmagick::resizeimage — Scales an image
- Gmagick::rollimage — Offsets an image
- Gmagick::rotateimage — Rotates an image
- Gmagick::scaleimage — Scales the size of an image
- Gmagick::separateimagechannel — Separates a channel from the image
- Gmagick::setCompressionQuality — Sets the object's default compression quality
- Gmagick::setfilename — Sets the filename before you read or write the image
- Gmagick::setimagebackgroundcolor — Sets the image background color
- Gmagick::setimageblueprimary — Sets the image chromaticity blue primary point
- Gmagick::setimagebordercolor — Sets the image border color
- Gmagick::setimagechanneldepth — Sets the depth of a particular image channel
- Gmagick::setimagecolorspace — Sets the image colorspace
- Gmagick::setimagecompose — Sets the image composite operator
- Gmagick::setimagedelay — Sets the image delay
- Gmagick::setimagedepth — Sets the image depth
- Gmagick::setimagedispose — Sets the image disposal method
- Gmagick::setimagefilename — Sets the filename of a particular image in a sequence
- Gmagick::setimageformat — Sets the format of a particular image
- Gmagick::setimagegamma — Sets the image gamma
- Gmagick::setimagegreenprimary — Sets the image chromaticity green primary point
- Gmagick::setimageindex — Set the iterator to the position in the image list specified with the index parameter
- Gmagick::setimageinterlacescheme — Sets the interlace scheme of the image
- Gmagick::setimageiterations — Sets the image iterations
- Gmagick::setimageprofile — Adds a named profile to the Gmagick object
- Gmagick::setimageredprimary — Sets the image chromaticity red primary point
- Gmagick::setimagerenderingintent — Sets the image rendering intent
- Gmagick::setimageresolution — Sets the image resolution
- Gmagick::setimagescene — Sets the image scene
- Gmagick::setimagetype — Sets the image type
- Gmagick::setimageunits — Sets the image units of resolution
- Gmagick::setimagewhitepoint — Sets the image chromaticity white point
- Gmagick::setsamplingfactors — Sets the image sampling factors
- Gmagick::setsize — Sets the size of the Gmagick object
- Gmagick::shearimage — Creating a parallelogram
- Gmagick::solarizeimage — Applies a solarizing effect to the image
- Gmagick::spreadimage — Randomly displaces each pixel in a block
- Gmagick::stripimage — Strips an image of all profiles and comments
- Gmagick::swirlimage — Swirls the pixels about the center of the image
- Gmagick::thumbnailimage — Changes the size of an image
- Gmagick::trimimage — Remove edges from the image
- Gmagick::write — Alias von Gmagick::writeimage
- Gmagick::writeimage — Writes an image to the specified filename

# The GmagickDraw class

(PECL gmagick >= Unknown)

## Einführung

## Klassenbeschreibung

class GmagickDraw {
/* Methoden */
public function annotate(float `$x`, float `$y`, string `$text`): GmagickDraw
public function arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw
public function bezier(array `$coordinate_array`): GmagickDraw
public function ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw
public function getfillcolor(): GmagickPixel
public function getfillopacity(): float
public function getfont(): mixed
public function getfontsize(): float
public function getfontstyle(): int
public function getfontweight(): int
public function getstrokecolor(): GmagickPixel
public function getstrokeopacity(): float
public function getstrokewidth(): float
public function gettextdecoration(): int
public function gettextencoding(): mixed
public function line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw
public function point(float `$x`, float `$y`): GmagickDraw
public function polygon(array `$coordinates`): GmagickDraw
public function polyline(array `$coordinate_array`): GmagickDraw
public function rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw
public function rotate(float `$degrees`): GmagickDraw
public function roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw
public function scale(float `$x`, float `$y`): GmagickDraw
public function setfillcolor(mixed `$color`): GmagickDraw
public function setfillopacity(float `$fill_opacity`): GmagickDraw
public function setfont(string `$font`): GmagickDraw
public function setfontsize(float `$pointsize`): GmagickDraw
public function setfontstyle(int `$style`): GmagickDraw
public function setfontweight(int `$weight`): GmagickDraw
public function setstrokecolor(mixed `$color`): GmagickDraw
public function setstrokeopacity(float `$stroke_opacity`): GmagickDraw
public function setstrokewidth(float `$width`): GmagickDraw
public function settextdecoration(int `$decoration`): GmagickDraw
public function settextencoding(string `$encoding`): GmagickDraw
}

# GmagickDraw::annotate

(PECL gmagick >= Unknown)

GmagickDraw::annotate — Draws text on the image

### Beschreibung

public function GmagickDraw::annotate(float `$x`, float `$y`, string `$text`): GmagickDraw

Draws text on the image.

### Parameter-Liste

`x`
  x ordinate to left of text
`y`
  y ordinate to text baseline
`text`
  text to draw

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::arc

(PECL gmagick >= Unknown)

GmagickDraw::arc — Draws an arc

### Beschreibung

public function GmagickDraw::arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw

Draws an arc falling within a specified bounding rectangle on the image.

### Parameter-Liste

`sx`
  starting x ordinate of bounding rectangle
`sy`
  starting y ordinate of bounding rectangle
`ex`
  ending x ordinate of bounding rectangle
`ey`
  ending y ordinate of bounding rectangle
`sd`
  starting degrees of rotation
`ed`
  ending degrees of rotation

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::bezier

(PECL gmagick >= Unknown)

GmagickDraw::bezier — Draws a bezier curve

### Beschreibung

public function GmagickDraw::bezier(array `$coordinate_array`): GmagickDraw

Draws a bezier curve through a set of points on the image.

### Parameter-Liste

`coordinate_array`
  Coordinates array

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::ellipse

(PECL gmagick >= Unknown)

GmagickDraw::ellipse — Draws an ellipse on the image

### Beschreibung

public function GmagickDraw::ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw

Draws an ellipse on the image.

### Parameter-Liste

`ox`
  origin x ordinate
`oy`
  origin y ordinate
`rx`
  radius in x
`ry`
  radius in y
`start`
  starting rotation in degrees
`end`
  ending rotation in degrees

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::getfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::getfillcolor — Returns the fill color

### Beschreibung

public function GmagickDraw::getfillcolor(): GmagickPixel

Returns the fill color used for drawing filled objects.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The GmagickPixel fill color used for drawing filled objects.

# GmagickDraw::getfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::getfillopacity — Returns the opacity used when drawing

### Beschreibung

public function GmagickDraw::getfillopacity(): float

Returns the opacity used when drawing

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the opacity used when drawing using the fill color or fill texture. Fully opaque is 1.0.

# GmagickDraw::getfont

(PECL gmagick >= Unknown)

GmagickDraw::getfont — Returns the font

### Beschreibung

public function GmagickDraw::getfont(): mixed

Returns a string specifying the font used when annotating with text.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string on success and `false` if no font is set.

# GmagickDraw::getfontsize

(PECL gmagick >= Unknown)

GmagickDraw::getfontsize — Returns the font pointsize

### Beschreibung

public function GmagickDraw::getfontsize(): float

Returns the font pointsize used when annotating with text.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the font size associated with the current GmagickDraw object.

# GmagickDraw::getfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::getfontstyle — Returns the font style

### Beschreibung

public function GmagickDraw::getfontstyle(): int

Returns the font style used when annotating with text.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the font style constant (STYLE_) associated with the GmagickDraw object or `0` if no style is set.

# GmagickDraw::getfontweight

(PECL gmagick >= Unknown)

GmagickDraw::getfontweight — Returns the font weight

### Beschreibung

public function GmagickDraw::getfontweight(): int

Returns the font weight used when annotating with text.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an int on success and 0 if no weight is set.

# GmagickDraw::getstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::getstrokecolor — Returns the color used for stroking object outlines

### Beschreibung

public function GmagickDraw::getstrokecolor(): GmagickPixel

Returns the color used for stroking object outlines.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an GmagickPixel object which describes the color.

# GmagickDraw::getstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::getstrokeopacity — Returns the opacity of stroked object outlines

### Beschreibung

public function GmagickDraw::getstrokeopacity(): float

Returns the opacity of stroked object outlines.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a float describing the opacity.

# GmagickDraw::getstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::getstrokewidth — Returns the width of the stroke used to draw object outlines

### Beschreibung

public function GmagickDraw::getstrokewidth(): float

Returns the width of the stroke used to draw object outlines.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a float describing the stroke width.

# GmagickDraw::gettextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::gettextdecoration — Returns the text decoration

### Beschreibung

public function GmagickDraw::gettextdecoration(): int

Returns the decoration applied when annotating with text.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns one of the DECORATION_ constants and 0 if no decoration is set.

# GmagickDraw::gettextencoding

(PECL gmagick >= Unknown)

GmagickDraw::gettextencoding — Returns the code set used for text annotations

### Beschreibung

public function GmagickDraw::gettextencoding(): mixed

Returns a string which specifies the code set used for text annotations.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string specifying the code set or `false` if text encoding is not set.

# GmagickDraw::line

(PECL gmagick >= Unknown)

GmagickDraw::line — Draws a line

### Beschreibung

public function GmagickDraw::line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw

Draws a line on the image using the current stroke color, stroke opacity, and stroke width.

### Parameter-Liste

`sx`
  starting x ordinate
`sy`
  starting y ordinate
`ex`
  ending x ordinate
`ey`
  ending y ordinate

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::point

(PECL gmagick >= Unknown)

GmagickDraw::point — Draws a point

### Beschreibung

public function GmagickDraw::point(float `$x`, float `$y`): GmagickDraw

Draws a point using the current stroke color and stroke thickness at the specified coordinates.

### Parameter-Liste

`x`
  target x coordinate
`y`
  target y coordinate

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::polygon

(PECL gmagick >= Unknown)

GmagickDraw::polygon — Draws a polygon

### Beschreibung

public function GmagickDraw::polygon(array `$coordinates`): GmagickDraw

Draws a polygon using the current stroke, stroke width, and fill color or texture, using the specified array of coordinates.

### Parameter-Liste

`coordinates`
  coordinate array

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::polyline

(PECL gmagick >= Unknown)

GmagickDraw::polyline — Draws a polyline

### Beschreibung

public function GmagickDraw::polyline(array `$coordinate_array`): GmagickDraw

Draws a polyline using the current stroke, stroke width, and fill color or texture, using the specified array of coordinates.

### Parameter-Liste

`coordinate_array`
  The array of coordinates

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::rectangle

(PECL gmagick >= Unknown)

GmagickDraw::rectangle — Draws a rectangle

### Beschreibung

public function GmagickDraw::rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw

Draws a rectangle given two coordinates and using the current stroke, stroke width, and fill settings.

### Parameter-Liste

`x1`
  x ordinate of first coordinate
`y1`
  y ordinate of first coordinate
`x2`
  x ordinate of second coordinate
`y2`
  y ordinate of second coordinate

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::rotate

(PECL gmagick >= Unknown)

GmagickDraw::rotate — Applies the specified rotation to the current coordinate space

### Beschreibung

public function GmagickDraw::rotate(float `$degrees`): GmagickDraw

Applies the specified rotation to the current coordinate space.

### Parameter-Liste

`degrees`
  degrees of rotation

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::roundrectangle

(PECL gmagick >= Unknown)

GmagickDraw::roundrectangle — Draws a rounded rectangle

### Beschreibung

public function GmagickDraw::roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw

Draws a rounded rectangle given two coordinates, x and y corner radiuses and using the current stroke, stroke width, and fill settings.

### Parameter-Liste

`x1`
  x ordinate of first coordinate
`y1`
  y ordinate of first coordinate
`x2`
  x ordinate of second coordinate
`y2`
  y ordinate of second coordinate
`rx`
  radius of corner in horizontal direction
`ry`
  radius of corner in vertical direction

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::scale

(PECL gmagick >= Unknown)

GmagickDraw::scale — Adjusts the scaling factor

### Beschreibung

public function GmagickDraw::scale(float `$x`, float `$y`): GmagickDraw

Adjusts the scaling factor to apply in the horizontal and vertical directions to the current coordinate space.

### Parameter-Liste

`x`
  horizontal scale factor
`y`
  vertical scale factor

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::setfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::setfillcolor — Sets the fill color to be used for drawing filled objects

### Beschreibung

public function GmagickDraw::setfillcolor(mixed `$color`): GmagickDraw

Sets the fill color to be used for drawing filled objects.

### Parameter-Liste

`color`
  GmagickPixel or string indicating color to use for filling.

### Rückgabewerte

The GmagickDraw object on success.

# GmagickDraw::setfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::setfillopacity — The setfillopacity purpose

### Beschreibung

public function GmagickDraw::setfillopacity(float `$fill_opacity`): GmagickDraw

Sets the opacity to use when drawing using the fill color or fill texture. Setting it to 1.0 will make fill full opaque.

### Parameter-Liste

`fill_opacity`
  Fill opacity

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::setfont

(PECL gmagick >= Unknown)

GmagickDraw::setfont — Sets the fully-specified font to use when annotating with text

### Beschreibung

public function GmagickDraw::setfont(string `$font`): GmagickDraw

Sets the fully-specified font to use when annotating with text

### Parameter-Liste

`font`
  font name

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::setfontsize

(PECL gmagick >= Unknown)

GmagickDraw::setfontsize — Sets the font pointsize to use when annotating with text

### Beschreibung

public function GmagickDraw::setfontsize(float `$pointsize`): GmagickDraw

Sets the font pointsize to use when annotating with text.

### Parameter-Liste

`pointsize`
  Text pointsize

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::setfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::setfontstyle — Sets the font style to use when annotating with text

### Beschreibung

public function GmagickDraw::setfontstyle(int `$style`): GmagickDraw

Sets the font style to use when annotating with text. The AnyStyle enumeration acts as a wild-card "don't care" option.

### Parameter-Liste

`style`
  Font style (NormalStyle, ItalicStyle, ObliqueStyle, AnyStyle)

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::setfontweight

(PECL gmagick >= Unknown)

GmagickDraw::setfontweight — Sets the font weight

### Beschreibung

public function GmagickDraw::setfontweight(int `$weight`): GmagickDraw

Sets the font weight to use when annotating with text.

### Parameter-Liste

`weight`
  Font weight (valid range 100-900)

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::setstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::setstrokecolor — Sets the color used for stroking object outlines

### Beschreibung

public function GmagickDraw::setstrokecolor(mixed `$color`): GmagickDraw

Sets the color used for stroking object outlines.

### Parameter-Liste

`color`
  GmagickPixel or string representing the color for the stroke.

### Rückgabewerte

The GmagickDraw object on success.

# GmagickDraw::setstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::setstrokeopacity — Specifies the opacity of stroked object outlines

### Beschreibung

public function GmagickDraw::setstrokeopacity(float `$stroke_opacity`): GmagickDraw

Specifies the opacity of stroked object outlines.

### Parameter-Liste

`stroke_opacity`
  Stroke opacity. The value 1.0 is opaque.

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::setstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::setstrokewidth — Sets the width of the stroke used to draw object outlines

### Beschreibung

public function GmagickDraw::setstrokewidth(float `$width`): GmagickDraw

Sets the width of the stroke used to draw object outlines

### Parameter-Liste

`width`
  Stroke width

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::settextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::settextdecoration — Specifies a decoration

### Beschreibung

public function GmagickDraw::settextdecoration(int `$decoration`): GmagickDraw

Specifies a decoration to be applied when annotating with text.

### Parameter-Liste

`int`
  Text decoration. One of NoDecoration, UnderlineDecoration, OverlineDecoration, or LineThroughDecoration

### Rückgabewerte

The GmagickDraw object.

# GmagickDraw::settextencoding

(PECL gmagick >= Unknown)

GmagickDraw::settextencoding — Specifies the text code set

### Beschreibung

public function GmagickDraw::settextencoding(string `$encoding`): GmagickDraw

Specifies the code set to use for text annotations. The only character encoding which may be specified at this time is "UTF-8" for representing Unicode as a sequence of bytes. Specify an empty string to set text encoding to the system's default. Successful text annotation using Unicode may require fonts designed to support Unicode.

### Parameter-Liste

`encoding`
  Character string specifying text encoding

### Rückgabewerte

The GmagickDraw object.

## Inhaltsverzeichnis

- GmagickDraw::annotate — Draws text on the image
- GmagickDraw::arc — Draws an arc
- GmagickDraw::bezier — Draws a bezier curve
- GmagickDraw::ellipse — Draws an ellipse on the image
- GmagickDraw::getfillcolor — Returns the fill color
- GmagickDraw::getfillopacity — Returns the opacity used when drawing
- GmagickDraw::getfont — Returns the font
- GmagickDraw::getfontsize — Returns the font pointsize
- GmagickDraw::getfontstyle — Returns the font style
- GmagickDraw::getfontweight — Returns the font weight
- GmagickDraw::getstrokecolor — Returns the color used for stroking object outlines
- GmagickDraw::getstrokeopacity — Returns the opacity of stroked object outlines
- GmagickDraw::getstrokewidth — Returns the width of the stroke used to draw object outlines
- GmagickDraw::gettextdecoration — Returns the text decoration
- GmagickDraw::gettextencoding — Returns the code set used for text annotations
- GmagickDraw::line — Draws a line
- GmagickDraw::point — Draws a point
- GmagickDraw::polygon — Draws a polygon
- GmagickDraw::polyline — Draws a polyline
- GmagickDraw::rectangle — Draws a rectangle
- GmagickDraw::rotate — Applies the specified rotation to the current coordinate space
- GmagickDraw::roundrectangle — Draws a rounded rectangle
- GmagickDraw::scale — Adjusts the scaling factor
- GmagickDraw::setfillcolor — Sets the fill color to be used for drawing filled objects
- GmagickDraw::setfillopacity — The setfillopacity purpose
- GmagickDraw::setfont — Sets the fully-specified font to use when annotating with text
- GmagickDraw::setfontsize — Sets the font pointsize to use when annotating with text
- GmagickDraw::setfontstyle — Sets the font style to use when annotating with text
- GmagickDraw::setfontweight — Sets the font weight
- GmagickDraw::setstrokecolor — Sets the color used for stroking object outlines
- GmagickDraw::setstrokeopacity — Specifies the opacity of stroked object outlines
- GmagickDraw::setstrokewidth — Sets the width of the stroke used to draw object outlines
- GmagickDraw::settextdecoration — Specifies a decoration
- GmagickDraw::settextencoding — Specifies the text code set

# The GmagickPixel class

(PECL gmagick >= Unknown)

## Einführung

## Klassenbeschreibung

class GmagickPixel {
/* Methoden */
public function __construct(string `$color` = ?)
public function getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed
public function getcolorcount(): int
public function getcolorvalue(int `$color`): float
public function setcolor(string `$color`): GmagickPixel
public function setcolorvalue(int `$color`, float `$value`): GmagickPixel
}

# GmagickPixel::__construct

(PECL gmagick >= Unknown)

GmagickPixel::__construct — Erstellt ein neues GmagickPixel-Objekt

### Beschreibung

public function GmagickPixel::__construct(string `$color` = ?)

Erstellt ein neues GmagickPixel-Objekt. Wenn `color` angegeben ist, wird das Objekt mit dieser Farbe initialisiert.

### Parameter-Liste

`color`
  Die optionale Farbzeichenkette, die als Initialwert benutzt wird.

# GmagickPixel::getcolor

(PECL gmagick >= Unknown)

GmagickPixel::getcolor — Gibt die Farbe zurück

### Beschreibung

public function GmagickPixel::getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed

Gibt die Farbe, die vom GmagickPixel-Objekt beschrieben wird, als String oder Array zurück. Wenn die Farbe einen Transparenz-Kanal hat, wird dieser als vierter Wert in der Liste angegeben.

### Parameter-Liste

`as_array`
  `true`, damit ein Array anstelle eines Strings zurückgegeben wird.
`normalize_array`
  `true`, um die Farbwerte zu normalisieren.

### Rückgabewerte

Ein String oder Array von Farbwerten, normalisiert, wenn `normalize_array` `true` ist. Löst bei einem Fehler eine GmagickPixelException aus.

# GmagickPixel::getcolorcount

(PECL gmagick >= Unknown)

GmagickPixel::getcolorcount — Returns the color count associated with this color

### Beschreibung

public function GmagickPixel::getcolorcount(): int

Returns the color count associated with this color.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the color count as an integer on success, throws GmagickPixelException on failure.

# GmagickPixel::getcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::getcolorvalue — Gets the normalized value of the provided color channel

### Beschreibung

public function GmagickPixel::getcolorvalue(int `$color`): float

Retrieves the value of the color channel specified, as a floating-point number between 0 and 1.

### Parameter-Liste

`color`
  The channel to check, specified as one of the Gmagick channel constants.

### Rückgabewerte

The value of the channel, as a normalized floating-point number, throwing GmagickPixelException on error.

# GmagickPixel::setcolor

(PECL gmagick >= Unknown)

GmagickPixel::setcolor — Sets the color

### Beschreibung

public function GmagickPixel::setcolor(string `$color`): GmagickPixel

Sets the color described by the GmagickPixel object, with a string (e.g. "blue", "#0000ff", "rgb(0,0,255)", "cmyk(100,100,100,10)", etc.).

### Parameter-Liste

`color`
  The color definition to use in order to initialise the GmagickPixel object.

### Rückgabewerte

The GmagickPixel object.

# GmagickPixel::setcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::setcolorvalue — Sets the normalized value of one of the channels

### Beschreibung

public function GmagickPixel::setcolorvalue(int `$color`, float `$value`): GmagickPixel

Sets the value of the specified channel of this object to the provided value, which should be between 0 and 1. This function can be used to provide an opacity channel to a GmagickPixel object.

### Parameter-Liste

`color`
  One of the Gmagick channel color constants.
`value`
  The value to set this channel to, ranging from 0 to 1.

### Rückgabewerte

The GmagickPixel object.

## Inhaltsverzeichnis

- GmagickPixel::__construct — Erstellt ein neues GmagickPixel-Objekt
- GmagickPixel::getcolor — Gibt die Farbe zurück
- GmagickPixel::getcolorcount — Returns the color count associated with this color
- GmagickPixel::getcolorvalue — Gets the normalized value of the provided color channel
- GmagickPixel::setcolor — Sets the color
- GmagickPixel::setcolorvalue — Sets the normalized value of one of the channels

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Vordefinierte Konstanten
- Beispiele
- Gmagick — The Gmagick class
  - Gmagick::addimage — Adds new image to Gmagick object image list
  - Gmagick::addnoiseimage — Adds random noise to the image
  - Gmagick::annotateimage — Annotates an image with text
  - Gmagick::blurimage — Adds blur filter to image
  - Gmagick::borderimage — Surrounds the image with a border
  - Gmagick::charcoalimage — Simulates a charcoal drawing
  - Gmagick::chopimage — Removes a region of an image and trims
  - Gmagick::clear — Clears all resources associated to Gmagick object
  - Gmagick::commentimage — Adds a comment to your image
  - Gmagick::compositeimage — Composite one image onto another
  - Gmagick::__construct — The Gmagick constructor
  - Gmagick::cropimage — Extracts a region of the image
  - Gmagick::cropthumbnailimage — Creates a crop thumbnail
  - Gmagick::current — The current purpose
  - Gmagick::cyclecolormapimage — Displaces an image's colormap
  - Gmagick::deconstructimages — Returns certain pixel differences between images
  - Gmagick::despeckleimage — The despeckleimage purpose
  - Gmagick::destroy — The destroy purpose
  - Gmagick::drawimage — Renders the GmagickDraw object on the current image
  - Gmagick::edgeimage — Enhance edges within the image
  - Gmagick::embossimage — Returns a grayscale image with a three-dimensional effect
  - Gmagick::enhanceimage — Improves the quality of a noisy image
  - Gmagick::equalizeimage — Equalizes the image histogram
  - Gmagick::flipimage — Creates a vertical mirror image
  - Gmagick::flopimage — Creates a horizontal mirror image
  - Gmagick::frameimage — Adds a simulated three-dimensional border
  - Gmagick::gammaimage — Gamma-corrects an image
  - Gmagick::getcopyright — Returns the GraphicsMagick API copyright as a string
  - Gmagick::getfilename — The filename associated with an image sequence
  - Gmagick::getimagebackgroundcolor — Returns the image background color
  - Gmagick::getimageblueprimary — Returns the chromaticy blue primary point
  - Gmagick::getimagebordercolor — Returns the image border color
  - Gmagick::getimagechanneldepth — Gets the depth for a particular image channel
  - Gmagick::getimagecolors — Returns the color of the specified colormap index
  - Gmagick::getimagecolorspace — Gets the image colorspace
  - Gmagick::getimagecompose — Returns the composite operator associated with the image
  - Gmagick::getimagedelay — Gets the image delay
  - Gmagick::getimagedepth — Gets the depth of the image
  - Gmagick::getimagedispose — Gets the image disposal method
  - Gmagick::getimageextrema — Gets the extrema for the image
  - Gmagick::getimagefilename — Returns the filename of a particular image in a sequence
  - Gmagick::getimageformat — Returns the format of a particular image in a sequence
  - Gmagick::getimagegamma — Gets the image gamma
  - Gmagick::getimagegreenprimary — Returns the chromaticy green primary point
  - Gmagick::getimageheight — Returns the image height
  - Gmagick::getimagehistogram — Gets the image histogram
  - Gmagick::getimageindex — Gets the index of the current active image
  - Gmagick::getimageinterlacescheme — Gets the image interlace scheme
  - Gmagick::getimageiterations — Gets the image iterations
  - Gmagick::getimagematte — Check if the image has a matte channel
  - Gmagick::getimagemattecolor — Returns the image matte color
  - Gmagick::getimageprofile — Returns the named image profile
  - Gmagick::getimageredprimary — Returns the chromaticity red primary point
  - Gmagick::getimagerenderingintent — Gets the image rendering intent
  - Gmagick::getimageresolution — Gets the image X and Y resolution
  - Gmagick::getimagescene — Gets the image scene
  - Gmagick::getimagesignature — Generates an SHA-256 message digest
  - Gmagick::getimagetype — Gets the potential image type
  - Gmagick::getimageunits — Gets the image units of resolution
  - Gmagick::getimagewhitepoint — Returns the chromaticity white point
  - Gmagick::getimagewidth — Returns the width of the image
  - Gmagick::getpackagename — Returns the GraphicsMagick package name
  - Gmagick::getquantumdepth — Returns the Gmagick quantum depth as a string
  - Gmagick::getreleasedate — Returns the GraphicsMagick release date as a string
  - Gmagick::getsamplingfactors — Gets the horizontal and vertical sampling factor
  - Gmagick::getsize — Returns the size associated with the Gmagick object
  - Gmagick::getversion — Returns the GraphicsMagick API version
  - Gmagick::hasnextimage — Checks if the object has more images
  - Gmagick::haspreviousimage — Checks if the object has a previous image
  - Gmagick::implodeimage — Creates a new image as a copy
  - Gmagick::labelimage — Adds a label to an image
  - Gmagick::levelimage — Adjusts the levels of an image
  - Gmagick::magnifyimage — Scales an image proportionally 2x
  - Gmagick::mapimage — Replaces the colors of an image with the closest color from a reference image
  - Gmagick::medianfilterimage — Applies a digital filter
  - Gmagick::minifyimage — Scales an image proportionally to half its size
  - Gmagick::modulateimage — Control the brightness, saturation, and hue
  - Gmagick::motionblurimage — Simulates motion blur
  - Gmagick::newimage — Creates a new image
  - Gmagick::nextimage — Moves to the next image
  - Gmagick::normalizeimage — Enhances the contrast of a color image
  - Gmagick::oilpaintimage — Simulates an oil painting
  - Gmagick::previousimage — Move to the previous image in the object
  - Gmagick::profileimage — Adds or removes a profile from an image
  - Gmagick::quantizeimage — Analyzes the colors within a reference image
  - Gmagick::quantizeimages — The quantizeimages purpose
  - Gmagick::queryfontmetrics — Returns an array representing the font metrics
  - Gmagick::queryfonts — Returns the configured fonts
  - Gmagick::queryformats — Returns formats supported by Gmagick
  - Gmagick::radialblurimage — Radial blurs an image
  - Gmagick::raiseimage — Creates a simulated 3d button-like effect
  - Gmagick::read — Reads image from filename
  - Gmagick::readimage — Reads image from filename
  - Gmagick::readimageblob — Reads image from a binary string
  - Gmagick::readimagefile — The readimagefile purpose
  - Gmagick::reducenoiseimage — Smooths the contours of an image
  - Gmagick::removeimage — Removes an image from the image list
  - Gmagick::removeimageprofile — Removes the named image profile and returns it
  - Gmagick::resampleimage — Resample image to desired resolution
  - Gmagick::resizeimage — Scales an image
  - Gmagick::rollimage — Offsets an image
  - Gmagick::rotateimage — Rotates an image
  - Gmagick::scaleimage — Scales the size of an image
  - Gmagick::separateimagechannel — Separates a channel from the image
  - Gmagick::setCompressionQuality — Sets the object's default compression quality
  - Gmagick::setfilename — Sets the filename before you read or write the image
  - Gmagick::setimagebackgroundcolor — Sets the image background color
  - Gmagick::setimageblueprimary — Sets the image chromaticity blue primary point
  - Gmagick::setimagebordercolor — Sets the image border color
  - Gmagick::setimagechanneldepth — Sets the depth of a particular image channel
  - Gmagick::setimagecolorspace — Sets the image colorspace
  - Gmagick::setimagecompose — Sets the image composite operator
  - Gmagick::setimagedelay — Sets the image delay
  - Gmagick::setimagedepth — Sets the image depth
  - Gmagick::setimagedispose — Sets the image disposal method
  - Gmagick::setimagefilename — Sets the filename of a particular image in a sequence
  - Gmagick::setimageformat — Sets the format of a particular image
  - Gmagick::setimagegamma — Sets the image gamma
  - Gmagick::setimagegreenprimary — Sets the image chromaticity green primary point
  - Gmagick::setimageindex — Set the iterator to the position in the image list specified with the index parameter
  - Gmagick::setimageinterlacescheme — Sets the interlace scheme of the image
  - Gmagick::setimageiterations — Sets the image iterations
  - Gmagick::setimageprofile — Adds a named profile to the Gmagick object
  - Gmagick::setimageredprimary — Sets the image chromaticity red primary point
  - Gmagick::setimagerenderingintent — Sets the image rendering intent
  - Gmagick::setimageresolution — Sets the image resolution
  - Gmagick::setimagescene — Sets the image scene
  - Gmagick::setimagetype — Sets the image type
  - Gmagick::setimageunits — Sets the image units of resolution
  - Gmagick::setimagewhitepoint — Sets the image chromaticity white point
  - Gmagick::setsamplingfactors — Sets the image sampling factors
  - Gmagick::setsize — Sets the size of the Gmagick object
  - Gmagick::shearimage — Creating a parallelogram
  - Gmagick::solarizeimage — Applies a solarizing effect to the image
  - Gmagick::spreadimage — Randomly displaces each pixel in a block
  - Gmagick::stripimage — Strips an image of all profiles and comments
  - Gmagick::swirlimage — Swirls the pixels about the center of the image
  - Gmagick::thumbnailimage — Changes the size of an image
  - Gmagick::trimimage — Remove edges from the image
  - Gmagick::write — Alias von Gmagick::writeimage
  - Gmagick::writeimage — Writes an image to the specified filename
- GmagickDraw — The GmagickDraw class
  - GmagickDraw::annotate — Draws text on the image
  - GmagickDraw::arc — Draws an arc
  - GmagickDraw::bezier — Draws a bezier curve
  - GmagickDraw::ellipse — Draws an ellipse on the image
  - GmagickDraw::getfillcolor — Returns the fill color
  - GmagickDraw::getfillopacity — Returns the opacity used when drawing
  - GmagickDraw::getfont — Returns the font
  - GmagickDraw::getfontsize — Returns the font pointsize
  - GmagickDraw::getfontstyle — Returns the font style
  - GmagickDraw::getfontweight — Returns the font weight
  - GmagickDraw::getstrokecolor — Returns the color used for stroking object outlines
  - GmagickDraw::getstrokeopacity — Returns the opacity of stroked object outlines
  - GmagickDraw::getstrokewidth — Returns the width of the stroke used to draw object outlines
  - GmagickDraw::gettextdecoration — Returns the text decoration
  - GmagickDraw::gettextencoding — Returns the code set used for text annotations
  - GmagickDraw::line — Draws a line
  - GmagickDraw::point — Draws a point
  - GmagickDraw::polygon — Draws a polygon
  - GmagickDraw::polyline — Draws a polyline
  - GmagickDraw::rectangle — Draws a rectangle
  - GmagickDraw::rotate — Applies the specified rotation to the current coordinate space
  - GmagickDraw::roundrectangle — Draws a rounded rectangle
  - GmagickDraw::scale — Adjusts the scaling factor
  - GmagickDraw::setfillcolor — Sets the fill color to be used for drawing filled objects
  - GmagickDraw::setfillopacity — The setfillopacity purpose
  - GmagickDraw::setfont — Sets the fully-specified font to use when annotating with text
  - GmagickDraw::setfontsize — Sets the font pointsize to use when annotating with text
  - GmagickDraw::setfontstyle — Sets the font style to use when annotating with text
  - GmagickDraw::setfontweight — Sets the font weight
  - GmagickDraw::setstrokecolor — Sets the color used for stroking object outlines
  - GmagickDraw::setstrokeopacity — Specifies the opacity of stroked object outlines
  - GmagickDraw::setstrokewidth — Sets the width of the stroke used to draw object outlines
  - GmagickDraw::settextdecoration — Specifies a decoration
  - GmagickDraw::settextencoding — Specifies the text code set
- GmagickPixel — The GmagickPixel class
  - GmagickPixel::__construct — Erstellt ein neues GmagickPixel-Objekt
  - GmagickPixel::getcolor — Gibt die Farbe zurück
  - GmagickPixel::getcolorcount — Returns the color count associated with this color
  - GmagickPixel::getcolorvalue — Gets the normalized value of the provided color channel
  - GmagickPixel::setcolor — Sets the color
  - GmagickPixel::setcolorvalue — Sets the normalized value of one of the channels

# Image Processing (ImageMagick)

# Einführung

Warnung

Diese Erweiterung ist EXPERIMENTELL. Das Verhalten dieser Erweiterung, einschließlich der Funktionsnamen, und alles Andere, was hier dokumentiert ist, kann sich in zukünftigen PHP-Versionen ohne Ankündigung ändern. Seien Sie gewarnt und verwenden Sie diese Erweiterung auf eigenes Risiko.

Imagick is a native php extension to create and modify images using the ImageMagick API.

## About ImageMagick

ImageMagick is a software suite to create, edit, and compose bitmap images. It can read, convert and write images in a variety of formats (over 100) including DPX, EXR, GIF, JPEG, JPEG-2000, PDF, PhotoCD, PNG, Postscript, SVG, and TIFF.

ImageMagick Studio LLC is a non-profit organization dedicated to making software imaging solutions freely available.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

## Installation requirements on non-Windows platforms

ImageMagick >= 6.2.4 is required. The amount of file formats supported by Imagick depends entirely upon the amount of formats supported by your ImageMagick installation. For example, Imagemagick requires ghostscript to conduct PDF operations.

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/imagick.

> Hinweis: The official name of this extension is imagick.

Windows users can download prebuilt DLL from the » PECL website. These packages already contain the extension DLL (php_imagick.dll) which needs to be put into the extension_dir. They also contain the ImageMagick DLLs, which need to be put somewhere in the PATH. As of Imagick 3.6.0, they also contain XML configuration files in config; to use these instead of the built-in defaults, they need to put into `%USERPROFILE%/.config/ImageMagick`, or alternatively in the path given by the environment variable MAGICK_CONFIGURE_PATH. Refer to the » ImageMagick configuration files documentation for further details.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Imagick configuration options
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
imagick.locale_fix | `false` | `INI_ALL` | Available since Imagick 2.1.0
imagick.progress_monitor | `false` | `INI_SYSTEM` | Available since Imagick 2.2.2
imagick.skip_version_check | `false` | `INI_SYSTEM` | Available since Imagick 3.3.0

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`imagick.locale_fix` bool

  Fixes a drawing bug with locales that use '`,`' as float separators.

`imagick.progress_monitor` bool

  Used to enable the image progress monitor.

`imagick.skip_version_check` bool

  When Imagick is loaded, it checks the version number of ImageMagick that it was compiled against, with the version number that is currently being used and will give a warning if they don't match. This warning can be suppressed by enabling this ini setting.

  Using a version of Imagick that was compiled against a different version of ImageMagick than the one being used is not recommended. Although it may appear to work, it can lead to random crashes or other undefined behaviour.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`COLOR_*` constants

Colortype constants. These constants are mainly used with ImagickPixel.

`imagick::COLOR_BLACK` (int)
  Black color
`imagick::COLOR_BLUE` (int)
  Blue color
`imagick::COLOR_CYAN` (int)
  Cyan color
`imagick::COLOR_GREEN` (int)
  Green color
`imagick::COLOR_RED` (int)
  Red color
`imagick::COLOR_YELLOW` (int)
  Yellow color
`imagick::COLOR_MAGENTA` (int)
  Magenta color
`imagick::COLOR_OPACITY` (int)
  Color's opacity
`imagick::COLOR_ALPHA` (int)
  Color's alpha
`imagick::COLOR_FUZZ` (int)
  Color's fuzz

`DISPOSE_*` constants

Dispose type constants

`imagick::DISPOSE_UNRECOGNIZED` (int)
  Unrecognized dispose type
`imagick::DISPOSE_UNDEFINED` (int)
  Undefined dispose type
`imagick::DISPOSE_NONE` (int)
  No dispose type defined
`imagick::DISPOSE_BACKGROUND` (int)
  Dispose background
`imagick::DISPOSE_PREVIOUS` (int)
  Dispose previous

`COMPOSITE_*` constants
`imagick::COMPOSITE_DEFAULT` (int)
  The default composite operator
`imagick::COMPOSITE_UNDEFINED` (int)
  Undefined composite operator
`imagick::COMPOSITE_NO` (int)
  No composite operator defined
`imagick::COMPOSITE_ADD` (int)
  The result of image + image
`imagick::COMPOSITE_ATOP` (int)
  The result is the same shape as image, with composite image obscuring image where the image shapes overlap
`imagick::COMPOSITE_BLEND` (int)
  Blends the image
`imagick::COMPOSITE_BUMPMAP` (int)
  The same as COMPOSITE_MULTIPLY, except the source is converted to grayscale first.
`imagick::COMPOSITE_CLEAR` (int)
  Makes the target image transparent
`imagick::COMPOSITE_COLORBURN` (int)
  Darkens the destination image to reflect the source image
`imagick::COMPOSITE_COLORDODGE` (int)
  Brightens the destination image to reflect the source image
`imagick::COMPOSITE_COLORIZE` (int)
  Colorizes the target image using the composite image
`imagick::COMPOSITE_COPYBLACK` (int)
  Copies black from the source to target
`imagick::COMPOSITE_COPYBLUE` (int)
  Copies blue from the source to target
`imagick::COMPOSITE_COPY` (int)
  Copies the source image on the target image
`imagick::COMPOSITE_COPYCYAN` (int)
  Copies cyan from the source to target
`imagick::COMPOSITE_COPYGREEN` (int)
  Copies green from the source to target
`imagick::COMPOSITE_COPYMAGENTA` (int)
  Copies magenta from the source to target
`imagick::COMPOSITE_COPYOPACITY` (int)
  Copies opacity from the source to target
`imagick::COMPOSITE_COPYRED` (int)
  Copies red from the source to target
`imagick::COMPOSITE_COPYYELLOW` (int)
  Copies yellow from the source to target
`imagick::COMPOSITE_DARKEN` (int)
  Darkens the target image
`imagick::COMPOSITE_DSTATOP` (int)
  The part of the destination lying inside of the source is composited over the source and replaces the destination
`imagick::COMPOSITE_DST` (int)
  The target is left untouched
`imagick::COMPOSITE_DSTIN` (int)
  The parts inside the source replace the target
`imagick::COMPOSITE_DSTOUT` (int)
  The parts outside the source replace the target
`imagick::COMPOSITE_DSTOVER` (int)
  Target replaces the source
`imagick::COMPOSITE_DIFFERENCE` (int)
  Subtracts the darker of the two constituent colors from the lighter
`imagick::COMPOSITE_DISPLACE` (int)
  Shifts target image pixels as defined by the source
`imagick::COMPOSITE_DISSOLVE` (int)
  Dissolves the source in to the target
`imagick::COMPOSITE_EXCLUSION` (int)
  Produces an effect similar to that of imagick::COMPOSITE_DIFFERENCE, but appears as lower contrast
`imagick::COMPOSITE_HARDLIGHT` (int)
  Multiplies or screens the colors, dependent on the source color value
`imagick::COMPOSITE_HUE` (int)
  Modifies the hue of the target as defined by source
`imagick::COMPOSITE_IN` (int)
  Composites source into the target
`imagick::COMPOSITE_LIGHTEN` (int)
  Lightens the target as defined by source
`imagick::COMPOSITE_LUMINIZE` (int)
  Luminizes the target as defined by source
`imagick::COMPOSITE_MINUS` (int)
  Subtracts the source from the target
`imagick::COMPOSITE_MODULATE` (int)
  Modulates the target brightness, saturation and hue as defined by source
`imagick::COMPOSITE_MULTIPLY` (int)
  Multiplies the target to the source
`imagick::COMPOSITE_OUT` (int)
  Composites outer parts of the source on the target
`imagick::COMPOSITE_OVER` (int)
  Composites source over the target
`imagick::COMPOSITE_OVERLAY` (int)
  Overlays the source on the target
`imagick::COMPOSITE_PLUS` (int)
  Adds the source to the target
`imagick::COMPOSITE_REPLACE` (int)
  Replaces the target with the source
`imagick::COMPOSITE_SATURATE` (int)
  Saturates the target as defined by the source
`imagick::COMPOSITE_SCREEN` (int)
  The source and destination are complemented and then multiplied and then replace the destination
`imagick::COMPOSITE_SOFTLIGHT` (int)
  Darkens or lightens the colors, dependent on the source
`imagick::COMPOSITE_SRCATOP` (int)
  The part of the source lying inside of the destination is composited onto the destination
`imagick::COMPOSITE_SRC` (int)
  The source is copied to the destination
`imagick::COMPOSITE_SRCIN` (int)
  The part of the source lying inside of the destination replaces the destination
`imagick::COMPOSITE_SRCOUT` (int)
  The part of the source lying outside of the destination replaces the destination
`imagick::COMPOSITE_SRCOVER` (int)
  The source replaces the destination
`imagick::COMPOSITE_SUBTRACT` (int)
  Subtract the colors in the source image from the destination image
`imagick::COMPOSITE_THRESHOLD` (int)
  The source is composited on the target as defined by source threshold
`imagick::COMPOSITE_XOR` (int)
  The part of the source that lies outside of the destination is combined with the part of the destination that lies outside of the source

`MONTAGEMODE_*` constants

`imagick::MONTAGEMODE_FRAME` (int)
`imagick::MONTAGEMODE_UNFRAME` (int)
`imagick::MONTAGEMODE_CONCATENATE` (int)

`STYLE_*` constants

`imagick::STYLE_NORMAL` (int)
`imagick::STYLE_ITALIC` (int)
`imagick::STYLE_OBLIQUE` (int)
`imagick::STYLE_ANY` (int)

`FILTER_*` constants

`imagick::FILTER_UNDEFINED` (int)
`imagick::FILTER_POINT` (int)
`imagick::FILTER_BOX` (int)
`imagick::FILTER_TRIANGLE` (int)
`imagick::FILTER_HERMITE` (int)
`imagick::FILTER_HANNING` (int)
`imagick::FILTER_HAMMING` (int)
`imagick::FILTER_BLACKMAN` (int)
`imagick::FILTER_GAUSSIAN` (int)
`imagick::FILTER_QUADRATIC` (int)
`imagick::FILTER_CUBIC` (int)
`imagick::FILTER_CATROM` (int)
`imagick::FILTER_MITCHELL` (int)
`imagick::FILTER_LANCZOS` (int)
`imagick::FILTER_BESSEL` (int)
`imagick::FILTER_SINC` (int)

`IMGTYPE_*` constants

`imagick::IMGTYPE_UNDEFINED` (int)
`imagick::IMGTYPE_BILEVEL` (int)
`imagick::IMGTYPE_GRAYSCALE` (int)
`imagick::IMGTYPE_GRAYSCALEMATTE` (int)
`imagick::IMGTYPE_PALETTE` (int)
`imagick::IMGTYPE_PALETTEMATTE` (int)
`imagick::IMGTYPE_TRUECOLOR` (int)
`imagick::IMGTYPE_TRUECOLORMATTE` (int)
`imagick::IMGTYPE_COLORSEPARATION` (int)
`imagick::IMGTYPE_COLORSEPARATIONMATTE` (int)
`imagick::IMGTYPE_OPTIMIZE` (int)

`RESOLUTION_*` constants

`imagick::RESOLUTION_UNDEFINED` (int)
`imagick::RESOLUTION_PIXELSPERINCH` (int)
`imagick::RESOLUTION_PIXELSPERCENTIMETER` (int)

`COMPRESSION_*` constants

`imagick::COMPRESSION_UNDEFINED` (int)
`imagick::COMPRESSION_NO` (int)
`imagick::COMPRESSION_BZIP` (int)
`imagick::COMPRESSION_FAX` (int)
`imagick::COMPRESSION_GROUP4` (int)
`imagick::COMPRESSION_JPEG` (int)
`imagick::COMPRESSION_JPEG2000` (int)
`imagick::COMPRESSION_LOSSLESSJPEG` (int)
`imagick::COMPRESSION_LZW` (int)
`imagick::COMPRESSION_RLE` (int)
`imagick::COMPRESSION_ZIP` (int)
`imagick::COMPRESSION_DXT1` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.0 or higher.
`imagick::COMPRESSION_DXT3` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.0 or higher.
`imagick::COMPRESSION_DXT5` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.0 or higher.

`PAINT_*` constants

`imagick::PAINT_POINT` (int)
`imagick::PAINT_REPLACE` (int)
`imagick::PAINT_FLOODFILL` (int)
`imagick::PAINT_FILLTOBORDER` (int)
`imagick::PAINT_RESET` (int)

`GRAVITY_*` constants

`imagick::GRAVITY_NORTHWEST` (int)
`imagick::GRAVITY_NORTH` (int)
`imagick::GRAVITY_NORTHEAST` (int)
`imagick::GRAVITY_WEST` (int)
`imagick::GRAVITY_CENTER` (int)
`imagick::GRAVITY_EAST` (int)
`imagick::GRAVITY_SOUTHWEST` (int)
`imagick::GRAVITY_SOUTH` (int)
`imagick::GRAVITY_SOUTHEAST` (int)

`STRETCH_*` constants

`imagick::STRETCH_NORMAL` (int)
`imagick::STRETCH_ULTRACONDENSED` (int)
`imagick::STRETCH_CONDENSED` (int)
`imagick::STRETCH_SEMICONDENSED` (int)
`imagick::STRETCH_SEMIEXPANDED` (int)
`imagick::STRETCH_EXPANDED` (int)
`imagick::STRETCH_EXTRAEXPANDED` (int)
`imagick::STRETCH_ULTRAEXPANDED` (int)
`imagick::STRETCH_ANY` (int)

`ALIGN_*` constants

`imagick::ALIGN_UNDEFINED` (int)
`imagick::ALIGN_LEFT` (int)
`imagick::ALIGN_CENTER` (int)
`imagick::ALIGN_RIGHT` (int)

`DECORATION_*` constants

`imagick::DECORATION_NO` (int)
`imagick::DECORATION_UNDERLINE` (int)
`imagick::DECORATION_OVERLINE` (int)
`imagick::DECORATION_LINETROUGH` (int)

`NOISE_*` constants

`imagick::NOISE_UNIFORM` (int)
`imagick::NOISE_GAUSSIAN` (int)
`imagick::NOISE_MULTIPLICATIVEGAUSSIAN` (int)
`imagick::NOISE_IMPULSE` (int)
`imagick::NOISE_LAPLACIAN` (int)
`imagick::NOISE_POISSON` (int)
`imagick::NOISE_RANDOM` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.6 or higher.

`CHANNEL_*` constants

`imagick::CHANNEL_UNDEFINED` (int)
`imagick::CHANNEL_RED` (int)
`imagick::CHANNEL_GRAY` (int)
`imagick::CHANNEL_CYAN` (int)
`imagick::CHANNEL_GREEN` (int)
`imagick::CHANNEL_MAGENTA` (int)
`imagick::CHANNEL_BLUE` (int)
`imagick::CHANNEL_YELLOW` (int)
`imagick::CHANNEL_ALPHA` (int)
`imagick::CHANNEL_OPACITY` (int)
`imagick::CHANNEL_MATTE` (int)
`imagick::CHANNEL_BLACK` (int)
`imagick::CHANNEL_INDEX` (int)
`imagick::CHANNEL_ALL` (int)
`imagick::CHANNEL_DEFAULT` (int)

`METRIC_*` constants

`imagick::METRIC_UNDEFINED` (int)
`imagick::METRIC_MEANABSOLUTEERROR` (int)
`imagick::METRIC_MEANSQUAREERROR` (int)
`imagick::METRIC_PEAKABSOLUTEERROR` (int)
`imagick::METRIC_PEAKSIGNALTONOISERATIO` (int)
`imagick::METRIC_ROOTMEANSQUAREDERROR` (int)

`PIXEL_*` constants

`imagick::PIXEL_CHAR` (int)
`imagick::PIXEL_DOUBLE` (int)
`imagick::PIXEL_FLOAT` (int)
`imagick::PIXEL_INTEGER` (int)
  Only available for ImageMagick < 7.
`imagick::PIXEL_LONG` (int)
`imagick::PIXEL_QUANTUM` (int)
`imagick::PIXEL_SHORT` (int)

`EVALUATE_*` constants

`imagick::EVALUATE_UNDEFINED` (int)
`imagick::EVALUATE_ADD` (int)
`imagick::EVALUATE_AND` (int)
`imagick::EVALUATE_DIVIDE` (int)
`imagick::EVALUATE_LEFTSHIFT` (int)
`imagick::EVALUATE_MAX` (int)
`imagick::EVALUATE_MIN` (int)
`imagick::EVALUATE_MULTIPLY` (int)
`imagick::EVALUATE_OR` (int)
`imagick::EVALUATE_RIGHTSHIFT` (int)
`imagick::EVALUATE_SET` (int)
`imagick::EVALUATE_SUBTRACT` (int)
`imagick::EVALUATE_XOR` (int)
`imagick::EVALUATE_POW` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_LOG` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_THRESHOLD` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_THRESHOLDBLACK` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_THRESHOLDWHITE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_GAUSSIANNOISE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_IMPULSENOISE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_LAPLACIANNOISE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_MULTIPLICATIVENOISE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_POISSONNOISE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_UNIFORMNOISE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_COSINE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_SINE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.
`imagick::EVALUATE_ADDMODULUS` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.4 or higher.

`COLORSPACE_*` constants

`imagick::COLORSPACE_UNDEFINED` (int)
`imagick::COLORSPACE_RGB` (int)
`imagick::COLORSPACE_GRAY` (int)
`imagick::COLORSPACE_TRANSPARENT` (int)
`imagick::COLORSPACE_OHTA` (int)
`imagick::COLORSPACE_LAB` (int)
`imagick::COLORSPACE_XYZ` (int)
`imagick::COLORSPACE_YCBCR` (int)
`imagick::COLORSPACE_YCC` (int)
`imagick::COLORSPACE_YIQ` (int)
`imagick::COLORSPACE_YPBPR` (int)
`imagick::COLORSPACE_YUV` (int)
`imagick::COLORSPACE_CMYK` (int)
`imagick::COLORSPACE_SRGB` (int)
`imagick::COLORSPACE_HSB` (int)
`imagick::COLORSPACE_HSL` (int)
`imagick::COLORSPACE_HWB` (int)
`imagick::COLORSPACE_REC601LUMA` (int)
`imagick::COLORSPACE_REC709LUMA` (int)
`imagick::COLORSPACE_LOG` (int)
`imagick::COLORSPACE_CMY` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.2 or higher.

`VIRTUALPIXELMETHOD_*` constants

`imagick::VIRTUALPIXELMETHOD_UNDEFINED` (int)
`imagick::VIRTUALPIXELMETHOD_BACKGROUND` (int)
`imagick::VIRTUALPIXELMETHOD_CONSTANT` (int)
`imagick::VIRTUALPIXELMETHOD_EDGE` (int)
`imagick::VIRTUALPIXELMETHOD_MIRROR` (int)
`imagick::VIRTUALPIXELMETHOD_TILE` (int)
`imagick::VIRTUALPIXELMETHOD_TRANSPARENT` (int)
`imagick::VIRTUALPIXELMETHOD_MASK` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.2 or higher.
`imagick::VIRTUALPIXELMETHOD_BLACK` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.2 or higher.
`imagick::VIRTUALPIXELMETHOD_GRAY` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.2 or higher.
`imagick::VIRTUALPIXELMETHOD_WHITE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.2 or higher.
`imagick::VIRTUALPIXELMETHOD_HORIZONTALTILE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.3 or higher.
`imagick::VIRTUALPIXELMETHOD_VERTICALTILE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.3 or higher.

`PREVIEW_*` constants

`imagick::PREVIEW_UNDEFINED` (int)
`imagick::PREVIEW_ROTATE` (int)
`imagick::PREVIEW_SHEAR` (int)
`imagick::PREVIEW_ROLL` (int)
`imagick::PREVIEW_HUE` (int)
`imagick::PREVIEW_SATURATION` (int)
`imagick::PREVIEW_BRIGHTNESS` (int)
`imagick::PREVIEW_GAMMA` (int)
`imagick::PREVIEW_SPIFF` (int)
`imagick::PREVIEW_DULL` (int)
`imagick::PREVIEW_GRAYSCALE` (int)
`imagick::PREVIEW_QUANTIZE` (int)
`imagick::PREVIEW_DESPECKLE` (int)
`imagick::PREVIEW_REDUCENOISE` (int)
`imagick::PREVIEW_ADDNOISE` (int)
`imagick::PREVIEW_SHARPEN` (int)
`imagick::PREVIEW_BLUR` (int)
`imagick::PREVIEW_THRESHOLD` (int)
`imagick::PREVIEW_EDGEDETECT` (int)
`imagick::PREVIEW_SPREAD` (int)
`imagick::PREVIEW_SOLARIZE` (int)
`imagick::PREVIEW_SHADE` (int)
`imagick::PREVIEW_RAISE` (int)
`imagick::PREVIEW_SEGMENT` (int)
`imagick::PREVIEW_SWIRL` (int)
`imagick::PREVIEW_IMPLODE` (int)
`imagick::PREVIEW_WAVE` (int)
`imagick::PREVIEW_OILPAINT` (int)
`imagick::PREVIEW_CHARCOALDRAWING` (int)
`imagick::PREVIEW_JPEG` (int)

`RENDERINGINTENT_*` constants

`imagick::RENDERINGINTENT_UNDEFINED` (int)
`imagick::RENDERINGINTENT_SATURATION` (int)
`imagick::RENDERINGINTENT_PERCEPTUAL` (int)
`imagick::RENDERINGINTENT_ABSOLUTE` (int)
`imagick::RENDERINGINTENT_RELATIVE` (int)

`INTERLACE_*` constants

`imagick::INTERLACE_UNDEFINED` (int)
`imagick::INTERLACE_NO` (int)
`imagick::INTERLACE_LINE` (int)
`imagick::INTERLACE_PLANE` (int)
`imagick::INTERLACE_PARTITION` (int)
`imagick::INTERLACE_GIF` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.4 or higher.
`imagick::INTERLACE_JPEG` (int)
`imagick::INTERLACE_PNG` (int)

`FILLRULE_*` constants

`imagick::FILLRULE_UNDEFINED` (int)
`imagick::FILLRULE_EVENODD` (int)
`imagick::FILLRULE_NONZERO` (int)

`PATHUNITS_*` constants

`imagick::PATHUNITS_UNDEFINED` (int)
`imagick::PATHUNITS_USERSPACE` (int)
`imagick::PATHUNITS_USERSPACEONUSE` (int)
`imagick::PATHUNITS_OBJECTBOUNDINGBOX` (int)

`LINECAP_*` constants

`imagick::LINECAP_UNDEFINED` (int)
`imagick::LINECAP_BUTT` (int)
`imagick::LINECAP_ROUND` (int)
`imagick::LINECAP_SQUARE` (int)

`LINEJOIN_*` constants

`imagick::LINEJOIN_UNDEFINED` (int)
`imagick::LINEJOIN_MITER` (int)
`imagick::LINEJOIN_ROUND` (int)
`imagick::LINEJOIN_BEVEL` (int)

`RESOURCETYPE_*` constants

`imagick::RESOURCETYPE_UNDEFINED` (int)
`imagick::RESOURCETYPE_AREA` (int)
  Set the maximum width * height of an image that can reside in the pixel cache memory.
`imagick::RESOURCETYPE_DISK` (int)
  Set maximum amount of disk space in bytes permitted for use by the pixel cache.
`imagick::RESOURCETYPE_FILE` (int)
  Set maximum number of open pixel cache files.
`imagick::RESOURCETYPE_MAP` (int)
  Set maximum amount of memory map in bytes to allocate for the pixel cache.
`imagick::RESOURCETYPE_MEMORY` (int)
  Set maximum amount of memory in bytes to allocate for the pixel cache from the heap.
`imagick::RESOURCETYPE_THREAD` (int)
  Set maximum parallel threads. Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.7.8 or higher.

`LAYERMETHOD_*` constants

`imagick::LAYERMETHOD_UNDEFINED` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.2.9 or higher.
`imagick::LAYERMETHOD_COALESCE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.2.9 or higher.
`imagick::LAYERMETHOD_COMPAREANY` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.2.9 or higher.
`imagick::LAYERMETHOD_COMPARECLEAR` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.2.9 or higher.
`imagick::LAYERMETHOD_COMPAREOVERLAY` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.2.9 or higher.
`imagick::LAYERMETHOD_DISPOSE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.2.9 or higher.
`imagick::LAYERMETHOD_OPTIMIZE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.2.9 or higher.
`imagick::LAYERMETHOD_OPTIMIZEPLUS` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.2.9 or higher.
`imagick::LAYERMETHOD_OPTIMIZEIMAGE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::LAYERMETHOD_OPTIMIZETRANS` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::LAYERMETHOD_REMOVEDUPS` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::LAYERMETHOD_REMOVEZERO` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::LAYERMETHOD_COMPOSITE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::LAYERMETHOD_MERGE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.7 or higher.
`imagick::LAYERMETHOD_FLATTEN` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.7 or higher.
`imagick::LAYERMETHOD_MOSAIC` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.7 or higher.

`ORIENTATION_*` constants

`imagick::ORIENTATION_UNDEFINED` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::ORIENTATION_TOPLEFT` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::ORIENTATION_TOPRIGHT` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::ORIENTATION_BOTTOMRIGHT` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::ORIENTATION_BOTTOMLEFT` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::ORIENTATION_LEFTTOP` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::ORIENTATION_RIGHTTOP` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::ORIENTATION_RIGHTBOTTOM` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.
`imagick::ORIENTATION_LEFTBOTTOM` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.0 or higher.

`DISTORTION_*` constants

`imagick::DISTORTION_UNDEFINED` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.6 or higher.
`imagick::DISTORTION_AFFINE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.6 or higher.
`imagick::DISTORTION_AFFINEPROJECTION` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.6 or higher.
`imagick::DISTORTION_ARC` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.6 or higher.
`imagick::DISTORTION_BILINEAR` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.6 or higher.
`imagick::DISTORTION_PERSPECTIVE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.6 or higher.
`imagick::DISTORTION_PERSPECTIVEPROJECTION` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.6 or higher.
`imagick::DISTORTION_SCALEROTATETRANSLATE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.6 or higher.
`imagick::DISTORTION_POLYNOMIAL` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::DISTORTION_POLAR` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::DISTORTION_DEPOLAR` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::DISTORTION_BARREL` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::DISTORTION_BARRELINVERSE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::DISTORTION_SHEPARDS` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::DISTORTION_SENTINEL` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.

`ALPHACHANNEL_*` constants

`imagick::ALPHACHANNEL_ACTIVATE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.8 or higher.
`imagick::ALPHACHANNEL_DEACTIVATE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.8 or higher.
`imagick::ALPHACHANNEL_RESET` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.8 or higher.
`imagick::ALPHACHANNEL_SET` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.8 or higher.
`imagick::ALPHACHANNEL_UNDEFINED` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::ALPHACHANNEL_COPY` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::ALPHACHANNEL_EXTRACT` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::ALPHACHANNEL_OPAQUE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::ALPHACHANNEL_SHAPE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::ALPHACHANNEL_TRANSPARENT` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::ALPHACHANNEL_BACKGROUND` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.5.3 or higher.
`imagick::ALPHACHANNEL_REMOVE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.7.8 or higher.
`imagick::ALPHACHANNEL_ASSOCIATE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.9.0 or higher.
`imagick::ALPHACHANNEL_DISSOCIATE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.9.0 or higher.
`imagick::ALPHACHANNEL_ON` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 7.0.0 or higher.
`imagick::ALPHACHANNEL_OFF` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 7.0.0 or higher.
`imagick::ALPHACHANNEL_DISCRETE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 7.0.0 or higher.

`SPARSECOLORMETHOD_*` constants

`imagick::SPARSECOLORMETHOD_UNDEFINED` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_BARYCENTRIC` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_BILINEAR` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_POLYNOMIAL` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_SPEPARDS` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::SPARSECOLORMETHOD_VORONOI` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.

`FUNCTION_*` constants

`imagick::FUNCTION_UNDEFINED` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.9 or higher.
`imagick::FUNCTION_POLYNOMIAL` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.9 or higher.
`imagick::FUNCTION_SINUSOID` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.9 or higher.

`INTERPOLATE_*` constants

`imagick::INTERPOLATE_UNDEFINED` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.2 or higher.
`imagick::INTERPOLATE_AVERAGE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.2 or higher.
`imagick::INTERPOLATE_BICUBIC` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.2 or higher.
`imagick::INTERPOLATE_BILINEAR` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.2 or higher.
`imagick::INTERPOLATE_FILTER` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.2 or higher.
`imagick::INTERPOLATE_INTEGER` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.2 or higher.
`imagick::INTERPOLATE_MESH` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.2 or higher.
`imagick::INTERPOLATE_NEARESTNEIGHBOR` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.2 or higher.
`imagick::INTERPOLATE_SPLINE` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.3.4 or higher.

`DITHERMETHOD_*` constants

`imagick::DITHERMETHOD_UNDEFINED` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::DITHERMETHOD_NO` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::DITHERMETHOD_RIEMERSMA` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.
`imagick::DITHERMETHOD_FLOYDSTEINBERG` (int)
  Diese Konstante ist verfügbar, wenn Imagick kompiliert wurde gegen die ImageMagick-Version 6.4.6 or higher.

# Beispiele

## Inhaltsverzeichnis

- Basic usage

## Basic usage

Imagick makes image manipulation in PHP extremely easy through an OO interface. Here is a quick example on how to make a thumbnail:

Beispiel #1 Creating a thumbnail in Imagick

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('image.jpg');

    // If 0 is provided as a width or height parameter,
    // aspect ratio is maintained
    $image->thumbnailImage(100, 0);

    echo $image;

    ?>

Using SPL and other OO features supported in Imagick, it can be simple to resize all files in a directory (useful for batch resizing large digital camera images to be web viewable). Here we use resize, as we might want to retain certain meta-data:

Beispiel #2 Make a thumbnail of all JPG files in a directory

    <?php

    $images = new Imagick(glob('images/*.JPG'));

    foreach($images as $image) {

        // Providing 0 forces thumbnailImage to maintain aspect ratio
        $image->thumbnailImage(1024,0);

    }

    $images->writeImages();

    ?>

This is an example of creating a reflection of an image. The reflection is created by flipping the image and overlaying a gradient on it. Then both, the original image and the reflection is overlaid on a canvas.

Beispiel #3 Creating a reflection of an image

    <?php
    /* Read the image */
    $im = new Imagick("test.png");

    /* Thumbnail the image */
    $im->thumbnailImage(200, null);

    /* Create a border for the image */
    $im->borderImage(new ImagickPixel("white"), 5, 5);

    /* Clone the image and flip it */
    $reflection = $im->clone();
    $reflection->flipImage();

    /* Create gradient. It will be overlaid on the reflection */
    $gradient = new Imagick();

    /* Gradient needs to be large enough for the image and the borders */
    $gradient->newPseudoImage($reflection->getImageWidth() + 10, $reflection->getImageHeight() + 10, "gradient:transparent-black");

    /* Composite the gradient on the reflection */
    $reflection->compositeImage($gradient, imagick::COMPOSITE_OVER, 0, 0);

    /* Add some opacity. Requires ImageMagick 6.2.9 or later */
    $reflection->setImageOpacity( 0.3 );

    /* Create an empty canvas */
    $canvas = new Imagick();

    /* Canvas needs to be large enough to hold the both images */
    $width = $im->getImageWidth() + 40;
    $height = ($im->getImageHeight() * 2) + 30;
    $canvas->newImage($width, $height, new ImagickPixel("black"));
    $canvas->setImageFormat("png");

    /* Composite the original image and the reflection on the canvas */
    $canvas->compositeImage($im, imagick::COMPOSITE_OVER, 20, 10);
    $canvas->compositeImage($reflection, imagick::COMPOSITE_OVER, 20, $im->getImageHeight() + 10);

    /* Output the image*/
    header("Content-Type: image/png");
    echo $canvas;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

This example illustrates how to use fill patterns during drawing.

Beispiel #4 Filling text with gradient

    <?php

    /* Create a new imagick object */
    $im = new Imagick();

    /* Create new image. This will be used as fill pattern */
    $im->newPseudoImage(50, 50, "gradient:red-black");

    /* Create imagickdraw object */
    $draw = new ImagickDraw();

    /* Start a new pattern called "gradient" */
    $draw->pushPattern('gradient', 0, 0, 50, 50);

    /* Composite the gradient on the pattern */
    $draw->composite(Imagick::COMPOSITE_OVER, 0, 0, 50, 50, $im);

    /* Close the pattern */
    $draw->popPattern();

    /* Use the pattern called "gradient" as the fill */
    $draw->setFillPatternURL('#gradient');

    /* Set font size to 52 */
    $draw->setFontSize(52);

    /* Annotate some text */
    $draw->annotation(20, 50, "Hello World!");

    /* Create a new canvas object and a white image */
    $canvas = new Imagick();
    $canvas->newImage(350, 70, "white");

    /* Draw the ImagickDraw on to the canvas */
    $canvas->drawImage($draw);

    /* 1px black border around the image */
    $canvas->borderImage('black', 1, 1);

    /* Set the format to PNG */
    $canvas->setImageFormat('png');

    /* Output the image */
    header("Content-Type: image/png");
    echo $canvas;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Working with animated GIF images

Beispiel #5 Read in GIF image and resize all frames

    <?php

    /* Create a new imagick object and read in GIF */
    $im = new Imagick("example.gif");

    /* Resize all frames */
    foreach ($im as $frame) {
        /* 50x50 frames */
        $frame->thumbnailImage(50, 50);

        /* Set the virtual canvas to correct size */
        $frame->setImagePage(50, 50, 0, 0);
    }

    /* Notice writeImages instead of writeImage */
    $im->writeImages("example_small.gif", true);
    ?>

Working with ellipse primitive and custom fonts

Beispiel #6 Create a PHP logo

    <?php
    /* Set width and height in proportion of genuine PHP logo */
    $width = 400;
    $height = 210;

    /* Create an Imagick object with transparent canvas */
    $img = new Imagick();
    $img->newImage($width, $height, new ImagickPixel('transparent'));

    /* New ImagickDraw instance for ellipse draw */
    $draw = new ImagickDraw();
    /* Set purple fill color for ellipse */
    $draw->setFillColor('#777bb4');
    /* Set ellipse dimensions */
    $draw->ellipse($width / 2, $height / 2, $width / 2, $height / 2, 0, 360);
    /* Draw ellipse onto the canvas */
    $img->drawImage($draw);

    /* Reset fill color from purple to black for text (note: we are reusing ImagickDraw object) */
    $draw->setFillColor('black');
    /* Set stroke border to white color */
    $draw->setStrokeColor('white');
    /* Set stroke border thickness */
    $draw->setStrokeWidth(2);
    /* Set font kerning (negative value means that letters are closer to each other) */
    $draw->setTextKerning(-8);
    /* Set font and font size used in PHP logo */
    $draw->setFont('Handel Gothic.ttf');
    $draw->setFontSize(150);
    /* Center text horizontally and vertically */
    $draw->setGravity(Imagick::GRAVITY_CENTER);

    /* Add center "php" with Y offset of -10 to canvas (inside ellipse) */
    $img->annotateImage($draw, 0, -10, 0, 'php');
    $img->setImageFormat('png');

    /* Set appropriate header for PNG and output the image */
    header('Content-Type: image/png');
    echo $img;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# The Imagick class

(PECL imagick 2, PECL imagick 3)

## Klassenbeschreibung

class Imagick implements Iterator {
public function __construct(mixed `$files` = ?)
public function adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool
public function addImage(Imagick `$source`): bool
public function addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function affineTransformImage(ImagickDraw `$matrix`): bool
public function animateImages(string `$x_server`): bool
public function annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool
public function appendImages(bool `$stack`): Imagick
public function autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function averageImages(): Imagick
public function blackThresholdImage(mixed `$threshold`): bool
public function blueShiftImage(float `$factor` = 1.5): bool
public function blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool
public function borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool
public function brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function charcoalImage(float `$radius`, float `$sigma`): bool
public function chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function clear(): bool
public function clipImage(): bool
public function clipImagePath(string `$pathname`, string `$inside`): void
public function clipPathImage(string `$pathname`, bool `$inside`): bool
public function clone(): Imagick
public function clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function coalesceImages(): Imagick
public function colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function colorMatrixImage(array `$color_matrix`): bool
public function combineImages(int `$channelType`): Imagick
public function commentImage(string `$comment`): bool
public function compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array
public function compareImageLayers(int `$method`): Imagick
public function compareImages(Imagick `$compare`, int `$metric`): array
public function compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function contrastImage(bool `$sharpen`): bool
public function contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function count(int `$mode` = 0): int
public function cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool
public function current(): Imagick
public function cycleColormapImage(int `$displace`): bool
public function decipherImage(string `$passphrase`): bool
public function deconstructImages(): Imagick
public function deleteImageArtifact(string `$artifact`): bool
public function deleteImageProperty(string `$name`): bool
public function deskewImage(float `$threshold`): bool
public function despeckleImage(): bool
public function destroy(): bool
public function displayImage(string `$servername`): bool
public function displayImages(string `$servername`): bool
public function distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool
public function drawImage(ImagickDraw `$draw`): bool
public function edgeImage(float `$radius`): bool
public function embossImage(float `$radius`, float `$sigma`): bool
public function encipherImage(string `$passphrase`): bool
public function enhanceImage(): bool
public function equalizeImage(): bool
public function evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array
public function extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool
public function flattenImages(): Imagick
public function flipImage(): bool
public function floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function flopImage(): bool
public function forwardFourierTransformimage(bool `$magnitude`): bool
public function frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool
public function functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick
public function gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function getColorspace(): int
public function getCompression(): int
public function getCompressionQuality(): int
public static function getCopyright(): string
public function getFilename(): string
public function getFont(): string
public function getFormat(): string
public function getGravity(): int
public static function getHomeURL(): string
public function getImage(): Imagick
public function getImageAlphaChannel(): bool
public function getImageArtifact(string `$artifact`): string
public function getImageAttribute(string `$key`): string
public function getImageBackgroundColor(): ImagickPixel
public function getImageBlob(): string
public function getImageBluePrimary(): array
public function getImageBorderColor(): ImagickPixel
public function getImageChannelDepth(int `$channel`): int
public function getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float
public function getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float
public function getImageChannelExtrema(int `$channel`): array
public function getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array
public function getImageChannelMean(int `$channel`): array
public function getImageChannelRange(int `$channel`): array
public function getImageChannelStatistics(): array
public function getImageClipMask(): Imagick
public function getImageColormapColor(int `$index`): ImagickPixel
public function getImageColors(): int
public function getImageColorspace(): int
public function getImageCompose(): int
public function getImageCompression(): int
public function getImageCompressionQuality(): int
public function getImageDelay(): int
public function getImageDepth(): int
public function getImageDispose(): int
public function getImageDistortion(MagickWand `$reference`, int `$metric`): float
public function getImageExtrema(): array
public function getImageFilename(): string
public function getImageFormat(): string
public function getImageGamma(): float
public function getImageGeometry(): array
public function getImageGravity(): int
public function getImageGreenPrimary(): array
public function getImageHeight(): int
public function getImageHistogram(): array
public function getImageIndex(): int
public function getImageInterlaceScheme(): int
public function getImageInterpolateMethod(): int
public function getImageIterations(): int
public function getImageLength(): int
public function getImageMatte(): bool
public function getImageMatteColor(): ImagickPixel
public function getImageMimeType(): string
public function getImageOrientation(): int
public function getImagePage(): array
public function getImagePixelColor(int `$x`, int `$y`): ImagickPixel
public function getImageProfile(string `$name`): string
public function getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperty(string `$name`): string
public function getImageRedPrimary(): array
public function getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick
public function getImageRenderingIntent(): int
public function getImageResolution(): array
public function getImagesBlob(): string
public function getImageScene(): int
public function getImageSignature(): string
public function getImageSize(): int
public function getImageTicksPerSecond(): int
public function getImageTotalInkDensity(): float
public function getImageType(): int
public function getImageUnits(): int
public function getImageVirtualPixelMethod(): int
public function getImageWhitePoint(): array
public function getImageWidth(): int
public function getInterlaceScheme(): int
public function getIteratorIndex(): int
public function getNumberImages(): int
public function getOption(string `$key`): string
public static function getPackageName(): string
public function getPage(): array
public function getPixelIterator(): ImagickPixelIterator
public function getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator
public function getPointSize(): float
public static function getQuantum(): int
public static function getQuantumDepth(): array
public static function getQuantumRange(): array
public static function getRegistry(string `$key`): string
public static function getReleaseDate(): string
public static function getResource(int `$type`): int
public static function getResourceLimit(int `$type`): int
public function getSamplingFactors(): array
public function getSize(): array
public function getSizeOffset(): int
public static function getVersion(): array
public function haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function hasNextImage(): bool
public function hasPreviousImage(): bool
public function identifyFormat(string `$embedText`): string|false
public function identifyImage(bool `$appendRawOutput` = `false`): array
public function implodeImage(float `$radius`): bool
public function importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool
public function inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool
public function labelImage(string `$label`): bool
public function levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool
public function liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool
public static function listRegistry(): array
public function magnifyImage(): bool
public function mapImage(Imagick `$map`, bool `$dither`): bool
public function matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function medianFilterImage(float `$radius`): bool
public function mergeImageLayers(int `$layer_method`): Imagick
public function minifyImage(): bool
public function modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool
public function montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick
public function morphImages(int `$number_frames`): Imagick
public function morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function mosaicImages(): Imagick
public function motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool
public function newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool
public function nextImage(): bool
public function normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function oilPaintImage(float `$radius`): bool
public function opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function optimizeImageLayers(): bool
public function orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool
public function pingImage(string `$filename`): bool
public function pingImageBlob(string `$image`): bool
public function pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool
public function polaroidImage(ImagickDraw `$properties`, float `$angle`): bool
public function posterizeImage(int `$levels`, bool `$dither`): bool
public function previewImages(int `$preview`): bool
public function previousImage(): bool
public function profileImage(string `$name`, string `$profile` = ?): bool
public function quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array
public static function queryFonts(string `$pattern` = "*"): array
public static function queryFormats(string `$pattern` = "*"): array
public function radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool
public function randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function readImage(string `$filename`): bool
public function readImageBlob(string `$image`, string `$filename` = ?): bool
public function readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool
public function readImages(array `$filenames`): bool
public function recolorImage(array `$matrix`): bool
public function reduceNoiseImage(float `$radius`): bool
public function remapImage(Imagick `$replacement`, int `$DITHER`): bool
public function removeImage(): bool
public function removeImageProfile(string `$name`): string
public function render(): bool
public function resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool
public function resetImagePage(string `$page`): bool
public function resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function rollImage(int `$x`, int `$y`): bool
public function rotateImage(mixed `$background`, float `$degrees`): bool
public function rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool
public function sampleImage(int `$columns`, int `$rows`): bool
public function scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool
public function selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function separateImageChannel(int `$channel`): bool
public function sepiaToneImage(float `$threshold`): bool
public function setBackgroundColor(mixed `$background`): bool
public function setColorspace(int `$COLORSPACE`): bool
public function setCompression(int `$compression`): bool
public function setCompressionQuality(int `$quality`): bool
public function setFilename(string `$filename`): bool
public function setFirstIterator(): bool
public function setFont(string `$font`): bool
public function setFormat(string `$format`): bool
public function setGravity(int `$gravity`): bool
public function setImage(Imagick `$replace`): bool
public function setImageAlphaChannel(int `$mode`): bool
public function setImageArtifact(string `$artifact`, string `$value`): bool
public function setImageAttribute(string `$key`, string `$value`): bool
public function setImageBackgroundColor(mixed `$background`): bool
public function setImageBias(float `$bias`): bool
public function setImageBiasQuantum(float `$bias`): void
public function setImageBluePrimary(float `$x`, float `$y`): bool
public function setImageBorderColor(mixed `$border`): bool
public function setImageChannelDepth(int `$channel`, int `$depth`): bool
public function setImageClipMask(Imagick `$clip_mask`): bool
public function setImageColormapColor(int `$index`, ImagickPixel `$color`): bool
public function setImageColorspace(int `$colorspace`): bool
public function setImageCompose(int `$compose`): bool
public function setImageCompression(int `$compression`): bool
public function setImageCompressionQuality(int `$quality`): bool
public function setImageDelay(int `$delay`): bool
public function setImageDepth(int `$depth`): bool
public function setImageDispose(int `$dispose`): bool
public function setImageExtent(int `$columns`, int `$rows`): bool
public function setImageFilename(string `$filename`): bool
public function setImageFormat(string `$format`): bool
public function setImageGamma(float `$gamma`): bool
public function setImageGravity(int `$gravity`): bool
public function setImageGreenPrimary(float `$x`, float `$y`): bool
public function setImageIndex(int `$index`): bool
public function setImageInterlaceScheme(int `$interlace_scheme`): bool
public function setImageInterpolateMethod(int `$method`): bool
public function setImageIterations(int `$iterations`): bool
public function setImageMatte(bool `$matte`): bool
public function setImageMatteColor(mixed `$matte`): bool
public function setImageOpacity(float `$opacity`): bool
public function setImageOrientation(int `$orientation`): bool
public function setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setImageProfile(string `$name`, string `$profile`): bool
public function setImageProperty(string `$name`, string `$value`): bool
public function setImageRedPrimary(float `$x`, float `$y`): bool
public function setImageRenderingIntent(int `$rendering_intent`): bool
public function setImageResolution(float `$x_resolution`, float `$y_resolution`): bool
public function setImageScene(int `$scene`): bool
public function setImageTicksPerSecond(int `$ticks_per_second`): bool
public function setImageType(int `$image_type`): bool
public function setImageUnits(int `$units`): bool
public function setImageVirtualPixelMethod(int `$method`): bool
public function setImageWhitePoint(float `$x`, float `$y`): bool
public function setInterlaceScheme(int `$interlace_scheme`): bool
public function setIteratorIndex(int `$index`): bool
public function setLastIterator(): bool
public function setOption(string `$key`, string `$value`): bool
public function setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setPointSize(float `$point_size`): bool
public function setProgressMonitor(callable `$callback`): bool
public static function setRegistry(string `$key`, string `$value`): bool
public function setResolution(float `$x_resolution`, float `$y_resolution`): bool
public static function setResourceLimit(int `$type`, int `$limit`): bool
public function setSamplingFactors(array `$factors`): bool
public function setSize(int `$columns`, int `$rows`): bool
public function setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool
public function setType(int `$image_type`): bool
public function shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool
public function shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool
public function sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function shaveImage(int `$columns`, int `$rows`): bool
public function shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool
public function sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool
public function smushImages(bool `$stack`, int `$offset`): Imagick
public function solarizeImage(int `$threshold`): bool
public function sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function spreadImage(float `$radius`): bool
public function statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick
public function stereoImage(Imagick `$offset_wand`): bool
public function stripImage(): bool
public function subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick
function swirlImage(float `$degrees`): bool
function textureImage(Imagick `$texture_wand`): Imagick
public function thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool
public function tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function __toString(): string
public function transformImage(string `$crop`, string `$geometry`): Imagick
public function transformImageColorspace(int `$colorspace`): bool
public function transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool
public function transposeImage(): bool
public function transverseImage(): bool
public function trimImage(float `$fuzz`): bool
public function uniqueImageColors(): bool
public function unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function valid(): bool
public function vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool
public function waveImage(float `$amplitude`, float `$length`): bool
public function whiteThresholdImage(mixed `$threshold`): bool
public function writeImage(string `$filename` = NULL): bool
public function writeImageFile(resource `$filehandle`, string `$format` = ?): bool
public function writeImages(string `$filename`, bool `$adjoin`): bool
public function writeImagesFile(resource `$filehandle`, string `$format` = ?): bool
}

## Image methods and global methods

The Imagick class has the ability to hold and operate on multiple images simultaneously. This is achieved through an internal stack. There is always an internal pointer that points at the current image. Some functions operate on all images in the Imagick class, but most operate only on the current image in the internal stack. As a convention, method names can contain the word Image to denote they affect only the current image in the stack.

## Class Methods

Because there are so many methods, here is a handy list of methods, somewhat reduced to their general purpose:

Class methods by purpose
Image effects | Get methods | Set methods | Read/write images | Other
--- | --- | --- | --- | ---
Imagick::adaptiveBlurImage() | Imagick::getCompression() | Imagick::setBackgroundColor() | Imagick::__construct() | Imagick::clear()
Imagick::adaptiveResizeImage() | Imagick::getFilename() | Imagick::setCompressionQuality() | Imagick::addImage() | Imagick::clone()
Imagick::adaptiveSharpenImage() | Imagick::getFormat() | Imagick::setCompression() | Imagick::appendImages() | Imagick::current()
Imagick::adaptiveThresholdImage() | Imagick::getImageBackgroundColor() | Imagick::setFilename() | Imagick::getFilename() | Imagick::destroy()
Imagick::addNoiseImage() | Imagick::getImageBlob() | Imagick::getImagesBlob() | Imagick::setFormat() | Imagick::getFormat()
Imagick::affinetransformimage() | Imagick::getImageBluePrimary() | Imagick::setImageBackgroundColor() | Imagick::getImageFilename() | Imagick::getHomeURL()
Imagick::annotateImage() | Imagick::getImageBorderColor() | Imagick::setFirstIterator() | Imagick::getImageFormat() | Imagick::commentImage()
Imagick::averageImages() | Imagick::getImageChannelDepth() | Imagick::setImageBias() | Imagick::getImage() | Imagick::getNumberImages()
Imagick::blackThresholdImage() | Imagick::getImageChannelDistortion() | Imagick::setImageBluePrimary() | Imagick::setImageFilename() | Imagick::getReleaseDate()
Imagick::blurImage() | Imagick::getImageChannelExtrema() | Imagick::setImageBorderColor() | Imagick::setImageFormat() | Imagick::getVersion()
Imagick::borderImage() | Imagick::getImageChannelMean() | Imagick::setImageChannelDepth() | Imagick::readImageFile() | Imagick::hasNextImage()
Imagick::charcoalImage() | Imagick::getImageChannelStatistics() | Imagick::setImageColormapColor() | Imagick::readImage() | Imagick::hasPreviousImage()
Imagick::chopImage() | Imagick::getImageColormapColor() | Imagick::setImageColorSpace() | Imagick::writeImages() | Imagick::labelImage()
Imagick::clipImage() | Imagick::getImageColorspace() | Imagick::setImageCompose() | Imagick::writeImage() | Imagick::newImage()
Imagick::clipPathImage() | Imagick::getImageColors() | Imagick::setImageCompression() |  | Imagick::newPseudoImage()
Imagick::coalesceImages() | Imagick::getImageCompose() | Imagick::setImageDelay() |  | Imagick::nextImage()
Imagick::colorFloodFillImage() | Imagick::getImageDelay() | Imagick::setImageDepth() |  | Imagick::pingImageBlob()
Imagick::colorizeImage() | Imagick::getImageDepth() | Imagick::setImageDispose() |  | Imagick::pingImageFile()
Imagick::combineImages() | Imagick::getImageDispose() | Imagick::setImageDispose() |  | Imagick::pingImage()
Imagick::compareImageChannels() | Imagick::getImageDistortion() | Imagick::setImageExtent() |  | Imagick::previousImage()
Imagick::compareImageLayers() | Imagick::getImageExtrema() | Imagick::setImageFilename() |  | Imagick::profileImage()
Imagick::compositeImage() | Imagick::getImageFilename() | Imagick::setImageFormat() |  | Imagick::queryFormats()
Imagick::contrastImage() | Imagick::getImageFormat() | Imagick::setImageGamma() |  | Imagick::removeImageProfile()
Imagick::contrastStretchImage() | Imagick::getImageGamma() | Imagick::setImageGreenPrimary() |  | Imagick::removeImage()
Imagick::convolveImage() | Imagick::getImageGeometry() | Imagick::setImageIndex() |  | Imagick::setFirstIterator()
Imagick::cropImage() | Imagick::getImageGreenPrimary() | Imagick::setImageInterpolateMethod() |  | Imagick::setImageIndex()
Imagick::cycleColormapImage() | Imagick::getImageHeight() | Imagick::setImageIterations() |  | Imagick::valid()
Imagick::deconstructImages() | Imagick::getImageHistogram() | Imagick::setImageMatteColor() |  | Imagick::getCopyright()
Imagick::drawImage() | Imagick::getImageIndex() | Imagick::setImageMatte() |  |
Imagick::edgeImage() | Imagick::getImageInterlaceScheme() | Imagick::setImagePage() |  |
Imagick::embossImage() | Imagick::getImageInterpolateMethod() | Imagick::setImageProfile() |  |
Imagick::enhanceImage() | Imagick::getImageIterations() | Imagick::setImageProperty() |  |
Imagick::equalizeImage() | Imagick::getImageMatteColor() | Imagick::setImageRedPrimary() |  |
Imagick::evaluateImage() | Imagick::getImageMatte() | Imagick::setImageRenderingIntent() |  |
Imagick::flattenImages() | Imagick::getImagePage() | Imagick::setImageResolution() |  |
Imagick::flipImage() | Imagick::getImagePixelColor() | Imagick::setImageScene() |  |
Imagick::flopImage() | Imagick::getImageProfile() | Imagick::setImageTicksPerSecond() |  |
| Imagick::getImageProperty() | Imagick::setImageType() |  |
Imagick::fxImage() | Imagick::getImageRedPrimary() | Imagick::setImageUnits() |  |
Imagick::gammaImage() | Imagick::getImageRegion() | Imagick::setImageVirtualPixelMethod() |  |
Imagick::gaussianBlurImage() | Imagick::getImageRenderingIntent() | Imagick::setImageWhitepoint() |  |
Imagick::implodeImage() | Imagick::getImageResolution() | Imagick::setInterlaceScheme() |  |
Imagick::levelImage() | Imagick::getImageScene() | Imagick::setOption() |  |
Imagick::linearStretchImage() | Imagick::getImageSignature() | Imagick::setPage() |  |
Imagick::magnifyImage() | Imagick::getImageTicksPerSecond() | Imagick::setResolution() |  |
Imagick::matteFloodFillImage() | Imagick::getImageTotalInkDensity() | Imagick::setResourceLimit() |  |
Imagick::medianFilterImage() | Imagick::getImageType() | Imagick::setSamplingFactors() |  |
Imagick::minifyImage() | Imagick::getImageUnits() | Imagick::setSizeOffset() |  |
Imagick::modulateImage() | Imagick::getImageVirtualPixelMethod() | Imagick::setSize() |  |
Imagick::montageImage() | Imagick::getImageWhitepoint() | Imagick::setType() |  |
Imagick::morphImages() | Imagick::getImageWidth() |  |  |
Imagick::mosaicImages() | Imagick::getImage() |  |  |
Imagick::motionBlurImage() | Imagick::getInterlaceScheme() |  |  |
Imagick::negateImage() | Imagick::getNumberImages() |  |  |
Imagick::normalizeImage() | Imagick::getOption() |  |  |
Imagick::oilPaintImage() | Imagick::getPackageName() |  |  |
Imagick::optimizeImageLayers() | Imagick::getPage() |  |  |
Imagick::paintOpaqueImage() | Imagick::getPixelIterator() |  |  |
Imagick::paintTransparentImage() | Imagick::getPixelRegionIterator() |  |  |
Imagick::posterizeImage() | Imagick::getQuantumDepth() |  |  |
Imagick::radialBlurImage() | Imagick::getQuantumRange() |  |  |
Imagick::raiseImage() | Imagick::getResourceLimit() |  |  |
Imagick::randomThresholdImage() | Imagick::getResource() |  |  |
Imagick::reduceNoiseImage() | Imagick::getSamplingFactors() |  |  |
Imagick::render() | Imagick::getSizeOffset() |  |  |
Imagick::resampleImage() | Imagick::getSize() |  |  |
Imagick::resizeImage() | Imagick::identifyImage() |  |  |
Imagick::rollImage() | Imagick::getImageSize() |  |  |
Imagick::rotateImage() |  |  |  |
Imagick::sampleImage() |  |  |  |
Imagick::scaleImage() |  |  |  |
Imagick::separateImageChannel() |  |  |  |
Imagick::sepiaToneImage() |  |  |  |
Imagick::shadeImage() |  |  |  |
Imagick::shadowImage() |  |  |  |
Imagick::sharpenImage() |  |  |  |
Imagick::shaveImage() |  |  |  |
Imagick::shearImage() |  |  |  |
Imagick::sigmoidalContrastImage() |  |  |  |
Imagick::sketchImage() |  |  |  |
Imagick::solarizeImage() |  |  |  |
Imagick::spliceImage() |  |  |  |
Imagick::spreadImage() |  |  |  |
Imagick::steganoImage() |  |  |  |
Imagick::stereoImage() |  |  |  |
Imagick::stripImage() |  |  |  |
Imagick::swirlImage() |  |  |  |
Imagick::textureImage() |  |  |  |
Imagick::thresholdImage() |  |  |  |
Imagick::thumbnailImage() |  |  |  |
Imagick::tintImage() |  |  |  |
Imagick::transverseImage() |  |  |  |
Imagick::trimImage() |  |  |  |
Imagick::uniqueImageColors() |  |  |  |
Imagick::unsharpMaskImage() |  |  |  |
Imagick::vignetteImage() |  |  |  |
Imagick::waveImage() |  |  |  |
Imagick::whiteThresholdImage() |  |  |  |

# Imagick::adaptiveBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveBlurImage — Adds adaptive blur filter to image

### Beschreibung

public function Imagick::adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Adds an adaptive blur filter to image. The intensity of an adaptive blur depends is dramatically decreased at edge of the image, whereas a standard blur is uniform across the image. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`radius`

  The radius of the Gaussian, in pixels, not counting the center pixel. Provide a value of 0 and the radius will be chosen automagically.

`sigma`

  The standard deviation of the Gaussian, in pixels.

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::adaptiveBlurImage():

Adaptively blur an image, then display to the browser.

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('test.jpg');

    $image->adaptiveBlurImage(5,3);
    echo $image;

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- Imagick::blurImage() - Adds blur filter to image
- Imagick::motionBlurImage() - Simulates motion blur
- Imagick::radialBlurImage() - Radial blurs an image

# Imagick::adaptiveResizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveResizeImage — Adaptively resize image with data dependent triangulation

### Beschreibung

public function Imagick::adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Adaptively resize image with data-dependent triangulation. Avoids blurring across sharp color changes. Most useful when used to shrink images slightly to a slightly smaller "web size"; may not look good when a full-sized image is adaptively resized to a thumbnail. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

> Hinweis: Das Verhalten des Parameters `bestfit` hat sich mit Imagick 3.0.0 geändert. Vor dieser Version wurde ein Bild der Größe 200x150 bei der angegebenen Größe von 400x400 nicht verändert. In Imagick 3.0.0 und späteren Versionen wird dieses Bild auf die Größe 400x300 hochgerechnet, da dies die passendste größe für die angegebene Bildgröße ist. Wenn der `bestfit`-Parameter angegeben wird, so muss sowohl eine Breite als auch eine Höhe angegeben werden.

### Parameter-Liste

`columns`

  The number of columns in the scaled image.

`rows`

  The number of rows in the scaled image.

`bestfit`

  Whether to fit the image inside a bounding box.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Added optional fit parameter.
PECL imagick 2.1.0 | This method now supports proportional scaling. Pass zero as either parameter for proportional scaling.

### Beispiele

Beispiel #1 Using Imagick::adaptiveResizeImage()

Resize an image to a standard size for the web. This method works best when resizing to a size only slightly smaller than the previous image size.

    <?php
    header('Content-type: image/jpeg');

    $image = new Imagick('image.jpg');
    $image->adaptiveResizeImage(1024,768);

    echo $image;
    ?>

### Siehe auch

- Imagick::chopImage() - Removes a region of an image and trims
- Imagick::cropImage() - Extracts a region of the image
- Imagick::magnifyImage() - Scales an image proportionally 2x
- Imagick::minifyImage() - Scales an image proportionally to half its size
- Imagick::resizeImage() - Scales an image
- Imagick::scaleImage() - Scales the size of an image
- Imagick::shaveImage() - Shaves pixels from the image edges
- Imagick::thumbnailImage() - Changes the size of an image
- Imagick::trimImage() - Remove edges from the image

# Imagick::adaptiveSharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveSharpenImage — Adaptively sharpen the image

### Beschreibung

public function Imagick::adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Adaptively sharpen the image by sharpening more intensely near image edges and less intensely far from edges. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`radius`

  The radius of the Gaussian, in pixels, not counting the center pixel. Use 0 for auto-select.

`sigma`

  The standard deviation of the Gaussian, in pixels.

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 A Imagick::adaptiveSharpenImage() example

Adaptively sharpen the image with radius 2 and sigma 1.

    <?php
    try {
        $image = new Imagick('image.png');
        $image->adaptiveSharpenImage(2,1);
    } catch(ImagickException $e) {
        echo 'Error: ' , $e->getMessage();
        die();
    }
    header('Content-type: image/png');
    echo $image;
    ?>

### Siehe auch

- Imagick::sharpenImage() - Sharpens an image

# Imagick::adaptiveThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveThresholdImage — Selects a threshold for each pixel based on a range of intensity

### Beschreibung

public function Imagick::adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool

Selects an individual threshold for each pixel based on the range of intensity values in its local neighborhood. This allows for thresholding of an image whose global intensity histogram doesn't contain distinctive peaks.

### Parameter-Liste

`width`

  Width of the local neighborhood.

`height`

  Height of the local neighborhood.

`offset`

  The mean offset

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::adaptiveThresholdImage()

    <?php
    function adaptiveThresholdImage($imagePath, $width, $height, $adaptiveOffset) {
        $imagick = new \Imagick(realpath($imagePath));
        $adaptiveOffsetQuantum = intval($adaptiveOffset * \Imagick::getQuantum());
        $imagick->adaptiveThresholdImage($width, $height, $adaptiveOffsetQuantum);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::addImage

(PECL imagick 2, PECL imagick 3)

Imagick::addImage — Adds new image to Imagick object image list

### Beschreibung

public function Imagick::addImage(Imagick `$source`): bool

Adds new image to Imagick object from the current position of the source object. After the operation iterator position is moved at the end of the list.

### Parameter-Liste

`source`

  The source Imagick object

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::addNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::addNoiseImage — Adds random noise to the image

### Beschreibung

public function Imagick::addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Adds random noise to the image.

### Parameter-Liste

`noise_type`

  The type of the noise. Refer to this list of noise constants.

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::addNoiseImage()

    <?php
    function addNoiseImage($noiseType, $imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->addNoiseImage($noiseType, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::affineTransformImage

(PECL imagick 2, PECL imagick 3)

Imagick::affineTransformImage — Transforms an image

### Beschreibung

public function Imagick::affineTransformImage(ImagickDraw `$matrix`): bool

Transforms an image as dictated by the affine matrix.

### Parameter-Liste

`matrix`

  The affine matrix

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::affineTransformImage()

    <?php
    function affineTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $draw = new \ImagickDraw();

        $angle = deg2rad(40);

        $affineRotate = array(
            "sx" => cos($angle), "sy" => cos($angle),
            "rx" => sin($angle), "ry" => -sin($angle),
            "tx" => 0, "ty" => 0,
        );

        $draw->affine($affineRotate);

        $imagick->affineTransformImage($draw);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::animateImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::animateImages — Animates an image or images

### Beschreibung

public function Imagick::animateImages(string `$x_server`): bool

This method animates the image onto a local or remote X server. This method is not available on Windows. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`x_server`

  X server address

### Rückgabewerte

Liefert `true` bei Erfolg.

### Siehe auch

- Imagick::displayImage() - Displays an image

# Imagick::annotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::annotateImage — Annotates an image with text

### Beschreibung

public function Imagick::annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool

Annotates an image with text.

### Parameter-Liste

`draw_settings`

  The ImagickDraw object that contains settings for drawing the text

`x`

  Horizontal offset in pixels to the left of text

`y`

  Vertical offset in pixels to the baseline of text

`angle`

  The angle at which to write the text

`text`

  The string to draw

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Using Imagick::annotateImage():

Annotate text on an empty image

    <?php
    /* Create some objects */
    $image = new Imagick();
    $draw = new ImagickDraw();
    $pixel = new ImagickPixel( 'gray' );

    /* New image */
    $image->newImage(800, 75, $pixel);

    /* Black text */
    $draw->setFillColor('black');

    /* Font properties */
    $draw->setFont('Bookman-DemiItalic');
    $draw->setFontSize( 30 );

    /* Create text */
    $image->annotateImage($draw, 10, 45, 0, 'The quick brown fox jumps over the lazy dog');

    /* Give image a format */
    $image->setImageFormat('png');

    /* Output the image with headers */
    header('Content-type: image/png');
    echo $image;

    ?>

### Siehe auch

- ImagickDraw::annotation() - Draws text on the image
- ImagickDraw::setFont() - Sets the fully-specified font to use when annotating with text

# Imagick::appendImages

(PECL imagick 2, PECL imagick 3)

Imagick::appendImages — Append a set of images

### Beschreibung

public function Imagick::appendImages(bool `$stack`): Imagick

Append a set of images into one larger image.

### Parameter-Liste

`stack`

  Whether to stack the images vertically. By default (or if `false` is specified) images are stacked left-to-right. If `stack` is `true`, images are stacked top-to-bottom.

### Rückgabewerte

Returns Imagick instance on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::appendImages() example

    <?php

    /* Create new imagick object */
    $im = new Imagick();

    /* create red, green and blue images */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Append the images into one */
    $im->resetIterator();
    $combined = $im->appendImages(true);

    /* Output the image */
    $combined->setImageFormat("png");
    header("Content-Type: image/png");
    echo $combined;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# Imagick::autoLevelImage

(PECL imagick 3 >= 3.3.0)

Imagick::autoLevelImage — Adjusts the levels of a particular image channel

### Beschreibung

public function Imagick::autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Adjusts the levels of a particular image channel by scaling the minimum and maximum values to the full quantum range.

### Parameter-Liste

`channel`

  Which channel should the auto-levelling should be done on.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::autoLevelImage()

    <?php
    function autoLevelImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->autoLevelImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::averageImages

(PECL imagick 2, PECL imagick 3)

Imagick::averageImages — Average a set of images

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::averageImages(): Imagick

Average a set of images.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a new Imagick object on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::blackThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::blackThresholdImage — Forces all pixels below the threshold into black

### Beschreibung

public function Imagick::blackThresholdImage(mixed `$threshold`): bool

Is like Imagick::thresholdImage() but forces all pixels below the threshold into black while leaving all pixels above the threshold unchanged.

### Parameter-Liste

`threshold`

  The threshold below which everything turns black

### Rückgabewerte

Liefert `true` bei Erfolg.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as a parameter. Previous versions allow only an ImagickPixel object.

### Beispiele

Beispiel #1 Imagick::blackThresholdImage()

    <?php
    function blackThresholdImage($imagePath, $thresholdColor) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blackthresholdimage($thresholdColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blueShiftImage

(PECL imagick 3 >= 3.3.0)

Imagick::blueShiftImage — Mutes the colors of the image

### Beschreibung

public function Imagick::blueShiftImage(float `$factor` = 1.5): bool

Mutes the colors of the image to simulate a scene at nighttime in the moonlight.

### Parameter-Liste

`factor`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::blueShiftImage()

    <?php
    function blueShiftImage($imagePath, $blueShift) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->blueShiftImage($blueShift);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::blurImage

(PECL imagick 2, PECL imagick 3)

Imagick::blurImage — Adds blur filter to image

### Beschreibung

public function Imagick::blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool

Adds blur filter to image. Optional third parameter to blur a specific channel.

### Parameter-Liste

`radius`

  Blur radius

`sigma`

  Standard deviation

`channel`

  The Channeltype constant. When not supplied, all channels are blurred.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::blurImage():

Blur an image, then display to the browser.

    <?php

    header('Content-type: image/jpeg');

    $image = new Imagick('test.jpg');

    $image->blurImage(5,3);
    echo $image;

    ?>

### Siehe auch

- Imagick::adaptiveBlurImage() - Adds adaptive blur filter to image
- Imagick::motionBlurImage() - Simulates motion blur
- Imagick::radialBlurImage() - Radial blurs an image

# Imagick::borderImage

(PECL imagick 2, PECL imagick 3)

Imagick::borderImage — Surrounds the image with a border

### Beschreibung

public function Imagick::borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool

Surrounds the image with a border of the color defined by the bordercolor ImagickPixel object.

### Parameter-Liste

`bordercolor`

  ImagickPixel object or a string containing the border color

`width`

  Border width

`height`

  Border height

### Rückgabewerte

Liefert `true` bei Erfolg.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter. Previous versions allow only an ImagickPixel object.

### Beispiele

Beispiel #1 Imagick::borderImage()

    <?php
    function borderImage($imagePath, $color, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->borderImage($color, $width, $height);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::brightnessContrastImage

(PECL imagick 3 >= 3.3.0)

Imagick::brightnessContrastImage — Change the brightness and/or contrast of an image

### Beschreibung

public function Imagick::brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Change the brightness and/or contrast of an image. It converts the brightness and contrast parameters into slope and intercept and calls a polynomial function to apply to the image.

### Parameter-Liste

`brightness`

`contrast`

`channel`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::brightnessContrastImage()

    <?php
    function brightnessContrastImage($imagePath, $brightness, $contrast, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->brightnessContrastImage($brightness, $contrast, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::charcoalImage

(PECL imagick 2, PECL imagick 3)

Imagick::charcoalImage — Simulates a charcoal drawing

### Beschreibung

public function Imagick::charcoalImage(float `$radius`, float `$sigma`): bool

Simulates a charcoal drawing.

### Parameter-Liste

`radius`

  The radius of the Gaussian, in pixels, not counting the center pixel

`sigma`

  The standard deviation of the Gaussian, in pixels

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::charcoalImage()

    <?php
    function charcoalImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->charcoalImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::chopImage

(PECL imagick 2, PECL imagick 3)

Imagick::chopImage — Removes a region of an image and trims

### Beschreibung

public function Imagick::chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Removes a region of an image and collapses the image to occupy the removed portion.

### Parameter-Liste

`width`

  Width of the chopped area

`height`

  Height of the chopped area

`x`

  X origo of the chopped area

`y`

  Y origo of the chopped area

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::chopImage():

Example of using Imagick::chopImage

    <?php
    /* Create some objects */
    $image = new Imagick();
    $pixel = new ImagickPixel( 'gray' );

    /* New image */
    $image->newImage(400, 200, $pixel);

    /* Chop image */
    $image->chopImage(200, 200, 0, 0);

    /* Give image a format */
    $image->setImageFormat('png');

    /* Output the image with headers */
    header('Content-type: image/png');
    echo $image;

    ?>

### Siehe auch

- Imagick::cropImage() - Extracts a region of the image

# Imagick::clampImage

(PECL imagick 3 >= 3.3.0)

Imagick::clampImage — Restricts the color range from 0 to the quantum depth.

### Beschreibung

public function Imagick::clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Restricts the color range from 0 to the quantum depth.

### Parameter-Liste

`channel`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# Imagick::clear

(PECL imagick 2, PECL imagick 3)

Imagick::clear — Clears all resources associated to Imagick object

### Beschreibung

public function Imagick::clear(): bool

Clears all resources associated to Imagick object

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::clipImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipImage — Clips along the first path from the 8BIM profile

### Beschreibung

public function Imagick::clipImage(): bool

Clips along the first path from the 8BIM profile, if present.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::clipImagePath

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::clipImagePath — Clips along the named paths from the 8BIM profile, if present

### Beschreibung

public function Imagick::clipImagePath(string `$pathname`, string `$inside`): void

Clips along the named paths from the 8BIM profile, if present. Later operations take effect inside the path. Id may be a number if preceded with #, to work on a numbered path, e.g., "#1" to use the first path.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`pathname`

`inside`

### Rückgabewerte

# Imagick::clipPathImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipPathImage — Clips along the named paths from the 8BIM profile

### Beschreibung

public function Imagick::clipPathImage(string `$pathname`, bool `$inside`): bool

Clips along the named paths from the 8BIM profile, if present. Later operations take effect inside the path. It may be a number if preceded with #, to work on a numbered path, e.g., "#1" to use the first path.

### Parameter-Liste

`pathname`

  The name of the path

`inside`

  If `true` later operations take effect inside clipping path. Otherwise later operations take effect outside clipping path.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::clone

(PECL imagick 2, PECL imagick 3)

Imagick::clone — Makes an exact copy of the Imagick object

### Beschreibung

public function Imagick::clone(): Imagick

Makes an exact copy of the Imagick object.

Warnung

This function has been DEPRECATED as of imagick 3.1.0 in favour of using the clone keyword.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

A copy of the Imagick object is returned.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 3.1.0 | The method was deprecated in favour of the clone keyword.

### Beispiele

Beispiel #1 Imagick object cloning in different versions of imagick

    <?php
    // Cloning an Imagick object in imagick 2.x and 3.0:
    $newImage = $image->clone();

    // Cloning an Imagick object from 3.1.0 on:
    $newImage = clone $image;
    ?>

# Imagick::clutImage

(PECL imagick 2, PECL imagick 3)

Imagick::clutImage — Replaces colors in the image

### Beschreibung

public function Imagick::clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Replaces colors in the image from a color lookup table. Optional second parameter to replace colors in a specific channel. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`lookup_table`

  Imagick object containing the color lookup table

`channel`

  The Channeltype constant. When not supplied, default channels are replaced.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Using Imagick::clutImage():

Replace colors in the image from a color lookup table.

    <?php
    $image = new Imagick('test.jpg');
    $clut = new Imagick();
    $clut->newImage(1, 1, new ImagickPixel('black'));
    $image->clutImage($clut);
    $image->writeImage('test_out.jpg');
    ?>

### Siehe auch

- Imagick::adaptiveBlurImage() - Adds adaptive blur filter to image
- Imagick::motionBlurImage() - Simulates motion blur
- Imagick::radialBlurImage() - Radial blurs an image

# Imagick::coalesceImages

(PECL imagick 2, PECL imagick 3)

Imagick::coalesceImages — Composites a set of images

### Beschreibung

public function Imagick::coalesceImages(): Imagick

Composites a set of images while respecting any page offsets and disposal methods. GIF, MIFF, and MNG animation sequences typically start with an image background and each subsequent image varies in size and offset. Returns a new Imagick object where each image in the sequence is the same size as the first and composited with the next image in the sequence.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a new Imagick object on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::colorFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorFloodfillImage — Changes the color value of any pixel that matches target

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Changes the color value of any pixel that matches target and is an immediate neighbor.

### Parameter-Liste

`fill`

  ImagickPixel object containing the fill color

`fuzz`

  The amount of fuzz. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color for the purposes of the floodfill.

`bordercolor`

  ImagickPixel object containing the border color

`x`

  X start position of the floodfill

`y`

  Y start position of the floodfill

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as first and third parameter. Previous versions allow only an ImagickPixel object.

# Imagick::colorizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorizeImage — Blends the fill color with the image

### Beschreibung

public function Imagick::colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool

Blends the fill color with each pixel in the image.

### Parameter-Liste

`colorize`

  ImagickPixel object or a string containing the colorize color

`opacity`

  ImagickPixel object or an float containing the opacity value. 1.0 is fully opaque and 0.0 is fully transparent.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter and a float representing the opacity value as the second parameter. Previous versions allow only an ImagickPixel objects.

### Beispiele

Beispiel #1 Imagick::colorizeImage()

    <?php
    function colorizeImage($imagePath, $color, $opacity) {
        $imagick = new \Imagick(realpath($imagePath));
        $opacity = $opacity / 255.0;
        $opacityColor = new \ImagickPixel("rgba(0, 0, 0, $opacity)");
        $imagick->colorizeImage($color, $opacityColor);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::colorMatrixImage

(PECL imagick 3 >= 3.3.0)

Imagick::colorMatrixImage — Apply color transformation to an image

### Beschreibung

public function Imagick::colorMatrixImage(array `$color_matrix`): bool

Apply color transformation to an image. The method permits saturation changes, hue rotation, luminance to alpha, and various other effects. Although variable-sized transformation matrices can be used, typically one uses a 5x5 matrix for an RGBA image and a 6x6 for CMYKA (or RGBA with offsets). The matrix is similar to those used by Adobe Flash except offsets are in column 6 rather than 5 (in support of CMYKA images) and offsets are normalized (divide Flash offset by 255)

### Parameter-Liste

`color_matrix`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::colorMatrixImage()

    <?php
    function colorMatrixImage($imagePath, $colorMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOpacity(1);

        //A color matrix should look like:
        //    $colorMatrix = [
        //        1.5, 0.0, 0.0, 0.0, 0.0, -0.157,
        //        0.0, 1.0, 0.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 1.5, 0.0, 0.0, -0.157,
        //        0.0, 0.0, 0.0, 1.0, 0.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 1.0,  0.0,
        //        0.0, 0.0, 0.0, 0.0, 0.0,  1.0
        //    ];

        $background = new \Imagick();
        $background->newPseudoImage($imagick->getImageWidth(), $imagick->getImageHeight(),  "pattern:checkerboard");

        $background->setImageFormat('png');

        $imagick->setImageFormat('png');
        $imagick->colorMatrixImage($colorMatrix);

        $background->compositeImage($imagick, \Imagick::COMPOSITE_ATOP, 0, 0);

        header("Content-Type: image/png");
        echo $background->getImageBlob();
    }

    ?>

# Imagick::combineImages

(PECL imagick 2, PECL imagick 3)

Imagick::combineImages — Combines one or more images into a single image

### Beschreibung

public function Imagick::combineImages(int `$channelType`): Imagick

Combines one or more images into a single image. The grayscale value of the pixels of each image in the sequence is assigned in order to the specified channels of the combined image. The typical ordering would be image 1 => Red, 2 => Green, 3 => Blue, etc.

### Parameter-Liste

`channelType`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::commentImage

(PECL imagick 2, PECL imagick 3)

Imagick::commentImage — Adds a comment to your image

### Beschreibung

public function Imagick::commentImage(string `$comment`): bool

Adds a comment to your image.

### Parameter-Liste

`comment`

  The comment to add

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::commentImage():

Commenting an image and retrieving the comment:

    <?php

    /* Create new Imagick object */
    $im = new imagick();

    /* Create an empty image */
    $im->newImage(100, 100, new ImagickPixel("red"));

    /* Add comment to the image */
    $im->commentImage("Hello World!");

    /* Display the comment */
    echo $im->getImageProperty("comment");

    ?>

# Imagick::compareImageChannels

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageChannels — Returns the difference in one or more images

### Beschreibung

public function Imagick::compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array

Compares one or more images and returns the difference image.

### Parameter-Liste

`image`

  Imagick object containing the image to compare.

`channelType`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

`metricType`

  One of the metric type constants.

### Rückgabewerte

Array consisting of `new_wand` and `distortion`.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::compareImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageLayers — Returns the maximum bounding region between images

### Beschreibung

public function Imagick::compareImageLayers(int `$method`): Imagick

Compares each image with the next in a sequence and returns the maximum bounding region of any pixel differences it discovers. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`method`

  One of the layer method constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::compareImageLayers()

Comparing image layers

    <?php
    /* create new imagick object */
    $im = new Imagick("test.gif");

    /* optimize the image layers */
    $result = $im->compareImageLayers(imagick::LAYERMETHOD_COALESCE);

    /* work on the $result */
    ?>

### Siehe auch

- Imagick::optimizeImageLayers() - Removes repeated portions of images to optimize
- Imagick::writeImages() - Writes an image or image sequence
- Imagick::writeImage() - Writes an image to the specified filename

# Imagick::compareImages

(PECL imagick 2, PECL imagick 3)

Imagick::compareImages — Compares an image to a reconstructed image

### Beschreibung

public function Imagick::compareImages(Imagick `$compare`, int `$metric`): array

Returns an array containing a reconstructed image and the difference between images.

### Parameter-Liste

`compare`

  An image to compare to.

`metric`

  Provide a valid metric type constant. Refer to this list of metric constants.

### Rückgabewerte

Returns an array containing a reconstructed image and the difference between images.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::compareImages():

Compare images and display the reconstructed image

    <?php

    $image1 = new imagick("image1.png");
    $image2 = new imagick("image2.png");

    $result = $image1->compareImages($image2, Imagick::METRIC_MEANSQUAREERROR);
    $result[0]->setImageFormat("png");

    header("Content-Type: image/png");
    echo $result[0];

    ?>

# Imagick::compositeImage

(PECL imagick 2, PECL imagick 3)

Imagick::compositeImage — Composite one image onto another

### Beschreibung

public function Imagick::compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Composite one image onto another at the specified offset. Any extra arguments needed for the compose algorithm should passed to setImageArtifact with 'compose:args' as the first parameter and the data as the second parameter.

### Parameter-Liste

`composite_object`

  Imagick object which holds the composite image

`compose`

  Composite operator. See Composite Operator Constants

`x`

  The column offset of the composited image

`y`

  The row offset of the composited image

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Using Imagick::compositeImage():

Composite two images with the 'mathematics' compose method

    <?php

    // Equivalent to running the command
    // convert src1.png src2.png -compose mathematics -define compose:args="1,0,-0.5,0.5" -composite output.png

    $src1 = new \Imagick("./src1.png");
    $src2 = new \Imagick("./src2.png");

    $src1->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
    $src1->setImageArtifact('compose:args', "1,0,-0.5,0.5");
    $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);
    $src1->writeImage("./output.png");

    ?>

### Siehe auch

- Imagick::setImageArtifact() - Set image artifact

# Imagick::__construct

(PECL imagick 2, PECL imagick 3)

Imagick::__construct — The Imagick constructor

### Beschreibung

public function Imagick::__construct(mixed `$files` = ?)

Creates an Imagick instance for a specified image or set of images.

### Parameter-Liste

`files`

  The path to an image to load or an array of paths. Paths can include wildcards for file names, or can be URLs.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::contrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastImage — Change the contrast of the image

### Beschreibung

public function Imagick::contrastImage(bool `$sharpen`): bool

Enhances the intensity differences between the lighter and darker elements of the image. Set sharpen to a value other than 0 to increase the image contrast otherwise the contrast is reduced.

### Parameter-Liste

`sharpen`

  The sharpen value

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::contrastImage()

    <?php
    function contrastImage($imagePath, $contrastType) {
        $imagick = new \Imagick(realpath($imagePath));
        if ($contrastType != 2) {
            $imagick->contrastImage($contrastType);
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::contrastStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastStretchImage — Enhances the contrast of a color image

### Beschreibung

public function Imagick::contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Enhances the contrast of a color image by adjusting the pixels color to span the entire range of colors available. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`black_point`

  The black point.

`white_point`

  The white point.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. `Imagick::CHANNEL_ALL`. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::convolveImage

(PECL imagick 2, PECL imagick 3)

Imagick::convolveImage — Applies a custom convolution kernel to the image

### Beschreibung

public function Imagick::convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Applies a custom convolution kernel to the image.

### Parameter-Liste

`kernel`

  The convolution kernel

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::convolveImage()

    <?php
    function convolveImage($imagePath, $bias, $kernelMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        //$edgeFindingKernel = [-1, -1, -1, -1, 8, -1, -1, -1, -1,];
        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($kernelMatrix);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::count

(PECL imagick 3 >= 3.3.0)

Imagick::count — Get the number of images

### Beschreibung

public function Imagick::count(int `$mode` = 0): int

Returns the number of images.

### Parameter-Liste

`mode`

  An unused argument. Currently there is a non-particularly well defined feature in PHP where calling count() on a countable object might (or might not) require this method to accept a parameter. This parameter is here to be conformant with the interface of countable, even though the param is not used.

### Rückgabewerte

Returns the number of images.

# Imagick::cropImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropImage — Extracts a region of the image

### Beschreibung

public function Imagick::cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Extracts a region of the image.

### Parameter-Liste

`width`

  The width of the crop

`height`

  The height of the crop

`x`

  The X coordinate of the cropped region's top left corner

`y`

  The Y coordinate of the cropped region's top left corner

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::cropImage()

    <?php
    function cropImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->cropImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::cropThumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropThumbnailImage — Creates a crop thumbnail

### Beschreibung

public function Imagick::cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool

Creates a fixed size thumbnail by first scaling the image up or down and cropping a specified area from the center.

### Parameter-Liste

`width`

  The width of the thumbnail

`height`

  The Height of the thumbnail

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::current

(PECL imagick 2, PECL imagick 3)

Imagick::current — Returns a reference to the current Imagick object

### Beschreibung

public function Imagick::current(): Imagick

Returns reference to the current imagick object with image pointer at the correct sequence.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns self on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::cycleColormapImage

(PECL imagick 2, PECL imagick 3)

Imagick::cycleColormapImage — Displaces an image's colormap

### Beschreibung

public function Imagick::cycleColormapImage(int `$displace`): bool

Displaces an image's colormap by a given number of positions. If you cycle the colormap a number of times you can produce a psychedelic effect.

### Parameter-Liste

`displace`

  The amount to displace the colormap.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::decipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::decipherImage — Deciphers an image

### Beschreibung

public function Imagick::decipherImage(string `$passphrase`): bool

Deciphers image that has been enciphered before. The image must be enciphered using Imagick::encipherImage(). Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.9 oder höher kompiliert wurde.

### Parameter-Liste

`passphrase`

  The passphrase

### Rückgabewerte

Liefert `true` bei Erfolg.

### Siehe auch

- Imagick::encipherImage() - Enciphers an image

# Imagick::deconstructImages

(PECL imagick 2, PECL imagick 3)

Imagick::deconstructImages — Returns certain pixel differences between images

### Beschreibung

public function Imagick::deconstructImages(): Imagick

Compares each image with the next in a sequence and returns the maximum bounding region of any pixel differences it discovers.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a new Imagick object on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::deleteImageArtifact

(PECL imagick 3)

Imagick::deleteImageArtifact — Delete image artifact

### Beschreibung

public function Imagick::deleteImageArtifact(string `$artifact`): bool

Deletes an artifact associated with the image. The difference between image properties and image artifacts is that properties are public and artifacts are private. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.5.7 oder höher kompiliert wurde.

### Parameter-Liste

`artifact`

  The name of the artifact to delete

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Siehe auch

- Imagick::setImageArtifact() - Set image artifact
- Imagick::getImageArtifact() - Get image artifact

# Imagick::deleteImageProperty

(PECL imagick 3 >= 3.3.0)

Imagick::deleteImageProperty — Deletes an image property

### Beschreibung

public function Imagick::deleteImageProperty(string `$name`): bool

Deletes an image property.

### Parameter-Liste

`name`

  The name of the property to delete.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::deskewImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.3.0)

Imagick::deskewImage — Removes skew from the image

### Beschreibung

public function Imagick::deskewImage(float `$threshold`): bool

This method can be used to remove skew from for example scanned images where the paper was not properly placed on the scanning surface. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.5 oder höher kompiliert wurde.

### Parameter-Liste

`threshold`

  Deskew threshold

### Rückgabewerte

### Beispiele

Beispiel #1 Imagick::deskewImage()

    <?php
    function deskewImage($threshold) {
        $imagick = new \Imagick(realpath("images/NYTimes-Page1-11-11-1918.jpg"));
        $deskewImagick = clone $imagick;

        //This is the only thing required for deskewing.
        $deskewImagick->deskewImage($threshold);

        //The rest of this example is to make the result obvious - because
        //otherwise the result is not obvious.
        $trim = 9;

        $deskewImagick->cropImage($deskewImagick->getImageWidth() - $trim, $deskewImagick->getImageHeight(), $trim, 0);
        $imagick->cropImage($imagick->getImageWidth() - $trim, $imagick->getImageHeight(), $trim, 0);
        $deskewImagick->resizeimage($deskewImagick->getImageWidth() / 2, $deskewImagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $imagick->resizeimage($imagick->getImageWidth() / 2, $imagick->getImageHeight() / 2, \Imagick::FILTER_LANCZOS, 1);
        $newCanvas = new \Imagick();
        $newCanvas->newimage($imagick->getImageWidth() + $deskewImagick->getImageWidth() + 20, $imagick->getImageHeight(), 'red', 'jpg');
        $newCanvas->compositeimage($imagick, \Imagick::COMPOSITE_COPY, 5, 0);
        $newCanvas->compositeimage($deskewImagick, \Imagick::COMPOSITE_COPY, $imagick->getImageWidth() + 10, 0);

        header("Content-Type: image/jpg");
        echo $newCanvas->getImageBlob();
    }

    ?>

# Imagick::despeckleImage

(PECL imagick 2, PECL imagick 3)

Imagick::despeckleImage — Reduces the speckle noise in an image

### Beschreibung

public function Imagick::despeckleImage(): bool

Reduces the speckle noise in an image while preserving the edges of the original image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::despeckleImage()

    <?php
    function despeckleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->despeckleImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::destroy

(PECL imagick 2, PECL imagick 3)

Imagick::destroy — Destroys the Imagick object

### Beschreibung

public function Imagick::destroy(): bool

Destroys the Imagick object and frees all resources associated with it. This method is deprecated in favour of Imagick::clear.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::displayImage

(PECL imagick 2, PECL imagick 3)

Imagick::displayImage — Displays an image

### Beschreibung

public function Imagick::displayImage(string `$servername`): bool

This method displays an image on a X server.

### Parameter-Liste

`servername`

  The X server name

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::displayImages

(PECL imagick 2, PECL imagick 3)

Imagick::displayImages — Displays an image or image sequence

### Beschreibung

public function Imagick::displayImages(string `$servername`): bool

Displays an image or image sequence on a X server.

### Parameter-Liste

`servername`

  The X server name

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::distortImage

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::distortImage — Distorts an image using various distortion methods

### Beschreibung

public function Imagick::distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool

Distorts an image using various distortion methods, by mapping color lookups of the source image to a new destination image usually of the same size as the source image, unless 'bestfit' is set to `true`.

If 'bestfit' is enabled, and distortion allows it, the destination image is adjusted to ensure the whole source 'image' will just fit within the final destination image, which will be sized and offset accordingly. Also in many cases the virtual offset of the source image will be taken into account in the mapping.

Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`method`

  The method of image distortion. See distortion constants

`arguments`

  The arguments for this distortion method

`bestfit`

  Attempt to resize destination to fit distorted source

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::distortImage():

Distort an image and display to the browser.

    <?php
    /* Create new object */
    $im = new Imagick();

    /* Create new checkerboard pattern */
    $im->newPseudoImage(100, 100, "pattern:checkerboard");

    /* Set the image format to png */
    $im->setImageFormat('png');

    /* Fill new visible areas with transparent */
    $im->setImageVirtualPixelMethod(Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);

    /* Activate matte */
    $im->setImageMatte(true);

    /* Control points for the distortion */
    $controlPoints = array( 10, 10,
                            10, 5,

                            10, $im->getImageHeight() - 20,
                            10, $im->getImageHeight() - 5,

                            $im->getImageWidth() - 10, 10,
                            $im->getImageWidth() - 10, 20,

                            $im->getImageWidth() - 10, $im->getImageHeight() - 10,
                            $im->getImageWidth() - 10, $im->getImageHeight() - 30);

    /* Perform the distortion */
    $im->distortImage(Imagick::DISTORTION_PERSPECTIVE, $controlPoints, true);

    /* Output the image */
    header("Content-Type: image/png");
    echo $im;
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

### Siehe auch

- Imagick::blurImage() - Adds blur filter to image
- Imagick::motionBlurImage() - Simulates motion blur
- Imagick::radialBlurImage() - Radial blurs an image

# Imagick::drawImage

(PECL imagick 2, PECL imagick 3)

Imagick::drawImage — Renders the ImagickDraw object on the current image

### Beschreibung

public function Imagick::drawImage(ImagickDraw `$draw`): bool

Renders the ImagickDraw object on the current image.

### Parameter-Liste

`draw`

  The drawing operations to render on the image.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::edgeImage

(PECL imagick 2, PECL imagick 3)

Imagick::edgeImage — Enhance edges within the image

### Beschreibung

public function Imagick::edgeImage(float `$radius`): bool

Enhance edges within the image with a convolution filter of the given radius. Use radius 0 and it will be auto-selected.

### Parameter-Liste

`radius`

  The radius of the operation.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::edgeImage()

    <?php
    function edgeImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->edgeImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::embossImage

(PECL imagick 2, PECL imagick 3)

Imagick::embossImage — Returns a grayscale image with a three-dimensional effect

### Beschreibung

public function Imagick::embossImage(float `$radius`, float `$sigma`): bool

Returns a grayscale image with a three-dimensional effect. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and it will choose a suitable radius for you.

### Parameter-Liste

`radius`

  The radius of the effect

`sigma`

  The sigma of the effect

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::embossImage()

    <?php
    function embossImage($imagePath, $radius, $sigma) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->embossImage($radius, $sigma);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::encipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::encipherImage — Enciphers an image

### Beschreibung

public function Imagick::encipherImage(string `$passphrase`): bool

Converts plain pixels to enciphered pixels. The image is not readable until it has been deciphered using Imagick::decipherImage() Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.9 oder höher kompiliert wurde.

### Parameter-Liste

`passphrase`

  The passphrase

### Rückgabewerte

Liefert `true` bei Erfolg.

### Siehe auch

- Imagick::decipherImage() - Deciphers an image

# Imagick::enhanceImage

(PECL imagick 2, PECL imagick 3)

Imagick::enhanceImage — Improves the quality of a noisy image

### Beschreibung

public function Imagick::enhanceImage(): bool

Applies a digital filter that improves the quality of a noisy image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::enhanceImage()

    <?php
    function enhanceImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->enhanceImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::equalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::equalizeImage — Equalizes the image histogram

### Beschreibung

public function Imagick::equalizeImage(): bool

Equalizes the image histogram.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::equalizeImage()

    <?php
    function equalizeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->equalizeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::evaluateImage

(PECL imagick 2, PECL imagick 3)

Imagick::evaluateImage — Applies an expression to an image

### Beschreibung

public function Imagick::evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Applies an arithmetic, relational, or logical expression to an image. Use these operators to lighten or darken an image, to increase or decrease contrast in an image, or to produce the "negative" of an image.

### Parameter-Liste

`op`

  The evaluation operator

`constant`

  The value of the operator

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::evaluateImage()

Using evaluateImage to reduce opacity in an image.

    <?php
    // Create new object with the image
    $im = new Imagick('example-alpha.png');

    // Reduce the alpha by 50%
    $im->evaluateImage(Imagick::EVALUATE_DIVIDE, 2, Imagick::CHANNEL_ALPHA);

    // Output the image
    header("Content-Type: image/png");
    echo $im;
    ?>

# Imagick::exportImagePixels

(PECL imagick 2 >=2.3.0, PECL imagick 3)

Imagick::exportImagePixels — Exports raw image pixels

### Beschreibung

public function Imagick::exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array

Exports image pixels into an array. The map defines the ordering of the exported pixels. The size of the returned array is `width * height * strlen(map)`. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.7 oder höher kompiliert wurde.

### Parameter-Liste

`x`

  X-coordinate of the exported area

`y`

  Y-coordinate of the exported area

`width`

  Width of the exported aread

`height`

  Height of the exported area

`map`

  Ordering of the exported pixels. For example `"RGB"`. Valid characters for the map are R, G, B, A, O, C, Y, M, K, I and P.

`STORAGE`

  Refer to this list of pixel type constants

### Rückgabewerte

Returns an array containing the pixels values.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::exportImagePixels()

Export image pixels into an array

    <?php

    /* Create new object */
    $im = new Imagick();

    /* Create new image */
    $im->newPseudoImage(0, 0, "magick:rose");

    /* Export the image pixels */
    $pixels = $im->exportImagePixels(10, 10, 2, 2, "RGB", Imagick::PIXEL_CHAR);

    /* Output */
    var_dump($pixels);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(12) {
      [0]=>
      int(72)
      [1]=>
      int(64)
      [2]=>
      int(57)
      [3]=>
      int(69)
      [4]=>
      int(59)
      [5]=>
      int(43)
      [6]=>
      int(124)
      [7]=>
      int(120)
      [8]=>
      int(-96)
      [9]=>
      int(91)
      [10]=>
      int(84)
      [11]=>
      int(111)
    }

# Imagick::extentImage

(PECL imagick 2, PECL imagick 3)

Imagick::extentImage — Set image size

### Beschreibung

public function Imagick::extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Comfortability method for setting image size. The method sets the image size and allows setting x,y coordinates where the new area begins. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.1 oder höher kompiliert wurde.

Achtung

Prior to ImageMagick 6.5.7-8 (1623), $x was positive when shifting to the left and negative when shifting to the right, and $y was positive when shifting an image up and negative when shifting an image down. Somewhere between ImageMagick 6.3.7 (1591) and ImageMagick 6.5.7-8 (1623), the axes of $x and $y were flipped, so that $x was negative when shifting to the left and positive when shifting to the right, and $y was negative when shifting an image up and positive when shifting an image down. Somewhere between ImageMagick 6.5.7-8 (1623) and ImageMagick 6.6.9-7 (1641), the axes of $x and $y were flipped back to pre-ImageMagick 6.5.7-8 (1623) functionality.

### Parameter-Liste

`width`

  The new width

`height`

  The new height

`x`

  X position for the new size

`y`

  Y position for the new size

### Rückgabewerte

Liefert `true` bei Erfolg.

### Siehe auch

- Imagick::resizeImage() - Scales an image
- Imagick::thumbnailImage() - Changes the size of an image
- Imagick::cropImage() - Extracts a region of the image

# Imagick::filter

(PECL imagick 3 >= 3.3.0)

Imagick::filter — Applies a custom convolution kernel to the image

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool

Applies a custom convolution kernel to the image.

### Parameter-Liste

`ImagickKernel`

  An instance of ImagickKernel that represents either a single kernel or a linked series of kernels.

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::filter()

    <?php
    function filter($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $matrix = [
            [-1, 0, -1],
            [0,  5,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $strength = 0.5;
        $kernel->scale($strength, \Imagick::NORMALIZE_KERNEL_VALUE);
        $kernel->addUnityKernel(1 - $strength);

        $imagick->filter($kernel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::flattenImages

(PECL imagick 2, PECL imagick 3)

Imagick::flattenImages — Merges a sequence of images

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::flattenImages(): Imagick

Merges a sequence of images. This is useful for combining Photoshop layers into a single image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::flipImage

(PECL imagick 2, PECL imagick 3)

Imagick::flipImage — Creates a vertical mirror image

### Beschreibung

public function Imagick::flipImage(): bool

Creates a vertical mirror image by reflecting the pixels around the central x-axis.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::flipImage()

    <?php
    function flipImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flipImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Siehe auch

- Imagick::flopimage() - Creates a horizontal mirror image

# Imagick::floodFillPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::floodFillPaintImage — Changes the color value of any pixel that matches target

### Beschreibung

public function Imagick::floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Changes the color value of any pixel that matches target and is an immediate neighbor. This method is a replacement for deprecated Imagick::paintFloodFillImage(). Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.8 oder höher kompiliert wurde.

### Parameter-Liste

`fill`

  ImagickPixel object or a string containing the fill color

`fuzz`

  Die Menge an Ungenauigkeit. Wird dieser Wert z. B. auf 10 gesetzt, so wird die Farbe Rot bei Intensitäten von 100 und 102 als identisch betrachtet.

`target`

  ImagickPixel object or a string containing the target color to paint

`x`

  X start position of the floodfill

`y`

  Y start position of the floodfill

`invert`

  If `true` paints any pixel that does not match the target color.

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::floodfillPaintImage() example

    <?php

    /* Create new imagick object */
    $im = new Imagick();

    /* create red, green and blue images */
    $im->newImage(100, 50, "red");
    $im->newImage(100, 50, "green");
    $im->newImage(100, 50, "blue");

    /* Append the images into one */
    $im->resetIterator();
    $combined = $im->appendImages(true);

    /* Save the intermediate image for comparison */
    $combined->writeImage("floodfillpaint_intermediate.png");

    /* The target pixel to paint */
    $x = 1;
    $y = 1;

    /* Get the color we are painting */
    $target = $combined->getImagePixelColor($x, $y);

    /* Paints pixel in position 1,1 black and all neighboring
       pixels that match the target color */
    $combined->floodfillPaintImage("black", 1, $target, $x, $y, false);

    /* Save the result */
    $combined->writeImage("floodfillpaint_result.png");
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# Imagick::flopImage

(PECL imagick 2, PECL imagick 3)

Imagick::flopImage — Creates a horizontal mirror image

### Beschreibung

public function Imagick::flopImage(): bool

Creates a horizontal mirror image by reflecting the pixels around the central y-axis.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::flopImage()

    <?php
    function flopImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->flopImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Siehe auch

- Imagick::flipimage() - Creates a vertical mirror image

# Imagick::forwardFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::forwardFourierTransformImage — Implements the discrete Fourier transform (DFT)

### Beschreibung

public function Imagick::forwardFourierTransformimage(bool `$magnitude`): bool

Implements the discrete Fourier transform (DFT) of the image either as a magnitude / phase or real / imaginary image pair.

### Parameter-Liste

`magnitude`

  If true, return as magnitude / phase pair otherwise a real / imaginary image pair.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::forwardFourierTransformImage()

    <?php
    //Utility function for forwardTransformImage
    function createMask() {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(0);
        $draw->setStrokeColor('rgb(255, 255, 255)');
        $draw->setFillColor('rgb(255, 255, 255)');

        //Draw a circle on the y-axis, with its centre
        //at x, y that touches the origin
        $draw->circle(250, 250, 220, 250);

        $imagick = new \Imagick();
        $imagick->newImage(512, 512, "black");
        $imagick->drawImage($draw);
        $imagick->gaussianBlurImage(20, 20);
        $imagick->autoLevelImage();

        return $imagick;
    }

    function forwardFourierTransformImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->resizeimage(512, 512, \Imagick::FILTER_LANCZOS, 1);

        $mask = createMask();
        $imagick->forwardFourierTransformImage(true);

        @$imagick->setimageindex(0);
        $magnitude = $imagick->getimage();

        @$imagick->setimageindex(1);
        $imagickPhase = $imagick->getimage();

        if (true) {
            $imagickPhase->compositeImage($mask, \Imagick::COMPOSITE_MULTIPLY, 0, 0);
        }

        if (false) {
            $output = clone $imagickPhase;
            $output->setimageformat('png');
            header("Content-Type: image/png");
            echo $output->getImageBlob();
        }

        $magnitude->inverseFourierTransformImage($imagickPhase, true);

        $magnitude->setimageformat('png');
        header("Content-Type: image/png");
        echo $magnitude->getImageBlob();
    }

    ?>

# Imagick::frameImage

(PECL imagick 2, PECL imagick 3)

Imagick::frameImage — Adds a simulated three-dimensional border

### Beschreibung

public function Imagick::frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool

Adds a simulated three-dimensional border around the image. The width and height specify the border width of the vertical and horizontal sides of the frame. The inner and outer bevels indicate the width of the inner and outer shadows of the frame.

### Parameter-Liste

`matte_color`

  ImagickPixel object or a string representing the matte color

`width`

  The width of the border

`height`

  The height of the border

`inner_bevel`

  The inner bevel width

`outer_bevel`

  The outer bevel width

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter. Previous versions allow only an ImagickPixel object.

### Beispiele

Beispiel #1 Imagick::frameImage()

    <?php
    function frameImage($imagePath, $color, $width, $height, $innerBevel, $outerBevel) {
        $imagick = new \Imagick(realpath($imagePath));

        $width = $width + $innerBevel + $outerBevel;
        $height = $height + $innerBevel + $outerBevel;

        $imagick->frameimage(
            $color,
            $width,
            $height,
            $innerBevel,
            $outerBevel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::functionImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::functionImage — Applies a function on the image

### Beschreibung

public function Imagick::functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Applies an arithmetic, relational, or logical expression to a pseudo image.

See also » ImageMagick v6 Examples - Image Transformations — Function, Multi-Argument Evaluate

Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.9 oder höher kompiliert wurde.

### Parameter-Liste

`function`

  Refer to this list of function constants

`arguments`

  Array of arguments to pass to this function.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Create a sinusoidal gradient

    <?php
    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(3, -90);
    $imagick->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    header("Content-Type: image/png");
    $imagick->setImageFormat("png");
    echo $imagick->getImageBlob();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Beispiel #2 Create a gradient from the polynomial (4x^2 - 4x + 1)

    <?php
    $imagick = new Imagick();
    $imagick->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(4, -4, 1);
    $imagick->functionImage(Imagick::FUNCTION_POLYNOMIAL, $arguments);

    header("Content-Type: image/png");
    $imagick->setimageformat("png");
    echo $imagick->getImageBlob();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

Beispiel #3 Create a complex gradient from the polynomial (4x^2 - 4x^2 + 1) modulated by a sinusoidal gradient

    <?php
    $imagick1 = new Imagick();
    $imagick1->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(9, -90);
    $imagick1->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);

    $imagick2 = new Imagick();
    $imagick2->newPseudoImage(200, 200, 'gradient:black-white');
    $arguments = array(0.5, 0);
    $imagick2->functionImage(Imagick::FUNCTION_SINUSOID, $arguments);
    $imagick1->compositeimage($imagick2, Imagick::COMPOSITE_MULTIPLY, 0, 0);

    header("Content-Type: image/png");
    $imagick1->setImageFormat("png");
    echo $imagick1->getImageBlob();
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# Imagick::fxImage

(PECL imagick 2, PECL imagick 3)

Imagick::fxImage — Evaluate expression for each pixel in the image

### Beschreibung

public function Imagick::fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick

Evaluate expression for each pixel in the image. Consult » The Fx Special Effects Image Operator for more information.

### Parameter-Liste

`expression`

  The expression.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::fxImage()

    <?php
    function fxImage() {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(200, 200, "xc:white");

        $fx = 'xx=i-w/2; yy=j-h/2; rr=hypot(xx,yy); (.5-rr/140)*1.2+.5';
        $fxImage = $imagick->fxImage($fx);

        header("Content-Type: image/png");
        $fxImage->setimageformat('png');
        echo $fxImage->getImageBlob();
    }

    ?>

# Imagick::gammaImage

(PECL imagick 2, PECL imagick 3)

Imagick::gammaImage — Gamma-corrects an image

### Beschreibung

public function Imagick::gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Gamma-corrects an image. The same image viewed on different devices will have perceptual differences in the way the image's intensities are represented on the screen. Specify individual gamma levels for the red, green, and blue channels, or adjust all three with the gamma parameter. Values typically range from 0.8 to 2.3.

### Parameter-Liste

`gamma`

  The amount of gamma-correction.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::gammaImage()

    <?php
    function gammaImage($imagePath, $gamma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gammaImage($gamma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::gaussianBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::gaussianBlurImage — Blurs an image

### Beschreibung

public function Imagick::gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Blurs an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, the radius should be larger than sigma. Use a radius of 0 and selects a suitable radius for you.

### Parameter-Liste

`radius`

  The radius of the Gaussian, in pixels, not counting the center pixel.

`sigma`

  The standard deviation of the Gaussian, in pixels.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::gaussianBlurImage()

    <?php
    function gaussianBlurImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->gaussianBlurImage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::getColorspace

(PECL imagick 3)

Imagick::getColorspace — Gets the colorspace

### Beschreibung

public function Imagick::getColorspace(): int

Gets the global colorspace value. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.5.7 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an integer which can be compared against COLORSPACE constants.

# Imagick::getCompression

(PECL imagick 2, PECL imagick 3)

Imagick::getCompression — Gets the object compression type

### Beschreibung

public function Imagick::getCompression(): int

Gets the object compression type.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the compression constant

# Imagick::getCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::getCompressionQuality — Gets the object compression quality

### Beschreibung

public function Imagick::getCompressionQuality(): int

Gets the object compression quality.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns integer describing the compression quality

# Imagick::getCopyright

(PECL imagick 2, PECL imagick 3)

Imagick::getCopyright — Returns the ImageMagick API copyright as a string

### Beschreibung

public static function Imagick::getCopyright(): string

Returns the ImageMagick API copyright as a string.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the copyright notice of Imagemagick and Magickwand C API.

# Imagick::getFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getFilename — The filename associated with an image sequence

### Beschreibung

public function Imagick::getFilename(): string

Returns the filename associated with an image sequence.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getFont — Gets font

### Beschreibung

public function Imagick::getFont(): string

Returns the objects font property. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.7 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string containing the font name or `false` if not font is set.

### Siehe auch

- Imagick::setFont() - Sets font
- ImagickDraw::setFont() - Sets the fully-specified font to use when annotating with text
- ImagickDraw::getFont() - Returns the font

# Imagick::getFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getFormat — Returns the format of the Imagick object

### Beschreibung

public function Imagick::getFormat(): string

Returns the format of the Imagick object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the format of the image.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getGravity

(PECL imagick 2, PECL imagick 3)

Imagick::getGravity — Gets the gravity

### Beschreibung

public function Imagick::getGravity(): int

Gets the global gravity property for the Imagick object. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.0 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the gravity property. Refer to the list of gravity constants.

# Imagick::getHomeURL

(PECL imagick 2, PECL imagick 3)

Imagick::getHomeURL — Returns the ImageMagick home URL

### Beschreibung

public static function Imagick::getHomeURL(): string

Returns the ImageMagick home URL.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a link to the imagemagick homepage.

# Imagick::getImage

(PECL imagick 2, PECL imagick 3)

Imagick::getImage — Returns a new Imagick object

### Beschreibung

public function Imagick::getImage(): Imagick

Returns a new Imagick object with the current image sequence.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a new Imagick object with the current image sequence.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageAlphaChannel

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageAlphaChannel — Checks if the image has an alpha channel

### Beschreibung

public function Imagick::getImageAlphaChannel(): bool

Returns whether the image has an alpha channel.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the image has an alpha channel value and `false` if not, i.e. the image is RGB rather than RGBA or CMYK rather than CMYKA.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 3.6.0 | Returns a Boolean now; previously, an Integer was returned.

# Imagick::getImageArtifact

(PECL imagick 3)

Imagick::getImageArtifact — Get image artifact

### Beschreibung

public function Imagick::getImageArtifact(string `$artifact`): string

Gets an artifact associated with the image. The difference between image properties and image artifacts is that properties are public and artifacts are private. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.5.7 oder höher kompiliert wurde.

### Parameter-Liste

`artifact`

  The name of the artifact

### Rückgabewerte

Returns the artifact value on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Siehe auch

- Imagick::setImageArtifact() - Set image artifact
- Imagick::deleteImageArtifact() - Delete image artifact

# Imagick::getImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::getImageAttribute — Returns a named attribute

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::getImageAttribute(string `$key`): string

Returns a named attribute.

### Parameter-Liste

`key`

  The key of the attribute to get.

### Rückgabewerte

# Imagick::getImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBackgroundColor — Returns the image background color

### Beschreibung

public function Imagick::getImageBackgroundColor(): ImagickPixel

Returns the image background color.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an ImagickPixel set to the background color of the image.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBlob — Returns the image sequence as a blob

### Beschreibung

public function Imagick::getImageBlob(): string

Implements direct to memory image formats. It returns the image sequence as a string. The format of the image determines the format of the returned blob (GIF, JPEG, PNG, etc.). To return a different image format, use Imagick::setImageFormat().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the image.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBluePrimary — Returns the chromaticy blue primary point

### Beschreibung

public function Imagick::getImageBluePrimary(): array

Returns the chromaticity blue primary point for the image.

### Parameter-Liste

`x`

  The chromaticity blue primary x-point.

`y`

  The chromaticity blue primary y-point.

### Rückgabewerte

Array consisting of "x" and "y" coordinates of point.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBorderColor — Returns the image border color

### Beschreibung

public function Imagick::getImageBorderColor(): ImagickPixel

Returns the image border color.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDepth — Gets the depth for a particular image channel

### Beschreibung

public function Imagick::getImageChannelDepth(int `$channel`): int

Gets the depth for a particular image channel.

### Parameter-Liste

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::getImageChannelDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDistortion — Compares image channels of an image to a reconstructed image

### Beschreibung

public function Imagick::getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float

Compares one or more image channels of an image to a reconstructed image and returns the specified distortion metric.

### Parameter-Liste

`reference`

  Imagick object to compare to.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

`metric`

  One of the metric type constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageChannelDistortions

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelDistortions — Gets channel distortions

### Beschreibung

public function Imagick::getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float

Compares one or more image channels of an image to a reconstructed image and returns the specified distortion metrics Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.4 oder höher kompiliert wurde.

### Parameter-Liste

`reference`

  Imagick object containing the reference image

`metric`

  Refer to this list of metric type constants.

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Returns a float describing the channel distortion.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageChannelExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelExtrema — Gets the extrema for one or more image channels

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::getImageChannelExtrema(int `$channel`): array

Gets the extrema for one or more image channels. Return value is an associative array with the keys "minima" and "maxima".

### Parameter-Liste

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageChannelKurtosis

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelKurtosis — The getImageChannelKurtosis purpose

### Beschreibung

public function Imagick::getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array

Get the kurtosis and skewness of a specific channel. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.9 oder höher kompiliert wurde.

### Parameter-Liste

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Returns an array with `kurtosis` and `skewness` members.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageChannelMean

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelMean — Gets the mean and standard deviation

### Beschreibung

public function Imagick::getImageChannelMean(int `$channel`): array

Gets the mean and standard deviation of one or more image channels.

### Parameter-Liste

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Returns an array with `"mean"` and `"standardDeviation"` members.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageChannelRange

(PECL imagick 2 >= 2.2.1, PECL imagick 3)

Imagick::getImageChannelRange — Gets channel range

### Beschreibung

public function Imagick::getImageChannelRange(int `$channel`): array

Gets the range for one or more image channels. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.0 oder höher kompiliert wurde.

### Parameter-Liste

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Returns an array containing minima and maxima values of the channel(s).

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageChannelStatistics

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelStatistics — Returns statistics for each channel in the image

### Beschreibung

public function Imagick::getImageChannelStatistics(): array

Returns statistics for each channel in the image. The statistics include the channel depth, its minima and maxima, the mean, and the standard deviation.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::getImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageClipMask — Gets image clip mask

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::getImageClipMask(): Imagick

Returns the image clip mask. The clip mask is an Imagick object containing the clip mask. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an Imagick object containing the clip mask.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColormapColor — Returns the color of the specified colormap index

### Beschreibung

public function Imagick::getImageColormapColor(int `$index`): ImagickPixel

Returns the color of the specified colormap index.

### Parameter-Liste

`index`

  The offset into the image colormap.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageColors

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColors — Gets the number of unique colors in the image

### Beschreibung

public function Imagick::getImageColors(): int

Gets the number of unique colors in the image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an int, the number of unique colors in the image.

# Imagick::getImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColorspace — Gets the image colorspace

### Beschreibung

public function Imagick::getImageColorspace(): int

Gets the image colorspace.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an integer which can be compared against COLORSPACE constants.

# Imagick::getImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageCompose — Returns the composite operator associated with the image

### Beschreibung

public function Imagick::getImageCompose(): int

Returns the composite operator associated with the image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::getImageCompression

(PECL imagick 3 >= 3.3.0)

Imagick::getImageCompression — Gets the current image's compression type

### Beschreibung

public function Imagick::getImageCompression(): int

Gets the current image's compression type.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the compression constant

# Imagick::getImageCompressionQuality

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::getImageCompressionQuality — Gets the current image's compression quality

### Beschreibung

public function Imagick::getImageCompressionQuality(): int

Gets the current image's compression quality

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns integer describing the images compression quality

# Imagick::getImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDelay — Gets the image delay

### Beschreibung

public function Imagick::getImageDelay(): int

Gets the image delay.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image delay.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDepth — Gets the image depth

### Beschreibung

public function Imagick::getImageDepth(): int

Gets the image depth.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The image depth.

# Imagick::getImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDispose — Gets the image disposal method

### Beschreibung

public function Imagick::getImageDispose(): int

Gets the image disposal method.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the dispose method on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDistortion — Compares an image to a reconstructed image

### Beschreibung

public function Imagick::getImageDistortion(MagickWand `$reference`, int `$metric`): float

Compares an image to a reconstructed image and returns the specified distortion metric.

### Parameter-Liste

`reference`

  Imagick object to compare to.

`metric`

  One of the metric type constants.

### Rückgabewerte

Returns the distortion metric used on the image (or the best guess thereof).

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageExtrema — Gets the extrema for the image

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::getImageExtrema(): array

Gets the extrema for the image. Returns an associative array with the keys "min" and "max".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an associative array with the keys "min" and "max".

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFilename — Returns the filename of a particular image in a sequence

### Beschreibung

public function Imagick::getImageFilename(): string

Returns the filename of a particular image in a sequence.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string with the filename of the image.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFormat — Returns the format of a particular image in a sequence

### Beschreibung

public function Imagick::getImageFormat(): string

Returns the format of a particular image in a sequence.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the image format on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGamma — Gets the image gamma

### Beschreibung

public function Imagick::getImageGamma(): float

Gets the image gamma.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image gamma on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageGeometry

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGeometry — Gets the width and height as an associative array

### Beschreibung

public function Imagick::getImageGeometry(): array

Returns the width and height as an associative array.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array with the width/height of the image.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::getImageGeometry()

    <?php
    $imagick = new Imagick();
    $imagick->newImage(100, 200, "black");
    print_r($imagick->getImageGeometry());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [width] => 100
        [height] => 200
    )

# Imagick::getImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageGravity — Gets the image gravity

### Beschreibung

public function Imagick::getImageGravity(): int

Gets the current gravity value of the image. Unlike Imagick::getGravity(), this method returns the gravity defined for the current image sequence. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.4 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the images gravity property. Refer to the list of gravity constants.

# Imagick::getImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGreenPrimary — Returns the chromaticy green primary point

### Beschreibung

public function Imagick::getImageGreenPrimary(): array

Returns the chromaticity green primary point. Returns an array with the keys "x" and "y".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array with the keys "x" and "y" on success, throws an ImagickException on failure.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageHeight

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHeight — Returns the image height

### Beschreibung

public function Imagick::getImageHeight(): int

Returns the image height.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image height in pixels.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageHistogram

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHistogram — Gets the image histogram

### Beschreibung

public function Imagick::getImageHistogram(): array

Returns the image histogram as an array of ImagickPixel objects.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image histogram as an array of ImagickPixel objects.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Generates Imagick::getImageHistogram()

    <?php
    function getColorStatistics($histogramElements, $colorChannel) {
        $colorStatistics = [];

        foreach ($histogramElements as $histogramElement) {
            $color = $histogramElement->getColorValue($colorChannel);
            $color = intval($color * 255);
            $count = $histogramElement->getColorCount();

            if (array_key_exists($color, $colorStatistics)) {
                $colorStatistics[$color] += $count;
            }
            else {
                $colorStatistics[$color] = $count;
            }
        }

        ksort($colorStatistics);

        return $colorStatistics;
    }

    function getImageHistogram($imagePath) {

        $backgroundColor = 'black';

        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(0); //make the lines be as thin as possible

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        $histogramWidth = 256;
        $histogramHeight = 100; // the height for each RGB segment

        $imagick = new \Imagick(realpath($imagePath));
        //Resize the image to be small, otherwise PHP tends to run out of memory
        //This might lead to bad results for images that are pathologically 'pixelly'
        $imagick->adaptiveResizeImage(200, 200, true);
        $histogramElements = $imagick->getImageHistogram();

        $histogram = new \Imagick();
        $histogram->newpseudoimage($histogramWidth, $histogramHeight * 3, 'xc:black');
        $histogram->setImageFormat('png');

        $getMax = function ($carry, $item)  {
            if ($item > $carry) {
                return $item;
            }
            return $carry;
        };

        $colorValues = [
            'red' => getColorStatistics($histogramElements, \Imagick::COLOR_RED),
            'lime' => getColorStatistics($histogramElements, \Imagick::COLOR_GREEN),
            'blue' => getColorStatistics($histogramElements, \Imagick::COLOR_BLUE),
        ];

        $max = array_reduce($colorValues['red'] , $getMax, 0);
        $max = array_reduce($colorValues['lime'] , $getMax, $max);
        $max = array_reduce($colorValues['blue'] , $getMax, $max);

        $scale =  $histogramHeight / $max;

        $count = 0;
        foreach ($colorValues as $color => $values) {
            $draw->setstrokecolor($color);

            $offset = ($count + 1) * $histogramHeight;

            foreach ($values as $index => $value) {
                $draw->line($index, $offset, $index, $offset - ($value * $scale));
            }
            $count++;
        }

        $histogram->drawImage($draw);

        header( "Content-Type: image/png" );
        echo $histogram;
    }

    ?>

# Imagick::getImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIndex — Gets the index of the current active image

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::getImageIndex(): int

Returns the index of the current active image within the Imagick object. This method has been deprecated. See Imagick::getIteratorIndex().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an integer containing the index of the image in the stack.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterlaceScheme — Gets the image interlace scheme

### Beschreibung

public function Imagick::getImageInterlaceScheme(): int

Gets the image interlace scheme.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the interlace scheme as an integer on success. Wirf eine ImagickException bei einem Fehler.

# Imagick::getImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterpolateMethod — Returns the interpolation method

### Beschreibung

public function Imagick::getImageInterpolateMethod(): int

Returns the interpolation method for the specified image. The method is one of the `Imagick::INTERPOLATE_*` constants.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the interpolate method on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIterations — Gets the image iterations

### Beschreibung

public function Imagick::getImageIterations(): int

Gets the image iterations.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image iterations as an integer.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageLength

(PECL imagick 2, PECL imagick 3)

Imagick::getImageLength — Returns the image length in bytes

### Beschreibung

public function Imagick::getImageLength(): int

Returns the image length in bytes

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an int containing the current image size.

### Beispiele

Beispiel #1 Using Imagick::getImageLength():

Getting image length in bytes

    <?php
    $image = new Imagick('test.jpg');
    echo $image->getImageLength() . ' bytes';
    ?>

# Imagick::getImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatte — Return if the image has a matte channel

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::getImageMatte(): bool

Returns `true` if the image has a matte channel otherwise false. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::getImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatteColor — Returns the image matte color

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::getImageMatteColor(): ImagickPixel

Returns the image matte color.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns ImagickPixel object on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageMimeType

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageMimeType — Returns the image mime-type

### Beschreibung

public function Imagick::getImageMimeType(): string

Returns the image mime-type.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# Imagick::getImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::getImageOrientation — Gets the image orientation

### Beschreibung

public function Imagick::getImageOrientation(): int

Gets the image orientation. The return value is one of the orientation constants.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an int on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePage — Returns the page geometry

### Beschreibung

public function Imagick::getImagePage(): array

Returns the page geometry associated with the image in an array with the keys "width", "height", "x", and "y".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the page geometry associated with the image in an array with the keys "width", "height", "x", and "y".

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImagePixelColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePixelColor — Returns the color of the specified pixel

### Beschreibung

public function Imagick::getImagePixelColor(int `$x`, int `$y`): ImagickPixel

Returns the color of the specified pixel.

### Parameter-Liste

`x`

  The x-coordinate of the pixel

`y`

  The y-coordinate of the pixel

### Rückgabewerte

Returns an ImagickPixel instance for the color at the coordinates given.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfile — Returns the named image profile

### Beschreibung

public function Imagick::getImageProfile(string `$name`): string

Returns the named image profile.

### Parameter-Liste

`name`

  The name of the profile to return.

### Rückgabewerte

Returns a string containing the image profile.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageProfiles

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfiles — Returns the image profiles

### Beschreibung

public function Imagick::getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array

Returns all associated profiles that match the pattern. If `false` is passed as second parameter only the profile names are returned. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`pattern`

  The pattern for profile names.

`include_values`

  Whether to return only profile names. If `false` then only profile names will be returned.

### Rückgabewerte

Returns an array containing the image profiles or profile names.

# Imagick::getImageProperties

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperties — Returns the image properties

### Beschreibung

public function Imagick::getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array

Returns all associated properties that match the pattern. If `false` is passed as second parameter only the property names are returned. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`pattern`

  The pattern for property names.

`include_values`

  Whether to return only property names. If `false` then only property names will be returned.

### Rückgabewerte

Returns an array containing the image properties or property names.

### Beispiele

Beispiel #1 Using Imagick::getImageProperties():

An example of extracting EXIF information.

    <?php

    /* Create the object */
    $im = new imagick("/path/to/example.jpg");

    /* Get the EXIF information */
    $exifArray = $im->getImageProperties("exif:*");

    /* Loop through the EXIF properties */
    foreach ($exifArray as $name => $property)
    {
        echo "{$name} => {$property}<br />\n";
    }

    ?>

# Imagick::getImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperty — Returns the named image property

### Beschreibung

public function Imagick::getImageProperty(string `$name`): string

Returns the named image property. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.2 oder höher kompiliert wurde.

### Parameter-Liste

`name`

  name of the property (for example Exif:DateTime)

### Rückgabewerte

Returns a string containing the image property, false if a property with the given name does not exist.

### Beispiele

Beispiel #1 Using Imagick::getImageProperty():

Setting and getting image property

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Siehe auch

- Imagick::setImageProperty() - Sets an image property

# Imagick::getImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRedPrimary — Returns the chromaticity red primary point

### Beschreibung

public function Imagick::getImageRedPrimary(): array

Returns the chromaticity red primary point as an array with the keys "x" and "y".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the chromaticity red primary point as an array with the keys "x" and "y". Wirf eine ImagickException bei einem Fehler.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageRegion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRegion — Extracts a region of the image

### Beschreibung

public function Imagick::getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick

Extracts a region of the image and returns it as a new Imagick object.

### Parameter-Liste

`width`

  The width of the extracted region.

`height`

  The height of the extracted region.

`x`

  X-coordinate of the top-left corner of the extracted region.

`y`

  Y-coordinate of the top-left corner of the extracted region.

### Rückgabewerte

Extracts a region of the image and returns it as a new wand.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRenderingIntent — Gets the image rendering intent

### Beschreibung

public function Imagick::getImageRenderingIntent(): int

Gets the image rendering intent.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image rendering intent.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::getImageResolution — Gets the image X and Y resolution

### Beschreibung

public function Imagick::getImageResolution(): array

Gets the image X and Y resolution.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the resolution as an array.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImagesBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImagesBlob — Returns all image sequences as a blob

### Beschreibung

public function Imagick::getImagesBlob(): string

Implements direct to memory image formats. It returns all image sequences as a string. The format of the image determines the format of the returned blob (GIF, JPEG, PNG, etc.). To return a different image format, use Imagick::setImageFormat().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the images. On failure, throws ImagickException.

# Imagick::getImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::getImageScene — Gets the image scene

### Beschreibung

public function Imagick::getImageScene(): int

Gets the image scene.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image scene.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageSignature

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSignature — Generates an SHA-256 message digest

### Beschreibung

public function Imagick::getImageSignature(): string

Generates an SHA-256 message digest for the image pixel stream.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a string containing the SHA-256 hash of the file.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageSize

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSize — Returns the image length in bytes

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::getImageSize(): int

Returns the image length in bytes. Deprecated in favour of Imagick::getImageLength()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an int containing the current image size.

# Imagick::getImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTicksPerSecond — Gets the image ticks-per-second

### Beschreibung

public function Imagick::getImageTicksPerSecond(): int

Gets the image ticks-per-second.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image ticks-per-second.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageTotalInkDensity

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTotalInkDensity — Gets the image total ink density

### Beschreibung

public function Imagick::getImageTotalInkDensity(): float

Gets the image total ink density.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image total ink density of the image. Wirf eine ImagickException bei einem Fehler.

# Imagick::getImageType

(PECL imagick 2, PECL imagick 3)

Imagick::getImageType — Gets the potential image type

### Beschreibung

public function Imagick::getImageType(): int

Gets the potential image type.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the potential image type.

- `imagick::IMGTYPE_UNDEFINED`
- `imagick::IMGTYPE_BILEVEL`
- `imagick::IMGTYPE_GRAYSCALE`
- `imagick::IMGTYPE_GRAYSCALEMATTE`
- `imagick::IMGTYPE_PALETTE`
- `imagick::IMGTYPE_PALETTEMATTE`
- `imagick::IMGTYPE_TRUECOLOR`
- `imagick::IMGTYPE_TRUECOLORMATTE`
- `imagick::IMGTYPE_COLORSEPARATION`
- `imagick::IMGTYPE_COLORSEPARATIONMATTE`
- `imagick::IMGTYPE_OPTIMIZE`

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::getImageUnits — Gets the image units of resolution

### Beschreibung

public function Imagick::getImageUnits(): int

Gets the image units of resolution.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image units of resolution.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageVirtualPixelMethod — Returns the virtual pixel method

### Beschreibung

public function Imagick::getImageVirtualPixelMethod(): int

Returns the virtual pixel method for the specified image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the virtual pixel method on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWhitePoint — Returns the chromaticity white point

### Beschreibung

public function Imagick::getImageWhitePoint(): array

Returns the chromaticity white point as an associative array with the keys "x" and "y".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the chromaticity white point as an associative array with the keys "x" and "y".

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getImageWidth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWidth — Returns the image width

### Beschreibung

public function Imagick::getImageWidth(): int

Returns the image width.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the image width.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getInterlaceScheme — Gets the object interlace scheme

### Beschreibung

public function Imagick::getInterlaceScheme(): int

Gets the object interlace scheme.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gets the wand interlace scheme.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getIteratorIndex — Gets the index of the current active image

### Beschreibung

public function Imagick::getIteratorIndex(): int

Returns the index of the current active image within the Imagick object. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an integer containing the index of the image in the stack.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::getIteratorIndex():

Create images, set and get the iterator index

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Siehe auch

- Imagick::setIteratorIndex() - Set the iterator position
- Imagick::getImageIndex() - Gets the index of the current active image
- Imagick::setImageIndex() - Set the iterator position

# Imagick::getNumberImages

(PECL imagick 2, PECL imagick 3)

Imagick::getNumberImages — Returns the number of images in the object

### Beschreibung

public function Imagick::getNumberImages(): int

Returns the number of images associated with Imagick object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the number of images associated with Imagick object.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getOption

(PECL imagick 2, PECL imagick 3)

Imagick::getOption — Returns a value associated with the specified key

### Beschreibung

public function Imagick::getOption(string `$key`): string

Returns a value associated within the object for the specified key.

### Parameter-Liste

`key`

  The name of the option

### Rückgabewerte

Returns a value associated with a wand and the specified key.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getPackageName

(PECL imagick 2, PECL imagick 3)

Imagick::getPackageName — Returns the ImageMagick package name

### Beschreibung

public static function Imagick::getPackageName(): string

Returns the ImageMagick package name.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ImageMagick package name as a string.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getPage

(PECL imagick 2, PECL imagick 3)

Imagick::getPage — Returns the page geometry

### Beschreibung

public function Imagick::getPage(): array

Returns the page geometry associated with the Imagick object in an associative array with the keys "width", "height", "x", and "y".

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the page geometry associated with the Imagick object in an associative array with the keys "width", "height", "x", and "y", throwing ImagickException on error.

# Imagick::getPixelIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelIterator — Returns a MagickPixelIterator

### Beschreibung

public function Imagick::getPixelIterator(): ImagickPixelIterator

Returns a MagickPixelIterator.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an ImagickPixelIterator on success.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::getPixelIterator()

    <?php
    function getPixelIterator($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelIterator();

        foreach ($imageIterator as $row => $pixels) { /* Loop through pixel rows */
            foreach ($pixels as $column => $pixel) { /* Loop through the pixels in the row (columns) */
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    $pixel->setColor("rgba(0, 0, 0, 0)"); /* Paint every second pixel black*/
                }
            }
            $imageIterator->syncIterator(); /* Sync the iterator, this is important to do on each iteration */
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# Imagick::getPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelRegionIterator — Get an ImagickPixelIterator for an image section

### Beschreibung

public function Imagick::getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator

Get an ImagickPixelIterator for an image section.

### Parameter-Liste

`x`

  The x-coordinate of the region.

`y`

  The y-coordinate of the region.

`columns`

  The width of the region.

`rows`

  The height of the region.

### Rückgabewerte

Returns an ImagickPixelIterator for an image section.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::getPixelRegionIterator() example

Iterate over the pixels in the top left of the image, changing them to be black.

    <?php
    $im = new Imagick(realpath("./testImage.png"));
    $areaIterator = $im->getPixelRegionIterator(0, 0, 10, 10);

    foreach ($areaIterator as $rowIterator) {
        foreach ($rowIterator as $pixel) {
            // Paint every pixel black
            $pixel->setColor("rgba(0, 0, 0, 0)");
        }
        $areaIterator->syncIterator();
    }
    $im->writeImage("./output.png");
    ?>

# Imagick::getPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getPointSize — Gets point size

### Beschreibung

public function Imagick::getPointSize(): float

Returns the objects point size property. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.7 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a Float containing the point size.

### Siehe auch

- Imagick::setPointSize() - Sets point size

# Imagick::getQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::getQuantum — Returns the ImageMagick quantum range

### Beschreibung

public static function Imagick::getQuantum(): int

Returns the ImageMagick quantum range. If HDRI was enabled then the type is a float, if not it is an int.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# Imagick::getQuantumDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumDepth — Gets the quantum depth

### Beschreibung

public static function Imagick::getQuantumDepth(): array

Returns the Imagick quantum depth.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array with `"quantumDepthLong"` and `"quantumDepthString"` members.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getQuantumRange

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumRange — Returns the Imagick quantum range

### Beschreibung

public static function Imagick::getQuantumRange(): array

Returns the quantum range for the Imagick instance.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an associative array containing the quantum range as an int (`"quantumRangeLong"`) and as a string (`"quantumRangeString"`).

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::getRegistry — Get a StringRegistry entry

### Beschreibung

public static function Imagick::getRegistry(string `$key`): string

Get the StringRegistry entry for the named key or false if not set.

### Parameter-Liste

`key`

  The entry to get.

### Rückgabewerte

# Imagick::getReleaseDate

(PECL imagick 2, PECL imagick 3)

Imagick::getReleaseDate — Returns the ImageMagick release date

### Beschreibung

public static function Imagick::getReleaseDate(): string

Returns the ImageMagick release date as a string.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ImageMagick release date as a string.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getResource

(PECL imagick 2, PECL imagick 3)

Imagick::getResource — Returns the specified resource's memory usage

### Beschreibung

public static function Imagick::getResource(int `$type`): int

Returns the specified resource's memory usage in megabytes.

### Parameter-Liste

`type`

  Refer to the list of resourcetype constants.

### Rückgabewerte

Returns the specified resource's memory usage in megabytes.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::getResourceLimit — Returns the specified resource limit

### Beschreibung

public static function Imagick::getResourceLimit(int `$type`): int

Returns the specified resource limit.

### Parameter-Liste

`type`

  One of the resourcetype constants.

### Rückgabewerte

Returns the specified resource limit. The unit depends on the type of the resource being limited.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Siehe auch

- Imagick::setResourceLimit() - Sets the limit for a particular resource

# Imagick::getSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::getSamplingFactors — Gets the horizontal and vertical sampling factor

### Beschreibung

public function Imagick::getSamplingFactors(): array

Gets the horizontal and vertical sampling factor.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an associative array with the horizontal and vertical sampling factors of the image.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getSize

(PECL imagick 2, PECL imagick 3)

Imagick::getSize — Returns the size associated with the Imagick object

### Beschreibung

public function Imagick::getSize(): array

Get the size in pixels associated with the Imagick object, previously set by Imagick::setSize().

> Hinweis:

> This method just returns the size that was set using Imagick::setSize(). If you want to get the actual width / height of the image, use Imagick::getImageWidth() and Imagick::getImageHeight().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the size associated with the Imagick object as an array with the keys "columns" and "rows".

### Beispiele

Beispiel #1 Getting the size of a raw RGB image set at 200x400, after scaling to 400x800 (compared to width / height)

    <?php
    //Set size first and then load the raw image
    $img = new Imagick();
    $img->setSize(200, 400);
    $img->readImage("image.rgb");

    $img->scaleImage(400, 800);

    $size = $img->getSize();
    print_r($size);

    echo $img->getImageWidth()."x".$img->getImageHeight();
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [columns] => 200
        [rows] => 400
    )
    400x800

# Imagick::getSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::getSizeOffset — Returns the size offset

### Beschreibung

public function Imagick::getSizeOffset(): int

Returns the size offset associated with the Imagick object. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the size offset associated with the Imagick object.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::getVersion

(PECL imagick 2, PECL imagick 3)

Imagick::getVersion — Returns the ImageMagick API version

### Beschreibung

public static function Imagick::getVersion(): array

Returns the ImageMagick API version as a string and as a number.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the ImageMagick API version as a string and as a number.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::haldClutImage

(PECL imagick 3)

Imagick::haldClutImage — Replaces colors in the image

### Beschreibung

public function Imagick::haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Replaces colors in the image using a Hald lookup table. Hald images can be created using HALD color coder.

### Parameter-Liste

`clut`

  Imagick object containing the Hald lookup image.

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::haldClutImage()

    <?php
    function haldClutImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagickPalette = new \Imagick(realpath("images/hald/hald_8.png"));
        $imagickPalette->sepiatoneImage(55);
        $imagick->haldClutImage($imagickPalette);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::hasNextImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasNextImage — Checks if the object has more images

### Beschreibung

public function Imagick::hasNextImage(): bool

Returns `true` if the object has more images when traversing the list in the forward direction.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the object has more images when traversing the list in the forward direction, returns `false` if there are none.

# Imagick::hasPreviousImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasPreviousImage — Checks if the object has a previous image

### Beschreibung

public function Imagick::hasPreviousImage(): bool

Returns `true` if the object has more images when traversing the list in the reverse direction

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns `true` if the object has more images when traversing the list in the reverse direction, returns `false` if there are none.

# Imagick::identifyFormat

(PECL imagick 3 >= 3.3.0)

Imagick::identifyFormat — Formats a string with image details

### Beschreibung

public function Imagick::identifyFormat(string `$embedText`): string|false

Replaces any embedded formatting characters with the appropriate image property and returns the interpreted text. See http://www.imagemagick.org/script/escape.php for escape sequences.

### Parameter-Liste

`embedText`

  A string containing formatting sequences e.g. "Trim box: %@ number of unique colors: %k".

### Rückgabewerte

Returns formatBei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Imagick::identifyFormat()

    <?php
            $output = "Output of 'Trim box: %@ number of unique colors: %k' is: <br/>";
            $imagick = new \Imagick(realpath("./images/artifact/mask.png"));
            $output .= $imagick->identifyFormat("Trim box: %@ number of unique colors: %k");

    ?>

# Imagick::identifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::identifyImage — Identifies an image and fetches attributes

### Beschreibung

public function Imagick::identifyImage(bool `$appendRawOutput` = `false`): array

Identifies an image and returns the attributes. Attributes include the image width, height, size, and others.

### Parameter-Liste

`appendRawOutput`

  If `true` then the raw output is appended to the array.

### Rückgabewerte

Identifies an image and returns the attributes. Attributes include the image width, height, size, and others.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Example Result Format

    Array
    (
        [imageName] => /some/path/image.jpg
        [format] => JPEG (Joint Photographic Experts Group JFIF format)
        [geometry] => Array
            (
                [width] => 90
                [height] => 90
            )

        [type] => TrueColor
        [colorSpace] => RGB
        [resolution] => Array
            (
                [x] => 300
                [y] => 300
            )

        [units] => PixelsPerInch
        [fileSize] => 1.88672kb
        [compression] => JPEG
        [signature] => 9a6dc8f604f97d0d691c0286176ddf992e188f0bebba98494b2146ee2d7118da
    )

# Imagick::implodeImage

(PECL imagick 2, PECL imagick 3)

Imagick::implodeImage — Creates a new image as a copy

### Beschreibung

public function Imagick::implodeImage(float `$radius`): bool

Creates a new image that is a copy of an existing one with the image pixels "imploded" by the specified percentage.

### Parameter-Liste

`radius`

  The radius of the implode

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::implodeImage()

    <?php
    function implodeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->implodeImage(0.0001);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# Imagick::importImagePixels

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::importImagePixels — Imports image pixels

### Beschreibung

public function Imagick::importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool

Imports pixels from an array into an image. The `map` is usually 'RGB'. This method imposes the following constraints for the parameters: amount of pixels in the array must match `width` x `height` x length of the map. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.5 oder höher kompiliert wurde.

### Parameter-Liste

`x`

  The image x position

`y`

  The image y position

`width`

  The image width

`height`

  The image height

`map`

  Map of pixel ordering as a string. This can be for example `RGB`. The value can be any combination or order of R = red, G = green, B = blue, A = alpha (0 is transparent), O = opacity (0 is opaque), C = cyan, Y = yellow, M = magenta, K = black, I = intensity (for grayscale), P = pad.

`storage`

  The pixel storage method. Refer to this list of pixel constants.

`pixels`

  The array of pixels

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::importImagePixels() example

    <?php

    /* Generate array of pixels. 2000 pixels per color stripe */
    $count = 2000 * 3;

    $pixels =
       array_merge(array_pad(array(), $count, 0),
                   array_pad(array(), $count, 255),
                   array_pad(array(), $count, 0),
                   array_pad(array(), $count, 255),
                   array_pad(array(), $count, 0));

    /* Width and height. The area is amount of pixels divided
       by three. Three comes from 'RGB', three values per pixel */
    $width = $height = pow((count($pixels) / 3), 0.5);

    /* Create empty image */
    $im = new Imagick();
    $im->newImage($width, $height, 'gray');

    /* Import the pixels into image.
       width * height * strlen("RGB") must match count($pixels) */
    $im->importImagePixels(0, 0, $width, $height, "RGB", Imagick::PIXEL_CHAR, $pixels);

    /* output as jpeg image */
    $im->setImageFormat('jpg');
    header("Content-Type: image/jpg");
    echo $im;

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

# Imagick::inverseFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::inverseFourierTransformImage — Implements the inverse discrete Fourier transform (DFT)

### Beschreibung

public function Imagick::inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool

Implements the inverse discrete Fourier transform (DFT) of the image either as a magnitude / phase or real / imaginary image pair.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`complement`

  The second image to combine with this one to form either the magnitude / phase or real / imaginary image pair.

`magnitude`

  If true, combine as magnitude / phase pair otherwise a real / imaginary image pair.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::labelImage

(PECL imagick 2, PECL imagick 3)

Imagick::labelImage — Adds a label to an image

### Beschreibung

public function Imagick::labelImage(string `$label`): bool

Adds a label to an image.

### Parameter-Liste

`label`

  The label to add

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::levelImage

(PECL imagick 2, PECL imagick 3)

Imagick::levelImage — Adjusts the levels of an image

### Beschreibung

public function Imagick::levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Adjusts the levels of an image by scaling the colors falling between specified white and black points to the full available quantum range. The parameters provided represent the black, mid, and white points. The black point specifies the darkest color in the image. Colors darker than the black point are set to zero. Mid point specifies a gamma correction to apply to the image. White point specifies the lightest color in the image. Colors brighter than the white point are set to the maximum quantum value.

### Parameter-Liste

`blackPoint`

  The image black point

`gamma`

  The gamma value

`whitePoint`

  The image white point

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::levelImage()

    <?php
    function levelImage($blackPoint, $gamma, $whitePoint) {
        $imagick = new \Imagick();
        $imagick->newPseudoimage(500, 500, 'gradient:black-white');

        $imagick->setFormat('png');
        $quantum = $imagick->getQuantum();
        $imagick->levelImage($blackPoint / 100 , $gamma, $quantum * $whitePoint / 100);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::linearStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::linearStretchImage — Stretches with saturation the image intensity

### Beschreibung

public function Imagick::linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool

Stretches with saturation the image intensity.

### Parameter-Liste

`blackPoint`

  The image black point

`whitePoint`

  The image white point

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::linearStretchImage()

    <?php
    function linearStretchImage($imagePath, $blackThreshold, $whiteThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $pixels = $imagick->getImageWidth() * $imagick->getImageHeight();
        $imagick->linearStretchImage($blackThreshold * $pixels, $whiteThreshold * $pixels);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::liquidRescaleImage

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::liquidRescaleImage — Animates an image or images

### Beschreibung

public function Imagick::liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool

This method scales the images using liquid rescaling method. This method is an implementation of a technique called seam carving. In order for this method to work as expected ImageMagick must be compiled with liblqr support. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.9 oder höher kompiliert wurde.

### Parameter-Liste

`width`

  The width of the target size

`height`

  The height of the target size

`delta_x`

  How much the seam can traverse on x-axis. Passing 0 causes the seams to be straight.

`rigidity`

  Introduces a bias for non-straight seams. This parameter is typically 0.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Siehe auch

- Imagick::resizeImage() - Scales an image

# Imagick::listRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::listRegistry — List all the registry settings

### Beschreibung

public static function Imagick::listRegistry(): array

List all the registry settings. Returns an array of all the key/value pairs in the registry

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

An array containing the key/values from the registry.

# Imagick::magnifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::magnifyImage — Scales an image proportionally 2x

### Beschreibung

public function Imagick::magnifyImage(): bool

Is a convenience method that scales an image proportionally to twice its original size.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::magnifyImage()

    <?php
    function magnifyImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->magnifyImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mapImage

(PECL imagick 2, PECL imagick 3)

Imagick::mapImage — Replaces the colors of an image with the closest color from a reference image

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::mapImage(Imagick `$map`, bool `$dither`): bool

### Parameter-Liste

`map`

`dither`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::matteFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::matteFloodfillImage — Changes the transparency value of a color

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool

Changes the transparency value of any pixel that matches target and is an immediate neighbor. If the method `FillToBorderMethod` is specified, the transparency value is changed for any neighbor pixel that does not match the bordercolor member of image.

### Parameter-Liste

`alpha`

  The level of transparency: 1.0 is fully opaque and 0.0 is fully transparent.

`fuzz`

  The fuzz member of image defines how much tolerance is acceptable to consider two colors as the same.

`bordercolor`

  An ImagickPixel object or string representing the border color.

`x`

  The starting x coordinate of the operation.

`y`

  The starting y coordinate of the operation.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the third parameter. Previous versions allow only an ImagickPixel object.

# Imagick::medianFilterImage

(PECL imagick 2, PECL imagick 3)

Imagick::medianFilterImage — Applies a digital filter

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::medianFilterImage(float `$radius`): bool

Applies a digital filter that improves the quality of a noisy image. Each pixel is replaced by the median in a set of neighboring pixels as defined by radius.

### Parameter-Liste

`radius`

  The radius of the pixel neighborhood.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::medianFilterImage()

    <?php
    function medianFilterImage($radius, $imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->medianFilterImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::mergeImageLayers

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::mergeImageLayers — Merges image layers

### Beschreibung

public function Imagick::mergeImageLayers(int `$layer_method`): Imagick

Merges image layers into one. This method is useful when working with image formats that use multiple layers such as PSD. The merging is controlled using the `layer_method` which defines how the layers are merged. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.7 oder höher kompiliert wurde.

### Parameter-Liste

`layer_method`

  One of the `Imagick::LAYERMETHOD_*` constants

### Rückgabewerte

Returns an Imagick object containing the merged image.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::mergeImageLayers()

    <?php
    function mergeImageLayers($layerMethodType, $imagePath1, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath1));

        $imagick2 = new \Imagick(realpath($imagePath2));
        $imagick->addImage($imagick2);
        $imagick->setImageFormat('png');

        $result = $imagick->mergeImageLayers($layerMethodType);
        header("Content-Type: image/png");
        echo $result->getImageBlob();
    }

    ?>

### Siehe auch

- Imagick::flattenImages() - Merges a sequence of images

# Imagick::minifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::minifyImage — Scales an image proportionally to half its size

### Beschreibung

public function Imagick::minifyImage(): bool

Is a convenience method that scales an image proportionally to one-half its original size

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::modulateImage

(PECL imagick 2, PECL imagick 3)

Imagick::modulateImage — Control the brightness, saturation, and hue

### Beschreibung

public function Imagick::modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool

Lets you control the brightness, saturation, and hue of an image. Hue is the percentage of absolute rotation from the current position. For example 50 results in a counter-clockwise rotation of 90 degrees, 150 results in a clockwise rotation of 90 degrees, with 0 and 200 both resulting in a rotation of 180 degrees.

### Parameter-Liste

`brightness`

`saturation`

`hue`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::modulateImage()

    <?php
    function modulateImage($imagePath, $hue, $brightness, $saturation) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->modulateImage($brightness, $saturation, $hue);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::montageImage

(PECL imagick 2, PECL imagick 3)

Imagick::montageImage — Creates a composite image

### Beschreibung

public function Imagick::montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick

Creates a composite image by combining several separate images. The images are tiled on the composite image with the name of the image optionally appearing just below the individual tile.

### Parameter-Liste

`draw`

  The font name, size, and color are obtained from this object.

`tile_geometry`

  The number of tiles per row and page (e.g. 6x4+0+0).

`thumbnail_geometry`

  Preferred image size and border size of each thumbnail (e.g. 120x120+4+3).

`mode`

  Thumbnail framing mode, see Montage Mode constants.

`frame`

  Surround the image with an ornamental border (e.g. 15x15+3+3). The frame color is that of the thumbnail's matte color.

### Rückgabewerte

Creates a composite image and returns it as a new Imagick object.

# Imagick::morphImages

(PECL imagick 2, PECL imagick 3)

Imagick::morphImages — Method morphs a set of images

### Beschreibung

public function Imagick::morphImages(int `$number_frames`): Imagick

Method morphs a set of images. Both the image pixels and size are linearly interpolated to give the appearance of a meta-morphosis from one image to the next.

### Parameter-Liste

`number_frames`

  The number of in-between images to generate.

### Rückgabewerte

This method returns a new Imagick object on success. Wirf eine ImagickException bei einem Fehler.

# Imagick::morphology

(PECL imagick 3 >= 3.3.0)

Imagick::morphology — Applies a user supplied kernel to the image according to the given morphology method.

### Beschreibung

public function Imagick::morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Applies a user supplied kernel to the image according to the given morphology method.

### Parameter-Liste

`morphologyMethod`

  Which morphology method to use one of the \Imagick::MORPHOLOGY_* constants.

`iterations`

  The number of iteration to apply the morphology function. A value of -1 means loop until no change found. How this is applied may depend on the morphology method. Typically this is a value of 1.

`ImagickKernel`

`channel`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Convolve Imagick::morphology()

    <?php
            $imagick = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_GAUSSIAN, "5,1");
            $imagick->morphology(\Imagick::MORPHOLOGY_CONVOLVE, 2, $kernel);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();

    ?>

Beispiel #2 Correlate Imagick::morphology()

    <?php

            // Top-left pixel must be black
            // Bottom right pixel must be white
            // We don't care about the rest.

            $imagick = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromMatrix(self::$correlateMatrix, [2, 2]);
            $imagick->morphology(\Imagick::MORPHOLOGY_CORRELATE, 1, $kernel);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();

    ?>

Beispiel #3 Erode Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_ERODE, 2, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #4 Erode Intensity Imagick::morphology()

    <?php
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
            $canvas->morphology(\Imagick::MORPHOLOGY_ERODE_INTENSITY, 2, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #5 Dilate Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_DILATE, 4, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #6 Dilate intensity Imagick::morphology()

    <?php
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "1");
            $canvas->morphology(\Imagick::MORPHOLOGY_DILATE_INTENSITY, 4, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #7 Distance with Chebyshev kernel Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CHEBYSHEV, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #8 Distance with Manhattan kernel Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_MANHATTAN, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #9 Distance with ocatagonal kernel Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGONAL, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #10 Distance with Euclidean kernel Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_EUCLIDEAN, "4");
            $canvas->morphology(\Imagick::MORPHOLOGY_DISTANCE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #11 Edge Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #12 Open Imagick::morphology()

    <?php
            // As a result you will see that 'Open' smoothed the outline, by rounding off any sharp points, and remove any parts that is smaller than the shape used. It will also disconnect or 'open' any thin bridges.
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_OPEN, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #13 Open intensity Imagick::morphology()

    <?php
            // As a result you will see that 'Open' smoothed the outline, by rounding off any sharp points, and remove any parts that is smaller than the shape used. It will also disconnect or 'open' any thin bridges.

            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_OPEN_INTENSITY, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #14 Close Imagick::morphology()

    <?php
            //The basic use of the 'Close' method is to reduce or remove any 'holes' or 'gaps' about the size of the kernel 'Structure Element'. That is 'close' parts of the background that are about that size.
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #15 Close Intensity Imagick::morphology()

    <?php
            //The basic use of the 'Close' method is to reduce or remove any 'holes' or 'gaps' about the size of the kernel 'Structure Element'. That is 'close' parts of the background that are about that size.
            $canvas = $this->getCharacter();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "6");
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE_INTENSITY, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #16 Smooth Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_SMOOTH, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #17 Edge in Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_IN, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #18 Edge out Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_OCTAGON, "3");
            $canvas->morphology(\Imagick::MORPHOLOGY_EDGE_OUT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #19 The 'TopHat' method, or more specifically 'White Top Hat', returns the pixels that were removed by a Opening of the shape, that is the pixels that were removed to round off the points, and the connecting bridged between shapes. Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_TOP_HAT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #20 The 'BottomHat' method, also known as 'Black TopHat' is the pixels that a Closing of the shape adds to the image. That is the pixels that were used to fill in the 'holes', 'gaps', and 'bridges'. Imagick::morphology()

    <?php

            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "5");
            $canvas->morphology(\Imagick::MORPHOLOGY_BOTTOM_HAT, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #21 Hit and Miss Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            //This finds all the pixels with 3 pixels of the right edge
            $matrix = [[1, false, false, 0]];
            $kernel = \ImagickKernel::fromMatrix(
                $matrix,
                [0, 0]
            );
            $canvas->morphology(\Imagick::MORPHOLOGY_HIT_AND_MISS, 1, $kernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #22 Thinning Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
            $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
            $leftEdgeKernel->addKernel($rightEdgeKernel);

            $canvas->morphology(\Imagick::MORPHOLOGY_THINNING, 3, $leftEdgeKernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #23 Thicken Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $leftEdgeKernel = \ImagickKernel::fromMatrix([[0, 1]], [1, 0]);
            $rightEdgeKernel = \ImagickKernel::fromMatrix([[1, 0]], [0, 0]);
            $leftEdgeKernel->addKernel($rightEdgeKernel);

            $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, 3, $leftEdgeKernel);
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #24 Thick to generate a convex hull Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $diamondKernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "1");
            $convexKernel =  \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CONVEX_HULL, "");

            // The thicken morphology doesn't handle small gaps. We close them
            // with the close morphology.
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);
            $canvas->morphology(\Imagick::MORPHOLOGY_THICKEN, -1, $convexKernel);
            $canvas->morphology(\Imagick::MORPHOLOGY_CLOSE, 1, $diamondKernel);

            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #25 Iterative morphology Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $kernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DISK, "2");
            $canvas->morphology(\Imagick::MORPHOLOGY_ITERATIVE, 3, $kernel);
            $canvas->autoLevelImage();
            header("Content-Type: image/png");
            echo $canvas->getImageBlob();

    ?>

Beispiel #26 Helper function to get an image silhouette Imagick::morphology()

    <?php
    function getCharacterOutline() {
        $imagick = new \Imagick(realpath("./images/character.png"));
        $character = new \Imagick();
        $character->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:white"
        );
        $canvas = new \Imagick();
        $canvas->newPseudoImage(
            $imagick->getImageWidth(),
            $imagick->getImageHeight(),
            "canvas:black"
        );

        $character->compositeimage(
            $imagick,
            \Imagick::COMPOSITE_COPYOPACITY,
            0, 0
        );
        $canvas->compositeimage(
            $character,
            \Imagick::COMPOSITE_ATOP,
            0, 0
        );
        $canvas->setFormat('png');

        return $canvas;
    }
    ?>

# Imagick::mosaicImages

(PECL imagick 2, PECL imagick 3)

Imagick::mosaicImages — Forms a mosaic from images

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::mosaicImages(): Imagick

Inlays an image sequence to form a single coherent picture. It returns a wand with each image in the sequence composited at the location defined by the page offset of the image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::motionBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::motionBlurImage — Simulates motion blur

### Beschreibung

public function Imagick::motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Simulates motion blur. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and MotionBlurImage() selects a suitable radius for you. Angle gives the angle of the blurring motion.

### Parameter-Liste

`radius`

  The radius of the Gaussian, in pixels, not counting the center pixel.

`sigma`

  The standard deviation of the Gaussian, in pixels.

`angle`

  Apply the effect along this angle.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants. The channel argument affects only if Imagick is compiled against ImageMagick version 6.4.4 or greater.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::motionBlurImage()

    <?php
    function motionBlurImage($imagePath, $radius, $sigma, $angle, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->motionBlurImage($radius, $sigma, $angle, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::negateImage

(PECL imagick 2, PECL imagick 3)

Imagick::negateImage — Negates the colors in the reference image

### Beschreibung

public function Imagick::negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Negates the colors in the reference image. The Grayscale option means that only grayscale values within the image are negated.

### Parameter-Liste

`gray`

  Whether to only negate grayscale pixels within the image.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::negateImage()

    <?php
    function negateImage($imagePath, $grayOnly, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->negateImage($grayOnly, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::newImage

(PECL imagick 2, PECL imagick 3)

Imagick::newImage — Creates a new image

### Beschreibung

public function Imagick::newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool

Creates a new image and associates ImagickPixel value as background color

### Parameter-Liste

`cols`

  Columns in the new image

`rows`

  Rows in the new image

`background`

  The background color used for this image

`format`

  Image format. This parameter was added in Imagick version 2.0.1.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the third parameter. Previous versions allow only an ImagickPixel object.

### Beispiele

Beispiel #1 Using Imagick::newImage():

Create a new image and display it.

    <?php

    $image = new Imagick();
    $image->newImage(100, 100, new ImagickPixel('red'));
    $image->setImageFormat('png');

    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::newPseudoImage

(PECL imagick 2, PECL imagick 3)

Imagick::newPseudoImage — Creates a new image

### Beschreibung

public function Imagick::newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool

Creates a new image using ImageMagick pseudo-formats.

### Parameter-Liste

`columns`

  columns in the new image

`rows`

  rows in the new image

`pseudoString`

  string containing pseudo image definition.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::newPseudoImage()

    <?php
    function newPseudoImage($canvasType) {
        $imagick = new \Imagick();
        $imagick->newPseudoImage(300, 300, $canvasType);
        $imagick->setImageFormat("png");
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    //newPseudoImage('gradient:red-rgba(64, 255, 255, 0.5)');
    //newPseudoImage("radial-gradient:red-blue");
    newPseudoImage("plasma:fractal");

    ?>

# Imagick::nextImage

(PECL imagick 2, PECL imagick 3)

Imagick::nextImage — Moves to the next image

### Beschreibung

public function Imagick::nextImage(): bool

Associates the next image in the image list with an Imagick object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::normalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::normalizeImage — Enhances the contrast of a color image

### Beschreibung

public function Imagick::normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Enhances the contrast of a color image by adjusting the pixels color to span the entire range of colors available.

### Parameter-Liste

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::normalizeImage()

    <?php
    function normalizeImage($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $original = clone $imagick;
        $original->cropimage($original->getImageWidth() / 2, $original->getImageHeight(), 0, 0);
        $imagick->normalizeImage($channel);
        $imagick->compositeimage($original, \Imagick::COMPOSITE_ATOP, 0, 0);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::oilPaintImage

(PECL imagick 2, PECL imagick 3)

Imagick::oilPaintImage — Simulates an oil painting

### Beschreibung

public function Imagick::oilPaintImage(float `$radius`): bool

Applies a special effect filter that simulates an oil painting. Each pixel is replaced by the most frequent color occurring in a circular region defined by radius.

### Parameter-Liste

`radius`

  The radius of the circular neighborhood.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::oilPaintImage()

    <?php
    function oilPaintImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->oilPaintImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::opaquePaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::opaquePaintImage — Changes the color value of any pixel that matches target

### Beschreibung

public function Imagick::opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Changes any pixel that matches color with the color defined by fill. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.8 oder höher kompiliert wurde.

### Parameter-Liste

`target`

  ImagickPixel object or a string containing the color to change

`fill`

  The replacement color

`fuzz`

  Die Menge an Ungenauigkeit. Wird dieser Wert z. B. auf 10 gesetzt, so wird die Farbe Rot bei Intensitäten von 100 und 102 als identisch betrachtet.

`invert`

  If `true` paints any pixel that does not match the target color.

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::optimizeImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::optimizeImageLayers — Removes repeated portions of images to optimize

### Beschreibung

public function Imagick::optimizeImageLayers(): bool

Compares each image the GIF disposed forms of the previous image in the sequence. From this it attempts to select the smallest cropped image to replace each frame, while preserving the results of the animation. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::optimizeImageLayers()

Reading, optimizing and writing a GIF image

    <?php
    /* create new imagick object */
    $im = new Imagick("test.gif");

    /* optimize the image layers */
    $im->optimizeImageLayers();

    /* write the image back */
    $im->writeImages("test_optimized.gif", true);
    ?>

### Siehe auch

- Imagick::compareImageLayers() - Returns the maximum bounding region between images
- Imagick::writeImages() - Writes an image or image sequence
- Imagick::writeImage() - Writes an image to the specified filename

# Imagick::orderedPosterizeImage

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::orderedPosterizeImage — Performs an ordered dither

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Performs an ordered dither based on a number of pre-defined dithering threshold maps, but over multiple intensity levels, which can be different for different channels, according to the input arguments. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.1 oder höher kompiliert wurde.

### Parameter-Liste

`threshold_map`

  A string containing the name of the threshold dither map to use

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::orderedPosterizeImage()

    <?php
    function orderedPosterizeImage($imagePath, $orderedPosterizeType) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->orderedPosterizeImage($orderedPosterizeType);
        $imagick->setImageFormat('png');

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    //orderedPosterizeImage($imagePath, 'o4x4,3,3');
    //orderedPosterizeImage($imagePath, 'o8x8,6,6');
    orderedPosterizeImage($imagePath, 'h8x8a');

    ?>

# Imagick::paintFloodfillImage

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::paintFloodfillImage — Changes the color value of any pixel that matches target

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Changes the color value of any pixel that matches target and is an immediate neighbor. As of ImageMagick 6.3.8 this method has been deprecated and Imagick::floodfillPaintImage() should be used instead.

### Parameter-Liste

`fill`

  ImagickPixel object or a string containing the fill color

`fuzz`

  The amount of fuzz. For example, set fuzz to 10 and the color red at intensities of 100 and 102 respectively are now interpreted as the same color for the purposes of the floodfill.

`bordercolor`

  ImagickPixel object or a string containing the border color

`x`

  X start position of the floodfill

`y`

  Y start position of the floodfill

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::paintOpaqueImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintOpaqueImage — Change any pixel that matches color

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Changes any pixel that matches color with the color defined by fill.

### Parameter-Liste

`target`

  Change this target color to the fill color within the image. An ImagickPixel object or a string representing the target color.

`fill`

  An ImagickPixel object or a string representing the fill color.

`fuzz`

  The fuzz member of image defines how much tolerance is acceptable to consider two colors as the same.

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as first and second parameter. Previous versions allow only an ImagickPixel object.

# Imagick::paintTransparentImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintTransparentImage — Changes any pixel that matches color with the color defined by fill

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool

Changes any pixel that matches color with the color defined by fill.

### Parameter-Liste

`target`

  Change this target color to specified opacity value within the image.

`alpha`

  The level of transparency: 1.0 is fully opaque and 0.0 is fully transparent.

`fuzz`

  The fuzz member of image defines how much tolerance is acceptable to consider two colors as the same.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter. Previous versions allow only an ImagickPixel object.

# Imagick::pingImage

(PECL imagick 2, PECL imagick 3)

Imagick::pingImage — Ruft grundlegende Merkmale eines Bildes ab

### Beschreibung

public function Imagick::pingImage(string `$filename`): bool

Diese Methode kann verwendet werden um Bildbreite, -höhe, -größe und -format abzufragen, ohne das gesamte Bild in den Speicher zu laden.

### Parameter-Liste

`filename`

  Pfad der Datei, die abgefragt werden soll.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::pingImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageBlob — Quickly fetch attributes

### Beschreibung

public function Imagick::pingImageBlob(string `$image`): bool

This method can be used to query image width, height, size, and format without reading the whole image to memory. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`image`

  A string containing the image.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Using Imagick::pingImageBlob()

Pinging an image from a string

    <?php
    /* read image contents */
    $image = file_get_contents("test.jpg");

    /* create new imagick object */
    $im = new Imagick();

    /* pass the string to the imagick object */
    $im->pingImageBlob($image);

    /* output image width and height */
    echo $im->getImageWidth() . 'x' . $im->getImageHeight();
    ?>

### Siehe auch

- Imagick::pingImage() - Ruft grundlegende Merkmale eines Bildes ab
- Imagick::pingImageFile() - Get basic image attributes in a lightweight manner
- Imagick::readImage() - Reads image from filename
- Imagick::readImageBlob() - Reads image from a binary string
- Imagick::readImageFile() - Reads image from open filehandle

# Imagick::pingImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageFile — Get basic image attributes in a lightweight manner

### Beschreibung

public function Imagick::pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool

This method can be used to query image width, height, size, and format without reading the whole image to memory. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`filehandle`

  An open filehandle to the image.

`fileName`

  Optional filename for this image.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Using Imagick::pingImageFile()

Opening a remote location

    <?php
    /* fopen a remote location */
    $fp = fopen("http://example.com/test.jpg");

    /* create new imagick object */
    $im = new Imagick();

    /* pass the handle to imagick */
    $im->pingImageFile($fp);
    ?>

### Siehe auch

- Imagick::pingImage() - Ruft grundlegende Merkmale eines Bildes ab
- Imagick::pingImageBlob() - Quickly fetch attributes
- Imagick::readImage() - Reads image from filename
- Imagick::readImageBlob() - Reads image from a binary string
- Imagick::readImageFile() - Reads image from open filehandle

# Imagick::polaroidImage

(PECL imagick 2, PECL imagick 3)

Imagick::polaroidImage — Simulates a Polaroid picture

### Beschreibung

public function Imagick::polaroidImage(ImagickDraw `$properties`, float `$angle`): bool

Simulates a Polaroid picture. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.2 oder höher kompiliert wurde.

### Parameter-Liste

`properties`

  The polaroid properties

`angle`

  The polaroid angle

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 A Imagick::polaroidImage() example

An example of using Imagick::polaroidImage()

    <?php
    /* Create the object */
    $image = new Imagick('source.png');

    /* Set the opacity */
    $image->polaroidImage(new ImagickDraw(), 25);

    /* output the image */
    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::posterizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::posterizeImage — Reduces the image to a limited number of color level

### Beschreibung

public function Imagick::posterizeImage(int `$levels`, bool `$dither`): bool

Reduces the image to a limited number of color level.

### Parameter-Liste

`levels`

`dither`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::posterizeImage()

    <?php
    function posterizeImage($imagePath, $posterizeType, $numberLevels) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->posterizeImage($numberLevels, $posterizeType);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    posterizeImage($imagePath, \Imagick::DITHERMETHOD_RIEMERSMA, 8);

    ?>

# Imagick::previewImages

(PECL imagick 2, PECL imagick 3)

Imagick::previewImages — Quickly pin-point appropriate parameters for image processing

### Beschreibung

public function Imagick::previewImages(int `$preview`): bool

Tiles 9 thumbnails of the specified image with an image processing operation applied at varying strengths. This is helpful to quickly pin-point an appropriate parameter for an image processing operation.

### Parameter-Liste

`preview`

  Preview type. See Preview type constants

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::previousImage

(PECL imagick 2, PECL imagick 3)

Imagick::previousImage — Move to the previous image in the object

### Beschreibung

public function Imagick::previousImage(): bool

Associates the previous image in an image list with the Imagick object.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::profileImage

(PECL imagick 2, PECL imagick 3)

Imagick::profileImage — Adds or removes a profile from an image

### Beschreibung

public function Imagick::profileImage(string `$name`, string `$profile` = ?): bool

Adds or removes a ICC, IPTC, or generic profile from an image. If the `profile` is `null`, it is removed from the image rather than added.

To remove every single profile from the image use `'*'` as the `name` and `null` for the `profile`.

### Parameter-Liste

`name`
  The profile name.
`profile`
  The profile data. If `null`, the specified profile will be deleted.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::quantizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImage — Analyzes the colors within a reference image

### Beschreibung

public function Imagick::quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Parameter-Liste

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::quantizeImage()

    <?php
    function quantizeImage($imagePath, $numberColors, $colorSpace, $treeDepth, $dither) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->quantizeImage($numberColors, $colorSpace, $treeDepth, $dither, false);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::quantizeImages

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImages — Analyzes the colors within a sequence of images

### Beschreibung

public function Imagick::quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### Parameter-Liste

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::queryFontMetrics

(PECL imagick 2, PECL imagick 3)

Imagick::queryFontMetrics — Returns an array representing the font metrics

### Beschreibung

public function Imagick::queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array

Returns a multi-dimensional array representing the font metrics.

### Parameter-Liste

`properties`

  ImagickDraw object containing font properties

`text`

  The text

`multiline`

  Multiline parameter. If left empty it is autodetected

### Rückgabewerte

Returns a multi-dimensional array representing the font metrics.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::queryFontMetrics():

Query the metrics for the text and dump the results on the screen.

    <?php
    /* Create a new Imagick object */
    $im = new Imagick();

    /* Create an ImagickDraw object */
    $draw = new ImagickDraw();

    /* Set the font */
    $draw->setFont('/path/to/font.ttf');

    /* Dump the font metrics, autodetect multiline */
    var_dump($im->queryFontMetrics($draw, "Hello World!"));
    ?>

# Imagick::queryFonts

(PECL imagick 2, PECL imagick 3)

Imagick::queryFonts — Returns the configured fonts

### Beschreibung

public static function Imagick::queryFonts(string `$pattern` = "*"): array

Returns the configured fonts.

### Parameter-Liste

`pattern`

  The query pattern

### Rückgabewerte

Returns an array containing the configured fonts.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::queryFonts()

    <?php
            $output = '';
            $output .= "Fonts that match 'Helvetica*' are:<br/>";

            $fontList = \Imagick::queryFonts("Helvetica*");

            foreach ($fontList as $fontName) {
                $output .= '<li>'. $fontName."</li>";
            }

            return $output;

    ?>

# Imagick::queryFormats

(PECL imagick 2, PECL imagick 3)

Imagick::queryFormats — Returns formats supported by Imagick

### Beschreibung

public static function Imagick::queryFormats(string `$pattern` = "*"): array

Returns formats supported by Imagick.

### Parameter-Liste

`pattern`

### Rückgabewerte

Returns an array containing the formats supported by Imagick.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::queryFormats()

    <?php
        function render() {
            $output = "";
            $input = \Imagick::queryformats();
            $columns = 6;

            $output .= "<table border='2'>";

            for ($i=0; $i < count($input); $i += $columns) {
                $output .= "<tr>";
                for ($c=0; $c<$columns; $c++) {
                    $output .= "<td>";
                    if (($i + $c) <  count($input)) {
                        $output .= $input[$i + $c];
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

    ?>

# Imagick::radialBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::radialBlurImage — Radial blurs an image

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Radial blurs an image.

### Parameter-Liste

`angle`

`channel`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::radialBlurImage()

    <?php
    function radialBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        //Blur 3 times with different radii
        $imagick->radialBlurImage(3);
        $imagick->radialBlurImage(5);
        $imagick->radialBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::raiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::raiseImage — Creates a simulated 3d button-like effect

### Beschreibung

public function Imagick::raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool

Creates a simulated three-dimensional button-like effect by lightening and darkening the edges of the image. Members width and height of raise_info define the width of the vertical and horizontal edge of the effect.

### Parameter-Liste

`width`

`height`

`x`

`y`

`raise`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::raiseImage()

    <?php
    function raiseImage($imagePath, $width, $height, $x, $y, $raise) {
        $imagick = new \Imagick(realpath($imagePath));

        //x and y do nothing?
        $imagick->raiseImage($width, $height, $x, $y, $raise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::randomThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::randomThresholdImage — Creates a high-contrast, two-color image

### Beschreibung

public function Imagick::randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Changes the value of individual pixels based on the intensity of each pixel compared to threshold. The result is a high-contrast, two color image. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`low`

  The low point

`high`

  The high point

`channel`

  Provide any channel constant that is valid for your channel mode. To apply to more than one channel, combine channeltype constants using bitwise operators. Refer to this list of channel constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::randomThresholdImage()

    <?php
    function randomThresholdimage($imagePath, $lowThreshold, $highThreshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->randomThresholdimage(
            $lowThreshold * \Imagick::getQuantum(),
            $highThreshold * \Imagick::getQuantum(),
            $channel
        );
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::readImage

(PECL imagick 2, PECL imagick 3)

Imagick::readImage — Reads image from filename

### Beschreibung

public function Imagick::readImage(string `$filename`): bool

Reads image from filename

### Parameter-Liste

`filename`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::readImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::readImageBlob — Reads image from a binary string

### Beschreibung

public function Imagick::readImageBlob(string `$image`, string `$filename` = ?): bool

Reads image from a binary string

### Parameter-Liste

`image`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::readImageBlob()

    <?php
    function readImageBlob() {
        $base64 = "iVBORw0KGgoAAAANSUhEUgAAAM0AAAD
     NCAMAAAAsYgRbAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5c
     cllPAAAABJQTFRF3NSmzMewPxIG//ncJEJsldTou1jHgAAAARBJREFUeNrs2EEK
     gCAQBVDLuv+V20dENbMY831wKz4Y/VHb/5RGQ0NDQ0NDQ0NDQ0NDQ0NDQ
     0NDQ0NDQ0NDQ0NDQ0NDQ0NDQ0PzMWtyaGhoaGhoaGhoaGhoaGhoxtb0QGho
     aGhoaGhoaGhoaGhoaMbRLEvv50VTQ9OTQ5OpyZ01GpM2g0bfmDQaL7S+ofFC6x
     v3ZpxJiywakzbvd9r3RWPS9I2+MWk0+kbf0Hih9Y17U0nTHibrDDQ0NDQ0NDQ0
     NDQ0NDQ0NTXbRSL/AK72o6GhoaGhoRlL8951vwsNDQ0NDQ1NDc0WyHtDTEhD
     Q0NDQ0NTS5MdGhoaGhoaGhoaGhoaGhoaGhoaGhoaGposzSHAAErMwwQ2HwRQ
     AAAAAElFTkSuQmCC";

        $imageBlob = base64_decode($base64);

        $imagick = new Imagick();
        $imagick->readImageBlob($imageBlob);

        header("Content-Type: image/png");
        echo $imagick;
    }

    ?>

# Imagick::readImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::readImageFile — Reads image from open filehandle

### Beschreibung

public function Imagick::readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool

Reads image from open filehandle

### Parameter-Liste

`filehandle`

`fileName`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::readimages

(PECL imagick 2, PECL imagick 3)

Imagick::readimages — Reads image from an array of filenames

### Beschreibung

public function Imagick::readImages(array `$filenames`): bool

Reads image from an array of filenames. All the images are held in a single Imagick object.

### Parameter-Liste

`filenames`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::recolorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::recolorImage — Recolors image

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::recolorImage(array `$matrix`): bool

Translate, scale, shear, or rotate image colors. This method supports variable sized matrices but normally 5x5 matrix is used for RGBA and 6x6 is used for CMYK. The last row should contain the normalized values. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`matrix`

  The matrix containing the color values

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::recolorImage()

    <?php
    function recolorImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $remapColor = [ 1, 0, 0,
            0, 0, 1,
            0, 1, 0,];

    //$remapColor = [
    //    1.438, -0.122, -0.016,  0, 0, -0.03,
    //    -0.062,  1.378, -0.016,  0, 0,  0.05,
    //    -0.062, -0.122, 1.483,   0, 0, -0.02,
    //];

        @$imagick->recolorImage($remapColor);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Siehe auch

- Imagick::displayImage() - Displays an image

# Imagick::reduceNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::reduceNoiseImage — Smooths the contours of an image

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::reduceNoiseImage(float `$radius`): bool

Smooths the contours of an image while still preserving edge information. The algorithm works by replacing each pixel with its neighbor closest in value. A neighbor is defined by radius. Use a radius of 0 and Imagick::reduceNoiseImage() selects a suitable radius for you.

### Parameter-Liste

`radius`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::reduceNoiseImage()

    <?php
    function reduceNoiseImage($imagePath, $reduceNoise) {
        $imagick = new \Imagick(realpath($imagePath));
        @$imagick->reduceNoiseImage($reduceNoise);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::remapImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::remapImage — Remaps image colors

### Beschreibung

public function Imagick::remapImage(Imagick `$replacement`, int `$DITHER`): bool

Replaces colors an image with those defined by `replacement`. The colors are replaced with the closest possible color. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.5 oder höher kompiliert wurde.

### Parameter-Liste

`replacement`

  An Imagick object containing the replacement colors

`DITHER`

  Refer to this list of dither method constants

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::removeImage

(PECL imagick 2, PECL imagick 3)

Imagick::removeImage — Removes an image from the image list

### Beschreibung

public function Imagick::removeImage(): bool

Removes an image from the image list.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::removeImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::removeImageProfile — Removes the named image profile and returns it

### Beschreibung

public function Imagick::removeImageProfile(string `$name`): string

Removes the named image profile and returns it.

### Parameter-Liste

`name`

### Rückgabewerte

Returns a string containing the profile of the image.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::render

(PECL imagick 2, PECL imagick 3)

Imagick::render — Renders all preceding drawing commands

### Beschreibung

public function Imagick::render(): bool

Renders all preceding drawing commands.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::resampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::resampleImage — Resample image to desired resolution

### Beschreibung

public function Imagick::resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool

Resample image to desired resolution.

### Parameter-Liste

`x_resolution`

`y_resolution`

`filter`

`blur`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::resampleImage()

    <?php
    function resampleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resampleImage(200, 200, \Imagick::FILTER_LANCZOS, 1);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::resetImagePage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::resetImagePage — Reset image page

### Beschreibung

public function Imagick::resetImagePage(string `$page`): bool

The page definition as a string. The string is in format WxH+x+y. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`page`

  The page definition. For example `7168x5147+0+0`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::resizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::resizeImage — Scales an image

### Beschreibung

public function Imagick::resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Scales an image to the desired dimensions with a filter.

> Hinweis: Das Verhalten des Parameters `bestfit` hat sich mit Imagick 3.0.0 geändert. Vor dieser Version wurde ein Bild der Größe 200x150 bei der angegebenen Größe von 400x400 nicht verändert. In Imagick 3.0.0 und späteren Versionen wird dieses Bild auf die Größe 400x300 hochgerechnet, da dies die passendste größe für die angegebene Bildgröße ist. Wenn der `bestfit`-Parameter angegeben wird, so muss sowohl eine Breite als auch eine Höhe angegeben werden.

### Parameter-Liste

`columns`

  Width of the image

`rows`

  Height of the image

`filter`

  Refer to the list of filter constants.

`blur`

  The blur factor where > 1 is blurry, < 1 is sharp.

`bestfit`

  Optional fit parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Added optional fit parameter. This method now supports proportional scaling. Pass zero as either parameter for proportional scaling.

### Beispiele

Beispiel #1 Imagick::resizeImage()

    <?php
    function resizeImage($imagePath, $width, $height, $filterType, $blur, $bestFit, $cropZoom) {
        //The blur factor where > 1 is blurry, < 1 is sharp.
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->resizeImage($width, $height, $filterType, $blur, $bestFit);

        $cropWidth = $imagick->getImageWidth();
        $cropHeight = $imagick->getImageHeight();

        if ($cropZoom) {
            $newWidth = $cropWidth / 2;
            $newHeight = $cropHeight / 2;

            $imagick->cropimage(
                $newWidth,
                $newHeight,
                ($cropWidth - $newWidth) / 2,
                ($cropHeight - $newHeight) / 2
            );

            $imagick->scaleimage(
                $imagick->getImageWidth() * 4,
                $imagick->getImageHeight() * 4
            );
        }

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rollImage

(PECL imagick 2, PECL imagick 3)

Imagick::rollImage — Offsets an image

### Beschreibung

public function Imagick::rollImage(int `$x`, int `$y`): bool

Offsets an image as defined by x and y.

### Parameter-Liste

`x`

  The X offset.

`y`

  The Y offset.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::rollImage()

    <?php
    function rollImage($imagePath, $rollX, $rollY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rollimage($rollX, $rollY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::rotateImage — Rotates an image

### Beschreibung

public function Imagick::rotateImage(mixed `$background`, float `$degrees`): bool

Rotates an image the specified number of degrees. Empty triangles left over from rotating the image are filled with the background color.

### Parameter-Liste

`background`

  The background color

`degrees`

  Rotation angle, in degrees. The rotation angle is interpreted as the number of degrees to rotate the image clockwise.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter. Previous versions allow only an ImagickPixel object.

### Beispiele

Beispiel #1 Imagick::rotateImage()

    <?php
    function rotateImage($imagePath, $angle, $color) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotateimage($color, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::rotationalBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::rotationalBlurImage — Rotational blurs an image

### Beschreibung

public function Imagick::rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Rotational blurs an image.

### Parameter-Liste

`angle`

  The angle to apply the blur over.

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::rotationalBlurImage()

    <?php
    function rotationalBlurImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->rotationalBlurImage(3);
        $imagick->rotationalBlurImage(5);
        $imagick->rotationalBlurImage(7);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::roundCorners

(PECL imagick 2, PECL imagick 3)

Imagick::roundCorners — Rounds image corners

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool

Rounds image corners. The first two parameters control the amount of rounding and the three last parameters can be used to fine-tune the rounding process. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde. Diese Funktion ist nicht verfügbar, wenn Imagick gegen die ImageMagick-Version 7.0.0 oder höher kompiliert wurde.

### Parameter-Liste

`x_rounding`

  x rounding

`y_rounding`

  y rounding

`stroke_width`

  stroke width

`displace`

  image displace

`size_correction`

  size correction

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Using Imagick::roundCorners():

Rounds the image corners

    <?php

    $image = new Imagick();
    $image->newPseudoImage(100, 100, "magick:rose");
    $image->setImageFormat("png");

    $image->roundCorners(5,3);
    $image->writeImage("rounded.png");
    ?>

# Imagick::sampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::sampleImage — Scales an image with pixel sampling

### Beschreibung

public function Imagick::sampleImage(int `$columns`, int `$rows`): bool

Scales an image to the desired dimensions with pixel sampling. Unlike other scaling methods, this method does not introduce any additional color into the scaled image.

### Parameter-Liste

`columns`

`rows`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::scaleImage

(PECL imagick 2, PECL imagick 3)

Imagick::scaleImage — Scales the size of an image

### Beschreibung

public function Imagick::scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool

Scales the size of an image to the given dimensions. The other parameter will be calculated if 0 is passed as either param.

> Hinweis: Das Verhalten des Parameters `bestfit` hat sich mit Imagick 3.0.0 geändert. Vor dieser Version wurde ein Bild der Größe 200x150 bei der angegebenen Größe von 400x400 nicht verändert. In Imagick 3.0.0 und späteren Versionen wird dieses Bild auf die Größe 400x300 hochgerechnet, da dies die passendste größe für die angegebene Bildgröße ist. Wenn der `bestfit`-Parameter angegeben wird, so muss sowohl eine Breite als auch eine Höhe angegeben werden.

### Parameter-Liste

`columns`

`rows`

`bestfit`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Added optional fit parameter. This method now supports proportional scaling. Pass zero as either parameter for proportional scaling.

### Beispiele

Beispiel #1 Imagick::scaleImage()

    <?php
    function scaleImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->scaleImage(150, 150, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::segmentImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::segmentImage — Segments an image

### Beschreibung

public function Imagick::segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool

Analyses the image and identifies units that are similar. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.5 oder höher kompiliert wurde.

### Parameter-Liste

`COLORSPACE`

  One of the COLORSPACE constants.

`cluster_threshold`

  A percentage describing minimum number of pixels contained in hexedra before it is considered valid.

`smooth_threshold`

  Eliminates noise from the histogram.

`verbose`

  Whether to output detailed information about recognised classes.

### Rückgabewerte

### Beispiele

Beispiel #1 Imagick::segmentImage()

    <?php
    function segmentImage($imagePath, $colorSpace, $clusterThreshold, $smoothThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->segmentImage($colorSpace, $clusterThreshold, $smoothThreshold);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    segmentImage($imagePath, \Imagick::COLORSPACE_RGB, 5, 5);

    ?>

# Imagick::selectiveBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::selectiveBlurImage — Selectively blur an image within a contrast threshold

### Beschreibung

public function Imagick::selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Selectively blur an image within a contrast threshold. It is similar to the unsharpen mask that sharpens everything with contrast above a certain threshold.

### Parameter-Liste

`radius`

`sigma`

`threshold`

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::selectiveBlurImage()

    <?php
    function selectiveBlurImage($imagePath, $radius, $sigma, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->selectiveBlurImage($radius, $sigma, $threshold, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::separateImageChannel

(PECL imagick 2, PECL imagick 3)

Imagick::separateImageChannel — Separates a channel from the image

### Beschreibung

public function Imagick::separateImageChannel(int `$channel`): bool

Separates a channel from the image and returns a grayscale image. A channel is a particular color component of each pixel in the image.

### Parameter-Liste

`channel`

  Which 'channel' to return. For colorspaces other than RGB, you can still use the CHANNEL_RED, CHANNEL_GREEN, CHANNEL_BLUE constants to indicate the 1st, 2nd and 3rd channels.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::separateImageChannel()

    <?php
    function separateImageChannel($imagePath, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->separateimagechannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    separateImageChannel($imagePath, \Imagick::CHANNEL_GREEN);

    ?>

# Imagick::sepiaToneImage

(PECL imagick 2, PECL imagick 3)

Imagick::sepiaToneImage — Sepia tones an image

### Beschreibung

public function Imagick::sepiaToneImage(float `$threshold`): bool

Applies a special effect to the image, similar to the effect achieved in a photo darkroom by sepia toning. Threshold ranges from 0 to QuantumRange and is a measure of the extent of the sepia toning. A threshold of 80 is a good starting point for a reasonable tone.

### Parameter-Liste

`threshold`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::sepiaToneImage()

    <?php
    function sepiaToneImage($imagePath, $sepia) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sepiaToneImage($sepia);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setBackgroundColor — Sets the object's default background color

### Beschreibung

public function Imagick::setBackgroundColor(mixed `$background`): bool

Sets the object's default background color.

### Parameter-Liste

`background`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as a parameter. Previous versions allow only an ImagickPixel object.

# Imagick::setColorspace

(PECL imagick 3)

Imagick::setColorspace — Set colorspace

### Beschreibung

public function Imagick::setColorspace(int `$COLORSPACE`): bool

Sets the global colorspace value for the object. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.5.7 oder höher kompiliert wurde.

### Parameter-Liste

`COLORSPACE`

  One of the COLORSPACE constants

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setCompression — Sets the object's default compression type

### Beschreibung

public function Imagick::setCompression(int `$compression`): bool

Sets the object's default compression type

### Parameter-Liste

`compression`

  The compression type. See the Imagick::COMPRESSION_* constants.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setCompressionQuality — Sets the object's default compression quality

### Beschreibung

public function Imagick::setCompressionQuality(int `$quality`): bool

Sets the object's default compression quality.

Achtung

This method only works for new images e.g. those created through Imagick::newPseudoImage. For existing images you should use Imagick::setImageCompressionQuality().

### Parameter-Liste

`quality`

  An Integer between 1 and 100, 1 = high compression, 100 low compression.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::setCompressionQuality()

    <?php
    function setCompressionQuality($imagePath, $quality) {

        $backgroundImagick = new \Imagick(realpath($imagePath));
        $imagick = new \Imagick();
        $imagick->setCompressionQuality($quality);
        $imagick->newPseudoImage(
            $backgroundImagick->getImageWidth(),
            $backgroundImagick->getImageHeight(),
            'canvas:white'
        );

        $imagick->compositeImage(
            $backgroundImagick,
            \Imagick::COMPOSITE_ATOP,
            0,
            0
        );

        $imagick->setFormat("jpg");
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setFilename — Sets the filename before you read or write the image

### Beschreibung

public function Imagick::setFilename(string `$filename`): bool

Sets the filename before you read or write an image file.

### Parameter-Liste

`filename`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setFirstIterator

(PECL imagick 2, PECL imagick 3)

Imagick::setFirstIterator — Sets the Imagick iterator to the first image

### Beschreibung

public function Imagick::setFirstIterator(): bool

Sets the Imagick iterator to the first image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setFont — Sets font

### Beschreibung

public function Imagick::setFont(string `$font`): bool

Sets object's font property. This method can be used for example to set font for caption: pseudo-format. The font needs to be configured in ImageMagick configuration or a file by the name of `font` must exist. This method should not be confused with ImagickDraw::setFont() which sets the font for a specific ImagickDraw object. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.7 oder höher kompiliert wurde.

### Parameter-Liste

`font`

  Font name or a filename

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 A Imagick::setFont() example

Example of using Imagick::setFont

    <?php
    /* Create new imagick object */
    $im = new Imagick();

    /* Set the font for the object */
    $im->setFont("example.ttf");

    /* Create new caption */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Do something with the image */
    ?>

### Siehe auch

- Imagick::getFont() - Gets font
- ImagickDraw::setFont() - Sets the fully-specified font to use when annotating with text
- ImagickDraw::getFont() - Returns the font

# Imagick::setFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setFormat — Sets the format of the Imagick object

### Beschreibung

public function Imagick::setFormat(string `$format`): bool

Sets the format of the Imagick object.

### Parameter-Liste

`format`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setGravity

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::setGravity — Sets the gravity

### Beschreibung

public function Imagick::setGravity(int `$gravity`): bool

Sets the global gravity property for the Imagick object. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.0 oder höher kompiliert wurde.

### Parameter-Liste

`gravity`

  The gravity property. Refer to the list of gravity constants.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# Imagick::setImage

(PECL imagick 2, PECL imagick 3)

Imagick::setImage — Replaces image in the object

### Beschreibung

public function Imagick::setImage(Imagick `$replace`): bool

Replaces the current image sequence with the image from replace object.

### Parameter-Liste

`replace`

  The replace Imagick object

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 A Imagick::setImage() example

An example of using Imagick::setImage()

    <?php
    /* Create the objects */
    $image = new Imagick('source.jpg');
    $replace = new Imagick('replace.jpg');

    /* source.jpg is replaced with replace.jpg */
    $image->setImage($replace);

    /* output the image */
    header('Content-type: image/jpeg');
    echo $image;

    ?>

# Imagick::setImageAlphaChannel

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setImageAlphaChannel — Sets image alpha channel

### Beschreibung

public function Imagick::setImageAlphaChannel(int `$mode`): bool

Activate or deactivate image alpha channel. The `mode` is one of the `Imagick::ALPHACHANNEL_*` constants. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.8 oder höher kompiliert wurde.

### Parameter-Liste

`mode`

  One of the `Imagick::ALPHACHANNEL_*` constants

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Siehe auch

- Imagick::setImageMatte() - Sets the image matte channel
- Imagick Alpha Channel Constants

# Imagick::setImageArtifact

(PECL imagick 3)

Imagick::setImageArtifact — Set image artifact

### Beschreibung

public function Imagick::setImageArtifact(string `$artifact`, string `$value`): bool

Associates an artifact with the image. The difference between image properties and image artifacts is that properties are public and artifacts are private. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.5.7 oder höher kompiliert wurde.

### Parameter-Liste

`artifact`

  The name of the artifact

`value`

  The value of the artifact

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::setImageArtifact()

    <?php
    function setImageArtifact() {

        $src1 = new \Imagick(realpath("./images/artifact/source1.png"));
        $src2 = new \Imagick(realpath("./images/artifact/source2.png"));

        $src2->setImageVirtualPixelMethod(\Imagick::VIRTUALPIXELMETHOD_TRANSPARENT);
        $src2->setImageArtifact('compose:args', "1,0,-0.5,0.5");
        $src1->compositeImage($src2, Imagick::COMPOSITE_MATHEMATICS, 0, 0);

        $src1->setImageFormat('png');
        header("Content-Type: image/png");
        echo $src1->getImagesBlob();
    }

    ?>

### Siehe auch

- Imagick::getImageArtifact() - Get image artifact
- Imagick::deleteImageArtifact() - Delete image artifact

# Imagick::setImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::setImageAttribute — Sets an image attribute

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::setImageAttribute(string `$key`, string `$value`): bool

Sets an image attribute.

### Parameter-Liste

`key`

`value`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBackgroundColor — Sets the image background color

### Beschreibung

public function Imagick::setImageBackgroundColor(mixed `$background`): bool

Sets the image background color.

### Parameter-Liste

`background`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the parameter. Previous versions allow only an ImagickPixel object.

# Imagick::setImageBias

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBias — Sets the image bias for any method that convolves an image

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::setImageBias(float `$bias`): bool

Sets the image bias for any method that convolves an image (e.g. Imagick::ConvolveImage()).

### Parameter-Liste

`bias`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::setImageBias()

    <?php
    //requires ImageMagick version 6.9.0-1 to have an effect on convolveImage
    function setImageBias($bias) {
        $imagick = new \Imagick(realpath("images/stack.jpg"));

        $xKernel = array(
            -0.70, 0, 0.70,
            -0.70, 0, 0.70,
            -0.70, 0, 0.70
        );

        $imagick->setImageBias($bias * \Imagick::getQuantum());
        $imagick->convolveImage($xKernel, \Imagick::CHANNEL_ALL);

        $imagick->setImageFormat('png');

        header('Content-type: image/png');
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageBiasQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::setImageBiasQuantum — Sets the image bias

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::setImageBiasQuantum(float `$bias`): void

Sets the image bias. Bias should be scaled with `0` (no adjustment) to `1` (quantum value).

### Parameter-Liste

`bias`

### Rückgabewerte

# Imagick::setImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBluePrimary — Sets the image chromaticity blue primary point

### Beschreibung

public function Imagick::setImageBluePrimary(float `$x`, float `$y`): bool

Sets the image chromaticity blue primary point.

### Parameter-Liste

`x`

`y`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBorderColor — Sets the image border color

### Beschreibung

public function Imagick::setImageBorderColor(mixed `$border`): bool

Sets the image border color.

### Parameter-Liste

`border`

  The border color

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as a parameter. Previous versions allow only an ImagickPixel object.

# Imagick::setImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageChannelDepth — Sets the depth of a particular image channel

### Beschreibung

public function Imagick::setImageChannelDepth(int `$channel`, int `$depth`): bool

Sets the depth of a particular image channel.

### Parameter-Liste

`channel`

`depth`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageClipMask — Sets image clip mask

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::setImageClipMask(Imagick `$clip_mask`): bool

Sets image clip mask from another Imagick object. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`clip_mask`

  The Imagick object containing the clip mask

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::setImageClipMask()

    <?php
    function setImageClipMask($imagePath) {
        $imagick = new \Imagick();
        $imagick->readImage(realpath($imagePath));

        $width = $imagick->getImageWidth();
        $height = $imagick->getImageHeight();

        $clipMask = new \Imagick();
        $clipMask->newPseudoImage(
            $width,
            $height,
            "canvas:transparent"
        );

        $draw = new \ImagickDraw();
        $draw->setFillColor('white');
        $draw->circle(
            $width / 2,
            $height / 2,
            ($width / 2) + ($width / 4),
            $height / 2
        );
        $clipMask->drawImage($draw);
        $imagick->setImageClipMask($clipMask);

        $imagick->negateImage(false);
        $imagick->setFormat("png");

        header("Content-Type: image/png");
        echo $imagick->getImagesBlob();

    }

    ?>

# Imagick::setImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColormapColor — Sets the color of the specified colormap index

### Beschreibung

public function Imagick::setImageColormapColor(int `$index`, ImagickPixel `$color`): bool

Sets the color of the specified colormap index.

### Parameter-Liste

`index`

`color`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColorspace — Sets the image colorspace

### Beschreibung

public function Imagick::setImageColorspace(int `$colorspace`): bool

Sets the image colorspace. This method should be used when creating new images. To change the colorspace of an existing image, you should use Imagick::transformImageColorspace().

### Parameter-Liste

`colorspace`

  One of the COLORSPACE constants

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompose — Sets the image composite operator

### Beschreibung

public function Imagick::setImageCompose(int `$compose`): bool

Sets the image composite operator, useful for specifying how to composite the image thumbnail when using the Imagick::montageImage() method.

### Parameter-Liste

`compose`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompression — Sets the image compression

### Beschreibung

public function Imagick::setImageCompression(int `$compression`): bool

### Parameter-Liste

`compression`

  One of the `COMPRESSION` constants

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompressionQuality — Sets the image compression quality

### Beschreibung

public function Imagick::setImageCompressionQuality(int `$quality`): bool

Sets the image compression quality.

### Parameter-Liste

`quality`

  The image compression quality as an integer

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::setImageCompressionQuality()

    <?php
    function setImageCompressionQuality($imagePath, $quality) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageCompressionQuality($quality);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDelay — Sets the image delay

### Beschreibung

public function Imagick::setImageDelay(int `$delay`): bool

Sets the image delay. For an animated image this is the amount of time that this frame of the image should be displayed for, before displaying the next frame.

The delay can be set individually for each frame in an image.

### Parameter-Liste

`delay`

  The amount of time expressed in 'ticks' that the image should be displayed for. For animated GIFs there are 100 ticks per second, so a value of 20 would be 20/100 of a second aka 1/5th of a second.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Modify animated Gif with Imagick::setImageDelay()

    <?php

    // Modify an animated Gif so that it's frames are played at a variable speed,
    // varying between being shown for 50ms down to 0ms, which will cause the frame
    // to be skipped in most browsers.
    $imagick = new Imagick(realpath("Test.gif"));
    $imagick = $imagick->coalesceImages();

    $frameCount = 0;

    foreach ($imagick as $frame) {
        $imagick->setImageDelay((($frameCount % 11) * 5));
        $frameCount++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/path/to/save/output.gif", true);

    ?>

# Imagick::setImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDepth — Sets the image depth

### Beschreibung

public function Imagick::setImageDepth(int `$depth`): bool

Sets the image depth.

### Parameter-Liste

`depth`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDispose — Sets the image disposal method

### Beschreibung

public function Imagick::setImageDispose(int `$dispose`): bool

Sets the image disposal method.

### Parameter-Liste

`dispose`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageExtent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageExtent — Sets the image size

### Beschreibung

public function Imagick::setImageExtent(int `$columns`, int `$rows`): bool

Sets the image size (i.e. columns & rows).

### Parameter-Liste

`columns`

`rows`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFilename — Sets the filename of a particular image

### Beschreibung

public function Imagick::setImageFilename(string `$filename`): bool

Sets the filename of a particular image in a sequence.

### Parameter-Liste

`filename`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFormat — Sets the format of a particular image

### Beschreibung

public function Imagick::setImageFormat(string `$format`): bool

Sets the format of a particular image in a sequence.

### Parameter-Liste

`format`

  String presentation of the image format. Format support depends on the ImageMagick installation.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGamma — Sets the image gamma

### Beschreibung

public function Imagick::setImageGamma(float `$gamma`): bool

Sets the image gamma.

### Parameter-Liste

`gamma`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageGravity — Sets the image gravity

### Beschreibung

public function Imagick::setImageGravity(int `$gravity`): bool

Sets the gravity property for the current image. This method can be used to set the gravity property for a single image sequence. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.4 oder höher kompiliert wurde.

### Parameter-Liste

`gravity`

  The gravity property. Refer to the list of gravity constants.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# Imagick::setImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGreenPrimary — Sets the image chromaticity green primary point

### Beschreibung

public function Imagick::setImageGreenPrimary(float `$x`, float `$y`): bool

Sets the image chromaticity green primary point.

### Parameter-Liste

`x`

`y`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIndex — Set the iterator position

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::setImageIndex(int `$index`): bool

Set the iterator to the position in the image list specified with the index parameter.

This method has been deprecated. See Imagick::setIteratorIndex().

### Parameter-Liste

`index`

  The position to set the iterator to

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterlaceScheme — Sets the image compression

### Beschreibung

public function Imagick::setImageInterlaceScheme(int `$interlace_scheme`): bool

Sets the image compression.

### Parameter-Liste

`interlace_scheme`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterpolateMethod — Sets the image interpolate pixel method

### Beschreibung

public function Imagick::setImageInterpolateMethod(int `$method`): bool

Sets the image interpolate pixel method.

### Parameter-Liste

`method`

  The method is one of the `Imagick::INTERPOLATE_*` constants

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIterations — Sets the image iterations

### Beschreibung

public function Imagick::setImageIterations(int `$iterations`): bool

Sets the number of iterations an animated image is repeated.

### Parameter-Liste

`iterations`

  The number of iterations the image should loop over. Set to '0' to loop continuously.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Basic Imagick::setImageIterations() usage

    <?php

    $imagick = new Imagick(realpath("Test.gif"));

    $imagick = $imagick->coalesceImages();
    $imagick->setImageIterations(1);
    $imagick = $imagick->deconstructImages();

    $imagick->writeImages('/path/to/save/OnceOnly.gif', true);

    ?>

# Imagick::setImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatte — Sets the image matte channel

### Beschreibung

public function Imagick::setImageMatte(bool `$matte`): bool

Sets the image matte channel. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`matte`

  True activates the matte channel and false disables it.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatteColor — Sets the image matte color

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::setImageMatteColor(mixed `$matte`): bool

Sets the image matte color.

### Parameter-Liste

`matte`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the parameter. Previous versions allow only an ImagickPixel object.

# Imagick::setImageOpacity

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOpacity — Sets the image opacity level

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::setImageOpacity(float `$opacity`): bool

Sets the image to the specified opacity level. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.1 oder höher kompiliert wurde. This method operates on all channels, which means that for example opacity value of 0.5 will set all transparent areas to partially opaque. To add transparency to areas that are not already transparent use Imagick::evaluateImage()

### Parameter-Liste

`opacity`

  The level of transparency: 1.0 is fully opaque and 0.0 is fully transparent.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 A Imagick::setImageOpacity() example

An example of using Imagick::setImageOpacity()

    <?php
    /* Create the object */
    $image = new Imagick('source.png');

    /* Set the opacity */
    $image->setImageOpacity(0.7);

    /* output the image */
    header('Content-type: image/png');
    echo $image;

    ?>

# Imagick::setImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOrientation — Sets the image orientation

### Beschreibung

public function Imagick::setImageOrientation(int `$orientation`): bool

Sets the image orientation.

### Parameter-Liste

`orientation`

  One of the orientation constants

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::setImageOrientation()

    <?php
    //Doesn't appear to do anything
    function setImageOrientation($imagePath, $orientationType) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOrientation($orientationType);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::setImagePage — Sets the page geometry of the image

### Beschreibung

public function Imagick::setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Sets the page geometry of the image.

### Parameter-Liste

`width`

`height`

`x`

`y`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProfile — Adds a named profile to the Imagick object

### Beschreibung

public function Imagick::setImageProfile(string `$name`, string `$profile`): bool

Adds a named profile to the Imagick object. If a profile with the same name already exists, it is replaced. This method differs from the Imagick::ProfileImage() method in that it does not apply any CMS color profiles.

### Parameter-Liste

`name`

`profile`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProperty — Sets an image property

### Beschreibung

public function Imagick::setImageProperty(string `$name`, string `$value`): bool

Sets a named property to the image. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.2 oder höher kompiliert wurde.

### Parameter-Liste

`name`

`value`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Using Imagick::setImageProperty():

Setting and getting image properties

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");

    $image->setImageProperty('Exif:Make', 'Imagick');
    echo $image->getImageProperty('Exif:Make');
    ?>

### Siehe auch

- Imagick::getImageProperty() - Returns the named image property

# Imagick::setImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRedPrimary — Sets the image chromaticity red primary point

### Beschreibung

public function Imagick::setImageRedPrimary(float `$x`, float `$y`): bool

Sets the image chromaticity red primary point.

### Parameter-Liste

`x`

`y`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRenderingIntent — Sets the image rendering intent

### Beschreibung

public function Imagick::setImageRenderingIntent(int `$rendering_intent`): bool

Sets the image rendering intent.

### Parameter-Liste

`rendering_intent`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setImageResolution — Sets the image resolution

### Beschreibung

public function Imagick::setImageResolution(float `$x_resolution`, float `$y_resolution`): bool

Sets the image resolution.

### Parameter-Liste

`x_resolution`

`y_resolution`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::setImageResolution()

    <?php
    function setImageResolution($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageResolution(50, 50);

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::setImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::setImageScene — Sets the image scene

### Beschreibung

public function Imagick::setImageScene(int `$scene`): bool

Sets the image scene.

### Parameter-Liste

`scene`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::setImageTicksPerSecond — Sets the image ticks-per-second

### Beschreibung

public function Imagick::setImageTicksPerSecond(int `$ticks_per_second`): bool

Adjust the amount of time that a frame of an animated image is displayed for.

> Hinweis:

> For animated GIFs, this function does not change the number of 'image ticks' per second, which is always defined as 100. Instead it adjusts the amount of time that the frame is displayed for to simulate the change in 'ticks per second'.

> For example, for an animated GIF where each frame is displayed for 20 ticks (1/5 of a second) when this method is called on each frame of that image with an argument of `50` the frames are adjusted to be displayed for 40 ticks (2/5 of a second) and the animation will play at half the original speed.

### Parameter-Liste

`ticks_per_second`

  The duration for which an image should be displayed expressed in ticks per second.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Modify animated Gif with Imagick::setImageTicksPerSecond()

    <?php

    // Modify an animated gif so the first half of the gif is played at half the
    // speed it currently is, and the second half to be played at double the speed
    // it currently is

    $imagick = new Imagick(realpath("Test.gif"));
    $imagick = $imagick->coalesceImages();

    $totalFrames = $imagick->getNumberImages();

    $frameCount = 0;

    foreach ($imagick as $frame) {
        $imagick->setImageTicksPerSecond(50);

        if ($frameCount < ($totalFrames / 2)) {
            // Modify the frame to be displayed for twice as long as it currently is
            $imagick->setImageTicksPerSecond(50);
        } else {
            // Modify the frame to be displayed for half as long as it currently is
            $imagick->setImageTicksPerSecond(200);
        }

        $frameCount++;
    }

    $imagick = $imagick->deconstructImages();

    $imagick->writeImages("/path/to/save/output.gif", true);

    ?>

# Imagick::setImageType

(PECL imagick 2, PECL imagick 3)

Imagick::setImageType — Sets the image type

### Beschreibung

public function Imagick::setImageType(int `$image_type`): bool

Sets the image type.

### Parameter-Liste

`image_type`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::setImageUnits — Sets the image units of resolution

### Beschreibung

public function Imagick::setImageUnits(int `$units`): bool

Sets the image units of resolution.

### Parameter-Liste

`units`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageVirtualPixelMethod — Sets the image virtual pixel method

### Beschreibung

public function Imagick::setImageVirtualPixelMethod(int `$method`): bool

Sets the image virtual pixel method.

### Parameter-Liste

`method`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::setImageWhitePoint — Sets the image chromaticity white point

### Beschreibung

public function Imagick::setImageWhitePoint(float `$x`, float `$y`): bool

Sets the image chromaticity white point.

### Parameter-Liste

`x`

`y`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::setInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setInterlaceScheme — Sets the image compression

### Beschreibung

public function Imagick::setInterlaceScheme(int `$interlace_scheme`): bool

Sets the image compression.

### Parameter-Liste

`interlace_scheme`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setIteratorIndex — Set the iterator position

### Beschreibung

public function Imagick::setIteratorIndex(int `$index`): bool

Set the iterator to the position in the image list specified with the index parameter. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`index`

  The position to set the iterator to

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Using Imagick::setIteratorIndex():

Create images, set and get the iterator index

    <?php
    $im = new Imagick();
    $im->newImage(100, 100, new ImagickPixel("red"));
    $im->newImage(100, 100, new ImagickPixel("green"));
    $im->newImage(100, 100, new ImagickPixel("blue"));

    $im->setIteratorIndex(1);
    echo $im->getIteratorIndex();
    ?>

### Siehe auch

- Imagick::getIteratorIndex() - Gets the index of the current active image
- Imagick::getImageIndex() - Gets the index of the current active image
- Imagick::setImageIndex() - Set the iterator position

# Imagick::setLastIterator

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::setLastIterator — Sets the Imagick iterator to the last image

### Beschreibung

public function Imagick::setLastIterator(): bool

Sets the Imagick iterator to the last image.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setOption

(PECL imagick 2, PECL imagick 3)

Imagick::setOption — Set an option

### Beschreibung

public function Imagick::setOption(string `$key`, string `$value`): bool

Associates one or more options with the wand.

### Parameter-Liste

`key`

`value`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Attempt to reach '$extent' sizeImagick::setOption()

    <?php
        function renderJPG($extent) {
            $imagePath = $this->control->getImagePath();
            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('jpg');
            $imagick->setOption('jpeg:extent', $extent);
            header("Content-Type: image/jpg");
            echo $imagick->getImageBlob();
        }

    ?>

Beispiel #2 Imagick::setOption()

    <?php
        function renderPNG($imagePath, $format) {

            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('png');
            $imagick->setOption('png:format', $format);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

        //Save as 64bit PNG.
        renderPNG($imagePath, 'png64');

    ?>

Beispiel #3 Imagick::setOption()

    <?php
        function renderCustomBitDepthPNG() {
            $imagePath = $this->control->getImagePath();
            $imagick = new \Imagick(realpath($imagePath));
            $imagick->setImageFormat('png');

            $imagick->setOption('png:bit-depth', '16');
            $imagick->setOption('png:color-type', 6);
            header("Content-Type: image/png");
            $crash = true;
            if ($crash) {
                echo $imagick->getImageBlob();
            }
            else {
                $tempFilename = tempnam('./', 'imagick');
                $imagick->writeimage(realpath($tempFilename));
                echo file_get_contents($tempFilename);
            }
        }

    ?>

# Imagick::setPage

(PECL imagick 2, PECL imagick 3)

Imagick::setPage — Sets the page geometry of the Imagick object

### Beschreibung

public function Imagick::setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Sets the page geometry of the Imagick object.

### Parameter-Liste

`width`

`height`

`x`

`y`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setPointSize — Sets point size

### Beschreibung

public function Imagick::setPointSize(float `$point_size`): bool

Sets object's point size property. This method can be used for example to set font size for caption: pseudo-format. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.7 oder höher kompiliert wurde.

### Parameter-Liste

`point_size`

  Point size

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 A Imagick::setPointSize() example

Example of using Imagick::setPointSize

    <?php
    /* Create new imagick object */
    $im = new Imagick();

    /* Set the font for the object */
    $im->setFont("example.ttf");

    /* Set the point size */
    $im->setPointSize(12);

    /* Create new caption */
    $im->newPseudoImage(100, 100, "caption:Hello");

    /* Do something with the image */
    ?>

### Siehe auch

- Imagick::getPointSize() - Gets point size

# Imagick::setProgressMonitor

(PECL imagick 3 >= 3.3.0)

Imagick::setProgressMonitor — Set a callback to be called during processing

### Beschreibung

public function Imagick::setProgressMonitor(callable `$callback`): bool

Set a callback that will be called during the processing of the Imagick image.

### Parameter-Liste

`callback`

  The progress function to call. It should return true if image processing should continue, or false if it should be cancelled. The offset parameter indicates the progress and the span parameter indicates the total amount of work needed to be done.

  function callback ( mixed `$offset` , mixed `$span` ): bool
  Achtung

  The values passed to the callback function are not consistent. In particular the span parameter can increase during image processing. Because of this calculating the percentage complete of an image operation is not trivial.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::setProgressMonitor()

    <?php
            $abortReason = null;

            try {
                $imagick = new \Imagick(realpath($this->control->getImagePath()));
                $startTime = time();

                $callback = function ($offset, $span)  use ($startTime, &$abortReason) {
                    if (((100 * $offset) / $span)  > 20) {
                        $abortReason = "Processing reached 20%";
                        return false;
                    }

                    $nowTime = time();

                    if ($nowTime - $startTime > 5) {
                        $abortReason = "Image processing took more than 5 seconds";
                        return false;
                    }
                    if (($offset % 5) == 0) {
                        echo "Progress: $offset / $span <br/>";
                    }
                    return true;
                };

                $imagick->setProgressMonitor($callback);

                $imagick->waveImage(2, 15);

                echo "Data len is: ".strlen($imagick->getImageBlob());
            }
            catch(\ImagickException $e) {
                if ($abortReason != null) {
                    echo "Image processing was aborted: ".$abortReason."<br/>";
                }
                else {
                    echo "ImagickException caught: ".$e->getMessage()." Exception type is ".get_class($e);
                }
            }

    ?>

# Imagick::setRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::setRegistry — Sets the ImageMagick registry entry named key to value

### Beschreibung

public static function Imagick::setRegistry(string `$key`, string `$value`): bool

Sets the ImageMagick registry entry named key to value. This is most useful for setting "temporary-path" which controls where ImageMagick creates temporary images e.g. while processing PDFs.

### Parameter-Liste

`key`

`value`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setResolution — Sets the image resolution

### Beschreibung

public function Imagick::setResolution(float `$x_resolution`, float `$y_resolution`): bool

Sets the image resolution.

### Parameter-Liste

`x_resolution`

  The horizontal resolution.

`y_resolution`

  The vertical resolution.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Anmerkungen

Imagick::setResolution() must be called before loading or creating an image.

### Siehe auch

- Imagick::setImageResolution() - Sets the image resolution
- Imagick::getImageResolution() - Gets the image X and Y resolution

# Imagick::setResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::setResourceLimit — Sets the limit for a particular resource

### Beschreibung

public static function Imagick::setResourceLimit(int `$type`, int `$limit`): bool

This method is used to modify the resource limits of the underlying ImageMagick library.

### Parameter-Liste

`type`

  Refer to the list of resourcetype constants.

`limit`

  One of the resourcetype constants. The unit depends on the type of the resource being limited.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Siehe auch

- Imagick::getResourceLimit() - Returns the specified resource limit

# Imagick::setSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::setSamplingFactors — Sets the image sampling factors

### Beschreibung

public function Imagick::setSamplingFactors(array `$factors`): bool

Sets the image sampling factors.

### Parameter-Liste

`factors`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::setSamplingFactors()

    <?php
    function setSamplingFactors($imagePath) {

        $imagePath = "../imagick/images/FineDetail.png";
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageFormat('jpg');
        $imagick->setSamplingFactors(array('2x2', '1x1', '1x1'));

        $compressed = $imagick->getImageBlob();

        $reopen = new \Imagick();
        $reopen->readImageBlob($compressed);

        $reopen->resizeImage(
            $reopen->getImageWidth() * 4,
            $reopen->getImageHeight() * 4,
            \Imagick::FILTER_POINT,
            1
        );

        header("Content-Type: image/jpg");
        echo $reopen->getImageBlob();
    }

    ?>

# Imagick::setSize

(PECL imagick 2, PECL imagick 3)

Imagick::setSize — Sets the size of the Imagick object

### Beschreibung

public function Imagick::setSize(int `$columns`, int `$rows`): bool

Sets the size of the Imagick object. Set it before you read a raw image format such as RGB, GRAY, or CMYK.

### Parameter-Liste

`columns`

`rows`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::setSizeOffset — Sets the size and offset of the Imagick object

### Beschreibung

public function Imagick::setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool

Sets the size and offset of the Imagick object. Set it before you read a raw image format such as RGB, GRAY, or CMYK. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`columns`

  The width in pixels.

`rows`

  The height in pixels.

`offset`

  The image offset.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::setType

(PECL imagick 2, PECL imagick 3)

Imagick::setType — Sets the image type attribute

### Beschreibung

public function Imagick::setType(int `$image_type`): bool

Sets the image type attribute.

### Parameter-Liste

`image_type`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::shadeImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadeImage — Creates a 3D effect

### Beschreibung

public function Imagick::shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool

Shines a distant light on an image to create a three-dimensional effect. You control the positioning of the light with azimuth and elevation; azimuth is measured in degrees off the x axis and elevation is measured in pixels above the Z axis. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`gray`

  A value other than zero shades the intensity of each pixel.

`azimuth`

  Defines the light source direction.

`elevation`

  Defines the light source direction.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Throws ImagickException on failure.

### Beispiele

Beispiel #1 Imagick::shadeImage()

    <?php
    function shadeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadeImage(true, 45, 20);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shadowImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadowImage — Simulates an image shadow

### Beschreibung

public function Imagick::shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool

Simulates an image shadow.

### Parameter-Liste

`opacity`

`sigma`

`x`

`y`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::shadowImage()

    <?php
    function shadowImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shadowImage(0.4, 10, 50, 5);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::sharpenImage — Sharpens an image

### Beschreibung

public function Imagick::sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Sharpens an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, the radius should be larger than sigma. Use a radius of 0 and Imagick::sharpenImage() selects a suitable radius for you.

### Parameter-Liste

`radius`

`sigma`

`channel`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::sharpenImage()

    <?php
    function sharpenImage($imagePath, $radius, $sigma, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sharpenimage($radius, $sigma, $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shaveImage

(PECL imagick 2, PECL imagick 3)

Imagick::shaveImage — Shaves pixels from the image edges

### Beschreibung

public function Imagick::shaveImage(int `$columns`, int `$rows`): bool

Shaves pixels from the image edges. It allocates the memory necessary for the new Image structure and returns a pointer to the new image.

### Parameter-Liste

`columns`

`rows`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::shaveImage()

    <?php
    function shaveImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shaveImage(100, 50);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::shearImage

(PECL imagick 2, PECL imagick 3)

Imagick::shearImage — Creating a parallelogram

### Beschreibung

public function Imagick::shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool

Slides one edge of an image along the X or Y axis, creating a parallelogram. An X direction shear slides an edge along the X axis, while a Y direction shear slides an edge along the Y axis. The amount of the shear is controlled by a shear angle. For X direction shears, x_shear is measured relative to the Y axis, and similarly, for Y direction shears y_shear is measured relative to the X axis. Empty triangles left over from shearing the image are filled with the background color.

### Parameter-Liste

`background`

  The background color

`x_shear`

  The number of degrees to shear on the x axis

`y_shear`

  The number of degrees to shear on the y axis

### Rückgabewerte

Liefert `true` bei Erfolg.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter. Previous versions allow only an ImagickPixel object.

### Beispiele

Beispiel #1 Imagick::shearImage()

    <?php
    function shearImage($imagePath, $color, $shearX, $shearY) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->shearimage($color, $shearX, $shearY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sigmoidalContrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::sigmoidalContrastImage — Adjusts the contrast of an image

### Beschreibung

public function Imagick::sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Adjusts the contrast of an image with a non-linear sigmoidal contrast algorithm. Increase the contrast of the image using a sigmoidal transfer function without saturating highlights or shadows. Contrast indicates how much to increase the contrast (0 is none; 3 is typical; 20 is pushing it); mid-point indicates where midtones fall in the resultant image (0 is white; 50 is middle-gray; 100 is black). Set sharpen to `true` to increase the image contrast otherwise the contrast is reduced.

See also » ImageMagick v6 Examples - Image Transformations — Sigmoidal Non-linearity Contrast

### Parameter-Liste

`sharpen`

  If true increase the contrast, if false decrease the contrast.

`alpha`

  The amount of contrast to apply. 1 is very little, 5 is a significant amount, 20 is extreme.

`beta`
  Where the midpoint of the gradient will be. This value should be in the range 0 to 1 - multiplied by the quantum value for ImageMagick.
`channel`

  Which color channels the contrast will be applied to.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Create a gradient image using Imagick::sigmoidalContrastImage() suitable for blending two images together smoothly, with the blending defined by $contrast and $the midpoint

    <?php

    function generateBlendImage($width, $height, $contrast = 10, $midpoint = 0.5) {
        $imagick = new Imagick();
        $imagick->newPseudoImage($width, $height, 'gradient:black-white');
        $quanta = $imagick->getQuantumRange();
        $imagick->sigmoidalContrastImage(true, $contrast, $midpoint * $quanta["quantumRangeLong"]);

        return $imagick;
    }

    ?>

# Imagick::sketchImage

(PECL imagick 2, PECL imagick 3)

Imagick::sketchImage — Simulates a pencil sketch

### Beschreibung

public function Imagick::sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool

Simulates a pencil sketch. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and Imagick::sketchImage() selects a suitable radius for you. Angle gives the angle of the blurring motion. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`radius`

  The radius of the Gaussian, in pixels, not counting the center pixel

`sigma`

  The standard deviation of the Gaussian, in pixels.

`angle`

  Apply the effect along this angle.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::sketchImage()

    <?php
    function sketchImage($imagePath, $radius, $sigma, $angle) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->sketchimage($radius, $sigma, $angle);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::smushImages

(PECL imagick 3 >= 3.3.0)

Imagick::smushImages — Takes all images from the current image pointer to the end of the image list and smushs them

### Beschreibung

public function Imagick::smushImages(bool `$stack`, int `$offset`): Imagick

Takes all images from the current image pointer to the end of the image list and smushs them to each other top-to-bottom if the stack parameter is true, otherwise left-to-right.

### Parameter-Liste

`stack`

`offset`

### Rückgabewerte

The new smushed image.

### Beispiele

Beispiel #1 Imagick::smushImages()

    <?php
    function smushImages($imagePath, $imagePath2) {

        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = new \Imagick(realpath($imagePath2));

        $imagick->addimage($imagick2);
        $smushed = $imagick->smushImages(false, 50);
        $smushed->setImageFormat('jpg');
        header("Content-Type: image/jpg");
        echo $smushed->getImageBlob();
    }

    ?>

# Imagick::solarizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::solarizeImage — Applies a solarizing effect to the image

### Beschreibung

public function Imagick::solarizeImage(int `$threshold`): bool

Applies a special effect to the image, similar to the effect achieved in a photo darkroom by selectively exposing areas of photo sensitive paper to light. Threshold ranges from 0 to QuantumRange and is a measure of the extent of the solarization.

### Parameter-Liste

`threshold`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::solarizeImage()

    <?php
    function solarizeImage($imagePath, $solarizeThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->solarizeImage($solarizeThreshold * \Imagick::getQuantum());
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::sparseColorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::sparseColorImage — Interpolates colors

### Beschreibung

public function Imagick::sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Given the arguments array containing numeric values this method interpolates the colors found at those coordinates across the whole image using `sparse_method`. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.4.5 oder höher kompiliert wurde.

### Parameter-Liste

`SPARSE_METHOD`

  Refer to this list of sparse method constants

`arguments`

  An array containing the coordinates. The array is in format `array(1,1, 2,45)`

`channel`

  Übergeben Sie eine Channel-Konstante, die für Ihren Channel-Moduls gültig ist. Um mehr als einen Channel anzuwenden, können Sie die Channel-Konstanten mit bitweisen Operationen verknüpfen. Der Standardwert ist `Imagick::CHANNEL_DEFAULT`. Weitere Informationen enthält die Liste der Channel-Konstanten

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

    <?php
        function renderImageBarycentric2() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(
                400, 400,
                $points,
                \Imagick::SPARSECOLORMETHOD_BARYCENTRIC
            );
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Beispiel #2 SPARSECOLORMETHOD_BILINEAR Imagick::sparseColorImage()

    <?php
        function renderImageBilinear() {
            $points = [[0.30, 0.10, 'red'], [0.10, 0.80, 'blue'], [0.70, 0.60, 'lime'], [0.80, 0.20, 'yellow'],];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_BILINEAR);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Beispiel #3 SPARSECOLORMETHOD_SPEPARDS Imagick::sparseColorImage()

    <?php
        function renderImageShepards() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(600, 600, $points, \Imagick::SPARSECOLORMETHOD_SPEPARDS);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Beispiel #4 SPARSECOLORMETHOD_VORONOI Imagick::sparseColorImage()

    <?php
        function renderImageVoronoi() {
            $points = [
                [0.30, 0.10, 'red'],
                [0.10, 0.80, 'blue'],
                [0.70, 0.60, 'lime'],
                [0.80, 0.20, 'yellow'],
            ];
            $imagick = createGradientImage(500, 500, $points, \Imagick::SPARSECOLORMETHOD_VORONOI);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Beispiel #5 SPARSECOLORMETHOD_BARYCENTRIC Imagick::sparseColorImage()

    <?php
        function renderImageBarycentric() {
            $points = [
                [0, 0, 'skyblue'],
                [-1, 1, 'skyblue'],
                [1, 1, 'black'],
            ];
            $imagick = createGradientImage(600, 200, $points, \Imagick::SPARSECOLORMETHOD_BARYCENTRIC);
            header("Content-Type: image/png");
            echo $imagick->getImageBlob();
        }

    ?>

Beispiel #6 createGradientImage is used by other examples. Imagick::sparseColorImage()

    <?php
    function createGradientImage($width, $height, $colorPoints, $sparseMethod, $absolute = false) {

        $imagick = new \Imagick();
        $imagick->newImage($width, $height, "white");
        $imagick->setImageFormat("png");

        $barycentricPoints = array();

        foreach ($colorPoints as $colorPoint) {

            if ($absolute == true) {
                $barycentricPoints[] = $colorPoint[0];
                $barycentricPoints[] = $colorPoint[1];
            }
            else {
                $barycentricPoints[] = $colorPoint[0] * $width;
                $barycentricPoints[] = $colorPoint[1] * $height;
            }

            if (is_string($colorPoint[2])) {
                $imagickPixel = new \ImagickPixel($colorPoint[2]);
            }
            else if ($colorPoint[2] instanceof \ImagickPixel) {
                $imagickPixel = $colorPoint[2];
            }
            else{
                $errorMessage = sprintf(
                    "Value %s is neither a string nor an ImagickPixel class. Cannot use as a color.",
                    $colorPoint[2]
                );

                throw new \InvalidArgumentException(
                    $errorMessage
                );
            }

            $red = $imagickPixel->getColorValue(\Imagick::COLOR_RED);
            $green = $imagickPixel->getColorValue(\Imagick::COLOR_GREEN);
            $blue = $imagickPixel->getColorValue(\Imagick::COLOR_BLUE);
            $alpha = $imagickPixel->getColorValue(\Imagick::COLOR_ALPHA);

            $barycentricPoints[] = $red;
            $barycentricPoints[] = $green;
            $barycentricPoints[] = $blue;
            $barycentricPoints[] = $alpha;
        }

        $imagick->sparseColorImage($sparseMethod, $barycentricPoints);

        return $imagick;
    }

    ?>

# Imagick::spliceImage

(PECL imagick 2, PECL imagick 3)

Imagick::spliceImage — Splices a solid color into the image

### Beschreibung

public function Imagick::spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Splices a solid color into the image.

### Parameter-Liste

`width`

`height`

`x`

`y`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::spliceImage()

    <?php
    function spliceImage($imagePath, $startX, $startY, $width, $height) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spliceImage($width, $height, $startX, $startY);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::spreadImage

(PECL imagick 2, PECL imagick 3)

Imagick::spreadImage — Randomly displaces each pixel in a block

### Beschreibung

public function Imagick::spreadImage(float `$radius`): bool

Special effects method that randomly displaces each pixel in a block defined by the radius parameter.

### Parameter-Liste

`radius`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::spreadImage()

    <?php
    function spreadImage($imagePath, $radius) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->spreadImage($radius);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::statisticImage

(PECL imagick 3 >= 3.3.0)

Imagick::statisticImage — Modifies image using a statistics function

### Beschreibung

public function Imagick::statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Replace each pixel with corresponding statistic from the neighborhood of the specified width and height.

### Parameter-Liste

`type`

`width`

`height`

`channel`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::statisticImage()

    <?php
    function statisticImage($imagePath, $statisticType, $width, $height, $channel) {
        $imagick = new \Imagick(realpath($imagePath));

        $imagick->statisticImage(
            $statisticType,
            $width,
            $height,
            $channel
        );

        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    statisticImage($imagePath, \Imagick::STATISTIC_MEDIAN, 5, 5, \Imagick::CHANNEL_DEFAULT);

    ?>

# Imagick::steganoImage

(PECL imagick 2, PECL imagick 3)

Imagick::steganoImage — Hides a digital watermark within the image

### Beschreibung

public function Imagick::steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick

Hides a digital watermark within the image. Recover the hidden watermark later to prove that the authenticity of an image. Offset defines the start position within the image to hide the watermark.

### Parameter-Liste

`watermark_wand`

`offset`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::stereoImage

(PECL imagick 2, PECL imagick 3)

Imagick::stereoImage — Composites two images

### Beschreibung

public function Imagick::stereoImage(Imagick `$offset_wand`): bool

Composites two images and produces a single image that is the composite of a left and right image of a stereo pair.

### Parameter-Liste

`offset_wand`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::stripImage

(PECL imagick 2, PECL imagick 3)

Imagick::stripImage — Strips an image of all profiles and comments

### Beschreibung

public function Imagick::stripImage(): bool

Strips an image of all profiles and comments.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

# Imagick::subImageMatch

(PECL imagick 3 >= 3.3.0)

Imagick::subImageMatch — Searches for a subimage in the current image and returns a similarity image

### Beschreibung

public function Imagick::subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick

Searches for a subimage in the current image and returns a similarity image such that an exact match location is completely white and if none of the pixels match, black, otherwise some gray level in-between. You can also pass in the optional parameters bestMatch and similarity. After calling the function similarity will be set to the 'score' of the similarity between the subimage and the matching position in the larger image, bestMatch will contain an associative array with elements x, y, width, height that describe the matching region.

### Parameter-Liste

`Imagick`

`offset`

`similarity`

  A new image that displays the amount of similarity at each pixel.

### Rückgabewerte

### Beispiele

Beispiel #1 Imagick::subImageMatch()

    <?php
    function subImageMatch($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick2 = clone $imagick;
        $imagick2->cropimage(40, 40, 250, 110);
        $imagick2->vignetteimage(0, 1, 3, 3);

        $similarity = null;
        $bestMatch = null;
        $comparison = $imagick->subImageMatch($imagick2, $bestMatch, $similarity);

        $comparison->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::swirlImage

(PECL imagick 2, PECL imagick 3)

Imagick::swirlImage — Swirls the pixels about the center of the image

### Beschreibung

function Imagick::swirlImage(float `$degrees`): bool

Swirls the pixels about the center of the image, where degrees indicates the sweep of the arc through which each pixel is moved. You get a more dramatic effect as the degrees move from 1 to 360.

### Parameter-Liste

`degrees`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::swirlImage()

    <?php
    function swirlImage($imagePath, $swirl) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->swirlImage($swirl);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::textureImage

(PECL imagick 2, PECL imagick 3)

Imagick::textureImage — Repeatedly tiles the texture image

### Beschreibung

function Imagick::textureImage(Imagick `$texture_wand`): Imagick

Repeatedly tiles the texture image across and down the image canvas.

### Parameter-Liste

`texture_wand`

  Imagick object to use as texture image

### Rückgabewerte

Returns a new Imagick object that has the repeated texture applied.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::textureImage()

    <?php
    function textureImage($imagePath) {
        $image = new \Imagick();
        $image->newImage(640, 480, new \ImagickPixel('pink'));
        $image->setImageFormat("jpg");
        $texture = new \Imagick(realpath($imagePath));
        $texture->scaleimage($image->getimagewidth() / 4, $image->getimageheight() / 4);
        $image = $image->textureImage($texture);
        header("Content-Type: image/jpg");
        echo $image;
    }

    ?>

# Imagick::thresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::thresholdImage — Changes the value of individual pixels based on a threshold

### Beschreibung

public function Imagick::thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

Changes the value of individual pixels based on the intensity of each pixel compared to threshold. The result is a high-contrast, two color image.

### Parameter-Liste

`threshold`

`channel`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::thresholdImage()

    <?php
    function thresholdimage($imagePath, $threshold, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->thresholdimage($threshold * \Imagick::getQuantum(), $channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::thumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::thumbnailImage — Changes the size of an image

### Beschreibung

public function Imagick::thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool

Changes the size of an image to the given dimensions and removes any associated profiles. The goal is to produce small, low cost thumbnail images suited for display on the Web. If `true` is given as a third parameter then columns and rows parameters are used as maximums for each side. Both sides will be scaled down until they match or are smaller than the parameter given for the side.

> Hinweis: Das Verhalten des Parameters `bestfit` hat sich mit Imagick 3.0.0 geändert. Vor dieser Version wurde ein Bild der Größe 200x150 bei der angegebenen Größe von 400x400 nicht verändert. In Imagick 3.0.0 und späteren Versionen wird dieses Bild auf die Größe 400x300 hochgerechnet, da dies die passendste größe für die angegebene Bildgröße ist. Wenn der `bestfit`-Parameter angegeben wird, so muss sowohl eine Breite als auch eine Höhe angegeben werden.

### Parameter-Liste

`columns`

  Image width

`rows`

  Image height

`bestfit`

  Whether to force maximum values

`fill`

  If the image does not fill the box completely then the box is filled with image's background color.

`legacy`

  Round the smaller dimension down instead to the closest integer.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::thumbnailImage()

    <?php
    function thumbnailImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setbackgroundcolor('rgb(64, 64, 64)');
        $imagick->thumbnailImage(100, 100, true, true);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::tintImage

(PECL imagick 2, PECL imagick 3)

Imagick::tintImage — Applies a color vector to each pixel in the image

### Beschreibung

public function Imagick::tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool

Applies a color vector to each pixel in the image. The length of the vector is 0 for black and white and at its maximum for the midtones. The vector weighing function is f(x)=(1-(4.0*((x-0.5)*(x-0.5)))).

### Parameter-Liste

`tint`

`opacity`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as the first parameter and a float representing the opacity value as the second parameter. Previous versions allow only an ImagickPixel objects.

### Beispiele

Beispiel #1 Imagick::tintImage()

    <?php
    function tintImage($r, $g, $b, $a) {
        $a = $a / 100;

        $imagick = new \Imagick();
        $imagick->newPseudoImage(400, 400, 'gradient:black-white');

        $tint = new \ImagickPixel("rgb($r, $g, $b)");
        $opacity = new \ImagickPixel("rgb(128, 128, 128, $a)");
        $imagick->tintImage($tint, $opacity);
        $imagick->setImageFormat('png');
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::__toString

(PECL imagick 2, PECL imagick 3)

Imagick::__toString — Returns the image as a string

### Beschreibung

public function Imagick::__toString(): string

Returns the current image as string. This will only return a single image; it should not be used for Imagick objects that contain multiple images e.g. an animated GIF or PDF with multiple pages.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the string content on success or an empty string on failure.

### Siehe auch

- Imagick::getImageBlob() - Returns the image sequence as a blob
- Imagick::getImagesBlob() - Returns all image sequences as a blob

# Imagick::transformImage

(PECL imagick 2, PECL imagick 3)

Imagick::transformImage — Convenience method for setting crop size and the image geometry

Warnung

Diese Funktion ist von Imagick 3.4.4 an MISSBILLIGT. Von der weiteren Verwendung wird dringend abgeraten.

### Beschreibung

public function Imagick::transformImage(string `$crop`, string `$geometry`): Imagick

A convenience method for setting crop size and the image geometry from strings. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`crop`

  A crop geometry string. This geometry defines a subregion of the image to crop.

`geometry`

  An image geometry string. This geometry defines the final size of the image.

### Rückgabewerte

Returns an Imagick object containing the transformed image.

### Beispiele

Beispiel #1 Using Imagick::transformImage():

The example creates a 100x100 black image.

    <?php
    $image = new Imagick();
    $image->newImage(300, 200, "black");
    $new_image = $image->transformImage("100x100", "100x100");
    $new_image->writeImage('test_out.jpg');
    ?>

### Siehe auch

- Imagick::cropImage() - Extracts a region of the image
- Imagick::resizeImage() - Scales an image
- Imagick::thumbnailImage() - Changes the size of an image

# Imagick::transformImageColorspace

(PECL imagick 3)

Imagick::transformImageColorspace — Transforms an image to a new colorspace

### Beschreibung

public function Imagick::transformImageColorspace(int `$colorspace`): bool

Transforms an image to a new colorspace.

### Parameter-Liste

`colorspace`

  The colorspace the image should be transformed to, one of the COLORSPACE constants e.g. Imagick::COLORSPACE_CMYK.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::transformImageColorspace() example

Transforms an image to a new colorspace, and then extracts a single channel so that the individual channel values can be viewed.

    <?php
    function transformImageColorspace($imagePath, $colorSpace, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transformimagecolorspace($colorSpace);
        //channel should be one of the channel constants e.g. \Imagick::CHANNEL_BLUE
        $imagick->separateImageChannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }
    ?>

### Siehe auch

- Imagick::setColorSpace() - Set colorspace

# Imagick::transparentPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::transparentPaintImage — Paints pixels transparent

### Beschreibung

public function Imagick::transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool

Paints pixels matching the target color transparent. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.8 oder höher kompiliert wurde.

### Parameter-Liste

`target`

  The target color to paint

`alpha`

  Die Stufe der Transparenz. 1.0 ist völlig undurchsichtig und 0.0 ist komplett transparent.

`fuzz`

  Die Menge an Ungenauigkeit. Wird dieser Wert z. B. auf 10 gesetzt, so wird die Farbe Rot bei Intensitäten von 100 und 102 als identisch betrachtet.

`invert`

  If `true` paints any pixel that does not match the target color.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::transparentPaintImage()

    <?php
    function transparentPaintImage($color, $alpha, $fuzz) {
        $imagick = new \Imagick(realpath("images/BlueScreen.jpg"));

        //Need to be in a format that supports transparency
        $imagick->setimageformat('png');

        $imagick->transparentPaintImage(
            $color, $alpha, $fuzz * \Imagick::getQuantum(), false
        );

        //Not required, but helps tidy up left over pixels
        $imagick->despeckleimage();

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::transposeImage

(PECL imagick 2, PECL imagick 3)

Imagick::transposeImage — Creates a vertical mirror image

### Beschreibung

public function Imagick::transposeImage(): bool

Creates a vertical mirror image by reflecting the pixels around the central x-axis while rotating them 90-degrees. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::transposeImage()

    <?php
    function transposeImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transposeImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Siehe auch

- Imagick::transverseImage() - Creates a horizontal mirror image

# Imagick::transverseImage

(PECL imagick 2, PECL imagick 3)

Imagick::transverseImage — Creates a horizontal mirror image

### Beschreibung

public function Imagick::transverseImage(): bool

Creates a horizontal mirror image by reflecting the pixels around the central y-axis while rotating them 270-degrees. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::transverseImage()

    <?php
    function transverseImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transverseImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Siehe auch

- Imagick::transposeImage() - Creates a vertical mirror image

# Imagick::trimImage

(PECL imagick 2, PECL imagick 3)

Imagick::trimImage — Remove edges from the image

### Beschreibung

public function Imagick::trimImage(float `$fuzz`): bool

Remove edges that are the background color from the image. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`fuzz`

  By default target must match a particular pixel color exactly. However, in many cases two colors may differ by a small amount. The fuzz member of image defines how much tolerance is acceptable to consider two colors as the same. This parameter represents the variation on the quantum range.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Using Imagick::trimImage():

Trim an image, then display to the browser.

    <?php
    /* Create the object and read the image in */
    $im = new Imagick("image.jpg");

    /* Trim the image. */
    $im->trimImage(0);

    /* Output the image */
    header("Content-Type: image/" . $im->getImageFormat());
    echo $im;
    ?>

### Siehe auch

- Imagick::getQuantumDepth() - Gets the quantum depth
- Imagick::getQuantumRange() - Returns the Imagick quantum range
- imagecropauto() - Crop an image automatically using one of the available modes

# Imagick::uniqueImageColors

(PECL imagick 2,PECL imagick 3)

Imagick::uniqueImageColors — Discards all but one of any pixel color

### Beschreibung

public function Imagick::uniqueImageColors(): bool

Discards all but one of any pixel color. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::uniqueImageColors()

    <?php
    function uniqueImageColors($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        //Reduce the image to 256 colours nicely.
        $imagick->quantizeImage(256, \Imagick::COLORSPACE_YIQ, 0, false, false);
        $imagick->uniqueImageColors();
        $imagick->scaleimage($imagick->getImageWidth(), $imagick->getImageHeight() * 20);
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::unsharpMaskImage

(PECL imagick 2, PECL imagick 3)

Imagick::unsharpMaskImage — Sharpens an image

### Beschreibung

public function Imagick::unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

Sharpens an image. We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 and Imagick::UnsharpMaskImage() selects a suitable radius for you.

### Parameter-Liste

`radius`

`sigma`

`amount`

`threshold`

`channel`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 Imagick::unsharpMaskImage()

    <?php
    function unsharpMaskImage($imagePath, $radius, $sigma, $amount, $unsharpThreshold) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->unsharpMaskImage($radius, $sigma, $amount, $unsharpThreshold);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::valid

(PECL imagick 2, PECL imagick 3)

Imagick::valid — Checks if the current item is valid

### Beschreibung

public function Imagick::valid(): bool

Checks if the current item is valid.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::vignetteImage

(PECL imagick 2, PECL imagick 3)

Imagick::vignetteImage — Adds vignette filter to the image

### Beschreibung

public function Imagick::vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool

Softens the edges of the image in vignette style. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`blackPoint`

  The black point.

`whitePoint`

  The white point

`x`

  X offset of the ellipse

`y`

  Y offset of the ellipse

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Imagick::vignetteImage()

    <?php
    function vignetteImage($imagePath, $blackPoint, $whitePoint, $x, $y) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->vignetteImage($blackPoint, $whitePoint, $x, $y);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Siehe auch

- Imagick::waveImage() - Applies wave filter to the image
- Imagick::swirlImage() - Swirls the pixels about the center of the image

# Imagick::waveImage

(PECL imagick 2, PECL imagick 3)

Imagick::waveImage — Applies wave filter to the image

### Beschreibung

public function Imagick::waveImage(float `$amplitude`, float `$length`): bool

Applies a wave filter to the image. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.2.9 oder höher kompiliert wurde.

### Parameter-Liste

`amplitude`

  The amplitude of the wave.

`length`

  The length of the wave.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Fehler/Exceptions

Wirft ImagickException bei Fehlern.

### Beispiele

Beispiel #1 WaveImage can be quite slow Imagick::waveImage()

    <?php
    function waveImage($imagePath, $amplitude, $length) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->waveImage($amplitude, $length);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

### Siehe auch

- Imagick::solarizeImage() - Applies a solarizing effect to the image
- Imagick::oilpaintImage() - Simulates an oil painting
- Imagick::embossImage() - Returns a grayscale image with a three-dimensional effect
- Imagick::addNoiseImage() - Adds random noise to the image
- Imagick::swirlImage() - Swirls the pixels about the center of the image

# Imagick::whiteThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::whiteThresholdImage — Force all pixels above the threshold into white

### Beschreibung

public function Imagick::whiteThresholdImage(mixed `$threshold`): bool

Is like Imagick::ThresholdImage() but force all pixels above the threshold into white while leaving all pixels below the threshold unchanged.

### Parameter-Liste

`threshold`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Changelog

Version | Beschreibung
--- | ---
PECL imagick 2.1.0 | Now allows a string representing the color as a parameter. Previous versions allow only an ImagickPixel object.

### Beispiele

Beispiel #1 Imagick::whiteThresholdImage()

    <?php
    function whiteThresholdImage($imagePath, $color) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->whiteThresholdImage($color);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::writeImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImage — Writes an image to the specified filename

### Beschreibung

public function Imagick::writeImage(string `$filename` = NULL): bool

Writes an image to the specified filename. If the filename parameter is NULL, the image is written to the filename set by Imagick::readImage() or Imagick::setImageFilename().

### Parameter-Liste

`filename`

  Filename where to write the image. The extension of the filename defines the type of the file. Format can be forced regardless of file extension using format: prefix, for example "jpg:test.png".

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::writeImageFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImageFile — Writes an image to a filehandle

### Beschreibung

public function Imagick::writeImageFile(resource `$filehandle`, string `$format` = ?): bool

Writes the image sequence to an open filehandle. The handle must be opened with for example fopen. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`filehandle`

  Filehandle where to write the image.

`format`

  The image format. The list of valid format specifiers depends on the compiled feature set of ImageMagick, and can be queried at runtime via Imagick::queryFormats().

### Rückgabewerte

Liefert `true` bei Erfolg.

### Siehe auch

- Imagick::queryFormats() - Returns formats supported by Imagick

# Imagick::writeImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImages — Writes an image or image sequence

### Beschreibung

public function Imagick::writeImages(string `$filename`, bool `$adjoin`): bool

Writes an image or image sequence.

### Parameter-Liste

`filename`

`adjoin`

### Rückgabewerte

Liefert `true` bei Erfolg.

# Imagick::writeImagesFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImagesFile — Writes frames to a filehandle

### Beschreibung

public function Imagick::writeImagesFile(resource `$filehandle`, string `$format` = ?): bool

Writes all image frames into an open filehandle. This method can be used to write animated gifs or other multiframe images into open filehandle. Diese Funktion ist verfügbar, wenn Imagick gegen die ImageMagick-Version 6.3.6 oder höher kompiliert wurde.

### Parameter-Liste

`filehandle`

  Filehandle where to write the images.

`format`

  The image format. The list of valid format specifiers depends on the compiled feature set of ImageMagick, and can be queried at runtime via Imagick::queryFormats().

### Rückgabewerte

Liefert `true` bei Erfolg.

### Siehe auch

- Imagick::queryFormats() - Returns formats supported by Imagick

## Inhaltsverzeichnis

- Imagick::adaptiveBlurImage — Adds adaptive blur filter to image
- Imagick::adaptiveResizeImage — Adaptively resize image with data dependent triangulation
- Imagick::adaptiveSharpenImage — Adaptively sharpen the image
- Imagick::adaptiveThresholdImage — Selects a threshold for each pixel based on a range of intensity
- Imagick::addImage — Adds new image to Imagick object image list
- Imagick::addNoiseImage — Adds random noise to the image
- Imagick::affineTransformImage — Transforms an image
- Imagick::animateImages — Animates an image or images
- Imagick::annotateImage — Annotates an image with text
- Imagick::appendImages — Append a set of images
- Imagick::autoLevelImage — Adjusts the levels of a particular image channel
- Imagick::averageImages — Average a set of images
- Imagick::blackThresholdImage — Forces all pixels below the threshold into black
- Imagick::blueShiftImage — Mutes the colors of the image
- Imagick::blurImage — Adds blur filter to image
- Imagick::borderImage — Surrounds the image with a border
- Imagick::brightnessContrastImage — Change the brightness and/or contrast of an image
- Imagick::charcoalImage — Simulates a charcoal drawing
- Imagick::chopImage — Removes a region of an image and trims
- Imagick::clampImage — Restricts the color range from 0 to the quantum depth.
- Imagick::clear — Clears all resources associated to Imagick object
- Imagick::clipImage — Clips along the first path from the 8BIM profile
- Imagick::clipImagePath — Clips along the named paths from the 8BIM profile, if present
- Imagick::clipPathImage — Clips along the named paths from the 8BIM profile
- Imagick::clone — Makes an exact copy of the Imagick object
- Imagick::clutImage — Replaces colors in the image
- Imagick::coalesceImages — Composites a set of images
- Imagick::colorFloodfillImage — Changes the color value of any pixel that matches target
- Imagick::colorizeImage — Blends the fill color with the image
- Imagick::colorMatrixImage — Apply color transformation to an image
- Imagick::combineImages — Combines one or more images into a single image
- Imagick::commentImage — Adds a comment to your image
- Imagick::compareImageChannels — Returns the difference in one or more images
- Imagick::compareImageLayers — Returns the maximum bounding region between images
- Imagick::compareImages — Compares an image to a reconstructed image
- Imagick::compositeImage — Composite one image onto another
- Imagick::__construct — The Imagick constructor
- Imagick::contrastImage — Change the contrast of the image
- Imagick::contrastStretchImage — Enhances the contrast of a color image
- Imagick::convolveImage — Applies a custom convolution kernel to the image
- Imagick::count — Get the number of images
- Imagick::cropImage — Extracts a region of the image
- Imagick::cropThumbnailImage — Creates a crop thumbnail
- Imagick::current — Returns a reference to the current Imagick object
- Imagick::cycleColormapImage — Displaces an image's colormap
- Imagick::decipherImage — Deciphers an image
- Imagick::deconstructImages — Returns certain pixel differences between images
- Imagick::deleteImageArtifact — Delete image artifact
- Imagick::deleteImageProperty — Deletes an image property
- Imagick::deskewImage — Removes skew from the image
- Imagick::despeckleImage — Reduces the speckle noise in an image
- Imagick::destroy — Destroys the Imagick object
- Imagick::displayImage — Displays an image
- Imagick::displayImages — Displays an image or image sequence
- Imagick::distortImage — Distorts an image using various distortion methods
- Imagick::drawImage — Renders the ImagickDraw object on the current image
- Imagick::edgeImage — Enhance edges within the image
- Imagick::embossImage — Returns a grayscale image with a three-dimensional effect
- Imagick::encipherImage — Enciphers an image
- Imagick::enhanceImage — Improves the quality of a noisy image
- Imagick::equalizeImage — Equalizes the image histogram
- Imagick::evaluateImage — Applies an expression to an image
- Imagick::exportImagePixels — Exports raw image pixels
- Imagick::extentImage — Set image size
- Imagick::filter — Applies a custom convolution kernel to the image
- Imagick::flattenImages — Merges a sequence of images
- Imagick::flipImage — Creates a vertical mirror image
- Imagick::floodFillPaintImage — Changes the color value of any pixel that matches target
- Imagick::flopImage — Creates a horizontal mirror image
- Imagick::forwardFourierTransformImage — Implements the discrete Fourier transform (DFT)
- Imagick::frameImage — Adds a simulated three-dimensional border
- Imagick::functionImage — Applies a function on the image
- Imagick::fxImage — Evaluate expression for each pixel in the image
- Imagick::gammaImage — Gamma-corrects an image
- Imagick::gaussianBlurImage — Blurs an image
- Imagick::getColorspace — Gets the colorspace
- Imagick::getCompression — Gets the object compression type
- Imagick::getCompressionQuality — Gets the object compression quality
- Imagick::getCopyright — Returns the ImageMagick API copyright as a string
- Imagick::getFilename — The filename associated with an image sequence
- Imagick::getFont — Gets font
- Imagick::getFormat — Returns the format of the Imagick object
- Imagick::getGravity — Gets the gravity
- Imagick::getHomeURL — Returns the ImageMagick home URL
- Imagick::getImage — Returns a new Imagick object
- Imagick::getImageAlphaChannel — Checks if the image has an alpha channel
- Imagick::getImageArtifact — Get image artifact
- Imagick::getImageAttribute — Returns a named attribute
- Imagick::getImageBackgroundColor — Returns the image background color
- Imagick::getImageBlob — Returns the image sequence as a blob
- Imagick::getImageBluePrimary — Returns the chromaticy blue primary point
- Imagick::getImageBorderColor — Returns the image border color
- Imagick::getImageChannelDepth — Gets the depth for a particular image channel
- Imagick::getImageChannelDistortion — Compares image channels of an image to a reconstructed image
- Imagick::getImageChannelDistortions — Gets channel distortions
- Imagick::getImageChannelExtrema — Gets the extrema for one or more image channels
- Imagick::getImageChannelKurtosis — The getImageChannelKurtosis purpose
- Imagick::getImageChannelMean — Gets the mean and standard deviation
- Imagick::getImageChannelRange — Gets channel range
- Imagick::getImageChannelStatistics — Returns statistics for each channel in the image
- Imagick::getImageClipMask — Gets image clip mask
- Imagick::getImageColormapColor — Returns the color of the specified colormap index
- Imagick::getImageColors — Gets the number of unique colors in the image
- Imagick::getImageColorspace — Gets the image colorspace
- Imagick::getImageCompose — Returns the composite operator associated with the image
- Imagick::getImageCompression — Gets the current image's compression type
- Imagick::getImageCompressionQuality — Gets the current image's compression quality
- Imagick::getImageDelay — Gets the image delay
- Imagick::getImageDepth — Gets the image depth
- Imagick::getImageDispose — Gets the image disposal method
- Imagick::getImageDistortion — Compares an image to a reconstructed image
- Imagick::getImageExtrema — Gets the extrema for the image
- Imagick::getImageFilename — Returns the filename of a particular image in a sequence
- Imagick::getImageFormat — Returns the format of a particular image in a sequence
- Imagick::getImageGamma — Gets the image gamma
- Imagick::getImageGeometry — Gets the width and height as an associative array
- Imagick::getImageGravity — Gets the image gravity
- Imagick::getImageGreenPrimary — Returns the chromaticy green primary point
- Imagick::getImageHeight — Returns the image height
- Imagick::getImageHistogram — Gets the image histogram
- Imagick::getImageIndex — Gets the index of the current active image
- Imagick::getImageInterlaceScheme — Gets the image interlace scheme
- Imagick::getImageInterpolateMethod — Returns the interpolation method
- Imagick::getImageIterations — Gets the image iterations
- Imagick::getImageLength — Returns the image length in bytes
- Imagick::getImageMatte — Return if the image has a matte channel
- Imagick::getImageMatteColor — Returns the image matte color
- Imagick::getImageMimeType — Returns the image mime-type
- Imagick::getImageOrientation — Gets the image orientation
- Imagick::getImagePage — Returns the page geometry
- Imagick::getImagePixelColor — Returns the color of the specified pixel
- Imagick::getImageProfile — Returns the named image profile
- Imagick::getImageProfiles — Returns the image profiles
- Imagick::getImageProperties — Returns the image properties
- Imagick::getImageProperty — Returns the named image property
- Imagick::getImageRedPrimary — Returns the chromaticity red primary point
- Imagick::getImageRegion — Extracts a region of the image
- Imagick::getImageRenderingIntent — Gets the image rendering intent
- Imagick::getImageResolution — Gets the image X and Y resolution
- Imagick::getImagesBlob — Returns all image sequences as a blob
- Imagick::getImageScene — Gets the image scene
- Imagick::getImageSignature — Generates an SHA-256 message digest
- Imagick::getImageSize — Returns the image length in bytes
- Imagick::getImageTicksPerSecond — Gets the image ticks-per-second
- Imagick::getImageTotalInkDensity — Gets the image total ink density
- Imagick::getImageType — Gets the potential image type
- Imagick::getImageUnits — Gets the image units of resolution
- Imagick::getImageVirtualPixelMethod — Returns the virtual pixel method
- Imagick::getImageWhitePoint — Returns the chromaticity white point
- Imagick::getImageWidth — Returns the image width
- Imagick::getInterlaceScheme — Gets the object interlace scheme
- Imagick::getIteratorIndex — Gets the index of the current active image
- Imagick::getNumberImages — Returns the number of images in the object
- Imagick::getOption — Returns a value associated with the specified key
- Imagick::getPackageName — Returns the ImageMagick package name
- Imagick::getPage — Returns the page geometry
- Imagick::getPixelIterator — Returns a MagickPixelIterator
- Imagick::getPixelRegionIterator — Get an ImagickPixelIterator for an image section
- Imagick::getPointSize — Gets point size
- Imagick::getQuantum — Returns the ImageMagick quantum range
- Imagick::getQuantumDepth — Gets the quantum depth
- Imagick::getQuantumRange — Returns the Imagick quantum range
- Imagick::getRegistry — Get a StringRegistry entry
- Imagick::getReleaseDate — Returns the ImageMagick release date
- Imagick::getResource — Returns the specified resource's memory usage
- Imagick::getResourceLimit — Returns the specified resource limit
- Imagick::getSamplingFactors — Gets the horizontal and vertical sampling factor
- Imagick::getSize — Returns the size associated with the Imagick object
- Imagick::getSizeOffset — Returns the size offset
- Imagick::getVersion — Returns the ImageMagick API version
- Imagick::haldClutImage — Replaces colors in the image
- Imagick::hasNextImage — Checks if the object has more images
- Imagick::hasPreviousImage — Checks if the object has a previous image
- Imagick::identifyFormat — Formats a string with image details
- Imagick::identifyImage — Identifies an image and fetches attributes
- Imagick::implodeImage — Creates a new image as a copy
- Imagick::importImagePixels — Imports image pixels
- Imagick::inverseFourierTransformImage — Implements the inverse discrete Fourier transform (DFT)
- Imagick::labelImage — Adds a label to an image
- Imagick::levelImage — Adjusts the levels of an image
- Imagick::linearStretchImage — Stretches with saturation the image intensity
- Imagick::liquidRescaleImage — Animates an image or images
- Imagick::listRegistry — List all the registry settings
- Imagick::magnifyImage — Scales an image proportionally 2x
- Imagick::mapImage — Replaces the colors of an image with the closest color from a reference image
- Imagick::matteFloodfillImage — Changes the transparency value of a color
- Imagick::medianFilterImage — Applies a digital filter
- Imagick::mergeImageLayers — Merges image layers
- Imagick::minifyImage — Scales an image proportionally to half its size
- Imagick::modulateImage — Control the brightness, saturation, and hue
- Imagick::montageImage — Creates a composite image
- Imagick::morphImages — Method morphs a set of images
- Imagick::morphology — Applies a user supplied kernel to the image according to the given morphology method.
- Imagick::mosaicImages — Forms a mosaic from images
- Imagick::motionBlurImage — Simulates motion blur
- Imagick::negateImage — Negates the colors in the reference image
- Imagick::newImage — Creates a new image
- Imagick::newPseudoImage — Creates a new image
- Imagick::nextImage — Moves to the next image
- Imagick::normalizeImage — Enhances the contrast of a color image
- Imagick::oilPaintImage — Simulates an oil painting
- Imagick::opaquePaintImage — Changes the color value of any pixel that matches target
- Imagick::optimizeImageLayers — Removes repeated portions of images to optimize
- Imagick::orderedPosterizeImage — Performs an ordered dither
- Imagick::paintFloodfillImage — Changes the color value of any pixel that matches target
- Imagick::paintOpaqueImage — Change any pixel that matches color
- Imagick::paintTransparentImage — Changes any pixel that matches color with the color defined by fill
- Imagick::pingImage — Ruft grundlegende Merkmale eines Bildes ab
- Imagick::pingImageBlob — Quickly fetch attributes
- Imagick::pingImageFile — Get basic image attributes in a lightweight manner
- Imagick::polaroidImage — Simulates a Polaroid picture
- Imagick::posterizeImage — Reduces the image to a limited number of color level
- Imagick::previewImages — Quickly pin-point appropriate parameters for image processing
- Imagick::previousImage — Move to the previous image in the object
- Imagick::profileImage — Adds or removes a profile from an image
- Imagick::quantizeImage — Analyzes the colors within a reference image
- Imagick::quantizeImages — Analyzes the colors within a sequence of images
- Imagick::queryFontMetrics — Returns an array representing the font metrics
- Imagick::queryFonts — Returns the configured fonts
- Imagick::queryFormats — Returns formats supported by Imagick
- Imagick::radialBlurImage — Radial blurs an image
- Imagick::raiseImage — Creates a simulated 3d button-like effect
- Imagick::randomThresholdImage — Creates a high-contrast, two-color image
- Imagick::readImage — Reads image from filename
- Imagick::readImageBlob — Reads image from a binary string
- Imagick::readImageFile — Reads image from open filehandle
- Imagick::readimages — Reads image from an array of filenames
- Imagick::recolorImage — Recolors image
- Imagick::reduceNoiseImage — Smooths the contours of an image
- Imagick::remapImage — Remaps image colors
- Imagick::removeImage — Removes an image from the image list
- Imagick::removeImageProfile — Removes the named image profile and returns it
- Imagick::render — Renders all preceding drawing commands
- Imagick::resampleImage — Resample image to desired resolution
- Imagick::resetImagePage — Reset image page
- Imagick::resizeImage — Scales an image
- Imagick::rollImage — Offsets an image
- Imagick::rotateImage — Rotates an image
- Imagick::rotationalBlurImage — Rotational blurs an image
- Imagick::roundCorners — Rounds image corners
- Imagick::sampleImage — Scales an image with pixel sampling
- Imagick::scaleImage — Scales the size of an image
- Imagick::segmentImage — Segments an image
- Imagick::selectiveBlurImage — Selectively blur an image within a contrast threshold
- Imagick::separateImageChannel — Separates a channel from the image
- Imagick::sepiaToneImage — Sepia tones an image
- Imagick::setBackgroundColor — Sets the object's default background color
- Imagick::setColorspace — Set colorspace
- Imagick::setCompression — Sets the object's default compression type
- Imagick::setCompressionQuality — Sets the object's default compression quality
- Imagick::setFilename — Sets the filename before you read or write the image
- Imagick::setFirstIterator — Sets the Imagick iterator to the first image
- Imagick::setFont — Sets font
- Imagick::setFormat — Sets the format of the Imagick object
- Imagick::setGravity — Sets the gravity
- Imagick::setImage — Replaces image in the object
- Imagick::setImageAlphaChannel — Sets image alpha channel
- Imagick::setImageArtifact — Set image artifact
- Imagick::setImageAttribute — Sets an image attribute
- Imagick::setImageBackgroundColor — Sets the image background color
- Imagick::setImageBias — Sets the image bias for any method that convolves an image
- Imagick::setImageBiasQuantum — Sets the image bias
- Imagick::setImageBluePrimary — Sets the image chromaticity blue primary point
- Imagick::setImageBorderColor — Sets the image border color
- Imagick::setImageChannelDepth — Sets the depth of a particular image channel
- Imagick::setImageClipMask — Sets image clip mask
- Imagick::setImageColormapColor — Sets the color of the specified colormap index
- Imagick::setImageColorspace — Sets the image colorspace
- Imagick::setImageCompose — Sets the image composite operator
- Imagick::setImageCompression — Sets the image compression
- Imagick::setImageCompressionQuality — Sets the image compression quality
- Imagick::setImageDelay — Sets the image delay
- Imagick::setImageDepth — Sets the image depth
- Imagick::setImageDispose — Sets the image disposal method
- Imagick::setImageExtent — Sets the image size
- Imagick::setImageFilename — Sets the filename of a particular image
- Imagick::setImageFormat — Sets the format of a particular image
- Imagick::setImageGamma — Sets the image gamma
- Imagick::setImageGravity — Sets the image gravity
- Imagick::setImageGreenPrimary — Sets the image chromaticity green primary point
- Imagick::setImageIndex — Set the iterator position
- Imagick::setImageInterlaceScheme — Sets the image compression
- Imagick::setImageInterpolateMethod — Sets the image interpolate pixel method
- Imagick::setImageIterations — Sets the image iterations
- Imagick::setImageMatte — Sets the image matte channel
- Imagick::setImageMatteColor — Sets the image matte color
- Imagick::setImageOpacity — Sets the image opacity level
- Imagick::setImageOrientation — Sets the image orientation
- Imagick::setImagePage — Sets the page geometry of the image
- Imagick::setImageProfile — Adds a named profile to the Imagick object
- Imagick::setImageProperty — Sets an image property
- Imagick::setImageRedPrimary — Sets the image chromaticity red primary point
- Imagick::setImageRenderingIntent — Sets the image rendering intent
- Imagick::setImageResolution — Sets the image resolution
- Imagick::setImageScene — Sets the image scene
- Imagick::setImageTicksPerSecond — Sets the image ticks-per-second
- Imagick::setImageType — Sets the image type
- Imagick::setImageUnits — Sets the image units of resolution
- Imagick::setImageVirtualPixelMethod — Sets the image virtual pixel method
- Imagick::setImageWhitePoint — Sets the image chromaticity white point
- Imagick::setInterlaceScheme — Sets the image compression
- Imagick::setIteratorIndex — Set the iterator position
- Imagick::setLastIterator — Sets the Imagick iterator to the last image
- Imagick::setOption — Set an option
- Imagick::setPage — Sets the page geometry of the Imagick object
- Imagick::setPointSize — Sets point size
- Imagick::setProgressMonitor — Set a callback to be called during processing
- Imagick::setRegistry — Sets the ImageMagick registry entry named key to value
- Imagick::setResolution — Sets the image resolution
- Imagick::setResourceLimit — Sets the limit for a particular resource
- Imagick::setSamplingFactors — Sets the image sampling factors
- Imagick::setSize — Sets the size of the Imagick object
- Imagick::setSizeOffset — Sets the size and offset of the Imagick object
- Imagick::setType — Sets the image type attribute
- Imagick::shadeImage — Creates a 3D effect
- Imagick::shadowImage — Simulates an image shadow
- Imagick::sharpenImage — Sharpens an image
- Imagick::shaveImage — Shaves pixels from the image edges
- Imagick::shearImage — Creating a parallelogram
- Imagick::sigmoidalContrastImage — Adjusts the contrast of an image
- Imagick::sketchImage — Simulates a pencil sketch
- Imagick::smushImages — Takes all images from the current image pointer to the end of the image list and smushs them
- Imagick::solarizeImage — Applies a solarizing effect to the image
- Imagick::sparseColorImage — Interpolates colors
- Imagick::spliceImage — Splices a solid color into the image
- Imagick::spreadImage — Randomly displaces each pixel in a block
- Imagick::statisticImage — Modifies image using a statistics function
- Imagick::steganoImage — Hides a digital watermark within the image
- Imagick::stereoImage — Composites two images
- Imagick::stripImage — Strips an image of all profiles and comments
- Imagick::subImageMatch — Searches for a subimage in the current image and returns a similarity image
- Imagick::swirlImage — Swirls the pixels about the center of the image
- Imagick::textureImage — Repeatedly tiles the texture image
- Imagick::thresholdImage — Changes the value of individual pixels based on a threshold
- Imagick::thumbnailImage — Changes the size of an image
- Imagick::tintImage — Applies a color vector to each pixel in the image
- Imagick::__toString — Returns the image as a string
- Imagick::transformImage — Convenience method for setting crop size and the image geometry
- Imagick::transformImageColorspace — Transforms an image to a new colorspace
- Imagick::transparentPaintImage — Paints pixels transparent
- Imagick::transposeImage — Creates a vertical mirror image
- Imagick::transverseImage — Creates a horizontal mirror image
- Imagick::trimImage — Remove edges from the image
- Imagick::uniqueImageColors — Discards all but one of any pixel color
- Imagick::unsharpMaskImage — Sharpens an image
- Imagick::valid — Checks if the current item is valid
- Imagick::vignetteImage — Adds vignette filter to the image
- Imagick::waveImage — Applies wave filter to the image
- Imagick::whiteThresholdImage — Force all pixels above the threshold into white
- Imagick::writeImage — Writes an image to the specified filename
- Imagick::writeImageFile — Writes an image to a filehandle
- Imagick::writeImages — Writes an image or image sequence
- Imagick::writeImagesFile — Writes frames to a filehandle

# Die Klasse ImagickDraw

(PECL imagick 2, PECL imagick 3)

## Klassenbeschreibung

class ImagickDraw {
public function affine(array `$affine`): bool
public function annotation(float `$x`, float `$y`, string `$text`): bool
public function arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
public function bezier(array `$coordinates`): bool
public function circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
public function clear(): bool
public function clone(): ImagickDraw
public function color(float `$x`, float `$y`, int `$paint`): bool
public function comment(string `$comment`): bool
public function composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
public function destroy(): bool
public function ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
public function getClipPath(): false|string
public function getClipRule(): int
public function getClipUnits(): int
public function getFillColor(): ImagickPixel
public function getFillOpacity(): float
public function getFillRule(): int
public function getFont(): string
public function getFontFamily(): string
public function getFontSize(): float
public function getFontStretch(): int
public function getFontStyle(): int
public function getFontWeight(): int
public function getGravity(): int
public function getStrokeAntialias(): bool
public function getStrokeColor(): ImagickPixel
public function getStrokeDashArray(): array
public function getStrokeDashOffset(): float
public function getStrokeLineCap(): int
public function getStrokeLineJoin(): int
public function getStrokeMiterLimit(): int
public function getStrokeOpacity(): float
public function getStrokeWidth(): float
public function getTextAlignment(): int
public function getTextAntialias(): bool
public function getTextDecoration(): int
public function getTextEncoding(): false|string
public function getTextInterlineSpacing(): float
public function getTextInterwordSpacing(): float
public function getTextKerning(): float
public function getTextUnderColor(): ImagickPixel
public function getVectorGraphics(): string
public function line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
public function matte(float `$x`, float `$y`, int `$paint`): bool
public function pathClose(): bool
public function pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierSmoothAbsolute(float `$x`, float `$y`): bool
public function pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
public function pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathFinish(): bool
public function pathLineToAbsolute(float `$x`, float `$y`): bool
public function pathLineToHorizontalAbsolute(float `$x`): bool
public function pathLineToHorizontalRelative(float `$x`): bool
public function pathLineToRelative(float `$x`, float `$y`): bool
public function pathLineToVerticalAbsolute(float `$y`): bool
public function pathLineToVerticalRelative(float `$y`): bool
public function pathMoveToAbsolute(float `$x`, float `$y`): bool
public function pathMoveToRelative(float `$x`, float `$y`): bool
public function pathStart(): bool
public function point(float `$x`, float `$y`): bool
public function polygon(array `$coordinates`): bool
public function polyline(array `$coordinates`): bool
public function pop(): bool
public function popClipPath(): bool
public function popDefs(): bool
public function popPattern(): bool
public function push(): bool
public function pushClipPath(string `$clip_mask_id`): bool
public function pushDefs(): bool
public function pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
public function rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
public function render(): bool
public function resetVectorGraphics(): bool
public function rotate(float `$degrees`): bool
public function roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
public function scale(float `$x`, float `$y`): bool
public function setClipPath(string `$clip_mask`): bool
public function setClipRule(int `$fillrule`): bool
public function setClipUnits(int `$pathunits`): bool
public function setFillAlpha(float `$alpha`): bool
public function setFillColor(ImagickPixel|string `$fill_color`): bool
public function setFillOpacity(float `$opacity`): bool
public function setFillPatternURL(string `$fill_url`): bool
public function setFillRule(int `$fillrule`): bool
public function setFont(string `$font_name`): bool
public function setFontFamily(string `$font_family`): bool
public function setFontSize(float `$point_size`): bool
public function setFontStretch(int `$stretch`): bool
public function setFontStyle(int `$style`): bool
public function setFontWeight(int `$weight`): bool
public function setGravity(int `$gravity`): bool
public function setResolution(float `$resolution_x`, float `$resolution_y`): bool
public function setStrokeAlpha(float `$alpha`): bool
public function setStrokeAntialias(bool `$enabled`): bool
public function setStrokeColor(ImagickPixel|string `$color`): bool
public function setStrokeDashArray(?array `$dashes`): bool
public function setStrokeDashOffset(float `$dash_offset`): bool
public function setStrokeLineCap(int `$linecap`): bool
public function setStrokeLineJoin(int `$linejoin`): bool
public function setStrokeMiterLimit(int `$miterlimit`): bool
public function setStrokeOpacity(float `$opacity`): bool
public function setStrokePatternURL(string `$stroke_url`): bool
public function setStrokeWidth(float `$width`): bool
public function setTextAlignment(int `$align`): bool
public function setTextAntialias(bool `$antialias`): bool
public function setTextDecoration(int `$decoration`): bool
public function setTextEncoding(string `$encoding`): bool
public function setTextInterlineSpacing(float `$spacing`): bool
public function setTextInterwordSpacing(float `$spacing`): bool
public function setTextKerning(float `$kerning`): bool
public function setTextUnderColor(ImagickPixel|string `$under_color`): bool
public function setVectorGraphics(string `$xml`): bool
public function setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
public function skewX(float `$degrees`): bool
public function skewY(float `$degrees`): bool
public function translate(float `$x`, float `$y`): bool
}

# ImagickDraw::affine

(PECL imagick 2, PECL imagick 3)

ImagickDraw::affine — Adjusts the current affine transformation matrix

### Beschreibung

public function ImagickDraw::affine(array `$affine`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Adjusts the current affine transformation matrix with the specified affine transformation matrix.

### Parameter-Liste

`affine`

  Affine matrix parameters

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::affine() example

    <?php
    function affine($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $PI = 3.141592653589794;
        $angle = 60 * $PI / 360;

        //Scale the drawing co-ordinates.
        $affineScale = array("sx" => 1.75, "sy" => 1.75, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

        //Shear the drawing co-ordinates.
        $affineShear = array("sx" => 1, "sy" => 1, "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0);

        //Rotate the drawing co-ordinates. The shear affine matrix
        //produces incorrectly scaled drawings.
        $affineRotate = array("sx" => cos($angle), "sy" => cos($angle), "rx" => sin($angle), "ry" => -sin($angle), "tx" => 0, "ty" => 0,);

        //Translate (offset) the drawing
        $affineTranslate = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 30, "ty" => 30);

        //The identity affine matrix
        $affineIdentity = array("sx" => 1, "sy" => 1, "rx" => 0, "ry" => 0, "tx" => 0, "ty" => 0);

        $examples = [$affineScale, $affineShear, $affineRotate, $affineTranslate, $affineIdentity,];

        $count = 0;

        foreach ($examples as $example) {
            $draw->push();
            $draw->translate(($count % 2) * 250, intval($count / 2) * 250);
            $draw->translate(100, 100);
            $draw->affine($example);
            $draw->rectangle(-50, -50, 50, 50);
            $draw->pop();
            $count++;
        }

        //Create an image object which the draw commands can be rendered into
        $image = new \Imagick();
        $image->newImage(500, 750, $backgroundColor);
        $image->setImageFormat("png");

        //Render the draw commands in the ImagickDraw object
        //into the image.
        $image->drawImage($draw);

        //Send the image to the browser
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::annotation

(PECL imagick 2, PECL imagick 3)

ImagickDraw::annotation — Draws text on the image

### Beschreibung

public function ImagickDraw::annotation(float `$x`, float `$y`, string `$text`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws text on the image.

### Parameter-Liste

`x`

  The x coordinate where text is drawn

`y`

  The y coordinate where text is drawn

`text`

  The text to draw on the image

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::arc

(PECL imagick 2, PECL imagick 3)

ImagickDraw::arc — Draws an arc

### Beschreibung

public function ImagickDraw::arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws an arc falling within a specified bounding rectangle on the image.

### Parameter-Liste

`start_x`

  Starting x ordinate of bounding rectangle

`start_y`

  starting y ordinate of bounding rectangle

`end_x`

  ending x ordinate of bounding rectangle

`end_y`

  ending y ordinate of bounding rectangle

`start_angle`

  starting degrees of rotation

`end_angle`

  ending degrees of rotation

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::arc() example

    <?php
    function arc($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $startAngle, $endAngle) {

        //Create a ImagickDraw object to draw into.
        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);

        $draw->arc($startX, $startY, $endX, $endY, $startAngle, $endAngle);

        //Create an image object which the draw commands can be rendered into
        $image = new \Imagick();
        $image->newImage(IMAGE_WIDTH, IMAGE_HEIGHT, $backgroundColor);
        $image->setImageFormat("png");

        //Render the draw commands in the ImagickDraw object
        //into the image.
        $image->drawImage($draw);

        //Send the image to the browser
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::bezier

(PECL imagick 2, PECL imagick 3)

ImagickDraw::bezier — Draws a bezier curve

### Beschreibung

public function ImagickDraw::bezier(array `$coordinates`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a bezier curve through a set of points on the image.

### Parameter-Liste

`coordinates`

  Multidimensional array like array( array( 'x' => 1, 'y' => 2 ), array( 'x' => 3, 'y' => 4 ) )

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::bezier() example

    <?php
    function bezier($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $smoothPointsSet = [
            [
                ['x' => 10.0 * 5, 'y' => 10.0 * 5],
                ['x' => 30.0 * 5, 'y' => 90.0 * 5],
                ['x' => 25.0 * 5, 'y' => 10.0 * 5],
                ['x' => 50.0 * 5, 'y' => 50.0 * 5],
            ],
            [
                ['x' => 50.0 * 5, 'y' => 50.0 * 5],
                ['x' => 75.0 * 5, 'y' => 90.0 * 5],
                ['x' => 70.0 * 5, 'y' => 10.0 * 5],
                ['x' => 90.0 * 5, 'y' => 40.0 * 5],
            ],
        ];

        foreach ($smoothPointsSet as $points) {
            $draw->bezier($points);
        }

        $disjointPoints = [
            [
                ['x' => 10 * 5, 'y' => 10 * 5],
                ['x' => 30 * 5, 'y' => 90 * 5],
                ['x' => 25 * 5, 'y' => 10 * 5],
                ['x' => 50 * 5, 'y' => 50 * 5],
            ],
            [
                ['x' => 50 * 5, 'y' => 50 * 5],
                ['x' => 80 * 5, 'y' => 50 * 5],
                ['x' => 70 * 5, 'y' => 10 * 5],
                ['x' => 90 * 5, 'y' => 40 * 5],
             ]
        ];
        $draw->translate(0, 200);

        foreach ($disjointPoints as $points) {
            $draw->bezier($points);
        }

        //Create an image object which the draw commands can be rendered into
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        //Render the draw commands in the ImagickDraw object
        //into the image.
        $imagick->drawImage($draw);

        //Send the image to the browser
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::circle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::circle — Draws a circle

### Beschreibung

public function ImagickDraw::circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a circle on the image.

### Parameter-Liste

`origin_x`

  origin x coordinate

`origin_y`

  origin y coordinate

`perimeter_x`

  perimeter x coordinate

`perimeter_y`

  perimeter y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::circle() example

    <?php
    function circle($strokeColor, $fillColor, $backgroundColor, $originX, $originY, $endX, $endY) {

        //Create a ImagickDraw object to draw into.
        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->circle($originX, $originY, $endX, $endY);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::clear

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clear — Clears the ImagickDraw

### Beschreibung

public function ImagickDraw::clear(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Clears the ImagickDraw object of any accumulated commands, and resets the settings it contains to their defaults.

### Rückgabewerte

Returns an ImagickDraw object.

# ImagickDraw::clone

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clone — Makes an exact copy of the specified ImagickDraw object

### Beschreibung

public function ImagickDraw::clone(): ImagickDraw
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Makes an exact copy of the specified ImagickDraw object.

### Rückgabewerte

returns an exact copy of the specified ImagickDraw object.

# ImagickDraw::color

(PECL imagick 2, PECL imagick 3)

ImagickDraw::color — Draws color on image

### Beschreibung

public function ImagickDraw::color(float `$x`, float `$y`, int `$paint`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws color on image using the current fill color, starting at specified position, and using specified paint method.

### Parameter-Liste

`x`

  x coordinate of the paint

`y`

  y coordinate of the paint

`paint`

  One of the PAINT constant (`imagick::PAINT_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::comment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::comment — Adds a comment

### Beschreibung

public function ImagickDraw::comment(string `$comment`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Adds a comment to a vector output stream.

### Parameter-Liste

`comment`

  The comment string to add to vector output stream

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::composite

(PECL imagick 2, PECL imagick 3)

ImagickDraw::composite — Composites an image onto the current image

### Beschreibung

public function ImagickDraw::composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Composites an image onto the current image, using the specified composition operator, specified position, and at the specified size.

### Parameter-Liste

`composite`

  composition operator. One of the Composite Operator constant (`imagick::COMPOSITE_*`).

`x`

  x coordinate of the top left corner.

`y`

  y coordinate of the top left corner.

`width`

  width of the composition image.

`height`

  height of the composition image.

`image`

  the Imagick object where composition image is taken from.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickDraw::composite() example

    <?php
    function composite($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setFillOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFont("../fonts/CANDY.TTF");
        $draw->setFontSize(140);
        $draw->rectangle(0, 0, 1000, 300);
        $draw->setFillColor('white');
        $draw->setfillopacity(1);
        $draw->annotation(50, 180, "Lorem Ipsum!");

        //Create an image object which the draw commands can be rendered into
        $imagick = new \Imagick();
        $imagick->newImage(1000, 302, $backgroundColor);
        $imagick->setImageFormat("png");

        //Render the draw commands in the ImagickDraw object
        //into the image.
        $imagick->drawImage($draw);

        //Send the image to the browser
        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::__construct

(PECL imagick 2, PECL imagick 3)

ImagickDraw::__construct — The ImagickDraw constructor

### Beschreibung

public function ImagickDraw::__construct()
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

The ImagickDraw constructor.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::destroy

(PECL imagick 2, PECL imagick 3)

ImagickDraw::destroy — Frees all associated resources

### Beschreibung

public function ImagickDraw::destroy(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Frees all resources associated with the ImagickDraw object.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::ellipse

(PECL imagick 2, PECL imagick 3)

ImagickDraw::ellipse — Draws an ellipse on the image

### Beschreibung

public function ImagickDraw::ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws an ellipse on the image.

### Parameter-Liste

`origin_x`

`origin_y`

`radius_x`

`radius_y`

`angle_start`

`angle_end`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::ellipse() example

    <?php
    function ellipse($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->ellipse(125, 70, 100, 50, 0, 360);
        $draw->ellipse(350, 70, 100, 50, 0, 315);

        $draw->push();
        $draw->translate(125, 250);
        $draw->rotate(30);
        $draw->ellipse(0, 0, 100, 50, 0, 360);
        $draw->pop();

        $draw->push();
        $draw->translate(350, 250);
        $draw->rotate(30);
        $draw->ellipse(0, 0, 100, 50, 0, 315);
        $draw->pop();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::getClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipPath — Obtains the current clipping path ID

### Beschreibung

public function ImagickDraw::getClipPath(): false|string
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Obtains the current clipping path ID.

### Rückgabewerte

Returns a string containing the clip path ID or false if no clip path exists.

# ImagickDraw::getClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipRule — Returns the current polygon fill rule

### Beschreibung

public function ImagickDraw::getClipRule(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the current polygon fill rule to be used by the clipping path.

### Rückgabewerte

Returns a FILLRULE constant (`imagick::FILLRULE_*`).

# ImagickDraw::getClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipUnits — Returns the interpretation of clip path units

### Beschreibung

public function ImagickDraw::getClipUnits(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the interpretation of clip path units.

### Rückgabewerte

Returns an Integer on success.

# ImagickDraw::getFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillColor — Returns the fill color

### Beschreibung

public function ImagickDraw::getFillColor(): ImagickPixel
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the fill color used for drawing filled objects.

### Rückgabewerte

Returns an ImagickPixel object.

# ImagickDraw::getFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillOpacity — Returns the opacity used when drawing

### Beschreibung

public function ImagickDraw::getFillOpacity(): float
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the opacity used when drawing using the fill color or fill texture. Fully opaque is 1.0.

### Rückgabewerte

The opacity.

# ImagickDraw::getFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillRule — Returns the fill rule

### Beschreibung

public function ImagickDraw::getFillRule(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the fill rule used while drawing polygons.

### Rückgabewerte

Returns a FILLRULE constant (`imagick::FILLRULE_*`).

# ImagickDraw::getFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFont — Returns the font

### Beschreibung

public function ImagickDraw::getFont(): string
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns a string specifying the font used when annotating with text.

### Rückgabewerte

Returns a string on success and false if no font is set.

# ImagickDraw::getFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontFamily — Returns the font family

### Beschreibung

public function ImagickDraw::getFontFamily(): string
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the font family to use when annotating with text.

### Rückgabewerte

Returns the font family currently selected or false if font family is not set.

# ImagickDraw::getFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontSize — Returns the font pointsize

### Beschreibung

public function ImagickDraw::getFontSize(): float
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the font pointsize used when annotating with text.

### Rückgabewerte

Returns the font size associated with the current ImagickDraw object.

# ImagickDraw::getFontStretch

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickDraw::getFontStretch — Gets the font stretch to use when annotating with text

### Beschreibung

public function ImagickDraw::getFontStretch(): int

Gets the font stretch to use when annotating with text. Returns a StretchType.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# ImagickDraw::getFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontStyle — Returns the font style

### Beschreibung

public function ImagickDraw::getFontStyle(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the font style used when annotating with text.

### Rückgabewerte

Returns a STYLE constant (`imagick::STYLE_*`) associated with the ImagickDraw object or 0 if no style is set.

# ImagickDraw::getFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontWeight — Returns the font weight

### Beschreibung

public function ImagickDraw::getFontWeight(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the font weight used when annotating with text.

### Rückgabewerte

Returns an Integer on success and 0 if no weight is set.

# ImagickDraw::getGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getGravity — Returns the text placement gravity

### Beschreibung

public function ImagickDraw::getGravity(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the text placement gravity used when annotating with text.

### Rückgabewerte

Returns a GRAVITY constant (`imagick::GRAVITY_*`) on success and 0 if no gravity is set.

# ImagickDraw::getStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeAntialias — Returns the current stroke antialias setting

### Beschreibung

public function ImagickDraw::getStrokeAntialias(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the current stroke antialias setting. Stroked outlines are antialiased by default. When antialiasing is disabled stroked pixels are thresholded to determine if the stroke color or underlying canvas color should be used.

### Rückgabewerte

Returns `true` if antialiasing is on and `false` if it is off.

# ImagickDraw::getStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeColor — Returns the color used for stroking object outlines

### Beschreibung

public function ImagickDraw::getStrokeColor(): ImagickPixel
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the color used for stroking object outlines.

### Parameter-Liste

`stroke_color`

### Rückgabewerte

Returns an ImagickPixel object which describes the color.

# ImagickDraw::getStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashArray — Returns an array representing the pattern of dashes and gaps used to stroke paths

### Beschreibung

public function ImagickDraw::getStrokeDashArray(): array
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns an array representing the pattern of dashes and gaps used to stroke paths.

### Rückgabewerte

Returns an array on success and empty array if not set.

# ImagickDraw::getStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashOffset — Returns the offset into the dash pattern to start the dash

### Beschreibung

public function ImagickDraw::getStrokeDashOffset(): float
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the offset into the dash pattern to start the dash.

### Rückgabewerte

Returns a float representing the offset and 0 if it's not set.

# ImagickDraw::getStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineCap — Returns the shape to be used at the end of open subpaths when they are stroked

### Beschreibung

public function ImagickDraw::getStrokeLineCap(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the shape to be used at the end of open subpaths when they are stroked.

### Rückgabewerte

Returns a LINECAP constant (`imagick::LINECAP_*`), or 0 if stroke linecap is not set.

# ImagickDraw::getStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineJoin — Returns the shape to be used at the corners of paths when they are stroked

### Beschreibung

public function ImagickDraw::getStrokeLineJoin(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the shape to be used at the corners of paths (or other vector shapes) when they are stroked.

### Rückgabewerte

Returns a LINEJOIN constant (`imagick::LINEJOIN_*`), or 0 if stroke line join is not set.

# ImagickDraw::getStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeMiterLimit — Returns the stroke miter limit

### Beschreibung

public function ImagickDraw::getStrokeMiterLimit(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the miter limit. When two line segments meet at a sharp angle and miter joins have been specified for 'lineJoin', it is possible for the miter to extend far beyond the thickness of the line stroking the path. The 'miterLimit' imposes a limit on the ratio of the miter length to the 'lineWidth'.

### Rückgabewerte

Returns an int describing the miter limit and 0 if no miter limit is set.

# ImagickDraw::getStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeOpacity — Returns the opacity of stroked object outlines

### Beschreibung

public function ImagickDraw::getStrokeOpacity(): float
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the opacity of stroked object outlines.

### Rückgabewerte

Returns a float describing the opacity.

# ImagickDraw::getStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeWidth — Returns the width of the stroke used to draw object outlines

### Beschreibung

public function ImagickDraw::getStrokeWidth(): float
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the width of the stroke used to draw object outlines.

### Rückgabewerte

Returns a float describing the stroke width.

# ImagickDraw::getTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAlignment — Returns the text alignment

### Beschreibung

public function ImagickDraw::getTextAlignment(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the alignment applied when annotating with text.

### Rückgabewerte

Returns a ALIGN constant (`imagick::ALIGN_*`), and 0 if no align is set.

# ImagickDraw::getTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAntialias — Returns the current text antialias setting

### Beschreibung

public function ImagickDraw::getTextAntialias(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the current text antialias setting, which determines whether text is antialiased. Text is antialiased by default.

### Rückgabewerte

Returns `true` if text is antialiased and `false` if not.

# ImagickDraw::getTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextDecoration — Returns the text decoration

### Beschreibung

public function ImagickDraw::getTextDecoration(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the decoration applied when annotating with text.

### Rückgabewerte

Returns a DECORATION constant (`imagick::DECORATION_*`), and 0 if no decoration is set.

# ImagickDraw::getTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextEncoding — Returns the code set used for text annotations

### Beschreibung

public function ImagickDraw::getTextEncoding(): false|string
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns a string which specifies the code set used for text annotations.

### Rückgabewerte

Returns a string specifying the code set or false if text encoding is not set.

# ImagickDraw::getTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterlineSpacing — Gets the text interline spacing

### Beschreibung

public function ImagickDraw::getTextInterlineSpacing(): float

Gets the text interline spacing.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# ImagickDraw::getTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterwordSpacing — Gets the text interword spacing

### Beschreibung

public function ImagickDraw::getTextInterwordSpacing(): float

Gets the text interword spacing.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# ImagickDraw::getTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextKerning — Gets the text kerning

### Beschreibung

public function ImagickDraw::getTextKerning(): float

Gets the text kerning.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# ImagickDraw::getTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextUnderColor — Returns the text under color

### Beschreibung

public function ImagickDraw::getTextUnderColor(): ImagickPixel
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the color of a background rectangle to place under text annotations.

### Rückgabewerte

Returns an ImagickPixel object describing the color.

# ImagickDraw::getVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getVectorGraphics — Returns a string containing vector graphics

### Beschreibung

public function ImagickDraw::getVectorGraphics(): string
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns a string which specifies the vector graphics generated by any graphics calls made since the ImagickDraw object was instantiated.

### Rückgabewerte

Returns a string containing the vector graphics.

# ImagickDraw::line

(PECL imagick 2, PECL imagick 3)

ImagickDraw::line — Draws a line

### Beschreibung

public function ImagickDraw::line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a line on the image using the current stroke color, stroke opacity, and stroke width.

### Parameter-Liste

`start_x`

  starting x coordinate

`start_y`

  starting y coordinate

`end_x`

  ending x coordinate

`end_y`

  ending y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::line() example

    <?php
    function line($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->line(125, 70, 100, 50);
        $draw->line(350, 170, 100, 150);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::matte

(PECL imagick 2, PECL imagick 3)

ImagickDraw::matte — Paints on the image's opacity channel

### Beschreibung

public function ImagickDraw::matte(float `$x`, float `$y`, int `$paint`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Paints on the image's opacity channel in order to set effected pixels to transparent, to influence the opacity of pixels.

### Parameter-Liste

`x`

  x coordinate of the matte

`y`

  y coordinate of the matte

`paint`

  One of the PAINT constant (`imagick::PAINT_*`).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::matte() example

    <?php
    function matte($strokeColor, $fillColor, $backgroundColor, $paintType) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->matte(120, 120, $paintType);
        $draw->rectangle(100, 100, 300, 200);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::pathClose

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathClose — Adds a path element to the current path

### Beschreibung

public function ImagickDraw::pathClose(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Adds a path element to the current path which closes the current subpath by drawing a straight line from the current point to the current subpath's most recent starting point (usually, the most recent moveto point).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathCurveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToAbsolute — Draws a cubic Bezier curve

### Beschreibung

public function ImagickDraw::pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a cubic Bezier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve using absolute coordinates. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybezier.

### Parameter-Liste

`x1`

  x coordinate of the first control point

`y1`

  y coordinate of the first control point

`x2`

  x coordinate of the second control point

`y2`

  y coordinate of the first control point

`x`

  x coordinate of the curve end

`y`

  y coordinate of the curve end

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathCurveToQuadraticBezierAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierAbsolute — Draws a quadratic Bezier curve

### Beschreibung

public function ImagickDraw::pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a quadratic Bezier curve from the current point to (x,y) using (x1,y1) as the control point using absolute coordinates. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybezier.

### Parameter-Liste

`x1`

  x coordinate of the control point

`y1`

  y coordinate of the control point

`x_end`

  x coordinate of the end point

`y`

  y coordinate of the end point

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::pathCurveToQuadraticBezierAbsolute() example

    <?php
    function pathCurveToQuadraticBezierAbsolute($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50,250);

        // This specifies a quadratic bezier curve with the current position as the start
        // point, the control point is the first two params, and the end point is the last two params.
        $draw->pathCurveToQuadraticBezierAbsolute(
            150,50,
            250,250
        );

        // This specifies a quadratic bezier curve with the current position as the start
        // point, the control point is mirrored from the previous curves control point
        // and the end point is defined by the x, y values.
        $draw->pathCurveToQuadraticBezierSmoothAbsolute(
            450,250
        );

        // This specifies a quadratic bezier curve with the current position as the start
        // point, the control point is mirrored from the previous curves control point
        // and the end point is defined relative from the current position by the x, y values.
        $draw->pathCurveToQuadraticBezierSmoothRelative(
            200,-100
        );

        $draw->pathFinish();

        $imagick = new \Imagick();
        $imagick->newImage(700, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickDraw::pathCurveToQuadraticBezierRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierRelative — Draws a quadratic Bezier curve

### Beschreibung

public function ImagickDraw::pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a quadratic Bezier curve from the current point to (x,y) using (x1,y1) as the control point using relative coordinates. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybezier.

### Parameter-Liste

`x1`

  starting x coordinate

`y1`

  starting y coordinate

`x_end`

  ending x coordinate

`y`

  ending y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Draws a quadratic Bezier curve

### Beschreibung

public function ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute(float `$x`, float `$y`): bool

Draws a quadratic Bezier curve (using absolute coordinates) from the current point to (x,y). The control point is assumed to be the reflection of the control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not a DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolut or DrawPathCurveToQuadraticBezierSmoothRelative, assume the control point is coincident with the current point.). At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybezier.

This function cannot be used to continue a cubic Bezier curve smoothly. It can only continue from a quadratic curve smoothly.

### Parameter-Liste

`x`

  ending x coordinate

`y`

  ending y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute() example

    <?php
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor("black");
    $draw->setFillColor("blue");

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50,250);

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is the first two params, and the end point is the last two params.
    $draw->pathCurveToQuadraticBezierAbsolute(
        150,50,
        250,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothAbsolute(
        450,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined relative from the current position by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothRelative(
        200,-100
    );

    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(700, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
    ?>

# ImagickDraw::pathCurveToQuadraticBezierSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Draws a quadratic Bezier curve

### Beschreibung

public function ImagickDraw::pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a quadratic Bezier curve (using relative coordinates) from the current point to (x, y). The control point is assumed to be the reflection of the control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not a DrawPathCurveToQuadraticBezierAbsolute, DrawPathCurveToQuadraticBezierRelative, DrawPathCurveToQuadraticBezierSmoothAbsolut or DrawPathCurveToQuadraticBezierSmoothRelative, assume the control point is coincident with the current point). At the end of the command, the new current point becomes the final (x, y) coordinate pair used in the polybezier.

This function cannot be used to continue a cubic Bezier curve smoothly. It can only continue from a quadratic curve smoothly.

### Parameter-Liste

`x`

  ending x coordinate

`y`

  ending y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::pathCurveToQuadraticBezierSmoothRelative() example

    <?php
    $draw = new \ImagickDraw();

    $draw->setStrokeOpacity(1);
    $draw->setStrokeColor("black");
    $draw->setFillColor("blue");

    $draw->setStrokeWidth(2);
    $draw->setFontSize(72);

    $draw->pathStart();
    $draw->pathMoveToAbsolute(50,250);

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is the first two params, and the end point is the last two params.
    $draw->pathCurveToQuadraticBezierAbsolute(
        150,50,
        250,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothAbsolute(
        450,250
    );

    // This specifies a quadratic bezier curve with the current position as the start
    // point, the control point is mirrored from the previous curves control point
    // and the end point is defined relative from the current position by the x, y values.
    $draw->pathCurveToQuadraticBezierSmoothRelative(
        200,-100
    );

    $draw->pathFinish();

    $imagick = new \Imagick();
    $imagick->newImage(700, 500, $backgroundColor);
    $imagick->setImageFormat("png");

    $imagick->drawImage($draw);

    header("Content-Type: image/png");
    echo $imagick->getImageBlob();
    ?>

# ImagickDraw::pathCurveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToRelative — Draws a cubic Bezier curve

### Beschreibung

public function ImagickDraw::pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a cubic Bezier curve from the current point to (x,y) using (x1,y1) as the control point at the beginning of the curve and (x2,y2) as the control point at the end of the curve using relative coordinates. At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybezier.

### Parameter-Liste

`x1`

  x coordinate of starting control point

`y1`

  y coordinate of starting control point

`x2`

  x coordinate of ending control point

`y2`

  y coordinate of ending control point

`x`

  ending x coordinate

`y`

  ending y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathCurveToSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothAbsolute — Draws a cubic Bezier curve

### Beschreibung

public function ImagickDraw::pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a cubic Bezier curve from the current point to (x,y) using absolute coordinates. The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not an DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute or DrawPathCurveToSmoothRelative, assume the first control point is coincident with the current point.) (x2,y2) is the second control point (i.e., the control point at the end of the curve). At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybezier.

### Parameter-Liste

`x2`

  x coordinate of the second control point

`y2`

  y coordinate of the second control point

`x`

  x coordinate of the ending point

`y`

  y coordinate of the ending point

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathCurveToSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothRelative — Draws a cubic Bezier curve

### Beschreibung

public function ImagickDraw::pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a cubic Bezier curve from the current point to (x,y) using relative coordinates. The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (If there is no previous command or if the previous command was not an DrawPathCurveToAbsolute, DrawPathCurveToRelative, DrawPathCurveToSmoothAbsolute or DrawPathCurveToSmoothRelative, assume the first control point is coincident with the current point.) (x2,y2) is the second control point (i.e., the control point at the end of the curve). At the end of the command, the new current point becomes the final (x,y) coordinate pair used in the polybezier.

### Parameter-Liste

`x2`

  x coordinate of the second control point

`y2`

  y coordinate of the second control point

`x`

  x coordinate of the ending point

`y`

  y coordinate of the ending point

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathEllipticArcAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcAbsolute — Draws an elliptical arc

### Beschreibung

public function ImagickDraw::pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws an elliptical arc from the current point to (x, y) using absolute coordinates. The size and orientation of the ellipse are defined by two radii (rx, ry) and an xAxisRotation, which indicates how the ellipse as a whole is rotated relative to the current coordinate system. The center (cx, cy) of the ellipse is calculated automatically to satisfy the constraints imposed by the other parameters. largeArcFlag and sweepFlag contribute to the automatic calculations and help determine how the arc is drawn. If `large_arc` is `true` then draw the larger of the available arcs. If `sweep` is true, then draw the arc matching a clock-wise rotation.

### Parameter-Liste

`rx`

  x radius

`ry`

  y radius

`x_axis_rotation`

  x axis rotation

`large_arc`

  large arc flag

`sweep`

  sweep flag

`x`

  x coordinate

`y`

  y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathEllipticArcRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcRelative — Draws an elliptical arc

### Beschreibung

public function ImagickDraw::pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws an elliptical arc from the current point to (x, y) using relative coordinates. The size and orientation of the ellipse are defined by two radii (rx, ry) and an xAxisRotation, which indicates how the ellipse as a whole is rotated relative to the current coordinate system. The center (cx, cy) of the ellipse is calculated automatically to satisfy the constraints imposed by the other parameters. largeArcFlag and sweepFlag contribute to the automatic calculations and help determine how the arc is drawn. If `large_arc` is `true` then draw the larger of the available arcs. If `sweep` is true, then draw the arc matching a clock-wise rotation.

### Parameter-Liste

`rx`

  x radius

`ry`

  y radius

`x_axis_rotation`

  x axis rotation

`large_arc`

  large arc flag

`sweep`

  sweep flag

`x`

  x coordinate

`y`

  y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathFinish

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathFinish — Terminates the current path

### Beschreibung

public function ImagickDraw::pathFinish(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Terminates the current path.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathLineToAbsolute

(PECL imagick 2)

ImagickDraw::pathLineToAbsolute — Draws a line path

### Beschreibung

public function ImagickDraw::pathLineToAbsolute(float `$x`, float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a line path from the current point to the given coordinate using absolute coordinates. The coordinate then becomes the new current point.

### Parameter-Liste

`x`

  starting x coordinate

`y`

  ending x coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathLineToHorizontalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalAbsolute — Draws a horizontal line path

### Beschreibung

public function ImagickDraw::pathLineToHorizontalAbsolute(float `$x`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a horizontal line path from the current point to the target point using absolute coordinates. The target point then becomes the new current point.

### Parameter-Liste

`x`

  x coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathLineToHorizontalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalRelative — Draws a horizontal line

### Beschreibung

public function ImagickDraw::pathLineToHorizontalRelative(float `$x`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a horizontal line path from the current point to the target point using relative coordinates. The target point then becomes the new current point.

### Parameter-Liste

`x`

  x coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathLineToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToRelative — Draws a line path

### Beschreibung

public function ImagickDraw::pathLineToRelative(float `$x`, float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a line path from the current point to the given coordinate using relative coordinates. The coordinate then becomes the new current point.

### Parameter-Liste

`x`

  starting x coordinate

`y`

  starting y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathLineToVerticalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalAbsolute — Draws a vertical line

### Beschreibung

public function ImagickDraw::pathLineToVerticalAbsolute(float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a vertical line path from the current point to the target point using absolute coordinates. The target point then becomes the new current point.

### Parameter-Liste

`y`

  y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathLineToVerticalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalRelative — Draws a vertical line path

### Beschreibung

public function ImagickDraw::pathLineToVerticalRelative(float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a vertical line path from the current point to the target point using relative coordinates. The target point then becomes the new current point.

### Parameter-Liste

`y`

  y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathMoveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToAbsolute — Starts a new sub-path

### Beschreibung

public function ImagickDraw::pathMoveToAbsolute(float `$x`, float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Starts a new sub-path at the given coordinate using absolute coordinates. The current point then becomes the specified coordinate.

### Parameter-Liste

`x`

  x coordinate of the starting point

`y`

  y coordinate of the starting point

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathMoveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToRelative — Starts a new sub-path

### Beschreibung

public function ImagickDraw::pathMoveToRelative(float `$x`, float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Starts a new sub-path at the given coordinate using relative coordinates. The current point then becomes the specified coordinate.

### Parameter-Liste

`x`

  target x coordinate

`y`

  target y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pathStart

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathStart — Declares the start of a path drawing list

### Beschreibung

public function ImagickDraw::pathStart(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Declares the start of a path drawing list which is terminated by a matching DrawPathFinish() command. All other DrawPath commands must be enclosed between a and a DrawPathFinish() command. This is because path drawing commands are subordinate commands and they do not function by themselves.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::pathStart() example

    <?php
    function pathStart($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 50);
        $draw->pathLineToAbsolute(100, 50);
        $draw->pathLineToRelative(0, 50);
        $draw->pathLineToHorizontalRelative(-50);
        $draw->pathFinish();

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 50);
        $draw->pathMoveToRelative(300, 0);
        $draw->pathLineToRelative(50, 0);
        $draw->pathLineToVerticalRelative(50);
        $draw->pathLineToHorizontalAbsolute(350);
        $draw->pathclose();
        $draw->pathFinish();

        $draw->pathStart();
        $draw->pathMoveToAbsolute(50, 300);
        $draw->pathCurveToAbsolute(50, 300, 100, 200, 300, 300);
        $draw->pathLineToVerticalAbsolute(350);
        $draw->pathFinish();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::point

(PECL imagick 2, PECL imagick 3)

ImagickDraw::point — Draws a point

### Beschreibung

public function ImagickDraw::point(float `$x`, float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a point using the current stroke color and stroke thickness at the specified coordinates.

### Parameter-Liste

`x`

  point's x coordinate

`y`

  point's y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::point() example

    <?php
    function point($fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setFillColor($fillColor);

        for ($x = 0; $x < 10000; $x++) {
            $draw->point(rand(0, 500), rand(0, 500));
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::polygon

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polygon — Draws a polygon

### Beschreibung

public function ImagickDraw::polygon(array `$coordinates`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a polygon using the current stroke, stroke width, and fill color or texture, using the specified array of coordinates.

### Parameter-Liste

`coordinates`

  multidimensional array like array( array( 'x' => 3, 'y' => 4 ), array( 'x' => 2, 'y' => 6 ) );

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickDraw::polygon() example

    <?php
    function polygon($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(4);

        $draw->setFillColor($fillColor);

        $points = [
            ['x' => 40 * 5, 'y' => 10 * 5],
            ['x' => 20 * 5, 'y' => 20 * 5],
            ['x' => 70 * 5, 'y' => 50 * 5],
            ['x' => 60 * 5, 'y' => 15 * 5],
        ];

        $draw->polygon($points);

        $image = new \Imagick();
        $image->newImage(500, 300, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::polyline

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polyline — Draws a polyline

### Beschreibung

public function ImagickDraw::polyline(array `$coordinates`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a polyline using the current stroke, stroke width, and fill color or texture, using the specified array of coordinates.

### Parameter-Liste

`coordinates`

  array of x and y coordinates: array( array( 'x' => 4, 'y' => 6 ), array( 'x' => 8, 'y' => 10 ) )

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickDraw::polyline() example

    <?php
    function polyline($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(5);

        $points = [
            ['x' => 40 * 5, 'y' => 10 * 5],
            ['x' => 20 * 5, 'y' => 20 * 5],
            ['x' => 70 * 5, 'y' => 50 * 5],
            ['x' => 60 * 5, 'y' => 15 * 5]
        ];

        $draw->polyline($points);

        $image = new \Imagick();
        $image->newImage(500, 300, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::pop

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pop — Destroys the current ImagickDraw in the stack, and returns to the previously pushed ImagickDraw

### Beschreibung

public function ImagickDraw::pop(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Destroys the current ImagickDraw in the stack, and returns to the previously pushed ImagickDraw. Multiple ImagickDraws may exist. It is an error to attempt to pop more ImagickDraws than have been pushed, and it is proper form to pop all ImagickDraws which have been pushed.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ImagickDraw::popClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popClipPath — Terminates a clip path definition

### Beschreibung

public function ImagickDraw::popClipPath(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Terminates a clip path definition.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::popDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popDefs — Terminates a definition list

### Beschreibung

public function ImagickDraw::popDefs(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Terminates a definition list.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::popDefs() example

    <?php
    function popDefs($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setstrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->pushDefs();
        $draw->setStrokeColor('white');
        $draw->rectangle(50, 50, 200, 200);
        $draw->popDefs();

        $draw->rectangle(300, 50, 450, 200);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::popPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popPattern — Terminates a pattern definition

### Beschreibung

public function ImagickDraw::popPattern(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Terminates a pattern definition.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ImagickDraw::push

(PECL imagick 2, PECL imagick 3)

ImagickDraw::push — Clones the current ImagickDraw and pushes it to the stack

### Beschreibung

public function ImagickDraw::push(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Clones the current ImagickDraw to create a new ImagickDraw, which is then added to the ImagickDraw stack. The original drawing ImagickDraw(s) may be returned to by invoking ImagickDraw::pop(). The ImagickDraws are stored on a ImagickDraw stack. For every Pop there must have already been an equivalent Push.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::push() example

    <?php
    function push($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillModifiedColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->push();
        $draw->translate(50, 50);
        $draw->rectangle(200, 200, 300, 300);
        $draw->pop();
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::pushClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushClipPath — Starts a clip path definition

### Beschreibung

public function ImagickDraw::pushClipPath(string `$clip_mask_id`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Starts a clip path definition which is comprised of any number of drawing commands and terminated by a ImagickDraw::popClipPath() command.

### Parameter-Liste

`clip_mask_id`

  Clip mask Id

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pushDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushDefs — Indicates that following commands create named elements for early processing

### Beschreibung

public function ImagickDraw::pushDefs(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Indicates that commands up to a terminating ImagickDraw::popDefs() command create named elements (e.g. clip-paths, textures, etc.) which may safely be processed earlier for the sake of efficiency.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::pushPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushPattern — Indicates that subsequent commands up to a ImagickDraw::opPattern() command comprise the definition of a named pattern

### Beschreibung

public function ImagickDraw::pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Indicates that subsequent commands up to a DrawPopPattern() command comprise the definition of a named pattern. The pattern space is assigned top left corner coordinates, a width and height, and becomes its own drawing space. Anything which can be drawn may be used in a pattern definition. Named patterns may be used as stroke or brush definitions.

### Parameter-Liste

`pattern_id`

  the pattern Id

`x`

  x coordinate of the top-left corner

`y`

  y coordinate of the top-left corner

`width`

  width of the pattern

`height`

  height of the pattern

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::pushPattern() example

    <?php
    function pushPattern($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(1);

        $draw->pushPattern("MyFirstPattern", 0, 0, 50, 50);
        for ($x = 0; $x < 50; $x += 10) {
            for ($y = 0; $y < 50; $y += 5) {
                $positionX = $x + (($y / 5) % 5);
                $draw->rectangle($positionX, $y, $positionX + 5, $y + 5);
            }
        }
        $draw->popPattern();

        $draw->setFillOpacity(0);
        $draw->rectangle(100, 100, 400, 400);
        $draw->setFillOpacity(1);

        $draw->setFillOpacity(1);

        $draw->push();
        $draw->setFillPatternURL('#MyFirstPattern');
        $draw->setFillColor('yellow');
        $draw->rectangle(100, 100, 400, 400);
        $draw->pop();

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::rectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rectangle — Draws a rectangle

### Beschreibung

public function ImagickDraw::rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a rectangle given two coordinates and using the current stroke, stroke width, and fill settings.

### Parameter-Liste

`top_left_x`

  x coordinate of the top left corner

`top_left_y`

  y coordinate of the top left corner

`bottom_right_x`

  x coordinate of the bottom right corner

`bottom_right_y`

  y coordinate of the bottom right corner

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::rectangle() example

    <?php
    function rectangle($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->rectangle(200, 200, 300, 300);
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::render

(PECL imagick 2, PECL imagick 3)

ImagickDraw::render — Renders all preceding drawing commands onto the image

### Beschreibung

public function ImagickDraw::render(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Renders all preceding drawing commands onto the image.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ImagickDraw::resetVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::resetVectorGraphics — Resets the vector graphics

### Beschreibung

public function ImagickDraw::resetVectorGraphics(): bool

Resets the vector graphics.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickDraw::rotate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rotate — Applies the specified rotation to the current coordinate space

### Beschreibung

public function ImagickDraw::rotate(float `$degrees`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Applies the specified rotation to the current coordinate space.

### Parameter-Liste

`degrees`

  degrees to rotate.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::rotate() example

    <?php
    function rotate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeOpacity(1);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);
        $draw->setFillColor($fillModifiedColor);
        $draw->rotate(15);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::roundRectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::roundRectangle — Draws a rounded rectangle

### Beschreibung

public function ImagickDraw::roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Draws a rounded rectangle given two coordinates, x & y corner radiuses and using the current stroke, stroke width, and fill settings.

### Parameter-Liste

`top_left_x`

  x coordinate of the top left corner

`top_left_y`

  y coordinate of the top left corner

`bottom_right_x`

  x coordinate of the bottom right

`bottom_right_y`

  y coordinate of the bottom right

`rounding_x`

  x rounding

`rounding_y`

  y rounding

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::roundRectangle() example

    <?php
    function roundRectangle($strokeColor, $fillColor, $backgroundColor, $startX, $startY, $endX, $endY, $roundX, $roundY) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->roundRectangle($startX, $startY, $endX, $endY, $roundX, $roundY);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::scale

(PECL imagick 2, PECL imagick 3)

ImagickDraw::scale — Adjusts the scaling factor

### Beschreibung

public function ImagickDraw::scale(float `$x`, float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Adjusts the scaling factor to apply in the horizontal and vertical directions to the current coordinate space.

### Parameter-Liste

`x`

  horizontal factor

`y`

  vertical factor

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::scale() example

    <?php
    function scale($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(4);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);
        $draw->setFillColor($fillModifiedColor);
        $draw->scale(1.4, 1.4);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipPath — Associates a named clipping path with the image

### Beschreibung

public function ImagickDraw::setClipPath(string `$clip_mask`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Associates a named clipping path with the image. Only the areas drawn on by the clipping path will be modified as long as it remains in effect.

### Parameter-Liste

`clip_mask`

  the clipping path name

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setClipPath() example

    <?php
    function setClipPath($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $clipPathName = 'testClipPath';

        $draw->pushClipPath($clipPathName);
        $draw->rectangle(0, 0, 250, 250);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);
        $draw->rectangle(100, 100, 400, 400);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipRule — Set the polygon fill rule to be used by the clipping path

### Beschreibung

public function ImagickDraw::setClipRule(int `$fillrule`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Set the polygon fill rule to be used by the clipping path.

### Parameter-Liste

`fillrule`

  One of the FILLRULE constant (`imagick::FILLRULE_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setClipRule() example

    <?php
    function setClipRule($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        //\Imagick::FILLRULE_EVENODD
        //\Imagick::FILLRULE_NONZERO

        $clipPathName = 'testClipPath';
        $draw->pushClipPath($clipPathName);
        $draw->setClipRule(\Imagick::FILLRULE_EVENODD);
        $draw->rectangle(0, 0, 300, 500);
        $draw->rectangle(200, 0, 500, 500);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);
        $draw->rectangle(200, 200, 300, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipUnits — Sets the interpretation of clip path units

### Beschreibung

public function ImagickDraw::setClipUnits(int `$pathunits`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the interpretation of clip path units.

### Parameter-Liste

`pathunits`

  the number of clip units

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setClipUnits() example

    <?php
    function setClipUnits($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $clipPathName = 'testClipPath';
        $draw->setClipUnits(\Imagick::RESOLUTION_PIXELSPERINCH);
        $draw->pushClipPath($clipPathName);
        $draw->rectangle(0, 0, 250, 250);
        $draw->popClipPath();
        $draw->setClipPath($clipPathName);

        //RESOLUTION_PIXELSPERINCH
        //RESOLUTION_PIXELSPERCENTIMETER

        $draw->rectangle(200, 200, 300, 300);
        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillAlpha — Sets the opacity to use when drawing using the fill color or fill texture

### Beschreibung

public function ImagickDraw::setFillAlpha(float `$alpha`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the opacity to use when drawing using the fill color or fill texture. Fully opaque is 1.0.

### Parameter-Liste

`alpha`

  fill alpha

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setFillAlpha() example

    <?php
    function setFillAlpha($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);
        $draw->rectangle(100, 200, 200, 300);
        @$draw->setFillAlpha(0.4);
        $draw->rectangle(300, 200, 400, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillColor — Sets the fill color to be used for drawing filled objects

### Beschreibung

public function ImagickDraw::setFillColor(ImagickPixel|string `$fill_color`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the fill color to be used for drawing filled objects.

### Parameter-Liste

`fill_color`

  ImagickPixel to use to set the color

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setFillColor()

    <?php
    function setFillColor($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(1.5);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle(50, 50, 150, 150);

        $draw->setFillColor("rgb(200, 32, 32)");
        $draw->rectangle(200, 50, 300, 150);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillOpacity — Sets the opacity to use when drawing using the fill color or fill texture

### Beschreibung

public function ImagickDraw::setFillOpacity(float `$opacity`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the opacity to use when drawing using the fill color or fill texture. Fully opaque is 1.0.

### Parameter-Liste

`opacity`

  the fill opacity

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setFillOpacity()

    <?php
    function setFillOpacity($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeOpacity(1);
        $draw->setStrokeWidth(2);

        $draw->rectangle(100, 200, 200, 300);

        $draw->setFillOpacity(0.4);
        $draw->rectangle(300, 200, 400, 300);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFillPatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillPatternURL — Sets the URL to use as a fill pattern for filling objects

### Beschreibung

public function ImagickDraw::setFillPatternURL(string `$fill_url`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the URL to use as a fill pattern for filling objects. Only local URLs ("#identifier") are supported at this time. These local URLs are normally created by defining a named fill pattern with DrawPushPattern/DrawPopPattern.

### Parameter-Liste

`fill_url`

  URL to use to obtain fill pattern.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ImagickDraw::setFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillRule — Sets the fill rule to use while drawing polygons

### Beschreibung

public function ImagickDraw::setFillRule(int `$fillrule`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the fill rule to use while drawing polygons.

### Parameter-Liste

`fillrule`

  One of the FILLRULE constant (`imagick::FILLRULE_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setFillRule() example

    <?php
    function setFillRule($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $fillRules = [\Imagick::FILLRULE_NONZERO, \Imagick::FILLRULE_EVENODD];

        $points = 11;
        $size = 150;

        $draw->translate(175, 160);

        for ($x = 0; $x < 2; $x++) {
            $draw->setFillRule($fillRules[$x]);
            $draw->pathStart();
            for ($n = 0; $n < $points * 2; $n++) {

                if ($n >= $points) {
                    $angle = fmod($n * 360 * 4 / $points, 360) * pi() / 180;
                }
                else {
                    $angle = fmod($n * 360 * 3 / $points, 360) * pi() / 180;
                }

                $positionX = $size * sin($angle);
                $positionY = $size * cos($angle);

                if ($n == 0) {
                    $draw->pathMoveToAbsolute($positionX, $positionY);
                }
                else {
                    $draw->pathLineToAbsolute($positionX, $positionY);
                }
            }

            $draw->pathClose();
            $draw->pathFinish();

            $draw->translate(325, 0);
        }

        $image = new \Imagick();
        $image->newImage(700, 320, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFont — Sets the fully-specified font to use when annotating with text

### Beschreibung

public function ImagickDraw::setFont(string `$font_name`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the fully-specified font to use when annotating with text.

### Parameter-Liste

`font_name`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickDraw::setFont() example

    <?php
    function setFont($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);
        $draw->setFontSize(36);

        $draw->setFont("../fonts/Arial.ttf");
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFont("../fonts/Consolas.ttf");
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFont("../fonts/CANDY.TTF");
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFont("../fonts/Inconsolata-dz.otf");
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontFamily — Sets the font family to use when annotating with text

### Beschreibung

public function ImagickDraw::setFontFamily(string `$font_family`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the font family to use when annotating with text.

### Parameter-Liste

`font_family`

  the font family

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickDraw::setFontFamily() example

    <?php
    function setFontFamily($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel($strokeColor);
        $fillColor = new \ImagickPixel($fillColor);

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(2);

        $draw->setFontSize(48);

        $draw->setFontFamily("Times");
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontFamily("AvantGarde");
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontFamily("NewCenturySchlbk");
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFontFamily("Palatino");
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(450, 250, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontSize — Sets the font pointsize to use when annotating with text

### Beschreibung

public function ImagickDraw::setFontSize(float `$point_size`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the font pointsize to use when annotating with text.

### Parameter-Liste

`point_size`

  the point size

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setFontSize() example

    <?php
    function setFontSize($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFont("../fonts/Arial.ttf");

        $sizes = [24, 36, 48, 60, 72];

        foreach ($sizes as $size) {
            $draw->setFontSize($size);
            $draw->annotation(50, ($size * $size / 16), "Lorem Ipsum!");
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontStretch

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStretch — Sets the font stretch to use when annotating with text

### Beschreibung

public function ImagickDraw::setFontStretch(int `$stretch`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the font stretch to use when annotating with text. The AnyStretch enumeration acts as a wild-card "don't care" option.

### Parameter-Liste

`stretch`

  One of the STRETCH constant (`imagick::STRETCH_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setFontStretch() example

    <?php
    function setFontStretch($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(36);

        $fontStretchTypes = [
            \Imagick::STRETCH_ULTRACONDENSED,
            \Imagick::STRETCH_CONDENSED,
            \Imagick::STRETCH_SEMICONDENSED,
            \Imagick::STRETCH_SEMIEXPANDED,
            \Imagick::STRETCH_EXPANDED,
            \Imagick::STRETCH_EXTRAEXPANDED,
            \Imagick::STRETCH_ULTRAEXPANDED,
            \Imagick::STRETCH_ANY
        ];

        $offset = 0;
        foreach ($fontStretchTypes as $fontStretch) {
            $draw->setFontStretch($fontStretch);
            $draw->annotation(50, 75 + $offset, "Lorem Ipsum!");
            $offset += 50;
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStyle — Sets the font style to use when annotating with text

### Beschreibung

public function ImagickDraw::setFontStyle(int `$style`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the font style to use when annotating with text. The AnyStyle enumeration acts as a wild-card "don't care" option.

### Parameter-Liste

`style`

  One of the STYLE constant (`imagick::STYLE_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setFontStyle() example

    <?php
    function setFontStyle($fillColor, $strokeColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(36);
        $draw->setFontStyle(\Imagick::STYLE_NORMAL);
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontStyle(\Imagick::STYLE_ITALIC);
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontStyle(\Imagick::STYLE_OBLIQUE);
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(350, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontWeight — Sets the font weight

### Beschreibung

public function ImagickDraw::setFontWeight(int `$weight`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the font weight to use when annotating with text.

### Parameter-Liste

`weight`

### Rückgabewerte

### Beispiele

Beispiel #1 ImagickDraw::setFontWeight() example

    <?php
    function setFontWeight($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(1);

        $draw->setFontSize(36);

        $draw->setFontWeight(100);
        $draw->annotation(50, 50, "Lorem Ipsum!");

        $draw->setFontWeight(200);
        $draw->annotation(50, 100, "Lorem Ipsum!");

        $draw->setFontWeight(400);
        $draw->annotation(50, 150, "Lorem Ipsum!");

        $draw->setFontWeight(800);
        $draw->annotation(50, 200, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setGravity — Sets the text placement gravity

### Beschreibung

public function ImagickDraw::setGravity(int `$gravity`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the text placement gravity to use when annotating with text.

### Parameter-Liste

`gravity`

  One of the GRAVITY constant (`imagick::GRAVITY_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setGravity() example

    <?php
    function setGravity($fillColor, $strokeColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(24);

        $gravitySettings = array(
            \Imagick::GRAVITY_NORTHWEST => 'NorthWest',
            \Imagick::GRAVITY_NORTH => 'North',
            \Imagick::GRAVITY_NORTHEAST => 'NorthEast',
            \Imagick::GRAVITY_WEST => 'West',
            \Imagick::GRAVITY_CENTER => 'Centre',
            \Imagick::GRAVITY_SOUTHWEST => 'SouthWest',
            \Imagick::GRAVITY_SOUTH => 'South',
            \Imagick::GRAVITY_SOUTHEAST => 'SouthEast',
            \Imagick::GRAVITY_EAST => 'East'
        );

        $draw->setFont("../fonts/Arial.ttf");

        foreach ($gravitySettings as $type => $description) {
            $draw->setGravity($type);
            $draw->annotation(50, 50, '"' . $description . '"');
        }

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setResolution

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setResolution — Sets the resolution

### Beschreibung

public function ImagickDraw::setResolution(float `$resolution_x`, float `$resolution_y`): bool

Sets the resolution.

### Parameter-Liste

`resolution_x`

`resolution_y`

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickDraw::setStrokeAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAlpha — Specifies the opacity of stroked object outlines

### Beschreibung

public function ImagickDraw::setStrokeAlpha(float `$alpha`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies the opacity of stroked object outlines.

### Parameter-Liste

`alpha`

  opacity

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeAlpha() example

    <?php
    function setStrokeAlpha($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeOpacity(0.1);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAntialias — Controls whether stroked outlines are antialiased

### Beschreibung

public function ImagickDraw::setStrokeAntialias(bool `$enabled`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Controls whether stroked outlines are antialiased. Stroked outlines are antialiased by default. When antialiasing is disabled stroked pixels are thresholded to determine if the stroke color or underlying canvas color should be used.

### Parameter-Liste

`enabled`

  the antialias setting

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeAntialias() example

    <?php
    function setStrokeAntialias($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setStrokeAntialias(false);
        $draw->line(100, 100, 400, 105);

        $draw->line(100, 140, 400, 185);

        $draw->setStrokeAntialias(true);
        $draw->line(100, 110, 400, 115);
        $draw->line(100, 150, 400, 195);

        $image = new \Imagick();
        $image->newImage(500, 250, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeColor — Sets the color used for stroking object outlines

### Beschreibung

public function ImagickDraw::setStrokeColor(ImagickPixel|string `$color`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the color used for stroking object outlines.

### Parameter-Liste

`color`

  the stroke color

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeColor() example

    <?php
    function setStrokeColor($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(5);

        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);

        $draw->setStrokeOpacity(0.1);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashArray — Specifies the pattern of dashes and gaps used to stroke paths

### Beschreibung

public function ImagickDraw::setStrokeDashArray(?array `$dashes`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies the pattern of dashes and gaps used to stroke paths. The strokeDashArray represents an array of numbers that specify the lengths of alternating dashes and gaps in pixels. If an odd number of values is provided, then the list of values is repeated to yield an even number of values. To remove an existing dash array, pass a zero number_elements argument and null dash_array. A typical strokeDashArray_ array might contain the members 5 3 2.

### Parameter-Liste

`dashes`

  array of floats

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeDashArray() example

    <?php
    function setStrokeDashArray($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);

        $draw->setStrokeDashArray([10, 10]);
        $draw->rectangle(100, 50, 225, 175);

        $draw->setStrokeDashArray([20, 5, 20, 5, 5, 5,]);
        $draw->rectangle(275, 50, 400, 175);

        $draw->setStrokeDashArray([20, 5, 20, 5, 5]);
        $draw->rectangle(100, 200, 225, 350);

        $draw->setStrokeDashArray([1, 1, 1, 1, 2, 2, 3, 3, 5, 5, 8, 8, 13, 13, 21, 21, 34, 34, 55, 55, 89, 89, 144, 144, 233, 233, 377, 377, 610, 610, 987, 987, 1597, 1597, 2584, 2584, 4181, 4181,]);

        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashOffset — Specifies the offset into the dash pattern to start the dash

### Beschreibung

public function ImagickDraw::setStrokeDashOffset(float `$dash_offset`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies the offset into the dash pattern to start the dash.

### Parameter-Liste

`dash_offset`

  dash offset

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeDashOffset() example

    <?php
    function setStrokeDashOffset($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(4);
        $draw->setStrokeDashArray([20, 20]);
        $draw->setStrokeDashOffset(0);
        $draw->rectangle(100, 50, 225, 175);

        //Start the dash effect halfway through the solid portion
        $draw->setStrokeDashOffset(10);
        $draw->rectangle(275, 50, 400, 175);

        //Start the dash effect on the space portion
        $draw->setStrokeDashOffset(20);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeDashOffset(5);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineCap — Specifies the shape to be used at the end of open subpaths when they are stroked

### Beschreibung

public function ImagickDraw::setStrokeLineCap(int `$linecap`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies the shape to be used at the end of open subpaths when they are stroked.

### Parameter-Liste

`linecap`

  One of the LINECAP constant (`imagick::LINECAP_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeLineCap() example

    <?php
    function setStrokeLineCap($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(25);

        $lineTypes = [\Imagick::LINECAP_BUTT, \Imagick::LINECAP_ROUND, \Imagick::LINECAP_SQUARE,];

        $offset = 0;

        foreach ($lineTypes as $lineType) {
            $draw->setStrokeLineCap($lineType);
            $draw->line(50 + $offset, 50, 50 + $offset, 250);
            $offset += 50;
        }

        $imagick = new \Imagick();
        $imagick->newImage(300, 300, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineJoin — Specifies the shape to be used at the corners of paths when they are stroked

### Beschreibung

public function ImagickDraw::setStrokeLineJoin(int `$linejoin`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies the shape to be used at the corners of paths (or other vector shapes) when they are stroked.

### Parameter-Liste

`linejoin`

  One of the LINEJOIN constant (`imagick::LINEJOIN_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeLineJoin() example

    <?php
    function setStrokeLineJoin($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);

        $draw->setStrokeWidth(20);

        $offset = 220;

        $lineJoinStyle = [
            \Imagick::LINEJOIN_MITER,
            \Imagick::LINEJOIN_ROUND,
            \Imagick::LINEJOIN_BEVEL,
            ];

        for ($x = 0; $x < count($lineJoinStyle); $x++) {
            $draw->setStrokeLineJoin($lineJoinStyle[$x]);
            $points = [
                ['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
                ['x' => 20 * 5, 'y' => 20 * 5 + $x * $offset],
                ['x' => 70 * 5, 'y' => 50 * 5 + $x * $offset],
                ['x' => 40 * 5, 'y' => 10 * 5 + $x * $offset],
            ];

            $draw->polyline($points);
        }

        $image = new \Imagick();
        $image->newImage(500, 700, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeMiterLimit — Specifies the miter limit

### Beschreibung

public function ImagickDraw::setStrokeMiterLimit(int `$miterlimit`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies the miter limit. When two line segments meet at a sharp angle and miter joins have been specified for 'lineJoin', it is possible for the miter to extend far beyond the thickness of the line stroking the path. The miterLimit' imposes a limit on the ratio of the miter length to the 'lineWidth'.

### Parameter-Liste

`miterlimit`

  the miter limit

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeMiterLimit() example

    <?php
    function setStrokeMiterLimit($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeOpacity(0.6);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(10);

        $yOffset = 100;

        $draw->setStrokeLineJoin(\Imagick::LINEJOIN_MITER);

        for ($y = 0; $y < 3; $y++) {

            $draw->setStrokeMiterLimit(40 * $y);

            $points = [
                ['x' => 22 * 3, 'y' => 15 * 4 + $y * $yOffset],
                ['x' => 20 * 3, 'y' => 20 * 4 + $y * $yOffset],
                ['x' => 70 * 5, 'y' => 45 * 4 + $y * $yOffset],
            ];

            $draw->polygon($points);
        }

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        $image->setImageType(\Imagick::IMGTYPE_PALETTE);
        $image->setImageCompressionQuality(100);
        $image->stripImage();

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeOpacity — Specifies the opacity of stroked object outlines

### Beschreibung

public function ImagickDraw::setStrokeOpacity(float `$opacity`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies the opacity of stroked object outlines.

### Parameter-Liste

`opacity`

  stroke opacity. 1.0 is fully opaque

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeOpacity() example

    <?php
    function setStrokeOpacity($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(10);
        $draw->setStrokeOpacity(1);
        $draw->line(100, 80, 400, 125);
        $draw->rectangle(25, 200, 150, 350);
        $draw->setStrokeOpacity(0.5);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(200, 200, 325, 350);
        $draw->setStrokeOpacity(0.2);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(375, 200, 500, 350);

        $image = new \Imagick();
        $image->newImage(550, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setStrokePatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokePatternURL — Sets the pattern used for stroking object outlines

### Beschreibung

public function ImagickDraw::setStrokePatternURL(string `$stroke_url`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the pattern used for stroking object outlines.

### Parameter-Liste

`stroke_url`

  stroke URL

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickDraw::setStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeWidth — Sets the width of the stroke used to draw object outlines

### Beschreibung

public function ImagickDraw::setStrokeWidth(float `$width`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the width of the stroke used to draw object outlines.

### Parameter-Liste

`width`

  stroke width

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setStrokeWidth() example

    <?php
    function setStrokeWidth($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeWidth(1);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->line(100, 100, 400, 145);
        $draw->rectangle(100, 200, 225, 350);
        $draw->setStrokeWidth(5);
        $draw->line(100, 120, 400, 165);
        $draw->rectangle(275, 200, 400, 350);

        $image = new \Imagick();
        $image->newImage(500, 400, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::setTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAlignment — Specifies a text alignment

### Beschreibung

public function ImagickDraw::setTextAlignment(int `$align`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies a text alignment to be applied when annotating with text.

### Parameter-Liste

`align`

  One of the ALIGN constant (`imagick::ALIGN_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setTextAlignment() example

    <?php
    function setTextAlignment($strokeColor, $fillColor, $backgroundColor) {
        $draw = new \ImagickDraw();
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(36);

        $draw->setTextAlignment(\Imagick::ALIGN_LEFT);
        $draw->annotation(250, 75, "Lorem Ipsum!");
        $draw->setTextAlignment(\Imagick::ALIGN_CENTER);
        $draw->annotation(250, 150, "Lorem Ipsum!");
        $draw->setTextAlignment(\Imagick::ALIGN_RIGHT);
        $draw->annotation(250, 225, "Lorem Ipsum!");
        $draw->line(250, 0, 250, 500);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAntialias — Controls whether text is antialiased

### Beschreibung

public function ImagickDraw::setTextAntialias(bool `$antialias`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Controls whether text is antialiased. Text is antialiased by default.

### Parameter-Liste

`antialias`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setTextAntialias() example

    <?php
    function setTextAntialias($fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();
        $draw->setStrokeColor('none');
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(1);
        $draw->setFontSize(32);
        $draw->setTextAntialias(false);
        $draw->annotation(5, 30, "Lorem Ipsum!");
        $draw->setTextAntialias(true);
        $draw->annotation(5, 65, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(220, 80, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        //Scale the image so that people can see the aliasing.
        $imagick->scaleImage(220 * 6, 80 * 6);
        $imagick->cropImage(640, 480, 0, 0);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextDecoration — Specifies a decoration

### Beschreibung

public function ImagickDraw::setTextDecoration(int `$decoration`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies a decoration to be applied when annotating with text.

### Parameter-Liste

`decoration`

  One of the DECORATION constant (`imagick::DECORATION_*`).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setTextDecoration() example

    <?php
    function setTextDecoration($strokeColor, $fillColor, $backgroundColor, $textDecoration) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->setTextDecoration($textDecoration);
        $draw->annotation(50, 75, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 200, $backgroundColor);
        $imagick->setImageFormat("png");
        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextEncoding — Specifies the text code set

### Beschreibung

public function ImagickDraw::setTextEncoding(string `$encoding`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies the code set to use for text annotations. The only character encoding which may be specified at this time is "UTF-8" for representing Unicode as a sequence of bytes. Specify an empty string to set text encoding to the system's default. Successful text annotation using Unicode may require fonts designed to support Unicode.

### Parameter-Liste

`encoding`

  the encoding name

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# ImagickDraw::setTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setTextInterlineSpacing — Sets the text interline spacing

### Beschreibung

public function ImagickDraw::setTextInterlineSpacing(float `$spacing`): bool

Sets the text interline spacing.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`spacing`

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickDraw::setTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextInterwordSpacing — Sets the text interword spacing

### Beschreibung

public function ImagickDraw::setTextInterwordSpacing(float `$spacing`): bool

Sets the text interword spacing.

### Parameter-Liste

`spacing`

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickDraw::setTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextKerning — Sets the text kerning

### Beschreibung

public function ImagickDraw::setTextKerning(float `$kerning`): bool

Sets the text kerning

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`kerning`

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickDraw::setTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextUnderColor — Specifies the color of a background rectangle

### Beschreibung

public function ImagickDraw::setTextUnderColor(ImagickPixel|string `$under_color`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Specifies the color of a background rectangle to place under text annotations.

### Parameter-Liste

`under_color`

  the under color

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setTextUnderColor() example

    <?php
    function setTextUnderColor($strokeColor, $fillColor, $backgroundColor, $textUnderColor) {
        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);
        $draw->annotation(50, 75, "Lorem Ipsum!");
        $draw->setTextUnderColor($textUnderColor);
        $draw->annotation(50, 175, "Lorem Ipsum!");

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setVectorGraphics — Sets the vector graphics

### Beschreibung

public function ImagickDraw::setVectorGraphics(string `$xml`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the vector graphics associated with the specified ImagickDraw object. Use this method with ImagickDraw::getVectorGraphics() as a method to persist the vector graphics state.

### Parameter-Liste

`xml`

  xml containing the vector graphics

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setVectorGraphics() example

    <?php
    function setVectorGraphics() {
        //Setup a draw object with some drawing in it.
        $draw = new \ImagickDraw();
        $draw->setFillColor("red");
        $draw->circle(20, 20, 50, 50);
        $draw->setFillColor("blue");
        $draw->circle(50, 70, 50, 50);
        $draw->rectangle(50, 120, 80, 150);

        //Get the drawing as a string
        $SVG = $draw->getVectorGraphics();

        //$svg is a string, and could be saved anywhere a string can be saved

        //Use the saved drawing to generate a new draw object
        $draw2 = new \ImagickDraw();
        //Apparently the SVG text is missing the root element.
        $draw2->setVectorGraphics("<root>".$SVG."</root>");

        $imagick = new \Imagick();
        $imagick->newImage(200, 200, 'white');
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw2);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::setViewbox

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setViewbox — Sets the overall canvas size

### Beschreibung

public function ImagickDraw::setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the overall canvas size to be recorded with the drawing vector data. Usually this will be specified using the same size as the canvas image. When the vector data is saved to SVG or MVG formats, the viewbox is use to specify the size of the canvas image that a viewer will render the vector data on.

### Parameter-Liste

`left_x`

  left x coordinate

`top_y`

  left y coordinate

`right_x`

  right x coordinate

`bottom_y`

  right y coordinate

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::setViewBox() example

    <?php
    function setViewBox($strokeColor, $fillColor, $backgroundColor) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->setStrokeWidth(2);
        $draw->setFontSize(72);

        /*

        Sets the overall canvas size to be recorded with the drawing vector data. Usually this will be specified using the same size as the canvas image. When the vector data is saved to SVG or MVG formats, the viewbox is use to specify the size of the canvas image that a viewer will render the vector data on.

         */

        $draw->circle(250, 250, 250, 0);
        $draw->setviewbox(0, 0, 200, 200);
        $draw->circle(125, 250, 250, 250);
        $draw->translate(250, 125);
        $draw->circle(0, 0, 125, 0);

        $imagick = new \Imagick();
        $imagick->newImage(500, 500, $backgroundColor);
        $imagick->setImageFormat("png");

        $imagick->drawImage($draw);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickDraw::skewX

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewX — Skews the current coordinate system in the horizontal direction

### Beschreibung

public function ImagickDraw::skewX(float `$degrees`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Skews the current coordinate system in the horizontal direction.

### Parameter-Liste

`degrees`

  degrees to skew

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::skewX() example

    <?php
    function skewX($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                   $startX, $startY, $endX, $endY, $skew) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);
        $draw->setFillColor($fillModifiedColor);
        $draw->skewX($skew);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::skewY

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewY — Skews the current coordinate system in the vertical direction

### Beschreibung

public function ImagickDraw::skewY(float `$degrees`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Skews the current coordinate system in the vertical direction.

### Parameter-Liste

`degrees`

  degrees to skew

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::skewY() example

    <?php
    function skewY($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                   $startX, $startY, $endX, $endY, $skew) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setStrokeWidth(2);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);
        $draw->setFillColor($fillModifiedColor);
        $draw->skewY($skew);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");
        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickDraw::translate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::translate — Applies a translation to the current coordinate system

### Beschreibung

public function ImagickDraw::translate(float `$x`, float `$y`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Applies a translation to the current coordinate system which moves the coordinate system origin to the specified coordinate.

### Parameter-Liste

`x`

  horizontal translation

`y`

  vertical translation

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 ImagickDraw::translate() example

    <?php
    function translate($strokeColor, $fillColor, $backgroundColor, $fillModifiedColor,
                       $startX, $startY, $endX, $endY, $translateX, $translateY) {

        $draw = new \ImagickDraw();

        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $draw->setFillColor($fillModifiedColor);
        $draw->translate($translateX, $translateY);
        $draw->rectangle($startX, $startY, $endX, $endY);

        $image = new \Imagick();
        $image->newImage(500, 500, $backgroundColor);
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

## Inhaltsverzeichnis

- ImagickDraw::affine — Adjusts the current affine transformation matrix
- ImagickDraw::annotation — Draws text on the image
- ImagickDraw::arc — Draws an arc
- ImagickDraw::bezier — Draws a bezier curve
- ImagickDraw::circle — Draws a circle
- ImagickDraw::clear — Clears the ImagickDraw
- ImagickDraw::clone — Makes an exact copy of the specified ImagickDraw object
- ImagickDraw::color — Draws color on image
- ImagickDraw::comment — Adds a comment
- ImagickDraw::composite — Composites an image onto the current image
- ImagickDraw::__construct — The ImagickDraw constructor
- ImagickDraw::destroy — Frees all associated resources
- ImagickDraw::ellipse — Draws an ellipse on the image
- ImagickDraw::getClipPath — Obtains the current clipping path ID
- ImagickDraw::getClipRule — Returns the current polygon fill rule
- ImagickDraw::getClipUnits — Returns the interpretation of clip path units
- ImagickDraw::getFillColor — Returns the fill color
- ImagickDraw::getFillOpacity — Returns the opacity used when drawing
- ImagickDraw::getFillRule — Returns the fill rule
- ImagickDraw::getFont — Returns the font
- ImagickDraw::getFontFamily — Returns the font family
- ImagickDraw::getFontSize — Returns the font pointsize
- ImagickDraw::getFontStretch — Gets the font stretch to use when annotating with text
- ImagickDraw::getFontStyle — Returns the font style
- ImagickDraw::getFontWeight — Returns the font weight
- ImagickDraw::getGravity — Returns the text placement gravity
- ImagickDraw::getStrokeAntialias — Returns the current stroke antialias setting
- ImagickDraw::getStrokeColor — Returns the color used for stroking object outlines
- ImagickDraw::getStrokeDashArray — Returns an array representing the pattern of dashes and gaps used to stroke paths
- ImagickDraw::getStrokeDashOffset — Returns the offset into the dash pattern to start the dash
- ImagickDraw::getStrokeLineCap — Returns the shape to be used at the end of open subpaths when they are stroked
- ImagickDraw::getStrokeLineJoin — Returns the shape to be used at the corners of paths when they are stroked
- ImagickDraw::getStrokeMiterLimit — Returns the stroke miter limit
- ImagickDraw::getStrokeOpacity — Returns the opacity of stroked object outlines
- ImagickDraw::getStrokeWidth — Returns the width of the stroke used to draw object outlines
- ImagickDraw::getTextAlignment — Returns the text alignment
- ImagickDraw::getTextAntialias — Returns the current text antialias setting
- ImagickDraw::getTextDecoration — Returns the text decoration
- ImagickDraw::getTextEncoding — Returns the code set used for text annotations
- ImagickDraw::getTextInterlineSpacing — Gets the text interline spacing
- ImagickDraw::getTextInterwordSpacing — Gets the text interword spacing
- ImagickDraw::getTextKerning — Gets the text kerning
- ImagickDraw::getTextUnderColor — Returns the text under color
- ImagickDraw::getVectorGraphics — Returns a string containing vector graphics
- ImagickDraw::line — Draws a line
- ImagickDraw::matte — Paints on the image's opacity channel
- ImagickDraw::pathClose — Adds a path element to the current path
- ImagickDraw::pathCurveToAbsolute — Draws a cubic Bezier curve
- ImagickDraw::pathCurveToQuadraticBezierAbsolute — Draws a quadratic Bezier curve
- ImagickDraw::pathCurveToQuadraticBezierRelative — Draws a quadratic Bezier curve
- ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Draws a quadratic Bezier curve
- ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Draws a quadratic Bezier curve
- ImagickDraw::pathCurveToRelative — Draws a cubic Bezier curve
- ImagickDraw::pathCurveToSmoothAbsolute — Draws a cubic Bezier curve
- ImagickDraw::pathCurveToSmoothRelative — Draws a cubic Bezier curve
- ImagickDraw::pathEllipticArcAbsolute — Draws an elliptical arc
- ImagickDraw::pathEllipticArcRelative — Draws an elliptical arc
- ImagickDraw::pathFinish — Terminates the current path
- ImagickDraw::pathLineToAbsolute — Draws a line path
- ImagickDraw::pathLineToHorizontalAbsolute — Draws a horizontal line path
- ImagickDraw::pathLineToHorizontalRelative — Draws a horizontal line
- ImagickDraw::pathLineToRelative — Draws a line path
- ImagickDraw::pathLineToVerticalAbsolute — Draws a vertical line
- ImagickDraw::pathLineToVerticalRelative — Draws a vertical line path
- ImagickDraw::pathMoveToAbsolute — Starts a new sub-path
- ImagickDraw::pathMoveToRelative — Starts a new sub-path
- ImagickDraw::pathStart — Declares the start of a path drawing list
- ImagickDraw::point — Draws a point
- ImagickDraw::polygon — Draws a polygon
- ImagickDraw::polyline — Draws a polyline
- ImagickDraw::pop — Destroys the current ImagickDraw in the stack, and returns to the previously pushed ImagickDraw
- ImagickDraw::popClipPath — Terminates a clip path definition
- ImagickDraw::popDefs — Terminates a definition list
- ImagickDraw::popPattern — Terminates a pattern definition
- ImagickDraw::push — Clones the current ImagickDraw and pushes it to the stack
- ImagickDraw::pushClipPath — Starts a clip path definition
- ImagickDraw::pushDefs — Indicates that following commands create named elements for early processing
- ImagickDraw::pushPattern — Indicates that subsequent commands up to a ImagickDraw::opPattern() command comprise the definition of a named pattern
- ImagickDraw::rectangle — Draws a rectangle
- ImagickDraw::render — Renders all preceding drawing commands onto the image
- ImagickDraw::resetVectorGraphics — Resets the vector graphics
- ImagickDraw::rotate — Applies the specified rotation to the current coordinate space
- ImagickDraw::roundRectangle — Draws a rounded rectangle
- ImagickDraw::scale — Adjusts the scaling factor
- ImagickDraw::setClipPath — Associates a named clipping path with the image
- ImagickDraw::setClipRule — Set the polygon fill rule to be used by the clipping path
- ImagickDraw::setClipUnits — Sets the interpretation of clip path units
- ImagickDraw::setFillAlpha — Sets the opacity to use when drawing using the fill color or fill texture
- ImagickDraw::setFillColor — Sets the fill color to be used for drawing filled objects
- ImagickDraw::setFillOpacity — Sets the opacity to use when drawing using the fill color or fill texture
- ImagickDraw::setFillPatternURL — Sets the URL to use as a fill pattern for filling objects
- ImagickDraw::setFillRule — Sets the fill rule to use while drawing polygons
- ImagickDraw::setFont — Sets the fully-specified font to use when annotating with text
- ImagickDraw::setFontFamily — Sets the font family to use when annotating with text
- ImagickDraw::setFontSize — Sets the font pointsize to use when annotating with text
- ImagickDraw::setFontStretch — Sets the font stretch to use when annotating with text
- ImagickDraw::setFontStyle — Sets the font style to use when annotating with text
- ImagickDraw::setFontWeight — Sets the font weight
- ImagickDraw::setGravity — Sets the text placement gravity
- ImagickDraw::setResolution — Sets the resolution
- ImagickDraw::setStrokeAlpha — Specifies the opacity of stroked object outlines
- ImagickDraw::setStrokeAntialias — Controls whether stroked outlines are antialiased
- ImagickDraw::setStrokeColor — Sets the color used for stroking object outlines
- ImagickDraw::setStrokeDashArray — Specifies the pattern of dashes and gaps used to stroke paths
- ImagickDraw::setStrokeDashOffset — Specifies the offset into the dash pattern to start the dash
- ImagickDraw::setStrokeLineCap — Specifies the shape to be used at the end of open subpaths when they are stroked
- ImagickDraw::setStrokeLineJoin — Specifies the shape to be used at the corners of paths when they are stroked
- ImagickDraw::setStrokeMiterLimit — Specifies the miter limit
- ImagickDraw::setStrokeOpacity — Specifies the opacity of stroked object outlines
- ImagickDraw::setStrokePatternURL — Sets the pattern used for stroking object outlines
- ImagickDraw::setStrokeWidth — Sets the width of the stroke used to draw object outlines
- ImagickDraw::setTextAlignment — Specifies a text alignment
- ImagickDraw::setTextAntialias — Controls whether text is antialiased
- ImagickDraw::setTextDecoration — Specifies a decoration
- ImagickDraw::setTextEncoding — Specifies the text code set
- ImagickDraw::setTextInterlineSpacing — Sets the text interline spacing
- ImagickDraw::setTextInterwordSpacing — Sets the text interword spacing
- ImagickDraw::setTextKerning — Sets the text kerning
- ImagickDraw::setTextUnderColor — Specifies the color of a background rectangle
- ImagickDraw::setVectorGraphics — Sets the vector graphics
- ImagickDraw::setViewbox — Sets the overall canvas size
- ImagickDraw::skewX — Skews the current coordinate system in the horizontal direction
- ImagickDraw::skewY — Skews the current coordinate system in the vertical direction
- ImagickDraw::translate — Applies a translation to the current coordinate system

# The ImagickDrawException class

(PECL imagick 3)

## Einführung

## Klassenbeschreibung

class ImagickDrawException extends Exception implements Throwable {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
/* Geerbte Methoden */
}

# The ImagickException class

(PECL imagick 3)

## Einführung

## Klassenbeschreibung

class ImagickException extends Exception implements Throwable {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
/* Geerbte Methoden */
}

# Die Klasse ImagickKernel

(PECL imagick >= 3.3.0)

## Einführung

## Klassenbeschreibung

class ImagickKernel {
/* Methoden */
public function addKernel(ImagickKernel `$ImagickKernel`): void
public function addUnityKernel(float `$scale`): void
public static function fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel
public static function fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel
public function getMatrix(): array
public function scale(float `$scale`, int `$normalizeFlag` = ?): void
public function separate(): array
}

# ImagickKernel::addKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addKernel — Attach another kernel to a kernel list

### Beschreibung

public function ImagickKernel::addKernel(ImagickKernel `$ImagickKernel`): void

Attach another kernel to this kernel to allow them to both be applied in a single morphology or filter function. Returns the new combined kernel.

### Parameter-Liste

`ImagickKernel`

### Rückgabewerte

### Beispiele

Beispiel #1 ImagickKernel::addKernel()

    <?php
    function addKernel($imagePath) {
        $matrix1 = [
            [-1, -1, -1],
            [ 0,  0,  0],
            [ 1,  1,  1],
        ];

        $matrix2 = [
            [-1,  0,  1],
            [-1,  0,  1],
            [-1,  0,  1],
        ];

        $kernel1 = ImagickKernel::fromMatrix($matrix1);
        $kernel2 = ImagickKernel::fromMatrix($matrix2);
        $kernel1->addKernel($kernel2);

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->filter($kernel1);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickKernel::addUnityKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addUnityKernel — Adds a Unity Kernel to the kernel list

### Beschreibung

public function ImagickKernel::addUnityKernel(float `$scale`): void

Adds a given amount of the 'Unity' Convolution Kernel to the given pre-scaled and normalized Kernel. This in effect adds that amount of the original image into the resulting convolution kernel. The resulting effect is to convert the defined kernels into blended soft-blurs, unsharp kernels or into sharpening kernels.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 ImagickKernel::addUnityKernel()

    <?php

        function renderKernelTable($matrix) {
            $output = "<table class='infoTable'>";

            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output = "Before adding unity kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());
        $kernel->addUnityKernel(0.5);
        $output .= "After adding unity kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output .= "After renormalizing kernel: <br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        echo $output;

    ?>

Beispiel #2 ImagickKernel::addUnityKernel()

    <?php
    function addUnityKernel($imagePath) {

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = ImagickKernel::fromMatrix($matrix);

        $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
        $kernel->addUnityKernel(0.5);

        $imagick = new \Imagick(realpath($imagePath));
        $imagick->filter($kernel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();

    }

    ?>

# ImagickKernel::fromBuiltIn

(PECL imagick >= 3.3.0)

ImagickKernel::fromBuiltIn — Create a kernel from a builtin in kernel

### Beschreibung

public static function ImagickKernel::fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel

Create a kernel from a builtin in kernel. See http://www.imagemagick.org/Usage/morphology/#kernel for examples. Currently the 'rotation' symbols are not supported. Example: $diamondKernel = ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "2");

### Parameter-Liste

`kerneltype`

  The type of kernel to build e.g. \Imagick::KERNEL_DIAMOND

`kernelString`

  A string that describes the parameters e.g. "4,2.5"

### Rückgabewerte

### Beispiele

Beispiel #1 ImagickKernel::fromBuiltin()

    <?php

    function renderKernel(ImagickKernel $imagickKernel) {
        $matrix = $imagickKernel->getMatrix();

        $imageMargin = 20;

        $tileSize = 20;
        $tileSpace = 4;
        $shadowSigma = 4;
        $shadowDropX = 20;
        $shadowDropY = 0;

        $radius = ($tileSize / 2) * 0.9;

        $rows = count($matrix);
        $columns = count($matrix[0]);

        $imagickDraw = new \ImagickDraw();

        $imagickDraw->setFillColor('#afafaf');
        $imagickDraw->setStrokeColor('none');

        $imagickDraw->translate($imageMargin, $imageMargin);
        $imagickDraw->push();

        ksort($matrix);

        foreach ($matrix as $row) {
            ksort($row);
            $imagickDraw->push();
            foreach ($row as $cell) {
                if ($cell !== false) {
                    $color = intval(255 * $cell);
                    $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                    $imagickDraw->setFillColor($colorString);
                    $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
                }
                $imagickDraw->translate(($tileSize + $tileSpace), 0);
            }
            $imagickDraw->pop();
            $imagickDraw->translate(0, ($tileSize + $tileSpace));
        }

        $imagickDraw->pop();

        $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
        $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

        $imagickDraw->push();
        $imagickDraw->translate($width/2 , $height/2);
        $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
        $imagickDraw->setStrokeColor('white');
        $imagickDraw->circle(0, 0, $radius - 1, 0);
        $imagickDraw->setStrokeColor('black');
        $imagickDraw->circle(0, 0, $radius, 0);
        $imagickDraw->pop();

        $canvasWidth = $width + (2 * $imageMargin);
        $canvasHeight = $height + (2 * $imageMargin);

        $kernel = new \Imagick();
        $kernel->newPseudoImage(
            $canvasWidth,
            $canvasHeight,
            'canvas:none'
        );

        $kernel->setImageFormat('png');
        $kernel->drawImage($imagickDraw);

        /* create drop shadow on it's own layer */
        $canvas = $kernel->clone();
        $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
        $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

        $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
        $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

        /* composite original text_layer onto shadow_layer */
        $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
        $canvas->setImageFormat('png');

        return $canvas;
    }

    function createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
        $string = '';

        if ($kernelFirstTerm != false && strlen(trim($kernelFirstTerm)) != 0) {
            $string .= $kernelFirstTerm;

            if ($kernelSecondTerm != false && strlen(trim($kernelSecondTerm)) != 0) {
                $string .= ','.$kernelSecondTerm;
                if ($kernelThirdTerm != false && strlen(trim($kernelThirdTerm)) != 0) {
                    $string .= ','.$kernelThirdTerm;
                }
            }
        }

        $kernel = ImagickKernel::fromBuiltIn(
            $kernelType,
            $string
        );

        return $kernel;
    }

    function fromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm) {
        $diamondKernel = createFromBuiltin($kernelType, $kernelFirstTerm, $kernelSecondTerm, $kernelThirdTerm);
        $imagick = renderKernel($diamondKernel);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    fromBuiltin(\Imagick::KERNEL_DIAMOND, 2, false, false);

    ?>

# ImagickKernel::fromMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::fromMatrix — Create a kernel from a 2d matrix of values

### Beschreibung

public static function ImagickKernel::fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel

Create a kernel from an 2d matrix of values. Each value should either be a float (if the element should be used) or 'false' if the element should be skipped. For matrices that are odd sizes in both dimensions the origin pixel will default to the centre of the kernel. For all other kernel sizes the origin pixel must be specified.

### Parameter-Liste

`array`

  A matrix (i.e. 2d array) of values that define the kernel. Each element should be either a float value, or FALSE if that element shouldn't be used by the kernel.

`array`

  Which element of the kernel should be used as the origin pixel. e.g. For a 3x3 matrix specifying the origin as [2, 2] would specify that the bottom right element should be the origin pixel.

### Rückgabewerte

The generated ImagickKernel.

### Beispiele

Beispiel #1 ImagickKernel::fromMatrix()

    <?php

    function renderKernel(ImagickKernel $imagickKernel) {
        $matrix = $imagickKernel->getMatrix();

        $imageMargin = 20;

        $tileSize = 20;
        $tileSpace = 4;
        $shadowSigma = 4;
        $shadowDropX = 20;
        $shadowDropY = 0;

        $radius = ($tileSize / 2) * 0.9;

        $rows = count($matrix);
        $columns = count($matrix[0]);

        $imagickDraw = new \ImagickDraw();

        $imagickDraw->setFillColor('#afafaf');
        $imagickDraw->setStrokeColor('none');

        $imagickDraw->translate($imageMargin, $imageMargin);
        $imagickDraw->push();

        ksort($matrix);

        foreach ($matrix as $row) {
            ksort($row);
            $imagickDraw->push();
            foreach ($row as $cell) {
                if ($cell !== false) {
                    $color = intval(255 * $cell);
                    $colorString = sprintf("rgb(%f, %f, %f)", $color, $color, $color);
                    $imagickDraw->setFillColor($colorString);
                    $imagickDraw->rectangle(0, 0, $tileSize, $tileSize);
                }
                $imagickDraw->translate(($tileSize + $tileSpace), 0);
            }
            $imagickDraw->pop();
            $imagickDraw->translate(0, ($tileSize + $tileSpace));
        }

        $imagickDraw->pop();

        $width = ($columns * $tileSize) + (($columns - 1) * $tileSpace);
        $height = ($rows * $tileSize) + (($rows - 1) * $tileSpace);

        $imagickDraw->push();
        $imagickDraw->translate($width/2 , $height/2);
        $imagickDraw->setFillColor('rgba(0, 0, 0, 0)');
        $imagickDraw->setStrokeColor('white');
        $imagickDraw->circle(0, 0, $radius - 1, 0);
        $imagickDraw->setStrokeColor('black');
        $imagickDraw->circle(0, 0, $radius, 0);
        $imagickDraw->pop();

        $canvasWidth = $width + (2 * $imageMargin);
        $canvasHeight = $height + (2 * $imageMargin);

        $kernel = new \Imagick();
        $kernel->newPseudoImage(
            $canvasWidth,
            $canvasHeight,
            'canvas:none'
        );

        $kernel->setImageFormat('png');
        $kernel->drawImage($imagickDraw);

        /* create drop shadow on it's own layer */
        $canvas = $kernel->clone();
        $canvas->setImageBackgroundColor(new \ImagickPixel('rgb(0, 0, 0)'));
        $canvas->shadowImage(100, $shadowSigma, $shadowDropX, $shadowDropY);

        $canvas->setImagePage($canvasWidth, $canvasHeight, -5, -5);
        $canvas->cropImage($canvasWidth, $canvasHeight, 0, 0);

        /* composite original text_layer onto shadow_layer */
        $canvas->compositeImage($kernel, \Imagick::COMPOSITE_OVER, 0, 0);
        $canvas->setImageFormat('png');

        return $canvas;
    }

    function createFromMatrix() {
        $matrix = [
            [0.5, 0, 0.2],
            [0, 1, 0],
            [0.9, 0, false],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);

        return $kernel;
    }

    function fromMatrix() {
        $kernel = createFromMatrix();
        $imagick = renderKernel($kernel);

        header("Content-Type: image/png");
        echo $imagick->getImageBlob();
    }

    ?>

# ImagickKernel::getMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::getMatrix — Get the 2d matrix of values used in this kernel

### Beschreibung

public function ImagickKernel::getMatrix(): array

Get the 2d matrix of values used in this kernel. The elements are either float for elements that are used or 'false' if the element should be skipped.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

A matrix (2d array) of the values that represent the kernel.

### Beispiele

Beispiel #1 ImagickKernel::getMatrix()

    <?php

    function renderKernelTable($matrix) {
        $output = "<table class='infoTable'>";

        foreach ($matrix as $row) {
            $output .= "<tr>";
            foreach ($row as $cell) {
                $output .= "<td style='text-align:left'>";
                if ($cell === false) {
                    $output .= "false";
                }
                else {
                    $output .= round($cell, 3);
                }
                $output .= "</td>";
            }
            $output .= "</tr>";
        }

        $output .= "</table>";

        return $output;
    }

        $output = "The built-in kernel name 'ring' with parameters of '2,3.5':<br/>";
        $kernel = \ImagickKernel::fromBuiltIn(
            \Imagick::KERNEL_RING,
            "2,3.5"
        );
        $matrix = $kernel->getMatrix();
        $output .= renderKernelTable($matrix);

        echo $output;

    ?>

# ImagickKernel::scale

(PECL imagick >= 3.3.0)

ImagickKernel::scale — Scales a kernel list by the given amount

### Beschreibung

public function ImagickKernel::scale(float `$scale`, int `$normalizeFlag` = ?): void

Scales the given kernel list by the given amount, with or without normalization of the sum of the kernel values (as per given flags). The exact behaviour of this function depends on the normalization type being used please see http://www.imagemagick.org/api/morphology.php#ScaleKernelInfo for details.

### Parameter-Liste

`scale`

`normalizeFlag`

  - Imagick::NORMALIZE_KERNEL_NONE
  - Imagick::NORMALIZE_KERNEL_VALUE
  - Imagick::NORMALIZE_KERNEL_CORRELATE
  - Imagick::NORMALIZE_KERNEL_PERCENT

### Rückgabewerte

### Beispiele

Beispiel #1 ImagickKernel::scale()

    <?php

        function renderKernelTable($matrix) {
            $output = "<table class='infoTable'>";

            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $output = "";

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernelClone = clone $kernel;

        $output .= "Start kernel<br/>";
        $output .= renderKernelTable($kernel->getMatrix());

        $output .= "Scaling with NORMALIZE_KERNEL_VALUE. The  <br/>";
        $kernel->scale(2, \Imagick::NORMALIZE_KERNEL_VALUE);
        $output .= renderKernelTable($kernel->getMatrix());

        $kernel = clone $kernelClone;
        $output .= "Scaling by percent<br/>";
        $kernel->scale(2, \Imagick::NORMALIZE_KERNEL_PERCENT);
        $output .= renderKernelTable($kernel->getMatrix());

        $matrix2 = [
            [-1, -1, 1],
            [ -1, false,  1],
            [1, 1, 1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix2);
        $output .= "Scaling by correlate<br/>";
        $kernel->scale(1, \Imagick::NORMALIZE_KERNEL_CORRELATE);
        $output .= renderKernelTable($kernel->getMatrix());

        return $output;
    ?>

# ImagickKernel::separate

(PECL imagick >= 3.3.0)

ImagickKernel::separate — Separates a linked set of kernels and returns an array of ImagickKernels

### Beschreibung

public function ImagickKernel::separate(): array

Separates a linked set of kernels and returns an array of ImagickKernels.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

### Beispiele

Beispiel #1 ImagickKernel::separate()

    <?php

        function renderKernelTable($matrix) {

            $output = "<table class='infoTable'>";
            foreach ($matrix as $row) {
                $output .= "<tr>";
                foreach ($row as $cell) {
                    $output .= "<td style='text-align:left'>";
                    if ($cell === false) {
                        $output .= "false";
                    }
                    else {
                        $output .= round($cell, 3);
                    }
                    $output .= "</td>";
                }
                $output .= "</tr>";
            }

            $output .= "</table>";

            return $output;
        }

        $matrix = [
            [-1, 0, -1],
            [ 0, 4,  0],
            [-1, 0, -1],
        ];

        $kernel = \ImagickKernel::fromMatrix($matrix);
        $kernel->scale(4, \Imagick::NORMALIZE_KERNEL_VALUE);
        $diamondKernel = \ImagickKernel::fromBuiltIn(
            \Imagick::KERNEL_DIAMOND,
            "2"
        );

        $kernel->addKernel($diamondKernel);

        $kernelList = $kernel->separate();

        $output = '';
        $count = 0;
        foreach ($kernelList as $kernel) {
            $output .= "<br/>Kernel $count<br/>";
            $output .= renderKernelTable($kernel->getMatrix());
            $count++;
        }

        return $output;

    ?>

## Inhaltsverzeichnis

- ImagickKernel::addKernel — Attach another kernel to a kernel list
- ImagickKernel::addUnityKernel — Adds a Unity Kernel to the kernel list
- ImagickKernel::fromBuiltIn — Create a kernel from a builtin in kernel
- ImagickKernel::fromMatrix — Create a kernel from a 2d matrix of values
- ImagickKernel::getMatrix — Get the 2d matrix of values used in this kernel
- ImagickKernel::scale — Scales a kernel list by the given amount
- ImagickKernel::separate — Separates a linked set of kernels and returns an array of ImagickKernels

# Die Klasse ImagickKernelException

(PECL imagick 3)

## Einführung

## Klassenbeschreibung

class ImagickKernelException extends Exception {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
/* Geerbte Methoden */
}

# Die Klasse ImagickPixel

(PECL imagick 2, PECL imagick 3)

## Klassenbeschreibung

class ImagickPixel {
public function clear(): bool
public function __construct(string `$color` = ?)
public function destroy(): bool
public function getColor(int `$normalized` = 0): array
public function getColorAsString(): string
public function getColorCount(): int
public function getColorQuantum(): array
public function getColorValue(int `$color`): float
public function getColorValueQuantum(int `$color`): int|float
public function getHSL(): array
public function getIndex(): int
public function isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool
public function isSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function setColor(string `$color`): bool
public function setcolorcount(int `$colorCount`): bool
public function setColorValue(int `$color`, float `$value`): bool
public function setColorValueQuantum(int `$color`, int|float `$value`): bool
public function setHSL(float `$hue`, float `$saturation`, float `$luminosity`): bool
public function setIndex(int `$index`): bool
}

# ImagickPixel::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixel::clear — Clears resources associated with this object

### Beschreibung

public function ImagickPixel::clear(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Clears the ImagickPixel object, leaving it in a fresh state. This also unsets any color associated with the object.

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickPixel::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixel::__construct — The ImagickPixel constructor

### Beschreibung

public function ImagickPixel::__construct(string `$color` = ?)
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Constructs an ImagickPixel object. If a color is specified, the object is constructed and then initialised with that color before being returned.

### Parameter-Liste

`color`

  The optional color string to use as the initial value of this object.

### Rückgabewerte

Returns an ImagickPixel object on success, throwing ImagickPixelException on failure.

### Beispiele

Beispiel #1 ImagickPixel::construct()

    <?php
    function construct() {

        $columns = 4;

        $exampleColors = array(
            "rgba(100%, 0%, 0%, 0.5)",
            "hsb(33.3333%, 100%,  75%)", // medium green
            "hsl(120, 255,   191.25)", //medium green
            "graya(50%, 0.5)", //  semi-transparent mid gray
            "LightCoral", "none", //"cmyk(0.9, 0.48, 0.83, 0.50)",
            "#f00", //  #rgb
            "#ff0000", //  #rrggbb
            "#ff0000ff", //  #rrggbbaa
            "#ffff00000000", //  #rrrrggggbbbb
            "#ffff00000000ffff", //  #rrrrggggbbbbaaaa
            "rgb(255, 0, 0)", //  an integer in the range 0—255 for each component
            "rgb(100.0%, 0.0%, 0.0%)", //  a float in the range 0—100% for each component
            "rgb(255, 0, 0)", //  range 0 - 255
            "rgba(255, 0, 0, 1.0)", //  the same, with an explicit alpha value
            "rgb(100%, 0%, 0%)", //  range 0.0% - 100.0%
            "rgba(100%, 0%, 0%, 1.0)", //  the same, with an explicit alpha value
        );

        $draw = new \ImagickDraw();
        $count = 0;
        $black = new \ImagickPixel('rgb(0, 0, 0)');

        foreach ($exampleColors as $exampleColor) {
            $color = new \ImagickPixel($exampleColor);

            $draw->setstrokewidth(1.0);
            $draw->setStrokeColor($black);
            $draw->setFillColor($color);
            $offsetX = ($count % $columns) * 50 + 5;
            $offsetY = intval($count / $columns) * 50 + 5;
            $draw->rectangle(0 + $offsetX, 0 + $offsetY, 40 + $offsetX, 40 + $offsetY);
            $count++;
        }

        $image = new \Imagick();
        $image->newImage(350, 350, "blue");
        $image->setImageFormat("png");
        $image->drawImage($draw);
        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixel::destroy — Deallocates resources associated with this object

### Beschreibung

public function ImagickPixel::destroy(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Deallocates any resources used by the ImagickPixel object, and unsets any associated color. The object should not be used after the destroy function has been called.

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickPixel::getColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColor — Returns the color

### Beschreibung

public function ImagickPixel::getColor(int `$normalized` = 0): array

Returns the color described by the ImagickPixel object, as an array. If the color has an opacity channel set, this is provided as a fourth value in the list.

### Parameter-Liste

`normalized`

  Normalize the color values. Possible values are `0`, `1` or `2`.

  List of possible values for `normalized`
  `normalized` | Description
  --- | ---
  `0` | The RGB values are returned as ints in the range `0` to `255` (inclusive.) The alpha value is returned as int and is either `0` or `1`.
  `1` | The RGBA values are returned as floats in the range `0` to `1` (inclusive.)
  `2` | The RGBA values are returned as ints in the range `0` to `255` (inclusive.)

### Rückgabewerte

An array of channel values. Throws ImagickPixelException on error.

### Beispiele

Beispiel #1 Basic Imagick::getColor() usage

    <?php

    //Create an ImagickPixel with the predefined color 'brown'
    $color = new ImagickPixel('brown');

    //Set the color to have an alpha of 25%
    $color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

    $colorInfo = $color->getColor();

    echo "Standard values".PHP_EOL;
    print_r($colorInfo);

    $colorInfo = $color->getColor(1);

    echo "Normalized values:".PHP_EOL;
    print_r($colorInfo);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Standard values
    Array
    (
        [r] => 165
        [g] => 42
        [b] => 42
        [a] => 0
    )
    Normalized values:
    Array
    (
        [r] => 0.64705882352941
        [g] => 0.16470588235294
        [b] => 0.16470588235294
        [a] => 0.25000381475547
    )

# ImagickPixel::getColorAsString

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

ImagickPixel::getColorAsString — Returns the color as a string

### Beschreibung

public function ImagickPixel::getColorAsString(): string

Returns the color of the ImagickPixel object as a string.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the color of the ImagickPixel object as a string.

### Beispiele

Beispiel #1 Basic Imagick::getColorAsString() usage

    <?php

    //Create an ImagickPixel with the predefined color 'brown'
    $color = new ImagickPixel('brown');

    $color->setColorValue(Imagick::COLOR_ALPHA, 64 / 256.0);

    $colorInfo = $color->getColorAsString();

    print_r($colorInfo);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    rgb(165,42,42)

### Anmerkungen

> Hinweis: Alpha not returned

> This function does not return the alpha value of the color in the string.

# ImagickPixel::getColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorCount — Returns the color count associated with this color

### Beschreibung

public function ImagickPixel::getColorCount(): int

Returns the color count associated with this color.

The color count is the number of pixels in the image that have the same color as this ImagickPixel.

ImagickPixel::getColorCount appears to only work for ImagickPixel objects created through Imagick::getImageHistogram()

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the color count as an integer on success, throws ImagickPixelException on failure.

### Beispiele

Beispiel #1 ImagickPixel getColorCount()

    <?php
        $imagick = new \Imagick();
        $imagick->newPseudoImage(640, 480, "magick:logo");
        $histogramElements = $imagick->getImageHistogram();
        $lastColor = array_pop($histogramElements);
        echo "Last pixel color count is: ".$lastColor->getColorCount();
    ?>

The output for this will be similar to:

    Last pixel color count is: 256244

# ImagickPixel::getColorQuantum

(No version information available, might only be in Git)

ImagickPixel::getColorQuantum — Returns the color of the pixel in an array as Quantum values

### Beschreibung

public function ImagickPixel::getColorQuantum(): array

Returns the color of the pixel in an array as Quantum values. If ImageMagick was compiled as HDRI these will be floats, otherwise they will be integers.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array with keys `"r"`, `"g"`, `"b"`, `"a"`.

# ImagickPixel::getColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorValue — Gets the normalized value of the provided color channel

### Beschreibung

public function ImagickPixel::getColorValue(int `$color`): float

Retrieves the value of the color channel specified, as a floating-point number between 0 and 1.

### Parameter-Liste

`color`

  The color to get the value of, specified as one of the Imagick color constants. This can be one of the RGB colors, CMYK colors, alpha and opacity e.g (Imagick::COLOR_BLUE, Imagick::COLOR_MAGENTA).

### Rückgabewerte

The value of the channel, as a normalized floating-point number, throwing ImagickPixelException on error.

### Beispiele

Beispiel #1 Basic Imagick::getColorValue() usage

    <?php

    $color = new ImagickPixel('rgba(90%, 20%, 20%, 0.75)');

    echo "Alpha value is ".$color->getColorValue(Imagick::COLOR_ALPHA).PHP_EOL;
    echo "".PHP_EOL;
    echo "Red value is ".$color->getColorValue(Imagick::COLOR_RED).PHP_EOL;
    echo "Green value is ".$color->getColorValue(Imagick::COLOR_GREEN).PHP_EOL;
    echo "Blue value is ".$color->getColorValue(Imagick::COLOR_BLUE).PHP_EOL;
    echo "".PHP_EOL;
    echo "Cyan value is ".$color->getColorValue(Imagick::COLOR_CYAN).PHP_EOL;
    echo "Magenta value is ".$color->getColorValue(Imagick::COLOR_MAGENTA).PHP_EOL;
    echo "Yellow value is ".$color->getColorValue(Imagick::COLOR_YELLOW).PHP_EOL;
    echo "Black value is ".$color->getColorValue(Imagick::COLOR_BLACK).PHP_EOL;

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Alpha value is 0.74999618524453

    Red value is 0.90000762951095
    Green value is 0.2
    Blue value is 0.2

    Cyan value is 0.90000762951095
    Magenta value is 0.2
    Yellow value is 0.2
    Black value is 0

# ImagickPixel::getColorValueQuantum

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getColorValueQuantum — Gets the quantum value of a color in the ImagickPixel

### Beschreibung

public function ImagickPixel::getColorValueQuantum(int `$color`): int|float

Gets the quantum value of a color in the ImagickPixel. Return value is a float if ImageMagick was compiled with HDRI, otherwise an integer.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

The quantum value of the color element. Float if ImageMagick was compiled with HDRI, otherwise an int.

### Beispiele

Beispiel #1 ImagickPixel::getColorValueQuantum()

    <?php
            $color = new \ImagickPixel('rgb(128, 5, 255)');
            $colorRed = $color->getColorValueQuantum(\Imagick::COLOR_RED);
            $colorGreen = $color->getColorValueQuantum(\Imagick::COLOR_GREEN);
            $colorBlue = $color->getColorValueQuantum(\Imagick::COLOR_BLUE);
            $colorAlpha = $color->getColorValueQuantum(\Imagick::COLOR_ALPHA);

            printf(
                "Red: %s Green: %s  Blue %s Alpha: %s",
                $colorRed,
                $colorGreen,
                $colorBlue,
                $colorAlpha
            );

    ?>

# ImagickPixel::getHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getHSL — Returns the normalized HSL color of the ImagickPixel object

### Beschreibung

public function ImagickPixel::getHSL(): array

Returns the normalized HSL color described by the ImagickPixel object, with each of the three values as floating point numbers between 0.0 and 1.0.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the HSL value in an array with the keys "hue", "saturation", and "luminosity". Throws ImagickPixelException on failure.

### Beispiele

Beispiel #1 Basic Imagick::getHSL() example

    <?php

    $color = new ImagickPixel('rgb(90%, 10%, 10%)');

    $colorInfo = $color->getHSL();

    print_r($colorInfo);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [hue] => 0
        [saturation] => 0.80001220740379
        [luminosity] => 0.50000762951095
    )

### Anmerkungen

> Hinweis:

> Available with ImageMagick library version 6.2.9 and higher.

# ImagickPixel::getIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getIndex — Gets the colormap index of the pixel wand

### Beschreibung

public function ImagickPixel::getIndex(): int

Gets the colormap index of the pixel wand.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

# ImagickPixel::isPixelSimilar

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilar — Check the distance between this color and another

### Beschreibung

public function ImagickPixel::isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool

Checks the distance between the color described by this ImagickPixel object and that of the provided object, by plotting their RGB values on the color cube. If the distance between the two points is less than the fuzz value given, the colors are similar. This method replaces ImagickPixel::isSimilar() and correctly normalises the fuzz value to ImageMagick QuantumRange.

### Parameter-Liste

`color`

  The ImagickPixel object to compare this object against.

`fuzz`

  The maximum distance within which to consider these colors as similar. The theoretical maximum for this value is the square root of three (1.732).

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickPixel::isPixelSimilarQuantum

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilarQuantum — Returns whether two colors differ by less than the specified distance

### Beschreibung

public function ImagickPixel::isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool

Returns true if the distance between two colors is less than the specified distance. The fuzz value should be in the range 0-QuantumRange. The maximum value represents the longest possible distance in the colorspace. e.g. from RGB(0, 0, 0) to RGB(255, 255, 255) for the RGB colorspace

### Parameter-Liste

`color`

`fuzz`

### Rückgabewerte

# ImagickPixel::isSimilar

(PECL imagick 2, PECL imagick 3)

ImagickPixel::isSimilar — Check the distance between this color and another

### Beschreibung

public function ImagickPixel::isSimilar(ImagickPixel `$color`, float `$fuzz`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Checks the distance between the color described by this ImagickPixel object and that of the provided object, by plotting their RGB values on the color cube. If the distance between the two points is less than the fuzz value given, the colors are similar. Deprecated in favour of ImagickPixel::isPixelSimilar().

### Parameter-Liste

`color`

  The ImagickPixel object to compare this object against.

`fuzz`

  The maximum distance within which to consider these colors as similar. The theoretical maximum for this value is the square root of three (1.732).

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickPixel::isSimilar()

    <?php
            // The tests below are written with the maximum distance expressed as 255
            // so we need to scale them by the square root of 3 - the diagonal length
            // of a unit cube.
            $root3 = 1.732050807568877;

            $tests = array(
                ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',   9 / $root3,         false,],
                ['rgb(245, 0, 0)',      'rgb(255, 0, 0)',  10 / $root3,         true,],
                ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',     9 / $root3,         false,],
                ['rgb(0, 0, 0)',        'rgb(7, 7, 0)',    10 / $root3,         true,],
                ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)', 9 / $root3,         false,],
                ['rgba(0, 0, 0, 1)',    'rgba(7, 7, 0, 1)',    10 / $root3,     true,],
                ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   7 / $root3,     false,],
                ['rgb(128, 128, 128)',  'rgb(128, 128, 120)',   8 / $root3,     true,],
                ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   254.9,          false,],
                ['rgb(0, 0, 0)',        'rgb(255, 255, 255)',   255,            true,],
                ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     254.9,          false,],
                ['rgb(255, 0, 0)',      'rgb(0, 255, 255)',     255,            true,],
                ['black',               'rgba(0, 0, 0)',        0.0,            true],
                ['black',               'rgba(10, 0, 0, 1.0)',  10.0 / $root3,  true],);

            $output = "<table width='100%' class='infoTable'><thead>
                    <tr>
                    <th>
                    Color 1
                    </th>
                    <th>
                    Color 2
                    </th>
                    <th>
                        Test distance * 255
                    </th>
                    <th>
                        Is within distance
                    </th>
                    </tr>
            </thead>";

            $output .= "<tbody>";

            foreach ($tests as $testInfo) {
                $color1 = $testInfo[0];
                $color2 = $testInfo[1];
                $distance = $testInfo[2];
                $expectation = $testInfo[3];
                $testDistance = ($distance / 255.0);

                $color1Pixel = new \ImagickPixel($color1);
                $color2Pixel = new \ImagickPixel($color2);

                $isSimilar = $color1Pixel->isPixelSimilar($color2Pixel, $testDistance);

                if ($isSimilar !== $expectation) {
                    echo "Test distance failed. Color [$color1] compared to color [$color2] is not within distance $testDistance FAILED.".NL;
                }

                $layout = "<tr>
                    <td>%s</td>
                    <td>%s</td>
                    <td>%s</td>
                    <td style='text-align: center;'>%s</td>
                </tr>";

                $output .= sprintf(
                    $layout,
                    $color1,
                    $color2,
                    $distance,
                    $isSimilar ? 'yes' : 'no'
                );
            }

            $output .= "</tbody></table>";

            return $output;

    ?>

# ImagickPixel::setColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColor — Sets the color

### Beschreibung

public function ImagickPixel::setColor(string `$color`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the color described by the ImagickPixel object, with a string (e.g. "blue", "#0000ff", "rgb(0,0,255)", "cmyk(100,100,100,10)", etc.).

### Parameter-Liste

`color`

  The color definition to use in order to initialise the ImagickPixel object.

### Rückgabewerte

Returns `true` if the specified color was set, `false` otherwise.

### Beispiele

Beispiel #1 ImagickPixel::setColor()

    <?php
    function setColor() {
        $draw = new \ImagickDraw();

        $strokeColor = new \ImagickPixel('green');
        $fillColor = new \ImagickPixel();
        $fillColor->setColor('rgba(100%, 75%, 0%, 1.0)');

        $draw->setstrokewidth(3.0);
        $draw->setStrokeColor($strokeColor);
        $draw->setFillColor($fillColor);
        $draw->rectangle(200, 200, 300, 300);

        $image = new \Imagick();
        $image->newImage(500, 500, "SteelBlue2");
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::setColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorCount — Sets the color count associated with this color

### Beschreibung

public function ImagickPixel::setcolorcount(int `$colorCount`): bool

Sets the color count associated with this color.

### Parameter-Liste

`colorCount`

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickPixel::setColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorValue — Sets the normalized value of one of the channels

### Beschreibung

public function ImagickPixel::setColorValue(int `$color`, float `$value`): bool

Sets the value of the specified channel of this object to the provided value, which should be between 0 and 1. This function can be used to provide an opacity channel to an ImagickPixel object.

### Parameter-Liste

`color`

  One of the Imagick color constants e.g. \Imagick::COLOR_GREEN or \Imagick::COLOR_ALPHA.

`value`

  The value to set this channel to, ranging from 0 to 1.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Basic Imagick::setColorValue() usage

    <?php

    $color  = new \ImagickPixel('firebrick');

    $color->setColorValue(Imagick::COLOR_ALPHA, 0.5);

    print_r($color->getcolor(true));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [r] => 0.69803921568627
        [g] => 0.13333333333333
        [b] => 0.13333333333333
        [a] => 0.50000762951095
    )

# ImagickPixel::setColorValueQuantum

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickPixel::setColorValueQuantum — Sets the quantum value of a color element of the ImagickPixel

### Beschreibung

public function ImagickPixel::setColorValueQuantum(int `$color`, int|float `$value`): bool

Sets the quantum value of a color element of the ImagickPixel.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`color`

  Which color element to set e.g. \Imagick::COLOR_GREEN.

`value`

  The quantum value to set the color element to. This should be a float if ImageMagick was compiled with HDRI otherwise an int in the range 0 to Imagick::getQuantum().

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickPixel::setColorValueQuantum()

    <?php
    function setColorValueQuantum() {
        $image = new \Imagick();

        $quantumRange = $image->getQuantumRange();

        $draw = new \ImagickDraw();
        $color = new \ImagickPixel('blue');
        $color->setcolorValueQuantum(\Imagick::COLOR_RED, 128 * $quantumRange['quantumRangeLong'] / 256);

        $draw->setstrokewidth(1.0);
        $draw->setStrokeColor($color);
        $draw->setFillColor($color);
        $draw->rectangle(200, 200, 300, 300);

        $image->newImage(500, 500, "SteelBlue2");
        $image->setImageFormat("png");

        $image->drawImage($draw);

        header("Content-Type: image/png");
        echo $image->getImageBlob();
    }

    ?>

# ImagickPixel::setHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setHSL — Sets the normalized HSL color

### Beschreibung

public function ImagickPixel::setHSL(float `$hue`, float `$saturation`, float `$luminosity`): bool

Sets the color described by the ImagickPixel object using normalized values for hue, saturation and luminosity.

### Parameter-Liste

`hue`

  The normalized value for hue, described as a fractional arc (between 0 and 1) of the hue circle, where the zero value is red.

`saturation`

  The normalized value for saturation, with 1 as full saturation.

`luminosity`

  The normalized value for luminosity, on a scale from black at 0 to white at 1, with the full HS value at 0.5 luminosity.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 Use ImagickPixel::setHSL() to modify a color

    <?php

    //Create an almost pure red color
    $color = new ImagickPixel('rgb(90%, 10%, 10%)');

    //Get it's HSL values
    $colorInfo = $color->getHSL();

    //Rotate the hue by 180 degrees
    $newHue = $colorInfo['hue'] + 0.5;
    if ($newHue > 1) {
        $newHue = $newHue - 1;
    }

    //Set the ImagickPixel to the new color
    $colorInfo = $color->setHSL($newHue, $colorInfo['saturation'], $colorInfo['luminosity']);

    //Check that the new color is blue/green
    $colorInfo = $color->getcolor();
    print_r($colorInfo);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [r] => 26
        [g] => 230
        [b] => 230
        [a] => 255
    )

### Anmerkungen

> Hinweis:

> Available with ImageMagick library version 6.2.9 and higher.

# ImagickPixel::setIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::setIndex — Sets the colormap index of the pixel wand

### Beschreibung

public function ImagickPixel::setIndex(int `$index`): bool

Sets the colormap index of the pixel wand.

### Parameter-Liste

`index`

### Rückgabewerte

Liefert `true` bei Erfolg.

## Inhaltsverzeichnis

- ImagickPixel::clear — Clears resources associated with this object
- ImagickPixel::__construct — The ImagickPixel constructor
- ImagickPixel::destroy — Deallocates resources associated with this object
- ImagickPixel::getColor — Returns the color
- ImagickPixel::getColorAsString — Returns the color as a string
- ImagickPixel::getColorCount — Returns the color count associated with this color
- ImagickPixel::getColorQuantum — Returns the color of the pixel in an array as Quantum values
- ImagickPixel::getColorValue — Gets the normalized value of the provided color channel
- ImagickPixel::getColorValueQuantum — Gets the quantum value of a color in the ImagickPixel
- ImagickPixel::getHSL — Returns the normalized HSL color of the ImagickPixel object
- ImagickPixel::getIndex — Gets the colormap index of the pixel wand
- ImagickPixel::isPixelSimilar — Check the distance between this color and another
- ImagickPixel::isPixelSimilarQuantum — Returns whether two colors differ by less than the specified distance
- ImagickPixel::isSimilar — Check the distance between this color and another
- ImagickPixel::setColor — Sets the color
- ImagickPixel::setColorCount — Sets the color count associated with this color
- ImagickPixel::setColorValue — Sets the normalized value of one of the channels
- ImagickPixel::setColorValueQuantum — Sets the quantum value of a color element of the ImagickPixel
- ImagickPixel::setHSL — Sets the normalized HSL color
- ImagickPixel::setIndex — Sets the colormap index of the pixel wand

# The ImagickPixelException class

(PECL imagick 3)

## Einführung

## Klassenbeschreibung

class ImagickPixelException extends Exception implements Throwable {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
/* Geerbte Methoden */
}

# Die Klasse ImagickPixelIterator

(PECL imagick 2, PECL imagick 3)

## Klassenbeschreibung

class ImagickPixelIterator {
public function clear(): bool
public function __construct(Imagick `$wand`)
public function destroy(): bool
public function getCurrentIteratorRow(): array
public function getIteratorRow(): int
public function getNextIteratorRow(): array
public function getPreviousIteratorRow(): array
public function newPixelIterator(Imagick `$wand`): bool
public function newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
public function resetIterator(): bool
public function setIteratorFirstRow(): bool
public function setIteratorLastRow(): bool
public function setIteratorRow(int `$row`): bool
public function syncIterator(): bool
}

# ImagickPixelIterator::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::clear — Clear resources associated with a PixelIterator

### Beschreibung

public function ImagickPixelIterator::clear(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Clear resources associated with a PixelIterator.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickPixelIterator::clear()

    <?php
    function clear($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));

        $imageIterator = $imagick->getPixelRegionIterator(100, 100, 250, 200);

        /* Loop through pixel rows */
        foreach ($imageIterator as $pixels) {
            /** @var $pixel \ImagickPixel */
            /* Loop through the pixels in the row (columns) */
            foreach ($pixels as $column => $pixel) {
                if ($column % 2) {
                    /* Paint every second pixel black*/
                    $pixel->setColor("rgba(0, 0, 0, 0)");
                }
            }
            /* Sync the iterator, this is important to do on each iteration */
            $imageIterator->syncIterator();
        }

        $imageIterator->clear();

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::__construct — The ImagickPixelIterator constructor

### Beschreibung

public function ImagickPixelIterator::__construct(Imagick `$wand`)
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

The ImagickPixelIterator constructor

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickPixelIterator::construct()

    <?php
    function construct($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = new \ImagickPixelIterator($imagick);

        /* Loop through pixel rows */
        foreach ($imageIterator as $pixels) {
            /* Loop through the pixels in the row (columns) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {
                    /* Paint every second pixel black*/
                    $pixel->setColor("rgba(0, 0, 0, 0)");
                }
            }
            /* Sync the iterator, this is important to do on each iteration */
            $imageIterator->syncIterator();
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::destroy — Deallocates resources associated with a PixelIterator

### Beschreibung

public function ImagickPixelIterator::destroy(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Deallocates resources associated with a PixelIterator.

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickPixelIterator::getCurrentIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getCurrentIteratorRow — Returns the current row of ImagickPixel objects

### Beschreibung

public function ImagickPixelIterator::getCurrentIteratorRow(): array
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the current row as an array of ImagickPixel objects from the pixel iterator.

### Rückgabewerte

Returns a row as an array of ImagickPixel objects that can themselves be iterated.

# ImagickPixelIterator::getIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getIteratorRow — Returns the current pixel iterator row

### Beschreibung

public function ImagickPixelIterator::getIteratorRow(): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the current pixel iterator row.

### Rückgabewerte

Returns the integer offset of the row, throwing ImagickPixelIteratorException on error.

# ImagickPixelIterator::getNextIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getNextIteratorRow — Returns the next row of the pixel iterator

### Beschreibung

public function ImagickPixelIterator::getNextIteratorRow(): array
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the next row as an array of pixel wands from the pixel iterator.

### Rückgabewerte

Returns the next row as an array of ImagickPixel objects, throwing ImagickPixelIteratorException on error.

### Beispiele

Beispiel #1 ImagickPixelIterator::getNextIteratorRow()

    <?php
    function getNextIteratorRow($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelIterator();

        $count = 0;
        while ($pixels = $imageIterator->getNextIteratorRow()) {
            if (($count % 3) == 0) {
                /* Loop through the pixels in the row (columns) */
                foreach ($pixels as $column => $pixel) {
                    /** @var $pixel \ImagickPixel */
                    if ($column % 2) {
                        /* Paint every second pixel black*/
                        $pixel->setColor("rgba(0, 0, 0, 0)");
                    }
                }
                /* Sync the iterator, this is important to do on each iteration */
                $imageIterator->syncIterator();
            }

            $count += 1;
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::getPreviousIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getPreviousIteratorRow — Returns the previous row

### Beschreibung

public function ImagickPixelIterator::getPreviousIteratorRow(): array
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns the previous row as an array of pixel wands from the pixel iterator.

### Rückgabewerte

Returns the previous row as an array of ImagickPixelWand objects from the ImagickPixelIterator, throwing ImagickPixelIteratorException on error.

# ImagickPixelIterator::newPixelIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelIterator — Returns a new pixel iterator

### Beschreibung

public function ImagickPixelIterator::newPixelIterator(Imagick `$wand`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns a new pixel iterator.

### Rückgabewerte

Liefert `true` bei Erfolg. Throwing ImagickPixelIteratorException.

# ImagickPixelIterator::newPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelRegionIterator — Returns a new pixel iterator

### Beschreibung

public function ImagickPixelIterator::newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Returns a new pixel iterator.

### Parameter-Liste

`wand`

`x`

`y`

`columns`

`rows`

### Rückgabewerte

Returns a new ImagickPixelIterator on success; on failure, throws ImagickPixelIteratorException.

# ImagickPixelIterator::resetIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::resetIterator — Resets the pixel iterator

### Beschreibung

public function ImagickPixelIterator::resetIterator(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Resets the pixel iterator. Use it in conjunction with ImagickPixelIterator::getNextIteratorRow() to iterate over all the pixels in a pixel container.

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickPixelIterator::resetIterator()

    <?php
    function resetIterator($imagePath) {

        $imagick = new \Imagick(realpath($imagePath));

        $imageIterator = $imagick->getPixelIterator();

        /* Loop through pixel rows */
        foreach ($imageIterator as $pixels) {
            /* Loop through the pixels in the row (columns) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 2) {

                    /* Make every second pixel 25% red*/
                    $pixel->setColorValue(\Imagick::COLOR_RED, 64);
                }
            }
            /* Sync the iterator, this is important to do on each iteration */
            $imageIterator->syncIterator();
        }

        $imageIterator->resetiterator();

        /* Loop through pixel rows */
        foreach ($imageIterator as $pixels) {
            /* Loop through the pixels in the row (columns) */
            foreach ($pixels as $column => $pixel) {
                /** @var $pixel \ImagickPixel */
                if ($column % 3) {
                    $pixel->setColorValue(\Imagick::COLOR_BLUE, 64); /* Make every second pixel a little blue*/
                    //$pixel->setColor("rgba(0, 0, 128, 0)"); /* Paint every second pixel black*/
                }
            }
            $imageIterator->syncIterator(); /* Sync the iterator, this is important to do on each iteration */
        }

        $imageIterator->clear();

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::setIteratorFirstRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorFirstRow — Sets the pixel iterator to the first pixel row

### Beschreibung

public function ImagickPixelIterator::setIteratorFirstRow(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the pixel iterator to the first pixel row.

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickPixelIterator::setIteratorLastRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorLastRow — Sets the pixel iterator to the last pixel row

### Beschreibung

public function ImagickPixelIterator::setIteratorLastRow(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Sets the pixel iterator to the last pixel row.

### Rückgabewerte

Liefert `true` bei Erfolg.

# ImagickPixelIterator::setIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorRow — Set the pixel iterator row

### Beschreibung

public function ImagickPixelIterator::setIteratorRow(int `$row`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Set the pixel iterator row.

### Parameter-Liste

`row`

### Rückgabewerte

Liefert `true` bei Erfolg.

### Beispiele

Beispiel #1 ImagickPixelIterator::setIteratorRow()

    <?php
    function setIteratorRow($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imageIterator = $imagick->getPixelRegionIterator(200, 100, 200, 200);

        for ($x = 0; $x < 20; $x++) {
            $imageIterator->setIteratorRow($x * 5);
            $pixels = $imageIterator->getCurrentIteratorRow();
            /* Loop through the pixels in the row (columns) */
            foreach ($pixels as $pixel) {
                /** @var $pixel \ImagickPixel */
                /* Paint every second pixel black*/
                $pixel->setColor("rgba(0, 0, 0, 0)");
            }

            /* Sync the iterator, this is important to do on each iteration */
            $imageIterator->syncIterator();
        }

        header("Content-Type: image/jpg");
        echo $imagick;
    }

    ?>

# ImagickPixelIterator::syncIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::syncIterator — Syncs the pixel iterator

### Beschreibung

public function ImagickPixelIterator::syncIterator(): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

Syncs the pixel iterator.

### Rückgabewerte

Liefert `true` bei Erfolg.

## Inhaltsverzeichnis

- ImagickPixelIterator::clear — Clear resources associated with a PixelIterator
- ImagickPixelIterator::__construct — The ImagickPixelIterator constructor
- ImagickPixelIterator::destroy — Deallocates resources associated with a PixelIterator
- ImagickPixelIterator::getCurrentIteratorRow — Returns the current row of ImagickPixel objects
- ImagickPixelIterator::getIteratorRow — Returns the current pixel iterator row
- ImagickPixelIterator::getNextIteratorRow — Returns the next row of the pixel iterator
- ImagickPixelIterator::getPreviousIteratorRow — Returns the previous row
- ImagickPixelIterator::newPixelIterator — Returns a new pixel iterator
- ImagickPixelIterator::newPixelRegionIterator — Returns a new pixel iterator
- ImagickPixelIterator::resetIterator — Resets the pixel iterator
- ImagickPixelIterator::setIteratorFirstRow — Sets the pixel iterator to the first pixel row
- ImagickPixelIterator::setIteratorLastRow — Sets the pixel iterator to the last pixel row
- ImagickPixelIterator::setIteratorRow — Set the pixel iterator row
- ImagickPixelIterator::syncIterator — Syncs the pixel iterator

# The ImagickPixelIteratorException class

(PECL imagick 3)

## Einführung

## Klassenbeschreibung

class ImagickPixelIteratorException extends Exception implements Throwable {
/* Geerbte Eigenschaften */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* Methoden */
/* Geerbte Methoden */
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Beispiele
  - Basic usage
- Imagick — The Imagick class
  - Imagick::adaptiveBlurImage — Adds adaptive blur filter to image
  - Imagick::adaptiveResizeImage — Adaptively resize image with data dependent triangulation
  - Imagick::adaptiveSharpenImage — Adaptively sharpen the image
  - Imagick::adaptiveThresholdImage — Selects a threshold for each pixel based on a range of intensity
  - Imagick::addImage — Adds new image to Imagick object image list
  - Imagick::addNoiseImage — Adds random noise to the image
  - Imagick::affineTransformImage — Transforms an image
  - Imagick::animateImages — Animates an image or images
  - Imagick::annotateImage — Annotates an image with text
  - Imagick::appendImages — Append a set of images
  - Imagick::autoLevelImage — Adjusts the levels of a particular image channel
  - Imagick::averageImages — Average a set of images
  - Imagick::blackThresholdImage — Forces all pixels below the threshold into black
  - Imagick::blueShiftImage — Mutes the colors of the image
  - Imagick::blurImage — Adds blur filter to image
  - Imagick::borderImage — Surrounds the image with a border
  - Imagick::brightnessContrastImage — Change the brightness and/or contrast of an image
  - Imagick::charcoalImage — Simulates a charcoal drawing
  - Imagick::chopImage — Removes a region of an image and trims
  - Imagick::clampImage — Restricts the color range from 0 to the quantum depth.
  - Imagick::clear — Clears all resources associated to Imagick object
  - Imagick::clipImage — Clips along the first path from the 8BIM profile
  - Imagick::clipImagePath — Clips along the named paths from the 8BIM profile, if present
  - Imagick::clipPathImage — Clips along the named paths from the 8BIM profile
  - Imagick::clone — Makes an exact copy of the Imagick object
  - Imagick::clutImage — Replaces colors in the image
  - Imagick::coalesceImages — Composites a set of images
  - Imagick::colorFloodfillImage — Changes the color value of any pixel that matches target
  - Imagick::colorizeImage — Blends the fill color with the image
  - Imagick::colorMatrixImage — Apply color transformation to an image
  - Imagick::combineImages — Combines one or more images into a single image
  - Imagick::commentImage — Adds a comment to your image
  - Imagick::compareImageChannels — Returns the difference in one or more images
  - Imagick::compareImageLayers — Returns the maximum bounding region between images
  - Imagick::compareImages — Compares an image to a reconstructed image
  - Imagick::compositeImage — Composite one image onto another
  - Imagick::__construct — The Imagick constructor
  - Imagick::contrastImage — Change the contrast of the image
  - Imagick::contrastStretchImage — Enhances the contrast of a color image
  - Imagick::convolveImage — Applies a custom convolution kernel to the image
  - Imagick::count — Get the number of images
  - Imagick::cropImage — Extracts a region of the image
  - Imagick::cropThumbnailImage — Creates a crop thumbnail
  - Imagick::current — Returns a reference to the current Imagick object
  - Imagick::cycleColormapImage — Displaces an image's colormap
  - Imagick::decipherImage — Deciphers an image
  - Imagick::deconstructImages — Returns certain pixel differences between images
  - Imagick::deleteImageArtifact — Delete image artifact
  - Imagick::deleteImageProperty — Deletes an image property
  - Imagick::deskewImage — Removes skew from the image
  - Imagick::despeckleImage — Reduces the speckle noise in an image
  - Imagick::destroy — Destroys the Imagick object
  - Imagick::displayImage — Displays an image
  - Imagick::displayImages — Displays an image or image sequence
  - Imagick::distortImage — Distorts an image using various distortion methods
  - Imagick::drawImage — Renders the ImagickDraw object on the current image
  - Imagick::edgeImage — Enhance edges within the image
  - Imagick::embossImage — Returns a grayscale image with a three-dimensional effect
  - Imagick::encipherImage — Enciphers an image
  - Imagick::enhanceImage — Improves the quality of a noisy image
  - Imagick::equalizeImage — Equalizes the image histogram
  - Imagick::evaluateImage — Applies an expression to an image
  - Imagick::exportImagePixels — Exports raw image pixels
  - Imagick::extentImage — Set image size
  - Imagick::filter — Applies a custom convolution kernel to the image
  - Imagick::flattenImages — Merges a sequence of images
  - Imagick::flipImage — Creates a vertical mirror image
  - Imagick::floodFillPaintImage — Changes the color value of any pixel that matches target
  - Imagick::flopImage — Creates a horizontal mirror image
  - Imagick::forwardFourierTransformImage — Implements the discrete Fourier transform (DFT)
  - Imagick::frameImage — Adds a simulated three-dimensional border
  - Imagick::functionImage — Applies a function on the image
  - Imagick::fxImage — Evaluate expression for each pixel in the image
  - Imagick::gammaImage — Gamma-corrects an image
  - Imagick::gaussianBlurImage — Blurs an image
  - Imagick::getColorspace — Gets the colorspace
  - Imagick::getCompression — Gets the object compression type
  - Imagick::getCompressionQuality — Gets the object compression quality
  - Imagick::getCopyright — Returns the ImageMagick API copyright as a string
  - Imagick::getFilename — The filename associated with an image sequence
  - Imagick::getFont — Gets font
  - Imagick::getFormat — Returns the format of the Imagick object
  - Imagick::getGravity — Gets the gravity
  - Imagick::getHomeURL — Returns the ImageMagick home URL
  - Imagick::getImage — Returns a new Imagick object
  - Imagick::getImageAlphaChannel — Checks if the image has an alpha channel
  - Imagick::getImageArtifact — Get image artifact
  - Imagick::getImageAttribute — Returns a named attribute
  - Imagick::getImageBackgroundColor — Returns the image background color
  - Imagick::getImageBlob — Returns the image sequence as a blob
  - Imagick::getImageBluePrimary — Returns the chromaticy blue primary point
  - Imagick::getImageBorderColor — Returns the image border color
  - Imagick::getImageChannelDepth — Gets the depth for a particular image channel
  - Imagick::getImageChannelDistortion — Compares image channels of an image to a reconstructed image
  - Imagick::getImageChannelDistortions — Gets channel distortions
  - Imagick::getImageChannelExtrema — Gets the extrema for one or more image channels
  - Imagick::getImageChannelKurtosis — The getImageChannelKurtosis purpose
  - Imagick::getImageChannelMean — Gets the mean and standard deviation
  - Imagick::getImageChannelRange — Gets channel range
  - Imagick::getImageChannelStatistics — Returns statistics for each channel in the image
  - Imagick::getImageClipMask — Gets image clip mask
  - Imagick::getImageColormapColor — Returns the color of the specified colormap index
  - Imagick::getImageColors — Gets the number of unique colors in the image
  - Imagick::getImageColorspace — Gets the image colorspace
  - Imagick::getImageCompose — Returns the composite operator associated with the image
  - Imagick::getImageCompression — Gets the current image's compression type
  - Imagick::getImageCompressionQuality — Gets the current image's compression quality
  - Imagick::getImageDelay — Gets the image delay
  - Imagick::getImageDepth — Gets the image depth
  - Imagick::getImageDispose — Gets the image disposal method
  - Imagick::getImageDistortion — Compares an image to a reconstructed image
  - Imagick::getImageExtrema — Gets the extrema for the image
  - Imagick::getImageFilename — Returns the filename of a particular image in a sequence
  - Imagick::getImageFormat — Returns the format of a particular image in a sequence
  - Imagick::getImageGamma — Gets the image gamma
  - Imagick::getImageGeometry — Gets the width and height as an associative array
  - Imagick::getImageGravity — Gets the image gravity
  - Imagick::getImageGreenPrimary — Returns the chromaticy green primary point
  - Imagick::getImageHeight — Returns the image height
  - Imagick::getImageHistogram — Gets the image histogram
  - Imagick::getImageIndex — Gets the index of the current active image
  - Imagick::getImageInterlaceScheme — Gets the image interlace scheme
  - Imagick::getImageInterpolateMethod — Returns the interpolation method
  - Imagick::getImageIterations — Gets the image iterations
  - Imagick::getImageLength — Returns the image length in bytes
  - Imagick::getImageMatte — Return if the image has a matte channel
  - Imagick::getImageMatteColor — Returns the image matte color
  - Imagick::getImageMimeType — Returns the image mime-type
  - Imagick::getImageOrientation — Gets the image orientation
  - Imagick::getImagePage — Returns the page geometry
  - Imagick::getImagePixelColor — Returns the color of the specified pixel
  - Imagick::getImageProfile — Returns the named image profile
  - Imagick::getImageProfiles — Returns the image profiles
  - Imagick::getImageProperties — Returns the image properties
  - Imagick::getImageProperty — Returns the named image property
  - Imagick::getImageRedPrimary — Returns the chromaticity red primary point
  - Imagick::getImageRegion — Extracts a region of the image
  - Imagick::getImageRenderingIntent — Gets the image rendering intent
  - Imagick::getImageResolution — Gets the image X and Y resolution
  - Imagick::getImagesBlob — Returns all image sequences as a blob
  - Imagick::getImageScene — Gets the image scene
  - Imagick::getImageSignature — Generates an SHA-256 message digest
  - Imagick::getImageSize — Returns the image length in bytes
  - Imagick::getImageTicksPerSecond — Gets the image ticks-per-second
  - Imagick::getImageTotalInkDensity — Gets the image total ink density
  - Imagick::getImageType — Gets the potential image type
  - Imagick::getImageUnits — Gets the image units of resolution
  - Imagick::getImageVirtualPixelMethod — Returns the virtual pixel method
  - Imagick::getImageWhitePoint — Returns the chromaticity white point
  - Imagick::getImageWidth — Returns the image width
  - Imagick::getInterlaceScheme — Gets the object interlace scheme
  - Imagick::getIteratorIndex — Gets the index of the current active image
  - Imagick::getNumberImages — Returns the number of images in the object
  - Imagick::getOption — Returns a value associated with the specified key
  - Imagick::getPackageName — Returns the ImageMagick package name
  - Imagick::getPage — Returns the page geometry
  - Imagick::getPixelIterator — Returns a MagickPixelIterator
  - Imagick::getPixelRegionIterator — Get an ImagickPixelIterator for an image section
  - Imagick::getPointSize — Gets point size
  - Imagick::getQuantum — Returns the ImageMagick quantum range
  - Imagick::getQuantumDepth — Gets the quantum depth
  - Imagick::getQuantumRange — Returns the Imagick quantum range
  - Imagick::getRegistry — Get a StringRegistry entry
  - Imagick::getReleaseDate — Returns the ImageMagick release date
  - Imagick::getResource — Returns the specified resource's memory usage
  - Imagick::getResourceLimit — Returns the specified resource limit
  - Imagick::getSamplingFactors — Gets the horizontal and vertical sampling factor
  - Imagick::getSize — Returns the size associated with the Imagick object
  - Imagick::getSizeOffset — Returns the size offset
  - Imagick::getVersion — Returns the ImageMagick API version
  - Imagick::haldClutImage — Replaces colors in the image
  - Imagick::hasNextImage — Checks if the object has more images
  - Imagick::hasPreviousImage — Checks if the object has a previous image
  - Imagick::identifyFormat — Formats a string with image details
  - Imagick::identifyImage — Identifies an image and fetches attributes
  - Imagick::implodeImage — Creates a new image as a copy
  - Imagick::importImagePixels — Imports image pixels
  - Imagick::inverseFourierTransformImage — Implements the inverse discrete Fourier transform (DFT)
  - Imagick::labelImage — Adds a label to an image
  - Imagick::levelImage — Adjusts the levels of an image
  - Imagick::linearStretchImage — Stretches with saturation the image intensity
  - Imagick::liquidRescaleImage — Animates an image or images
  - Imagick::listRegistry — List all the registry settings
  - Imagick::magnifyImage — Scales an image proportionally 2x
  - Imagick::mapImage — Replaces the colors of an image with the closest color from a reference image
  - Imagick::matteFloodfillImage — Changes the transparency value of a color
  - Imagick::medianFilterImage — Applies a digital filter
  - Imagick::mergeImageLayers — Merges image layers
  - Imagick::minifyImage — Scales an image proportionally to half its size
  - Imagick::modulateImage — Control the brightness, saturation, and hue
  - Imagick::montageImage — Creates a composite image
  - Imagick::morphImages — Method morphs a set of images
  - Imagick::morphology — Applies a user supplied kernel to the image according to the given morphology method.
  - Imagick::mosaicImages — Forms a mosaic from images
  - Imagick::motionBlurImage — Simulates motion blur
  - Imagick::negateImage — Negates the colors in the reference image
  - Imagick::newImage — Creates a new image
  - Imagick::newPseudoImage — Creates a new image
  - Imagick::nextImage — Moves to the next image
  - Imagick::normalizeImage — Enhances the contrast of a color image
  - Imagick::oilPaintImage — Simulates an oil painting
  - Imagick::opaquePaintImage — Changes the color value of any pixel that matches target
  - Imagick::optimizeImageLayers — Removes repeated portions of images to optimize
  - Imagick::orderedPosterizeImage — Performs an ordered dither
  - Imagick::paintFloodfillImage — Changes the color value of any pixel that matches target
  - Imagick::paintOpaqueImage — Change any pixel that matches color
  - Imagick::paintTransparentImage — Changes any pixel that matches color with the color defined by fill
  - Imagick::pingImage — Ruft grundlegende Merkmale eines Bildes ab
  - Imagick::pingImageBlob — Quickly fetch attributes
  - Imagick::pingImageFile — Get basic image attributes in a lightweight manner
  - Imagick::polaroidImage — Simulates a Polaroid picture
  - Imagick::posterizeImage — Reduces the image to a limited number of color level
  - Imagick::previewImages — Quickly pin-point appropriate parameters for image processing
  - Imagick::previousImage — Move to the previous image in the object
  - Imagick::profileImage — Adds or removes a profile from an image
  - Imagick::quantizeImage — Analyzes the colors within a reference image
  - Imagick::quantizeImages — Analyzes the colors within a sequence of images
  - Imagick::queryFontMetrics — Returns an array representing the font metrics
  - Imagick::queryFonts — Returns the configured fonts
  - Imagick::queryFormats — Returns formats supported by Imagick
  - Imagick::radialBlurImage — Radial blurs an image
  - Imagick::raiseImage — Creates a simulated 3d button-like effect
  - Imagick::randomThresholdImage — Creates a high-contrast, two-color image
  - Imagick::readImage — Reads image from filename
  - Imagick::readImageBlob — Reads image from a binary string
  - Imagick::readImageFile — Reads image from open filehandle
  - Imagick::readimages — Reads image from an array of filenames
  - Imagick::recolorImage — Recolors image
  - Imagick::reduceNoiseImage — Smooths the contours of an image
  - Imagick::remapImage — Remaps image colors
  - Imagick::removeImage — Removes an image from the image list
  - Imagick::removeImageProfile — Removes the named image profile and returns it
  - Imagick::render — Renders all preceding drawing commands
  - Imagick::resampleImage — Resample image to desired resolution
  - Imagick::resetImagePage — Reset image page
  - Imagick::resizeImage — Scales an image
  - Imagick::rollImage — Offsets an image
  - Imagick::rotateImage — Rotates an image
  - Imagick::rotationalBlurImage — Rotational blurs an image
  - Imagick::roundCorners — Rounds image corners
  - Imagick::sampleImage — Scales an image with pixel sampling
  - Imagick::scaleImage — Scales the size of an image
  - Imagick::segmentImage — Segments an image
  - Imagick::selectiveBlurImage — Selectively blur an image within a contrast threshold
  - Imagick::separateImageChannel — Separates a channel from the image
  - Imagick::sepiaToneImage — Sepia tones an image
  - Imagick::setBackgroundColor — Sets the object's default background color
  - Imagick::setColorspace — Set colorspace
  - Imagick::setCompression — Sets the object's default compression type
  - Imagick::setCompressionQuality — Sets the object's default compression quality
  - Imagick::setFilename — Sets the filename before you read or write the image
  - Imagick::setFirstIterator — Sets the Imagick iterator to the first image
  - Imagick::setFont — Sets font
  - Imagick::setFormat — Sets the format of the Imagick object
  - Imagick::setGravity — Sets the gravity
  - Imagick::setImage — Replaces image in the object
  - Imagick::setImageAlphaChannel — Sets image alpha channel
  - Imagick::setImageArtifact — Set image artifact
  - Imagick::setImageAttribute — Sets an image attribute
  - Imagick::setImageBackgroundColor — Sets the image background color
  - Imagick::setImageBias — Sets the image bias for any method that convolves an image
  - Imagick::setImageBiasQuantum — Sets the image bias
  - Imagick::setImageBluePrimary — Sets the image chromaticity blue primary point
  - Imagick::setImageBorderColor — Sets the image border color
  - Imagick::setImageChannelDepth — Sets the depth of a particular image channel
  - Imagick::setImageClipMask — Sets image clip mask
  - Imagick::setImageColormapColor — Sets the color of the specified colormap index
  - Imagick::setImageColorspace — Sets the image colorspace
  - Imagick::setImageCompose — Sets the image composite operator
  - Imagick::setImageCompression — Sets the image compression
  - Imagick::setImageCompressionQuality — Sets the image compression quality
  - Imagick::setImageDelay — Sets the image delay
  - Imagick::setImageDepth — Sets the image depth
  - Imagick::setImageDispose — Sets the image disposal method
  - Imagick::setImageExtent — Sets the image size
  - Imagick::setImageFilename — Sets the filename of a particular image
  - Imagick::setImageFormat — Sets the format of a particular image
  - Imagick::setImageGamma — Sets the image gamma
  - Imagick::setImageGravity — Sets the image gravity
  - Imagick::setImageGreenPrimary — Sets the image chromaticity green primary point
  - Imagick::setImageIndex — Set the iterator position
  - Imagick::setImageInterlaceScheme — Sets the image compression
  - Imagick::setImageInterpolateMethod — Sets the image interpolate pixel method
  - Imagick::setImageIterations — Sets the image iterations
  - Imagick::setImageMatte — Sets the image matte channel
  - Imagick::setImageMatteColor — Sets the image matte color
  - Imagick::setImageOpacity — Sets the image opacity level
  - Imagick::setImageOrientation — Sets the image orientation
  - Imagick::setImagePage — Sets the page geometry of the image
  - Imagick::setImageProfile — Adds a named profile to the Imagick object
  - Imagick::setImageProperty — Sets an image property
  - Imagick::setImageRedPrimary — Sets the image chromaticity red primary point
  - Imagick::setImageRenderingIntent — Sets the image rendering intent
  - Imagick::setImageResolution — Sets the image resolution
  - Imagick::setImageScene — Sets the image scene
  - Imagick::setImageTicksPerSecond — Sets the image ticks-per-second
  - Imagick::setImageType — Sets the image type
  - Imagick::setImageUnits — Sets the image units of resolution
  - Imagick::setImageVirtualPixelMethod — Sets the image virtual pixel method
  - Imagick::setImageWhitePoint — Sets the image chromaticity white point
  - Imagick::setInterlaceScheme — Sets the image compression
  - Imagick::setIteratorIndex — Set the iterator position
  - Imagick::setLastIterator — Sets the Imagick iterator to the last image
  - Imagick::setOption — Set an option
  - Imagick::setPage — Sets the page geometry of the Imagick object
  - Imagick::setPointSize — Sets point size
  - Imagick::setProgressMonitor — Set a callback to be called during processing
  - Imagick::setRegistry — Sets the ImageMagick registry entry named key to value
  - Imagick::setResolution — Sets the image resolution
  - Imagick::setResourceLimit — Sets the limit for a particular resource
  - Imagick::setSamplingFactors — Sets the image sampling factors
  - Imagick::setSize — Sets the size of the Imagick object
  - Imagick::setSizeOffset — Sets the size and offset of the Imagick object
  - Imagick::setType — Sets the image type attribute
  - Imagick::shadeImage — Creates a 3D effect
  - Imagick::shadowImage — Simulates an image shadow
  - Imagick::sharpenImage — Sharpens an image
  - Imagick::shaveImage — Shaves pixels from the image edges
  - Imagick::shearImage — Creating a parallelogram
  - Imagick::sigmoidalContrastImage — Adjusts the contrast of an image
  - Imagick::sketchImage — Simulates a pencil sketch
  - Imagick::smushImages — Takes all images from the current image pointer to the end of the image list and smushs them
  - Imagick::solarizeImage — Applies a solarizing effect to the image
  - Imagick::sparseColorImage — Interpolates colors
  - Imagick::spliceImage — Splices a solid color into the image
  - Imagick::spreadImage — Randomly displaces each pixel in a block
  - Imagick::statisticImage — Modifies image using a statistics function
  - Imagick::steganoImage — Hides a digital watermark within the image
  - Imagick::stereoImage — Composites two images
  - Imagick::stripImage — Strips an image of all profiles and comments
  - Imagick::subImageMatch — Searches for a subimage in the current image and returns a similarity image
  - Imagick::swirlImage — Swirls the pixels about the center of the image
  - Imagick::textureImage — Repeatedly tiles the texture image
  - Imagick::thresholdImage — Changes the value of individual pixels based on a threshold
  - Imagick::thumbnailImage — Changes the size of an image
  - Imagick::tintImage — Applies a color vector to each pixel in the image
  - Imagick::__toString — Returns the image as a string
  - Imagick::transformImage — Convenience method for setting crop size and the image geometry
  - Imagick::transformImageColorspace — Transforms an image to a new colorspace
  - Imagick::transparentPaintImage — Paints pixels transparent
  - Imagick::transposeImage — Creates a vertical mirror image
  - Imagick::transverseImage — Creates a horizontal mirror image
  - Imagick::trimImage — Remove edges from the image
  - Imagick::uniqueImageColors — Discards all but one of any pixel color
  - Imagick::unsharpMaskImage — Sharpens an image
  - Imagick::valid — Checks if the current item is valid
  - Imagick::vignetteImage — Adds vignette filter to the image
  - Imagick::waveImage — Applies wave filter to the image
  - Imagick::whiteThresholdImage — Force all pixels above the threshold into white
  - Imagick::writeImage — Writes an image to the specified filename
  - Imagick::writeImageFile — Writes an image to a filehandle
  - Imagick::writeImages — Writes an image or image sequence
  - Imagick::writeImagesFile — Writes frames to a filehandle
- ImagickDraw — Die Klasse ImagickDraw
  - ImagickDraw::affine — Adjusts the current affine transformation matrix
  - ImagickDraw::annotation — Draws text on the image
  - ImagickDraw::arc — Draws an arc
  - ImagickDraw::bezier — Draws a bezier curve
  - ImagickDraw::circle — Draws a circle
  - ImagickDraw::clear — Clears the ImagickDraw
  - ImagickDraw::clone — Makes an exact copy of the specified ImagickDraw object
  - ImagickDraw::color — Draws color on image
  - ImagickDraw::comment — Adds a comment
  - ImagickDraw::composite — Composites an image onto the current image
  - ImagickDraw::__construct — The ImagickDraw constructor
  - ImagickDraw::destroy — Frees all associated resources
  - ImagickDraw::ellipse — Draws an ellipse on the image
  - ImagickDraw::getClipPath — Obtains the current clipping path ID
  - ImagickDraw::getClipRule — Returns the current polygon fill rule
  - ImagickDraw::getClipUnits — Returns the interpretation of clip path units
  - ImagickDraw::getFillColor — Returns the fill color
  - ImagickDraw::getFillOpacity — Returns the opacity used when drawing
  - ImagickDraw::getFillRule — Returns the fill rule
  - ImagickDraw::getFont — Returns the font
  - ImagickDraw::getFontFamily — Returns the font family
  - ImagickDraw::getFontSize — Returns the font pointsize
  - ImagickDraw::getFontStretch — Gets the font stretch to use when annotating with text
  - ImagickDraw::getFontStyle — Returns the font style
  - ImagickDraw::getFontWeight — Returns the font weight
  - ImagickDraw::getGravity — Returns the text placement gravity
  - ImagickDraw::getStrokeAntialias — Returns the current stroke antialias setting
  - ImagickDraw::getStrokeColor — Returns the color used for stroking object outlines
  - ImagickDraw::getStrokeDashArray — Returns an array representing the pattern of dashes and gaps used to stroke paths
  - ImagickDraw::getStrokeDashOffset — Returns the offset into the dash pattern to start the dash
  - ImagickDraw::getStrokeLineCap — Returns the shape to be used at the end of open subpaths when they are stroked
  - ImagickDraw::getStrokeLineJoin — Returns the shape to be used at the corners of paths when they are stroked
  - ImagickDraw::getStrokeMiterLimit — Returns the stroke miter limit
  - ImagickDraw::getStrokeOpacity — Returns the opacity of stroked object outlines
  - ImagickDraw::getStrokeWidth — Returns the width of the stroke used to draw object outlines
  - ImagickDraw::getTextAlignment — Returns the text alignment
  - ImagickDraw::getTextAntialias — Returns the current text antialias setting
  - ImagickDraw::getTextDecoration — Returns the text decoration
  - ImagickDraw::getTextEncoding — Returns the code set used for text annotations
  - ImagickDraw::getTextInterlineSpacing — Gets the text interline spacing
  - ImagickDraw::getTextInterwordSpacing — Gets the text interword spacing
  - ImagickDraw::getTextKerning — Gets the text kerning
  - ImagickDraw::getTextUnderColor — Returns the text under color
  - ImagickDraw::getVectorGraphics — Returns a string containing vector graphics
  - ImagickDraw::line — Draws a line
  - ImagickDraw::matte — Paints on the image's opacity channel
  - ImagickDraw::pathClose — Adds a path element to the current path
  - ImagickDraw::pathCurveToAbsolute — Draws a cubic Bezier curve
  - ImagickDraw::pathCurveToQuadraticBezierAbsolute — Draws a quadratic Bezier curve
  - ImagickDraw::pathCurveToQuadraticBezierRelative — Draws a quadratic Bezier curve
  - ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — Draws a quadratic Bezier curve
  - ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — Draws a quadratic Bezier curve
  - ImagickDraw::pathCurveToRelative — Draws a cubic Bezier curve
  - ImagickDraw::pathCurveToSmoothAbsolute — Draws a cubic Bezier curve
  - ImagickDraw::pathCurveToSmoothRelative — Draws a cubic Bezier curve
  - ImagickDraw::pathEllipticArcAbsolute — Draws an elliptical arc
  - ImagickDraw::pathEllipticArcRelative — Draws an elliptical arc
  - ImagickDraw::pathFinish — Terminates the current path
  - ImagickDraw::pathLineToAbsolute — Draws a line path
  - ImagickDraw::pathLineToHorizontalAbsolute — Draws a horizontal line path
  - ImagickDraw::pathLineToHorizontalRelative — Draws a horizontal line
  - ImagickDraw::pathLineToRelative — Draws a line path
  - ImagickDraw::pathLineToVerticalAbsolute — Draws a vertical line
  - ImagickDraw::pathLineToVerticalRelative — Draws a vertical line path
  - ImagickDraw::pathMoveToAbsolute — Starts a new sub-path
  - ImagickDraw::pathMoveToRelative — Starts a new sub-path
  - ImagickDraw::pathStart — Declares the start of a path drawing list
  - ImagickDraw::point — Draws a point
  - ImagickDraw::polygon — Draws a polygon
  - ImagickDraw::polyline — Draws a polyline
  - ImagickDraw::pop — Destroys the current ImagickDraw in the stack, and returns to the previously pushed ImagickDraw
  - ImagickDraw::popClipPath — Terminates a clip path definition
  - ImagickDraw::popDefs — Terminates a definition list
  - ImagickDraw::popPattern — Terminates a pattern definition
  - ImagickDraw::push — Clones the current ImagickDraw and pushes it to the stack
  - ImagickDraw::pushClipPath — Starts a clip path definition
  - ImagickDraw::pushDefs — Indicates that following commands create named elements for early processing
  - ImagickDraw::pushPattern — Indicates that subsequent commands up to a ImagickDraw::opPattern() command comprise the definition of a named pattern
  - ImagickDraw::rectangle — Draws a rectangle
  - ImagickDraw::render — Renders all preceding drawing commands onto the image
  - ImagickDraw::resetVectorGraphics — Resets the vector graphics
  - ImagickDraw::rotate — Applies the specified rotation to the current coordinate space
  - ImagickDraw::roundRectangle — Draws a rounded rectangle
  - ImagickDraw::scale — Adjusts the scaling factor
  - ImagickDraw::setClipPath — Associates a named clipping path with the image
  - ImagickDraw::setClipRule — Set the polygon fill rule to be used by the clipping path
  - ImagickDraw::setClipUnits — Sets the interpretation of clip path units
  - ImagickDraw::setFillAlpha — Sets the opacity to use when drawing using the fill color or fill texture
  - ImagickDraw::setFillColor — Sets the fill color to be used for drawing filled objects
  - ImagickDraw::setFillOpacity — Sets the opacity to use when drawing using the fill color or fill texture
  - ImagickDraw::setFillPatternURL — Sets the URL to use as a fill pattern for filling objects
  - ImagickDraw::setFillRule — Sets the fill rule to use while drawing polygons
  - ImagickDraw::setFont — Sets the fully-specified font to use when annotating with text
  - ImagickDraw::setFontFamily — Sets the font family to use when annotating with text
  - ImagickDraw::setFontSize — Sets the font pointsize to use when annotating with text
  - ImagickDraw::setFontStretch — Sets the font stretch to use when annotating with text
  - ImagickDraw::setFontStyle — Sets the font style to use when annotating with text
  - ImagickDraw::setFontWeight — Sets the font weight
  - ImagickDraw::setGravity — Sets the text placement gravity
  - ImagickDraw::setResolution — Sets the resolution
  - ImagickDraw::setStrokeAlpha — Specifies the opacity of stroked object outlines
  - ImagickDraw::setStrokeAntialias — Controls whether stroked outlines are antialiased
  - ImagickDraw::setStrokeColor — Sets the color used for stroking object outlines
  - ImagickDraw::setStrokeDashArray — Specifies the pattern of dashes and gaps used to stroke paths
  - ImagickDraw::setStrokeDashOffset — Specifies the offset into the dash pattern to start the dash
  - ImagickDraw::setStrokeLineCap — Specifies the shape to be used at the end of open subpaths when they are stroked
  - ImagickDraw::setStrokeLineJoin — Specifies the shape to be used at the corners of paths when they are stroked
  - ImagickDraw::setStrokeMiterLimit — Specifies the miter limit
  - ImagickDraw::setStrokeOpacity — Specifies the opacity of stroked object outlines
  - ImagickDraw::setStrokePatternURL — Sets the pattern used for stroking object outlines
  - ImagickDraw::setStrokeWidth — Sets the width of the stroke used to draw object outlines
  - ImagickDraw::setTextAlignment — Specifies a text alignment
  - ImagickDraw::setTextAntialias — Controls whether text is antialiased
  - ImagickDraw::setTextDecoration — Specifies a decoration
  - ImagickDraw::setTextEncoding — Specifies the text code set
  - ImagickDraw::setTextInterlineSpacing — Sets the text interline spacing
  - ImagickDraw::setTextInterwordSpacing — Sets the text interword spacing
  - ImagickDraw::setTextKerning — Sets the text kerning
  - ImagickDraw::setTextUnderColor — Specifies the color of a background rectangle
  - ImagickDraw::setVectorGraphics — Sets the vector graphics
  - ImagickDraw::setViewbox — Sets the overall canvas size
  - ImagickDraw::skewX — Skews the current coordinate system in the horizontal direction
  - ImagickDraw::skewY — Skews the current coordinate system in the vertical direction
  - ImagickDraw::translate — Applies a translation to the current coordinate system
- ImagickDrawException — The ImagickDrawException class
- ImagickException — The ImagickException class
- ImagickKernel — Die Klasse ImagickKernel
  - ImagickKernel::addKernel — Attach another kernel to a kernel list
  - ImagickKernel::addUnityKernel — Adds a Unity Kernel to the kernel list
  - ImagickKernel::fromBuiltIn — Create a kernel from a builtin in kernel
  - ImagickKernel::fromMatrix — Create a kernel from a 2d matrix of values
  - ImagickKernel::getMatrix — Get the 2d matrix of values used in this kernel
  - ImagickKernel::scale — Scales a kernel list by the given amount
  - ImagickKernel::separate — Separates a linked set of kernels and returns an array of ImagickKernels
- ImagickKernelException — Die Klasse ImagickKernelException
- ImagickPixel — Die Klasse ImagickPixel
  - ImagickPixel::clear — Clears resources associated with this object
  - ImagickPixel::__construct — The ImagickPixel constructor
  - ImagickPixel::destroy — Deallocates resources associated with this object
  - ImagickPixel::getColor — Returns the color
  - ImagickPixel::getColorAsString — Returns the color as a string
  - ImagickPixel::getColorCount — Returns the color count associated with this color
  - ImagickPixel::getColorQuantum — Returns the color of the pixel in an array as Quantum values
  - ImagickPixel::getColorValue — Gets the normalized value of the provided color channel
  - ImagickPixel::getColorValueQuantum — Gets the quantum value of a color in the ImagickPixel
  - ImagickPixel::getHSL — Returns the normalized HSL color of the ImagickPixel object
  - ImagickPixel::getIndex — Gets the colormap index of the pixel wand
  - ImagickPixel::isPixelSimilar — Check the distance between this color and another
  - ImagickPixel::isPixelSimilarQuantum — Returns whether two colors differ by less than the specified distance
  - ImagickPixel::isSimilar — Check the distance between this color and another
  - ImagickPixel::setColor — Sets the color
  - ImagickPixel::setColorCount — Sets the color count associated with this color
  - ImagickPixel::setColorValue — Sets the normalized value of one of the channels
  - ImagickPixel::setColorValueQuantum — Sets the quantum value of a color element of the ImagickPixel
  - ImagickPixel::setHSL — Sets the normalized HSL color
  - ImagickPixel::setIndex — Sets the colormap index of the pixel wand
- ImagickPixelException — The ImagickPixelException class
- ImagickPixelIterator — Die Klasse ImagickPixelIterator
  - ImagickPixelIterator::clear — Clear resources associated with a PixelIterator
  - ImagickPixelIterator::__construct — The ImagickPixelIterator constructor
  - ImagickPixelIterator::destroy — Deallocates resources associated with a PixelIterator
  - ImagickPixelIterator::getCurrentIteratorRow — Returns the current row of ImagickPixel objects
  - ImagickPixelIterator::getIteratorRow — Returns the current pixel iterator row
  - ImagickPixelIterator::getNextIteratorRow — Returns the next row of the pixel iterator
  - ImagickPixelIterator::getPreviousIteratorRow — Returns the previous row
  - ImagickPixelIterator::newPixelIterator — Returns a new pixel iterator
  - ImagickPixelIterator::newPixelRegionIterator — Returns a new pixel iterator
  - ImagickPixelIterator::resetIterator — Resets the pixel iterator
  - ImagickPixelIterator::setIteratorFirstRow — Sets the pixel iterator to the first pixel row
  - ImagickPixelIterator::setIteratorLastRow — Sets the pixel iterator to the last pixel row
  - ImagickPixelIterator::setIteratorRow — Set the pixel iterator row
  - ImagickPixelIterator::syncIterator — Syncs the pixel iterator
- ImagickPixelIteratorException — The ImagickPixelIteratorException class

- Exif — Exchangable Image Information (EXIF)
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Exif-Funktionen
- GD — Bildbearbeitung und GD
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - GD- und Image-Funktionen
  - GdImage — The GdImage class
  - GdFont — The GdFont class
- Gmagick
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Gmagick — The Gmagick class
  - GmagickDraw — The GmagickDraw class
  - GmagickPixel — The GmagickPixel class
- ImageMagick — Image Processing (ImageMagick)
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - Imagick — The Imagick class
  - ImagickDraw — Die Klasse ImagickDraw
  - ImagickDrawException — The ImagickDrawException class
  - ImagickException — The ImagickException class
  - ImagickKernel — Die Klasse ImagickKernel
  - ImagickKernelException — Die Klasse ImagickKernelException
  - ImagickPixel — Die Klasse ImagickPixel
  - ImagickPixelException — The ImagickPixelException class
  - ImagickPixelIterator — Die Klasse ImagickPixelIterator
  - ImagickPixelIteratorException — The ImagickPixelIteratorException class

# E-Mail-relevante Erweiterungen

# IMAP, POP3 and NNTP

# Einführung

Warnung

Diese Erweiterung ist seit PHP 8.4.0 DEPRECATED (veraltet) und UNBUNDLED (nicht mehr eingebunden).

Die Funktionen dieser Erweiterung ermöglichen die Kommunikation mit IMAP-, NNTP- und POP3-Servern sowie den Zugriff auf lokale Mailbox-Dateien.

Allerdings ist Vorsicht geboten, da einige IMAP-Funktionen nicht richtig mit dem POP-Protokoll funktionieren.

Warnung

Die IMAP-Erweiterung ist nicht thread-sicher; sie sollte nicht mit ZTS-Builds verwendet werden.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Anforderungen

Diese Erweiterung benötigt die c-client-Bibliothek. Die jeweils aktuelle Version des Quellcodes dieser Bibliothek findet sich unter » https://github.com/uw-imap/imap.

Wenn Sie die Bibliothek selbst kompilieren, ist es wichtig, dass Sie die Header-Dateien nicht direkt im Standard-Includeverzeichnis ablegen, da dies zu Namenskonflikten führen kann. Stattdessen sollten Sie ein neues Unterverzeichnis, z. B. /usr/local/imap-2000b/ mit zwei weiteren Unterverzeichnissen lib/ und include/ anlegen. Kopieren Sie alle *.h-Dateien aus dem c-client-Quellcodeverzeichnis in das neue include/-Verzeichnis und alle *.c-Dateien in das neue lib/-Verzeichnis. Die bei der Kompilierung des Bibliotheksquellcodes erzeugte Datei c-client.a kopieren Sie als libc-client.a ebenfalls in das neue lib/-Verzeichnis.

> Hinweis:

> Nähere Informationen zur Aktivierung der SSL- und Kerberos-Unterstützung der Bibliothek finden Sie in der Dokumentation, die im Quell-Paket enthaltenen ist.

> Hinweis: Mandrake Linux liefert die IMAP-Bibliothek libc-client.a) ohne Kerberos-Unterstützung aus. Eine seperate Version mit SSL-Unterstützung wird als client-PHP4.a mitgeliefert. Für die Kerberos-Unterstützung müssen Sie die Bibliothek selbst kompilieren.

## Installation

## PHP 8.4

Diese Erweiterung wurde ins » PECL-Repositorium verschoben und ist nicht mehr Teil von PHP ab PHP 8.4.0

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/imap.

## PHP < 8.4

Um diese Funktionen nutzen zu können, müssen Sie PHP mit --with-imap[=DIR] kompilieren, wobei DIR der Installationspräfix der c-client-Bibliothek ist. Wenn Sie diese wie oben angegeben installiert haben, können Sie --with-imap=/usr/local/imap-2000b als Konfigurationsoption angeben. Windows-Benutzer können die php_imap.dll DLL in php.ini einbinden.

> Hinweis: Je nachdem wie der c-client konfiguriert wurde, müssen Sie eventuell --with-imap-ssl=/path/to/openssl/ und/oder --with-kerberos=/path/to/kerberos zu den PHP-Konfigurationsoptionen hinzufügen.

Warnung

Die IMAP-Erweiterung ist nicht thread-sicher; sie sollte nicht mit ZTS-Builds verwendet werden.

Warnung

Die Erweiterungen IMAP, recode und YAZ können nicht zusammen verwendet werden. Diese Tatsache liegt darin begründet, dass alle diese Erweiterungen die gleichen internen Symbole benutzen. Hinweis: Yaz 2.0 und höher hat dieses Problem nicht.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

IMAP Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
imap.enable_insecure_rsh | "0" | `INI_SYSTEM` | Available as of PHP 7.1.25, 7.2.13 and 7.3.0. Formerly, it was implicitly enabled.

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`imap.enable_insecure_rsh` bool

  Establishing a connection to a server may invoke rsh or ssh commands, unless this php.ini option is disabled.

  Warnung

  Neither PHP nor the IMAP library filter mailbox names before passing them to rsh or ssh commands, thus passing untrusted data to this function without disabling this php.ini option is insecure.

## Ressource-Typen

Vor PHP 8.1.0 verwendete diese Erweiterung eine `imap`-Ressource, die von imap_open() zurückgegeben wurde und sich auf einen offenen IMAP-Stream bezog.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`NIL` (int)
  Seit PHP 8.1.0 veraltet.
`OP_DEBUG` (int)
`OP_READONLY` (int)
  Das Postfach nur zum Lesen öffnen
`OP_ANONYMOUS` (int)
  Für News keine .newsrc-Datei lesen oder schreiben (nur NNTP)
`OP_SHORTCACHE` (int)
`OP_SILENT` (int)
`OP_PROTOTYPE` (int)
`OP_HALFOPEN` (int)
  Verbindung aufbauen, aber noch kein Postfach öffnen (IMAP und NNTP)
`OP_EXPUNGE` (int)
`OP_SECURE` (int)
`CL_EXPUNGE` (int)
  Löschen aller dazu markierten Nachrichten beim Beenden der Verbindung mit imap_close()
`FT_UID` (int)
  Der Parameter ist eine UID
`FT_PEEK` (int)
  Das \Seen-Flag nicht setzen, falls es noch nicht gesetzt ist
`FT_NOT` (int)
`FT_INTERNAL` (int)
  Der Ergebnistext ist in internem Format, es wird keine Umwandlung der Zeilenenden zu CRLF vorgenommen.
`FT_PREFETCHTEXT` (int)
`ST_UID` (int)
  Die übergebene Sequenz enthält UIDs anstelle von Nachrichtennummern
`ST_SILENT` (int)
`ST_SET` (int)
`CP_UID` (int)
  Die Sequenznummern enthalten UIDs
`CP_MOVE` (int)
  Lösche Nachrichten aus dem aktuellen Postfach, nachdem sie mit imap_mail_copy() kopiert wurden.
`SE_UID` (int)
  Gebe UIDs anstelle von Nachrichtennummern zurück
`SE_FREE` (int)
`SE_NOPREFETCH` (int)
  Suchergebnisse nicht vorab übertragen
`SO_FREE` (int)
`SO_NOSERVER` (int)
`SA_MESSAGES` (int)
`SA_RECENT` (int)
`SA_UNSEEN` (int)
`SA_UIDNEXT` (int)
`SA_UIDVALIDITY` (int)
`SA_ALL` (int)
`LATT_NOINFERIORS` (int)
  Dieses Postfach enthält keine Unterpostfächer
`LATT_NOSELECT` (int)
  Dies ist nur ein Ordner, kein Postfach, und kann daher nicht geöffnet werden
`LATT_MARKED` (int)
  Dieses Postfach ist markiert. Wird nur von UW-IMAPD verwendet.
`LATT_UNMARKED` (int)
  Dieses Postfach ist nicht markiert. Wird nur von UW-IMAPD verwendet.
`LATT_REFERRAL` (int)
  Dieses Postfach bezieht sich auf eine Remote-Mailbox.
`LATT_HASCHILDREN` (int)
  Dieses Postfach enthält auswählbare Unterpostfächer.
`LATT_HASNOCHILDREN` (int)
  Dieses Postfach enthält keine auswählbaren Unterpostfächer.
`SORTDATE` (int)
  Sortierkriterium für imap_sort(): nach Sendedatum
`SORTARRIVAL` (int)
  Sortierkriterium für imap_sort(): nach Empfangsdatum
`SORTFROM` (int)
  Sortierkriterium für imap_sort(): nach erster Absender-Adresse
`SORTSUBJECT` (int)
  Sortierkriterium für imap_sort(): nach Betreff
`SORTTO` (int)
  Sortierkriterium für imap_sort(): nach erster Empfänger-Adresse
`SORTCC` (int)
  Sortierkriterium für imap_sort(): nach erster CC-Adresse
`SORTSIZE` (int)
  Sortierkriterium für imap_sort(): nach Größe
`TYPETEXT` (int)
  Primärer Typ des Textkörpers: unformatierter Text
`TYPEMULTIPART` (int)
  Primärer Typ des Textkörpers: multipart
`TYPEMESSAGE` (int)
  Primärer Typ des Textkörpers: verkapselte Nachricht
`TYPEAPPLICATION` (int)
  Primärer Typ des Textkörpers: Anwendungsdaten
`TYPEAUDIO` (int)
  Primärer Typ des Textkörpers: Audio
`TYPEIMAGE` (int)
  Primärer Typ des Textkörpers: statisches Bild
`TYPEVIDEO` (int)
  Primärer Typ des Textkörpers: Video
`TYPEMODEL` (int)
  Primärer Typ des Textkörpers: model
`TYPEOTHER` (int)
  Primärer Typ des Textkörpers: unbekannt
`ENC7BIT` (int)
  Kodierung des Textkörpers: 7 bit SMTP-Semantik-Daten
`ENC8BIT` (int)
  Kodierung des Textkörpers: 8 bit SMTP-Semantik-Daten
`ENCBINARY` (int)
  Kodierung des Textkörpers: 8 bit Binärdaten
`ENCBASE64` (int)
  Kodierung des Textkörpers: base-64-kodierte Daten
`ENCQUOTEDPRINTABLE` (int)
  Kodierung des Textkörpers: menschenlesbare 8 als 7 bit Daten
`ENCOTHER` (int)
  Kodierung des Textkörpers: unbekannt
`IMAP_OPENTIMEOUT` (int)
`IMAP_READTIMEOUT` (int)
`IMAP_WRITETIMEOUT` (int)
`IMAP_CLOSETIMEOUT` (int)
`IMAP_GC_ELT` (int)
  Garbage collector: lösche Elemente im Nachrichten-Cache.
`IMAP_GC_ENV` (int)
  Garbage collector: lösche Umschläge und Textkörper.
`IMAP_GC_TEXTS` (int)
  Garbage collector: lösche Texte.

# IMAP Funktionen

# Siehe auch

Dieses Dokument kann nicht alle von den enthaltenen Funktionen berührten Themenbereiche im Detail beschreiben. Weitergehende Informationen finden Sie in der Dokumentation zum c-client-Quellcode (docs/internal.txt) und in den folgenden RFC-Standarddokumenten:

- » RFC2821: `Simple Mail Transfer Protocol` (SMTP).
- » RFC2822: `Standard for ARPA internet text messages`.
- » RFC2060: `Internet Message Access Protocol` (IMAP) Version 4rev1.
- » RFC1939: `Post Office Protocol Version 3` (POP3).
- » RFC977: `Network News Transfer Protocol` (NNTP).
- » RFC2076: `Common Internet Message Headers`.
- » RFC2045, » RFC2046, » RFC2047, » RFC2048 & » RFC2049: `Multipurpose Internet Mail Extensions` (MIME).

Einen detaillierten Überblick der relevanten Themen bieten auch die Bücher » Programming Internet Email von David Wood und » Managing IMAP von Dianna Mullet & Kevin Mullet.

# imap_8bit

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_8bit — Konvertiert einen 8bit-String in einen quoted-printable String

### Beschreibung

function imap_8bit(string `$string`): string|false

Konvertiert einen 8bit-String gemäß » RFC2045, Abschnitt 6.7 in einen quoted-printable String.

### Parameter-Liste

`string`

  Der zu konvertierende 8bit-String

### Rückgabewerte

Der Eingabestring in quoted-printable-Kodierung. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- imap_qprint() - Konvertiert einen quoted-printable-kodierten String in einen 8-Bit-String

# imap_alerts

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_alerts — Liefert alle aufgetretenen IMAP-Alarmnachrichten

### Beschreibung

function imap_alerts(): array|false

Gibt alle IMAP-Alarmbenachrichtigungen seit dem letzen Aufruf von imap_alerts() oder seit Anfang des Skripts zurück.

Durch den Aufruf von imap_alerts() wird der Alarmstack gelöscht. Die IMAP-Spezifikation schreibt vor, dass alle Alarmmeldungen an den Benutzer weitergegebenen werden müssen.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein Array mit allen erzeugten IMAP-Alarmmeldungen zurück oder `false`, wenn keine Alarmmeldungen vorliegen.

### Siehe auch

- imap_errors() - Liefert alle bisher aufgetretenen Fehlermeldungen

# imap_append

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_append — Hängt eine String-Nachricht an ein Postfach an

### Beschreibung

function imap_append(
IMAP\Connection `$imap`,
string `$folder`,
string `$message`,
?string `$options` = `null`,
?string `$internal_date` = `null`
): bool

Der in `message` übergebene String wird als Nachricht an das Postfach `folder` angefügt.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`folder`

  Der Name des Postfachs, siehe imap_open() für nähere Informationen

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`message`

  Die anzufügende Nachricht als String

  Bei Verbindungen mit dem Cyrus-IMAP-Server ist es zwingend erforderlich, "\r\n" als Zeilenende zu verwenden. Mit einem einfachen "\n" schlägt die Operation fehl.

`options`

  Wenn angegeben, werden die in `options` gesetzten Optionen auch ins Postfach `folder` geschrieben.

`internal_date`

  Wenn dieser Parameter angegeben wird, wird das INTERNALDATE für die hinzugefügte Nachricht gesetzt. Der Parameter sollte ein Datumsstring sein, der den rfc2060-Spezifikationen für einen date_time-Wert entspricht.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.
8.0.0 | `options` und `internal_date` sind jetzt nullable (akzeptieren den `null`-Wert).

### Beispiele

Beispiel #1 imap_append()-Beispiel

    <?php
    $imap = imap_open("{imap.example.org}INBOX.Drafts", "username", "password");

    $check = imap_check($imap);
    echo "Anzahl der Nachrichten vor dem Anhängen: ". $check->Nmsgs . "\n";

    imap_append($imap, "{imap.example.org}INBOX.Drafts"
                       , "From: me@example.com\r\n"
                       . "To: you@example.com\r\n"
                       . "Subject: test\r\n"
                       . "\r\n"
                       . "this is a test message, please ignore\r\n"
                       );

    $check = imap_check($imap);
    echo "Anzahl der Nachrichten nach dem Anhängen: ". $check->Nmsgs . "\n";

    imap_close($imap);
    ?>

# imap_base64

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_base64 — Dekodiert Base64-kodierten Text

### Beschreibung

function imap_base64(string `$string`): string|false

Dekodiert den angegebenen Base64-kodierten `string`.

### Parameter-Liste

`string`

  Der zu dekodierende Text

### Rückgabewerte

Gibt den dekodierten Text als String zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- imap_binary() - Konvertiert einen 8bit-String in einen Base64-kodierten String
- base64_encode() - Kodiert Daten MIME base64
- base64_decode() - Dekodiert MIME base64-kodierte Daten
- » RFC2045, Abschnitt 6.8

# imap_binary

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_binary — Konvertiert einen 8bit-String in einen Base64-kodierten String

### Beschreibung

function imap_binary(string `$string`): string|false

Konvertiert einen 8bit-String gemäß » RFC2045, Abschnitt 6.8 in einen Base64-kodierten String.

### Parameter-Liste

`string`

  Der zu konvertierende 8bit-String

### Rückgabewerte

Gibt einen Base64-kodierten String zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- imap_base64() - Dekodiert Base64-kodierten Text

# imap_body

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_body — Liefert den Textkörper einer Nachricht

### Beschreibung

function imap_body(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

imap_body() gibt den Textkörper der mit `message_num` angegebenen Nachricht aus dem aktuellen Postfach zurück.

imap_body() gibt eine 1:1-Kopie des gesamten Nachrichtenkörpers zurück. Um einzelne Teile einer mehrteiligen MIME-kodierten Nachricht auszulesen, müssen Sie zunächst die Struktur der Nachricht mit imap_fetchstructure() analysieren, um anschließend einzelne Komponenten mit imap_fetchbody() anzufordern.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_num`

  Die Nummer der Nachricht

`flags`

  Der optionale Parameter `flags` kann eine Bitmaske mit folgenden Optionen enthalten:

  - `FT_UID` - `message_num` ist eine UID
  - `FT_PEEK` - Das \Seen-Flag nicht setzen, falls es nicht bereits gesetzt ist
  - `FT_INTERNAL` - Rückgabe im internen Format ohne Umwandlung der Zeilenenden in CRLF.

### Rückgabewerte

Gibt den Textkörper der gewünschten Nachricht als String zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

# imap_bodystruct

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_bodystruct — Liefert die Struktur eines bestimmten Nachrichtenteils

### Beschreibung

function imap_bodystruct(IMAP\Connection `$imap`, int `$message_num`, string `$section`): stdClass|false

Gibt die Struktur des mit `section` angegebenen Teils der Nachricht `message_num` zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_num`

  Die Nummer der Nachricht

`section`

  Der gewünschte Nachrichtenteil

### Rückgabewerte

Gibt ein Objekt mit den gewünschten Informationen zurück. Bei einem Fehler wird `false` zurückgegeben. Zum Aufbau des Objekts und seiner Eigenschaften siehe imap_fetchstructure().

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_fetchstructure() - Liefert die Struktur einer Nachricht

# imap_check

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_check — Prüft das aktuelle Postfach

### Beschreibung

function imap_check(IMAP\Connection `$imap`): stdClass|false

Prüft Informationen zum aktuellen Postfach.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

### Rückgabewerte

Die Informationen werden als Objekt mit folgenden Eigenschaften zurückgegeben:

- `Date` - Die aktuelle Serverzeit, formatiert gemäß » RFC2822
- `Driver` - Das Protokoll des Postfachs: POP3, IMAP oder NNTP
- `Mailbox` - Der Name des Postfachs
- `Nmsgs` - Die Anzahl der Nachrichten im Postfach
- `Recent` - Die Anzahl kürzlich eingetroffener Nachrichten im Postfach

Gibt bei einem Fehler `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_check()-Beispiel

    <?php

    $imap = imap_check($imap_stream);
    var_dump($imap);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    object(stdClass)(5) {
      ["Date"]=>
      string(37) "Wed, 10 Dec 2003 17:56:54 +0100 (CET)"
      ["Driver"]=>
      string(4) "imap"
      ["Mailbox"]=>
      string(54)
      "{www.example.com:143/imap/user="foo@example.com"}INBOX"
      ["Nmsgs"]=>
      int(1)
      ["Recent"]=>
      int(0)
    }

# imap_clearflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_clearflag_full — Löscht die Flags einer Nachricht

### Beschreibung

function imap_clearflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

Diese Funktion bewirkt bei den mit `sequence` spezifizerten Nachrichten das Löschen der in `flag` angegebenen Flags.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`sequence`

  Eine Reihe von Nachrichtennummern. Diese können als Aufzählung in der Form `X,Y` oder als Intervall in der Form `X:Y` angegeben werden.

`flag`

  Die folgenden Flags werden unterstüzt: "\\Seen", "\\Answered", "\\Flagged", "\\Deleted" und "\\Draft" (siehe auch » RFC2060)

`options`

  `options` ist eine Bitmaske und kann nur die folgende Option enthalten:

  - `ST_UID` - der Parameter `sequence` besteht aus UIDs anstelle von Nachrichtennummern.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Wenn `options` ungültig ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.
8.0.0 | Bei ungültigen Parameterwerten von `options` wird nun ein ValueError geworfen; zuvor wurde eine Warnung ausgegeben und die Funktion gab `false` zurück.

### Siehe auch

- imap_setflag_full() - Setzt Nachrichtenflags

# imap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_close — Schließt einen IMAP-Stream

### Beschreibung

function imap_close(IMAP\Connection `$imap`, int `$flags` = 0): true

Schließt den angegebenen IMAP-Stream.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`flags`

  Wenn `CL_EXPUNGE` als `flag` übergeben wird, werden alle zum Löschen vorgemerkten Nachrichten des aktuellen Postfachs vor Beenden der Verbindung endgültig gelöscht. Dies lässt sich auch durch die Funktion imap_expunge() erreichen.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Wenn `flags` ungültig ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.
8.0.0 | Bei ungültigen Parameterwerten von `flags` wird nun ein ValueError geworfen; zuvor wurde eine Warnung ausgegeben und die Funktion gab `false` zurück.

### Siehe auch

- imap_open() - Öffnet einen IMAP-Stream zu einem Postfach

# imap_create

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_create — Alias von imap_createmailbox()

### Beschreibung

Diese Funktion ist ein Alias für: imap_createmailbox().

# imap_createmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_createmailbox — Legt ein neues Postfach an

### Beschreibung

function imap_createmailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Legt ein neues Postfach mit dem Namen `mailbox` an.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`mailbox`

  Der Name des Postfachs, siehe imap_open() für nähere Informationen. Namen, die nicht-ASCII-Zeichen enthalten, sollten mit imap_utf7_encode() kodiert werden.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_createmailbox()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
         or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $name1 = "phpnewbox";
    $name2 = imap_utf7_encode("phpnewböx"); // phpnewb&w7Y-x

    $newname = $name1;

    echo "Der neue Name wird '$name1' sein<br />\n";

    // Legen wir nun ein neues Postfach "phptestbox" in Ihrem Posteingangsordner an,
    // überprüfen seinen Status nach der Erstellung und löschen es schließlich,
    // um den Posteingang wieder in den Ausgangszustand zu versetzen.

    if (@imap_createmailbox($mbox, imap_utf7_encode("{imap.example.org}INBOX.$newname"))) {
        $status = @imap_status($mbox, "{imap.example.org}INBOX.$newname", SA_ALL);
        if ($status) {
            echo "Ihr neues Postfach '$name1' hat den folgenden Status:<br />\n";
            echo "Nachrichten:   " . $status->messages    . "<br />\n";
            echo "Neueste:     " . $status->recent      . "<br />\n";
            echo "Ungelesen:     " . $status->unseen      . "<br />\n";
            echo "UIDnext:    " . $status->uidnext     . "<br />\n";
            echo "UIDvalidity:" . $status->uidvalidity . "<br />\n";

            if (imap_renamemailbox($mbox, "{imap.example.org}INBOX.$newname", "{imap.example.org}INBOX.$name2")) {
                echo "Neues Postfach von '$name1' in '$name2' umbenannt<br />\n";
                $newname = $name2;
            } else {
                echo "imap_renamemailbox bei neuem Postfach fehlgeschlagen: " . imap_last_error() . "<br />\n";
            }
        } else {
            echo "imap_status bei neuem Postfach fehlgeschlagen: " . imap_last_error() . "<br />\n";
        }

        if (@imap_deletemailbox($mbox, "{imap.example.org}INBOX.$newname")) {
            echo "Neues Postfach gelöscht, um den Ausgangszustand wiederherzustellen<br />\n";
        } else {
            echo "imap_deletemailbox bei neuem Postfach fehlgeschlagen: " . implode("<br />\n", imap_errors()) . "<br />\n";
        }

    } else {
        echo "Konnte kein neues Postfach anlegen: " . implode("<br />\n", imap_errors()) . "<br />\n";
    }

    imap_close($mbox);
    ?>

### Siehe auch

- imap_renamemailbox() - Ändert den Namen eines Postfachs
- imap_deletemailbox() - Löscht ein Postfach

# imap_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_delete — Markiert eine Nachricht im aktuellen Postfach zur Löschung

### Beschreibung

function imap_delete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Die mit `message_nums` angegebene Nachricht wird zur Löschung vorgemerkt. Entsprechend markierte Nachrichten bleiben im Postfach erhalten, bis entweder imap_expunge() aufgerufen wird oder imap_close() mit der Option `CL_EXPUNGE` beim Schließen der Verbindung.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_nums`

  Ein String, der eine oder mehrere Nachrichten im IMAP4-üblichen Sequenzformat darstellt (`"n"`, `"n:m"` oder eine Kombination daraus, durch Kommas getrennt).

`flags`

  Mit Hilfe der Option `FT_UID` kann festgelegt werden, dass `message_nums` `UID`s anstelle der Nachrichtennummern enthält.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Wenn `flags` ungültig ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.
8.0.0 | Bei ungültigen Parameterwerten von `flags` wird nun ein ValueError geworfen; zuvor wurde eine Warnung ausgegeben und die Funktion gab `false` zurück.

### Beispiele

Beispiel #1 imap_delete()-Beispiel

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
        or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);
    echo "Anzahl der Nachrichten vor imap_delete: " . $check->Nmsgs . "<br />\n";

    imap_delete($mbox, 1);

    $check = imap_mailboxmsginfo($mbox);
    echo "Anzahl der Nachrichten nach imap_delete: " . $check->Nmsgs . "<br />\n";

    imap_expunge($mbox);

    $check = imap_mailboxmsginfo($mbox);
    echo "Anzahl der Nachrichten nach imap_expunge: " . $check->Nmsgs . "<br />\n";

    imap_close($mbox);
    ?>

### Anmerkungen

> Hinweis:

> Bei IMAP-Postfächern können Nachrichten-Flags serverseitig nicht zwischen Verbindungen gespeichert werden; markierte Nachrichten sollten daher noch während der aktuellen Verbindung mit imap_expunge() entfernt werden, ansonsten bleiben sie möglicherweise ohne Löschmarkierung weiter erhalten.

### Siehe auch

- imap_undelete() - Nimmt eine bereits gesetzte Löschmarkierung einer Nachricht zurück
- imap_expunge() - Löscht alle zum Löschen markierte Nachrichten
- imap_close() - Schließt einen IMAP-Stream

# imap_deletemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_deletemailbox — Löscht ein Postfach

### Beschreibung

function imap_deletemailbox(IMAP\Connection `$imap`, string `$mailbox`): bool

Löscht das mit `mailbox` angegebene Postfach.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`mailbox`

  Der Name des Postfachs, für weitere Informationen siehe imap_open()

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_createmailbox() - Legt ein neues Postfach an
- imap_renamemailbox() - Ändert den Namen eines Postfachs
- Zum `mbox`-Format siehe imap_open() - Öffnet einen IMAP-Stream zu einem Postfach

# imap_errors

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_errors — Liefert alle bisher aufgetretenen Fehlermeldungen

### Beschreibung

function imap_errors(): array|false

Gibt alle IMAP-Fehlermeldungen zurück (falls vorhanden), die im Verlauf der Seitenanfrage oder seit dem letzten Löschen der Fehlerliste aufgetreten sind.

Wenn imap_errors() aufgerufen wird, wird der Fehlerstack anschließend gelöscht.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Diese Funktion gibt ein Array aller IMAP-Fehlermeldungen seit dem letzten Aufruf von imap_errors() oder seit dem Beginn des Skripts zurück. Wenn keine Fehlermeldungen vorhanden sind, wird `false` zurückgegeben.

### Siehe auch

- imap_last_error() - Liefert den zuletzt aufgetretenen IMAP-Fehler
- imap_alerts() - Liefert alle aufgetretenen IMAP-Alarmnachrichten

# imap_expunge

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_expunge — Löscht alle zum Löschen markierte Nachrichten

### Beschreibung

function imap_expunge(IMAP\Connection `$imap`): true

Löscht alle Nachrichten im aktuellen Postfach, die durch die Funktionen imap_delete(), imap_mail_move() oder imap_setflag_full() zum Löschen vorgemerkt wurden.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

# imap_fetch_overview

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetch_overview — Liefert eine Zusammenfassung der Kopfdaten von Nachrichten

### Beschreibung

function imap_fetch_overview(IMAP\Connection `$imap`, string `$sequence`, int `$flags` = 0): array|false

Die Funktion fragt die Kopfdaten der mit sequence() angegebenen Nachrichten ab und gibt eine Zusammenfassung darüber zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`sequence`

  Die Beschreibung der gewünschten Nachrichten. Mehrere Nachrichten können durch Komma getrennt angegeben werden (`X,Y`), Nachrichtenbereiche durch einen Doppelpunkt zwischen der ersten und der letzten Nachricht (`X:Y`).

`flags`

  Wenn dieser Parameter auf `FT_UID` gesetzt wird, werden die einzelnen Einträge der Nachrichtenliste `sequence` als UIDs und nicht als Nachrichtennummern interpretiert.

### Rückgabewerte

Gibt ein Array von Objekten zurück, die jeweils den Nachrichtenkopf einer Nachricht beschreiben. Das Objekt hat eine Eigenschaft nur dann, wenn sie auch existiert. Die möglichen Eigenschaften sind:

- `subject` - die Betreffzeile der Nachricht
- `from` - der Absender
- `to` - der Empfänger
- `date` - der Sendezeitpunkt
- `message_id` - die ID der Nachricht
- `references` - die Referenz auf die Nachricht mit dieser ID
- `in_reply_to` - die Antwort auf die Nachricht mit dieser ID
- `size` - die Größe in Bytes
- `uid` - die UID innerhalb des Postfachs
- `msgno` - die aktuelle Nachrichtennummer innerhalb des Postfachs
- `recent` - diese Nachricht ist als kürzlich eingetroffen markiert
- `flagged` - diese Nachricht ist als wichtig markiert
- `answered` - diese Nachricht ist als beantwortet markiert
- `deleted` - diese Nachricht ist zur Löschung vorgemerkt
- `seen` - diese Nachricht ist als bereits gelesen markiert
- `draft` - diese Nachricht ist als Entwurf markiert
- `udate` - der UNIX-Zeitstempel des Ankunftsdatums

Diese Funktion gibt bei einem Fehler `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_fetch_overview()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password")
         or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $MC = imap_check($mbox);

    // Rufe eine Übersicht aller Nachrichten im Eingangspostfach INBOX ab
    $result = imap_fetch_overview($mbox,"1:{$MC->Nmsgs}",0);
    foreach ($result as $overview) {
        echo "#{$overview->msgno} ({$overview->date}) - From: {$overview->from}
        {$overview->subject}\n";
    }
    imap_close($mbox);
    ?>

### Siehe auch

- imap_fetchheader() - Liefert den Kopf einer Nachricht

# imap_fetchbody

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchbody — Liefert einen bestimmten Abschnitt aus dem Textkörper einer Nachricht

### Beschreibung

function imap_fetchbody(
IMAP\Connection `$imap`,
int `$message_num`,
string `$section`,
int `$flags` = 0
): string|false

Gibt den mit `section` angebenen Teil aus dem Textkörper der Nachricht `message_num` im aktuellen Postfach zurück. Der Teil des Textkörpers wird dabei nicht dekodiert.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_num`

  Die Nummer der Nachricht

`section`

  Die Nummer des gewünschten Nachrichtenteils. Diese wird gemäß der IMAP4-Spezifikation als String von mit Punkten getrennten Zahlen angegeben.

`flags`

  Eine Bitmaske, die sich aus folgenden Werten zusammensetzen kann:

  - `FT_UID` - `message_num` ist eine UID
  - `FT_PEEK` - Das \Seen-Flag nicht setzen, falls es nicht bereits gesetzt ist
  - `FT_INTERNAL` - Rückgabe im internen Format ohne Umwandlung der Zeilenenden in CRLF.

### Rückgabewerte

Gibt einen bestimmten Teil des Textkörpers der angegebenen Nachricht als Textstring zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_savebody() - Speichert einen Teil des Nachrichtentextes in einer Datei
- imap_fetchstructure() - Liefert die Struktur einer Nachricht

# imap_fetchheader

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchheader — Liefert den Kopf einer Nachricht

### Beschreibung

function imap_fetchheader(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): string|false

Diese Funktion gibt den kompletten ungefilterten Kopf der angegebenen Nachricht gemäß » RFC2822 zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_num`

  Die Nummer der Nachricht

`flags`

  Folgende Flags können in `flags` gesetzt werden:

  - `FT_UID` - `message_num` ist eine UID
  - `FT_INTERNAL` - Der zurückgegebene String ist im internen Format ohne Umwandlung der Zeilenenden in CRLF.
  - `FT_PREFETCHTEXT` - Der Textkörper der Nachricht wird zusammen mit dem Kopf zum Client übertragen. Dies vermeidet einen weiteren Zugriff auf den IMAP-Server, wenn die gesamte Nachricht bearbeitet werden soll (z. B. zum Abspeichern in einer lokalen Datei).

### Rückgabewerte

Gibt den Kopf der angegebenen Nachricht als String zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_fetch_overview() - Liefert eine Zusammenfassung der Kopfdaten von Nachrichten

# imap_fetchmime

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

imap_fetchmime — Fetch MIME headers for a particular section of the message

### Beschreibung

function imap_fetchmime(
IMAP\Connection `$imap`,
int `$message_num`,
string `$section`,
int `$flags` = 0
): string|false

Fetch the MIME headers of a particular section of the body of the specified messages.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_num`

  The message number

`section`

  The part number. It is a string of integers delimited by period which index into a body part list as per the IMAP4 specification

`flags`

  A bitmask with one or more of the following:

  - `FT_UID` - The `message_num` is a UID
  - `FT_PEEK` - Do not set the \Seen flag if not already set
  - `FT_INTERNAL` - The return string is in internal format, will not canonicalize to CRLF.

### Rückgabewerte

Returns the MIME headers of a particular section of the body of the specified messages as a text string, Bei einem Fehler wird `false` zurückgegeben..

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_fetchbody() - Liefert einen bestimmten Abschnitt aus dem Textkörper einer Nachricht
- imap_fetchstructure() - Liefert die Struktur einer Nachricht
- imap_fetchheader() - Liefert den Kopf einer Nachricht

# imap_fetchstructure

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchstructure — Liefert die Struktur einer Nachricht

### Beschreibung

function imap_fetchstructure(IMAP\Connection `$imap`, int `$message_num`, int `$flags` = 0): stdClass|false

Gibt alle Strukturinformationen für die angegebene Nachricht zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_num`

  Die Nummer der Nachricht

`flags`

  Dieser optionale Parameter hat nur eine einzige Option, `FT_UID`, die angibt, dass `message_num` als `UID` behandelt werden soll.

### Rückgabewerte

Gibt ein Objekt mit Eigenschaften zurück, die in der Tabelle weiter unten aufgelistet werden. Bei einem Fehler wird `false` zurückgegeben.

Zurückgegebenes Objekt für imap_fetchstructure()
type | Primärer Typ des Textkörpers
encoding | Übertragungskodierung des Textkörpers
ifsubtype | `true`, falls ein Untertyp-Eintrag existiert
subtype | MIME-Untertyp
ifdescription | `true`, falls ein Beschreibungstext existiert
description | Beschreibungstext
ifid | `true`, falls ein Identifikationstext existiert
id | Identifikationstext
lines | Anzahl der Zeilen
bytes | Größe in Bytes
ifdisposition | `true`, falls ein Eintrag zur Verwendungsart (disposition) existiert
disposition | Verwendungsart
ifdparameters | `true`, falls ein dparameters-Array existiert
dparameters | Ein Array von Objekten, wobei jedes Objekt eine `"attribute"`- und eine `"value"`-Eigenschaft hat, die den Parametern der MIME-Kopfzeile `Content-disposition` entsprechen.
ifparameters | `true`, falls ein "parameters"-Array existiert
parameters | Ein Array von Objekten mit je einer `"attribute"`- und einer `"value"`-Eigenschaft.
parts | Wenn der Nachrichtenteil selbst weitere untergeordnete MIME-Nachrichtenteile enthält, wird hier ein Array mit Objekten für diese Teile angelegt. Die Elemente dieses Arrays sind selbst jeweils wieder Objekte mit der hier beschriebenen Struktur.

Gängige primäre Nachrichtentypen (der Wert kann sich je nach Bibliothek ändern; die Verwendung der Konstanten wird empfohlen)
Wert | Typ | Konstante
--- | --- | ---
0 | text | TYPETEXT
1 | multipart | TYPEMULTIPART
2 | message | TYPEMESSAGE
3 | application | TYPEAPPLICATION
4 | audio | TYPEAUDIO
5 | image | TYPEIMAGE
6 | video | TYPEVIDEO
7 | model | TYPEMODEL
8 | other | TYPEOTHER

Gängige Übertragungskodierungen (der Wert kann sich je nach Bibliothek ändern; die Verwendung der Konstanten wird empfohlen)
Wert | Typ | Konstante
--- | --- | ---
0 | 7bit | ENC7BIT
1 | 8bit | ENC8BIT
2 | Binary | ENCBINARY
3 | Base64 | ENCBASE64
4 | Quoted-Printable | ENCQUOTEDPRINTABLE
5 | other | ENCOTHER

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_fetchbody() - Liefert einen bestimmten Abschnitt aus dem Textkörper einer Nachricht
- imap_bodystruct() - Liefert die Struktur eines bestimmten Nachrichtenteils

# imap_fetchtext

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchtext — Alias von imap_body()

### Beschreibung

Diese Funktion ist ein Alias für: imap_body().

# imap_gc

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_gc — Leert den IMAP-Cache

### Beschreibung

function imap_gc(IMAP\Connection `$imap`, int `$flags`): true

Säubert den Cache von Einträgen eines bestimmtes Typs.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`flags`

  Der zu löschende Cache. Es kann eine oder eine Kombination der folgenden Konstanten sein: `IMAP_GC_ELT` (Cache-Elemente der Nachricht), `IMAP_GC_ENV` (Umschlag und Textkörper) und `IMAP_GC_TEXTS` (Texte).

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Wenn `flags` ungültig ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.
8.0.0 | Bei ungültigen Parameterwerten von `flags` wird nun ein ValueError geworfen; zuvor wurde eine Warnung ausgegeben und die Funktion gab `false` zurück.

### Beispiele

Beispiel #1 imap_gc()-Beispiel

    <?php

    $mbox = imap_open("{imap.example.org:143}", "username", "password");

    imap_gc($mbox, IMAP_GC_ELT);

    ?>

# imap_get_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_get_quota — Liefert Quota-Einstellungen und Nutzungsstatistik der Postfächer

### Beschreibung

function imap_get_quota(IMAP\Connection `$imap`, string `$quota_root`): array|false

imap_get_quota() ermittelt die aktuellen Quota-Einstellungen und tatsächlich genutzten Ressourcen für Postfächer.

Für die Ausführung dieser Funktion ist ein IMAP-Benutzer mit Administrationsrechten erforderlich, eine nichtadministrative Variante der Funktion ist imap_get_quotaroot().

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`quota_root`

  `quota_root` sollte normalerweise in der Form `user.name` angegeben werden. name ist dabei der Name des Postfachs, für das Informationen geliefert werden sollen.

### Rückgabewerte

Gibt ein Array mit den zwei Integer-Elementen limit und usage zurück, die den insgesamt verfügbaren und den zur Zeit vom Postfach genutzten Speicherplatz angeben. Im Fehlerfall wird `false` zurückgegeben.

Ab PHP 4.3 hält sich die Funktion genauer an die Vorgaben aus » RFC2087. Das Ergebnisarray unterstützt nun eine unbegrenzte Anzahl von Ressourcenwerten (d. h. der Nachrichten oder Unterordner). Für jede Ressource wird ein Arrayelement mit dem Namen der Ressource als Key angelegt, die einzelnen Arrayelemente sind wiederum Arrays mit Angaben zu Limit und Nutzung.

Aus Gründen der Rückwärtskompatibilität werden außerdem weiterhin die beiden ursprünglichen Arrayelemente limit und usage zurückgegeben, ihre weitere Nutzung wird allerdings nicht empfohlen.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_get_quota()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $quota_value = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_value)) {
        echo "Aktuell genutzt: " . $quota_value['usage'];
        echo "Verfügbar (Limit): " . $quota_value['limit'];
    }

    imap_close($mbox);
    ?>

Beispiel #2 Beispiel für imap_get_quota() ab 4.3 und aufwärts

    <?php
    $mbox = imap_open("{imap.example.org}", "mailadmin", "password", OP_HALFOPEN)
          or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $quota_values = imap_get_quota($mbox, "user.kalowsky");
    if (is_array($quota_values)) {
       $storage = $quota_values['STORAGE'];
       echo "Speicherplatz (aktuell genutzt): " .  $storage['usage'];
       echo "Speicherplatz (Limit): " .  $storage['limit'];

       $message = $quota_values['MESSAGE'];
       echo "Anzahl Nachrichten (aktuell): " .  $message['usage'];
       echo "Anzahl Nachrichten (Limit): " .  $message['limit'];

       /* ...  */
    }

    imap_close($mbox);
    ?>

### Anmerkungen

Diese Funktion ist aktuell erst ab der Bibliotheksversion c-client2000 verfügbar.

Der angegebene `imap` muss als Mail-Administrator geöffnet werden, sonst schlägt diese Funktion fehl.

### Siehe auch

- imap_open() - Öffnet einen IMAP-Stream zu einem Postfach
- imap_set_quota() - Legt die Größenbeschränkung für ein Postfach fest
- imap_get_quotaroot() - Liefert die Quota-Einstellungen für ein Benutzerpostfach

# imap_get_quotaroot

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imap_get_quotaroot — Liefert die Quota-Einstellungen für ein Benutzerpostfach

### Beschreibung

function imap_get_quotaroot(IMAP\Connection `$imap`, string `$mailbox`): array|false

Gibt die Quota-Einstellungen für den aktuellen Benutzer zurück. Die ermittelten Quota-Einstellungen gelten über alle Postfächer des Benutzers, der Nutzungswert für die aktuell im angegebenen Postfach genutzte Kapazität.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`mailbox`

  Der Name des zu untersuchenden Postfachs, z. B. INBOX.

### Rückgabewerte

Gibt ein Array zurück mit Ressourcennamen als Index und Arrays mit den Elementen limit und usage als Werte, die das aktuelle Limit sowie die tatsächliche Nutzung der jeweiligen Ressource für das angegebene Postfach angeben.

Die Funktion gibt `false` zurück, wenn Fehler auftreten, und ein Array mit Verbindungsinformationen, falls die Antwort des Servers nicht verarbeitet werden konnte.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_get_quotaroot()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org}", "kalowsky", "password", OP_HALFOPEN)
          or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $quota = imap_get_quotaroot($mbox, "INBOX");
    if (is_array($quota)) {
       $storage = $quota['STORAGE'];
       echo "Speicherplatz (aktuell genutzt): " .  $storage['usage'];
       echo "Speicherplatz (Limit): " .  $storage['limit'];

       $message = $quota['MESSAGE'];
       echo "Anzahl Nachrichten (aktuell): " .  $message['usage'];
       echo "Anzahl Nachrichten (Limit): " .  $message['limit'];

       /* ...  */

    }

    imap_close($mbox);
    ?>

### Anmerkungen

Diese Funktion ist aktuell erst ab der Bibliotheksversion c-client2000 verfügbar.

Das zu prüfende Postfach muss dem Benutzer gehören, für den `imap` geöffnet wurde.

### Siehe auch

- imap_open() - Öffnet einen IMAP-Stream zu einem Postfach
- imap_set_quota() - Legt die Größenbeschränkung für ein Postfach fest
- imap_get_quota() - Liefert Quota-Einstellungen und Nutzungsstatistik der Postfächer

# imap_getacl

(PHP 5, PHP 7, PHP 8)

imap_getacl — Liefert die Liste der Zugriffsrechte (ACL) für ein Postfach

### Beschreibung

function imap_getacl(IMAP\Connection `$imap`, string `$mailbox`): array|false

Gibt die Zugriffsrechte (ACL, Access Control List) für ein gegebenes Postfach zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`mailbox`

  Der Name des Postfachs, siehe imap_open() für weitere Informationen

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

### Rückgabewerte

Gibt ein Array mit Postfachnamen als Schlüssel und Zugriffsrecht-Listen als Wert zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_getacl()-Beispiel

    <?php

    print_r(imap_getacl($imap, 'user.joecool'));

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [asubfolder] => lrswipcda
        [anothersubfolder] => lrswipcda
    )

### Anmerkungen

Diese Funktion ist aktuell erst ab der Bibliotheksversion c-client2000 verfügbar.

### Siehe auch

- imap_setacl() - Legt die ACL (Zugriffsrechte) für ein Postfach fest

# imap_getmailboxes

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getmailboxes — Liefert detaillierte Informationen zu allen Postfächern

### Beschreibung

function imap_getmailboxes(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Gibt Informationen über die Postfächer zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`reference`

  Die Angabe des Servers in der in imap_open() beschriebenen Form.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`pattern`

  Gibt an, wo in der Postfach-Hierarchie mit der Suche begonnen werden soll.

  Es gibt zwei Sonderzeichen, die man als Teil von `pattern` verwenden kann: '`*`' und '`%`'. '`*`' heißt, dass alle Postfächer zurückgegeben werden sollen. Wenn man `pattern` als '`*`' übergibt, so erhält man eine Liste der vollständigen Postfach-Hierarchie. '`%`' heißt, dass nur die aktuelle Stufe zurückgegeben wird. '`%`' als Wert des Parameters `pattern` gibt nur die Postfächer der obersten Ebene zurück. '`~/mail/%`' unter `UW_IMAPD` gibt alle Postfächer des Verzeichnisses ~/mail zurück, aber keine aus dessen Unterverzeichnissen.

### Rückgabewerte

Gibt ein Array zurück, das Objekte mit Postfachbeschreibungen enthält. Jedes Objekt verfügt über die Attribute `name` für den Namen des Postfachs, `delimiter` für das gültige Hierachietrennzeichen innerhalb des Hierachieabschnitts, in dem sich das Postfach befindet, und den Eigenschaften des Postfachs in `attributes`. Die Eigenschaften setzen sich als Bitmaske aus folgenden möglichen Werten zusammen:

- `LATT_NOINFERIORS` - Dieses Postfach enthält keine Unterpostfächer und kann auch keine enthalten. Der Aufruf von imap_createmailbox() wird für dieses Postfach fehlschlagen.

- `LATT_NOSELECT` - Dieses Postfach enthält nur Unterpostfächer aber keine Nachrichten; es kann nicht geöffnet werden.

- `LATT_MARKED` - Dieses Postfach ist markiert. Das bedeutet, dass es neue Nachrichten enthalten kann, seitdem es zuletzt geprüft wurde. Wird nicht von allen IMAP-Servern unterstützt.

- `LATT_UNMARKED` - Dieses Postfach ist nicht markiert, d. h. es enthält keine neuen Nachrichten. Wenn entweder `MARKED` oder `UNMARKED` vorhanden ist, kann man davon ausgehen, das der IMAP-Server dieses Feature für dieses Postfach unterstützt.

- `LATT_REFERRAL` - Dieses Postfach bezieht sich auf eine Remote-Mailbox.

- `LATT_HASCHILDREN` - Dieses Postfach enthält auswählbare Unterpostfächer.

- `LATT_HASNOCHILDREN` - Dieses Postfach enthält keine auswählbaren Unterpostfächer.

Diese Funktion gibt bei einem Fehler `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_getmailboxes()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $list = imap_getmailboxes($mbox, "{imap.example.org}", "*");
    if (is_array($list)) {
        foreach ($list as $key => $val) {
            echo "($key) ";
            echo imap_utf7_decode($val->name) . ",";
            echo "'" . $val->delimiter . "',";
            echo $val->attributes . "<br />\n";
        }
    } else {
        echo "imap_getmailboxes schlug fehl: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### Siehe auch

- imap_getsubscribed() - Liefert die Liste aller abonnierten Postfächer

# imap_getsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getsubscribed — Liefert die Liste aller abonnierten Postfächer

### Beschreibung

function imap_getsubscribed(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Gibt Informationen zu den abonnierten Postfächern zurück.

Diese Funktion ist weitgehend identisch zu imap_getmailboxes(), beachtet aber nur Postfächer, die der Benutzer bereits abonniert hat.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`reference`

  Die Angabe des Servers in der in imap_open() beschriebenen Form.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`pattern`

  Gibt an, wo in der Postfach-Hierarchie mit der Suche begonnen werden soll.

  Es gibt zwei Sonderzeichen, die man als Teil von `pattern` verwenden kann: '`*`' und '`%`'. '`*`' heißt, dass alle Postfächer zurückgegeben werden sollen. Wenn man `pattern` als '`*`' übergibt, so erhält man eine Liste der vollständigen Postfach-Hierarchie. '`%`' heißt, dass nur die aktuelle Stufe zurückgegeben wird. '`%`' als Wert des Parameters `pattern` gibt nur die Postfächer der obersten Ebene zurück. '`~/mail/%`' unter `UW_IMAPD` gibt alle Postfächer des Verzeichnisses ~/mail zurück, aber keine aus dessen Unterverzeichnissen.

### Rückgabewerte

Gibt ein Array zurück, das Objekte mit Postfachbeschreibungen enthält. Jedes Objekt verfügt über die Attribute `name` für den Namen des Postfachs, `delimiter` für das gültige Hierachietrennzeichen innerhalb des Hierachieabschnitts, in dem sich das Postfach befindet, und Eigenschaften des Postfachs in `attribute`. Die Eigenschaften setzen sich als Bitmaske aus folgenden möglichen Werten zusammen:

- `LATT_NOINFERIORS` - Dieses Postfach enthält keine Unterpostfächer.
- `LATT_NOSELECT` - Dieses Postfach enthält nur Unterpostfächer aber keine Nachrichten; es kann nicht geöffnet werden.
- `LATT_MARKED` - Dieses Postfach ist markiert. Wird nur von UW-IMAPD verwendet.
- `LATT_UNMARKED` - Dieses Postfach ist nicht markiert. Wird nur von UW-IMAPD verwendet.
- `LATT_REFERRAL` - Dieses Postfach bezieht sich auf eine Remote-Mailbox.
- `LATT_HASCHILDREN` - Dieses Postfach enthält auswählbare Unterpostfächer.
- `LATT_HASNOCHILDREN` - Dieses Postfach enthält keine auswählbaren Unterpostfächer.

Diese Funktion gibt bei einem Fehler `false` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

# imap_header

(PHP 4, PHP 5, PHP 7)

imap_header — Alias von imap_headerinfo()

Warnung

Dieser Alias wurde in PHP 8.0.0 ENTFERNT.

### Beschreibung

Diese Funktion ist ein Alias für: imap_headerinfo().

# imap_headerinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headerinfo — Liefert Informationen über die Kopfdaten einer Nachricht

### Beschreibung

function imap_headerinfo(
IMAP\Connection `$imap`,
int `$message_num`,
int `$from_length` = 0,
int `$subject_length` = 0
): stdClass|false

Liest die Kopfdaten der Nachricht mit der Nummer `message_num` und gibt daraus gewonnene Informationen zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_num`

  Die Nummer der Nachricht

`from_length`

  Die maximale Anzahl Zeichen für die Eigenschaft `fetchfrom` (muss größer oder gleich Null sein).

`subject_length`

  Die maximale Anzahl Zeichen für die Eigenschaft `fetchsubject` (muss größer oder gleich Null sein).

`defaulthost`

### Rückgabewerte

Gibt bei einem Fehler `false` zurück oder bei Erfolg die Informationen in einem Objekt mit folgenden Eigenschaften:

- toaddress - der Inhalt der "To:"-Zeile (max. 1024 Zeichen)
- to - ein Array von Objekten aus der "To:"-Zeile mit den folgenden Eigenschaften: `personal`, `adl`, `mailbox` und `host`
- fromaddress - der Inhalt der "From:"-Zeile (max. 1024 Zeichen)
- from - ein Array von Objekten aus der "From:"-Zeile mit den folgenden Eigenschaften: `personal`, `adl`, `mailbox` und `host`
- ccaddress - der Inhalt der "Cc:"-Zeile (max. 1024 Zeichen)
- cc - ein Array von Objekten aus der "Cc:"-Zeile mit den folgenden Eigenschaften: `personal`, `adl`, `mailbox` und `host`
- bccaddress - der Inhalt der "Bcc:"-Zeile (max. 1024 Zeichen)
- bcc - ein Array von Objekten aus der "Bcc:"-Zeile mit den folgenden Eigenschaften: `personal`, `adl`, `mailbox` und `host`
- reply_toaddress - der Inhalt der "Reply-To:"-Zeile (max. 1024 Zeichen)
- reply_to - ein Array von Objekten aus der "Reply-To:"-Zeile mit den folgenden Eigenschaften: `personal`, `adl`, `mailbox` und `host`
- senderaddress - der Inhalt der "Sender:"-Zeile (max. 1024 Zeichen)
- sender - ein Array von Objekten aus der "Sender:"-Zeile mit den folgenden Eigenschaften: `personal`, `adl`, `mailbox` und `host`
- return_pathaddress - der Inhalt der "Return-Path:"-Zeile (max. 1024 Zeichen)
- return_path - ein Array von Objekten aus der "Return-Path:"-Zeile mit den folgenden Eigenschaften: `personal`, `adl`, `mailbox` und `host`
- remail -
- date - das Sendedatum der Nachricht laut Kopfdaten
- Date - enthält die gleichen Daten wie 'date'
- subject - die Betreffzeile der Nachricht
- Subject - enthält die gleichen Daten wie 'subject'
- in_reply_to -
- message_id -
- newsgroups -
- followup_to -
- references -
- Recent - `R`, wenn kürzlich eingetroffen und gelesen, `N`, wenn kürzlich eingetroffen und ungelesen, ' ', wenn nicht kürzlich eingetroffen.
- Unseen - `U`, wenn nicht kürzlich eingetroffen UND ungelesen, ' ', wenn gelesen ODER ungelesen und kürzlich eingetroffen.
- Flagged - `F`, wenn als wichtig markiert, sonst ' '
- Answered - `A`, wenn beantwortet, sonst ' '
- Deleted - `D`, wenn zum Löschen vorgemerkt, sonst ' '
- Draft - `X`, wenn als Entwurf markiert, sonst ' '
- Msgno - die Nummer der Nachricht
- MailDate -
- Size - die Größe der Nachricht in Bytes
- udate - das Sendedatum als Unix-Timestamp
- fetchfrom - die "From:"-Zeile limitiert auf `from_length` Zeichen
- fetchsubject - die "Subject:"-Zeile, limitiert auf `subject_length` Zeichen

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.
8.0.0 | Der nicht verwendete Parameter `defaulthost` wurde entfernt.

### Siehe auch

- imap_fetch_overview() - Liefert eine Zusammenfassung der Kopfdaten von Nachrichten

# imap_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headers — Liefert die Kopfzeilen aller Nachrichten eines Postfachs

### Beschreibung

function imap_headers(IMAP\Connection `$imap`): array|false

Diese Funktion gibt die Kopfzeilen aller Nachrichten eines Postfachs zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

### Rückgabewerte

Gibt ein Array aus Strings mit formatierten Headerinformationen zurück. Das Array enthält ein Element für jede Nachricht im Postfach. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

# imap_is_open

(PHP 8 >= 8.2.1)

imap_is_open — Check if the IMAP stream is still valid

### Beschreibung

function imap_is_open(IMAP\Connection `$imap`): bool

Check if the IMAP stream is still valid.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

### Rückgabewerte

Returns `true` if the stream is still valid, `false` otherwise.

### Beispiele

Beispiel #1 imap_is_open() example

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
    imap_is_open($mbox);
    // ...
    ?>

# imap_last_error

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_last_error — Liefert den zuletzt aufgetretenen IMAP-Fehler

### Beschreibung

function imap_last_error(): string|false

Gibt den vollständigen Text der letzten IMAP-Fehlermeldung zurück, die für die aktuelle Seite erzeugt wurde. Der Fehlerstack bleibt erhalten, wiederholte imap_last_error()-Aufrufe liefern daher die gleiche Fehlermeldung, falls nicht inzwschen ein weiterer Fehler aufgetreten ist.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den vollständigen Text der letzten IMAP-Fehlermeldung zurück, die auf der aktuellen Seite aufgetreten ist, und `false`, wenn es keine gibt.

### Siehe auch

- imap_errors() - Liefert alle bisher aufgetretenen Fehlermeldungen

# imap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_list — Liefert die Liste der Postfächer

### Beschreibung

function imap_list(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Gibt die Liste aller Pöstfächer zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`reference`

  Die Angabe des Servers in der in imap_open() beschriebenen Form.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`pattern`

  Gibt an, wo in der Postfach-Hierarchie mit der Suche begonnen werden soll.

  Es gibt zwei Sonderzeichen, die man als Teil von `pattern` verwenden kann: '`*`' und '`%`'. '`*`' heißt, dass alle Postfächer zurückgegeben werden sollen. Wenn man `pattern` als '`*`' übergibt, so erhält man eine Liste der vollständigen Postfach-Hierarchie. '`%`' heißt, dass nur die aktuelle Stufe zurückgegeben wird. '`%`' als Wert des Parameters `pattern` gibt nur die Postfächer der obersten Ebene zurück. '`~/mail/%`' unter `UW_IMAPD` gibt alle Postfächer des Verzeichnisses ~/mail zurück, aber keine aus dessen Unterverzeichnissen.

### Rückgabewerte

Gibt ein Array mit den Namen der gefundenen Postfächer zurück oder `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_list()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org}", "username", "password", OP_HALFOPEN)
          or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $list = imap_list($mbox, "{imap.example.org}", "*");
    if (is_array($list)) {
        foreach ($list as $val) {
            echo imap_utf7_decode($val) . "\n";
        }
    } else {
        echo "imap_list schlug fehl: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

### Siehe auch

- imap_getmailboxes() - Liefert detaillierte Informationen zu allen Postfächern
- imap_lsub() - Liefert eine Liste aller abonnierten Postfächer

# imap_listmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listmailbox — Alias von imap_list()

### Beschreibung

Diese Funktion ist ein Alias für: imap_list().

# imap_listscan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listscan — Liefert eine Liste von Postfächern nach Suchkriterien

### Beschreibung

function imap_listscan(
IMAP\Connection `$imap`,
string `$reference`,
string `$pattern`,
string `$content`
): array|false

Gibt ein Array mit den Namen der Postfächer zurück, in deren Inhalt der Suchtext `content` vorkommt.

Diese Funktion verhält sich ähnlich wie imap_listmailbox(), sucht aber zusätzlich nach dem Suchtext `content` innerhalb der Daten des Postfachs.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`reference`

  Die Angabe des Servers in der in imap_open() beschriebenen Form.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`pattern`

  Gibt an, wo in der Postfach-Hierarchie mit der Suche begonnen werden soll.

  Es gibt zwei Sonderzeichen, die man als Teil von `pattern` verwenden kann: '`*`' und '`%`'. '`*`' heißt, dass alle Postfächer zurückgegeben werden sollen. Wenn man `pattern` als '`*`' übergibt, so erhält man eine Liste der vollständigen Postfach-Hierarchie. '`%`' heißt, dass nur die aktuelle Stufe zurückgegeben wird. '`%`' als Wert des Parameters `pattern` gibt nur die Postfächer der obersten Ebene zurück. '`~/mail/%`' unter `UW_IMAPD` gibt alle Postfächer des Verzeichnisses ~/mail zurück, aber keine aus dessen Unterverzeichnissen.

`content`

  Der zu suchende Text

### Rückgabewerte

Gibt ein Array mit den Namen der Postfächer zurück, in deren Inhalt der Suchtext `content` vorkommt. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_listmailbox() - Alias von imap_list
- imap_search() - Liefert ein Array von Nachrichten, die den gegebenen Suchkriterien entsprechen

# imap_listsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listsubscribed — Alias von imap_lsub()

### Beschreibung

Diese Funktion ist ein Alias für: imap_lsub().

# imap_lsub

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_lsub — Liefert eine Liste aller abonnierten Postfächer

### Beschreibung

function imap_lsub(IMAP\Connection `$imap`, string `$reference`, string `$pattern`): array|false

Gibt ein Array aller vom Benutzer abonnierten Postfächer zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`reference`

  Die Angabe des Servers in der in imap_open() beschriebenen Form.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`pattern`

  Gibt an, wo in der Postfach-Hierarchie mit der Suche begonnen werden soll.

  Es gibt zwei Sonderzeichen, die man als Teil von `pattern` verwenden kann: '`*`' und '`%`'. '`*`' heißt, dass alle Postfächer zurückgegeben werden sollen. Wenn man `pattern` als '`*`' übergibt, so erhält man eine Liste der vollständigen Postfach-Hierarchie. '`%`' heißt, dass nur die aktuelle Stufe zurückgegeben wird. '`%`' als Wert des Parameters `pattern` gibt nur die Postfächer der obersten Ebene zurück. '`~/mail/%`' unter `UW_IMAPD` gibt alle Postfächer des Verzeichnisses ~/mail zurück, aber keine aus dessen Unterverzeichnissen.

### Rückgabewerte

Gibt ein Array mit allen abonnierten Postfächern zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_list() - Liefert die Liste der Postfächer
- imap_getmailboxes() - Liefert detaillierte Informationen zu allen Postfächern

# imap_mail

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail — Sendet eine E-Mail-Nachricht

### Beschreibung

function imap_mail(
string `$to`,
string `$subject`,
string `$message`,
?string `$additional_headers` = `null`,
?string `$cc` = `null`,
?string `$bcc` = `null`,
?string `$return_path` = `null`
): bool

Diese Funktion ermöglicht das Senden einer E-Mail mit korrekter Behandlung von Cc- und Bcc-Kopffeldern.

Die Parameter `to`, `cc` und `bcc` sind Strings, die als Adresslisten gemäß » RFC822 interpretiert werden.

### Parameter-Liste

`to`

  Der Empfänger der Nachricht

`subject`

  Die Betreffzeile der Nachricht

`message`

  Der Inhalt der Nachricht, siehe imap_mail_compose()

`additional_headers`

  Ein String mit zusätzlichen Kopfzeilen

`cc`

`bcc`

  Die in `bcc` angegebenen weiteren Empfänger erhalten die Nachricht, werden aber nicht im Nachrichtenkopf aufgeführt.

`return_path`

  Die Rückgabeadresse für den Fall, dass die Zustellung der Nachricht fehlschlägt. Diese ist nützlich, wenn PHP als Mail-Client für mehrere Benutzer verwendet wird.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `additional_headers`, `cc`, `bcc` und `return_path` sind nun Nullable-Typen.

### Siehe auch

- mail() - Sendet eine E-Mail
- imap_mail_compose() - Erzeugt eine MIME-Nachricht aus Kopf- und Nachrichtenelementen

# imap_mail_compose

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_compose — Erzeugt eine MIME-Nachricht aus Kopf- und Nachrichtenelementen

### Beschreibung

function imap_mail_compose(array `$envelope`, array `$bodies`): string|false

Erzeugt eine MIME-konforme Nachricht aus den in `envelope` gegebenen Kopfelementen und den Nachrichtenteilen aus `bodies`.

### Parameter-Liste

`envelope`

  Ein assoziatives Array von Kopfzeilenfeldern. Gültige Schlüssel sind: `"remail"`, `"return_path"`, `"date"`, `"from"`, `"reply_to"`, `"in_reply_to"`, `"subject"`, `"to"`, `"cc"`, `"bcc"` und `"message_id"`, die die jeweiligen Kopfzeilen zum angegebenen String definieren. Um zusätzliche Kopfzeilen zu definieren, kann der Schlüssel `"custom_headers"` verwendet werden, der ein Array von anderen Kopfzeilen erwartet, z. B. `["User-Agent: Mein Mail-Client"]`).

`bodies`

  Ein Array mit dem Textkörper. Das erste Element des Arrays ist der zentrale Teil der Nachricht. Nur wenn er vom Typ `TYPEMULTIPART` ist, werden die weiteren Elemente verarbeitet. Die verarbeiteten Elemente bilden die Teile des Körpers.

  Der Aufbau des Körper-Arrays
  Schlüssel | Typ | Beschreibung
  --- | --- | ---
  `type` | int | Der MIME-Typ. Entweder `TYPETEXT` (Standard), `TYPEMULTIPART`, `TYPEMESSAGE`, `TYPEAPPLICATION`, `TYPEAUDIO`, `TYPEIMAGE`, `TYPEMODEL` oder `TYPEOTHER`.
  `encoding` | int | Das `Content-Transfer-Encoding`. Entweder `ENC7BIT` (Standard), `ENC8BIT`, `ENCBINARY`, `ENCBASE64`, `ENCQUOTEDPRINTABLE` oder `ENCOTHER`.
  `charset` | string | Der Zeichensatz-Parameter des MIME-Typs.
  `type.parameters` | array | Ein assoziatives Array von `Content-Type`-Parameternamen und deren Werten.
  `subtype` | string | Der MIME-Subtyp, z. B. `'jpeg'` für `TYPEIMAGE`.
  `id` | string | Die `Content-ID`.
  `description` | string | Die `Content-Description`.
  `disposition.type` | string | Die `Content-Disposition`, z. B. `'attachment'`.
  `disposition` | array | Ein assoziatives Array von `Content-Disposition`-Parameternamen und deren Werten.
  `contents.data` | string | Der Inhalt.
  `lines` | int | Die Größe des Inhalts in Zeilen.
  `bytes` | int | Die Größe des Inhalts in Bytes.
  `md5` | string | Die MD5-Prüfsumme des Inhalts.

### Rückgabewerte

Gibt eine MIME-konforme Nachricht als String zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 imap_mail_compose()-Beispiel

    <?php

    $envelope["from"]= "joe@example.com";
    $envelope["to"]  = "foo@example.com";
    $envelope["cc"]  = "bar@example.com";

    $part1["type"] = TYPEMULTIPART;
    $part1["subtype"] = "mixed";

    $filename = "/tmp/imap.c.gz";
    $fp = fopen($filename, "r");
    $contents = fread($fp, filesize($filename));
    fclose($fp);

    $part2["type"] = TYPEAPPLICATION;
    $part2["encoding"] = ENCBINARY;
    $part2["subtype"] = "octet-stream";
    $part2["description"] = basename($filename);
    $part2["contents.data"] = $contents;

    $part3["type"] = TYPETEXT;
    $part3["subtype"] = "plain";
    $part3["description"] = "description3";
    $part3["contents.data"] = "contents.data3\n\n\n\t";

    $body[1] = $part1;
    $body[2] = $part2;
    $body[3] = $part3;

    echo nl2br(imap_mail_compose($envelope, $body));

    ?>

# imap_mail_copy

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_copy — Kopiert Nachrichten in ein Postfach

### Beschreibung

function imap_mail_copy(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

imap_mail_copy() kopiert die mit `message_nums` angegebenen Nachrichten in das Postfach `mailbox`.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_nums`

  `message_nums` ist keine Liste von Nachrichtennummern, sondern ein Nachrichtenbereich (wie in » RFC2060 beschrieben).

`mailbox`

  Das Zielpostfach, für weitere Informationen siehe imap_open()

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`flags`

  `flags` ist eine Bitmaske, die sich aus einem oder mehreren der folgenden Flags zusammensetzt:

  - `CP_UID` - die Nummern der Nachrichten sind UIDs
  - `CP_MOVE` - Nachrichten nach dem Kopieren aus dem aktuellen Postfach entfernen. Wenn dieses Flag gesetzt ist, verhält sich die Funktion genauso wie imap_mail_move().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_mail_move() - Verschiebt Nachrichten in ein anderes Postfach

# imap_mail_move

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_move — Verschiebt Nachrichten in ein anderes Postfach

### Beschreibung

function imap_mail_move(
IMAP\Connection `$imap`,
string `$message_nums`,
string `$mailbox`,
int `$flags` = 0
): bool

imap_mail_move() verschiebt die mit `message_nums` angegebenen Nachrichten in das Postfach `mailbox`. Es ist zu beachten, dass die Nachrichten in Wirklichkeit in das Postfach `mailbox` kopiert werden und die ursprünglichen Nachrichten zum Löschen markiert werden. Das bedeutet, dass die Nachrichten in `mailbox` neue UIDs zugewiesen bekommen.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_nums`

  `message_nums` ist keine Liste von Nachrichtennummern, sondern ein Nachrichtenbereich (wie in » RFC2060 beschrieben).

`mailbox`

  Das Zielpostfach, für weitere Informationen siehe imap_open()

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`flags`

  `flags` ist eine Bitmaske und kann zur Zeit nur eine Option enthalten:

  - `CP_UID` - die Nummern der Nachrichten sind UIDs

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Anmerkungen

> Hinweis:

> imap_mail_move() setzt für die Original-Nachricht ein Lösch-Flag. Um sie erfolgreich zu löschen, muss die Funktion imap_expunge() aufgerufen werden.

### Siehe auch

- imap_mail_copy() - Kopiert Nachrichten in ein Postfach

# imap_mailboxmsginfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mailboxmsginfo — Liefert Informationen zum aktuellen Postfach

### Beschreibung

function imap_mailboxmsginfo(IMAP\Connection `$imap`): stdClass

Prüft den aktuelle Status des Postfachs auf dem Server. Die Funktion ist vergleichbar mit imap_status(), gibt aber zusätzlich auch die Gesamtgröße aller Nachrichten in Bytes zurück. Das Aufsummieren der einzelnen Nachrichtengrößen benötigt dabei zusätzliche Zeit zur Ausführung.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

### Rückgabewerte

Die Ergebnisse werden in einem Objekt mit folgenden Eigenschaften zurückgegeben:

Postfach-Eigenschaften
Date | Zeitpunkt der letzten Änderung (aktuelle Zeit)
Driver | Treiber
Mailbox | Name des Postfachs
Nmsgs | Anzahl der Nachrichten
Recent | Anzahl der kürzlich eingetroffenen Nachrichten
Unread | Anzal der ungelesenen Nachrichten
Deleted | Anzahl der gelöschten Nachrichten
Size | Gesamtgröße des Postfachs in Bytes

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_mailboxmsginfo()-Beispiel

    <?php

    $mbox = imap_open("{imap.example.org}INBOX", "username", "password")
          or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $check = imap_mailboxmsginfo($mbox);

    if ($check) {
        echo "Datum: "       . $check->Date    . "<br />\n" ;
        echo "Treiber: "     . $check->Driver  . "<br />\n" ;
        echo "Postfach: "    . $check->Mailbox . "<br />\n" ;
        echo "Nachrichten: " . $check->Nmsgs   . "<br />\n" ;
        echo "Neueste: "     . $check->Recent  . "<br />\n" ;
        echo "Ungelesen: "   . $check->Unread  . "<br />\n" ;
        echo "Gelöscht: "    . $check->Deleted . "<br />\n" ;
        echo "Größe: "       . $check->Size    . "<br />\n" ;
    } else {
        echo "imap_mailboxmsginfo() schlug fehl: " . imap_last_error() . "<br />\n";
    }

    imap_close($mbox);

    ?>

# imap_mime_header_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mime_header_decode — Dekodiert MIME-kodierte Kopfzeilen

### Beschreibung

function imap_mime_header_decode(string `$string`): array|false

Dekodiert MIME-kodierte Kopfzeilen, die nicht-ASCII-Zeichen enthalten (siehe » RFC2047).

### Parameter-Liste

`string`

  Der MIME-kodierte Text

### Rückgabewerte

Die dekodierten Textteile werden als ein Array von Objekten zurückgegeben, die jeweils eine `charset`- und eine `text`-Eigenschaft enthalten.

Für nicht kodierte ASCII-Teile wird die `charset`-Eigenschaft auf den Wert `default` gesetzt.

Die Funktion gibt bei einem Fehler `false` zurück.

### Beispiele

Beispiel #1 imap_mime_header_decode()-Beispiel

    <?php
    $text = "=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@example.com>";

    $elements = imap_mime_header_decode($text);
    for ($i=0; $i<count($elements); $i++) {
        echo "Zeichensatz: {$elements[$i]->charset}\n";
        echo "Text: {$elements[$i]->text}\n\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Zeichensatz: ISO-8859-1
    Text: Keld Jørn Simonsen

    Zeichensatz: default
    Text:  <keld@example.com>

In diesem Beispiel erhalten wir zwei Textteile zurück, den ersten kodiert im westeuropäischen ISO-8859-1-Zeichensatz und den zweiten als einfachen ASCII-String.

### Siehe auch

- imap_utf8() - Konvertiert Text nach UTF-8

# imap_msgno

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_msgno — Liefert die Nummer einer Nachricht für eine gegebene UID

### Beschreibung

function imap_msgno(IMAP\Connection `$imap`, int `$message_uid`): int

Gibt die Nummer der Nachricht für `message_uid` zurück.

Diese Funktion ist das Gegenstück zu imap_uid().

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_uid`

  Die UID der Nachricht

### Rückgabewerte

Gibt die Nummer der Nachricht mit der gegebenen `message_uid` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_uid() - Liefert die UID für die gegebene Nachrichtennummer

# imap_mutf7_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_mutf7_to_utf8 — Decode a modified UTF-7 string to UTF-8

### Beschreibung

function imap_mutf7_to_utf8(string `$string`): string|false

Decode a modified UTF-7 (as specified in RFC 2060, section 5.1.3) string to UTF-8.

> Hinweis:

> This function is only available, if libcclient exports utf8_to_mutf7().

### Parameter-Liste

`string`

  A string encoded in modified UTF-7.

### Rückgabewerte

Returns `string` converted to UTF-8, Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- imap_utf8_to_mutf7() - Encode a UTF-8 string to modified UTF-7

# imap_num_msg

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_msg — Liefert die Anzahl der Nachrichten im aktuellen Postfach

### Beschreibung

function imap_num_msg(IMAP\Connection `$imap`): int|false

Gibt die Anzahl der Nachrichten im aktuellen Postfach zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

### Rückgabewerte

Gibt die Anzahl der Nachrichten im aktuellen Postfach als Integer zurück oder `false` im Fehlerfall.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_num_recent() - Liefert die Anzahl der kürzlich eingetroffenen Nachrichten
- imap_status() - Liefert Statusinformationen zum angegebenen Postfach

# imap_num_recent

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_recent — Liefert die Anzahl der kürzlich eingetroffenen Nachrichten

### Beschreibung

function imap_num_recent(IMAP\Connection `$imap`): int

Gibt die Anzahl der kürzlich im aktuellen Postfach eingetroffenen Nachrichten zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

### Rückgabewerte

Gibt die Anzahl der kürzlich im aktuellen Postfach eingetroffenen Nachrichten als Integer zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_num_msg() - Liefert die Anzahl der Nachrichten im aktuellen Postfach
- imap_status() - Liefert Statusinformationen zum angegebenen Postfach

# imap_open

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_open — Öffnet einen IMAP-Stream zu einem Postfach

### Beschreibung

function imap_open(
string `$mailbox`,
string `$user`,
string `$password`,
int `$flags` = 0,
int `$retries` = 0,
array `$options` = []
): IMAP\Connection|false

Öffnet einen IMAP-Stream zum Postfach `mailbox`.

Diese Funktion kann auch verwendet werden, um Streams zu POP3- und NNTP-Servern zu öffnen, einige Funktionen und Eigenschaften sind aber nur bei IMAP-Verbindungen verfügbar.

### Parameter-Liste

`mailbox`

  Ein Postfachname besteht aus einer Serveradresse und dem Pfad zum Postfach auf diesem Server. Der reservierte Name `INBOX` steht für das persönliche Postfach des aktuellen Benutzers. Enthält der Name des Postfachs internationale Zeichen außerhalb des druckbaren ASCII-Bereichs, so müssen diese mit imap_utf7_encode() kodiert werden.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

  Der Serverteil wird in '{' und '}' eingebettet und besteht aus der Domain oder der IP-Adresse des Servers, einer optionalen Portnummer (eingeleitet mit ':') und einer optionalen Protokollangabe (eingeleitet mit '/').

  Die Angabe des Serverteils ist immer zwingend bei allen Postfach-Parametern.

  Alle Namen, die mit `{` beginnen, bezeichnen Serverdienste und werden in der Form `"{" remote_system_name [":" port] [flags] "}"[mailbox_name]` angegeben:

  - `remote_system_name` - der Internet-Domain-Name oder die in Klammern gesetzte IP-Adresse des Servers
  - `port` - die optionale Portnummer, Standard ist der jeweilige Standardport des gewählten Protokolls
  - `flags` - optionale Flags, siehe folgende Tabelle
  - `mailbox_name` - der Name des gewünschten Serverpostfachs, Standard ist "INBOX"

  Optionale Flags
  Flag | Beschreibung
  --- | ---
  `/service=`service | Postfach-Zugriffsprotokoll, Standard ist "imap"
  `/user=`user | Benutzername für die Anmeldung am Mailserver
  `/authuser=`user | Benutzername für die Remote-Authentifizierung; falls angegeben, ist dies der Benutzername dessen Passwort verwendet wird (z. B. administrator)
  `/anonymous` | Zugriff als anonymer Benutzer
  `/debug` | Protokollausgaben im Debug-Log der Anwendung aufzeichnen
  `/secure` | Übertragung von Klartext-Passwörtern wird verhindert
  `/imap`, `/imap2`, `/imap2bis`, `/imap4`, `/imap4rev1` | Kurzform für `/service=imap`
  `/pop3` | Kurzform für `/service=pop3`
  `/nntp` | Kurzform für `/service=nntp`
  `/norsh` | Für eine vorauthentifizierte IMAP-Verbindung soll weder RSH noch SSH verwendet werden
  `/ssl` | `Secure Socket Layer` (SSL) zur Verschlüsselung der Verbindung verwenden
  `/validate-cert` | TLS/SSL-Zertifikate verifizieren (Standardverhalten)
  `/novalidate-cert` | TLS/SSL-Zertifikate nicht verifizieren; wird für selbstsignierte Zertifikate benötigt
  `/tls` | `start-TLS`-Verschlüsselung erzwingen und Verbindungen zu Servern, die dies nicht unterstützen, ablehnen
  `/notls` | `start-TLS` nicht zum Verschlüsseln der Verbindung verwenden, auch wenn es der Server unterstützt
  `/readonly` | Öffnen des Postfachs im Nur-Lese-Modus anfordern (nur für IMAP, NNTP ignoriert dies, POP3 und SMTP verweigern readonly-Verbindungen)

`user`

  Der Benutzername

`password`

  Das Passwort von `user`

`flags`

  Der Parameter `flags` kann sich als Bitmaske aus folgenden Werten zusammensetzen:

  - `OP_READONLY` - nur lesende Zugriffe
  - `OP_ANONYMOUS` - ein existierendes .newsrc weder lesen noch aktualisieren (nur NNTP)
  - `OP_HALFOPEN` - Verbindung zum Server öffnen, aber noch kein Postfach auswählen (nur IMAP und NNTP)
  - `CL_EXPUNGE` - zum Löschen markierte Nachrichten beim Schließen des Postfachs automatisch entfernen (siehe auch imap_delete() und imap_expunge())
  - `OP_DEBUG` - Protokollverhandlungen debuggen
  - `OP_SHORTCACHE` - kurzes Caching (nur `elt`)
  - `OP_SILENT` - Ereignisse nicht weitergeben (interne Einstellung)
  - `OP_PROTOTYPE` - Treiber-Prototyp zurückgeben
  - `OP_SECURE` - keine unsichere Verbindung zum Server öffnen
`retries`

  Maximale Anzahl der Verbindungsversuche

`options`

  Verbindungsparameter; die folgenden (String-)Schlüssel können verwendet werden, um einen oder mehrere Verbindungsparameter anzugeben:

  - `DISABLE_AUTHENTICATOR` - Deaktiviere Authentifizierungs-Eigenschaften

### Rückgabewerte

Gibt bei Erfolg eine IMAP\Connection-Instanz zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Gibt jetzt eine IMAP\Connection-Instanz zurück; vorher wurde eine Ressource zurückgegeben.

### Beispiele

Beispiel #1 Verschiedene imap_open()-Aufrufe

    <?php
    // Verbindung zu einem IMAP-Server auf Port 143 des lokalen Rechners
    $mbox = imap_open("{localhost:143}INBOX", "user_id", "password");

    // Verbindung zu einem POP3-Server auf Port 110 des lokalen Rechners
    $mbox = imap_open ("{localhost:110/pop3}INBOX", "user_id", "password");

    // Für SSL-verschlüsselte Verbindungen zu einem IMAP- oder POP3-Server wird
    // /ssl an die Protokollspezifikation angefügt
    $mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password");

    // Zur SSL-Verbindung mit IMAP- oder POP3-Servern mit selbstsignierten
    // Zertifikaten muss zusätzlich /novalidate-cert angefügt werden
    $mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password");

    // Verbindung zu einem NNTP-Server auf Port 119 des lokalen Rechners
    $nntp = imap_open ("{localhost:119/nntp}comp.test", "", "");
    // Für Verbindungen zu anderen Servern wird "localhost" mit dem Namen
    // oder der IP-Adresse des Servers ersetzt
    ?>

Beispiel #2 imap_open()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password");

    echo "<h1>Postfächer</h1>\n";
    $folders = imap_listmailbox($mbox, "{imap.example.org:143}", "*");

    if ($folders == false) {
        echo "Abruf fehlgeschlagen<br />\n";
    } else {
        foreach ($folders as $val) {
            echo $val . "<br />\n";
        }
    }

    echo "<h1>Nachrichten in INBOX</h1>\n";
    $headers = imap_headers($mbox);

    if ($headers == false) {
        echo "Abruf fehlgeschlagen<br />\n";
    } else {
        foreach ($headers as $val) {
            echo $val . "<br />\n";
        }
    }

    imap_close($mbox);
    ?>

### Siehe auch

- imap_close() - Schließt einen IMAP-Stream

# imap_ping

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_ping — Prüft einen IMAP-Stream auf Funktionalität

### Beschreibung

function imap_ping(IMAP\Connection `$imap`): bool

imap_ping() 'pingt' einen IMAP-Stream an, um zu sehen, ob dieser noch aktiv ist. Diese Funktion kann auch neu eingetroffene Nachrichten erkennen. Daher ist dies die bevorzugte Methode zur regelmäßigen Überprüfung auf neue Nachrichten und um die Verbindung bei Servern offen zu halten, die sie sonst nach einer gewissen Zeit der Inaktivität beenden.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

### Rückgabewerte

Gibt `true` zurück, wenn der Stream noch funktioniert, sonst `false`.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_ping()-Beispiel

    <?php

    $imap = imap_open("{imap.example.org}", "mailadmin", "password");

    // nach einer gewissen Zeit
    if (!imap_ping($imap)) {
        // Verbindung wieder aufbauen
    }

    ?>

# imap_qprint

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_qprint — Konvertiert einen quoted-printable-kodierten String in einen 8-Bit-String

### Beschreibung

function imap_qprint(string `$string`): string|false

Konvertiert einen quoted-printable String in einen 8-Bit-String gemäß » RFC2045, Abschnitt 6.7.

### Parameter-Liste

`string`

  Ein quoted-printable-kodierter String

### Rückgabewerte

Gibt einen 8-Bit-String zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- imap_8bit() - Konvertiert einen 8bit-String in einen quoted-printable String

# imap_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rename — Alias von imap_renamemailbox()

### Beschreibung

Diese Funktion ist ein Alias für: imap_renamemailbox().

# imap_renamemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_renamemailbox — Ändert den Namen eines Postfachs

### Beschreibung

function imap_renamemailbox(IMAP\Connection `$imap`, string `$from`, string `$to`): bool

Diese Funktion ändert den Namen des Postfachs von `from` in `to` (siehe imap_open() für das Format von `mbox`-Namen).

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`from`

  Der bisherige Name des Postfachs, siehe imap_open() für weitere Informationen.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`to`

  Der neue Name des Postfachs, siehe imap_open() für weitere Informationen.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_createmailbox() - Legt ein neues Postfach an
- imap_deletemailbox() - Löscht ein Postfach

# imap_reopen

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_reopen — Öffnet einen IMAP-Stream für ein anderes Postfach neu

### Beschreibung

function imap_reopen(
IMAP\Connection `$imap`,
string `$mailbox`,
int `$flags` = 0,
int `$retries` = 0
): bool

imap_reopen() öffnet die angegebene Verbindung zu einem IMAP- oder NNTP-Server erneut für ein anderes Postfach.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`mailbox`

  Der Name des Postfachs, siehe imap_open() für weitere Informationen.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`flags`

  Der Parameter `flags` kann als Bitmaske einen oder mehrere der folgenden Werte enthalten:

  - `OP_READONLY` - öffnet das Postfach nur für Lesezugriffe
  - `OP_ANONYMOUS` - die .newsrc-Datei weder lesen noch aktualisieren (nur NNTP)
  - `OP_HALFOPEN` - die Verbindung aufbauen, ohne ein Postfach zu öffnen (nur IMAP und NNTP)
  - `OP_EXPUNGE` - zum Löschen vorgemerkte Nachrichten stillschweigend sofort löschen
  - `CL_EXPUNGE` - zum Löschen vorgemerkte Nachrichten werden beim Schließen der Verbindung automatisch gelöscht (siehe auch imap_delete() und imap_expunge())
`retries`

  Die maximale Anzahl von Verbindungsversuchen

### Rückgabewerte

Gibt `true` zurück, wenn der Stream wieder geöffnet wird, ansonsten `false`.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_reopen()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org:143}INBOX", "username", "password") or die(implode(", ", imap_errors()));
    // ...
    imap_reopen($mbox, "{imap.example.org:143}INBOX.Sent") or die(implode(", ", imap_errors()));
    // ..
    ?>

# imap_rfc822_parse_adrlist

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_adrlist — Zerlegt einen String mit Mailadressen

### Beschreibung

function imap_rfc822_parse_adrlist(string `$string`, string `$default_hostname`): array

Zerlegt den übergebenen String mit Mailadressen in einzelne Mailadressen gemäß » RFC2822.

### Parameter-Liste

`string`

  Ein String aus Mailadressen

`default_hostname`

  Der Standard-Hostname

### Rückgabewerte

Gibt ein Array aus Objekten mit folgenden Eigenschaften zurück:

- mailbox - der Name des Postfachs bzw. der Benutzername
- host - der Hostname
- personal - der tatsächliche Name des Benutzers
- adl - "at-domain-list"; wird nicht mehr verwendet

### Beispiele

Beispiel #1 imap_rfc822_parse_adrlist()-Beispiel

    <?php

    $address_string = "Joe Doe <doe@example.com>, postmaster@example.com, root";
    $address_array  = imap_rfc822_parse_adrlist($address_string, "example.com");
    if (!is_array($address_array) || count($address_array) < 1) {
        die("something is wrong\n");
    }

    foreach ($address_array as $id => $val) {
        echo "# $id\n";
        echo "  mailbox : " . $val->mailbox . "\n";
        echo "  host    : " . $val->host . "\n";
        echo "  personal: " . $val->personal . "\n";
        echo "  adl     : " . $val->adl . "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    # 0
      mailbox : doe
      host    : example.com
      personal: Joe Doe
      adl     :
    # 1
      mailbox : postmaster
      host    : example.com
      personal:
      adl     :
    # 2
      mailbox : root
      host    : example.com
      personal:
      adl     :

### Siehe auch

- imap_rfc822_parse_headers() - Liest E-Mail-Kopfzeilen aus einem String aus

# imap_rfc822_parse_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_headers — Liest E-Mail-Kopfzeilen aus einem String aus

### Beschreibung

function imap_rfc822_parse_headers(string `$headers`, string `$default_hostname` = "UNKNOWN"): stdClass

Gibt ein Objekt mit diversen Kopfelementen zurück, ähnlich imap_header().

### Parameter-Liste

`headers`

  Die auszulesenden Kopfdaten

`default_hostname`

  Der Standard-Hostname

### Rückgabewerte

Gibt ein ähnliches Objekt zurück wie imap_header(), mit Ausnahme der Flags und anderen vom IMAP-Server zurückgegebenen Daten.

### Siehe auch

- imap_rfc822_parse_adrlist() - Zerlegt einen String mit Mailadressen

# imap_rfc822_write_address

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_write_address — Liefert eine korrekt formatierte E-Mail-Adresse aus übergebenen Informationen

### Beschreibung

function imap_rfc822_write_address(string `$mailbox`, string `$hostname`, string `$personal`): string|false

imap_rfc822_write_address() bildet eine gemäß » RFC2822 formatierte E-Mail-Adresse aus den übergebenen Informationen.

### Parameter-Liste

`mailbox`

  Der Name des Postfachs, siehe imap_open() für weitere Informationen.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`hostname`

  Der Domain-Teil der Mailadresse

`personal`

  Der tatsächliche Name des Besitzers des Postfachs

### Rückgabewerte

Gibt eine gemäß » RFC2822 formatierte Mailadresse als String zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 imap_rfc822_write_address()-Beispiel

    <?php
    echo imap_rfc822_write_address("hartmut", "example.com", "Hartmut Holzgraefe");
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Hartmut Holzgraefe <hartmut@example.com>

# imap_savebody

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

imap_savebody — Speichert einen Teil des Nachrichtentextes in einer Datei

### Beschreibung

function imap_savebody(
IMAP\Connection `$imap`,
resource|string|int `$file`,
int `$message_num`,
string `$section` = "",
int `$flags` = 0
): bool

Speichert einen Teil des Nachrichtenkörpers oder den gesamten Textkörper der angegebenen Nachricht.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`file`

  Der Name der Zieldatei oder ein gültiger von fopen() zurückgegebener Dateideskriptor.

`message_num`

  Die Nummer der Nachricht

`section`

  Die Nummer des Nachrichtenabschnitts. Ein String aus ganzen Zahlen, getrennt durch Punkte, der einen Teil des Nachrichtentextes gemäß der IMAP4-Spezifikation definiert.

`flags`

  Eine Bitmaske aus einem oder mehrereren der folgenden Werte:

  - `FT_UID` - `message_num` ist eine UID
  - `FT_PEEK` - Das \Seen-Flag nicht setzen, falls es nicht bereits gesetzt ist
  - `FT_INTERNAL` - Rückgabe im internen Format ohne Umwandlung der Zeilenenden in CRLF.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_fetchbody() - Liefert einen bestimmten Abschnitt aus dem Textkörper einer Nachricht

# imap_scan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scan — Alias von imap_listscan()

### Beschreibung

Diese Funktion ist ein Alias für: imap_listscan().

# imap_scanmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scanmailbox — Alias von imap_listscan()

### Beschreibung

Diese Funktion ist ein Alias für: imap_listscan().

# imap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_search — Liefert ein Array von Nachrichten, die den gegebenen Suchkriterien entsprechen

### Beschreibung

function imap_search(
IMAP\Connection `$imap`,
string `$criteria`,
int `$flags` = `SE_FREE`,
string `$charset` = ""
): array|false

Diese Funktion durchsucht die Nachrichten des aktuellen Postfachs auf dem angegebenen IMAP-Stream.

Der Suchstring, um z. B. nach allen unbeantworteten Nachrichten von Mutter zu suchen, wäre "UNANSWERED FROM Mutter". Die Suche unterscheidet nicht nach Groß- und Kleinschreibung. Die folgende Liste von Suchkriterien wurde aus dem Sourcecode des UW-c-client erstellt und ist daher nicht unbedingt vollständig oder in allen Einzelheiten korrekt (siehe auch » RFC1176, Abschnitt "tag SEARCH search_criteria").

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`criteria`

  Ein String, in dem die folgenden durch Leerzeichen getrennten Schlüsselwörter erlaubt sind. Argumente, die selbt Leerzeichen enthalten, müssen in doppelte Anführungszeichen gefasst werden (z. B. `FROM "Hans Müller"`). Die Ergebnisse müssen mit allen Einträgen in `criteria` übereinstimmen.

  - ALL - gebe alle Nachrichten zurück, die den übrigen Kriterien entsprechen
  - ANSWERED - sucht Nachrichten mit dem Flag \\ANSWERED
  - BCC "text" - sucht Nachrichten mit "text" im Bcc:-Feld
  - BEFORE "datum" - sucht Nachrichten, die vor "datum" gesendet wurden
  - BODY "text" - sucht Nachrichten mit "text" im Nachrichtenkörper
  - CC "text" - sucht Nachrichten mit "text" im Cc:-Feld
  - DELETED - sucht Nachrichten, die zur Löschung vorgemerkt sind
  - FLAGGED - sucht Nachrichten mit dem Flag \\FLAGGED (manchmal auch als wichtig oder dringend bezeichnet)
  - FROM "text" - sucht Nachrichten mit "text" im From:-Feld
  - KEYWORD "text" - sucht Nachrichten mit dem Schlüsselwort "text"
  - NEW - sucht neue Nachrichten
  - OLD - sucht alte Nachrichten
  - ON "datum" - sucht Nachrichten, die am angegebenen "datum" gesendet wurden
  - RECENT - sucht Nachrichten mit dem Flag \\RECENT
  - SEEN - sucht bereits gelesene Nachrichten (das Flag \\SEEN ist gesetzt)
  - SINCE "datum" - sucht nach "datum" gesendete Nachrichten
  - SUBJECT "text" - sucht Nachrichten mit "text" in der Betreffzeile
  - TEXT "text" - sucht Nachrichten, deren Text "text" enthält
  - TO "text" - sucht Nachrichten mit "text" im To:-Feld
  - UNANSWERED - sucht noch nicht beantwortete Nachrichten
  - UNDELETED - sucht Nachrichten, die nicht zum Löschen vorgemerkt sind
  - UNFLAGGED - sucht Nachrichten, die nicht als wichtig markiert sind
  - UNKEYWORD "text" - sucht Nachrichten, in deren Schlüsselwörtern "text" nicht enthalten ist
  - UNSEEN - sucht ungelesene Nachrichten
`flags`

  Der einzige gültige Werte für `flags` ist `SE_UID`, was bewirkt, dass das zurückgegebene Array UIDs anstelle von Nachrichtennummern enthält.

`charset`

  Der bei der Stringsuche zu verwendende MIME-Zeichensatz.

### Rückgabewerte

Gibt ein Array mit Nachrichtennummern oder UIDs zurück.

Wenn die Suchkriterien `criteria` nicht verstanden wurden oder keine Nachrichten gefunden wurden, wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_search()-Beispiel

    <?php
    $imap   = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'foo@example.com', 'pass123', OP_READONLY);

    $some   = imap_search($imap, 'SUBJECT "HOWTO be Awesome" SINCE "8 August 2008"', SE_UID);
    $msgnos = imap_search($imap, 'ALL');
    $uids   = imap_search($imap, 'ALL', SE_UID);

    print_r($some);
    print_r($msgnos);
    print_r($uids);
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Array
    (
        [0] => 4
        [1] => 6
        [2] => 11
    )
    Array
    (
        [0] => 1
        [1] => 2
        [2] => 3
        [3] => 4
        [4] => 5
        [5] => 6
    )
    Array
    (
        [0] => 1
        [1] => 4
        [2] => 6
        [3] => 8
        [4] => 11
        [5] => 12
    )

### Siehe auch

- imap_listscan() - Liefert eine Liste von Postfächern nach Suchkriterien

# imap_set_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_set_quota — Legt die Größenbeschränkung für ein Postfach fest

### Beschreibung

function imap_set_quota(IMAP\Connection `$imap`, string `$quota_root`, int `$mailbox_size`): bool

Legt die Größenbeschränkung für das angegebene Postfach fest.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`quota_root`

  Das Postfach, für das eine Größenbeschränkung festgelegt werden soll. Dieses sollte dem IMAP-Standard für Postfächer folgen: `user.name`.

`mailbox_size`

  Die maximale Größe des Postfachs `quota_root` in KB

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_set_quota()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org:143}", "mailadmin", "password");

    if (!imap_set_quota($mbox, "user.kalowsky", 3000)) {
        echo "Fehler beim Festlegen der Beschränkung\n";
        return;
    }

    imap_close($mbox);
    ?>

### Anmerkungen

Diese Funktion ist aktuell erst ab der Bibliotheksversion c-client2000 verfügbar.

Die Serververbindung `imap` muss von einem Benutzer mit Administratorrechten geöffnet worden sein, ansonsten schlägt die Funktion fehl.

### Siehe auch

- imap_open() - Öffnet einen IMAP-Stream zu einem Postfach
- imap_get_quota() - Liefert Quota-Einstellungen und Nutzungsstatistik der Postfächer

# imap_setacl

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_setacl — Legt die ACL (Zugriffsrechte) für ein Postfach fest

### Beschreibung

function imap_setacl(
IMAP\Connection `$imap`,
string `$mailbox`,
string `$user_id`,
string `$rights`
): bool

Legt die ACL (Zugriffsrechte) für das angegebene Postfach fest.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`mailbox`

  Der Name des Postfachs, siehe imap_open() für nähere Informationen.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`user_id`

  Der Benutzer, dessen Berechtigungen geändert werden sollen.

`rights`

  Die Berechtigungen, die dem Benutzer gewährt werden sollen. Durch die Übergabe eines leeren Strings wird die ACL entfernt, d. h. alle Berechtigungen werden entzogen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Anmerkungen

Diese Funktion ist derzeit nur ab der Bibliotheksversion c-client2000 verfügbar.

### Siehe auch

- imap_getacl() - Liefert die Liste der Zugriffsrechte (ACL) für ein Postfach

# imap_setflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_setflag_full — Setzt Nachrichtenflags

### Beschreibung

function imap_setflag_full(
IMAP\Connection `$imap`,
string `$sequence`,
string `$flag`,
int `$options` = 0
): true

Setzt die mit `flag` angegebenen Flags bei allen Nachrichten aus der Liste `sequence`.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`sequence`

  Eine Liste von Nachrichtennummern. Sie können die gewünschten Nachrichten mit Komma getrennt aufzählen (`X,Y`) oder alle Nachrichten in einem bestimmten Intervall mit `X:Y` auswählen.

`flag`

  Die möglichen Flags, die gesetzt werden können, sind `\Seen`, `\Answered`, `\Flagged`, `\Deleted` und `\Draft`, wie in » RFC2060 definiert.

`options`

  Eine Bitmaske mit Optionen, die zurzeit wird nur eine Option unterstützt:

  - `ST_UID` - Die Nachrichtenliste `sequence` enthält UIDs anstelle von Nachrichtennummern.

### Rückgabewerte

Gibt immer `true` zurück.

### Fehler/Exceptions

Wenn `options` ungültig ist, wird ein ValueError geworfen.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.
8.0.0 | Bei ungültigen Parameterwerten von `options` wird nun ein ValueError geworfen; zuvor wurde eine Warnung ausgegeben und die Funktion gab `false` zurück.

### Beispiele

Beispiel #1 imap_setflag_full()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.org:143}", "username", "password")
         or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $status = imap_setflag_full($mbox, "2,5", "\\Seen \\Flagged");

    echo gettype($status) . "\n";
    echo $status . "\n";

    imap_close($mbox);
    ?>

### Siehe auch

- imap_clearflag_full() - Löscht die Flags einer Nachricht

# imap_sort

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_sort — Liefert und sortiert Nachrichten eines Postfachs

### Beschreibung

function imap_sort(
IMAP\Connection `$imap`,
int `$criteria`,
bool `$reverse`,
int `$flags` = 0,
?string `$search_criteria` = `null`,
?string `$charset` = `null`
): array|false

Gibt eine gemäß den angegebenen Sortierkriterien sortierte Liste von Nachrichtennummern zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`criteria`

  Nur eines der folgenden Sortierkriterien:

  - `SORTDATE` - das Sendedatum
  - `SORTARRIVAL` - das Eingangsdatum
  - `SORTFROM` - die erste Absenderadresse
  - `SORTSUBJECT` - der Betreff
  - `SORTTO` - die erste Empfängeradresse
  - `SORTCC` - die erste CC-Empfängeradresse
  - `SORTSIZE` - die Größe der Nachricht in Bytes
`reverse`

  Sortierung in umgekehrter Reihenfolge, wenn `true`

`flags`

  Der Parameter `flags` enthält eine Bitmaske mit einem oder mehreren der folgenden Werte:

  - `SE_UID` - es werden UIDs anstelle von Nachrichtennummern zurückgegeben
  - `SE_NOPREFETCH` - Nachrichten werden nicht auf Vorrat abgerufen
`search_criteria`

  Ein String mit Suchkriterien im IMAP2-Format. Details können imap_search() entnommen werden.

`charset`

  Der zum Sortieren von Strings zu verwendende MIME-Zeichensatz.

### Rückgabewerte

Gibt ein Array mit Nachrichtennummern zurück, die nach den angegebenen Sortierkriterien sortiert sind. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.
8.0.0 | `reverse` ist nun vom Typ bool statt int.
8.0.0 | `search_criteria` und `charset` sind nun nullable (akzeptieren den (`null`-Wert).

# imap_status

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_status — Liefert Statusinformationen zum angegebenen Postfach

### Beschreibung

function imap_status(IMAP\Connection `$imap`, string `$mailbox`, int `$flags`): stdClass|false

Gibt Statusinformationen zum Postfach `mailbox` zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`mailbox`

  Der Name des Postfachs, siehe imap_open() für weitere Informationen.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

`flags`

  Eine Bitmaske mit folgenden möglichen Werten:

  - `SA_MESSAGES` - setzt $status->messages auf die Anzahl der Nachrichten im Postfach
  - `SA_RECENT` - setzt $status->recent auf die Anzahl kürzlich eingetroffener Nachrichten im Postfach
  - `SA_UNSEEN` - setzt $status->unseen auf die Anzahl ungelesener (neuer) Nachrichten im Postfach
  - `SA_UIDNEXT` - setzt $status->uidnext auf die nächste diesem Postfach zugeteilte UID
  - `SA_UIDVALIDITY` - setzt $status->uidvalidity auf eine Konstante, die sich ändert, falls die UIDs im Postfach ihre Gültigkeit verloren haben könnten
  - `SA_ALL` - setzt alle Flags

### Rückgabewerte

Diese Funktion gibt ein Objekt mit Statusinformationen zurück. Bei einem Fehler wird `false` zurückgegeben. Das Objekt hat die folgenden Eigenschaften: `messages`, `recent`, `unseen`, `uidnext` und `uidvalidity`.

`flags` wird ebenfalls gesetzt und enthält eine Bitmaske, mit der die tatsächlich zurückgegebenen Informationen mit Hilfe der oben beschriebenen Konstanten geprüft werden können.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_status()-Beispiel

    <?php
    $mbox = imap_open("{imap.example.com}", "username", "password", OP_HALFOPEN)
          or die("Kann keine Verbindung aufbauen: " . imap_last_error());

    $status = imap_status($mbox, "{imap.example.org}INBOX", SA_ALL);
    if ($status) {
      echo "Nachrichten:   " . $status->messages    . "<br />\n";
      echo "Neueste:     " . $status->recent      . "<br />\n";
      echo "Ungelesen:     " . $status->unseen      . "<br />\n";
      echo "UIDnext:    " . $status->uidnext     . "<br />\n";
      echo "UIDvalidity:" . $status->uidvalidity . "<br />\n";
    } else {
      echo "imap_status schlug fehl: " . imap_last_error() . "\n";
    }

    imap_close($mbox);
    ?>

# imap_subscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_subscribe — Abonniert ein Postfach

### Beschreibung

function imap_subscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Abonniert ein neues Postfach.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`mailbox`

  Der Name des Postfachs, siehe imap_open() für weitere Informationen.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_unsubscribe() - Beendet das Abonnement eines Postfachs

# imap_thread

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_thread — Liefert Nachrichten als Baum zusammenhängender Themenstränge

### Beschreibung

function imap_thread(IMAP\Connection `$imap`, int `$flags` = `SE_FREE`): array|false

Gibt Nachrichten als Baum zusammenhängender Themenstränge zurück.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`flags`

### Rückgabewerte

imap_thread() gibt ein assoziatives Array von Nachrichten zurück, die über `REFERENCES` verknüpft sind, oder `false` bei Fehlern.

Jede Nachricht im aktuellen Postfach wird im zurückgegebenen Array durch drei Einträge repräsentiert:

- $thread["XX.num"] - die Nummer der aktuellen Nachricht

- $thread["XX.next"]

- $thread["XX.branch"]

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Beispiele

Beispiel #1 imap_thread()-Beispiel

    <?php

    // Ausgabe der verschiedenen Themenstränge einer Newsgroup in HTML

    $nntp = imap_open('{news.example.com:119/nntp}some.newsgroup', '', '');
    $threads = imap_thread($nntp);

    foreach ($threads as $key => $val) {
      $tree = explode('.', $key);
      if ($tree[1] == 'num') {
        $header = imap_headerinfo($nntp, $val);
        echo "<ul>\n\t<li>" . $header->fromaddress . "\n";
      } elseif ($tree[1] == 'branch') {
        echo "\t</li>\n</ul>\n";
      }
    }

    imap_close($nntp);

    ?>

# imap_timeout

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

imap_timeout — Setzt oder liefert den Imap-Timeout

### Beschreibung

function imap_timeout(int `$timeout_type`, int `$timeout` = -1): int|bool

Setzt den Timeoutwert für das IMAP-Protokoll oder gibt ihn zurück.

### Parameter-Liste

`timeout_type`

  Eine der folgenden Konstanten: `IMAP_OPENTIMEOUT`, `IMAP_READTIMEOUT`, `IMAP_WRITETIMEOUT` oder `IMAP_CLOSETIMEOUT`.

`timeout`

  Der Timeout in Sekunden

### Rückgabewerte

Wenn der Parameter `timeout` gesetzt ist, gibt diese Funktion bei Erfolg `true` zurück, sonst `false`.

Wird kein `timeout` übergeben oder entspricht dessen Wert -1, so wird der aktuelle Timeoutwert für `timeout_type` als Integer zurückgegeben.

### Beispiele

Beispiel #1 imap_timeout()-Beispiel

    <?php

    echo "Der aktuelle Lese-Timeout ist " . imap_timeout(IMAP_READTIMEOUT) . "\n";

    ?>

# imap_uid

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_uid — Liefert die UID für die gegebene Nachrichtennummer

### Beschreibung

function imap_uid(IMAP\Connection `$imap`, int `$message_num`): int|false

Diese Funktion gibt die UID für die angegebene Nachrichtennummer zurück. Eine UID ist ein eindeutiger Bezeichner für eine Nachricht, der sich nicht mit der Zeit ändert, während eine Nachrichtennummer sich bei jeder Veränderung des Postfachinhalts ändern kann.

Diese Funktion ist das Gegenstück zu imap_msgno().

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_num`

  Die Nummer der Nachricht

### Rückgabewerte

Gibt die UID der gewünschten Nachricht zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Anmerkungen

> Hinweis:

> Diese Funktion wird von POP3-Postfächern nicht unterstützt.

### Siehe auch

- imap_msgno() - Liefert die Nummer einer Nachricht für eine gegebene UID

# imap_undelete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_undelete — Nimmt eine bereits gesetzte Löschmarkierung einer Nachricht zurück

### Beschreibung

function imap_undelete(IMAP\Connection `$imap`, string `$message_nums`, int `$flags` = 0): true

Entfernt das "gelöscht"-Flag der angegebenen Nachricht. Das Flag wird von den Funktionen imap_delete() oder imap_mail_move() gesetzt.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`message_nums`

  Ein String, der eine oder mehrere Nachrichten im IMAP4-üblichen Sequenzformat darstellt (`"n"`, `"n:m"` oder eine Kombination daraus, durch Kommas getrennt).

`flags`

### Rückgabewerte

Gibt immer `true` zurück.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_delete() - Markiert eine Nachricht im aktuellen Postfach zur Löschung
- imap_mail_move() - Verschiebt Nachrichten in ein anderes Postfach

# imap_unsubscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_unsubscribe — Beendet das Abonnement eines Postfachs

### Beschreibung

function imap_unsubscribe(IMAP\Connection `$imap`, string `$mailbox`): bool

Beendet das Abonnement des Postfachs `mailbox`.

### Parameter-Liste

`imap`

  Eine IMAP\Connection-Instanz.

`mailbox`

  Der Name des Postfachs, siehe imap_open() für weitere Informationen.

  Warnung

  Die Übergabe von nicht vertrauenswürdigen Daten an diesen Parameter ist unsicher,falls imap.enable_insecure_rsh nicht deaktiviert ist.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Der Parameter `imap` erwartet nun eine IMAP\Connection-Instanz; vorher wurde eine gültige `imap`-Ressource erwartet.

### Siehe auch

- imap_subscribe() - Abonniert ein Postfach

# imap_utf7_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_decode — Dekodiert einen String im modifizierten UTF-7-Format

### Beschreibung

function imap_utf7_decode(string `$string`): string|false

Dekodiert den String `string` aus dem modifizierten UTF-7-Format in ISO-8859-1-kodierten Text.

Diese Funktion wird benötigt, um Mailboxnamen zu dekodieren, die Zeichen außerhalb des druckbaren ASCII-Bereichs enthalten.

### Parameter-Liste

`string`

  Ein String im modifizerten UTF-7-Format gemäß » RFC 2060, Abschnitt 5.1.3..

### Rückgabewerte

Gibt einen ISO-8859-1-kodierten String zurück oder `false`, wenn `string` ungültige modifizierte UTF-7-Sequenzen enthält oder Zeichen, die nicht Teil des ISO-8859-1-Zeichensatzes sind.

### Siehe auch

- imap_utf7_encode() - Kodiert ISO-8859-1 Text im modifizieren UTF-7-Format

# imap_utf7_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_encode — Kodiert ISO-8859-1 Text im modifizieren UTF-7-Format

### Beschreibung

function imap_utf7_encode(string `$string`): string

Konvertiert den in `string` übergebenen Text in das modifizierte UTF-7-Format.

Diese Funktion wird benötigt, um Mailboxnamen zu kodieren, die außerhalb des druckbaren ASCII-Bereichs liegen.

### Parameter-Liste

`string`

  Ein ISO-8859-1-String

### Rückgabewerte

Gibt `string` kodiert im modifizierten UTF-7-Format wie in » RFC 2060, Abschnitt 5.1.3 definiert zurück.

### Siehe auch

- imap_utf7_decode() - Dekodiert einen String im modifizierten UTF-7-Format

# imap_utf8

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf8 — Konvertiert Text nach UTF-8

### Beschreibung

function imap_utf8(string `$mime_encoded_text`): string

Konvertiert den übergebenen String `mime_encoded_text` ins UTF-8-Format, wenn der deklarierte Zeichensatz dem libc-Client bekannt ist. Andernfalls wird der übergebene Text dekodiert, aber nicht nach UTF-8 konvertiert.

### Parameter-Liste

`mime_encoded_text`

  Ein MIME-kodierter String. Die Methode der MIME-Kodierung und die UTF-8-Spezifikation finden sich unter » RFC2047 und » RFC2044.

### Rückgabewerte

Gibt den dekodierten String zurück, wenn möglich nach UTF-8 konvertiert.

### Beispiele

Beispiel #1 Die grundlegende imap_utf8()-Verwendung

    <?php
    echo imap_utf8("Johannes =?ISO-8859-1?Q?Schl=FCter?=");
    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Johannes Schlüter

### Siehe auch

- imap_mime_header_decode() - Dekodiert MIME-kodierte Kopfzeilen

# imap_utf8_to_mutf7

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_utf8_to_mutf7 — Encode a UTF-8 string to modified UTF-7

### Beschreibung

function imap_utf8_to_mutf7(string `$string`): string|false

Encode a UTF-8 string to modified UTF-7 (as specified in RFC 2060, section 5.1.3).

> Hinweis:

> This function is only available, if libcclient exports utf8_to_mutf7().

### Parameter-Liste

`string`

  A UTF-8 encoded string.

### Rückgabewerte

Returns `string` converted to modified UTF-7, Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- imap_mutf7_to_utf8() - Decode a modified UTF-7 string to UTF-8

## Inhaltsverzeichnis

- imap_8bit — Konvertiert einen 8bit-String in einen quoted-printable String
- imap_alerts — Liefert alle aufgetretenen IMAP-Alarmnachrichten
- imap_append — Hängt eine String-Nachricht an ein Postfach an
- imap_base64 — Dekodiert Base64-kodierten Text
- imap_binary — Konvertiert einen 8bit-String in einen Base64-kodierten String
- imap_body — Liefert den Textkörper einer Nachricht
- imap_bodystruct — Liefert die Struktur eines bestimmten Nachrichtenteils
- imap_check — Prüft das aktuelle Postfach
- imap_clearflag_full — Löscht die Flags einer Nachricht
- imap_close — Schließt einen IMAP-Stream
- imap_create — Alias von imap_createmailbox
- imap_createmailbox — Legt ein neues Postfach an
- imap_delete — Markiert eine Nachricht im aktuellen Postfach zur Löschung
- imap_deletemailbox — Löscht ein Postfach
- imap_errors — Liefert alle bisher aufgetretenen Fehlermeldungen
- imap_expunge — Löscht alle zum Löschen markierte Nachrichten
- imap_fetch_overview — Liefert eine Zusammenfassung der Kopfdaten von Nachrichten
- imap_fetchbody — Liefert einen bestimmten Abschnitt aus dem Textkörper einer Nachricht
- imap_fetchheader — Liefert den Kopf einer Nachricht
- imap_fetchmime — Fetch MIME headers for a particular section of the message
- imap_fetchstructure — Liefert die Struktur einer Nachricht
- imap_fetchtext — Alias von imap_body
- imap_gc — Leert den IMAP-Cache
- imap_get_quota — Liefert Quota-Einstellungen und Nutzungsstatistik der Postfächer
- imap_get_quotaroot — Liefert die Quota-Einstellungen für ein Benutzerpostfach
- imap_getacl — Liefert die Liste der Zugriffsrechte (ACL) für ein Postfach
- imap_getmailboxes — Liefert detaillierte Informationen zu allen Postfächern
- imap_getsubscribed — Liefert die Liste aller abonnierten Postfächer
- imap_header — Alias von imap_headerinfo
- imap_headerinfo — Liefert Informationen über die Kopfdaten einer Nachricht
- imap_headers — Liefert die Kopfzeilen aller Nachrichten eines Postfachs
- imap_is_open — Check if the IMAP stream is still valid
- imap_last_error — Liefert den zuletzt aufgetretenen IMAP-Fehler
- imap_list — Liefert die Liste der Postfächer
- imap_listmailbox — Alias von imap_list
- imap_listscan — Liefert eine Liste von Postfächern nach Suchkriterien
- imap_listsubscribed — Alias von imap_lsub
- imap_lsub — Liefert eine Liste aller abonnierten Postfächer
- imap_mail — Sendet eine E-Mail-Nachricht
- imap_mail_compose — Erzeugt eine MIME-Nachricht aus Kopf- und Nachrichtenelementen
- imap_mail_copy — Kopiert Nachrichten in ein Postfach
- imap_mail_move — Verschiebt Nachrichten in ein anderes Postfach
- imap_mailboxmsginfo — Liefert Informationen zum aktuellen Postfach
- imap_mime_header_decode — Dekodiert MIME-kodierte Kopfzeilen
- imap_msgno — Liefert die Nummer einer Nachricht für eine gegebene UID
- imap_mutf7_to_utf8 — Decode a modified UTF-7 string to UTF-8
- imap_num_msg — Liefert die Anzahl der Nachrichten im aktuellen Postfach
- imap_num_recent — Liefert die Anzahl der kürzlich eingetroffenen Nachrichten
- imap_open — Öffnet einen IMAP-Stream zu einem Postfach
- imap_ping — Prüft einen IMAP-Stream auf Funktionalität
- imap_qprint — Konvertiert einen quoted-printable-kodierten String in einen 8-Bit-String
- imap_rename — Alias von imap_renamemailbox
- imap_renamemailbox — Ändert den Namen eines Postfachs
- imap_reopen — Öffnet einen IMAP-Stream für ein anderes Postfach neu
- imap_rfc822_parse_adrlist — Zerlegt einen String mit Mailadressen
- imap_rfc822_parse_headers — Liest E-Mail-Kopfzeilen aus einem String aus
- imap_rfc822_write_address — Liefert eine korrekt formatierte E-Mail-Adresse aus übergebenen Informationen
- imap_savebody — Speichert einen Teil des Nachrichtentextes in einer Datei
- imap_scan — Alias von imap_listscan
- imap_scanmailbox — Alias von imap_listscan
- imap_search — Liefert ein Array von Nachrichten, die den gegebenen Suchkriterien entsprechen
- imap_set_quota — Legt die Größenbeschränkung für ein Postfach fest
- imap_setacl — Legt die ACL (Zugriffsrechte) für ein Postfach fest
- imap_setflag_full — Setzt Nachrichtenflags
- imap_sort — Liefert und sortiert Nachrichten eines Postfachs
- imap_status — Liefert Statusinformationen zum angegebenen Postfach
- imap_subscribe — Abonniert ein Postfach
- imap_thread — Liefert Nachrichten als Baum zusammenhängender Themenstränge
- imap_timeout — Setzt oder liefert den Imap-Timeout
- imap_uid — Liefert die UID für die gegebene Nachrichtennummer
- imap_undelete — Nimmt eine bereits gesetzte Löschmarkierung einer Nachricht zurück
- imap_unsubscribe — Beendet das Abonnement eines Postfachs
- imap_utf7_decode — Dekodiert einen String im modifizierten UTF-7-Format
- imap_utf7_encode — Kodiert ISO-8859-1 Text im modifizieren UTF-7-Format
- imap_utf8 — Konvertiert Text nach UTF-8
- imap_utf8_to_mutf7 — Encode a UTF-8 string to modified UTF-7

# Die Klasse IMAP\Connection

(PHP 8 >= 8.1.0)

## Einführung

Eine vollständig opake Klasse, die ab PHP 8.1.0 eine `imap`-Ressource ersetzt.

## Klassenbeschreibung

final class IMAP\Connection {
}

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- IMAP Funktionen
  - imap_8bit — Konvertiert einen 8bit-String in einen quoted-printable String
  - imap_alerts — Liefert alle aufgetretenen IMAP-Alarmnachrichten
  - imap_append — Hängt eine String-Nachricht an ein Postfach an
  - imap_base64 — Dekodiert Base64-kodierten Text
  - imap_binary — Konvertiert einen 8bit-String in einen Base64-kodierten String
  - imap_body — Liefert den Textkörper einer Nachricht
  - imap_bodystruct — Liefert die Struktur eines bestimmten Nachrichtenteils
  - imap_check — Prüft das aktuelle Postfach
  - imap_clearflag_full — Löscht die Flags einer Nachricht
  - imap_close — Schließt einen IMAP-Stream
  - imap_create — Alias von imap_createmailbox
  - imap_createmailbox — Legt ein neues Postfach an
  - imap_delete — Markiert eine Nachricht im aktuellen Postfach zur Löschung
  - imap_deletemailbox — Löscht ein Postfach
  - imap_errors — Liefert alle bisher aufgetretenen Fehlermeldungen
  - imap_expunge — Löscht alle zum Löschen markierte Nachrichten
  - imap_fetch_overview — Liefert eine Zusammenfassung der Kopfdaten von Nachrichten
  - imap_fetchbody — Liefert einen bestimmten Abschnitt aus dem Textkörper einer Nachricht
  - imap_fetchheader — Liefert den Kopf einer Nachricht
  - imap_fetchmime — Fetch MIME headers for a particular section of the message
  - imap_fetchstructure — Liefert die Struktur einer Nachricht
  - imap_fetchtext — Alias von imap_body
  - imap_gc — Leert den IMAP-Cache
  - imap_get_quota — Liefert Quota-Einstellungen und Nutzungsstatistik der Postfächer
  - imap_get_quotaroot — Liefert die Quota-Einstellungen für ein Benutzerpostfach
  - imap_getacl — Liefert die Liste der Zugriffsrechte (ACL) für ein Postfach
  - imap_getmailboxes — Liefert detaillierte Informationen zu allen Postfächern
  - imap_getsubscribed — Liefert die Liste aller abonnierten Postfächer
  - imap_header — Alias von imap_headerinfo
  - imap_headerinfo — Liefert Informationen über die Kopfdaten einer Nachricht
  - imap_headers — Liefert die Kopfzeilen aller Nachrichten eines Postfachs
  - imap_is_open — Check if the IMAP stream is still valid
  - imap_last_error — Liefert den zuletzt aufgetretenen IMAP-Fehler
  - imap_list — Liefert die Liste der Postfächer
  - imap_listmailbox — Alias von imap_list
  - imap_listscan — Liefert eine Liste von Postfächern nach Suchkriterien
  - imap_listsubscribed — Alias von imap_lsub
  - imap_lsub — Liefert eine Liste aller abonnierten Postfächer
  - imap_mail — Sendet eine E-Mail-Nachricht
  - imap_mail_compose — Erzeugt eine MIME-Nachricht aus Kopf- und Nachrichtenelementen
  - imap_mail_copy — Kopiert Nachrichten in ein Postfach
  - imap_mail_move — Verschiebt Nachrichten in ein anderes Postfach
  - imap_mailboxmsginfo — Liefert Informationen zum aktuellen Postfach
  - imap_mime_header_decode — Dekodiert MIME-kodierte Kopfzeilen
  - imap_msgno — Liefert die Nummer einer Nachricht für eine gegebene UID
  - imap_mutf7_to_utf8 — Decode a modified UTF-7 string to UTF-8
  - imap_num_msg — Liefert die Anzahl der Nachrichten im aktuellen Postfach
  - imap_num_recent — Liefert die Anzahl der kürzlich eingetroffenen Nachrichten
  - imap_open — Öffnet einen IMAP-Stream zu einem Postfach
  - imap_ping — Prüft einen IMAP-Stream auf Funktionalität
  - imap_qprint — Konvertiert einen quoted-printable-kodierten String in einen 8-Bit-String
  - imap_rename — Alias von imap_renamemailbox
  - imap_renamemailbox — Ändert den Namen eines Postfachs
  - imap_reopen — Öffnet einen IMAP-Stream für ein anderes Postfach neu
  - imap_rfc822_parse_adrlist — Zerlegt einen String mit Mailadressen
  - imap_rfc822_parse_headers — Liest E-Mail-Kopfzeilen aus einem String aus
  - imap_rfc822_write_address — Liefert eine korrekt formatierte E-Mail-Adresse aus übergebenen Informationen
  - imap_savebody — Speichert einen Teil des Nachrichtentextes in einer Datei
  - imap_scan — Alias von imap_listscan
  - imap_scanmailbox — Alias von imap_listscan
  - imap_search — Liefert ein Array von Nachrichten, die den gegebenen Suchkriterien entsprechen
  - imap_set_quota — Legt die Größenbeschränkung für ein Postfach fest
  - imap_setacl — Legt die ACL (Zugriffsrechte) für ein Postfach fest
  - imap_setflag_full — Setzt Nachrichtenflags
  - imap_sort — Liefert und sortiert Nachrichten eines Postfachs
  - imap_status — Liefert Statusinformationen zum angegebenen Postfach
  - imap_subscribe — Abonniert ein Postfach
  - imap_thread — Liefert Nachrichten als Baum zusammenhängender Themenstränge
  - imap_timeout — Setzt oder liefert den Imap-Timeout
  - imap_uid — Liefert die UID für die gegebene Nachrichtennummer
  - imap_undelete — Nimmt eine bereits gesetzte Löschmarkierung einer Nachricht zurück
  - imap_unsubscribe — Beendet das Abonnement eines Postfachs
  - imap_utf7_decode — Dekodiert einen String im modifizierten UTF-7-Format
  - imap_utf7_encode — Kodiert ISO-8859-1 Text im modifizieren UTF-7-Format
  - imap_utf8 — Konvertiert Text nach UTF-8
  - imap_utf8_to_mutf7 — Encode a UTF-8 string to modified UTF-7
- IMAP\Connection — Die Klasse IMAP\Connection

# Mail

# Einführung

Die mail()-Funktion ermöglicht das Senden von E-Mails.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Laufzeit-Konfiguration

## Anforderungen

PHP muss während des Kompilierens Zugriff auf die Binärversion von `sendmail` auf Ihrem Rechner haben. Falls Sie ein anderes Mail-Programm, wie z. B. qmail oder postfix, benutzen, müssen Sie dafür sorgen, dass Sie den passenden, mitgelieferten sendmail-Wrapper verwenden. PHP sucht nach sendmail zunächst im System-PATH und anschließend hier: `/usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib`. Wir empfehlen, dass sendmail auf Ihrem Rechner im PATH verfügbar ist. Der Benutzer, der PHP kompiliert hat, muss die Berechtigung haben, auf die Binärversion von sendmail zuzugreifen.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Mail-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
mail.add_x_header | "0" | `INI_PERDIR` |
mail.mixed_lf_and_crlf | "0" | `INI_SYSTEM`|`INI_PERDIR` | Hinzugefügt in PHP 8.2.4
mail.log | NULL | `INI_SYSTEM`|`INI_PERDIR` |
mail.force_extra_parameters | NULL | `INI_SYSTEM` |
SMTP | "localhost" | `INI_ALL` |
smtp_port | "25" | `INI_ALL` |
sendmail_from | NULL | `INI_ALL` |
sendmail_path | "/usr/sbin/sendmail -t -i" | `INI_SYSTEM` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`mail.add_x_header` bool

  Fügt den `X-PHP-Originating-Script`-Header hinzu, der die UID des Skripts gefolgt vom Dateinamen enthält.

`mail.log` string

  Der Pfad zur Log-Datei, in der mail()-Aufrufe geloggt werden. Die Log-Einträge enthalten den vollen Pfad des Skripts, die Zeilennummer, die `To`-Adresse und alle Header.

`mail.mixed_lf_and_crlf` bool

  Ermöglicht die Konvertierung des Zeilentrenners für E-Mail-Kopfzeilen und -Textkörper in LF (Line Feed) und ahmt damit das nicht konforme Verhalten von PHP 7 nach. Es wird als Kompatibilitätsmaßnahme für bestimmte nicht konforme Mail Transfer Agents (MTAs) bereitgestellt, die CRLF (Carriage Return + Line Feed) nicht korrekt als Zeilentrennzeichen in E-Mail-Kopfzeilen und -Nachrichtentexten verarbeiten.

`mail.force_extra_parameters` string

  Erzwingt das Hinzufügen der angegebenen Parameter als extra Parameter an das sendmail-Binary. Diese Parameter ersetzen immer den Wert für den fünften Parameter der Funktion mail().

  Zusätzlich zum Standardverhalten für `INI_SYSTEM`, kann dieser Wert auch in der httpd.conf mit `php_value` gesetzt werden (dies wird jedoch nicht empfohlen).
`SMTP` string

  Wird nur unter Windows verwendet: Der Hostname oder die IP-Adresse des SMTP-Servers, den PHP für Mails verwenden soll, die mit der Funktion mail() verschickt werden.

`smtp_port` int

  Wird nur unter Windows benutzt: Die Nummer des Ports des Servers (angegeben in der `SMTP`-Option), um eine Verbindung herzustellen, wenn eine Mail mit der Funktion mail() verschickt wird. Standardwert ist 25.

`sendmail_from` string

  Die "From:"-Mail-Adresse, die in Mails verwendet werden soll, die direkt über SMTP gesendet werden (nur unter Windows). Diese Direktive setzt auch den "Return-Path:"-Header.

`sendmail_path` string

  Der Pfad, in dem sich das sendmail-Programm befindet, z. B. /usr/sbin/sendmail oder /usr/lib/sendmail. configure versucht, die richtige Position automatisch zu finden. Falls die automatische Erkennung aber fehlschlägt und der Standardwert auf Ihrem Rechner falsch ist, dann können Sie hier den richtigen Pfad angeben.

  Falls Sie auf Ihrem Rechner sendmail nicht verwenden, müssen Sie den Pfad angeben, in dem sich der sendmail-Wrapper/-Ersatz befindet, sofern vorhanden. Zum Beispiel können » Qmail-Benutzer diese Option auf /var/qmail/bin/sendmail oder /var/qmail/bin/qmail-inject setzen.

  qmail-inject benötigt keine Optionen, um Mails korrekt zu verarbeiten.

  Diese Option funktioniert auch unter Windows. Wenn Sie gesetzt ist, werden smtp, smtp_port und sendmail_from ignoriert und das angegebene Kommando wird ausgeführt.

# Mail-Funktionen

# ezmlm_hash

(PHP 4 >= 4.0.2, PHP 5, PHP 7)

ezmlm_hash — Berechnet den Hash-Wert, der von EZMLM benötigt wird

Warnung

Diese Funktion ist seit PHP 7.4.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function ezmlm_hash(string `$addr`): int

ezmlm_hash() berechnet den Hash-Wert, der benötigt wird, wenn EZMLM-Mailinglisten in einer MySQL-Datenbank gespeichert werden.

### Parameter-Liste

`addr`

  Die E-Mail-Adresse, die gehasht werden soll.

### Rückgabewerte

Der Hash-Wert von `addr`.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Diese Funktion wurde entfernt.
7.2.0 | Diese Funktion wurde als veraltet eingestuft.

### Beispiele

Beispiel #1 Hash-Wert berechnen und einen Benutzer hinzufügen

    <?php

    $user = "joecool@example.com";
    $hash = ezmlm_hash($user);
    $query = sprintf("INSERT INTO beispiel VALUES (%s, '%s')", $hash, $user);
    $db->query($query);  // die PHPLIB-DB-Klasse wird benutzt

    ?>

# mail

(PHP 4, PHP 5, PHP 7, PHP 8)

mail — Sendet eine E-Mail

### Beschreibung

function mail(
string `$to`,
string `$subject`,
string `$message`,
array|string `$additional_headers` = [],
string `$additional_params` = ""
): bool

Sendet eine E-Mail.

### Parameter-Liste

`to`

  Ein oder mehrere Empfänger der E-Mail.

  Die Formatierung dieser Zeichenkette muss nach » RFC 2822 erfolgen. Beispiele:

  - benutzer@example.com
  - benutzer@example.com, benutzer2@example.com
  - Name
  - Name , Name2
`subject`

  Der Betreff der E-Mail.

  Achtung

  Die Formatierung dieser Zeichenkette muss nach » RFC 2047 erfolgen.

`message`

  Die zu sendende Nachricht.

  Jede Zeile muss durch CRLF (\r\n) getrennt werden. Außerdem sollten die Zeilen nicht mehr als 70 Zeichen enthalten.

  Achtung

  (Nur unter Windows) Falls PHP direkt mit einem SMTP-Server kommuniziert und wenn ein Punkt (.) an einem Zeilenanfang steht, wird dieser Punkt entfernt. Um das zu verhindern, können Sie diese Punkte durch zwei Punkte ersetzen.

      <?php
      $text = str_replace("\n.", "\n..", $text);
      ?>

`additional_headers` (optional)

  string oder array, das am Ende des E-Mail-Headers eingefügt werden soll.

  Dies kann benutzt werden, um zusätzliche Header wie From, Cc oder Bcc anzugeben. Falls mehrere solcher zusätzlichen Header angegeben werden sollen, müssen diese durch ein CRLF-Zeichen (\r\n) getrennt werden. Wenn von außen kommende Daten verwendet werden, um diesen Header zusammenzustellen, sollten diese Daten bereinigt werden, so dass keine ungewünschten Header eingeschleust werden können.

  Wird ein array übergeben, werden dessen Schlüssel als Header-Namen, und dessen Werte als entsprechende Header-Werte interpretiert.

  > Hinweis:

  > Um eine E-Mail zu senden, muss die E-Mail einen `From`-Header enthalten. Dies kann entweder durch Setzen eines `additional_headers`-Parameters oder durch Setzen eines Standardwertes in der php.ini geschehen.

  > Falls dies nicht geschieht, wird eine Fehlermeldung ähnlich wie `Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing` ausgegeben. Der `From`-Header setzt unter Windows auch den `Return-Path`-Header.

  > Hinweis:

  > Wenn E-Mails nicht ankommen, versuchen Sie bitte, nur das LF-Zeichen (\n) zu verwenden. Einige UNIX-MTAs (Mail Transfer Agents) (ganz besonders » qmail) ersetzen leider LF durch CRLF (\r\n) automatisch (wodurch das CR-Zeichen verdoppelt wird, wenn CRLF verwendet wird). Dies sollte aber nur in Ausnahmefällen geschehen, da es gegen » RFC 2822 verstößt.

`additional_params` (optional)

  Der Parameter `additional_params` kann verwendet werden, um zusätzliche Parameter an das Programm zu senden, das für den E-Mail-Versand konfiguriert ist (wenn die `sendmail_path`-Einstellung verwendet wird). Zum Beispiel kann hiermit die Envelope Sender Address (Umschlag-Absenderadresse) gesetzt werden, wenn sendmail mit der `-f`-Option verwendet wird.

  Dieser Parameter wird intern durch escapeshellcmd() maskiert, um die Kommando-Injection zu verhindern. escapeshellcmd() verhindert die Kommando-Injection, erlaubt aber, zusätzliche Parameter hinzuzufügen. Aus Sicherheitsgründen wird empfohlen, dass dieser Parameter bereinigt wird, um zu verhindern, dass keine unerwünschten Parameter an das Shell-Kommando übergeben werden.

  Da escapeshellcmd() automatisch angewendet wird, können einige Zeichen, die gemäß Internet-RFCs in E-Mail-Adressen erlaubt sind, nicht verwendet werden. mail() kann solche Zeichen nicht erlauben, so dass für Programme, die diese Zeichen unterstützen müssen, alternative Methoden für den E-Mail-Versand (wie beispielsweise die Verwendung eines Frameworks oder einer Bibliothek) empfohlen werden.

  Der Benutzer, unter dem der Webserver läuft, sollte als vertrauenswürdiger Benutzer in der sendmail-Konfiguration eingetragen werden, um zu verhindern, dass ein 'X-Warning'-Header zu den E-Mails hingefügt wird, wenn mit dieser Methode (-f) der Absender gesetzt wird. Sendmail-Benutzer finden diese Datei hier: /etc/mail/trusted-users.

### Rückgabewerte

Gibt `true` zurück, wenn die E-Mail erfolgreich für den Versand akzeptiert wurde, sonst `false`.

Dass eine E-Mail für den Versand akzeptiert wurde, bedeutet NICHT, dass sie auch wirklich den gewünschten Empfänger erreichen wird.

### Changelog

Version | Beschreibung
--- | ---
7.2.0 | Der Parameter `additional_headers` akzeptiert nun auch ein array.

### Beispiele

Beispiel #1 Verschicken einer E-Mail

mail() wird benutzt, um eine einfache E-Mail zu versenden:

    <?php
    // Die Nachricht
    $nachricht = "Zeile 1\r\nZeile 2\r\nZeile 3";

    // Falls eine Zeile der Nachricht mehr als 70 Zeichen enthälten könnte,
    // sollte wordwrap() benutzt werden
    $nachricht = wordwrap($nachricht, 70, "\r\n");

    // Verschicken
    mail('benutzer@example.com', 'Mein Betreff', $nachricht);
    ?>

Beispiel #2 Verschicken einer E-Mail mit zusätzlichen Headern

Hier werden einfache Header gesetzt, um dem MUA (Mail User Agent, z. B. ein E-Mail-Programm) die From- und die Reply-To-Adressen mitzuteilen:

    <?php
    $empfaenger = 'niemand@example.com';
    $betreff = 'Der Betreff';
    $nachricht = 'Hallo';
    $header = 'From: webmaster@example.com' . "\r\n" .
        'Reply-To: webmaster@example.com' . "\r\n" .
        'X-Mailer: PHP/' . phpversion();

    mail($empfaenger, $betreff, $nachricht, $header);
    ?>

Beispiel #3 Verschicken einer E-Mail mit zusätzliche Headern als Array

Dieses Beispiel verschickt die selbe E-Mail wie das Beispiel direkt darüber, aber diesemal werden die zusätzlichen Header als Array übergeben (verfügbar von PHP 7.2.0 an).

    <?php
    $empfaenger = 'niemand@example.com';
    $betreff = 'Der Betreff';
    $nachricht = 'Hallo';
    $header = array(
        'From' => 'webmaster@example.com',
        'Reply-To' => 'webmaster@example.com',
        'X-Mailer' => 'PHP/' . phpversion()
    );

    mail($empfaenger, $betreff, $nachricht, $header);
    ?>

Beispiel #4 Verschicken einer E-Mail mit einem zusätzlichen Kommandozeilen-Parameter

Der Parameter `additional_params` kann verwendet werden, um einen zusätzlichen Parameter an das über `sendmail_path` konfigurierte Programm zu senden.

    <?php
    mail('niemand@example.com', 'Betreff', 'Nachricht', null,
       '-fwebmaster@example.com');
    ?>

Beispiel #5 Verschicken einer HTML-E-Mail.

Auch HTML-E-Mails können mit mail() versendet werden.

    <?php
    // mehrere Empfänger
    $empfaenger  = 'max@example.com, moritz@example.com'; // beachte das Komma

    // Betreff
    $betreff = 'Geburtstags-Erinnerungen für August';

    // Nachricht
    $nachricht = '
    <html>
    <head>
      <title>Geburtstags-Erinnerungen für August</title>
    </head>
    <body>
      <p>Hier sind die Geburtstage im August:</p>
      <table>
        <tr>
          <th>Person</th><th>Tag</th><th>Monat</th><th>Jahr</th>
        </tr>
        <tr>
          <td>Max</td><td>3.</td><td>August</td><td>1970</td>
        </tr>
        <tr>
          <td>Moritz</td><td>17.</td><td>August</td><td>1973</td>
        </tr>
      </table>
    </body>
    </html>
    ';

    // für HTML-E-Mails muss der 'Content-type'-Header gesetzt werden
    $header[] = 'MIME-Version: 1.0';
    $header[] = 'Content-type: text/html; charset=iso-8859-1';

    // zusätzliche Header
    $header[] = 'To: Simone <simone@example.com>, Andreas <andreas@example.com>';
    $header[] = 'From: Geburtstags-Erinnerungen <geburtstag@example.com>';
    $header[] = 'Cc: geburtstagsarchiv@example.com';
    $header[] = 'Bcc: geburtstagscheck@example.com';

    // verschicke die E-Mail
    mail($empfaenger, $betreff, $nachricht, implode("\r\n", $header));
    ?>

> Hinweis:

> Wenn HTML- oder anderweitig komplexe E-Mails versendet werden sollen, ist es empfehlenswert, das PEAR-Paket » PEAR::Mail_Mime zu verwenden.

### Anmerkungen

> Hinweis:

> Die SMTP-Implementierung (nur unter Windows) von mail() unterscheidet sich auf mehrere Arten von der Unix-Implementierung. Zum einen verwendet sie kein lokales Programm, um die Mails zu erstellen, sondern arbeitet auf Sockets, d. h., es wird ein `MTA` benötigt, der auf einem Netzwerk-Socket lauscht (entweder auf dem eigenen oder einem entfernten Rechner).

> Zum anderen, werden die benutzerdefinierten Header wie `From:`, `Cc:`, `Bcc:` und `Date:` nicht direkt durch den `MTA` interpretiert, sondern zunächst von PHP geparst.

> Daher sollte der Parameter `to` keine Adresse der Form "Irgendwas <irgendwer@example.com>" enthalten, da dies von PHP möglicherweise nicht korrekt an den MTA übergeben werden kann.

> Hinweis:

> Es ist zu beachten, dass die Funktion mail() nicht dazu geeignet ist, große Mengen von E-Mails in einer Schleife zu senden, da die Funktion für jede E-Mail einen SMTP-Socket öffnet und schließt, was nicht sehr effizient ist.

> Um große Mengen von E-Mails zu senden, können die PEAR-Pakete » PEAR::Mail und » PEAR::Mail_Queue verwendet werden.

> Hinweis:

> Die folgenden RFCs könnten nützlich für Sie sein: » RFC 1896, » RFC 2045, » RFC 2046, » RFC 2047, » RFC 2048, » RFC 2049 und » RFC 2822.

### Siehe auch

- mb_send_mail() - Send encoded mail
- imap_mail() - Sendet eine E-Mail-Nachricht
- » PEAR::Mail
- » PEAR::Mail_Mime

## Inhaltsverzeichnis

- ezmlm_hash — Berechnet den Hash-Wert, der von EZMLM benötigt wird
- mail — Sendet eine E-Mail

- Installation/Konfiguration
  - Anforderungen
  - Laufzeit-Konfiguration
- Mail-Funktionen
  - ezmlm_hash — Berechnet den Hash-Wert, der von EZMLM benötigt wird
  - mail — Sendet eine E-Mail

# Mailparse

# Einführung

Mailparse is an extension for parsing and working with email messages. It can deal with » RFC 822 and » RFC 2045 (`MIME`) compliant messages.

Mailparse is stream based, which means that it does not keep in-memory copies of the files it processes - so it is very resource efficient when dealing with large messages.

> Hinweis: Mailparse requires the mbstring extension, and mbstring must be loaded before mailparse.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Laufzeit-Konfiguration
- Ressource-Typen

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP. Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/mailparse.

In order to use these functions you must compile PHP with mailparse support by using the --enable-mailparse configure option.

Windows users will enable php_mailparse.dll inside of php.ini in order to use these functions. Windows-Binaries (DLL-Dateien) für diese PECL-Erweiterung sind auf der PECL-Website erhältlich.

It is necessary that the mbstring extension is loaded before mailparse.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Mailparse Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
mailparse.def_charset | "us-ascii" | `INI_SYSTEM` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`mailparse.def_charset` string
  The default character set.

## Ressource-Typen

Mailparse defines the resource type `mailparse_mail_structure`, which is returned by mailparse_msg_create() and mailparse_msg_parse_file().

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`MAILPARSE_EXTRACT_OUTPUT` (int)
`MAILPARSE_EXTRACT_STREAM` (int)
`MAILPARSE_EXTRACT_RETURN` (int)

# Mailparse Funktionen

# mailparse_determine_best_xfer_encoding

(PECL mailparse >= 0.9.0)

mailparse_determine_best_xfer_encoding — Gets the best way of encoding

### Beschreibung

function mailparse_determine_best_xfer_encoding(resource `$fp`): string

Figures out the best way of encoding the content read from the given file pointer.

### Parameter-Liste

`fp`
  A valid file pointer, which must be seek-able.

### Rückgabewerte

Returns one of the character encodings supported by the mbstring module.

### Beispiele

Beispiel #1 mailparse_determine_best_xfer_encoding() example

    <?php

    $fp = fopen('somemail.eml', 'r');
    echo 'Best encoding: ' . mailparse_determine_best_xfer_encoding($fp);

    ?>

Das oben gezeigte Beispiel erzeugt eine ähnliche Ausgabe wie:

    Best encoding: 7bit

# mailparse_msg_create

(PECL mailparse >= 0.9.0)

mailparse_msg_create — Create a mime mail resource

### Beschreibung

function mailparse_msg_create(): resource

Create a `MIME` mail resource.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a handle that can be used to parse a message.

### Anmerkungen

> Hinweis: It is recommended to call mailparse_msg_free() on the result of this function, when it is no longer needed, to avoid memory leaks.

### Siehe auch

- mailparse_msg_free() - Frees a MIME resource
- mailparse_msg_parse_file() - Parses a file

# mailparse_msg_extract_part

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part — Extracts/decodes a message section

### Beschreibung

function mailparse_msg_extract_part(resource `$mimemail`, string `$msgbody`, callable `$callbackfunc` = ?): void
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`mimemail`
  A valid `MIME` resource.
`msgbody`
`callbackfunc`

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- mailparse_msg_extract_part_file() - Extracts/decodes a message section
- mailparse_msg_extract_whole_part_file() - Extracts a message section including headers without decoding the transfer encoding

# mailparse_msg_extract_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part_file — Extracts/decodes a message section

### Beschreibung

function mailparse_msg_extract_part_file(resource `$mimemail`, mixed `$filename`, callable `$callbackfunc` = ?): string

Extracts/decodes a message section from the supplied filename.

The contents of the section will be decoded according to their transfer encoding - base64, quoted-printable and uuencoded text are supported.

### Parameter-Liste

`mimemail`
  A valid `MIME` resource, created with mailparse_msg_create().
`filename`
  Can be a file name or a valid stream resource.
`callbackfunc`
  If set, this must be either a valid callback that will be passed the extracted section, or `null` to make this function return the extracted section. If not specified, the contents will be sent to "stdout".

### Rückgabewerte

If `callbackfunc` is not `null` returns `true` on success.

If `callbackfunc` is set to `null`, returns the extracted section as a string.

Returns `false` on error.

### Siehe auch

- mailparse_msg_extract_part() - Extracts/decodes a message section
- mailparse_msg_extract_whole_part_file() - Extracts a message section including headers without decoding the transfer encoding

# mailparse_msg_extract_whole_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_whole_part_file — Extracts a message section including headers without decoding the transfer encoding

### Beschreibung

function mailparse_msg_extract_whole_part_file(resource `$mimemail`, string `$filename`, callable `$callbackfunc` = ?): string
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`mimemail`
  A valid `MIME` resource.
`filename`
`callbackfunc`

### Rückgabewerte

### Siehe auch

- mailparse_msg_extract_part() - Extracts/decodes a message section
- mailparse_msg_extract_part_file() - Extracts/decodes a message section

# mailparse_msg_free

(PECL mailparse >= 0.9.0)

mailparse_msg_free — Frees a MIME resource

### Beschreibung

function mailparse_msg_free(resource `$mimemail`): bool

Frees a `MIME` resource.

### Parameter-Liste

`mimemail`
  A valid `MIME` resource allocated by mailparse_msg_create() or mailparse_msg_parse_file().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- mailparse_msg_create() - Create a mime mail resource
- mailparse_msg_parse_file() - Parses a file

# mailparse_msg_get_part

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part — Returns a handle on a given section in a mimemessage

### Beschreibung

function mailparse_msg_get_part(resource `$mimemail`, string `$mimesection`): resource
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`mimemail`
  A valid `MIME` resource.
`mimesection`

# mailparse_msg_get_part_data

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part_data — Returns an associative array of info about the message

### Beschreibung

function mailparse_msg_get_part_data(resource `$mimemail`): array
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`mimemail`
  A valid `MIME` resource.

# mailparse_msg_get_structure

(PECL mailparse >= 0.9.0)

mailparse_msg_get_structure — Returns an array of mime section names in the supplied message

### Beschreibung

function mailparse_msg_get_structure(resource `$mimemail`): array
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`mimemail`
  A valid `MIME` resource.

# mailparse_msg_parse

(PECL mailparse >= 0.9.0)

mailparse_msg_parse — Incrementally parse data into buffer

### Beschreibung

function mailparse_msg_parse(resource `$mimemail`, string `$data`): bool

Incrementally parse data into the supplied mime mail resource.

This function allow you to stream portions of a file at a time, rather than read and parse the whole thing.

### Parameter-Liste

`mimemail`
  A valid `MIME` resource.
`data`

  > Hinweis: The final chunk of `data` is supposed to end with a newline (`CRLF`); otherwise the last line of the message will not be parsed.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# mailparse_msg_parse_file

(PECL mailparse >= 0.9.0)

mailparse_msg_parse_file — Parses a file

### Beschreibung

function mailparse_msg_parse_file(string `$filename`): resource

Parses a file. This is the optimal way of parsing a mail file that you have on disk.

### Parameter-Liste

`filename`
  Path to the file holding the message. The file is opened and streamed through the parser.

  > Hinweis: The message contained in `filename` is supposed to end with a newline (`CRLF`); otherwise the last line of the message will not be parsed.

### Rückgabewerte

Returns a `MIME` resource representing the structure, or `false` on error.

### Anmerkungen

> Hinweis: It is recommended to call mailparse_msg_free() on the result of this function, when it is no longer needed, to avoid memory leaks.

### Siehe auch

- mailparse_msg_free() - Frees a MIME resource
- mailparse_msg_create() - Create a mime mail resource

# mailparse_rfc822_parse_addresses

(PECL mailparse >= 0.9.0)

mailparse_rfc822_parse_addresses — Parse RFC 822 compliant addresses

### Beschreibung

function mailparse_rfc822_parse_addresses(string `$addresses`): array

Parses a » RFC 822 compliant recipient list, such as that found in the `To:` header.

### Parameter-Liste

`addresses`
  A string containing addresses, like in: `Wez Furlong <wez@example.com>, doe@example.com`

  > Hinweis: This string must not include the header name.

### Rückgabewerte

Returns an array of associative arrays with the following keys for each recipient:

`display` | The recipient name, for display purpose. If this part is not set for a recipient, this key will hold the same value as `address`.
`address` | The email address
`is_group` | `true` if the recipient is a newsgroup, `false` otherwise.

### Beispiele

Beispiel #1 mailparse_rfc822_parse_addresses() example

    <?php

    $to = 'Wez Furlong <wez@example.com>, doe@example.com';
    var_dump(mailparse_rfc822_parse_addresses($to));

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(2) {
      [0]=>
      array(3) {
        ["display"]=>
        string(11) "Wez Furlong"
        ["address"]=>
        string(15) "wez@example.com"
        ["is_group"]=>
        bool(false)
      }
      [1]=>
      array(3) {
        ["display"]=>
        string(15) "doe@example.com"
        ["address"]=>
        string(15) "doe@example.com"
        ["is_group"]=>
        bool(false)
      }
    }

# mailparse_stream_encode

(PECL mailparse >= 0.9.0)

mailparse_stream_encode — Streams data from source file pointer, apply encoding and write to destfp

### Beschreibung

function mailparse_stream_encode(resource `$sourcefp`, resource `$destfp`, string `$encoding`): bool

Streams data from the source file pointer, apply `encoding` and write to the destination file pointer.

### Parameter-Liste

`sourcefp`
  A valid file handle. The file is streamed through the parser.
`destfp`
  The destination file handle in which the encoded data will be written.
`encoding`
  One of the character encodings supported by the mbstring module.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 mailparse_stream_encode() example

    <?php

    // email.eml contents: hello, this is some text=hello.
    $fp = fopen('email.eml', 'r');

    $dest = tmpfile();

    mailparse_stream_encode($fp, $dest, "quoted-printable");

    rewind($dest);

    // Display new file contents
    fpassthru($dest);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    hello, this is some text=3Dhello.

# mailparse_uudecode_all

(PECL mailparse >= 0.9.0)

mailparse_uudecode_all — Scans the data from fp and extract each embedded uuencoded file

### Beschreibung

function mailparse_uudecode_all(resource `$fp`): array

Scans the data from the given file pointer and extract each embedded uuencoded file into a temporary file.

### Parameter-Liste

`fp`
  A valid file pointer.

### Rückgabewerte

Returns an array of associative arrays listing filename information.

`filename` | Path to the temporary file name created
`origfilename` | The original filename, for uuencoded parts only

The first filename entry is the message body. The next entries are the decoded uuencoded files.

### Beispiele

Beispiel #1 mailparse_uudecode_all() example

    <?php

    $text = <<<EOD
    To: fred@example.com

    hello, this is some text hello.
    blah blah blah.

    begin 644 test.txt
    /=&AI<R!I<R!A('1E<W0*
    `
    end

    EOD;

    $fp = tmpfile();
    fwrite($fp, $text);

    $data = mailparse_uudecode_all($fp);

    echo "BODY\n";
    readfile($data[0]["filename"]);
    echo "UUE ({$data[1]['origfilename']})\n";
    readfile($data[1]["filename"]);

    // Clean up
    unlink($data[0]["filename"]);
    unlink($data[1]["filename"]);

    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    BODY
    To: fred@example.com

    hello, this is some text hello.
    blah blah blah.

    UUE (test.txt)
    this is a test

## Inhaltsverzeichnis

- mailparse_determine_best_xfer_encoding — Gets the best way of encoding
- mailparse_msg_create — Create a mime mail resource
- mailparse_msg_extract_part — Extracts/decodes a message section
- mailparse_msg_extract_part_file — Extracts/decodes a message section
- mailparse_msg_extract_whole_part_file — Extracts a message section including headers without decoding the transfer encoding
- mailparse_msg_free — Frees a MIME resource
- mailparse_msg_get_part — Returns a handle on a given section in a mimemessage
- mailparse_msg_get_part_data — Returns an associative array of info about the message
- mailparse_msg_get_structure — Returns an array of mime section names in the supplied message
- mailparse_msg_parse — Incrementally parse data into buffer
- mailparse_msg_parse_file — Parses a file
- mailparse_rfc822_parse_addresses — Parse RFC 822 compliant addresses
- mailparse_stream_encode — Streams data from source file pointer, apply encoding and write to destfp
- mailparse_uudecode_all — Scans the data from fp and extract each embedded uuencoded file

- Installation/Konfiguration
  - Installation
  - Laufzeit-Konfiguration
  - Ressource-Typen
- Vordefinierte Konstanten
- Mailparse Funktionen
  - mailparse_determine_best_xfer_encoding — Gets the best way of encoding
  - mailparse_msg_create — Create a mime mail resource
  - mailparse_msg_extract_part — Extracts/decodes a message section
  - mailparse_msg_extract_part_file — Extracts/decodes a message section
  - mailparse_msg_extract_whole_part_file — Extracts a message section including headers without decoding the transfer encoding
  - mailparse_msg_free — Frees a MIME resource
  - mailparse_msg_get_part — Returns a handle on a given section in a mimemessage
  - mailparse_msg_get_part_data — Returns an associative array of info about the message
  - mailparse_msg_get_structure — Returns an array of mime section names in the supplied message
  - mailparse_msg_parse — Incrementally parse data into buffer
  - mailparse_msg_parse_file — Parses a file
  - mailparse_rfc822_parse_addresses — Parse RFC 822 compliant addresses
  - mailparse_stream_encode — Streams data from source file pointer, apply encoding and write to destfp
  - mailparse_uudecode_all — Scans the data from fp and extract each embedded uuencoded file

- IMAP — IMAP, POP3 and NNTP
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - IMAP Funktionen
  - IMAP\Connection — Die Klasse IMAP\Connection
- Mail
  - Installation/Konfiguration
  - Mail-Funktionen
- Mailparse
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Mailparse Funktionen

# Mathematische Erweiterungen

# BCMath Rechnen mit beliebiger Genauigkeit

# Einführung

Für beliebig genaue mathematische Operationen bietet PHP BCMath, das Zahlen von beliebiger Länge und Genauigkeit mit bis zu `2147483647` (oder `0x7FFFFFFF`) Dezimalstellen unterstützt, falls genügend Speicherplatz vorhanden ist, dargestellt als String.

Gültige (d. h. wohlgeformte) BCMath-Zahlen sind Strings, die auf den regulären Ausdruck `/^[+-]?[0-9]*(\.[0-9]*)?$/` passen.

Achtung

Die Übergabe von Werten vom Typ float an eine BCMath-Funktion, die einen String als Operanden erwartet, funktioniert aufgrund der Art, wie PHP float-Werte in Strings konvertiert, möglicherweise nicht wie erwartet, nämlich dass der String u. U. in exponentieller Notation vorliegt (was von BCMath nicht unterstützt wird), und dass der Dezimaltrenner vor PHP 8.0.0 von der Locale abhängt (wohingegen BCMath immer einen Dezimalpunkt erwartet).

    <?php
    $num1 = 0; // (string) 0 => '0'
    $num2 = -0.000005; // (string) -0.000005 => '-5.05E-6'
    echo bcadd($num1, $num2, 6); // => '0.000000'

    setlocale(LC_NUMERIC, 'de_DE'); // verwendet ein Dezimalkomma
    $num2 = 1.2; // (string) 1.2 => '1,2'
    echo bcsub($num1, $num2, 1); // => '0.0'
    ?>

# Installation/Konfiguration

## Inhaltsverzeichnis

- Installation
- Laufzeit-Konfiguration

## Installation

Diese Funktionen sind nur verfügbar, wenn PHP mit --enable-bcmath konfiguriert wurde.

Die Windowsversion von PHP enthält diese Erweiterung. Um diese Funktionen zu verwenden, müssen Sie keine zusätzlichen Erweiterungen aktivieren.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

BC-math-Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
bcmath.scale | "0" | `INI_ALL` |

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`bcmath.scale` int

  Anzahl der Dezimalstellen für alle bcmath-Funktionen. Siehe auch bcscale().

  > Hinweis: BcMath\Number ist von dieser Einstellung nicht betroffen.

# BC Math Funktionen

# bcadd

(PHP 4, PHP 5, PHP 7, PHP 8)

bcadd — Addition zweier Zahlen beliebiger Genauigkeit

### Beschreibung

function bcadd(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Addiert `num1` und `num2`.

### Parameter-Liste

`num1`

  Der linke Operand als Zeichenkette.

`num2`

  Der rechte Operand als Zeichenkette.

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Die Summe beider Operanden als Zeichenkette.

### Fehler/Exceptions

Diese Funktion löst in den folgenden Fällen einen ValueError aus:

- `num1` oder `num2` ist keine wohlgeformte numerische BCMath-Zeichenkette.
- `scale` liegt außerhalb des gültigen Bereichs.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `scale` ist jetzt nullbar.

### Beispiele

Beispiel #1 bcadd()-Beispiel

    <?php

    $a = '1.234';
    $b = '5';

    echo bcadd($a, $b);     // 6
    echo bcadd($a, $b, 4);  // 6.2340

    ?>

### Siehe auch

- bcsub() - Subtrahiert zwei Zahlen beliebiger Genauigkeit
- BcMath\Number::add() - Adds an arbitrary precision number

# bcceil

(PHP 8 >= 8.4.0)

bcceil — Round up arbitrary precision number

### Beschreibung

function bcceil(string `$num`): string

Returns the next highest integer value by rounding up `num` if necessary.

### Parameter-Liste

`num`
  The value to round.

### Rückgabewerte

Returns a numeric string representing `num` rounded up to the nearest integer.

### Fehler/Exceptions

This function throws a ValueError if `num` is not a well-formed BCMath numeric string.

### Beispiele

Beispiel #1 bcceil() example

    <?php
    var_dump(bcceil('4.3'));
    var_dump(bcceil('9.999'));
    var_dump(bcceil('-3.14'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "5"
    string(2) "10"
    string(2) "-3"

### Siehe auch

- bcfloor() - Round down arbitrary precision number
- bcround() - Round arbitrary precision number
- BcMath\Number::ceil() - Rounds up an arbitrary precision number

# bccomp

(PHP 4, PHP 5, PHP 7, PHP 8)

bccomp — Vergleich zweier Zahlen beliebiger Genauigkeit

### Beschreibung

function bccomp(string `$num1`, string `$num2`, ?int `$scale` = `null`): int

Vergleicht `num1` mit `num2` und gibt das Ergebnis als Integer-Wert zurück.

### Parameter-Liste

`num1`

  Der linke Operand als Zeichenkette.

`num2`

  Der rechte Operand als Zeichenkette.

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Gibt `0` zurück, wenn beide Operatoren gleich sind, `1`, wenn `num1` größer ist als `num2`, und andernfalls `-1`.

### Fehler/Exceptions

Diese Funktion löst in den folgenden Fällen einen ValueError aus:

- `num1` oder `num2` ist keine wohlgeformte numerische BCMath-Zeichenkette.
- `scale` liegt außerhalb des gültigen Bereichs.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `scale` ist jetzt nullbar.

### Beispiele

Beispiel #1 bccomp()-Beispiel

    <?php

    echo bccomp('1', '2') . "\n";   // -1
    echo bccomp('1.00001', '1', 3); // 0
    echo bccomp('1.00001', '1', 5); // 1

    ?>

### Siehe auch

- BcMath\Number::compare() - Compares two arbitrary precision numbers

# bcdiv

(PHP 4, PHP 5, PHP 7, PHP 8)

bcdiv — Division zweier Zahlen beliebiger Genauigkeit

### Beschreibung

function bcdiv(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Dividiert `num1` durch `num2`.

### Parameter-Liste

`num1`

  Der Dividend als Zeichenkette.

`num2`

  Der Divisor als Zeichenkette.

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Gibt das Ergebnis der Division als Zeichenkette zurück.

### Fehler/Exceptions

Diese Funktion löst in den folgenden Fällen einen ValueError aus:

- `num1` oder `num2` ist keine wohlgeformte numerische BCMath-Zeichenkette.
- `scale` liegt außerhalb des gültigen Bereichs.

Wenn `num2` `0` ist, löst diese Funktion eine DivisionByZeroError-Exception aus.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `scale` ist jetzt nullbar.
8.0.0 | Die Division durch `0` löst nun eine DivisionByZeroError-Exception aus, anstatt `null` zurückzugeben.

### Beispiele

Beispiel #1 bcdiv()-Beispiel

    <?php

    echo bcdiv('105', '6.55957', 3);  // 16.007

    ?>

### Siehe auch

- bcdivmod() - Get the quotient and modulus of an arbitrary precision number
- bcmod() - Modulo zweier Zahlen mit beliebiger Genauigkeit
- bcmul() - Multiplikation zweier Zahlen beliebiger Genauigkeit
- BcMath\Number::div() - Divides by an arbitrary precision number

# bcdivmod

(PHP 8 >= 8.4.0)

bcdivmod — Get the quotient and modulus of an arbitrary precision number

### Beschreibung

function bcdivmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): array

Get the quotient and remainder of dividing `num1` by `num2`.

### Parameter-Liste

`num1`

  Der Dividend als Zeichenkette.

`num2`

  Der Divisor als Zeichenkette.

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Returns an indexed array where the first element is the quotient as a string and the second element is the remainder as a string.

### Fehler/Exceptions

Diese Funktion löst in den folgenden Fällen einen ValueError aus:

- `num1` oder `num2` ist keine wohlgeformte numerische BCMath-Zeichenkette.
- `scale` liegt außerhalb des gültigen Bereichs.

Wenn `num2` `0` ist, löst diese Funktion eine DivisionByZeroError-Exception aus.

### Beispiele

Beispiel #1 bcdivmod() example

    <?php
    bcscale(0);

    [$quot, $rem] = bcdivmod('5',  '3');
    echo $quot; // 1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('5',  '-3');
    echo $quot; // -1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('-5',  '3');
    echo $quot; // -1
    echo $rem;  // -2

    [$quot, $rem] = bcdivmod('-5',  '-3');
    echo $quot; // 1
    echo $rem;  // -2
    ?>

Beispiel #2 bcdivmod() with decimals

    <?php
    [$quot, $rem] = bcdivmod('5.7', '1.3', 1);
    echo $quot; // 4
    echo $rem;  // 0.5
    ?>

### Siehe auch

- bcdiv() - Division zweier Zahlen beliebiger Genauigkeit
- bcmod() - Modulo zweier Zahlen mit beliebiger Genauigkeit
- BcMath\Number::divmod() - Gets the quotient and modulus of an arbitrary precision number

# bcfloor

(PHP 8 >= 8.4.0)

bcfloor — Round down arbitrary precision number

### Beschreibung

function bcfloor(string `$num`): string

Returns the next lowest integer value by rounding down `num` if necessary.

### Parameter-Liste

`num`
  The value to round.

### Rückgabewerte

Returns a numeric string representing `num` rounded down to the nearest integer.

### Fehler/Exceptions

This function throws a ValueError if `num` is not a well-formed BCMath numeric string.

### Beispiele

Beispiel #1 bcfloor() example

    <?php
    var_dump(bcfloor('4.3'));
    var_dump(bcfloor('9.999'));
    var_dump(bcfloor('-3.14'));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "4"
    string(1) "9"
    string(2) "-4"

### Siehe auch

- bcceil() - Round up arbitrary precision number
- bcround() - Round arbitrary precision number
- BcMath\Number::floor() - Rounds down an arbitrary precision number

# bcmod

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmod — Modulo zweier Zahlen mit beliebiger Genauigkeit

### Beschreibung

function bcmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Liefert den Rest der Division von `num1` durch `num2`. Das Ergnis hat dasselbe Vorzeichen wie `num1`.

### Parameter-Liste

`num1`

  Der linke Operand als Zeichenkette.

`num2`

  Der rechte Operand als Zeichenkette.

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Gibt den Modulo als Zeichenkette zurück.

### Fehler/Exceptions

Diese Funktion löst in den folgenden Fällen einen ValueError aus:

- `num1` oder `num2` ist keine wohlgeformte numerische BCMath-Zeichenkette.
- `scale` liegt außerhalb des gültigen Bereichs.

Wenn `num2` `0` ist, löst diese Funktion eine DivisionByZeroError-Exception aus.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `scale` ist jetzt nullbar.
8.0.0 | Die Division durch `0` löst nun eine DivisionByZeroError-Exception aus, anstatt `null` zurückzugeben.
7.2.0 | `num1` und `num2` werden nicht länger zu einer Ganzzahl abgeschnitten, so dass nun das Verhalten von bcmod() eher fmod() statt dem `%` Operator entspricht.
7.2.0 | Der Parameter `scale` wurde hinzugefügt.

### Beispiele

Beispiel #1 bcmod()-Beispiel

    <?php
    bcscale(0);
    echo bcmod( '5',  '3'); //  2
    echo bcmod( '5', '-3'); //  2
    echo bcmod('-5',  '3'); // -2
    echo bcmod('-5', '-3'); // -2
    ?>

Beispiel #2 bcmod() mit Dezimalzahlen

    <?php
    bcscale(1);
    echo bcmod('5.7', '1.3'); // 0.5 von PHP 7.2.0 an; 0 zuvor
    ?>

### Siehe auch

- bcdiv() - Division zweier Zahlen beliebiger Genauigkeit
- bcdivmod() - Get the quotient and modulus of an arbitrary precision number
- BcMath\Number::mod() - Gets the modulus of an arbitrary precision number

# bcmul

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmul — Multiplikation zweier Zahlen beliebiger Genauigkeit

### Beschreibung

function bcmul(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Multipliziert `num1` mit `num2`.

### Parameter-Liste

`num1`

  Der linke Operand als Zeichenkette.

`num2`

  Der rechte Operand als Zeichenkette.

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Gibt das Ergebnis als Zeichenkette zurück.

### Fehler/Exceptions

Diese Funktion löst in den folgenden Fällen einen ValueError aus:

- `num1` oder `num2` ist keine wohlgeformte numerische BCMath-Zeichenkette.
- `scale` liegt außerhalb des gültigen Bereichs.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `scale` ist jetzt nullbar.
7.3.0 | bcmul() liefert nun Zahlen mit den angeforderten Nachkommastellen zurück. Zuvor haben die zurückgelieferten Zahlen möglicherweise abschließende Dezimalnullen ausgelassen.

### Beispiele

Beispiel #1 bcmul()-Beispiel

    <?php
    echo bcmul('1.34747474747', '35', 3); // 47.161
    echo bcmul('2', '4'); // 8
    ?>

### Anmerkungen

> Hinweis:

> Vor PHP 7.3.0 kann bcmul() ein Ergebnis mit weniger Nachkommastellen zurückgeben, als der Parameter `scale` angibt. Dies geschieht nur, wenn das Ergebnis nicht die gesamte durch `scale` erlaubte Genauigkeit erfordert. Zum Beispiel:

> Beispiel #2 bcmul()-Nachkommastellen-Beispiel

>     <?php
>     echo bcmul('5', '2', 2);     // gibt "10" aus, nicht "10.00"
>     ?>

### Siehe auch

- bcdiv() - Division zweier Zahlen beliebiger Genauigkeit
- BcMath\Number::mul() - Multiplies an arbitrary precision number

# bcpow

(PHP 4, PHP 5, PHP 7, PHP 8)

bcpow — Potenz einer Zahl beliebiger Genauigkeit

### Beschreibung

function bcpow(string `$num`, string `$exponent`, ?int `$scale` = `null`): string

Potenziert `num` mit `exponent`.

### Parameter-Liste

`num`

  Die Basis als Zeichenkette.

`exponent`

  Der Exponent in Form einer Zeichenkette; muss ein Wert ohne Nachkommastelle sein. Der gültige Bereich des Exponenten ist plattformabhängig, ist allerdings mindestens `-2147483648` bis `2147483647`.

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Gibt das Ergebnis als Zeichenkette zurück.

### Fehler/Exceptions

In den folgenden Fällen löst diese Funktion einen ValueError aus:

- `num` oder `exponent` ist keine wohlgeformte numerische BCMath-Zeichenkette
- `exponent` hat eine Nachkommastelle
- `exponent` oder `scale` liegt außerhalb des gültigen Bereichs

Wenn `num` `0` ist und `exponent` ein negativer Wert ist, löst diese Funktion eine DivisionByZeroError-Exception aus.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Bei negativen Potenzen von `0` wurde bisher `0` zurückgegeben, nun wird eine DivisionByZeroError-Exception ausgelöst.
8.0.0 | Wenn `exponent` eine Nachkommastelle hat, wird nun ein ValueError ausgelöst, anstatt den Wert abzuschneiden.
7.3.0 | bcpow() gibt nun Zahlen mit den angeforderten Nachkommastellen zurück. Zuvor haben die zurückgegebenen Zahlen möglicherweise abschließende Dezimalnullen ausgelassen.

### Beispiele

Beispiel #1 bcpow()-Beispiel

    <?php

    echo bcpow('4.2', '3', 2); // 74.08

    ?>

### Anmerkungen

> Hinweis:

> Vor PHP 7.3.0 kann bcpow() ein Ergebnis mit weniger Nachkommastellen zurückgeben, als der Parameter `scale` angibt. Dies geschieht nur, wenn das Ergebnis nicht die gesamte durch `scale` erlaubte Genauigkeit erfordert. Zum Beispiel:

> Beispiel #2 bcpow() Genauigkeitsbeispiel

>     <?php
>     echo bcpow('5', '2', 2);     // gibt "25" aus, nicht "25.00"
>     ?>

### Siehe auch

- bcpowmod() - Potenz einer Zahl beliebiger Genauigkeit, vermindert um ein angegebenen Modulo
- bcsqrt() - Ermittelt die Quadratwurzel einer Zahl beliebiger Genauigkeit
- BcMath\Number::pow() - Raises an arbitrary precision number

# bcpowmod

(PHP 5, PHP 7, PHP 8)

bcpowmod — Potenz einer Zahl beliebiger Genauigkeit, vermindert um ein angegebenen Modulo

### Beschreibung

function bcpowmod(
string `$num`,
string `$exponent`,
string `$modulus`,
?int `$scale` = `null`
): string

Benutzen Sie diese schnelle Exponentialmethode, um `num` mit `exponent` unter Berücksichtigung des Modulo `modulus` zu potenzieren.

### Parameter-Liste

`num`

  Der Basis als ganzzahlige Zeichenkette (d. h. ohne Nachkommastellen).

`exponent`

  Der Exponent als nicht-negative, ganzzahlige Zeichenkette (d. h. ohne Nachkommastellen).

`modulus`

  Der Modulus als ganzzahlige Zeichenkette (d. h. ohne Nachkommastellen).

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Gibt das Ergebnis als Zeichenkette zurück.

### Fehler/Exceptions

In den folgenden Fällen löst diese Funktion einen ValueError aus:

- `num`, `exponent` oder `modulus` ist keine wohlgeformte numerische BCMath-Zeichenkette
- `num`, `exponent` oder `modulus` hat eine Nachkommastelle
- `exponent` ist ein negativer Wert
- `scale` liegt außerhalb des gültigen Bereichs

Wenn `modulus` `0` ist, löst diese Funktion eine DivisionByZeroError-Exception aus.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `scale` ist jetzt nullbar.
8.0.0 | Nun wird ein ValueError ausgelöst, anstatt `false` zurückzugeben, wenn `exponent` ein negativer Wert ist.
8.0.0 | Dividieren durch `0` löst nun eine DivisionByZeroError-Exception aus, anstatt `false` zurückzugeben.

### Beispiele

Die folgenden zwei Anweisungen sind funktional identisch. Die bcpowmod()-Version ist allerdings schneller und akzeptiert größere Parameter.

    <?php
    $a = bcpowmod($x, $y, $mod);

    $b = bcmod(bcpow($x, $y), $mod);

    // $a und $b entsprechen einander.

    ?>

### Anmerkungen

> Hinweis:

> Da diese Methode mit der Modulo-Operation arbeitet, können nicht-positive Ganzzahlen zu unerwarteten Ergebnissen führen.

### Siehe auch

- bcpow() - Potenz einer Zahl beliebiger Genauigkeit
- bcmod() - Modulo zweier Zahlen mit beliebiger Genauigkeit
- BcMath\Number::powmod() - Raises an arbitrary precision number, reduced by a specified modulus

# bcround

(PHP 8 >= 8.4.0)

bcround — Round arbitrary precision number

### Beschreibung

function bcround(string `$num`, int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): string

Returns the rounded value of `num` to specified `precision` (number of digits after the decimal point). `precision` can also be negative or zero (default).

### Parameter-Liste

`num`

  Der zu rundende Wert.

`precision`

  Auf wie viele Nachkommastellen gerundet werden soll.

  Ist die Genauigkeit `precision` positiv, wird `num` auf `precision` signifikante Stellen nach dem Dezimalpunkt gerundet.

  Ist die Genauigkeit `precision` negativ, wird `num` auf `precision` signifikante Stellen vor dem Dezimalpunkt gerundet, d. h. auf das nächste Vielfache von `pow(10, -precision)`, z. B. wird `num` mit einer `precision` von -1 auf Zehner gerundet, mit einer `precision` von -2 auf Hunderter usw.

`mode`
  Specifies the rounding mode. For more information about modes, see RoundingMode.

### Rückgabewerte

Returns a numeric string representing `num` rounded to the given precision.

### Fehler/Exceptions

This function throws a ValueError in the following cases:

- `num` is not a well-formed BCMath numeric string.
- An invalid `mode` is specified.

### Beispiele

Beispiel #1 bcround() examples

    <?php
    var_dump(bcround('3.4'));
    var_dump(bcround('3.5'));
    var_dump(bcround('3.6'));
    var_dump(bcround('3.6', 0));
    var_dump(bcround('5.045', 2));
    var_dump(bcround('5.055', 2));
    var_dump(bcround('345', -2));
    var_dump(bcround('345', -3));
    var_dump(bcround('678', -2));
    var_dump(bcround('678', -3));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(1) "3"
    string(1) "4"
    string(1) "4"
    string(1) "4"
    string(4) "5.05"
    string(4) "5.06"
    string(3) "300"
    string(1) "0"
    string(3) "700"
    string(4) "1000"

Beispiel #2 Example of using bcround() with different `precision` values

    <?php
    $number = '123.45';

    var_dump(bcround($number, 3));
    var_dump(bcround($number, 2));
    var_dump(bcround($number, 1));
    var_dump(bcround($number, 0));
    var_dump(bcround($number, -1));
    var_dump(bcround($number, -2));
    var_dump(bcround($number, -3));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(7) "123.450"
    string(6) "123.45"
    string(5) "123.5"
    string(3) "123"
    string(3) "120"
    string(3) "100"
    string(1) "0"

Beispiel #3 Example of using bcround() with different `mode` values

    <?php
    echo 'Rounding modes with 9.5' . PHP_EOL;
    var_dump(bcround('9.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('9.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('9.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('9.5', 0, RoundingMode::PositiveInfinity));

    echo PHP_EOL;
    echo 'Rounding modes with 8.5' . PHP_EOL;
    var_dump(bcround('8.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('8.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('8.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('8.5', 0, RoundingMode::PositiveInfinity));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Rounding modes with 9.5
    string(2) "10"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(2) "10"

    Rounding modes with 8.5
    string(1) "9"
    string(1) "8"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"

Beispiel #4 Example of using bcround() with different `mode` values when specifying `precision`

    <?php
    echo 'Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfAwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfAwayFromZero));

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfTowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfTowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfTowardsZero));

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfEven with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfEven));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfEven));

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfOdd with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfOdd));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfOdd));

    echo PHP_EOL;
    echo 'Using RoundingMode::TowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::TowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::TowardsZero));

    echo PHP_EOL;
    echo 'Using RoundingMode::AwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::AwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::AwayFromZero));

    echo PHP_EOL;
    echo 'Using RoundingMode::NegativeInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::NegativeInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::NegativeInfinity));

    echo PHP_EOL;
    echo 'Using RoundingMode::PositiveInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::PositiveInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::PositiveInfinity));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision
    string(3) "1.6"
    string(4) "-1.6"

    Using RoundingMode::HalfTowardsZero with 1 decimal digit precision
    string(3) "1.5"
    string(4) "-1.5"

    Using RoundingMode::HalfEven with 1 decimal digit precision
    string(3) "1.6"
    string(4) "-1.6"

    Using RoundingMode::HalfOdd with 1 decimal digit precision
    string(3) "1.5"
    string(4) "-1.5"

    Using RoundingMode::TowardsZero with 1 decimal digit precision
    string(3) "1.5"
    string(4) "-1.5"

    Using RoundingMode::AwayFromZero with 1 decimal digit precision
    string(3) "1.6"
    string(4) "-1.6"

    Using RoundingMode::NegativeInfinity with 1 decimal digit precision
    string(3) "1.5"
    string(4) "-1.6"

    Using RoundingMode::PositiveInfinity with 1 decimal digit precision
    string(3) "1.6"
    string(4) "-1.5"

### Siehe auch

- bcceil() - Round up arbitrary precision number
- bcfloor() - Round down arbitrary precision number
- BcMath\Number::round() - Rounds an arbitrary precision number

# bcscale

(PHP 4, PHP 5, PHP 7, PHP 8)

bcscale — Setzt oder holt die Genauigkeit aller BCmath-Funktionen

### Beschreibung

function bcscale(int `$scale`): int

Diese Funktionen legt die Standard-Genauigkeit aller im Folgenden aufgerufenden BCmath-Funktionen fest, die nicht explizit die Genauigkeit angeben.

function bcscale(null `$scale` = `null`): int

Holt die aktuelle Genauigkeit.

### Parameter-Liste

`scale`

  Die Genauigkeitsangabe.

### Rückgabewerte

Gibt die alte Genauigkeit zurück, wenn als Setter verwendet. Andernfalls wird die aktuelle Genauigkeit zurückgeliefert.

### Fehler/Exceptions

Diese Funktion löst einen ValueError aus, wenn `scale` außerhalb des gültigen Bereichs liegt.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `scale` ist jetzt nullbar.
7.3.0 | bcscale() kann nun verwendet werden, um die aktuelle Genauigkeit zu ermitteln; wird es als Setter verwendet, gibt es nun die vorherige Genauigkeit zurück. Zuvor war `scale` obligatorisch, und bscale() gab immer `true` zurück.

### Beispiele

Beispiel #1 bcscale()-Beispiel

    <?php

    // Standard-Genauigkeit: 3
    bcscale(3);
    echo bcdiv('105', '6.55957'); // 16.007

    // Die selbe Operation ohne Verwendung von bcscale()
    echo bcdiv('105', '6.55957', 3); // 16.007

    ?>

# bcsqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsqrt — Ermittelt die Quadratwurzel einer Zahl beliebiger Genauigkeit

### Beschreibung

function bcsqrt(string `$num`, ?int `$scale` = `null`): string

Liefert die Quadratwurzel von `num`.

### Parameter-Liste

`num`

  Der Operand als wohlgeformte numerische BCMath-Zeichenkette.

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Gibt die Quadratwurzel als wohlgeformte numerische BCMath-Zeichenkette zurück.

### Fehler/Exceptions

In den folgenden Fällen löst diese Funktion einen ValueError aus:

- `num` ist kein wohlgeformter numerischer BCMath-String
- `num` ist kleiner als `0`
- `scale` liegt außerhalb des gültigen Bereichs

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | Wenn `num` kein wohlgeformter numerischer BCMath-String ist oder kleiner als `0`, wird ein ValueError ausgelöst; zuvor wurde stattdessen ein `E_WARNING` ausgelöst.
8.0.0 | `scale` muss nun zwischen `0` und `2147483647` liegen; zuvor wurden negative Werte stillschweigend als `0` behandelt.
8.0.0 | `scale` ist jetzt nullbar.

### Beispiele

Beispiel #1 bcsqrt()-Beispiel

    <?php

    echo bcsqrt('2', 3); // 1.414

    ?>

### Siehe auch

- bcpow() - Potenz einer Zahl beliebiger Genauigkeit
- BcMath\Number::sqrt() - Gets the square root of an arbitrary precision number

# bcsub

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsub — Subtrahiert zwei Zahlen beliebiger Genauigkeit

### Beschreibung

function bcsub(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

Subtrahiert `num2` von `num1`.

### Parameter-Liste

`num1`

  Der linke Operand als Zeichenkette.

`num2`

  Der rechte Operand als Zeichenkette.

`scale`
  Dieser Parameter wird verwendet, um die Anzahl der Nachkommastellen im Ergebnis festzulegen. Falls `null`, wird die mit bcscale() definierte Standard-Genauigkeit verwendet oder auf den Wert der INI-Direktive `bcmath.scale` zurückgegriffen.

### Rückgabewerte

Das Ergebnis der Subtraktion als Zeichenkette.

### Fehler/Exceptions

Diese Funktion löst in den folgenden Fällen einen ValueError aus:

- `num1` oder `num2` ist keine wohlgeformte numerische BCMath-Zeichenkette.
- `scale` liegt außerhalb des gültigen Bereichs.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `scale` ist nun nullable (akzeptiert den `null`-Wert).

### Beispiele

Beispiel #1 bcsub()-Beispiel

    <?php

    $a = '1.234';
    $b = '5';

    echo bcsub($a, $b);     // -3
    echo bcsub($a, $b, 4);  // -3.7660

    ?>

### Siehe auch

- bcadd() - Addition zweier Zahlen beliebiger Genauigkeit
- BcMath\Number::sub() - Subtracts an arbitrary precision number

## Inhaltsverzeichnis

- bcadd — Addition zweier Zahlen beliebiger Genauigkeit
- bcceil — Round up arbitrary precision number
- bccomp — Vergleich zweier Zahlen beliebiger Genauigkeit
- bcdiv — Division zweier Zahlen beliebiger Genauigkeit
- bcdivmod — Get the quotient and modulus of an arbitrary precision number
- bcfloor — Round down arbitrary precision number
- bcmod — Modulo zweier Zahlen mit beliebiger Genauigkeit
- bcmul — Multiplikation zweier Zahlen beliebiger Genauigkeit
- bcpow — Potenz einer Zahl beliebiger Genauigkeit
- bcpowmod — Potenz einer Zahl beliebiger Genauigkeit, vermindert um ein angegebenen Modulo
- bcround — Round arbitrary precision number
- bcscale — Setzt oder holt die Genauigkeit aller BCmath-Funktionen
- bcsqrt — Ermittelt die Quadratwurzel einer Zahl beliebiger Genauigkeit
- bcsub — Subtrahiert zwei Zahlen beliebiger Genauigkeit

# The BcMath\Number class

(PHP 8 >= 8.4.0)

## Einführung

A class for an arbitrary precision number. These objects support overloaded arithmetic and comparison operators.

> Hinweis: This class is not affected by the bcmath.scale INI directive set in php.ini.

> Hinweis: The behavior of an overloaded operator is the same as specifying `null` for the `scale` parameter on the corresponding method.

## Klassenbeschreibung

namespace BcMath;
final readonly class Number implements Stringable {
/* Eigenschaften */
public string $value;
public int $scale;
/* Methoden */
public function __construct(string|int `$num`)
public function add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function ceil(): BcMath\Number
public function compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int
public function div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array
public function floor(): BcMath\Number
public function mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number
public function powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number
public function round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number
public function __serialize(): array
public function sqrt(?int `$scale` = `null`): BcMath\Number
public function sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function __toString(): string
public function __unserialize(array `$data`): void
}

## Eigenschaften

value
  A string representation of an arbitrary precision number.
scale
  The scale value currently set on the object. For objects resulting from calculations, this value is automatically computed and set, unless the `scale` parameter was set in the calculation method.

# BcMath\Number::add

(PHP 8 >= 8.4.0)

BcMath\Number::add — Adds an arbitrary precision number

### Beschreibung

public function BcMath\Number::add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Adds $this and `num`.

### Parameter-Liste

`num`
  The value to add.
`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### Rückgabewerte

Returns the result of addition as a new BcMath\Number object.

When the BcMath\Number::scale of the result object is automatically set, the greater BcMath\Number::scale of the two numbers used for addition is used.

That is, if the BcMath\Number::scales of two values are `2` and `5` respectively, the BcMath\Number::scale of the result will be `5`.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- `num` is string and not a well-formed BCMath numeric string
- `scale` is outside the valid range

### Beispiele

Beispiel #1 BcMath\Number::add() example when `scale` is not specified

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'));
    $ret2 = $number->add('-3.456');
    $ret3 = $number->add(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(7) "3.57967"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(6) "-2.222"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.234"
      ["scale"]=>
      int(3)
    }

Beispiel #2 BcMath\Number::add() example of explicitly specifying `scale`

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->add('-3.456', 10);
    $ret3 = $number->add(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "3.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-2.2220000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### Siehe auch

- bcadd() - Addition zweier Zahlen beliebiger Genauigkeit
- BcMath\Number::sub() - Subtracts an arbitrary precision number

# BcMath\Number::ceil

(PHP 8 >= 8.4.0)

BcMath\Number::ceil — Rounds up an arbitrary precision number

### Beschreibung

public function BcMath\Number::ceil(): BcMath\Number

Returns the next highest integer value by rounding up $this if necessary.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the result as a new BcMath\Number object. The BcMath\Number::scale of the result is always `0`.

### Beispiele

Beispiel #1 BcMath\Number::ceil() example

    <?php
    $num1 = new BcMath\Number('4.3')->ceil();
    $num2 = new BcMath\Number('9.999')->ceil();
    $num3 = new BcMath\Number('-3.14')->ceil();

    var_dump($num1, $num2, $num3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "5"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }

### Siehe auch

- bcceil() - Round up arbitrary precision number
- BcMath\Number::floor() - Rounds down an arbitrary precision number
- BcMath\Number::round() - Rounds an arbitrary precision number

# BcMath\Number::compare

(PHP 8 >= 8.4.0)

BcMath\Number::compare — Compares two arbitrary precision numbers

### Beschreibung

public function BcMath\Number::compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int

Compare two arbitrary precision numbers. This method behaves similar to the spaceship operator.

### Parameter-Liste

`num`
  The value to be compared to.
`scale`
  Specify the `scale` to use for comparison. If `null`, all digits are used in the comparison.

### Rückgabewerte

Returns `0` if the two numbers are equal, `1` if $this is greater than `num`, `-1` otherwise.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- `num` is string and not a well-formed BCMath numeric string
- `scale` is outside the valid range

### Beispiele

Beispiel #1 BcMath\Number::compare() example when `scale` is not specified

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.234')),
        $number->compare('1.23400'),
        $number->compare('1.23401'),
        $number->compare(1),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    int(0)
    int(-1)
    int(1)

Beispiel #2 BcMath\Number::compare() example of explicitly specifying `scale`

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.299'), 1),
        $number->compare('1.24', 2),
        $number->compare('1.22', 2),
        $number->compare(1, 0),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(0)
    int(-1)
    int(1)
    int(0)

### Siehe auch

- bccomp() - Vergleich zweier Zahlen beliebiger Genauigkeit

# BcMath\Number::__construct

(PHP 8 >= 8.4.0)

BcMath\Number::__construct — Creates a BcMath\Number object

### Beschreibung

public function BcMath\Number::__construct(string|int `$num`)

Creates a BcMath\Number object from an int or string value.

### Parameter-Liste

`num`
  An int or string value. If `num` is a int, the BcMath\Number::scale is always set to `0`. If `num` is a string, it must be a valid number, and the BcMath\Number::scale is automatically set by parsing the string.

### Fehler/Exceptions

This method throws a ValueError if `num` is string and not a well-formed BCMath numeric string.

### Beispiele

Beispiel #1 BcMath\Number::__construct() example

    <?php
    $num1 = new BcMath\Number(100);
    $num2 = new BcMath\Number('-200');
    $num3 = new BcMath\Number('300.00');

    var_dump($num1, $num2, $num3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "-200"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "300.00"
      ["scale"]=>
      int(2)
    }

### Siehe auch

- BcMath\Number::__serialize() - Serializes a BcMath\Number object
- BcMath\Number::__unserialize() - Deserializes a data parameter into a BcMath\Number object

# BcMath\Number::div

(PHP 8 >= 8.4.0)

BcMath\Number::div — Divides by an arbitrary precision number

### Beschreibung

public function BcMath\Number::div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Divides $this by `num`.

### Parameter-Liste

`num`
  The divisor.
`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### Rückgabewerte

Returns the result of division as a new BcMath\Number object.

When the BcMath\Number::scale of the result object is automatically set, the BcMath\Number::scale of the dividend is used. However, in cases such as indivisible division, the BcMath\Number::scale of the result is expanded. Expansion is done only as needed, up to a maximum of `+10`.

That is, if the BcMath\Number::scale of the dividend is `5`, the BcMath\Number::scale of the result is between `5` and `15`.

Even in indivisible calculations, the BcMath\Number::scale will not always be `+10`. A `0` at the end of the result is considered not to need expansion, so the BcMath\Number::scale is reduced by that amount. The BcMath\Number::scale will never be less than the BcMath\Number::scale before expansion. See also the code example.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- `num` is string and not a well-formed BCMath numeric string
- `scale` is outside the valid range
- BcMath\Number::scale of the result object is outside the valid range

This method throws a DivisionByZeroError exception if `num` is `0`.

### Beispiele

Beispiel #1 BcMath\Number::div() example when `scale` is not specified

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'));
    $ret2 = $number->div('-3');
    $ret3 = $number->div(32);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "0.001"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(16) "-0.0006666666666"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(9) "0.0000625"
      ["scale"]=>
      int(7)
    }

Beispiel #2 BcMath\Number::div() example of explicitly specifying `scale`

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'), 15);
    $ret2 = $number->div('-3', 5);
    $ret3 = $number->div(32, 2);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(17) "0.001000000000000"
      ["scale"]=>
      int(15)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(8) "-0.00066"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "0.00"
      ["scale"]=>
      int(2)
    }

Beispiel #3 BcMath\Number::div() example of expansioning BcMath\Number::scale of result object

    <?php
    var_dump(
        new BcMath\Number('0.001')->div('10001'),
        new BcMath\Number('0.001')->div('10001', 13),
        new BcMath\Number('0.001')->div('100000000000001'),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.00000009999"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(15) "0.0000000999900"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }

### Siehe auch

- bcdiv() - Division zweier Zahlen beliebiger Genauigkeit
- BcMath\Number::divmod() - Gets the quotient and modulus of an arbitrary precision number
- BcMath\Number::mod() - Gets the modulus of an arbitrary precision number
- BcMath\Number::sqrt() - Gets the square root of an arbitrary precision number
- BcMath\Number::pow() - Raises an arbitrary precision number
- BcMath\Number::mul() - Multiplies an arbitrary precision number

# BcMath\Number::divmod

(PHP 8 >= 8.4.0)

BcMath\Number::divmod — Gets the quotient and modulus of an arbitrary precision number

### Beschreibung

public function BcMath\Number::divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array

Gets the quotient and remainder of dividing $this by `num`.

### Parameter-Liste

`num`
  The divisor.
`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### Rückgabewerte

Returns an indexed array where the first element is the quotient as a new BcMath\Number object and the second element is the remainder as a new BcMath\Number object.

The quotient is always an integer value, so BcMath\Number::scale of the quotient will always be `0`, regardless of whether explicitly specify `scale`.

If `scale` is explicitly specified, BcMath\Number::scale of the remainder will be the specified value. When the BcMath\Number::scale of the result's remainder object is automatically set, the greater BcMath\Number::scale of the two numbers used for modulus operation is used.

That is, if the BcMath\Number::scales of two values are `2` and `5` respectively, the BcMath\Number::scale of the remainder will be `5`.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- `num` is string and not a well-formed BCMath numeric string
- `scale` is outside the valid range

This method throws a DivisionByZeroError exception if `num` is `0`.

### Beispiele

Beispiel #1 BcMath\Number::divmod() example when `scale` is not specified

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'));
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3');
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3);
    var_dump($quot, $rem);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "1.34"
      ["scale"]=>
      int(2)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

Beispiel #2 BcMath\Number::divmod() example of explicitly specifying `scale`

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'), 1);
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3', 4);
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3, 5);
    var_dump($quot, $rem);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.3"
      ["scale"]=>
      int(1)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(6) "0.0000"
      ["scale"]=>
      int(4)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(7) "1.00000"
      ["scale"]=>
      int(5)
    }

### Siehe auch

- bcdivmod() - Get the quotient and modulus of an arbitrary precision number
- BcMath\Number::div() - Divides by an arbitrary precision number
- BcMath\Number::mod() - Gets the modulus of an arbitrary precision number

# BcMath\Number::floor

(PHP 8 >= 8.4.0)

BcMath\Number::floor — Rounds down an arbitrary precision number

### Beschreibung

public function BcMath\Number::floor(): BcMath\Number

Returns the next highest integer value by rounding down $this if necessary.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the result as a new BcMath\Number object. The BcMath\Number::scale of the result is always `0`.

### Beispiele

Beispiel #1 BcMath\Number::floor() example

    <?php
    $num1 = new BcMath\Number('4.3')->floor();
    $num2 = new BcMath\Number('9.999')->floor();
    $num3 = new BcMath\Number('-3.14')->floor();

    var_dump($num1, $num2, $num3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-4"
      ["scale"]=>
      int(0)
    }

### Siehe auch

- bcfloor() - Round down arbitrary precision number
- BcMath\Number::ceil() - Rounds up an arbitrary precision number
- BcMath\Number::round() - Rounds an arbitrary precision number

# BcMath\Number::mod

(PHP 8 >= 8.4.0)

BcMath\Number::mod — Gets the modulus of an arbitrary precision number

### Beschreibung

public function BcMath\Number::mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Gets the remainder of dividing $this by `num`. Unless `num` is `0`, the result has the same sign as $this.

### Parameter-Liste

`num`
  The divisor.
`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### Rückgabewerte

Returns the modulus as a new BcMath\Number object.

When the BcMath\Number::scale of the result object is automatically set, the greater BcMath\Number::scale of the two numbers used for modulus operation is used.

That is, if the BcMath\Number::scales of two values are `2` and `5` respectively, the BcMath\Number::scale of the result will be `5`.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- `num` is string and not a well-formed BCMath numeric string
- `scale` is outside the valid range

This method throws a DivisionByZeroError exception if `num` is `0`.

### Beispiele

Beispiel #1 BcMath\Number::mod() example when `scale` is not specified

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'));
    $ret2 = $number->mod('8.3');
    $ret3 = $number->mod(-5);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "1.64"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "3.3"
      ["scale"]=>
      int(1)
    }

Beispiel #2 BcMath\Number::mod() example of explicitly specifying `scale`

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'), 1);
    $ret2 = $number->mod('8.3', 3);
    $ret3 = $number->mod(-5, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }

### Siehe auch

- bcmod() - Modulo zweier Zahlen mit beliebiger Genauigkeit
- BcMath\Number::div() - Divides by an arbitrary precision number
- BcMath\Number::divmod() - Gets the quotient and modulus of an arbitrary precision number
- BcMath\Number::powmod() - Raises an arbitrary precision number, reduced by a specified modulus

# BcMath\Number::mul

(PHP 8 >= 8.4.0)

BcMath\Number::mul — Multiplies an arbitrary precision number

### Beschreibung

public function BcMath\Number::mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Multiplies $this by `num`.

### Parameter-Liste

`num`
  The multiplier.
`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### Rückgabewerte

Returns the result of multiplication as a new BcMath\Number object.

When the BcMath\Number::scale of the result object is automatically set, the sum of the BcMath\Number::scales of the two values used for multiplication is used.

That is, if the BcMath\Number::scales of two values are `2` and `5` respectively, the BcMath\Number::scale of the result will be `7`.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- `num` is string and not a well-formed BCMath numeric string
- `scale` is outside the valid range
- BcMath\Number::scale of the result object is outside the valid range

### Beispiele

Beispiel #1 BcMath\Number::mul() example when `scale` is not specified

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'));
    $ret2 = $number->mul('-3.4');
    $ret3 = $number->mul(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "2.8944704"
      ["scale"]=>
      int(7)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "-4.1956"
      ["scale"]=>
      int(4)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.638"
      ["scale"]=>
      int(3)
    }

Beispiel #2 BcMath\Number::mul() example of explicitly specifying `scale`

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'), 1);
    $ret2 = $number->mul('-3.4', 10);
    $ret3 = $number->mul(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.8"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-4.1956000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### Siehe auch

- bcmul() - Multiplikation zweier Zahlen beliebiger Genauigkeit
- BcMath\Number::div() - Divides by an arbitrary precision number
- BcMath\Number::pow() - Raises an arbitrary precision number
- BcMath\Number::powmod() - Raises an arbitrary precision number, reduced by a specified modulus

# BcMath\Number::pow

(PHP 8 >= 8.4.0)

BcMath\Number::pow — Raises an arbitrary precision number

### Beschreibung

public function BcMath\Number::pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number

Raises $this to the `exponent` power.

### Parameter-Liste

`exponent`
  The exponent. Must be a value with no fractional part. The valid range of the `exponent` is platform specific, but it is at least `-2147483648` to `2147483647`.
`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### Rückgabewerte

Returns the result of power as a new BcMath\Number object.

When the BcMath\Number::scale of the result object is automatically set, depending on the value of `exponent`, the BcMath\Number::scale of result will be as follows:

`exponent` | BcMath\Number::scale of result
--- | ---
positive | (BcMath\Number::scale of power base) * (`exponent`'s value)
`0` | `0`
negative | Between (BcMath\Number::scale of power base) and (BcMath\Number::scale of power base + `10`)

If an indivisible division occurs due to a negative `exponent`, the BcMath\Number::scale of the result is expanded. Expansion is done only as needed, up to a maximum of `+10`. This behavior is the same as BcMath\Number::div(), so please see that for details.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- `exponent` is string and not a well-formed BCMath numeric string
- `exponent` has a fractional part
- `exponent` or `scale` is outside the valid range
- BcMath\Number::scale of the result object is outside the valid range

This method throws a DivisionByZeroError exception if $this's value is `0` and `exponent` is a negative value.

### Beispiele

Beispiel #1 BcMath\Number::pow() example when `scale` is not specified

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'));
    $ret2 = $number->pow('-1');
    $ret3 = $number->pow(0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "243.00000"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.33333333333"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

Beispiel #2 BcMath\Number::pow() example of explicitly specifying `scale`

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'), 0);
    $ret2 = $number->pow('-1', 2);
    $ret3 = $number->pow(0, 10);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "243"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "0.33"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(12) "1.0000000000"
      ["scale"]=>
      int(10)
    }

### Siehe auch

- bcpow() - Potenz einer Zahl beliebiger Genauigkeit
- BcMath\Number::powmod() - Raises an arbitrary precision number, reduced by a specified modulus
- BcMath\Number::mul() - Multiplies an arbitrary precision number
- BcMath\Number::sqrt() - Gets the square root of an arbitrary precision number
- BcMath\Number::div() - Divides by an arbitrary precision number

# BcMath\Number::powmod

(PHP 8 >= 8.4.0)

BcMath\Number::powmod — Raises an arbitrary precision number, reduced by a specified modulus

### Beschreibung

public function BcMath\Number::powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number

Use the fast-exponentiation method to raise $this to the power `exponent` with respect to the modulus `modulus`.

### Parameter-Liste

`exponent`
  The exponent, as an non-negative and integral (i.e. the scale has to be zero).
`modulus`
  The modulus, as an integral (i.e. the scale has to be zero).
`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### Rückgabewerte

Returns the result as a new BcMath\Number object.

When the BcMath\Number::scale of the result object is automatically set, the BcMath\Number::scale of the result object will always be `0`.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- `exponent` or `modulus` is string and not a well-formed BCMath numeric string
- $this, `exponent` or `modulus` has a fractional part
- `exponent` is a negative value
- `scale` is outside the valid range

This method throws a DivisionByZeroError exception if `modulus` is `0`.

### Beispiele

Beispiel #1 BcMath\Number::powmod() example when `scale` is not specified

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('8')->powmod('2', -3),
        new BcMath\Number('-8')->powmod(5, 7),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(2) "-1"
      ["scale"]=>
      int(0)
    }

Beispiel #2 BcMath\Number::powmod() example of explicitly specifying `scale`

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5, 1),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5, 2),
        new BcMath\Number('8')->powmod('2', -3, 3),
        new BcMath\Number('-8')->powmod(5, 7, 4),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "-2.00"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "1.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(7) "-1.0000"
      ["scale"]=>
      int(4)
    }

### Siehe auch

- bcpowmod() - Potenz einer Zahl beliebiger Genauigkeit, vermindert um ein angegebenen Modulo
- BcMath\Number::pow() - Raises an arbitrary precision number
- BcMath\Number::mod() - Gets the modulus of an arbitrary precision number

# BcMath\Number::round

(PHP 8 >= 8.4.0)

BcMath\Number::round — Rounds an arbitrary precision number

### Beschreibung

public function BcMath\Number::round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number

Returns the rounded value of $this to specified `precision` (number of digits after the decimal point). `precision` can also be negative or zero (default).

### Parameter-Liste

`precision`

  Auf wie viele Nachkommastellen gerundet werden soll.

  Ist die Genauigkeit `precision` positiv, wird `num` auf `precision` signifikante Stellen nach dem Dezimalpunkt gerundet.

  Ist die Genauigkeit `precision` negativ, wird `num` auf `precision` signifikante Stellen vor dem Dezimalpunkt gerundet, d. h. auf das nächste Vielfache von `pow(10, -precision)`, z. B. wird `num` mit einer `precision` von -1 auf Zehner gerundet, mit einer `precision` von -2 auf Hunderter usw.

`mode`
  Specifies the rounding mode. For more information about modes, see RoundingMode.

### Rückgabewerte

Returns the result as a new BcMath\Number object.

### Fehler/Exceptions

This method throws a ValueError if an invalid `mode` is specified.

### Beispiele

Beispiel #1 BcMath\Number::round() example

    <?php
    var_dump(
        new BcMath\Number('3.4')->round(),
        new BcMath\Number('3.5')->round(),
        new BcMath\Number('3.6')->round(),
        new BcMath\Number('3.6')->round(0),
        new BcMath\Number('5.045')->round(2),
        new BcMath\Number('5.055')->round(2),
        new BcMath\Number('345')->round(-2),
        new BcMath\Number('345')->round(-3),
        new BcMath\Number('678')->round(-2),
        new BcMath\Number('678')->round(-3),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "5.05"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "5.06"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(3) "300"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(3) "700"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "1000"
      ["scale"]=>
      int(0)
    }

Beispiel #2 Example of using BcMath\Number::round() with different `precision` values

    <?php
    $number = new BcMath\Number('123.45');

    var_dump(
        $number->round(3),
        $number->round(2),
        $number->round(1),
        $number->round(0),
        $number->round(-1),
        $number->round(-2),
        $number->round(-3),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "123.450"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "123.45"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "123.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "123"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(3) "120"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }

Beispiel #3 Example of using BcMath\Number::round() with different `mode` values

    <?php
    echo 'Rounding modes with 9.5' . PHP_EOL;
    $number = new BcMath\Number('9.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );

    echo PHP_EOL;
    echo 'Rounding modes with 8.5' . PHP_EOL;
    $number = new BcMath\Number('8.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Rounding modes with 9.5
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#17 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }

    Rounding modes with 8.5
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }

Beispiel #4 Example of using BcMath\Number::round() with different `mode` values when specifying `precision`

    <?php
    $positive = new BcMath\Number('1.55');
    $negative = new BcMath\Number('-1.55');

    echo 'Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfAwayFromZero),
        $negative->round(1, RoundingMode::HalfAwayFromZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfTowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfTowardsZero),
        $negative->round(1, RoundingMode::HalfTowardsZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfEven with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfEven),
        $negative->round(1, RoundingMode::HalfEven),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfOdd with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfOdd),
        $negative->round(1, RoundingMode::HalfOdd),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::TowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::TowardsZero),
        $negative->round(1, RoundingMode::TowardsZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::AwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::AwayFromZero),
        $negative->round(1, RoundingMode::AwayFromZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::NegativeInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::NegativeInfinity),
        $negative->round(1, RoundingMode::NegativeInfinity),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::PositiveInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::PositiveInfinity),
        $negative->round(1, RoundingMode::PositiveInfinity),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::HalfTowardsZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::HalfEven with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::HalfOdd with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::TowardsZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::AwayFromZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::NegativeInfinity with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::PositiveInfinity with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#12 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

### Siehe auch

- bcround() - Round arbitrary precision number
- BcMath\Number::ceil() - Rounds up an arbitrary precision number
- BcMath\Number::floor() - Rounds down an arbitrary precision number

# BcMath\Number::__serialize

(PHP 8 >= 8.4.0)

BcMath\Number::__serialize — Serializes a BcMath\Number object

### Beschreibung

public function BcMath\Number::__serialize(): array

Serializes $this.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Siehe auch

- BcMath\Number::__construct() - Creates a BcMath\Number object
- BcMath\Number::__unserialize() - Deserializes a data parameter into a BcMath\Number object

# BcMath\Number::sqrt

(PHP 8 >= 8.4.0)

BcMath\Number::sqrt — Gets the square root of an arbitrary precision number

### Beschreibung

public function BcMath\Number::sqrt(?int `$scale` = `null`): BcMath\Number

Return the square root of $this.

### Parameter-Liste

`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### Rückgabewerte

Returns the square root as a new BcMath\Number object.

When the BcMath\Number::scale of the result object is automatically set, the BcMath\Number::scale of $this is used. However, in cases such as indivisible division, the BcMath\Number::scale of the result is expanded. Expansion is done only as needed, up to a maximum of `+10`. This behavior is the same as BcMath\Number::div(), so please see that for details.

That is, if the BcMath\Number::scale of $this is `5`, the BcMath\Number::scale of the result is between `5` and `15`.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- $this is a negative value
- `scale` is outside the valid range
- BcMath\Number::scale of the result object is outside the valid range

### Beispiele

Beispiel #1 BcMath\Number::sqrt() example

    <?php
    var_dump(
        new BcMath\Number('2')->sqrt(),
        new BcMath\Number('2')->sqrt(3),
        new BcMath\Number('4')->sqrt(),
        new BcMath\Number('4')->sqrt(3),
    );
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "1.4142135623"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "1.414"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(5) "2.000"
      ["scale"]=>
      int(3)
    }

### Siehe auch

- bcsqrt() - Ermittelt die Quadratwurzel einer Zahl beliebiger Genauigkeit
- BcMath\Number::div() - Divides by an arbitrary precision number
- BcMath\Number::pow() - Raises an arbitrary precision number

# BcMath\Number::sub

(PHP 8 >= 8.4.0)

BcMath\Number::sub — Subtracts an arbitrary precision number

### Beschreibung

public function BcMath\Number::sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

Subtracts `num` from $this.

### Parameter-Liste

`num`
  The value to subtract.
`scale`
  BcMath\Number::scale explicitly specified for calculation results. If `null`, the BcMath\Number::scale of the calculation result will be set automatically.

### Rückgabewerte

Returns the result of subtraction as a new BcMath\Number object.

When the BcMath\Number::scale of the result object is automatically set, the greater BcMath\Number::scale of the two numbers used for subtraction is used.

That is, if the BcMath\Number::scales of two values are `2` and `5` respectively, the BcMath\Number::scale of the result will be `5`.

### Fehler/Exceptions

This method throws a ValueError in the following cases:

- `num` is string and not a well-formed BCMath numeric string
- `scale` is outside the valid range

### Beispiele

Beispiel #1 BcMath\Number::sub() example when `scale` is not specified

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'));
    $ret2 = $number->sub('-3.456');
    $ret3 = $number->sub(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(8) "-1.11167"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "4.690"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(6) "-5.766"
      ["scale"]=>
      int(3)
    }

Beispiel #2 BcMath\Number::sub() example of explicitly specifying `scale`

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->sub('-3.456', 10);
    $ret3 = $number->sub(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "-1.1"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "4.6900000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-5"
      ["scale"]=>
      int(0)
    }

### Siehe auch

- bcsub() - Subtrahiert zwei Zahlen beliebiger Genauigkeit
- BcMath\Number::add() - Adds an arbitrary precision number

# BcMath\Number::__toString

(PHP 8 >= 8.4.0)

BcMath\Number::__toString — Converts BcMath\Number to string

### Beschreibung

public function BcMath\Number::__toString(): string

Converts BcMath\Number to string.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns BcMath\Number::value as a string.

# BcMath\Number::__unserialize

(PHP 8 >= 8.4.0)

BcMath\Number::__unserialize — Deserializes a data parameter into a BcMath\Number object

### Beschreibung

public function BcMath\Number::__unserialize(array `$data`): void

Deserializes a data parameter into a BcMath\Number object.

### Parameter-Liste

`data`
  The serialized data parameter as an associative array

### Fehler/Exceptions

This method throws a ValueError if invalid serialized data is passed.

### Siehe auch

- BcMath\Number::__construct() - Creates a BcMath\Number object
- BcMath\Number::serialize()

## Inhaltsverzeichnis

- BcMath\Number::add — Adds an arbitrary precision number
- BcMath\Number::ceil — Rounds up an arbitrary precision number
- BcMath\Number::compare — Compares two arbitrary precision numbers
- BcMath\Number::__construct — Creates a BcMath\Number object
- BcMath\Number::div — Divides by an arbitrary precision number
- BcMath\Number::divmod — Gets the quotient and modulus of an arbitrary precision number
- BcMath\Number::floor — Rounds down an arbitrary precision number
- BcMath\Number::mod — Gets the modulus of an arbitrary precision number
- BcMath\Number::mul — Multiplies an arbitrary precision number
- BcMath\Number::pow — Raises an arbitrary precision number
- BcMath\Number::powmod — Raises an arbitrary precision number, reduced by a specified modulus
- BcMath\Number::round — Rounds an arbitrary precision number
- BcMath\Number::__serialize — Serializes a BcMath\Number object
- BcMath\Number::sqrt — Gets the square root of an arbitrary precision number
- BcMath\Number::sub — Subtracts an arbitrary precision number
- BcMath\Number::__toString — Converts BcMath\Number to string
- BcMath\Number::__unserialize — Deserializes a data parameter into a BcMath\Number object

- Installation/Konfiguration
  - Installation
  - Laufzeit-Konfiguration
- BC Math Funktionen
  - bcadd — Addition zweier Zahlen beliebiger Genauigkeit
  - bcceil — Round up arbitrary precision number
  - bccomp — Vergleich zweier Zahlen beliebiger Genauigkeit
  - bcdiv — Division zweier Zahlen beliebiger Genauigkeit
  - bcdivmod — Get the quotient and modulus of an arbitrary precision number
  - bcfloor — Round down arbitrary precision number
  - bcmod — Modulo zweier Zahlen mit beliebiger Genauigkeit
  - bcmul — Multiplikation zweier Zahlen beliebiger Genauigkeit
  - bcpow — Potenz einer Zahl beliebiger Genauigkeit
  - bcpowmod — Potenz einer Zahl beliebiger Genauigkeit, vermindert um ein angegebenen Modulo
  - bcround — Round arbitrary precision number
  - bcscale — Setzt oder holt die Genauigkeit aller BCmath-Funktionen
  - bcsqrt — Ermittelt die Quadratwurzel einer Zahl beliebiger Genauigkeit
  - bcsub — Subtrahiert zwei Zahlen beliebiger Genauigkeit
- BcMath\Number — The BcMath\Number class
  - BcMath\Number::add — Adds an arbitrary precision number
  - BcMath\Number::ceil — Rounds up an arbitrary precision number
  - BcMath\Number::compare — Compares two arbitrary precision numbers
  - BcMath\Number::__construct — Creates a BcMath\Number object
  - BcMath\Number::div — Divides by an arbitrary precision number
  - BcMath\Number::divmod — Gets the quotient and modulus of an arbitrary precision number
  - BcMath\Number::floor — Rounds down an arbitrary precision number
  - BcMath\Number::mod — Gets the modulus of an arbitrary precision number
  - BcMath\Number::mul — Multiplies an arbitrary precision number
  - BcMath\Number::pow — Raises an arbitrary precision number
  - BcMath\Number::powmod — Raises an arbitrary precision number, reduced by a specified modulus
  - BcMath\Number::round — Rounds an arbitrary precision number
  - BcMath\Number::__serialize — Serializes a BcMath\Number object
  - BcMath\Number::sqrt — Gets the square root of an arbitrary precision number
  - BcMath\Number::sub — Subtracts an arbitrary precision number
  - BcMath\Number::__toString — Converts BcMath\Number to string
  - BcMath\Number::__unserialize — Deserializes a data parameter into a BcMath\Number object

# GNU Multiple Precision

# Einführung

Die Funktionen erlauben das Arbeiten mit beliebig großen Integern unter Verwendung der GNU-MP-Bibliothek.

> Hinweis:

> Die meisten GMP-Funktionen akzeptieren GMP-Zahlen als Argumente. Diese werden in dieser Dokumentation als GMP-Objekte dargestellt. Die meisten der Funktionen akzeptieren außerdem numerische Angaben und Strings als Argumente, sofern es möglich ist, diese in in Zahlen umzuwandeln. Weiterhin wird geprüft, ob es eine performantere Funktion gibt, die mit den Argumenten (nur Integerwerte) arbeiten kann, und sofern vorhanden diese auch verwendet. Lesen Sie dazu auch die Dokumentation zu gmp_init().

> Hinweis:

> Die arithmetischen, die Bit- und die Vergleichs-Operatoren könnn mit den GMP-Objekten, die von gmp_init() und anderen GMP-Funktionen zurückgegeben werden, verwenden werden.

Warnung

Große Ganzzahlen müssen als Strings angegeben werden; andernfalls wird PHP eine Konvertierung zu Gleitkommazahlen erzwingen, was in einem Genauigkeitsverlust resultiert.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

Die GMP-Bibliothek kann von » http://gmplib.org/#DOWNLOAD heruntergeladen werden. Auf dieser Seite steht zudem das GMP-Manual bereit.

Für diese Funktionen wird mindestens GMP Version 4.2 benötigt. Einige Funktionen können aktuellere Versionen der GMP-Bibliothek voraussetzen.

Unter Windows ist MPIR anstelle von GMP erforderlich.

## Installation

Damit diese Funktionen verfügbar sind, muss PHP mit GMP-Support durch Verwendung der --with-gmp-Option kompiliert werden.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`GMP_ROUND_ZERO` (int)
`GMP_ROUND_PLUSINF` (int)
`GMP_ROUND_MINUSINF` (int)
`GMP_MSW_FIRST` (int)
`GMP_LSW_FIRST` (int)
`GMP_LITTLE_ENDIAN` (int)
`GMP_BIG_ENDIAN` (int)
`GMP_NATIVE_ENDIAN` (int)
`GMP_VERSION` (string)
  Die Version der GMP-Bibliothek
`GMP_MPIR_VERSION` (string)
  Die Version der MPIR-Bibliothek.

# Beispiele

Beispiel #1 Fakultätsfunktion unter Verwendung von GMP

    <?php
    function fact($x)
    {
        $return = 1;
        for ($i=2; $i < $x; $i++) {
            $return = gmp_mul($return, $i);
        }
        return $return;
    }

    echo gmp_strval(fact(1000)) . "\n";
    ?>

Dies berechnet die Fakultät von 1000 sehr schnell (eine wirklich große Zahl).

# GMP Funktionen

## Siehe auch

Weitere mathematische Funktionen finden Sie im Kapitel Mathematische Erweiterungen.

# gmp_abs

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_abs — Absolute value

### Beschreibung

function gmp_abs(GMP|int|string `$num`): GMP

Get the absolute value of a number.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Returns the absolute value of `num`, as a GMP number.

### Beispiele

Beispiel #1 gmp_abs() example

    <?php
    $abs1 = gmp_abs("274982683358");
    $abs2 = gmp_abs("-274982683358");

    echo gmp_strval($abs1) . "\n";
    echo gmp_strval($abs2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    274982683358
    274982683358

# gmp_add

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_add — Add numbers

### Beschreibung

function gmp_add(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Add two numbers.

### Parameter-Liste

`num1`
  The first summand (augend).

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  The second summand (addend).

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

A GMP number representing the sum of the arguments.

### Beispiele

Beispiel #1 gmp_add() example

    <?php
    $sum = gmp_add("123456789012345", "76543210987655");
    echo gmp_strval($sum) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    200000000000000

# gmp_and

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_and — Bitwise AND

### Beschreibung

function gmp_and(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calculates bitwise AND of two GMP numbers.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

A GMP number representing the bitwise `AND` comparison.

### Beispiele

Beispiel #1 gmp_and() example

    <?php
    $and1 = gmp_and("0xfffffffff4", "0x4");
    $and2 = gmp_and("0xfffffffff4", "0x8");
    echo gmp_strval($and1) . "\n";
    echo gmp_strval($and2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    4
    0

# gmp_binomial

(PHP 7 >= 7.3.0, PHP 8)

gmp_binomial — Calculates binomial coefficient

### Beschreibung

function gmp_binomial(GMP|int|string `$n`, int `$k`): GMP

Calculates the binomial coefficient C(n, k).

### Parameter-Liste

`n`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`k`

### Rückgabewerte

Returns the binomial coefficient C(n, k).

### Fehler/Exceptions

Throws ValueError if `k` is negative. Prior to PHP 8.0.0, `E_WARNING` was issued instead.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | This function no longer returns `false` on failure.

# gmp_clrbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_clrbit — Clear bit

### Beschreibung

function gmp_clrbit(GMP `$num`, int `$index`): void

Clears (sets to 0) bit `index` in `num`. The index starts at 0.

### Parameter-Liste

`num`

  A GMP object.

`index`

  The index of the bit to clear. Index 0 represents the least significant bit.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 gmp_clrbit() example

    <?php
    $a = gmp_init("0xff");
    gmp_clrbit($a, 0); // index starts at 0, least significant bit
    echo gmp_strval($a) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    254

### Anmerkungen

> Hinweis:

> Unlike most of the other GMP functions, gmp_clrbit() must be called with a GMP object that already exists (using gmp_init() for example). One will not be automatically created.

### Siehe auch

- gmp_setbit() - Set bit
- gmp_testbit() - Tests if a bit is set

# gmp_cmp

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_cmp — Compare numbers

### Beschreibung

function gmp_cmp(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Compares two numbers.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Returns a positive value if `a > b`, zero if `a = b` and a negative value if `a < b`.

### Beispiele

Beispiel #1 gmp_cmp() example

    <?php
    $cmp1 = gmp_cmp("1234", "1000"); // greater than
    $cmp2 = gmp_cmp("1000", "1234"); // less than
    $cmp3 = gmp_cmp("1234", "1234"); // equal to

    echo "$cmp1 $cmp2 $cmp3\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1 -1 0

# gmp_com

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_com — Calculates one's complement

### Beschreibung

function gmp_com(GMP|int|string `$num`): GMP

Returns the one's complement of `num`.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Returns the one's complement of `num`, as a GMP number.

### Beispiele

Beispiel #1 gmp_com() example

    <?php
    $com = gmp_com("1234");
    echo gmp_strval($com) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    -1235

# gmp_div

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div — Alias von gmp_div_q()

### Beschreibung

Diese Funktion ist ein Alias für: gmp_div_q().

# gmp_div_q

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_q — Divide numbers

### Beschreibung

function gmp_div_q(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): GMP

Divides `num1` by `num2` and returns the integer result.

### Parameter-Liste

`num1`

  The number being divided.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  The number that `num1` is being divided by.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`rounding_mode`

  The result rounding is defined by the `rounding_mode`, which can have the following values:

  - `GMP_ROUND_ZERO`: The result is truncated towards 0.
  - `GMP_ROUND_PLUSINF`: The result is rounded towards `+infinity`.
  - `GMP_ROUND_MINUSINF`: The result is rounded towards `-infinity`.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_div_q() example

    <?php
    $div1 = gmp_div_q("100", "5");
    echo gmp_strval($div1) . "\n";

    $div2 = gmp_div_q("1", "3");
    echo gmp_strval($div2) . "\n";

    $div3 = gmp_div_q("1", "3", GMP_ROUND_PLUSINF);
    echo gmp_strval($div3) . "\n";

    $div4 = gmp_div_q("-1", "4", GMP_ROUND_PLUSINF);
    echo gmp_strval($div4) . "\n";

    $div5 = gmp_div_q("-1", "4", GMP_ROUND_MINUSINF);
    echo gmp_strval($div5) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    20
    0
    1
    0
    -1

### Anmerkungen

> Hinweis:

> This function can also be called as gmp_div().

### Siehe auch

- gmp_div_r() - Remainder of the division of numbers
- gmp_div_qr() - Divide numbers and get quotient and remainder

# gmp_div_qr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_qr — Divide numbers and get quotient and remainder

### Beschreibung

function gmp_div_qr(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): array

The function divides `num1` by `num2`.

### Parameter-Liste

`num1`

  The number being divided.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  The number that `num1` is being divided by.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`rounding_mode`

  See the gmp_div_q() function for description of the `rounding_mode` argument.

### Rückgabewerte

Returns an array, with the first element being `[n/d]` (the integer result of the division) and the second being `(n - [n/d] * d)` (the remainder of the division).

### Beispiele

Beispiel #1 Division of GMP numbers

    <?php
    $a = gmp_init("0x41682179fbf5");
    $res = gmp_div_qr($a, "0xDEFE75");
    printf("Result is: q - %s, r - %s",
           gmp_strval($res[0]), gmp_strval($res[1]));
    ?>

### Siehe auch

- gmp_div_q() - Divide numbers
- gmp_div_r() - Remainder of the division of numbers

# gmp_div_r

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_r — Remainder of the division of numbers

### Beschreibung

function gmp_div_r(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): GMP

Calculates remainder of the integer division of `num1` by `num2`. The remainder has the sign of the `num1` argument, if not zero.

### Parameter-Liste

`num1`

  The number being divided.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  The number that `num1` is being divided by.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`rounding_mode`

  See the gmp_div_q() function for description of the `rounding_mode` argument.

### Rückgabewerte

The remainder, as a GMP number.

### Beispiele

Beispiel #1 gmp_div_r() example

    <?php
    $div = gmp_div_r("105", "20");
    echo gmp_strval($div) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    5

### Siehe auch

- gmp_div_q() - Divide numbers
- gmp_div_qr() - Divide numbers and get quotient and remainder

# gmp_divexact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_divexact — Exact division of numbers

### Beschreibung

function gmp_divexact(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Divides `num1` by `num2`, using fast "exact division" algorithm. This function produces correct results only when it is known in advance that `num2` divides `num1`.

### Parameter-Liste

`num1`

  The number being divided.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  The number that `num1` is being divided by.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_divexact() example

    <?php
    $div1 = gmp_divexact("10", "2");
    echo gmp_strval($div1) . "\n";

    $div2 = gmp_divexact("10", "3"); // bogus result
    echo gmp_strval($div2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    5
    2863311534

# gmp_export

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_export — Export to a binary string

### Beschreibung

function gmp_export(GMP|int|string `$num`, int `$word_size` = 1, int `$flags` = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): string

Export a GMP number to a binary string

### Parameter-Liste

`num`

  The GMP number being exported

`word_size`

  Default value is 1. The number of bytes in each chunk of binary data. This is mainly used in conjunction with the options parameter.

`flags`

  Default value is `GMP_MSW_FIRST` | `GMP_NATIVE_ENDIAN`.

### Rückgabewerte

Returns a string.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | This function no longer returns `false` on failure.

### Beispiele

Beispiel #1 gmp_export() example

    <?php
    $number = gmp_init(16705);
    echo gmp_export($number) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    AA

### Siehe auch

- gmp_import() - Import from a binary string

# gmp_fact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_fact — Factorial

### Beschreibung

function gmp_fact(GMP|int|string `$num`): GMP

Calculates factorial (`num!`) of `num`.

### Parameter-Liste

`num`

  The factorial number.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_fact() example

    <?php
    $fact1 = gmp_fact(5); // 5 * 4 * 3 * 2 * 1
    echo gmp_strval($fact1) . "\n";

    $fact2 = gmp_fact(50); // 50 * 49 * 48, ... etc
    echo gmp_strval($fact2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    120
    30414093201713378043612608166064768844377641568960512000000000000

# gmp_gcd

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcd — Calculate GCD

### Beschreibung

function gmp_gcd(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calculate greatest common divisor of `num1` and `num2`. The result is always positive even if either of, or both, input operands are negative.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

A positive GMP number that divides into both `num1` and `num2`.

### Beispiele

Beispiel #1 gmp_gcd() example

    <?php
    $gcd = gmp_gcd("12", "21");
    echo gmp_strval($gcd) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3

### Siehe auch

- gmp_lcm() - Calculate LCM

# gmp_gcdext

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcdext — Calculate GCD and multipliers

### Beschreibung

function gmp_gcdext(GMP|int|string `$num1`, GMP|int|string `$num2`): array

Calculates g, s, and t, such that `a*s + b*t = g = gcd(a,b)`, where gcd is the greatest common divisor. Returns an array with respective elements g, s and t.

This function can be used to solve linear Diophantine equations in two variables. These are equations that allow only integer solutions and have the form: `a*x + b*y = c`. For more information, go to the » "Diophantine Equation" page at MathWorld

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

An array of GMP numbers.

### Beispiele

Beispiel #1 Solving a linear Diophantine equation

    <?php
    // Solve the equation a*s + b*t = g
    // where a = 12, b = 21, g = gcd(12, 21) = 3
    $a = gmp_init(12);
    $b = gmp_init(21);
    $g = gmp_gcd($a, $b);
    $r = gmp_gcdext($a, $b);

    $check_gcd = (gmp_strval($g) == gmp_strval($r['g']));
    $eq_res = gmp_add(gmp_mul($a, $r['s']), gmp_mul($b, $r['t']));
    $check_res = (gmp_strval($g) == gmp_strval($eq_res));

    if ($check_gcd && $check_res) {
        $fmt = "Solution: %d*%d + %d*%d = %d\n";
        printf($fmt, gmp_strval($a), gmp_strval($r['s']), gmp_strval($b),
        gmp_strval($r['t']), gmp_strval($r['g']));
    } else {
        echo "Error while solving the equation\n";
    }

    // output: Solution: 12*2 + 21*-1 = 3
    ?>

# gmp_hamdist

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_hamdist — Hamming distance

### Beschreibung

function gmp_hamdist(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Returns the hamming distance between `num1` and `num2`. Both operands should be non-negative.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

  It should be positive.

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

  It should be positive.

### Rückgabewerte

The hamming distance between `num1` and `num2`, as an int.

### Beispiele

Beispiel #1 gmp_hamdist() example

    <?php
    $ham1 = gmp_init("1001010011", 2);
    $ham2 = gmp_init("1011111100", 2);
    echo gmp_hamdist($ham1, $ham2) . "\n";

    /* hamdist is equivalent to: */
    echo gmp_popcount(gmp_xor($ham1, $ham2)) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    6
    6

### Siehe auch

- gmp_popcount() - Population count
- gmp_xor() - Bitwise XOR

# gmp_import

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_import — Import from a binary string

### Beschreibung

function gmp_import(string `$data`, int `$word_size` = 1, int `$flags` = GMP_MSW_FIRST | GMP_NATIVE_ENDIAN): GMP

Import a GMP number from a binary string

### Parameter-Liste

`data`

  The binary string being imported

`word_size`

  Default value is 1. The number of bytes in each chunk of binary data. This is mainly used in conjunction with the options parameter.

`flags`

  Default value is `GMP_MSW_FIRST` | `GMP_NATIVE_ENDIAN`.

### Rückgabewerte

Returns a GMP number.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | This function no longer returns `false` on failure.

### Beispiele

Beispiel #1 gmp_import() example

    <?php
    $number = gmp_import("\0");
    echo gmp_strval($number) . "\n";

    $number = gmp_import("\0\1\2");
    echo gmp_strval($number) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0
    258

### Siehe auch

- gmp_export() - Export to a binary string

# gmp_init

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_init — Create GMP number

### Beschreibung

function gmp_init(int|string `$num`, int `$base` = 0): GMP

Creates a GMP number from an integer or string.

### Parameter-Liste

`num`
  An integer or a string. The string representation can be decimal, hexadecimal, octal, or binary.
`base`
  The base to use for converting a string representation. An explicit base can be between `2` and `62`. For bases up to `36`, case is ignored; upper-case and lower-case letters have the same value. For bases `37` to `62`, upper-case letter represent the values `10` to `35` and lower-case letter represent the values `36` to `61`. If `base` is `0` then the actual base is determined from the leading characters of `num`. If the first two characters are `0x` or `0X`, the string is interpreted as a hexadecimal integer. If the first two characters are `0b` or `0B`, the string is interpreted as a binary integer. If the first two characters are `0o` or `0O`, the string is interpreted as an octal integer. Moreover, if the first character is `0` the string is also interpreted as an octal integer. In all other cases, the string is interpreted as a decimal integer.

### Rückgabewerte

Ein GMP-Objekt.

### Changelog

Version | Beschreibung
--- | ---
8.1.0 | Support for explicit octal prefixes `0o` and `0O` has been added for `num` strings. Interpretation of such prefixes when `base` is `0` has also been added.

### Beispiele

Beispiel #1 Creating GMP number

    <?php
    $a = gmp_init(123456);
    $b = gmp_init("0xFFFFDEBACDFEDF7200");
    ?>

### Anmerkungen

> Hinweis:

> It is not necessary to call this function in order to use integers or strings in place of GMP numbers in GMP functions (such as with gmp_add()). Function arguments are automatically converted to GMP numbers, if such conversion is possible and needed, using the same rules as gmp_init().

### Siehe auch

- GMP::__construct() - Create GMP number

# gmp_intval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_intval — Convert GMP number to integer

### Beschreibung

function gmp_intval(GMP|int|string `$num`): int

This function converts GMP number into native PHP ints.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

The int value of `num`.

### Beispiele

Beispiel #1 gmp_intval() example

    <?php
    // displays correct result
    echo gmp_intval("2147483647") . "\n";

    // displays wrong result, above PHP integer limit
    echo gmp_intval("2147483648") . "\n";

    // displays correct result
    echo gmp_strval("2147483648") . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2147483647
    2147483647
    2147483648

### Anmerkungen

Warnung

This function returns a useful result only if the number actually fits the PHP integer (i.e., signed long type). To simply print the GMP number, use gmp_strval().

# gmp_invert

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_invert — Inverse by modulo

### Beschreibung

function gmp_invert(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP|false

Computes the inverse of `num1` modulo `num2`.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

A GMP number on success or `false` if an inverse does not exist.

### Beispiele

Beispiel #1 gmp_invert() example

    <?php
    echo gmp_invert("5", "10"); // no inverse, outputs nothing, result is FALSE
    $invert = gmp_invert("5", "11");
    echo gmp_strval($invert) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    9

# gmp_jacobi

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_jacobi — Jacobi symbol

### Beschreibung

function gmp_jacobi(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Computes » Jacobi symbol of `num1` and `num2`. `num2` should be odd and must be positive.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

  Should be odd and must be positive.

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_jacobi() example

    <?php
    echo gmp_jacobi("1", "3") . "\n";
    echo gmp_jacobi("2", "3") . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1
    0

### Siehe auch

- gmp_kronecker() - Kronecker symbol
- gmp_legendre() - Legendre symbol

# gmp_kronecker

(PHP 7 >= 7.3.0, PHP 8)

gmp_kronecker — Kronecker symbol

### Beschreibung

function gmp_kronecker(GMP|int|string `$num1`, GMP|int|string `$num2`): int

This function computes the Kronecker symbol of `num1` and `num2`.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Returns the Kronecker symbol of `num1` and `num2`

### Siehe auch

- gmp_jacobi() - Jacobi symbol
- gmp_legendre() - Legendre symbol

# gmp_lcm

(PHP 7 >= 7.3.0, PHP 8)

gmp_lcm — Calculate LCM

### Beschreibung

function gmp_lcm(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

This function computes the least common multiple (lcm) of `num1` and `num2`.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Ein GMP-Objekt.

### Siehe auch

- gmp_gcd() - Calculate GCD

# gmp_legendre

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_legendre — Legendre symbol

### Beschreibung

function gmp_legendre(GMP|int|string `$num1`, GMP|int|string `$num2`): int

Compute the » Legendre symbol of `num1` and `num2`. `num2` should be odd and must be positive.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

  Should be odd and must be positive.

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_legendre() example

    <?php
    echo gmp_legendre("1", "3") . "\n";
    echo gmp_legendre("2", "3") . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1
    0

### Siehe auch

- gmp_jacobi() - Jacobi symbol
- gmp_kronecker() - Kronecker symbol

# gmp_mod

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mod — Modulo operation

### Beschreibung

function gmp_mod(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calculates `num1` modulo `num2`. The result is always non-negative, the sign of `num2` is ignored.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  The modulo that is being evaluated.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_mod() example

    <?php
    $mod = gmp_mod("8", "3");
    echo gmp_strval($mod) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2

# gmp_mul

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mul — Multiply numbers

### Beschreibung

function gmp_mul(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Multiplies `num1` by `num2` and returns the result.

### Parameter-Liste

`num1`

  A number that will be multiplied by `num2`.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  A number that will be multiplied by `num1`.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_mul() example

    <?php
    $mul = gmp_mul("12345678", "2000");
    echo gmp_strval($mul) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    24691356000

# gmp_neg

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_neg — Negate number

### Beschreibung

function gmp_neg(GMP|int|string `$num`): GMP

Returns the negative value of a number.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Returns -`num`, as a GMP number.

### Beispiele

Beispiel #1 gmp_neg() example

    <?php
    $neg1 = gmp_neg("1");
    echo gmp_strval($neg1) . "\n";
    $neg2 = gmp_neg("-1");
    echo gmp_strval($neg2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    -1
    1

# gmp_nextprime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

gmp_nextprime — Find next prime number

### Beschreibung

function gmp_nextprime(GMP|int|string `$num`): GMP

Find next prime number

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Return the next prime number greater than `num`, as a GMP number.

### Beispiele

Beispiel #1 gmp_nextprime() example

    <?php
    $prime1 = gmp_nextprime(10); // next prime number greater than 10
    $prime2 = gmp_nextprime(-1000); // next prime number greater than -1000

    echo gmp_strval($prime1) . "\n";
    echo gmp_strval($prime2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    11
    2

### Anmerkungen

> Hinweis:

> This function uses a probabilistic algorithm to identify primes and chances to get a composite number are extremely small.

# gmp_or

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_or — Bitwise OR

### Beschreibung

function gmp_or(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calculates bitwise inclusive OR of two GMP numbers.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_or() example

    <?php
    $or1 = gmp_or("0xfffffff2", "4");
    echo gmp_strval($or1, 16) . "\n";
    $or2 = gmp_or("0xfffffff2", "2");
    echo gmp_strval($or2, 16) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    fffffff6
    fffffff2

# gmp_perfect_power

(PHP 7 >= 7.3.0, PHP 8)

gmp_perfect_power — Perfect power check

### Beschreibung

function gmp_perfect_power(GMP|int|string `$num`): bool

Checks whether `num` is a perfect power.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Returns `true` if `num` is a perfect power, `false` otherwise.

### Siehe auch

- gmp_perfect_square() - Perfect square check

# gmp_perfect_square

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_perfect_square — Perfect square check

### Beschreibung

function gmp_perfect_square(GMP|int|string `$num`): bool

Check if a number is a perfect square.

### Parameter-Liste

`num`

  The number being checked as a perfect square.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Returns `true` if `num` is a perfect square, `false` otherwise.

### Beispiele

Beispiel #1 gmp_perfect_square() example

    <?php
    // 3 * 3, perfect square
    var_dump(gmp_perfect_square("9"));

    // not a perfect square
    var_dump(gmp_perfect_square("7"));

    // 1234567890 * 1234567890, perfect square
    var_dump(gmp_perfect_square("1524157875019052100"));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(true)
    bool(false)
    bool(true)

### Siehe auch

- gmp_perfect_power() - Perfect power check
- gmp_sqrt() - Calculate square root
- gmp_sqrtrem() - Square root with remainder

# gmp_popcount

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_popcount — Population count

### Beschreibung

function gmp_popcount(GMP|int|string `$num`): int

Get the population count.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

The population count of `num`, as an int.

### Beispiele

Beispiel #1 gmp_popcount() example

    <?php
    $pop1 = gmp_init("10000101", 2); // 3 1's
    echo gmp_popcount($pop1) . "\n";
    $pop2 = gmp_init("11111110", 2); // 7 1's
    echo gmp_popcount($pop2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3
    7

# gmp_pow

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_pow — Raise number into power

### Beschreibung

function gmp_pow(GMP|int|string `$num`, int `$exponent`): GMP

Raise `num` into power `exponent`.

### Parameter-Liste

`num`

  The base number.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`exponent`

  The positive power to raise the `num`.

### Rückgabewerte

The new (raised) number, as a GMP number. The case of `0^0` yields 1.

### Beispiele

Beispiel #1 gmp_pow() example

    <?php
    $pow1 = gmp_pow("2", 31);
    echo gmp_strval($pow1) . "\n";
    $pow2 = gmp_pow("0", 0);
    echo gmp_strval($pow2) . "\n";
    $pow3 = gmp_pow("2", -1); // Negative exp, generates warning
    echo gmp_strval($pow3) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2147483648
    1

# gmp_powm

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_powm — Raise number into power with modulo

### Beschreibung

function gmp_powm(GMP|int|string `$num`, GMP|int|string `$exponent`, GMP|int|string `$modulus`): GMP

Calculate (`num` raised into power `exponent`) modulo `modulus`. If `exponent` is negative, result is undefined.

### Parameter-Liste

`num`

  The base number.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`exponent`

  The positive power to raise the `num`.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`modulus`

  The modulo.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

The new (raised) number, as a GMP number.

### Beispiele

Beispiel #1 gmp_powm() example

    <?php
    $pow1 = gmp_powm("2", "31", "2147483649");
    echo gmp_strval($pow1) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2147483648

# gmp_prob_prime

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_prob_prime — Check if number is "probably prime"

### Beschreibung

function gmp_prob_prime(GMP|int|string `$num`, int `$repetitions` = 10): int

The function uses Miller-Rabin's probabilistic test to check if a number is a prime.

### Parameter-Liste

`num`

  The number being checked as a prime.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`repetitions`

  Reasonable values of `repetitions` vary from 5 to 10 (default being 10); a higher value lowers the probability for a non-prime to pass as a "probable" prime.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

If this function returns 0, `num` is definitely not prime. If it returns 1, then `num` is "probably" prime. If it returns 2, then `num` is surely prime.

### Beispiele

Beispiel #1 gmp_prob_prime() example

    <?php
    // definitely not a prime
    echo gmp_prob_prime("6") . "\n";

    // probably a prime
    echo gmp_prob_prime("1111111111111111111") . "\n";

    // definitely a prime
    echo gmp_prob_prime("11") . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    0
    1
    2

# gmp_random

(PHP 4 >= 4.0.4, PHP 5, PHP 7)

gmp_random — Random number

Warnung

Diese Funktion ist seit PHP 7.2.0 als DEPRECATED (veraltet) markiert und wurde in PHP 8.0.0 ENTFERNT. Von der Verwendung dieser Funktion wird dringend abgeraten.

### Beschreibung

function gmp_random(int `$limiter` = 20): GMP

Generate a random number. The number will be between 0 and (2 ** n) - 1, where n is the number of bits per limb multiplied by `limiter`. If `limiter` is negative, negative numbers are generated.

A limb is an internal GMP mechanism. The number of bits in a limb is not static, and can vary from system to system. Generally, the number of bits in a limb is either 32 or 64, but this is not guaranteed.

Achtung

Diese Funktion erzeugt keine kryptografisch sicheren Werte und darf nicht für kryptografische Zwecke verwendet werden oder für Zwecke, bei denen die zurückgegebenen Werte nicht abschätzbar sein dürfen.

Falls kryptographisch sichere Zufallszahlen benötigt werden, kann der Random\Randomizer mit der Random\Engine\Secure-Engine verwendet werden. Für einfache Anwendungsfälle bieten die Funktionen random_int() und random_bytes() eine bequeme und sichere API, die den CSPRNG des Betriebssystems verwendet.

### Parameter-Liste

`limiter`

  The limiter.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

A random GMP number.

### Beispiele

Beispiel #1 gmp_random() example

    <?php
    $rand1 = gmp_random(1); // random number from 0 to 1 * bits per limb
    $rand2 = gmp_random(2); // random number from 0 to 2 * bits per limb

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1915834968
    8642564075890328087

# gmp_random_bits

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_bits — Random number

### Beschreibung

function gmp_random_bits(int `$bits`): GMP

Generate a random number. The number will be between `0` and `2$bits - 1`.

`bits` must be greater than 0, and the maximum value is restricted by available memory.

Achtung

Diese Funktion erzeugt keine kryptografisch sicheren Werte und darf nicht für kryptografische Zwecke verwendet werden oder für Zwecke, bei denen die zurückgegebenen Werte nicht abschätzbar sein dürfen.

Falls kryptographisch sichere Zufallszahlen benötigt werden, kann der Random\Randomizer mit der Random\Engine\Secure-Engine verwendet werden. Für einfache Anwendungsfälle bieten die Funktionen random_int() und random_bytes() eine bequeme und sichere API, die den CSPRNG des Betriebssystems verwendet.

### Parameter-Liste

`bits`

  The number of bits to generate.

### Rückgabewerte

A random GMP number.

### Fehler/Exceptions

If `bits` is less than `1`, a ValueError will be thrown.

### Beispiele

Beispiel #1 gmp_random_bits() example

    <?php
    $rand1 = gmp_random_bits(3); // random number from 0 to 7
    $rand2 = gmp_random_bits(5); // random number from 0 to 31

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3
    15

# gmp_random_range

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_range — Get a uniformly selected integer

### Beschreibung

function gmp_random_range(GMP|int|string `$min`, GMP|int|string `$max`): GMP

Generate a random number. The number will be between `min` and `max`.

`min` and `max` can both be negative, but `min` must always be less than `max`.

Achtung

Diese Funktion erzeugt keine kryptografisch sicheren Werte und darf nicht für kryptografische Zwecke verwendet werden oder für Zwecke, bei denen die zurückgegebenen Werte nicht abschätzbar sein dürfen.

Falls kryptographisch sichere Zufallszahlen benötigt werden, kann der Random\Randomizer mit der Random\Engine\Secure-Engine verwendet werden. Für einfache Anwendungsfälle bieten die Funktionen random_int() und random_bytes() eine bequeme und sichere API, die den CSPRNG des Betriebssystems verwendet.

### Parameter-Liste

`min`

  A GMP number representing the lower bound for the random number

`max`

  A GMP number representing the upper bound for the random number

### Rückgabewerte

Returns a GMP object which contains a uniformly selected integer from the closed interval [`min`, `max`]. Both `min` and `max` are possible return values.

### Fehler/Exceptions

If `max` is less than `min`, a ValueError will be thrown.

### Beispiele

Beispiel #1 gmp_random_range() example

    <?php
    $rand1 = gmp_random_range(0, 100);    // random number between 0 and 100
    $rand2 = gmp_random_range(-100, -10); // random number between -100 and -10

    echo gmp_strval($rand1) . "\n";
    echo gmp_strval($rand2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    42
    -67

# gmp_random_seed

(PHP 7, PHP 8)

gmp_random_seed — Sets the RNG seed

### Beschreibung

function gmp_random_seed(GMP|int|string `$seed`): void

### Parameter-Liste

`seed`

  The seed to be set for the gmp_random(), gmp_random_bits(), and gmp_random_range() functions.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Fehler/Exceptions

Throws a ValueError if `seed` is invalid.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | If `seed` is invalid, gmp_random_seed() now throws a ValueError. Previously it emitted an `E_WARNING` and returned `false`.

### Beispiele

Beispiel #1 gmp_random_seed() example

    <?php
    // set the seed
    gmp_random_seed(100);

    var_dump(gmp_strval(gmp_random(1)));

    // set the seed to something else
    gmp_random_seed(gmp_init(-100));

    var_dump(gmp_strval(gmp_random_bits(10)));

    // set the seed to something invalid
    var_dump(gmp_random_seed('not a number'));

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    string(20) "15370156633245019617"
    string(3) "683"

    Warning: gmp_random_seed(): Unable to convert variable to GMP - string is not an integer in %s on line %d
    bool(false)

### Siehe auch

- gmp_init() - Create GMP number
- gmp_random() - Random number
- gmp_random_bits() - Random number
- gmp_random_range() - Get a uniformly selected integer

# gmp_root

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_root — Take the integer part of nth root

### Beschreibung

function gmp_root(GMP|int|string `$num`, int `$nth`): GMP

Takes the `nth` root of `num` and returns the integer component of the result.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`nth`

  The positive root to take of `num`.

### Rückgabewerte

The integer component of the resultant root, as a GMP number.

# gmp_rootrem

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_rootrem — Take the integer part and remainder of nth root

### Beschreibung

function gmp_rootrem(GMP|int|string `$num`, int `$nth`): array

Takes the `nth` root of `num` and returns the integer component and remainder of the result.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`nth`

  The positive root to take of `num`.

### Rückgabewerte

A two element array, where the first element is the integer component of the root, and the second element is the remainder, both represented as GMP numbers.

# gmp_scan0

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan0 — Scan for 0

### Beschreibung

function gmp_scan0(GMP|int|string `$num1`, int `$start`): int

Scans `num1`, starting with bit `start`, towards more significant bits, until the first clear bit is found.

### Parameter-Liste

`num1`

  The number to scan.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`start`

  The starting bit.

### Rückgabewerte

Returns the index of the found bit, as an int. The index starts from 0.

### Beispiele

Beispiel #1 gmp_scan0() example

    <?php
    // "0" bit is found at position 3. index starts at 0
    $s1 = gmp_init("10111", 2);
    echo gmp_scan0($s1, 0) . "\n";

    // "0" bit is found at position 7. index starts at 5
    $s2 = gmp_init("101110000", 2);
    echo gmp_scan0($s2, 5) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3
    7

# gmp_scan1

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan1 — Scan for 1

### Beschreibung

function gmp_scan1(GMP|int|string `$num1`, int `$start`): int

Scans `num1`, starting with bit `start`, towards more significant bits, until the first set bit is found.

### Parameter-Liste

`num1`

  The number to scan.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`start`

  The starting bit.

### Rückgabewerte

Returns the index of the found bit, as an int. If no set bit is found, -1 is returned.

### Beispiele

Beispiel #1 gmp_scan1() example

    <?php
    // "1" bit is found at position 3. index starts at 0
    $s1 = gmp_init("01000", 2);
    echo gmp_scan1($s1, 0) . "\n";

    // "1" bit is found at position 9. index starts at 5
    $s2 = gmp_init("01000001111", 2);
    echo gmp_scan1($s2, 5) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3
    9

# gmp_setbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_setbit — Set bit

### Beschreibung

function gmp_setbit(GMP `$num`, int `$index`, bool `$value` = `true`): void

Sets bit `index` in `num`.

### Parameter-Liste

`num`

  A GMP object.

`index`

  The index of the bit to set. Index 0 represents the least significant bit.

`value`

  True to set the bit (set it to 1/on); false to clear the bit (set it to 0/off).

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 gmp_setbit() example - 0 index

    <?php
    $a = gmp_init("2"); //
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 0); // 0b10 now becomes 0b11
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    2 -> 0b10
    3 -> 0b11

Beispiel #2 gmp_setbit() example - 1 index

    <?php
    $a = gmp_init("0xfd");
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 1); // index starts at 0
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    253 -> 0b11111101
    255 -> 0b11111111

Beispiel #3 gmp_setbit() example - clearing a bit

    <?php
    $a = gmp_init("0xff");
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    gmp_setbit($a, 0, false); // clear bit at index 0
    echo gmp_strval($a), ' -> 0b', gmp_strval($a, 2), "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    255 -> 0b11111111
    254 -> 0b11111110

### Anmerkungen

> Hinweis:

> Unlike most of the other GMP functions, gmp_setbit() must be called with a GMP object that already exists (using gmp_init() for example). One will not be automatically created.

### Siehe auch

- gmp_clrbit() - Clear bit
- gmp_testbit() - Tests if a bit is set

# gmp_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sign — Sign of number

### Beschreibung

function gmp_sign(GMP|int|string `$num`): int

Checks the sign of a number.

### Parameter-Liste

`num`

  Either a GMP object, or a numeric string provided that it is possible to convert the latter to an int.

### Rückgabewerte

Returns 1 if `num` is positive, -1 if `num` is negative, and 0 if `num` is zero.

### Beispiele

Beispiel #1 gmp_sign() example

    <?php
    // positive
    echo gmp_sign("500") . "\n";

    // negative
    echo gmp_sign("-500") . "\n";

    // zero
    echo gmp_sign("0") . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1
    -1
    0

### Siehe auch

- gmp_abs() - Absolute value
- abs() - Absolutwert bzw. Betrag

# gmp_sqrt

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrt — Calculate square root

### Beschreibung

function gmp_sqrt(GMP|int|string `$num`): GMP

Calculates square root of `num`.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

The integer portion of the square root, as a GMP number.

### Beispiele

Beispiel #1 gmp_sqrt() example

    <?php
    $sqrt1 = gmp_sqrt("9");
    $sqrt2 = gmp_sqrt("7");
    $sqrt3 = gmp_sqrt("1524157875019052100");

    echo gmp_strval($sqrt1) . "\n";
    echo gmp_strval($sqrt2) . "\n";
    echo gmp_strval($sqrt3) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3
    2
    1234567890

# gmp_sqrtrem

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrtrem — Square root with remainder

### Beschreibung

function gmp_sqrtrem(GMP|int|string `$num`): array

Calculate the square root of a number, with remainder.

### Parameter-Liste

`num`

  The number being square rooted.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Returns array where first element is the integer square root of `num` and the second is the remainder (i.e., the difference between `num` and the first element squared).

### Beispiele

Beispiel #1 gmp_sqrtrem() example

    <?php
    list($sqrt1, $sqrt1rem) = gmp_sqrtrem("9");
    list($sqrt2, $sqrt2rem) = gmp_sqrtrem("7");
    list($sqrt3, $sqrt3rem) = gmp_sqrtrem("1048576");

    echo gmp_strval($sqrt1) . ", " . gmp_strval($sqrt1rem) . "\n";
    echo gmp_strval($sqrt2) . ", " . gmp_strval($sqrt2rem) . "\n";
    echo gmp_strval($sqrt3) . ", " . gmp_strval($sqrt3rem) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    3, 0
    2, 3
    1024, 0

# gmp_strval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_strval — Convert GMP number to string

### Beschreibung

function gmp_strval(GMP|int|string `$num`, int `$base` = 10): string

Convert GMP number to string representation in base `base`. The default base is 10.

### Parameter-Liste

`num`

  The GMP number that will be converted to a string.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`base`

  The base of the returned number. The default base is 10. Allowed values for the base are from 2 to 62 and -2 to -36.

### Rückgabewerte

The number, as a string.

### Beispiele

Beispiel #1 Converting a GMP number to a string

    <?php
    $a = gmp_init("0x41682179fbf5");
    printf("Decimal: %s, 36-based: %s", gmp_strval($a), gmp_strval($a,36));
    ?>

# gmp_sub

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sub — Subtract numbers

### Beschreibung

function gmp_sub(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Subtracts `num2` from `num1` and returns the result.

### Parameter-Liste

`num1`

  The number being subtracted from.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  The number subtracted from `num1`.

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_sub() example

    <?php
    $sub = gmp_sub("281474976710656", "4294967296"); // 2^48 - 2^32
    echo gmp_strval($sub) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    281470681743360

# gmp_testbit

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gmp_testbit — Tests if a bit is set

### Beschreibung

function gmp_testbit(GMP|int|string `$num`, int `$index`): bool

Tests if the specified bit is set.

### Parameter-Liste

`num`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`index`

  The bit to test

### Rückgabewerte

Returns `true` if the bit is set in `num`, otherwise `false`.

### Fehler/Exceptions

An `E_WARNING` level error is issued when `index` is less than zero, and `false` is returned.

### Beispiele

Beispiel #1 gmp_testbit() example

    <?php
    $n = gmp_init("1000000");
    var_dump(gmp_testbit($n, 1));
    gmp_setbit($n, 1);
    var_dump(gmp_testbit($n, 1));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    bool(false)
    bool(true)

### Siehe auch

- gmp_setbit() - Set bit
- gmp_clrbit() - Clear bit

# gmp_xor

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_xor — Bitwise XOR

### Beschreibung

function gmp_xor(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

Calculates bitwise exclusive OR (XOR) of two GMP numbers.

### Parameter-Liste

`num1`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

`num2`

  Ein GMP-Object, ein Integer oder eine Zeichenkette, die als Zahl interpretiert werden kann, wobei die gleiche Logik gilt, als ob die Zeichenkette in gmp_init() mit automatischer Erkennung der Basis verwendet würde (d. h. wenn `base` gleich 0 ist).

### Rückgabewerte

Ein GMP-Objekt.

### Beispiele

Beispiel #1 gmp_xor() example

    <?php
    $xor1 = gmp_init("1101101110011101", 2);
    $xor2 = gmp_init("0110011001011001", 2);

    $xor3 = gmp_xor($xor1, $xor2);

    echo gmp_strval($xor3, 2) . "\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1011110111000100

## Inhaltsverzeichnis

- gmp_abs — Absolute value
- gmp_add — Add numbers
- gmp_and — Bitwise AND
- gmp_binomial — Calculates binomial coefficient
- gmp_clrbit — Clear bit
- gmp_cmp — Compare numbers
- gmp_com — Calculates one's complement
- gmp_div — Alias von gmp_div_q
- gmp_div_q — Divide numbers
- gmp_div_qr — Divide numbers and get quotient and remainder
- gmp_div_r — Remainder of the division of numbers
- gmp_divexact — Exact division of numbers
- gmp_export — Export to a binary string
- gmp_fact — Factorial
- gmp_gcd — Calculate GCD
- gmp_gcdext — Calculate GCD and multipliers
- gmp_hamdist — Hamming distance
- gmp_import — Import from a binary string
- gmp_init — Create GMP number
- gmp_intval — Convert GMP number to integer
- gmp_invert — Inverse by modulo
- gmp_jacobi — Jacobi symbol
- gmp_kronecker — Kronecker symbol
- gmp_lcm — Calculate LCM
- gmp_legendre — Legendre symbol
- gmp_mod — Modulo operation
- gmp_mul — Multiply numbers
- gmp_neg — Negate number
- gmp_nextprime — Find next prime number
- gmp_or — Bitwise OR
- gmp_perfect_power — Perfect power check
- gmp_perfect_square — Perfect square check
- gmp_popcount — Population count
- gmp_pow — Raise number into power
- gmp_powm — Raise number into power with modulo
- gmp_prob_prime — Check if number is "probably prime"
- gmp_random — Random number
- gmp_random_bits — Random number
- gmp_random_range — Get a uniformly selected integer
- gmp_random_seed — Sets the RNG seed
- gmp_root — Take the integer part of nth root
- gmp_rootrem — Take the integer part and remainder of nth root
- gmp_scan0 — Scan for 0
- gmp_scan1 — Scan for 1
- gmp_setbit — Set bit
- gmp_sign — Sign of number
- gmp_sqrt — Calculate square root
- gmp_sqrtrem — Square root with remainder
- gmp_strval — Convert GMP number to string
- gmp_sub — Subtract numbers
- gmp_testbit — Tests if a bit is set
- gmp_xor — Bitwise XOR

# The GMP class

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

## Einführung

A GMP number. These objects support overloaded arithmetic, bitwise and comparison operators.

> Hinweis:

> No object-oriented interface is provided to manipulate GMP objects. Please use the procedural GMP API.

## Klassenbeschreibung

final class GMP {
/* Methoden */
public function __construct(int|string `$num` = 0, int `$base` = 0)
public function __serialize(): array
public function __unserialize(array `$data`): void
}

## Changelog

Version | Beschreibung
--- | ---
8.4.0 | GMP is now marked final

# GMP::__construct

(PHP 8 >= 8.2.4)

GMP::__construct — Create GMP number

### Beschreibung

public function GMP::__construct(int|string `$num` = 0, int `$base` = 0)

Creates a GMP number from an integer or string.

### Parameter-Liste

`num`
  An integer or a string. The string representation can be decimal, hexadecimal, octal, or binary.
`base`
  The base to use for converting a string representation. An explicit base can be between `2` and `62`. For bases up to `36`, case is ignored; upper-case and lower-case letters have the same value. For bases `37` to `62`, upper-case letter represent the values `10` to `35` and lower-case letter represent the values `36` to `61`. If `base` is `0` then the actual base is determined from the leading characters of `num`. If the first two characters are `0x` or `0X`, the string is interpreted as a hexadecimal integer. If the first two characters are `0b` or `0B`, the string is interpreted as a binary integer. If the first two characters are `0o` or `0O`, the string is interpreted as an octal integer. Moreover, if the first character is `0` the string is also interpreted as an octal integer. In all other cases, the string is interpreted as a decimal integer.

### Siehe auch

- gmp_init() - Create GMP number

# GMP::__serialize

(PHP 8 >= 8.1.0)

GMP::__serialize — Serializes the GMP object

### Beschreibung

public function GMP::__serialize(): array

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# GMP::__unserialize

(PHP 8 >= 8.1.0)

GMP::__unserialize — Deserializes the `data` parameter into a GMP object

### Beschreibung

public function GMP::__unserialize(array `$data`): void

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`data`

  The value being deserialized.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

## Inhaltsverzeichnis

- GMP::__construct — Create GMP number
- GMP::__serialize — Serializes the GMP object
- GMP::__unserialize — Deserializes the data parameter into a GMP object

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Vordefinierte Konstanten
- Beispiele
- GMP Funktionen
  - gmp_abs — Absolute value
  - gmp_add — Add numbers
  - gmp_and — Bitwise AND
  - gmp_binomial — Calculates binomial coefficient
  - gmp_clrbit — Clear bit
  - gmp_cmp — Compare numbers
  - gmp_com — Calculates one's complement
  - gmp_div — Alias von gmp_div_q
  - gmp_div_q — Divide numbers
  - gmp_div_qr — Divide numbers and get quotient and remainder
  - gmp_div_r — Remainder of the division of numbers
  - gmp_divexact — Exact division of numbers
  - gmp_export — Export to a binary string
  - gmp_fact — Factorial
  - gmp_gcd — Calculate GCD
  - gmp_gcdext — Calculate GCD and multipliers
  - gmp_hamdist — Hamming distance
  - gmp_import — Import from a binary string
  - gmp_init — Create GMP number
  - gmp_intval — Convert GMP number to integer
  - gmp_invert — Inverse by modulo
  - gmp_jacobi — Jacobi symbol
  - gmp_kronecker — Kronecker symbol
  - gmp_lcm — Calculate LCM
  - gmp_legendre — Legendre symbol
  - gmp_mod — Modulo operation
  - gmp_mul — Multiply numbers
  - gmp_neg — Negate number
  - gmp_nextprime — Find next prime number
  - gmp_or — Bitwise OR
  - gmp_perfect_power — Perfect power check
  - gmp_perfect_square — Perfect square check
  - gmp_popcount — Population count
  - gmp_pow — Raise number into power
  - gmp_powm — Raise number into power with modulo
  - gmp_prob_prime — Check if number is "probably prime"
  - gmp_random — Random number
  - gmp_random_bits — Random number
  - gmp_random_range — Get a uniformly selected integer
  - gmp_random_seed — Sets the RNG seed
  - gmp_root — Take the integer part of nth root
  - gmp_rootrem — Take the integer part and remainder of nth root
  - gmp_scan0 — Scan for 0
  - gmp_scan1 — Scan for 1
  - gmp_setbit — Set bit
  - gmp_sign — Sign of number
  - gmp_sqrt — Calculate square root
  - gmp_sqrtrem — Square root with remainder
  - gmp_strval — Convert GMP number to string
  - gmp_sub — Subtract numbers
  - gmp_testbit — Tests if a bit is set
  - gmp_xor — Bitwise XOR
- GMP — The GMP class
  - GMP::__construct — Create GMP number
  - GMP::__serialize — Serializes the GMP object
  - GMP::__unserialize — Deserializes the data parameter into a GMP object

# Mathematische Funktionen

# Einführung

Die mathematischen Funktionen behandeln nur Werte im Bereich der Datentypen int und float. Wenn es um größere Zahlen geht, empfiehlt sich ein Blick auf die Funktionen für das Rechnen mit beliebiger Genauigkeit oder die Funktionen für GNU Multiple Precision.

## Siehe auch

- Arithmetische Operatoren
- Funktionen für das Rechnen mit beliebiger Genauigkeit
- Funktionen für GNU Multiple Precision

# Vordefinierte Konstanten

Die aufgelisteten Konstanten stehen immer zur Verfügung, da sie zum Grundbestand von PHP gehören.

Mathematische Konstanten
`M_PI` (float)
  Näherung der Zahl π (pi). (`3.14159265358979323846`).
`M_E` (float)
  Näherung der Eulersche Zahl `e` (`2.7182818284590452354`).
`M_LOG2E` (float)
  Näherung von `log2(e)` (`1.4426950408889634074`).
`M_LOG10E` (float)
  Näherung von `log10(e)` (`0.43429448190325182765`).
`M_LN2` (float)
  Näherung von `ln(2)` (`0.69314718055994530942`).
`M_LN10` (float)
  Näherung von `ln(10)` (`2.30258509299404568402`).
`M_PI_2` (float)
  Näherung von `π/2` (`1.57079632679489661923`).
`M_PI_4` (float)
  Näherung von `π/4` (`0.78539816339744830962`).
`M_1_PI` (float)
  Näherung von `1/π` (`0.31830988618379067154`).
`M_2_PI` (float)
  Näherung von `2/π` (`0.63661977236758134308`).
`M_SQRTPI` (float)
  Näherung von `sqrt(π)` (`1.77245385090551602729`).
`M_2_SQRTPI` (float)
  Näherung von `2/sqrt(π)` (`1.12837916709551257390`).
`M_SQRT2` (float)
  Näherung von `sqrt(2)` (`1.41421356237309504880`).
`M_SQRT3` (float)
  Näherung von `sqrt(3)` (`1.73205080756887729352`).
`M_SQRT1_2` (float)
  Näherung von `1/sqrt(2)` (`0.70710678118654752440`).
`M_LNPI` (float)
  Näherung von `ln(π)` (`1.14472988584940017414`).
`M_EULER` (float)
  Näherung der Euler-Konstante γ (`0.57721566490153286061`).

IEEE-754-Gleitkommakonstanten
`NAN` (float)
  Not A Number (Keine Zahl)
`INF` (float)
  Unendlich

Rounding constants

> Hinweis: Seit PHP 8.4.0 wird empfohlen, stattdessen die RoundingMode-Enum zu verwenden.

`PHP_ROUND_HALF_UP` (int)
  n,5 wird aufgerundet (weg von Null, Kaufmännisches Runden)
`PHP_ROUND_HALF_DOWN` (int)
  n,5 wird abgerundet (hin zu Null)
`PHP_ROUND_HALF_EVEN` (int)
  n,5 wird zur nächsten geraden Zahl gerundet
`PHP_ROUND_HALF_ODD` (int)
  n,5 wird zur nächsten ungeraden Zahl gerundet

# The RoundingMode Enum

(PHP 8 >= 8.4.0)

## Einführung

The RoundingMode enum is used to specify how rounding should be performed for round(), bcround(), and BcMath\Number::round().

## Übersicht über Aufzählungen

enum RoundingMode
{
case HalfAwayFromZero ; // Round to the nearest integer. If the decimal part is `5`, round to the integer with the larger absolute value.
case HalfTowardsZero ; // Round to the nearest integer. If the decimal part is `5`, round to the integer with the smaller absolute value.
case HalfEven ; // Round to the nearest integer. If the decimal part is `5`, round to the even integer.
case HalfOdd ; // Round to the nearest integer. If the decimal part is `5`, round to the odd integer.
case TowardsZero ; // Round to the nearest integer with a smaller or equal absolute value.
case AwayFromZero ; // Round to the nearest integer with a greater or equal absolute value.
case NegativeInfinity ; // Round to the largest integer that is smaller or equal.
case PositiveInfinity ; // Round to the smallest integer that is greater or equal.
}

# Mathematische Funktionen

# abs

(PHP 4, PHP 5, PHP 7, PHP 8)

abs — Absolutwert bzw. Betrag

### Beschreibung

function abs(int|float `$num`): int|float

Gibt den Betrag des Wertes `num` ohne Vorzeichen zurück.

### Parameter-Liste

`num`

  Der zu bearbeitende Wert

### Rückgabewerte

Der Betrag des Wertes `num`. Ist `num` vom Typ float, so ist auch das Ergebnis von diesem Typ. Andernfalls wird das Ergebnis als int zurückgegeben (float hat normalerweise einen größeren Wertebereich als int).

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `num` akzeptiert keine internen Objekte mehr, die eine numerische Konvertierung unterstützen.

### Beispiele

Beispiel #1 abs()-Beispiel

    <?php
    var_dump(abs(-4.2));
    var_dump(abs(5));
    var_dump(abs(-5));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(4.2)
    int(5)
    int(5)

### Siehe auch

- gmp_abs() - Absolute value
- gmp_sign() - Sign of number

# acos

(PHP 4, PHP 5, PHP 7, PHP 8)

acos — Arkuskosinus

### Beschreibung

function acos(float `$num`): float

Berechnet den Arkuskosinus des Parameters `num` im Bogenmaß. acos() ist die Umkehrfunktion von cos(), d. h. für jeden Wert von `num`, der innerhalb des Wertebereichs von acos() liegt, gilt `$num == cos(acos($num))`.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der Arkuskosinus von `num` im Bogenmaß.

### Siehe auch

- cos() - Kosinus
- acosh() - Areakosinus hyperbolikus
- asin() - Arkussinus
- atan() - Arkustangens

# acosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

acosh — Areakosinus hyperbolikus

### Beschreibung

function acosh(float `$num`): float

Gibt den inversen Kosinus hyperbolikus von `num` zurück, d.h. den Wert dessen Kosinus hyperbolikus `num` ergibt.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der Areakosinus hyperbolikus von `num`.

### Siehe auch

- cosh() - Kosinus hyperbolikus
- acos() - Arkuskosinus
- asinh() - Areasinus hyperbolikus
- atanh() - Areatangens hyperbolikus

# asin

(PHP 4, PHP 5, PHP 7, PHP 8)

asin — Arkussinus

### Beschreibung

function asin(float `$num`): float

Berechnet den Arkussinus des Parameters `num` im Bogenmaß. asin() ist die Umkehrfunktion von sin(), d. h. für jeden Wert von `num`, der innerhalb des Wertebereichs von asin() liegt, gilt `$num == sin(asin($num))`.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der Arkussinus von `num` im Bogenmaß.

### Siehe auch

- sin() - Sinus
- asinh() - Areasinus hyperbolikus
- acos() - Arkuskosinus
- atan() - Arkustangens

# asinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

asinh — Areasinus hyperbolikus

### Beschreibung

function asinh(float `$num`): float

Berechnet den Areasinus hyperbolikus von `num`. Der Areasinus hyperbolikus ist die Umkehrfunktion des Sinus hyperbolikus, d.h. `asinh(sinh(num)) = num`.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der Areasinus hyperbolikus von `num`.

### Siehe auch

- sinh() - Sinus hyperbolikus
- asin() - Arkussinus
- acosh() - Areakosinus hyperbolikus
- atanh() - Areatangens hyperbolikus

# atan

(PHP 4, PHP 5, PHP 7, PHP 8)

atan — Arkustangens

### Beschreibung

function atan(float `$num`): float

Berechnet den Arkustangens von `num` im Bogenmaß. atan() ist die Umkehrfunktion von tan(), d. h. für jeden Wert von `num`, der im Wertebereich von atan() liegt, gilt `$num == tan(atan($num))`.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der Arkustangens von `num` im Bogenmaß.

### Siehe auch

- tan() - Tangens
- atanh() - Areatangens hyperbolikus
- asin() - Arkussinus
- acos() - Arkuskosinus

# atan2

(PHP 4, PHP 5, PHP 7, PHP 8)

atan2 — Arkustangens-Variante mit zwei Parametern

### Beschreibung

function atan2(float `$y`, float `$x`): float

Diese Funktion berechnet den Arkustangens von `y`/`x`. Im Gegensatz zu atan() kann sie dabei die Vorzeichen beider Parameter beachten und so den Quadranten des Ergebnisses bestimmen.

Die Funktion gibt das Ergebnis im Bogenmaß zurück, das zwischen -PI und PI (inklusive) liegt.

### Parameter-Liste

`y`

  Der Dividend (Zähler).

`x`

  Der Divisor (Nenner).

### Rückgabewerte

Der Arkustangens von `y`/`x` im Bogenmaß.

### Siehe auch

- atan() - Arkustangens

# atanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

atanh — Areatangens hyperbolikus

### Beschreibung

function atanh(float `$num`): float

Gibt den inversen Tangens hyperbolikus von `num` zurück, d.h. den Wert dessen Tangens hyperbolikus `num` ergibt.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der Areatangens hyperbolikus von `num`.

### Siehe auch

- tanh() - Tangens hyperbolikus
- atan() - Arkustangens
- asinh() - Areasinus hyperbolikus
- acosh() - Areakosinus hyperbolikus

# base_convert

(PHP 4, PHP 5, PHP 7, PHP 8)

base_convert — Wandelt einen numerischen Wert zwischen verschiedenen Zahlensystemen um

### Beschreibung

function base_convert(string `$num`, int `$from_base`, int `$to_base`): string

base_convert() gibt eine Zeichenkette zurück, die `num` in der Darstellung des Zahlensystems `to_base` enthält. Das Zahlensystem, in dem die Zahl `num` vorliegt, wird in `from_base` angegeben. Sowohl `from_base` als auch `to_base` müssen zwischen 2 und 36 (inklusive) liegen. In Zahlensystemen mit einer Basis größer als zehn werden die Zahlen größer als neun durch die Buchstaben a bis z dargestellt. Dabei steht a für 10, b für 11 und so weiter bis z für 35. Die Groß- und Kleinschreibung der Buchstaben spielt dabei keine Rolle, d.h. `num` wird ohne Berücksichtigung der Groß- und Kleinschreibung ausgewertet.

Warnung

base_convert() kann bei großen Werten auf Grund von Eigenschaften des zugrunde liegenden internen Datentyps float die Genauigkeit verschlechtern. Nähere Informationen hierzu und zu den Einschränkungen sind im Abschnitt Gleitkommazahlen des Handbuchs zu finden.

### Parameter-Liste

`num`

  Die umzuwandelnde numerische Zeichenkette. Alle ungültigen Zeichen werden ohne Warnung ignoriert. Von PHP 7.4.0 an ist die Übergabe jeglicher ungültiger Zeichen missbilligt.

`from_base`

  Die Basis, zu der `num` kodiert ist

`to_base`

  Die Basis, zu der `num` umgewandelt werden soll

### Rückgabewerte

`num` umgewandelt zur Basis `to_base`.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Die Übergabe ungültiger Zeichen löst nun einen Hinweis aus, dass dies veraltet ist. Das Ergebnis wird weiterhin so berechnet, als würden die ungültigen Zeichen nicht existieren.

### Beispiele

Beispiel #1 base_convert()-Beispiel

    <?php
    $hexadecimal = 'a37334';
    echo base_convert($hexadecimal, 16, 2);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    101000110111001100110100

### Siehe auch

- intval() - Konvertiert einen Wert nach integer

# bindec

(PHP 4, PHP 5, PHP 7, PHP 8)

bindec — Wandelt von binär zu dezimal um

### Beschreibung

function bindec(string `$binary_string`): int|float

Gibt die dezimale Entsprechung der in binärer Darstellung angegebenen Zeichenkette `binary_string` zurück.

bindec() wandelt eine binäre Zahl in einen int oder, falls aus Größengründen benötigt, in einen float um.

bindec() interpretiert alle `binary_string`-Werte als vorzeichenlose Ganzzahlen. Dies ist so, weil bindec() das höchstwertige Bit als weitere Größenordnung anstatt als Vorzeichenbit ansieht.

### Parameter-Liste

`binary_string`

  Die umzuwandelnde Binär-Zeichenkette. Jegliche ungültigen Zeichen in `binary_string` werden stillschweigend ignoriert. Von PHP 7.4.0 an ist die Übergabe jeglicher ungültiger Zeichen missbilligt.

Warnung

Der Parameter muss eine Zeichenkette sein. Andere Datentypen ergeben unerwartete Ergebnisse.

### Rückgabewerte

Der Dezimalwert von `binary_string`.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Die Übergabe ungültiger Zeichen löst nun einen Deprecation-Hinweis aus. Das Ergebnis wird weiterhin so berechnet, als würden die ungültigen Zeichen nicht existieren.

### Beispiele

Beispiel #1 bindec()-Beispiel

    <?php
    echo bindec('110011') . "\n";
    echo bindec('000110011') . "\n";

    echo bindec('111');
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    51
    51
    7

Beispiel #2 bindec() interpretiert die Eingabe als vorzeichenlose Ganzzahlen

    <?php
    /*
     * Die Lektion dieses Beispiels liegt in der Ausgabe,
     * und nicht im PHP-Code selbst.
     */

    $magnitude_lower = pow(2, (PHP_INT_SIZE * 8) - 2);
    p($magnitude_lower - 1);
    p($magnitude_lower, 'Beachte den Überlauf, auch in den folgenden Fällen!');

    p(PHP_INT_MAX, 'PHP_INT_MAX');
    p(~PHP_INT_MAX, 'interpretiert als eins mehr als PHP_INT_MAX');

    if (PHP_INT_SIZE == 4) {
        $note = 'interpretiert als größte vorzeichenlose Ganzzahl';
    } else {
        $note = 'interpretiert als größte vorzeichenlose Ganzzahl (18446744073709551615),
                  aber ungenau aufgrund mangelnder Gleitkommagenauigkeit';
    }
    p(-1, $note);

    function p($input, $note = '') {
        echo "Eingabe:      $input\n";

        $format = '%0' . (PHP_INT_SIZE * 8) . 'b';
        $bin = sprintf($format, $input);
        echo "Binär:        $bin\n";

        ini_set('precision', 20);  // zur Lesbarkeit auf 64bit-Systemen
        $dec = bindec($bin);
        echo 'bindec():     ' . $dec . "\n";

        if ($note) {
            echo "HINWEIS:      $note\n";
        }

        echo "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt auf 32-Bit-Systemen folgende Ausgabe:

    Eingabe:      1073741823
    Binär:        00111111111111111111111111111111
    bindec():     1073741823

    Eingabe:      1073741824
    Binär:        01000000000000000000000000000000
    bindec():     1073741824
    HINWEIS:      Beachte den Überlauf, auch in den folgenden Fällen!

    Eingabe:      2147483647
    Binär:        01111111111111111111111111111111
    bindec():     2147483647
    HINWEIS:      PHP_INT_MAX

    Eingabe:      -2147483648
    Binär:        10000000000000000000000000000000
    bindec():     2147483648
    HINWEIS:      interpretiert als eins mehr als PHP_INT_MAX

    Eingabe:      -1
    Binär:        11111111111111111111111111111111
    bindec():     4294967295
    HINWEIS:      interpretiert als größte vorzeichenlose Ganzzahl

Das oben gezeigte Beispiel erzeugt auf 64-Bit-Systemen folgende Ausgabe:

    Eingabe:      4611686018427387903
    Binär:        0011111111111111111111111111111111111111111111111111111111111111
    bindec():     4611686018427387903

    Eingabe:      4611686018427387904
    Binär:        0100000000000000000000000000000000000000000000000000000000000000
    bindec():     4611686018427387904
    HINWEIS:      Beachte den Überlauf, auch in den folgenden Fällen!

    Eingabe:      9223372036854775807
    Binär:        0111111111111111111111111111111111111111111111111111111111111111
    bindec():     9223372036854775807
    HINWEIS:      PHP_INT_MAX

    Eingabe:      -9223372036854775808
    Binär:        1000000000000000000000000000000000000000000000000000000000000000
    bindec():     9223372036854775808
    HINWEIS:      interpretiert als eins mehr als PHP_INT_MAX

    Eingabe:      -1
    Binär:        1111111111111111111111111111111111111111111111111111111111111111
    bindec():     18446744073709551616
    HINWEIS:      interpretiert als größte vorzeichenlose Ganzzahl (18446744073709551615),
                  aber ungenau aufgrund mangelnder Gleitkommagenauigkeit

### Anmerkungen

> Hinweis:

> Die Funktion kann Zahlen umwandeln, die für den Typ int der Plattform zu groß sind; größere Werte werden dann als float zurückgegeben.

### Siehe auch

- decbin() - Wandelt von dezimal zu binär um
- octdec() - Wandelt von oktal zu dezimal um
- hexdec() - Wandelt von hexadezimal zu dezimal um
- base_convert() - Wandelt einen numerischen Wert zwischen verschiedenen Zahlensystemen um

# ceil

(PHP 4, PHP 5, PHP 7, PHP 8)

ceil — Rundet Brüche auf

### Beschreibung

function ceil(int|float `$num`): float

Rundet `num`, falls erforderlich, auf und gibt den nächstgrößeren ganzzahligen Wert nach `num` zurück.

### Parameter-Liste

`num`

  Der aufzurundende Wert.

### Rückgabewerte

Gibt den nächstgrößeren ganzzahligen Wert nach `num` zurück. Dieser Rückgabewert ist weiterhin vom Typ float, da der Wertebereich von float normalerweise größer ist als der von int.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `num` akzeptiert keine internen Objekte mehr, die eine numerische Konvertierung unterstützen.

### Beispiele

Beispiel #1 ceil()-Beispiel

    <?php
    echo ceil(4.3), PHP_EOL;    // 5
    echo ceil(9.999), PHP_EOL;  // 10
    echo ceil(-3.14), PHP_EOL;  // -3
    ?>

### Siehe auch

- floor() - Rundet Brüche ab
- round() - Rundet einen Gleitkommawert

# cos

(PHP 4, PHP 5, PHP 7, PHP 8)

cos — Kosinus

### Beschreibung

function cos(float `$num`): float

cos() berechnet den Kosinus des Winkels `num`. Der Parameter `num` ist im Bogenmaß.

### Parameter-Liste

`num`

  Ein Winkel in Bogenmaß.

### Rückgabewerte

Der Kosinus des Winkels `num`.

### Beispiele

Beispiel #1 cos()-Beispiel

    <?php

    echo cos(M_PI); // -1

    ?>

### Siehe auch

- acos() - Arkuskosinus
- sin() - Sinus
- tan() - Tangens
- deg2rad() - Rechnet einen Winkel von Grad in Bogenmaß um

# cosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cosh — Kosinus hyperbolikus

### Beschreibung

function cosh(float `$num`): float

Berechnet den Kosinus hyperbolikus des Parameters `num`, welcher definiert ist als `(exp($num) + exp(-$num))/2`.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der Kosinus hyperbolikus von `num`.

### Siehe auch

- cos() - Kosinus
- acosh() - Areakosinus hyperbolikus
- sinh() - Sinus hyperbolikus
- tanh() - Tangens hyperbolikus

# decbin

(PHP 4, PHP 5, PHP 7, PHP 8)

decbin — Wandelt von dezimal zu binär um

### Beschreibung

function decbin(int `$num`): string

Gibt die binäre Darstellung der in `num` angegebenen Ganzzahl als Zeichenkette zurück.

### Parameter-Liste

`num`

  Der umzuwandelnde Dezimalwert.

  Wertebereich der Eingabe unter 32bit-Systemen
  positive `num` | negative `num` | Rückgabewert
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... weiterer Verlauf ...
  2147483646 |  | 1111111111111111111111111111110
  2147483647 (größte vorzeichenbehaftete Ganzzahl) |  | 1111111111111111111111111111111 (31 Einsen)
  2147483648 | -2147483648 | 10000000000000000000000000000000
  ... weiterer Verlauf ...
  4294967294 | -2 | 11111111111111111111111111111110
  4294967295 (größte vorzeichenlose Ganzzahl) | -1 | 11111111111111111111111111111111 (32 Einsen)

  Wertebereich der Eingabe unter 64bit-Systemen
  positive `num` | negative `num` | Rückgabewert
  --- | --- | ---
  0 |  | 0
  1 |  | 1
  2 |  | 10
  ... weiterer Verlauf ...
  9223372036854775806 |  | 111111111111111111111111111111111111111111111111111111111111110
  9223372036854775807 (größte vorzeichenbehaftete Ganzzahl) |  | 111111111111111111111111111111111111111111111111111111111111111 (63 Einsen)
  | -9223372036854775808 | 1000000000000000000000000000000000000000000000000000000000000000
  ... weiterer Verlauf ...
  | -2 | 1111111111111111111111111111111111111111111111111111111111111110
  | -1 | 1111111111111111111111111111111111111111111111111111111111111111 (64 Einsen)

### Rückgabewerte

Binärdarstellung von `num` als Zeichenkette.

### Beispiele

Beispiel #1 decbin()-Beispiel

    <?php
    echo decbin(12) . "\n";
    echo decbin(26);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    1100
    11010

### Siehe auch

- bindec() - Wandelt von binär zu dezimal um
- decoct() - Wandelt von dezimal zu oktal um
- dechex() - Wandelt von dezimal zu hexadezimal um
- base_convert() - Wandelt einen numerischen Wert zwischen verschiedenen Zahlensystemen um
- printf() - Liefert einen formatierten String unter Verwendung von `%b`, `%032b` oder `%064b` als Format
- sprintf() - Gibt einen formatierten String zurück unter Verwendung von `%b`, `%032b` oder `%064b` als Format

# dechex

(PHP 4, PHP 5, PHP 7, PHP 8)

dechex — Wandelt von dezimal zu hexadezimal um

### Beschreibung

function dechex(int `$num`): string

Gibt die hexadezimale Darstellung der in `num` angegebenen vorzeichenlosen Ganzzahl als Zeichenkette zurück.

Der größte umwandelbare Wert ist `PHP_INT_MAX``* 2 + 1` (oder `-1`): auf 32bit-Platformen ist dies `4294967295` in Dezimaldarstellung, was in dechex() `ffffffff` zurückgibt.

### Parameter-Liste

`num`

  Der umzuwandelnde Wert.

  Da der Typ int von PHP vorzeichenbehaftet ist, aber dechex() nur vorzeichenlose Ganzzahlen umwandelt, werden negative Ganzzahlen behandelt, als wären sie vorzeichenlos.

### Rückgabewerte

Die hexadezimale Zeichenkettendarstellung von `num`.

### Beispiele

Beispiel #1 dechex()-Beispiel

    <?php
    echo dechex(10) . "\n";
    echo dechex(47);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    a
    2f

Beispiel #2 dechex()-Beispiel mit großen Ganzzahlen

    <?php
    // Die Ausgaben weiter unten setzen eine 32bit-Plattform voraus.
    // Es ist zu beachten, dass die Ausgabe für alle Werte gleich ist.
    echo dechex(-1)."\n";
    echo dechex(PHP_INT_MAX * 2 + 1)."\n";
    echo dechex(pow(2, 32) - 1)."\n";
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ffffffff
    ffffffff
    ffffffff

### Siehe auch

- hexdec() - Wandelt von hexadezimal zu dezimal um
- decbin() - Wandelt von dezimal zu binär um
- decoct() - Wandelt von dezimal zu oktal um
- base_convert() - Wandelt einen numerischen Wert zwischen verschiedenen Zahlensystemen um

# decoct

(PHP 4, PHP 5, PHP 7, PHP 8)

decoct — Wandelt von dezimal zu oktal um

### Beschreibung

function decoct(int `$num`): string

Gibt die in `num` angegebene Ganzzahl als Zeichenkette in oktaler Darstellung zurück. Der größte umwandelbare Wert variiert abhängig von der verwendeten Plattform. Unter 32bit ist dies üblicherweise `4294967295` (dezimal) bzw. `37777777777` (oktal). Auf 64bit-Plattformen liegt das Limit üblicherweise bei `9223372036854775807` (dezimal) bzw. `777777777777777777777` (oktal).

### Parameter-Liste

`num`

  Der zu umzuwandelnde Wert.

### Rückgabewerte

Oktale Zeichenkettendarstellung von `num`.

### Beispiele

Beispiel #1 decoct()-Beispiel

    <?php
    echo decoct(15) . "\n";
    echo decoct(264);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    17
    410

### Siehe auch

- octdec() - Wandelt von oktal zu dezimal um
- decbin() - Wandelt von dezimal zu binär um
- dechex() - Wandelt von dezimal zu hexadezimal um
- base_convert() - Wandelt einen numerischen Wert zwischen verschiedenen Zahlensystemen um

# deg2rad

(PHP 4, PHP 5, PHP 7, PHP 8)

deg2rad — Rechnet einen Winkel von Grad in Bogenmaß um

### Beschreibung

function deg2rad(float `$num`): float

Die Funktion rechnet den Wert `num` von Grad in den entsprechenden Wert im Bogenmaß um.

### Parameter-Liste

`num`

  Ein Winkel in Grad.

### Rückgabewerte

Der äquivalente Wert zu `num` im Bogenmaß.

### Beispiele

Beispiel #1 deg2rad()-Beispiel

    <?php

    echo deg2rad(45), PHP_EOL; // 0.785398163397
    var_dump(deg2rad(45) === M_PI_4); // bool(true)

    ?>

### Siehe auch

- rad2deg() - Rechnet einen Winkel vom Bogenmaß in Grad um

# exp

(PHP 4, PHP 5, PHP 7, PHP 8)

exp — Berechnet den Exponenten von `e`

### Beschreibung

function exp(float `$num`): float

Berechnet `e` hoch `num`.

> Hinweis:

> '`e`' ist die Basis des natürlichen Logarithmus (ca. 2,718282).

### Parameter-Liste

`num`

  Der zu verarbeitende Exponent.

### Rückgabewerte

'e' hoch `num`.

### Beispiele

Beispiel #1 exp()-Beispiel

    <?php
    echo exp(12), PHP_EOL;
    echo exp(5.7);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    162754.791419
    298.86740096706

### Siehe auch

- log() - Natürlicher Logarithmus
- pow() - Potenzfunktion

# expm1

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

expm1 — Berechnet `exp(Zahl) - 1` mit guter Genauigkeit, auch wenn Zahl nahe bei Null liegt

### Beschreibung

function expm1(float `$num`): float

expm1() gibt das Äquivalent zu `exp($`num`) - 1` zurück, das so berechnet wird, dass es auch dann genau ist, wenn `num` sehr nahe bei Null liegt. In solchen Fällen würde exp() auf Grund mangelnder Präzision gerundet eins zurückgeben und das Gesamtergebnis von `exp($`num`) - 1` wäre einfach Null.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

`e` hoch `num` minus eins.

### Siehe auch

- log1p() - Berechnet log(1 + Zahl) mit guter Genauigkeit, auch wenn Zahl nahe bei Null liegt
- exp() - Berechnet den Exponenten von e

# fdiv

(PHP 8)

fdiv — Dividiert zwei Zahlen gemäß IEEE 754

### Beschreibung

function fdiv(float `$num1`, float `$num2`): float

Gibt das Ergebnis der Gleitkomma-Division von `num1` durch `num2` zurück. Wenn `num2` gleich Null ist, dann wird entweder `INF`, -`INF` oder `NAN` zurückgegeben.

Es ist zu beachten, dass `NAN` bei Vergleichen niemals gleich (`==`) oder identisch (`===`) mit irgendeinem Wert, einschließlich sich selbst, ist.

### Parameter-Liste

`num1`

  Der Dividend (Zähler).

`num2`

  Der Divisor (Nenner).

### Rückgabewerte

Das Ergebnis von `num1`/`num2` als Gleitkommazahl.

### Beispiele

Beispiel #1 Beispiel für die Verwendung von fdiv()

    <?php
    var_dump(fdiv(5.7, 1.3)); // float(4.384615384615385)
    var_dump(fdiv(4, 2)); // float(2)
    var_dump(fdiv(1.0, 0.0)); // float(INF)
    var_dump(fdiv(-1.0, 0.0)); // float(-INF)
    var_dump(fdiv(0.0, 0.0)); // float(NAN)
    ?>

### Siehe auch

- Divisions-Operator `/`
- intdiv() - Integer-Division - Integer-Division
- fmod() - Rest einer Gleitkommadivision (Modulus)
- fpow() - Raise one number to the power of another, according to IEEE 754

# floor

(PHP 4, PHP 5, PHP 7, PHP 8)

floor — Rundet Brüche ab

### Beschreibung

function floor(int|float `$num`): float

Gibt die nächste ganze Zahl, die kleiner oder gleich dem Parameter `num` ist, als Gleitkommazahl zurück.

### Parameter-Liste

`num`

  Der abzurundende Wert.

### Rückgabewerte

Gibt den Wert von `num` gerundet auf die nächstkleinere ganze Zahl zurück. Der Rückgabewert von floor() ist nach wie vor vom Typ float.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | `num` akzeptiert keine internen Objekte mehr, die eine numerische Konvertierung unterstützen.

### Beispiele

Beispiel #1 floor()-Beispiel

    <?php
    echo floor(4.3), PHP_EOL;   // 4
    echo floor(9.999), PHP_EOL; // 9
    echo floor(-3.14), PHP_EOL; // -4
    ?>

### Siehe auch

- ceil() - Rundet Brüche auf
- round() - Rundet einen Gleitkommawert

# fmod

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

fmod — Rest einer Gleitkommadivision (Modulus)

### Beschreibung

function fmod(float `$num1`, float `$num2`): float

Berechnet den Gleitkommarest der Division des Dividenden `num1` durch den Divisor `num2`. Der Rest r ist definiert als 'num1 = i * num2 + r' für ein Ganzzahliges Divisionsergebnis i. Ist `num2` ungleich Null, so hat r das gleiche Vorzeichen wie `num1` und ist kleiner als `num2`.

### Parameter-Liste

`num1`

  Der Dividend (Zähler).

`num2`

  Der Divisor (Nenner).

### Rückgabewerte

Der Gleitkommarest der Division `num1`/`num2`. Falls das zweite Argument `0` ist: `NAN` (float).

### Beispiele

Beispiel #1 fmod()-Beispiel

    <?php
    $x = 5.7;
    $y = 1.3;
    $r = fmod($x, $y);
    // $r ist 0.5 weil 4 * 1.3 + 0.5 = 5.7

    var_dump($x, $y, $r);
    ?>

### Siehe auch

- `/` - Gleitkomma-Division
- `%` - Integer-Modulus
- intdiv() - Integer-Division - Integer-Division

# fpow

(PHP 8 >= 8.4.0)

fpow — Raise one number to the power of another, according to IEEE 754

### Beschreibung

function fpow(float `$num`, float `$exponent`): float

Returns the floating point result of raising `num` to the power of `exponent`. If `num` is zero and `exponent` is less than zero, then `INF` is returned.

### Parameter-Liste

`num`
  The base to use.
`exponent`
  The exponent.

### Rückgabewerte

Returns a float corresponding to `$num$exponent`.

### Beispiele

Beispiel #1 fpow() example

    <?php
    var_dump(fpow(10, 2));
    var_dump(fpow(0, -3));
    var_dump(fpow(-1, 5.5));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(100)
    float(INF)
    float(NAN)

### Siehe auch

- Exponentiation operator `**`
- pow() - Potenzfunktion
- fdiv() - Dividiert zwei Zahlen gemäß IEEE 754
- fmod() - Rest einer Gleitkommadivision (Modulus)

# hexdec

(PHP 4, PHP 5, PHP 7, PHP 8)

hexdec — Wandelt von hexadezimal zu dezimal um

### Beschreibung

function hexdec(string `$hex_string`): int|float

Gibt die dezimale Entsprechung der in hexadezimaler Darstellung angegebenen Zahl `hex_string` zurück. Die Funktion hexdec() wandelt eine hexadezimale Zeichenkette in eine Dezimalzahl um.

hexdec() ignoriert alle nicht hexadezimal kodierten Zeichen (0-9 a-f) in `hex_string`. Von PHP 7.4.0 an ist die Übergabe jeglicher ungültiger Zeichen missbilligt.

### Parameter-Liste

`hex_string`

  Die umzuwandelnde hexadezimale Zeichenkette.

### Rückgabewerte

Dezimaldarstellung von `hex_string`.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Die Übergabe ungültiger Zeichen löst nun einen Deprecation-Hinweis aus. Das Ergebnis wird weiterhin so berechnet, als würden die ungültigen Zeichen nicht existieren.

### Beispiele

Beispiel #1 hexdec()-Beispiel

    <?php
    var_dump(hexdec("ee")); // gibt "int(238)" aus
    var_dump(hexdec("a0")); // gibt "int(160)" aus
    ?>

Beispiel #2 hexdec() mit ungültigen Zeichen

    <?php
    var_dump(hexdec("See"));  // gibt "int(238)" aus
    var_dump(hexdec("that")); // gibt "int(10)" aus
    ?>

### Anmerkungen

> Hinweis:

> Die Funktion kann nun auch Werte umwandeln, die zu groß für den Typ int der jeweiligen Plattform sind, das Ergebnis wird dann als float zurückgegeben.

### Siehe auch

- dechex() - Wandelt von dezimal zu hexadezimal um
- bindec() - Wandelt von binär zu dezimal um
- octdec() - Wandelt von oktal zu dezimal um
- base_convert() - Wandelt einen numerischen Wert zwischen verschiedenen Zahlensystemen um

# hypot

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

hypot — Berechnet die Länge der Hypotenuse eines rechtwinkligen Dreiecks

### Beschreibung

function hypot(float `$x`, float `$y`): float

hypot() berechnet die Länge der Hypotenuse eines rechtwinkligen Dreiecks aus den Längen der beiden Katheten bzw. den Abstand eines Punktes (`x`,`y`) vom Ursprung. Dies entspricht `sqrt($x*$x + $y*$y)`.

### Parameter-Liste

`x`

  Die Länge der ersten Kathete.

`y`

  Die Länge der zweiten Kathete.

### Rückgabewerte

Die berechnete Länge der Hypotenuse.

# intdiv

(PHP 7, PHP 8)

intdiv — Integer-Division

### Beschreibung

function intdiv(int `$num1`, int `$num2`): int

Gibt den Integer-Quotienten der Division von `num1` durch `num2` zurück.

### Parameter-Liste

`num1`

  Die Ausgangszahl, die geteilt werden soll.

`num2`

  Die Zahl, durch die `num1` geteilt werden soll.

### Rückgabewerte

Der Integer-Quotient der Division `num1` durch `num2`.

### Fehler/Exceptions

Wenn `num2` `0` ist, wird eine DivisionByZeroError-Exception ausgelöst. Wenn `num1` `PHP_INT_MIN` ist und `num2` `-1`, wird eine ArithmeticError-Exception ausgelöst.

### Beispiele

Beispiel #1 intdiv()-Beispiel

    <?php
    var_dump(intdiv(3, 2));
    var_dump(intdiv(-3, 2));
    var_dump(intdiv(3, -2));
    var_dump(intdiv(-3, -2));
    var_dump(intdiv(PHP_INT_MAX, PHP_INT_MAX));
    var_dump(intdiv(PHP_INT_MIN, PHP_INT_MIN));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    int(1)
    int(-1)
    int(-1)
    int(1)
    int(1)
    int(1)

Beispiel #2 intdiv()-Beispiel mit ungültigem Divisor

    <?php
    try {
        intdiv(PHP_INT_MIN, -1);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    try {
        intdiv(1, 0);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    ArithmeticError: Division of PHP_INT_MIN by -1 is not an integer
    DivisionByZeroError: Division by zero

### Siehe auch

- `/` - Gleitkomma-Division
- `%` - Integer-Modulus
- fmod() - Rest einer Gleitkommadivision (Modulus) - Gleitkomma-Modulus

# is_finite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_finite — Prüft, ob eine Gleitkommazahl endlich ist

### Beschreibung

function is_finite(float `$num`): bool

Gibt zurück, ob der übergebene Parameter `num` eine endliche Gleitkommazahl ist.

Eine endliche Gleitkommazahl ist weder `NAN` (is_nan()) noch unendlich (is_infinite()).

### Parameter-Liste

`num`

  Die zu überprüfende Gleitkommazahl

### Rückgabewerte

Gibt `true` zurück, wenn `num` nicht `NAN`, `INF` oder -`INF` ist, andernfalls `false`.

### Beispiele

Beispiel #1 is_finite()-Beispiel

    <?php
    $float = 1.2345;
    var_dump($float, is_finite($float));

    $nan = sqrt(-1);
    var_dump($nan, is_finite($nan));

    $inf = 1e308 * 2;
    var_dump($inf, is_finite($inf));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(1.2345)
    bool(true)
    float(NAN)
    bool(false)
    float(INF)
    bool(false)

### Siehe auch

- is_infinite() - Prüft, ob eine Gleitkommazahl unendlich ist
- is_nan() - Prüft, ob eine Gleitkommazahl NAN ist

# is_infinite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_infinite — Prüft, ob eine Gleitkommazahl unendlich ist

### Beschreibung

function is_infinite(float `$num`): bool

Gibt zurück, ob der übergebene Parameter `num` entweder `INF` oder -`INF` ist.

### Parameter-Liste

`num`

  Die zu überprüfende Gleitkommazahl

### Rückgabewerte

Gibt `true` zurück, wenn `num` entweder `INF` oder -`INF` ist, andernfalls `false`.

### Beispiele

Beispiel #1 is_infinite()-Beispiel

    <?php
    $inf = 1e308 * 2;

    var_dump($inf, is_infinite($inf));

    $negative_inf = -$inf;

    var_dump($negative_inf, is_infinite($negative_inf));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(INF)
    bool(true)
    float(-INF)
    bool(true)

### Siehe auch

- is_finite() - Prüft, ob eine Gleitkommazahl endlich ist
- is_nan() - Prüft, ob eine Gleitkommazahl NAN ist

# is_nan

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_nan — Prüft, ob eine Gleitkommazahl NAN ist

### Beschreibung

function is_nan(float `$num`): bool

Gibt zurück, ob die angegebene `Zahl` `NAN` (Not A Number) ist.

`NAN` wird von mathematischen Operationen zurückgegeben, die undefiniert sind, z. B. bei der Übergabe von Parametern außerhalb des Eingabebereichs einer Funktion. Die Quadratwurzel (sqrt()) ist nur für positive Zahlen definiert, die Übergabe einer negativen Zahl führt zu `NAN`. Andere Beispiele für Operationen, die `NAN` zurückgeben, sind die Division von `INF` durch `INF` und jede Operation, die sich auf einen bestehenden `NAN`-Wert bezieht.

> Hinweis:

> Trotz seines Namens Not A Number ist `NAN` (keine Zahl) ein gültiger Wert vom Typ Float.

Achtung

`NAN` kann nicht mit `NAN` verglichen werden. Um zu prüfen, ob ein float `NAN` ist, muss is_nan() verwendet werden. Zu prüfen, ob `$float === NAN` ist, funktioniert nicht.

### Parameter-Liste

`num`

  Die zu überprüfende Gleitkommazahl

### Rückgabewerte

Gibt `true` zurück, wenn `num` `NAN` ist, andernfalls `false`.

### Beispiele

Beispiel #1 is_nan()-Beispiel

    <?php
    $nan = sqrt(-1);

    var_dump($nan, is_nan($nan));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(NAN)
    bool(true)

### Siehe auch

- is_finite() - Prüft, ob eine Gleitkommazahl endlich ist
- is_infinite() - Prüft, ob eine Gleitkommazahl unendlich ist

# log

(PHP 4, PHP 5, PHP 7, PHP 8)

log — Natürlicher Logarithmus

### Beschreibung

function log(float `$num`, float `$base` = `M_E`): float

Berechnet den natürlichen Logarithmus von `num` beziehungsweise, falls der optionale zweite Parameter `base` gegeben ist, den Logarithmus von `num` zur Basis `base`.

### Parameter-Liste

`num`

  Der Wert, für den der Logarithmus berechnet werden soll.

`base`

  Die optionale Basis für die Berechnung des Logarithmus (der Vorgabewert ist 'e' für den natürlichen Logarithmus).

### Rückgabewerte

Der Logarithmus von `num` zur Basis `base` bzw. der natürliche Logarithmus.

### Siehe auch

- log10() - Dekadischer Logarithmus (Logarithmus zur Basis 10)
- exp() - Berechnet den Exponenten von e
- pow() - Potenzfunktion
- error_log() - Sendet eine Fehlermeldung an die definierten Fehlerbehandlungsroutinen

# log10

(PHP 4, PHP 5, PHP 7, PHP 8)

log10 — Dekadischer Logarithmus (Logarithmus zur Basis 10)

### Beschreibung

function log10(float `$num`): float

Berechnet den dekadischen Logarithmus von `num`.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der dekadische Logarithmus von `num`.

### Siehe auch

- log() - Natürlicher Logarithmus

# log1p

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

log1p — Berechnet log(1 + Zahl) mit guter Genauigkeit, auch wenn Zahl nahe bei Null liegt

### Beschreibung

function log1p(float `$num`): float

log1p() gibt log(1 + `num`) zurück, das so berechnet wird, dass es auch dann genau ist, wenn der Wert von `num` sehr nahe bei `0` liegt. log() liefert in solchen Fällen aufgrund von Rundungsfehlern oft nur den Wert von log(1).

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

log(1 + `num`).

### Siehe auch

- expm1() - Berechnet exp(Zahl) - 1 mit guter Genauigkeit, auch wenn Zahl nahe bei Null liegt
- log() - Natürlicher Logarithmus
- log10() - Dekadischer Logarithmus (Logarithmus zur Basis 10)

# max

(PHP 4, PHP 5, PHP 7, PHP 8)

max — Bestimmt den Maximalwert

### Beschreibung

function max(mixed `$value`, mixed `...$values`): mixed

Alternative Signatur (benannte Parameter werden nicht unterstützt):

function max(array `$value_array`): mixed

Ist der erste und einzige Parameter ein Array, gibt max() den größten Wert dieses Arrays zurück. Werden mindestens zwei Parameter übergeben, gibt max() den größeren dieser Werte zurück.

> Hinweis:

> Werte unterschiedlichen Typs werden unter Verwendung der Standard-Vergleichsregeln verglichen. Zum Beispiel wird ein nichtnumerischer string mit einem int verglichen, als ob er `0` wäre, aber mehrere nichtnumerische string-Werte werden alphanumerisch verglichen. Der tatsächlich zurückgegebene Wert ist vom ursprünglichen Typ ohne angewandte Umwandlung.

Achtung

Vorsicht ist geboten, wenn Argumente verschiedenen Typs übergeben werden, da max() in diesem Fall unvorhersehbare Ergebnisse liefert.

### Parameter-Liste

`value`

  Ein vergleichbarer Wert.

`values`

  Jegliche vergleichbaren Werte.

`value_array`

  Ein Array, das Werte enthält.

### Rückgabewerte

max() gibt den gemäß den Standard-Vergleichen als "größten" angesehenen Parameter-Wert zurück. Evaluieren mehrere Werte unterschiedlichen Typs als gleich (z. B. `0` und `'abc'`), wird der zuerst übergebene zurückgegeben.

### Fehler/Exceptions

Wird ein leeres Array übergeben, löst max() einen ValueError aus.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | max() löst bei einem Fehler nun einen ValueError aus; vorher wurde `false` zurückgegeben und ein Fehler der Stufe `E_WARNING` ausgegeben.
8.0.0 | Die Art und Weise, wie Zeichenketten und Zahlen verglichen werden, wurde geändert, sodass max() in solchen Fällen nicht mehr je nach Reihenfolge der Argumente unterschiedliche Werte zurückgibt.

### Beispiele

Beispiel #1 Beispiele für die Verwendung von max()

    <?php
    echo max(2, 3, 1, 6, 7), PHP_EOL;  // 7
    echo max(array(2, 4, 5)), PHP_EOL; // 5

    // Hier vergleichen wir -1 < 0, sodass 'hallo' der größte Wert ist
    echo max('hallo', -1), PHP_EOL;    // hallo

    // Bei mehreren Arrays unterschiedlicher Länge, gibt max das längste zurück
    $val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)
    var_dump($val);

    // Mehrere Arrays gleicher Länge werden von links nach rechts verglichen,
    // daher ist in unserem Beispiel 2 == 2, aber 5 > 4
    $val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1)
    var_dump($val);

    // Sind ein Array und ein Nicht-Array-Parameter gegeben, wird das Array zurückgegeben,
    // da Vergleiche Arrays als größer behandeln als alle anderen Werte
    $val = max('string', array(2, 5, 7), 42);   // array(2, 5, 7)
    var_dump($val);

    // Ist ein Argument NULL oder ein boolescher Wert, wird es mit anderen Werten
    // unter Verwendung der Regel FALSE < TRUE verglichen, ohne Rücksicht auf die anderen beteiligten Typen
    // Im folgenden Beispiel wird -10 im Vergleich wie TRUE behandelt
    $val = max(-10, FALSE); // -10
    var_dump($val);

    // Andererseits wird 0 wie FALSE behandelt, so dass es "kleiner" ist als TRUE
    $val = max(0, TRUE); // TRUE
    var_dump($val);
    ?>

### Siehe auch

- min() - Bestimmt den Minimalwert
- count() - Zählt alle Elemente eines Arrays oder eines Countable-Objekts

# min

(PHP 4, PHP 5, PHP 7, PHP 8)

min — Bestimmt den Minimalwert

### Beschreibung

function min(mixed `$value`, mixed `...$values`): mixed

Alternative Signatur (benannte Parameter werden nicht unterstützt):

function min(array `$value_array`): mixed

Ist der erste und einzige Parameter ein Array, gibt min() den niedrigsten Wert dieses Arrays zurück. Werden mindestens zwei Parameter übergeben, gibt min() den kleinsten dieser Werte zurück.

> Hinweis:

> Werte unterschiedlichen Typs werden unter Verwendung der Standard-Vergleichsregeln verglichen. Zum Beispiel wird ein nichtnumerischer string mit einem int verglichen, als ob er `0` wäre, aber mehrere nichtnumerische string-Werte werden alphanumerisch verglichen. Der tatsächlich zurückgegebene Wert ist vom ursprünglichen Typ ohne angewandte Umwandlung.

Achtung

Vorsicht ist geboten, wenn Argumente verschiedenen Typs übergeben werden, da min() in diesem Fall unvorhersehbare Ergebnisse liefert.

### Parameter-Liste

`value`

  Ein vergleichbarer Wert.

`values`

  Jegliche vergleichbaren Werte.

`value_array`

  Ein Array, das Werte enthält.

### Rückgabewerte

min() gibt den gemäß den Standard-Vergleichen als "kleinsten" angesehenen Parameter-Wert zurück. Evaluieren mehrere Werte unterschiedlichen Typs als gleich (z. B. `0` und `'abc'`), wird der zuerst übergebene zurückgegeben.

### Fehler/Exceptions

Wird ein leeres Array übergeben, löst min() einen ValueError aus.

### Changelog

Version | Beschreibung
--- | ---
8.0.0 | min() löst bei einem Fehler nun einen ValueError aus; vorher wurde `false` zurückgegeben und ein Fehler der Stufe `E_WARNING` ausgegeben.
8.0.0 | Die Art und Weise, wie Zeichenketten und Zahlen verglichen werden, wurde geändert, sodass min() in solchen Fällen nicht mehr je nach Reihenfolge der Argumente unterschiedliche Werte zurückgibt.

### Beispiele

Beispiel #1 Beispiele für die Verwendung von min()

    <?php
    echo min(2, 3, 1, 6, 7), PHP_EOL;  // 1
    echo min(array(2, 4, 5)), PHP_EOL; // 2

    // Hier vergleichen wir -1 < 0, so dass -1 der kleinste Wert ist
    echo min('hello', -1), PHP_EOL;    // -1

    // Bei mehreren Arrays unterschiedlicher Länge, gibt min das kürzeste zurück
    $val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2)
    var_dump($val);

    // Mehrere Arrays gleicher Länge werden von links nach rechts verglichen,
    // daher ist in unserem Beispiel 2 == 2, aber 4 < 5
    $val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)
    var_dump($val);

    // Sind ein Array und ein Nicht-Array-Parameter gegeben, wird nie das Array zurückgegeben,
    // da Vergleiche Arrays als größer behandeln als alle anderen Werte
    $val = min('string', array(2, 5, 7), 42);   // string
    var_dump($val);

    // Ist ein Argument NULL oder ein boolescher Wert, wird es mit anderen Werten
    // unter Verwendung der Regeln FALSE < TRUE und NULL == FALSE verglichen, ohne Rücksicht auf die anderen beteiligten Typen
    // In den folgenden Beispielen wird -10 im Vergleich wie TRUE behandelt
    $val = min(-10, FALSE, 10); // FALSE
    var_dump($val);

    $val = min(-10, NULL, 10);  // NULL
    var_dump($val);

    // Andererseits wird 0 wie FALSE behandelt, so dass es "kleiner" ist als TRUE
    $val = min(0, TRUE); // 0
    var_dump($val);
    ?>

### Siehe auch

- max() - Bestimmt den Maximalwert
- count() - Zählt alle Elemente eines Arrays oder eines Countable-Objekts

# octdec

(PHP 4, PHP 5, PHP 7, PHP 8)

octdec — Wandelt von oktal zu dezimal um

### Beschreibung

function octdec(string `$octal_string`): int|float

Gibt die dezimale Entsprechung der in oktaler Darstellung angegebenen Zahl `octal_string` zurück.

### Parameter-Liste

`octal_string`

  Die umzuwandelnde Oktal-Zeichenkette. Jegliche ungültigen Zeichen in `octal_string` werden stillschweigend ignoriert. Von PHP 7.4.0 an ist die Übergabe jeglicher ungültiger Zeichen missbilligt.

### Rückgabewerte

Die Dezimaldarstellung von `octal_string`.

### Changelog

Version | Beschreibung
--- | ---
7.4.0 | Die Übergabe ungültiger Zeichen löst nun einen Deprecation-Hinweis aus. Das Ergebnis wird weiterhin so berechnet, als würden die ungültigen Zeichen nicht existieren.

### Beispiele

Beispiel #1 octdec()-Beispiel

    <?php
    echo octdec('77') . "\n";
    echo octdec(decoct(45));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    63
    45

### Anmerkungen

> Hinweis:

> Die Funktion kann nun auch Werte umwandeln, die zu groß für den Typ int der jeweiligen Plattform sind, das Ergebnis wird dann als float zurückgegeben.

### Siehe auch

- decoct() - Wandelt von dezimal zu oktal um
- bindec() - Wandelt von binär zu dezimal um
- hexdec() - Wandelt von hexadezimal zu dezimal um
- base_convert() - Wandelt einen numerischen Wert zwischen verschiedenen Zahlensystemen um

# pi

(PHP 4, PHP 5, PHP 7, PHP 8)

pi — Liefert den Wert von Pi

### Beschreibung

function pi(): float

Die Funktion gibt einen Näherungswert von Pi zurück. Sie können auch die Konstante `M_PI` verwenden, die das gleiche Resultat liefert wie pi().

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Der Wert von Pi als float.

### Beispiele

Beispiel #1 pi()-Beispiel

    <?php
    echo pi(), PHP_EOL; // 3.1415926535898
    echo M_PI, PHP_EOL; // 3.1415926535898
    ?>

# pow

(PHP 4, PHP 5, PHP 7, PHP 8)

pow — Potenzfunktion

### Beschreibung

function pow(mixed `$num`, mixed `$exponent`): int|float|object

Berechnet die Potenz von `exponent` zur Basis `num` oder kurz `num`exponent.

> Hinweis:

> Alternativ kann der **-Operator verwendet werden.

### Parameter-Liste

`num`

  Die zu potenzierende Basis.

`exponent`

  Der Exponent.

### Rückgabewerte

`num` in der Potenz `exponent`. Sind beide Argumente nichtnegative Ganzzahlen und kann das Ergebnis als Ganzzahl dargestellt werden, wird das Ergebnis als int zurückgegeben, andernfalls als float.

Das Verhalten dieser Operation kann durch PHP-Erweiterungen überschrieben werden, sodass sie ein Objekt zurückgibt.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Die Anwendung eines negativen `exponent`en auf `0` ist nun veraltet.

### Beispiele

Beispiel #1 Einige pow()-Beispiele

    <?php

    var_dump(pow(2, 8)); // int(256)
    echo pow(-1, 20), PHP_EOL; // 1
    echo pow(0, 0), PHP_EOL; // 1
    echo pow(10, -1), PHP_EOL; // 0.1

    echo pow(-1, 5.5), PHP_EOL; // NAN
    ?>

Beispiel #2 Beispiel für pow() mit einem Objekt der Erweiterung GMP

    <?php
    var_dump(pow(new GMP("3"), new GMP("2"))); // object(GMP)
    ?>

### Anmerkungen

> Hinweis:

> Diese Funktion wandelt alle Eingaben in numerische Werte um, selbst nicht-skalare Werte. Dies kann zu seltsamen Ergebnissen führen.

### Siehe auch

- Potenz-Operator `**`
- fpow() - Raise one number to the power of another, according to IEEE 754
- exp() - Berechnet den Exponenten von e
- sqrt() - Quadratwurzel
- bcpow() - Potenz einer Zahl beliebiger Genauigkeit
- gmp_pow() - Raise number into power

# rad2deg

(PHP 4, PHP 5, PHP 7, PHP 8)

rad2deg — Rechnet einen Winkel vom Bogenmaß in Grad um

### Beschreibung

function rad2deg(float `$num`): float

Diese Funktion rechnet einen Winkel `num` vom Bogenmaß in Grad um.

### Parameter-Liste

`num`

  Ein Winkel im Bogenmaß.

### Rückgabewerte

Der zu `num` äquivalente Wert in Grad.

### Beispiele

Beispiel #1 rad2deg()-Beispiel

    <?php

    echo rad2deg(M_PI_4); // 45

    ?>

### Siehe auch

- deg2rad() - Rechnet einen Winkel von Grad in Bogenmaß um

# round

(PHP 4, PHP 5, PHP 7, PHP 8)

round — Rundet einen Gleitkommawert

### Beschreibung

function round(int|float `$num`, int `$precision` = 0, int|RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): float

Rundet den Parameter `num` auf die mit `precision` angegebene Anzahl von Nachkommastellen. `precision` kann dabei auch Null (Vorgabewert) oder negativ sein. So wird bei einer Stellenzahl von -1 z. B. auf volle Zehner gerundet.

### Parameter-Liste

`num`

  Der zu rundende Wert.

`precision`

  Auf wie viele Nachkommastellen gerundet werden soll.

  Ist die Genauigkeit `precision` positiv, wird `num` auf `precision` signifikante Stellen nach dem Dezimalpunkt gerundet.

  Ist die Genauigkeit `precision` negativ, wird `num` auf `precision` signifikante Stellen vor dem Dezimalpunkt gerundet, d. h. auf das nächste Vielfache von `pow(10, -precision)`, z. B. wird `num` mit einer `precision` von -1 auf Zehner gerundet, mit einer `precision` von -2 auf Hunderter usw.

`mode`

  Um den Rundungsmodus festzulegen, kann RoundingMode oder eine der folgenden Konstanten verwendet werden.

  Konstanten | Beschreibung
  --- | ---
  `PHP_ROUND_HALF_UP` | Rundet `num` auf halber Strecke von Null weg, womit 1.5 zu 2 wird und -1.5 zu -2.
  `PHP_ROUND_HALF_DOWN` | Rundet `num` auf halber Strecke zu Null hin, womit 1.5 zu 1 wird und -1.5 zu -1.
  `PHP_ROUND_HALF_EVEN` | Rundet `num` auf halber Strecke auf den nächsten geraden Wert, womit sowohl 1.5 als auch 2.5 zu 2 werden.
  `PHP_ROUND_HALF_ODD` | Rundet `num` auf halber Strecke auf den nächsten ungeraden Wert, womit 1.5 zu 1 wird und 2.5 zu 3.

  Es ist jedoch zu beachten, dass einige neu hinzugefügte Modi nur in RoundingMode existieren.

### Rückgabewerte

Der auf die angegebene `precision` gerundete Wert als Float.

### Fehler/Exceptions

Wenn `mode` ungültig ist, löst die Funktion einen ValueError aus. Vor PHP 8.4.0 wurde bei einem ungültigen Modus automatisch `PHP_ROUND_HALF_UP` verwendet.

### Changelog

Version | Beschreibung
--- | ---
8.4.0 | Vier neue Rundungsmodi wurden hinzugefügt.
8.4.0 | Es wird nun ein ValueError ausgelöst, wenn `mode` ungültig ist.
8.0.0 | `num` akzeptiert keine internen Objekte mehr, die eine numerische Konvertierung unterstützen.

### Beispiele

Beispiel #1 round()-Beispiele

    <?php
    var_dump(round(3.4));
    var_dump(round(3.5));
    var_dump(round(3.6));
    var_dump(round(3.6, 0));
    var_dump(round(5.045, 2));
    var_dump(round(5.055, 2));
    var_dump(round(345, -2));
    var_dump(round(345, -3));
    var_dump(round(678, -2));
    var_dump(round(678, -3));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(3)
    float(4)
    float(4)
    float(4)
    float(5.05)
    float(5.06)
    float(300)
    float(0)
    float(700)
    float(1000)

Beispiel #2 Wie `precision` eine Gleitkommazahl betrifft

    <?php
    $number = 135.79;

    var_dump(round($number, 3));
    var_dump(round($number, 2));
    var_dump(round($number, 1));
    var_dump(round($number, 0));
    var_dump(round($number, -1));
    var_dump(round($number, -2));
    var_dump(round($number, -3));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    float(135.79)
    float(135.79)
    float(135.8)
    float(136)
    float(140)
    float(100)
    float(0)

Beispiel #3 `mode`-Beispiele

    <?php
    echo 'Rundundsmodi mit 9.5' . PHP_EOL;
    var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));
    var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));

    echo PHP_EOL;
    echo 'Rundundsmodi mit 8.5' . PHP_EOL;
    var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));
    var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Rundundsmodi mit 9.5
    float(10)
    float(9)
    float(10)
    float(9)

    Rundundsmodi mit 8.5
    float(9)
    float(8)
    float(8)
    float(9)

Beispiel #4 Beispiele für `mode` mit `precision`

    <?php
    echo 'Verwendung von PHP_ROUND_HALF_UP mit einer Dezimalstelle Genauigkeit' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));

    echo PHP_EOL;
    echo 'Verwendung von PHP_ROUND_HALF_DOWN mit einer Dezimalstelle Genauigkeit' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));

    echo PHP_EOL;
    echo 'Verwendung von PHP_ROUND_HALF_EVEN mit einer Dezimalstelle Genauigkeit' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));

    echo PHP_EOL;
    echo 'Verwendung von PHP_ROUND_HALF_ODD mit einer Dezimalstelle Genauigkeit' . PHP_EOL;
    var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
    var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Verwendung von PHP_ROUND_HALF_UP mit einer Dezimalstelle Genauigkeit
    float(1.6)
    float(-1.6)

    Verwendung von PHP_ROUND_HALF_DOWN mit einer Dezimalstelle Genauigkeit
    float(1.5)
    float(-1.5)

    Verwendung von PHP_ROUND_HALF_EVEN mit einer Dezimalstelle Genauigkeit
    float(1.6)
    float(-1.6)

    Verwendung von PHP_ROUND_HALF_ODD mit einer Dezimalstelle Genauigkeit
    float(1.5)
    float(-1.5)

Beispiel #5 Beispiel für die Verwendung von RoundingMode

    <?php
    foreach (RoundingMode::cases() as $mode) {
        foreach ([
            8.5,
            9.5,
            -3.5,
        ] as $number) {
            printf("%-17s: %+.17g -> %+.17g\n", $mode->name, $number, round($number, 0, $mode));
        }
        echo "\n";
    }
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    HalfAwayFromZero : +8.5 -> +9
    HalfAwayFromZero : +9.5 -> +10
    HalfAwayFromZero : -3.5 -> -4

    HalfTowardsZero  : +8.5 -> +8
    HalfTowardsZero  : +9.5 -> +9
    HalfTowardsZero  : -3.5 -> -3

    HalfEven         : +8.5 -> +8
    HalfEven         : +9.5 -> +10
    HalfEven         : -3.5 -> -4

    HalfOdd          : +8.5 -> +9
    HalfOdd          : +9.5 -> +9
    HalfOdd          : -3.5 -> -3

    TowardsZero      : +8.5 -> +8
    TowardsZero      : +9.5 -> +9
    TowardsZero      : -3.5 -> -3

    AwayFromZero     : +8.5 -> +9
    AwayFromZero     : +9.5 -> +10
    AwayFromZero     : -3.5 -> -4

    NegativeInfinity : +8.5 -> +8
    NegativeInfinity : +9.5 -> +9
    NegativeInfinity : -3.5 -> -4

    PositiveInfinity : +8.5 -> +9
    PositiveInfinity : +9.5 -> +10
    PositiveInfinity : -3.5 -> -3

### Siehe auch

- ceil() - Rundet Brüche auf
- floor() - Rundet Brüche ab
- number_format() - Formatiert eine Zahl mit Tausender-Trennzeichen

# sin

(PHP 4, PHP 5, PHP 7, PHP 8)

sin — Sinus

### Beschreibung

function sin(float `$num`): float

sin() berechnet den Sinus des Winkels `num`. Der Parameter `num` ist im Bogenmaß.

### Parameter-Liste

`num`

  Ein Winkel in Bogenmaß.

### Rückgabewerte

Der Sinus von `num`.

### Beispiele

Beispiel #1 sin()-Beispiel

    <?php
    // Die Stellenzahl des Ergebnisses hängt von der 'precision'-Einstellung ab
    echo sin(deg2rad(60)), PHP_EOL;  //  0.866025403 ...
    echo sin(60), PHP_EOL;           // -0.304810621 ...
    ?>

### Siehe auch

- asin() - Arkussinus
- sinh() - Sinus hyperbolikus
- cos() - Kosinus
- tan() - Tangens
- deg2rad() - Rechnet einen Winkel von Grad in Bogenmaß um

# sinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sinh — Sinus hyperbolikus

### Beschreibung

function sinh(float `$num`): float

Berechnet den Sinus hyperbolikus des Parameters `num`, welcher als `(exp($num) - exp(-$num))/2` definiert ist.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der Sinus hyperbolikus von `num`.

### Siehe auch

- sin() - Sinus
- asinh() - Areasinus hyperbolikus
- cosh() - Kosinus hyperbolikus
- tanh() - Tangens hyperbolikus

# sqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

sqrt — Quadratwurzel

### Beschreibung

function sqrt(float `$num`): float

Berechnet die Quadratwurzel des Parameters `num`.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Die Quadratwurzel des Parameters `num` oder der spezielle Wert `NAN` für negative Zahlen.

### Beispiele

Beispiel #1 sqrt()-Beispiel

    <?php
    // Die Anzahl der Nachkommastellen hängt von der 'precision'-Einstellung ab
    echo sqrt(9), PHP_EOL; // 3
    echo sqrt(10), PHP_EOL; // 3.16227766 ...
    ?>

### Siehe auch

- pow() - Potenzfunktion
- `M_SQRTPI` - `sqrt(pi)`
- `M_2_SQRTPI` - `2/sqrt(pi)`
- `M_SQRT2` - `sqrt(2)`
- `M_SQRT3` - `sqrt(3)`
- `M_SQRT1_2` - `1/sqrt(2)`

# tan

(PHP 4, PHP 5, PHP 7, PHP 8)

tan — Tangens

### Beschreibung

function tan(float `$num`): float

tan() berechnet den Tangens des Winkels `num`. Der Parameter `num` ist im Bogenmaß.

### Parameter-Liste

`num`

  Ein Winkel in Bogenmaß.

### Rückgabewerte

Der Tangens des Winkels `num`.

### Beispiele

Beispiel #1 tan()-Beispiel

    <?php

    echo tan(M_PI_4); // 1

    ?>

### Siehe auch

- atan() - Arkustangens
- atan2() - Arkustangens-Variante mit zwei Parametern
- sin() - Sinus
- cos() - Kosinus
- tanh() - Tangens hyperbolikus
- deg2rad() - Rechnet einen Winkel von Grad in Bogenmaß um

# tanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

tanh — Tangens hyperbolikus

### Beschreibung

function tanh(float `$num`): float

Berechnet den Tangens hyperbolikus des Parameters `num`, welcher als `sinh($num)/cosh($num)` definiert ist.

### Parameter-Liste

`num`

  Der zu verarbeitende Wert.

### Rückgabewerte

Der Tangens hyperbolikus von `num`.

### Siehe auch

- tan() - Tangens
- atanh() - Areatangens hyperbolikus
- sinh() - Sinus hyperbolikus
- cosh() - Kosinus hyperbolikus

## Inhaltsverzeichnis

- abs — Absolutwert bzw. Betrag
- acos — Arkuskosinus
- acosh — Areakosinus hyperbolikus
- asin — Arkussinus
- asinh — Areasinus hyperbolikus
- atan — Arkustangens
- atan2 — Arkustangens-Variante mit zwei Parametern
- atanh — Areatangens hyperbolikus
- base_convert — Wandelt einen numerischen Wert zwischen verschiedenen Zahlensystemen um
- bindec — Wandelt von binär zu dezimal um
- ceil — Rundet Brüche auf
- cos — Kosinus
- cosh — Kosinus hyperbolikus
- decbin — Wandelt von dezimal zu binär um
- dechex — Wandelt von dezimal zu hexadezimal um
- decoct — Wandelt von dezimal zu oktal um
- deg2rad — Rechnet einen Winkel von Grad in Bogenmaß um
- exp — Berechnet den Exponenten von e
- expm1 — Berechnet exp(Zahl) - 1 mit guter Genauigkeit, auch wenn Zahl nahe bei Null liegt
- fdiv — Dividiert zwei Zahlen gemäß IEEE 754
- floor — Rundet Brüche ab
- fmod — Rest einer Gleitkommadivision (Modulus)
- fpow — Raise one number to the power of another, according to IEEE 754
- hexdec — Wandelt von hexadezimal zu dezimal um
- hypot — Berechnet die Länge der Hypotenuse eines rechtwinkligen Dreiecks
- intdiv — Integer-Division
- is_finite — Prüft, ob eine Gleitkommazahl endlich ist
- is_infinite — Prüft, ob eine Gleitkommazahl unendlich ist
- is_nan — Prüft, ob eine Gleitkommazahl NAN ist
- log — Natürlicher Logarithmus
- log10 — Dekadischer Logarithmus (Logarithmus zur Basis 10)
- log1p — Berechnet log(1 + Zahl) mit guter Genauigkeit, auch wenn Zahl nahe bei Null liegt
- max — Bestimmt den Maximalwert
- min — Bestimmt den Minimalwert
- octdec — Wandelt von oktal zu dezimal um
- pi — Liefert den Wert von Pi
- pow — Potenzfunktion
- rad2deg — Rechnet einen Winkel vom Bogenmaß in Grad um
- round — Rundet einen Gleitkommawert
- sin — Sinus
- sinh — Sinus hyperbolikus
- sqrt — Quadratwurzel
- tan — Tangens
- tanh — Tangens hyperbolikus

- Vordefinierte Konstanten
- RoundingMode — The RoundingMode Enum
- Mathematische Funktionen
  - abs — Absolutwert bzw. Betrag
  - acos — Arkuskosinus
  - acosh — Areakosinus hyperbolikus
  - asin — Arkussinus
  - asinh — Areasinus hyperbolikus
  - atan — Arkustangens
  - atan2 — Arkustangens-Variante mit zwei Parametern
  - atanh — Areatangens hyperbolikus
  - base_convert — Wandelt einen numerischen Wert zwischen verschiedenen Zahlensystemen um
  - bindec — Wandelt von binär zu dezimal um
  - ceil — Rundet Brüche auf
  - cos — Kosinus
  - cosh — Kosinus hyperbolikus
  - decbin — Wandelt von dezimal zu binär um
  - dechex — Wandelt von dezimal zu hexadezimal um
  - decoct — Wandelt von dezimal zu oktal um
  - deg2rad — Rechnet einen Winkel von Grad in Bogenmaß um
  - exp — Berechnet den Exponenten von e
  - expm1 — Berechnet exp(Zahl) - 1 mit guter Genauigkeit, auch wenn Zahl nahe bei Null liegt
  - fdiv — Dividiert zwei Zahlen gemäß IEEE 754
  - floor — Rundet Brüche ab
  - fmod — Rest einer Gleitkommadivision (Modulus)
  - fpow — Raise one number to the power of another, according to IEEE 754
  - hexdec — Wandelt von hexadezimal zu dezimal um
  - hypot — Berechnet die Länge der Hypotenuse eines rechtwinkligen Dreiecks
  - intdiv — Integer-Division
  - is_finite — Prüft, ob eine Gleitkommazahl endlich ist
  - is_infinite — Prüft, ob eine Gleitkommazahl unendlich ist
  - is_nan — Prüft, ob eine Gleitkommazahl NAN ist
  - log — Natürlicher Logarithmus
  - log10 — Dekadischer Logarithmus (Logarithmus zur Basis 10)
  - log1p — Berechnet log(1 + Zahl) mit guter Genauigkeit, auch wenn Zahl nahe bei Null liegt
  - max — Bestimmt den Maximalwert
  - min — Bestimmt den Minimalwert
  - octdec — Wandelt von oktal zu dezimal um
  - pi — Liefert den Wert von Pi
  - pow — Potenzfunktion
  - rad2deg — Rechnet einen Winkel vom Bogenmaß in Grad um
  - round — Rundet einen Gleitkommawert
  - sin — Sinus
  - sinh — Sinus hyperbolikus
  - sqrt — Quadratwurzel
  - tan — Tangens
  - tanh — Tangens hyperbolikus

# Statistics

# Einführung

Warnung

Diese Erweiterung wird nicht mehr gepflegt.

This is the statistics extension. It contains few dozens of functions useful for statistical computations. It is a wrapper around 2 scientific libraries, namely DCDFLIB (Library of C routines for Cumulative Distributions Functions, Inverses, and Other parameters) by B. Brown & J. Lavato and RANDLIB by Barry Brown, James Lavato & Kathy Russell. Includes CD and PD functions.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

No external libraries are needed. The extension comes bundled with the libraries used.

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Diese Erweiterung wird als nicht mehr gepflegt betrachtet und es gibt dort keine Aktivität mehr. Der Quellcode für diese Erweiterung steht jedoch weiterhin innerhalb des PECL SVN hier zur Verfügung: » https://pecl.php.net/package/stats.

Windows-Binaries (DLL-Dateien) für diese PECL-Erweiterung sind auf der PECL-Website erhältlich.

# Statistic Funktionen

# stats_absolute_deviation

(PECL stats >= 1.0.0)

stats_absolute_deviation — Returns the absolute deviation of an array of values

### Beschreibung

function stats_absolute_deviation(array `$a`): float

Returns the absolute deviation of the values in `a`.

### Parameter-Liste

`a`
  The input array

### Rückgabewerte

Returns the absolute deviation of the values in `a`, or `false` if `a` is empty or is not an array.

# stats_cdf_beta

(PECL stats >= 1.0.0)

stats_cdf_beta — Calculates any one parameter of the beta distribution given values for the others

### Beschreibung

function stats_cdf_beta(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the beta distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, alpha, and beta denotes cumulative distribution function, the value of the random variable, and shape parameters of the beta distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | alpha | beta
2 | x | CDF | alpha | beta
3 | alpha | x | CDF | beta
4 | beta | x | CDF | alpha

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, alpha, or beta, determined by `which`.

# stats_cdf_binomial

(PECL stats >= 1.0.0)

stats_cdf_binomial — Calculates any one parameter of the binomial distribution given values for the others

### Beschreibung

function stats_cdf_binomial(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the binomial distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, n, and p denotes cumulative distribution function, the number of successes, the number of trials, and the success rate for each trial, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | n | p
2 | x | CDF | n | p
3 | n | x | CDF | p
4 | p | x | CDF | n

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, n, or p, determined by `which`.

# stats_cdf_cauchy

(PECL stats >= 1.0.0)

stats_cdf_cauchy — Calculates any one parameter of the Cauchy distribution given values for the others

### Beschreibung

function stats_cdf_cauchy(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the Cauchy distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, x0, and gamma denotes cumulative distribution function, the value of the random variable, the location and the scale parameter of the Cauchy distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | x0 | gamma
2 | x | CDF | x0 | gamma
3 | x0 | x | CDF | gamma
4 | gamma | x | CDF | x0

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, x0, or gamma, determined by `which`.

# stats_cdf_chisquare

(PECL stats >= 1.0.0)

stats_cdf_chisquare — Calculates any one parameter of the chi-square distribution given values for the others

### Beschreibung

function stats_cdf_chisquare(float `$par1`, float `$par2`, int `$which`): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the chi-square distribution. The kind of the return value and parameters (`par1` and `par2`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, and k denotes cumulative distribution function, the value of the random variable, and the degree of freedom of the chi-square distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | k
2 | x | CDF | k
3 | k | x | CDF

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, or k, determined by `which`.

# stats_cdf_exponential

(PECL stats >= 1.0.0)

stats_cdf_exponential — Calculates any one parameter of the exponential distribution given values for the others

### Beschreibung

function stats_cdf_exponential(float `$par1`, float `$par2`, int `$which`): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the exponential distribution. The kind of the return value and parameters (`par1` and `par2`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, and lambda denotes cumulative distribution function, the value of the random variable, and the rate parameter of the exponential distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, or lambda, determined by `which`.

# stats_cdf_f

(PECL stats >= 1.0.0)

stats_cdf_f — Calculates any one parameter of the F distribution given values for the others

### Beschreibung

function stats_cdf_f(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the F distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, d1, and d2 denotes cumulative distribution function, the value of the random variable, and the degree of freedoms of the F distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | d1 | d2
2 | x | CDF | d1 | d2
3 | d1 | x | CDF | d2
4 | d2 | x | CDF | d1

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, d1, or d2, determined by `which`.

# stats_cdf_gamma

(PECL stats >= 1.0.0)

stats_cdf_gamma — Calculates any one parameter of the gamma distribution given values for the others

### Beschreibung

function stats_cdf_gamma(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the gamma distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, k, and theta denotes cumulative distribution function, the value of the random variable, and the shape and the scale parameter of the gamma distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | k | theta
2 | x | CDF | k | theta
3 | k | x | CDF | theta
4 | theta | x | CDF | k

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, k, or theta, determined by `which`.

# stats_cdf_laplace

(PECL stats >= 1.0.0)

stats_cdf_laplace — Calculates any one parameter of the Laplace distribution given values for the others

### Beschreibung

function stats_cdf_laplace(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the Laplace distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, mu, and b denotes cumulative distribution function, the value of the random variable, and the location and the scale parameter of the Laplace distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | mu | b
2 | x | CDF | mu | b
3 | mu | x | CDF | b
4 | b | x | CDF | mu

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, mu, or b, determined by `which`.

# stats_cdf_logistic

(PECL stats >= 1.0.0)

stats_cdf_logistic — Calculates any one parameter of the logistic distribution given values for the others

### Beschreibung

function stats_cdf_logistic(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the logistic distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, mu, and s denotes cumulative distribution function, the value of the random variable, and the location and the scale parameter of the logistic distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | mu | s
2 | x | CDF | mu | s
3 | mu | x | CDF | s
4 | s | x | CDF | mu

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, mu, or s, determined by `which`.

# stats_cdf_negative_binomial

(PECL stats >= 1.0.0)

stats_cdf_negative_binomial — Calculates any one parameter of the negative binomial distribution given values for the others

### Beschreibung

function stats_cdf_negative_binomial(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the negative binomial distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, r, and p denotes cumulative distribution function, the number of failure, the number of success, and the success rate for each trial, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | r | p
2 | x | CDF | r | p
3 | r | x | CDF | p
4 | p | x | CDF | r

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, r, or p, determined by `which`.

# stats_cdf_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_cdf_noncentral_chisquare — Calculates any one parameter of the non-central chi-square distribution given values for the others

### Beschreibung

function stats_cdf_noncentral_chisquare(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the non-central chi-square distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, k, and lambda denotes cumulative distribution function, the value of the random variable, the degree of freedom and the non-centrality parameter of the distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, k, or lambda, determined by `which`.

# stats_cdf_noncentral_f

(PECL stats >= 1.0.0)

stats_cdf_noncentral_f — Calculates any one parameter of the non-central F distribution given values for the others

### Beschreibung

function stats_cdf_noncentral_f(
float `$par1`,
float `$par2`,
float `$par3`,
float `$par4`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the non-central F distribution. The kind of the return value and parameters (`par1`, `par2`, `par3`, and `par4`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, nu1, nu2, and lambda denotes cumulative distribution function, the value of the random variable, the degree of freedoms and the non-centrality parameter of the distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3` | `par4`
--- | --- | --- | --- | --- | ---
1 | CDF | x | nu1 | nu2 | lambda
2 | x | CDF | nu1 | nu2 | lambda
3 | nu1 | x | CDF | nu2 | lambda
4 | nu2 | x | CDF | nu1 | lambda
5 | lambda | x | CDF | nu1 | nu2

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`par4`
  The fourth parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, nu1, nu2, or lambda, determined by `which`.

# stats_cdf_noncentral_t

(PECL stats >= 1.0.0)

stats_cdf_noncentral_t — Calculates any one parameter of the non-central t-distribution give values for the others

### Beschreibung

function stats_cdf_noncentral_t(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the non-central t-distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, nu, and mu denotes cumulative distribution function, the value of the random variable, the degrees of freedom and the non-centrality parameter of the distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | nu | mu
2 | x | CDF | nu | mu
3 | nu | x | CDF | mu
4 | mu | x | CDF | nu

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, nu, or mu, determined by `which`.

# stats_cdf_normal

(PECL stats >= 1.0.0)

stats_cdf_normal — Calculates any one parameter of the normal distribution given values for the others

### Beschreibung

function stats_cdf_normal(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the normal distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, mu, and sigma denotes cumulative distribution function, the value of the random variable, the mean and the standard deviation of the normal distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | mu | sigma
2 | x | CDF | mu | sigma
3 | mu | x | CDF | sigma
4 | sigma | x | CDF | mu

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, mu, or sigma, determined by `which`.

# stats_cdf_poisson

(PECL stats >= 1.0.0)

stats_cdf_poisson — Calculates any one parameter of the Poisson distribution given values for the others

### Beschreibung

function stats_cdf_poisson(float `$par1`, float `$par2`, int `$which`): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the Poisson distribution. The kind of the return value and parameters (`par1` and `par2`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, and lambda denotes cumulative distribution function, the value of the random variable, and the parameter of the Poisson distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | lambda
2 | x | CDF | lambda
3 | lambda | x | CDF

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, or lambda, determined by `which`.

# stats_cdf_t

(PECL stats >= 1.0.0)

stats_cdf_t — Calculates any one parameter of the t-distribution given values for the others

### Beschreibung

function stats_cdf_t(float `$par1`, float `$par2`, int `$which`): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the t-distribution. The kind of the return value and parameters (`par1` and `par2`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, and nu denotes cumulative distribution function, the value of the random variable, and the degrees of freedom of the t-distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2`
--- | --- | --- | ---
1 | CDF | x | nu
2 | x | CDF | nu
3 | nu | x | CDF

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, or nu, determined by `which`.

# stats_cdf_uniform

(PECL stats >= 1.0.0)

stats_cdf_uniform — Calculates any one parameter of the uniform distribution given values for the others

### Beschreibung

function stats_cdf_uniform(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the uniform distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, a, and b denotes cumulative distribution function, the value of the random variable, the lower bound and the higher bound of the uniform distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | a | b
2 | x | CDF | a | b
3 | a | x | CDF | b
4 | b | x | CDF | a

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, a, or b, determined by `which`.

# stats_cdf_weibull

(PECL stats >= 1.0.0)

stats_cdf_weibull — Calculates any one parameter of the Weibull distribution given values for the others

### Beschreibung

function stats_cdf_weibull(
float `$par1`,
float `$par2`,
float `$par3`,
int `$which`
): float

Returns the cumulative distribution function, its inverse, or one of its parameters, of the Weibull distribution. The kind of the return value and parameters (`par1`, `par2`, and `par3`) are determined by `which`.

The following table lists the return value and parameters by `which`. CDF, x, k, and lambda denotes cumulative distribution function, the value of the random variable, the shape and the scale parameter of the Weibull distribution, respectively.

Return value and parameters
`which` | Return value | `par1` | `par2` | `par3`
--- | --- | --- | --- | ---
1 | CDF | x | k | lambda
2 | x | CDF | k | lambda
3 | k | x | CDF | lambda
4 | lambda | x | CDF | k

### Parameter-Liste

`par1`
  The first parameter
`par2`
  The second parameter
`par3`
  The third parameter
`which`
  The flag to determine what to be calculated

### Rückgabewerte

Returns CDF, x, k, or lambda, determined by `which`.

# stats_covariance

(PECL stats >= 1.0.0)

stats_covariance — Computes the covariance of two data sets

### Beschreibung

function stats_covariance(array `$a`, array `$b`): float

Returns the covariance of `a` and `b`.

### Parameter-Liste

`a`
  The first array
`b`
  The second array

### Rückgabewerte

Returns the covariance of `a` and `b`, or `false` on failure.

# stats_dens_beta

(PECL stats >= 1.0.0)

stats_dens_beta — Probability density function of the beta distribution

### Beschreibung

function stats_dens_beta(float `$x`, float `$a`, float `$b`): float

Returns the probability density at `x`, where the random variable follows the beta distribution of which the shape parameters are `a` and `b`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`a`
  The shape parameter of the distribution
`b`
  The shape parameter of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_cauchy

(PECL stats >= 1.0.0)

stats_dens_cauchy — Probability density function of the Cauchy distribution

### Beschreibung

function stats_dens_cauchy(float `$x`, float `$ave`, float `$stdev`): float

Returns the probability density at `x`, where the random variable follows the Cauchy distribution whose location and scale are `ave` and `stdev`, respectively.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`ave`
  The location parameter of the distribution
`stdev`
  The scale parameter of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_chisquare

(PECL stats >= 1.0.0)

stats_dens_chisquare — Probability density function of the chi-square distribution

### Beschreibung

function stats_dens_chisquare(float `$x`, float `$dfr`): float

Returns the probability density at `x`, where the random variable follows the chi-square distribution of which the degree of freedom is `dfr`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`dfr`
  The degree of freedom of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_exponential

(PECL stats >= 1.0.0)

stats_dens_exponential — Probability density function of the exponential distribution

### Beschreibung

function stats_dens_exponential(float `$x`, float `$scale`): float

Returns the probability density at `x`, where the random variable follows the exponential distribution of which the scale is `scale`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`scale`
  The scale of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_f

(PECL stats >= 1.0.0)

stats_dens_f — Probability density function of the F distribution

### Beschreibung

function stats_dens_f(float `$x`, float `$dfr1`, float `$dfr2`): float

Returns the probability density at `x`, where the random variable follows the F distribution of which the degree of freedoms are `dfr1` and `dfr2`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`dfr1`
  The degree of freedom of the distribution
`dfr2`
  The degree of freedom of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_gamma

(PECL stats >= 1.0.0)

stats_dens_gamma — Probability density function of the gamma distribution

### Beschreibung

function stats_dens_gamma(float `$x`, float `$shape`, float `$scale`): float

Returns the probability density at `x`, where the random variable follows the gamma distribution of which the shape parameter is `shape` and the scale parameter is `scale`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`shape`
  The shape parameter of the distribution
`scale`
  The scale parameter of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_laplace

(PECL stats >= 1.0.0)

stats_dens_laplace — Probability density function of the Laplace distribution

### Beschreibung

function stats_dens_laplace(float `$x`, float `$ave`, float `$stdev`): float

Returns the probability density at `x`, where the random variable follows the Laplace distribution of which the location parameter is `ave` and the scale parameter is `stdev`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`ave`
  The location parameter of the distribution
`stdev`
  The shape parameter of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_logistic

(PECL stats >= 1.0.0)

stats_dens_logistic — Probability density function of the logistic distribution

### Beschreibung

function stats_dens_logistic(float `$x`, float `$ave`, float `$stdev`): float

Returns the probability density at `x`, where the random variable follows the logistic distribution of which the location parameter is `ave` and the scale parameter is `stdev`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`ave`
  The location parameter of the distribution
`stdev`
  The shape parameter of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_normal

(PECL stats >= 1.0.0)

stats_dens_normal — Probability density function of the normal distribution

### Beschreibung

function stats_dens_normal(float `$x`, float `$ave`, float `$stdev`): float

Returns the probability density at `x`, where the random variable follows the normal distribution of which the mean is `ave` and the standard deviation is `stdev`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`ave`
  The mean of the distribution
`stdev`
  The standard deviation of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_pmf_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_binomial — Probability mass function of the binomial distribution

### Beschreibung

function stats_dens_pmf_binomial(float `$x`, float `$n`, float `$pi`): float

Returns the probability mass at `x`, where the random variable follows the binomial distribution of which the number of trials is `n` and the success rate is `pi`.

### Parameter-Liste

`x`
  The value at which the probability mass is calculated
`n`
  The number of trials of the distribution
`pi`
  The success rate of the distribution

### Rückgabewerte

The probability mass at `x` or `false` for failure.

# stats_dens_pmf_hypergeometric

(PECL stats >= 1.0.0)

stats_dens_pmf_hypergeometric — Probability mass function of the hypergeometric distribution

### Beschreibung

function stats_dens_pmf_hypergeometric(
float `$n1`,
float `$n2`,
float `$N1`,
float `$N2`
): float

Returns the probability mass at `n1`, where the random variable follows the hypergeometric distribution of which the number of failure is `n2`, the number of success samples is `N1`, and the number of failure samples is `N2`.

### Parameter-Liste

`n1`
  The number of success, at which the probability mass is calculated
`n2`
  The number of failure of the distribution
`N1`
  The number of success samples of the distribution
`N2`
  The number of failure samples of the distribution

### Rückgabewerte

The probability mass at `n1` or `false` for failure.

# stats_dens_pmf_negative_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_negative_binomial — Probability mass function of the negative binomial distribution

### Beschreibung

function stats_dens_pmf_negative_binomial(float `$x`, float `$n`, float `$pi`): float

Returns the probability mass at `x`, where the random variable follows the negative binomial distribution of which the number of the success is `n` and the success rate is `pi`.

### Parameter-Liste

`x`
  The value at which the probability mass is calculated
`n`
  The number of the success of the distribution
`pi`
  The success rate of the distribution

### Rückgabewerte

The probability mass at `x` or `false` for failure.

# stats_dens_pmf_poisson

(PECL stats >= 1.0.0)

stats_dens_pmf_poisson — Probability mass function of the Poisson distribution

### Beschreibung

function stats_dens_pmf_poisson(float `$x`, float `$lb`): float

Returns the probability mass at `x`, where the random variable follows the Poisson distribution whose parameter is `lb`.

### Parameter-Liste

`x`
  The value at which the probability mass is calculated
`lb`
  The parameter of the Poisson distribution

### Rückgabewerte

The probability mass at `x` or `false` for failure.

# stats_dens_t

(PECL stats >= 1.0.0)

stats_dens_t — Probability density function of the t-distribution

### Beschreibung

function stats_dens_t(float `$x`, float `$dfr`): float

Returns the probability density at `x`, where the random variable follows the t-distribution of which the degree of freedom is `dfr`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`dfr`
  The degree of freedom of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_uniform

(PECL stats >= 1.0.0)

stats_dens_uniform — Probability density function of the uniform distribution

### Beschreibung

function stats_dens_uniform(float `$x`, float `$a`, float `$b`): float

Returns the probability density at `x`, where the random variable follows the uniform distribution of which the lower bound is `a` and the upper bound is `b`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`a`
  The lower bound of the distribution
`b`
  The upper bound of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_dens_weibull

(PECL stats >= 1.0.0)

stats_dens_weibull — Probability density function of the Weibull distribution

### Beschreibung

function stats_dens_weibull(float `$x`, float `$a`, float `$b`): float

Returns the probability density at `x`, where the random variable follows the Weibull distribution of which the shape parameter is `a` and the scale parameter is `b`.

### Parameter-Liste

`x`
  The value at which the probability density is calculated
`a`
  The shape parameter of the distribution
`b`
  The scale parameter of the distribution

### Rückgabewerte

The probability density at `x` or `false` for failure.

# stats_harmonic_mean

(PECL stats >= 1.0.0)

stats_harmonic_mean — Returns the harmonic mean of an array of values

### Beschreibung

function stats_harmonic_mean(array `$a`): number

Returns the harmonic mean of the values in `a`.

### Parameter-Liste

`a`
  The input array

### Rückgabewerte

Returns the harmonic mean of the values in `a`, or `false` if `a` is empty or is not an array.

# stats_kurtosis

(PECL stats >= 1.0.0)

stats_kurtosis — Computes the kurtosis of the data in the array

### Beschreibung

function stats_kurtosis(array `$a`): float

Returns the kurtosis of the values in `a`.

### Parameter-Liste

`a`
  The input array

### Rückgabewerte

Returns the kurtosis of the values in `a`, or `false` if `a` is empty or is not an array.

# stats_rand_gen_beta

(PECL stats >= 1.0.0)

stats_rand_gen_beta — Generates a random deviate from the beta distribution

### Beschreibung

function stats_rand_gen_beta(float `$a`, float `$b`): float

Returns a random deviate from the beta distribution with parameters A and B. The density of the beta is x^(a-1) * (1-x)^(b-1) / B(a,b) for 0 < x <. Method R. C. H. Cheng.

### Parameter-Liste

`a`
  The shape parameter of the beta distribution
`b`
  The shape parameter of the beta distribution

### Rückgabewerte

A random deviate

# stats_rand_gen_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_chisquare — Generates a random deviate from the chi-square distribution

### Beschreibung

function stats_rand_gen_chisquare(float `$df`): float

Returns a random deviate from the chi-square distribution where the degrees of freedom is `df`.

### Parameter-Liste

`df`
  The degrees of freedom

### Rückgabewerte

A random deviate

# stats_rand_gen_exponential

(PECL stats >= 1.0.0)

stats_rand_gen_exponential — Generates a random deviate from the exponential distribution

### Beschreibung

function stats_rand_gen_exponential(float `$av`): float

Returns a random deviate from the exponential distribution of which the scale is `av`.

### Parameter-Liste

`av`
  The scale parameter

### Rückgabewerte

A random deviate

# stats_rand_gen_f

(PECL stats >= 1.0.0)

stats_rand_gen_f — Generates a random deviate from the F distribution

### Beschreibung

function stats_rand_gen_f(float `$dfn`, float `$dfd`): float

Generates a random deviate from the F (variance ratio) distribution with "dfn" degrees of freedom in the numerator and "dfd" degrees of freedom in the denominator. Method : directly generates ratio of chisquare variates.

### Parameter-Liste

`dfn`

  The degrees of freedom in the numerator

`dfd`

  The degrees of freedom in the denominator

### Rückgabewerte

A random deviate

# stats_rand_gen_funiform

(PECL stats >= 1.0.0)

stats_rand_gen_funiform — Generates uniform float between low (exclusive) and high (exclusive)

### Beschreibung

function stats_rand_gen_funiform(float `$low`, float `$high`): float

Returns a random deviate from the uniform distribution from `low` to `high`.

### Parameter-Liste

`low`
  The lower bound (exclusive)
`high`
  The upper bound (exclusive)

### Rückgabewerte

A random deviate

# stats_rand_gen_gamma

(PECL stats >= 1.0.0)

stats_rand_gen_gamma — Generates a random deviate from the gamma distribution

### Beschreibung

function stats_rand_gen_gamma(float `$a`, float `$r`): float

Generates a random deviate from the gamma distribution whose density is (A**R)/Gamma(R) * X**(R-1) * Exp(-A*X).

### Parameter-Liste

`a`
  location parameter of Gamma distribution (`a` > 0).
`r`
  shape parameter of Gamma distribution (`r` > 0).

### Rückgabewerte

A random deviate

# stats_rand_gen_ibinomial

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial — Generates a random deviate from the binomial distribution

### Beschreibung

function stats_rand_gen_ibinomial(int `$n`, float `$pp`): int

Returns a random deviate from the binomial distribution whose number of trials is `n` and whose probability of an event in each trial is `pp`.

### Parameter-Liste

`n`
  The number of trials
`pp`
  The probability of an event in each trial

### Rückgabewerte

A random deviate

# stats_rand_gen_ibinomial_negative

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial_negative — Generates a random deviate from the negative binomial distribution

### Beschreibung

function stats_rand_gen_ibinomial_negative(int `$n`, float `$p`): int

Returns a random deviate from a negative binomial distribution where the number of success is `n` and the success rate is `p`.

### Parameter-Liste

`n`
  The number of success
`p`
  The success rate

### Rückgabewerte

A random deviate, which is the number of failure.

# stats_rand_gen_int

(PECL stats >= 1.0.0)

stats_rand_gen_int — Generates random integer between 1 and 2147483562

### Beschreibung

function stats_rand_gen_int(): int

Returns a random integer between 1 and 2147483562

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

A random integer

# stats_rand_gen_ipoisson

(PECL stats >= 1.0.0)

stats_rand_gen_ipoisson — Generates a single random deviate from a Poisson distribution

### Beschreibung

function stats_rand_gen_ipoisson(float `$mu`): int

Returns a random deviate from the Poisson distribution with parameter `mu`.

### Parameter-Liste

`mu`
  The parameter of the Poisson distribution

### Rückgabewerte

A random deviate

# stats_rand_gen_iuniform

(PECL stats >= 1.0.0)

stats_rand_gen_iuniform — Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)

### Beschreibung

function stats_rand_gen_iuniform(int `$low`, int `$high`): int

Returns a random integer from the discrete uniform distribution between `low` (inclusive) and `high` (inclusive).

### Parameter-Liste

`low`
  The lower bound
`high`
  The upper bound

### Rückgabewerte

A random integer

# stats_rand_gen_noncentral_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_chisquare — Generates a random deviate from the non-central chi-square distribution

### Beschreibung

function stats_rand_gen_noncentral_chisquare(float `$df`, float `$xnonc`): float

Returns a random deviate from the non-central chi-square distribution with degrees of freedom, `df`, and non-centrality parameter, `xnonc`.

### Parameter-Liste

`df`
  The degrees of freedom
`xnonc`
  The non-centrality parameter

### Rückgabewerte

A random deviate

# stats_rand_gen_noncentral_f

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_f — Generates a random deviate from the noncentral F distribution

### Beschreibung

function stats_rand_gen_noncentral_f(float `$dfn`, float `$dfd`, float `$xnonc`): float

Returns a random deviate from the non-central F distribution where the degrees of freedoms are `dfn` (numerator) and `dfd` (denominator), and the non-centrality parameter is `xnonc`.

### Parameter-Liste

`dfn`
  The degrees of freedom of the numerator
`dfd`
  The degrees of freedom of the denominator
`xnonc`
  The non-centrality parameter

### Rückgabewerte

A random deviate

# stats_rand_gen_noncentral_t

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_t — Generates a single random deviate from a non-central t-distribution

### Beschreibung

function stats_rand_gen_noncentral_t(float `$df`, float `$xnonc`): float

Returns a random deviate from the non-central t-distribution with the degrees of freedom, `df`, and the non-centrality parameter, `xnonc`.

### Parameter-Liste

`df`
  The degrees of freedom
`xnonc`
  The non-centrality parameter

### Rückgabewerte

A random deviate

# stats_rand_gen_normal

(PECL stats >= 1.0.0)

stats_rand_gen_normal — Generates a single random deviate from a normal distribution

### Beschreibung

function stats_rand_gen_normal(float `$av`, float `$sd`): float

Returns a random deviate from the normal distribution with mean, `av`, and standard deviation, `sd`.

### Parameter-Liste

`av`
  The mean of the normal distribution
`sd`
  The standard deviation of the normal distribution

### Rückgabewerte

A random deviate

# stats_rand_gen_t

(PECL stats >= 1.0.0)

stats_rand_gen_t — Generates a single random deviate from a t-distribution

### Beschreibung

function stats_rand_gen_t(float `$df`): float

Returns a random deviate from the t-distribution with the degrees of freedom, `df`.

### Parameter-Liste

`df`
  The degrees of freedom

### Rückgabewerte

A random deviate

# stats_rand_get_seeds

(PECL stats >= 1.0.0)

stats_rand_get_seeds — Get the seed values of the random number generator

### Beschreibung

function stats_rand_get_seeds(): array

Returns the current seed values of the random number generator

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns an array of two integers.

# stats_rand_phrase_to_seeds

(PECL stats >= 1.0.0)

stats_rand_phrase_to_seeds — Generate two seeds for the RGN random number generator

### Beschreibung

function stats_rand_phrase_to_seeds(string `$phrase`): array

Generate two seeds for the random number generator from a `phrase`.

### Parameter-Liste

`phrase`
  The input phrase

### Rückgabewerte

Returns an array of two integers.

# stats_rand_ranf

(PECL stats >= 1.0.0)

stats_rand_ranf — Generates a random floating point number between 0 and 1

### Beschreibung

function stats_rand_ranf(): float

Returns a random floating point number from a uniform distribution between 0 (exclusive) and 1 (exclusive).

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

A random floating point number

# stats_rand_setall

(PECL stats >= 1.0.0)

stats_rand_setall — Set seed values to the random generator

### Beschreibung

function stats_rand_setall(int `$iseed1`, int `$iseed2`): void

Set `iseed1` and `iseed2` as seed values to the random generator used in statistic functions.

### Parameter-Liste

`iseed1`
  The value which is used as the random seed
`iseed2`
  The value which is used as the random seed

### Rückgabewerte

No values are returned.

# stats_skew

(PECL stats >= 1.0.0)

stats_skew — Computes the skewness of the data in the array

### Beschreibung

function stats_skew(array `$a`): float

Returns the skewness of the values in `a`.

### Parameter-Liste

`a`
  The input array

### Rückgabewerte

Returns the skewness of the values in `a`, or `false` if `a` is empty or is not an array.

# stats_standard_deviation

(PECL stats >= 1.0.0)

stats_standard_deviation — Returns the standard deviation

### Beschreibung

function stats_standard_deviation(array `$a`, bool `$sample` = `false`): float

Returns the standard deviation of the values in `a`.

### Parameter-Liste

`a`
  The array of data to find the standard deviation for. Note that all values of the array will be cast to float.
`sample`
  Indicates if `a` represents a sample of the population; defaults to `false`.

### Rückgabewerte

Returns the standard deviation on success; `false` on failure.

### Fehler/Exceptions

Raises an `E_WARNING` when there are fewer than 2 values in `a`.

# stats_stat_binomial_coef

(PECL stats >= 1.0.0)

stats_stat_binomial_coef — Returns a binomial coefficient

### Beschreibung

function stats_stat_binomial_coef(int `$x`, int `$n`): float

Returns the binomial coefficient of `n` choose `x`.

### Parameter-Liste

`x`
  The number of chooses from the set
`n`
  The number of elements in the set

### Rückgabewerte

Returns the binomial coefficient

# stats_stat_correlation

(PECL stats >= 1.0.0)

stats_stat_correlation — Returns the Pearson correlation coefficient of two data sets

### Beschreibung

function stats_stat_correlation(array `$arr1`, array `$arr2`): float

Returns the Pearson correlation coefficient between `arr1` and `arr2`.

### Parameter-Liste

`arr1`
  The first array
`arr2`
  The second array

### Rückgabewerte

Returns the Pearson correlation coefficient between `arr1` and `arr2`, or `false` on failure.

# stats_stat_factorial

(PECL stats >= 1.0.0)

stats_stat_factorial — Returns the factorial of an integer

### Beschreibung

function stats_stat_factorial(int `$n`): float

Returns the factorial of an integer, `n`.

### Parameter-Liste

`n`
  An integer

### Rückgabewerte

The factorial of `n`.

# stats_stat_independent_t

(PECL stats >= 1.0.0)

stats_stat_independent_t — Returns the t-value from the independent two-sample t-test

### Beschreibung

function stats_stat_independent_t(array `$arr1`, array `$arr2`): float

Returns the t-value of the independent two-sample t-test between `arr1` and `arr2`.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`arr1`
  The first set of values
`arr2`
  The second set of values

### Rückgabewerte

Returns the t-value, or `false` if failure.

# stats_stat_innerproduct

(PECL stats >= 1.0.0)

stats_stat_innerproduct — Returns the inner product of two vectors

### Beschreibung

function stats_stat_innerproduct(array `$arr1`, array `$arr2`): float

Returns the inner product of `arr1` and `arr2`.

### Parameter-Liste

`arr1`
  The first array
`arr2`
  The second array

### Rückgabewerte

Returns the inner product of `arr1` and `arr2`, or `false` on failure.

# stats_stat_paired_t

(PECL stats >= 1.0.0)

stats_stat_paired_t — Returns the t-value of the dependent t-test for paired samples

### Beschreibung

function stats_stat_paired_t(array `$arr1`, array `$arr2`): float

Returns the t-value of the dependent t-test for paired samples `arr1` and `arr2`.

### Parameter-Liste

`arr1`
  The first samples
`arr2`
  The second samples

### Rückgabewerte

Returns the t-value, or `false` if failure.

# stats_stat_percentile

(PECL stats >= 1.0.0)

stats_stat_percentile — Returns the percentile value

### Beschreibung

function stats_stat_percentile(array `$arr`, float `$perc`): float

Returns the `perc`-th percentile value of the array `arr`.

### Parameter-Liste

`arr`
  The input array
`perc`
  The percentile

### Rückgabewerte

Returns the percentile values of the input array.

# stats_stat_powersum

(PECL stats >= 1.0.0)

stats_stat_powersum — Returns the power sum of a vector

### Beschreibung

function stats_stat_powersum(array `$arr`, float `$power`): float

Returns the sum of the `power`-th power of a vector represented as an array `arr`.

### Parameter-Liste

`arr`
  The input array
`power`
  The power

### Rückgabewerte

Returns the power sum of the input array.

# stats_variance

(PECL stats >= 1.0.0)

stats_variance — Returns the variance

### Beschreibung

function stats_variance(array `$a`, bool `$sample` = `false`): float

Returns the variance of the values in `a`.

### Parameter-Liste

`a`
  The array of data to find the standard deviation for. Note that all values of the array will be cast to float.
`sample`
  Indicates if `a` represents a sample of the population; defaults to `false`.

### Rückgabewerte

Returns the variance on success; `false` on failure.

## Inhaltsverzeichnis

- stats_absolute_deviation — Returns the absolute deviation of an array of values
- stats_cdf_beta — Calculates any one parameter of the beta distribution given values for the others
- stats_cdf_binomial — Calculates any one parameter of the binomial distribution given values for the others
- stats_cdf_cauchy — Calculates any one parameter of the Cauchy distribution given values for the others
- stats_cdf_chisquare — Calculates any one parameter of the chi-square distribution given values for the others
- stats_cdf_exponential — Calculates any one parameter of the exponential distribution given values for the others
- stats_cdf_f — Calculates any one parameter of the F distribution given values for the others
- stats_cdf_gamma — Calculates any one parameter of the gamma distribution given values for the others
- stats_cdf_laplace — Calculates any one parameter of the Laplace distribution given values for the others
- stats_cdf_logistic — Calculates any one parameter of the logistic distribution given values for the others
- stats_cdf_negative_binomial — Calculates any one parameter of the negative binomial distribution given values for the others
- stats_cdf_noncentral_chisquare — Calculates any one parameter of the non-central chi-square distribution given values for the others
- stats_cdf_noncentral_f — Calculates any one parameter of the non-central F distribution given values for the others
- stats_cdf_noncentral_t — Calculates any one parameter of the non-central t-distribution give values for the others
- stats_cdf_normal — Calculates any one parameter of the normal distribution given values for the others
- stats_cdf_poisson — Calculates any one parameter of the Poisson distribution given values for the others
- stats_cdf_t — Calculates any one parameter of the t-distribution given values for the others
- stats_cdf_uniform — Calculates any one parameter of the uniform distribution given values for the others
- stats_cdf_weibull — Calculates any one parameter of the Weibull distribution given values for the others
- stats_covariance — Computes the covariance of two data sets
- stats_dens_beta — Probability density function of the beta distribution
- stats_dens_cauchy — Probability density function of the Cauchy distribution
- stats_dens_chisquare — Probability density function of the chi-square distribution
- stats_dens_exponential — Probability density function of the exponential distribution
- stats_dens_f — Probability density function of the F distribution
- stats_dens_gamma — Probability density function of the gamma distribution
- stats_dens_laplace — Probability density function of the Laplace distribution
- stats_dens_logistic — Probability density function of the logistic distribution
- stats_dens_normal — Probability density function of the normal distribution
- stats_dens_pmf_binomial — Probability mass function of the binomial distribution
- stats_dens_pmf_hypergeometric — Probability mass function of the hypergeometric distribution
- stats_dens_pmf_negative_binomial — Probability mass function of the negative binomial distribution
- stats_dens_pmf_poisson — Probability mass function of the Poisson distribution
- stats_dens_t — Probability density function of the t-distribution
- stats_dens_uniform — Probability density function of the uniform distribution
- stats_dens_weibull — Probability density function of the Weibull distribution
- stats_harmonic_mean — Returns the harmonic mean of an array of values
- stats_kurtosis — Computes the kurtosis of the data in the array
- stats_rand_gen_beta — Generates a random deviate from the beta distribution
- stats_rand_gen_chisquare — Generates a random deviate from the chi-square distribution
- stats_rand_gen_exponential — Generates a random deviate from the exponential distribution
- stats_rand_gen_f — Generates a random deviate from the F distribution
- stats_rand_gen_funiform — Generates uniform float between low (exclusive) and high (exclusive)
- stats_rand_gen_gamma — Generates a random deviate from the gamma distribution
- stats_rand_gen_ibinomial — Generates a random deviate from the binomial distribution
- stats_rand_gen_ibinomial_negative — Generates a random deviate from the negative binomial distribution
- stats_rand_gen_int — Generates random integer between 1 and 2147483562
- stats_rand_gen_ipoisson — Generates a single random deviate from a Poisson distribution
- stats_rand_gen_iuniform — Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)
- stats_rand_gen_noncentral_chisquare — Generates a random deviate from the non-central chi-square distribution
- stats_rand_gen_noncentral_f — Generates a random deviate from the noncentral F distribution
- stats_rand_gen_noncentral_t — Generates a single random deviate from a non-central t-distribution
- stats_rand_gen_normal — Generates a single random deviate from a normal distribution
- stats_rand_gen_t — Generates a single random deviate from a t-distribution
- stats_rand_get_seeds — Get the seed values of the random number generator
- stats_rand_phrase_to_seeds — Generate two seeds for the RGN random number generator
- stats_rand_ranf — Generates a random floating point number between 0 and 1
- stats_rand_setall — Set seed values to the random generator
- stats_skew — Computes the skewness of the data in the array
- stats_standard_deviation — Returns the standard deviation
- stats_stat_binomial_coef — Returns a binomial coefficient
- stats_stat_correlation — Returns the Pearson correlation coefficient of two data sets
- stats_stat_factorial — Returns the factorial of an integer
- stats_stat_independent_t — Returns the t-value from the independent two-sample t-test
- stats_stat_innerproduct — Returns the inner product of two vectors
- stats_stat_paired_t — Returns the t-value of the dependent t-test for paired samples
- stats_stat_percentile — Returns the percentile value
- stats_stat_powersum — Returns the power sum of a vector
- stats_variance — Returns the variance

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Statistic Funktionen
  - stats_absolute_deviation — Returns the absolute deviation of an array of values
  - stats_cdf_beta — Calculates any one parameter of the beta distribution given values for the others
  - stats_cdf_binomial — Calculates any one parameter of the binomial distribution given values for the others
  - stats_cdf_cauchy — Calculates any one parameter of the Cauchy distribution given values for the others
  - stats_cdf_chisquare — Calculates any one parameter of the chi-square distribution given values for the others
  - stats_cdf_exponential — Calculates any one parameter of the exponential distribution given values for the others
  - stats_cdf_f — Calculates any one parameter of the F distribution given values for the others
  - stats_cdf_gamma — Calculates any one parameter of the gamma distribution given values for the others
  - stats_cdf_laplace — Calculates any one parameter of the Laplace distribution given values for the others
  - stats_cdf_logistic — Calculates any one parameter of the logistic distribution given values for the others
  - stats_cdf_negative_binomial — Calculates any one parameter of the negative binomial distribution given values for the others
  - stats_cdf_noncentral_chisquare — Calculates any one parameter of the non-central chi-square distribution given values for the others
  - stats_cdf_noncentral_f — Calculates any one parameter of the non-central F distribution given values for the others
  - stats_cdf_noncentral_t — Calculates any one parameter of the non-central t-distribution give values for the others
  - stats_cdf_normal — Calculates any one parameter of the normal distribution given values for the others
  - stats_cdf_poisson — Calculates any one parameter of the Poisson distribution given values for the others
  - stats_cdf_t — Calculates any one parameter of the t-distribution given values for the others
  - stats_cdf_uniform — Calculates any one parameter of the uniform distribution given values for the others
  - stats_cdf_weibull — Calculates any one parameter of the Weibull distribution given values for the others
  - stats_covariance — Computes the covariance of two data sets
  - stats_dens_beta — Probability density function of the beta distribution
  - stats_dens_cauchy — Probability density function of the Cauchy distribution
  - stats_dens_chisquare — Probability density function of the chi-square distribution
  - stats_dens_exponential — Probability density function of the exponential distribution
  - stats_dens_f — Probability density function of the F distribution
  - stats_dens_gamma — Probability density function of the gamma distribution
  - stats_dens_laplace — Probability density function of the Laplace distribution
  - stats_dens_logistic — Probability density function of the logistic distribution
  - stats_dens_normal — Probability density function of the normal distribution
  - stats_dens_pmf_binomial — Probability mass function of the binomial distribution
  - stats_dens_pmf_hypergeometric — Probability mass function of the hypergeometric distribution
  - stats_dens_pmf_negative_binomial — Probability mass function of the negative binomial distribution
  - stats_dens_pmf_poisson — Probability mass function of the Poisson distribution
  - stats_dens_t — Probability density function of the t-distribution
  - stats_dens_uniform — Probability density function of the uniform distribution
  - stats_dens_weibull — Probability density function of the Weibull distribution
  - stats_harmonic_mean — Returns the harmonic mean of an array of values
  - stats_kurtosis — Computes the kurtosis of the data in the array
  - stats_rand_gen_beta — Generates a random deviate from the beta distribution
  - stats_rand_gen_chisquare — Generates a random deviate from the chi-square distribution
  - stats_rand_gen_exponential — Generates a random deviate from the exponential distribution
  - stats_rand_gen_f — Generates a random deviate from the F distribution
  - stats_rand_gen_funiform — Generates uniform float between low (exclusive) and high (exclusive)
  - stats_rand_gen_gamma — Generates a random deviate from the gamma distribution
  - stats_rand_gen_ibinomial — Generates a random deviate from the binomial distribution
  - stats_rand_gen_ibinomial_negative — Generates a random deviate from the negative binomial distribution
  - stats_rand_gen_int — Generates random integer between 1 and 2147483562
  - stats_rand_gen_ipoisson — Generates a single random deviate from a Poisson distribution
  - stats_rand_gen_iuniform — Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)
  - stats_rand_gen_noncentral_chisquare — Generates a random deviate from the non-central chi-square distribution
  - stats_rand_gen_noncentral_f — Generates a random deviate from the noncentral F distribution
  - stats_rand_gen_noncentral_t — Generates a single random deviate from a non-central t-distribution
  - stats_rand_gen_normal — Generates a single random deviate from a normal distribution
  - stats_rand_gen_t — Generates a single random deviate from a t-distribution
  - stats_rand_get_seeds — Get the seed values of the random number generator
  - stats_rand_phrase_to_seeds — Generate two seeds for the RGN random number generator
  - stats_rand_ranf — Generates a random floating point number between 0 and 1
  - stats_rand_setall — Set seed values to the random generator
  - stats_skew — Computes the skewness of the data in the array
  - stats_standard_deviation — Returns the standard deviation
  - stats_stat_binomial_coef — Returns a binomial coefficient
  - stats_stat_correlation — Returns the Pearson correlation coefficient of two data sets
  - stats_stat_factorial — Returns the factorial of an integer
  - stats_stat_independent_t — Returns the t-value from the independent two-sample t-test
  - stats_stat_innerproduct — Returns the inner product of two vectors
  - stats_stat_paired_t — Returns the t-value of the dependent t-test for paired samples
  - stats_stat_percentile — Returns the percentile value
  - stats_stat_powersum — Returns the power sum of a vector
  - stats_variance — Returns the variance

# Technical Analysis for Traders

# Einführung

The trader extension is a free open source stock library based on TA-Lib. It's dedicated to trading software developers requiring to perform technical analysis of financial market data. Alongside many indicators like ADX, MACD, RSI, Stochastic, TRIX the candlestick pattern recognition and several vector arithmetic and algebraic functions are present.

Calculations can be done in two modes - TA-Lib and Metastock. Changing it using trader_set_compat() will affect the way some trader functions work.

Some trader functions provide different results depending of the "starting point" of the data being involved. This is often referred as a function having memories. An example of such function is the Exponential Moving Average. It is possible to control the unstable period (the amount of data to strip off) using trader_set_unstable_period() function.

Extended documentation about indicators, formulas and implementations in other programming languages can be found under » https://ta-lib.org/.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

The trader extension is based on » TA-Lib. TA-Lib is fully integrated into the extension, therefore no external libraries are needed.

## Installation

Diese » PECL-Erweiterung ist nicht Teil von PHP.

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/trader.

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Trader Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
trader.real_precision | 3 | `INI_ALL` | Since trader 0.2.1
trader.real_round_mode | HALF_DOWN | `INI_ALL` | Since trader 0.3.0

Hier eine kurze Erklärung der Konfigurationsoptionen:

`trader.real_precision` int

  All the values in the returned arrays will be rounded to this precision. However the calculations inside TA-Lib happen with unrounded values.

`trader.real_round_mode` string

  Controls the trader real rounding policy. Valid values are `HALF_UP`, `HALF_DOWN`, `HALF_EVEN` and `HALF_ODD`. The behaviour is identical to the round() function used with the mode argument.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`TRADER_MA_TYPE_SMA` (int)
`TRADER_MA_TYPE_EMA` (int)
`TRADER_MA_TYPE_WMA` (int)
`TRADER_MA_TYPE_DEMA` (int)
`TRADER_MA_TYPE_TEMA` (int)
`TRADER_MA_TYPE_TRIMA` (int)
`TRADER_MA_TYPE_KAMA` (int)
`TRADER_MA_TYPE_MAMA` (int)
`TRADER_MA_TYPE_T3` (int)
`TRADER_REAL_MIN` (float)
`TRADER_REAL_MAX` (float)
`TRADER_FUNC_UNST_ADX` (int)
`TRADER_FUNC_UNST_ADXR` (int)
`TRADER_FUNC_UNST_ATR` (int)
`TRADER_FUNC_UNST_CMO` (int)
`TRADER_FUNC_UNST_DX` (int)
`TRADER_FUNC_UNST_EMA` (int)
`TRADER_FUNC_UNST_HT_DCPERIOD` (int)
`TRADER_FUNC_UNST_HT_DCPHASE` (int)
`TRADER_FUNC_UNST_HT_PHASOR` (int)
`TRADER_FUNC_UNST_HT_SINE` (int)
`TRADER_FUNC_UNST_HT_TRENDLINE` (int)
`TRADER_FUNC_UNST_HT_TRENDMODE` (int)
`TRADER_FUNC_UNST_KAMA` (int)
`TRADER_FUNC_UNST_MAMA` (int)
`TRADER_FUNC_UNST_MFI` (int)
`TRADER_FUNC_UNST_MINUS_DI` (int)
`TRADER_FUNC_UNST_MINUS_DM` (int)
`TRADER_FUNC_UNST_NATR` (int)
`TRADER_FUNC_UNST_PLUS_DI` (int)
`TRADER_FUNC_UNST_PLUS_DM` (int)
`TRADER_FUNC_UNST_RSI` (int)
`TRADER_FUNC_UNST_STOCHRSI` (int)
`TRADER_FUNC_UNST_T3` (int)
`TRADER_FUNC_UNST_ALL` (int)
`TRADER_FUNC_UNST_NONE` (int)
`TRADER_COMPATIBILITY_DEFAULT` (int)
`TRADER_COMPATIBILITY_METASTOCK` (int)
`TRADER_ERR_SUCCESS` (int)
`TRADER_ERR_LIB_NOT_INITIALIZE` (int)
`TRADER_ERR_BAD_PARAM` (int)
`TRADER_ERR_ALLOC_ERR` (int)
`TRADER_ERR_GROUP_NOT_FOUND` (int)
`TRADER_ERR_FUNC_NOT_FOUND` (int)
`TRADER_ERR_INVALID_HANDLE` (int)
`TRADER_ERR_INVALID_PARAM_HOLDER` (int)
`TRADER_ERR_INVALID_PARAM_HOLDER_TYPE` (int)
`TRADER_ERR_INVALID_PARAM_FUNCTION` (int)
`TRADER_ERR_INPUT_NOT_ALL_INITIALIZE` (int)
`TRADER_ERR_OUTPUT_NOT_ALL_INITIALIZE` (int)
`TRADER_ERR_OUT_OF_RANGE_START_INDEX` (int)
`TRADER_ERR_OUT_OF_RANGE_END_INDEX` (int)
`TRADER_ERR_INVALID_LIST_TYPE` (int)
`TRADER_ERR_BAD_OBJECT` (int)
`TRADER_ERR_NOT_SUPPORTED` (int)
`TRADER_ERR_INTERNAL_ERROR` (int)
`TRADER_ERR_UNKNOWN_ERROR` (int)

# Trader Funktionen

# trader_acos

(PECL trader >= 0.2.0)

trader_acos — Vector Trigonometric ACos

### Beschreibung

function trader_acos(array `$real`): array

Calculates the arc cosine for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ad

(PECL trader >= 0.2.0)

trader_ad — Chaikin A/D Line

### Beschreibung

function trader_ad(
array `$high`,
array `$low`,
array `$close`,
array `$volume`
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`volume`

  Volume traded, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_add

(PECL trader >= 0.2.0)

trader_add — Vector Arithmetic Add

### Beschreibung

function trader_add(array `$real0`, array `$real1`): array

Calculates the vector addition of `real0` to `real1` and returns the resulting vector.

### Parameter-Liste

`real0`

  Array of real values.

`real1`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_adosc

(PECL trader >= 0.2.0)

trader_adosc — Chaikin A/D Oscillator

### Beschreibung

function trader_adosc(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`volume`

  Volume traded, array of real values.

`fastPeriod`

  Number of period for the fast MA. Valid range from 2 to 100000.

`slowPeriod`

  Number of period for the slow MA. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_adx

(PECL trader >= 0.2.0)

trader_adx — Average Directional Movement Index

### Beschreibung

function trader_adx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_adxr

(PECL trader >= 0.2.0)

trader_adxr — Average Directional Movement Index Rating

### Beschreibung

function trader_adxr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_apo

(PECL trader >= 0.2.0)

trader_apo — Absolute Price Oscillator

### Beschreibung

function trader_apo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### Parameter-Liste

`real`

  Array of real values.

`fastPeriod`

  Number of period for the fast MA. Valid range from 2 to 100000.

`slowPeriod`

  Number of period for the slow MA. Valid range from 2 to 100000.

`mAType`

  Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_aroon

(PECL trader >= 0.2.0)

trader_aroon — Aroon

### Beschreibung

function trader_aroon(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_aroonosc

(PECL trader >= 0.2.0)

trader_aroonosc — Aroon Oscillator

### Beschreibung

function trader_aroonosc(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_asin

(PECL trader >= 0.2.0)

trader_asin — Vector Trigonometric ASin

### Beschreibung

function trader_asin(array `$real`): array

Calculates the arc sine for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_atan

(PECL trader >= 0.2.0)

trader_atan — Vector Trigonometric ATan

### Beschreibung

function trader_atan(array `$real`): array

Calculates the arc tangent for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_atr

(PECL trader >= 0.2.0)

trader_atr — Average True Range

### Beschreibung

function trader_atr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_avgprice

(PECL trader >= 0.2.0)

trader_avgprice — Average Price

### Beschreibung

function trader_avgprice(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_bbands

(PECL trader >= 0.2.0)

trader_bbands — Bollinger Bands

### Beschreibung

function trader_bbands(
array `$real`,
int `$timePeriod` = ?,
float `$nbDevUp` = ?,
float `$nbDevDn` = ?,
int `$mAType` = ?
): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`nbDevUp`

  Deviation multiplier for upper band. Valid range from TRADER_REAL_MIN to TRADER_REAL_MAX.

`nbDevDn`

  Deviation multiplier for lower band. Valid range from TRADER_REAL_MIN to TRADER_REAL_MAX.

`mAType`

  Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_beta

(PECL trader >= 0.2.0)

trader_beta — Beta

### Beschreibung

function trader_beta(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### Parameter-Liste

`real0`

  Array of real values.

`real1`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_bop

(PECL trader >= 0.2.0)

trader_bop — Balance Of Power

### Beschreibung

function trader_bop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cci

(PECL trader >= 0.2.0)

trader_cci — Commodity Channel Index

### Beschreibung

function trader_cci(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdl2crows

(PECL trader >= 0.2.0)

trader_cdl2crows — Two Crows

### Beschreibung

function trader_cdl2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdl3blackcrows

(PECL trader >= 0.2.0)

trader_cdl3blackcrows — Three Black Crows

### Beschreibung

function trader_cdl3blackcrows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdl3inside

(PECL trader >= 0.2.0)

trader_cdl3inside — Three Inside Up/Down

### Beschreibung

function trader_cdl3inside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdl3linestrike

(PECL trader >= 0.2.0)

trader_cdl3linestrike — Three-Line Strike

### Beschreibung

function trader_cdl3linestrike(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdl3outside

(PECL trader >= 0.2.0)

trader_cdl3outside — Three Outside Up/Down

### Beschreibung

function trader_cdl3outside(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdl3starsinsouth

(PECL trader >= 0.2.0)

trader_cdl3starsinsouth — Three Stars In The South

### Beschreibung

function trader_cdl3starsinsouth(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdl3whitesoldiers

(PECL trader >= 0.2.0)

trader_cdl3whitesoldiers — Three Advancing White Soldiers

### Beschreibung

function trader_cdl3whitesoldiers(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlabandonedbaby

(PECL trader >= 0.2.0)

trader_cdlabandonedbaby — Abandoned Baby

### Beschreibung

function trader_cdlabandonedbaby(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`penetration`

  Percentage of penetration of a candle within another candle.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdladvanceblock

(PECL trader >= 0.2.0)

trader_cdladvanceblock — Advance Block

### Beschreibung

function trader_cdladvanceblock(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlbelthold

(PECL trader >= 0.2.0)

trader_cdlbelthold — Belt-hold

### Beschreibung

function trader_cdlbelthold(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlbreakaway

(PECL trader >= 0.2.0)

trader_cdlbreakaway — Breakaway

### Beschreibung

function trader_cdlbreakaway(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlclosingmarubozu

(PECL trader >= 0.2.0)

trader_cdlclosingmarubozu — Closing Marubozu

### Beschreibung

function trader_cdlclosingmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlconcealbabyswall

(PECL trader >= 0.2.0)

trader_cdlconcealbabyswall — Concealing Baby Swallow

### Beschreibung

function trader_cdlconcealbabyswall(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlcounterattack

(PECL trader >= 0.2.0)

trader_cdlcounterattack — Counterattack

### Beschreibung

function trader_cdlcounterattack(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdldarkcloudcover

(PECL trader >= 0.2.0)

trader_cdldarkcloudcover — Dark Cloud Cover

### Beschreibung

function trader_cdldarkcloudcover(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`penetration`

  Percentage of penetration of a candle within another candle.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdldoji

(PECL trader >= 0.2.0)

trader_cdldoji — Doji

### Beschreibung

function trader_cdldoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdldojistar

(PECL trader >= 0.2.0)

trader_cdldojistar — Doji Star

### Beschreibung

function trader_cdldojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdldragonflydoji

(PECL trader >= 0.2.0)

trader_cdldragonflydoji — Dragonfly Doji

### Beschreibung

function trader_cdldragonflydoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlengulfing

(PECL trader >= 0.2.0)

trader_cdlengulfing — Engulfing Pattern

### Beschreibung

function trader_cdlengulfing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdleveningdojistar

(PECL trader >= 0.2.0)

trader_cdleveningdojistar — Evening Doji Star

### Beschreibung

function trader_cdleveningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`penetration`

  Percentage of penetration of a candle within another candle.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdleveningstar

(PECL trader >= 0.2.0)

trader_cdleveningstar — Evening Star

### Beschreibung

function trader_cdleveningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`penetration`

  Percentage of penetration of a candle within another candle.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlgapsidesidewhite

(PECL trader >= 0.2.0)

trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines

### Beschreibung

function trader_cdlgapsidesidewhite(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlgravestonedoji

(PECL trader >= 0.2.0)

trader_cdlgravestonedoji — Gravestone Doji

### Beschreibung

function trader_cdlgravestonedoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlhammer

(PECL trader >= 0.2.0)

trader_cdlhammer — Hammer

### Beschreibung

function trader_cdlhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlhangingman

(PECL trader >= 0.2.0)

trader_cdlhangingman — Hanging Man

### Beschreibung

function trader_cdlhangingman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlharami

(PECL trader >= 0.2.0)

trader_cdlharami — Harami Pattern

### Beschreibung

function trader_cdlharami(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlharamicross

(PECL trader >= 0.2.0)

trader_cdlharamicross — Harami Cross Pattern

### Beschreibung

function trader_cdlharamicross(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlhighwave

(PECL trader >= 0.2.0)

trader_cdlhighwave — High-Wave Candle

### Beschreibung

function trader_cdlhighwave(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlhikkake

(PECL trader >= 0.2.0)

trader_cdlhikkake — Hikkake Pattern

### Beschreibung

function trader_cdlhikkake(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlhikkakemod

(PECL trader >= 0.2.0)

trader_cdlhikkakemod — Modified Hikkake Pattern

### Beschreibung

function trader_cdlhikkakemod(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlhomingpigeon

(PECL trader >= 0.2.0)

trader_cdlhomingpigeon — Homing Pigeon

### Beschreibung

function trader_cdlhomingpigeon(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlidentical3crows

(PECL trader >= 0.2.0)

trader_cdlidentical3crows — Identical Three Crows

### Beschreibung

function trader_cdlidentical3crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlinneck

(PECL trader >= 0.2.0)

trader_cdlinneck — In-Neck Pattern

### Beschreibung

function trader_cdlinneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlinvertedhammer

(PECL trader >= 0.2.0)

trader_cdlinvertedhammer — Inverted Hammer

### Beschreibung

function trader_cdlinvertedhammer(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlkicking

(PECL trader >= 0.2.0)

trader_cdlkicking — Kicking

### Beschreibung

function trader_cdlkicking(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlkickingbylength

(PECL trader >= 0.2.0)

trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu

### Beschreibung

function trader_cdlkickingbylength(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlladderbottom

(PECL trader >= 0.2.0)

trader_cdlladderbottom — Ladder Bottom

### Beschreibung

function trader_cdlladderbottom(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdllongleggeddoji

(PECL trader >= 0.2.0)

trader_cdllongleggeddoji — Long Legged Doji

### Beschreibung

function trader_cdllongleggeddoji(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdllongline

(PECL trader >= 0.2.0)

trader_cdllongline — Long Line Candle

### Beschreibung

function trader_cdllongline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlmarubozu

(PECL trader >= 0.2.0)

trader_cdlmarubozu — Marubozu

### Beschreibung

function trader_cdlmarubozu(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlmatchinglow

(PECL trader >= 0.2.0)

trader_cdlmatchinglow — Matching Low

### Beschreibung

function trader_cdlmatchinglow(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlmathold

(PECL trader >= 0.2.0)

trader_cdlmathold — Mat Hold

### Beschreibung

function trader_cdlmathold(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`penetration`

  Percentage of penetration of a candle within another candle.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlmorningdojistar

(PECL trader >= 0.2.0)

trader_cdlmorningdojistar — Morning Doji Star

### Beschreibung

function trader_cdlmorningdojistar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`penetration`

  Percentage of penetration of a candle within another candle.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlmorningstar

(PECL trader >= 0.2.0)

trader_cdlmorningstar — Morning Star

### Beschreibung

function trader_cdlmorningstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`,
float `$penetration` = ?
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`penetration`

  Percentage of penetration of a candle within another candle.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlonneck

(PECL trader >= 0.2.0)

trader_cdlonneck — On-Neck Pattern

### Beschreibung

function trader_cdlonneck(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlpiercing

(PECL trader >= 0.2.0)

trader_cdlpiercing — Piercing Pattern

### Beschreibung

function trader_cdlpiercing(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlrickshawman

(PECL trader >= 0.2.0)

trader_cdlrickshawman — Rickshaw Man

### Beschreibung

function trader_cdlrickshawman(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlrisefall3methods

(PECL trader >= 0.2.0)

trader_cdlrisefall3methods — Rising/Falling Three Methods

### Beschreibung

function trader_cdlrisefall3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlseparatinglines

(PECL trader >= 0.2.0)

trader_cdlseparatinglines — Separating Lines

### Beschreibung

function trader_cdlseparatinglines(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlshootingstar

(PECL trader >= 0.2.0)

trader_cdlshootingstar — Shooting Star

### Beschreibung

function trader_cdlshootingstar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlshortline

(PECL trader >= 0.2.0)

trader_cdlshortline — Short Line Candle

### Beschreibung

function trader_cdlshortline(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlspinningtop

(PECL trader >= 0.2.0)

trader_cdlspinningtop — Spinning Top

### Beschreibung

function trader_cdlspinningtop(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlstalledpattern

(PECL trader >= 0.2.0)

trader_cdlstalledpattern — Stalled Pattern

### Beschreibung

function trader_cdlstalledpattern(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlsticksandwich

(PECL trader >= 0.2.0)

trader_cdlsticksandwich — Stick Sandwich

### Beschreibung

function trader_cdlsticksandwich(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdltakuri

(PECL trader >= 0.2.0)

trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)

### Beschreibung

function trader_cdltakuri(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdltasukigap

(PECL trader >= 0.2.0)

trader_cdltasukigap — Tasuki Gap

### Beschreibung

function trader_cdltasukigap(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlthrusting

(PECL trader >= 0.2.0)

trader_cdlthrusting — Thrusting Pattern

### Beschreibung

function trader_cdlthrusting(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdltristar

(PECL trader >= 0.2.0)

trader_cdltristar — Tristar Pattern

### Beschreibung

function trader_cdltristar(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlunique3river

(PECL trader >= 0.2.0)

trader_cdlunique3river — Unique 3 River

### Beschreibung

function trader_cdlunique3river(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlupsidegap2crows

(PECL trader >= 0.2.0)

trader_cdlupsidegap2crows — Upside Gap Two Crows

### Beschreibung

function trader_cdlupsidegap2crows(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cdlxsidegap3methods

(PECL trader >= 0.2.0)

trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods

### Beschreibung

function trader_cdlxsidegap3methods(
array `$open`,
array `$high`,
array `$low`,
array `$close`
): array

### Parameter-Liste

`open`

  Opening price, array of real values.

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ceil

(PECL trader >= 0.2.0)

trader_ceil — Vector Ceil

### Beschreibung

function trader_ceil(array `$real`): array

Calculates the next highest integer for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cmo

(PECL trader >= 0.2.0)

trader_cmo — Chande Momentum Oscillator

### Beschreibung

function trader_cmo(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_correl

(PECL trader >= 0.2.0)

trader_correl — Pearson's Correlation Coefficient (r)

### Beschreibung

function trader_correl(array `$real0`, array `$real1`, int `$timePeriod` = ?): array

### Parameter-Liste

`real0`

  Array of real values.

`real1`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cos

(PECL trader >= 0.2.0)

trader_cos — Vector Trigonometric Cos

### Beschreibung

function trader_cos(array `$real`): array

Calculates the cosine for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_cosh

(PECL trader >= 0.2.0)

trader_cosh — Vector Trigonometric Cosh

### Beschreibung

function trader_cosh(array `$real`): array

Calculates the hyperbolic cosine for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_dema

(PECL trader >= 0.2.0)

trader_dema — Double Exponential Moving Average

### Beschreibung

function trader_dema(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_div

(PECL trader >= 0.2.0)

trader_div — Vector Arithmetic Div

### Beschreibung

function trader_div(array `$real0`, array `$real1`): array

Divides each value from `real0` by the corresponding value from `real1` and returns the resulting array.

### Parameter-Liste

`real0`

  Array of real values.

`real1`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_dx

(PECL trader >= 0.2.0)

trader_dx — Directional Movement Index

### Beschreibung

function trader_dx(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ema

(PECL trader >= 0.2.0)

trader_ema — Exponential Moving Average

### Beschreibung

function trader_ema(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_errno

(PECL trader >= 0.3.0)

trader_errno — Get error code

### Beschreibung

function trader_errno(): int

Get error code of the last operation.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the error code identified by one of the TRADER_ERR_* constants.

# trader_exp

(PECL trader >= 0.2.0)

trader_exp — Vector Arithmetic Exp

### Beschreibung

function trader_exp(array `$real`): array

Calculates `e` raised to the power of each value in `real`. Returns an array with the calculated data.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_floor

(PECL trader >= 0.2.0)

trader_floor — Vector Floor

### Beschreibung

function trader_floor(array `$real`): array

Calculates the next lowest integer for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_get_compat

(PECL trader >= 0.2.2)

trader_get_compat — Get compatibility mode

### Beschreibung

function trader_get_compat(): int

Get compatibility mode which affects the way calculations are done by all the extension functions.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns the compatibility mode id which can be identified by TRADER_COMPATIBILITY_* series of constants.

# trader_get_unstable_period

(PECL trader >= 0.2.2)

trader_get_unstable_period — Get unstable period

### Beschreibung

function trader_get_unstable_period(int `$functionId`): int

Get unstable period factor for a particular function.

### Parameter-Liste

`functionId`

  Function ID the factor to be read for. TRADER_FUNC_UNST_* series of constants should be used.

### Rückgabewerte

Returns the unstable period factor for the corresponding function.

# trader_ht_dcperiod

(PECL trader >= 0.2.0)

trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period

### Beschreibung

function trader_ht_dcperiod(array `$real`): array

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ht_dcphase

(PECL trader >= 0.2.0)

trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase

### Beschreibung

function trader_ht_dcphase(array `$real`): array

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ht_phasor

(PECL trader >= 0.2.0)

trader_ht_phasor — Hilbert Transform - Phasor Components

### Beschreibung

function trader_ht_phasor(array `$real`): array

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ht_sine

(PECL trader >= 0.2.0)

trader_ht_sine — Hilbert Transform - SineWave

### Beschreibung

function trader_ht_sine(array `$real`): array

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ht_trendline

(PECL trader >= 0.2.0)

trader_ht_trendline — Hilbert Transform - Instantaneous Trendline

### Beschreibung

function trader_ht_trendline(array `$real`): array

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ht_trendmode

(PECL trader >= 0.2.0)

trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode

### Beschreibung

function trader_ht_trendmode(array `$real`): array

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_kama

(PECL trader >= 0.2.0)

trader_kama — Kaufman Adaptive Moving Average

### Beschreibung

function trader_kama(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_linearreg

(PECL trader >= 0.2.0)

trader_linearreg — Linear Regression

### Beschreibung

function trader_linearreg(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_linearreg_angle

(PECL trader >= 0.2.0)

trader_linearreg_angle — Linear Regression Angle

### Beschreibung

function trader_linearreg_angle(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_linearreg_intercept

(PECL trader >= 0.2.0)

trader_linearreg_intercept — Linear Regression Intercept

### Beschreibung

function trader_linearreg_intercept(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_linearreg_slope

(PECL trader >= 0.2.0)

trader_linearreg_slope — Linear Regression Slope

### Beschreibung

function trader_linearreg_slope(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ln

(PECL trader >= 0.2.0)

trader_ln — Vector Log Natural

### Beschreibung

function trader_ln(array `$real`): array

Calculates the natural logarithm for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_log10

(PECL trader >= 0.2.0)

trader_log10 — Vector Log10

### Beschreibung

function trader_log10(array `$real`): array

Calculates the base-10 logarithm for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ma

(PECL trader >= 0.2.0)

trader_ma — Moving average

### Beschreibung

function trader_ma(array `$real`, int `$timePeriod` = ?, int `$mAType` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`mAType`

  Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_macd

(PECL trader >= 0.2.0)

trader_macd — Moving Average Convergence/Divergence

### Beschreibung

function trader_macd(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$signalPeriod` = ?
): array

### Parameter-Liste

`real`

  Array of real values.

`fastPeriod`

  Number of period for the fast MA. Valid range from 2 to 100000.

`slowPeriod`

  Number of period for the slow MA. Valid range from 2 to 100000.

`signalPeriod`

  Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_macdext

(PECL trader >= 0.2.0)

trader_macdext — MACD with controllable MA type

### Beschreibung

function trader_macdext(
array `$real`,
int `$fastPeriod` = ?,
int `$fastMAType` = ?,
int `$slowPeriod` = ?,
int `$slowMAType` = ?,
int `$signalPeriod` = ?,
int `$signalMAType` = ?
): array

### Parameter-Liste

`real`

  Array of real values.

`fastPeriod`

  Number of period for the fast MA. Valid range from 2 to 100000.

`fastMAType`

  Type of Moving Average for fast MA. TRADER_MA_TYPE_* series of constants should be used.

`slowPeriod`

  Number of period for the slow MA. Valid range from 2 to 100000.

`slowMAType`

  Type of Moving Average for slow MA. TRADER_MA_TYPE_* series of constants should be used.

`signalPeriod`

  Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

`signalMAType`

  Type of Moving Average for signal line. TRADER_MA_TYPE_* series of constants should be used.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_macdfix

(PECL trader >= 0.2.0)

trader_macdfix — Moving Average Convergence/Divergence Fix 12/26

### Beschreibung

function trader_macdfix(array `$real`, int `$signalPeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`signalPeriod`

  Smoothing for the signal line (nb of period). Valid range from 1 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_mama

(PECL trader >= 0.2.0)

trader_mama — MESA Adaptive Moving Average

### Beschreibung

function trader_mama(array `$real`, float `$fastLimit` = ?, float `$slowLimit` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`fastLimit`

  Upper limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.

`slowLimit`

  Lower limit use in the adaptive algorithm. Valid range from 0.01 to 0.99.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_mavp

(PECL trader >= 0.2.0)

trader_mavp — Moving average with variable period

### Beschreibung

function trader_mavp(
array `$real`,
array `$periods`,
int `$minPeriod` = ?,
int `$maxPeriod` = ?,
int `$mAType` = ?
): array

### Parameter-Liste

`real`

  Array of real values.

`periods`

  Array of real values.

`minPeriod`

  Value less than minimum will be changed to Minimum period. Valid range from 2 to 100000

`maxPeriod`

  Value higher than minimum will be changed to Maximum period. Valid range from 2 to 100000

`mAType`

  Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_max

(PECL trader >= 0.2.0)

trader_max — Highest value over a specified period

### Beschreibung

function trader_max(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_maxindex

(PECL trader >= 0.2.0)

trader_maxindex — Index of highest value over a specified period

### Beschreibung

function trader_maxindex(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_medprice

(PECL trader >= 0.2.0)

trader_medprice — Median Price

### Beschreibung

function trader_medprice(array `$high`, array `$low`): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_mfi

(PECL trader >= 0.2.0)

trader_mfi — Money Flow Index

### Beschreibung

function trader_mfi(
array `$high`,
array `$low`,
array `$close`,
array `$volume`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`volume`

  Volume traded, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_midpoint

(PECL trader >= 0.2.0)

trader_midpoint — MidPoint over period

### Beschreibung

function trader_midpoint(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_midprice

(PECL trader >= 0.2.0)

trader_midprice — Midpoint Price over period

### Beschreibung

function trader_midprice(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_min

(PECL trader >= 0.2.0)

trader_min — Lowest value over a specified period

### Beschreibung

function trader_min(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_minindex

(PECL trader >= 0.2.0)

trader_minindex — Index of lowest value over a specified period

### Beschreibung

function trader_minindex(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_minmax

(PECL trader >= 0.2.0)

trader_minmax — Lowest and highest values over a specified period

### Beschreibung

function trader_minmax(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_minmaxindex

(PECL trader >= 0.2.0)

trader_minmaxindex — Indexes of lowest and highest values over a specified period

### Beschreibung

function trader_minmaxindex(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_minus_di

(PECL trader >= 0.2.0)

trader_minus_di — Minus Directional Indicator

### Beschreibung

function trader_minus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_minus_dm

(PECL trader >= 0.2.0)

trader_minus_dm — Minus Directional Movement

### Beschreibung

function trader_minus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_mom

(PECL trader >= 0.2.0)

trader_mom — Momentum

### Beschreibung

function trader_mom(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_mult

(PECL trader >= 0.2.0)

trader_mult — Vector Arithmetic Mult

### Beschreibung

function trader_mult(array `$real0`, array `$real1`): array

Calculates the vector dot product of `real0` with `real1` and returns the resulting vector.

### Parameter-Liste

`real0`

  Array of real values.

`real1`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_natr

(PECL trader >= 0.2.0)

trader_natr — Normalized Average True Range

### Beschreibung

function trader_natr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_obv

(PECL trader >= 0.2.0)

trader_obv — On Balance Volume

### Beschreibung

function trader_obv(array `$real`, array `$volume`): array

### Parameter-Liste

`real`

  Array of real values.

`volume`

  Volume traded, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_plus_di

(PECL trader >= 0.2.0)

trader_plus_di — Plus Directional Indicator

### Beschreibung

function trader_plus_di(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_plus_dm

(PECL trader >= 0.2.0)

trader_plus_dm — Plus Directional Movement

### Beschreibung

function trader_plus_dm(array `$high`, array `$low`, int `$timePeriod` = ?): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ppo

(PECL trader >= 0.2.0)

trader_ppo — Percentage Price Oscillator

### Beschreibung

function trader_ppo(
array `$real`,
int `$fastPeriod` = ?,
int `$slowPeriod` = ?,
int `$mAType` = ?
): array

### Parameter-Liste

`real`

  Array of real values.

`fastPeriod`

  Number of period for the fast MA. Valid range from 2 to 100000.

`slowPeriod`

  Number of period for the slow MA. Valid range from 2 to 100000.

`mAType`

  Type of Moving Average. TRADER_MA_TYPE_* series of constants should be used.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_roc

(PECL trader >= 0.2.0)

trader_roc — Rate of change : ((price/prevPrice)-1)*100

### Beschreibung

function trader_roc(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_rocp

(PECL trader >= 0.2.0)

trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice

### Beschreibung

function trader_rocp(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_rocr

(PECL trader >= 0.2.0)

trader_rocr — Rate of change ratio: (price/prevPrice)

### Beschreibung

function trader_rocr(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_rocr100

(PECL trader >= 0.2.0)

trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100

### Beschreibung

function trader_rocr100(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_rsi

(PECL trader >= 0.2.0)

trader_rsi — Relative Strength Index

### Beschreibung

function trader_rsi(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_sar

(PECL trader >= 0.2.0)

trader_sar — Parabolic SAR

### Beschreibung

function trader_sar(
array `$high`,
array `$low`,
float `$acceleration` = ?,
float `$maximum` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`acceleration`

  Acceleration Factor used up to the Maximum value. Valid range from 0 to TRADER_REAL_MAX.

`maximum`

  Acceleration Factor Maximum value. Valid range from 0 to TRADER_REAL_MAX.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_sarext

(PECL trader >= 0.2.0)

trader_sarext — Parabolic SAR - Extended

### Beschreibung

function trader_sarext(
array `$high`,
array `$low`,
float `$startValue` = ?,
float `$offsetOnReverse` = ?,
float `$accelerationInitLong` = ?,
float `$accelerationLong` = ?,
float `$accelerationMaxLong` = ?,
float `$accelerationInitShort` = ?,
float `$accelerationShort` = ?,
float `$accelerationMaxShort` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`startValue`

  Start value and direction. 0 for Auto, >0 for Long, <0 for Short. Valid range from TRADER_REAL_MIN to TRADER_REAL_MAX.

`offsetOnReverse`

  Percent offset added/removed to initial stop on short/long reversal. Valid range from 0 to TRADER_REAL_MAX.

`accelerationInitLong`

  Acceleration Factor initial value for the Long direction. Valid range from 0 to TRADER_REAL_MAX.

`accelerationLong`

  Acceleration Factor for the Long direction. Valid range from 0 to TRADER_REAL_MAX.

`accelerationMaxLong`

  Acceleration Factor maximum value for the Long direction. Valid range from 0 to TRADER_REAL_MAX.

`accelerationInitShort`

  Acceleration Factor initial value for the Short direction. Valid range from 0 to TRADER_REAL_MAX.

`accelerationShort`

  Acceleration Factor for the Short direction. Valid range from 0 to TRADER_REAL_MAX.

`accelerationMaxShort`

  Acceleration Factor maximum value for the Short direction. Valid range from 0 to TRADER_REAL_MAX.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_set_compat

(PECL trader >= 0.2.2)

trader_set_compat — Set compatibility mode

### Beschreibung

function trader_set_compat(int `$compatId`): void

Set compatibility mode which will affect the way calculations are done by all the extension functions.

### Parameter-Liste

`compatId`

  Compatibility Id. TRADER_COMPATIBILITY_* series of constants should be used.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# trader_set_unstable_period

(PECL trader >= 0.2.2)

trader_set_unstable_period — Set unstable period

### Beschreibung

function trader_set_unstable_period(int `$functionId`, int `$timePeriod`): void

Influences unstable period factor for functions, which are sensible to it. More information about unstable periods can be found on the » TA-Lib API documentation page.

### Parameter-Liste

`functionId`

  Function ID the factor should be set for. TRADER_FUNC_UNST_* constant series can be used to affect the corresponding function.

`timePeriod`

  Unstable period value.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# trader_sin

(PECL trader >= 0.2.0)

trader_sin — Vector Trigonometric Sin

### Beschreibung

function trader_sin(array `$real`): array

Calculates the sine for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_sinh

(PECL trader >= 0.2.0)

trader_sinh — Vector Trigonometric Sinh

### Beschreibung

function trader_sinh(array `$real`): array

Calculates the hyperbolic sine for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_sma

(PECL trader >= 0.2.0)

trader_sma — Simple Moving Average

### Beschreibung

function trader_sma(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_sqrt

(PECL trader >= 0.2.0)

trader_sqrt — Vector Square Root

### Beschreibung

function trader_sqrt(array `$real`): array

Calculates the square root of each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_stddev

(PECL trader >= 0.2.0)

trader_stddev — Standard Deviation

### Beschreibung

function trader_stddev(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`nbDev`

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_stoch

(PECL trader >= 0.2.0)

trader_stoch — Stochastic

### Beschreibung

function trader_stoch(
array `$high`,
array `$low`,
array `$close`,
int `$fastK_Period` = ?,
int `$slowK_Period` = ?,
int `$slowK_MAType` = ?,
int `$slowD_Period` = ?,
int `$slowD_MAType` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`fastK_Period`

  Time period for building the Fast-K line. Valid range from 1 to 100000.

`slowK_Period`

  Smoothing for making the Slow-K line. Valid range from 1 to 100000, usually set to 3.

`slowK_MAType`

  Type of Moving Average for Slow-K. TRADER_MA_TYPE_* series of constants should be used.

`slowD_Period`

  Smoothing for making the Slow-D line. Valid range from 1 to 100000.

`slowD_MAType`

  Type of Moving Average for Slow-D. TRADER_MA_TYPE_* series of constants should be used.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_stochf

(PECL trader >= 0.2.0)

trader_stochf — Stochastic Fast

### Beschreibung

function trader_stochf(
array `$high`,
array `$low`,
array `$close`,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`fastK_Period`

  Time period for building the Fast-K line. Valid range from 1 to 100000.

`fastD_Period`

  Smoothing for making the Fast-D line. Valid range from 1 to 100000, usually set to 3.

`fastD_MAType`

  Type of Moving Average for Fast-D. TRADER_MA_TYPE_* series of constants should be used.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_stochrsi

(PECL trader >= 0.2.0)

trader_stochrsi — Stochastic Relative Strength Index

### Beschreibung

function trader_stochrsi(
array `$real`,
int `$timePeriod` = ?,
int `$fastK_Period` = ?,
int `$fastD_Period` = ?,
int `$fastD_MAType` = ?
): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`fastK_Period`

  Time period for building the Fast-K line. Valid range from 1 to 100000.

`fastD_Period`

  Smoothing for making the Fast-D line. Valid range from 1 to 100000, usually set to 3.

`fastD_MAType`

  Type of Moving Average for Fast-D. TRADER_MA_TYPE_* series of constants should be used.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_sub

(PECL trader >= 0.2.0)

trader_sub — Vector Arithmetic Subtraction

### Beschreibung

function trader_sub(array `$real0`, array `$real1`): array

Calculates the vector subtraction of `real1` from `real0` and returns the resulting vector.

### Parameter-Liste

`real0`

  Array of real values.

`real1`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_sum

(PECL trader >= 0.2.0)

trader_sum — Summation

### Beschreibung

function trader_sum(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_t3

(PECL trader >= 0.2.0)

trader_t3 — Triple Exponential Moving Average (T3)

### Beschreibung

function trader_t3(array `$real`, int `$timePeriod` = ?, float `$vFactor` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`vFactor`

  Volume Factor. Valid range from 1 to 0.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_tan

(PECL trader >= 0.2.0)

trader_tan — Vector Trigonometric Tan

### Beschreibung

function trader_tan(array `$real`): array

Calculates the tangent for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_tanh

(PECL trader >= 0.2.0)

trader_tanh — Vector Trigonometric Tanh

### Beschreibung

function trader_tanh(array `$real`): array

Calculates the hyperbolic tangent for each value in `real` and returns the resulting array.

### Parameter-Liste

`real`

  Array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_tema

(PECL trader >= 0.2.0)

trader_tema — Triple Exponential Moving Average

### Beschreibung

function trader_tema(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_trange

(PECL trader >= 0.2.0)

trader_trange — True Range

### Beschreibung

function trader_trange(array `$high`, array `$low`, array `$close`): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_trima

(PECL trader >= 0.2.0)

trader_trima — Triangular Moving Average

### Beschreibung

function trader_trima(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_trix

(PECL trader >= 0.2.0)

trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA

### Beschreibung

function trader_trix(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_tsf

(PECL trader >= 0.2.0)

trader_tsf — Time Series Forecast

### Beschreibung

function trader_tsf(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_typprice

(PECL trader >= 0.2.0)

trader_typprice — Typical Price

### Beschreibung

function trader_typprice(array `$high`, array `$low`, array `$close`): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_ultosc

(PECL trader >= 0.2.0)

trader_ultosc — Ultimate Oscillator

### Beschreibung

function trader_ultosc(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod1` = ?,
int `$timePeriod2` = ?,
int `$timePeriod3` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod1`

  Number of bars for 1st period. Valid range from 1 to 100000.

`timePeriod2`

  Number of bars for 2nd period. Valid range from 1 to 100000.

`timePeriod3`

  Number of bars for 3rd period. Valid range from 1 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_var

(PECL trader >= 0.2.0)

trader_var — Variance

### Beschreibung

function trader_var(array `$real`, int `$timePeriod` = ?, float `$nbDev` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

`nbDev`

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_wclprice

(PECL trader >= 0.2.0)

trader_wclprice — Weighted Close Price

### Beschreibung

function trader_wclprice(array `$high`, array `$low`, array `$close`): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_willr

(PECL trader >= 0.2.0)

trader_willr — Williams' %R

### Beschreibung

function trader_willr(
array `$high`,
array `$low`,
array `$close`,
int `$timePeriod` = ?
): array

### Parameter-Liste

`high`

  High price, array of real values.

`low`

  Low price, array of real values.

`close`

  Closing price, array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

# trader_wma

(PECL trader >= 0.2.0)

trader_wma — Weighted Moving Average

### Beschreibung

function trader_wma(array `$real`, int `$timePeriod` = ?): array

### Parameter-Liste

`real`

  Array of real values.

`timePeriod`

  Number of period. Valid range from 2 to 100000.

### Rückgabewerte

Returns an array with calculated data or false on failure.

## Inhaltsverzeichnis

- trader_acos — Vector Trigonometric ACos
- trader_ad — Chaikin A/D Line
- trader_add — Vector Arithmetic Add
- trader_adosc — Chaikin A/D Oscillator
- trader_adx — Average Directional Movement Index
- trader_adxr — Average Directional Movement Index Rating
- trader_apo — Absolute Price Oscillator
- trader_aroon — Aroon
- trader_aroonosc — Aroon Oscillator
- trader_asin — Vector Trigonometric ASin
- trader_atan — Vector Trigonometric ATan
- trader_atr — Average True Range
- trader_avgprice — Average Price
- trader_bbands — Bollinger Bands
- trader_beta — Beta
- trader_bop — Balance Of Power
- trader_cci — Commodity Channel Index
- trader_cdl2crows — Two Crows
- trader_cdl3blackcrows — Three Black Crows
- trader_cdl3inside — Three Inside Up/Down
- trader_cdl3linestrike — Three-Line Strike
- trader_cdl3outside — Three Outside Up/Down
- trader_cdl3starsinsouth — Three Stars In The South
- trader_cdl3whitesoldiers — Three Advancing White Soldiers
- trader_cdlabandonedbaby — Abandoned Baby
- trader_cdladvanceblock — Advance Block
- trader_cdlbelthold — Belt-hold
- trader_cdlbreakaway — Breakaway
- trader_cdlclosingmarubozu — Closing Marubozu
- trader_cdlconcealbabyswall — Concealing Baby Swallow
- trader_cdlcounterattack — Counterattack
- trader_cdldarkcloudcover — Dark Cloud Cover
- trader_cdldoji — Doji
- trader_cdldojistar — Doji Star
- trader_cdldragonflydoji — Dragonfly Doji
- trader_cdlengulfing — Engulfing Pattern
- trader_cdleveningdojistar — Evening Doji Star
- trader_cdleveningstar — Evening Star
- trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines
- trader_cdlgravestonedoji — Gravestone Doji
- trader_cdlhammer — Hammer
- trader_cdlhangingman — Hanging Man
- trader_cdlharami — Harami Pattern
- trader_cdlharamicross — Harami Cross Pattern
- trader_cdlhighwave — High-Wave Candle
- trader_cdlhikkake — Hikkake Pattern
- trader_cdlhikkakemod — Modified Hikkake Pattern
- trader_cdlhomingpigeon — Homing Pigeon
- trader_cdlidentical3crows — Identical Three Crows
- trader_cdlinneck — In-Neck Pattern
- trader_cdlinvertedhammer — Inverted Hammer
- trader_cdlkicking — Kicking
- trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu
- trader_cdlladderbottom — Ladder Bottom
- trader_cdllongleggeddoji — Long Legged Doji
- trader_cdllongline — Long Line Candle
- trader_cdlmarubozu — Marubozu
- trader_cdlmatchinglow — Matching Low
- trader_cdlmathold — Mat Hold
- trader_cdlmorningdojistar — Morning Doji Star
- trader_cdlmorningstar — Morning Star
- trader_cdlonneck — On-Neck Pattern
- trader_cdlpiercing — Piercing Pattern
- trader_cdlrickshawman — Rickshaw Man
- trader_cdlrisefall3methods — Rising/Falling Three Methods
- trader_cdlseparatinglines — Separating Lines
- trader_cdlshootingstar — Shooting Star
- trader_cdlshortline — Short Line Candle
- trader_cdlspinningtop — Spinning Top
- trader_cdlstalledpattern — Stalled Pattern
- trader_cdlsticksandwich — Stick Sandwich
- trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)
- trader_cdltasukigap — Tasuki Gap
- trader_cdlthrusting — Thrusting Pattern
- trader_cdltristar — Tristar Pattern
- trader_cdlunique3river — Unique 3 River
- trader_cdlupsidegap2crows — Upside Gap Two Crows
- trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods
- trader_ceil — Vector Ceil
- trader_cmo — Chande Momentum Oscillator
- trader_correl — Pearson's Correlation Coefficient (r)
- trader_cos — Vector Trigonometric Cos
- trader_cosh — Vector Trigonometric Cosh
- trader_dema — Double Exponential Moving Average
- trader_div — Vector Arithmetic Div
- trader_dx — Directional Movement Index
- trader_ema — Exponential Moving Average
- trader_errno — Get error code
- trader_exp — Vector Arithmetic Exp
- trader_floor — Vector Floor
- trader_get_compat — Get compatibility mode
- trader_get_unstable_period — Get unstable period
- trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period
- trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase
- trader_ht_phasor — Hilbert Transform - Phasor Components
- trader_ht_sine — Hilbert Transform - SineWave
- trader_ht_trendline — Hilbert Transform - Instantaneous Trendline
- trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode
- trader_kama — Kaufman Adaptive Moving Average
- trader_linearreg — Linear Regression
- trader_linearreg_angle — Linear Regression Angle
- trader_linearreg_intercept — Linear Regression Intercept
- trader_linearreg_slope — Linear Regression Slope
- trader_ln — Vector Log Natural
- trader_log10 — Vector Log10
- trader_ma — Moving average
- trader_macd — Moving Average Convergence/Divergence
- trader_macdext — MACD with controllable MA type
- trader_macdfix — Moving Average Convergence/Divergence Fix 12/26
- trader_mama — MESA Adaptive Moving Average
- trader_mavp — Moving average with variable period
- trader_max — Highest value over a specified period
- trader_maxindex — Index of highest value over a specified period
- trader_medprice — Median Price
- trader_mfi — Money Flow Index
- trader_midpoint — MidPoint over period
- trader_midprice — Midpoint Price over period
- trader_min — Lowest value over a specified period
- trader_minindex — Index of lowest value over a specified period
- trader_minmax — Lowest and highest values over a specified period
- trader_minmaxindex — Indexes of lowest and highest values over a specified period
- trader_minus_di — Minus Directional Indicator
- trader_minus_dm — Minus Directional Movement
- trader_mom — Momentum
- trader_mult — Vector Arithmetic Mult
- trader_natr — Normalized Average True Range
- trader_obv — On Balance Volume
- trader_plus_di — Plus Directional Indicator
- trader_plus_dm — Plus Directional Movement
- trader_ppo — Percentage Price Oscillator
- trader_roc — Rate of change : ((price/prevPrice)-1)*100
- trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice
- trader_rocr — Rate of change ratio: (price/prevPrice)
- trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100
- trader_rsi — Relative Strength Index
- trader_sar — Parabolic SAR
- trader_sarext — Parabolic SAR - Extended
- trader_set_compat — Set compatibility mode
- trader_set_unstable_period — Set unstable period
- trader_sin — Vector Trigonometric Sin
- trader_sinh — Vector Trigonometric Sinh
- trader_sma — Simple Moving Average
- trader_sqrt — Vector Square Root
- trader_stddev — Standard Deviation
- trader_stoch — Stochastic
- trader_stochf — Stochastic Fast
- trader_stochrsi — Stochastic Relative Strength Index
- trader_sub — Vector Arithmetic Subtraction
- trader_sum — Summation
- trader_t3 — Triple Exponential Moving Average (T3)
- trader_tan — Vector Trigonometric Tan
- trader_tanh — Vector Trigonometric Tanh
- trader_tema — Triple Exponential Moving Average
- trader_trange — True Range
- trader_trima — Triangular Moving Average
- trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA
- trader_tsf — Time Series Forecast
- trader_typprice — Typical Price
- trader_ultosc — Ultimate Oscillator
- trader_var — Variance
- trader_wclprice — Weighted Close Price
- trader_willr — Williams' %R
- trader_wma — Weighted Moving Average

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- Vordefinierte Konstanten
- Trader Funktionen
  - trader_acos — Vector Trigonometric ACos
  - trader_ad — Chaikin A/D Line
  - trader_add — Vector Arithmetic Add
  - trader_adosc — Chaikin A/D Oscillator
  - trader_adx — Average Directional Movement Index
  - trader_adxr — Average Directional Movement Index Rating
  - trader_apo — Absolute Price Oscillator
  - trader_aroon — Aroon
  - trader_aroonosc — Aroon Oscillator
  - trader_asin — Vector Trigonometric ASin
  - trader_atan — Vector Trigonometric ATan
  - trader_atr — Average True Range
  - trader_avgprice — Average Price
  - trader_bbands — Bollinger Bands
  - trader_beta — Beta
  - trader_bop — Balance Of Power
  - trader_cci — Commodity Channel Index
  - trader_cdl2crows — Two Crows
  - trader_cdl3blackcrows — Three Black Crows
  - trader_cdl3inside — Three Inside Up/Down
  - trader_cdl3linestrike — Three-Line Strike
  - trader_cdl3outside — Three Outside Up/Down
  - trader_cdl3starsinsouth — Three Stars In The South
  - trader_cdl3whitesoldiers — Three Advancing White Soldiers
  - trader_cdlabandonedbaby — Abandoned Baby
  - trader_cdladvanceblock — Advance Block
  - trader_cdlbelthold — Belt-hold
  - trader_cdlbreakaway — Breakaway
  - trader_cdlclosingmarubozu — Closing Marubozu
  - trader_cdlconcealbabyswall — Concealing Baby Swallow
  - trader_cdlcounterattack — Counterattack
  - trader_cdldarkcloudcover — Dark Cloud Cover
  - trader_cdldoji — Doji
  - trader_cdldojistar — Doji Star
  - trader_cdldragonflydoji — Dragonfly Doji
  - trader_cdlengulfing — Engulfing Pattern
  - trader_cdleveningdojistar — Evening Doji Star
  - trader_cdleveningstar — Evening Star
  - trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines
  - trader_cdlgravestonedoji — Gravestone Doji
  - trader_cdlhammer — Hammer
  - trader_cdlhangingman — Hanging Man
  - trader_cdlharami — Harami Pattern
  - trader_cdlharamicross — Harami Cross Pattern
  - trader_cdlhighwave — High-Wave Candle
  - trader_cdlhikkake — Hikkake Pattern
  - trader_cdlhikkakemod — Modified Hikkake Pattern
  - trader_cdlhomingpigeon — Homing Pigeon
  - trader_cdlidentical3crows — Identical Three Crows
  - trader_cdlinneck — In-Neck Pattern
  - trader_cdlinvertedhammer — Inverted Hammer
  - trader_cdlkicking — Kicking
  - trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu
  - trader_cdlladderbottom — Ladder Bottom
  - trader_cdllongleggeddoji — Long Legged Doji
  - trader_cdllongline — Long Line Candle
  - trader_cdlmarubozu — Marubozu
  - trader_cdlmatchinglow — Matching Low
  - trader_cdlmathold — Mat Hold
  - trader_cdlmorningdojistar — Morning Doji Star
  - trader_cdlmorningstar — Morning Star
  - trader_cdlonneck — On-Neck Pattern
  - trader_cdlpiercing — Piercing Pattern
  - trader_cdlrickshawman — Rickshaw Man
  - trader_cdlrisefall3methods — Rising/Falling Three Methods
  - trader_cdlseparatinglines — Separating Lines
  - trader_cdlshootingstar — Shooting Star
  - trader_cdlshortline — Short Line Candle
  - trader_cdlspinningtop — Spinning Top
  - trader_cdlstalledpattern — Stalled Pattern
  - trader_cdlsticksandwich — Stick Sandwich
  - trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)
  - trader_cdltasukigap — Tasuki Gap
  - trader_cdlthrusting — Thrusting Pattern
  - trader_cdltristar — Tristar Pattern
  - trader_cdlunique3river — Unique 3 River
  - trader_cdlupsidegap2crows — Upside Gap Two Crows
  - trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods
  - trader_ceil — Vector Ceil
  - trader_cmo — Chande Momentum Oscillator
  - trader_correl — Pearson's Correlation Coefficient (r)
  - trader_cos — Vector Trigonometric Cos
  - trader_cosh — Vector Trigonometric Cosh
  - trader_dema — Double Exponential Moving Average
  - trader_div — Vector Arithmetic Div
  - trader_dx — Directional Movement Index
  - trader_ema — Exponential Moving Average
  - trader_errno — Get error code
  - trader_exp — Vector Arithmetic Exp
  - trader_floor — Vector Floor
  - trader_get_compat — Get compatibility mode
  - trader_get_unstable_period — Get unstable period
  - trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period
  - trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase
  - trader_ht_phasor — Hilbert Transform - Phasor Components
  - trader_ht_sine — Hilbert Transform - SineWave
  - trader_ht_trendline — Hilbert Transform - Instantaneous Trendline
  - trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode
  - trader_kama — Kaufman Adaptive Moving Average
  - trader_linearreg — Linear Regression
  - trader_linearreg_angle — Linear Regression Angle
  - trader_linearreg_intercept — Linear Regression Intercept
  - trader_linearreg_slope — Linear Regression Slope
  - trader_ln — Vector Log Natural
  - trader_log10 — Vector Log10
  - trader_ma — Moving average
  - trader_macd — Moving Average Convergence/Divergence
  - trader_macdext — MACD with controllable MA type
  - trader_macdfix — Moving Average Convergence/Divergence Fix 12/26
  - trader_mama — MESA Adaptive Moving Average
  - trader_mavp — Moving average with variable period
  - trader_max — Highest value over a specified period
  - trader_maxindex — Index of highest value over a specified period
  - trader_medprice — Median Price
  - trader_mfi — Money Flow Index
  - trader_midpoint — MidPoint over period
  - trader_midprice — Midpoint Price over period
  - trader_min — Lowest value over a specified period
  - trader_minindex — Index of lowest value over a specified period
  - trader_minmax — Lowest and highest values over a specified period
  - trader_minmaxindex — Indexes of lowest and highest values over a specified period
  - trader_minus_di — Minus Directional Indicator
  - trader_minus_dm — Minus Directional Movement
  - trader_mom — Momentum
  - trader_mult — Vector Arithmetic Mult
  - trader_natr — Normalized Average True Range
  - trader_obv — On Balance Volume
  - trader_plus_di — Plus Directional Indicator
  - trader_plus_dm — Plus Directional Movement
  - trader_ppo — Percentage Price Oscillator
  - trader_roc — Rate of change : ((price/prevPrice)-1)*100
  - trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice
  - trader_rocr — Rate of change ratio: (price/prevPrice)
  - trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100
  - trader_rsi — Relative Strength Index
  - trader_sar — Parabolic SAR
  - trader_sarext — Parabolic SAR - Extended
  - trader_set_compat — Set compatibility mode
  - trader_set_unstable_period — Set unstable period
  - trader_sin — Vector Trigonometric Sin
  - trader_sinh — Vector Trigonometric Sinh
  - trader_sma — Simple Moving Average
  - trader_sqrt — Vector Square Root
  - trader_stddev — Standard Deviation
  - trader_stoch — Stochastic
  - trader_stochf — Stochastic Fast
  - trader_stochrsi — Stochastic Relative Strength Index
  - trader_sub — Vector Arithmetic Subtraction
  - trader_sum — Summation
  - trader_t3 — Triple Exponential Moving Average (T3)
  - trader_tan — Vector Trigonometric Tan
  - trader_tanh — Vector Trigonometric Tanh
  - trader_tema — Triple Exponential Moving Average
  - trader_trange — True Range
  - trader_trima — Triangular Moving Average
  - trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA
  - trader_tsf — Time Series Forecast
  - trader_typprice — Typical Price
  - trader_ultosc — Ultimate Oscillator
  - trader_var — Variance
  - trader_wclprice — Weighted Close Price
  - trader_willr — Williams' %R
  - trader_wma — Weighted Moving Average

- BC Math — BCMath Rechnen mit beliebiger Genauigkeit
  - Installation/Konfiguration
  - BC Math Funktionen
  - BcMath\Number — The BcMath\Number class
- GMP — GNU Multiple Precision
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Beispiele
  - GMP Funktionen
  - GMP — The GMP class
- Math — Mathematische Funktionen
  - Vordefinierte Konstanten
  - RoundingMode — The RoundingMode Enum
  - Mathematische Funktionen
- Statistics
  - Installation/Konfiguration
  - Statistic Funktionen
- Trader — Technical Analysis for Traders
  - Installation/Konfiguration
  - Vordefinierte Konstanten
  - Trader Funktionen

# Non-Text MIME-Ausgaben

# Forms Data Format Funktionen

# Einführung

Forms Data Format (FDF) ist ein Format zur Verarbeitung von Formularen innerhalb von PDF-Dokumenten. Weiterführende Informationen zu FDF und dessen Verwendung sind unter » http://www.adobe.com/devnet/acrobat/fdftoolkit.html zu finden.

Der Ansatz den FDF verfolgt, ist vergleichbar mit dem üblicher HTML-Formulare. Die wesentlichen Unterschiede liegen in der Übertragung der Daten nach Absenden des Formulars (dies ist das eigentliche Form Data Format), sowie in dem Format des Dokuments welches das Formular enthält(PDF). Die Verarbeitung der FDF-Daten ist eine der Möglichkeiten, die die FDF-Funktionen bereitstellen. Darüber hinaus kann man beispielsweise innerhalb eines vorhandenen PDF-Formulars die Input-Felder dynamisch mit Daten füllen, ohne das Formular selbst zu verändern. Hierzu erzeugt man das FDF-Dokument (fdf_create()), setzt die Werte der jeweiligen Input-Felder (fdf_set_value()) und verbindet es mit dem jeweiligen PDF-Formular (fdf_set_file()). Nachdem man das FDF-Dokument, mit dem passenden MimeType `application/vnd.fdf` versehen, ausgegeben hat, erkennt das Acrobat-Reader-PlugIn des Browsers den MimeType und füllt das Zielformular mit den Daten des FDF-Dokuments.

Betrachtet man ein FDF-Dokument mit einem Text-Editor, findet sich dort ein Katalog-Objekt `FDF`. Dieses Objekt kann mehrere Einträge der Art `Fields`, `F`, `Status` etc.. enthalten. Die gebräuchlichsten Einträge sind `Fields`, welches zu einer Anzahl von Input-Feldern verweist, sowie `F` das den Dateinamen des zugehörigen PDF-Dokuments enthält. Diese Einträge finden sich in der FDF-Dokumentation unter /F-Key oder /Status-Key. Modifikationen dieser Einträge werden mit Hilfe der Funktionen fdf_set_file() und fdf_set_status() vorgenommen. Felder werden u.a. mit fdf_set_value(), fdf_set_opt() modifiziert.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Ressource-Typen

## Anforderungen

Benötigt wird das FDF-Toolkit-SDK, welches unter » http://www.adobe.com/devnet/acrobat/fdftoolkit.html heruntergeladen werden kann. Ab PHP-Version 4.3.0 ist mindestens die Version 5.0 des FDF-SDKs erforderlich. Die FDF-Toolkit-Bibliothek steht ausschließlich vorkompiliert zur Verfügung. Von Adobe unterstütze Plattformen sind Win32, Linux, Solaris und AIX.

## Installation

Diese Erweiterung wird als nicht mehr gepflegt betrachtet und es gibt dort keine Aktivität mehr. Der Quellcode für diese Erweiterung steht jedoch weiterhin innerhalb des PECL SVN hier zur Verfügung: » https://svn.php.net/viewvc/pecl/fdf.

Diese Erweiterung ist nicht mehr mit PHP gebündelt.

> Hinweis: Wenn bei der Konfiguration von PHP mit Fdftk-Unterstützung Probleme auftreten, prüfen Sie, ob sich die Includedatei fdftk.h und die Bibliothek libfdftk.so tatsächlich im angegebenen Verzeichnis befinden. Das configure-Skript unterstützt sowohl die Verzeichnisstruktur der FDF SDK Distribution als auch die übliche DIR/include- / DIR/lib-Struktur. Sie können daher entweder direkt auf das entpackte Distributionsverzeichnis verweisen oder die Include- und Bibliotheksdateien in den entsprechenden Verzeichnissen Ihres Systems, z. B. /usr/local/include und /usr/local/lib, ablegen und dann mit --with-fdftk=/usr/local konfigurieren.

> Hinweis: Hinweis für Win32 Benutzer
> Diese Erweiterung benötigt DLL-Dateien. die für Windows verfügbar seien müssen. Der FAQ-Eintrag " Wie füge ich unter Windows PATH mein PHP-Verzeichnis hinzu?" gibt hierzu weitere Informationen. Obwohl ein einfaches Kopieren der DLL-Dateien vom PHP-Verzeichnis in den Windows-Systemordner auch funktioniert (weil der Systemordner immer im PATH enthalten ist), ist dieses Vorgehen nicht empfehlenswert. Diese Erweiterung benötigt die folgenden Dateien im PATH: fdftk.dll

## Ressource-Typen

Die meisten FDF-Funktionen benötigen eine `fdf`-Ressource als ersten Parameter. Eine `fdf`-Ressource ist ein Zeiger auf eine geöffnete FDF-Datei. `fdf`-Ressourcen können mit den Funktionen fdf_create(), fdf_open() und fdf_open_string() erstellt werden.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

`FDFValue` (int)
`FDFStatus` (int)
`FDFFile` (int)
`FDFID` (int)
`FDFFf` (int)
`FDFSetFf` (int)
`FDFClearFf` (int)
`FDFFlags` (int)
`FDFSetF` (int)
`FDFClrF` (int)
`FDFAP` (int)
`FDFAS` (int)
`FDFAction` (int)
`FDFAA` (int)
`FDFAPRef` (int)
`FDFIF` (int)
`FDFEnter` (int)
`FDFExit` (int)
`FDFDown` (int)
`FDFUp` (int)
`FDFFormat` (int)
`FDFValidate` (int)
`FDFKeystroke` (int)
`FDFCalculate` (int)
`FDFNormalAP` (int)
`FDFRolloverAP` (int)
`FDFDownAP` (int)

# Beispiele

Das folgende Beispiel zeigt die Auswertung der Formular Daten.

Beispiel #1 Auswertung eines FDF_Dokuments

    <?php
    // Speichern der FDF Daten in eine temporäre Datei
    $fdffp = fopen("test.fdf", "w");
    fwrite($fdffp, $HTTP_FDF_DATA, strlen($HTTP_FDF_DATA));
    fclose($fdffp);

    // Öffnen der temporären Datei und Auswertung der Daten
    // Das PDF Formular enthält verschiedene Eingabefelder mit den zugehörigen Namen
    // band, datum, kommentar, verleger, bearbeiter, sowie zwei Checkboxen
    // zeige_verleger und zeige_bearbeiter.

    $fdf = fdf_open("test.fdf");
    $band = fdf_get_value($fdf, "band");
    echo "Das Feld Band hat den Wert '<b>$band</b>'<br />";

    $datum = fdf_get_value($fdf, "datum");
    echo "Das Feld Datum hat den Wert '<b>$datum</b>'<br />";

    $kommentar = fdf_get_value($fdf, "kommentar");
    echo "Das Feld Kommentar hat den Wert '<b>$kommentar</b>'<br />";

    if (fdf_get_value($fdf, "zeige_verleger") == "On") {
        $verleger = fdf_get_value($fdf, "verleger");
        echo "Das Feld Verleger hat den Wert '<b>$verleger</b>'<br />";
    } else {
      echo "Verleger soll nicht angezeigt werden.<br />";
    }

    if (fdf_get_value($fdf, "zeige_bearbeiter") == "On") {
      $bearbeiter = fdf_get_value($fdf, "bearbeiter");
      echo "Das Feld Bearbeiter hat den Wert '&<b>$bearbeiter</b>'<br />";
    } else {
      echo "Bearbeiter soll nicht angezeigt werden.<br />";
    }
    fdf_close($fdf);
    ?>

# FDF Funktionen

# fdf_add_doc_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_doc_javascript — Fügt JavaScript-Code in ein FDF-Dokument ein

### Beschreibung

function fdf_add_doc_javascript(resource `$fdf_document`, string `$script_name`, string `$script_code`): bool

Fügt ein Script zum FDF-Dokument, welches Acrobat zu den doc-level-Scripts eines Dokuments hinzufügt, sobald das FDF importiert wurde.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`script_name`
  Der Scriptname.
`script_code`
  Der Scriptcode. Es wird unbedingt empfohlen `\r` für Zeilenumbrüche innerhalb des Scriptcodes zu verwenden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 JavaScript-Code zu einem FDF hinzufügen

    <?php
    $fdf = fdf_create();
    fdf_add_doc_javascript($fdf, "PlusOne", "function PlusOne(x)\r{\r  return x+1;\r}\r");
    fdf_save($fdf);
    ?>

erzeugt ein FDF wie folgt:

    %FDF-1.2
    %âãÏÓ
    1 0 obj
    <<
    /FDF << /JavaScript << /Doc [ (PlusOne)(function PlusOne\(x\)\r{\r  return x+1;\r}\r)] >> >>
    >>
    endobj
    trailer
    <<
    /Root 1 0 R

    >>
    %%EOF

# fdf_add_template

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_add_template — Fügt dem FDF Dokument ein Template hinzu

### Beschreibung

function fdf_add_template(
resource `$fdf_document`,
int `$newpage`,
string `$filename`,
string `$template`,
int `$rename`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# fdf_close

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_close — Schließt ein FDF Dokument

### Beschreibung

function fdf_close(resource `$fdf_document`): void

Schließt das FDF Dokument.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Siehe auch

- fdf_open() - Öffnet ein FDF Dokument

# fdf_create

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_create — Erzeugt ein neues FDF Dokument

### Beschreibung

function fdf_create(): resource

Erzeugt ein neues FDF Dokument.

Diese Funktion wird benötigt, wenn man Eingabefelder in einem PDF Dokument mit Daten belegen möchte.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt ein FDF-Dokument-Handle zurück, oder `false` im Fehlerfall.

### Beispiele

Beispiel #1 Füllen von Formularwerten in einem PDF Dokument

    <?php
    $outfdf = fdf_create();
    fdf_set_value($outfdf, "band", $band, 0);

    fdf_set_file($outfdf, "http:/testfdf/resultlabel.pdf");
    fdf_save($outfdf, "outtest.fdf");
    fdf_close($outfdf);
    Header("Content-type: application/vnd.fdf");
    $fp = fopen("outtest.fdf", "r");
    fpassthru($fp);
    unlink("outtest.fdf");
    ?>

### Siehe auch

- fdf_close() - Schließt ein FDF Dokument
- fdf_save() - Speichern eines FDF Dokuments
- fdf_open() - Öffnet ein FDF Dokument

# fdf_enum_values

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_enum_values — Ruft für jeden Dokumentwert eine benutzerdefinierte Funktion auf

### Beschreibung

function fdf_enum_values(resource `$fdf_document`, callable `$function`, mixed `$userdata` = ?): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# fdf_errno

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_errno — Gibt den Fehlercode der letzten FDF Operation zurück

### Beschreibung

function fdf_errno(): int

Liefert den Fehlercode der vom letzten FDF Funktionsaufruf gesetzt wurde.

Eine textuelle Beschreibung des Fehlers kann mit der Funktion fdf_error() ermittelt werden.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Gibt den Fehlercode als Integer zurück oder 0 wenn kein Fehler aufgetreten ist.

### Siehe auch

- fdf_error() - Gibt die Beschrebung eines Fehlercodes zurück

# fdf_error

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_error — Gibt die Beschrebung eines Fehlercodes zurück

### Beschreibung

function fdf_error(int `$error_code` = -1): string

Gibt eine textuelle Beschreibung des in `error_code` übergebenen FDF Fehlercodes zurück.

### Parameter-Liste

`error_code`
  Ein von der Funktion fdf_errno() zurückgegebener Fehlercode. Wenn kein Fehlercode übergeben wurde wird der von der letzten Operation gesetzte interne Code genutzt.

### Rückgabewerte

Gibt die Fehlerbeschreibung als String zurück. Ist kein Fehler aufgetreten wird der String `no error` zurückgegeben.

### Siehe auch

- fdf_errno() - Gibt den Fehlercode der letzten FDF Operation zurück

# fdf_get_ap

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_ap — Get the appearance of a field

### Beschreibung

function fdf_get_ap(
resource `$fdf_document`,
string `$field`,
int `$face`,
string `$filename`
): bool

Gets the appearance of a `field` (i.e. the value of the /AP key) and stores it in a file.

### Parameter-Liste

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`field`
`face`
  The possible values are `FDFNormalAP`, `FDFRolloverAP` and `FDFDownAP`.
`filename`
  The appearance will be stored in this parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# fdf_get_attachment

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_attachment — Extracts uploaded file embedded in the FDF

### Beschreibung

function fdf_get_attachment(resource `$fdf_document`, string `$fieldname`, string `$savepath`): array

Extracts a file uploaded by means of the "file selection" field `fieldname` and stores it under `savepath`.

### Parameter-Liste

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`fieldname`
`savepath`
  May be the name of a plain file or an existing directory in which the file is to be created under its original name. Any existing file under the same name will be overwritten.

  > Hinweis: There seems to be no other way to find out the original filename but to store the file using a directory as `savepath` and check for the basename it was stored under.

### Rückgabewerte

The returned array contains the following fields:

- `path` - path where the file got stored
- `size` - size of the stored file in bytes
- `type` - mimetype if given in the FDF

### Beispiele

Beispiel #1 Storing an uploaded file

    <?php
      $fdf = fdf_open_string($HTTP_FDF_DATA);
      $data = fdf_get_attachment($fdf, "filename", "/tmpdir");
      echo "The uploaded file is stored in $data[path]";
    ?>

# fdf_get_encoding

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_encoding — Liefert den Wert des /Encoding Schlüssels

### Beschreibung

function fdf_get_encoding(resource `$fdf_document`): string

Liefert den Wert des `/Encoding` Schlüssels.

### Parameter-Liste

`fdf_document`
  Eine FDF Dokumentresource wie von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben.

### Rückgabewerte

Gibt das Encoding als String zurück. Wenn das Standardencoding `PDFDocEncoding/Unicode` benutzt wird wird nur ein Leerstring zurückgegeben.

### Siehe auch

- fdf_set_encoding() - Legt die FDF Zeichenkodierung fest

# fdf_get_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_file — Gibt den Wert des /F Schlüssels zurück

### Beschreibung

function fdf_get_file(resource `$fdf_document`): string

Gibt den Wert des `/F` Schlüssels zurück.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.

### Rückgabewerte

Gibt den Wert des Schlüssels als Zeichenkette zurück.

### Siehe auch

- fdf_set_file() - Definiert ein PDF-Dokument, das FDF-Daten anzeigen soll

# fdf_get_flags

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_flags — Ermittelt die Flags eines Feldes

### Beschreibung

function fdf_get_flags(resource `$fdf_document`, string `$fieldname`, int `$whichflags`): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# fdf_get_opt

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECLv)

fdf_get_opt — Liefert einen Wert aus dem Optionsarray eines Feldes

### Beschreibung

function fdf_get_opt(resource `$fdf_document`, string `$fieldname`, int `$element` = -1): mixed
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# fdf_get_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_status — Gibt den Wert des /STATUS Schlüssels zurück

### Beschreibung

function fdf_get_status(resource `$fdf_document`): string

Gibt den Wert des `/STATUS` Schlüssels zurück.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.

### Rückgabewerte

Gibt den Wert des Schlüssels als Zeichenkette zurück.

### Siehe auch

- fdf_set_status() - Setzt den Wert des /STATUS Schlüssels

# fdf_get_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_value — Gibt den Wert eines Feldes zurück

### Beschreibung

function fdf_get_value(resource `$fdf_document`, string `$fieldname`, int `$which` = -1): mixed

Gibt den Wert des abgefragten Felds zurück.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`fieldname`
  Name des FDF-Felds als Zeichenkette.
`which`
  Elemente eines Arrays können abgefragt werden, indem dieser optionale Parameter übergeben wird. Die Elemente des abzufragenden Arrays starten bei Null. Bei Nicht-Array-Feldern wird dieser Parameter ignoriert.

### Rückgabewerte

Returns the field value.

### Siehe auch

- fdf_set_value() - Legt den Wert eines Feldes fest

# fdf_get_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_get_version — Liefert die Versionsnummer einer FDF-Datei oder des APIs

### Beschreibung

function fdf_get_version(resource `$fdf_document` = ?): string

Gibt die FDF-Version des angegebenen Dokuments zurück. Wird kein Dokument übergeben so wird die API-Version des Tookits zurückgegeben.

### Parameter-Liste

`fdf_document`
  Eine FDF-Dokumentressource wie von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben.

### Rückgabewerte

Gibt die Versionsnumer als String zurück. Für das aktuelle FDF-Toolkit 5.0 ist die Versionsnummer `5.0`, die Versionsnummer eines Dokuments ist entweder `1.2`, `1.3` oder `1.4`.

### Siehe auch

- fdf_set_version() - Sets version number for a FDF file

# fdf_header

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVNf)

fdf_header — Setzt FDF-spezifische Header

### Beschreibung

function fdf_header(): void

Dies ist eine Hilfsfunktion die die nötigen HTTP Header für FDF Dokumente setzt. Sie setzt den `Content-type:` auf `application/vnd.fdf`.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

# fdf_next_field_name

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_next_field_name — Gibt den Namen des nächsten Feldes zurück

### Beschreibung

function fdf_next_field_name(resource `$fdf_document`, string `$fieldname` = ?): string

Gibt den Namen des Feldes nach dem angegebenen Feld zurück. Dieser Name kann mit mehreren Funktionen verwendet werden.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`fieldname`
  Name des FDF-Felds als Zeichenkette. Wenn nicht angegeben, wird das erste Feld angenommen.

### Rückgabewerte

Gibt den Feldnamen als Zeichenkette zurück.

### Beispiele

Beispiel #1 Alle Feldnamen in einem FDF ermitteln

    <?php
    $fdf = fdf_open($HTTP_FDF_DATA);
    for ($field = fdf_next_field_name($fdf);
        $field != "";
        $field = fdf_next_field_name($fdf, $field)) {
        echo "field: $field\n";
    }
    ?>

### Siehe auch

- fdf_get_value() - Gibt den Wert eines Feldes zurück

# fdf_open

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open — Öffnet ein FDF Dokument

### Beschreibung

function fdf_open(string `$filename`): resource

Öffnet eine Datei mit Formulardaten.

Sie können ebenfalls fdf_open_string() verwenden, um die Ergebnisse einer PDF-Formular POST-Anfrage zu verarbeiten.

### Parameter-Liste

`filename`
  Pfad zur FDF-Datei. Diese Datei muss entweder die von einem PDF Formular zurückgegebenen Formulardaten oder Formulardaten, die mit fdf_create() und fdf_save() erzeugt wurden, enthalten.

### Rückgabewerte

Gibt ein FDF-Dokument-Handle zurück, oder `false` im Fehlerfall.

### Beispiele

Beispiel #1 Zugang zu den Formulardaten

    <?php
    // Speichern der FDF Daten in eine temporäre Datei
    $fdffp = fopen("test.fdf", "w");
    fwrite($fdffp, $HTTP_FDF_DATA, strlen($HTTP_FDF_DATA));
    fclose($fdffp);

    // Öffnen der temporären Datei und Auswertung der Daten
    $fdf = fdf_open("test.fdf");
    ...
    fdf_close($fdf);
    ?>

### Siehe auch

- fdf_open_string() - Read a FDF document from a string
- fdf_close() - Schließt ein FDF Dokument
- fdf_create() - Erzeugt ein neues FDF Dokument
- fdf_save() - Speichern eines FDF Dokuments

# fdf_open_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_open_string — Read a FDF document from a string

### Beschreibung

function fdf_open_string(string `$fdf_data`): resource

Reads form data from a string.

You can use fdf_open_string() together with $HTTP_FDF_DATA to process FDF form input from a remote client.

### Parameter-Liste

`fdf_data`
  The data as returned from a PDF form or created using fdf_create() and fdf_save_string().

### Rückgabewerte

Returns a FDF document handle, or `false` on error.

### Beispiele

Beispiel #1 Accessing the form data

    <?php
    $fdf = fdf_open_string($HTTP_FDF_DATA);
    /* ... */
    fdf_close($fdf);
    ?>

### Siehe auch

- fdf_open() - Öffnet ein FDF Dokument
- fdf_close() - Schließt ein FDF Dokument
- fdf_create() - Erzeugt ein neues FDF Dokument
- fdf_save_string() - Returns the FDF document as a string

# fdf_remove_item

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_remove_item — Setzt den Zielrahmen für ein Formular

### Beschreibung

function fdf_remove_item(resource `$fdf_document`, string `$fieldname`, int `$item`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

# fdf_save

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save — Speichern eines FDF Dokuments

### Beschreibung

function fdf_save(resource `$fdf_document`, string `$filename` = ?): bool

Speichert ein FDF Dokument.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`filename`
  Wenn angegeben, wird das resultierende FDF in diesen Parameter geschrieben. Andernfals wird das FDF an der Standardausgabe von PHP ausgegeben.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fdf_close() - Schließt ein FDF Dokument
- fdf_create() - Erzeugt ein neues FDF Dokument
- fdf_save_string() - Returns the FDF document as a string

# fdf_save_string

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_save_string — Returns the FDF document as a string

### Beschreibung

function fdf_save_string(resource `$fdf_document`): string

Returns the FDF document as a string.

### Parameter-Liste

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().

### Rückgabewerte

Returns the document as a string, or `false` on error.

### Beispiele

Beispiel #1 Retrieving FDF as a string

    <?php
    $fdf = fdf_create();
    fdf_set_value($fdf, "foo", "bar");
    $str = fdf_save_string($fdf);
    fdf_close($fdf);
    echo $str;
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    %FDF-1.2
    %âãÏÓ
    1 0 obj
    <<
    /FDF << /Fields 2 0 R >>
    >>
    endobj
    2 0 obj
    [
    << /T (foo)/V (bar)>>
    ]
    endobj
    trailer
    <<
    /Root 1 0 R

    >>
    %%EOF

### Siehe auch

- fdf_open_string() - Read a FDF document from a string
- fdf_close() - Schließt ein FDF Dokument
- fdf_create() - Erzeugt ein neues FDF Dokument
- fdf_save() - Speichern eines FDF Dokuments

# fdf_set_ap

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_ap — Legt das Aussehen eines Feldes fest

### Beschreibung

function fdf_set_ap(
resource `$fdf_document`,
string `$field_name`,
int `$face`,
string `$filename`,
int `$page_number`
): bool

Legt das Aussehen eines Feldes (d.h. den Wert des `/AP` Schlüssels) fest.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`field_name`
`face`
  Die möglichen Werte sind `FDFNormalAP`, `FDFRolloverAP` und `FDFDownAP`.
`filename`
`page_number`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# fdf_set_encoding

(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_encoding — Legt die FDF Zeichenkodierung fest

### Beschreibung

function fdf_set_encoding(resource `$fdf_document`, string `$encoding`): bool

Legt die Zeichenkodierung des FDF Dokuments fest.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`encoding`
  Der Name der Zeichenkodierung. Folgende Werte werden unterstützt: "`Shift-JIS`", "`UHC`", "`GBK`" und "`BigFive`". Ein leerer String setzt die Kodierung auf den voreingestellten Wert PDFDocEncoding/Unicode.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# fdf_set_file

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_file — Definiert ein PDF-Dokument, das FDF-Daten anzeigen soll

### Beschreibung

function fdf_set_file(resource `$fdf_document`, string `$url`, string `$target_frame` = ?): bool

Wählt ein anderes PDF-Dokument aus, in dem FDF-Formulardaten angezeigt werden sollen, als das Formular dem sie entstammen.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`url`
  Sollte als absolute URL angegeben werden.
`target_frame`
  Der Rahmen in dem das Dokument angezeigt werden soll, kann mit diesem Parameter oder fdf_set_target_frame() festgelegt werden.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 FDF-Daten an ein zweites Formular übergeben

    <?php
      /* Inhaltstyp für Adobe FDF festlegen */
      fdf_header();

      /* neues FDF beginnen */
      $fdf = fdf_create();

      /* Feld "foo" auf Wert "bar" setzen */
      fdf_set_value($fdf, "foo", "bar");

      /* den Client anweisen, FDF-Daten unter Verwendung von "fdf_form.pdf" anzuzeigen */
      fdf_set_file($fdf, "http://www.example.com/fdf_form.pdf");

      /* FDF ausgeben */
      fdf_save($fdf);

      /* aufräumen */
      fdf_close($fdf);
    ?>

### Siehe auch

- fdf_get_file() - Gibt den Wert des /F Schlüssels zurück
- fdf_set_target_frame() - Set target frame for form display

# fdf_set_flags

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_flags — Setzt Flags eines Feldes

### Beschreibung

function fdf_set_flags(
resource `$fdf_document`,
string `$fieldname`,
int `$whichFlags`,
int `$newFlags`
): bool

Setzt bestimmte Flags des angegebenen Feldes.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`fieldname`
  Name des FDF-Felds als Zeichenkette.
`whichFlags`
`newFlags`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fdf_set_opt() - Legt eine Option eines Feldes fest

# fdf_set_javascript_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_javascript_action — Weist einem Feld eine JavaScript Aktion zu

### Beschreibung

function fdf_set_javascript_action(
resource `$fdf_document`,
string `$fieldname`,
int `$trigger`,
string `$script`
): bool

Weist dem angegebenen Feld eine JavaScript Aktion zu.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`fieldname`
  Name des FDF-Felds als Zeichenkette.
`trigger`
`script`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fdf_set_submit_form_action() - Setzt eine Submit-Form-Aktion für ein Feld

# fdf_set_on_import_javascript

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_on_import_javascript — Adds javascript code to be executed when Acrobat opens the FDF

### Beschreibung

function fdf_set_on_import_javascript(resource `$fdf_document`, string `$script`, bool `$before_data_import`): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Siehe auch

- fdf_add_doc_javascript() - Fügt JavaScript-Code in ein FDF-Dokument ein
- fdf_set_javascript_action() - Weist einem Feld eine JavaScript Aktion zu

# fdf_set_opt

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_opt — Legt eine Option eines Feldes fest

### Beschreibung

function fdf_set_opt(
resource `$fdf_document`,
string `$fieldname`,
int `$element`,
string `$str1`,
string `$str2`
): bool

Legt Optionen des angegebenen Felds fest.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`fieldname`
  Name des FDF-Felds als Zeichenkette.
`element`
`str1`
`str2`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fdf_set_flags() - Setzt Flags eines Feldes

# fdf_set_status

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_status — Setzt den Wert des /STATUS Schlüssels

### Beschreibung

function fdf_set_status(resource `$fdf_document`, string `$status`): bool

Setzt den Wert des `/STATUS` Schlüssels. Dieser wird bei der Anzeige in einem Warnungsfeld angezeigt.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`status`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fdf_get_status() - Gibt den Wert des /STATUS Schlüssels zurück

# fdf_set_submit_form_action

(PHP 4 >= 4.0.2, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_submit_form_action — Setzt eine Submit-Form-Aktion für ein Feld

### Beschreibung

function fdf_set_submit_form_action(
resource `$fdf_document`,
string `$fieldname`,
int `$trigger`,
string `$script`,
int `$flags`
): bool

Setzt eine Submit-Form-Aktion für das angegebene Feld.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`fieldname`
  Name des FDF-Felds als Zeichenkette.
`trigger`
`script`
`flags`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fdf_set_javascript_action() - Weist einem Feld eine JavaScript Aktion zu

# fdf_set_target_frame

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_target_frame — Set target frame for form display

### Beschreibung

function fdf_set_target_frame(resource `$fdf_document`, string `$frame_name`): bool

Sets the target frame to display a result PDF defined with fdf_save_file() in.

### Parameter-Liste

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`frame_name`
  The frame name, as a string.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fdf_save_file()

# fdf_set_value

(PHP 4, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_value — Legt den Wert eines Feldes fest

### Beschreibung

function fdf_set_value(
resource `$fdf_document`,
string `$fieldname`,
mixed `$value`,
int `$isName` = ?
): bool

Legt den `value` des angegebenen Feldes fest.

### Parameter-Liste

`fdf_document`
  Das FDF-Dokument-Handle, das von fdf_create(), fdf_open() oder fdf_open_string() zurückgegeben wurde.
`fieldname`
  Name des FDF-Felds als Zeichenkette.
`value`
  Dieser Parameter wird als String, oder falls der übergebene Wert ein Array ist, als Array gespeichert.
`isName`

  > Hinweis: In älteren Versionen des FDF-Toolkits legte der letzte Parameter fest, ob der Wert in einen PDF-Namen (= 1) konvertiert oder als PDf-String (= 0) behandelt werden sollte. Dieser Parameter wird in Version 5.0 des Toolkits nicht mehr benutzt. Aus Kompatibilitätsgründen wird der Parameter als optional unterstützt aber ignoriert.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fdf_get_value() - Gibt den Wert eines Feldes zurück
- fdf_remove_item() - Setzt den Zielrahmen für ein Formular

# fdf_set_version

(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL fdf SVN)

fdf_set_version — Sets version number for a FDF file

### Beschreibung

function fdf_set_version(resource `$fdf_document`, string `$version`): bool

Sets the FDF `version` for the given document.

Some features supported by this extension are only available in newer FDF versions.

### Parameter-Liste

`fdf_document`
  The FDF document handle, returned by fdf_create(), fdf_open() or fdf_open_string().
`version`
  The version number. For the current FDF toolkit 5.0, this may be either `1.2`, `1.3` or `1.4`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- fdf_get_version() - Liefert die Versionsnummer einer FDF-Datei oder des APIs

## Inhaltsverzeichnis

- fdf_add_doc_javascript — Fügt JavaScript-Code in ein FDF-Dokument ein
- fdf_add_template — Fügt dem FDF Dokument ein Template hinzu
- fdf_close — Schließt ein FDF Dokument
- fdf_create — Erzeugt ein neues FDF Dokument
- fdf_enum_values — Ruft für jeden Dokumentwert eine benutzerdefinierte Funktion auf
- fdf_errno — Gibt den Fehlercode der letzten FDF Operation zurück
- fdf_error — Gibt die Beschrebung eines Fehlercodes zurück
- fdf_get_ap — Get the appearance of a field
- fdf_get_attachment — Extracts uploaded file embedded in the FDF
- fdf_get_encoding — Liefert den Wert des /Encoding Schlüssels
- fdf_get_file — Gibt den Wert des /F Schlüssels zurück
- fdf_get_flags — Ermittelt die Flags eines Feldes
- fdf_get_opt — Liefert einen Wert aus dem Optionsarray eines Feldes
- fdf_get_status — Gibt den Wert des /STATUS Schlüssels zurück
- fdf_get_value — Gibt den Wert eines Feldes zurück
- fdf_get_version — Liefert die Versionsnummer einer FDF-Datei oder des APIs
- fdf_header — Setzt FDF-spezifische Header
- fdf_next_field_name — Gibt den Namen des nächsten Feldes zurück
- fdf_open — Öffnet ein FDF Dokument
- fdf_open_string — Read a FDF document from a string
- fdf_remove_item — Setzt den Zielrahmen für ein Formular
- fdf_save — Speichern eines FDF Dokuments
- fdf_save_string — Returns the FDF document as a string
- fdf_set_ap — Legt das Aussehen eines Feldes fest
- fdf_set_encoding — Legt die FDF Zeichenkodierung fest
- fdf_set_file — Definiert ein PDF-Dokument, das FDF-Daten anzeigen soll
- fdf_set_flags — Setzt Flags eines Feldes
- fdf_set_javascript_action — Weist einem Feld eine JavaScript Aktion zu
- fdf_set_on_import_javascript — Adds javascript code to be executed when Acrobat opens the FDF
- fdf_set_opt — Legt eine Option eines Feldes fest
- fdf_set_status — Setzt den Wert des /STATUS Schlüssels
- fdf_set_submit_form_action — Setzt eine Submit-Form-Aktion für ein Feld
- fdf_set_target_frame — Set target frame for form display
- fdf_set_value — Legt den Wert eines Feldes fest
- fdf_set_version — Sets version number for a FDF file

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- Beispiele
- FDF — FDF Funktionen
  - fdf_add_doc_javascript — Fügt JavaScript-Code in ein FDF-Dokument ein
  - fdf_add_template — Fügt dem FDF Dokument ein Template hinzu
  - fdf_close — Schließt ein FDF Dokument
  - fdf_create — Erzeugt ein neues FDF Dokument
  - fdf_enum_values — Ruft für jeden Dokumentwert eine benutzerdefinierte Funktion auf
  - fdf_errno — Gibt den Fehlercode der letzten FDF Operation zurück
  - fdf_error — Gibt die Beschrebung eines Fehlercodes zurück
  - fdf_get_ap — Get the appearance of a field
  - fdf_get_attachment — Extracts uploaded file embedded in the FDF
  - fdf_get_encoding — Liefert den Wert des /Encoding Schlüssels
  - fdf_get_file — Gibt den Wert des /F Schlüssels zurück
  - fdf_get_flags — Ermittelt die Flags eines Feldes
  - fdf_get_opt — Liefert einen Wert aus dem Optionsarray eines Feldes
  - fdf_get_status — Gibt den Wert des /STATUS Schlüssels zurück
  - fdf_get_value — Gibt den Wert eines Feldes zurück
  - fdf_get_version — Liefert die Versionsnummer einer FDF-Datei oder des APIs
  - fdf_header — Setzt FDF-spezifische Header
  - fdf_next_field_name — Gibt den Namen des nächsten Feldes zurück
  - fdf_open — Öffnet ein FDF Dokument
  - fdf_open_string — Read a FDF document from a string
  - fdf_remove_item — Setzt den Zielrahmen für ein Formular
  - fdf_save — Speichern eines FDF Dokuments
  - fdf_save_string — Returns the FDF document as a string
  - fdf_set_ap — Legt das Aussehen eines Feldes fest
  - fdf_set_encoding — Legt die FDF Zeichenkodierung fest
  - fdf_set_file — Definiert ein PDF-Dokument, das FDF-Daten anzeigen soll
  - fdf_set_flags — Setzt Flags eines Feldes
  - fdf_set_javascript_action — Weist einem Feld eine JavaScript Aktion zu
  - fdf_set_on_import_javascript — Adds javascript code to be executed when Acrobat opens the FDF
  - fdf_set_opt — Legt eine Option eines Feldes fest
  - fdf_set_status — Setzt den Wert des /STATUS Schlüssels
  - fdf_set_submit_form_action — Setzt eine Submit-Form-Aktion für ein Feld
  - fdf_set_target_frame — Set target frame for form display
  - fdf_set_value — Legt den Wert eines Feldes fest
  - fdf_set_version — Sets version number for a FDF file

# GNU Privacy Guard

# Einführung

Dieses Modul ermöglicht es, mit » gnupg zu interagieren.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation

## Anforderungen

Diese Erweitung benötigt die » gpgme-Bibliothek

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/gnupg.

# Vordefinierte Konstanten

`GNUPG_SIG_MODE_NORMAL` (int)
`GNUPG_SIG_MODE_DETACH` (int)
`GNUPG_SIG_MODE_CLEAR` (int)
`GNUPG_VALIDITY_UNKNOWN` (int)
`GNUPG_VALIDITY_UNDEFINED` (int)
`GNUPG_VALIDITY_NEVER` (int)
`GNUPG_VALIDITY_MARGINAL` (int)
`GNUPG_VALIDITY_FULL` (int)
`GNUPG_VALIDITY_ULTIMATE` (int)
`GNUPG_PROTOCOL_OpenPGP` (int)
`GNUPG_PROTOCOL_CMS` (int)
`GNUPG_SIGSUM_VALID` (int)
`GNUPG_SIGSUM_GREEN` (int)
`GNUPG_SIGSUM_RED` (int)
`GNUPG_SIGSUM_KEY_REVOKED` (int)
`GNUPG_SIGSUM_KEY_EXPIRED` (int)
`GNUPG_SIGSUM_KEY_MISSING` (int)
`GNUPG_SIGSUM_SIG_EXPIRED` (int)
`GNUPG_SIGSUM_CRL_MISSING` (int)
`GNUPG_SIGSUM_CRL_TOO_OLD` (int)
`GNUPG_SIGSUM_BAD_POLICY` (int)
`GNUPG_SIGSUM_SYS_ERROR` (int)
`GNUPG_ERROR_WARNING` (int)
`GNUPG_ERROR_EXCEPTION` (int)
`GNUPG_ERROR_SILENT` (int)

# Beispiele

## Inhaltsverzeichnis

- Signieren eines Textes mit Klartextsignatur

## Signieren eines Textes mit Klartextsignatur

In diesem Beispiel wird ein gegebener Text mit Klartextsignatur signiert.

Beispiel #1 Erstellen einer Klatext-Signatur mit gnupg (prozedural)

    <?php
    // gnupg initialisieren
    $res = gnupg_init();
    // wird nicht benötigt; Clearsign ist voreingestellt.
    gnupg_setsignmode($res,GNUPG_SIG_MODE_CLEAR);
    // Schlüssel mit Passphrase 'test' zum Signieren hinzufügen
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    // signieren
    $signed = gnupg_sign($res,"just a test");
    echo $signed;
    ?>

Beispiel #2 Erstellen einer Klatext-Signatur mit gnupg (objektorientiert)

    <?php
    // neue Klasse
    $gnupg = new gnupg();
    // wird nicht benötigt; Clearsign ist voreingestellt.
    $gnupg->setsignmode(gnupg::SIG_MODE_CLEAR);
    // Schlüssel mit Passphrase 'test' zum Signieren hinzufügen
    $gnupg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    // signieren
    $signed = $gnupg->sign("just a test");
    echo $signed;
    ?>

Beispiel #3 keylistiterator

Diese Erweiterung enthält auch einen Iterator für den Schlüsselbund.

    <?php
    // Erstellen eines neuen Iterators, der alle öffentlichen Schlüssel auflistet,
    // die auf "example" passen
    foreach($iterator as $fingerprint => $userid){
        echo $fingerprint." -> ".$userid."\n";
    }
    ?>

# GnuPG Funktionen

# Anmerkungen

Diese Erweiterung verwendet den Schlüsselbund des aktuellen Benutzers. Dieser Schlüsselbund ist normalerweise unter ~/.gnupg/ zu finden. Um einen benutzerdefinierten Pfad festzulegen, kann der Pfad zum Schlüsselbund in der Umgebungsvariablen GNUPGHOME gespeichert werden. Siehe hierzu putenv für weitere Informationen.

Einige Funktionen erfordern die Spezifikationen des Schlüssels. Diese Spezifikation kann irgendetwas sein, das den Schlüssel einzigartig macht (User-ID, Schlüssel-ID, Fingerabdruck, ...). In dieser Dokumentation wird in allen Beispielen der Fingerabdruck verwendet.

> Hinweis: Als Alternative zu den explizit dokumentierten Funktionen, die Ressourcen (resource) verwenden, kann auch der objektorientierte Stil mit gnupg-Objekten verwendet werden.

# gnupg_adddecryptkey

(PECL gnupg >= 0.5)

gnupg_adddecryptkey — Fügt einen Schlüssel für Entschlüsselung hinzu

### Beschreibung

function gnupg_adddecryptkey(resource `$identifier`, string `$fingerprint`, string `$passphrase`): bool

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`fingerprint`

  Der 'Fingerprint'-Schlüssel.

`passphrase`
  Das Passwort.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Verwendungsbeispiel gnupg_adddecryptkey()

    <?php
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

Beispiel #2 OO gnupg_adddecryptkey() Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

# gnupg_addencryptkey

(PECL gnupg >= 0.5)

gnupg_addencryptkey — Fügt einen Schlüssel zur Verschlüsselung hinzu

### Beschreibung

function gnupg_addencryptkey(resource `$identifier`, string `$fingerprint`): bool

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`fingerprint`

  Der 'Fingerprint'-Schlüssel.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Prozedurales gnupg_addencryptkey() Beispiel

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_addencryptkey()-Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_addsignkey

(PECL gnupg >= 0.5)

gnupg_addsignkey — Fügt einen Schlüssel für Signierung hinzu

### Beschreibung

function gnupg_addsignkey(resource `$identifier`, string `$fingerprint`, string `$passphrase` = ?): bool

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`fingerprint`

  Der 'Fingerprint'-Schlüssel.

`passphrase`
  Das Passwort.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Prozedurales gnupg_addsignkey() Beispiel

    <?php
    $res = gnupg_init();
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_addsignkey()-Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    ?>

# gnupg_cleardecryptkeys

(PECL gnupg >= 0.5)

gnupg_cleardecryptkeys — Entfernt alle Schlüssel, die vorher für Entschlüsselung hinterlegt wurden

### Beschreibung

function gnupg_cleardecryptkeys(resource `$identifier`): bool

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Prozedurales gnupg_cleardecryptkeys() Beispiel

    <?php
    $res = gnupg_init();
    gnupg_cleardecryptkeys($res);
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_cleardecryptkeys() Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->cleardecryptkeys();
    ?>

# gnupg_clearencryptkeys

(PECL gnupg >= 0.5)

gnupg_clearencryptkeys — Entfernt alle Schlüssel, die vorher zur Verschlüsselung hinterlegt wurden

### Beschreibung

function gnupg_clearencryptkeys(resource `$identifier`): bool

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Prozedurales gnupg_clearencryptkeys() Beispiel

    <?php
    $res = gnupg_init();
    gnupg_clearencryptkeys($res);
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_clearencryptkeys() Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->clearencryptkeys();
    ?>

# gnupg_clearsignkeys

(PECL gnupg >= 0.5)

gnupg_clearsignkeys — Entfernt alle Schlüssel die vorher zur Signierung hinterlegt wurden

### Beschreibung

function gnupg_clearsignkeys(resource `$identifier`): bool

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Prozedurales gnupg_clearsignkeys() Beispiel

    <?php
    $res = gnupg_init();
    gnupg_clearsignkeys($res);
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_clearsignkeys() Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->clearsignkeys();
    ?>

# gnupg_decrypt

(PECL gnupg >= 0.1)

gnupg_decrypt — Entschlüsselt einen gegebenen Text

### Beschreibung

function gnupg_decrypt(resource `$identifier`, string `$text`): string|false

Entschlüsselt einen gegebenen Text mit den Schlüsseln, die mit gnupg_adddecryptkey hinterlegt wurden.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`text`
  Der zu entschlüsselnde Text.

### Rückgabewerte

Bei Erfolg gibt diese Funktion den entschlüsselten Text zurück. Bei einem Fehler gibt diese Funktion `false` zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_decrypt()-Beispiel

    <?php
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $plain = gnupg_decrypt($res,$encrypted_text);
    echo $plain;
    ?>

Beispiel #2 OO (objektorientiertes)gnupg_decrypt()-Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $plain = $gpg->decrypt($encrypted_text);
    echo $plain;
    ?>

# gnupg_decryptverify

(PECL gnupg >= 0.2)

gnupg_decryptverify — Entschlüsselt und vertifiziert einen gegebenen Text

### Beschreibung

function gnupg_decryptverify(resource `$identifier`, string `$text`, string `&$plaintext`): array|false

Entschlüsselt und verifiziert einen gegebenen Text und gibt Informationen über die Signatur zurück.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`text`
  Der zu entschlüsselnde Text.
`plaintext`
  Der Parameter `plaintext` wird mit dem entschlüsselten Text gefüllt.

### Rückgabewerte

Bei Erfolgg gibt die Funktion Informationen über die Signatur und füllt den Parameter `plaintext` mit dem entschlüsselten Text. Bei einem Fehler gibt diese Funktion `false` zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_decryptverify()-Beispiel

    <?php
    $plaintext = "";
    $res = gnupg_init();
    gnupg_adddecryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $info = gnupg_decryptverify($res,$text,$plaintext);
    print_r($info);
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_decryptverify()-Beispiel

    <?php
    $plaintext = "";
    $gpg = new gnupg();
    $gpg->adddecryptkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $info = $gpg->decryptverify($text,$plaintext);
    print_r($info);
    ?>

# gnupg_deletekey

(PECL gnupg >= 0.5)

gnupg_deletekey — Löscht einen Schlüssel aus dem Schlüsselbund

### Beschreibung

function gnupg_deletekey(resource `$identifier`, string `$key`, bool `$allow_secret`): bool

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`key`
  Der zu löschende Schlüssel.
`allow_secret`
  Gibt an, ob auch geheime Schlüssel gelöscht werden sollen.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Prozedurales gnupg_deletekey()-Beispiel

    <?php
    $res = gnupg_init();
    gnupg_deletekey($res, "8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

Beispiel #2 Objektorientiertes gnupg_deletekey()-Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->deletekey("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_encrypt

(PECL gnupg >= 0.1)

gnupg_encrypt — Verschlüsselt einen gegebenen Text

### Beschreibung

function gnupg_encrypt(resource `$identifier`, string `$plaintext`): string|false

Verschlüsselt den gegebenen `plaintext` mit den Schlüsseln, die vorher mit gnupg_addencryptkey gesetzt wurden und gibt den verschlüsselten Text zurück.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`plaintext`
  Der zu verschlüsselnde Text.

### Rückgabewerte

Bei Erfolg gibt diese Funktion den verschlüsselten Text zurück. Bei einem Fehler gibt diese Funktion `false` zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_encrypt()-Beispiel

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    $enc = gnupg_encrypt($res, "just a test");
    echo $enc;
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_encrypt()-Beispiele

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    $enc = $gpg->encrypt("just a test");
    echo $enc;
    ?>

# gnupg_encryptsign

(PECL gnupg >= 0.2)

gnupg_encryptsign — Verschlüsselt und signiert einen gegebenen Text

### Beschreibung

function gnupg_encryptsign(resource `$identifier`, string `$plaintext`): string|false

Verschlüsselt und signiert den gegebenen `plaintext` mit den Schlüsseln, die vorher mit gnupg_addsignkey und gnupg_addencryptkey hinterlegten Schlüsseln und gibt den verschlüsselten und signierten Text zurück.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`plaintext`
  Der zu verschlüsselnde Text.

### Rückgabewerte

Bei Erfolg gibt diese Funktionn den verschlüsselten und signierten Text zurück, bei einem Fehler gibt diese Funktion `false` zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_encryptsign()-Beispiel

    <?php
    $res = gnupg_init();
    gnupg_addencryptkey($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $enc = gnupg_encryptsign($res, "just a test");
    echo $enc;
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_encryptsign()-Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->addencryptkey("8660281B6051D071D94B5B230549F9DC851566DC");
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $enc = $gpg->encryptsign("just a test");
    echo $enc;
    ?>

# gnupg_export

(PECL gnupg >= 0.1)

gnupg_export — Exportiert einen Schlüssel

### Beschreibung

function gnupg_export(resource `$identifier`, string `$fingerprint`): string|false

Exportiert den Schlüssel `fingerprint`.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`fingerprint`

  Der 'Fingerprint'-Schlüssel.

### Rückgabewerte

Bei Erfolg gibt diese Funktion die Schlüssel-Daten zurück. Bei einem Fehler gibt diese Funktion `false` zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_export()-Beispiel

    <?php
    $res = gnupg_init();
    $export = gnupg_export($res,"8660281B6051D071D94B5B230549F9DC851566DC");
    echo $export;
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_export()-Beispiel

    <?php
    $gpg = new gnupg();
    $export = $gpg->export("8660281B6051D071D94B5B230549F9DC851566DC");
    ?>

# gnupg_getengineinfo

(PECL gnupg >= 1.5)

gnupg_getengineinfo — Liefert Informationen über die Engine

### Beschreibung

function gnupg_getengineinfo(resource `$identifier`): array

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

### Rückgabewerte

Gibt ein Array mit Informationen zur Engine zurück, das aus `protocol`, `file_name` und `home_dir` besteht.

### Beispiele

Beispiel #1 Prozedurales gnupg_getengineinfo()-Beispiel

    <?php
    $res = gnupg_init();
    print_r(gnupg_getengineinfo($res));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      ["protocol"]=>
      int(0)
      ["file_name"]=>
      string(12) "/usr/bin/gpg"
      ["home_dir"]=>
      string(0) ""
    }

Beispiel #2 Objektorientiertes gnupg_getengineinfo()-Beispiel

    <?php
    $gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    print_r($gpg->getengineinfo());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(3) {
      ["protocol"]=>
      int(0)
      ["file_name"]=>
      string(13) "/usr/bin/gpg2"
      ["home_dir"]=>
      string(15) "/var/www/.gnupg"
    }

# gnupg_geterror

(PECL gnupg >= 0.1)

gnupg_geterror — Gibt den Fehlertext zurück, wenn eine Funktion scheitert

### Beschreibung

function gnupg_geterror(resource `$identifier`): string|false

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

### Rückgabewerte

Gibt den Fehlertext zurück, wenn ein Fehler aufgetreten ist, sonst `false`.

### Beispiele

Beispiel #1 Prozedurales gnupg_geterror()-Beispiel

    <?php
    $res = gnupg_init();
    echo gnupg_geterror($res);
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_geterror()-Beispiel

    <?php
    $gpg = new gnupg();
    echo $gpg->geterror();
    ?>

# gnupg_geterrorinfo

(PECL gnupg >= 1.5)

gnupg_geterrorinfo — Liefert Fehlerinformationen

### Beschreibung

function gnupg_geterrorinfo(resource `$identifier`): array

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

### Rückgabewerte

Gibt ein Array mit Fehlerinformationen zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_geterrorinfo()-Beispiel

    <?php
    $res = gnupg_init();
    // dies wird ohne Fehler aufgerufen
    print_r(gnupg_geterrorinfo($res));
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      ["generic_message"]=>
      bool(false)
      ["gpgme_code"]=>
      int(0)
      ["gpgme_source"]=>
      string(18) "Unspecified source"
      ["gpgme_message"]=>
      string(7) "Success"
    }

Beispiel #2 Objektorientiertes gnupg_geterrorinfo()-Beispiel

    <?php
    $gpg = new gnupg();
    // fehlerhafter Aufruf
    $gpg->decrypt('abc');
    // die Fehlerinformationen sollten angezeigt werden
    print_r($gpg->geterrorinfo());
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    array(4) {
      ["generic_message"]=>
      string(14) "decrypt failed"
      ["gpgme_code"]=>
      int(117440570)
      ["gpgme_source"]=>
      string(5) "GPGME"
      ["gpgme_message"]=>
      string(7) "No data"
    }

# gnupg_getprotocol

(PECL gnupg >= 0.1)

gnupg_getprotocol — Gibt das aktuell für alle Operationen aktive Protokoll zurück

### Beschreibung

function gnupg_getprotocol(resource `$identifier`): int

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

### Rückgabewerte

Gibt das aktuell aktive Protokoll zurück, welches eine der `GNUPG_PROTOCOL_OpenPGP`- oder `GNUPG_PROTOCOL_CMS`-Konstanten sein kann.

### Beispiele

Beispiel #1 Prozedurales gnupg_getprotocol() Beispiel

    <?php
    $res = gnupg_init();
    echo gnupg_getprotocol($res);
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_getprotocol() Beispiel

    <?php
    $gpg = new gnupg();
    echo $gpg->getprotocol();
    ?>

# gnupg_gettrustlist

(PECL gnupg >= 0.5)

gnupg_gettrustlist — Sucht nach vertrauenswürdigen Elementen

### Beschreibung

function gnupg_gettrustlist(resource `$identifier`, string `$pattern`): ?array

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`pattern`
  Ein Suchbegriff, der die Liste der vertrauenswürdigen Elemente auf diejenigen beschränkt, die dem Muster entsprechen.

### Rückgabewerte

Bei Erfolg gibt diese Funktion ein Array von vertrauenswürdigen Elementen zurück; bei einem Fehler gibt sie `null` zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_gettrustlist()-Beispiel

    <?php
    $res = gnupg_init();
    $items = gnupg_gettrustlist($res);
    print_r($items);
    ?>

Beispiel #2 Objektorientiertes gnupg_gettrustlist()-Beispiel

    <?php
    $gpg = new gnupg();
    $items = $gpg->gettrustlist();
    print_r($items);
    ?>

# gnupg_import

(PECL gnupg >= 0.3)

gnupg_import — Importiert einen Schlüssel

### Beschreibung

function gnupg_import(resource `$identifier`, string `$keydata`): array|false

Importiert den Schlüssel `keydata` und gibt ein Array mit Informationen über den Importprozess zurück.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`keydata`
  Die Daten des zu importierenden Schlüssels.

### Rückgabewerte

Bei Erfolg gibt diese Funktion ein info-array über den Importprozess zurück. Bei einem Fehler gibt diese Funktion `false` zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_import()-Beispiel

    <?php
    $res = gnupg_init();
    $info = gnupg_import($res,$keydata);
    print_r($info);
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_import()-Beispiel

    <?php
    $gpg = new gnupg();
    $info = $gpg->import($keydata);
    print_r($info);
    ?>

# gnupg_init

(PECL gnupg >= 0.4)

gnupg_init — Initialisiert eine Verbindung

### Beschreibung

function gnupg_init(?array `$options` = `null`): resource

### Parameter-Liste

`options`

  Muss ein assoziatives Array sein. Es wird verwendet, um die Standardkonfiguration der Krypto-Engine zu ändern.

  Konfigurationsänderungen
  Schlüssel | Typ | Beschreibung
  --- | --- | ---
  file_name | string | Der Dateiname des ausführbaren Programms, das dieses Protokoll implementiert. Üblicherweise ist das der Pfad des ausführbaren `gpg`-Programms.
  home_dir | string | Der Verzeichnisname des Konfigurationsverzeichnisses. Er überschreibt auch die Umgebungsvariable `GNUPGHOME`, die für denselben Zweck verwendet wird.

### Rückgabewerte

Eine GnuPG-Verbindungs-Ressource, die von anderen GnuPG-Funktionen benutzt wird.

### Changelog

Version | Beschreibung
--- | ---
PECL gnupg 1.5.0 | Der Parameter `options` wurde hinzugefügt.

### Beispiele

Beispiel #1 Prozedurales gnupg_init()-Beispiel mit Standardeinstellung

    <?php
    $res = gnupg_init();
    ?>

Beispiel #2 Prozedurales gnupg_init()-Beispiel mit geänderten Dateinamen und Home-Verzeichnis

    <?php
    $res = gnupg_init(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    ?>

Beispiel #3 OO (objektorientiertes) gnupg-Initialisierungsbeispiel mit Standardeinstellung

    <?php
    $gpg = new gnupg();
    ?>

Beispiel #4 OO gnupg-Initialisierungsbeispiel mit geänderten Dateinamen und Home-Verzeichnis

    <?php
    $gpg = new gnupg(["file_name" => "/usr/bin/gpg2", "home_dir" => "/var/www/.gnupg"]);
    ?>

# gnupg_keyinfo

(PECL gnupg >= 0.1)

gnupg_keyinfo — Gibt ein Array mit Informationen über alle Schlüssel zurück, die dem gegebenen Muster entsprechen

### Beschreibung

function gnupg_keyinfo(resource `$identifier`, string `$pattern`): array|false

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`pattern`
  Das Muster, das mit den Schlüsseln verglichen werden soll.

### Rückgabewerte

Gibt ein Array mit Informationen über alle Schlüssel, die dem übergebenen Muster entsprechen oder `false`, wenn ein Fehler auftritt.

### Beispiele

Beispiel #1 Prozedurales gnupg_keyinfo()-Beispiel

    <?php
    $res = gnupg_init();
    $info = gnupg_keyinfo($res, 'test');
    print_r($info);
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_keyinfo()-Beispiel

    <?php
    $gpg = new gnupg();
    $info = $gpg->keyinfo("test");
    print_r($info);
    ?>

# gnupg_listsignatures

(PECL gnupg >= 0.5)

gnupg_listsignatures — Liefert eine Liste von Schlüsselsignaturen

### Beschreibung

function gnupg_listsignatures(resource `$identifier`, string `$keyid`): ?array

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`keyid`
  Die Schlüssel-ID, für die Signaturen aufgelistet werden sollen.

### Rückgabewerte

Bei Erfolg gibt diese Funktion ein Array von Schlüsselsignaturen zurück; bei einem Fehler gibt sie `null` zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_listsignatures()-Beispiel

    <?php
    $res = gnupg_init();
    $signatures = gnupg_listsignatures($res, "8660281B6051D071D94B5B230549F9DC851566DC");
    print_r($signatures);
    ?>

Beispiel #2 Objektorientiertes gnupg_listsignatures()-Beispiel

    <?php
    $gpg = new gnupg();
    $signatures = $gpg->listsignatures("8660281B6051D071D94B5B230549F9DC851566DC");
    print_r($signatures);
    ?>

# gnupg_setarmor

(PECL gnupg >= 0.1)

gnupg_setarmor — Gepanzerte Ausgabe umschalten

### Beschreibung

function gnupg_setarmor(resource `$identifier`, int `$armor`): bool

Umschalten der gepanzerten Ausgabe.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`armor`
  Übergibt einen nicht-null Integer-Wert zu dieser Funktion um die gepanzerte Ausgabe zu aktivieren (standard). Übergib 0 um die gepanzerte Ausgabe zu deaktivieren.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Prozedurales gnupg_setarmor() Beispiel

    <?php
    $res = gnupg_init();
    gnupg_setarmor($res,1); // gepanzerte Ausgabe aktivieren;
    gnupg_setarmor($res,0); // gepanzerte Ausgabe deaktivieren;
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_setarmor() Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->setarmor(1); // gepanzerte Ausgabe aktivieren;
    $gpg->setarmor(0); // gepanzerte Ausgabe deaktivieren;
    ?>

# gnupg_seterrormode

(PECL gnupg >= 0.6)

gnupg_seterrormode — Setzt den Modus für error_reporting

### Beschreibung

function gnupg_seterrormode(resource `$identifier`, int `$errormode`): void

Setzt den Modus für error_reporting.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`errormode`
  Der Fehler-Modus. `errormode` übernimmt eine Konstante, die angibt, welche Art von error_reporting verwendet werden sollte. Die möglichen Werte sind `GNUPG_ERROR_WARNING`, `GNUPG_ERROR_EXCEPTION` und `GNUPG_ERROR_SILENT`. Standardmäßig wird `GNUPG_ERROR_SILENT` verwendet.

### Rückgabewerte

Es wird kein Wert zurückgegeben.

### Beispiele

Beispiel #1 Procedurales gnupg_seterrormode() Beispiel

    <?php
    $res = gnupg_init();
    gnupg_seterrormode($res,GNUPG_ERROR_WARNING); // erzeugt eine PHP-Warnung im Fall eines Fehlers
    ?>

Beispiel #2 OO (objektorientiertes) gnupg_seterrormode() Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->seterrormode(gnupg::ERROR_EXCEPTION); // erzeugt eine Ausnahme im Fall eines Fehlers
    ?>

# gnupg_setsignmode

(PECL gnupg >= 0.1)

gnupg_setsignmode — Setzt den Signierungs-Modus

### Beschreibung

function gnupg_setsignmode(resource `$identifier`, int `$signmode`): bool

Setzt den Signierungs-Modus.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`sigmode`
  Der Modus der Signierung. `signmode` übernimmt eine Konstante, die angibt, welche Art von Signatur erzeugt werden soll. Die möglichen Werte sind `GNUPG_SIG_MODE_NORMAL`, `GNUPG_SIG_MODE_DETACH` und `GNUPG_SIG_MODE_CLEAR`. Standardmäßig wird `GNUPG_SIG_MODE_CLEAR` verwendet.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Prozedurales gnupg_setsignmode() Beispiel

    <?php
    $res = gnupg_init();
    gnupg_setsignmode($res,GNUPG_SIG_MODE_DETACH); // erzeugt eine abgetrennte Signatur
    ?>

Beispiel #2 OO gnupg_setsignmode() Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->setsignmode(gnupg::SIG_MODE_DETACH); // erzeugt eine abgetrennte Signatur
    ?>

# gnupg_sign

(PECL gnupg >= 0.1)

gnupg_sign — Signiert einen übergebenen Text

### Beschreibung

function gnupg_sign(resource `$identifier`, string `$plaintext`): string|false

Signiert den übergebenen `plaintext` mit den Schlüsseln, die vorher mit gnupg_addsignkey hinterlegt wurden und gibt den signierten Text oder die Signatur zurück, abhängig davon, was mit gnupg_setsignmode festgelegt wurde.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`plaintext`
  Der zu signierende Klartext.

### Rückgabewerte

Bei Erfolg gibt diese Funktion den signierten Text oder die Signatur zurück, bei einem Fehler `false`.

### Beispiele

Beispiel #1 Prozedurales gnupg_sign()-Beispiel

    <?php
    $res = gnupg_init();
    gnupg_addsignkey($res,"8660281B6051D071D94B5B230549F9DC851566DC","test");
    $signed = gnupg_sign($res, "just a test");
    echo $signed;
    ?>

Beispiel #2 OO gnupg_sign()-Beispiel

    <?php
    $gpg = new gnupg();
    $gpg->addsignkey("8660281B6051D071D94B5B230549F9DC851566DC","test");
    $signed = $gpg->sign("just a test");
    echo $signed;
    ?>

# gnupg_verify

(PECL gnupg >= 0.1)

gnupg_verify — Verifiziert einen signierten Text

### Beschreibung

function gnupg_verify(
resource `$identifier`,
string `$signed_text`,
string `$signature`,
string `&$plaintext` = ?
): array|false

Verifiziert den gegebenen `signed_text` und gibt Informationen über die Signatur zurück.

### Parameter-Liste

`identifier`

  Eine von gnupg_init() oder der Klasse gnupg zurückgegebene GnuPG-Ressource.

`signed_text`
  Der signierte Text.
`signature`
  Die Signatur. Um einen klar signierten Text zu verifizieren, setzen Sie signature auf `false`.
`plaintext`
  Der Klartext. Wenn dieser optionale Parameter übergeben ist, ist er mit dem Klartext gefüllt.

### Rückgabewerte

Bei Erfolg gibt diese Funktion Informationen über die Signatur, bei einem Fehler `false` zurück.

### Beispiele

Beispiel #1 Prozedurales gnupg_verify()-Beispiel

    <?php
    $plaintext = "";
    $res = gnupg_init();
    // clearsigned
    $info = gnupg_verify($res,$signed_text,false,$plaintext);
    print_r($info);
    // detached signature
    $info = gnupg_verify($res,$signed_text,$signature);
    print_r($info);
    ?>

Beispiel #2 OO gnupg_verify()-Beispiel

    <?php
    $plaintext = "";
    $gpg = new gnupg();
    // clearsigned
    $info = $gpg->verify($signed_text,false,$plaintext);
    print_r($info);
    // detached signature
    $info = $gpg->verify($signed_text,$signature);
    print_r($info);
    ?>

## Inhaltsverzeichnis

- gnupg_adddecryptkey — Fügt einen Schlüssel für Entschlüsselung hinzu
- gnupg_addencryptkey — Fügt einen Schlüssel zur Verschlüsselung hinzu
- gnupg_addsignkey — Fügt einen Schlüssel für Signierung hinzu
- gnupg_cleardecryptkeys — Entfernt alle Schlüssel, die vorher für Entschlüsselung hinterlegt wurden
- gnupg_clearencryptkeys — Entfernt alle Schlüssel, die vorher zur Verschlüsselung hinterlegt wurden
- gnupg_clearsignkeys — Entfernt alle Schlüssel die vorher zur Signierung hinterlegt wurden
- gnupg_decrypt — Entschlüsselt einen gegebenen Text
- gnupg_decryptverify — Entschlüsselt und vertifiziert einen gegebenen Text
- gnupg_deletekey — Löscht einen Schlüssel aus dem Schlüsselbund
- gnupg_encrypt — Verschlüsselt einen gegebenen Text
- gnupg_encryptsign — Verschlüsselt und signiert einen gegebenen Text
- gnupg_export — Exportiert einen Schlüssel
- gnupg_getengineinfo — Liefert Informationen über die Engine
- gnupg_geterror — Gibt den Fehlertext zurück, wenn eine Funktion scheitert
- gnupg_geterrorinfo — Liefert Fehlerinformationen
- gnupg_getprotocol — Gibt das aktuell für alle Operationen aktive Protokoll zurück
- gnupg_gettrustlist — Sucht nach vertrauenswürdigen Elementen
- gnupg_import — Importiert einen Schlüssel
- gnupg_init — Initialisiert eine Verbindung
- gnupg_keyinfo — Gibt ein Array mit Informationen über alle Schlüssel zurück, die dem gegebenen Muster entsprechen
- gnupg_listsignatures — Liefert eine Liste von Schlüsselsignaturen
- gnupg_setarmor — Gepanzerte Ausgabe umschalten
- gnupg_seterrormode — Setzt den Modus für error_reporting
- gnupg_setsignmode — Setzt den Signierungs-Modus
- gnupg_sign — Signiert einen übergebenen Text
- gnupg_verify — Verifiziert einen signierten Text

- Installation/Konfiguration
  - Anforderungen
  - Installation
- Vordefinierte Konstanten
- Beispiele
  - Signieren eines Textes mit Klartextsignatur
- GnuPG Funktionen
  - gnupg_adddecryptkey — Fügt einen Schlüssel für Entschlüsselung hinzu
  - gnupg_addencryptkey — Fügt einen Schlüssel zur Verschlüsselung hinzu
  - gnupg_addsignkey — Fügt einen Schlüssel für Signierung hinzu
  - gnupg_cleardecryptkeys — Entfernt alle Schlüssel, die vorher für Entschlüsselung hinterlegt wurden
  - gnupg_clearencryptkeys — Entfernt alle Schlüssel, die vorher zur Verschlüsselung hinterlegt wurden
  - gnupg_clearsignkeys — Entfernt alle Schlüssel die vorher zur Signierung hinterlegt wurden
  - gnupg_decrypt — Entschlüsselt einen gegebenen Text
  - gnupg_decryptverify — Entschlüsselt und vertifiziert einen gegebenen Text
  - gnupg_deletekey — Löscht einen Schlüssel aus dem Schlüsselbund
  - gnupg_encrypt — Verschlüsselt einen gegebenen Text
  - gnupg_encryptsign — Verschlüsselt und signiert einen gegebenen Text
  - gnupg_export — Exportiert einen Schlüssel
  - gnupg_getengineinfo — Liefert Informationen über die Engine
  - gnupg_geterror — Gibt den Fehlertext zurück, wenn eine Funktion scheitert
  - gnupg_geterrorinfo — Liefert Fehlerinformationen
  - gnupg_getprotocol — Gibt das aktuell für alle Operationen aktive Protokoll zurück
  - gnupg_gettrustlist — Sucht nach vertrauenswürdigen Elementen
  - gnupg_import — Importiert einen Schlüssel
  - gnupg_init — Initialisiert eine Verbindung
  - gnupg_keyinfo — Gibt ein Array mit Informationen über alle Schlüssel zurück, die dem gegebenen Muster entsprechen
  - gnupg_listsignatures — Liefert eine Liste von Schlüsselsignaturen
  - gnupg_setarmor — Gepanzerte Ausgabe umschalten
  - gnupg_seterrormode — Setzt den Modus für error_reporting
  - gnupg_setsignmode — Setzt den Signierungs-Modus
  - gnupg_sign — Signiert einen übergebenen Text
  - gnupg_verify — Verifiziert einen signierten Text

# wkhtmltox

# Einführung

libwkhtmltox is an open source LGPLv3 library for rendering HTML into PDF and various image formats using the QtWebKit rendering engine.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Laufzeit-Konfiguration

## Anforderungen

libwkhtmltox source and binary releases are distributed at » wkhtmltopdf.org.

Achtung

Windows users need to take the additional step of adding wkhtmltox.dll to their PATH.

## Installation

The source code of this extension, and binaries for Windows are hosted by » github,

Fetching the source code and building the extension:

    git clone https://github.com/krakjoe/wkhtmltox
    cd wkhtmltox
    phpize
    ./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
    make
    sudo make install

Fetching updates and rebuilding the extension:

    cd wkhtmltox
    phpize --clean
    git pull origin master
    phpize
    ./configure --with-wkhtmltox=/path/to/wkhtmltox/installation
    make
    sudo make install

## Laufzeit-Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

wkhtmltox Konfigurationsoptionen
Name | Standard | Veränderbar | Changelog
--- | --- | --- | ---
wkhtmltox.graphics | Off | `INI_SYSTEM`|`INI_PERDIR` | >= 0.3.2

Weitere Details und die Definitionen der INI_*-Konstanten sind unter Wo Konfigurationseinstellungen gesetzt werden können zu finden.

Hier eine kurze Erklärung der Konfigurationsoptionen:

`wkhtmltox.graphics` bool

  Allow libwkhtmltox to use graphics.

# The wkhtmltox\PDF\Converter class

(wkhtmltox >= 0.1.0)

## Einführung

Converts an HTML input, or set of HTML inputs, into PDF output

## Klassenbeschreibung

class wkhtmltox\PDF\Converter {
/* Constructor */
public function __construct(array `$settings` = ?)
/* Methoden */
public function add(wkhtmltox\PDF\Object `$object`): void
public function convert(): ?string
public function getVersion(): string
}

# wkhtmltox\PDF\Converter::add

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::add — Add an object for conversion

### Beschreibung

public function wkhtmltox\PDF\Converter::add(wkhtmltox\PDF\Object `$object`): void

Adds the given object to conversion

### Parameter-Liste

`object`

  The object to add

# wkhtmltox\PDF\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::__construct — Create a new PDF converter

### Beschreibung

public function wkhtmltox\PDF\Converter::__construct(array `$settings` = ?)

Creates a PDF converter, using optional configuration settings

### Parameter-Liste

`settings`

  Name | Description | Values | Changelog
  --- | --- | --- | ---
  size.pageSize | paper size of output document | A4 | >= 0.1.0
  size.width | with of the output document | 210mm | >= 0.1.0
  size.height | height of the output document | 297mm | >= 0.1.0
  orientation | orientation of the output document |
  Landscape
  Portrait
  | >= 0.1.0
  colorMode | color mode of the output document |
  Color
  Greyscale
  | >= 0.1.0
  resolution | resolution of the output document | most likely has no effect | >= 0.1.0
  dpi | dpi to use while printing | 80 | >= 0.1.0
  pageOffset | integer added to page numbers generating headers, footers, and toc |  | >= 0.1.0
  copies |  |  | >= 0.1.0
  collate | collate copies | boolean | >= 0.1.0
  outline | generate PDF outline | boolean | >= 0.1.0
  outlineDepth | maximum depth of outline |  | >= 0.1.0
  dumpOutline | path of file to dump outline XML |  | >= 0.1.0
  out | path of output file, if "-" stdout is used |  | >= 0.1.0
  documentTitle | title for the output document |  | >= 0.1.0
  useCompression | enable or disable lossless compression | boolean | >= 0.1.0
  margin.top | size of the top margin | 2cm | >= 0.1.0
  margin.bottom | size of the bottom margin | 2cm | >= 0.1.0
  margin.left | size of the left margin | 2cm | >= 0.1.0
  margin.right | size of the right margin | 2cm | >= 0.1.0
  imageDPI | maximum DPI for images in the output document |  | >= 0.1.0
  imageQuality | the jpeg compression factor for images in the output document | 94 | >= 0.1.0
  load.cookieJar | path of file used to load and store cookies | /tmp/cookies.txt | >= 0.1.0

# wkhtmltox\PDF\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Converter::convert — Perform PDF conversion

### Beschreibung

public function wkhtmltox\PDF\Converter::convert(): ?string

Performs conversion of all previously added Objects

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Where the return value is used, it will be populated with the contents of the conversion buffer

# wkhtmltox\PDF\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\PDF\Converter::getVersion — Determine version of Converter

### Beschreibung

public function wkhtmltox\PDF\Converter::getVersion(): string

Determines the version of Converter as reported by libwkhtmltox

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a version string

## Inhaltsverzeichnis

- wkhtmltox\PDF\Converter::add — Add an object for conversion
- wkhtmltox\PDF\Converter::__construct — Create a new PDF converter
- wkhtmltox\PDF\Converter::convert — Perform PDF conversion
- wkhtmltox\PDF\Converter::getVersion — Determine version of Converter

# The wkhtmltox\PDF\Object class

(wkhtmltox >= 0.1.0)

## Einführung

Represents an HTML document, input to PDF converter

## Klassenbeschreibung

class wkhtmltox\PDF\Object {
/* Constructor */
public function __construct(string `$buffer`, array `$settings` = ?)
}

# wkhtmltox\PDF\Object::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\PDF\Object::__construct — Create a new PDF Object

### Beschreibung

public function wkhtmltox\PDF\Object::__construct(string `$buffer`, array `$settings` = ?)

Creates a new PDF Object from the given buffer and optional configuration settings

### Parameter-Liste

`buffer`

  HTML

`settings`

  Name | Description | Values | Changelog
  --- | --- | --- | ---
  page | URL or path of the HTML to convert |  | >= 0.1.0
  useExternalLinks | set true to convert external links in the input into external PDF links in the output | boolean | >= 0.1.0
  useLocalLinks | set true to convert internal links in the input into internal PDF links in the output | boolean | >= 0.1.0
  produceForms | set true to turn HTML forms into PDF forms | boolean | >= 0.1.0
  replacements | undocumented |  | >= 0.1.0
  includeInOutline | set true to include sections from this object in the outline and toc | boolean | >= 0.1.0
  pagesCount | set true to make page count in toc inclusive of the number of pages in this object | boolean | >= 0.1.0
  tocXsl | set to style sheet to convert this object into a toc object |  | >= 0.1.0
  toc.useDottedLines | set true to use dotted lines in toc | boolean | >= 0.1.0
  toc.captionText | the caption text for toc |  | >= 0.1.0
  toc.forwardLinks | set true to create links from toc to content | boolean | >= 0.1.0
  toc.backLinks | set true to create links from content to toc | boolean | >= 0.1.0
  toc.indentation | indentation for toc | 2em | >= 0.1.0
  toc.fontScale | the factor to scale down the font at every toc level | 0.8 | >= 0.1.0
  header.fontSize | font size for use in header | 13 | >= 0.1.0
  header.fontName | name of font for use in header | times | >= 0.1.0
  header.left | text for left of header |  | >= 0.1.0
  header.center | text for center of header |  | >= 0.1.0
  header.right | text for right of header |  | >= 0.1.0
  header.line | enable or disable horizontal rule under header | boolean | >= 0.1.0
  header.spacing | space between header and content | 1.8 | >= 0.1.0
  header.htmlUrl | URL or path of HTML to use in header |  | >= 0.1.0
  footer.fontSize | font size for use in footer | 13 | >= 0.1.0
  footer.fontName | name of font for use in footer | times | >= 0.1.0
  footer.left | text for left of footer |  | >= 0.1.0
  footer.center | text for center of footer |  | >= 0.1.0
  footer.right | text for right of footer |  | >= 0.1.0
  footer.line | enable or disable horizontal rule under footer | boolean | >= 0.1.0
  footer.spacing | space between footer and content | 1.8 | >= 0.1.0
  footer.htmlUrl | URL or path of HTML to use in footer |  | >= 0.1.0
  load.username | user name to use when loging into a website | bart | >= 0.1.0
  load.password | the password to used when logging into a website | elbarto | >= 0.1.0
  load.jsdelay | the amount of time in milliseconds to wait after a page is loaded until it is captured | 1200 | >= 0.1.0
  load.zoomFactor | how much zoom should be applied to the content | 2.2 | >= 0.1.0
  load.customHeaders | custom headers to send when requesting the main web page |  | >= 0.1.0
  load.repertCustomHeaders | set true to send with all requests | boolean | >= 0.1.0
  load.cookies | cookie string to send when requesting the main web page |  | >= 0.1.0
  load.post | post string to send when requesting the main web page |  | >= 0.1.0
  load.blockLocalFileAccess | disallow local and piped files to access other local files | boolean | >= 0.1.0
  load.stopSlowScript | stop slow running javascript | boolean |
  load.debugJavascript | allow javascript to raise warnings | boolean | >= 0.1.0
  load.loadErrorHandling | set error handling strategy |
  abort | abort the convertion process
  skip | do not add the object to the final output
  ignore | try to add the object to the final output
  | >= 0.1.0
  load.proxy |  |  | >= 0.1.0
  web.background | include background image in output | boolean | >= 0.1.0
  web.loadImages | include images in output | boolean | >= 0.1.0
  web.enableJavascript | enable or disable javascript | boolean | >= 0.1.0
  web.enableIntelligentShrinking | enable to attempt to fit more content on page, only applies to PDF output | boolean | >= 0.1.0
  web.minimumFontSize | the minimum font size allowed | 9 | >= 0.1.0
  web.printMediaType | print content using print media type instead of screen media type | boolean | >= 0.1.0
  web.defaultEncoding | content to use where no encoding is specified | utf-8 | >= 0.1.0
  web.userStyleSheet | URL or path to a user specified style sheet | /path/to/style.css | >= 0.1.0
  web.enablePlugins | enable or disable NS plugins | boolean | >= 0.1.0

## Inhaltsverzeichnis

- wkhtmltox\PDF\Object::__construct — Create a new PDF Object

# The wkhtmltox\Image\Converter class

(wkhtmltox >= 0.1.0)

## Einführung

Converts an HTML input into various image formats

## Klassenbeschreibung

class wkhtmltox\Image\Converter {
/* Constructor */
public function __construct(string `$buffer` = ?, array `$settings` = ?)
/* Methoden */
public function convert(): ?string
public function getVersion(): string
}

# wkhtmltox\Image\Converter::__construct

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::__construct — Create a new Image converter

### Beschreibung

public function wkhtmltox\Image\Converter::__construct(string `$buffer` = ?, array `$settings` = ?)

Creates an Image converter, optionally taking an input buffer and configuration settings

### Parameter-Liste

`buffer`

  HTML

`settings`

  Name | Description | Values | Changelog
  --- | --- | --- | ---
  in | URL or path of the input file, if "-" stdin is used | /path/to/markup.html | >= 0.1.0
  out | path of output file, if "-" stdout is used, by default an internal buffer is used | /path/to/output.png | >= 0.1.0
  fmt | output format to use |
  "" | default
  jpg | output as JPEG
  png | output as PNG
  bmp | output as bitmap
  svg | output as SVG
  | >= 0.1.0
  transparent | when outputting a PNG or SVG, make the white background transparent | boolean | >= 0.1.0
  screenWidth | the with of the screen used to render in pixels | 800 | >= 0.1.0
  smartWidth | when true, screenWidth is expanded to the content width | boolean | >= 0.1.0
  quality | compression factor to use when outputting a JPEG image | 94 | >= 0.1.0
  crop.left | left/x coordinate of the window to capture in pixels | 200 | >= 0.1.0
  crop.top | top/y coordinate of the window to capture in pixels | 200 | >= 0.1.0
  crop.width | width of the window to capture in pixels | 200 | >= 0.1.0
  crop.height | height of the window to capture in pixels | 200 | >= 0.1.0
  load.cookieJar | path of file used to load and store cookies | /tmp/cookies.txt | >= 0.1.0
  load.username | user name to use when loging into a website | bart | >= 0.1.0
  load.password | the password to used when logging into a website | elbarto | >= 0.1.0
  load.jsdelay | the amount of time in milliseconds to wait after a page is loaded until it is captured | 1200 | >= 0.1.0
  load.zoomFactor | how much zoom should be applied to the content | 2.2 | >= 0.1.0
  load.customHeaders | custom headers to send when requesting the main web page |  | >= 0.1.0
  load.repertCustomHeaders | set true to send with all requests | boolean | >= 0.1.0
  load.cookies | cookie string to send when requesting the main web page |  | >= 0.1.0
  load.post | post string to send when requesting the main web page |  | >= 0.1.0
  load.blockLocalFileAccess | disallow local and piped files to access other local files | boolean | >= 0.1.0
  load.stopSlowScript | stop slow running javascript | boolean |
  load.debugJavascript | allow javascript to raise warnings | boolean | >= 0.1.0
  load.loadErrorHandling | set error handling strategy |
  abort | abort the convertion process
  skip | do not add the object to the final output
  ignore | try to add the object to the final output
  | >= 0.1.0
  load.proxy |  |  | >= 0.1.0
  web.background | include background image in output | boolean | >= 0.1.0
  web.loadImages | include images in output | boolean | >= 0.1.0
  web.enableJavascript | enable or disable javascript | boolean | >= 0.1.0
  web.enableIntelligentShrinking | enable to attempt to fit more content on page, only applies to PDF output | boolean | >= 0.1.0
  web.minimumFontSize | the minimum font size allowed | 9 | >= 0.1.0
  web.printMediaType | print content using print media type instead of screen media type | boolean | >= 0.1.0
  web.defaultEncoding | content to use where no encoding is specified | utf-8 | >= 0.1.0
  web.userStyleSheet | URL or path to a user specified style sheet | /path/to/style.css | >= 0.1.0
  web.enablePlugins | enable or disable NS plugins | boolean | >= 0.1.0

# wkhtmltox\Image\Converter::convert

(wkhtmltox >= 0.1.0)

wkhtmltox\Image\Converter::convert — Perform Image conversion

### Beschreibung

public function wkhtmltox\Image\Converter::convert(): ?string

Performs conversion of the input buffer

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Where the return value is used, it will be populated with the contents of the conversion buffer

# wkhtmltox\Image\Converter::getVersion

(wkhtmltox >= 0.3.2)

wkhtmltox\Image\Converter::getVersion — Determine version of Converter

### Beschreibung

public function wkhtmltox\Image\Converter::getVersion(): string

Determines the version of Converter as reported by libwkhtmltox

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Returns a version string

Warnung

This is not yet implemented by libwkhtmltox

## Inhaltsverzeichnis

- wkhtmltox\Image\Converter::__construct — Create a new Image converter
- wkhtmltox\Image\Converter::convert — Perform Image conversion
- wkhtmltox\Image\Converter::getVersion — Determine version of Converter

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Laufzeit-Konfiguration
- wkhtmltox\PDF\Converter — The wkhtmltox\PDF\Converter class
  - wkhtmltox\PDF\Converter::add — Add an object for conversion
  - wkhtmltox\PDF\Converter::__construct — Create a new PDF converter
  - wkhtmltox\PDF\Converter::convert — Perform PDF conversion
  - wkhtmltox\PDF\Converter::getVersion — Determine version of Converter
- wkhtmltox\PDF\Object — The wkhtmltox\PDF\Object class
  - wkhtmltox\PDF\Object::__construct — Create a new PDF Object
- wkhtmltox\Image\Converter — The wkhtmltox\Image\Converter class
  - wkhtmltox\Image\Converter::__construct — Create a new Image converter
  - wkhtmltox\Image\Converter::convert — Perform Image conversion
  - wkhtmltox\Image\Converter::getVersion — Determine version of Converter

# PostScript document creation

# Einführung

This module allows to create PostScript documents. It has many similarities with the pdf extension. Actually the API is almost identical and one can in many cases just replace the prefix of each function from pdf_ to ps_. This also works for functions which has no meaning in the PostScript document (like adding hyperlinks) but will have an effect if the document is converted to PDF.

Documents created by this extension are sometimes even superior to documents created with the pdf extension, because pslib's text rendering functions can handle kerning, hyphenation and ligatures which results in much better output of boxed text.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Ressource-Typen

## Anforderungen

You need at least pslib >= 0.1.12. The ps library (pslib) is available at » http://pslib.sourceforge.net/.

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/ps.

## Ressource-Typen

This extension defines a PostScript document resource returned by ps_new().

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

The following two tables lists all constants defined by the ps extension.

Constants for line caps
Name | Meaning
--- | ---
`ps_LINECAP_BUTT` |
`ps_LINECAP_ROUND` |
`ps_LINECAP_SQUARED` |

Constants for line joins
Name | Meaning
--- | ---
`ps_LINEJOIN_MITER` |
`ps_LINEJOIN_ROUND` |
`ps_LINEJOIN_BEVEL` |

# PS Funktionen

## Contact Information

If you have comments, bugfixes, enhancements for either this extension or pslib then please drop me a mail » steinm@php.net. Any help is very welcome.

# ps_add_bookmark

(PECL ps >= 1.1.0)

ps_add_bookmark — Add bookmark to current page

### Beschreibung

function ps_add_bookmark(
resource `$psdoc`,
string `$text`,
int `$parent` = 0,
int `$open` = 0
): int

Adds a bookmark for the current page. Bookmarks usually appear in PDF-Viewers left of the page in a hierarchical tree. Clicking on a bookmark will jump to the given page.

Diese Notiz wird nicht sichtbar sein, wenn das Dokument gedruckt oder betrachtet wird. Sie wird aber sichtbar sein, wenn das Dokument entweder mit Acrobat Distiller™ oder Ghostview zu PDF konvertiert wird.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text used for displaying the bookmark.

`parent`

  A bookmark previously created by this function which is used as the parent of the new bookmark.

`open`

  If `open` is unequal to zero the bookmark will be shown open by the pdf viewer.

### Rückgabewerte

The returned value is a reference for the bookmark. It is only used if the bookmark shall be used as a parent. The value is greater zero if the function succeeds. In case of an error zero will be returned.

### Siehe auch

- ps_add_launchlink() - Adds link which launches file
- ps_add_pdflink() - Adds link to a page in a second pdf document
- ps_add_weblink() - Adds link to a web location

# ps_add_launchlink

(PECL ps >= 1.1.0)

ps_add_launchlink — Adds link which launches file

### Beschreibung

function ps_add_launchlink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$filename`
): bool

Places a hyperlink at the given position pointing to a file program which is being started when clicked on. The hyperlink's source position is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border.

Diese Notiz wird nicht sichtbar sein, wenn das Dokument gedruckt oder betrachtet wird. Sie wird aber sichtbar sein, wenn das Dokument entweder mit Acrobat Distiller™ oder Ghostview zu PDF konvertiert wird.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`llx`

  The x-coordinate of the lower left corner.

`lly`

  The y-coordinate of the lower left corner.

`urx`

  The x-coordinate of the upper right corner.

`ury`

  The y-coordinate of the upper right corner.

`filename`

  The path of the program to be started, when the link is clicked on.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_add_locallink() - Adds link to a page in the same document
- ps_add_pdflink() - Adds link to a page in a second pdf document
- ps_add_weblink() - Adds link to a web location

# ps_add_locallink

(PECL ps >= 1.1.0)

ps_add_locallink — Adds link to a page in the same document

### Beschreibung

function ps_add_locallink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
int `$page`,
string `$dest`
): bool

Places a hyperlink at the given position pointing to a page in the same document. Clicking on the link will jump to the given page. The first page in a document has number 1.

The hyperlink's source position is a rectangle with its lower left corner at (`llx`, `lly`) and its upper right corner at (`urx`, `ury`). The rectangle has by default a thin blue border.

Diese Notiz wird nicht sichtbar sein, wenn das Dokument gedruckt oder betrachtet wird. Sie wird aber sichtbar sein, wenn das Dokument entweder mit Acrobat Distiller™ oder Ghostview zu PDF konvertiert wird.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`llx`

  The x-coordinate of the lower left corner.

`lly`

  The y-coordinate of the lower left corner.

`urx`

  The x-coordinate of the upper right corner.

`ury`

  The y-coordinate of the upper right corner.

`page`

  The number of the page displayed when clicking on the link.

`dest`

  The parameter `dest` determines how the document is being viewed. It can be `fitpage`, `fitwidth`, `fitheight`, or `fitbbox`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_add_launchlink() - Adds link which launches file
- ps_add_pdflink() - Adds link to a page in a second pdf document
- ps_add_weblink() - Adds link to a web location

# ps_add_note

(PECL ps >= 1.1.0)

ps_add_note — Adds note to current page

### Beschreibung

function ps_add_note(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$contents`,
string `$title`,
string `$icon`,
int `$open`
): bool

Adds a note at a certain position on the page. Notes are like little rectangular sheets with text on it, which can be placed anywhere on a page. They are shown either folded or unfolded. If folded, the specified icon is used as a placeholder.

Diese Notiz wird nicht sichtbar sein, wenn das Dokument gedruckt oder betrachtet wird. Sie wird aber sichtbar sein, wenn das Dokument entweder mit Acrobat Distiller™ oder Ghostview zu PDF konvertiert wird.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`llx`

  The x-coordinate of the lower left corner.

`lly`

  The y-coordinate of the lower left corner.

`urx`

  The x-coordinate of the upper right corner.

`ury`

  The y-coordinate of the upper right corner.

`contents`

  The text of the note.

`title`

  The title of the note as displayed in the header of the note.

`icon`

  The icon shown if the note is folded. This parameter can be set to `comment`, `insert`, `note`, `paragraph`, `newparagraph`, `key`, or `help`.

`open`

  If `open` is unequal to zero the note will be shown unfolded after opening the document with a pdf viewer.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_add_pdflink() - Adds link to a page in a second pdf document
- ps_add_launchlink() - Adds link which launches file
- ps_add_locallink() - Adds link to a page in the same document
- ps_add_weblink() - Adds link to a web location

# ps_add_pdflink

(PECL ps >= 1.1.0)

ps_add_pdflink — Adds link to a page in a second pdf document

### Beschreibung

function ps_add_pdflink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$filename`,
int `$page`,
string `$dest`
): bool

Places a hyperlink at the given position pointing to a second pdf document. Clicking on the link will branch to the document at the given page. The first page in a document has number 1.

The hyperlink's source position is a rectangle with its lower left corner at (`llx`, `lly`) and its upper right corner at (`urx`, `ury`). The rectangle has by default a thin blue border.

Diese Notiz wird nicht sichtbar sein, wenn das Dokument gedruckt oder betrachtet wird. Sie wird aber sichtbar sein, wenn das Dokument entweder mit Acrobat Distiller™ oder Ghostview zu PDF konvertiert wird.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`llx`

  The x-coordinate of the lower left corner.

`lly`

  The y-coordinate of the lower left corner.

`urx`

  The x-coordinate of the upper right corner.

`ury`

  The y-coordinate of the upper right corner.

`filename`

  The name of the pdf document to be opened when clicking on this link.

`page`

  The page number of the destination pdf document

`dest`

  The parameter `dest` determines how the document is being viewed. It can be `fitpage`, `fitwidth`, `fitheight`, or `fitbbox`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_add_launchlink() - Adds link which launches file
- ps_add_locallink() - Adds link to a page in the same document
- ps_add_weblink() - Adds link to a web location

# ps_add_weblink

(PECL ps >= 1.1.0)

ps_add_weblink — Adds link to a web location

### Beschreibung

function ps_add_weblink(
resource `$psdoc`,
float `$llx`,
float `$lly`,
float `$urx`,
float `$ury`,
string `$url`
): bool

Places a hyperlink at the given position pointing to a web page. The hyperlink's source position is a rectangle with its lower left corner at (`llx`, `lly`) and its upper right corner at (`urx`, `ury`). The rectangle has by default a thin blue border.

Diese Notiz wird nicht sichtbar sein, wenn das Dokument gedruckt oder betrachtet wird. Sie wird aber sichtbar sein, wenn das Dokument entweder mit Acrobat Distiller™ oder Ghostview zu PDF konvertiert wird.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`llx`

  The x-coordinate of the lower left corner.

`lly`

  The y-coordinate of the lower left corner.

`urx`

  The x-coordinate of the upper right corner.

`ury`

  The y-coordinate of the upper right corner.

`url`

  The url of the hyperlink to be opened when clicking on this link, e.g. `http://www.php.net`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_add_launchlink() - Adds link which launches file
- ps_add_locallink() - Adds link to a page in the same document
- ps_add_pdflink() - Adds link to a page in a second pdf document

# ps_arc

(PECL ps >= 1.1.0)

ps_arc — Draws an arc counterclockwise

### Beschreibung

function ps_arc(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$radius`,
float `$alpha`,
float `$beta`
): bool

Draws a portion of a circle with at middle point at (`x`, `y`). The arc starts at an angle of `alpha` and ends at an angle of `beta`. It is drawn counterclockwise (use ps_arcn() to draw clockwise). The subpath added to the current path starts on the arc at angle `alpha` and ends on the arc at angle `beta`.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  The x-coordinate of the circle's middle point.

`y`

  The y-coordinate of the circle's middle point.

`radius`

  The radius of the circle

`alpha`

  The start angle given in degrees.

`beta`

  The end angle given in degrees.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_arcn() - Draws an arc clockwise

# ps_arcn

(PECL ps >= 1.1.0)

ps_arcn — Draws an arc clockwise

### Beschreibung

function ps_arcn(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$radius`,
float `$alpha`,
float `$beta`
): bool

Draws a portion of a circle with at middle point at (`x`, `y`). The arc starts at an angle of `alpha` and ends at an angle of `beta`. It is drawn clockwise (use ps_arc() to draw counterclockwise). The subpath added to the current path starts on the arc at angle `beta` and ends on the arc at angle `alpha`.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  The x-coordinate of the circle's middle point.

`y`

  The y-coordinate of the circle's middle point.

`radius`

  The radius of the circle

`alpha`

  The starting angle given in degrees.

`beta`

  The end angle given in degrees.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_arc() - Draws an arc counterclockwise

# ps_begin_page

(PECL ps >= 1.1.0)

ps_begin_page — Start a new page

### Beschreibung

function ps_begin_page(resource `$psdoc`, float `$width`, float `$height`): bool

Starts a new page. Although the parameters `width` and `height` imply a different page size for each page, this is not possible in PostScript. The first call of ps_begin_page() will set the page size for the whole document. Consecutive calls will have no effect, except for creating a new page. The situation is different if you intent to convert the PostScript document into PDF. This function places pdfmarks into the document which can set the size for each page indiviually. The resulting PDF document will have different page sizes.

Though PostScript does not know different page sizes, pslib places a bounding box for each page into the document. This size is evaluated by some PostScript viewers and will have precedence over the BoundingBox in the Header of the document. This can lead to unexpected results when you set a BoundingBox whose lower left corner is not (0, 0), because the bounding box of the page will always have a lower left corner (0, 0) and overwrites the global setting.

Each page is encapsulated into save/restore. This means, that most of the settings made on one page will not be retained on the next page.

If there is up to the first call of ps_begin_page() no call of ps_findfont(), then the header of the PostScript document will be output and the bounding box will be set to the size of the first page. The lower left corner of the bounding box is set to (0, 0). If ps_findfont() was called before, then the header has been output already, and the document will not have a valid bounding box. In order to prevent this, one should call ps_set_info() to set the info field `BoundingBox` and possibly `Orientation` before any ps_findfont() or ps_begin_page() calls.

> Hinweis:

> Up to version 0.2.6 of pslib, this function will always overwrite the BoundingBox and Orientation, if it has been set before with ps_set_info() and ps_findfont() has not been called before.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`width`

  The width of the page in pixel, e.g. 596 for A4 format.

`height`

  The height of the page in pixel, e.g. 842 for A4 format.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_end_page() - End a page
- ps_findfont() - Loads a font
- ps_set_info() - Sets information fields of document

# ps_begin_pattern

(PECL ps >= 1.2.0)

ps_begin_pattern — Start a new pattern

### Beschreibung

function ps_begin_pattern(
resource `$psdoc`,
float `$width`,
float `$height`,
float `$xstep`,
float `$ystep`,
int `$painttype`
): int|false

Starts a new pattern. A pattern is like a page containing e.g. a drawing which can be used for filling areas. It is used like a color by calling ps_setcolor() and setting the color space to `pattern`.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`width`

  The width of the pattern in pixel.

`height`

  The height of the pattern in pixel.

`xstep`

  The distance in pixel of placements of the pattern in horizontal direction.

`ystep`

  The distance in pixel of placements of the pattern in vertical direction.

`painttype`

  Must be 1 or 2.

### Rückgabewerte

The identifier of the pattern Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Creating and using a pattern

    <?php
    $ps = ps_new();

    if (!ps_open_file($ps, "pattern.ps")) {
      print "Cannot open PostScript file\n";
      exit;
    }

    ps_set_parameter($ps, "warning", "true");
    ps_set_info($ps, "Creator", "pattern.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Pattern example");

    $pspattern = ps_begin_pattern($ps, 10.0, 10.0, 10.0, 10.0, 1);
    ps_setlinewidth($ps, 0.2);
    ps_setcolor($ps, "stroke", "rgb", 0.0, 0.0, 1.0, 0.0);
    ps_moveto($ps, 0, 0);
    ps_lineto($ps, 7, 7);
    ps_stroke($ps);
    ps_moveto($ps, 0, 7);
    ps_lineto($ps, 7, 0);
    ps_stroke($ps);
    ps_end_pattern($ps);

    ps_begin_page($ps, 596, 842);
    ps_setcolor($ps, "both", "pattern", $pspattern, 0.0, 0.0, 0.0);
    ps_rect($ps, 50, 400, 200, 200);
    ps_fill($ps);
    ps_end_page($ps);

    ps_close($ps);
    ps_delete($ps);
    ?>

### Siehe auch

- ps_end_pattern() - End a pattern
- ps_setcolor() - Sets current color
- ps_shading_pattern() - Creates a pattern based on a shading

# ps_begin_template

(PECL ps >= 1.2.0)

ps_begin_template — Start a new template

### Beschreibung

function ps_begin_template(resource `$psdoc`, float `$width`, float `$height`): int

Starts a new template. A template is called a form in the postscript language. It is created similar to a pattern but used like an image. Templates are often used for drawings which are placed several times through out the document, e.g. like a company logo. All drawing functions may be used within a template. The template will not be drawn until it is placed by ps_place_image().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`width`

  The width of the template in pixel.

`height`

  The height of the template in pixel.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Creating and using a template

    <?php
    $ps = ps_new();

    if (!ps_open_file($ps, "template.ps")) {
      print "Cannot open PostScript file\n";
      exit;
    }

    ps_set_parameter($ps, "warning", "true");
    ps_set_info($ps, "Creator", "template.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Template example");

    $pstemplate = ps_begin_template($ps, 30.0, 30.0);
    ps_moveto($ps, 0, 0);
    ps_lineto($ps, 30, 30);
    ps_moveto($ps, 0, 30);
    ps_lineto($ps, 30, 0);
    ps_stroke($ps);
    ps_end_template($ps);

    ps_begin_page($ps, 596, 842);
    ps_place_image($ps, $pstemplate, 20.0, 20.0, 1.0);
    ps_place_image($ps, $pstemplate, 50.0, 30.0, 0.5);
    ps_place_image($ps, $pstemplate, 70.0, 70.0, 0.6);
    ps_place_image($ps, $pstemplate, 30.0, 50.0, 1.3);
    ps_end_page($ps);

    ps_close($ps);
    ps_delete($ps);
    ?>

### Siehe auch

- ps_end_template() - End a template

# ps_circle

(PECL ps >= 1.1.0)

ps_circle — Draws a circle

### Beschreibung

function ps_circle(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$radius`
): bool

Draws a circle with its middle point at (`x`, `y`). The circle starts and ends at position (`x`+`radius`, `y`). If this function is called outside a path it will start a new path. If it is called within a path it will add the circle as a subpath. If the last drawing operation does not end in point (`x`+`radius`, `y`) then there will be a gap in the path.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  The x-coordinate of the circle's middle point.

`y`

  The y-coordinate of the circle's middle point.

`radius`

  The radius of the circle

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_arc() - Draws an arc counterclockwise
- ps_arcn() - Draws an arc clockwise

# ps_clip

(PECL ps >= 1.1.0)

ps_clip — Clips drawing to current path

### Beschreibung

function ps_clip(resource `$psdoc`): bool

Takes the current path and uses it to define the border of a clipping area. Everything drawn outside of that area will not be visible.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_closepath() - Closes path

# ps_close

(PECL ps >= 1.1.0)

ps_close — Closes a PostScript document

### Beschreibung

function ps_close(resource `$psdoc`): bool

Closes the PostScript document.

This function writes the trailer of the PostScript document. It also writes the bookmark tree. ps_close() does not free any resources, which is done by ps_delete().

This function is also called by ps_delete() if it has not been called before.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_open_file() - Opens a file for output
- ps_delete() - Deletes all resources of a PostScript document

# ps_close_image

(PECL ps >= 1.1.0)

ps_close_image — Closes image and frees memory

### Beschreibung

function ps_close_image(resource `$psdoc`, int `$imageid`): void|false

Closes an image and frees its resources. Once an image is closed it cannot be used anymore.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`imageid`

  Resource identifier of the image as returned by ps_open_image() or ps_open_image_file().

### Rückgabewerte

Returns `null` on successBei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- ps_open_image() - Reads an image for later placement
- ps_open_image_file() - Opens image from file

# ps_closepath

(PECL ps >= 1.1.0)

ps_closepath — Closes path

### Beschreibung

function ps_closepath(resource `$psdoc`): bool

Connects the last point with the first point of a path. The resulting path can be used for stroking, filling, clipping, etc..

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_clip() - Clips drawing to current path
- ps_closepath_stroke() - Closes and strokes path

# ps_closepath_stroke

(PECL ps >= 1.1.0)

ps_closepath_stroke — Closes and strokes path

### Beschreibung

function ps_closepath_stroke(resource `$psdoc`): bool

Connects the last point with first point of a path and draws the resulting closed line.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_closepath() - Closes path

# ps_continue_text

(PECL ps >= 1.1.0)

ps_continue_text — Continue text in next line

### Beschreibung

function ps_continue_text(resource `$psdoc`, string `$text`): bool

Output a text one line below the last line. The line spacing is taken from the value "leading" which must be set with ps_set_value(). The actual position of the text is determined by the values "textx" and "texty" which can be requested with ps_get_value()

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text to output.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_show() - Output text
- ps_show_xy() - Output text at given position
- ps_show_boxed() - Output text in a box

# ps_curveto

(PECL ps >= 1.1.0)

ps_curveto — Draws a curve

### Beschreibung

function ps_curveto(
resource `$psdoc`,
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x3`,
float `$y3`
): bool

Add a section of a cubic Bézier curve described by the three given control points to the current path.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x1`

  x-coordinate of first control point.

`y1`

  y-coordinate of first control point.

`x2`

  x-coordinate of second control point.

`y2`

  y-coordinate of second control point.

`x3`

  x-coordinate of third control point.

`y3`

  y-coordinate of third control point.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_lineto() - Draws a line

# ps_delete

(PECL ps >= 1.1.0)

ps_delete — Deletes all resources of a PostScript document

### Beschreibung

function ps_delete(resource `$psdoc`): bool

Mainly frees memory used by the document. Also closes a file, if it was not closed before with ps_close(). You should in any case close the file with ps_close() before, because ps_close() not just closes the file but also outputs a trailor containing PostScript comments like the number of pages in the document and adding the bookmark hierarchy.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_close() - Closes a PostScript document

# ps_end_page

(PECL ps >= 1.1.0)

ps_end_page — End a page

### Beschreibung

function ps_end_page(resource `$psdoc`): bool

Ends a page which was started with ps_begin_page(). Ending a page will leave the current drawing context, which e.g. requires to reload fonts if they were loading within the page, and to set many other drawing parameters like the line width, or color.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_begin_page() - Start a new page

# ps_end_pattern

(PECL ps >= 1.2.0)

ps_end_pattern — End a pattern

### Beschreibung

function ps_end_pattern(resource `$psdoc`): bool

Ends a pattern which was started with ps_begin_pattern(). Once a pattern has been ended, it can be used like a color to fill areas.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_begin_pattern() - Start a new pattern

# ps_end_template

(PECL ps >= 1.2.0)

ps_end_template — End a template

### Beschreibung

function ps_end_template(resource `$psdoc`): bool

Ends a template which was started with ps_begin_template(). Once a template has been ended, it can be used like an image.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_begin_template() - Start a new template

# ps_fill

(PECL ps >= 1.1.0)

ps_fill — Fills the current path

### Beschreibung

function ps_fill(resource `$psdoc`): bool

Fills the path constructed with previously called drawing functions like ps_lineto().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_fill_stroke() - Fills and strokes the current path
- ps_stroke() - Draws the current path

# ps_fill_stroke

(PECL ps >= 1.1.0)

ps_fill_stroke — Fills and strokes the current path

### Beschreibung

function ps_fill_stroke(resource `$psdoc`): bool

Fills and draws the path constructed with previously called drawing functions like ps_lineto().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_fill() - Fills the current path
- ps_stroke() - Draws the current path

# ps_findfont

(PECL ps >= 1.1.0)

ps_findfont — Loads a font

### Beschreibung

function ps_findfont(
resource `$psdoc`,
string `$fontname`,
string `$encoding`,
bool `$embed` = `false`
): int

Loads a font for later use. Before text is output with a loaded font it must be set with ps_setfont(). This function needs the adobe font metric file in order to calculate the space used up by the characters. A font which is loaded within a page will only be available on that page. Fonts which are to be used in the complete document have to be loaded before the first call of ps_begin_page(). Calling ps_findfont() between pages will make that font available for all following pages.

The name of the afm file must be `fontname``.afm`. If the font shall be embedded the file `fontname``.pfb` containing the font outline must be present as well.

Calling ps_findfont() before the first page requires to output the postscript header which includes the BoundingBox for the whole document. Usually the BoundingBox is set with the first call of ps_begin_page() which now comes after ps_findfont(). Consequently the BoundingBox has not been set and a warning will be issued when ps_findfont() is called. In order to prevent this situation, one should call ps_set_parameter() to set the BoundingBox before ps_findfont() is called.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`fontname`

  The name of the font.

`encoding`

  ps_findfont() will try to load the file passed in the parameter `encoding`. Encoding files are of the same syntax as those used by dvips(1). They contain a font encoding vector (which is currently not used but must be present) and a list of extra ligatures to extend the list of ligatures derived from the afm file.

  `encoding` can be `null` or the empty string if the default encoding (TeXBase1) shall be used.

  If the encoding is set to `builtin` then there will be no reencoding and the font specific encoding will be used. This is very useful with symbol fonts.

`embed`

  If set to a value >0 the font will be embedded into the document. This requires the font outline (.pfb file) to be present.

### Rückgabewerte

Returns the identifier of the font or zero in case of an error. The identifier is a positive number.

### Siehe auch

- ps_begin_page() - Start a new page
- ps_setfont() - Sets font to use for following output

# ps_get_buffer

(PECL ps >= 1.1.0)

ps_get_buffer — Fetches the full buffer containig the generated PS data

### Beschreibung

function ps_get_buffer(resource `$psdoc`): string

This function is not implemented yet. It will always return an empty string. The idea for a later implementation is to write the contents of the postscript file into an internal buffer if in memory creation is requested, and retrieve the buffer content with this function. Currently, documents created in memory are send to the browser without buffering.

Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Siehe auch

- ps_open_file() - Opens a file for output

# ps_get_parameter

(PECL ps >= 1.1.0)

ps_get_parameter — Gets certain parameters

### Beschreibung

function ps_get_parameter(resource `$psdoc`, string `$name`, float `$modifier` = ?): string|false

Gets several parameters which were directly set by ps_set_parameter() or indirectly by one of the other functions. Parameters are by definition string values. This function cannot be used to retrieve resources which were also set by ps_set_parameter().

The parameter `name` can have the following values.

`fontname`

  The name of the currently active font or the font whose identifier is passed in parameter `modifier`.

`fontencoding`

  The encoding of the currently active font.

`dottedversion`

  The version of the underlying pslib library in the format <major>.<minor>.<subminor>

`scope`

  The current drawing scope. Can be object, document, null, page, pattern, path, template, prolog, font, glyph.

`ligaturedisolvechar`

  The character which dissolves a ligature. If your are using a font which contains the ligature `ff' and `|' is the char to dissolve the ligature, then `f|f' will result in two `f' instead of the ligature `ff'.

`imageencoding`

  The encoding used for encoding images. Can be either `hex` or `85`. hex encoding uses two bytes in the postscript file each byte in the image. 85 stand for Ascii85 encoding.

`linenumbermode`

  Set to `paragraph` if lines are numbered within a paragraph or `box` if they are numbered within the surrounding box.

`linebreak`

  Only used if text is output with ps_show_boxed(). If set to `true` a carriage return will add a line break.

`parbreak`

  Only used if text is output with ps_show_boxed(). If set to `true` a carriage return will start a new paragraph.

`hyphenation`

  Only used if text is output with ps_show_boxed(). If set to `true` the paragraph will be hyphenated if a hypen dictionary is set and exists.

`hyphendict`

  Filename of the dictionary used for hyphenation pattern.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`name`

  Name of the parameter.

`modifier`

  An identifier needed if a parameter of a resource is requested, e.g. the size of an image. In such a case the resource id is passed.

### Rückgabewerte

Returns the value of the parameter Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- ps_set_parameter() - Sets certain parameters

# ps_get_value

(PECL ps >= 1.1.0)

ps_get_value — Gets certain values

### Beschreibung

function ps_get_value(resource `$psdoc`, string `$name`, float `$modifier` = ?): float

Gets several values which were set by ps_set_value(). Values are by definition float values.

The parameter `name` can have the following values.

`fontsize`

  The size of the currently active font or the font whose identifier is passed in parameter `modifier`.

`font`

  The currently active font itself.

`imagewidth`

  The width of the image whose id is passed in the parameter `modifier`.

`imageheight`

  The height of the image whose id is passed in the parameter `modifier`.

`capheight`

  The height of a capital M in the currently active font or the font whose identifier is passed in parameter `modifier`.

`ascender`

  The ascender of the currently active font or the font whose identifier is passed in parameter `modifier`.

`descender`

  The descender of the currently active font or the font whose identifier is passed in parameter `modifier`.

`italicangle`

  The italicangle of the currently active font or the font whose identifier is passed in parameter `modifier`.

`underlineposition`

  The underlineposition of the currently active font or the font whose identifier is passed in parameter `modifier`.

`underlinethickness`

  The underlinethickness of the currently active font or the font whose identifier is passed in parameter `modifier`.

`textx`

  The current x-position for text output.

`texty`

  The current y-position for text output.

`textrendering`

  The current mode for text rendering.

`textrise`

  The space by which text is risen above the base line.

`leading`

  The distance between text lines in points.

`wordspacing`

  The space between words as a multiple of the width of a space char.

`charspacing`

  The space between chars. If charspacing is != 0.0 ligatures will always be dissolved.

`hyphenminchars`

  Minimum number of chars hyphenated at the end of a word.

`parindent`

  Indention of the first n line in a paragraph.

`numindentlines`

  Number of line in a paragraph to indent if parindent != 0.0.

`parskip`

  Distance between paragraphs.

`linenumberspace`

  Overall space in front of each line for the line number.

`linenumbersep`

  Space between the line and the line number.

`major`

  The major version number of pslib.

`minor`

  The minor version number of pslib.

`subminor`, `revision`

  The subminor version number of pslib.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`name`

  Name of the value.

`modifier`

  The parameter `modifier` specifies the resource for which the value is to be retrieved. This can be the id of a font or an image.

### Rückgabewerte

Returns the value of the parameter or `false`.

### Siehe auch

- ps_set_value() - Sets certain values

# ps_hyphenate

(PECL ps >= 1.1.1)

ps_hyphenate — Hyphenates a word

### Beschreibung

function ps_hyphenate(resource `$psdoc`, string `$text`): array|false

Hyphenates the passed word. ps_hyphenate() evaluates the value hyphenminchars (set by ps_set_value()) and the parameter hyphendict (set by ps_set_parameter()). hyphendict must be set before calling this function.

This function requires the locale category `LC_CTYPE` to be set properly. This is done when the extension is initialized by using the environment variables. On Unix systems read the man page of locale for more information.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`
  `text` should not contain any non alpha characters. Possible positions for breaks are returned in an array of integer numbers. Each number is the position of the char in `text` after which a hyphenation can take place.

### Rückgabewerte

An array of integers indicating the position of possible breaks in the text Bei einem Fehler wird `false` zurückgegeben..

### Beispiele

Beispiel #1 Hyphennate a text

    <?php
    $word = "Koordinatensystem";
    $psdoc = ps_new();
    ps_set_parameter($psdoc, "hyphendict", "hyph_de.dic");
    $hyphens = ps_hyphenate($psdoc, $word);
    for($i=0; $i<strlen($word); $i++) {
      echo $word[$i];
      if(in_array($i, $hyphens))
        echo "-";
    }
    ps_delete($psdoc);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Ko-ordi-na-ten-sys-tem

### Siehe auch

- ps_show_boxed() - Output text in a box
- locale(1)

# ps_include_file

(PECL ps >= 1.3.4)

ps_include_file — Reads an external file with raw PostScript code

### Beschreibung

function ps_include_file(resource `$psdoc`, string `$file`): bool

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`file`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ps_lineto

(PECL ps >= 1.1.0)

ps_lineto — Draws a line

### Beschreibung

function ps_lineto(resource `$psdoc`, float `$x`, float `$y`): bool

Adds a straight line from the current point to the given coordinates to the current path. Use ps_moveto() to set the starting point of the line.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  x-coordinate of the end point of the line.

`y`

  y-coordinate of the end point of the line.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Drawing a rectangle

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "rectangle.ps")) {
      print "Cannot open PostScript file\n";
      exit;
    }

    ps_set_info($ps, "Creator", "rectangle.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Lineto example");

    ps_begin_page($ps, 596, 842);
    ps_moveto($ps, 100, 100);
    ps_lineto($ps, 100, 200);
    ps_lineto($ps, 200, 200);
    ps_lineto($ps, 200, 100);
    ps_lineto($ps, 100, 100);
    ps_stroke($ps);
    ps_end_page($ps);

    ps_delete($ps);
    ?>

### Siehe auch

- ps_moveto() - Sets current point

# ps_makespotcolor

(PECL ps >= 1.1.0)

ps_makespotcolor — Create spot color

### Beschreibung

function ps_makespotcolor(resource `$psdoc`, string `$name`, int `$reserved` = 0): int

Creates a spot color from the current fill color. The fill color must be defined in rgb, cmyk or gray colorspace. The spot color name can be an arbitrary name. A spot color can be set as any color with ps_setcolor(). When the document is not printed but displayed by an postscript viewer the given color in the specified color space is use.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`name`

  Name of the spot color, e.g. Pantone 5565.

### Rückgabewerte

The id of the new spot color or 0 in case of an error.

### Beispiele

Beispiel #1 Creating and using a spot color

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "spotcolor.ps")) {
      print "Cannot open PostScript file\n";
      exit;
    }

    ps_set_info($ps, "Creator", "spotcolor.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Spot color example");

    ps_begin_page($ps, 596, 842);
    ps_setcolor($ps, "fill", "cmyk", 0.37, 0.0, 0.34, 0.34);
    $spotcolor = ps_makespotcolor($ps, "PANTONE 5565 C", 0);
    ps_setcolor($ps, "fill", "spot", $spotcolor, 0.5, 0.0, 0.0);
    ps_moveto($ps, 100, 100);
    ps_lineto($ps, 100, 200);
    ps_lineto($ps, 200, 200);
    ps_lineto($ps, 200, 100);
    ps_lineto($ps, 100, 100);
    ps_fill($ps);
    ps_end_page($ps);

    ps_delete($ps);
    ?>

This example creates the spot color "PANTONE 5565 C" which is a darker green (olive) and fills a rectangle with 50% intensity.

### Siehe auch

- ps_setcolor() - Sets current color

# ps_moveto

(PECL ps >= 1.1.0)

ps_moveto — Sets current point

### Beschreibung

function ps_moveto(resource `$psdoc`, float `$x`, float `$y`): bool

Sets the current point to new coordinates. If this is the first call of ps_moveto() after a previous path has been ended then it will start a new path. If this function is called in the middle of a path it will just set the current point and start a subpath.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  x-coordinate of the point to move to.

`y`

  y-coordinate of the point to move to.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_lineto() - Draws a line

# ps_new

(PECL ps >= 1.1.0)

ps_new — Creates a new PostScript document object

### Beschreibung

function ps_new(): resource|false

Creates a new document instance. It does not create the file on disk or in memory, it just sets up everything. ps_new() is usually followed by a call of ps_open_file() to actually create the postscript document.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Resource of PostScript documentBei einem Fehler wird `false` zurückgegeben.. The return value is passed to all other functions as the first argument.

### Siehe auch

- ps_delete() - Deletes all resources of a PostScript document

# ps_open_file

(PECL ps >= 1.1.0)

ps_open_file — Opens a file for output

### Beschreibung

function ps_open_file(resource `$psdoc`, string `$filename` = ?): bool

Creates a new file on disk and writes the PostScript document into it. The file will be closed when ps_close() is called.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`filename`

  The name of the postscript file. If `filename` is not passed the document will be created in memory and all output will go straight to the browser.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_close() - Closes a PostScript document

# ps_open_image

(PECL ps >= 1.1.0)

ps_open_image — Reads an image for later placement

### Beschreibung

function ps_open_image(
resource `$psdoc`,
string `$type`,
string `$source`,
string `$data`,
int `$length`,
int `$width`,
int `$height`,
int `$components`,
int `$bpc`,
string `$params`
): int

Reads an image which is already available in memory. The parameter `source` is currently not evaluated and assumed to be `memory`. The image data is a sequence of pixels starting in th upper left corner and ending in the lower right corner. Each pixel consists of `components` color components, and each component has `bpc` bits.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`type`

  The type of the image. Possible values are `png`, `jpeg`, or `eps`.

`source`

  Not used.

`data`

  The image data.

`length`

  The length of the image data.

`width`

  The width of the image.

`height`

  The height of the image.

`components`

  The number of components for each pixel. This can be 1 (gray scale images), 3 (rgb images), or 4 (cmyk, rgba images).

`bpc`

  Number of bits per component (quite often 8).

`params`

### Rückgabewerte

Returns identifier of image or zero in case of an error. The identifier is a positive number greater than 0.

### Siehe auch

- ps_open_image_file() - Opens image from file
- ps_place_image() - Places image on the page
- ps_close_image() - Closes image and frees memory

# ps_open_image_file

(PECL ps >= 1.1.0)

ps_open_image_file — Opens image from file

### Beschreibung

function ps_open_image_file(
resource `$psdoc`,
string `$type`,
string `$filename`,
string `$stringparam` = ?,
int `$intparam` = 0
): int

Loads an image for later use.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`type`

  The type of the image. Possible values are `png`, `jpeg`, or `eps`.

`filename`

  The name of the file containing the image data.

`stringparam`

  Not used.

`intparam`

  Not used.

### Rückgabewerte

Returns identifier of image or zero in case of an error. The identifier is a positive number greater than 0.

### Siehe auch

- ps_open_image() - Reads an image for later placement
- ps_place_image() - Places image on the page
- ps_close_image() - Closes image and frees memory

# ps_open_memory_image

(PECL ps >= 1.1.0)

ps_open_memory_image — Takes an GD image and returns an image for placement in a PS document

### Beschreibung

function ps_open_memory_image(resource `$psdoc`, int `$gd`): int
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`gd`

# ps_place_image

(PECL ps >= 1.1.0)

ps_place_image — Places image on the page

### Beschreibung

function ps_place_image(
resource `$psdoc`,
int `$imageid`,
float `$x`,
float `$y`,
float `$scale`
): bool

Places a formerly loaded image on the page. The image can be scaled. If the image shall be rotated as well, you will have to rotate the coordinate system before with ps_rotate().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`imageid`

  The resource identifier of the image as returned by ps_open_image() or ps_open_image_file().

`x`

  x-coordinate of the lower left corner of the image.

`y`

  y-coordinate of the lower left corner of the image.

`scale`

  The scaling factor for the image. A scale of 1.0 will result in a resolution of 72 dpi, because each pixel is equivalent to 1 point.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_open_image() - Reads an image for later placement
- ps_open_image_file() - Opens image from file

# ps_rect

(PECL ps >= 1.1.0)

ps_rect — Draws a rectangle

### Beschreibung

function ps_rect(
resource `$psdoc`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool

Draws a rectangle with its lower left corner at (`x`, `y`). The rectangle starts and ends in its lower left corner. If this function is called outside a path it will start a new path. If it is called within a path it will add the rectangle as a subpath. If the last drawing operation does not end in the lower left corner then there will be a gap in the path.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  x-coordinate of the lower left corner of the rectangle.

`y`

  y-coordinate of the lower left corner of the rectangle.

`width`

  The width of the image.

`height`

  The height of the image.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_arc() - Draws an arc counterclockwise
- ps_circle() - Draws a circle
- ps_lineto() - Draws a line

# ps_restore

(PECL ps >= 1.1.0)

ps_restore — Restore previously save context

### Beschreibung

function ps_restore(resource `$psdoc`): bool

Restores a previously saved graphics context. Any call of ps_save() must be accompanied by a call to ps_restore(). All coordinate transformations, line style settings, color settings, etc. are being restored to the state before the call of ps_save().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_save() - Save current context

# ps_rotate

(PECL ps >= 1.1.0)

ps_rotate — Sets rotation factor

### Beschreibung

function ps_rotate(resource `$psdoc`, float `$rot`): bool

Sets the rotation of the coordinate system.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`rot`

  Angle of rotation in degree.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Rotation of the coordinate system

    <?php
    function rectangle($ps) {
        ps_moveto($ps, 0, 0);
        ps_lineto($ps, 0, 50);
        ps_lineto($ps, 50, 50);
        ps_lineto($ps, 50, 0);
        ps_lineto($ps, 0, 0);
        ps_stroke($ps);
    }

    $ps = ps_new();
    if (!ps_open_file($ps, "rotation.ps")) {
      print "Cannot open PostScript file\n";
      exit;
    }

    ps_set_info($ps, "Creator", "rotation.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Rotation example");
    ps_set_info($ps, "BoundingBox", "0 0 596 842");

    $psfont = ps_findfont($ps, "Helvetica", "", 0);

    ps_begin_page($ps, 596, 842);
    ps_set_text_pos($ps, 100, 100);
    ps_save($ps);
    ps_translate($ps, 100, 100);
    ps_rotate($ps, 45);
    rectangle($ps);
    ps_restore($ps);
    ps_setfont($ps, $psfont, 8.0);
    ps_show($ps, "Text without rotation");
    ps_end_page($ps);

    ps_delete($ps);
    ?>

The above example illustrates a very common way of rotating a graphic (in this case just a rectangle) by simply rotating the coordinate system. Since the graphic's coordinate system assumes (0,0) to be the origin, the page coordinate system is also translated to place the graphics not on the edge of the page. Pay attention to the order of ps_translate() and ps_rotate(). In the above case the rectancle is rotated around the point (100, 100) in the untranslated coordinate system. Switching the two statements has a completely different result.

In order to output the following text at the original position, all modifications of the coordinate system are encapsulated in ps_save() and ps_restore().

### Siehe auch

- ps_scale() - Sets scaling factor
- ps_translate() - Sets translation

# ps_save

(PECL ps >= 1.1.0)

ps_save — Save current context

### Beschreibung

function ps_save(resource `$psdoc`): bool

Saves the current graphics context, containing colors, translation and rotation settings and some more. A saved context can be restored with ps_restore().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_restore() - Restore previously save context

# ps_scale

(PECL ps >= 1.1.0)

ps_scale — Sets scaling factor

### Beschreibung

function ps_scale(resource `$psdoc`, float `$x`, float `$y`): bool

Sets horizontal and vertical scaling of the coordinate system.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  Scaling factor in horizontal direction.

`y`

  Scaling factor in vertical direction.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_rotate() - Sets rotation factor
- ps_translate() - Sets translation

# ps_set_border_color

(PECL ps >= 1.1.0)

ps_set_border_color — Sets color of border for annotations

### Beschreibung

function ps_set_border_color(
resource `$psdoc`,
float `$red`,
float `$green`,
float `$blue`
): bool

Links added with one of the functions ps_add_weblink(), ps_add_pdflink(), etc. will be displayed with a surounded rectangle when the postscript document is converted to pdf and viewed in a pdf viewer. This rectangle is not visible in the postscript document. This function sets the color of the rectangle's border line.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`red`

  The red component of the border color.

`green`

  The green component of the border color.

`blue`

  The blue component of the border color.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_set_border_dash() - Sets length of dashes for border of annotations
- ps_set_border_style() - Sets border style of annotations

# ps_set_border_dash

(PECL ps >= 1.1.0)

ps_set_border_dash — Sets length of dashes for border of annotations

### Beschreibung

function ps_set_border_dash(resource `$psdoc`, float `$black`, float `$white`): bool

Links added with one of the functions ps_add_weblink(), ps_add_pdflink(), etc. will be displayed with a surounded rectangle when the postscript document is converted to pdf and viewed in a pdf viewer. This rectangle is not visible in the postscript document. This function sets the length of the black and white portion of a dashed border line.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`black`

  The length of the dash.

`white`

  The length of the gap between dashes.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_set_border_color() - Sets color of border for annotations
- ps_set_border_style() - Sets border style of annotations

# ps_set_border_style

(PECL ps >= 1.1.0)

ps_set_border_style — Sets border style of annotations

### Beschreibung

function ps_set_border_style(resource `$psdoc`, string `$style`, float `$width`): bool

Links added with one of the functions ps_add_weblink(), ps_add_pdflink(), etc. will be displayed with a surounded rectangle when the postscript document is converted to pdf and viewed in a pdf viewer. This rectangle is not visible in the postscript document. This function sets the appearance and width of the border line.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`style`

  `style` can be `solid` or `dashed`.

`width`

  The line width of the border.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_set_border_color() - Sets color of border for annotations
- ps_set_border_dash() - Sets length of dashes for border of annotations

# ps_set_info

(PECL ps >= 1.1.0)

ps_set_info — Sets information fields of document

### Beschreibung

function ps_set_info(resource `$psdoc`, string `$key`, string `$value`): bool

Sets certain information fields of the document. This fields will be shown as a comment in the header of the PostScript file. If the document is converted to pdf this fields will also be used for the document information.

The `BoundingBox` is usually set to the value given to the first page. This only works if ps_findfont() has not been called before. In such cases the BoundingBox would be left unset unless you set it explicitly with this function.

This function will have no effect anymore when the header of the postscript file has been already written. It must be called before the first page or the first call of ps_findfont().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`key`

  The name of the information field to set. The values which can be set are `Keywords`, `Subject`, `Title`, `Creator`, `Author`, `BoundingBox`, and `Orientation`. Be aware that some of them has a meaning to PostScript viewers.

`value`

  The value of the information field. The field `Orientation` can be set to either `Portrait` or `Landscape`. The `BoundingBox` is a string consisting of four numbers. The first two numbers are the coordinates of the lower left corner of the page. The last two numbers are the coordinates of the upper right corner.

  > Hinweis:

  > Up to version 0.2.6 of pslib, the BoundingBox and Orientation will be overwritten by ps_begin_page(), unless ps_findfont() has been called before.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_findfont() - Loads a font
- ps_begin_page() - Start a new page

# ps_set_parameter

(PECL ps >= 1.1.0)

ps_set_parameter — Sets certain parameters

### Beschreibung

function ps_set_parameter(resource `$psdoc`, string `$name`, string `$value`): bool

Sets several parameters which are used by many functions. Parameters are by definition string values.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`name`

  For a list of possible names see ps_get_parameter().

`value`

  The value of the parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_get_parameters()
- ps_set_value() - Sets certain values

# ps_set_text_pos

(PECL ps >= 1.1.0)

ps_set_text_pos — Sets position for text output

### Beschreibung

function ps_set_text_pos(resource `$psdoc`, float `$x`, float `$y`): bool

Set the position for the next text output. You may alternatively set the x and y value separately by calling ps_set_value() and choosing `textx` respectively `texty` as the value name.

If you want to output text at a certain position it is more convenient to use ps_show_xy() instead of setting the text position and calling ps_show().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  x-coordinate of the new text position.

`y`

  y-coordinate of the new text position.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Placing text at a given position

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "text.ps")) {
      print "Cannot open PostScript file\n";
      exit;
    }

    ps_set_info($ps, "Creator", "rectangle.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Text placement example");

    ps_begin_page($ps, 596, 842);
    $psfont = ps_findfont($ps, "Helvetica", "", 0);
    ps_setfont($ps, $psfont, 8.0);
    ps_show_xy($ps, "Some text at (100, 100)", 100, 100);

    ps_set_value($ps, "textx", 100);
    ps_set_value($ps, "texty", 120);
    ps_show($ps, "Some text at (100, 120)");
    ps_end_page($ps);

    ps_delete($ps);
    ?>

### Siehe auch

- ps_set_value() - Sets certain values
- ps_show() - Output text

# ps_set_value

(PECL ps >= 1.1.0)

ps_set_value — Sets certain values

### Beschreibung

function ps_set_value(resource `$psdoc`, string `$name`, float `$value`): bool

Sets several values which are used by many functions. Parameters are by definition float values.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`name`

  The `name` can be one of the following:

  textrendering

    The way how text is shown.

  textx

    The x coordinate for text output.

  texty

    The y coordinate for text output.

  wordspacing

    The distance between words relative to the width of a space.

  leading

    The distance between lines in pixels.

`value`

  The value of the parameter.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_get_value() - Gets certain values
- ps_set_parameter() - Sets certain parameters

# ps_setcolor

(PECL ps >= 1.1.0)

ps_setcolor — Sets current color

### Beschreibung

function ps_setcolor(
resource `$psdoc`,
string `$type`,
string `$colorspace`,
float `$c1`,
float `$c2`,
float `$c3`,
float `$c4`
): bool

Sets the color for drawing, filling, or both.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`type`

  The parameter `type` can be `both`, `fill`, or `fillstroke`.

`colorspace`

  The colorspace should be one of `gray`, `rgb`, `cmyk`, `spot`, `pattern`. Depending on the colorspace either only the first, the first three or all parameters will be used.

`c1`

  Depending on the colorspace this is either the red component (rgb), the cyan component (cmyk), the gray value (gray), the identifier of the spot color or the identifier of the pattern.

`c2`

  Depending on the colorspace this is either the green component (rgb), the magenta component (cmyk).

`c3`

  Depending on the colorspace this is either the blue component (rgb), the yellow component (cmyk).

`c4`

  This must only be set in cmyk colorspace and specifies the black component.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Anmerkungen

Achtung

The second parameter is currently not always evaluated. The color is sometimes set for filling and drawing just as if `fillstroke` were passed.

# ps_setdash

(PECL ps >= 1.1.0)

ps_setdash — Sets appearance of a dashed line

### Beschreibung

function ps_setdash(resource `$psdoc`, float `$on`, float `$off`): bool

Sets the length of the black and white portions of a dashed line.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`on`

  The length of the dash.

`off`

  The length of the gap between dashes.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_setpolydash() - Sets appearance of a dashed line

# ps_setflat

(PECL ps >= 1.1.0)

ps_setflat — Sets flatness

### Beschreibung

function ps_setflat(resource `$psdoc`, float `$value`): bool

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`value`

  The `value` must be between 0.2 and 1.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ps_setfont

(PECL ps >= 1.1.0)

ps_setfont — Sets font to use for following output

### Beschreibung

function ps_setfont(resource `$psdoc`, int `$fontid`, float `$size`): bool

Sets a font, which has to be loaded before with ps_findfont(). Outputting text without setting a font results in an error.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`fontid`

  The font identifier as returned by ps_findfont().

`size`

  The size of the font.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_findfont() - Loads a font
- ps_set_text_pos() - Sets position for text output for an example.

# ps_setgray

(PECL ps >= 1.1.0)

ps_setgray — Sets gray value

### Beschreibung

function ps_setgray(resource `$psdoc`, float `$gray`): bool

Sets the gray value for all following drawing operations.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`gray`

  The value must be between 0 (white) and 1 (black).

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_setcolor() - Sets current color

# ps_setlinecap

(PECL ps >= 1.1.0)

ps_setlinecap — Sets appearance of line ends

### Beschreibung

function ps_setlinecap(resource `$psdoc`, int `$type`): bool

Sets how line ends look like.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`type`

  The type of line ends. Possible values are `PS_LINECAP_BUTT`, `PS_LINECAP_ROUND`, or `PS_LINECAP_SQUARED`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_setlinejoin() - Sets how contected lines are joined
- ps_setlinewidth() - Sets width of a line
- ps_setmiterlimit() - Sets the miter limit

# ps_setlinejoin

(PECL ps >= 1.1.0)

ps_setlinejoin — Sets how contected lines are joined

### Beschreibung

function ps_setlinejoin(resource `$psdoc`, int `$type`): bool

Sets how lines are joined.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`type`

  The way lines are joined. Possible values are `PS_LINEJOIN_MITER`, `PS_LINEJOIN_ROUND`, or `PS_LINEJOIN_BEVEL`.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_setlinecap() - Sets appearance of line ends
- ps_setlinewidth() - Sets width of a line
- ps_setmiterlimit() - Sets the miter limit

# ps_setlinewidth

(PECL ps >= 1.1.0)

ps_setlinewidth — Sets width of a line

### Beschreibung

function ps_setlinewidth(resource `$psdoc`, float `$width`): bool

Sets the line width for all following drawing operations.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`width`

  The width of lines in points.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_setlinecap() - Sets appearance of line ends
- ps_setlinejoin() - Sets how contected lines are joined
- ps_setmiterlimit() - Sets the miter limit

# ps_setmiterlimit

(PECL ps >= 1.1.0)

ps_setmiterlimit — Sets the miter limit

### Beschreibung

function ps_setmiterlimit(resource `$psdoc`, float `$value`): bool

If two lines join in a small angle and the line join is set to `PS_LINEJOIN_MITER`, then the resulting spike will be very long. The miter limit is the maximum ratio of the miter length (the length of the spike) and the line width.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`value`

  The maximum ratio between the miter length and the line width. Larger values (> 10) will result in very long spikes when two lines meet in a small angle. Keep the default unless you know what you are doing.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_setlinecap() - Sets appearance of line ends
- ps_setlinejoin() - Sets how contected lines are joined
- ps_setlinewidth() - Sets width of a line

# ps_setoverprintmode

(PECL ps >= 1.3.0)

ps_setoverprintmode — Sets overprint mode

### Beschreibung

function ps_setoverprintmode(resource `$psdoc`, int `$mode`): bool

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`mode`

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ps_setpolydash

(PECL ps >= 1.1.0)

ps_setpolydash — Sets appearance of a dashed line

### Beschreibung

function ps_setpolydash(resource `$psdoc`, float `$arr`): bool

Sets the length of the black and white portions of a dashed line. ps_setpolydash() is used to set more complicated dash patterns.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`arr`

  `arr` is a list of length elements alternately for the black and white portion.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Drawing a dashed line

    <?php
    $ps = ps_new();
    if (!ps_open_file($ps, "polydash.ps")) {
       print "Cannot open PostScript file\n";
         exit;
    }

    ps_set_info($ps, "Creator", "polydash.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Poly dash example");

    ps_begin_page($ps, 596, 842);
    ps_setpolydash($ps, array(10, 5, 2, 5));
    ps_moveto($ps, 100, 100);
    ps_lineto($ps, 200, 200);
    ps_stroke($ps);
    ps_end_page($ps);

    ps_delete($ps);
    ?>

This example draws a line with a 10 and 2 points long line, and gaps of 5 points inbetween.

### Siehe auch

- ps_setdash() - Sets appearance of a dashed line

# ps_shading

(PECL ps >= 1.3.0)

ps_shading — Creates a shading for later use

### Beschreibung

function ps_shading(
resource `$psdoc`,
string `$type`,
float `$x0`,
float `$y0`,
float `$x1`,
float `$y1`,
float `$c1`,
float `$c2`,
float `$c3`,
float `$c4`,
string `$optlist`
): int|false

Creates a shading, which can be used by ps_shfill() or ps_shading_pattern().

The color of the shading can be in any color space except for `pattern`.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`type`

  The type of shading can be either `radial` or `axial`. Each shading starts with the current fill color and ends with the given color values passed in the parameters `c1` to `c4` (see ps_setcolor() for their meaning).

`x0, x1, y0, y1`

  The coordinates `x0`, `y0`, `x1`, `y1` are the start and end point of the shading. If the type of shading is `radial` the two points are the middle points of a starting and ending circle.

`c1, c2, c3, c4`

  See ps_setcolor() for their meaning.

`optlist`

  If the shading is of type `radial` the `optlist` must also contain the parameters `r0` and `r1` with the radius of the start and end circle.

### Rückgabewerte

Returns the identifier of the pattern Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- ps_shading_pattern() - Creates a pattern based on a shading
- ps_shfill() - Fills an area with a shading

# ps_shading_pattern

(PECL ps >= 1.3.0)

ps_shading_pattern — Creates a pattern based on a shading

### Beschreibung

function ps_shading_pattern(resource `$psdoc`, int `$shadingid`, string `$optlist`): int|false

Creates a pattern based on a shading, which has to be created before with ps_shading(). Shading patterns can be used like regular patterns.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`shadingid`

  The identifier of a shading previously created with ps_shading().

`optlist`

  This argument is not currently used.

### Rückgabewerte

The identifier of the pattern Bei einem Fehler wird `false` zurückgegeben..

### Siehe auch

- ps_shading() - Creates a shading for later use
- ps_shfill() - Fills an area with a shading

# ps_shfill

(PECL ps >= 1.3.0)

ps_shfill — Fills an area with a shading

### Beschreibung

function ps_shfill(resource `$psdoc`, int `$shadingid`): bool

Fills an area with a shading, which has to be created before with ps_shading(). This is an alternative way to creating a pattern from a shading ps_shading_pattern() and using the pattern as the filling color.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`shadingid`

  The identifier of a shading previously created with ps_shading().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_shading() - Creates a shading for later use
- ps_shading_pattern() - Creates a pattern based on a shading

# ps_show

(PECL ps >= 1.1.0)

ps_show — Output text

### Beschreibung

function ps_show(resource `$psdoc`, string `$text`): bool

Output a text at the current text position. The text position can be set by storing the x and y coordinates into the values `textx` and `texty` with the function ps_set_value(). The function will issue an error if a font was not set before with ps_setfont().

ps_show() evaluates the following parameters and values as set by ps_set_parameter() and ps_set_value().

charspacing (value)

  Distance between two consecutive glyphs. If this value is unequal to zero then all ligatures will be resolved. Values less than zero are allowed.

kerning (parameter)

  Setting this parameter to "false" will turn off kerning. Kerning is turned on by default.

ligatures (parameter)

  Setting this parameter to "false" will turn off the use of ligatures. Ligatures are turned on by default.

underline (parameter)

  Setting this parameter to "true" will turn on underlining. Underlining is turned off by default.

overline (parameter)

  Setting this parameter to "true" will turn on overlining. Overlining is turned off by default.

strikeout (parameter)

  Setting this parameter to "true" will turn on striking out. Striking out is turned off by default.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text to be output.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_continue_text() - Continue text in next line
- ps_show_xy() - Output text at given position
- ps_setfont() - Sets font to use for following output

# ps_show_boxed

(PECL ps >= 1.1.0)

ps_show_boxed — Output text in a box

### Beschreibung

function ps_show_boxed(
resource `$psdoc`,
string `$text`,
float `$left`,
float `$bottom`,
float `$width`,
float `$height`,
string `$hmode`,
string `$feature` = ?
): int

Outputs a text in a given box. The lower left corner of the box is at (`left`, `bottom`). Line breaks will be inserted where needed. Multiple spaces are treated as one. Tabulators are treated as spaces.

The text will be hyphenated if the parameter `hyphenation` is set to `true` and the parameter `hyphendict` contains a valid filename for a hyphenation file. The line spacing is taken from the value `leading`. Paragraphs can be separated by an empty line just like in TeX. If the value `parindent` is set to value > 0.0 then the first n lines will be indented. The number n of lines is set by the parameter `numindentlines`. In order to prevent indenting of the first m paragraphs set the value `parindentskip` to a positive number.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text to be output into the given box.

`left`

  x-coordinate of the lower left corner of the box.

`bottom`

  y-coordinate of the lower left corner of the box.

`width`

  Width of the box.

`height`

  Height of the box.

`hmode`

  The parameter `hmode` can be `justify`, `fulljustify`, `right`, `left`, or `center`. The difference of `justify` and `fulljustify` just affects the last line of the box. In `fulljustify` mode the last line will be left and right justified unless this is also the last line of paragraph. In `justify` mode it will always be left justified.

`feature`

#### Used parameters

The output of ps_show_boxed() can be configured with several parameters and values which must be set with either ps_set_parameter() or ps_set_value(). Beside the parameters and values which affect text output, the following parameters and values are evaluated.

leading (value)

  Distance between baselines of two consecutive lines.

linebreak (parameter)

  Set to `true` if you want a carriage return to start a new line instead of treating it as a space. Defaults to `false`.

parbreak (parameter)

  Set to `true` if you want a carriage return on a single line to start a new paragraph instead of treating it as a space. Defaults to `true`.

hyphenation (parameter)

  Set to `true` in order to turn hyphenation on. This requires a dictionary to be set with the parameter `hyphendict`. Defaults to `false`.

hyphendict (parameter)

  Filename of the dictionary used for hyphenation pattern (see below).

hyphenminchar (value)

  The number of chars which must at least be left over before or after the hyphen. This implies that only words of at least two times this value will be hyphenated. The default value is three. Setting a value of zero will result in the default value.

parindent (value)

  Set the amount of space in pixel for indenting the first m lines of a paragraph. m can be set with the value `numindentlines`.

parskip (value)

  Set the amount of extra space in pixel between paragraphs. Defaults to `0` which will result in a normal line distance.

numindentlines (value)

  Number of lines from the start of the paragraph which will be indented. Defaults to `1`.

parindentskip (value)

  Number of paragraphs in the box whose first lines will not be indented. This defaults to `0`. This is useful for paragraphs right after a section heading or text being continued in a second box. In both case one would set this to `1`.

linenumbermode (parameter)

  Set how lines are to be numbered. Possible values are `box` for numbering lines in the whole box or `paragraph` to number lines within each paragraph.

linenumberspace (value)

  The space for the column left of the numbered line containing the line number. The line number will be right justified into this column. Defaults to `20`.

linenumbersep (value)

  The space between the column with line numbers and the line itself. Defaults to `5`.

#### Hyphenation

Text is hyphenated if the parameter `hyphenation` is set to true and a valid hyphenation dictionary is set. pslib does not ship its own hyphenation dictionary but uses one from openoffice, scribus or koffice. You can find their dictionaries for different languages in one of the following directories if the software is installed:

- /usr/share/apps/koffice/hyphdicts/
- /usr/lib/scribus/dicts/
- /usr/lib/openoffice/share/dict/ooo/

Currently scribus appears to have the most complete hyphenation dictionaries.

### Rückgabewerte

Number of characters that could not be written.

### Siehe auch

- ps_continue_text() - Continue text in next line

# ps_show_xy

(PECL ps >= 1.1.0)

ps_show_xy — Output text at given position

### Beschreibung

function ps_show_xy(
resource `$psdoc`,
string `$text`,
float `$x`,
float `$y`
): bool

Output a text at the given text position.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text to be output.

`x`

  x-coordinate of the lower left corner of the box surrounding the text.

`y`

  y-coordinate of the lower left corner of the box surrounding the text.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_continue_text() - Continue text in next line
- ps_show() - Output text

# ps_show_xy2

(PECL ps >= 1.1.0)

ps_show_xy2 — Output text at position

### Beschreibung

function ps_show_xy2(
resource `$psdoc`,
string `$text`,
int `$len`,
float `$xcoor`,
float `$ycoor`
): bool
Warnung

Diese Funktion ist bis jetzt nicht dokumentiert. Es steht nur die Liste der Parameter zur Verfügung.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ps_show2

(PECL ps >= 1.1.0)

ps_show2 — Output a text at current position

### Beschreibung

function ps_show2(resource `$psdoc`, string `$text`, int `$len`): bool

Output text at the current position. Do not print more than `len` characters.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text to be output.

`len`

  The maximum number of characters to print.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

# ps_string_geometry

(PECL ps >= 1.2.0)

ps_string_geometry — Gets geometry of a string

### Beschreibung

function ps_string_geometry(
resource `$psdoc`,
string `$text`,
int `$fontid` = 0,
float `$size` = 0.0
): array

This function is similar to ps_stringwidth() but returns an array of dimensions containing the width, ascender, and descender of the text.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text for which the geometry is to be calculated.

`fontid`

  The identifier of the font to be used. If not font is specified the current font will be used.

`size`

  The size of the font. If no size is specified the current size is used.

### Rückgabewerte

An array of the dimensions of a string. The element 'width' contains the width of the string as returned by ps_stringwidth(). The element 'descender' contains the maximum descender and 'ascender' the maximum ascender of the string.

### Siehe auch

- ps_continue_text() - Continue text in next line
- ps_stringwidth() - Gets width of a string

# ps_stringwidth

(PECL ps >= 1.1.0)

ps_stringwidth — Gets width of a string

### Beschreibung

function ps_stringwidth(
resource `$psdoc`,
string `$text`,
int `$fontid` = 0,
float `$size` = 0.0
): float

Calculates the width of a string in points if it was output in the given font and font size. This function needs an Adobe font metrics file to calculate the precise width. If kerning is turned on, it will be taken into account.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`text`

  The text for which the width is to be calculated.

`fontid`

  The identifier of the font to be used. If not font is specified the current font will be used.

`size`

  The size of the font. If no size is specified the current size is used.

### Rückgabewerte

Width of a string in points.

### Siehe auch

- ps_string_geometry() - Gets geometry of a string

# ps_stroke

(PECL ps >= 1.1.0)

ps_stroke — Draws the current path

### Beschreibung

function ps_stroke(resource `$psdoc`): bool

Draws the path constructed with previously called drawing functions like ps_lineto().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_closepath_stroke() - Closes and strokes path
- ps_fill() - Fills the current path
- ps_fill_stroke() - Fills and strokes the current path

# ps_symbol

(PECL ps >= 1.2.0)

ps_symbol — Output a glyph

### Beschreibung

function ps_symbol(resource `$psdoc`, int `$ord`): bool

Output the glyph at position `ord` in the font encoding vector of the current font. The font encoding for a font can be set when loading the font with ps_findfont().

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`ord`

  The position of the glyph in the font encoding vector.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- ps_symbol_name() - Gets name of a glyph
- ps_symbol_width() - Gets width of a glyph

# ps_symbol_name

(PECL ps >= 1.2.0)

ps_symbol_name — Gets name of a glyph

### Beschreibung

function ps_symbol_name(resource `$psdoc`, int `$ord`, int `$fontid` = 0): string

This function needs an Adobe font metrics file to know which glyphs are available.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`ord`

  The parameter `ord` is the position of the glyph in the font encoding vector.

`fontid`

  The identifier of the font to be used. If not font is specified the current font will be used.

### Rückgabewerte

The name of a glyph in the given font.

### Siehe auch

- ps_symbol() - Output a glyph
- ps_symbol_width() - Gets width of a glyph

# ps_symbol_width

(PECL ps >= 1.2.0)

ps_symbol_width — Gets width of a glyph

### Beschreibung

function ps_symbol_width(
resource `$psdoc`,
int `$ord`,
int `$fontid` = 0,
float `$size` = 0.0
): float

Calculates the width of a glyph in points if it was output in the given font and font size. This function needs an Adobe font metrics file to calculate the precise width.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`ord`

  The position of the glyph in the font encoding vector.

`fontid`

  The identifier of the font to be used. If not font is specified the current font will be used.

`size`

  The size of the font. If no size is specified the current size is used.

### Rückgabewerte

The width of a glyph in points.

### Siehe auch

- ps_symbol() - Output a glyph
- ps_symbol_name() - Gets name of a glyph

# ps_translate

(PECL ps >= 1.1.0)

ps_translate — Sets translation

### Beschreibung

function ps_translate(resource `$psdoc`, float `$x`, float `$y`): bool

Sets a new initial point of the coordinate system.

### Parameter-Liste

`psdoc`

  Resource identifier of the postscript file as returned by ps_new().

`x`

  x-coordinate of the origin of the translated coordinate system.

`y`

  y-coordinate of the origin of the translated coordinate system.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 Translation of the coordinate system

    <?php
    function rectangle($ps) {
        ps_moveto($ps, 0, 0);
        ps_lineto($ps, 0, 50);
        ps_lineto($ps, 50, 50);
        ps_lineto($ps, 50, 0);
        ps_lineto($ps, 0, 0);
        ps_stroke($ps);
    }

    $ps = ps_new();
    if (!ps_open_file($ps, "translate.ps")) {
      print "Cannot open PostScript file\n";
      exit;
    }

    ps_set_info($ps, "Creator", "translate.php");
    ps_set_info($ps, "Author", "Uwe Steinmann");
    ps_set_info($ps, "Title", "Translated example");
    ps_set_info($ps, "BoundingBox", "0 0 596 842");

    $psfont = ps_findfont($ps, "Helvetica", "", 0);

    ps_begin_page($ps, 596, 842);
    ps_set_text_pos($ps, 100, 100);
    ps_translate($ps, 500, 750);
    rectangle($ps);
    ps_translate($ps, -500, -750);
    ps_setfont($ps, $psfont, 8.0);
    ps_show($ps, "Text at initial position");
    ps_end_page($ps);

    ps_begin_page($ps, 596, 842);
    ps_set_text_pos($ps, 100, 100);
    ps_save($ps);
    ps_translate($ps, 500, 750);
    rectangle($ps);
    ps_restore($ps);
    ps_setfont($ps, $psfont, 8.0);
    ps_show($ps, "Text at initial position");
    ps_end_page($ps);

    ps_delete($ps);
    ?>

The above example demonstrates two possible ways to place a graphic (in this case just a rectangle) at any position on the page, while the graphic itself uses its own coordinate system. The trick is to change the origin of the current coordinate system before drawing the rectangle. The translation has to be undone after the graphic has been drawn.

On the second page a slightly different and more elegant approach is applied. Instead of undoing the translation with a second call of ps_translate() the graphics context is saved before modifying the coordinate system and restored after drawing the rectangle.

### Siehe auch

- ps_scale() - Sets scaling factor
- ps_rotate() - Sets rotation factor

## Inhaltsverzeichnis

- ps_add_bookmark — Add bookmark to current page
- ps_add_launchlink — Adds link which launches file
- ps_add_locallink — Adds link to a page in the same document
- ps_add_note — Adds note to current page
- ps_add_pdflink — Adds link to a page in a second pdf document
- ps_add_weblink — Adds link to a web location
- ps_arc — Draws an arc counterclockwise
- ps_arcn — Draws an arc clockwise
- ps_begin_page — Start a new page
- ps_begin_pattern — Start a new pattern
- ps_begin_template — Start a new template
- ps_circle — Draws a circle
- ps_clip — Clips drawing to current path
- ps_close — Closes a PostScript document
- ps_close_image — Closes image and frees memory
- ps_closepath — Closes path
- ps_closepath_stroke — Closes and strokes path
- ps_continue_text — Continue text in next line
- ps_curveto — Draws a curve
- ps_delete — Deletes all resources of a PostScript document
- ps_end_page — End a page
- ps_end_pattern — End a pattern
- ps_end_template — End a template
- ps_fill — Fills the current path
- ps_fill_stroke — Fills and strokes the current path
- ps_findfont — Loads a font
- ps_get_buffer — Fetches the full buffer containig the generated PS data
- ps_get_parameter — Gets certain parameters
- ps_get_value — Gets certain values
- ps_hyphenate — Hyphenates a word
- ps_include_file — Reads an external file with raw PostScript code
- ps_lineto — Draws a line
- ps_makespotcolor — Create spot color
- ps_moveto — Sets current point
- ps_new — Creates a new PostScript document object
- ps_open_file — Opens a file for output
- ps_open_image — Reads an image for later placement
- ps_open_image_file — Opens image from file
- ps_open_memory_image — Takes an GD image and returns an image for placement in a PS document
- ps_place_image — Places image on the page
- ps_rect — Draws a rectangle
- ps_restore — Restore previously save context
- ps_rotate — Sets rotation factor
- ps_save — Save current context
- ps_scale — Sets scaling factor
- ps_set_border_color — Sets color of border for annotations
- ps_set_border_dash — Sets length of dashes for border of annotations
- ps_set_border_style — Sets border style of annotations
- ps_set_info — Sets information fields of document
- ps_set_parameter — Sets certain parameters
- ps_set_text_pos — Sets position for text output
- ps_set_value — Sets certain values
- ps_setcolor — Sets current color
- ps_setdash — Sets appearance of a dashed line
- ps_setflat — Sets flatness
- ps_setfont — Sets font to use for following output
- ps_setgray — Sets gray value
- ps_setlinecap — Sets appearance of line ends
- ps_setlinejoin — Sets how contected lines are joined
- ps_setlinewidth — Sets width of a line
- ps_setmiterlimit — Sets the miter limit
- ps_setoverprintmode — Sets overprint mode
- ps_setpolydash — Sets appearance of a dashed line
- ps_shading — Creates a shading for later use
- ps_shading_pattern — Creates a pattern based on a shading
- ps_shfill — Fills an area with a shading
- ps_show — Output text
- ps_show_boxed — Output text in a box
- ps_show_xy — Output text at given position
- ps_show_xy2 — Output text at position
- ps_show2 — Output a text at current position
- ps_string_geometry — Gets geometry of a string
- ps_stringwidth — Gets width of a string
- ps_stroke — Draws the current path
- ps_symbol — Output a glyph
- ps_symbol_name — Gets name of a glyph
- ps_symbol_width — Gets width of a glyph
- ps_translate — Sets translation

- Installation/Konfiguration
  - Anforderungen
  - Installation
  - Ressource-Typen
- Vordefinierte Konstanten
- PS Funktionen
  - ps_add_bookmark — Add bookmark to current page
  - ps_add_launchlink — Adds link which launches file
  - ps_add_locallink — Adds link to a page in the same document
  - ps_add_note — Adds note to current page
  - ps_add_pdflink — Adds link to a page in a second pdf document
  - ps_add_weblink — Adds link to a web location
  - ps_arc — Draws an arc counterclockwise
  - ps_arcn — Draws an arc clockwise
  - ps_begin_page — Start a new page
  - ps_begin_pattern — Start a new pattern
  - ps_begin_template — Start a new template
  - ps_circle — Draws a circle
  - ps_clip — Clips drawing to current path
  - ps_close — Closes a PostScript document
  - ps_close_image — Closes image and frees memory
  - ps_closepath — Closes path
  - ps_closepath_stroke — Closes and strokes path
  - ps_continue_text — Continue text in next line
  - ps_curveto — Draws a curve
  - ps_delete — Deletes all resources of a PostScript document
  - ps_end_page — End a page
  - ps_end_pattern — End a pattern
  - ps_end_template — End a template
  - ps_fill — Fills the current path
  - ps_fill_stroke — Fills and strokes the current path
  - ps_findfont — Loads a font
  - ps_get_buffer — Fetches the full buffer containig the generated PS data
  - ps_get_parameter — Gets certain parameters
  - ps_get_value — Gets certain values
  - ps_hyphenate — Hyphenates a word
  - ps_include_file — Reads an external file with raw PostScript code
  - ps_lineto — Draws a line
  - ps_makespotcolor — Create spot color
  - ps_moveto — Sets current point
  - ps_new — Creates a new PostScript document object
  - ps_open_file — Opens a file for output
  - ps_open_image — Reads an image for later placement
  - ps_open_image_file — Opens image from file
  - ps_open_memory_image — Takes an GD image and returns an image for placement in a PS document
  - ps_place_image — Places image on the page
  - ps_rect — Draws a rectangle
  - ps_restore — Restore previously save context
  - ps_rotate — Sets rotation factor
  - ps_save — Save current context
  - ps_scale — Sets scaling factor
  - ps_set_border_color — Sets color of border for annotations
  - ps_set_border_dash — Sets length of dashes for border of annotations
  - ps_set_border_style — Sets border style of annotations
  - ps_set_info — Sets information fields of document
  - ps_set_parameter — Sets certain parameters
  - ps_set_text_pos — Sets position for text output
  - ps_set_value — Sets certain values
  - ps_setcolor — Sets current color
  - ps_setdash — Sets appearance of a dashed line
  - ps_setflat — Sets flatness
  - ps_setfont — Sets font to use for following output
  - ps_setgray — Sets gray value
  - ps_setlinecap — Sets appearance of line ends
  - ps_setlinejoin — Sets how contected lines are joined
  - ps_setlinewidth — Sets width of a line
  - ps_setmiterlimit — Sets the miter limit
  - ps_setoverprintmode — Sets overprint mode
  - ps_setpolydash — Sets appearance of a dashed line
  - ps_shading — Creates a shading for later use
  - ps_shading_pattern — Creates a pattern based on a shading
  - ps_shfill — Fills an area with a shading
  - ps_show — Output text
  - ps_show_boxed — Output text in a box
  - ps_show_xy — Output text at given position
  - ps_show_xy2 — Output text at position
  - ps_show2 — Output a text at current position
  - ps_string_geometry — Gets geometry of a string
  - ps_stringwidth — Gets width of a string
  - ps_stroke — Draws the current path
  - ps_symbol — Output a glyph
  - ps_symbol_name — Gets name of a glyph
  - ps_symbol_width — Gets width of a glyph
  - ps_translate — Sets translation

# RpmInfo

# Einführung

This extension enables you to retrieve information from RPM files or from the installed RPMs database.

It also provides a `rpm` stream wrapper to retrieve RPM content (since version 1.0.0 with librpm >= 4.13).

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation via PECL

## Anforderungen

This extension requires » librpm version 4.11.3 or higher.

## Installation via PECL

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/rpminfo.

# Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

Miscellaneous constants
`RPMVERSION` (string)
  System librpm version.

RPM Senses
`RPMSENSE_ANY` (int)
`RPMSENSE_LESS` (int)
`RPMSENSE_GREATER` (int)
`RPMSENSE_EQUAL` (int)
`RPMSENSE_POSTTRANS` (int)
`RPMSENSE_PREREQ` (int)
`RPMSENSE_PRETRANS` (int)
`RPMSENSE_INTERP` (int)
`RPMSENSE_SCRIPT_PRE` (int)
`RPMSENSE_SCRIPT_POST` (int)
`RPMSENSE_SCRIPT_PREUN` (int)
`RPMSENSE_SCRIPT_POSTUN` (int)
`RPMSENSE_SCRIPT_VERIFY` (int)
`RPMSENSE_FIND_REQUIRES` (int)
`RPMSENSE_FIND_PROVIDES` (int)
`RPMSENSE_TRIGGERIN` (int)
`RPMSENSE_TRIGGERUN` (int)
`RPMSENSE_TRIGGERPOSTUN` (int)
`RPMSENSE_MISSINGOK` (int)
`RPMSENSE_RPMLIB` (int)
`RPMSENSE_TRIGGERPREIN` (int)
`RPMSENSE_KEYRING` (int)
`RPMSENSE_CONFIG` (int)

RPM Mire
`RPMMIRE_DEFAULT` (int)
  Search pattern is a regular expression with `\.`, `.*`, and `^...$` added.
`RPMMIRE_STRCMP` (int)
  Search pattern is a string, using `strcmp(3)`.
`RPMMIRE_REGEX` (int)
  Search pattern is a regular expression, using `regcomp(3)`.
`RPMMIRE_GLOB` (int)
  Search pattern is a glob expression, using `fnmatch(3)`.

RPM tags
`RPMTAG_ARCH` (int)
`RPMTAG_ARCHSUFFIX` (int)
  Requires librpm >= 4.18
`RPMTAG_ARCHIVESIZE` (int)
`RPMTAG_BASENAMES` (int)
  Name (not path) of files, with database index.
`RPMTAG_BUGURL` (int)
`RPMTAG_BUILDARCHS` (int)
`RPMTAG_BUILDHOST` (int)
`RPMTAG_BUILDTIME` (int)
`RPMTAG_C` (int)
`RPMTAG_CHANGELOGNAME` (int)
`RPMTAG_CHANGELOGTEXT` (int)
`RPMTAG_CHANGELOGTIME` (int)
`RPMTAG_CLASSDICT` (int)
`RPMTAG_CONFLICTFLAGS` (int)
`RPMTAG_CONFLICTNAME` (int)
  Conflicting dependencies, with database index.
`RPMTAG_CONFLICTNEVRS` (int)
`RPMTAG_CONFLICTS` (int)
`RPMTAG_CONFLICTVERSION` (int)
`RPMTAG_COOKIE` (int)
`RPMTAG_DBINSTANCE` (int)
`RPMTAG_DEPENDSDICT` (int)
`RPMTAG_DESCRIPTION` (int)
`RPMTAG_DIRINDEXES` (int)
`RPMTAG_DIRNAMES` (int)
  Directory of files, with database index.
`RPMTAG_DISTRIBUTION` (int)
`RPMTAG_DISTTAG` (int)
`RPMTAG_DISTURL` (int)
`RPMTAG_DSAHEADER` (int)
`RPMTAG_E` (int)
`RPMTAG_ENCODING` (int)
`RPMTAG_ENHANCEFLAGS` (int)
`RPMTAG_ENHANCENAME` (int)
  Weak dependencies, with database index, requires librpm >= 4.13.
`RPMTAG_ENHANCENEVRS` (int)
`RPMTAG_ENHANCES` (int)
`RPMTAG_ENHANCEVERSION` (int)
`RPMTAG_EPOCH` (int)
`RPMTAG_EPOCHNUM` (int)
`RPMTAG_EVR` (int)
`RPMTAG_EXCLUDEARCH` (int)
`RPMTAG_EXCLUDEOS` (int)
`RPMTAG_EXCLUSIVEARCH` (int)
`RPMTAG_EXCLUSIVEOS` (int)
`RPMTAG_FILECAPS` (int)
`RPMTAG_FILECLASS` (int)
`RPMTAG_FILECOLORS` (int)
`RPMTAG_FILECONTEXTS` (int)
`RPMTAG_FILEDEPENDSN` (int)
`RPMTAG_FILEDEPENDSX` (int)
`RPMTAG_FILEDEVICES` (int)
`RPMTAG_FILEDIGESTALGO` (int)
`RPMTAG_FILEDIGESTS` (int)
`RPMTAG_FILEFLAGS` (int)
`RPMTAG_FILEGROUPNAME` (int)
`RPMTAG_FILEINODES` (int)
`RPMTAG_FILELANGS` (int)
`RPMTAG_FILELINKTOS` (int)
`RPMTAG_FILEMD5S` (int)
`RPMTAG_FILEMODES` (int)
`RPMTAG_FILEMTIMES` (int)
`RPMTAG_FILENAMES` (int)
`RPMTAG_FILENLINKS` (int)
`RPMTAG_FILEPROVIDE` (int)
`RPMTAG_FILERDEVS` (int)
`RPMTAG_FILEREQUIRE` (int)
`RPMTAG_FILESIGNATURELENGTH` (int)
`RPMTAG_FILESIGNATURES` (int)
`RPMTAG_FILESIZES` (int)
`RPMTAG_FILESTATES` (int)
`RPMTAG_FILETRIGGERCONDS` (int)
`RPMTAG_FILETRIGGERFLAGS` (int)
`RPMTAG_FILETRIGGERINDEX` (int)
`RPMTAG_FILETRIGGERNAME` (int)
  File trigger name, with database index, requires librpm >= 4.13.
`RPMTAG_FILETRIGGERPRIORITIES` (int)
`RPMTAG_FILETRIGGERSCRIPTFLAGS` (int)
`RPMTAG_FILETRIGGERSCRIPTPROG` (int)
`RPMTAG_FILETRIGGERSCRIPTS` (int)
`RPMTAG_FILETRIGGERTYPE` (int)
`RPMTAG_FILETRIGGERVERSION` (int)
`RPMTAG_FILEUSERNAME` (int)
`RPMTAG_FILEVERIFYFLAGS` (int)
`RPMTAG_FSCONTEXTS` (int)
`RPMTAG_GIF` (int)
`RPMTAG_GROUP` (int)
  Group of the package, with database index.
`RPMTAG_HDRID` (int)
  Deprecated, use `RPMTAG_SHA1HEADER` instead. Removed in librpm 6.
`RPMTAG_HEADERCOLOR` (int)
`RPMTAG_HEADERI18NTABLE` (int)
`RPMTAG_HEADERIMAGE` (int)
`RPMTAG_HEADERIMMUTABLE` (int)
`RPMTAG_HEADERREGIONS` (int)
`RPMTAG_HEADERSIGNATURES` (int)
`RPMTAG_ICON` (int)
`RPMTAG_INSTALLCOLOR` (int)
`RPMTAG_INSTALLTID` (int)
  Installation transaction ID, with database index.
`RPMTAG_INSTALLTIME` (int)
`RPMTAG_INSTFILENAMES` (int)
  Path of files, with database index.
`RPMTAG_INSTPREFIXES` (int)
`RPMTAG_LICENSE` (int)
`RPMTAG_LONGARCHIVESIZE` (int)
`RPMTAG_LONGFILESIZES` (int)
`RPMTAG_LONGSIGSIZE` (int)
`RPMTAG_LONGSIZE` (int)
`RPMTAG_MODULARITYLABEL` (int)
`RPMTAG_N` (int)
`RPMTAG_NAME` (int)
  Package name, with database index.
`RPMTAG_NEVR` (int)
`RPMTAG_NEVRA` (int)
`RPMTAG_NOPATCH` (int)
`RPMTAG_NOSOURCE` (int)
`RPMTAG_NVR` (int)
`RPMTAG_NVRA` (int)
`RPMTAG_O` (int)
`RPMTAG_OBSOLETEFLAGS` (int)
`RPMTAG_OBSOLETENAME` (int)
  Obsoleted packages, with database index.
`RPMTAG_OBSOLETENEVRS` (int)
`RPMTAG_OBSOLETES` (int)
`RPMTAG_OBSOLETEVERSION` (int)
`RPMTAG_OLDENHANCES` (int)
`RPMTAG_OLDENHANCESFLAGS` (int)
`RPMTAG_OLDENHANCESNAME` (int)
`RPMTAG_OLDENHANCESVERSION` (int)
`RPMTAG_OLDFILENAMES` (int)
`RPMTAG_OLDSUGGESTS` (int)
`RPMTAG_OLDSUGGESTSFLAGS` (int)
`RPMTAG_OLDSUGGESTSNAME` (int)
`RPMTAG_OLDSUGGESTSVERSION` (int)
`RPMTAG_OPTFLAGS` (int)
`RPMTAG_ORDERFLAGS` (int)
`RPMTAG_ORDERNAME` (int)
`RPMTAG_ORDERVERSION` (int)
`RPMTAG_ORIGBASENAMES` (int)
`RPMTAG_ORIGDIRINDEXES` (int)
`RPMTAG_ORIGDIRNAMES` (int)
`RPMTAG_ORIGFILENAMES` (int)
`RPMTAG_OS` (int)
`RPMTAG_P` (int)
`RPMTAG_PACKAGER` (int)
`RPMTAG_PATCH` (int)
`RPMTAG_PATCHESFLAGS` (int)
`RPMTAG_PATCHESNAME` (int)
`RPMTAG_PATCHESVERSION` (int)
`RPMTAG_PAYLOADCOMPRESSOR` (int)
`RPMTAG_PAYLOADDIGEST` (int)
`RPMTAG_PAYLOADDIGESTALT` (int)
  With librpm >= 4.16.
`RPMTAG_PAYLOADDIGESTALGO` (int)
`RPMTAG_PAYLOADFLAGS` (int)
`RPMTAG_PAYLOADFORMAT` (int)
`RPMTAG_PKGID` (int)
  Deprecated, use `RPMTAG_SIGMD5` instead. Removed in librpm 6.
`RPMTAG_PLATFORM` (int)
`RPMTAG_POLICIES` (int)
`RPMTAG_POLICYFLAGS` (int)
`RPMTAG_POLICYNAMES` (int)
`RPMTAG_POLICYTYPES` (int)
`RPMTAG_POLICYTYPESINDEXES` (int)
`RPMTAG_POSTIN` (int)
`RPMTAG_POSTINFLAGS` (int)
`RPMTAG_POSTINPROG` (int)
`RPMTAG_POSTTRANS` (int)
`RPMTAG_POSTTRANSFLAGS` (int)
`RPMTAG_POSTTRANSPROG` (int)
`RPMTAG_POSTUN` (int)
`RPMTAG_POSTUNFLAGS` (int)
`RPMTAG_POSTUNPROG` (int)
`RPMTAG_POSTUNTRANS` (int)
  Requires librpm >= 4.19
`RPMTAG_POSTUNTRANSFLAGS` (int)
  Requires librpm >= 4.19
`RPMTAG_POSTUNTRANSPROG` (int)
  Requires librpm >= 4.19
`RPMTAG_PREFIXES` (int)
`RPMTAG_PREIN` (int)
`RPMTAG_PREINFLAGS` (int)
`RPMTAG_PREINPROG` (int)
`RPMTAG_PRETRANS` (int)
`RPMTAG_PRETRANSFLAGS` (int)
`RPMTAG_PRETRANSPROG` (int)
`RPMTAG_PREUN` (int)
`RPMTAG_PREUNFLAGS` (int)
`RPMTAG_PREUNPROG` (int)
`RPMTAG_PREUNTRANS` (int)
  Requires librpm >= 4.19
`RPMTAG_PREUNTRANSFLAGS` (int)
  Requires librpm >= 4.19
`RPMTAG_PREUNTRANSPROG` (int)
  Requires librpm >= 4.19
`RPMTAG_PROVIDEFLAGS` (int)
`RPMTAG_PROVIDENAME` (int)
  Provided dependencies, with database index.
`RPMTAG_PROVIDENEVRS` (int)
`RPMTAG_PROVIDES` (int)
`RPMTAG_PROVIDEVERSION` (int)
`RPMTAG_PUBKEYS` (int)
`RPMTAG_R` (int)
`RPMTAG_RECOMMENDFLAGS` (int)
`RPMTAG_RECOMMENDNAME` (int)
  Recommended weak dependencies, with database index, requires librpm >= 4.13.
`RPMTAG_RECOMMENDNEVRS` (int)
`RPMTAG_RECOMMENDS` (int)
`RPMTAG_RECOMMENDVERSION` (int)
`RPMTAG_RECONTEXTS` (int)
`RPMTAG_RELEASE` (int)
`RPMTAG_REMOVETID` (int)
`RPMTAG_REQUIREFLAGS` (int)
`RPMTAG_REQUIRENAME` (int)
  Required dependencies, with database index.
`RPMTAG_REQUIRENEVRS` (int)
`RPMTAG_REQUIRES` (int)
`RPMTAG_REQUIREVERSION` (int)
`RPMTAG_RPMVERSION` (int)
`RPMTAG_RSAHEADER` (int)
`RPMTAG_SHA1HEADER` (int)
  SHA1 signature, with database index.
`RPMTAG_SHA256HEADER` (int)
`RPMTAG_SIGGPG` (int)
`RPMTAG_SIGMD5` (int)
  MD5 signature, with database index.
`RPMTAG_SIGPGP` (int)
`RPMTAG_SIGSIZE` (int)
`RPMTAG_SIZE` (int)
`RPMTAG_SOURCE` (int)
`RPMTAG_SOURCEPACKAGE` (int)
`RPMTAG_SOURCEPKGID` (int)
`RPMTAG_SOURCERPM` (int)
`RPMTAG_SPEC` (int)
  Requires librpm >= 4.18
`RPMTAG_SUGGESTFLAGS` (int)
`RPMTAG_SUGGESTNAME` (int)
  Suggested weak dependencies, with database index, requires librpm >= 4.13.
`RPMTAG_SUGGESTNEVRS` (int)
`RPMTAG_SUGGESTS` (int)
`RPMTAG_SUGGESTVERSION` (int)
`RPMTAG_SUMMARY` (int)
`RPMTAG_SUPPLEMENTFLAGS` (int)
`RPMTAG_SUPPLEMENTNAME` (int)
  Weak dependencies, with database index, requires librpm >= 4.13.
`RPMTAG_SUPPLEMENTNEVRS` (int)
`RPMTAG_SUPPLEMENTS` (int)
`RPMTAG_SUPPLEMENTVERSION` (int)
`RPMTAG_SYSUSERS` (int)
  Requires librpm >= 4.19
`RPMTAG_TRANSFILETRIGGERCONDS` (int)
`RPMTAG_TRANSFILETRIGGERFLAGS` (int)
`RPMTAG_TRANSFILETRIGGERINDEX` (int)
`RPMTAG_TRANSFILETRIGGERNAME` (int)
  Transaction file trigger name, with database index, requires librpm >= 4.13.
`RPMTAG_TRANSFILETRIGGERPRIORITIES` (int)
`RPMTAG_TRANSFILETRIGGERSCRIPTFLAGS` (int)
`RPMTAG_TRANSFILETRIGGERSCRIPTPROG` (int)
`RPMTAG_TRANSFILETRIGGERSCRIPTS` (int)
`RPMTAG_TRANSFILETRIGGERTYPE` (int)
`RPMTAG_TRANSFILETRIGGERVERSION` (int)
`RPMTAG_TRANSLATIONURL` (int)
  Requires librpm >= 4.18
`RPMTAG_TRIGGERCONDS` (int)
`RPMTAG_TRIGGERFLAGS` (int)
`RPMTAG_TRIGGERINDEX` (int)
`RPMTAG_TRIGGERNAME` (int)
  Trigger name, with database index.
`RPMTAG_TRIGGERSCRIPTFLAGS` (int)
`RPMTAG_TRIGGERSCRIPTPROG` (int)
`RPMTAG_TRIGGERSCRIPTS` (int)
`RPMTAG_TRIGGERTYPE` (int)
`RPMTAG_TRIGGERVERSION` (int)
`RPMTAG_UPSTREAMRELEASES` (int)
  Requires librpm >= 4.18
`RPMTAG_URL` (int)
`RPMTAG_V` (int)
`RPMTAG_VCS` (int)
`RPMTAG_VENDOR` (int)
`RPMTAG_VERBOSE` (int)
`RPMTAG_VERIFYSCRIPT` (int)
`RPMTAG_VERIFYSCRIPTFLAGS` (int)
`RPMTAG_VERIFYSCRIPTPROG` (int)
`RPMTAG_VERITYSIGNATUREALGO` (int)
  With librpm >= 4.17.
`RPMTAG_VERITYSIGNATURES` (int)
  With librpm >= 4.17.
`RPMTAG_VERSION` (int)
`RPMTAG_XPM` (int)

# RpmInfo Funktionen

# rpmaddtag

(PECL rpminfo >= 0.5.0)

rpmaddtag — Add tag retrieved in query

### Beschreibung

function rpmaddtag(int `$tag`): bool

Add an additional retrieved tag in subsequent queries.

### Parameter-Liste

`tag`
  One of `RPMTAG_*` constant.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Siehe auch

- rpminfo() - Get information from a RPM file
- rpmdbinfo() - Get information from installed RPM
- rpmdbsearch() - Search RPM packages

# rpmdbinfo

(PECL rpminfo >= 0.2.0)

rpmdbinfo — Get information from installed RPM

### Beschreibung

function rpmdbinfo(string `$nevr`, bool `$full` = `false`): ?array

Retrieve information about an installed package, from the system RPM database.

### Parameter-Liste

`nevr`
  Name with optional epoch, version and release.
`full`
  If `true` all information headers for the file are retrieved, else only a minimal set.

### Rückgabewerte

An array of array of information, or `null` on error.

### Beispiele

Beispiel #1 A rpmdbinfo() example

    <?php
    rpmaddtag(RPMTAG_INSTALLTIME);
    $info = rpmdbinfo("php-pecl-rpminfo");
    print_r($info);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => Array
            (
                [Name] => php-pecl-rpminfo
                [Version] => 0.4.2
                [Release] => 1.fc31
                [Summary] => RPM information
                [Installtime] => 1586244687
                [Arch] => x86_64
            )
    )

### Siehe auch

- rpmaddtag() - Add tag retrieved in query

# rpmdbsearch

(PECL rpminfo >= 0.3.0)

rpmdbsearch — Search RPM packages

### Beschreibung

function rpmdbsearch(
string `$pattern`,
int `$rpmtag` = RPMTAG_NAME,
int `$rpmmire` = -1,
bool `$full` = `false`
): ?array

Search packages in the system RPM database.

### Parameter-Liste

`pattern`
  Value to search for.
`rpmtag`
  Search criterion, which is one of the `RPMTAG_*` constants.
`rpmmire`
  Pattern type, which is one of the `RPMMIRE_*` constants. When < 0 the criterion must equal the value, and database index is used if possible.
`full`
  If `true` all information headers for the file are retrieved, else only a minimal set.

### Rückgabewerte

An array of array of information, or `null` on error.

### Beispiele

Beispiel #1 Searching for the package owning a file

    <?php
    $info = rpmdbsearch("/usr/bin/php", RPMTAG_INSTFILENAMES);
    print_r($info);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [0] => Array
            (
                [Name] => php-cli
                [Version] => 7.4.4
                [Release] => 1.fc32
                [Summary] => Command-line interface for PHP
                [Arch] => x86_64
            )

    )

### Siehe auch

- rpmaddtag() - Add tag retrieved in query

# rpmdefine

(PECL rpminfo >= 1.2.0)

rpmdefine — Define or change a RPM macro value

### Beschreibung

function rpmdefine(string `$text`): bool

Define or change a RPM macro value.

This can be used to select the database path and backend to use instead of system default one.

### Parameter-Liste

`text`
  Macro name, options, body.

### Rückgabewerte

Gibt bei Erfolg `true` zurück. Bei einem Fehler wird `false` zurückgegeben.

### Beispiele

Beispiel #1 A rpmdefine() example

    <?php
    // use an old database (bdb) from an EL-8 chroot
    rpmdefine("_dbpath /var/lib/mock/almalinux-8-x86_64/root/var/lib/rpm");
    rpmdefine("_db_backend bdb_ro");
    print_r(rpmdbinfo("almalinux-release")[0]["Summary"]);

    // use a new database (sqlite) from a Fedora-41 chroot
    rpmdefine("_dbpath /var/lib/mock/fedora-41-x86_64/root/usr/lib/sysimage/rpm");
    rpmdefine("_db_backend sqlite");
    print_r(rpmdbinfo("fedora-release")[0]["Summary"]);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    AlmaLinux release file
    Fedora release files

### Siehe auch

- rpmexpand() - Retrieve expanded value of a RPM macro
- rpmdbinfo() - Get information from installed RPM

# rpmexpand

(PECL rpminfo >= 1.2.0)

rpmexpand — Retrieve expanded value of a RPM macro

### Beschreibung

function rpmexpand(string `$text`): string

Retrieve expanded value of a RPM macro.

### Parameter-Liste

`text`
  Text with RPM macros to expand.

### Rückgabewerte

A string with concatenated macro expansions.

### Beispiele

Beispiel #1 A rpmexpand() example

    <?php
    $distro = rpmexpand("%{?fedora:Fedora %{fedora}}%{?rhel:Enterprise Linux %{rhel}}");
    print_r($distro);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Fedora 41

### Siehe auch

- rpmexpandnumeric() - Retrieve numerical value of a RPM macro

# rpmexpandnumeric

(PECL rpminfo >= 1.2.0)

rpmexpandnumeric — Retrieve numerical value of a RPM macro

### Beschreibung

function rpmexpandnumeric(string `$text`): int

Retrieve numerical value of a RPM macro.

### Parameter-Liste

`text`
  Text with RPM macros to expand.

### Rückgabewerte

Macro expansion as a int. Boolean values (`Y` or `y` returns 1, `N` or `n` returns `0`) are permitted as well. An undefined macro returns `0`.

### Beispiele

Beispiel #1 A rpmexpandnumeric() example

    <?php
    $bits = rpmexpandnumeric("%__isa_bits");
    print_r($bits);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    64

### Siehe auch

- rpmexpand() - Retrieve expanded value of a RPM macro

# rpmgetsymlink

(PECL rpminfo >= 1.1.0)

rpmgetsymlink — Get target of a symlink

### Beschreibung

function rpmgetsymlink(string `$path`, string `$name`): ?string

Get target of a symlink.

### Parameter-Liste

`path`
  Path of the RPM file.
`name`
  Name of the symlink file.

### Rückgabewerte

A string with target of the symlink, `null` on error, or an empty string if not a symlink.

# rpminfo

(PECL rpminfo >= 0.1.0)

rpminfo — Get information from a RPM file

### Beschreibung

function rpminfo(string `$path`, bool `$full` = `false`, string `&$error` = ?): ?array

Retrieve information about a local file, a RPM package.

### Parameter-Liste

`path`
  Path of the RPM file.
`full`
  If `true` all information headers for the file are retrieved, else only a minimal set.
`error`
  If provided, will receive the possible error message, and will avoid a runtime warning.

### Rückgabewerte

An array of information, or `null` on error.

### Beispiele

Beispiel #1 A rpminfo() example

    <?php
    rpmaddtag(RPMTAG_BUILDTIME);
    $info = rpminfo("./php-pecl-rpminfo-0.4.2-1.el8.remi.7.4.x86_64.rpm");
    print_r($info);
    ?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

    Array
    (
        [Name] => php-pecl-rpminfo
        [Version] => 0.4.2
        [Release] => 1.el8
        [Summary] => RPM information
        [Buildtime] => 1586244821
        [Arch] => x86_64
    )

### Siehe auch

- rpmaddtag() - Add tag retrieved in query

# rpmvercmp

(PECL rpminfo >= 0.1.0)

rpmvercmp — RPM version comparison

### Beschreibung

function rpmvercmp(string `$evr1`, string `$evr2`, ?string `$operator` = `null`): int|bool

Compare two RPM package versions.

### Parameter-Liste

`evr1`
  First `epoch:version-release` string.
`evr2`
  Second `epoch:version-release` string.
`operator`

  An optional operator. The possible operators are: `<`, `lt`, `<=`, `le`, `>`, `gt`, `>=`, `ge`, `==`, `=`, `eq`, `!=`, `<>`, `ne`.

  This parameter is case-sensitive, values should be lowercase.

### Rückgabewerte

Returns `-1` if `evr1` is less than `evr2`, `1` if `evr1` is greater than `evr2`, and `0` if they are equal.

When using the optional `operator` argument, the function will return `true` if the relationship is the one specified by the operator, `false` otherwise.

### Changelog

Version | Beschreibung
--- | ---
PECL rpminfo 0.7.0 | Optional `operator` was added.

## Inhaltsverzeichnis

- rpmaddtag — Add tag retrieved in query
- rpmdbinfo — Get information from installed RPM
- rpmdbsearch — Search RPM packages
- rpmdefine — Define or change a RPM macro value
- rpmexpand — Retrieve expanded value of a RPM macro
- rpmexpandnumeric — Retrieve numerical value of a RPM macro
- rpmgetsymlink — Get target of a symlink
- rpminfo — Get information from a RPM file
- rpmvercmp — RPM version comparison

- Installation/Konfiguration
  - Anforderungen
  - Installation via PECL
- Vordefinierte Konstanten
- RpmInfo Funktionen
  - rpmaddtag — Add tag retrieved in query
  - rpmdbinfo — Get information from installed RPM
  - rpmdbsearch — Search RPM packages
  - rpmdefine — Define or change a RPM macro value
  - rpmexpand — Retrieve expanded value of a RPM macro
  - rpmexpandnumeric — Retrieve numerical value of a RPM macro
  - rpmgetsymlink — Get target of a symlink
  - rpminfo — Get information from a RPM file
  - rpmvercmp — RPM version comparison

# XLSWriter

# Einführung

An efficient and fast xlsx file export extension.

# Installation/Konfiguration

## Inhaltsverzeichnis

- Anforderungen
- Installation
- Ressource-Typen

## Anforderungen

XLSWriter requires PHP 7.0 and above.

## Installation

Information zur Installation dieser PECL-Erweiterung finden sie im Kapitel Installation von PECL-Erweiterungen. Zusätzliche Informationen wie neue Releases, Downloads, Quelldateien, Maintainerinformation und ein CHANGELOG finden Sie hier: » https://pecl.php.net/package/xlswriter

## Ressource-Typen

There is one resource used by the procedural version of the XLSWriter extension: returned by fileName() or \Vtiful\Kernel\Format.

# The Vtiful\Kernel\Excel class

(PECL xlswriter >= 1.2.1)

## Einführung

Create xlsx files and set cells and output xlsx files

## Klassenbeschreibung

class Vtiful\Kernel\Excel {
/* Methoden */
public function __construct(array `$config`)
public function addSheet(string `$sheetName`)
public function autoFilter(string `$scope`)
public function constMemory(string `$fileName`, string `$sheetName` = ?)
public function data(array `$data`)
public function fileName(string `$fileName`, string `$sheetName` = ?)
public function getHandle()
public function header(array `$headerData`)
public function insertFormula(int `$row`, int `$column`, string `$formula`)
public function insertImage(int `$row`, int `$column`, string `$localImagePath`)
public function insertText(
int `$row`,
int `$column`,
int|float|string `$data`,
string `$format` = ?
)
public function mergeCells(string `$scope`, string `$data`)
public function output()
public function setColumn(string `$range`, float `$width`, resource `$format` = ?)
public function setRow(string `$range`, float `$height`, resource `$format` = ?)
}

# Vtiful\Kernel\Excel::addSheet

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::addSheet — Vtiful\Kernel\Excel addSheet

### Beschreibung

public function Vtiful\Kernel\Excel::addSheet(string `$sheetName`)

Create a new worksheet in the xlsx file.

### Parameter-Liste

`sheetName`

  Worksheet name

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $fileObject  = new \Vtiful\Kernel\Excel($config);

    $file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
        ->header(['name', 'age'])
        ->data([
            ['viest', 23],
            ['wjx', 23]
        ]);

    $file->addSheet('sheet_two')
        ->header(['name', 'age'])
        ->data([
            ['james', 33],
            ['king', 33]
        ]);

    $file->output();
    ?>

# Vtiful\Kernel\Excel::autoFilter

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::autoFilter — Vtiful\Kernel\Excel autoFilter

### Beschreibung

public function Vtiful\Kernel\Excel::autoFilter(string `$scope`)

Add autofilter to a worksheet.

### Parameter-Liste

`scope`

  Cell start and end coordinate string.

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $fileObject  = new \Vtiful\Kernel\Excel($config);

    $file = $fileObject->fileName('test.xlsx')
            ->header(['name', 'age'])
            ->data($data)
            ->autoFilter('A1:B11')  // auto filter
            ->output();
    ?>

# Vtiful\Kernel\Excel::constMemory

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::constMemory — Vtiful\Kernel\Excel constMemory

### Beschreibung

public function Vtiful\Kernel\Excel::constMemory(string `$fileName`, string `$sheetName` = ?)

Write a large file with constant memory usage.

### Parameter-Liste

`fileName`

  XLSX file name

`sheetName`

  Worksheet name

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
      'path' => '/home/viest'
    ];

    $fileObject = new \Vtiful\Kernel\Excel($config);

    $file = $fileObject->constMemory('tutorial.xlsx', 'sheet');
    ?>

# Vtiful\Kernel\Excel::__construct

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::__construct — Vtiful\Kernel\Excel constructor

### Beschreibung

public function Vtiful\Kernel\Excel::__construct(array `$config`)

Vtiful\Kernel\Excel constructor, create a class object.

### Parameter-Liste

`config`

  XLSX file export configuration

### Beispiele

Beispiel #1 example

    <?php
    $config = [
      'path' => '/home/viest'
    ];

    $excelObject = new \Vtiful\Kernel\Excel($config);
    ?>

# Vtiful\Kernel\Excel::data

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::data — Vtiful\Kernel\Excel data

### Beschreibung

public function Vtiful\Kernel\Excel::data(array `$data`)

Write a data in the worksheet.

### Parameter-Liste

`data`

  worksheet data

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $fileObject  = new \Vtiful\Kernel\Excel($config);

    $file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
        ->header(['name', 'age'])
        ->data([
          ['viest', 23],
          ['wjx', 23],
        ]);
    ?>

# Vtiful\Kernel\Excel::fileName

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::fileName — Vtiful\Kernel\Excel fileName

### Beschreibung

public function Vtiful\Kernel\Excel::fileName(string `$fileName`, string `$sheetName` = ?)

Create a brand new xlsx file and create a worksheet.

### Parameter-Liste

`fileName`

  XLSX file name

`sheetName`

  Worksheet name

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
      'path' => '/home/viest'
    ];

    $fileObject = new \Vtiful\Kernel\Excel($config);

    $file = $fileObject->fileName('tutorial.xlsx', 'sheet');
    ?>

# Vtiful\Kernel\Excel::getHandle

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::getHandle — Vtiful\Kernel\Excel getHandle

### Beschreibung

public function Vtiful\Kernel\Excel::getHandle()

Get the xlsx text resource handle.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

Resource

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $fileObject  = new \Vtiful\Kernel\Excel($config);

    $file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
        ->header(['name', 'age']);

    $handle = $file->getHandle();
    ?>

# Vtiful\Kernel\Excel::header

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::header — Vtiful\Kernel\Excel header

### Beschreibung

public function Vtiful\Kernel\Excel::header(array `$headerData`)

Write a header in the worksheet.

### Parameter-Liste

`headerData`

  worksheet header data

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $fileObject  = new \Vtiful\Kernel\Excel($config);

    $file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
        ->header(['name', 'age']);
    ?>

# Vtiful\Kernel\Excel::insertFormula

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::insertFormula — Vtiful\Kernel\Excel insertFormula

### Beschreibung

public function Vtiful\Kernel\Excel::insertFormula(int `$row`, int `$column`, string `$formula`)

Insert calculation formula.

### Parameter-Liste

`row`

  cell row

`column`

  cell column

`formula`

  formula string

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $excel = new \Vtiful\Kernel\Excel($config);

    $file = $excel->fileName("free.xlsx")
        ->header(['name', 'money']);

    for($index = 1; $index < 10; $index++) {
        $file->insertText($index, 0, 'viest');
        $file->insertText($index, 1, 10);
    }

    $file->insertText(12, 0, "Total");
    $file->insertFormula(12, 1, '=SUM(B2:B11)'); // insert formula

    $file->output();

# Vtiful\Kernel\Excel::insertImage

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::insertImage — Vtiful\Kernel\Excel insertImage

### Beschreibung

public function Vtiful\Kernel\Excel::insertImage(int `$row`, int `$column`, string `$localImagePath`)

Insert a local image into the cell.

### Parameter-Liste

`row`

  cell row

`column`

  cell column

`localImagePath`

  local image path

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $excel = new \Vtiful\Kernel\Excel($config);

    $file = $excel->fileName("free.xlsx");

    $file->insertImage(5, 0, '/vagrant/ASW-G-66.jpg');

    $file->output();

# Vtiful\Kernel\Excel::insertText

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::insertText — Vtiful\Kernel\Excel insertText

### Beschreibung

public function Vtiful\Kernel\Excel::insertText(
int `$row`,
int `$column`,
int|float|string `$data`,
string `$format` = ?
)

Write text in a cell.

### Parameter-Liste

`row`

  cell row

`column`

  cell column

`data`

  data to be written

`format`

  String format

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $excel = new \Vtiful\Kernel\Excel($config);

    $file = $excel->fileName("free.xlsx")
        ->header(['name', 'money']);

    for ($index = 0; $index < 10; $index++) {
        $file->insertText($index+1, 0, 'viest');
        $file->insertText($index+1, 1, 10000, '#,##0');
    }

    $file->output();

# Vtiful\Kernel\Excel::mergeCells

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::mergeCells — Vtiful\Kernel\Excel mergeCells

### Beschreibung

public function Vtiful\Kernel\Excel::mergeCells(string `$scope`, string `$data`)

Merge Cells.

### Parameter-Liste

`scope`

  cell start and end coordinate strings

`data`

  string data

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $excel = new \Vtiful\Kernel\Excel($config);

    $excel->fileName("test.xlsx")
            ->mergeCells('A1:C1', 'Merge cells')
            ->output();

# Vtiful\Kernel\Excel::output

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::output — Vtiful\Kernel\Excel output

### Beschreibung

public function Vtiful\Kernel\Excel::output()

Output xlsx file to disk.

### Parameter-Liste

Diese Funktion besitzt keine Parameter.

### Rückgabewerte

XLSX file path;

### Beispiele

Beispiel #1 example

    <?php
    $config = [
        'path' => './tests'
    ];

    $fileObject  = new \Vtiful\Kernel\Excel($config);

    $file = $fileObject->fileName('tutorial.xlsx', 'sheet_one')
        ->header(['name', 'age'])
        ->data([
          ['viest', 23],
          ['wjx', 23],
        ]);

    $path = $file->output();
    ?>

# Vtiful\Kernel\Excel::setColumn

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::setColumn — Vtiful\Kernel\Excel setColumn

### Beschreibung

public function Vtiful\Kernel\Excel::setColumn(string `$range`, float `$width`, resource `$format` = ?)

Set the format of the column.

### Parameter-Liste

`range`

  cell start and end coordinate strings

`width`

  column width

`format`

  cell format resource

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 setColumn example

    <?php
    $config = [
        'path' => './tests'
    ];

    $excel = new \Vtiful\Kernel\Excel($config);
    $excel->fileName('tutorial01.xlsx');

    $format = new \Vtiful\Kernel\Format($excel->getHandle());
    $boldStyle = $format->bold()->toResource();

    $excel->header(['name', 'age'])
        ->data([['viest', 21]])
        ->setColumn('A:A', 200, $boldStyle)
        ->output();

# Vtiful\Kernel\Excel::setRow

(PECL xlswriter >= 1.2.1)

Vtiful\Kernel\Excel::setRow — Vtiful\Kernel\Excel setRow

### Beschreibung

public function Vtiful\Kernel\Excel::setRow(string `$range`, float `$height`, resource `$format` = ?)

Set the format of the row.

### Parameter-Liste

`range`

  cell start and end coordinate strings

`height`

  row height

`format`

  cell format resource

### Rückgabewerte

Vtiful\Kernel\Excel instance

### Beispiele

Beispiel #1 setRow example

    <?php
    $config = [
        'path' => './tests'
    ];

    $excel = new \Vtiful\Kernel\Excel($config);
    $excel->fileName('tutorial01.xlsx');

    $format = new \Vtiful\Kernel\Format($excel->getHandle());
    $boldStyle = $format->bold()->toResource();

    $excel->header(['name', 'age'])
        ->data([['viest', 21]])
        ->setRow('A1', 20, $boldStyle)
        ->output();

## Inhaltsverzeichnis

- Vtiful\Kernel\Excel::addSheet — Vtiful\Kernel\Excel addSheet
- Vtiful\Kernel\Excel::autoFilter — Vtiful\Kernel\Excel autoFilter
- Vtiful\Kernel\Excel::constMemory — Vtiful\Kernel\Excel constMemory
- Vtiful\Kernel\Excel::__construct — Vtiful\Kernel\Excel constructor
- Vtiful\Kernel\Excel::data — Vtiful\Kernel\Excel data
- Vtiful\Kernel\Excel::fileName — Vtiful\Kernel\Excel fileName
- Vtiful\Kernel\Excel::getHandle — Vtiful\Kernel\Excel getHandle
- Vtiful\Kernel\Excel::header — Vtiful\Kernel\Excel header
- Vtiful\Kernel\Excel::insertFormula — Vtiful\Kernel\Excel insertFormula
- Vtiful\Kernel\Excel::insertImage — Vtiful\Kernel\Excel insertImage
- Vtiful\Kernel\Excel::insertText — Vtiful\Kernel\Excel insertText
- Vtiful\Kernel\Excel::mergeCells — Vtiful\Kernel\Excel mergeCells
- Vtiful\Kernel\Excel::output — Vtiful\Kernel\Excel output
- Vtiful\Kernel\Excel::setColumn — Vtiful\Kernel\Excel setColumn
- Vtiful\Kernel\Excel::setRow — Vtiful\Kernel\Excel setRow

# The Vtiful\Kernel\Format class

(PECL xlswriter >= 1.2.1)

## Einführung

Create a cell format object

## Klassenbeschreibung

class Vtiful\Kernel\Format {
/* Konstanten */
const int FORMAT_ALIGN_LEFT = 1;
const int FORMAT_ALIGN_CENTER = 2;
const int FORMAT_ALIGN_RIGHT = 3;
const int FORMAT_ALIGN_FILL = 4;
const int FORMAT_ALIGN_JUSTIFY = 5;
const int FORMAT_ALIGN_CENTER_ACROSS = 6;
const int FORMAT_ALIGN_DISTRIBUTED = 7;
const int FORMAT_ALIGN_VERTICAL_TOP = 8;
const int FORMAT_ALIGN_VERTICAL_BOTTOM = 9;
const int FORMAT_ALIGN_VERTICAL_CENTER = 10;
const int FORMAT_ALIGN_VERTICAL_JUSTIFY = 11;
const int FORMAT_ALIGN_VERTICAL_DISTRIBUTED = 12;
const int UNDERLINE_SINGLE = 1;
const int UNDERLINE_DOUBLE = 2;
const int UNDERLINE_SINGLE_ACCOUNTING = 3;
const int UNDERLINE_DOUBLE_ACCOUNTING = 4;
/* Methoden */
public function align(resource `$handle`, int `$style`)
public function bold(resource `$handle`)
public function italic(resource `$handle`)
public function underline(resource `$handle`, int `$style`)
}

## Vordefinierte Konstanten

`Vtiful\Kernel\Format::FORMAT_ALIGN_LEFT`

`Vtiful\Kernel\Format::FORMAT_ALIGN_CENTER`

`Vtiful\Kernel\Format::FORMAT_ALIGN_RIGHT`

`Vtiful\Kernel\Format::FORMAT_ALIGN_FILL`

`Vtiful\Kernel\Format::FORMAT_ALIGN_JUSTIFY`

`Vtiful\Kernel\Format::FORMAT_ALIGN_CENTER_ACROSS`

`Vtiful\Kernel\Format::FORMAT_ALIGN_DISTRIBUTED`

`Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_TOP`

`Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_BOTTOM`

`Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_CENTER`

`Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_JUSTIFY`

`Vtiful\Kernel\Format::FORMAT_ALIGN_VERTICAL_DISTRIBUTED`

`Vtiful\Kernel\Format::UNDERLINE_SINGLE`

`Vtiful\Kernel\Format::UNDERLINE_DOUBLE`

`Vtiful\Kernel\Format::UNDERLINE_SINGLE_ACCOUNTING`
[file cut: first 33554432 bytes kept]
